describe new options, don't describe obsolete ones
[ppp.git] / pppd / pppd.8
index 84a328badd12088b5ed1edb2f869304f2d023031..473eba550c971f1559b614642df45fba3263beb3 100644 (file)
@@ -1,5 +1,5 @@
 .\" manual page [] for pppd 2.0
-.\" $Id: pppd.8,v 1.15 1995/08/17 01:52:17 paulus Exp $
+.\" $Id: pppd.8,v 1.18 1996/04/04 04:01:28 paulus Exp $
 .\" SH section heading
 .\" SS subsection heading
 .\" LP paragraph
@@ -119,15 +119,6 @@ peer requests a smaller value via MRU negotiation, \fIpppd\fR will
 request that the kernel networking code send data packets of no more
 than \fIn\fR bytes through the PPP network interface. 
 .TP
-.B netmask \fI<n>
-Set the interface netmask to <n>, 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 passive
 Enables the "passive" option in the LCP.  With this option,
 .I pppd
@@ -136,13 +127,6 @@ 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
-ancient versions of \fIpppd\fR).
 .SH OPTIONS
 .TP
 .I <local_IP_address>\fB:\fI<remote_IP_address>
@@ -163,21 +147,19 @@ and/or
 .B ipcp-accept-remote
 options are given, respectively.
 .TP
-.B -ac
-Disable Address/Control compression negotiation (use default, i.e.
-address/control field compression disabled).
-.TP
-.B -all
-Don't request or allow negotiation of any options for LCP and IPCP (use
-default values).
-.TP
-.B -am
-Disable asyncmap negotiation (use the default asyncmap, i.e. escape
-all control characters).
-.TP
-.B -as \fI<n>
-Same as
-.B asyncmap \fI<n>
+.B active-filter \fIfilter-expression
+Specifies a packet filter to be applied to data packets to determine
+which packets are to be regarded as link activity, and therefore reset
+the idle timer, or cause the link to be brought up in demand-dialling
+mode.  This option is useful in conjunction with the
+\fBidle\fR option if there are packets being sent or received
+regularly over the link (for example, routing information packets)
+which would otherwise prevent the link from ever appearing to be idle.
+The \fIfilter-expression\fR syntax is as described for tcpdump(1),
+except that qualifiers which are inappropriate for a PPP link, such as
+\fBether\fR and \fBarp\fR, are not permitted.  Generally the filter
+expression should be enclosed in single-quotes to prevent whitespace
+in the expression from being interpreted by the shell.
 .TP
 .B bsdcomp \fInr,nt
 Request that the peer compress packets that it sends, using the
@@ -190,17 +172,6 @@ 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 \-bsdcomp
-Disables compression; \fBpppd\fR will not request or agree to compress
-packets using the BSD-Compress scheme.
-.TP
-.B +chap
-Require the peer to authenticate itself using CHAP [Cryptographic
-Handshake Authentication Protocol] authentication.
-.TP
-.B -chap
-Don't agree to authenticate using CHAP.
-.TP
 .B chap-interval \fI<n>
 If this option is given,
 .I pppd
@@ -214,34 +185,46 @@ Set the maximum number of CHAP challenge transmissions to <n> (default
 Set the CHAP restart interval (retransmission timeout for challenges)
 to <n> seconds (default 3).
 .TP
-.B -crtscts
-Disable hardware flow control (i.e. RTS/CTS) on the serial port.  If
-neither the \fBcrtscts\fR nor the \fB\-crtscts\fR option is given,
-the hardware flow control setting for the serial port is left
-unchanged.
-.TP
-.B -d
-Increase debugging level (same as the \fBdebug\fR option).
-.TP
 .B debug
-Increase debugging level (same as \fB\-d\fR).
-If this
-option is given, \fIpppd\fR 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 \-defaultroute
-Disable the \fBdefaultroute\fR option.  The system administrator who
-wishes to prevent users from creating default routes with \fIpppd\fR
-can do so by placing this option in the /etc/ppp/options file.
+Increase debugging level.
+If this option is given, \fIpppd\fR 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,
+\fIpppd\fR will use the default MRU value of 1500 bytes for both the
+transmit and receive direction.
 .TP
-.B -detach
-Don't fork to become a background process (otherwise
-.I pppd
-will do so if a serial device other than its controlling terminal is
-specified).
+.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 bits, and
+agree to compress packets sent to the peer with a maximum window size of
+\fI2**nt\fR bits.  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: \fBpppd\fR
+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 specific by the user
+on the command line or in an options file.  \fBpppd\fR will initially
+configure the interface and enable it for IP traffic without
+connecting to the peer.  When traffic is available, \fBpppd\fR will
+connect to the peer and perform negotiation, authentication, etc.
+When this is completed, \fBpppd\fR will commence passing data packets
+(i.e., IP packets) across the link.  The persist, idle and holdoff
+options are often useful in conjuction with this option.
 .TP
 .B domain \fI<d>
 Append the domain name <d> to the local host name for authentication
