X-Git-Url: http://git.ozlabs.org/?a=blobdiff_plain;f=pppd%2Fpppd.8;h=4a1fecb077048d7bdf1bd62a96af742df114ea63;hb=878b8024277edfd6fe5e442c8e54edf7e576d6ee;hp=474c589505bb8b8b223df7c88bb703f3a1ce48f8;hpb=3179440a51d714e31b667c75e4490a48b49df760;p=ppp.git diff --git a/pppd/pppd.8 b/pppd/pppd.8 index 474c589..4a1fecb 100644 --- a/pppd/pppd.8 +++ b/pppd/pppd.8 @@ -1,5 +1,5 @@ -.\" manual page [] for pppd 2.0 -.\" $Id: pppd.8,v 1.2 1994/02/08 23:50:51 paulus Exp $ +.\" manual page [] for pppd 2.3 +.\" $Id: pppd.8,v 1.21 1996/08/28 06:41:53 paulus Exp $ .\" SH section heading .\" SS subsection heading .\" LP paragraph @@ -11,11 +11,11 @@ pppd \- Point to Point Protocol daemon .SH SYNOPSIS .B pppd [ -.I options -] [ .I tty_name ] [ .I speed +] [ +.I options ] .SH DESCRIPTION .LP @@ -27,85 +27,109 @@ a family of Network Control Protocols (NCP) for establishing and configuring different network-layer protocols. .LP The encapsulation scheme is provided by driver code in the kernel. -.B pppd -provides the basic LCP, authentication support, and an -NCP for establishing and configuring the Internet Protocol (IP) -(called the IP Control Protocol, IPCP). +Pppd provides the basic LCP, authentication support, and an NCP for +establishing and configuring the Internet Protocol (IP) (called the IP +Control Protocol, IPCP). .SH FREQUENTLY USED OPTIONS .TP .I -Communicate over the named device. The string "/dev/" -is prepended if necessary. If no device name is given, -.I pppd -will use the controlling terminal, and will not fork to put itself in -the background. +Communicate over the named device. The string "/dev/" is prepended if +necessary. If no device name is given, or if the name of the terminal +connected to the standard input is given, pppd +will use that terminal, and will not fork to put itself in the +background. This option is privileged if the \fInoauth\fR option is +used. .TP .I -Set the baud rate to . On systems such as 4.4BSD and NetBSD, -any speed can be specified. Other systems (e.g. SunOS) allow only a -limited set of speeds. +Set the baud rate to (a decimal number). On systems such as +4.4BSD and NetBSD, any speed can be specified. Other systems +(e.g. SunOS) allow only a limited set of speeds. .TP .B asyncmap \fI -Set the async character map to . -This map describes which control characters cannot be successfully -received over the serial line. -.I pppd -will ask the peer to send these characters as a 2-byte "escape" sequence. -The argument is a 32 bit hex number -with each bit representing a character to escape. -Bit 0 (00000001) represents the character 0x00; -bit 31 (80000000) represents the character 0x1f or ^_. -The default asyncmap is 0. If multiple \fBasyncmap\fR options are -given, the values are ORed together. +Set the async character map to . This map describes which +control characters cannot be successfully received over the serial +line. Pppd will ask the peer to send these characters as a 2-byte +escape sequence. The argument is a 32 bit hex number with each bit +representing a character to escape. Bit 0 (00000001) represents the +character 0x00; bit 31 (80000000) represents the character 0x1f or ^_. +If multiple \fIasyncmap\fR options are given, the values are ORed +together. If no \fIasyncmap\fR option is given, no async character +map will be negotiated for the receive direction; the peer should then +escape \fIall\fR control characters. To escape transmitted +characters, use the \fIescape\fR option. .TP .B auth Require the peer to authenticate itself before allowing network packets to be sent or received. .TP -.B connect \fI

-Use the executable or shell command specified by

