diff options
Diffstat (limited to 'src/ppp.8.m4')
| -rw-r--r-- | src/ppp.8.m4 | 6134 |
1 files changed, 6134 insertions, 0 deletions
diff --git a/src/ppp.8.m4 b/src/ppp.8.m4 new file mode 100644 index 0000000..18319de --- /dev/null +++ b/src/ppp.8.m4 @@ -0,0 +1,6134 @@ +changequote({,})dnl +changecom(,)dnl +.\" +.\" Copyright (c) 2001 Brian Somers <brian@Awfulhak.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/usr.sbin/ppp/ppp.8.m4,v 1.327.2.2.4.1 2010/12/21 17:10:29 kensmith Exp $ +.\" +.Dd August 25, 2009 +.Dt PPP 8 +.Os +.Sh NAME +.Nm ppp +.Nd Point to Point Protocol (a.k.a. user-ppp) +.Sh SYNOPSIS +.Nm +.Op Fl Va mode +.Op Fl nat +.Op Fl quiet +.Op Fl unit Ns Ar N +.Op Ar system ... +.Sh DESCRIPTION +This is a user process +.Em PPP +software package. +Normally, +.Em PPP +is implemented as a part of the kernel (e.g., as managed by +.Xr pppd 8 ) +and it is thus somewhat hard to debug and/or modify its behaviour. +However, in this implementation +.Em PPP +is done as a user process with the help of the +tunnel device driver (tun). +.Pp +The +.Fl nat +flag does the equivalent of a +.Dq nat enable yes , +enabling +.Nm Ns No 's +network address translation features. +This allows +.Nm +to act as a NAT or masquerading engine for all machines on an internal +LAN. +ifdef({LOCALNAT},{},{Refer to +.Xr libalias 3 +for details on the technical side of the NAT engine. +})dnl +Refer to the +.Sx NETWORK ADDRESS TRANSLATION (PACKET ALIASING) +section of this manual page for details on how to configure NAT in +.Nm . +.Pp +The +.Fl quiet +flag tells +.Nm +to be silent at startup rather than displaying the mode and interface +to standard output. +.Pp +The +.Fl unit +flag tells +.Nm +to only attempt to open +.Pa /dev/tun Ns Ar N . +Normally, +.Nm +will start with a value of 0 for +.Ar N , +and keep trying to open a tunnel device by incrementing the value of +.Ar N +by one each time until it succeeds. +If it fails three times in a row +because the device file is missing, it gives up. +.Pp +The following +.Va mode Ns No s +are understood by +.Nm : +.Bl -tag -width XXX -offset XXX +.It Fl auto +.Nm +opens the tun interface, configures it then goes into the background. +The link is not brought up until outgoing data is detected on the tun +interface at which point +.Nm +attempts to bring up the link. +Packets received (including the first one) while +.Nm +is trying to bring the link up will remain queued for a default of +2 minutes. +See the +.Dq set choked +command below. +.Pp +In +.Fl auto +mode, at least one +.Dq system +must be given on the command line (see below) and a +.Dq set ifaddr +must be done in the system profile that specifies a peer IP address to +use when configuring the interface. +Something like +.Dq 10.0.0.1/0 +is usually appropriate. +See the +.Dq pmdemand +system in +.Pa /usr/share/examples/ppp/ppp.conf.sample +for an example. +.It Fl background +Here, +.Nm +attempts to establish a connection with the peer immediately. +If it succeeds, +.Nm +goes into the background and the parent process returns an exit code +of 0. +If it fails, +.Nm +exits with a non-zero result. +.It Fl foreground +In foreground mode, +.Nm +attempts to establish a connection with the peer immediately, but never +becomes a daemon. +The link is created in background mode. +This is useful if you wish to control +.Nm Ns No 's +invocation from another process. +.It Fl direct +This is used for communicating over an already established connection, +usually when receiving incoming connections accepted by +.Xr getty 8 . +.Nm +ignores the +.Dq set device +line and uses descriptor 0 as the link. +.Nm +will also ignore any configured chat scripts unless the +.Dq force-scripts +option has been enabled. +.Pp +If callback is configured, +.Nm +will use the +.Dq set device +information when dialing back. +.Pp +When run in +.Fl direct +mode, +.Nm +will behave slightly differently if descriptor 0 was created by +.Xr pipe 2 . +As pipes are not bi-directional, ppp will redirect all writes to descriptor +1 (standard output), leaving only reads acting on descriptor 0. +No special action is taken if descriptor 0 was created by +.Xr socketpair 2 . +.It Fl dedicated +This option is designed for machines connected with a dedicated +wire. +.Nm +will always keep the device open and will ignore any configured +chat scripts unless the +.Dq force-scripts +option has been enabled. +.It Fl ddial +This mode is equivalent to +.Fl auto +mode except that +.Nm +will bring the link back up any time it is dropped for any reason. +.It Fl interactive +This is a no-op, and gives the same behaviour as if none of the above +modes have been specified. +.Nm +loads any sections specified on the command line then provides an +interactive prompt. +.El +.Pp +One or more configuration entries or systems +(as specified in +.Pa /etc/ppp/ppp.conf ) +may also be specified on the command line. +.Nm +will read the +.Dq default +system from +.Pa /etc/ppp/ppp.conf +at startup, followed by each of the systems specified on the command line. +.Sh Major Features +.Bl -diag +.It Provides an interactive user interface. +Using its command mode, the user can +easily enter commands to establish the connection with the remote end, check +the status of connection and close the connection. +All functions can also be optionally password protected for security. +.It Supports both manual and automatic dialing. +Interactive mode has a +.Dq term +command which enables you to talk to the device directly. +When you are connected to the remote peer and it starts to talk +.Em PPP , +.Nm +detects it and switches to packet mode automatically. +Once you have +determined the proper sequence for connecting with the remote host, you +can write a chat script to {define} the necessary dialing and login +procedure for later convenience. +.It Supports on-demand dialup capability. +By using +.Fl auto +mode, +.Nm +will act as a daemon and wait for a packet to be sent over the +.Em PPP +link. +When this happens, the daemon automatically dials and establishes the +connection. +In almost the same manner +.Fl ddial +mode (direct-dial mode) also automatically dials and establishes the +connection. +However, it differs in that it will dial the remote site +any time it detects the link is down, even if there are no packets to be +sent. +This mode is useful for full-time connections where we worry less +about line charges and more about being connected full time. +A third +.Fl dedicated +mode is also available. +This mode is targeted at a dedicated link between two machines. +.Nm +will never voluntarily quit from dedicated mode - you must send it the +.Dq quit all +command via its diagnostic socket. +A +.Dv SIGHUP +will force an LCP renegotiation, and a +.Dv SIGTERM +will force it to exit. +.It Supports client callback. +.Nm +can use either the standard LCP callback protocol or the Microsoft +CallBack Control Protocol (ftp://ftp.microsoft.com/developr/rfc/cbcp.txt). +.It Supports NAT or packet aliasing. +Packet aliasing (a.k.a.\& IP masquerading) allows computers on a +private, unregistered network to access the Internet. +The +.Em PPP +host acts as a masquerading gateway. +IP addresses as well as TCP and +UDP port numbers are NAT'd for outgoing packets and de-NAT'd for +returning packets. +.It Supports background PPP connections. +In background mode, if +.Nm +successfully establishes the connection, it will become a daemon. +Otherwise, it will exit with an error. +This allows the setup of +scripts that wish to execute certain commands only if the connection +is successfully established. +.It Supports server-side PPP connections. +In direct mode, +.Nm +acts as server which accepts incoming +.Em PPP +connections on stdin/stdout. +.It "Supports PAP and CHAP (rfc 1994, 2433 and 2759) authentication. +With PAP or CHAP, it is possible to skip the Unix style +.Xr login 1 +procedure, and use the +.Em PPP +protocol for authentication instead. +If the peer requests Microsoft CHAP authentication and +.Nm +is compiled with DES support, an appropriate MD4/DES response will be +made. +.It Supports RADIUS (rfc 2138 & 2548) authentication. +An extension to PAP and CHAP, +.Em \&R Ns No emote +.Em \&A Ns No ccess +.Em \&D Ns No ial +.Em \&I Ns No n +.Em \&U Ns No ser +.Em \&S Ns No ervice +allows authentication information to be stored in a central or +distributed database along with various per-user framed connection +characteristics. +ifdef({LOCALRAD},{},{If +.Xr libradius 3 +is available at compile time, +.Nm +will use it to make +.Em RADIUS +requests when configured to do so. +})dnl +.It Supports Proxy Arp. +.Nm +can be configured to make one or more proxy arp entries on behalf of +the peer. +This allows routing from the peer to the LAN without +configuring each machine on that LAN. +.It Supports packet filtering. +User can {define} four kinds of filters: the +.Em in +filter for incoming packets, the +.Em out +filter for outgoing packets, the +.Em dial +filter to {define} a dialing trigger packet and the +.Em alive +filter for keeping a connection alive with the trigger packet. +.It Tunnel driver supports bpf. +The user can use +.Xr tcpdump 1 +to check the packet flow over the +.Em PPP +link. +.It Supports PPP over TCP and PPP over UDP. +If a device name is specified as +.Em host Ns No : Ns Em port Ns +.Xo +.Op / Ns tcp|udp , +.Xc +.Nm +will open a TCP or UDP connection for transporting data rather than using a +conventional serial device. +UDP connections force +.Nm +into synchronous mode. +.It Supports PPP over ISDN. +If +.Nm +is given a raw B-channel i4b device to open as a link, it is able to talk +to the +.Xr isdnd 8 +daemon to establish an ISDN connection. +.It Supports PPP over Ethernet (rfc 2516). +If +.Nm +is given a device specification of the format +.No PPPoE: Ns Ar iface Ns Xo +.Op \&: Ns Ar provider Ns +.Xc +and if +.Xr netgraph 4 +is available, +.Nm +will attempt talk +.Em PPP +over Ethernet to +.Ar provider +using the +.Ar iface +network interface. +.Pp +On systems that do not support +.Xr netgraph 4 , +an external program such as +.Xr pppoed 8 +may be used. +.It "Supports IETF draft Predictor-1 (rfc 1978) and DEFLATE (rfc 1979) compression." +.Nm +supports not only VJ-compression but also Predictor-1 and DEFLATE compression. +Normally, a modem has built-in compression (e.g., v42.bis) and the system +may receive higher data rates from it as a result of such compression. +While this is generally a good thing in most other situations, this +higher speed data imposes a penalty on the system by increasing the +number of serial interrupts the system has to process in talking to the +modem and also increases latency. +Unlike VJ-compression, Predictor-1 and DEFLATE compression pre-compresses +.Em all +network traffic flowing through the link, thus reducing overheads to a +minimum. +.It Supports Microsoft's IPCP extensions (rfc 1877). +Name Server Addresses and NetBIOS Name Server Addresses can be negotiated +with clients using the Microsoft +.Em PPP +stack (i.e., Win95, WinNT) +.It Supports Multi-link PPP (rfc 1990) +It is possible to configure +.Nm +to open more than one physical connection to the peer, combining the +bandwidth of all links for better throughput. +.It Supports MPPE (draft-ietf-pppext-mppe) +MPPE is Microsoft Point to Point Encryption scheme. +It is possible to configure +.Nm +to participate in Microsoft's Windows VPN. +For now, +.Nm +can only get encryption keys from CHAP 81 authentication. +.Nm +must be compiled with DES for MPPE to operate. +.It Supports IPV6CP (rfc 2023). +An IPv6 connection can be made in addition to or instead of the normal +IPv4 connection. +.El +.Sh PERMISSIONS +.Nm +is installed as user +.Dv root +and group +.Dv network , +with permissions +.Dv 04554 . +By default, +.Nm +will not run if the invoking user id is not zero. +This may be overridden by using the +.Dq allow users +command in +.Pa /etc/ppp/ppp.conf . +When running as a normal user, +.Nm +switches to user id 0 in order to alter the system routing table, set up +system lock files and read the ppp configuration files. +All external commands (executed via the "shell" or "!bg" commands) are executed +as the user id that invoked +.Nm . +Refer to the +.Sq ID0 +logging facility if you are interested in what exactly is done as user id +zero. +.Sh GETTING STARTED +When you first run +.Nm +you may need to deal with some initial configuration details. +.Bl -bullet +.It +Make sure that your system has a group named +.Dq network +in the +.Pa /etc/group +file and that the group contains the names of all users expected to use +.Nm . +Refer to the +.Xr group 5 +manual page for details. +Each of these users must also be given access using the +.Dq allow users +command in +.Pa /etc/ppp/ppp.conf . +.It +Create a log file. +.Nm +uses +.Xr syslog 3 +to log information. +A common log file name is +.Pa /var/log/ppp.log . +To make output go to this file, put the following lines in the +.Pa /etc/syslog.conf +file: +.Bd -literal -offset indent +!ppp +*.*<TAB>/var/log/ppp.log +.Ed +.Pp +It is possible to have more than one +.Em PPP +log file by creating a link to the +.Nm +executable: +.Pp +.Dl # cd /usr/sbin +.Dl # ln ppp ppp0 +.Pp +and using +.Bd -literal -offset indent +!ppp0 +*.*<TAB>/var/log/ppp0.log +.Ed +.Pp +in +.Pa /etc/syslog.conf . +Do not forget to send a +.Dv HUP +signal to +.Xr syslogd 8 +after altering +.Pa /etc/syslog.conf . +.It +Although not strictly relevant to +.Nm Ns No 's +operation, you should configure your resolver so that it works correctly. +This can be done by configuring a local DNS +(using +.Xr named 8 ) +or by adding the correct +.Sq nameserver +lines to the file +.Pa /etc/resolv.conf . +Refer to the +.Xr resolv.conf 5 +manual page for details. +.Pp +Alternatively, if the peer supports it, +.Nm +can be configured to ask the peer for the nameserver address(es) and to +update +.Pa /etc/resolv.conf +automatically. +Refer to the +.Dq enable dns +and +.Dq resolv +commands below for details. +.El +.Sh MANUAL DIALING +In the following examples, we assume that your machine name is +.Dv awfulhak . +when you invoke +.Nm +(see +.Sx PERMISSIONS +above) with no arguments, you are presented with a prompt: +.Bd -literal -offset indent +ppp ON awfulhak> +.Ed +.Pp +The +.Sq ON +part of your prompt should always be in upper case. +If it is in lower case, it means that you must supply a password using the +.Dq passwd +command. +This only ever happens if you connect to a running version of +.Nm +and have not authenticated yourself using the correct password. +.Pp +You can start by specifying the device name and speed: +.Bd -literal -offset indent +ppp ON awfulhak> set device /dev/cuad0 +ppp ON awfulhak> set speed 38400 +.Ed +.Pp +Normally, hardware flow control (CTS/RTS) is used. +However, under +certain circumstances (as may happen when you are connected directly +to certain PPP-capable terminal servers), this may result in +.Nm +hanging as soon as it tries to write data to your communications link +as it is waiting for the CTS (clear to send) signal - which will never +come. +Thus, if you have a direct line and cannot seem to make a +connection, try turning CTS/RTS off with +.Dq set ctsrts off . +If you need to do this, check the +.Dq set accmap +description below too - you will probably need to +.Dq set accmap 000a0000 . +.Pp +Usually, parity is set to +.Dq none , +and this is +.Nm Ns No 's +default. +Parity is a rather archaic error checking mechanism that is no +longer used because modern modems do their own error checking, and most +link-layer protocols (that is what +.Nm +is) use much more reliable checking mechanisms. +Parity has a relatively +huge overhead (a 12.5% increase in traffic) and as a result, it is always +disabled +(set to +.Dq none ) +when +.Dv PPP +is opened. +However, some ISPs (Internet Service Providers) may use +specific parity settings at connection time (before +.Dv PPP +is opened). +Notably, Compuserve insist on even parity when logging in: +.Bd -literal -offset indent +ppp ON awfulhak> set parity even +.Ed +.Pp +You can now see what your current device settings look like: +.Bd -literal -offset indent +ppp ON awfulhak> show physical +Name: deflink + State: closed + Device: N/A + Link Type: interactive + Connect Count: 0 + Queued Packets: 0 + Phone Number: N/A + +Defaults: + Device List: /dev/cuad0 + Characteristics: 38400bps, cs8, even parity, CTS/RTS on + +Connect time: 0 secs +0 octets in, 0 octets out +Overall 0 bytes/sec +ppp ON awfulhak> +.Ed +.Pp +The term command can now be used to talk directly to the device: +.Bd -literal -offset indent +ppp ON awfulhak> term +at +OK +atdt123456 +CONNECT +login: myispusername +Password: myisppassword +Protocol: ppp +.Ed +.Pp +When the peer starts to talk in +.Em PPP , +.Nm +detects this automatically and returns to command mode. +.Bd -literal -offset indent +ppp ON awfulhak> # No link has been established +Ppp ON awfulhak> # We've connected & finished LCP +PPp ON awfulhak> # We've authenticated +PPP ON awfulhak> # We've agreed IP numbers +.Ed +.Pp +If it does not, it is probable that the peer is waiting for your end to +start negotiating. +To force +.Nm +to start sending +.Em PPP +configuration packets to the peer, use the +.Dq ~p +command to drop out of terminal mode and enter packet mode. +.Pp +If you never even receive a login prompt, it is quite likely that the +peer wants to use PAP or CHAP authentication instead of using Unix-style +login/password authentication. +To set things up properly, drop back to +the prompt and set your authentication name and key, then reconnect: +.Bd -literal -offset indent +~. +ppp ON awfulhak> set authname myispusername +ppp ON awfulhak> set authkey myisppassword +ppp ON awfulhak> term +at +OK +atdt123456 +CONNECT +.Ed +.Pp +You may need to tell ppp to initiate negotiations with the peer here too: +.Bd -literal -offset indent +~p +ppp ON awfulhak> # No link has been established +Ppp ON awfulhak> # We've connected & finished LCP +PPp ON awfulhak> # We've authenticated +PPP ON awfulhak> # We've agreed IP numbers +.Ed +.Pp +You are now connected! +Note that +.Sq PPP +in the prompt has changed to capital letters to indicate that you have +a peer connection. +If only some of the three Ps go uppercase, wait until +either everything is uppercase or lowercase. +If they revert to lowercase, it means that +.Nm +could not successfully negotiate with the peer. +A good first step for troubleshooting at this point would be to +.Bd -literal -offset indent +ppp ON awfulhak> set log local phase lcp ipcp +.Ed +.Pp +and try again. +Refer to the +.Dq set log +command description below for further details. +If things fail at this point, +it is quite important that you turn logging on and try again. +It is also +important that you note any prompt changes and report them to anyone trying +to help you. +.Pp +When the link is established, the show command can be used to see how +things are going: +.Bd -literal -offset indent +PPP ON awfulhak> show physical +* Modem related information is shown here * +PPP ON awfulhak> show ccp +* CCP (compression) related information is shown here * +PPP ON awfulhak> show lcp +* LCP (line control) related information is shown here * +PPP ON awfulhak> show ipcp +* IPCP (IP) related information is shown here * +PPP ON awfulhak> show ipv6cp +* IPV6CP (IPv6) related information is shown here * +PPP ON awfulhak> show link +* Link (high level) related information is shown here * +PPP ON awfulhak> show bundle +* Logical (high level) connection related information is shown here * +.Ed +.Pp +At this point, your machine has a host route to the peer. +This means +that you can only make a connection with the host on the other side +of the link. +If you want to add a default route entry (telling your +machine to send all packets without another routing entry to the other +side of the +.Em PPP +link), enter the following command: +.Bd -literal -offset indent +PPP ON awfulhak> add default HISADDR +.Ed +.Pp +The string +.Sq HISADDR +represents the IP address of the connected peer. +If the +.Dq add +command fails due to an existing route, you can overwrite the existing +route using: +.Bd -literal -offset indent +PPP ON awfulhak> add! default HISADDR +.Ed +.Pp +This command can also be executed before actually making the connection. +If a new IP address is negotiated at connection time, +.Nm +will update your default route accordingly. +.Pp +You can now use your network applications (ping, telnet, ftp, etc.) +in other windows or terminals on your machine. +If you wish to reuse the current terminal, you can put +.Nm +into the background using your standard shell suspend and background +commands (usually +.Dq ^Z +followed by +.Dq bg ) . +.Pp +Refer to the +.Sx PPP COMMAND LIST +section for details on all available commands. +.Sh AUTOMATIC DIALING +To use automatic dialing, you must prepare some Dial and Login chat scripts. +See the example definitions in +.Pa /usr/share/examples/ppp/ppp.conf.sample +(the format of +.Pa /etc/ppp/ppp.conf +is pretty simple). +Each line contains one comment, inclusion, label or command: +.Bl -bullet +.It +A line starting with a +.Pq Dq # +character is treated as a comment line. +Leading whitespace are ignored when identifying comment lines. +.It +An inclusion is a line beginning with the word +.Sq {!include} . +It must have one argument - the file to {include}. +You may wish to +.Dq {!include} ~/.ppp.conf +for compatibility with older versions of +.Nm . +.It +A label name starts in the first column and is followed by +a colon +.Pq Dq \&: . +.It +A command line must contain a space or tab in the first column. +.It +A string starting with the +.Dq $ +character is substituted with the value of the environment variable by +the same name. +Likewise, a string starting with the +.Dq ~ +character is substituted with the full path to the home directory of +the user account by the same name, and the +.Dq ~ +character by itself is substituted with the full path to the home directory +of the current user. +If you want to include a literal +.Dq $ +or +.Dq ~ +character in a command or argument, enclose them in double quotes, e.g., +.Bd -literal -offset indent +set password "pa$ss~word" +.Ed +.El +.Pp +The +.Pa /etc/ppp/ppp.conf +file should consist of at least a +.Dq default +section. +This section is always executed. +It should also contain +one or more sections, named according to their purpose, for example, +.Dq MyISP +would represent your ISP, and +.Dq ppp-in +would represent an incoming +.Nm +configuration. +You can now specify the destination label name when you invoke +.Nm . +Commands associated with the +.Dq default +label are executed, followed by those associated with the destination +label provided. +When +.Nm +is started with no arguments, the +.Dq default +section is still executed. +The load command can be used to manually load a section from the +.Pa /etc/ppp/ppp.conf +file: +.Bd -literal -offset indent +ppp ON awfulhak> load MyISP +.Ed +.Pp +Note, no action is taken by +.Nm +after a section is loaded, whether it is the result of passing a label on +the command line or using the +.Dq load +command. +Only the commands specified for that label in the configuration +file are executed. +However, when invoking +.Nm +with the +.Fl background , +.Fl ddial , +or +.Fl dedicated +switches, the link mode tells +.Nm +to establish a connection. +Refer to the +.Dq set mode +command below for further details. +.Pp +Once the connection is made, the +.Sq ppp +portion of the prompt will change to +.Sq PPP : +.Bd -literal -offset indent +# ppp MyISP +\&... +ppp ON awfulhak> dial +Ppp ON awfulhak> +PPp ON awfulhak> +PPP ON awfulhak> +.Ed +.Pp +The Ppp prompt indicates that +.Nm +has entered the authentication phase. +The PPp prompt indicates that +.Nm +has entered the network phase. +The PPP prompt indicates that +.Nm +has successfully negotiated a network layer protocol and is in +a usable state. +.Pp +If the +.Pa /etc/ppp/ppp.linkup +file is available, its contents are executed +when the +.Em PPP +connection is established. +See the provided +.Dq pmdemand +example in +.Pa /usr/share/examples/ppp/ppp.conf.sample +which runs a script in the background after the connection is established +(refer to the +.Dq shell +and +.Dq bg +commands below for a description of possible substitution strings). +Similarly, when a connection is closed, the contents of the +.Pa /etc/ppp/ppp.linkdown +file are executed. +Both of these files have the same format as +.Pa /etc/ppp/ppp.conf . +.Pp +In previous versions of +.Nm , +it was necessary to re-add routes such as the default route in the +.Pa ppp.linkup +file. +.Nm +supports +.Sq sticky routes , +where all routes that contain the +.Dv HISADDR , +.Dv MYADDR , +.Dv HISADDR6 +or +.Dv MYADDR6 +literals will automatically be updated when the values of these variables +change. +.Sh BACKGROUND DIALING +If you want to establish a connection using +.Nm +non-interactively (such as from a +.Xr crontab 5 +entry or an +.Xr at 1 +job) you should use the +.Fl background +option. +When +.Fl background +is specified, +.Nm +attempts to establish the connection immediately. +If multiple phone +numbers are specified, each phone number will be tried once. +If the attempt fails, +.Nm +exits immediately with a non-zero exit code. +If it succeeds, then +.Nm +becomes a daemon, and returns an exit status of zero to its caller. +The daemon exits automatically if the connection is dropped by the +remote system, or it receives a +.Dv TERM +signal. +.Sh DIAL ON DEMAND +Demand dialing is enabled with the +.Fl auto +or +.Fl ddial +options. +You must also specify the destination label in +.Pa /etc/ppp/ppp.conf +to use. +It must contain the +.Dq set ifaddr +command to {define} the remote peers IP address. +(refer to +.Pa /usr/share/examples/ppp/ppp.conf.sample ) +.Bd -literal -offset indent +# ppp -auto pmdemand +.Ed +.Pp +When +.Fl auto +or +.Fl ddial +is specified, +.Nm +runs as a daemon but you can still configure or examine its +configuration by using the +.Dq set server +command in +.Pa /etc/ppp/ppp.conf , +(for example, +.Dq Li "set server +3000 mypasswd" ) +and connecting to the diagnostic port as follows: +.Bd -literal -offset indent +# pppctl 3000 (assuming tun0) +Password: +PPP ON awfulhak> show who +tcp (127.0.0.1:1028) * +.Ed +.Pp +The +.Dq show who +command lists users that are currently connected to +.Nm +itself. +If the diagnostic socket is closed or changed to a different +socket, all connections are immediately dropped. +.Pp +In +.Fl auto +mode, when an outgoing packet is detected, +.Nm +will perform the dialing action (chat script) and try to connect +with the peer. +In +.Fl ddial +mode, the dialing action is performed any time the line is found +to be down. +If the connect fails, the default behaviour is to wait 30 seconds +and then attempt to connect when another outgoing packet is detected. +This behaviour can be changed using the +.Dq set redial +command: +.Pp +.No set redial Ar secs Ns Xo +.Oo + Ns Ar inc Ns +.Op - Ns Ar max Ns +.Oc Ns Op . Ns Ar next +.Op Ar attempts +.Xc +.Pp +.Bl -tag -width attempts -compact +.It Ar secs +is the number of seconds to wait before attempting +to connect again. +If the argument is the literal string +.Sq Li random , +the delay period is a random value between 1 and 30 seconds inclusive. +.It Ar inc +is the number of seconds that +.Ar secs +should be incremented each time a new dial attempt is made. +The timeout reverts to +.Ar secs +only after a successful connection is established. +The default value for +.Ar inc +is zero. +.It Ar max +is the maximum number of times +.Nm +should increment +.Ar secs . +The default value for +.Ar max +is 10. +.It Ar next +is the number of seconds to wait before attempting +to dial the next number in a list of numbers (see the +.Dq set phone +command). +The default is 3 seconds. +Again, if the argument is the literal string +.Sq Li random , +the delay period is a random value between 1 and 30 seconds. +.It Ar attempts +is the maximum number of times to try to connect for each outgoing packet +that triggers a dial. +The previous value is unchanged if this parameter is omitted. +If a value of zero is specified for +.Ar attempts , +.Nm +will keep trying until a connection is made. +.El +.Pp +So, for example: +.Bd -literal -offset indent +set redial 10.3 4 +.Ed +.Pp +will attempt to connect 4 times for each outgoing packet that causes +a dial attempt with a 3 second delay between each number and a 10 second +delay after all numbers have been tried. +If multiple phone numbers +are specified, the total number of attempts is still 4 (it does not +attempt each number 4 times). +.Pp +Alternatively, +.Pp +.Bd -literal -offset indent +set redial 10+10-5.3 20 +.Ed +.Pp +tells +.Nm +to attempt to connect 20 times. +After the first attempt, +.Nm +pauses for 10 seconds. +After the next attempt it pauses for 20 seconds +and so on until after the sixth attempt it pauses for 1 minute. +The next 14 pauses will also have a duration of one minute. +If +.Nm +connects, disconnects and fails to connect again, the timeout starts again +at 10 seconds. +.Pp +Modifying the dial delay is very useful when running +.Nm +in +.Fl auto +mode on both ends of the link. +If each end has the same timeout, +both ends wind up calling each other at the same time if the link +drops and both ends have packets queued. +At some locations, the serial link may not be reliable, and carrier +may be lost at inappropriate times. +It is possible to have +.Nm +redial should carrier be unexpectedly lost during a session. +.Bd -literal -offset indent +set reconnect timeout ntries +.Ed +.Pp +This command tells +.Nm +to re-establish the connection +.Ar ntries +times on loss of carrier with a pause of +.Ar timeout +seconds before each try. +For example, +.Bd -literal -offset indent +set reconnect 3 5 +.Ed +.Pp +tells +.Nm +that on an unexpected loss of carrier, it should wait +.Ar 3 +seconds before attempting to reconnect. +This may happen up to +.Ar 5 +times before +.Nm +gives up. +The default value of ntries is zero (no reconnect). +Care should be taken with this option. +If the local timeout is slightly +longer than the remote timeout, the reconnect feature will always be +triggered (up to the given number of times) after the remote side +times out and hangs up. +NOTE: In this context, losing too many LQRs constitutes a loss of +carrier and will trigger a reconnect. +If the +.Fl background +flag is specified, all phone numbers are dialed at most once until +a connection is made. +The next number redial period specified with the +.Dq set redial +command is honoured, as is the reconnect tries value. +If your redial +value is less than the number of phone numbers specified, not all +the specified numbers will be tried. +To terminate the program, type +.Bd -literal -offset indent +PPP ON awfulhak> close +ppp ON awfulhak> quit all +.Ed +.Pp +A simple +.Dq quit +command will terminate the +.Xr pppctl 8 +or +.Xr telnet 1 +connection but not the +.Nm +program itself. +You must use +.Dq quit all +to terminate +.Nm +as well. +.Sh RECEIVING INCOMING PPP CONNECTIONS (Method 1) +To handle an incoming +.Em PPP +connection request, follow these steps: +.Bl -enum +.It +Make sure the modem and (optionally) +.Pa /etc/rc.serial +is configured correctly. +.Bl -bullet -compact +.It +Use Hardware Handshake (CTS/RTS) for flow control. +.It +Modem should be set to NO echo back (ATE0) and NO results string (ATQ1). +.El +.Pp +.It +Edit +.Pa /etc/ttys +to enable a +.Xr getty 8 +on the port where the modem is attached. +For example: +.Pp +.Dl ttyd1 Qo /usr/libexec/getty std.38400 Qc dialup on secure +.Pp +Do not forget to send a +.Dv HUP +signal to the +.Xr init 8 +process to start the +.Xr getty 8 : +.Pp +.Dl # kill -HUP 1 +.Pp +It is usually also necessary to train your modem to the same DTR speed +as the getty: +.Bd -literal -offset indent +# ppp +ppp ON awfulhak> set device /dev/cuad1 +ppp ON awfulhak> set speed 38400 +ppp ON awfulhak> term +deflink: Entering terminal mode on /dev/cuad1 +Type `~?' for help +at +OK +at +OK +atz +OK +at +OK +~. +ppp ON awfulhak> quit +.Ed +.It +Create a +.Pa /usr/local/bin/ppplogin +file with the following contents: +.Bd -literal -offset indent +#! /bin/sh +exec /usr/sbin/ppp -direct incoming +.Ed +.Pp +Direct mode +.Pq Fl direct +lets +.Nm +work with stdin and stdout. +You can also use +.Xr pppctl 8 +to connect to a configured diagnostic port, in the same manner as with +client-side +.Nm . +.Pp +Here, the +.Ar incoming +section must be set up in +.Pa /etc/ppp/ppp.conf . +.Pp +Make sure that the +.Ar incoming +section contains the +.Dq allow users +command as appropriate. +.It +Prepare an account for the incoming user. +.Bd -literal +ppp:xxxx:66:66:PPP Login User:/home/ppp:/usr/local/bin/ppplogin +.Ed +.Pp +Refer to the manual entries for +.Xr adduser 8 +and +.Xr vipw 8 +for details. +.It +Support for IPCP Domain Name Server and NetBIOS Name Server negotiation +can be enabled using the +.Dq accept dns +and +.Dq set nbns +commands. +Refer to their descriptions below. +.El +.Sh RECEIVING INCOMING PPP CONNECTIONS (Method 2) +This method differs in that we use +.Nm +to authenticate the connection rather than +.Xr login 1 : +.Bl -enum +.It +Configure your default section in +.Pa /etc/gettytab +with automatic ppp recognition by specifying the +.Dq pp +capability: +.Bd -literal +default:\\ + :pp=/usr/local/bin/ppplogin:\\ + ..... +.Ed +.It +Configure your serial device(s), enable a +.Xr getty 8 +and create +.Pa /usr/local/bin/ppplogin +as in the first three steps for method 1 above. +.It +Add either +.Dq enable chap +or +.Dq enable pap +(or both) +to +.Pa /etc/ppp/ppp.conf +under the +.Sq incoming +label (or whatever label +.Pa ppplogin +uses). +.It +Create an entry in +.Pa /etc/ppp/ppp.secret +for each incoming user: +.Bd -literal +Pfred<TAB>xxxx +Pgeorge<TAB>yyyy +.Ed +.El +.Pp +Now, as soon as +.Xr getty 8 +detects a ppp connection (by recognising the HDLC frame headers), it runs +.Dq /usr/local/bin/ppplogin . +.Pp +It is +.Em VITAL +that either PAP or CHAP are enabled as above. +If they are not, you are +allowing anybody to establish a ppp session with your machine +.Em without +a password, opening yourself up to all sorts of potential attacks. +.Sh AUTHENTICATING INCOMING CONNECTIONS +Normally, the receiver of a connection requires that the peer +authenticates itself. +This may be done using +.Xr login 1 , +but alternatively, you can use PAP or CHAP. +CHAP is the more secure of the two, but some clients may not support it. +Once you decide which you wish to use, add the command +.Sq enable chap +or +.Sq enable pap +to the relevant section of +.Pa ppp.conf . +.Pp +You must then configure the +.Pa /etc/ppp/ppp.secret +file. +This file contains one line per possible client, each line +containing up to five fields: +.Pp +.Ar name Ar key Oo +.Ar hisaddr Op Ar label Op Ar callback-number +.Oc +.Pp +The +.Ar name +and +.Ar key +specify the client username and password. +If +.Ar key +is +.Dq \&* +and PAP is being used, +.Nm +will look up the password database +.Pq Xr passwd 5 +when authenticating. +If the client does not offer a suitable response based on any +.Ar name Ns No / Ns Ar key +combination in +.Pa ppp.secret , +authentication fails. +.Pp +If authentication is successful, +.Ar hisaddr +(if specified) +is used when negotiating IP numbers. +See the +.Dq set ifaddr +command for details. +.Pp +If authentication is successful and +.Ar label +is specified, the current system label is changed to match the given +.Ar label . +This will change the subsequent parsing of the +.Pa ppp.linkup +and +.Pa ppp.linkdown +files. +.Pp +If authentication is successful and +.Ar callback-number +is specified and +.Dq set callback +has been used in +.Pa ppp.conf , +the client will be called back on the given number. +If CBCP is being used, +.Ar callback-number +may also contain a list of numbers or a +.Dq \&* , +as if passed to the +.Dq set cbcp +command. +The value will be used in +.Nm Ns No 's +subsequent CBCP phase. +.Sh PPP OVER TCP and UDP (a.k.a Tunnelling) +Instead of running +.Nm +over a serial link, it is possible to +use a TCP connection instead by specifying the host, port and protocol as the +device: +.Pp +.Dl set device ui-gate:6669/tcp +.Pp +Instead of opening a serial device, +.Nm +will open a TCP connection to the given machine on the given +socket. +It should be noted however that +.Nm +does not use the telnet protocol and will be unable to negotiate +with a telnet server. +You should set up a port for receiving this +.Em PPP +connection on the receiving machine (ui-gate). +This is done by first updating +.Pa /etc/services +to name the service: +.Pp +.Dl ppp-in 6669/tcp # Incoming PPP connections over TCP +.Pp +and updating +.Pa /etc/inetd.conf +to tell +.Xr inetd 8 +how to deal with incoming connections on that port: +.Pp +.Dl ppp-in stream tcp nowait root /usr/sbin/ppp ppp -direct ppp-in +.Pp +Do not forget to send a +.Dv HUP +signal to +.Xr inetd 8 +after you have updated +.Pa /etc/inetd.conf . +Here, we use a label named +.Dq ppp-in . +The entry in +.Pa /etc/ppp/ppp.conf +on ui-gate (the receiver) should contain the following: +.Bd -literal -offset indent +ppp-in: + set timeout 0 + set ifaddr 10.0.4.1 10.0.4.2 +.Ed +.Pp +and the entry in +.Pa /etc/ppp/ppp.linkup +should contain: +.Bd -literal -offset indent +ppp-in: + add 10.0.1.0/24 HISADDR +.Ed +.Pp +It is necessary to put the +.Dq add +command in +.Pa ppp.linkup +to ensure that the route is only added after +.Nm +has negotiated and assigned addresses to its interface. +.Pp +You may also want to enable PAP or CHAP for security. +To enable PAP, add the following line: +.Bd -literal -offset indent + enable PAP +.Ed +.Pp +You will also need to create the following entry in +.Pa /etc/ppp/ppp.secret : +.Bd -literal -offset indent +MyAuthName MyAuthPasswd +.Ed +.Pp +If +.Ar MyAuthPasswd +is a +.Dq * , +the password is looked up in the +.Xr passwd 5 +database. +.Pp +The entry in +.Pa /etc/ppp/ppp.conf +on awfulhak (the initiator) should contain the following: +.Bd -literal -offset indent +ui-gate: + set escape 0xff + set device ui-gate:ppp-in/tcp + set dial + set timeout 30 + set log Phase Chat Connect hdlc LCP IPCP IPV6CP CCP tun + set ifaddr 10.0.4.2 10.0.4.1 +.Ed +.Pp +with the route setup in +.Pa /etc/ppp/ppp.linkup : +.Bd -literal -offset indent +ui-gate: + add 10.0.2.0/24 HISADDR +.Ed +.Pp +Again, if you are enabling PAP, you will also need this in the +.Pa /etc/ppp/ppp.conf +profile: +.Bd -literal -offset indent + set authname MyAuthName + set authkey MyAuthKey +.Ed +.Pp +We are assigning the address of 10.0.4.1 to ui-gate, and the address +10.0.4.2 to awfulhak. +To open the connection, just type +.Pp +.Dl awfulhak # ppp -background ui-gate +.Pp +The result will be an additional "route" on awfulhak to the +10.0.2.0/24 network via the TCP connection, and an additional +"route" on ui-gate to the 10.0.1.0/24 network. +The networks are effectively bridged - the underlying TCP +connection may be across a public network (such as the +Internet), and the +.Em PPP +traffic is conceptually encapsulated +(although not packet by packet) inside the TCP stream between +the two gateways. +.Pp +The major disadvantage of this mechanism is that there are two +"guaranteed delivery" mechanisms in place - the underlying TCP +stream and whatever protocol is used over the +.Em PPP +link - probably TCP again. +If packets are lost, both levels will +get in each others way trying to negotiate sending of the missing +packet. +.Pp +To avoid this overhead, it is also possible to do all this using +UDP instead of TCP as the transport by simply changing the protocol +from "tcp" to "udp". +When using UDP as a transport, +.Nm +will operate in synchronous mode. +This is another gain as the incoming +data does not have to be rearranged into packets. +.Pp +Care should be taken when adding a default route through a tunneled +setup like this. +It is quite common for the default route +(added in +.Pa /etc/ppp/ppp.linkup ) +to end up routing the link's TCP connection through the tunnel, +effectively garrotting the connection. +To avoid this, make sure you add a static route for the benefit of +the link: +.Bd -literal -offset indent +ui-gate: + set escape 0xff + set device ui-gate:ppp-in/tcp + add ui-gate x.x.x.x + ..... +.Ed +.Pp +where +.Dq x.x.x.x +is the IP number that your route to +.Dq ui-gate +would normally use. +.Pp +When routing your connection accross a public network such as the Internet, +it is preferable to encrypt the data. +This can be done with the help of the MPPE protocol, although currently this +means that you will not be able to also compress the traffic as MPPE is +implemented as a compression layer (thank Microsoft for this). +To enable MPPE encryption, add the following lines to +.Pa /etc/ppp/ppp.conf +on the server: +.Bd -literal -offset indent + enable MSCHAPv2 + disable deflate pred1 + deny deflate pred1 +.Ed +.Pp +ensuring that you have put the requisite entry in +.Pa /etc/ppp/ppp.secret +(MSCHAPv2 is challenge based, so +.Xr passwd 5 +cannot be used) +.Pp +MSCHAPv2 and MPPE are accepted by default, so the client end should work +without any additional changes (although ensure you have +.Dq set authname +and +.Dq set authkey +in your profile). +.Sh NETWORK ADDRESS TRANSLATION (PACKET ALIASING) +The +.Fl nat +command line option enables network address translation (a.k.a.\& packet +aliasing). +This allows the +.Nm +host to act as a masquerading gateway for other computers over +a local area network. +Outgoing IP packets are NAT'd so that they appear to come from the +.Nm +host, and incoming packets are de-NAT'd so that they are routed +to the correct machine on the local area network. +NAT allows computers on private, unregistered subnets to have Internet +access, although they are invisible from the outside world. +In general, correct +.Nm +operation should first be verified with network address translation disabled. +Then, the +.Fl nat +option should be switched on, and network applications (web browser, +.Xr telnet 1 , +.Xr ftp 1 , +.Xr ping 8 , +.Xr traceroute 8 ) +should be checked on the +.Nm +host. +Finally, the same or similar applications should be checked on other +computers in the LAN. +If network applications work correctly on the +.Nm +host, but not on other machines in the LAN, then the masquerading +software is working properly, but the host is either not forwarding +or possibly receiving IP packets. +Check that IP forwarding is enabled in +.Pa /etc/rc.conf +and that other machines have designated the +.Nm +host as the gateway for the LAN. +.Sh PACKET FILTERING +This implementation supports packet filtering. +There are four kinds of +filters: the +.Em in +filter, the +.Em out +filter, the +.Em dial +filter and the +.Em alive +filter. +Here are the basics: +.Bl -bullet +.It +A filter definition has the following syntax: +.Pp +set filter +.Ar name +.Ar rule-no +.Ar action +.Op !\& +.Oo +.Op host +.Ar src_addr Ns Op / Ns Ar width +.Op Ar dst_addr Ns Op / Ns Ar width +.Oc +.Ar [ proto Op src Ar cmp port +.Op dst Ar cmp port +.Op estab +.Op syn +.Op finrst +.Op timeout Ar secs ] +.Bl -enum +.It +.Ar Name +should be one of +.Sq in , +.Sq out , +.Sq dial +or +.Sq alive . +.It +.Ar Rule-no +is a numeric value between +.Sq 0 +and +.Sq 39 +specifying the rule number. +Rules are specified in numeric order according to +.Ar rule-no , +but only if rule +.Sq 0 +is defined. +.It +.Ar Action +may be specified as +.Sq permit +or +.Sq deny , +in which case, if a given packet matches the rule, the associated action +is taken immediately. +.Ar Action +can also be specified as +.Sq clear +to clear the action associated with that particular rule, or as a new +rule number greater than the current rule. +In this case, if a given +packet matches the current rule, the packet will next be matched against +the new rule number (rather than the next rule number). +.Pp +The +.Ar action +may optionally be followed with an exclamation mark +.Pq Dq !\& , +telling +.Nm +to reverse the sense of the following match. +.It +.Op Ar src_addr Ns Op / Ns Ar width +and +.Op Ar dst_addr Ns Op / Ns Ar width +are the source and destination IP number specifications. +If +.Op / Ns Ar width +is specified, it gives the number of relevant netmask bits, +allowing the specification of an address range. +.Pp +Either +.Ar src_addr +or +.Ar dst_addr +may be given the values +.Dv MYADDR , +.Dv HISADDR , +.Dv MYADDR6 +or +.Dv HISADDR6 +(refer to the description of the +.Dq bg +command for a description of these values). +When these values are used, +the filters will be updated any time the values change. +This is similar to the behaviour of the +.Dq add +command below. +.It +.Ar Proto +may be any protocol from +.Xr protocols 5 . +.It +.Ar Cmp +is one of +.Sq \< , +.Sq \&eq +or +.Sq \> , +meaning less-than, equal and greater-than respectively. +.Ar Port +can be specified as a numeric port or by service name from +.Pa /etc/services . +.It +The +.Sq estab , +.Sq syn , +and +.Sq finrst +flags are only allowed when +.Ar proto +is set to +.Sq tcp , +and represent the TH_ACK, TH_SYN and TH_FIN or TH_RST TCP flags respectively. +.It +The timeout value adjusts the current idle timeout to at least +.Ar secs +seconds. +If a timeout is given in the alive filter as well as in the in/out +filter, the in/out value is used. +If no timeout is given, the default timeout (set using +.Ic set timeout +and defaulting to 180 seconds) is used. +.El +.Pp +.It +Each filter can hold up to 40 rules, starting from rule 0. +The entire rule set is not effective until rule 0 is defined, +i.e., the default is to allow everything through. +.It +If no rule in a defined set of rules matches a packet, that packet will +be discarded (blocked). +If there are no rules in a given filter, the packet will be permitted. +.It +It is possible to filter based on the payload of UDP frames where those +frames contain a +.Em PROTO_IP +.Em PPP +frame header. +See the +.Ar filter-decapsulation +option below for further details. +.It +Use +.Dq set filter Ar name No -1 +to flush all rules. +.El +.Pp +See +.Pa /usr/share/examples/ppp/ppp.conf.sample . +.Sh SETTING THE IDLE TIMER +To check/set the idle timer, use the +.Dq show bundle +and +.Dq set timeout +commands: +.Bd -literal -offset indent +ppp ON awfulhak> set timeout 600 +.Ed +.Pp +The timeout period is measured in seconds, the default value for which +is 180 seconds +(or 3 min). +To disable the idle timer function, use the command +.Bd -literal -offset indent +ppp ON awfulhak> set timeout 0 +.Ed +.Pp +In +.Fl ddial +and +.Fl dedicated +modes, the idle timeout is ignored. +In +.Fl auto +mode, when the idle timeout causes the +.Em PPP +session to be +closed, the +.Nm +program itself remains running. +Another trigger packet will cause it to attempt to re-establish the link. +.Sh PREDICTOR-1 and DEFLATE COMPRESSION +.Nm +supports both Predictor type 1 and deflate compression. +By default, +.Nm +will attempt to use (or be willing to accept) both compression protocols +when the peer agrees +(or requests them). +The deflate protocol is preferred by +.Nm . +Refer to the +.Dq disable +and +.Dq deny +commands if you wish to disable this functionality. +.Pp +It is possible to use a different compression algorithm in each direction +by using only one of +.Dq disable deflate +and +.Dq deny deflate +(assuming that the peer supports both algorithms). +.Pp +By default, when negotiating DEFLATE, +.Nm +will use a window size of 15. +Refer to the +.Dq set deflate +command if you wish to change this behaviour. +.Pp +A special algorithm called DEFLATE24 is also available, and is disabled +and denied by default. +This is exactly the same as DEFLATE except that +it uses CCP ID 24 to negotiate. +This allows +.Nm +to successfully negotiate DEFLATE with +.Nm pppd +version 2.3.*. +.Sh CONTROLLING IP ADDRESS +For IPv4, +.Nm +uses IPCP to negotiate IP addresses. +Each side of the connection +specifies the IP address that it is willing to use, and if the requested +IP address is acceptable then +.Nm +returns an ACK to the requester. +Otherwise, +.Nm +returns NAK to suggest that the peer use a different IP address. +When +both sides of the connection agree to accept the received request (and +send an ACK), IPCP is set to the open state and a network level connection +is established. +To control this IPCP behaviour, this implementation has the +.Dq set ifaddr +command for defining the local and remote IP address: +.Bd -ragged -offset indent +.No set ifaddr Oo Ar src_addr Ns +.Op / Ns Ar \&nn +.Oo Ar dst_addr Ns Op / Ns Ar \&nn +.Oo Ar netmask +.Op Ar trigger_addr +.Oc +.Oc +.Oc +.Ed +.Pp +where, +.Sq src_addr +is the IP address that the local side is willing to use, +.Sq dst_addr +is the IP address which the remote side should use and +.Sq netmask +is the netmask that should be used. +.Sq Src_addr +defaults to the current +.Xr hostname 1 , +.Sq dst_addr +defaults to 0.0.0.0, and +.Sq netmask +defaults to whatever mask is appropriate for +.Sq src_addr . +It is only possible to make +.Sq netmask +smaller than the default. +The usual value is 255.255.255.255, as +most kernels ignore the netmask of a POINTOPOINT interface. +.Pp +Some incorrect +.Em PPP +implementations require that the peer negotiates a specific IP +address instead of +.Sq src_addr . +If this is the case, +.Sq trigger_addr +may be used to specify this IP number. +This will not affect the +routing table unless the other side agrees with this proposed number. +.Bd -literal -offset indent +set ifaddr 192.244.177.38 192.244.177.2 255.255.255.255 0.0.0.0 +.Ed +.Pp +The above specification means: +.Pp +.Bl -bullet -compact +.It +I will first suggest that my IP address should be 0.0.0.0, but I +will only accept an address of 192.244.177.38. +.It +I strongly insist that the peer uses 192.244.177.2 as his own +address and will not permit the use of any IP address but 192.244.177.2. +When the peer requests another IP address, I will always suggest that +it uses 192.244.177.2. +.It +The routing table entry will have a netmask of 0xffffffff. +.El +.Pp +This is all fine when each side has a pre-determined IP address, however +it is often the case that one side is acting as a server which controls +all IP addresses and the other side should go along with it. +In order to allow more flexible behaviour, the +.Dq set ifaddr +command allows the user to specify IP addresses more loosely: +.Pp +.Dl set ifaddr 192.244.177.38/24 192.244.177.2/20 +.Pp +A number followed by a slash +.Pq Dq / +represents the number of bits significant in the IP address. +The above example means: +.Pp +.Bl -bullet -compact +.It +I would like to use 192.244.177.38 as my address if it is possible, but I will +also accept any IP address between 192.244.177.0 and 192.244.177.255. +.It +I would like to make him use 192.244.177.2 as his own address, but I will also +permit him to use any IP address between 192.244.176.0 and +192.244.191.255. +.It +As you may have already noticed, 192.244.177.2 is equivalent to saying +192.244.177.2/32. +.It +As an exception, 0 is equivalent to 0.0.0.0/0, meaning that I have no +preferred IP address and will obey the remote peers selection. +When using zero, no routing table entries will be made until a connection +is established. +.It +192.244.177.2/0 means that I will accept/permit any IP address but I will +suggest that 192.244.177.2 be used first. +.El +.Pp +When negotiating IPv6 addresses, no control is given to the user. +IPV6CP negotiation is fully automatic. +.Sh CONNECTING WITH YOUR INTERNET SERVICE PROVIDER +The following steps should be taken when connecting to your ISP: +.Bl -enum +.It +Describe your providers phone number(s) in the dial script using the +.Dq set phone +command. +This command allows you to set multiple phone numbers for +dialing and redialing separated by either a pipe +.Pq Dq \&| +or a colon +.Pq Dq \&: : +.Bd -ragged -offset indent +.No set phone Ar telno Ns Xo +.Oo \&| Ns Ar backupnumber +.Oc Ns ... Ns Oo : Ns Ar nextnumber +.Oc Ns ... +.Xc +.Ed +.Pp +Numbers after the first in a pipe-separated list are only used if the +previous number was used in a failed dial or login script. +Numbers +separated by a colon are used sequentially, irrespective of what happened +as a result of using the previous number. +For example: +.Bd -literal -offset indent +set phone "1234567|2345678:3456789|4567890" +.Ed +.Pp +Here, the 1234567 number is attempted. +If the dial or login script fails, +the 2345678 number is used next time, but *only* if the dial or login script +fails. +On the dial after this, the 3456789 number is used. +The 4567890 +number is only used if the dial or login script using the 3456789 fails. +If the login script of the 2345678 number fails, the next number is still the +3456789 number. +As many pipes and colons can be used as are necessary +(although a given site would usually prefer to use either the pipe or the +colon, but not both). +The next number redial timeout is used between all numbers. +When the end of the list is reached, the normal redial period is +used before starting at the beginning again. +The selected phone number is substituted for the \\\\T string in the +.Dq set dial +command (see below). +.It +Set up your redial requirements using +.Dq set redial . +For example, if you have a bad telephone line or your provider is +usually engaged (not so common these days), you may want to specify +the following: +.Bd -literal -offset indent +set redial 10 4 +.Ed +.Pp +This says that up to 4 phone calls should be attempted with a pause of 10 +seconds before dialing the first number again. +.It +Describe your login procedure using the +.Dq set dial +and +.Dq set login +commands. +The +.Dq set dial +command is used to talk to your modem and establish a link with your +ISP, for example: +.Bd -literal -offset indent +set dial "ABORT BUSY ABORT NO\\\\sCARRIER TIMEOUT 4 \\"\\" \e + ATZ OK-ATZ-OK ATDT\\\\T TIMEOUT 60 CONNECT" +.Ed +.Pp +This modem "chat" string means: +.Bl -bullet +.It +Abort if the string "BUSY" or "NO CARRIER" are received. +.It +Set the timeout to 4 seconds. +.It +Expect nothing. +.It +Send ATZ. +.It +Expect OK. +If that is not received within the 4 second timeout, send ATZ +and expect OK. +.It +Send ATDTxxxxxxx where xxxxxxx is the next number in the phone list from +above. +.It +Set the timeout to 60. +.It +Wait for the CONNECT string. +.El +.Pp +Once the connection is established, the login script is executed. +This script is written in the same style as the dial script, but care should +be taken to avoid having your password logged: +.Bd -literal -offset indent +set authkey MySecret +set login "TIMEOUT 15 login:-\\\\r-login: awfulhak \e + word: \\\\P ocol: PPP HELLO" +.Ed +.Pp +This login "chat" string means: +.Bl -bullet +.It +Set the timeout to 15 seconds. +.It +Expect "login:". +If it is not received, send a carriage return and expect +"login:" again. +.It +Send "awfulhak" +.It +Expect "word:" (the tail end of a "Password:" prompt). +.It +Send whatever our current +.Ar authkey +value is set to. +.It +Expect "ocol:" (the tail end of a "Protocol:" prompt). +.It +Send "PPP". +.It +Expect "HELLO". +.El +.Pp +The +.Dq set authkey +command is logged specially. +When +.Ar command +or +.Ar chat +logging is enabled, the actual password is not logged; +.Sq ******** +is logged instead. +.Pp +Login scripts vary greatly between ISPs. +If you are setting one up for the first time, +.Em ENABLE CHAT LOGGING +so that you can see if your script is behaving as you expect. +.It +Use +.Dq set device +and +.Dq set speed +to specify your serial line and speed, for example: +.Bd -literal -offset indent +set device /dev/cuad0 +set speed 115200 +.Ed +.Pp +Cuad0 is the first serial port on +.Fx . +If you are running +.Nm +on +.Ox , +cua00 is the first. +A speed of 115200 should be specified +if you have a modem capable of bit rates of 28800 or more. +In general, the serial speed should be about four times the modem speed. +.It +Use the +.Dq set ifaddr +command to {define} the IP address. +.Bl -bullet +.It +If you know what IP address your provider uses, then use it as the remote +address (dst_addr), otherwise choose something like 10.0.0.2/0 (see below). +.It +If your provider has assigned a particular IP address to you, then use +it as your address (src_addr). +.It +If your provider assigns your address dynamically, choose a suitably +unobtrusive and unspecific IP number as your address. +10.0.0.1/0 would be appropriate. +The bit after the / specifies how many bits of the +address you consider to be important, so if you wanted to insist on +something in the class C network 1.2.3.0, you could specify 1.2.3.1/24. +.It +If you find that your ISP accepts the first IP number that you suggest, +specify third and forth arguments of +.Dq 0.0.0.0 . +This will force your ISP to assign a number. +(The third argument will +be ignored as it is less restrictive than the default mask for your +.Sq src_addr ) . +.El +.Pp +An example for a connection where you do not know your IP number or your +ISPs IP number would be: +.Bd -literal -offset indent +set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0 +.Ed +.Pp +.It +In most cases, your ISP will also be your default router. +If this is the case, add the line +.Bd -literal -offset indent +add default HISADDR +.Ed +.Pp +to +.Pa /etc/ppp/ppp.conf +(or to +.Pa /etc/ppp/ppp.linkup +for setups that do not use +.Fl auto +mode). +.Pp +This tells +.Nm +to add a default route to whatever the peer address is +(10.0.0.2 in this example). +This route is +.Sq sticky , +meaning that should the value of +.Dv HISADDR +change, the route will be updated accordingly. +.It +If your provider requests that you use PAP/CHAP authentication methods, add +the next lines to your +.Pa /etc/ppp/ppp.conf +file: +.Bd -literal -offset indent +set authname MyName +set authkey MyPassword +.Ed +.Pp +Both are accepted by default, so +.Nm +will provide whatever your ISP requires. +.Pp +It should be noted that a login script is rarely (if ever) required +when PAP or CHAP are in use. +.It +Ask your ISP to authenticate your nameserver address(es) with the line +.Bd -literal -offset indent +enable dns +.Ed +.Pp +Do +.Em NOT +do this if you are running a local DNS unless you also either use +.Dq resolv readonly +or have +.Dq resolv restore +in +.Pa /etc/ppp/ppp.linkdown , +as +.Nm +will simply circumvent its use by entering some nameserver lines in +.Pa /etc/resolv.conf . +.El +.Pp +Please refer to +.Pa /usr/share/examples/ppp/ppp.conf.sample +and +.Pa /usr/share/examples/ppp/ppp.linkup.sample +for some real examples. +The pmdemand label should be appropriate for most ISPs. +.Sh LOGGING FACILITY +.Nm +is able to generate the following log info either via +.Xr syslog 3 +or directly to the screen: +.Pp +.Bl -tag -width XXXXXXXXX -offset XXX -compact +.It Li All +Enable all logging facilities. +This generates a lot of log. +The most common use of 'all' is as a basis, where you remove some facilities +after enabling 'all' ('debug' and 'timer' are usually best disabled.) +.It Li Async +Dump async level packet in hex. +.It Li CBCP +Generate CBCP (CallBack Control Protocol) logs. +.It Li CCP +Generate a CCP packet trace. +.It Li Chat +Generate +.Sq dial , +.Sq login , +.Sq logout +and +.Sq hangup +chat script trace logs. +.It Li Command +Log commands executed either from the command line or any of the configuration +files. +.It Li Connect +Log Chat lines containing the string "CONNECT". +.It Li Debug +Log debug information. +.It Li DNS +Log DNS QUERY packets. +.It Li Filter +Log packets permitted by the dial filter and denied by any filter. +.It Li HDLC +Dump HDLC packet in hex. +.It Li ID0 +Log all function calls specifically made as user id 0. +.It Li IPCP +Generate an IPCP packet trace. +.It Li LCP +Generate an LCP packet trace. +.It Li LQM +Generate LQR reports. +.It Li Phase +Phase transition log output. +.It Li Physical +Dump physical level packet in hex. +.It Li Radius +Dump RADIUS information. +RADIUS information resulting from the link coming up or down is logged at +.Dq Phase +level unless +.Dq Radius +logging is enabled. +This log level is most useful for monitoring RADIUS alive information. +.It Li Sync +Dump sync level packet in hex. +.It Li TCP/IP +Dump all TCP/IP packets. +.It Li Timer +Log timer manipulation. +.It Li TUN +Include the tun device on each log line. +.It Li Warning +Output to the terminal device. +If there is currently no terminal, +output is sent to the log file using syslogs +.Dv LOG_WARNING . +.It Li Error +Output to both the terminal device +and the log file using syslogs +.Dv LOG_ERROR . +.It Li Alert +Output to the log file using +.Dv LOG_ALERT . +.El +.Pp +The +.Dq set log +command allows you to set the logging output level. +Multiple levels can be specified on a single command line. +The default is equivalent to +.Dq set log Phase . +.Pp +It is also possible to log directly to the screen. +The syntax is the same except that the word +.Dq local +should immediately follow +.Dq set log . +The default is +.Dq set log local +(i.e., only the un-maskable warning, error and alert output). +.Pp +If The first argument to +.Dq set log Op local +begins with a +.Sq + +or a +.Sq - +character, the current log levels are +not cleared, for example: +.Bd -literal -offset indent +PPP ON awfulhak> set log phase +PPP ON awfulhak> show log +Log: Phase Warning Error Alert +Local: Warning Error Alert +PPP ON awfulhak> set log +tcp/ip -warning +PPP ON awfulhak> set log local +command +PPP ON awfulhak> show log +Log: Phase TCP/IP Warning Error Alert +Local: Command Warning Error Alert +.Ed +.Pp +Log messages of level Warning, Error and Alert are not controllable +using +.Dq set log Op local . +.Pp +The +.Ar Warning +level is special in that it will not be logged if it can be displayed +locally. +.Sh SIGNAL HANDLING +.Nm +deals with the following signals: +.Bl -tag -width "USR2" +.It INT +Receipt of this signal causes the termination of the current connection +(if any). +This will cause +.Nm +to exit unless it is in +.Fl auto +or +.Fl ddial +mode. +.It HUP, TERM & QUIT +These signals tell +.Nm +to exit. +.It USR1 +This signal, tells +.Nm +to re-open any existing server socket, dropping all existing diagnostic +connections. +Sockets that could not previously be opened will be retried. +.It USR2 +This signal, tells +.Nm +to close any existing server socket, dropping all existing diagnostic +connections. +.Dv SIGUSR1 +can still be used to re-open the socket. +.El +.Sh MULTI-LINK PPP +If you wish to use more than one physical link to connect to a +.Em PPP +peer, that peer must also understand the +.Em MULTI-LINK PPP +protocol. +Refer to RFC 1990 for specification details. +.Pp +The peer is identified using a combination of his +.Dq endpoint discriminator +and his +.Dq authentication id . +Either or both of these may be specified. +It is recommended that +at least one is specified, otherwise there is no way of ensuring that +all links are actually connected to the same peer program, and some +confusing lock-ups may result. +Locally, these identification variables are specified using the +.Dq set enddisc +and +.Dq set authname +commands. +The +.Sq authname +(and +.Sq authkey ) +must be agreed in advance with the peer. +.Pp +Multi-link capabilities are enabled using the +.Dq set mrru +command (set maximum reconstructed receive unit). +Once multi-link is enabled, +.Nm +will attempt to negotiate a multi-link connection with the peer. +.Pp +By default, only one +.Sq link +is available +(called +.Sq deflink ) . +To create more links, the +.Dq clone +command is used. +This command will clone existing links, where all +characteristics are the same except: +.Bl -enum +.It +The new link has its own name as specified on the +.Dq clone +command line. +.It +The new link is an +.Sq interactive +link. +Its mode may subsequently be changed using the +.Dq set mode +command. +.It +The new link is in a +.Sq closed +state. +.El +.Pp +A summary of all available links can be seen using the +.Dq show links +command. +.Pp +Once a new link has been created, command usage varies. +All link specific commands must be prefixed with the +.Dq link Ar name +command, specifying on which link the command is to be applied. +When only a single link is available, +.Nm +is smart enough not to require the +.Dq link Ar name +prefix. +.Pp +Some commands can still be used without specifying a link - resulting +in an operation at the +.Sq bundle +level. +For example, once two or more links are available, the command +.Dq show ccp +will show CCP configuration and statistics at the multi-link level, and +.Dq link deflink show ccp +will show the same information at the +.Dq deflink +link level. +.Pp +Armed with this information, the following configuration might be used: +.Pp +.Bd -literal -offset indent +mp: + set timeout 0 + set log phase chat + set device /dev/cuad0 /dev/cuad1 /dev/cuad2 + set phone "123456789" + set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \\"\\" ATZ \e + OK-AT-OK \\\\dATDT\\\\T TIMEOUT 45 CONNECT" + set login + set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0 + set authname ppp + set authkey ppppassword + + set mrru 1500 + clone 1,2,3 # Create 3 new links - duplicates of the default + link deflink remove # Delete the default link (called ``deflink'') +.Ed +.Pp +Note how all cloning is done at the end of the configuration. +Usually, the link will be configured first, then cloned. +If you wish all links +to be up all the time, you can add the following line to the end of your +configuration. +.Pp +.Bd -literal -offset indent + link 1,2,3 set mode ddial +.Ed +.Pp +If you want the links to dial on demand, this command could be used: +.Pp +.Bd -literal -offset indent + link * set mode auto +.Ed +.Pp +Links may be tied to specific names by removing the +.Dq set device +line above, and specifying the following after the +.Dq clone +command: +.Pp +.Bd -literal -offset indent + link 1 set device /dev/cuad0 + link 2 set device /dev/cuad1 + link 3 set device /dev/cuad2 +.Ed +.Pp +Use the +.Dq help +command to see which commands require context (using the +.Dq link +command), which have optional +context and which should not have any context. +.Pp +When +.Nm +has negotiated +.Em MULTI-LINK +mode with the peer, it creates a local domain socket in the +.Pa /var/run +directory. +This socket is used to pass link information (including +the actual link file descriptor) between different +.Nm +invocations. +This facilitates +.Nm Ns No 's +ability to be run from a +.Xr getty 8 +or directly from +.Pa /etc/gettydefs +(using the +.Sq pp= +capability), without needing to have initial control of the serial +line. +Once +.Nm +negotiates multi-link mode, it will pass its open link to any +already running process. +If there is no already running process, +.Nm +will act as the master, creating the socket and listening for new +connections. +.Sh PPP COMMAND LIST +This section lists the available commands and their effect. +They are usable either from an interactive +.Nm +session, from a configuration file or from a +.Xr pppctl 8 +or +.Xr telnet 1 +session. +.Bl -tag -width 2n +.It accept|deny|enable|disable Ar option.... +These directives tell +.Nm +how to negotiate the initial connection with the peer. +Each +.Dq option +has a default of either accept or deny and enable or disable. +.Dq Accept +means that the option will be ACK'd if the peer asks for it. +.Dq Deny +means that the option will be NAK'd if the peer asks for it. +.Dq Enable +means that the option will be requested by us. +.Dq Disable +means that the option will not be requested by us. +.Pp +.Dq Option +may be one of the following: +.Bl -tag -width 2n +.It acfcomp +Default: Enabled and Accepted. +ACFComp stands for Address and Control Field Compression. +Non LCP packets will usually have an address +field of 0xff (the All-Stations address) and a control field of +0x03 (the Unnumbered Information command). +If this option is +negotiated, these two bytes are simply not sent, thus minimising +traffic. +.Pp +See +.Pa rfc1662 +for details. +.It chap Ns Op \&05 +Default: Disabled and Accepted. +CHAP stands for Challenge Handshake Authentication Protocol. +Only one of CHAP and PAP (below) may be negotiated. +With CHAP, the authenticator sends a "challenge" message to its peer. +The peer uses a one-way hash function to encrypt the +challenge and sends the result back. +The authenticator does the same, and compares the results. +The advantage of this mechanism is that no +passwords are sent across the connection. +A challenge is made when the connection is first made. +Subsequent challenges may occur. +If you want to have your peer authenticate itself, you must +.Dq enable chap . +in +.Pa /etc/ppp/ppp.conf , +and have an entry in +.Pa /etc/ppp/ppp.secret +for the peer. +.Pp +When using CHAP as the client, you need only specify +.Dq AuthName +and +.Dq AuthKey +in +.Pa /etc/ppp/ppp.conf . +CHAP is accepted by default. +Some +.Em PPP +implementations use "MS-CHAP" rather than MD5 when encrypting the +challenge. +MS-CHAP is a combination of MD4 and DES. +If +.Nm +was built on a machine with DES libraries available, it will respond +to MS-CHAP authentication requests, but will never request them. +.It deflate +Default: Enabled and Accepted. +This option decides if deflate +compression will be used by the Compression Control Protocol (CCP). +This is the same algorithm as used by the +.Xr gzip 1 +program. +Note: There is a problem negotiating +.Ar deflate +capabilities with +.Xr pppd 8 +- a +.Em PPP +implementation available under many operating systems. +.Nm pppd +(version 2.3.1) incorrectly attempts to negotiate +.Ar deflate +compression using type +.Em 24 +as the CCP configuration type rather than type +.Em 26 +as specified in +.Pa rfc1979 . +Type +.Ar 24 +is actually specified as +.Dq PPP Magna-link Variable Resource Compression +in +.Pa rfc1975 ! +.Nm +is capable of negotiating with +.Nm pppd , +but only if +.Dq deflate24 +is +.Ar enable Ns No d +and +.Ar accept Ns No ed . +.It deflate24 +Default: Disabled and Denied. +This is a variance of the +.Ar deflate +option, allowing negotiation with the +.Xr pppd 8 +program. +Refer to the +.Ar deflate +section above for details. +It is disabled by default as it violates +.Pa rfc1975 . +.It dns +Default: Disabled and Denied. +This option allows DNS negotiation. +.Pp +If +.Dq enable Ns No d, +.Nm +will request that the peer confirms the entries in +.Pa /etc/resolv.conf . +If the peer NAKs our request (suggesting new IP numbers), +.Pa /etc/resolv.conf +is updated and another request is sent to confirm the new entries. +.Pp +If +.Dq accept Ns No ed, +.Nm +will answer any DNS queries requested by the peer rather than rejecting +them. +The answer is taken from +.Pa /etc/resolv.conf +unless the +.Dq set dns +command is used as an override. +.It enddisc +Default: Enabled and Accepted. +This option allows control over whether we +negotiate an endpoint discriminator. +We only send our discriminator if +.Dq set enddisc +is used and +.Ar enddisc +is enabled. +We reject the peers discriminator if +.Ar enddisc +is denied. +.It LANMan|chap80lm +Default: Disabled and Accepted. +The use of this authentication protocol +is discouraged as it partially violates the authentication protocol by +implementing two different mechanisms (LANMan & NT) under the guise of +a single CHAP type (0x80). +.Dq LANMan +uses a simple DES encryption mechanism and is the least secure of the +CHAP alternatives (although is still more secure than PAP). +.Pp +Refer to the +.Dq MSChap +description below for more details. +.It lqr +Default: Disabled and Accepted. +This option decides if Link Quality Requests will be sent or accepted. +LQR is a protocol that allows +.Nm +to determine that the link is down without relying on the modems +carrier detect. +When LQR is enabled, +.Nm +sends the +.Em QUALPROTO +option (see +.Dq set lqrperiod +below) as part of the LCP request. +If the peer agrees, both sides will +exchange LQR packets at the agreed frequency, allowing detailed link +quality monitoring by enabling LQM logging. +If the peer does not agree, and if the +.Dq echo +option is enabled, +.Nm +will send +.Em LCP ECHO +requests instead. +These packets pass no information of interest, but they +.Em MUST +be replied to by the peer. +.Pp +Whether using +.Em LQR +or +.Em LCP ECHO , +.Nm +will abruptly drop the connection if 5 unacknowledged packets have been +sent rather than sending a 6th. +A message is logged at the +.Em PHASE +level, and any appropriate +.Dq reconnect +values are honoured as if the peer were responsible for dropping the +connection. +.Pp +Refer to the +.Dq enable echo +command description for differences in behaviour prior to +.Nm +version 3.4.2. +.It mppe +Default: Enabled and Accepted. +This is Microsoft Point to Point Encryption scheme. +MPPE key size can be +40-, 56- and 128-bits. +Refer to +.Dq set mppe +command. +.It MSChapV2|chap81 +Default: Disabled and Accepted. +It is very similar to standard CHAP (type 0x05) +except that it issues challenges of a fixed 16 bytes in length and uses a +combination of MD4, SHA-1 and DES to encrypt the challenge rather than using the +standard MD5 mechanism. +.It MSChap|chap80nt +Default: Disabled and Accepted. +The use of this authentication protocol +is discouraged as it partially violates the authentication protocol by +implementing two different mechanisms (LANMan & NT) under the guise of +a single CHAP type (0x80). +It is very similar to standard CHAP (type 0x05) +except that it issues challenges of a fixed 8 bytes in length and uses a +combination of MD4 and DES to encrypt the challenge rather than using the +standard MD5 mechanism. +CHAP type 0x80 for LANMan is also supported - see +.Dq enable LANMan +for details. +.Pp +Because both +.Dq LANMan +and +.Dq NT +use CHAP type 0x80, when acting as authenticator with both +.Dq enable Ns No d , +.Nm +will rechallenge the peer up to three times if it responds using the wrong +one of the two protocols. +This gives the peer a chance to attempt using both protocols. +.Pp +Conversely, when +.Nm +acts as the authenticatee with both protocols +.Dq accept Ns No ed , +the protocols are used alternately in response to challenges. +.Pp +Note: If only LANMan is enabled, +.Xr pppd 8 +(version 2.3.5) misbehaves when acting as authenticatee. +It provides both +the NT and the LANMan answers, but also suggests that only the NT answer +should be used. +.It pap +Default: Disabled and Accepted. +PAP stands for Password Authentication Protocol. +Only one of PAP and CHAP (above) may be negotiated. +With PAP, the ID and Password are sent repeatedly to the peer until +authentication is acknowledged or the connection is terminated. +This is a rather poor security mechanism. +It is only performed when the connection is first established. +If you want to have your peer authenticate itself, you must +.Dq enable pap . +in +.Pa /etc/ppp/ppp.conf , +and have an entry in +.Pa /etc/ppp/ppp.secret +for the peer (although see the +.Dq passwdauth +and +.Dq set radius +options below). +.Pp +When using PAP as the client, you need only specify +.Dq AuthName +and +.Dq AuthKey +in +.Pa /etc/ppp/ppp.conf . +PAP is accepted by default. +.It pred1 +Default: Enabled and Accepted. +This option decides if Predictor 1 +compression will be used by the Compression Control Protocol (CCP). +.It protocomp +Default: Enabled and Accepted. +This option is used to negotiate +PFC (Protocol Field Compression), a mechanism where the protocol +field number is reduced to one octet rather than two. +.It shortseq +Default: Enabled and Accepted. +This option determines if +.Nm +will request and accept requests for short +(12 bit) +sequence numbers when negotiating multi-link mode. +This is only applicable if our MRRU is set (thus enabling multi-link). +.It vjcomp +Default: Enabled and Accepted. +This option determines if Van Jacobson header compression will be used. +.El +.Pp +The following options are not actually negotiated with the peer. +Therefore, accepting or denying them makes no sense. +.Bl -tag -width 2n +.It echo +Default: Disabled. +When this option is enabled, +.Nm +will send +.Em LCP ECHO +requests to the peer at the frequency defined by +.Dq echoperiod . +Note, +.Em LQR +requests will supersede +.Em LCP ECHO +requests if enabled and negotiated. +See +.Dq set lqrperiod +below for details. +.Pp +Prior to +.Nm +version 3.4.2, +.Dq echo +was considered enabled if lqr was enabled and negotiated, otherwise it was +considered disabled. +For the same behaviour, it is now necessary to +.Dq enable lqr echo +rather than just +.Dq enable lqr . +.It filter-decapsulation +Default: Disabled. +When this option is enabled, +.Nm +will examine UDP frames to see if they actually contain a +.Em PPP +frame as their payload. +If this is the case, all filters will operate on the payload rather +than the actual packet. +.Pp +This is useful if you want to send PPPoUDP traffic over a +.Em PPP +link, but want that link to do smart things with the real data rather than +the UDP wrapper. +.Pp +The UDP frame payload must not be compressed in any way, otherwise +.Nm +will not be able to interpret it. +It is therefore recommended that you +.Ic disable vj pred1 deflate +and +.Ic deny vj pred1 deflate +in the configuration for the +.Nm +invocation with the udp link. +.It force-scripts +Default: Disabled. +Forces execution of the configured chat scripts in +.Dv direct +and +.Dv dedicated +modes. +.It idcheck +Default: Enabled. +When +.Nm +exchanges low-level LCP, CCP and IPCP configuration traffic, the +.Em Identifier +field of any replies is expected to be the same as that of the request. +By default, +.Nm +drops any reply packets that do not contain the expected identifier +field, reporting the fact at the respective log level. +If +.Ar idcheck +is disabled, +.Nm +will ignore the identifier field. +.It iface-alias +Default: Enabled if +.Fl nat +is specified. +This option simply tells +.Nm +to add new interface addresses to the interface rather than replacing them. +The option can only be enabled if network address translation is enabled +.Pq Dq nat enable yes . +.Pp +With this option enabled, +.Nm +will pass traffic for old interface addresses through the NAT +ifdef({LOCALNAT},{engine,},{engine +(see +.Xr libalias 3 ) ,}) +resulting in the ability (in +.Fl auto +mode) to properly connect the process that caused the PPP link to +come up in the first place. +.Pp +Disabling NAT with +.Dq nat enable no +will also disable +.Sq iface-alias . +.It ipcp +Default: Enabled. +This option allows +.Nm +to attempt to negotiate IP control protocol capabilities and if +successful to exchange IP datagrams with the peer. +.It ipv6cp +Default: Enabled. +This option allows +.Nm +to attempt to negotiate IPv6 control protocol capabilities and if +successful to exchange IPv6 datagrams with the peer. +.It keep-session +Default: Disabled. +When +.Nm +runs as a Multi-link server, a different +.Nm +instance initially receives each connection. +After determining that +the link belongs to an already existing bundle (controlled by another +.Nm +invocation), +.Nm +will transfer the link to that process. +.Pp +If the link is a tty device or if this option is enabled, +.Nm +will not exit, but will change its process name to +.Dq session owner +and wait for the controlling +.Nm +to finish with the link and deliver a signal back to the idle process. +This prevents the confusion that results from +.Nm Ns No 's +parent considering the link resource available again. +.Pp +For tty devices that have entries in +.Pa /etc/ttys , +this is necessary to prevent another +.Xr getty 8 +from being started, and for program links such as +.Xr sshd 8 , +it prevents +.Xr sshd 8 +from exiting due to the death of its child. +As +.Nm +cannot determine its parents requirements (except for the tty case), this +option must be enabled manually depending on the circumstances. +.It loopback +Default: Enabled. +When +.Ar loopback +is enabled, +.Nm +will automatically loop back packets being sent +out with a destination address equal to that of the +.Em PPP +interface. +If disabled, +.Nm +will send the packet, probably resulting in an ICMP redirect from +the other end. +It is convenient to have this option enabled when +the interface is also the default route as it avoids the necessity +of a loopback route. +.It NAS-IP-Address +Default: Enabled. +This option controls whether +.Nm +sends the +.Dq NAS-IP-Address +attribute to the RADIUS server when RADIUS is in use +.Pq see Dq set radius . +.Pp +Note, at least one of +.Dq NAS-IP-Address +and +.Dq NAS-Identifier +must be enabled. +.Pp +Versions of +.Nm +prior to version 3.4.1 did not send the +.Dq NAS-IP-Address +attribute as it was reported to break the Radiator RADIUS server. +As the latest rfc (2865) no longer hints that only one of +.Dq NAS-IP-Address +and +.Dq NAS-Identifier +should be sent (as rfc 2138 did), +.Nm +now sends both and leaves it up to the administrator that chooses to use +bad RADIUS implementations to +.Dq disable NAS-IP-Address . +.It NAS-Identifier +Default: Enabled. +This option controls whether +.Nm +sends the +.Dq NAS-Identifier +attribute to the RADIUS server when RADIUS is in use +.Pq see Dq set radius . +.Pp +Note, at least one of +.Dq NAS-IP-Address +and +.Dq NAS-Identifier +must be enabled. +.It passwdauth +Default: Disabled. +Enabling this option will tell the PAP authentication +code to use the password database (see +.Xr passwd 5 ) +to authenticate the caller if they cannot be found in the +.Pa /etc/ppp/ppp.secret +file. +.Pa /etc/ppp/ppp.secret +is always checked first. +If you wish to use passwords from +.Xr passwd 5 , +but also to specify an IP number or label for a given client, use +.Dq \&* +as the client password in +.Pa /etc/ppp/ppp.secret . +.It proxy +Default: Disabled. +Enabling this option will tell +.Nm +to proxy ARP for the peer. +This means that +.Nm +will make an entry in the ARP table using +.Dv HISADDR +and the +.Dv MAC +address of the local network in which +.Dv HISADDR +appears. +This allows other machines connecteed to the LAN to talk to +the peer as if the peer itself was connected to the LAN. +The proxy entry cannot be made unless +.Dv HISADDR +is an address from a LAN. +.It proxyall +Default: Disabled. +Enabling this will tell +.Nm +to add proxy arp entries for every IP address in all class C or +smaller subnets routed via the tun interface. +.Pp +Proxy arp entries are only made for sticky routes that are added +using the +.Dq add +command. +No proxy arp entries are made for the interface address itself +(as created by the +.Dq set ifaddr +command). +.It sroutes +Default: Enabled. +When the +.Dq add +command is used with the +.Dv HISADDR , +.Dv MYADDR , +.Dv HISADDR6 +or +.Dv MYADDR6 +values, entries are stored in the +.Sq sticky route +list. +Each time these variables change, this list is re-applied to the routing table. +.Pp +Disabling this option will prevent the re-application of sticky routes, +although the +.Sq stick route +list will still be maintained. +.It Op tcp Ns Xo +.No mssfixup +.Xc +Default: Enabled. +This option tells +.Nm +to adjust TCP SYN packets so that the maximum receive segment +size is not greater than the amount allowed by the interface MTU. +.It throughput +Default: Enabled. +This option tells +.Nm +to gather throughput statistics. +Input and output is sampled over +a rolling 5 second window, and current, best and total figures are retained. +This data is output when the relevant +.Em PPP +layer shuts down, and is also available using the +.Dq show +command. +Throughput statistics are available at the +.Dq IPCP +and +.Dq physical +levels. +.It utmp +Default: Enabled. +Normally, when a user is authenticated using PAP or CHAP, and when +.Nm +is running in +.Fl direct +mode, an entry is made in the utmp and wtmp files for that user. +Disabling this option will tell +.Nm +not to make any utmp or wtmp entries. +This is usually only necessary if +you require the user to both login and authenticate themselves. +.El +.Pp +.It add Ns Xo +.Op !\& +.Ar dest Ns Op / Ns Ar nn +.Op Ar mask +.Op Ar gateway +.Xc +.Ar Dest +is the destination IP address. +The netmask is specified either as a number of bits with +.Ar /nn +or as an IP number using +.Ar mask . +.Ar 0 0 +or simply +.Ar 0 +with no mask refers to the default route. +It is also possible to use the literal name +.Sq default +instead of +.Ar 0 . +.Ar Gateway +is the next hop gateway to get to the given +.Ar dest +machine/network. +Refer to the +.Xr route 8 +command for further details. +.Pp +It is possible to use the symbolic names +.Sq MYADDR , +.Sq HISADDR , +.Sq MYADDR6 +or +.Sq HISADDR6 +as the destination, and +.Sq HISADDR +or +.Sq HISADDR6 +as the +.Ar gateway . +.Sq MYADDR +is replaced with the interface IP address, +.Sq HISADDR +is replaced with the interface IP destination (peer) address, +.Sq MYADDR6 +is replaced with the interface IPv6 address, and +.Sq HISADDR6 +is replaced with the interface IPv6 destination address, +.Pp +If the +.Ar add!\& +command is used +(note the trailing +.Dq !\& ) , +then if the route already exists, it will be updated as with the +.Sq route change +command (see +.Xr route 8 +for further details). +.Pp +Routes that contain the +.Dq HISADDR , +.Dq MYADDR , +.Dq HISADDR6 , +.Dq MYADDR6 , +.Dq DNS0 , +or +.Dq DNS1 +constants are considered +.Sq sticky . +They are stored in a list (use +.Dq show ncp +to see the list), and each time the value of one of these variables +changes, the appropriate routing table entries are updated. +This facility may be disabled using +.Dq disable sroutes . +.It allow Ar command Op Ar args +This command controls access to +.Nm +and its configuration files. +It is possible to allow user-level access, +depending on the configuration file label and on the mode that +.Nm +is being run in. +For example, you may wish to configure +.Nm +so that only user +.Sq fred +may access label +.Sq fredlabel +in +.Fl background +mode. +.Pp +User id 0 is immune to these commands. +.Bl -tag -width 2n +.It allow user Ns Xo +.Op s +.Ar logname Ns No ... +.Xc +By default, only user id 0 is allowed access to +.Nm . +If this command is used, all of the listed users are allowed access to +the section in which the +.Dq allow users +command is found. +The +.Sq default +section is always checked first (even though it is only ever automatically +loaded at startup). +.Dq allow users +commands are cumulative in a given section, but users allowed in any given +section override users allowed in the default section, so it is possible to +allow users access to everything except a given label by specifying default +users in the +.Sq default +section, and then specifying a new user list for that label. +.Pp +If user +.Sq * +is specified, access is allowed to all users. +.It allow mode Ns Xo +.Op s +.Ar mode Ns No ... +.Xc +By default, access using any +.Nm +mode is possible. +If this command is used, it restricts the access +.Ar modes +allowed to load the label under which this command is specified. +Again, as with the +.Dq allow users +command, each +.Dq allow modes +command overrides any previous settings, and the +.Sq default +section is always checked first. +.Pp +Possible modes are: +.Sq interactive , +.Sq auto , +.Sq direct , +.Sq dedicated , +.Sq ddial , +.Sq background +and +.Sq * . +.Pp +When running in multi-link mode, a section can be loaded if it allows +.Em any +of the currently existing line modes. +.El +.Pp +.It nat Ar command Op Ar args +This command allows the control of the network address translation (also +known as masquerading or IP aliasing) facilities that are built into +.Nm . +NAT is done on the external interface only, and is unlikely to make sense +if used with the +.Fl direct +flag. +.Pp +If nat is enabled on your system (it may be omitted at compile time), +the following commands are possible: +.Bl -tag -width 2n +.It nat enable yes|no +This command either switches network address translation on or turns it off. +The +.Fl nat +command line flag is synonymous with +.Dq nat enable yes . +.It nat addr Op Ar addr_local addr_alias +This command allows data for +.Ar addr_alias +to be redirected to +.Ar addr_local . +It is useful if you own a small number of real IP numbers that +you wish to map to specific machines behind your gateway. +.It nat deny_incoming yes|no +If set to yes, this command will refuse all incoming packets where an +aliasing link does not already exist. +ifdef({LOCALNAT},{},{Refer to the +.Sx CONCEPTUAL BACKGROUND +section of +.Xr libalias 3 +for a description of what an +.Dq aliasing link +is. +})dnl +.Pp +It should be noted under what circumstances an aliasing link is +ifdef({LOCALNAT},{created.},{created by +.Xr libalias 3 .}) +It may be necessary to further protect your network from outside +connections using the +.Dq set filter +or +.Dq nat target +commands. +.It nat help|? +This command gives a summary of available nat commands. +.It nat log yes|no +This option causes various NAT statistics and information to +be logged to the file +.Pa /var/log/alias.log . +.It nat port Ar proto Ar targetIP Ns Xo +.No : Ns Ar targetPort Ns +.Oo +.No - Ns Ar targetPort +.Oc Ar aliasPort Ns +.Oo +.No - Ns Ar aliasPort +.Oc Oo Ar remoteIP : Ns +.Ar remotePort Ns +.Oo +.No - Ns Ar remotePort +.Oc Ns +.Oc +.Xc +This command causes incoming +.Ar proto +connections to +.Ar aliasPort +to be redirected to +.Ar targetPort +on +.Ar targetIP . +.Ar proto +is either +.Dq tcp +or +.Dq udp . +.Pp +A range of port numbers may be specified as shown above. +The ranges must be of the same size. +.Pp +If +.Ar remoteIP +is specified, only data coming from that IP number is redirected. +.Ar remotePort +must either be +.Dq 0 +(indicating any source port) +or a range of ports the same size as the other ranges. +.Pp +This option is useful if you wish to run things like Internet phone on +machines behind your gateway, but is limited in that connections to only +one interior machine per source machine and target port are possible. +.It nat proto Ar proto localIP Oo +.Ar publicIP Op Ar remoteIP +.Oc +This command tells +.Nm +to redirect packets of protocol type +.Ar proto +(see +.Xr protocols 5 ) +to the internal address +.Ar localIP . +.Pp +If +.Ar publicIP +is specified, only packets destined for that address are matched, +otherwise the default alias address is used. +.Pp +If +.Ar remoteIP +is specified, only packets matching that source address are matched, +.Pp +This command is useful for redirecting tunnel endpoints to an internal machine, +for example: +.Pp +.Dl nat proto ipencap 10.0.0.1 +.It "nat proxy cmd" Ar arg Ns No ... +This command tells +.Nm +to proxy certain connections, redirecting them to a given server. +ifdef({LOCALNAT},{},{Refer to the description of +.Fn PacketAliasProxyRule +in +.Xr libalias 3 +for details of the available commands. +})dnl +.It nat punch_fw Op Ar base count +This command tells +.Nm +to punch holes in the firewall for FTP or IRC DCC connections. +This is done dynamically by installing termporary firewall rules which +allow a particular connection (and only that connection) to go through +the firewall. +The rules are removed once the corresponding connection terminates. +.Pp +A maximum of +.Ar count +rules starting from rule number +.Ar base +will be used for punching firewall holes. +The range will be cleared when the +.Dq nat punch_fw +command is run. +.Pp +If no arguments are given, firewall punching is disabled. +.It nat skinny_port Op Ar port +This command tells +.Nm +which TCP port is used by the Skinny Station protocol. +Skinny is used by +Cisco IP phones to communicate with Cisco Call Managers to setup voice +over IP calls. +The typical port used by Skinny is 2000. +.Pp +If no argument is given, skinny aliasing is disabled. +.It nat same_ports yes|no +When enabled, this command will tell the network address translation engine to +attempt to avoid changing the port number on outgoing packets. +This is useful +if you want to support protocols such as RPC and LPD which require +connections to come from a well known port. +.It nat target Op Ar address +Set the given target address or clear it if no address is given. +The target address is used +ifdef({LOCALNAT},{},{by libalias })dnl +to specify how to NAT incoming packets by default. +If a target address is not set or if +.Dq default +is given, packets are not altered and are allowed to route to the internal +network. +.Pp +The target address may be set to +.Dq MYADDR , +in which case +ifdef({LOCALNAT},{all packets will be redirected}, +{libalias will redirect all packets}) +to the interface address. +.It nat use_sockets yes|no +When enabled, this option tells the network address translation engine to +create a socket so that it can guarantee a correct incoming ftp data or +IRC connection. +.It nat unregistered_only yes|no +Only alter outgoing packets with an unregistered source address. +According to RFC 1918, unregistered source addresses +are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16. +.El +.Pp +These commands are also discussed in the file +.Pa README.nat +which comes with the source distribution. +.Pp +.It Op !\& Ns Xo +.No bg Ar command +.Xc +The given +.Ar command +is executed in the background with the following words replaced: +.Bl -tag -width COMPILATIONDATE +.It Li AUTHNAME +This is replaced with the local +.Ar authname +value. +See the +.Dq set authname +command below. +.It Li COMPILATIONDATE +In previous software revisions, this was replaced with the date on which +.Nm +was compiled. +This is no longer supported as it breaks the ability to recompile the same +code to produce an exact duplicate of a previous compilation. +.It Li DNS0 & DNS1 +These are replaced with the primary and secondary nameserver IP numbers. +If nameservers are negotiated by IPCP, the values of these macros will change. +.It Li ENDDISC +This is replaced with the local endpoint discriminator value. +See the +.Dq set enddisc +command below. +.It Li HISADDR +This is replaced with the peers IP number. +.It Li HISADDR6 +This is replaced with the peers IPv6 number. +.It Li INTERFACE +This is replaced with the name of the interface that is in use. +.It Li IPOCTETSIN +This is replaced with the number of IP bytes received since the connection +was established. +.It Li IPOCTETSOUT +This is replaced with the number of IP bytes sent since the connection +was established. +.It Li IPPACKETSIN +This is replaced with the number of IP packets received since the connection +was established. +.It Li IPPACKETSOUT +This is replaced with the number of IP packets sent since the connection +was established. +.It Li IPV6OCTETSIN +This is replaced with the number of IPv6 bytes received since the connection +was established. +.It Li IPV6OCTETSOUT +This is replaced with the number of IPv6 bytes sent since the connection +was established. +.It Li IPV6PACKETSIN +This is replaced with the number of IPv6 packets received since the connection +was established. +.It Li IPV6PACKETSOUT +This is replaced with the number of IPv6 packets sent since the connection +was established. +.It Li LABEL +This is replaced with the last label name used. +A label may be specified on the +.Nm +command line, via the +.Dq load +or +.Dq dial +commands and in the +.Pa ppp.secret +file. +.It Li MYADDR +This is replaced with the IP number assigned to the local interface. +.It Li MYADDR6 +This is replaced with the IPv6 number assigned to the local interface. +.It Li OCTETSIN +This is replaced with the number of bytes received since the connection +was established. +.It Li OCTETSOUT +This is replaced with the number of bytes sent since the connection +was established. +.It Li PACKETSIN +This is replaced with the number of packets received since the connection +was established. +.It Li PACKETSOUT +This is replaced with the number of packets sent since the connection +was established. +.It Li PEER_ENDDISC +This is replaced with the value of the peers endpoint discriminator. +.It Li PROCESSID +This is replaced with the current process id. +.It Li SOCKNAME +This is replaced with the name of the diagnostic socket. +.It Li UPTIME +This is replaced with the bundle uptime in HH:MM:SS format. +.It Li USER +This is replaced with the username that has been authenticated with PAP or +CHAP. +Normally, this variable is assigned only in -direct mode. +This value is available irrespective of whether utmp logging is enabled. +.It Li VERSION +This is replaced with the current version number of +.Nm . +.El +.Pp +These substitutions are also done by the +.Dq set proctitle , +.Dq ident +and +.Dq log +commands. +.Pp +If you wish to pause +.Nm +while the command executes, use the +.Dq shell +command instead. +.It clear physical|ipcp|ipv6 Op current|overall|peak... +Clear the specified throughput values at either the +.Dq physical , +.Dq ipcp +or +.Dq ipv6cp +level. +If +.Dq physical +is specified, context must be given (see the +.Dq link +command below). +If no second argument is given, all values are cleared. +.It clone Ar name Ns Xo +.Op \&, Ns Ar name Ns +.No ... +.Xc +Clone the specified link, creating one or more new links according to the +.Ar name +argument(s). +This command must be used from the +.Dq link +command below unless you have only got a single link (in which case that +link becomes the default). +Links may be removed using the +.Dq remove +command below. +.Pp +The default link name is +.Dq deflink . +.It close Op lcp|ccp Ns Op !\& +If no arguments are given, the relevant protocol layers will be brought +down and the link will be closed. +If +.Dq lcp +is specified, the LCP layer is brought down, but +.Nm +will not bring the link offline. +It is subsequently possible to use +.Dq term +(see below) +to talk to the peer machine if, for example, something like +.Dq slirp +is being used. +If +.Dq ccp +is specified, only the relevant compression layer is closed. +If the +.Dq !\& +is used, the compression layer will remain in the closed state, otherwise +it will re-enter the STOPPED state, waiting for the peer to initiate +further CCP negotiation. +In any event, this command does not disconnect the user from +.Nm +or exit +.Nm . +See the +.Dq quit +command below. +.It delete Ns Xo +.Op !\& +.Ar dest +.Xc +This command deletes the route with the given +.Ar dest +IP address. +If +.Ar dest +is specified as +.Sq ALL , +all non-direct entries in the routing table for the current interface, +and all +.Sq sticky route +entries are deleted. +If +.Ar dest +is specified as +.Sq default , +the default route is deleted. +.Pp +If the +.Ar delete!\& +command is used +(note the trailing +.Dq !\& ) , +.Nm +will not complain if the route does not already exist. +.It dial|call Op Ar label Ns Xo +.No ... +.Xc +This command is the equivalent of +.Dq load label +followed by +.Dq open , +and is provided for backwards compatibility. +.It down Op Ar lcp|ccp +Bring the relevant layer down ungracefully, as if the underlying layer +had become unavailable. +It is not considered polite to use this command on +a Finite State Machine that is in the OPEN state. +If no arguments are +supplied, the entire link is closed (or if no context is given, all links +are terminated). +If +.Sq lcp +is specified, the +.Em LCP +layer is terminated but the device is not brought offline and the link +is not closed. +If +.Sq ccp +is specified, only the relevant compression layer(s) are terminated. +.It help|? Op Ar command +Show a list of available commands. +If +.Ar command +is specified, show the usage string for that command. +.It ident Op Ar text Ns No ... +Identify the link to the peer using +.Ar text . +If +.Ar text +is empty, link identification is disabled. +It is possible to use any of the words described for the +.Ic bg +command above. +Refer to the +.Ic sendident +command for details of when +.Nm +identifies itself to the peer. +.It iface Ar command Op args +This command is used to control the interface used by +.Nm . +.Ar Command +may be one of the following: +.Bl -tag -width 2n +.It iface add Ns Xo +.Op !\& +.Ar addr Ns Op / Ns Ar bits +.Op Ar peer +.Xc +.It iface add Ns Xo +.Op !\& +.Ar addr +.Ar mask +.Ar peer +.Xc +Add the given +.Ar addr mask peer +combination to the interface. +Instead of specifying +.Ar mask , +.Ar /bits +can be used +(with no space between it and +.Ar addr ) . +If the given address already exists, the command fails unless the +.Dq !\& +is used - in which case the previous interface address entry is overwritten +with the new one, allowing a change of netmask or peer address. +.Pp +If only +.Ar addr +is specified, +.Ar bits +defaults to +.Dq 32 +and +.Ar peer +defaults to +.Dq 255.255.255.255 . +This address (the broadcast address) is the only duplicate peer address that +.Nm +allows. +.It iface clear Op INET | INET6 +If this command is used while +.Nm +is in the OPENED state or while in +.Fl auto +mode, all addresses except for the NCP negotiated address are deleted +from the interface. +If +.Nm +is not in the OPENED state and is not in +.Fl auto +mode, all interface addresses are deleted. +.Pp +If the INET or INET6 arguments are used, only addresses for that address +family are cleared. +.Pp +.It iface delete Ns Xo +.Op !\& Ns +.No |rm Ns Op !\& +.Ar addr +.Xc +This command deletes the given +.Ar addr +from the interface. +If the +.Dq !\& +is used, no error is given if the address is not currently assigned to +the interface (and no deletion takes place). +.It iface show +Shows the current state and current addresses for the interface. +It is much the same as running +.Dq ifconfig INTERFACE . +.It iface help Op Ar sub-command +This command, when invoked without +.Ar sub-command , +will show a list of possible +.Dq iface +sub-commands and a brief synopsis for each. +When invoked with +.Ar sub-command , +only the synopsis for the given sub-command is shown. +.El +.It Op data Ns Xo +.No link +.Ar name Ns Op , Ns Ar name Ns +.No ... Ar command Op Ar args +.Xc +This command may prefix any other command if the user wishes to +specify which link the command should affect. +This is only applicable after multiple links have been created in Multi-link +mode using the +.Dq clone +command. +.Pp +.Ar Name +specifies the name of an existing link. +If +.Ar name +is a comma separated list, +.Ar command +is executed on each link. +If +.Ar name +is +.Dq * , +.Ar command +is executed on all links. +.It load Op Ar label Ns Xo +.No ... +.Xc +Load the given +.Ar label Ns No (s) +from the +.Pa ppp.conf +file. +If +.Ar label +is not given, the +.Ar default +label is used. +.Pp +Unless the +.Ar label +section uses the +.Dq set mode , +.Dq open +or +.Dq dial +commands, +.Nm +will not attempt to make an immediate connection. +.It log Ar word Ns No ... +Send the given word(s) to the log file with the prefix +.Dq LOG: . +Word substitutions are done as explained under the +.Dq !bg +command above. +.It open Op lcp|ccp|ipcp +This is the opposite of the +.Dq close +command. +All closed links are immediately brought up apart from second and subsequent +.Ar demand-dial +links - these will come up based on the +.Dq set autoload +command that has been used. +.Pp +If the +.Dq lcp +argument is used while the LCP layer is already open, LCP will be +renegotiated. +This allows various LCP options to be changed, after which +.Dq open lcp +can be used to put them into effect. +After renegotiating LCP, +any agreed authentication will also take place. +.Pp +If the +.Dq ccp +argument is used, the relevant compression layer is opened. +Again, if it is already open, it will be renegotiated. +.Pp +If the +.Dq ipcp +argument is used, the link will be brought up as normal, but if +IPCP is already open, it will be renegotiated and the network +interface will be reconfigured. +.Pp +It is probably not good practice to re-open the PPP state machines +like this as it is possible that the peer will not behave correctly. +It +.Em is +however useful as a way of forcing the CCP or VJ dictionaries to be reset. +.It passwd Ar pass +Specify the password required for access to the full +.Nm +command set. +This password is required when connecting to the diagnostic port (see the +.Dq set server +command). +.Ar Pass +is specified on the +.Dq set server +command line. +The value of +.Ar pass +is not logged when +.Ar command +logging is active, instead, the literal string +.Sq ******** +is logged. +.It quit|bye Op all +If +.Dq quit +is executed from the controlling connection or from a command file, +ppp will exit after closing all connections. +Otherwise, if the user +is connected to a diagnostic socket, the connection is simply dropped. +.Pp +If the +.Ar all +argument is given, +.Nm +will exit despite the source of the command after closing all existing +connections. +.It remove|rm +This command removes the given link. +It is only really useful in multi-link mode. +A link must be in the +.Dv CLOSED +state before it is removed. +.It rename|mv Ar name +This command renames the given link to +.Ar name . +It will fail if +.Ar name +is already used by another link. +.Pp +The default link name is +.Sq deflink . +Renaming it to +.Sq modem , +.Sq cuad0 +or +.Sq USR +may make the log file more readable. +.It resolv Ar command +This command controls +.Nm Ns No 's +manipulation of the +.Xr resolv.conf 5 +file. +When +.Nm +starts up, it loads the contents of this file into memory and retains this +image for future use. +.Ar command +is one of the following: +.Bl -tag -width readonly +.It Em readonly +Treat +.Pa /etc/resolv.conf +as read only. +If +.Dq dns +is enabled, +.Nm +will still attempt to negotiate nameservers with the peer, making the results +available via the +.Dv DNS0 +and +.Dv DNS1 +macros. +This is the opposite of the +.Dq resolv writable +command. +.It Em reload +Reload +.Pa /etc/resolv.conf +into memory. +This may be necessary if for example a DHCP client overwrote +.Pa /etc/resolv.conf . +.It Em restore +Replace +.Pa /etc/resolv.conf +with the version originally read at startup or with the last +.Dq resolv reload +command. +This is sometimes a useful command to put in the +.Pa /etc/ppp/ppp.linkdown +file. +.It Em rewrite +Rewrite the +.Pa /etc/resolv.conf +file. +This command will work even if the +.Dq resolv readonly +command has been used. +It may be useful as a command in the +.Pa /etc/ppp/ppp.linkup +file if you wish to defer updating +.Pa /etc/resolv.conf +until after other commands have finished. +.It Em writable +Allow +.Nm +to update +.Pa /etc/resolv.conf +if +.Dq dns +is enabled and +.Nm +successfully negotiates a DNS. +This is the opposite of the +.Dq resolv readonly +command. +.El +.It save +This option is not (yet) implemented. +.It sendident +This command tells +.Nm +to identify itself to the peer. +The link must be in LCP state or higher. +If no identity has been set (via the +.Ic ident +command), +.Ic sendident +will fail. +.Pp +When an identity has been set, +.Nm +will automatically identify itself when it sends or receives a configure +reject, when negotiation fails or when LCP reaches the opened state. +.Pp +Received identification packets are logged to the LCP log (see +.Ic set log +for details) and are never responded to. +.It set Ns Xo +.Op up +.Ar var value +.Xc +This option allows the setting of any of the following variables: +.Bl -tag -width 2n +.It set accmap Ar hex-value +ACCMap stands for Asynchronous Control Character Map. +This is always +negotiated with the peer, and defaults to a value of 00000000 in hex. +This protocol is required to defeat hardware that depends on passing +certain characters from end to end (such as XON/XOFF etc). +.Pp +For the XON/XOFF scenario, use +.Dq set accmap 000a0000 . +.It set Op auth Ns Xo +.No key Ar value +.Xc +This sets the authentication key (or password) used in client mode +PAP or CHAP negotiation to the given value. +It also specifies the +password to be used in the dial or login scripts in place of the +.Sq \eP +sequence, preventing the actual password from being logged. +If +.Ar command +or +.Ar chat +logging is in effect, +.Ar value +is logged as +.Sq ******** +for security reasons. +.Pp +If the first character of +.Ar value +is an exclamation mark +.Pq Dq !\& , +.Nm +treats the remainder of the string as a program that must be executed +to determine the +.Dq authname +and +.Dq authkey +values. +.Pp +If the +.Dq !\& +is doubled up +(to +.Dq !! ) , +it is treated as a single literal +.Dq !\& , +otherwise, ignoring the +.Dq !\& , +.Ar value +is parsed as a program to execute in the same was as the +.Dq !bg +command above, substituting special names in the same manner. +Once executed, +.Nm +will feed the program three lines of input, each terminated by a newline +character: +.Bl -bullet +.It +The host name as sent in the CHAP challenge. +.It +The challenge string as sent in the CHAP challenge. +.It +The locally defined +.Dq authname . +.El +.Pp +Two lines of output are expected: +.Bl -bullet +.It +The +.Dq authname +to be sent with the CHAP response. +.It +The +.Dq authkey , +which is encrypted with the challenge and request id, the answer being sent +in the CHAP response packet. +.El +.Pp +When configuring +.Nm +in this manner, it is expected that the host challenge is a series of ASCII +digits or characters. +An encryption device or Secure ID card is usually +required to calculate the secret appropriate for the given challenge. +.It set authname Ar id +This sets the authentication id used in client mode PAP or CHAP negotiation. +.Pp +If used in +.Fl direct +mode with CHAP enabled, +.Ar id +is used in the initial authentication challenge and should normally be set to +the local machine name. +.It set autoload Xo +.Ar min-percent max-percent period +.Xc +These settings apply only in multi-link mode and default to zero, zero and +five respectively. +When more than one +.Ar demand-dial +(also known as +.Fl auto ) +mode link is available, only the first link is made active when +.Nm +first reads data from the tun device. +The next +.Ar demand-dial +link will be opened only when the current bundle throughput is at least +.Ar max-percent +percent of the total bundle bandwidth for +.Ar period +seconds. +When the current bundle throughput decreases to +.Ar min-percent +percent or less of the total bundle bandwidth for +.Ar period +seconds, a +.Ar demand-dial +link will be brought down as long as it is not the last active link. +.Pp +Bundle throughput is measured as the maximum of inbound and outbound +traffic. +.Pp +The default values cause +.Ar demand-dial +links to simply come up one at a time. +.Pp +Certain devices cannot determine their physical bandwidth, so it +is sometimes necessary to use the +.Dq set bandwidth +command (described below) to make +.Dq set autoload +work correctly. +.It set bandwidth Ar value +This command sets the connection bandwidth in bits per second. +.Ar value +must be greater than zero. +It is currently only used by the +.Dq set autoload +command above. +.It set callback Ar option Ns No ... +If no arguments are given, callback is disabled, otherwise, +.Nm +will request (or in +.Fl direct +mode, will accept) one of the given +.Ar option Ns No s . +In client mode, if an +.Ar option +is NAK'd +.Nm +will request a different +.Ar option , +until no options remain at which point +.Nm +will terminate negotiations (unless +.Dq none +is one of the specified +.Ar option ) . +In server mode, +.Nm +will accept any of the given protocols - but the client +.Em must +request one of them. +If you wish callback to be optional, you must {include} +.Ar none +as an option. +.Pp +The +.Ar option Ns No s +are as follows (in this order of preference): +.Pp +.Bl -tag -width Ds +.It auth +The callee is expected to decide the callback number based on +authentication. +If +.Nm +is the callee, the number should be specified as the fifth field of +the peers entry in +.Pa /etc/ppp/ppp.secret . +.It cbcp +Microsoft's callback control protocol is used. +See +.Dq set cbcp +below. +.Pp +If you wish to negotiate +.Ar cbcp +in client mode but also wish to allow the server to request no callback at +CBCP negotiation time, you must specify both +.Ar cbcp +and +.Ar none +as callback options. +.It E.164 *| Ns Xo +.Ar number Ns Op , Ns Ar number Ns +.No ... +.Xc +The caller specifies the +.Ar number . +If +.Nm +is the callee, +.Ar number +should be either a comma separated list of allowable numbers or a +.Dq \&* , +meaning any number is permitted. +If +.Nm +is the caller, only a single number should be specified. +.Pp +Note, this option is very unsafe when used with a +.Dq \&* +as a malicious caller can tell +.Nm +to call any (possibly international) number without first authenticating +themselves. +.It none +If the peer does not wish to do callback at all, +.Nm +will accept the fact and continue without callback rather than terminating +the connection. +This is required (in addition to one or more other callback +options) if you wish callback to be optional. +.El +.Pp +.It set cbcp Oo +.No *| Ns Ar number Ns Oo +.No , Ns Ar number Ns ...\& Oc +.Op Ar delay Op Ar retry +.Oc +If no arguments are given, CBCP (Microsoft's CallBack Control Protocol) +is disabled - ie, configuring CBCP in the +.Dq set callback +command will result in +.Nm +requesting no callback in the CBCP phase. +Otherwise, +.Nm +attempts to use the given phone +.Ar number Ns No (s). +.Pp +In server mode +.Pq Fl direct , +.Nm +will insist that the client uses one of these numbers, unless +.Dq \&* +is used in which case the client is expected to specify the number. +.Pp +In client mode, +.Nm +will attempt to use one of the given numbers (whichever it finds to +be agreeable with the peer), or if +.Dq \&* +is specified, +.Nm +will expect the peer to specify the number. +.It set cd Oo +.No off| Ns Ar seconds Ns Op !\& +.Oc +Normally, +.Nm +checks for the existence of carrier depending on the type of device +that has been opened: +.Bl -tag -width XXX -offset XXX +.It Terminal Devices +Carrier is checked one second after the login script is complete. +If it is not set, +.Nm +assumes that this is because the device does not support carrier (which +is true for most +.Dq laplink +NULL-modem cables), logs the fact and stops checking +for carrier. +.Pp +As ptys do not support the TIOCMGET ioctl, the tty device will switch all +carrier detection off when it detects that the device is a pty. +.It ISDN (i4b) Devices +Carrier is checked once per second for 6 seconds. +If it is not set after +the sixth second, the connection attempt is considered to have failed and +the device is closed. +Carrier is always required for i4b devices. +.It PPPoE (netgraph) Devices +Carrier is checked once per second for 5 seconds. +If it is not set after +the fifth second, the connection attempt is considered to have failed and +the device is closed. +Carrier is always required for PPPoE devices. +.El +.Pp +All other device types do not support carrier. +Setting a carrier value will +result in a warning when the device is opened. +.Pp +Some modems take more than one second after connecting to assert the carrier +signal. +If this delay is not increased, this will result in +.Nm Ns No 's +inability to detect when the link is dropped, as +.Nm +assumes that the device is not asserting carrier. +.Pp +The +.Dq set cd +command overrides the default carrier behaviour. +.Ar seconds +specifies the maximum number of seconds that +.Nm +should wait after the dial script has finished before deciding if +carrier is available or not. +.Pp +If +.Dq off +is specified, +.Nm +will not check for carrier on the device, otherwise +.Nm +will not proceed to the login script until either carrier is detected +or until +.Ar seconds +has elapsed, at which point +.Nm +assumes that the device will not set carrier. +.Pp +If no arguments are given, carrier settings will go back to their default +values. +.Pp +If +.Ar seconds +is followed immediately by an exclamation mark +.Pq Dq !\& , +.Nm +will +.Em require +carrier. +If carrier is not detected after +.Ar seconds +seconds, the link will be disconnected. +.It set choked Op Ar timeout +This sets the number of seconds that +.Nm +will keep a choked output queue before dropping all pending output packets. +If +.Ar timeout +is less than or equal to zero or if +.Ar timeout +is not specified, it is set to the default value of +.Em 120 seconds . +.Pp +A choked output queue occurs when +.Nm +has read a certain number of packets from the local network for transmission, +but cannot send the data due to link failure (the peer is busy etc.). +.Nm +will not read packets indefinitely. +Instead, it reads up to +.Em 30 +packets (or +.Em 30 No + +.Em nlinks No * +.Em 2 +packets in multi-link mode), then stops reading the network interface +until either +.Ar timeout +seconds have passed or at least one packet has been sent. +.Pp +If +.Ar timeout +seconds pass, all pending output packets are dropped. +.It set ctsrts|crtscts on|off +This sets hardware flow control. +Hardware flow control is +.Ar on +by default. +.It set deflate Ar out-winsize Op Ar in-winsize +This sets the DEFLATE algorithms default outgoing and incoming window +sizes. +Both +.Ar out-winsize +and +.Ar in-winsize +must be values between +.Em 8 +and +.Em 15 . +If +.Ar in-winsize +is specified, +.Nm +will insist that this window size is used and will not accept any other +values from the peer. +.It set dns Op Ar primary Op Ar secondary +This command specifies DNS overrides for the +.Dq accept dns +command. +Refer to the +.Dq accept +command description above for details. +This command does not affect the IP numbers requested using +.Dq enable dns . +.It set device|line Xo +.Ar value Ns No ... +.Xc +This sets the device(s) to which +.Nm +will talk to the given +.Dq value . +.Pp +All ISDN and serial device names are expected to begin with +.Pa /dev/ . +ISDN devices are usually called +.Pa i4brbchX +and serial devices are usually called +.Pa cuaXX . +.Pp +If +.Dq value +does not begin with +.Pa /dev/ , +it must either begin with an exclamation mark +.Pq Dq !\& , +be of the format +.No PPPoE: Ns Ar iface Ns Xo +.Op \&: Ns Ar provider Ns +.Xc +(on +.Xr netgraph 4 +enabled systems), or be of the format +.Sm off +.Ar host : port Op /tcp|udp . +.Sm on +.Pp +If it begins with an exclamation mark, the rest of the device name is +treated as a program name, and that program is executed when the device +is opened. +Standard input, output and error are fed back to +.Nm +and are read and written as if they were a regular device. +.Pp +If a +.No PPPoE: Ns Ar iface Ns Xo +.Op \&: Ns Ar provider Ns +.Xc +specification is given, +.Nm +will attempt to create a +.Em PPP +over Ethernet connection using the given +.Ar iface +interface by using +.Xr netgraph 4 . +If +.Xr netgraph 4 +is not available, +.Nm +will attempt to load it using +.Xr kldload 2 . +If this fails, an external program must be used such as the +.Xr pppoed 8 +program available under +.Ox . +The given +.Ar provider +is passed as the service name in the PPPoE Discovery Initiation (PADI) +packet. +If no provider is given, an empty value will be used. +.Pp +When a PPPoE connection is established, +.Nm +will place the name of the Access Concentrator in the environment variable +.Ev ACNAME . +.Pp +Refer to +.Xr netgraph 4 +and +.Xr ng_pppoe 4 +for further details. +.Pp +If a +.Ar host Ns No : Ns Ar port Ns Oo +.No /tcp|udp +.Oc +specification is given, +.Nm +will attempt to connect to the given +.Ar host +on the given +.Ar port . +If a +.Dq /tcp +or +.Dq /udp +suffix is not provided, the default is +.Dq /tcp . +Refer to the section on +.Em PPP OVER TCP and UDP +above for further details. +.Pp +If multiple +.Dq values +are specified, +.Nm +will attempt to open each one in turn until it succeeds or runs out of +devices. +.It set dial Ar chat-script +This specifies the chat script that will be used to dial the other +side. +See also the +.Dq set login +command below. +Refer to +.Xr chat 8 +and to the example configuration files for details of the chat script +format. +It is possible to specify some special +.Sq values +in your chat script as follows: +.Bl -tag -width 2n +.It Li \ec +When used as the last character in a +.Sq send +string, this indicates that a newline should not be appended. +.It Li \ed +When the chat script encounters this sequence, it delays two seconds. +.It Li \ep +When the chat script encounters this sequence, it delays for one quarter of +a second. +.It Li \en +This is replaced with a newline character. +.It Li \er +This is replaced with a carriage return character. +.It Li \es +This is replaced with a space character. +.It Li \et +This is replaced with a tab character. +.It Li \eT +This is replaced by the current phone number (see +.Dq set phone +below). +.It Li \eP +This is replaced by the current +.Ar authkey +value (see +.Dq set authkey +above). +.It Li \eU +This is replaced by the current +.Ar authname +value (see +.Dq set authname +above). +.El +.Pp +Note that two parsers will examine these escape sequences, so in order to +have the +.Sq chat parser +see the escape character, it is necessary to escape it from the +.Sq command parser . +This means that in practice you should use two escapes, for example: +.Bd -literal -offset indent +set dial "... ATDT\\\\T CONNECT" +.Ed +.Pp +It is also possible to execute external commands from the chat script. +To do this, the first character of the expect or send string is an +exclamation mark +.Pq Dq !\& . +If a literal exclamation mark is required, double it up to +.Dq !!\& +and it will be treated as a single literal +.Dq !\& . +When the command is executed, standard input and standard output are +directed to the open device (see the +.Dq set device +command), and standard error is read by +.Nm +and substituted as the expect or send string. +If +.Nm +is running in interactive mode, file descriptor 3 is attached to +.Pa /dev/tty . +.Pp +For example (wrapped for readability): +.Bd -literal -offset indent +set login "TIMEOUT 5 \\"\\" \\"\\" login:--login: ppp \e +word: ppp \\"!sh \\\\-c \\\\\\"echo \\\\-n label: >&2\\\\\\"\\" \e +\\"!/bin/echo in\\" HELLO" +.Ed +.Pp +would result in the following chat sequence (output using the +.Sq set log local chat +command before dialing): +.Bd -literal -offset indent +Dial attempt 1 of 1 +dial OK! +Chat: Expecting: +Chat: Sending: +Chat: Expecting: login:--login: +Chat: Wait for (5): login: +Chat: Sending: ppp +Chat: Expecting: word: +Chat: Wait for (5): word: +Chat: Sending: ppp +Chat: Expecting: !sh \\-c "echo \\-n label: >&2" +Chat: Exec: sh -c "echo -n label: >&2" +Chat: Wait for (5): !sh \\-c "echo \\-n label: >&2" --> label: +Chat: Exec: /bin/echo in +Chat: Sending: +Chat: Expecting: HELLO +Chat: Wait for (5): HELLO +login OK! +.Ed +.Pp +Note (again) the use of the escape character, allowing many levels of +nesting. +Here, there are four parsers at work. +The first parses the original line, reading it as three arguments. +The second parses the third argument, reading it as 11 arguments. +At this point, it is +important that the +.Dq \&- +signs are escaped, otherwise this parser will see them as constituting +an expect-send-expect sequence. +When the +.Dq !\& +character is seen, the execution parser reads the first command as three +arguments, and then +.Xr sh 1 +itself expands the argument after the +.Fl c . +As we wish to send the output back to the modem, in the first example +we redirect our output to file descriptor 2 (stderr) so that +.Nm +itself sends and logs it, and in the second example, we just output to stdout, +which is attached directly to the modem. +.Pp +This, of course means that it is possible to execute an entirely external +.Dq chat +command rather than using the internal one. +See +.Xr chat 8 +for a good alternative. +.Pp +The external command that is executed is subjected to the same special +word expansions as the +.Dq !bg +command. +.It set enddisc Op label|IP|MAC|magic|psn value +This command sets our local endpoint discriminator. +If set prior to LCP negotiation, and if no +.Dq disable enddisc +command has been used, +.Nm +will send the information to the peer using the LCP endpoint discriminator +option. +The following discriminators may be set: +.Bl -tag -width indent +.It Li label +The current label is used. +.It Li IP +Our local IP number is used. +As LCP is negotiated prior to IPCP, it is +possible that the IPCP layer will subsequently change this value. +If +it does, the endpoint discriminator stays at the old value unless manually +reset. +.It Li MAC +This is similar to the +.Ar IP +option above, except that the MAC address associated with the local IP +number is used. +If the local IP number is not resident on any Ethernet +interface, the command will fail. +.Pp +As the local IP number defaults to whatever the machine host name is, +.Dq set enddisc mac +is usually done prior to any +.Dq set ifaddr +commands. +.It Li magic +A 20 digit random number is used. +Care should be taken when using magic numbers as restarting +.Nm +or creating a link using a different +.Nm +invocation will also use a different magic number and will therefore not +be recognised by the peer as belonging to the same bundle. +This makes it unsuitable for +.Fl direct +connections. +.It Li psn Ar value +The given +.Ar value +is used. +.Ar Value +should be set to an absolute public switched network number with the +country code first. +.El +.Pp +If no arguments are given, the endpoint discriminator is reset. +.It set escape Ar value... +This option is similar to the +.Dq set accmap +option above. +It allows the user to specify a set of characters that will be +.Sq escaped +as they travel across the link. +.It set filter dial|alive|in|out Ar rule-no Xo +.No permit|deny|clear| Ns Ar rule-no +.Op !\& +.Oo Op host +.Ar src_addr Ns Op / Ns Ar width +.Op Ar dst_addr Ns Op / Ns Ar width +.Oc [ Ns Ar proto +.Op src lt|eq|gt Ar port +.Op dst lt|eq|gt Ar port +.Op estab +.Op syn +.Op finrst +.Op timeout Ar secs ] +.Xc +.Nm +supports four filter sets. +The +.Em alive +filter specifies packets that keep the connection alive - resetting the +idle timer. +The +.Em dial +filter specifies packets that cause +.Nm +to dial when in +.Fl auto +mode. +The +.Em in +filter specifies packets that are allowed to travel +into the machine and the +.Em out +filter specifies packets that are allowed out of the machine. +.Pp +Filtering is done prior to any IP alterations that might be done by the +NAT engine on outgoing packets and after any IP alterations that might +be done by the NAT engine on incoming packets. +By default all empty filter sets allow all packets to pass. +Rules are processed in order according to +.Ar rule-no +(unless skipped by specifying a rule number as the +.Ar action ) . +Up to 40 rules may be given for each set. +If a packet does not match +any of the rules in a given set, it is discarded. +In the case of +.Em in +and +.Em out +filters, this means that the packet is dropped. +In the case of +.Em alive +filters it means that the packet will not reset the idle timer (even if +the +.Ar in Ns No / Ns Ar out +filter has a +.Dq timeout +value) and in the case of +.Em dial +filters it means that the packet will not trigger a dial. +A packet failing to trigger a dial will be dropped rather than queued. +Refer to the +section on +.Sx PACKET FILTERING +above for further details. +.It set hangup Ar chat-script +This specifies the chat script that will be used to reset the device +before it is closed. +It should not normally be necessary, but can +be used for devices that fail to reset themselves properly on close. +.It set help|? Op Ar command +This command gives a summary of available set commands, or if +.Ar command +is specified, the command usage is shown. +.It set ifaddr Oo Ar myaddr Ns +.Op / Ns Ar \&nn +.Oo Ar hisaddr Ns Op / Ns Ar \&nn +.Oo Ar netmask +.Op Ar triggeraddr +.Oc Oc +.Oc +This command specifies the IP addresses that will be used during +IPCP negotiation. +Addresses are specified using the format +.Pp +.Dl a.b.c.d/nn +.Pp +Where +.Dq a.b.c.d +is the preferred IP, but +.Ar nn +specifies how many bits of the address we will insist on. +If +.No / Ns Ar nn +is omitted, it defaults to +.Dq /32 +unless the IP address is 0.0.0.0 in which case it defaults to +.Dq /0 . +.Pp +If you wish to assign a dynamic IP number to the peer, +.Ar hisaddr +may also be specified as a range of IP numbers in the format +.Bd -ragged -offset indent +.Ar \&IP Ns Oo \&- Ns Ar \&IP Ns Xo +.Oc Ns Oo , Ns Ar \&IP Ns +.Op \&- Ns Ar \&IP Ns +.Oc Ns ... +.Xc +.Ed +.Pp +for example: +.Pp +.Dl set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20 +.Pp +will only negotiate +.Dq 10.0.0.1 +as the local IP number, but may assign any of the given 10 IP +numbers to the peer. +If the peer requests one of these numbers, +and that number is not already in use, +.Nm +will grant the peers request. +This is useful if the peer wants +to re-establish a link using the same IP number as was previously +allocated (thus maintaining any existing tcp or udp connections). +.Pp +If the peer requests an IP number that is either outside +of this range or is already in use, +.Nm +will suggest a random unused IP number from the range. +.Pp +If +.Ar triggeraddr +is specified, it is used in place of +.Ar myaddr +in the initial IPCP negotiation. +However, only an address in the +.Ar myaddr +range will be accepted. +This is useful when negotiating with some +.Dv PPP +implementations that will not assign an IP number unless their peer +requests +.Dq 0.0.0.0 . +.Pp +It should be noted that in +.Fl auto +mode, +.Nm +will configure the interface immediately upon reading the +.Dq set ifaddr +line in the config file. +In any other mode, these values are just +used for IPCP negotiations, and the interface is not configured +until the IPCP layer is up. +.Pp +Note that the +.Ar HISADDR +argument may be overridden by the third field in the +.Pa ppp.secret +file once the client has authenticated itself +(if PAP or CHAP are +.Dq enabled ) . +Refer to the +.Sx AUTHENTICATING INCOMING CONNECTIONS +section for details. +.Pp +In all cases, if the interface is already configured, +.Nm +will try to maintain the interface IP numbers so that any existing +bound sockets will remain valid. +.It set ifqueue Ar packets +Set the maximum number of packets that +.Nm +will read from the tunnel interface while data cannot be sent to any of +the available links. +This queue limit is necessary to flow control outgoing data as the tunnel +interface is likely to be far faster than the combined links available to +.Nm . +.Pp +If +.Ar packets +is set to a value less than the number of links, +.Nm +will read up to that value regardless. +This prevents any possible latency problems. +.Pp +The default value for +.Ar packets +is +.Dq 30 . +.It set ccpretry|ccpretries Oo Ar timeout +.Op Ar reqtries Op Ar trmtries +.Oc +.It set chapretry|chapretries Oo Ar timeout +.Op Ar reqtries +.Oc +.It set ipcpretry|ipcpretries Oo Ar timeout +.Op Ar reqtries Op Ar trmtries +.Oc +.It set ipv6cpretry|ipv6cpretries Oo Ar timeout +.Op Ar reqtries Op Ar trmtries +.Oc +.It set lcpretry|lcpretries Oo Ar timeout +.Op Ar reqtries Op Ar trmtries +.Oc +.It set papretry|papretries Oo Ar timeout +.Op Ar reqtries +.Oc +These commands set the number of seconds that +.Nm +will wait before resending Finite State Machine (FSM) Request packets. +The default +.Ar timeout +for all FSMs is 3 seconds (which should suffice in most cases). +.Pp +If +.Ar reqtries +is specified, it tells +.Nm +how many configuration request attempts it should make while receiving +no reply from the peer before giving up. +The default is 5 attempts for +CCP, LCP and IPCP and 3 attempts for PAP and CHAP. +.Pp +If +.Ar trmtries +is specified, it tells +.Nm +how many terminate requests should be sent before giving up waiting for the +peers response. +The default is 3 attempts. +Authentication protocols are +not terminated and it is therefore invalid to specify +.Ar trmtries +for PAP or CHAP. +.Pp +In order to avoid negotiations with the peer that will never converge, +.Nm +will only send at most 3 times the configured number of +.Ar reqtries +in any given negotiation session before giving up and closing that layer. +.It set log Xo +.Op local +.Op +|- Ns +.Ar value Ns No ... +.Xc +This command allows the adjustment of the current log level. +Refer to the Logging Facility section for further details. +.It set login Ar chat-script +This +.Ar chat-script +compliments the dial-script. +If both are specified, the login +script will be executed after the dial script. +Escape sequences available in the dial script are also available here. +.It set logout Ar chat-script +This specifies the chat script that will be used to logout +before the hangup script is called. +It should not normally be necessary. +.It set lqrperiod|echoperiod Ar frequency +This command sets the +.Ar frequency +in seconds at which +.Em LQR +or +.Em LCP ECHO +packets are sent. +The default is 30 seconds. +You must also use the +.Dq enable lqr +and/or +.Dq enable echo +commands if you wish to send +.Em LQR +or +.Em LCP ECHO +requests to the peer. +.It set mode Ar interactive|auto|ddial|background +This command allows you to change the +.Sq mode +of the specified link. +This is normally only useful in multi-link mode, +but may also be used in uni-link mode. +.Pp +It is not possible to change a link that is +.Sq direct +or +.Sq dedicated . +.Pp +Note: If you issue the command +.Dq set mode auto , +and have network address translation enabled, it may be useful to +.Dq enable iface-alias +afterwards. +This will allow +.Nm +to do the necessary address translations to enable the process that +triggers the connection to connect once the link is up despite the +peer assigning us a new (dynamic) IP address. +.It set mppe Op 40|56|128|* Op stateless|stateful|* +This option selects the encryption parameters used when negotiation +MPPE. +MPPE can be disabled entirely with the +.Dq disable mppe +command. +If no arguments are given, +.Nm +will attempt to negotiate a stateful link with a 128 bit key, but +will agree to whatever the peer requests (including no encryption +at all). +.Pp +If any arguments are given, +.Nm +will +.Em insist +on using MPPE and will close the link if it is rejected by the peer (Note; +this behaviour can be overridden by a configured RADIUS server). +.Pp +The first argument specifies the number of bits that +.Nm +should insist on during negotiations and the second specifies whether +.Nm +should insist on stateful or stateless mode. +In stateless mode, the +encryption dictionary is re-initialised with every packet according to +an encryption key that is changed with every packet. +In stateful mode, +the encryption dictionary is re-initialised every 256 packets or after +the loss of any data and the key is changed every 256 packets. +Stateless mode is less efficient but is better for unreliable transport +layers. +.It set mrru Op Ar value +Setting this option enables Multi-link PPP negotiations, also known as +Multi-link Protocol or MP. +There is no default MRRU (Maximum Reconstructed Receive Unit) value. +If no argument is given, multi-link mode is disabled. +.It set mru Xo +.Op max Ns Op imum +.Op Ar value +.Xc +The default MRU (Maximum Receive Unit) is 1500. +If it is increased, the other side *may* increase its MTU. +In theory there is no point in decreasing the MRU to below the default as the +.Em PPP +protocol says implementations *must* be able to accept packets of at +least 1500 octets. +.Pp +If the +.Dq maximum +keyword is used, +.Nm +will refuse to negotiate a higher value. +The maximum MRU can be set to 2048 at most. +Setting a maximum of less than 1500 violates the +.Em PPP +rfc, but may sometimes be necessary. +For example, +.Em PPPoE +imposes a maximum of 1492 due to hardware limitations. +.Pp +If no argument is given, 1500 is assumed. +A value must be given when +.Dq maximum +is specified. +.It set mtu Xo +.Op max Ns Op imum +.Op Ar value +.Xc +The default MTU is 1500. +At negotiation time, +.Nm +will accept whatever MRU the peer requests (assuming it is +not less than 296 bytes or greater than the assigned maximum). +If the MTU is set, +.Nm +will not accept MRU values less than +.Ar value . +When negotiations are complete, the MTU is used when writing to the +interface, even if the peer requested a higher value MRU. +This can be useful for +limiting your packet size (giving better bandwidth sharing at the expense +of more header data). +.Pp +If the +.Dq maximum +keyword is used, +.Nm +will refuse to negotiate a higher value. +The maximum MTU can be set to 2048 at most. +Note, it is necessary to use the +.Dq maximum +keyword to limit the MTU when using PPPoE. +.Pp +If no +.Ar value +is given, 1500, or whatever the peer asks for is used. +A value must be given when +.Dq maximum +is specified. +.It set nbns Op Ar x.x.x.x Op Ar y.y.y.y +This option allows the setting of the Microsoft NetBIOS name server +values to be returned at the peers request. +If no values are given, +.Nm +will reject any such requests. +.It set openmode active|passive Op Ar delay +By default, +.Ar openmode +is always +.Ar active +with a one second +.Ar delay . +That is, +.Nm +will always initiate LCP/IPCP/CCP negotiation one second after the line +comes up. +If you want to wait for the peer to initiate negotiations, you +can use the value +.Ar passive . +If you want to initiate negotiations immediately or after more than one +second, the appropriate +.Ar delay +may be specified here in seconds. +.It set parity odd|even|none|mark +This allows the line parity to be set. +The default value is +.Ar none . +.It set phone Ar telno Ns Xo +.Oo \&| Ns Ar backupnumber +.Oc Ns ... Ns Oo : Ns Ar nextnumber +.Oc Ns ... +.Xc +This allows the specification of the phone number to be used in +place of the \\\\T string in the dial and login chat scripts. +Multiple phone numbers may be given separated either by a pipe +.Pq Dq \&| +or a colon +.Pq Dq \&: . +.Pp +Numbers after the pipe are only dialed if the dial or login +script for the previous number failed. +.Pp +Numbers after the colon are tried sequentially, irrespective of +the reason the line was dropped. +.Pp +If multiple numbers are given, +.Nm +will dial them according to these rules until a connection is made, retrying +the maximum number of times specified by +.Dq set redial +below. +In +.Fl background +mode, each number is attempted at most once. +.It set pppoe Op standard|3Com +This option configures the underlying +.Xr ng_pppoe 4 +node to either standard RFC2516 PPPoE or proprietary 3Com mode. +If not set the system default will be used. +.It set Op proc Ns Xo +.No title Op Ar value +.Xc +The current process title as displayed by +.Xr ps 1 +is changed according to +.Ar value . +If +.Ar value +is not specified, the original process title is restored. +All the +word replacements done by the shell commands (see the +.Dq bg +command above) are done here too. +.Pp +Note, if USER is required in the process title, the +.Dq set proctitle +command must appear in +.Pa ppp.linkup , +as it is not known when the commands in +.Pa ppp.conf +are executed. +.It set radius Op Ar config-file +This command enables RADIUS support (if it is compiled in). +.Ar config-file +refers to the radius client configuration file as described in +.Xr radius.conf 5 . +If PAP, CHAP, MSCHAP or MSCHAPv2 are +.Dq enable Ns No d , +.Nm +behaves as a +.Em \&N Ns No etwork +.Em \&A Ns No ccess +.Em \&S Ns No erver +and uses the configured RADIUS server to authenticate rather than +authenticating from the +.Pa ppp.secret +file or from the passwd database. +.Pp +If none of PAP, CHAP, MSCHAP or MSCHAPv2 are enabled, +.Dq set radius +will do nothing. +.Pp +.Nm +uses the following attributes from the RADIUS reply: +.Bl -tag -width XXX -offset XXX +.It RAD_FRAMED_IP_ADDRESS +The peer IP address is set to the given value. +.It RAD_FRAMED_IP_NETMASK +The tun interface netmask is set to the given value. +.It RAD_FRAMED_MTU +If the given MTU is less than the peers MRU as agreed during LCP +negotiation, *and* it is less that any configured MTU (see the +.Dq set mru +command), the tun interface MTU is set to the given value. +.It RAD_FRAMED_COMPRESSION +If the received compression type is +.Dq 1 , +.Nm +will request VJ compression during IPCP negotiations despite any +.Dq disable vj +configuration command. +.It RAD_FILTER_ID +If this attribute is supplied, +.Nm +will attempt to use it as an additional label to load from the +.Pa ppp.linkup +and +.Pa ppp.linkdown +files. +The load will be attempted before (and in addition to) the normal +label search. +If the label does not exist, no action is taken and +.Nm +proceeds to the normal load using the current label. +.It RAD_FRAMED_ROUTE +The received string is expected to be in the format +.Ar dest Ns Op / Ns Ar bits +.Ar gw +.Op Ar metrics . +Any specified metrics are ignored. +.Dv MYADDR +and +.Dv HISADDR +are understood as valid values for +.Ar dest +and +.Ar gw , +.Dq default +can be used for +.Ar dest +to sepcify the default route, and +.Dq 0.0.0.0 +is understood to be the same as +.Dq default +for +.Ar dest +and +.Dv HISADDR +for +.Ar gw . +.Pp +For example, a returned value of +.Dq 1.2.3.4/24 0.0.0.0 1 2 -1 3 400 +would result in a routing table entry to the 1.2.3.0/24 network via +.Dv HISADDR +and a returned value of +.Dq 0.0.0.0 0.0.0.0 +or +.Dq default HISADDR +would result in a default route to +.Dv HISADDR . +.Pp +All RADIUS routes are applied after any sticky routes are applied, making +RADIUS routes override configured routes. +This also applies for RADIUS routes that do not {include} the +.Dv MYADDR +or +.Dv HISADDR +keywords. +.Pp +.It RAD_FRAMED_IPV6_PREFIX +If this attribute is supplied, the value is substituted for IPV6PREFIX +in a command. +You may pass it to an upper layer protocol such as DHCPv6 for delegating an +IPv6 prefix to a peer. +.It RAD_FRAMED_IPV6_ROUTE +The received string is expected to be in the format +.Ar dest Ns Op / Ns Ar bits +.Ar gw +.Op Ar metrics . +Any specified metrics are ignored. +.Dv MYADDR6 +and +.Dv HISADDR6 +are understood as valid values for +.Ar dest +and +.Ar gw , +.Dq default +can be used for +.Ar dest +to sepcify the default route, and +.Dq :: +is understood to be the same as +.Dq default +for +.Ar dest +and +.Dv HISADDR6 +for +.Ar gw . +.Pp +For example, a returned value of +.Dq 3ffe:505:abcd::/48 :: +would result in a routing table entry to the 3ffe:505:abcd::/48 network via +.Dv HISADDR6 +and a returned value of +.Dq :: :: +or +.Dq default HISADDR6 +would result in a default route to +.Dv HISADDR6 . +.Pp +All RADIUS IPv6 routes are applied after any sticky routes are +applied, making RADIUS IPv6 routes override configured routes. +This +also applies for RADIUS IPv6 routes that do not {include} the +.Dv MYADDR6 +or +.Dv HISADDR6 +keywords. +.Pp +.It RAD_SESSION_TIMEOUT +If supplied, the client connection is closed after the given number of +seconds. +.It RAD_REPLY_MESSAGE +If supplied, this message is passed back to the peer as the authentication +SUCCESS text. +.It RAD_MICROSOFT_MS_CHAP_ERROR +If this +.Dv RAD_VENDOR_MICROSOFT +vendor specific attribute is supplied, it is passed back to the peer as the +authentication FAILURE text. +.It RAD_MICROSOFT_MS_CHAP2_SUCCESS +If this +.Dv RAD_VENDOR_MICROSOFT +vendor specific attribute is supplied and if MS-CHAPv2 authentication is +being used, it is passed back to the peer as the authentication SUCCESS text. +.It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY +If this +.Dv RAD_VENDOR_MICROSOFT +vendor specific attribute is supplied and has a value of 2 (Required), +.Nm +will insist that MPPE encryption is used (even if no +.Dq set mppe +configuration command has been given with arguments). +If it is supplied with a value of 1 (Allowed), encryption is made optional +(despite any +.Dq set mppe +configuration commands with arguments). +.It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES +If this +.Dv RAD_VENDOR_MICROSOFT +vendor specific attribute is supplied, bits 1 and 2 are examined. +If either or both are set, 40 bit and/or 128 bit (respectively) encryption +options are set, overriding any given first argument to the +.Dq set mppe +command. +Note, it is not currently possible for the RADIUS server to specify 56 bit +encryption. +.It RAD_MICROSOFT_MS_MPPE_RECV_KEY +If this +.Dv RAD_VENDOR_MICROSOFT +vendor specific attribute is supplied, it is value is used as the master +key for decryption of incoming data. +When clients are authenticated using +MSCHAPv2, the RADIUS server MUST provide this attribute if inbound MPPE is +to function. +.It RAD_MICROSOFT_MS_MPPE_SEND_KEY +If this +.Dv RAD_VENDOR_MICROSOFT +vendor specific attribute is supplied, it is value is used as the master +key for encryption of outgoing data. +When clients are authenticated using +MSCHAPv2, the RADIUS server MUST provide this attribute if outbound MPPE is +to function. +.El +.Pp +Values received from the RADIUS server may be viewed using +.Dq show bundle . +.It set rad_alive Ar timeout +When RADIUS is configured, setting +.Dq rad_alive +to a non-zero +.Ar timeout +value will tell +.Nm +to sent RADIUS accounting information to the RADIUS server every +.Ar timeout +seconds. +.It set rad_port_id Ar option +When RADIUS is configured, setting the +.Dq rad_port_id +value allows to specify what should be sent to the RADIUS server as +NAS-Port-Id. +The +.Ar option Ns No s +are as follows: +.Pp +.Bl -tag -width Ds +.It pid +PID of the corresponding tunnel. +.It tunnum +.Xr tun 4 +interface number. +.It ifnum +index of the interface as returned by +.Xr if_nametoindex 3 . +.It default +keeps the default behavior. +.El +.It set reconnect Ar timeout ntries +Should the line drop unexpectedly (due to loss of CD or LQR +failure), a connection will be re-established after the given +.Ar timeout . +The line will be re-connected at most +.Ar ntries +times. +.Ar Ntries +defaults to zero. +A value of +.Ar random +for +.Ar timeout +will result in a variable pause, somewhere between 1 and 30 seconds. +.It set recvpipe Op Ar value +This sets the routing table RECVPIPE value. +The optimum value is just over twice the MTU value. +If +.Ar value +is unspecified or zero, the default kernel controlled value is used. +.It set redial Ar secs Ns Xo +.Oo + Ns Ar inc Ns +.Op - Ns Ar max Ns +.Oc Ns Op . Ns Ar next +.Op Ar attempts +.Xc +.Nm +can be instructed to attempt to redial +.Ar attempts +times. +If more than one phone number is specified (see +.Dq set phone +above), a pause of +.Ar next +is taken before dialing each number. +A pause of +.Ar secs +is taken before starting at the first number again. +A literal value of +.Dq Li random +may be used here in place of +.Ar secs +and +.Ar next , +causing a random delay of between 1 and 30 seconds. +.Pp +If +.Ar inc +is specified, its value is added onto +.Ar secs +each time +.Nm +tries a new number. +.Ar secs +will only be incremented at most +.Ar max +times. +.Ar max +defaults to 10. +.Pp +Note, the +.Ar secs +delay will be effective, even after +.Ar attempts +has been exceeded, so an immediate manual dial may appear to have +done nothing. +If an immediate dial is required, a +.Dq !\& +should immediately follow the +.Dq open +keyword. +See the +.Dq open +description above for further details. +.It set sendpipe Op Ar value +This sets the routing table SENDPIPE value. +The optimum value is just over twice the MTU value. +If +.Ar value +is unspecified or zero, the default kernel controlled value is used. +.It "set server|socket" Ar TcpPort Ns No \&| Ns Xo +.Ar LocalName Ns No |none|open|closed +.Op password Op Ar mask +.Xc +This command tells +.Nm +to listen on the given socket or +.Sq diagnostic port +for incoming command connections. +.Pp +The word +.Dq none +instructs +.Nm +to close any existing socket and clear the socket configuration. +The word +.Dq open +instructs +.Nm +to attempt to re-open the port. +The word +.Dq closed +instructs +.Nm +to close the open port. +.Pp +If you wish to specify a local domain socket, +.Ar LocalName +must be specified as an absolute file name, otherwise it is assumed +to be the name or number of a TCP port. +You may specify the octal umask to be used with a local domain socket. +Refer to +.Xr umask 2 +for umask details. +Refer to +.Xr services 5 +for details of how to translate TCP port names. +.Pp +You must also specify the password that must be entered by the client +(using the +.Dq passwd +variable above) when connecting to this socket. +If the password is +specified as an empty string, no password is required for connecting clients. +.Pp +When specifying a local domain socket, the first +.Dq %d +sequence found in the socket name will be replaced with the current +interface unit number. +This is useful when you wish to use the same +profile for more than one connection. +.Pp +In a similar manner TCP sockets may be prefixed with the +.Dq + +character, in which case the current interface unit number is added to +the port number. +.Pp +When using +.Nm +with a server socket, the +.Xr pppctl 8 +command is the preferred mechanism of communications. +Currently, +.Xr telnet 1 +can also be used, but link encryption may be implemented in the future, so +.Xr telnet 1 +should be avoided. +.Pp +Note; +.Dv SIGUSR1 +and +.Dv SIGUSR2 +interact with the diagnostic socket. +.It set speed Ar value +This sets the speed of the serial device. +If speed is specified as +.Dq sync , +.Nm +treats the device as a synchronous device. +.Pp +Certain device types will know whether they should be specified as +synchronous or asynchronous. +These devices will override incorrect +settings and log a warning to this effect. +.It set stopped Op Ar LCPseconds Op Ar CCPseconds +If this option is set, +.Nm +will time out after the given FSM (Finite State Machine) has been in +the stopped state for the given number of +.Dq seconds . +This option may be useful if the peer sends a terminate request, +but never actually closes the connection despite our sending a terminate +acknowledgement. +This is also useful if you wish to +.Dq set openmode passive +and time out if the peer does not send a Configure Request within the +given time. +Use +.Dq set log +lcp +ccp +to make +.Nm +log the appropriate state transitions. +.Pp +The default value is zero, where +.Nm +does not time out in the stopped state. +.Pp +This value should not be set to less than the openmode delay (see +.Dq set openmode +above). +.It set timeout Ar idleseconds Op Ar mintimeout +This command allows the setting of the idle timer. +Refer to the section titled +.Sx SETTING THE IDLE TIMER +for further details. +.Pp +If +.Ar mintimeout +is specified, +.Nm +will never idle out before the link has been up for at least that number +of seconds. +.It set urgent Xo +.Op tcp|udp|none +.Oo Op +|- Ns +.Ar port +.Oc No ... +.Xc +This command controls the ports that +.Nm +prioritizes when transmitting data. +The default priority TCP ports +are ports 21 (ftp control), 22 (ssh), 23 (telnet), 513 (login), 514 (shell), +543 (klogin) and 544 (kshell). +There are no priority UDP ports by default. +See +.Xr services 5 +for details. +.Pp +If neither +.Dq tcp +or +.Dq udp +are specified, +.Dq tcp +is assumed. +.Pp +If no +.Ar port Ns No s +are given, the priority port lists are cleared (although if +.Dq tcp +or +.Dq udp +is specified, only that list is cleared). +If the first +.Ar port +argument is prefixed with a plus +.Pq Dq \&+ +or a minus +.Pq Dq \&- , +the current list is adjusted, otherwise the list is reassigned. +.Ar port Ns No s +prefixed with a plus or not prefixed at all are added to the list and +.Ar port Ns No s +prefixed with a minus are removed from the list. +.Pp +If +.Dq none +is specified, all priority port lists are disabled and even +.Dv IPTOS_LOWDELAY +packets are not prioritised. +.It set vj slotcomp on|off +This command tells +.Nm +whether it should attempt to negotiate VJ slot compression. +By default, slot compression is turned +.Ar on . +.It set vj slots Ar nslots +This command sets the initial number of slots that +.Nm +will try to negotiate with the peer when VJ compression is enabled (see the +.Sq enable +command above). +It defaults to a value of 16. +.Ar Nslots +must be between +.Ar 4 +and +.Ar 16 +inclusive. +.El +.Pp +.It shell|! Op Ar command +If +.Ar command +is not specified a shell is invoked according to the +.Dv SHELL +environment variable. +Otherwise, the given +.Ar command +is executed. +Word replacement is done in the same way as for the +.Dq !bg +command as described above. +.Pp +Use of the !\& character +requires a following space as with any of the other commands. +You should note that this command is executed in the foreground; +.Nm +will not continue running until this process has exited. +Use the +.Dv bg +command if you wish processing to happen in the background. +.It show Ar var +This command allows the user to examine the following: +.Bl -tag -width 2n +.It show bundle +Show the current bundle settings. +.It show ccp +Show the current CCP compression statistics. +.It show compress +Show the current VJ compression statistics. +.It show escape +Show the current escape characters. +.It show filter Op Ar name +List the current rules for the given filter. +If +.Ar name +is not specified, all filters are shown. +.It show hdlc +Show the current HDLC statistics. +.It show help|? +Give a summary of available show commands. +.It show iface +Show the current interface information +(the same as +.Dq iface show ) . +.It show ipcp +Show the current IPCP statistics. +.It show layers +Show the protocol layers currently in use. +.It show lcp +Show the current LCP statistics. +.It show Op data Ns Xo +.No link +.Xc +Show high level link information. +.It show links +Show a list of available logical links. +.It show log +Show the current log values. +.It show mem +Show current memory statistics. +.It show ncp +Show the current NCP statistics. +.It show physical +Show low level link information. +.It show mp +Show Multi-link information. +.It show proto +Show current protocol totals. +.It show route +Show the current routing tables. +.It show stopped +Show the current stopped timeouts. +.It show timer +Show the active alarm timers. +.It show version +Show the current version number of +.Nm . +.El +.Pp +.It term +Go into terminal mode. +Characters typed at the keyboard are sent to the device. +Characters read from the device are displayed on the screen. +When a remote +.Em PPP +peer is detected, +.Nm +automatically enables Packet Mode and goes back into command mode. +.El +.Sh MORE DETAILS +.Bl -bullet +.It +Read the example configuration files. +They are a good source of information. +.It +Use +.Dq help , +.Dq nat \&? , +.Dq enable \&? , +.Dq set ?\& +and +.Dq show ?\& +to get online information about what is available. +.It +The following URLs contain useful information: +.Bl -bullet -compact +.It +http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/faq/ppp.html +.It +http://www.FreeBSD.org/doc/handbook/userppp.html +.El +.Pp +.El +.Sh FILES +.Nm +refers to four files: +.Pa ppp.conf , +.Pa ppp.linkup , +.Pa ppp.linkdown +and +.Pa ppp.secret . +These files are placed in the +.Pa /etc/ppp +directory. +.Bl -tag -width 2n +.It Pa /etc/ppp/ppp.conf +System default configuration file. +.It Pa /etc/ppp/ppp.secret +An authorisation file for each system. +.It Pa /etc/ppp/ppp.linkup +A file to check when +.Nm +establishes a network level connection. +.It Pa /etc/ppp/ppp.linkdown +A file to check when +.Nm +closes a network level connection. +.It Pa /var/log/ppp.log +Logging and debugging information file. +Note, this name is specified in +.Pa /etc/syslog.conf . +See +.Xr syslog.conf 5 +for further details. +.It Pa /var/spool/lock/LCK..* +tty port locking file. +Refer to +.Xr uucplock 3 +for further details. +.It Pa /var/run/tunN.pid +The process id (pid) of the +.Nm +program connected to the tunN device, where +.Sq N +is the number of the device. +.It Pa /var/run/ttyXX.if +The tun interface used by this port. +Again, this file is only created in +.Fl background , +.Fl auto +and +.Fl ddial +modes. +.It Pa /etc/services +Get port number if port number is using service name. +.It Pa /var/run/ppp-authname-class-value +In multi-link mode, local domain sockets are created using the peer +authentication name +.Pq Sq authname , +the peer endpoint discriminator class +.Pq Sq class +and the peer endpoint discriminator value +.Pq Sq value . +As the endpoint discriminator value may be a binary value, it is turned +to HEX to determine the actual file name. +.Pp +This socket is used to pass links between different instances of +.Nm . +.El +.Sh SEE ALSO +.Xr at 1 , +.Xr ftp 1 , +.Xr gzip 1 , +.Xr hostname 1 , +.Xr login 1 , +.Xr tcpdump 1 , +.Xr telnet 1 , +.Xr kldload 2 , +.Xr pipe 2 , +.Xr socketpair 2 , +ifdef({LOCALNAT},{},{.Xr libalias 3 , +})dnl +ifdef({LOCALRAD},{},{.Xr libradius 3 , +})dnl +.Xr syslog 3 , +.Xr uucplock 3 , +.Xr netgraph 4 , +.Xr ng_pppoe 4 , +.Xr crontab 5 , +.Xr group 5 , +.Xr passwd 5 , +.Xr protocols 5 , +.Xr radius.conf 5 , +.Xr resolv.conf 5 , +.Xr syslog.conf 5 , +.Xr adduser 8 , +.Xr chat 8 , +.Xr getty 8 , +.Xr inetd 8 , +.Xr init 8 , +.Xr isdnd 8 , +.Xr named 8 , +.Xr ping 8 , +.Xr pppctl 8 , +.Xr pppd 8 , +.Xr pppoed 8 , +.Xr route 8 , +.Xr sshd 8 , +.Xr syslogd 8 , +.Xr traceroute 8 , +.Xr vipw 8 +.Sh HISTORY +This program was originally written by +.An Toshiharu OHNO Aq tony-o@iij.ad.jp , +and was submitted to +.Fx 2.0.5 +by +.An Atsushi Murai Aq amurai@spec.co.jp . +.Pp +It was substantially modified during 1997 by +.An Brian Somers Aq brian@Awfulhak.org , +and was ported to +.Ox +in November that year +(just after the 2.2 release). +.Pp +Most of the code was rewritten by +.An Brian Somers +in early 1998 when multi-link ppp support was added. |