.\" manual page [] for pppd 2.4
-.\" $Id: pppd.8,v 1.89 2007/06/19 02:08:35 carlsonj Exp $
+.\" $Id: pppd.8,v 1.90 2008/03/26 12:09:40 paulus Exp $
.\" SH section heading
.\" SS subsection heading
.\" LP paragraph
This entry is removed when the PPP connection is broken. This option
is privileged if the \fInodefaultroute\fR option has been specified.
.TP
+.B defaultroute-metric
+Define the metric of the \fIdefaultroute\fR and only add it if there
+is no other default route with the same metric. With the default
+value of -1, the route is only added if there is no default route at
+all.
+.TP
+.B defaultroute6
+Add a default IPv6 route to the system routing tables, using the peer as
+the gateway, when IPv6CP negotiation is successfully completed.
+This entry is removed when the PPP connection is broken. This option
+is privileged if the \fInodefaultroute6\fR option has been specified.
+.TP
.B disconnect \fIscript
Execute the command specified by \fIscript\fR, by passing it to a
shell, after
negotiation, unless the \fIipcp\-accept\-local\fR and/or
\fIipcp\-accept\-remote\fR options are given, respectively.
.TP
+.B +ipv6
+Enable the IPv6CP and IPv6 protocols.
+.TP
.B ipv6 \fI<local_interface_identifier>\fR,\fI<remote_interface_identifier>
Set the local and/or remote 64-bit interface identifier. Either one may be
-omitted. The identifier must be specified in standard ascii notation of
+omitted. The identifier must be specified in standard ASCII notation of
IPv6 addresses (e.g. ::dead:beef). If the
\fIipv6cp\-use\-ipaddr\fR
option is given, the local identifier is the local IPv4 address (see above).
compression in the corresponding direction. Use \fInobsdcomp\fR or
\fIbsdcomp 0\fR to disable BSD-Compress compression entirely.
.TP
+.B ca \fIca-file
+(EAP-TLS) Use the file \fIca-file\fR as the X.509 Certificate Authority
+(CA) file (in PEM format), needed for setting up an EAP-TLS connection.
+This option is used on the client-side in conjunction with the \fBcert\fR
+and \fBkey\fR options.
+.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,
bi-directional flow control. The sacrifice is that this flow
control mode does not permit using DTR as a modem control line.
.TP
+.B cert \fIcertfile
+(EAP-TLS) Use the file \fIcertfile\fR as the X.509 certificate (in PEM
+format), needed for setting up an EAP-TLS connection. This option is
+used on the client-side in conjunction with the \fBca\fR and
+\fBkey\fR options.
+.TP
.B chap\-interval \fIn
If this option is given, pppd will rechallenge the peer every \fIn\fR
seconds.
Set the CHAP restart interval (retransmission timeout for challenges)
to \fIn\fR seconds (default 3).
.TP
+.B chap-timeout \fIn
+Set timeout for CHAP authentication by peer to \fIn\fR seconds (default 60).
+.TP
.B child\-timeout \fIn
When exiting, wait for up to \fIn\fR seconds for any child processes
(such as the command specified with the \fBpty\fR command) to exit
1000 (1 second). This wait period only applies if the \fBconnect\fR
or \fBpty\fR option is used.
.TP
+.B crl \fIfilename
+(EAP-TLS) Use the file \fIfilename\fR as the Certificate Revocation List
+to check for the validity of the peer's certificate. This option is not
+mandatory for setting up an EAP-TLS connection. Also see the \fBcrl-dir\fR
+option.
+.TP
+.B crl-dir \fIdirectory
+(EAP-TLS) Use the directory \fIdirectory\fR to scan for CRL files in
+has format ($hash.r0) to check for the validity of the peer's certificate.
+This option is not mandatory for setting up an EAP-TLS connection.
+Also see the \fBcrl\fR option.
+.TP
.B debug
Enables connection debugging facilities.
If this option is given, pppd will log the contents of all
.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
+With this option, the remote IP address may be specified by the user
+on the command line or in an options file, or if not, pppd will use
+an arbitrary address in the 10.x.x.x range. 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.
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.
+options are also useful in conjunction with the \fIdemand\fR option.
.TP
.B domain \fId
Append the domain name \fId\fR to the local host name for authentication
option is given, the \fIstring\fR supplied is given as the 6th
parameter to those scripts.
.TP
+.B ipv6cp\-accept\-local
+With this option, pppd will accept the peer's idea of our local IPv6
+interface identifier, even if the local IPv6 interface identifier
+was specified in an option.
+.TP
+.B ipv6cp\-accept\-remote
+With this option, pppd will accept the peer's idea of its (remote)
+IPv6 interface identifier, even if the remote IPv6 interface
+identifier was specified in an option.
+.TP
.B ipv6cp\-max\-configure \fIn
Set the maximum number of IPv6CP configure-request transmissions to
\fIn\fR (default 10).
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
+Set the maximum number of IPXCP terminate request frames before the
local system considers that the peer is not listening to them. The
default value is 3.
.TP
the kernel are logged by syslog(1) to a file as directed in the
/etc/syslog.conf configuration file.
.TP
+.B key \fIkeyfile
+(EAP-TLS) Use the file \fIkeyfile\fR as the private key file (in PEM
+format), needed for setting up an EAP-TLS connection. This option is
+used on the client-side in conjunction with the \fBca\fR and
+\fBcert\fR options.
+.TP
.B ktune
Enables pppd to alter kernel settings as appropriate. Under Linux,
pppd will enable IP forwarding (i.e. set /proc/sys/net/ipv4/ip_forward
dynamic IP address option (i.e. set /proc/sys/net/ipv4/ip_dynaddr to
1) in demand mode if the local address changes.
.TP
+.B lcp\-echo\-adaptive
+If this option is used with the \fIlcp\-echo\-failure\fR option then
+pppd will send LCP echo\-request frames only if no traffic was received
+from the peer since the last echo\-request was sent.
+.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
system password database to be allowed access. See also the
\fBenable\-session\fR option.
.TP
+.B master_detach
+If multilink is enabled and this pppd process is the multilink bundle
+master, and the link controlled by this pppd process terminates, this
+pppd process continues to run in order to maintain the bundle. If the
+\fBmaster_detach\fR option has been given, pppd will detach from its
+controlling terminal in this situation, even if the \fBnodetach\fR
+option has been given.
+.TP
.B maxconnect \fIn
Terminate the connection when it has been available for network
traffic for \fIn\fR seconds (i.e. \fIn\fR seconds after the first
Disable Address/Control compression in both directions (send and
receive).
.TP
+.B need-peer-eap
+(EAP-TLS) Require the peer to verify our authentication credentials.
+.TP
.B noauth
Do not require the peer to authenticate itself. This option is
privileged.
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 nodefaultroute6
+Disable the \fIdefaultroute6\fR option. The system administrator who
+wishes to prevent users from adding a default route 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.
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 noremoteip
+Allow pppd to operate without having an IP address for the peer. This
+option is only available under Linux. Normally, pppd will request the
+peer's IP address, and if the peer does not supply it, pppd will use
+an arbitrary address in the 10.x.x.x subnet.
+With this option, if the peer does
+not supply its IP address, pppd will not ask the peer for it, and will
+not set the destination address of the ppp interface. In this
+situation, the ppp interface can be used for routing by creating
+device routes, but the peer itself cannot be addressed directly for IP
+traffic.
+.TP
.B notty
Normally, pppd requires a terminal device. With this option, pppd
will allocate itself a pseudo-tty master/slave pair and use the slave
device. The \fIscript\fR will be run in a child process with the
pseudo-tty master as its standard input and output. An explicit
device name may not be given if this option is used. (Note: if the
-\fIrecord\fR option is used in conjuction with the \fIpty\fR option,
+\fIrecord\fR option is used in conjunction with the \fIpty\fR option,
the child process will have pipes on its standard input and output.)
.TP
.B receive\-all
Require the peer to authenticate itself using PAP [Password
Authentication Protocol] authentication.
.TP
+.B set \fIname\fR=\fIvalue
+Set an environment variable for scripts that are invoked by pppd.
+When set by a privileged source, the variable specified by \fIname\fR
+cannot be changed by options contained in an unprivileged source. See
+also the \fIunset\fR option and the environment described in
+\fISCRIPTS\fR.
+.TP
.B show\-password
When logging the contents of PAP packets, this option causes pppd to
show the password string in the log message.
.TP
.B srp\-use\-pseudonym
When operating as an EAP SRP\-SHA1 client, attempt to use the pseudonym
-stored in ~/.ppp_psuedonym first as the identity, and save in this
+stored in ~/.ppp_pseudonym first as the identity, and save in this
file any pseudonym offered by the peer during authentication.
.TP
+.B stop\-bits \fIn
+Set the number of stop bits for the serial port. Valid values are 1 or 2.
+The default value is 1.
+.TP
.B sync
Use synchronous HDLC serial encoding instead of asynchronous.
The device used by pppd with this option must have sync support.
.TP
.B unit \fInum
Sets the ppp unit number (for a ppp0 or ppp1 etc interface name) for outbound
-connections.
+connections. If the unit is already in use a dynamically allocated number will
+be used.
+.TP
+.B ifname \fIstring
+Set the ppp interface name for outbound connections. If the interface name is
+already in use, or if the name cannot be used for any other reason, pppd will
+terminate.
+.TP
+.B unset \fIname
+Remove a variable from the environment variable for scripts that are
+invoked by pppd. When specified by a privileged source, the variable
+\fIname\fR cannot be set by options contained in an unprivileged
+source. See also the \fIset\fR option and the environment described
+in \fISCRIPTS\fR.
.TP
.B updetach
With this option, pppd will detach from its controlling terminal once
the first network control protocol, usually the IP control protocol,
has come up).
.TP
+.B up_sdnotify
+Use this option to run pppd in systemd service units of Type=notify
+(\fBup_sdnotify\fR implies \fBnodetach\fR).
+When \fBup_sdnotify\fR is enabled, pppd will notify systemd once
+it has successfully established the ppp connection (to the point where
+the first network control protocl, usually the IP control protocol,
+has come up). This option is only availble when pppd is compiled with
+systemd support.
+.TP
.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
.B xonxoff
Use software flow control (i.e. XON/XOFF) to control the flow of data on
the serial port.
+.SH PPPOE OPTIONS
+To establish PPP link over Ethernet (PPPoE) it is needed to load pppd's
+\fBplugin pppoe.so\fR and then specify option \fBnic-\fIinterface\fR
+instead of modem options \fIttyname\fR and \fIspeed\fR.
+Recognized pppd's PPPoE options are:
+.TP
+.B nic-\fIinterface
+Use the ethernet device \fIinterface\fR to communicate with the peer.
+For example, establishing PPPoE link on \fIeth0\fR interface is done
+by specifying ppp'd option \fBnic-eth0\fR. Prefix \fBnic-\fR for this
+option may be avoided if interface name is unambiguous and does not
+look like any other pppd's option.
+.TP
+.B rp_pppoe_service \fIname
+Connect to specified PPPoE service name.
+.TP
+.B rp_pppoe_ac \fIname
+Connect to specified PPPoE access concentrator name.
+.TP
+.B rp_pppoe_sess \fIsessid\fP:\fImacaddr
+Attach to existing PPPoE session.
+.TP
+.B rp_pppoe_verbose \fIn
+Be verbose about discovered access concentrators.
+.TP
+.B pppoe-mac \fImacaddr
+Connect to specified MAC address.
+.TP
+.B host-uniq \fIstring
+Set the PPPoE Host-Uniq tag to the supplied hex string.
+By default PPPoE Host-Uniq tag is set to the pppd's process PID.
+.TP
+.B pppoe-padi-timeout \fIn
+Initial timeout for discovery packets in seconds (default 5).
+.TP
+.B pppoe-padi-attempts \fIn
+Number of discovery attempts (default 3).
.SH OPTIONS FILES
Options can be taken from files as well as the command line. Pppd
reads options from the files /etc/ppp/options, ~/.ppprc and
.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 double-quotes ("). A backslash (\\) quotes the following character.
+word in double-quotes ("). A backslash (\e) 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.
.br
"name:" "^Umyuserid"
.br
-"word:" "\\qmypassword"
+"word:" "\eqmypassword"
.br
-"ispts" "\\q^Uppp"
+"ispts" "\eq^Uppp"
.br
"~\-^Uppp\-~"
.LP
.B LINKNAME
The logical name of the link, set with the \fIlinkname\fR option.
.TP
+.B CALL_FILE
+The value of the \fIcall\fR option.
+.TP
.B DNS1
If the peer supplies DNS server addresses, this variable is set to the
-first DNS server address supplied.
+first DNS server address supplied (whether or not the usepeerdns
+option was given).
.TP
.B DNS2
If the peer supplies DNS server addresses, this variable is set to the
-second DNS server address supplied.
+second DNS server address supplied (whether or not the usepeerdns
+option was given).
.P
Pppd invokes the following scripts, if they exist. It is not an error
if they don't exist.
.I PPP in HDLC-like Framing.
July 1994.
.TP
+.B RFC1990
+Sklower, K.; et al.,
+.I The PPP Multilink Protocol (MP).
+August 1996.
+.TP
.B RFC2284
Blunk, L.; Vollbrecht, J.,
.I PPP Extensible Authentication Protocol (EAP).
prior written permission.
.LP
4. Redistributions of any form whatsoever must retain the following
- acknowledgments:
+ acknowledgements:
.br
"This product includes software developed by Computing Services
at Carnegie Mellon University (http://www.cmu.edu/computing/)."
projects / ppp.git / blobdiff