1 PPPD(1M) Maintenance Commands PPPD(1M)
2
3 NAME
4 pppd - point to point protocol daemon
5
6 SYNOPSIS
7 pppd [tty_name] [speed] [options]
8
9
10 DESCRIPTION
11 The point-to-point protocol (PPP) provides a method for transmitting
12 datagrams over serial point-to-point links. PPP is composed of three
13 components: a facility for encapsulating datagrams over serial links,
14 an extensible link control protocol (LCP), and a family of network
15 control protocols (NCP) for establishing and configuring different
16 network-layer protocols.
17
18
19 The encapsulation scheme is provided by driver code in the kernel. pppd
20 provides the basic LCP authentication support and several NCPs for
21 establishing and configuring the Internet Protocol (referred to as the
22 IP Control Protocol or "IPCP") and IPv6 (IPV6CP).
23
24 OPTIONS
25 The following sections discuss the pppd options:
26
27 Options Files
28 Options are taken from files and the command line. pppd reads options
29 from the files /etc/ppp/options, $HOME/.ppprc and
30 /etc/ppp/options.ttyname (in that order) before processing the options
31 on the command line. (Command-line options are scanned for the terminal
32 name before the options.ttyname file is read.) To form the name of the
33 options.ttyname file, the initial /dev/ is removed from the terminal
34 name, and any remaining forward slash characters (/) are replaced with
35 dots. For example, with serial device /dev/cua/a, option file
36 /etc/ppp/options.cua.a is read.
37
38
39 An options file is parsed into a series of words that are delimited by
40 whitespace. Whitespace can be included in a word by enclosing the word
41 in double-quotes ("). A backslash (\) quotes the succeeding character.
42 A hash (#) starts a comment, which continues until the end of the line.
43 There is no restriction on using the file or call options within an
44 options file.
45
46 Frequently Used Options
47 <tty_name>
48 Communicate over the named device. The string
49 /dev/ is prepended if necessary. If no device
50 name is given, or if the name of the terminal
51 connected to the standard input is given, pppd
52 uses that terminal and does not fork to put
53 itself in the background. A value for this
54 option from a privileged source cannot be
55 overridden by a non-privileged user.
56
57
58 <speed>
59 Set the baud rate to <speed> (a decimal number).
60 The default is to leave the baud rate unchanged.
61 This option is normally needed for dial-out
62 only.
63
64
65 asyncmap <map>
66 Set the async character map to <map>. The map
67 describes which control characters cannot be
68 successfully received over the serial line.
69 pppd asks the peer to send these characters as a
70 2-byte escape sequence. The argument is a 32
71 bit hex number, with each bit representing a
72 character to escape. Bit 0 (00000001) represents
73 the character 0x00; bit 31 (80000000) represents
74 the character 0x1f or ^_. If multiple asyncmap
75 options are given, the values are ORed together.
76 If no asyncmap option is given, pppd attempts to
77 negotiate a value of 0. If the peer agrees, this
78 disables escaping of the standard control
79 characters. Use the default-asyncmap option to
80 disable negotiation and escape all control
81 characters.
82
83
84 auth
85 Require the peer to authenticate itself before
86 allowing network packets to be sent or received.
87 This option is the default if the system has a
88 default route. If the auth or the noauth option
89 is not specified, pppd allows the peer to use
90 only those IP addresses to which the system does
91 not already have a route.
92
93
94 call name
95 Read options from the file /etc/ppp/peers/name.
96 This file may contain privileged options,
97 including noauth, even if pppd is not being run
98 by root. The name string may not begin with a
99 slash ("/") or include consecutive periods
100 ("..") as a pathname component.
101
102
103 callback number
104 Request a callback to the given telephone number
105 using Microsoft CBCP.
106
107
108 connect script
109 Use the executable or shell command specified by
110 script to set up the serial line. This script
111 would typically use the chat(1M) program to dial
112 the modem and start the remote PPP session. A
113 value for this option originating from a
114 privileged source cannot be overridden by a non-
115 privileged user.
116
117
118 crtscts
119 Use hardware flow control, that is, RTS/CTS, to
120 control the flow of data on the serial port. If
121 the crtscts, nocrtscts, cdtrcts or nocdtrcts
122 option is not provided, the hardware flow
123 control setting for the serial port is left
124 unchanged. Some serial ports lack a true RTS
125 output and use this mode to implement
126 unidirectional flow control. The serial port
127 suspends transmission when requested by the
128 modem by means of CTS but cannot request the
129 modem to stop sending to the computer. This mode
130 allows the use of DTR as a modem control line.
131
132
133 defaultroute
134 Add a default route to the system routing tables
135 when IPCP negotiation successfully completes,
136 using the peer as the gateway. This entry is
137 removed when the PPP connection is broken. This
138 option is privileged if the nodefaultroute
139 option is specified.
140
141
142 disconnect script
143 Run the executable or shell command specified by
144 script after pppd terminates the link.
145 Typically, this script is used to command the
146 modem to hang up if hardware modem control
147 signals are not available. disconnect is not run
148 if the modem has already hung up. A value for
149 this option originating from a privileged source
150 cannot be overridden by a non-privileged user.
151
152
153 escape xx,yy,...
154 Specifies that certain characters be escaped on
155 transmission regardless of whether the peer
156 requests them to be escaped with its async
157 control character map. The characters to be
158 escaped are specified as a list of hex numbers
159 separated by commas. Note that almost any
160 character can be specified for the escape
161 option, unlike the asyncmap option which allows
162 only control characters to be specified.
163 Characters that cannot be escaped are those
164 containing hex values 0x20 through 0x3f and
165 0x5e.
166
167
168 file name
169 Read options from file name. If this option is
170 used on the command line or in $HOME/.ppprc, the
171 file must be readable by the user invoking pppd.
172 See for a list of files that pppd always reads,
173 regardless of the use of this option.
174
175
176 init script
177 Run the executable or shell command specified by
178 script to initialize the serial line. This
179 script would typically use the chat(1M) program
180 to configure the modem to enable auto-answer. A
181 value for this option from a privileged source
182 cannot be overridden by a non-privileged user.
183
184
185 lock
186 Directs pppd to create a UUCP-style lock file
187 for the serial device to ensure exclusive access
188 to the device.
189
190
191 mru n
192 Set the Maximum Receive Unit (MRU) value to n.
193 pppd asks the peer to send packets of no more
194 than n bytes. Minimum MRU value is 128. Default
195 MRU value is 1500. A value of 296 is recommended
196 for slow links (40 bytes for TCP/IP header + 256
197 bytes of data). For IPv6, MRU must be at least
198 1280.
199
200
201 mtu n
202 Set the Maximum Transmit Unit (MTU) value to n.
203 Unless the peer requests a smaller value via MRU
204 negotiation, pppd requests the kernel networking
205 code to send data packets of no more than n
206 bytes through the PPP network interface. For
207 IPv6, MTU must be at least 1280.
208
209
210 passive
211 Enables the "passive" option in the LCP. With
212 this option, pppd attempts to initiate a
213 connection; if no reply is received from the
214 peer, pppd waits passively for a valid LCP
215 packet instead of exiting, as it would without
216 this option.
217
218
219 Options
220 <local_IP_address>:<remote_IP_address>
221
222 Set the local and/or remote interface IP addresses. Either one may
223 be omitted, but the colon is required. The IP addresses are
224 specified with a host name or in decimal dot notation, for example:
225 :10.1.2.3. The default local address is the first IP address of the
226 system unless the noipdefault option is provided. The remote
227 address is obtained from the peer if not specified in any option.
228 Thus, in simple cases, this option is not required. If a local
229 and/or remote IP address is specified with this option, pppd will
230 not accept a different value from the peer in the IPCP negotiation
231 unless the ipcp-accept-local and/or ipcp-accept-remote options are
232 given, respectively.
233
234
235 allow-fcs fcs-type
236
237 Set allowable FCS type(s) for data sent to the peer. The fcs-type
238 is a comma-separated list of "crc16", "crc32", "null", or integers.
239 By default, all known types are allowed. If this option is
240 specified and the peer requests a type not listed, a LCP Configure-
241 Nak is sent to request only the listed types.
242
243
244 allow-ip address(es)
245
246 Allow peers to use the given IP address or subnet without
247 authenticating themselves. The parameter is parsed in the same
248 manner as each element of the list of allowed IP addresses is
249 parsed in the secrets files. See the section more more details.
250
251
252 bsdcomp nr,nt
253
254 Request that the peer compress packets that it sends using the BSD-
255 Compress scheme, with a maximum code size of nr bits, and agree to
256 compress packets sent to the peer with a maximum code size of nt
257 bits. If nt is not specified, it defaults to the value given for
258 nr. Values in the range 9 to 15 may be used for nr and nt; larger
259 values provide better compression but consume more kernel memory
260 for compression dictionaries. Alternatively, a value of 0 for nr
261 or nt disables compression in the corresponding direction. Use
262 nobsdcomp or bsdcomp 0 to disable BSD-Compress compression
263 entirely. If this option is read from a privileged source, a
264 nonprivileged user may not specify a code size larger than the
265 value from the privileged source.
266
267
268 cdtrcts
269
270 Use a non-standard hardware flow control such as DTR/CTS to control
271 the flow of data on the serial port. If the crtscts, nocrtscts,
272 cdtrcts or nocdtrcts option is not specified, the hardware flow
273 control setting for the serial port is left unchanged. Some serial
274 ports lack a true RTS output. Such serial ports use this mode to
275 implement true bi-directional flow control. Note that this flow
276 control mode does not permit using DTR as a modem control line.
277
278
279 chap-interval n
280
281 If this option is given, pppd will rechallenge the peer every n
282 seconds.
283
284
285 chap-max-challenge n
286
287 Set the maximum number of CHAP challenge transmissions to n
288 (default 10).
289
290
291 chap-restart n
292
293 Set the CHAP restart interval (retransmission timeout for
294 challenges) to n seconds. The default is 3.
295
296
297 connect-delay n
298
299 Wait for up to n milliseconds after the connect script finishes for
300 a valid PPP packet from the peer. When the wait period elapses or
301 when a valid PPP packet is received from the peer, pppd begins
302 negotiation by sending its first LCP packet. The default value is
303 1000 (1 second). A wait period applies only if the connect or pty
304 option is used.
305
306
307 datarate n
308
309 Set maximum data rate to n (in bytes per second) when using the
310 pty, notty, record, or socket options.
311
312
313 debug
314
315 Enables connection debugging facilities. If this option is given,
316 pppd logs the contents of all control packets sent or received in a
317 readable form. The packets are logged through syslog with facility
318 daemon and level debug. This information can be directed to a file
319 by configuring /etc/syslog.conf appropriately.
320
321
322 default-asyncmap
323
324 Disable asyncmap negotiation, forcing all control characters to be
325 escaped for both the transmit and the receive direction.
326
327
328 default-fcs
329
330 Disable FCS Alternatives negotiation entirely. By default, no FCS
331 Alternatives option is sent to the peer, but the option is
332 accepted. If this option is specified by the peer, then LCP
333 Configure-Reject is sent.
334
335
336 default-mru
337
338 Disable MRU [Maximum Receive Unit] negotiation. With this option,
339 pppd uses the default MRU value of 1500 bytes for the transmit and
340 receive directions.
341
342
343 deflate nr,nt,e
344
345 Request that the peer compress packets that it sends, using the
346 deflate scheme, with a maximum window size of 2**nr bytes, and
347 agree to compress packets sent to the peer with a maximum window
348 size of 2**nt bytes and effort level of e (1 to 9). If nt is not
349 specified, it defaults to the value given for nr. If e is not
350 specified, it defaults to 6. Values in the range 9 to 15 may be
351 used for nr and nt; larger values provide better compression but
352 consume more kernel memory for compression dictionaries. (Value 8
353 is not permitted due to a zlib bug.) Alternatively, a value of 0
354 for nr or nt disables compression in the corresponding direction.
355 Use nodeflate or deflate 0 to disable deflate compression entirely.
356 (Note: pppd requests deflate compression in preference to BSD-
357 Compress if the peer can do either.) If this option is read from a
358 privileged source, a nonprivileged user may not specify a code size
359 larger than the value from the privileged source.
360
361
362 demand
363
364 Initiate the link only on demand, that is, when data traffic is
365 present. With this option, the remote IP address must be specified
366 by the user on the command line or in an options file. pppd
367 initially configures and enables the interface for IP traffic
368 without connecting to the peer. When traffic is available, pppd
369 connects to the peer and performs negotiation, authentication and
370 other actions. When completed, pppd passes data packets across the
371 link. The demand option implies the persist option. If this
372 behavior is not desired, use the nopersist option after the demand
373 option. The idle and holdoff options can be used in conjunction
374 with the demand option.
375
376
377 domain d
378
379 Append the domain name d to the local host name for authentication
380 purposes. For example, if gethostname() returns the name porsche,
381 but the fully qualified domain name is porsche.Example.COM, you
382 could specify domain Example.COM. With this configuration, pppd
383 uses the name porsche.Example.COM for accessing secrets in the
384 secrets file and as the default name when authenticating to the
385 peer. This option is privileged.
386
387
388 endpoint endpoint-value
389
390 Set the endpoint discriminator (normally used for RFC 1990
391 Multilink PPP operation). The endpoint-value consists of a class
392 identifier and a class-dependent value. The class identifier is one
393 of "null," "local," "IP," "MAC," "magic," "phone," or a decimal
394 integer. If present, the class-dependent value is separated from
395 the identifier by a colon (":") or period (".") . This value may be
396 a standard dotted-decimal IP address for class "IP," an optionally
397 colon-or-dot separated hex Ethernet address for class "MAC" (must
398 have 6 numbers), or an arbitrary string of bytes specified in hex
399 with optional colon or dot separators between bytes. Although this
400 option is available, this implementation does not support
401 multilink.
402
403
404 fcs fcs-type
405
406 Set FCS type(s) desired for data sent by the peer. The fcs-type is
407 a comma-separated list of crc16, crc32, null, or integers. By
408 default, an FCS Alternatives option is not specified, and the
409 medium-dependent FCS type is used. If this option is specified and
410 the peer sends an LCP Configure-Nak, only the listed types are
411 used. If none are in common, the FCS Alternatives option is omitted
412 from the next LCP Configure-Request to drop back to the default.
413
414
415 hide-password
416
417 When logging the contents of PAP packets, this option causes pppd
418 to exclude the password string from the log. This is the default.
419
420
421 holdoff n
422
423 Specifies how many seconds to wait before re-initiating the link
424 after it terminates. This option is effective only if the persist
425 or demand option is used. The holdoff period is not applied if the
426 link is terminated because it was idle.
427
428
429 ident string
430
431 Set the LCP Identification string. The default value is a version
432 string similar to that displayed by the --version option.
433
434
435 idle n
436
437 Specifies that pppd must disconnect if the link is idle for n
438 seconds. The link is idle when no data packets (i.e. IP packets)
439 are being sent or received. Do not use this option with the persist
440 option but without the demand option.
441
442
443 ipcp-accept-local
444
445 With this option, pppd accepts the peer's idea of the local IP
446 address, even if the local IP address is specified in an option.
447
448
449 ipcp-accept-remote
450
451 With this option, pppd accepts the peer's idea of its remote IP
452 address, even if the remote IP address is specified in an option.
453
454
455 ipcp-max-configure n
456
457 Set the maximum number of IPCP Configure-Request transmissions to n
458 (default 10).
459
460
461 ipcp-max-failure n
462
463 Set the maximum number of IPCP Configure-NAKs sent before sending
464 Configure-Rejects instead to n (default 10).
465
466
467 ipcp-max-terminate n
468
469 Set the maximum number of IPCP terminate-request transmissions to n
470 (default 3).
471
472
473 ipcp-restart n
474
475 Set the IPCP restart interval (retransmission timeout) to n seconds
476 (default 3).
477
478
479 ipparam string
480
481 Provides an extra parameter to the ip-up and ip-down scripts. When
482 this option is given, the string supplied is given as the sixth
483 parameter to those scripts. See the section.
484
485
486 ipv6 <local_interface_identifier>,<remote_interface_identifier>
487
488 Set the local and/or remote 64-bit interface identifier. Either one
489 may be omitted. The identifier must be specified in standard ASCII
490 notation of IPv6 addresses (for example: ::dead:beef). If the
491 ipv6cp-use-ipaddr option is given, the local and remote identifiers
492 are derived from the respective IPv4 addresses (see above). The
493 ipv6cp-use-persistent option can be used instead of the ipv6
494 <local>,<remote> option.
495
496
497 ipv6cp-accept-local
498
499 Accept peer's interface identifier for the local link identifier.
500
501
502 ipv6cp-max-configure n
503
504 Set the maximum number of IPv6CP Configure-Request transmissions to
505 n (default 10).
506
507
508 ipv6cp-max-failure n
509
510 Set the maximum number of IPv6CP Configure-NAKs sent before sending
511 Configure-Rejects instead to n (default 10).
512
513
514 ipv6cp-max-terminate n
515
516 Set the maximum number of IPv6CP terminate-request transmissions to
517 n (default 3).
518
519
520 ipv6cp-restart n
521
522 Set the IPv6CP restart interval (retransmission timeout) to n
523 seconds (default 3).
524
525
526 ipv6cp-use-ipaddr
527
528 If either the local or remote IPv6 address is unspecified, use the
529 corresponding configured IPv4 address as a default interface
530 identifier. (This option uses the configured addresses, not the
531 negotiated addresses. Do not use it with ipcp-accept-local if the
532 local IPv6 identifier is unspecified or with ipcp-accept-remote if
533 the remote IPv6 identifier is unspecified.)
534
535
536 ipv6cp-use-persistent
537
538 Use uniquely-available persistent value for link local address.
539
540
541 kdebug n
542
543 Enable debugging code in the kernel-level PPP driver. Argument n is
544 the sum of the following values: 1 to enable general debug
545 messages, 2 to request that contents of received packets be
546 printed, and 4 to request contents of transmitted packets be
547 printed. Messages printed by the kernel are logged by syslogd(1M)
548 to a file directed in the /etc/syslog.conf configuration file. Do
549 not use the kdebug option to debug failed links. Use the debug
550 option instead.
551
552
553 lcp-echo-failure n
554
555 If this option is given, pppd presumes the peer to be dead if n LCP
556 Echo-Requests are sent without receiving a valid LCP Echo-Reply. If
557 this happens, pppd terminates the connection. This option requires
558 a non-zero value for the lcp-echo-interval parameter. This option
559 enables pppd to terminate after the physical connection is broken
560 (for example, if the modem has hung up) in situations where no
561 hardware modem control lines are available.
562
563
564 lcp-echo-interval n
565
566 If this option is given, pppd sends an LCP Echo-Request frame to
567 the peer every n seconds. Normally the peer responds to the Echo-
568 Request by sending an Echo-Reply. This option can be used with the
569 lcp-echo-failure option to detect that the peer is no longer
570 connected.
571
572
573 lcp-max-configure n
574
575 Set the maximum number of LCP Configure-Request transmissions to n
576 (default 10).
577
578
579 lcp-max-failure n
580
581 Set the maximum number of LCP Configure-NAKs sent before starting
582 to send Configure-Rejects instead to n (default 10).
583
584
585 lcp-max-terminate n
586
587 Set the maximum number of LCP Terminate-Request transmissions to n
588 (default 3).
589
590
591 lcp-restart n
592
593 Set the LCP restart interval (retransmission timeout) to n seconds
594 (default 3).
595
596
597 linkname name
598
599 Sets the logical name of the link to name. pppd creates a file
600 named ppp-name.pid in /var/run containing its process ID. This is
601 useful in determining which instance of pppd is responsible for the
602 link to a given peer system. This is a privileged option.
603
604
605 local
606
607 Do not use modem control lines. With this option, pppd ignores the
608 state of the CD (Carrier Detect) signal from the modem and does not
609 change the state of the DTR (Data Terminal Ready) signal.
610
611
612 logfd n
613
614 Send log messages to file descriptor n. pppd sends log messages to
615 (at most) one file or file descriptor (as well as sending the log
616 messages to syslog), so this option and the logfile option are
617 mutually exclusive. By default pppd sends log messages to stdout
618 (file descriptor 1) unless the serial port is open on stdout.
619
620
621 logfile filename
622
623 Append log messages to the file filename (and send the log messages
624 to syslog). The file is opened in append mode with the privileges
625 of the user who invoked pppd.
626
627
628 login
629
630 Use the system password database for authenticating the peer using
631 PAP, and record the user in the system wtmp file. Note that the
632 peer must have an entry in the /etc/ppp/pap-secrets file and the
633 system password database to be allowed access.
634
635
636 maxconnect n
637
638 Terminate the connection after it has been available for network
639 traffic for n seconds (that is, n seconds after the first network
640 control protocol starts). An LCP Time-Remaining message is sent
641 when the first NCP starts, and again when 5, 2, and 0.5 minutes are
642 remaining.
643
644
645 maxfail n
646
647 Terminate after n consecutive failed connection attempts. A value
648 of 0 means no limit. The default value is 10.
649
650
651 modem
652
653 Use the modem control lines. This option is the default. With this
654 option, pppd waits for the CD (Carrier Detect) signal from the
655 modem to be asserted when opening the serial device (unless a
656 connect script is specified), and drops the DTR (Data Terminal
657 Ready) signal briefly when the connection is terminated and before
658 executing the connect script.
659
660
661 ms-dns <addr>
662
663 If pppd is acting as a server for Microsoft Windows clients, this
664 option allows pppd to supply one or two DNS (Domain Name Server)
665 addresses to the clients. The first instance of this option
666 specifies the primary DNS address; the second instance (if given)
667 specifies the secondary DNS address. If the first instance
668 specifies a name that resolves to multiple IP addresses, then the
669 first two addresses are used. (This option is present in some older
670 versions of pppd under the name dns-addr.)
671
672
673 ms-lanman
674
675 If pppd connects as a client to a Microsoft server and uses MS-
676 CHAPv1 for authentication, this option selects the LAN Manager
677 password style instead of Microsoft NT.
678
679
680 ms-wins <addr>
681
682 If pppd acts as a server for Microsoft Windows or Samba clients,
683 this option allows pppd to supply one or two WINS (Windows Internet
684 Name Services) server addresses to the clients. The first instance
685 of this option specifies the primary WINS address; the second
686 instance (if given) specifies the secondary WINS address. As with
687 ms-dns, if the name specified resolves to multiple IP addresses,
688 then the first two will be taken as primary and secondary.
689
690
691 name name
692
693 Set the name of the local system for authentication purposes to
694 name. This is a privileged option. With this option, pppd uses
695 lines in the secrets files that have name as the second field to
696 look for a secret to use in authenticating the peer. In addition,
697 unless overridden with the user option, name is used as the name to
698 send to the peer when authenticating the local system. (Note that
699 pppd does not append the domain name to name.)
700
701
702 no-accm-test
703
704 Disable use of asyncmap (ACCM) checking using LCP Echo-Request
705 messages. If the lcp-echo-failure is used on an asynchronous line,
706 pppd includes all control characters in the first n LCP Echo-
707 Request messages. If the asyncmap is set incorrectly, the link
708 drops rather than continue operation with random failures. This
709 option disables that feature.
710
711
712 noaccomp
713
714 Disable HDLC Address/Control compression in both directions (send
715 and receive).
716
717
718 noauth
719
720 Do not require the peer to authenticate itself. This option is
721 privileged.
722
723
724 nobsdcomp
725
726 Disables BSD-Compress compression; pppd will not request or agree
727 to compress packets using the BSD-Compress scheme. This option is
728 not necessary if noccp is specified.
729
730
731 noccp
732
733 Disable CCP (Compression Control Protocol) negotiation. This option
734 should only be required if the peer has bugs or becomes confused by
735 requests from pppd for CCP negotiation. If CCP is disabled, then
736 BSD and deflate compression do not need to be separately disabled.
737
738
739 nocrtscts
740
741 Disable hardware flow control (i.e. RTS/CTS) on the serial port. If
742 the crtscts, nocrtscts, cdtrcts or nocdtrcts options are not given,
743 the hardware flow control setting for the serial port is left
744 unchanged.
745
746
747 nocdtrcts
748
749 This option is a synonym for nocrtscts. Either option will disable
750 both forms of hardware flow control.
751
752
753 nodefaultroute
754
755 Disable the defaultroute option. You can prevent non-root users
756 from creating default routes with pppd by placing this option in
757 the /etc/ppp/options file.
758
759
760 nodeflate
761
762 Disables deflate compression; pppd will not request or agree to
763 compress packets using the deflate scheme. This option is not
764 necessary if noccp is specified.
765
766
767 nodeflatedraft
768
769 Do not use Internet Draft (incorrectly assigned) algorithm number
770 for deflate compression. This option is not necessary if noccp is
771 specified.
772
773
774 nodetach
775
776 Do not detach from the controlling terminal. Without this option,
777 pppd forks to become a background process if a serial device other
778 than the terminal on the standard input is specified.
779
780
781 noendpoint
782
783 Do not send or accept the Multilink Endpoint Discriminator option.
784
785
786 noident
787
788 Disable use of LCP Identification. LCP Identification messages will
789 not be sent to the peer, but received messages will be logged.
790 (Specify this option twice to completely disable LCP
791 Identification. In this case, pppd sends LCP Code-Reject in
792 response to received LCP Identification messages.)
793
794
795 noip
796
797 Disable IPCP negotiation and IP communication. Use this option only
798 if the peer has bugs or becomes confused by requests from pppd for
799 IPCP negotiation.
800
801
802 noipv6
803
804 Disable IPv6CP negotiation and IPv6 communication. IPv6 is not
805 enabled by default.
806
807
808 noipdefault
809
810 Disables the default behavior when no local IP address is
811 specified, which is to determine (if possible) the local IP address
812 from the hostname. With this option, the peer must supply the local
813 IP address during IPCP negotiation (unless it specified explicitly
814 on the command line or in an options file).
815
816
817 nolog
818
819 Do not send log messages to a file or file descriptor. This option
820 cancels the logfd and logfile options. nologfd acts as an alias for
821 this option.
822
823
824 nomagic
825
826 Disable magic number negotiation. With this option, pppd cannot
827 detect a looped-back line. Use this option only if the peer has
828 bugs. Do not use this option to work around the "Serial line is
829 looped back" error message.
830
831
832 nopam
833
834 This privileged option disables use of pluggable authentication
835 modules. If this option is specified, pppd reverts to standard
836 authentication mechanisms. The default is not to use PAM.
837
838
839 nopcomp
840
841 Disable protocol field compression negotiation in the receive and
842 the transmit direction.
843
844
845 nopersist
846
847 Exit once a connection has been made and terminated. This is the
848 default unless the persist or demand option is specified.
849
850
851 noplink
852
853 Cause pppd to use I_LINK instead of I_PLINK. This is the default.
854 When I_LINK is used, the system cleans up terminated interfaces
855 (even when SIGKILL is used) but does not allow ifconfig(1M) to
856 unplumb PPP streams or insert or remove modules dynamically. Use
857 the plink option if ifconfig(1M) modinsert, modremove or unplumb
858 support is needed.
859
860
861 nopredictor1
862
863 Do not accept or agree to Predictor-1 compression. (This option is
864 accepted for compatibility. The implementation does not support
865 Predictor-1 compression.)
866
867
868 noproxyarp
869
870 Disable the proxyarp option. If you want to prevent users from
871 creating proxy ARP entries with pppd, place this option in the
872 /etc/ppp/options file.
873
874
875 notty
876
877 Normally, pppd requires a terminal device. With this option, pppd
878 allocates itself a pseudo-terminal pair and uses the subsidiary as
879 its terminal device. pppd creates a child process to act as a
880 character shunt to transfer characters between the pseudo-terminal
881 manager and its standard input and output. Thus, pppd transmits
882 characters on its standard output and receives characters on its
883 standard input even if they are not terminal devices. This option
884 increases the latency and CPU overhead of transferring data over
885 the ppp interface as all of the characters sent and received must
886 flow through the character shunt process. An explicit device name
887 may not be given if this option is used.
888
889
890 novj
891
892 Disable Van Jacobson style TCP/IP header compression in both the
893 transmit and the receive direction.
894
895
896 novjccomp
897
898 Disable the connection-ID compression option in Van Jacobson style
899 TCP/IP header compression. With this option, pppd does not omit the
900 connection-ID byte from Van Jacobson compressed TCP/IP headers, nor
901 does it ask the peer to do so. This option is unnecessary if novj
902 is specified.
903
904
905 pam
906
907 This privileged option enables use of PAM. If this is specified,
908 pppd uses the pam(3PAM) framework for user authentication with a
909 service name of "ppp" if the login option and PAP authentication
910 are used. The default is not to use PAM.
911
912
913 papcrypt
914
915 Indicates that pppd should not accept a password which, before
916 encryption, is identical to the secret from the /etc/ppp/pap-
917 secrets file. Use this option if the secrets in the pap-secrets
918 file are in crypt(3C) format.
919
920
921 pap-max-authreq n
922
923 Set the maximum number of PAP authenticate-request transmissions to
924 n (default 10).
925
926
927 pap-restart n
928
929 Set the PAP restart interval (retransmission timeout) to n seconds
930 (default 3).
931
932
933 pap-timeout n
934
935 Set the maximum time that pppd waits for the peer to authenticate
936 itself with PAP to n seconds (0= no limit). The default is 30
937 seconds.
938
939
940 password string
941
942 Password string for authentication to the peer.
943
944
945 persist
946
947 Do not exit after a connection is terminated; instead try to reopen
948 the connection.
949
950
951 plink
952
953 Cause pppd to use I_PLINK instead of I_LINK. The default is to use
954 I_LINK, which cleans up terminated interface (even if SIGKILL is
955 used), but does not allow ifconfig(1M) to unplumb PPP streams or
956 insert or remove modules dynamically. Use this option if
957 ifconfig(1M) modinsert/modremove/unplumb support is needed. See
958 also the plumbed option.
959
960
961 plugin filename
962
963 Load the shared library object file filename as a plugin. This is a
964 privileged option. Unless the filename specifies an explicit path,
965 /etc/ppp/plugins and /usr/lib/inet/ppp will be searched for the
966 object to load in that order.
967
968
969 plumbed
970
971 This option indicates that pppd should find a plumbed interface and
972 use that for the session. If IPv4 addresses or IPv6 interface IDs
973 or link MTU are otherwise unspecified, they are copied from the
974 interface selected. This mode mimics some of the functionality of
975 the older aspppd implementation and may be helpful when pppd is
976 used with external applications that use ifconfig(1M).
977
978
979 pppmux timer
980
981 Enable PPP Multiplexing option negotiation and set transmit
982 multiplexing timeout to timer microseconds.
983
984
985 privgroup group-name
986
987 Allows members of group group-name to use privileged options. This
988 is a privileged option. Because there is no guarantee that members
989 of group-name cannot use pppd to become root themselves, you should
990 be careful using this option. Consider it equivalent to putting the
991 members of group-name in the root or sys group.
992
993
994 proxyarp
995
996 Add an entry to the system's Address Resolution Protocol (ARP)
997 table with the IP address of the peer and the Ethernet address of
998 this system. When you use this option, the peer appears to other
999 systems to be on the local Ethernet. The remote address on the PPP
1000 link must be in the same subnet as assigned to an Ethernet
1001 interface.
1002
1003
1004 pty script
1005
1006 Specifies that the command script, and not a specific terminal
1007 device is used for serial communication. pppd allocates itself a
1008 pseudo-terminal pair and uses the subsidiary as its terminal
1009 device. script runs in a child process with the pseudo-terminal
1010 manager as its standard input and output. An explicit device name
1011 may not be given if this option is used. (Note: if the record
1012 option is used in conjunction with the pty option, the child
1013 process will have pipes on its standard input and output.)
1014
1015
1016 receive-all
1017
1018 With this option, pppd accepts all control characters from the
1019 peer, including those marked in the receive asyncmap. Without this
1020 option, pppd discards those characters as specified in RFC 1662.
1021 This option should be used only if the peer has bugs, as is often
1022 found with dial-back implementations.
1023
1024
1025 record filename
1026
1027 Directs pppd to record all characters sent and received to a file
1028 named filename. filename is opened in append mode, using the user's
1029 user-ID and permissions. Because this option uses a pseudo-terminal
1030 and a process to transfer characters between the pseudo-terminal
1031 and the real serial device, it increases the latency and CPU
1032 overhead of transferring data over the PPP interface. Characters
1033 are stored in a tagged format with timestamps that can be displayed
1034 in readable form using the pppdump(1M) program. This option is
1035 generally used when debugging the kernel portion of pppd
1036 (especially CCP compression algorithms) and not for debugging link
1037 configuration problems. See the debug option.
1038
1039
1040 remotename name
1041
1042 Set the assumed name of the remote system for authentication
1043 purposes to name. Microsoft WindowsNT does not provide a system
1044 name in its CHAP Challenge messages, and this option is often used
1045 to work around this problem.
1046
1047
1048 refuse-chap
1049
1050 With this option, pppd will not agree to authenticate itself to the
1051 peer using standard Challenge Handshake Authentication Protocol
1052 (CHAP). (MS-CHAP is not affected.)
1053
1054
1055 refuse-mschap
1056
1057 Do not agree to authenticate to peer with MS-CHAPv1. If this option
1058 is specified, requests for MS-CHAPv1 authentication from the peer
1059 are declined with LCP Configure-Nak. That option does not disable
1060 any other form of CHAP.
1061
1062
1063 refuse-mschapv2
1064
1065 Do not agree to authenticate to peer with MS-CHAPv2. If specified,
1066 this option requests that MS-CHAPv2 authentication from the peer be
1067 declined with LCP Configure-Nak. That option does not disable any
1068 other form of CHAP.
1069
1070
1071 refuse-pap
1072
1073 With this option, pppd will not agree to authenticate itself to the
1074 peer using Password Authentication Protocol (PAP).
1075
1076
1077 require-chap
1078
1079 Require the peer to authenticate itself using standard CHAP
1080 authentication. MS-CHAP is not affected.
1081
1082
1083 require-mschap
1084
1085 Require the peer to authenticate itself using MS-CHAPv1
1086 authentication.
1087
1088
1089 require-mschapv2
1090
1091 Require the peer to authenticate itself using MS-CHAPv2
1092 authentication.
1093
1094
1095 require-pap
1096
1097 Require the peer to authenticate itself using PAP authentication.
1098
1099
1100 show-password
1101
1102 When logging contents of PAP packets, this option causes pppd to
1103 show the password string in the log message.
1104
1105
1106 silent
1107
1108 With this option, pppd will not transmit LCP packets to initiate a
1109 connection until a valid LCP packet is received from the peer. This
1110 is like the "passive" option with older versions of pppd and is
1111 retained for compatibility, but the current passive option is
1112 preferred.
1113
1114
1115 small-accm-test
1116
1117 When checking the asyncmap (ACCM) setting, pppd uses all 256
1118 possible values by default. See no-accm-test. This option restricts
1119 the test so that only the 32 values affected by standard ACCM
1120 negotiation are tested. This option is useful on very slow links.
1121
1122
1123 socket host:port
1124
1125 Connect to given host and port using TCP and run PPP over this
1126 connection.
1127
1128
1129 sync
1130
1131 Use synchronous HDLC serial encoding instead of asynchronous. The
1132 device used by pppd with this option must have sync support.
1133 Currently supports zs, se, and hsi drivers.
1134
1135
1136 unit n
1137
1138 Set PPP interface unit number to n, if possible.
1139
1140
1141 updetach
1142
1143 With this option, pppd detaches from its controlling terminal after
1144 establishing the PPP connection. When this is specified, messages
1145 sent to stderr by the connect script, usually chat(1M), and
1146 debugging messages from the debug option are directed to pppd's
1147 standard output.
1148
1149
1150 usehostname
1151
1152 Enforce the use of the hostname with domain name appended, if
1153 given, as the name of the local system for authentication purposes.
1154 This overrides the name option. Because the name option is
1155 privileged, this option is normally not needed.
1156
1157
1158 usepeerdns
1159
1160 Ask the peer for up to two DNS server addresses. Addresses supplied
1161 by the peer, if any, are passed to the /etc/ppp/ip-up script in the
1162 environment variables DNS1 and DNS2. In addition, pppd creates an
1163 /etc/ppp/resolv.conf file containing one or two nameserver lines
1164 with the address(es) supplied by the peer.
1165
1166
1167 user name
1168
1169 Sets the name used for authenticating the local system to the peer
1170 to name.
1171
1172
1173 vj-max-slots n
1174
1175 Sets the number of connection slots to be used by the Van Jacobson
1176 TCP/IP header compression and decompression code to n, which must
1177 be between 2 and 16 (inclusive).
1178
1179
1180 welcome script
1181
1182 Run the executable or shell command specified by script before
1183 initiating PPP negotiation, after the connect script, if any, has
1184 completed. A value for this option from a privileged source cannot
1185 be overridden by a non-privileged user.
1186
1187
1188 xonxoff
1189
1190 Use software flow control, that is, XON/XOFF, to control the flow
1191 of data on the serial port.
1192
1193
1194 Obsolete Options
1195 The following options are obsolete:
1196
1197 +ua name
1198 Read a PAP user name and password from the file name.
1199 This file must have two lines for name and password. Name
1200 and password are sent to the peer when the peer requests
1201 PAP authentication.
1202
1203
1204 +ipv6
1205 Enable IPv6 and IPv6CP without specifying interface
1206 identifiers.
1207
1208
1209 --version
1210 Show version number and exit.
1211
1212
1213 --help
1214 Show brief help message and exit.
1215
1216
1217 EXTENDED DESCRIPTION
1218 The following sections discuss miscellaneous features of pppd:
1219
1220 Security
1221 pppd allows system administrators to provide legitimate users with PPP
1222 access to a server machine without fear of compromising the security of
1223 the server or the network it runs on. Access control is provided by
1224 restricting IP addresses the peer may use based on its authenticated
1225 identity (if any), and through restrictions on options a non-privileged
1226 user may use. Options that permit potentially insecure configurations
1227 are privileged. Privileged options are accepted only in files that are
1228 under the control of the system administrator or when pppd is being run
1229 by root.
1230
1231
1232 By default, pppd allows an unauthenticated peer to use a given IP
1233 address only if the system does not already have a route to that IP
1234 address. For example, a system with a permanent connection to the wider
1235 Internet will normally have a default route, meaning all peers must
1236 authenticate themselves to set up a connection. On such a system, the
1237 auth option is the default. Conversely, a system with a PPP link that
1238 comprises the only connection to the Internet probably does not possess
1239 a default route, so the peer can use virtually any IP address without
1240 authenticating itself.
1241
1242
1243 Security-sensitive options are privileged and cannot be accessed by a
1244 non-privileged user running pppd, either on the command line, in the
1245 user's $HOME/.ppprc file, or in an options file read using the file
1246 option. Privileged options may be used in /etc/ppp/options file or in
1247 an options file read using the call option. If pppd is run by the root
1248 user, privileged options can be used without restriction. If the
1249 /etc/ppp/options file does not exist, then only root may invoke pppd.
1250 The /etc/ppp/options file must be created (but may be empty) to allow
1251 ordinary non-root users to access pppd.
1252
1253
1254 When opening the device, pppd uses the invoking user's user ID or the
1255 root UID (that is, 0), depending if the device name was specified by
1256 the user or the system administrator. If the device name comes from a
1257 privileged source, that is, /etc/ppp/options or an options file read
1258 using the call option, pppd uses full root privileges when opening the
1259 device. Thus, by creating an appropriate file under /etc/ppp/peers, the
1260 system administrator can allow users to establish a PPP connection via
1261 a device that they would not normally have access to. Otherwise pppd
1262 uses the invoking user's real UID when opening the device.
1263
1264 Authentication
1265 During the authentication process, one peer convinces the other of its
1266 identity by sending its name and some secret information to the other.
1267 During authentication, the first peer becomes the "client" and the
1268 second becomes the "server." Authentication names can (but are not
1269 required to) correspond to the peer's Internet hostnames.
1270
1271
1272 pppd supports four authentication protocols: the Password
1273 Authentication Protocol (PAP) and three forms of the Challenge
1274 Handshake Authentication Protocol (CHAP). With the PAP protocol, the
1275 client sends its name and a cleartext password to the server to
1276 authenticate itself. With CHAP, the server initiates the authentication
1277 exchange by sending a challenge to the client who must respond with its
1278 name and a hash value derived from the shared secret and the challenge.
1279
1280
1281 The PPP protocol is symmetrical, meaning that each peer may be required
1282 to authenticate itself to the other. Different authentication protocols
1283 and names can be used for each exchange.
1284
1285
1286 By default, pppd authenticates if requested and does not require
1287 authentication from the peer. However, pppd does not authenticate
1288 itself with a specific protocol if it has no secrets that can do so.
1289
1290
1291 pppd stores authentication secrets in the /etc/ppp/pap-secrets (for
1292 PAP), and /etc/ppp/chap-secrets (for CHAP) files. Both files use the
1293 same format. pppd uses secrets files to authenticate itself to other
1294 systems and to authenticate other systems to itself.
1295
1296
1297 Secrets files contain one secret per line. Secrets are specific to a
1298 particular combination of client and server and can only be used by
1299 that client to authenticate itself to that server. Each line in a
1300 secrets file has a minimum of three fields that contain the client and
1301 server names followed by the secret. Often, these three fields are
1302 followed by IP addresses that are used by clients to connect to a
1303 server.
1304
1305
1306 A secrets file is parsed into words, with client name, server name and
1307 secrets fields allocated one word each. Embedded spaces or other
1308 special characters within a word must be quoted or escaped. Case is
1309 significant in all three fields.
1310
1311
1312 A secret beginning with an at sign ("@") is followed by the name of a
1313 file containing the secret. An asterisk (*) as the client or server
1314 name matches any name. When choosing a match, pppd selects the one with
1315 the fewest wildcards. Succeeding words on a line are interpreted by
1316 pppd as acceptable IP addresses for that client. IP Addresses are
1317 disallowed if they appear in lines that contain only three words or
1318 lines whose first word begins with a hyphen ("-"). To allow any
1319 address, use "*". An address starting with an exclamation point ("!")
1320 indicates that the specified address is not acceptable. An address may
1321 be followed by "/" and a number n to indicate a whole subnet (all
1322 addresses that have the same value in the most significant n bits). In
1323 this form, the address may be followed by a plus sign ("+") to indicate
1324 that one address from the subnet is authorized, based on the ppp
1325 network interface unit number in use. In this case, the host part of
1326 the address is set to the unit number, plus one.
1327
1328
1329 When authenticating the peer, pppd chooses a secret with the peer's
1330 name in the first field of the secrets file and the name of the local
1331 system in the second field. The local system name defaults to the
1332 hostname, with the domain name appended if the domain option is used.
1333 The default can be overridden with the name option unless the
1334 usehostname option is used.
1335
1336
1337 When authenticating to the peer, pppd first determines the name it will
1338 use to identify itself to the peer. This name is specified with the
1339 user option. If the user option is not used, the name defaults to the
1340 host name of the local system. pppd then selects a secret from the
1341 secrets file by searching for an entry with a local name in the first
1342 field and the peer's name in the second field. pppd will know the name
1343 of the peer if standard CHAP authentication is used because the peer
1344 will have sent it in the Challenge packet. However, if MS-CHAP or PAP
1345 is being used, pppd must determine the peer's name from the options
1346 specified by the user. The user can specify the peer's name directly
1347 with the remotename option. Otherwise, if the remote IP address was
1348 specified by a name, rather than in numeric form, that name will be
1349 used as the peer's name. If that fails, pppd uses the null string as
1350 the peer's name.
1351
1352
1353 When authenticating the peer with PAP, the supplied password is
1354 compared with data in the secrets file. If the password and secret do
1355 not match, the password is encrypted using crypt() and checked against
1356 the secret again. If the papcrypt option is given, the first
1357 unencrypted comparison is omitted for better security, and entries must
1358 thus be in encrypted crypt(3C) form.
1359
1360
1361 If the login option is specified, the username and password are also
1362 checked against the system password database. This allows you to set up
1363 the pap-secrets file to enable PPP access only to certain users, and to
1364 restrict the set of IP addresses available to users. Typically, when
1365 using the login option, the secret in /etc/ppp/pap-secrets would be "",
1366 which matches any password supplied by the peer. This makes having the
1367 same secret in two places unnecessary. When login is used, the pam
1368 option enables access control through pam(3PAM).
1369
1370
1371 Authentication must be completed before IPCP (or other network
1372 protocol) can be started. If the peer is required to authenticate
1373 itself and fails, pppd closes LCP and terminates the link. If IPCP
1374 negotiates an unacceptable IP address for the remote host, IPCP is
1375 closed. IP packets are sent or received only when IPCP is open.
1376
1377
1378 To allow hosts that cannot authenticate themselves to connect and use
1379 one of a restricted set of IP addresses, add a line to the pap-secrets
1380 file specifying the empty string for the client name and secret.
1381
1382
1383 Additional pppd options for a given peer may be specified by placing
1384 them at the end of the secrets entry, separated by two dashes (--). For
1385 example
1386
1387 peername servername secret ip-address -- novj
1388
1389
1390 Routing
1391 When IPCP negotiation is complete, pppd informs the kernel of the local
1392 and remote IP addresses for the PPP interface and creates a host route
1393 to the remote end of the link that enables peers to exchange IP
1394 packets. Communication with other machines generally requires further
1395 modification to routing tables and/or Address Resolution Protocol (ARP)
1396 tables. In most cases the defaultroute and/or proxyarp options are
1397 sufficient for this, but further intervention may be necessary. If
1398 further intervention is required, use the /etc/ppp/ip-up script or a
1399 routing protocol daemon.
1400
1401
1402 To add a default route through the remote host, use the defaultroute
1403 option. This option is typically used for "client" systems; that is,
1404 end-nodes that use the PPP link for access to the general Internet.
1405
1406
1407 In some cases it is desirable to use proxy ARP, for example on a server
1408 machine connected to a LAN, to allow other hosts to communicate with
1409 the remote host. proxyarp instructs pppd to look for a network
1410 interface on the same subnet as the remote host. That is, an interface
1411 supporting broadcast and ARP that is not a point-to-point or loopback
1412 interface and that is currently up. If found, pppd creates a permanent,
1413 published ARP entry with the IP address of the remote host and the
1414 hardware address of the network interface.
1415
1416
1417 When the demand option is used, the interface IP addresses are already
1418 set at the time when IPCP comes up. If pppd cannot negotiate the same
1419 addresses it used to configure the interface, it changes the interface
1420 IP addresses to the negotiated addresses. This may disrupt existing
1421 connections. Using demand dialing with peers that perform dynamic IP
1422 address assignment is not recommended.
1423
1424 Scripts
1425 pppd invokes scripts at various stages during processing that are used
1426 to perform site-specific ancillary processing. These scripts may be
1427 shell scripts or executable programs. pppd does not wait for the
1428 scripts to finish. The scripts are executed as root (with the real and
1429 effective user-id set to 0), enabling them to update routing tables,
1430 run privileged daemons, or perform other tasks. Be sure that the
1431 contents of these scripts do not compromise your system's security.
1432 pppd runs the scripts with standard input, output and error redirected
1433 to /dev/null, and with an environment that is empty except for some
1434 environment variables that give information about the link. The pppd
1435 environment variables are:
1436
1437 DEVICE
1438 Name of the serial tty device.
1439
1440
1441 IFNAME
1442 Name of the network interface.
1443
1444
1445 IPLOCAL
1446 IP address for the link's local end. This is set only
1447 when IPCP has started.
1448
1449
1450 IPREMOTE
1451 IP address for the link's remote end. This is set only
1452 when IPCP has started.
1453
1454
1455 PEERNAME
1456 Authenticated name of the peer. This is set only if the
1457 peer authenticates itself.
1458
1459
1460 SPEED
1461 Baud rate of the tty device.
1462
1463
1464 ORIG_UID
1465 Real user-id of user who invoked pppd.
1466
1467
1468 PPPLOGNAME
1469 Username of the real user-id who invoked pppd. This is
1470 always set.
1471
1472
1473
1474 pppd also sets the following variables for the ip-down and auth-down
1475 scripts:
1476
1477 CONNECT_TIME
1478 Number of seconds between the start of PPP negotiation
1479 and connection termination.
1480
1481
1482 BYTES_SENT
1483 Number of bytes sent at the level of the serial port
1484 during the connection.
1485
1486
1487 BYTES_RCVD
1488 Number of bytes received at the level of the serial
1489 port during the connection.
1490
1491
1492 LINKNAME
1493 Logical name of the link, set with the linkname
1494 option.
1495
1496
1497
1498 If they exist, pppd invokes the following scripts. It is not an error
1499 if they do not exist.
1500
1501 /etc/ppp/auth-up
1502 Program or script executed after the remote
1503 system successfully authenticates itself. It is
1504 executed with five command-line arguments:
1505 interface-name peer-name user-name tty-device
1506 speed. Note that this script is not executed if
1507 the peer does not authenticate itself, for
1508 example, when the noauth option is used.
1509
1510
1511 /etc/ppp/auth-down
1512 Program or script executed when the link goes
1513 down if /etc/ppp/auth-up was previously
1514 executed. It is executed in the same manner with
1515 the same parameters as /etc/ppp/auth-up.
1516
1517
1518 /etc/ppp/ip-up
1519 A program or script that is executed when the link
1520 is available for sending and receiving IP packets
1521 (that is, IPCP has come up). It is executed with
1522 six command-line arguments: interface-name tty-
1523 device speed local-IP-address remote-IP-address
1524 ipparam.
1525
1526
1527 /etc/ppp/ip-down
1528 A program or script which is executed when the
1529 link is no longer available for sending and
1530 receiving IP packets. This script can be used for
1531 undoing the effects of the /etc/ppp/ip-up script.
1532 It is invoked in the same manner and with the same
1533 parameters as the ip-up script.
1534
1535
1536 /etc/ppp/ipv6-up
1537 Similar to /etc/ppp/ip-up, except that it is
1538 executed when the link is available for sending
1539 and receiving IPv6 packets. Executed with six
1540 command-line arguments: interface-name tty-device
1541 speed local-link-local-address remote-link-local-
1542 address ipparam.
1543
1544
1545 /etc/ppp/ipv6-down
1546 Similar to /etc/ppp/ip-down, but executed when
1547 IPv6 packets can no longer be transmitted on the
1548 link. Executed with the same parameters as the
1549 ipv6-up script.
1550
1551
1552 EXAMPLES
1553 Example 1 Using the auth Option
1554
1555
1556 The following examples assume that the /etc/ppp/options file contains
1557 the auth option.
1558
1559
1560
1561 pppd is commonly used to dial out to an ISP. You can do this using the
1562 "pppd call isp" command where the /etc/ppp/peers/isp file is set up to
1563 contain a line similar to the following:
1564
1565
1566 cua/a 19200 crtscts connect '/usr/bin/chat -f /etc/ppp/chat-isp' noauth
1567
1568
1569
1570 For this example, chat(1M) is used to dial the ISP's modem and process
1571 any login sequence required. The /etc/ppp/chat-isp file is used by chat
1572 and could contain the following:
1573
1574
1575 ABORT "NO CARRIER"
1576 ABORT "NO DIALTONE"
1577 ABORT "ERROR"
1578 ABORT "NO ANSWER"
1579 ABORT "BUSY"
1580 ABORT "Username/Password Incorrect"
1581 "" "at"
1582 OK "at&f&d2&c1"
1583 OK "atdt2468135"
1584 "name:" "^Umyuserid"
1585 "word:" "\qmypassword"
1586 "ispts" "\q^Uppp"
1587 "~-^Uppp-~"
1588
1589
1590
1591 See the chat(1M) man page for details of chat scripts.
1592
1593
1594 Example 2 Using pppd with proxyarp
1595
1596
1597 pppd can also provide a dial-in ppp service for users. If the users
1598 already have login accounts, the simplest way to set up the ppp service
1599 is to let the users log in to their accounts and run pppd as shown in
1600 the following example:
1601
1602
1603 example% pppd proxyarp
1604
1605
1606
1607 Example 3 Providing a User with Access to PPP Facilities
1608
1609
1610 To provide a user with access to the PPP facilities, allocate an IP
1611 address for the user's machine, create an entry in /etc/ppp/pap-secrets
1612 or /etc/ppp/chap-secrets. This enables the user's machine to
1613 authenticate itself. For example, to enable user "Joe" using machine
1614 "joespc" to dial in to machine "server" and use the IP address
1615 "joespc.example.net," add the following entry to the /etc/ppp/pap-
1616 secrets or /etc/ppp/chap-secrets files:
1617
1618
1619 joespc server "joe's secret" joespc.example.net
1620
1621
1622
1623
1624 Alternatively, you can create another username, for example "ppp,"
1625 whose login shell is /usr/bin/pppd and whose home directory is
1626 /etc/ppp. If you run pppd this way, add the options to the
1627 /etc/ppp/.ppprc file.
1628
1629
1630
1631 If your serial connection is complex, it may be useful to escape such
1632 control characters as XON (^Q) and XOFF (^S), using asyncmap a0000. If
1633 the path includes a telnet, escape ^] (asyncmap 200a0000). If the path
1634 includes a rlogin command, add escape ff option to the options, because
1635 rlogin removes the window-size-change sequence [0xff, 0xff, 0x73, 0x73,
1636 followed by any 8 bytes] from the stream.
1637
1638
1639 EXIT STATUS
1640 The pppd exit status indicates errors or specifies why a link was
1641 terminated. Exit status values are:
1642
1643 0
1644 pppd has detached or the connection was successfully established
1645 and terminated at the peer's request.
1646
1647
1648 1
1649 An immediately fatal error occurred. For example, an essential
1650 system call failed.
1651
1652
1653 2
1654 An error was detected in the options given. For example, two
1655 mutually exclusive options were used, or /etc/ppp/options is
1656 missing and the user is not root.
1657
1658
1659 3
1660 pppd is not setuid-root and the invoking user is not root.
1661
1662
1663 4
1664 The kernel does not support PPP. For example, the PPP kernel
1665 driver is not included or cannot be loaded.
1666
1667
1668 5
1669 pppd terminated because it was sent a SIGINT, SIGTERM or SIGHUP
1670 signal.
1671
1672
1673 6
1674 The serial port could not be locked.
1675
1676
1677 7
1678 The serial port could not be opened.
1679
1680
1681 8
1682 The connect script failed and returned a non-zero exit status.
1683
1684
1685 9
1686 The command specified as the argument to the pty option could
1687 not be run.
1688
1689
1690 10
1691 The PPP negotiation failed because no network protocols were
1692 able to run.
1693
1694
1695 11
1696 The peer system failed or refused to authenticate itself.
1697
1698
1699 12
1700 The link was established successfully, but terminated because it
1701 was idle.
1702
1703
1704 13
1705 The link was established successfully, but terminated because
1706 the connect time limit was reached.
1707
1708
1709 14
1710 Callback was negotiated and an incoming call should arrive
1711 shortly.
1712
1713
1714 15
1715 The link was terminated because the peer is not responding to
1716 echo requests.
1717
1718
1719 16
1720 The link was terminated by the modem hanging up.
1721
1722
1723 17
1724 The PPP negotiation failed because serial loopback was detected.
1725
1726
1727 18
1728 The init script failed because a non-zero exit status was
1729 returned.
1730
1731
1732 19
1733 Authentication to the peer failed.
1734
1735
1736 FILES
1737 /var/run/spppn.pid
1738 Process-ID for pppd process on PPP
1739 interface unit n.
1740
1741
1742 /var/run/ppp-name.pid
1743 Process-ID for pppd process for logical
1744 link name (see the linkname option).
1745
1746
1747 /etc/ppp/pap-secrets
1748 Usernames, passwords and IP addresses for
1749 PAP authentication. This file should be
1750 owned by root and not readable or writable
1751 by any other user, otherwise pppd will log
1752 a warning.
1753
1754
1755 /etc/ppp/chap-secrets
1756 Names, secrets and IP addresses for all
1757 forms of CHAP authentication. The
1758 /etc/ppp/pap-secrets file should be owned
1759 by root should not readable or writable by
1760 any other user, otherwise, pppd will log a
1761 warning.
1762
1763
1764 /etc/ppp/options
1765 System default options for pppd, read
1766 before user default options or command-
1767 line options.
1768
1769
1770 $HOME/.ppprc
1771 User default options, read before
1772 /etc/ppp/options.ttyname.
1773
1774
1775 /etc/ppp/options.ttyname
1776 System default options for the serial port
1777 in use; read after $HOME/.ppprc. The
1778 ttyname component of this filename is
1779 formed when the initial /dev/ is stripped
1780 from the port name (if present), and
1781 slashes (if any) are converted to dots.
1782
1783
1784 /etc/ppp/peers
1785 Directory with options files that may
1786 contain privileged options, even if pppd
1787 was invoked by a user other than root. The
1788 system administrator can create options
1789 files in this directory to permit non-
1790 privileged users to dial out without
1791 requiring the peer to authenticate, but
1792 only to certain trusted peers.
1793
1794
1795 ATTRIBUTES
1796 See attributes(5) for descriptions of the following attributes:
1797
1798
1799
1800
1801 +--------------------+-----------------+
1802 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
1803 +--------------------+-----------------+
1804 |Interface Stability | Evolving |
1805 +--------------------+-----------------+
1806
1807 SEE ALSO
1808 chat(1M), ifconfig(1M), crypt(3C), pam(3PAM), attributes(5)
1809
1810
1811 Haskin, D., Allen, E. RFC 2472 - IP Version 6 Over PPP. Network Working
1812 Group. December 1998.
1813
1814
1815 Jacobson, V. RFC 1144, Compressing TCP/IP Headers for Low-Speed Serial
1816 Links. Network Working Group. February, 1990
1817
1818
1819 Lloyd, B., Simpson, W. RFC 1334, PPP Authentication Protocols. Network
1820 Working Group. October 1992.
1821
1822
1823 McGregor, G. RFC 1332, The PPP Internet Protocol Control Protocol
1824 (IPCP). Network Working Group. May 1992.
1825
1826
1827 Rivest, R. RFC 1321, The MD5 Message-Digest Algorithm. Network Working
1828 Group. April 1992
1829
1830
1831 Simpson, W. RFC 1661, The Point-to-Point Protocol (PPP). Network
1832 Working Group. July 1994.
1833
1834
1835 Simpson, W. RFC 1662, HDLC-like Framing . Network Working Group. July
1836 1994.
1837
1838 NOTES
1839 These signals affect pppd behavior:
1840
1841 SIGINT, SIGTERM
1842 Terminate the link, restore the serial device
1843 settings and exit.
1844
1845
1846 SIGHUP
1847 Terminate the link, restore the serial device
1848 settings and close the serial device. If the
1849 persist or demand option is specified, pppd
1850 attempts to reopen the serial device and start
1851 another connection after the holdoff period.
1852 Otherwise pppd exits. If received during the
1853 holdoff period, SIGHUP causes pppd to end the
1854 holdoff period immediately.
1855
1856
1857 SIGUSR1
1858 Toggles the state of the debug option and prints
1859 link status information to the log.
1860
1861
1862 SIGUSR2
1863 Causes pppd to renegotiate compression. This is
1864 useful to re-enable compression after it has been
1865 disabled as a result of a fatal decompression
1866 error. (Fatal decompression errors generally
1867 indicate a bug in an implementation.)
1868
1869
1870 DIAGNOSTICS
1871 Messages are sent to the syslog daemon using facility LOG_DAEMON. To
1872 see error and debug messages, edit the /etc/syslog.conf file to direct
1873 the messages to the desired output device or file, or use the updetach
1874 or logfile options.
1875
1876
1877 The debug option causes the contents of all LCP, PAP, CHAP or IPCP
1878 control packets sent or received to be logged. This is useful if PPP
1879 negotiation does not succeed or if authentication fails.
1880
1881
1882 Debugging can also be enabled or disabled by sending a SIGUSR1 signal,
1883 which acts as a toggle to the pppd process.
1884
1885 February 5, 2022 PPPD(1M)