.\" manual page [] for pppd 2.3
-.\" $Id: pppd.8,v 1.25 1997/03/04 03:42:25 paulus Exp $
+.\" $Id: pppd.8,v 1.31 1999/02/26 10:38:52 paulus Exp $
.\" SH section heading
.\" SS subsection heading
.\" LP paragraph
4.4BSD and NetBSD, any speed can be specified. Other systems
(e.g. SunOS) allow only a limited set of speeds.
.TP
+.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. This option
+is currently only available under NetBSD, and then only
+if both the kernel and pppd were compiled with PPP_FILTER defined.
+.TP
.B asyncmap \fI<map>
Set the async character map to <map>. This map describes which
control characters cannot be successfully received over the serial
.TP
.B auth
Require the peer to authenticate itself before allowing network
-packets to be sent or received.
+packets to be sent or received. If neither this option nor the
+\fInoauth\fR option is specified, the default is that pppd will not
+require the peer to authenticate, but will then only allow it to use
+IP addresses to which the system does not already have a route.
.TP
.B call \fIname
Read options from the file /etc/ppp/peers/\fIname\fR. This file may
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. If neither the \fIcrtscts\fR nor the
-\fInocrtscts\fR option is given, the hardware flow control setting
-for the serial port is left unchanged.
+Use hardware flow control (i.e. RTS/CTS) to control the flow of
+data on the serial port. If neither the \fIcrtscts\fR, the
+\fInocrtscts\fR, the \fIcdtrcts\fR nor the \fInocdtrcts\fR option
+is given, the hardware flow control setting for the serial port is
+left unchanged.
+Some serial ports (such as Macintosh serial ports) lack a true
+RTS output. Such serial ports use this mode to implement
+unidirectional flow control. The serial port will
+suspend transmission when requested by the modem (via CTS)
+but will be unable to request the modem stop sending to the
+computer. This mode retains the ability to use DTR as
+a modem control line.
+.TP
+.B cdtrcts
+Use a non-standard hardware flow control (i.e. DTR/CTS) to control
+the flow of data on the serial port. If neither the \fIcrtscts\fR,
+the \fInocrtscts\fR, the \fIcdtrcts\fR nor the \fInocdtrcts\fR
+option is given, the hardware flow control setting for the serial
+port is left unchanged.
+Some serial ports (such as Macintosh serial ports) lack a true
+RTS output. Such serial ports use this mode to implement true
+bi-directional flow control. The sacrifice is that this flow
+control mode does not permit using DTR as a modem control line.
.TP
.B defaultroute
Add a default route to the system routing tables, using the peer as
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.
+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 ipcp-accept-local
With this option, pppd will accept the peer's idea of our local IP
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.
+system which are on the same network. (Note: on some platforms, pppd
+will always use 255.255.255.255 for the netmask, if that is the only
+appropriate value for a point-to-point interface.)
.TP
.B noaccomp
Disable Address/Control compression in both directions (send and
.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.
+privileged.
.TP
.B nobsdcomp
Disables BSD-Compress compression; \fBpppd\fR will not request or
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 \fInocrtscts\fR option is given,
-the hardware flow control setting for the serial port is left
-unchanged.
+Disable hardware flow control (i.e. RTS/CTS) on the serial port.
+If neither the \fIcrtscts\fR nor the \fInocrtscts\fR nor the
+\fIcdtrcts\fR nor the \fInodtrcts\fR option is given, the hardware
+flow control setting for the serial port is left unchanged.
+.TP
+.B nodtrcts
+This option is a synonym for \fInocrtscts\fR. Either of these options will
+disable both forms of hardware flow control.
.TP
.B nodefaultroute
Disable the \fIdefaultroute\fR option. The system administrator who
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 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 prevent specific network daemons (such as
+routed) using up link bandwidth, or to provide a basic firewall
+capability.
+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. This
+option is currently only available under NetBSD, and then only if both
+the kernel and pppd were compiled with PPP_FILTER defined.
+.TP
.B persist
Do not exit after a connection is terminated; instead try to reopen
the connection.
.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).
+the \fIname\fR option). This option is not normally needed since the
+\fIname\fR option is privileged.
.TP
.B user \fIname
Sets the name used for authenticating the local system to the peer to
.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.
+word in double-quotes ("). A backslash (\\) quotes the following character.
A hash (#) starts a comment, which continues until the end of the
line. There is no restriction on using the \fIfile\fR or \fIcall\fR
options within an options file.
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 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.
+on. This control is provided through restrictions on which IP
+addresses the peer may use, based on its authenticated identity (if
+any), and through restrictions on which options a non-privileged user
+may use. Several of pppd's options are privileged, in particular
+those which permit potentially insecure configurations; these options
+are only accepted in files which are under the control of the system
+administrator, or if pppd is being run by root.
.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.
+The default behaviour of pppd is to allow an unauthenticated peer
+to use a given IP address if the system does not already have a
+route to that IP address already. For example, a system with a
+permanent connection to the wider internet will normally have a
+default route, and thus all peers will have to authenticate themselves
+in order to set up a connection. On such a system, the \fIauth\fR
+option should be used in /etc/ppp/options so that pppd will ask the
+peer to authenticate itself. On the other hand, a system where the
+PPP link is the only connection to the internet will not normally have
+a default route, so the peer will be able to use almost any IP address
+without authenticating itself.
.PP
As indicated above, some security-sensitive options are privileged,
which means that they may not be used by an ordinary non-privileged
.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 or Linux), \fB/etc/ppp/ppp\fIn\fB.pid \fR(others)
-Process-ID for pppd process on ppp interface unit \fIn\fR.
+.SH SCRIPTS
+Pppd invokes scripts at various stages in its processing which can be
+used to perform site-specific ancillary processing. These scripts are
+usually shell scripts, but could be executable code files instead.
+Pppd does not wait for the scripts to finish. The scripts are
+executed as root (with the real and effective user-id set to 0), so
+that they can do things such as update routing tables or run
+privileged daemons. Be careful that the contents of these scripts do
+not compromise your system's security. Pppd runs the scripts with
+standard input, output and error redirected to /dev/null, and with an
+environment that is empty except for some environment variables that
+give information about the link. The environment variables that pppd
+sets are:
+.TP
+.B DEVICE
+The name of the serial tty device being used.
+.TP
+.B IFNAME
+The name of the network interface being used.
+.TP
+.B IPLOCAL
+The IP address for the local end of the link. This is only set when
+IPCP has come up.
+.TP
+.B IPREMOTE
+The IP address for the remote end of the link. This is only set when
+IPCP has come up.
+.TP
+.B PEERNAME
+The authenticated name of the peer. This is only set if the peer
+authenticates itself.
+.TP
+.B SPEED
+The baud rate of the tty device.
+.TP
+.B ORIG_UID
+The real user-id of the user who invoked pppd.
+.P
+Pppd invokes the following scripts, if they exist. It is not an error
+if they don't exist.
.TP
.B /etc/ppp/auth-up
A program or script which is executed after the remote system
.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. (Note
-that this script is not executed if the peer doesn't authenticate
-itself, for example when the \fInoauth\fR option is used.)
+Note that this script is not executed if the peer doesn't authenticate
+itself, for example when the \fInoauth\fR option is used.
.TP
.B /etc/ppp/auth-down
A program or script which is executed when the link goes down, if
.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.
+script.
.TP
.B /etc/ppp/ipx-up
A program or script which is executed when the link is available for
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
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.
+script.
+.SH FILES
+.TP
+.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/pap-secrets
Usernames, passwords and IP addresses for PAP authentication. This
projects / ppp.git / blobdiff