to set up the -serial line. This script would typically use the "chat" program to -dial the modem and start the remote ppp session. +.B call \fIname +Read options from the file /etc/ppp/peers/\fIname\fR. This file may +contain privileged options, such as \fInoauth\fR, even if pppd +is not being run by root. The \fIname\fR string may not begin with / +or include .. as a pathname component. +.TP +.B connect \fIscript +Use the executable or shell command specified by \fIscript\fR to set +up the serial line. This script would typically use the chat(8) +program to dial the modem and start the remote ppp session. This +option is privileged if the \fInoauth\fR option is used. .TP .B crtscts -Use hardware flow control (i.e. RTS/CTS) to control the flow of data on -the serial port. +Use hardware flow control (i.e. RTS/CTS) to control the flow of data +on the serial port. If neither the \fIcrtscts\fR nor the +\fI\nocrtscts\fR option is given, the hardware flow control setting +for the serial port is left unchanged. .TP .B defaultroute Add a default route to the system routing tables, using the peer as the gateway, when IPCP negotiation is successfully completed. -This entry is removed when the PPP connection is broken. -.TP -.B file \fI -Read options from file (the format is described below). -.TP -.B mru \fI -Set the MRU [Maximum Receive Unit] value to for negotiation. -.I pppd -will ask the peer to send packets of no more than bytes. - The minimum MRU value is 128. -The default MRU value is 1500. A value of 296 is recommended for slow -links (40 bytes for TCP/IP header + 256 bytes of data). -.TP -.B netmask \fI -Set the interface netmask to , a 32 bit netmask in "decimal dot" notation -(e.g. 255.255.255.0). +This entry is removed when the PPP connection is broken. This option +is privileged if the \fInodefaultroute\fR option has been specified. +.TP +.B disconnect \fIscript +Run the executable or shell command specified by \fIscript\fR after +pppd has terminated the link. This script could, for example, issue +commands to the modem to cause it to hang up if hardware modem control +signals were not available. The disconnect script is not run if the +modem has already hung up. This option is privileged if the +\fInoauth\fR option is used. +.TP +.B escape \fIxx,yy,... +Specifies that certain characters should be escaped on transmission +(regardless of whether the peer requests them to be escaped with its +async control character map). The characters to be escaped are +specified as a list of hex numbers separated by commas. Note that +almost any character can be specified for the \fIescape\fR option, +unlike the \fIasyncmap\fR option which only allows control characters +to be specified. The characters which may not be escaped are those +with hex values 0x20 - 0x3f or 0x5e. +.TP +.B file \fIname +Read options from file \fIname\fR (the format is described below). +The file must be readable by the user who has invoked pppd. +.TP +.B lock +Specifies that pppd should create a UUCP-style lock file for the +serial device to ensure exclusive access to the device. +.TP +.B mru \fIn +Set the MRU [Maximum Receive Unit] value to \fIn\fR. Pppd +will ask the peer to send packets of no more than \fIn\fR bytes. The +minimum MRU value is 128. The default MRU value is 1500. A value of +296 is recommended for slow links (40 bytes for TCP/IP header + 256 +bytes of data). +.TP +.B mtu \fIn +Set the MTU [Maximum Transmit Unit] value to \fIn\fR. Unless the +peer requests a smaller value via MRU negotiation, pppd will +request that the kernel networking code send data packets of no more +than \fIn\fR bytes through the PPP network interface. .TP .B passive -Enables the "passive" option in the LCP. With this option, -.I pppd -will attempt to initiate a connection; if no reply is received from -the peer, -.I pppd -will then just wait passively for a valid LCP packet from the peer -(instead of exiting, as it does without this option). -.TP -.B silent -With this option, -.I pppd -will not transmit LCP packets to initiate a connection until a valid -LCP packet is received from the peer (as for the "passive" option with -old versions of \fIpppd\fR). +Enables the "passive" option in the LCP. With this option, pppd will +attempt to initiate a connection; if no reply is received from the +peer, pppd will then just wait passively for a valid LCP packet from +the peer, instead of exiting, as it would without this option. .SH OPTIONS .TP .I \fB:\fI @@ -113,130 +137,326 @@ Set the local and/or remote interface IP addresses. Either one may be omitted. The IP addresses can be specified with a host name or in decimal dot notation (e.g. 150.234.56.78). The default local address is the (first) IP address of the system (unless the -.B noipdefault +\fInoipdefault\fR option is given). The remote address will be obtained from the peer if not specified in any option. Thus, in simple cases, this option is -not required. -If a local and/or remote IP address is specified with this option, -.I pppd +not required. If a local and/or remote IP address is specified with +this option, pppd will not accept a different value from the peer in the IPCP -negotiation, unless the -.B ipcp-accept-local -and/or -.B ipcp-accept-remote -options are given, respectively. -.TP -.B -all -Don't request or allow negotiation of any options for LCP and IPCP (use -default values). -.TP -.B -ac -Disable Address/Control compression negotiation (use default, i.e. -disabled). -.TP -.B -am -Disable asyncmap negotiation (use default, i.e. 0xffffffff). +negotiation, unless the \fIipcp-accept-local\fR and/or +\fIipcp-accept-remote\fR options are given, respectively. +.TP +.B bsdcomp \fInr,nt +Request that the peer compress packets that it sends, using the +BSD-Compress scheme, with a maximum code size of \fInr\fR bits, and +agree to compress packets sent to the peer with a maximum code size of +\fInt\fR bits. If \fInt\fR is not specified, it defaults to the value +given for \fInr\fR. Values in the range 9 to 15 may be used for +\fInr\fR and \fInt\fR; larger values give better compression but +consume more kernel memory for compression dictionaries. +Alternatively, a value of 0 for \fInr\fR or \fInt\fR disables +compression in the corresponding direction. +.TP +.B chap-interval \fIn +If this option is given, pppd will rechallenge the peer every \fIn\fR +seconds. +.TP +.B chap-max-challenge \fIn +Set the maximum number of CHAP challenge transmissions to \fIn\fR +(default 10). .TP -.B -as \fI -Same as -.B asyncmap \fI +.B chap-restart \fIn +Set the CHAP restart interval (retransmission timeout for challenges) +to \fIn\fR seconds (default 3). .TP -.B -d +.B debug Increase debugging level. +If this option is given, pppd will log the contents of all +control packets sent or received in a readable form. The packets are +logged through syslog with facility \fIdaemon\fR and level +\fIdebug\fR. This information can be directed to a file by setting up +/etc/syslog.conf appropriately (see syslog.conf(5)). +.TP +.B default-asyncmap +Disable asyncmap negotiation, forcing all control characters to be +escaped for both the transmit and the receive direction. +.TP +.B default-mru +Disable MRU [Maximum Receive Unit] negotiation. With this option, +pppd will use the default MRU value of 1500 bytes for both the +transmit and receive direction. +.TP +.B deflate \fInr,nt +Request that the peer compress packets that it sends, using the +Deflate scheme, with a maximum window size of \fI2**nr\fR bytes, and +agree to compress packets sent to the peer with a maximum window size +of \fI2**nt\fR bytes. If \fInt\fR is not specified, it defaults to +the value given for \fInr\fR. Values in the range 8 to 15 may be used +for \fInr\fR and \fInt\fR; larger values give better compression but +consume more kernel memory for compression dictionaries. +Alternatively, a value of 0 for \fInr\fR or \fInt\fR disables +compression in the corresponding direction. (Note: pppd requests +Deflate compression in preference to BSD-Compress if the peer can do +either.) +.TP +.B demand +Initiate the link only on demand, i.e. when data traffic is present. +With this option, the remote IP address must be specified by the user +on the command line or in an options file. Pppd will initially +configure the interface and enable it for IP traffic without +connecting to the peer. When traffic is available, pppd will +connect to the peer and perform negotiation, authentication, etc. +When this is completed, pppd will commence passing data packets +(i.e., IP packets) across the link. + +The \fIdemand\fR option implies the \fIpersist\fR option. If this +behaviour is not desired, use the \fInopersist\fR option after the +\fIdemand\fR option. The \fIidle\fR and \fIholdoff\fR +options are also useful in conjuction with the \fIdemand\fR option. +.TP +.B domain \fId +Append the domain name \fId\fR to the local host name for authentication +purposes. For example, if gethostname() returns the name porsche, but +the fully qualified domain name is porsche.Quotron.COM, you could +specify \fIdomain Quotron.COM\fR. Pppd would then use the name +\fIporsche.Quotron.COM\fR for looking up secrets in the secrets file, +and as the default name to send to the peer when authenticating itself +to the peer. This option is privileged. +.TP +.B holdoff \fIn +Specifies how many seconds to wait before re-initiating the link after +it terminates. This option only has any effect if the \fIpersist\fR +or \fIdemand\fR option is used. The holdoff period is not applied if +the link was terminated because it was idle. +.TP +.B idle \fIn +Specifies that pppd should disconnect if the link is idle for \fIn\fR +seconds. The link is idle when no data packets (i.e. IP packets) are +being sent or received. Note: it is not advisable to use this option +with the \fIpersist\fR option without the \fIdemand\fR option. +.TP +.B ipx +Enable the IPXCP and IPX protocols. Under Linux, this is the default +condition if your kernel supports IPX. This option is presently only +supported under Linux. .TP -.B -detach -Don't fork to become a background process (otherwise -.I pppd -will do so if a serial device is specified). -.TP -.B -ip -Disable IP address negotiation (with this option, the remote IP -address must be specified with an option on the command line or in an -options file). -.TP -.B -mn -Disable magic number negotiation. With this option, -.I pppd -cannot detect a looped-back line. -.TP -.B -mru -Disable MRU [Maximum Receive Unit] negotiation (use default, i.e. 1500). -.TP -.B -p -Same as the -.B passive -option. -.TP -.B -pc -Disable protocol field compression negotiation (use default, i.e. disabled). -.TP -.B +ua \fI

