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