1 .\" manual page [] for pppd 2.3
2 .\" $Id: pppd.8,v 1.26 1997/04/30 05:56:22 paulus Exp $
4 .\" SS subsection heading
6 .\" IP indented paragraph
10 pppd \- Point to Point Protocol daemon
22 The Point-to-Point Protocol (PPP) provides a method for transmitting
23 datagrams over serial point-to-point links. PPP
24 is composed of three parts: a method for encapsulating datagrams over
25 serial links, an extensible Link Control Protocol (LCP), and
26 a family of Network Control Protocols (NCP) for establishing
27 and configuring different network-layer protocols.
29 The encapsulation scheme is provided by driver code in the kernel.
30 Pppd provides the basic LCP, authentication support, and an NCP for
31 establishing and configuring the Internet Protocol (IP) (called the IP
32 Control Protocol, IPCP).
33 .SH FREQUENTLY USED OPTIONS
36 Communicate over the named device. The string "/dev/" is prepended if
37 necessary. If no device name is given, or if the name of the terminal
38 connected to the standard input is given, pppd
39 will use that terminal, and will not fork to put itself in the
40 background. This option is privileged if the \fInoauth\fR option is
44 Set the baud rate to <speed> (a decimal number). On systems such as
45 4.4BSD and NetBSD, any speed can be specified. Other systems
46 (e.g. SunOS) allow only a limited set of speeds.
48 .B active-filter \fIfilter-expression
49 Specifies a packet filter to be applied to data packets to determine
50 which packets are to be regarded as link activity, and therefore reset
51 the idle timer, or cause the link to be brought up in demand-dialling
52 mode. This option is useful in conjunction with the
53 \fBidle\fR option if there are packets being sent or received
54 regularly over the link (for example, routing information packets)
55 which would otherwise prevent the link from ever appearing to be idle.
56 The \fIfilter-expression\fR syntax is as described for tcpdump(1),
57 except that qualifiers which are inappropriate for a PPP link, such as
58 \fBether\fR and \fBarp\fR, are not permitted. Generally the filter
59 expression should be enclosed in single-quotes to prevent whitespace
60 in the expression from being interpreted by the shell. This option
61 is currently only available under NetBSD, and then only
62 if both the kernel and pppd were compiled with PPP_FILTER defined.
65 Set the async character map to <map>. This map describes which
66 control characters cannot be successfully received over the serial
67 line. Pppd will ask the peer to send these characters as a 2-byte
68 escape sequence. The argument is a 32 bit hex number with each bit
69 representing a character to escape. Bit 0 (00000001) represents the
70 character 0x00; bit 31 (80000000) represents the character 0x1f or ^_.
71 If multiple \fIasyncmap\fR options are given, the values are ORed
72 together. If no \fIasyncmap\fR option is given, no async character
73 map will be negotiated for the receive direction; the peer should then
74 escape \fIall\fR control characters. To escape transmitted
75 characters, use the \fIescape\fR option.
78 Require the peer to authenticate itself before allowing network
79 packets to be sent or received.
82 Read options from the file /etc/ppp/peers/\fIname\fR. This file may
83 contain privileged options, such as \fInoauth\fR, even if pppd
84 is not being run by root. The \fIname\fR string may not begin with /
85 or include .. as a pathname component. The format of the options file
89 Use the executable or shell command specified by \fIscript\fR to set
90 up the serial line. This script would typically use the chat(8)
91 program to dial the modem and start the remote ppp session. This
92 option is privileged if the \fInoauth\fR option is used.
95 Use hardware flow control (i.e. RTS/CTS) to control the flow of data
96 on the serial port. If neither the \fIcrtscts\fR nor the
97 \fInocrtscts\fR option is given, the hardware flow control setting
98 for the serial port is left unchanged.
101 Add a default route to the system routing tables, using the peer as
102 the gateway, when IPCP negotiation is successfully completed.
103 This entry is removed when the PPP connection is broken. This option
104 is privileged if the \fInodefaultroute\fR option has been specified.
106 .B disconnect \fIscript
107 Run the executable or shell command specified by \fIscript\fR after
108 pppd has terminated the link. This script could, for example, issue
109 commands to the modem to cause it to hang up if hardware modem control
110 signals were not available. The disconnect script is not run if the
111 modem has already hung up. This option is privileged if the
112 \fInoauth\fR option is used.
114 .B escape \fIxx,yy,...
115 Specifies that certain characters should be escaped on transmission
116 (regardless of whether the peer requests them to be escaped with its
117 async control character map). The characters to be escaped are
118 specified as a list of hex numbers separated by commas. Note that
119 almost any character can be specified for the \fIescape\fR option,
120 unlike the \fIasyncmap\fR option which only allows control characters
121 to be specified. The characters which may not be escaped are those
122 with hex values 0x20 - 0x3f or 0x5e.
125 Read options from file \fIname\fR (the format is described below).
126 The file must be readable by the user who has invoked pppd.
129 Specifies that pppd should create a UUCP-style lock file for the
130 serial device to ensure exclusive access to the device.
133 Set the MRU [Maximum Receive Unit] value to \fIn\fR. Pppd
134 will ask the peer to send packets of no more than \fIn\fR bytes. The
135 minimum MRU value is 128. The default MRU value is 1500. A value of
136 296 is recommended for slow links (40 bytes for TCP/IP header + 256
140 Set the MTU [Maximum Transmit Unit] value to \fIn\fR. Unless the
141 peer requests a smaller value via MRU negotiation, pppd will
142 request that the kernel networking code send data packets of no more
143 than \fIn\fR bytes through the PPP network interface.
146 Enables the "passive" option in the LCP. With this option, pppd will
147 attempt to initiate a connection; if no reply is received from the
148 peer, pppd will then just wait passively for a valid LCP packet from
149 the peer, instead of exiting, as it would without this option.
152 .I <local_IP_address>\fB:\fI<remote_IP_address>
153 Set the local and/or remote interface IP addresses. Either one may be
154 omitted. The IP addresses can be specified with a host name or in
155 decimal dot notation (e.g. 150.234.56.78). The default local
156 address is the (first) IP address of the system (unless the
158 option is given). The remote address will be obtained from the peer
159 if not specified in any option. Thus, in simple cases, this option is
160 not required. If a local and/or remote IP address is specified with
162 will not accept a different value from the peer in the IPCP
163 negotiation, unless the \fIipcp-accept-local\fR and/or
164 \fIipcp-accept-remote\fR options are given, respectively.
167 Request that the peer compress packets that it sends, using the
168 BSD-Compress scheme, with a maximum code size of \fInr\fR bits, and
169 agree to compress packets sent to the peer with a maximum code size of
170 \fInt\fR bits. If \fInt\fR is not specified, it defaults to the value
171 given for \fInr\fR. Values in the range 9 to 15 may be used for
172 \fInr\fR and \fInt\fR; larger values give better compression but
173 consume more kernel memory for compression dictionaries.
174 Alternatively, a value of 0 for \fInr\fR or \fInt\fR disables
175 compression in the corresponding direction. Use \fInobsdcomp\fR or
176 \fIbsdcomp 0\fR to disable BSD-Compress compression entirely.
178 .B chap-interval \fIn
179 If this option is given, pppd will rechallenge the peer every \fIn\fR
182 .B chap-max-challenge \fIn
183 Set the maximum number of CHAP challenge transmissions to \fIn\fR
187 Set the CHAP restart interval (retransmission timeout for challenges)
188 to \fIn\fR seconds (default 3).
191 Enables connection debugging facilities.
192 If this option is given, pppd will log the contents of all
193 control packets sent or received in a readable form. The packets are
194 logged through syslog with facility \fIdaemon\fR and level
195 \fIdebug\fR. This information can be directed to a file by setting up
196 /etc/syslog.conf appropriately (see syslog.conf(5)).
199 Disable asyncmap negotiation, forcing all control characters to be
200 escaped for both the transmit and the receive direction.
203 Disable MRU [Maximum Receive Unit] negotiation. With this option,
204 pppd will use the default MRU value of 1500 bytes for both the
205 transmit and receive direction.
208 Request that the peer compress packets that it sends, using the
209 Deflate scheme, with a maximum window size of \fI2**nr\fR bytes, and
210 agree to compress packets sent to the peer with a maximum window size
211 of \fI2**nt\fR bytes. If \fInt\fR is not specified, it defaults to
212 the value given for \fInr\fR. Values in the range 8 to 15 may be used
213 for \fInr\fR and \fInt\fR; larger values give better compression but
214 consume more kernel memory for compression dictionaries.
215 Alternatively, a value of 0 for \fInr\fR or \fInt\fR disables
216 compression in the corresponding direction. Use \fInodeflate\fR or
217 \fIdeflate 0\fR to disable Deflate compression entirely. (Note: pppd
218 requests Deflate compression in preference to BSD-Compress if the peer
222 Initiate the link only on demand, i.e. when data traffic is present.
223 With this option, the remote IP address must be specified by the user
224 on the command line or in an options file. Pppd will initially
225 configure the interface and enable it for IP traffic without
226 connecting to the peer. When traffic is available, pppd will
227 connect to the peer and perform negotiation, authentication, etc.
228 When this is completed, pppd will commence passing data packets
229 (i.e., IP packets) across the link.
231 The \fIdemand\fR option implies the \fIpersist\fR option. If this
232 behaviour is not desired, use the \fInopersist\fR option after the
233 \fIdemand\fR option. The \fIidle\fR and \fIholdoff\fR
234 options are also useful in conjuction with the \fIdemand\fR option.
237 Append the domain name \fId\fR to the local host name for authentication
238 purposes. For example, if gethostname() returns the name porsche, but
239 the fully qualified domain name is porsche.Quotron.COM, you could
240 specify \fIdomain Quotron.COM\fR. Pppd would then use the name
241 \fIporsche.Quotron.COM\fR for looking up secrets in the secrets file,
242 and as the default name to send to the peer when authenticating itself
243 to the peer. This option is privileged.
246 Specifies how many seconds to wait before re-initiating the link after
247 it terminates. This option only has any effect if the \fIpersist\fR
248 or \fIdemand\fR option is used. The holdoff period is not applied if
249 the link was terminated because it was idle.
252 Specifies that pppd should disconnect if the link is idle for \fIn\fR
253 seconds. The link is idle when no data packets (i.e. IP packets) are
254 being sent or received. Note: it is not advisable to use this option
255 with the \fIpersist\fR option without the \fIdemand\fR option.
256 If the \fBactive-filter\fR
257 option is given, data packets which are rejected by the specified
258 activity filter also count as the link being idle.
261 With this option, pppd will accept the peer's idea of our local IP
262 address, even if the local IP address was specified in an option.
264 .B ipcp-accept-remote
265 With this option, pppd will accept the peer's idea of its (remote) IP
266 address, even if the remote IP address was specified in an option.
268 .B ipcp-max-configure \fIn
269 Set the maximum number of IPCP configure-request transmissions to
270 \fIn\fR (default 10).
272 .B ipcp-max-failure \fIn
273 Set the maximum number of IPCP configure-NAKs returned before starting
274 to send configure-Rejects instead to \fIn\fR (default 10).
276 .B ipcp-max-terminate \fIn
277 Set the maximum number of IPCP terminate-request transmissions to
281 Set the IPCP restart interval (retransmission timeout) to \fIn\fR
285 Provides an extra parameter to the ip-up and ip-down scripts. If this
286 option is given, the \fIstring\fR supplied is given as the 6th
287 parameter to those scripts.
290 Enable the IPXCP and IPX protocols. This option is presently only
291 supported under Linux, and only if your kernel has been configured to
295 Set the IPX network number in the IPXCP configure request frame to
296 \fIn\fR, a hexadecimal number (without a leading 0x). There is no
297 valid default. If this option is not specified, the network number is
298 obtained from the peer. If the peer does not have the network number,
299 the IPX protocol will not be started.
301 .B ipx-node \fIn\fB:\fIm
302 Set the IPX node numbers. The two node numbers are separated from each
303 other with a colon character. The first number \fIn\fR is the local
304 node number. The second number \fIm\fR is the peer's node number. Each
305 node number is a hexadecimal number, at most 10 digits long. The node
306 numbers on the ipx-network must be unique. There is no valid
307 default. If this option is not specified then the node numbers are
308 obtained from the peer.
310 .B ipx-router-name \fI<string>
311 Set the name of the router. This is a string and is sent to the peer
315 Set the routing protocol to be received by this option. More than one
316 instance of \fIipx-routing\fR may be specified. The '\fInone\fR'
317 option (0) may be specified as the only instance of ipx-routing. The
318 values may be \fI0\fR for \fINONE\fR, \fI2\fR for \fIRIP/SAP\fR, and
319 \fI4\fR for \fINLSP\fR.
321 .B ipxcp-accept-local
322 Accept the peer's NAK for the node number specified in the ipx-node
323 option. If a node number was specified, and non-zero, the default is
324 to insist that the value be used. If you include this option then you
325 will permit the peer to override the entry of the node number.
327 .B ipxcp-accept-network
328 Accept the peer's NAK for the network number specified in the
329 ipx-network option. If a network number was specified, and non-zero, the
330 default is to insist that the value be used. If you include this
331 option then you will permit the peer to override the entry of the node
334 .B ipxcp-accept-remote
335 Use the peer's network number specified in the configure request
336 frame. If a node number was specified for the peer and this option was
337 not specified, the peer will be forced to use the value which you have
340 .B ipxcp-max-configure \fIn
341 Set the maximum number of IPXCP configure request frames which the
342 system will send to \fIn\fR. The default is 10.
344 .B ipxcp-max-failure \fIn
345 Set the maximum number of IPXCP NAK frames which the local system will
346 send before it rejects the options. The default value is 3.
348 .B ipxcp-max-terminate \fIn
349 Set the maximum nuber of IPXCP terminate request frames before the
350 local system considers that the peer is not listening to them. The
354 Enable debugging code in the kernel-level PPP driver. The argument
355 \fIn\fR is a number which is the sum of the following values: 1 to
356 enable general debug messages, 2 to request that the contents of
357 received packets be printed, and 4 to request that the contents of
358 transmitted packets be printed. On most systems, messages printed by
359 the kernel are logged by syslog(1) to a file as directed in the
360 /etc/syslog.conf configuration file.
362 .B lcp-echo-failure \fIn
363 If this option is given, pppd will presume the peer to be dead
364 if \fIn\fR LCP echo-requests are sent without receiving a valid LCP
365 echo-reply. If this happens, pppd will terminate the
366 connection. Use of this option requires a non-zero value for the
367 \fIlcp-echo-interval\fR parameter. This option can be used to enable
368 pppd to terminate after the physical connection has been broken
369 (e.g., the modem has hung up) in situations where no hardware modem
370 control lines are available.
372 .B lcp-echo-interval \fIn
373 If this option is given, pppd will send an LCP echo-request frame to
374 the peer every \fIn\fR seconds. Normally the peer should respond to
375 the echo-request by sending an echo-reply. This option can be used
376 with the \fIlcp-echo-failure\fR option to detect that the peer is no
379 .B lcp-max-configure \fIn
380 Set the maximum number of LCP configure-request transmissions to
381 \fIn\fR (default 10).
383 .B lcp-max-failure \fIn
384 Set the maximum number of LCP configure-NAKs returned before starting
385 to send configure-Rejects instead to \fIn\fR (default 10).
387 .B lcp-max-terminate \fIn
388 Set the maximum number of LCP terminate-request transmissions to
392 Set the LCP restart interval (retransmission timeout) to \fIn\fR
396 Don't use the modem control lines. With this option, pppd will ignore
397 the state of the CD (Carrier Detect) signal from the modem and will
398 not change the state of the DTR (Data Terminal Ready) signal.
401 Use the system password database for authenticating the peer using
402 PAP, and record the user in the system wtmp file. Note that the peer
403 must have an entry in the /etc/ppp/pap-secrets file as well as the
404 system password database to be allowed access.
407 Terminate the connection when it has been available for network
408 traffic for \fIn\fR seconds (i.e. \fIn\fR seconds after the first
409 network control protocol comes up).
412 Use the modem control lines. This option is the default. With this
413 option, pppd will wait for the CD (Carrier Detect) signal from the
414 modem to be asserted when opening the serial device (unless a connect
415 script is specified), and it will drop the DTR (Data Terminal Ready)
416 signal briefly when the connection is terminated and before executing
417 the connect script. On Ultrix, this option implies hardware flow
418 control, as for the \fIcrtscts\fR option.
421 If pppd is acting as a server for Microsoft Windows clients, this
422 option allows pppd to supply one or two DNS (Domain Name Server)
423 addresses to the clients. The first instance of this option specifies
424 the primary DNS address; the second instance (if given) specifies the
425 secondary DNS address. (This option was present in some older
426 versions of pppd under the name \fBdns-addr\fR.)
429 If pppd is acting as a server for Microsoft Windows or "Samba"
430 clients, this option allows pppd to supply one or two WINS (Windows
431 Internet Name Services) server addresses to the clients. The first
432 instance of this option specifies the primary WINS address; the second
433 instance (if given) specifies the secondary WINS address.
436 Set the name of the local system for authentication purposes to
437 \fIname\fR. This is a privileged option. With this option, pppd will
438 use lines in the secrets files which have \fIname\fR as the second
439 field when looking for a secret to use in authenticating the peer. In
440 addition, unless overridden with the \fIuser\fR option, \fIname\fR
441 will be used as the name to send to the peer when authenticating the
442 local system to the peer. (Note that pppd does not append the domain
446 Set the interface netmask to \fIn\fR, a 32 bit netmask in "decimal dot"
447 notation (e.g. 255.255.255.0). If this option is given, the value
448 specified is ORed with the default netmask. The default netmask is
449 chosen based on the negotiated remote IP address; it is the
450 appropriate network mask for the class of the remote IP address, ORed
451 with the netmasks for any non point-to-point network interfaces in the
452 system which are on the same network.
455 Disable Address/Control compression in both directions (send and
459 Do not require the peer to authenticate itself. This option is
460 privileged if the \fIauth\fR option is specified in /etc/ppp/options.
463 Disables BSD-Compress compression; \fBpppd\fR will not request or
464 agree to compress packets using the BSD-Compress scheme.
467 Disable CCP (Compression Control Protocol) negotiation. This option
468 should only be required if the peer is buggy and gets confused by
469 requests from pppd for CCP negotiation.
472 Disable hardware flow control (i.e. RTS/CTS) on the serial port. If
473 neither the \fIcrtscts\fR nor the \fInocrtscts\fR option is given,
474 the hardware flow control setting for the serial port is left
478 Disable the \fIdefaultroute\fR option. The system administrator who
479 wishes to prevent users from creating default routes with pppd
480 can do so by placing this option in the /etc/ppp/options file.
483 Disables Deflate compression; pppd will not request or agree to
484 compress packets using the Deflate scheme.
487 Don't detach from the controlling terminal. Without this option, if a
488 serial device other than the terminal on the standard input is
489 specified, pppd will fork to become a background process.
492 Disable IPCP negotiation and IP communication. This option should
493 only be required if the peer is buggy and gets confused by requests
494 from pppd for IPCP negotiation.
497 Disables the default behaviour when no local IP address is specified,
498 which is to determine (if possible) the local IP address from the
499 hostname. With this option, the peer will have to supply the local IP
500 address during IPCP negotiation (unless it specified explicitly on the
501 command line or in an options file).
504 Disable the IPXCP and IPX protocols. This option should only be
505 required if the peer is buggy and gets confused by requests from pppd
506 for IPXCP negotiation.
509 Disable magic number negotiation. With this option, pppd cannot
510 detect a looped-back line. This option should only be needed if the
514 Disable protocol field compression negotiation in both the receive and
515 the transmit direction.
518 Exit once a connection has been made and terminated. This is the
519 default unless the \fIpersist\fR or \fIdemand\fR option has been
523 Do not accept or agree to Predictor-1 comprssion.
526 Disable the \fIproxyarp\fR option. The system administrator who
527 wishes to prevent users from creating proxy ARP entries with pppd can
528 do so by placing this option in the /etc/ppp/options file.
531 Disable Van Jacobson style TCP/IP header compression in both the
532 transmit and the receive direction.
535 Disable the connection-ID compression option in Van Jacobson style
536 TCP/IP header compression. With this option, pppd will not omit the
537 connection-ID byte from Van Jacobson compressed TCP/IP headers, nor
538 ask the peer to do so.
541 Indicates that all secrets in the /etc/ppp/pap-secrets file which are
542 used for checking the identity of the peer are encrypted, and thus
543 pppd should not accept a password which, before encryption, is
544 identical to the secret from the /etc/ppp/pap-secrets file.
546 .B pap-max-authreq \fIn
547 Set the maximum number of PAP authenticate-request transmissions to
548 \fIn\fR (default 10).
551 Set the PAP restart interval (retransmission timeout) to \fIn\fR
555 Set the maximum time that pppd will wait for the peer to authenticate
556 itself with PAP to \fIn\fR seconds (0 means no limit).
558 .B pass-filter \fIfilter-expression
559 Specifies a packet filter to applied to data packets being sent or
560 received to determine which packets should be allowed to pass.
561 Packets which are rejected by the filter are silently discarded. This
562 option can be used to prevent specific network daemons (such as
563 routed) using up link bandwidth, or to provide a basic firewall
565 The \fIfilter-expression\fR syntax is as described for tcpdump(1),
566 except that qualifiers which are inappropriate for a PPP link, such as
567 \fBether\fR and \fBarp\fR, are not permitted. Generally the filter
568 expression should be enclosed in single-quotes to prevent whitespace
569 in the expression from being interpreted by the shell. Note that it
570 is possible to apply different constraints to incoming and outgoing
571 packets using the \fBinbound\fR and \fBoutbound\fR qualifiers. This
572 option is currently only available under NetBSD, and then only if both
573 the kernel and pppd were compiled with PPP_FILTER defined.
576 Do not exit after a connection is terminated; instead try to reopen
580 Request that the peer compress frames that it sends using Predictor-1
581 compression, and agree to compress transmitted frames with Predictor-1
582 if requested. This option has no effect unless the kernel driver
583 supports Predictor-1 compression.
586 Add an entry to this system's ARP [Address Resolution Protocol] table
587 with the IP address of the peer and the Ethernet address of this
588 system. This will have the effect of making the peer appear to other
589 systems to be on the local ethernet.
591 .B remotename \fIname
592 Set the assumed name of the remote system for authentication purposes
596 With this option, pppd will not agree to authenticate itself to the
600 With this option, pppd will not agree to authenticate itself to the
604 Require the peer to authenticate itself using CHAP [Challenge
605 Handshake Authentication Protocol] authentication.
608 Require the peer to authenticate itself using PAP [Password
609 Authentication Protocol] authentication.
612 With this option, pppd will not transmit LCP packets to initiate a
613 connection until a valid LCP packet is received from the peer (as for
614 the `passive' option with ancient versions of pppd).
617 Enforce the use of the hostname (with domain name appended, if given)
618 as the name of the local system for authentication purposes (overrides
619 the \fIname\fR option).
622 Sets the name used for authenticating the local system to the peer to
626 Sets the number of connection slots to be used by the Van Jacobson
627 TCP/IP header compression and decompression code to \fIn\fR, which
628 must be between 2 and 16 (inclusive).
631 Run the executable or shell command specified by \fIscript\fR before
632 initiating PPP negotiation, after the connect script (if any) has
633 completed. This option is privileged if the \fInoauth\fR option is
637 Use software flow control (i.e. XON/XOFF) to control the flow of data on
640 Options can be taken from files as well as the command line. Pppd
641 reads options from the files /etc/ppp/options, ~/.ppprc and
642 /etc/ppp/options.\fIttyname\fR (in that order) before processing the
643 options on the command line. (In fact, the command-line options are
644 scanned to find the terminal name before the options.\fIttyname\fR
645 file is read.) In forming the name of the options.\fIttyname\fR file,
646 the initial /dev/ is removed from the terminal name, and any remaining
647 / characters are replaced with dots.
649 An options file is parsed into a series of words, delimited by
650 whitespace. Whitespace can be included in a word by enclosing the
651 word in quotes ("). A backslash (\\) quotes the following character.
652 A hash (#) starts a comment, which continues until the end of the
653 line. There is no restriction on using the \fIfile\fR or \fIcall\fR
654 options within an options file.
657 provides system administrators with sufficient access control that PPP
658 access to a server machine can be provided to legitimate users without
659 fear of compromising the security of the server or the network it's
660 on. In part this is provided by the /etc/ppp/options file, where the
661 administrator can place options to restrict the ways in which pppd can
662 be used, and in part by the PAP and CHAP secrets files, where the
663 administrator can restrict the set of IP addresses which individual
666 The normal way that pppd should be set up is to have the \fIauth\fR
667 option in the /etc/ppp/options file. (This may become the default in
668 later releases.) If users wish to use pppd to dial out to a peer
669 which will refuse to authenticate itself (such as an internet service
670 provider), the system administrator should create an options file
671 under /etc/ppp/peers containing the \fInoauth\fR option, the name of
672 the serial port to use, and the \fIconnect\fR option (if required),
673 plus any other appropriate options. In this way, pppd can be set up
674 to allow non-privileged users to make unauthenticated connections only
677 As indicated above, some security-sensitive options are privileged,
678 which means that they may not be used by an ordinary non-privileged
679 user running a setuid-root pppd, either on the command line, in the
680 user's ~/.ppprc file, or in an options file read using the \fIfile\fR
681 option. Privileged options may be used in /etc/ppp/options file or in
682 an options file read using the \fIcall\fR option. If pppd is being
683 run by the root user, privileged options can be used without
686 Authentication is the process whereby one peer convinces the other of
687 its identity. This involves the first peer sending its name to the
688 other, together with some kind of secret information which could only
689 come from the genuine authorized user of that name. In such an
690 exchange, we will call the first peer the "client" and the other the
691 "server". The client has a name by which it identifies itself to the
692 server, and the server also has a name by which it identifies itself
693 to the client. Generally the genuine client shares some secret (or
694 password) with the server, and authenticates itself by proving that it
695 knows that secret. Very often, the names used for authentication
696 correspond to the internet hostnames of the peers, but this is not
699 At present, pppd supports two authentication protocols: the Password
700 Authentication Protocol (PAP) and the Challenge Handshake
701 Authentication Protocol (CHAP). PAP involves the client sending its
702 name and a cleartext password to the server to authenticate itself.
703 In contrast, the server initiates the CHAP authentication exchange by
704 sending a challenge to the client (the challenge packet includes the
705 server's name). The client must respond with a response which
706 includes its name plus a hash value derived from the shared secret and
707 the challenge, in order to prove that it knows the secret.
709 The PPP protocol, being symmetrical, allows both peers to require the
710 other to authenticate itself. In that case, two separate and
711 independent authentication exchanges will occur. The two exchanges
712 could use different authentication protocols, and in principle,
713 different names could be used in the two exchanges.
715 The default behaviour of pppd is to agree to authenticate if
716 requested, and to not require authentication from the peer. However,
717 pppd will not agree to authenticate itself with a particular protocol
718 if it has no secrets which could be used to do so.
720 Pppd stores secrets for use in authentication in secrets
721 files (/etc/ppp/pap-secrets for PAP, /etc/ppp/chap-secrets for CHAP).
722 Both secrets files have the same format. The secrets files can
723 contain secrets for pppd to use in authenticating itself to other
724 systems, as well as secrets for pppd to use when authenticating other
727 Each line in a secrets file contains one secret. A given secret is
728 specific to a particular combination of client and server - it can
729 only be used by that client to authenticate itself to that server.
730 Thus each line in a secrets file has at least 3 fields: the name of
731 the client, the name of the server, and the secret. These fields may
732 be followed by a list of the IP addresses that the specified client
733 may use when connecting to the specified server.
735 A secrets file is parsed into words as for a options file, so the
736 client name, server name and secrets fields must each be one word,
737 with any embedded spaces or other special characters quoted or
738 escaped. Any following words on the same line are taken to be a list
739 of acceptable IP addresses for that client. If there are only 3 words
740 on the line, or if the first word is "-", then all IP addresses are
741 disallowed. To allow any address, use "*".
742 A word starting with "!" indicates that the
743 specified address is \fInot\fR acceptable. An address may be followed
744 by "/" and a number \fIn\fR, to indicate a whole subnet, i.e. all
745 addresses which have the same value in the most significant \fIn\fR
746 bits. Note that case is significant in the client and server names
749 If the secret starts with an `@', what follows is assumed to be the
750 name of a file from which to read the secret. A "*" as the client or
751 server name matches any name. When selecting a secret, pppd takes the
752 best match, i.e. the match with the fewest wildcards.
754 Thus a secrets file contains both secrets for use in authenticating
755 other hosts, plus secrets which we use for authenticating ourselves to
756 others. When pppd is authenticating the peer (checking the peer's
757 identity), it chooses a secret with the peer's name in the first
758 field and the name of the local system in the second field. The
759 name of the local system defaults to the hostname, with the domain
760 name appended if the \fIdomain\fR option is used. This default can be
761 overridden with the \fIname\fR option, except when the
762 \fIusehostname\fR option is used.
764 When pppd is choosing a secret to use in authenticating itself to the
765 peer, it first determines what name it is going to use to identify
766 itself to the peer. This name can be specified by the user with the
767 \fIuser\fR option. If this option is not used, the name defaults to
768 the name of the local system, determined as described in the previous
769 paragraph. Then pppd looks for a secret with this name in the first
770 field and the peer's name in the second field. Pppd will know the
771 name of the peer if CHAP authentication is being used, because the
772 peer will have sent it in the challenge packet. However, if PAP is being
773 used, pppd will have to determine the peer's name from the options
774 specified by the user. The user can specify the peer's name directly
775 with the \fIremotename\fR option. Otherwise, if the remote IP address
776 was specified by a name (rather than in numeric form), that name will
777 be used as the peer's name. Failing that, pppd will use the null
778 string as the peer's name.
780 When authenticating the peer with PAP, the supplied password is first
781 compared with the secret from the secrets file. If the password
782 doesn't match the secret, the password is encrypted using crypt() and
783 checked against the secret again. Thus secrets for authenticating the
784 peer can be stored in encrypted form if desired. If the
785 \fIpapcrypt\fR option is given, the first (unencrypted) comparison is
786 omitted, for better security.
788 Furthermore, if the \fIlogin\fR option was specified, the username and
789 password are also checked against the system password database. Thus,
790 the system administrator can set up the pap-secrets file to allow PPP
791 access only to certain users, and to restrict the set of IP addresses
792 that each user can use. Typically, when using the \fIlogin\fR option,
793 the secret in /etc/ppp/pap-secrets would be "", which will match any
794 password supplied by the peer. This avoids the need to have the same
795 secret in two places.
797 Authentication must be satisfactorily completed before IPCP (or any
798 other Network Control Protocol) can be started. If the peer is
799 required to authenticate itself, and fails to do so, pppd will
800 terminated the link (by closing LCP). If IPCP negotiates an
801 unacceptable IP address for the remote host, IPCP will be closed. IP
802 packets can only be sent or received when IPCP is open.
804 In some cases it is desirable to allow some hosts which can't
805 authenticate themselves to connect and use one of a restricted set of
806 IP addresses, even when the local host generally requires
807 authentication. If the peer refuses to authenticate itself when
808 requested, pppd takes that as equivalent to authenticating with PAP
809 using the empty string for the username and password. Thus, by adding
810 a line to the pap-secrets file which specifies the empty string for
811 the client and password, it is possible to allow restricted access to
812 hosts which refuse to authenticate themselves.
815 When IPCP negotiation is completed successfully, pppd will inform the
816 kernel of the local and remote IP addresses for the ppp interface.
817 This is sufficient to create a host route to the remote end of the
818 link, which will enable the peers to exchange IP packets.
819 Communication with other machines generally requires further
820 modification to routing tables and/or ARP (Address Resolution
821 Protocol) tables. In most cases the \fIdefaultroute\fR and/or
822 \fIproxyarp\fR options are sufficient for this, but in some cases
823 further intervention is required. The /etc/ppp/ip-up script can be
826 Sometimes it is desirable to add a default route through the remote
827 host, as in the case of a machine whose only connection to the
828 Internet is through the ppp interface. The \fIdefaultroute\fR option
829 causes pppd to create such a default route when IPCP comes up, and
830 delete it when the link is terminated.
832 In some cases it is desirable to use proxy ARP, for example on a
833 server machine connected to a LAN, in order to allow other hosts to
834 communicate with the remote host. The \fIproxyarp\fR option causes
835 pppd to look for a network interface on the same subnet as the remote
836 host (an interface supporting broadcast and ARP, which is up and not a
837 point-to-point or loopback interface). If found, pppd creates a
838 permanent, published ARP entry with the IP address of the remote host
839 and the hardware address of the network interface found.
841 When the \fIdemand\fR option is used, the interface IP addresses have
842 already been set at the point when IPCP comes up. If pppd has not
843 been able to negotiate the same addresses that it used to configure
844 the interface (for example when the peer is an ISP that uses dynamic
845 IP address assignment), pppd has to change the interface IP addresses
846 to the negotiated addresses. This may disrupt existing connections,
847 and the use of demand dialling with peers that do dynamic IP address
848 assignment is not recommended.
851 The following examples assume that the /etc/ppp/options file contains
852 the \fIauth\fR option (as in the default /etc/ppp/options file in the
855 Probably the most common use of pppd is to dial out to an ISP. This
856 can be done with a command such as
860 where the /etc/ppp/peers/isp file is set up by the system
861 administrator to contain something like this:
865 connect '/usr/sbin/chat -v -f /etc/ppp/chat-isp'
869 In this example, we are using chat to dial the ISP's modem and go
870 through any logon sequence required. The /etc/ppp/chat-isp file
871 contains the script used by chat; it could for example contain
884 ABORT "Username/Password Incorrect"
894 "word:" "\\qmypassword"
900 See the chat(8) man page for details of chat scripts.
902 Pppd can also be used to provide a dial-in ppp service for users. If
903 the users already have login accounts, the simplest way to set up the
904 ppp service is to let the users log in to their accounts and run pppd
905 (installed setuid-root) with a command such as
909 To allow a user to use the PPP facilities, you need to allocate an IP
910 address for that user's machine and create an entry in
911 /etc/ppp/pap-secrets or /etc/ppp/chap-secrets (depending on which
912 authentication method the PPP implementation on the user's machine
913 supports), so that the user's
914 machine can authenticate itself. For example, if Joe has a machine
915 called "joespc" which is to be allowed to dial in to the machine
916 called "server" and use the IP address joespc.my.net, you would add an
917 entry like this to /etc/ppp/pap-secrets or /etc/ppp/chap-secrets:
919 joespc server "joe's secret" joespc.my.net
921 Alternatively, you can create a username called (for example) "ppp",
922 whose login shell is pppd and whose home directory is /etc/ppp.
923 Options to be used when pppd is run this way can be put in
926 If your serial connection is any more complicated than a piece of
927 wire, you may need to arrange for some control characters to be
928 escaped. In particular, it is often useful to escape XON (^Q) and
929 XOFF (^S), using \fIasyncmap a0000\fR. If the path includes a telnet,
930 you probably should escape ^] as well (\fIasyncmap 200a0000\fR). If
931 the path includes an rlogin, you will need to use the \fIescape ff\fR
932 option on the end which is running the rlogin client, since many
933 rlogin implementations are not transparent; they will remove the
934 sequence [0xff, 0xff, 0x73, 0x73, followed by any 8 bytes] from the
938 Messages are sent to the syslog daemon using facility LOG_DAEMON.
939 (This can be overriden by recompiling pppd with the macro
940 LOG_PPP defined as the desired facility.) In order to see the error
941 and debug messages, you will need to edit your /etc/syslog.conf file
942 to direct the messages to the desired output device or file.
944 The \fIdebug\fR option causes the contents of all control packets sent
945 or received to be logged, that is, all LCP, PAP, CHAP or IPCP packets.
946 This can be useful if the PPP negotiation does not succeed or if
947 authentication fails.
948 If debugging is enabled at compile time, the \fIdebug\fR option also
949 causes other debugging messages to be logged.
951 Debugging can also be enabled or disabled by sending a SIGUSR1 signal
952 to the pppd process. This signal acts as a toggle.
955 .B /var/run/ppp\fIn\fB.pid \fR(BSD or Linux), \fB/etc/ppp/ppp\fIn\fB.pid \fR(others)
956 Process-ID for pppd process on ppp interface unit \fIn\fR.
959 A program or script which is executed after the remote system
960 successfully authenticates itself. It is executed with the parameters
962 \fIinterface-name peer-name user-name tty-device speed\fR
964 and with its standard input, output and error redirected to
965 /dev/null. This program or script is executed with the real and
966 effective user-IDs set to root, and with an empty environment. (Note
967 that this script is not executed if the peer doesn't authenticate
968 itself, for example when the \fInoauth\fR option is used.)
970 .B /etc/ppp/auth-down
971 A program or script which is executed when the link goes down, if
972 /etc/ppp/auth-up was previously executed. It is executed in the same
973 manner with the same parameters as /etc/ppp/auth-up.
976 A program or script which is executed when the link is available for
977 sending and receiving IP packets (that is, IPCP has come up). It is
978 executed with the parameters
980 \fIinterface-name tty-device speed local-IP-address
981 remote-IP-address ipparam\fR
983 and with its standard input,
984 output and error streams redirected to /dev/null.
986 This program or script is executed with the real and effective
987 user-IDs set to root. This is so that it can be used to manipulate
988 routes, run privileged daemons (e.g. \fIsendmail\fR), etc. Be
989 careful that the contents of the /etc/ppp/ip-up and /etc/ppp/ip-down
990 scripts do not compromise your system's security.
992 This program or script is executed with an empty environment, so you
993 must either specify a PATH or use full pathnames.
996 A program or script which is executed when the link is no longer
997 available for sending and receiving IP packets. This script can be
998 used for undoing the effects of the /etc/ppp/ip-up script. It is
999 invoked in the same manner and with the same parameters as the ip-up
1000 script, and the same security considerations apply.
1003 A program or script which is executed when the link is available for
1004 sending and receiving IPX packets (that is, IPXCP has come up). It is
1005 executed with the parameters
1007 \fIinterface-name tty-device speed network-number local-IPX-node-address
1008 remote-IPX-node-address local-IPX-routing-protocol remote-IPX-routing-protocol
1009 local-IPX-router-name remote-IPX-router-name ipparam pppd-pid\fR
1011 and with its standard input,
1012 output and error streams redirected to /dev/null.
1015 The local-IPX-routing-protocol and remote-IPX-routing-protocol field
1016 may be one of the following:
1018 NONE to indicate that there is no routing protocol
1020 RIP to indicate that RIP/SAP should be used
1022 NLSP to indicate that Novell NLSP should be used
1024 RIP NLSP to indicate that both RIP/SAP and NLSP should be used
1027 This program or script is executed with the real and effective
1028 user-IDs set to root, and with an empty environment. This is so
1029 that it can be used to manipulate routes, run privileged daemons (e.g.
1030 \fIripd\fR), etc. Be careful that the contents of the /etc/ppp/ipx-up
1031 and /etc/ppp/ipx-down scripts do not compromise your system's
1034 .B /etc/ppp/ipx-down
1035 A program or script which is executed when the link is no longer
1036 available for sending and receiving IPX packets. This script can be
1037 used for undoing the effects of the /etc/ppp/ipx-up script. It is
1038 invoked in the same manner and with the same parameters as the ipx-up
1039 script, and the same security considerations apply.
1041 .B /etc/ppp/pap-secrets
1042 Usernames, passwords and IP addresses for PAP authentication. This
1043 file should be owned by root and not readable or writable by any other
1044 user. Pppd will log a warning if this is not the case.
1046 .B /etc/ppp/chap-secrets
1047 Names, secrets and IP addresses for CHAP authentication. As for
1048 /etc/ppp/pap-secrets, this file should be owned by root and not
1049 readable or writable by any other user. Pppd will log a warning if
1050 this is not the case.
1053 System default options for pppd, read before user default options or
1054 command-line options.
1057 User default options, read before /etc/ppp/options.\fIttyname\fR.
1059 .B /etc/ppp/options.\fIttyname
1060 System default options for the serial port being used, read after
1061 ~/.ppprc. In forming the \fIttyname\fR part of this
1062 filename, an initial /dev/ is stripped from the port name (if
1063 present), and any slashes in the remaining part are converted to
1067 A directory containing options files which may contain privileged
1068 options, even if pppd was invoked by a user other than root. The
1069 system administrator can create options files in this directory to
1070 permit non-privileged users to dial out without requiring the peer to
1071 authenticate, but only to certain trusted peers.
1076 \fICompressing TCP/IP headers for low-speed serial links.\fR
1081 .I The MD5 Message-Digest Algorithm.
1086 .I PPP Internet Protocol Control Protocol (IPCP).
1090 Lloyd, B.; Simpson, W.A.
1091 .I PPP authentication protocols.
1096 .I The Point\-to\-Point Protocol (PPP).
1101 .I PPP in HDLC-like Framing.
1104 The following signals have the specified effect when sent to pppd.
1107 These signals cause pppd to terminate the link (by closing LCP),
1108 restore the serial device settings, and exit.
1111 This signal causes pppd to terminate the link, restore the serial
1112 device settings, and close the serial device. If the \fIpersist\fR or
1113 \fIdemand\fR option has been specified, pppd will try to reopen the
1114 serial device and start another connection (after the holdoff period).
1115 Otherwise pppd will exit. If this signal is received during the
1116 holdoff period, it causes pppd to end the holdoff period immediately.
1119 This signal toggles the state of the \fIdebug\fR option.
1122 This signal causes pppd to renegotiate compression. This can be
1123 useful to re-enable compression after it has been disabled as a result
1124 of a fatal decompression error. (Fatal decompression errors generally
1125 indicate a bug in one or other implementation.)
1128 Paul Mackerras (Paul.Mackerras@cs.anu.edu.au), based on earlier work by
projects / ppp.git / blob