-Agree to authenticate using PAP [Password Authentication Protocol] if -requested by the peer, and -use the data in file

for the user and password to send to the -peer. The file contains the remote user name, followed by a newline, -followed by the remote password, followed by a newline. This option -is obsolescent. -.TP -.B +pap -Require the peer to authenticate itself using PAP. -.TP -.B -pap -Don't agree to authenticate using PAP. -.TP -.B +chap -Require the peer to authenticate itself using CHAP [Cryptographic -Handshake Authentication Protocol] authentication. +.B ipcp-accept-local +With this option, pppd will accept the peer's idea of our local IP +address, even if the local IP address was specified in an option. .TP -.B -chap -Don't agree to authenticate using CHAP. +.B ipcp-accept-remote +With this option, pppd will accept the peer's idea of its (remote) IP +address, even if the remote IP address was specified in an option. .TP -.B -vj -Disable negotiation of Van Jacobson style IP header compression (use -default, i.e. no compression). +.B ipcp-max-configure \fIn +Set the maximum number of IPCP configure-request transmissions to +\fIn\fR (default 10). .TP -.B debug -Increase debugging level (same as -.B -d -). +.B ipcp-max-failure \fIn +Set the maximum number of IPCP configure-NAKs returned before starting +to send configure-Rejects instead to \fIn\fR (default 10). +.TP +.B ipcp-max-terminate \fIn +Set the maximum number of IPCP terminate-request transmissions to +\fIn\fR (default 3). +.TP +.B ipcp-restart \fIn +Set the IPCP restart interval (retransmission timeout) to \fIn\fR +seconds (default 3). +.TP +.B ipparam \fIstring +Provides an extra parameter to the ip-up and ip-down scripts. If this +option is given, the \fIstring\fR supplied is given as the 6th +parameter to those scripts. +.TP +.B ipx-network \fIn +Set the IPX network number in the IPXCP configure request frame to +\fIn\fR, a hexadecimal number (without a leading 0x). There is no +valid default. If this option is not specified, the network number is +obtained from the peer. If the peer does not have the network number, +the IPX protocol will not be started. +.TP +.B ipx-node \fIn\fB:\fIm +Set the IPX node numbers. The two node numbers are separated from each +other with a colon character. The first number \fIn\fR is the local +node number. The second number \fIm\fR is the peer's node number. Each +node number is a hexadecimal number, at most 10 digits long. The node +numbers on the ipx-network must be unique. There is no valid +default. If this option is not specified then the node numbers are +obtained from the peer. +.TP +.B ipx-router-name \fI +Set the name of the router. This is a string and is sent to the peer +as information data. +.TP +.B ipx-routing \fIn +Set the routing protocol to be received by this option. More than one +instance of \fIipx-routing\fR may be specified. The '\fInone\fR' +option (0) may be specified as the only instance of ipx-routing. The +values may be \fI0\fR for \fINONE\fR, \fI2\fR for \fIRIP/SAP\fR, and +\fI4\fR for \fINLSP\fR. +.TP +.B ipxcp-accept-local +Accept the peer's NAK for the node number specified in the ipx-node +option. If a node number was specified, and non-zero, the default is +to insist that the value be used. If you include this option then you +will permit the peer to override the entry of the node number. +.TP +.B ipxcp-accept-network +Accept the peer's NAK for the network number specified in the +ipx-network option. If a network number was specified, and non-zero, the +default is to insist that the value be used. If you include this +option then you will permit the peer to override the entry of the node +number. +.TP +.B ipxcp-accept-remote +Use the peer's network number specified in the configure request +frame. If a node number was specified for the peer and this option was +not specified, the peer will be forced to use the value which you have +specified. +.TP +.B ipxcp-max-configure \fIn +Set the maximum number of IPXCP configure request frames which the +system will send to \fIn\fR. The default is 10. +.TP +.B ipxcp-max-failure \fIn +Set the maximum number of IPXCP NAK frames which the local system will +send before it rejects the options. The default value is 3. +.TP +.B ipxcp-max-terminate \fIn +Set the maximum nuber of IPXCP terminate request frames before the +local system considers that the peer is not listening to them. The +default value is 3. +.TP +.B kdebug \fIn +Enable debugging code in the kernel-level PPP driver. The argument +\fIn\fR is a number which is the sum of the following values: 1 to +enable general debug messages, 2 to request that the contents of +received packets be printed, and 4 to request that the contents of +transmitted packets be printed. +.TP +.B lcp-echo-failure \fIn +If this option is given, pppd will presume the peer to be dead +if \fIn\fR LCP echo-requests are sent without receiving a valid LCP +echo-reply. If this happens, pppd will terminate the +connection. Use of this option requires a non-zero value for the +\fIlcp-echo-interval\fR parameter. This option can be used to enable +pppd to terminate after the physical connection has been broken +(e.g., the modem has hung up) in situations where no hardware modem +control lines are available. +.TP +.B lcp-echo-interval \fIn +If this option is given, pppd will send an LCP echo-request frame to +the peer every \fIn\fR seconds. Normally the peer should respond to +the echo-request by sending an echo-reply. This option can be used +with the \fIlcp-echo-failure\fR option to detect that the peer is no +longer connected. +.TP +.B lcp-max-configure \fIn +Set the maximum number of LCP configure-request transmissions to +\fIn\fR (default 10). +.TP +.B lcp-max-failure \fIn +Set the maximum number of LCP configure-NAKs returned before starting +to send configure-Rejects instead to \fIn\fR (default 10). .TP -.B domain \fI -Append the domain name to the local host name for authentication -purposes. For example, if gethostname() returns the name porsche, but the -fully qualified domain name is porsche.Quotron.COM, you would use the -domain option to set the domain name to Quotron.COM. +.B lcp-max-terminate \fIn +Set the maximum number of LCP terminate-request transmissions to +\fIn\fR (default 3). .TP -.B modem -Use the modem control lines. (This option is not fully implemented.) +.B lcp-restart \fIn +Set the LCP restart interval (retransmission timeout) to \fIn\fR +seconds (default 3). .TP .B local -Don't use the modem control lines. -.TP -.B name \fI -Set the name of the local system for authentication purposes to . -.TP -.B user \fI -Set the user name to use for authenticating this machine with the peer -using PAP to . -.TP -.B usehostname -Enforce the use of the hostname as the name of the local system for -authentication purposes (overrides the -.B name -option). -.TP -.B remotename \fI -Set the assumed name of the remote system for authentication purposes -to . -.TP -.B proxyarp -Add an entry to this system's ARP [Address Resolution Protocol] table -with the IP address of the peer and the Ethernet address of this -system. +Don't use the modem control lines. With this option, pppd will ignore +the state of the CD (Carrier Detect) signal from the modem and will +not change the state of the DTR (Data Terminal Ready) signal. .TP .B login Use the system password database for authenticating the peer using -PAP. +PAP, and record the user in the system wtmp file. Note that if the +/etc/ppp/pap-secrets file exists, the peer must have an entry in that +file as well as the system password database to be allowed access. +.TP +.B maxconnect \fIn +Terminate the connection after \fIn\fR seconds. +.TP +.B modem +Use the modem control lines. This option is the default. With this +option, pppd will wait for the CD (Carrier Detect) signal from the +modem to be asserted when opening the serial device (unless a connect +script is specified), and it will drop the DTR (Data Terminal Ready) +signal briefly when the connection is terminated and before executing +the connect script. On Ultrix, this option implies hardware flow +control, as for the \fIcrtscts\fR option. +.TP +.B ms-dns \fI +If pppd is acting as a server for Microsoft Windows clients, this +option allows pppd to supply one or two DNS (Domain Name Server) +addresses to the clients. The first instance of this option specifies +the primary DNS address; the second instance (if given) specifies the +secondary DNS address. +.TP +.B name \fIname +Set the name of the local system for authentication purposes to +\fIname\fR. This is a privileged option. With this option, pppd will +use lines in the secrets files which have \fIname\fR as the second +field when looking for a secret to use in authenticating the peer. In +addition, unless overridden with the \fIuser\fR option, \fIname\fR +will be used as the name to send to the peer when authenticating the +local system to the peer. +.TP +.B netmask \fIn +Set the interface netmask to \fIn\fR, a 32 bit netmask in "decimal dot" +notation (e.g. 255.255.255.0). If this option is given, the value +specified is ORed with the default netmask. The default netmask is +chosen based on the negotiated remote IP address; it is the +appropriate network mask for the class of the remote IP address, ORed +with the netmasks for any non point-to-point network interfaces in the +system which are on the same network. +.TP +.B noaccomp +Disable Address/Control compression in both directions (send and +receive). +.TP +.B noauth +Do not require the peer to authenticate itself. This option is +privileged if the \fIauth\fR option is specified in /etc/ppp/options. +.TP +.B nobsdcomp +Disables BSD-Compress compression; \fBpppd\fR will not request or +agree to compress packets using the BSD-Compress scheme. +.TP +.B noccp +Disable CCP (Compression Control Protocol) negotiation. This option +should only be required if the peer is buggy and gets confused by +requests from pppd for CCP negotiation. +.TP +.B nocrtscts +Disable hardware flow control (i.e. RTS/CTS) on the serial port. If +neither the \fIcrtscts\fR nor the \fI\nocrtscts\fR option is given, +the hardware flow control setting for the serial port is left +unchanged. +.TP +.B nodefaultroute +Disable the \fIdefaultroute\fR option. The system administrator who +wishes to prevent users from creating default routes with pppd +can do so by placing this option in the /etc/ppp/options file. +.TP +.B nodeflate +Disables Deflate compression; pppd will not request or agree to +compress packets using the Deflate scheme. +.TP +.B nodetach +Don't detach from the controlling terminal. Without this option, if a +serial device other than the terminal on the standard input is +specified, pppd will fork to become a background process. +.TP +.B noip +Disable IPCP negotiation and IP communication. This option should +only be required if the peer is buggy and gets confused by requests +from pppd for IPCP negotiation. .TP .B noipdefault Disables the default behaviour when no local IP address is specified, @@ -245,216 +465,278 @@ hostname. With this option, the peer will have to supply the local IP address during IPCP negotiation (unless it specified explicitly on the command line or in an options file). .TP -.B lcp-restart \fI -Set the LCP restart interval (retransmission timeout) to seconds -(default 3). -.TP -.B lcp-max-terminate \fI -Set the maximum number of LCP terminate-request transmissions to -(default 3). +.B noipx +Disable the IPXCP and IPX protocols. This option should only be +required if the peer is buggy and gets confused by requests from pppd +for IPXCP negotiation. +.TP +.B nomagic +Disable magic number negotiation. With this option, pppd cannot +detect a looped-back line. This option should only be needed if the +peer is buggy. +.TP +.B nopcomp +Disable protocol field compression negotiation in both the receive and +the transmit direction. +.TP +.B nopersist +Exit once a connection has been made and terminated. This is the +default unless the \fIpersist\fR or \fIdemand\fR option has been +specified. +.TP +.B nopredictor1 +Do not accept or agree to Predictor-1 comprssion. +.TP +.B noproxyarp +Disable the \fIproxyarp\fR option. The system administrator who +wishes to prevent users from creating proxy ARP entries with pppd can +do so by placing this option in the /etc/ppp/options file. +.TP +.B novj +Disable Van Jacobson style TCP/IP header compression in both the +transmit and the receive direction. +.TP +.B novjccomp +Disable the connection-ID compression option in Van Jacobson style +TCP/IP header compression. With this option, pppd will not omit the +connection-ID byte from Van Jacobson compressed TCP/IP headers, nor +ask the peer to do so. +.TP +.B papcrypt +Indicates that all secrets in the /etc/ppp/pap-secrets file which are +used for checking the identity of the peer are encrypted, and thus +pppd should not accept a password which, before encryption, is +identical to the secret from the /etc/ppp/pap-secrets file. +.TP +.B pap-max-authreq \fIn +Set the maximum number of PAP authenticate-request transmissions to +\fIn\fR (default 10). .TP -.B lcp-max-configure \fI -Set the maximum number of LCP configure-request transmissions to -(default 10). +.B pap-restart \fIn +Set the PAP restart interval (retransmission timeout) to \fIn\fR +seconds (default 3). .TP -.B lcp-max-failure \fI -Set the maximum number of LCP configure-NAKs returned before starting -to send configure-Rejects instead to (default 10). +.B pap-timeout \fIn +Set the maximum time that pppd will wait for the peer to authenticate +itself with PAP to \fIn\fR seconds (0 means no limit). .TP -.B ipcp-restart \fI -Set the IPCP restart interval (retransmission timeout) to seconds -(default 3). +.B persist +Do not exit after a connection is terminated; instead try to reopen +the connection. .TP -.B ipcp-max-terminate \fI -Set the maximum number of IPCP terminate-request transmissions to -(default 3). +.B predictor1 +Request that the peer compress frames that it sends using Predictor-1 +compression, and agree to compress transmitted frames with Predictor-1 +if requested. This option has no effect unless the kernel driver +supports Predictor-1 compression. .TP -.B ipcp-max-configure \fI -Set the maximum number of IPCP configure-request transmissions to -(default 10). +.B proxyarp +Add an entry to this system's ARP [Address Resolution Protocol] table +with the IP address of the peer and the Ethernet address of this +system. This will have the effect of making the peer appear to other +systems to be on the local ethernet. .TP -.B ipcp-max-failure \fI -Set the maximum number of IPCP configure-NAKs returned before starting -to send configure-Rejects instead to (default 10). +.B remotename \fIname +Set the assumed name of the remote system for authentication purposes +to \fIname\fR. .TP -.B pap-restart \fI -Set the PAP restart interval (retransmission timeout) to seconds -(default 3). +.B refuse-chap +With this option, pppd will not agree to authenticate itself to the +peer using CHAP. .TP -.B pap-max-authreq \fI -Set the maximum number of PAP authenticate-request transmissions to - (default 10). +.B refuse-pap +With this option, pppd will not agree to authenticate itself to the +peer using PAP. .TP -.B chap-restart \fI -Set the CHAP restart interval (retransmission timeout for challenges) -to seconds (default 3). +.B require-chap +Require the peer to authenticate itself using CHAP [Challenge +Handshake Authentication Protocol] authentication. .TP -.B chap-max-challenge \fI -Set the maximum number of CHAP challenge transmissions to (default -10). +.B require-pap +Require the peer to authenticate itself using PAP [Password +Authentication Protocol] authentication. .TP -.B chap-interval \fI -If this option is given, -.I pppd -will rechallenge the peer every seconds. -.TP -.B ipcp-accept-local -With this option, -.I pppd -will accept the peer's idea of our local IP address, even if the -local IP address was specified in an option. +.B silent +With this option, pppd will not transmit LCP packets to initiate a +connection until a valid LCP packet is received from the peer (as for +the `passive' option with ancient versions of pppd). .TP -.B ipcp-accept-remote -With this option, -.I pppd -will accept the peer's idea of its (remote) IP address, even if the -remote IP address was specified in an option. +.B usehostname +Enforce the use of the hostname (with domain name appended, if given) +as the name of the local system for authentication purposes (overrides +the \fIname\fR option). +.TP +.B user \fIname +Sets the name used for authenticating the local system to the peer to +\fIname\fR. +.TP +.B vj-max-slots \fIn +Sets the number of connection slots to be used by the Van Jacobson +TCP/IP header compression and decompression code to \fIn\fR, which +must be between 2 and 16 (inclusive). +.TP +.B welcome \fIscript +Run the executable or shell command specified by \fIscript\fR before +initiating PPP negotiation, after the connect script (if any) has +completed. This option is privileged if the \fInoauth\fR option is +used. +.TP +.B xonxoff +Use software flow control (i.e. XON/XOFF) to control the flow of data on +the serial port. .SH OPTIONS FILES -Options can be taken from files as well as the command line. -.I pppd -reads options from the files /etc/ppp/options and $HOME/.ppprc before -looking at the command line. An options file is parsed into a series -of words, delimited by whitespace. Whitespace can be included in a -word by enclosing the word in quotes ("). A backslash (\\) quotes the -following character. A hash (#) starts a comment, which continues -until the end of the line. +Options can be taken from files as well as the command line. Pppd +reads options from the files /etc/ppp/options, ~/.ppprc and +/etc/ppp/options.\fIttyname\fR (in that order) before processing the +options on the command line. (In fact, the command-line options are +scanned to find the terminal name before the options.\fIttyname\fR +file is read.) In forming the name of the options.\fIttyname\fR file, +the initial /dev/ is removed from the terminal name, and any remaining +/ characters are replaced with dots. +.PP +An options file is parsed into a series of words, delimited by +whitespace. Whitespace can be included in a word by enclosing the +word in quotes ("). A backslash (\\) quotes the following character. +A hash (#) starts a comment, which continues until the end of the +line. +.SH PRIVILEGED OPTIONS +As indicated above, some security-sensitive options are privileged, +which means that they may not be used by an ordinary non-privileged +user running a setuid-root pppd, either on the command line, in the +user's ~/.ppprc file, or in an options file read using the \fIfile\fR +option. Privileged options may be used in /etc/ppp/options file or in +an options file read using the \fIcall\fR option. If pppd is being +run by the root user, privileged options can be used without +restriction. +.PP +The normal way that pppd should be set up is to have the \fIauth\fR +option in the /etc/ppp/options file. (This may become the default in +later releases.) If users wish to use pppd to dial out to a peer +which will refuse to authenticate itself (such as an internet service +provider), the system administrator should create an options file +under /etc/ppp/peers containing the \fInoauth\fR option, the name of +the serial port to use, and the \fIconnect\fR option (if required), +plus any other appropriate options. In this way, pppd can be set up +to allow non-privileged users to make unauthenticated connections only +to trusted peers. .SH AUTHENTICATION .I pppd provides system administrators with sufficient access control that PPP access to a server machine can be provided to legitimate users without fear of compromising the security of the server or the network it's on. In part this is provided by the /etc/ppp/options file, where the -administrator can place options to require authentication whenever -.I pppd -is run, and in part by the PAP and CHAP secrets files, where the +administrator can place options to restrict the ways in which pppd can +be used, and in part by the PAP and CHAP secrets files, where the administrator can restrict the set of IP addresses which individual users may use. .LP -The default behaviour of -.I pppd -is to agree to authenticate if requested, and to not -require authentication from the peer. However, -.I pppd -will not agree to -authenticate itself with a particular protocol if it has no secrets -which could be used to do so. +The default behaviour of pppd is to agree to authenticate if +requested, and to not require authentication from the peer. However, +pppd will not agree to authenticate itself with a particular protocol +if it has no secrets which could be used to do so. .LP Authentication is based on secrets, which are selected from secrets files (/etc/ppp/pap-secrets for PAP, /etc/ppp/chap-secrets for CHAP). Both secrets files have the same format, and both can store secrets for several combinations of server (authenticating peer) and client -(peer being authenticated). Note that -.I pppd -can be both a server -and client, and that different protocols can be used in the two -directions if desired. +(peer being authenticated). Note that pppd can be both a server and +client, and that different protocols can be used in the two directions +if desired. .LP A secrets file is parsed into words as for a options file. A secret is specified by a line containing at least 3 words, in the order -client, server, secret. Any following words on the same line are -taken to be a list of acceptable IP addresses for that client. If -there are only 3 words on the line, it is assumed that any IP address -is OK; to disallow all IP addresses, use "-". If the secret starts -with an `@', what follows is assumed to be the name of a file from -which to read the secret. A "*" as the client or server name matches -any name. When selecting a secret, \fIpppd\fR takes the best match, i.e. -the match with the fewest wildcards. +client name, server name, secret. Any following words on the same +line are taken to be a list of acceptable IP addresses for that +client. If there are only 3 words on the line, it is assumed that any +IP address is OK; to disallow all IP addresses, use "-". A word +starting with "!" indicates that the specified address is \fInot\fR +acceptable. An address may be followed by "/" and a number \fIn\fR, +to indicate a whole subnet, i.e. all addresses which have the same +value in the most significant \fIn\fR bits. +.LP +If the secret starts with an `@', what follows is assumed to be the +name of a file from which to read the secret. A "*" as the client or +server name matches any name. When selecting a secret, pppd takes the +best match, i.e. the match with the fewest wildcards. .LP Thus a secrets file contains both secrets for use in authenticating other hosts, plus secrets which we use for authenticating ourselves to -others. Which secret to use is chosen based on the names of the host -(the `local name') and its peer (the `remote name'). The local name -is set as follows: -.TP 3 -if the \fBusehostname\fR option is given, -then the local name is the hostname of this machine -(with the domain appended, if given) -.TP 3 -else if the \fBname\fR option is given, -then use the argument of the first \fBname\fR option seen -.TP 3 -else if the local IP address is specified with a hostname, -then use that name -.TP 3 -else use the hostname of this machine (with the domain appended, if given) +others. When pppd is authenticating the peer (checking the peer's +identity), it chooses a secret with the peer's name in the first +column and the name of the local system in the second column. The +name of the local system defaults to the hostname, with the domain +name appended if the \fIdomain\fR option is used. This default can be +overridden with the \fIname\fR option (unless the \fIusehostname\fR +option is used.) .LP -When authenticating ourselves using PAP, there is also a `username' -which is the local name by default, but can be set with the \fBuser\fR -option or the \fB+ua\fR option. -.LP -The remote name is set as follows: -.TP 3 -if the \fBremotename\fR option is given, -then use the argument of the last \fBremotename\fR option seen -.TP 3 -else if the remote IP address is specified with a hostname, -then use that host name -.TP 3 -else the remote name is the null string "". -.LP -Secrets are selected from the PAP secrets file as follows: -.TP 2 -* -For authenticating the peer, look for a secret with client == -username specified in the PAP authenticate-request, and server == -local name. -.TP 2 -* -For authenticating ourselves to the peer, look for a secret with -client == our username, server == remote name. +When pppd is choosing a secret to use in authenticating itself to the +peer, it looks for a secret with the local name in the first column +and the name of the remote system in the second column. The local +name is determined as described in the previous paragraph, except that +it may be overridden with the \fIuser\fR option. The remote name will +have been received from the peer if CHAP authentication is being +used. However, with PAP, pppd does not know the remote name at the +time when it has to look for the secret. In this case, it will use +the value given for the \fIremotename\fR option if specified. Failing +that, if the remote IP address was given as a name (rather than in +numeric form), it will use that name. Failing that, it will use the +empty string. .LP When authenticating the peer with PAP, a secret of "" matches any password supplied by the peer. If the password doesn't match the secret, the password is encrypted using crypt() and checked against the secret again; thus secrets for authenticating the peer can be -stored in encrypted form. If the \fBlogin\fR option was specified, the -username and password are also checked against the system password -database. Thus, the system administrator can set up the pap-secrets -file to allow PPP access only to certain users, and to restrict the -set of IP addresses that each user can use. +stored in encrypted form. If the \fIpapcrypt\fR option is given, the +first (unencrypted) comparison is omitted, for better security. .LP -Secrets are selected from the CHAP secrets file as follows: -.TP 2 -* -For authenticating the peer, look for a secret with client == name -specified in the CHAP-Response message, and server == local name. -.TP 2 -* -For authenticating ourselves to the peer, look for a secret with -client == local name, and server == name specified in the -CHAP-Challenge message. +If the \fIlogin\fR option was specified, the username and password are +also checked against the system password database. Thus, the system +administrator can set up the pap-secrets file to allow PPP access only +to certain users, and to restrict the set of IP addresses that each +user can use. Typically, when using the \fIlogin\fR option, the +secret in /etc/ppp/pap-secrets would be "", to avoid the need to have +the same secret in two places. .LP Authentication must be satisfactorily completed before IPCP (or any -other Network Control Protocol) can be started. If authentication -fails, \fIpppd\fR will terminated the link (by closing LCP). If IPCP -negotiates an unacceptable IP address for the remote host, IPCP will -be closed. IP packets can only be sent or received when IPCP is open. +other Network Control Protocol) can be started. If the peer is +required to authenticate itself, and fails to do so, pppd will +terminated the link (by closing LCP). If IPCP negotiates an +unacceptable IP address for the remote host, IPCP will be closed. IP +packets can only be sent or received when IPCP is open. +.LP +In some cases it is desirable to allow some hosts which can't +authenticate themselves to connect and use one of a restricted set of +IP addresses, even when the local host generally requires +authentication. If the peer refuses to authenticate itself when +requested, pppd takes that as equivalent to authenticating with PAP +using the empty string for the username and password. Thus, by adding +a line to the pap-secrets file which specifies the empty string for +the client and password, it is possible to allow restricted access to +hosts which refuse to authenticate themselves. .SH ROUTING .LP -When IPCP negotiation is completed successfully, -.I pppd -will inform the kernel of the local and remote IP addresses for the -ppp interface. This is sufficient to create a -host route to the remote end of the link, which will enable the peers -to exchange IP packets. Communication with other machines generally -requires further modification to routing tables and/or ARP (Address -Resolution Protocol) tables. In some cases this will be done -automatically through the actions of the \fIrouted\fR or \fIgated\fR -daemons, but in most cases some further intervention is required. +When IPCP negotiation is completed successfully, pppd will inform the +kernel of the local and remote IP addresses for the ppp interface. +This is sufficient to create a host route to the remote end of the +link, which will enable the peers to exchange IP packets. +Communication with other machines generally requires further +modification to routing tables and/or ARP (Address Resolution +Protocol) tables. In some cases this will be done automatically +through the actions of the \fIrouted\fR or \fIgated\fR daemons, but in +most cases some further intervention is required. .LP -Sometimes it is desirable -to add a default route through the remote host, as in the case of a -machine whose only connection to the Internet is through the ppp -interface. The \fBdefaultroute\fR option causes \fIpppd\fR to create such a -default route when IPCP comes up, and delete it when the link is -terminated. +Sometimes it is desirable to add a default route through the remote +host, as in the case of a machine whose only connection to the +Internet is through the ppp interface. The \fIdefaultroute\fR option +causes pppd to create such a default route when IPCP comes up, and +delete it when the link is terminated. .LP In some cases it is desirable to use proxy ARP, for example on a server machine connected to a LAN, in order to allow other hosts to -communicate with the remote host. The \fBproxyarp\fR option causes \fIpppd\fR -to look for a network interface on the same subnet as the remote host -(an interface supporting broadcast and ARP, which is up and not a -point-to-point or loopback interface). If found, \fIpppd\fR creates a +communicate with the remote host. The \fIproxyarp\fR option causes +pppd to look for a network interface on the same subnet as the remote +host (an interface supporting broadcast and ARP, which is up and not a +point-to-point or loopback interface). If found, pppd creates a permanent, published ARP entry with the IP address of the remote host and the hardware address of the network interface found. .SH EXAMPLES @@ -477,45 +759,126 @@ isn't dropped), and issue a command like pppd /dev/ttya 9600 .LP The process of logging in to the other machine and starting \fIpppd\fR -can be automated by using the \fBconnect\fR option to run \fIchat\fR, +can be automated by using the \fIconnect\fR option to run \fIchat\fR, for example: .IP pppd /dev/ttya 38400 connect 'chat "" "" "login:" "username" "Password:" "password" "% " "exec pppd passive"' .LP +(Note however that running chat like this will leave the password +visible in the parameter list of pppd and chat.) +.LP If your serial connection is any more complicated than a piece of wire, you may need to arrange for some control characters to be escaped. In particular, it is often useful to escape XON (^Q) and -XOFF (^S), using \fBasyncmap a0000\fR. If the path includes a telnet, -you probably should escape ^] as well (\fBasyncmap 200a0000\fR). -Don't use an rlogin in the path - many implementations are not -transparent; they will remove the sequence [0xff, 0xff, 0x73, 0x73, -followed by any 8 bytes] from the stream. +XOFF (^S), using \fIasyncmap a0000\fR. If the path includes a telnet, +you probably should escape ^] as well (\fIasyncmap 200a0000\fR). If +the path includes an rlogin, you will need to use the \fIescape ff\fR +option on the end which is running the rlogin client, since many +rlogin implementations are not transparent; they will remove the +sequence [0xff, 0xff, 0x73, 0x73, followed by any 8 bytes] from the +stream. .SH DIAGNOSTICS .LP -Messages are sent to the syslog daemon using facility -LOG_DAEMON unless -.I pppd -has been compiled with debugging code. In this case the logging -facility used will be LOG_LOCAL2 in order to allow separation of the debug -output from the other daemons using the LOG_DAEMON facility. You can -override this by defining the macro LOG_PPP to the desired facility -and recompiling. In order to see the error and debug messages, you -will need to edit your /etc/syslog.conf file to direct the messages to -the desired output device or file. +Messages are sent to the syslog daemon using facility LOG_DAEMON. +(This can be overriden by recompiling pppd with the macro +LOG_PPP defined as the desired facility.) In order to see the error +and debug messages, you will need to edit your /etc/syslog.conf file +to direct the messages to the desired output device or file. .LP -If enabled at compile time, debugging printout can be enabled by -setting the -d or debug flag on the command line, or by sending a -SIGUSR1 to the -.I pppd -process. -Debugging may be disabled by sending a SIGUSR2 to the -.I pppd -process. +The \fIdebug\fR option causes the contents of all control packets sent +or received to be logged, that is, all LCP, PAP, CHAP or IPCP packets. +This can be useful if the PPP negotiation does not succeed. +If debugging is enabled at compile time, the \fIdebug\fR option also +causes other debugging messages to be logged. +.LP +Debugging can also be enabled or disabled by sending a SIGUSR1 signal +to the pppd process. This signal acts as a toggle. .SH FILES .TP -.B /var/run/ppp\fIn\fB.pid \fR(BSD), \fB/etc/ppp/ppp\fIn\fB.pid \fR(SunOS) -Process-ID for \fIpppd\fR process on ppp interface unit \fIn\fR. +.B /var/run/ppp\fIn\fB.pid \fR(BSD or Linux), \fB/etc/ppp/ppp\fIn\fB.pid \fR(others) +Process-ID for pppd process on ppp interface unit \fIn\fR. +.TP +.B /etc/ppp/auth-up +A program or script which is executed after the remote system +successfully authenticates itself. It is executed with the parameters +.IP +\fIinterface-name peer-name user-name tty-device speed\fR +.IP +and with its standard input, output and error redirected to +/dev/null. This program or script is executed with the real and +effective user-IDs set to root, and with an empty environment. +.TP +.B /etc/ppp/auth-down +A program or script which is executed when the link goes down, if +/etc/ppp/auth-up was previously executed. It is executed in the same +manner with the same parameters as /etc/ppp/auth-up. +.TP +.B /etc/ppp/ip-up +A program or script which is executed when the link is available for +sending and receiving IP packets (that is, IPCP has come up). It is +executed with the parameters +.IP +\fIinterface-name tty-device speed local-IP-address +remote-IP-address ipparam\fR +.IP +and with its standard input, +output and error streams redirected to /dev/null. +.IP +This program or script is executed with the real and effective +user-IDs set to root. This is so that it can be used to manipulate +routes, run privileged daemons (e.g. \fIsendmail\fR), etc. Be +careful that the contents of the /etc/ppp/ip-up and /etc/ppp/ip-down +scripts do not compromise your system's security. +.IP +This program or script is executed with an empty environment, so you +must either specify a PATH or use full pathnames. +.TP +.B /etc/ppp/ip-down +A program or script which is executed when the link is no longer +available for sending and receiving IP packets. This script can be +used for undoing the effects of the /etc/ppp/ip-up script. It is +invoked in the same manner and with the same parameters as the ip-up +script, and the same security considerations apply. +.TP +.B /etc/ppp/ipx-up +A program or script which is executed when the link is available for +sending and receiving IPX packets (that is, IPXCP has come up). It is +executed with the parameters +.IP +\fIinterface-name tty-device speed network-number local-IPX-node-address +remote-IPX-node-address local-IPX-routing-protocol remote-IPX-routing-protocol +local-IPX-router-name remote-IPX-router-name ipparam pppd-pid\fR +.IP +and with its standard input, +output and error streams redirected to /dev/null. +.br +.IP +The local-IPX-routing-protocol and remote-IPX-routing-protocol field +may be one of the following: +.IP +NONE to indicate that there is no routing protocol +.br +RIP to indicate that RIP/SAP should be used +.br +NLSP to indicate that Novell NLSP should be used +.br +RIP NLSP to indicate that both RIP/SAP and NLSP should be used +.br +.IP +This program or script is executed with the real and effective +user-IDs set to root, and with an empty environment. This is so +that it can be used to manipulate routes, run privileged daemons (e.g. +\fIripd\fR), etc. Be careful that the contents of the /etc/ppp/ipx-up +and /etc/ppp/ipx-down scripts do not compromise your system's +security. +.TP +.B /etc/ppp/ipx-down +A program or script which is executed when the link is no longer +available for sending and receiving IPX packets. This script can be +used for undoing the effects of the /etc/ppp/ipx-up script. It is +invoked in the same manner and with the same parameters as the ipx-up +script, and the same security considerations apply. .TP .B /etc/ppp/pap-secrets Usernames, passwords and IP addresses for PAP authentication. @@ -524,59 +887,75 @@ Usernames, passwords and IP addresses for PAP authentication. Names, secrets and IP addresses for CHAP authentication. .TP .B /etc/ppp/options -System default options for -.I pppd, -read before user default options or command-line options. -.TP -.B $HOME/.ppprc -User default options, read before command-line options. +System default options for pppd, read before user default options or +command-line options. +.TP +.B ~/.ppprc +User default options, read before /etc/ppp/options.\fIttyname\fR. +.TP +.B /etc/ppp/options.\fIttyname +System default options for the serial port being used, read after +~/.ppprc. In forming the \fIttyname\fR part of this +filename, an initial /dev/ is stripped from the port name (if +present), and any slashes in the remaining part are converted to +dots. .SH SEE ALSO .TP .B RFC1144 Jacobson, V. -.I Compressing TCP/IP headers for low-speed serial links. -1990 February. +\fICompressing TCP/IP headers for low-speed serial links.\fR +February 1990. .TP .B RFC1321 Rivest, R. .I The MD5 Message-Digest Algorithm. -1992 April. -.TP -.B RFC1331 -Simpson, W.A. -.I Point\-to\-Point Protocol (PPP) for the transmission of multi\-protocol -.I datagrams over point\-to\-point links. -1992 May. +April 1992. .TP .B RFC1332 McGregor, G. .I PPP Internet Protocol Control Protocol (IPCP). -1992 May. +May 1992. .TP .B RFC1334 Lloyd, B.; Simpson, W.A. .I PPP authentication protocols. -1992 October. +October 1992. +.TP +.B RFC1661 +Simpson, W.A. +.I The Point\-to\-Point Protocol (PPP). +July 1994. +.TP +.B RFC1662 +Simpson, W.A. +.I PPP in HDLC-like Framing. +July 1994. .SH NOTES -The following signals have the specified effect when sent to the -.I pppd -process. +The following signals have the specified effect when sent to pppd. .TP .B SIGINT, SIGTERM -These signals cause \fIpppd\fR to terminate the link (by closing LCP), +These signals cause pppd to terminate the link (by closing LCP), restore the serial device settings, and exit. .TP .B SIGHUP -Indicates that the physical layer has been disconnected. \fIpppd\fR -will attempt to restore the serial device settings (this may produce -error messages on Suns), and then exit. -.SH BUGS -The use of the modem control lines and the effects of the \fBmodem\fR -and \fBlocal\fR options are not well defined. +This signal causes pppd to terminate the link, restore the serial +device settings, and close the serial device. If the \fIpersist\fR or +\fIdemand\fR option has been specified, pppd will try to reopen the +serial device and start another connection (after the holdoff period). +Otherwise pppd will exit. If this signal is received during the +holdoff period, it causes pppd to end the holdoff period immediately. +.TP +.B SIGUSR2 +This signal causes pppd to renegotiate compression. This can be +useful to re-enable compression after it has been disabled as a result +of a fatal decompression error. (Fatal decompression errors generally +indicate a bug in one or other implementation.) + .SH AUTHORS +Paul Mackerras (Paul.Mackerras@cs.anu.edu.au), based on earlier work by Drew Perkins, Brad Clements, Karl Fox, Greg Christy, -Brad Parker (brad@fcr.com), -Paul Mackerras (paulus@cs.anu.edu.au) +and +Brad Parker.