@@ -249,10 +232,22 @@ 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.
 .TP
-.B -ip
-Disable IP address negotiation.  If this option is used, the remote IP
-address must be specified with an option on the command line or in an
-options file.
+.B holdoff \fI<n>
+Specifies how many seconds to wait before re-initiating the link after
+it terminates.  This option only has effect if the persist option is
+used.
+.TP
+.B idle \fI<n>
+Specifies that \fBpppd\fR should disconnect if it is idle for
+\fI<n>\fR seconds.  The link is idle when no data packets (i.e. IP
+packets) are being sent or received.  If the \fBactive-filter\fR
+option is given, data packets which are rejected by the specified
+activity filter also count as the link being idle.
+.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 ipcp-accept-local
 With this option,
@@ -287,6 +282,67 @@ 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 \fI<n>
+Set the IPX network number in the IPXCP configure request frame to
+<n>. There is no valid default. If this option is not specified then
+the network number is obtained from the peer. If the peer does not
+have the network number, the IPX protocol will not be started. This is
+a hexadecimal number and is entered without any leading sequence such
+as 0x. It is related to the \fIipxcp-accept-network\fR option.
+.TP
+.B ipx-node \fI<n>:<m>
+Set the IPX node numbers. The two node numbers are separated from each
+other with a colon character. The first number <n> is the local node
+number. The second number <m> is the peer's node number. Each node number
+is a hexadecimal number, to the maximum of ten significant digits. The
+node numbers on the ipx-network must be unique. There is no valid
+default. If this option is not specified then the node number is
+obtained from the peer. This option is a related to the
+\fIipxcp-accept-local\fR and \fIipxcp-accept-remote\fR options.
+.TP
+.B ipx-router-name \fI<string>
+Set the name of the router. This is a string and is sent to the peer
+as information data.
+.TP
+.B ipx-routing \fI<n>
+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 \fI<n>
+Set the maximum number of IPXCP configure request frames which the
+system will send to <n>. The default is 10.
+.TP
+.B ipxcp-max-failure \fI<n>
+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 \fI<n>
+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
@@ -351,18 +407,72 @@ executing the connect script.
 On Ultrix, this option implies hardware
 flow control, as for the \fBcrtscts\fR option.  
 .TP
-.B -mn
-Disable magic number negotiation.  With this option,
+.B ms-dns \fI<addr>
+If
 .I pppd
-cannot detect a looped-back line.
-.TP
-.B -mru
-Disable MRU [Maximum Receive Unit] negotiation.  With this option,
-\fIpppd\fR will use the default MRU value of 1500 bytes.
+is acting as a server for Microsoft Windows clients, this option
+allows
+.I 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 \fI<n>
 Set the name of the local system for authentication purposes to <n>.
 .TP
+.B netmask \fI<n>
+Set the interface netmask to <n>, 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 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
+.I pppd
+for CCP negotiation.
+.TP
+.B nocrtscts
+Disable hardware flow control (i.e. RTS/CTS) on the serial port.  If
+neither the \fBcrtscts\fR nor the \fB\-crtscts\fR option is given,
+the hardware flow control setting for the serial port is left
+unchanged.
+.TP
+.B nodefaultroute
+Disable the \fBdefaultroute\fR option.  The system administrator who
+wishes to prevent users from creating default routes with \fIpppd\fR
+can do so by placing this option in the /etc/ppp/options file.
+.TP
+.B nodeflate
+Disables Deflate compression; \fBpppd\fR 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 its controlling terminal is specified,
+.I 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
+.I pppd
+for IPCP negotiation.
+.TP
 .B noipdefault
 Disables the default behaviour when no local IP address is specified,
 which is to determine (if possible) the local IP address from the
@@ -370,16 +480,40 @@ 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 -p
-Same as the
-.B passive
-option.
+.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
+.I pppd
+for IPXCP negotiation.
 .TP
-.B +pap
-Require the peer to authenticate itself using PAP.
+.B nomagic
+Disable magic number negotiation.  With this option,
+.I 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 nopredictor1
+Do not accept or agree to Predictor-1 comprssion.
+.TP
+.B noproxyarp
+Disable the \fBproxyarp\fR option.  The system administrator who
+wishes to prevent users from creating proxy ARP entries with
+\fIpppd\fR can do so by placing this option in the /etc/ppp/options
+file.
 .TP
-.B -pap
-Don't agree to authenticate using PAP.
+.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, \fIpppd\fR 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
@@ -401,36 +535,60 @@ Set the maximum time that
 will wait for the peer to authenticate itself with PAP to
 <n> seconds (0 means no limit).
 .TP
