.\" manual page [] for pppd 2.4
-.\" $Id: pppd.8,v 1.57 2001/03/12 22:49:25 paulus Exp $
+.\" $Id: pppd.8,v 1.71 2003/04/25 08:57:58 fcusack Exp $
.\" SH section heading
.\" SS subsection heading
.\" LP paragraph
\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
+is currently only available under NetBSD or Linux, and then only
if both the kernel and pppd were compiled with PPP_FILTER defined.
.TP
.B allow-ip \fIaddress(es)
element of the list of allowed IP addresses in the secrets files (see
the AUTHENTICATION section below).
.TP
+.B allow-number \fInumber
+Allow peers to connect from the given telephone number. A trailing
+`*' character will match all numbers beginning with the leading part.
+.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
network interface. This option is currently only available under
Linux.
.TP
+.B eap-interval \fIn
+If this option is given and pppd authenticates the peer with EAP
+(i.e., is the server), pppd will restart EAP authentication every
+\fIn\fR seconds. For EAP SRP-SHA1, see also the \fBsrp-interval\fR
+option, which enables lightweight rechallenge.
+.TP
+.B eap-max-rreq \fIn
+Set the maximum number of EAP Requests to which pppd will respond (as
+a client) without hearing EAP Success or Failure. (Default is 20.)
+.TP
+.B eap-max-sreq \fIn
+Set the maximum number of EAP Requests that pppd will issue (as a
+server) while attempting authentication. (Default is 10.)
+.TP
+.B eap-restart \fIn
+Set the retransmit timeout for EAP Requests when acting as a server
+(authenticator). (Default is 3 seconds.)
+.TP
+.B eap-timeout \fIn
+Set the maximum time to wait for the peer to send an EAP Request when
+acting as a client (authenticatee). (Default is 20 seconds.)
+.TP
.B hide-password
When logging the contents of PAP packets, this option causes pppd to
exclude the password string from the log. This is the default.
Enables the use of PPP multilink; this is an alias for the `multilink'
option. This option is currently only available under Linux.
.TP
+.B mppe-stateful
+Allow MPPE to use stateful mode. Stateless mode is still attempted first.
+The default is to disallow stateful mode.
+.TP
.B mpshortseq
Enables the use of short (12-bit) sequence numbers in multilink
headers, as opposed to 24-bit sequence numbers. This option is only
Disables the use of PPP multilink. This option is currently only
available under Linux.
.TP
+.B nomppe
+Disables MPPE (Microsoft Point to Point Encryption). This is the default.
+.TP
+.B nomppe-40
+Disable 40\-bit encryption with MPPE.
+.TP
+.B nomppe-128
+Disable 128\-bit encryption with MPPE.
+.TP
+.B nomppe-stateful
+Disable MPPE stateful mode. This is the default.
+.TP
.B nompshortseq
Disables the use of short (12-bit) sequence numbers in the PPP
multilink protocol, forcing the use of 24-bit sequence numbers. This
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.
+option is currently only available under NetBSD or Linux, and then
+only if both the kernel and pppd were compiled with PPP_FILTER defined.
+.TP
+.B password \fIpassword-string
+Specifies the password to use for authenticating to the peer. Use
+of this option is discouraged, as the password is likely to be visible
+to other users on the system (for example, by using ps(1)).
.TP
.B persist
Do not exit after a connection is terminated; instead try to reopen
-the connection.
+the connection. The \fBmaxfail\fR option still has an effect on
+persistent connections.
.TP
.B plugin \fIfilename
Load the shared library object file \fIfilename\fR as a plugin. This
-is a privileged option.
+is a privileged option. If \fIfilename\fR does not contain a slash
+(/), pppd will look in the \fB/usr/lib/pppd/\fIversion\fR directory
+for the plugin, where
+\fIversion\fR is the version number of pppd (for example, 2.4.2).
.TP
.B predictor1
Request that the peer compress frames that it sends using Predictor-1
Set the assumed name of the remote system for authentication purposes
to \fIname\fR.
.TP
+.B remotenumber \fInumber
+Set the assumed telephone number of the remote system for authentication
+purposes to \fInumber\fR.
+.TP
.B refuse-chap
With this option, pppd will not agree to authenticate itself to the
peer using CHAP.
.TP
+.B refuse-mschap
+With this option, pppd will not agree to authenticate itself to the
+peer using MS-CHAP.
+.TP
+.B refuse-mschap-v2
+With this option, pppd will not agree to authenticate itself to the
+peer using MS-CHAPv2.
+.TP
+.B refuse-eap
+With this option, pppd will not agree to authenticate itself to the
+peer using EAP.
+.TP
.B refuse-pap
With this option, pppd will not agree to authenticate itself to the
peer using PAP.
Require the peer to authenticate itself using CHAP [Challenge
Handshake Authentication Protocol] authentication.
.TP
+.B require-mppe
+Require the use of MPPE (Microsoft Point to Point Encryption). This
+option disables all other compression types. This option enables
+both 40\-bit and 128\-bit encryption. In order for MPPE to successfully
+come up, you must have authenticated with either MS-CHAP or MS-CHAPv2.
+This option is presently only supported under Linux, and only if your
+kernel has been configured to include MPPE support.
+.TP
+.B require-mppe-40
+Require the use of MPPE, with 40\-bit encryption.
+.TP
+.B require-mppe-128
+Require the use of MPPE, with 128\-bit encryption.
+.TP
+.B require-mschap
+Require the peer to authenticate itself using MS-CHAP [Microsft Challenge
+Handshake Authentication Protocol] authentication.
+.TP
+.B require-mschap-v2
+Require the peer to authenticate itself using MS-CHAPv2 [Microsft Challenge
+Handshake Authentication Protocol, Version 2] authentication.
+.TP
+.B require-eap
+Require the peer to authenticate itself using EAP [Extensible
+Authentication Protocol] authentication.
+.TP
.B require-pap
Require the peer to authenticate itself using PAP [Password
Authentication Protocol] authentication.
connection until a valid LCP packet is received from the peer (as for
the `passive' option with ancient versions of pppd).
.TP
+.B srp-interval \fIn
+If this parameter is given and pppd uses EAP SRP-SHA1 to authenticate
+the peer (i.e., is the server), then pppd will use the optional
+lightweight SRP rechallenge mechanism at intervals of \fIn\fR
+seconds. This option is faster than \fBeap-interval\fR
+reauthentication because it uses a hash-based mechanism and does not
+derive a new session key.
+.TP
+.B srp-pn-secret \fIstring
+Set the long-term pseudonym-generating secret for the server. This
+value is optional and if set, needs to be known at the server
+(authenticator) side only, and should be different for each server (or
+poll of identical servers). It is used along with the current date to
+generate a key to encrypt and decrypt the client's identity contained
+in the pseudonym.
+.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
+file any pseudonym offered by the peer during authentication.
+.TP
.B sync
Use synchronous HDLC serial encoding instead of asynchronous.
The device used by pppd with this option must have sync support.
Currently supports Microgate SyncLink adapters
under Linux and FreeBSD 2.2.8 and later.
.TP
+.B unit \fInum
+Sets the ppp unit number (for a ppp0 or ppp1 etc interface name) for outbound
+connections.
+.TP
.B updetach
With this option, pppd will detach from its controlling terminal once
it has successfully established the ppp connection (to the point where
correspond to the internet hostnames of the peers, but this is not
essential.
.LP
-At present, pppd supports two authentication protocols: the Password
-Authentication Protocol (PAP) and the Challenge Handshake
-Authentication Protocol (CHAP). PAP involves the client sending its
-name and a cleartext password to the server to authenticate itself.
-In contrast, the server initiates the CHAP authentication exchange by
-sending a challenge to the client (the challenge packet includes the
-server's name). The client must respond with a response which
-includes its name plus a hash value derived from the shared secret and
-the challenge, in order to prove that it knows the secret.
+At present, pppd supports three authentication protocols: the Password
+Authentication Protocol (PAP), Challenge Handshake Authentication
+Protocol (CHAP), and Extensible Authentication Protocol (EAP). PAP
+involves the client sending its name and a cleartext password to the
+server to authenticate itself. In contrast, the server initiates the
+CHAP authentication exchange by sending a challenge to the client (the
+challenge packet includes the server's name). The client must respond
+with a response which includes its name plus a hash value derived from
+the shared secret and the challenge, in order to prove that it knows
+the secret. EAP supports CHAP-style authentication, and also includes
+the SRP-SHA1 mechanism, which is resistant to dictionary-based attacks
+and does not require a cleartext password on the server side.
.LP
The PPP protocol, being symmetrical, allows both peers to require the
other to authenticate itself. In that case, two separate and
if it has no secrets which could be used to do so.
.LP
Pppd stores secrets for use in authentication in secrets
-files (/etc/ppp/pap-secrets for PAP, /etc/ppp/chap-secrets for CHAP).
-Both secrets files have the same format. The secrets files can
+files (/etc/ppp/pap-secrets for PAP, /etc/ppp/chap-secrets for CHAP,
+MS-CHAP, MS-CHAPv2, and EAP MD5-Challenge, and /etc/ppp/srp-secrets
+for EAP SRP-SHA1).
+All secrets files have the same format. The secrets files can
contain secrets for pppd to use in authenticating itself to other
systems, as well as secrets for pppd to use when authenticating other
systems to itself.
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, except when the
-\fIusehostname\fR option is used.
+\fIusehostname\fR option is used. (For EAP SRP-SHA1, see the
+srp-entry(8) utility for generating proper validator entries to be
+used in the "secret" field.)
.LP
When pppd is choosing a secret to use in authenticating itself to the
peer, it first determines what name it is going to use to identify
the name of the local system, determined as described in the previous
paragraph. Then pppd looks for a secret with this name in the first
field and the peer's name in the second field. Pppd will know the
-name of the peer if CHAP authentication is being used, because the
-peer will have sent it in the challenge packet. However, if PAP is being
-used, pppd will have to determine the peer's name from the options
-specified by the user. The user can specify the peer's name directly
-with the \fIremotename\fR option. Otherwise, if the remote IP address
-was specified by a name (rather than in numeric form), that name will
-be used as the peer's name. Failing that, pppd will use the null
-string as the peer's name.
+name of the peer if CHAP or EAP authentication is being used, because
+the peer will have sent it in the challenge packet. However, if PAP
+is being used, pppd will have to determine the peer's name from the
+options specified by the user. The user can specify the peer's name
+directly with the \fIremotename\fR option. Otherwise, if the remote
+IP address was specified by a name (rather than in numeric form), that
+name will be used as the peer's name. Failing that, pppd will use the
+null string as the peer's name.
.LP
When authenticating the peer with PAP, the supplied password is first
compared with the secret from the secrets file. If the password
.LP
To allow a user to use the PPP facilities, you need to allocate an IP
address for that user's machine and create an entry in
-/etc/ppp/pap-secrets or /etc/ppp/chap-secrets (depending on which
-authentication method the PPP implementation on the user's machine
-supports), so that the user's
-machine can authenticate itself. For example, if Joe has a machine
-called "joespc" which is to be allowed to dial in to the machine
-called "server" and use the IP address joespc.my.net, you would add an
-entry like this to /etc/ppp/pap-secrets or /etc/ppp/chap-secrets:
+/etc/ppp/pap-secrets, /etc/ppp/chap-secrets, or /etc/ppp/srp-secrets
+(depending on which authentication method the PPP implementation on
+the user's machine supports), so that the user's machine can
+authenticate itself. For example, if Joe has a machine called
+"joespc" that is to be allowed to dial in to the machine called
+"server" and use the IP address joespc.my.net, you would add an entry
+like this to /etc/ppp/pap-secrets or /etc/ppp/chap-secrets:
.IP
joespc server "joe's secret" joespc.my.net
.LP
+(See srp-entry(8) for a means to generate the server's entry when
+SRP-SHA1 is in use.)
Alternatively, you can create a username called (for example) "ppp",
whose login shell is pppd and whose home directory is /etc/ppp.
Options to be used when pppd is run this way can be put in
.SH DIAGNOSTICS
.LP
Messages are sent to the syslog daemon using facility LOG_DAEMON.
-(This can be overriden by recompiling pppd with the macro
+(This can be overridden 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
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.
+or received to be logged, that is, all LCP, PAP, CHAP, EAP, or IPCP packets.
This can be useful if the PPP negotiation does not succeed or if
authentication fails.
If debugging is enabled at compile time, the \fIdebug\fR option also
.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 /var/run/ppp-\fIname\fB.pid \fR(BSD or Linux), \fB/etc/ppp/ppp-\fIname\fB.pid \fR(others)
+.B /var/run/ppp-\fIname\fB.pid \fR(BSD or Linux),
+\fB/etc/ppp/ppp-\fIname\fB.pid \fR(others)
Process-ID for pppd process for logical link \fIname\fR (see the
\fIlinkname\fR option).
.TP
user. Pppd will log a warning if this is not the case.
.TP
.B /etc/ppp/chap-secrets
-Names, secrets and IP addresses for CHAP authentication. As for
+Names, secrets and IP addresses for CHAP/MS-CHAP/MS-CHAPv2 authentication.
+As for /etc/ppp/pap-secrets, this file should be owned by root and not
+readable or writable by any other user. Pppd will log a warning if
+this is not the case.
+.TP
+.B /etc/ppp/srp-secrets
+Names, secrets, and IP addresses for EAP authentication. As for
/etc/ppp/pap-secrets, this file should be owned by root and not
readable or writable by any other user. Pppd will log a warning if
this is not the case.
.TP
+.B ~/.ppp_pseudonym
+Saved client-side SRP-SHA1 pseudonym. See the \fIsrp-use-pseudonym\fR
+option for details.
+.TP
.B /etc/ppp/options
System default options for pppd, read before user default options or
command-line options.
.I PPP in HDLC-like Framing.
July 1994.
.TP
+.B RFC2284
+Blunk, L.; Vollbrecht, J.,
+.I PPP Extensible Authentication Protocol (EAP).
+March 1998.
+.TP
.B RFC2472
Haskin, D.
.I IP Version 6 over PPP
December 1998.
+.TP
+.B RFC2945
+Wu, T.,
+.I The SRP Authentication and Key Exchange System
+September 2000.
+.TP
+.B draft-ietf-pppext-eap-srp-03.txt
+Carlson, J.; et al.,
+.I EAP SRP-SHA1 Authentication Protocol.
+July 2001.
.SH NOTES
The following signals have the specified effect when sent to pppd.
.TP
projects / ppp.git / blobdiff