![[OpenBSD]](/openbsd.gif){kind=small}
| PPPD(8) | System Manager's Manual | PPPD(8) |
pppd —
pppd |
[ tty_name ]
[speed ]
[options ] |
pppd daemon works together with the kernel
ppp(4) driver to establish and
maintain a PPP link with another system (called the
peer) and to negotiate Internet Protocol (IP)
addresses for each end of the link. pppd
can also authenticate the peer and/or supply authentication information to the
peer. PPP can be used with other network protocols besides IP, but such use is
becoming increasingly rare.
pppd will use that terminal, and will
not fork to put itself in the background. This option is privileged if the
noauth option is used.active-filter
filter-expressionidle 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 filter-expression syntax is as
described for tcpdump(8),
except that qualifiers which are inappropriate for a PPP link, such as
ether and
arp, 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.asyncmap
mappppd will ask the peer to send these
characters as a 2-byte escape sequence. If multiple
asyncmap options are given, the values
are ORed together. If no asyncmap
option is given, no async character map will be negotiated for the receive
direction; the peer should then escape all
control characters. To escape transmitted characters, use the
escape option.authcall
namenoauth, even if
pppd is not being run by root. The
name string may not begin with
“/” or include “..” as a pathname component.
The format of the options file is described below.connect
scriptpppd to execute (by passing it to a
shell) before attempting to start PPP negotiation. The
chat(8) program is often
useful here, as it provides a way to send arbitrary strings to a modem and
respond to received characters. This option is privileged if the
noauth option is used.crtsctspppd should set the
serial port to use hardware flow control using the RTS and CTS signals in
the RS-232 interface. If neither the
crtscts nor the
nocrtscts option is given, the hardware
flow control setting for the serial port is left unchanged.defaultroutenodefaultroute option has been
specified.disconnect
scriptpppd
has terminated the link. This command could, for example, issue commands
to the modem to cause it to hang up if hardware modem control signals were
not available. The disconnect script is not run if the modem has already
hung up. This option is privileged if the
noauth option is used.escape
xx,yy,...escape option,
unlike the asyncmap option which only
allows control characters to be specified. The characters which may not be
escaped are those with hex values 0x20 - 0x3f or 0x5e.file
namepppd.lockpppd should create a
UUCP-style lock file for the serial device to ensure exclusive access to
the device.mru
npppd will ask the peer to send packets
of no more than n bytes. The value of
n must be between 128 and 16384; the
default is 1500. A value of 296 works well on very slow links (40 bytes
for TCP/IP header + 256 bytes of data). Note that for the IPv6 protocol,
the MRU must be at least 1280.mtu
npppd will
request that the kernel networking code send data packets of no more than
n bytes through the PPP network
interface. Note that for the IPv6 protocol, the MTU must be at least
1280.passivepppd will attempt to initiate a
connection; if no reply is received from the peer,
pppd will then just wait passively for
a valid LCP packet from the peer, instead of exiting, as it would without
this option.noipdefault option is given). The
remote address will be obtained from the peer if not specified in any
option. Thus, in simple cases, this option is not required. If a local
and/or remote IP address is specified with this option,
pppd will not accept a different value
from the peer in the IPCP negotiation, unless the
ipcp-accept-local and/or
ipcp-accept-remote options are given,
respectively.bsdcomp
nr,ntnobsdcomp or
bsdcomp 0 disables BSD-Compress
compression entirely.chap-interval
npppd will
rechallenge the peer every n
seconds.chap-max-challenge
nchap-restart
ndebugpppd will log the contents of all
control packets sent or received in a readable form. The packets are
logged through syslogd(8)
with facility daemon and level
debug. This information can be directed
to a file by setting up
/etc/syslog.conf appropriately (see
syslog.conf(5)).default-asyncmapdefault-mrupppd will use the default MRU value of
1500 bytes for both the transmit and receive direction.deflate
nr,ntnodeflate
or deflate 0 to disable Deflate
compression entirely. (Note: pppd
requests Deflate compression in preference to BSD-Compress if the peer can
do either.)demandpppd 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. When
this is completed, pppd will commence
passing data packets (i.e., IP packets) across the link.
The demand option implies the
persist option. If this behaviour is
not desired, use the nopersist option
after the demand option. The
idle and
holdoff options are also useful in
conjunction with the demand
option.domain
ddomain
Quotron.COM. pppd would then use
the name porsche.Quotron.COM for looking
up secrets in the secrets file, and as the default name to send to the
peer when authenticating itself to the peer. This option is
privileged.holdoff
npersist or
demand option is used. The holdoff
period is not applied if the link was terminated because it was idle.idle
npppd should disconnect
if the link is idle for n 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
persist option without the
demand option. If the
active-filter option is given, data
packets which are rejected by the specified activity filter also count as
the link being idle.ipcp-accept-localpppd will accept the
peer's idea of our local IP address, even if the local IP address was
specified in an option.ipcp-accept-remotepppd will accept the
peer's idea of its (remote) IP address, even if the remote IP address was
specified in an option.ipcp-max-configure
nipcp-max-failure
nipcp-max-terminate
nipcp-restart
nipparam
stringkdebug
nlcp-echo-failure
npppd will
presume the peer to be dead if n LCP
echo-requests are sent without receiving a valid LCP echo-reply. If this
happens, pppd will terminate the
connection. Use of this option requires a non-zero value for the
lcp-echo-interval parameter. This
option can be used to enable pppd to
terminate after the physical connection has been broken (e.g., the modem
has hung up) in situations where no hardware modem control lines are
available.lcp-echo-interval
npppd will send
an LCP echo-request frame to the peer every
n seconds. Normally the peer should
respond to the echo-request by sending an echo-reply. This option can be
used with the lcp-echo-failure option
to detect that the peer is no longer connected.lcp-max-configure
nlcp-max-failure
nlcp-max-terminate
nlcp-restart
nlocalpppd will ignore the state of the CD
(Carrier Detect) signal from the modem and will not change the state of
the DTR (Data Terminal Ready) signal.loginmaxconnect
nmodempppd will wait for the CD (Carrier
Detect) signal from the modem to be asserted when opening the serial
device (unless a connect script is specified), and it will drop the DTR
(Data Terminal Ready) signal briefly when the connection is terminated and
before executing the connect script. On Ultrix, this option implies
hardware flow control, as for the
crtscts option.modem_chatms-dns
[pppd is acting as a server for
Microsoft Windows clients, this option allows
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. (This option was present in some
older versions of pppd under the name
dns-addr.)ms-wins
[pppd is acting as a server for
Microsoft Windows or “Samba” clients, this option allows
pppd to supply one or two WINS (Windows
Internet Name Services) server addresses to the clients. The first
instance of this option specifies the primary WINS address; the second
instance (if given) specifies the secondary WINS address.name
namepppd will use lines in the
secrets files which have name as the
second field when looking for a secret to use in authenticating the peer.
In addition, unless overridden with the
user option,
name will be used as the name to send to
the peer when authenticating the local system to the peer. (Note that
pppd does not append the domain name to
name.)netmask
npppd will always use
255.255.255.255 for the netmask, if that is the only appropriate value for
a point-to-point interface.)noaccompnoauthauth option is specified in
/etc/ppp/options.nobsdcomppppd
will not request or agree to compress packets using the BSD-Compress
scheme.noccppppd for CCP negotiation.nocrtsctscrtscts nor the
nocrtscts option is given, the hardware
flow control setting for the serial port is left unchanged.nodefaultroutedefaultroute option. The
system administrator who wishes to prevent users from creating default
routes with pppd can do so by placing
this option in the /etc/ppp/options
file.nodeflatepppd will
not request or agree to compress packets using the Deflate scheme.nodetachpppd will fork to become a background
process.noippppd for IPCP negotiation.noipdefaultnomagicpppd cannot detect a looped-back line.
This option should only be needed if the peer is buggy.nopcompnopersistpersist or
demand option has been specified.nopredictor1noproxyarpproxyarp option. The system
administrator who wishes to prevent users from creating proxy ARP entries
with pppd can do so by placing this
option in the /etc/ppp/options
file.novjnovjccomppppd will not omit the connection-ID
byte from Van Jacobson compressed TCP/IP headers, nor ask the peer to do
so.papcryptpppd should not accept a password
which, before encryption, is identical to the secret from the
/etc/ppp/pap-secrets file.pap-max-authreq
npap-restart
npap-timeout
npppd will
wait for the peer to authenticate itself with PAP to
n seconds (0 means no limit).pass-filter
filter-expressioninbound and
outbound qualifiers.persistpredictor1proxyarpremotename
namerefuse-chappppd will not agree
to authenticate itself to the peer using CHAP.refuse-pappppd will not agree
to authenticate itself to the peer using PAP.require-chaprequire-papsilentpppd 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 pppd).usehostnamename option).user
namevj-max-slots
nwelcome
scriptnoauth option is used.xonxoffpppd reads options from the files
/etc/ppp/options,
~/.ppprc and
/etc/ppp/options.ttyname (in that order)
before processing the options on the command line. (In fact, the command-line
options are scanned to find the terminal name before the
options.ttyname file is read.) In forming the
name of the options.ttyname file, the initial
/dev/ is removed from the terminal name, and any remaining / characters are
replaced with dots.
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. A hash (#) starts a
comment, which continues until the end of the line. There is no restriction on
using the file or
call options within an options file.
pppd.
pppd 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.
The normal way that pppd should be set up is
to have the auth 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
noauth option, the name of the serial port
to use, and the connect 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.
As indicated above, some security-sensitive options are privileged, which means
that they may not be used by an ordinary non-privileged user running a
setuid-root pppd, either on the command
line, in the user's ~/.ppprc file, or in an
options file read using the file option.
Privileged options may be used in the
/etc/ppp/options file or in an options file
read using the call option. If
pppd is being run by the root user,
privileged options can be used without restriction.
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.
The PPP protocol, being symmetrical, allows both peers to require the other to
authenticate itself. In that case, two separate and independent authentication
exchanges will occur. The two exchanges could use different authentication
protocols, and in principle, different names could be used in the two
exchanges.
The default behaviour of pppd is to agree to
authenticate if requested, and to not require authentication from the peer.
However, pppd will not agree to
authenticate itself with a particular protocol if it has no secrets which
could be used to do so.
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 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.
Each line in a secrets file contains one secret. Any following words on the same
line are taken to be a list of acceptable IP addresses for that client. If
there are only 3 words on the line, or if the first word is “-”,
then all IP addresses are disallowed. To allow any address, use
“*”. A word starting with “!” indicates that the
specified address is not acceptable. An address
may be followed by “/” and a number
n, to indicate a whole subnet, i.e., all
addresses which have the same value in the most significant
n bits. Case is significant in the client and
server names and in the secret.
If the secret starts with an `@', what follows is assumed to be the name of a
file from which to read the secret. A “*” as the client or
server name matches any name. When selecting a secret,
pppd takes the best match, i.e., the match
with the fewest wildcards.
Thus a secrets file contains both secrets for use in authenticating other hosts,
plus secrets which we use for authenticating ourselves to others. When
pppd is authenticating the peer (checking
the peer's identity), it chooses a secret with the peer's name in the first
field and the name of the local system in the second field. The name of the
local system defaults to the hostname, with the domain name appended if the
domain option is used. This default can be
overridden with the name option, except
when the usehostname option is used.
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 itself to the peer. This name can be specified by the user
with the user option. If this option is not
used, the name defaults to 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 remotename 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.
When authenticating the peer with PAP, the supplied password is first compared
with the secret from the secrets file. If the password doesn't match the
secret, the password is encrypted using
crypt(3) and checked against the
secret again. Thus secrets for authenticating the peer can be stored in
encrypted form if desired. If the papcrypt
option is given, the first (unencrypted) comparison is omitted, for better
security.
Furthermore, if the login option was
specified, the username and password are also checked against the system
password database. Thus, the system administrator can set up the pap-secrets
file to allow PPP access only to certain users, and to restrict the set of IP
addresses that each user can use. Typically, when using the
login option, the secret in
/etc/ppp/pap-secrets would be (), which
will match any password supplied by the peer. This avoids the need to have the
same secret in two places.
Authentication must be satisfactorily completed before IPCP (or any other
Network Control Protocol) can be started. If the peer is required to
authenticate itself, and fails to do so,
pppd will terminate the link (by closing
LCP). If IPCP negotiates an unacceptable IP address for the remote host, IPCP
will be closed. IP packets can only be sent or received when IPCP is open.
In some cases it is desirable to allow some hosts which can't authenticate
themselves to connect and use one of a restricted set of IP addresses, even
when the local host generally requires authentication. If the peer refuses to
authenticate itself when requested, pppd
takes that as equivalent to authenticating with PAP using the empty string for
the username and password. Thus, by adding a line to the pap-secrets file
which specifies the empty string for the client and password, it is possible
to allow restricted access to hosts which refuse to authenticate themselves.
pppd will inform the kernel of the local
and remote IP addresses for the PPP interface. This is sufficient to create a
host route to the remote end of the link, which will enable the peers to
exchange IP packets. Communication with other machines generally requires
further modification to routing tables and/or ARP (Address Resolution
Protocol) tables. In most cases the
defaultroute and/or
proxyarp options are sufficient for this,
but in some cases further intervention is required. The
/etc/ppp/ip-up script can be used for this.
Sometimes it is desirable to add a default route through the remote host, as in
the case of a machine whose only connection to the Internet is through the PPP
interface. The defaultroute option causes
pppd to create such a default route when
IPCP comes up, and delete it when the link is terminated.
In some cases it is desirable to use proxy ARP, for example on a server machine
connected to a LAN, in order to allow other hosts to communicate with the
remote host. The proxyarp option causes
pppd to look for a network interface on the
same subnet as the remote host (an interface supporting broadcast and ARP,
which is up and not a point-to-point or loopback interface). If found,
pppd creates a permanent, published ARP
entry with the IP address of the remote host and the hardware address of the
network interface found.
When the demand option is used, the interface
IP addresses have already been set at the point when IPCP comes up. If
pppd has not been able to negotiate the
same addresses that it used to configure the interface (for example when the
peer is an ISP that uses dynamic IP address assignment),
pppd has to change the interface IP
addresses to the negotiated addresses. This may disrupt existing connections,
and the use of demand dialling with peers that do dynamic IP address
assignment is not recommended.
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. 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:
DEVICEIFNAMEIPLOCALIPREMOTEPEERNAMESPEEDUIDpppd.pppd invokes the following scripts, if they
exist. It is not an error if they don't exist.
noauth
option is used.pppd will log a warning if this is not
the case.pppd will log a warning if this is not
the case.pppd, read
before user default options or command-line options.pppd was invoked by a user
other than root. The system administrator can create options files in this
directory to permit non-privileged users to dial out without requiring the
peer to authenticate, but only to certain trusted peers.auth option (as in the default
/etc/ppp/options file in the PPP
distribution).
Probably the most common use of pppd is to
dial out to an ISP. This can be done with a command such as
pppd call ispttyS0 19200 crtscts connect '/usr/sbin/chat -v -f /etc/ppp/chat-isp' noauth
ABORT "NO CARRIER" ABORT "NO DIALTONE" ABORT "ERROR" ABORT "NO ANSWER" ABORT "BUSY" ABORT "Username/Password Incorrect" "" "at" OK "at&d0&c1" OK "atdt2468135" "name:" "^Umyuserid" "word:" "\qmypassword" "ispts" "\q^Uppp" "~-^Uppp-~"
pppd can also be used to provide a dial-in
PPP service for users. If the users already have login accounts, the simplest
way to set up the PPP service is to let the users log in to their accounts and
run pppd (installed setuid-root) with a
command such as
pppd proxyarpjoespc server "joe's
secret" joespc.my.netpppd and whose home directory is
/etc/ppp. Options to be used when
pppd is run this way can be put in
/etc/ppp/.ppprc.
If your serial connection is any more complicated than a piece of wire, you may
need to arrange for some control characters to be escaped. In particular, it
is often useful to escape XON (^Q) and XOFF (^S), using
asyncmap a0000. If the path includes a
telnet, you probably should escape ^] as well
(asyncmap 200a0000). If the path includes
an rlogin, you will need to use the escape
ff option on the end which is running the rlogin client, since many
rlogin implementations are not transparent; they will remove the sequence
(0xff, 0xff, 0x73, 0x73, followed by any 8 bytes) from the stream.
LOG_DAEMON. (This can be
overridden by recompiling pppd with the
macro LOG_PPP defined as the desired
facility.) See the syslogd(8)
documentation for details of where the syslog daemon will write the messages.
On most systems, the syslog daemon uses the
/etc/syslog.conf file to specify the
destination(s) for syslog messages. You may need to edit that file to suit.
The debug option causes the contents of all
control packets sent or received to be logged, that is, all LCP, PAP, CHAP 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
debug option also causes other debugging
messages to be logged.
Debugging can also be enabled or disabled by sending a SIGUSR1 signal to the
pppd process. This signal acts as a toggle.
pppd process by sending it a signal from
the list below.
pppd to terminate
the link (by closing LCP), restore the serial device settings, and
exit.pppd to terminate
the link, restore the serial device settings, and close the serial device.
If the persist or
demand option has been specified,
pppd will try to reopen the serial
device and start another connection (after the holdoff period). Otherwise
pppd will exit. If this signal is
received during the holdoff period, it causes
pppd to end the holdoff period
immediately.debug option.pppd to renegotiate
compression. This can be useful to re-enable compression after it has been
disabled as a result of a fatal decompression error. (Fatal decompression
errors generally indicate a bug in one or other implementation.)| October 28, 2015 | OpenBSD-current |