-.B -pc
-Disable protocol field compression negotiation (use default, i.e.
-protocol field compression disabled).
+.B pass-filter \fIfilter-expression
+Specifies a packet filter to applied to data packets being sent or
+received to determine which packets should be allowed to pass.
+Packets which are rejected by the filter are silently discarded.  This
+option can be used to provide protection against IP address spoofing
+and other attacks.
+The \fIfilter-expression\fR syntax is as described for tcpdump(1),
+except that qualifiers which are inappropriate for a PPP link, such as
+\fBether\fR and \fBarp\fR, are not permitted.  Generally the filter
+expression should be enclosed in single-quotes to prevent whitespace
+in the expression from being interpreted by the shell.  Note that it
+is possible to apply different constraints to incoming and outgoing
+packets using the \fBinbound\fR and \fBoutbound\fR qualifiers.
 .TP
 .B persist
 Do not exit after a connection is terminated; instead try to reopen
 the connection.
 .TP
+.B predictor1
+Attempt to request that the peer send frames which
+have been compressed using Predictor-1 compression.  This option will
+be ignored unless Predictor-1 code has been loaded into the kernel.
+.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.
 .TP
-.B \-proxyarp
-Disable the \fBproxyarp\fR option.  The system administrator who
-wishes to prevent users from creating proxy ARP entries with
-\fIpppd\fR can do so by placing this option in the /etc/ppp/options
-file.
-.TP
 .B remotename \fI<n>
 Set the assumed name of the remote system for authentication purposes
 to <n>.
 .TP
-.B +ua \fI<p>
-Agree to authenticate using PAP [Password Authentication Protocol] if
-requested by the peer, and
-use the data in file <p> 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.
+.B refuse-chap
+With this option, \fIpppd\fR will not agree to authenticate itself
+to the peer using CHAP.
+.TP
+.B refuse-pap
+With this option, \fIpppd\fR will not agree to authenticate itself
+to the peer using PAP.
+.TP
+.B require-chap
+Require the peer to authenticate itself using CHAP [Cryptographic
+Handshake Authentication Protocol] authentication.
+.TP
+.B require-pap
+Require the peer to authenticate itself using PAP [Password
+Authentication Protocol] authentication.
+.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
+ancient versions of \fIpppd\fR).
 .TP
 .B usehostname
 Enforce the use of the hostname as the name of the local system for
@@ -442,16 +600,6 @@ option).
 Set the user name to use for authenticating this machine with the peer
 using PAP to <u>.
 .TP
-.B -vj
-Disable negotiation of Van Jacobson style TCP/IP header compression (use
-default, i.e. no compression).
-.TP
-.B -vjccomp
-Disable the connection-ID compression option in Van Jacobson style
-TCP/IP header compression.  With this option, \fIpppd\fR will not omit
-the connection-ID byte from Van Jacobson compressed TCP/IP headers,
-nor ask the peer to do so.
-.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
@@ -704,6 +852,10 @@ be used to manipulate routes, run privileged daemons (e.g.
 \fBsendmail\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 without an environment, so you
+must either specify a PATH or use full pathnames (e.g. \fI/sbin/route\fR,
+as opposed to \fIroute\fR).
 .TP
 .B /etc/ppp/ip-down
 A program or script which is executed when the link is no longer
@@ -713,6 +865,47 @@ invoked with the same parameters as the ip-up script, and the same
 security considerations apply, since it is executed with the same
 effective and real user-IDs as \fIpppd\fR.
 .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 \fB/dev/null\fR.
+.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 same real and effective
+user-ID as \fIpppd\fR, that is, at least the effective user-ID and
+possibly the real user-ID will be \fBroot\fR.  This is so that it can
+be used to manipulate routes, run privileged daemons (e.g.
+\fBripd\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 with the same parameters as the ipx-up script, and the same
+security considerations apply, since it is executed with the same
+effective and real user-IDs as \fIpppd\fR.
+.TP
 .B /etc/ppp/pap-secrets
 Usernames, passwords and IP addresses for PAP authentication.
 .TP
@@ -729,38 +922,41 @@ User default options, read before command-line options.
 .TP
 .B /etc/ppp/options.\fIttyname
 System default options for the serial port being used, read after
-command-line options.
+command-line options.  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.
+February 1990.
 .TP
 .B RFC1321
 Rivest, R.
 .I The MD5 Message-Digest Algorithm.
-1992 April.
+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 RFC1548
+.B RFC1661
 Simpson, W.A.
 .I The Point\-to\-Point Protocol (PPP).
-1993 December.
+July 1994.
 .TP
-.B RFC1549
+.B RFC1662
 Simpson, W.A.
-.I PPP in HDLC Framing.
-1993 December
+.I PPP in HDLC-like Framing.
+July 1994.
 .SH NOTES
 The following signals have the specified effect when sent to the
 .I pppd
@@ -787,9 +983,10 @@ decompression errors generally indicate a bug in one or other
 implementation.
 
 .SH AUTHORS
+Paul Mackerras (paulus@cs.anu.edu.au), based on earlier work by
 Drew Perkins,
 Brad Clements,
 Karl Fox,
 Greg Christy,
-Brad Parker,
-Paul Mackerras (paulus@cs.anu.edu.au).
+and
+Brad Parker.