describe new options, don't describe obsolete ones
[ppp.git] / pppd / pppd.8
index 9cfba63ec4e637a5c5f9645d61f279fcc9313ba3..473eba550c971f1559b614642df45fba3263beb3 100644 (file)
@@ -1,5 +1,5 @@
 .\" manual page [] for pppd 2.0
-.\" $Id: pppd.8,v 1.16 1995/12/18 03:48:04 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,44 +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).
+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 \-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.
+.B default-asyncmap
+Disable asyncmap negotiation, forcing all control characters to be
+escaped for both the transmit and the 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 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 ms-dns \fI<addr>
-If
-.I pppd
-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.
+.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
@@ -259,24 +232,23 @@ 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 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.
+.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
+.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 -ipx
-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 ipcp-accept-local
 With this option,
 .I pppd
@@ -435,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
@@ -454,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 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 +pap
-Require the peer to authenticate itself using PAP.
+.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
@@ -485,9 +535,19 @@ 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
@@ -498,31 +558,37 @@ 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 -predictor1
-Do not accept or agree to Predictor-1 comprssion.
-.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
@@ -534,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
@@ -796,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
@@ -862,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
@@ -920,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.