pppd.8: conversion to mdoc(7)
[dragonfly.git] / usr.sbin / pppd / pppd.8
1 .Dd August 31, 2013
2 .Dt PPPD 8
3 .Os
4 .Sh NAME
5 .Nm pppd
6 .Nd Point-to-Point Protocol daemon
8 .Nm
9 .Op Ar tty_name
10 .Op Ar speed
11 .Op Ar options
13 The Point-to-Point Protocol (PPP) provides a method for transmitting
14 datagrams over serial point-to-point links.
15 PPP is composed of three parts: a method for encapsulating datagrams over
16 serial links, an extensible Link Control Protocol (LCP), and
17 a family of Network Control Protocols (NCP) for establishing
18 and configuring different network-layer protocols.
19 .Pp
20 The encapsulation scheme is provided by driver code in the kernel.
21 .Nm
22 provides the basic LCP, authentication support, and an NCP for
23 establishing and configuring the Internet Protocol (IP) (called the IP
24 Control Protocol, IPCP).
26 .Bl -ohang -offset indent
27 .It Ar tty_name
28 Communicate over the named device.
29 The string
30 .Dq /dev/
31 is prepended if necessary.
32 If no device name is given, or if the name of the terminal
33 connected to the standard input is given,
34 .Nm
35 will use that terminal, and will not fork to put itself in the
36 background.
37 This option is privileged if the
38 .Cm noauth
39 option is used.
40 .It Ar speed
41 Set the baud rate to
42 .Ar speed
43 (a decimal number).
44 On systems such as
45 .Bx 4.4
46 and
47 .Nx ,
48 any speed can be specified, providing that it is
49 supported by the serial device driver.
50 Other systems (e.g. SunOS, Linux) allow only a limited set of speeds.
51 .It Cm active-filter Ar filter-expression
52 Specifies a packet filter to be applied to data packets to determine
53 which packets are to be regarded as link activity, and therefore reset
54 the idle timer, or cause the link to be brought up in demand-dialling
55 mode.
56 This option is useful in conjunction with the
57 .Cm idle
58 option if there are packets being sent or received
59 regularly over the link (for example, routing information packets)
60 which would otherwise prevent the link from ever appearing to be idle.
61 The
62 .Ar filter-expression
63 syntax is as described for
64 .Xr tcpdump 1 ,
65 except that qualifiers which are inappropriate for a PPP link, such as
66 .Cm ether
67 and
68 .Cm arp ,
69 are not permitted.
70 Generally the filter
71 expression should be enclosed in single-quotes to prevent whitespace
72 in the expression from being interpreted by the shell.
73 This option is only available if both the kernel and
74 .Nm
75 were compiled with
77 defined.
78 .It Cm asyncmap Ar map
79 Set the async character map to
80 .Ar map .
81 This map describes which control characters cannot be successfully
82 received over the serial line.
83 .Nm
84 will ask the peer to send these characters as a 2-byte
85 escape sequence.
86 The argument is a 32 bit hex number with each bit
87 representing a character to escape.
88 Bit 0 (00000001) represents the character 0x00;
89 bit 31 (80000000) represents the character 0x1f or ^_.
90 If multiple
91 .Cm asyncmap
92 options are given, the values are ORed together.
93 If no
94 .Cm asyncmap
95 option is given, no async character
96 map will be negotiated for the receive direction;
97 the peer should then escape all control characters.
98 To escape transmitted characters, use the
99 .Cm escape
100 option.
101 .It Cm auth
102 Require the peer to authenticate itself before allowing network
103 packets to be sent or received.
104 .It Cm call Ar name
105 Read options from the file
106 .Pa /etc/ppp/peers/ Ns Ar name .
107 This file may contain privileged options, such as
108 .Cm noauth ,
109 even if
110 .Nm
111 is not being run by root.
112 The
113 .Ar name
114 string may not begin with
115 .Dq /
116 or include
117 .Dq ..
118 as a pathname component.
119 The format of the options file is described below.
120 .It Cm connect Ar script
121 Use the executable or shell command specified by
122 .Ar script
123 to set up the serial line.
124 This script would typically use the
125 .Xr chat 8
126 program to dial the modem and start the remote ppp session.
127 This option is privileged if the
128 .Cm noauth
129 option is used.
130 .It Cm connect-max-attempts Ar number
131 Attempt dial-out connection to remote system no more than specified
132 .Ar number
133 of times.
134 The default is 1.
135 If the connection is not made,
136 .Nm
137 will exit.
138 Requires that
139 .Cm persist
140 has been specified.
141 .It Cm crtscts
142 Use hardware flow control (i.e. RTS/CTS) to control the flow of data
143 on the serial port.
144 If neither the
145 .Cm crtscts
146 nor the
147 .Cm nocrtscts
148 option is given, the hardware flow control setting
149 for the serial port is left unchanged.
150 .It Cm defaultroute
151 Add a default route to the system routing tables, using the peer as
152 the gateway, when IPCP negotiation is successfully completed.
153 This entry is removed when the PPP connection is broken.
154 This option is privileged if the
155 .Cm nodefaultroute
156 option has been specified.
157 .It Cm disconnect Ar script
158 Run the executable or shell command specified by
159 .Ar script
160 after
161 .Nm
162 has terminated the link.
163 This script could, for example, issue commands to the modem to cause
164 it to hang up if hardware modem control signals were not available.
165 The disconnect script is not run if the modem has already hung up.
166 This option is privileged if the
167 .Cm noauth
168 option is used.
169 .It Cm escape Ar xx,yy,...
170 Specifies that certain characters should be escaped on transmission
171 (regardless of whether the peer requests them to be escaped with its
172 async control character map).
173 The characters to be escaped are specified as a list of hex numbers
174 separated by commas.
175 Note that almost any character can be specified for the
176 .Cm escape
177 option, unlike the
178 .Cm asyncmap
179 option which only allows control characters to be specified.
180 The characters which may not be escaped are those
181 with hex values 0x20 to 0x3f or 0x5e.
182 .It Cm file Ar name
183 Read options from file
184 .Ar name
185 (the format is described below).
186 The file must be readable by the user who has invoked
187 .Nm .
188 .It Cm lock
189 Specifies that
190 .Nm
191 should create a UUCP-style lock file for the
192 serial device to ensure exclusive access to the device.
193 .It Cm mru Ar size
194 Set the Maximum Receive Unit (MRU) value to
195 .Ar size .
196 .Nm
197 will ask the peer to send packets of no more than
198 .Ar size
199 bytes.
200 The minimum MRU value is 128.
201 The default MRU value is 1500.
202 A value of 296 is recommended for slow links
203 (40 bytes for TCP/IP header + 256 bytes of data).
204 .It Cm mtu Ar size
205 Set the Maximum Transmit Unit (MTU) value to
206 .Ar size .
207 Unless the peer requests a smaller value via MRU negotiation,
208 .Nm
209 will request that the kernel networking code send data packets of no more
210 than
211 .Ar size
212 bytes through the PPP network interface.
213 .It Cm passive
214 Enables the
215 .Dq passive
216 option in the LCP.
217 With this option,
218 .Nm
219 will attempt to initiate a connection;
220 if no reply is received from the peer,
221 .Nm
222 will then just wait passively for a valid LCP packet from
223 the peer, instead of exiting, as it would without this option.
224 .El
226 .Bl -ohang -offset indent
227 .It Ar local_IP_address Ns Li : Ns Ar remote_IP_address
228 Set the local and/or remote interface IP addresses.
229 Either one may be omitted.
230 The IP addresses can be specified with a host name or in
231 decimal dot notation (e.g.
232 The default local
233 address is the (first) IP address of the system (unless the
234 .Cm noipdefault
235 option is given).
236 The remote address will be obtained from the peer
237 if not specified in any option.
238 Thus, in simple cases, this option is not required.
239 If a local and/or remote IP address is specified with
240 this option,
241 .Nm
242 will not accept a different value from the peer in the IPCP
243 negotiation, unless the
244 .Cm ipcp-accept-local
245 and/or
246 .Cm ipcp-accept-remote
247 options are given, respectively.
248 .It Cm bsdcomp Ar nr Ns Li , Ns Ar nt
249 Request that the peer compress packets that it sends, using the
250 BSD-Compress scheme, with a maximum code size of
251 .Ar nr
252 bits, and
253 agree to compress packets sent to the peer with a maximum code size of
254 .Ar nt
255 bits.
256 If
257 .Ar nt
258 is not specified, it defaults to the value given for
259 .Ar nr .
260 Values in the range 9 to 15 may be used for
261 .Ar nr
262 and
263 .Ar nt ;
264 larger values give better compression but
265 consume more kernel memory for compression dictionaries.
266 Alternatively, a value of 0 for
267 .Ar nr
268 or
269 .Ar nt
270 disables compression in the corresponding direction.
271 Use
272 .Cm nobsdcomp
273 or
274 .Cm bsdcomp Li 0
275 to disable BSD-Compress compression entirely.
276 .It Cm chap-interval Ar number
277 If this option is given,
278 .Nm
279 will rechallenge the peer every
280 .Ar number
281 seconds.
282 .It Cm chap-max-challenge Ar number
283 Set the maximum number of CHAP challenge transmissions to
284 .Ar number .
285 The default is 10.
286 .It Cm chap-restart Ar number
287 Set the CHAP restart interval (retransmission timeout for challenges)
288 to
289 .Ar number
290 seconds.
291 The default is 3.
292 .It Cm debug
293 Enables connection debugging facilities.
294 If this option is given,
295 .Nm
296 will log the contents of all
297 control packets sent or received in a readable form.
298 The packets are logged through syslog with facility
299 .Sy daemon
300 and level
301 .Sy debug .
302 This information can be directed to a file by setting up
303 .Pa /etc/syslog.conf
304 appropriately (see
305 .Xr syslog.conf 5 ) .
306 .It Cm default-asyncmap
307 Disable asyncmap negotiation, forcing all control characters to be
308 escaped for both the transmit and the receive direction.
309 .It Cm default-mru
310 Disable Maximum Receive Unit (MRU) negotiation.
311 With this option,
312 .Nm
313 will use the default MRU value of 1500 bytes for both the
314 transmit and receive direction.
315 .It Cm deflate Ar nr Ns Li , Ns Ar nt
316 Request that the peer compress packets that it sends, using the
317 Deflate scheme, with a maximum window size of
318 .Li 2** Ns Ar nr
319 bytes, and agree to compress packets sent to the peer with a
320 maximum window size of
321 .Li 2** Ns Ar nt
322 bytes.
323 If
324 .Ar nt
325 is not specified, it defaults to the value given for
326 .Ar nr .
327 Values in the range 8 to 15 may be used for
328 .Ar nr
329 and
330 .Ar nt ;
331 larger values give better compression but
332 consume more kernel memory for compression dictionaries.
333 Alternatively, a value of 0 for
334 .Ar nr
335 or
336 .Ar nt
337 disables compression in the corresponding direction.
338 Use
339 .Cm nodeflate
340 or
341 .Cm deflate Li 0
342 to disable Deflate compression entirely.
343 Note:
344 .Nm
345 requests Deflate compression in preference to BSD-Compress if the peer
346 can do either.
347 .It Cm demand
348 Initiate the link only on demand, i.e. when data traffic is present.
349 With this option, the remote IP address must be specified by the user
350 on the command line or in an options file.
351 .Nm
352 will initially
353 configure the interface and enable it for IP traffic without
354 connecting to the peer.
355 When traffic is available,
356 .Nm
357 will connect to the peer and perform negotiation, authentication, etc.
358 When this is completed,
359 .Nm
360 will commence passing data packets
361 (i.e. IP packets) across the link.
362 The
363 .Cm demand
364 option implies the
365 .Cm persist
366 option.
367 If this behaviour is not desired, use the
368 .Cm nopersist
369 option after the
370 .Cm demand
371 option.
372 The
373 .Cm idle
374 and
375 .Cm holdoff
376 options are also useful in conjunction with the
377 .Cm demand
378 option.
379 .It Cm domain Ar name
380 Append the domain name
381 .Ar name
382 to the local host name for authentication purposes.
383 For example, if gethostname() returns the name
384 .Sq porsche ,
385 but the fully qualified domain name is
386 .Sq porsche.quotron.com ,
387 you could specify
388 .Cm domain Li quotron.com .
389 .Nm
390 would then use the name
391 .Sq porsche.quotron.com
392 for looking up secrets in the secrets file, and as the default name
393 to send to the peer when authenticating itself to the peer.
394 This option is privileged.
395 .It Cm holdoff Ar number
396 Specifies how many seconds to wait before re-initiating the link after
397 it terminates.
398 This option only has any effect if the
399 .Cm persist
400 or
401 .Cm demand
402 option is used.
403 The holdoff period is not applied if
404 the link was terminated because it was idle.
405 .It Cm idle Ar number
406 Specifies that
407 .Nm
408 should disconnect if the link is idle for
409 .Ar number
410 seconds.
411 The link is idle when no data packets (i.e. IP packets) are
412 being sent or received.
413 If the
414 .Cm active-filter
415 option is given, data packets which are rejected by the specified
416 activity filter also count as the link being idle.
417 Note: it is not advisable to use this option with the
418 .Cm persist
419 option without the
420 .Cm demand
421 option.
422 .It Cm ipcp-accept-local
423 With this option,
424 .Nm
425 will accept the peer's idea of our local IP
426 address, even if the local IP address was specified in an option.
427 .It Cm ipcp-accept-remote
428 With this option,
429 .Nm
430 will accept the peer's idea of its (remote) IP
431 address, even if the remote IP address was specified in an option.
432 .It Cm ipcp-max-configure Ar number
433 Set the maximum number of IPCP configure-request transmissions to
434 .Ar number .
435 The default is 10.
436 .It Cm ipcp-max-failure Ar number
437 Set the maximum number of IPCP configure-NAKs returned before starting
438 to send configure-Rejects instead to
439 .Ar number .
440 The default is 10.
441 .It Cm ipcp-max-terminate Ar number
442 Set the maximum number of IPCP terminate-request transmissions to
443 .Ar number .
444 The default is 3.
445 .It Cm ipcp-restart Ar number
446 Set the IPCP restart interval (retransmission timeout) to
447 .Ar number
448 seconds.
449 The default is 3.
450 .It Cm ipparam Ar string
451 Provides an extra parameter to the ip-up and ip-down scripts.
452 If this option is given, the
453 .Ar string
454 supplied is given as the 6th
455 parameter to those scripts.
456 .It Cm ipx
457 Enable the IPXCP and IPX protocols.
458 This option is presently only supported under Linux, and only if your
459 kernel has been configured to include IPX support.
460 .It Cm ipx-network Ar number
461 Set the IPX network number in the IPXCP configure request frame to
462 .Ar number ,
463 a hexadecimal number (without a leading 0x).
464 There is no valid default.
465 If this option is not specified, the network number is
466 obtained from the peer.
467 If the peer does not have the network number,
468 the IPX protocol will not be started.
469 .It Cm ipx-node Ar local Ns Li : Ns Ar remote
470 Set the IPX node numbers.
471 The two node numbers are separated from each
472 other with a colon character.
473 The first number
474 .Ar local
475 is the local node number.
476 The second number
477 .Ar remote
478 is the peer's node number.
479 Each node number is a hexadecimal number, at most 10 digits long.
480 The node numbers on the ipx-network must be unique.
481 There is no valid default.
482 If this option is not specified then the node numbers are
483 obtained from the peer.
484 .It Cm ipx-router-name Ar string
485 Set the name of the router.
486 This is a string and is sent to the peer
487 as information data.
488 .It Cm ipx-routing Ar protocol
489 Set the routing protocol to be received by this option.
490 More than one instance of
491 .Cm ipx-routing
492 may be specified.
493 The values may be 0 for NONE, 2 for IRIP/SAP, and 4 for NLSP.
494 The NONE option may be specified as the only instance of ipx-routing.
495 .It Cm ipxcp-accept-local
496 Accept the peer's NAK for the node number specified in the ipx-node
497 option.
498 If a node number was specified, and non-zero, the default is
499 to insist that the value be used.
500 If you include this option then you
501 will permit the peer to override the entry of the node number.
502 .It Cm ipxcp-accept-network
503 Accept the peer's NAK for the network number specified in the
504 ipx-network option.
505 If a network number was specified, and non-zero, the
506 default is to insist that the value be used.
507 If you include this
508 option then you will permit the peer to override the entry of the node
509 number.
510 .It Cm ipxcp-accept-remote
511 Use the peer's network number specified in the configure request
512 frame.
513 If a node number was specified for the peer and this option was
514 not specified, the peer will be forced to use the value which you have
515 specified.
516 .It Cm ipxcp-max-configure Ar number
517 Set the maximum number of IPXCP configure request frames which the
518 system will send.
519 The default is 10.
520 .It Cm ipxcp-max-failure Ar number
521 Set the maximum number of IPXCP NAK frames which the local system will
522 send before it rejects the options.
523 The default is 3.
524 .It Cm ipxcp-max-terminate Ar number
525 Set the maximum number of IPXCP terminate request frames before the
526 local system considers that the peer is not listening to them.
527 The default is 3.
528 .It Cm kdebug Ar level
529 Enable debugging code in the kernel-level PPP driver.
530 The argument
531 .Ar level
532 is a number which is the sum of the following values: 1 to
533 enable general debug messages, 2 to request that the contents of
534 received packets be printed, and 4 to request that the contents of
535 transmitted packets be printed.
536 On most systems, messages printed by the kernel are logged by
537 .Xr syslog 1 ,
538 to a file as directed in the
539 .Pa /etc/syslog.conf
540 configuration file.
541 .It Cm lcp-echo-failure Ar number
542 If this option is given,
543 .Nm
544 will presume the peer to be dead if
545 .Ar number
546 LCP echo-requests are sent without receiving a valid LCP echo-reply.
547 If this happens,
548 .Nm
549 will terminate the connection.
550 Use of this option requires a non-zero value for the
551 .Cm lcp-echo-interval
552 parameter.
553 This option can be used to enable
554 .Nm
555 to terminate after the physical connection has been broken
556 (e.g., the modem has hung up) in situations where no hardware modem
557 control lines are available.
558 .It Cm lcp-echo-interval Ar number
559 If this option is given,
560 .Nm
561 will send an LCP echo-request frame to the peer every
562 .Ar number
563 seconds.
564 Normally the peer should respond to
565 the echo-request by sending an echo-reply.
566 This option can be used
567 with the
568 .Cm lcp-echo-failure
569 option to detect that the peer is no longer connected.
570 .It Cm lcp-max-configure Ar number
571 Set the maximum number of LCP configure-request transmissions to
572 .Ar number .
573 The default is 10.
574 .It Cm lcp-max-failure Ar number
575 Set the maximum number of LCP configure-NAKs returned before starting
576 to send configure-Rejects instead to
577 .Ar number .
578 The default is 10.
579 .It Cm lcp-max-terminate Ar number
580 Set the maximum number of LCP terminate-request transmissions to
581 .Ar number .
582 The default is 3.
583 .It Cm lcp-restart Ar number
584 Set the LCP restart interval (retransmission timeout) to
585 .Ar number
586 seconds.
587 The default is 3.
588 .It Cm local
589 Don't use the modem control lines.
590 With this option,
591 .Nm
592 will ignore
593 the state of the CD (Carrier Detect) signal from the modem and will
594 not change the state of the DTR (Data Terminal Ready) signal.
595 .It Cm login
596 Use the system password database for authenticating the peer using
597 PAP, and record the user in the system wtmp file.
598 Note that the peer must have an entry in the
599 .Pa /etc/ppp/pap-secrets
600 file as well as the system password database to be allowed access.
601 .It Cm maxconnect Ar number
602 Terminate the connection when it has been available for network
603 traffic for
604 .Ar number
605 seconds (i.e.\&
606 .Ar number
607 seconds after the first network control protocol comes up).
608 .It Cm modem
609 Use the modem control lines.
610 This option is the default.
611 With this option,
612 .Nm
613 will wait for the CD (Carrier Detect) signal from the
614 modem to be asserted when opening the serial device (unless a connect
615 script is specified), and it will drop the DTR (Data Terminal Ready)
616 signal briefly when the connection is terminated and before executing
617 the connect script.
618 On Ultrix, this option implies hardware flow control, as for the
619 .Cm crtscts
620 option.
621 .It Cm ms-dns Ar address
622 If
623 .Nm
624 is acting as a server for Microsoft Windows clients, this
625 option allows
626 .Nm
627 to supply one or two DNS (Domain Name Server) addresses to the clients.
628 The first instance of this option specifies the primary DNS address;
629 the second instance (if given) specifies the secondary DNS address.
630 Note: this option was present in some older versions of
631 .Nm
632 under the name
633 .Cm dns-addr .
634 .It Cm ms-wins Ar address
635 If
636 .Nm
637 is acting as a server for Microsoft Windows or Samba
638 clients, this option allows
639 .Nm
640 to supply one or two WINS (Windows
641 Internet Name Services) server addresses to the clients.
642 The first instance of this option specifies the primary WINS address;
643 the second instance (if given) specifies the secondary WINS address.
644 .It Cm name Ar name
645 Set the name of the local system for authentication purposes to
646 .Ar name .
647 This is a privileged option.
648 With this option,
649 .Nm
650 will use lines in the secrets files which have
651 .Ar name
652 as the second
653 field when looking for a secret to use in authenticating the peer.
654 In addition, unless overridden with the
655 .Cm user
656 option,
657 .Cm name
658 will be used as the name to send to the peer when authenticating the
659 local system to the peer.
660 Note:
661 .Nm
662 does not append the domain name to
663 .Ar name .
664 .It Cm netmask Ar mask
665 Set the interface netmask to
666 .Ar mask ,
667 a 32 bit netmask in decimal dot notation (e.g.
668 If this option is given, the value
669 specified is ORed with the default netmask.
670 The default netmask is chosen based on the negotiated remote IP address;
671 it is the
672 appropriate network mask for the class of the remote IP address, ORed
673 with the netmasks for any non point-to-point network interfaces in the
674 system which are on the same network.
675 .It Cm noaccomp
676 Disable Address/Control compression in both directions (send and
677 receive).
678 .It Cm noauth
679 Do not require the peer to authenticate itself.
680 This option is privileged if the
681 .Cm auth
682 option is specified in
683 .Pa /etc/ppp/options .
684 .It Cm nobsdcomp
685 Disables BSD-Compress compression;
686 .Nm
687 will not request or
688 agree to compress packets using the BSD-Compress scheme.
689 .It Cm noccp
690 Disable Compression Control Protocol (CCP) negotiation.
691 This option
692 should only be required if the peer is buggy and gets confused by
693 requests from
694 .Nm
695 for CCP negotiation.
696 .It Cm nocrtscts
697 Disable hardware flow control (i.e. RTS/CTS) on the serial port.
698 If neither the
699 .Cm crtscts
700 nor the
701 .Cm nocrtscts
702 option is given, the hardware flow control setting for the serial
703 port is left unchanged.
704 .It Cm nodefaultroute
705 Disable the
706 .Cm defaultroute
707 option.
708 The system administrator who
709 wishes to prevent users from creating default routes with
710 .Nm
711 can do so by placing this option in the
712 .Pa /etc/ppp/options
713 file.
714 .It Cm nodeflate
715 Disables Deflate compression;
716 .Nm
717 will not request or agree to compress packets using the Deflate scheme.
718 .It Cm nodetach
719 Don't detach from the controlling terminal.
720 Without this option, if a
721 serial device other than the terminal on the standard input is
722 specified,
723 .Nm
724 will fork to become a background process.
725 .It Cm noip
726 Disable IPCP negotiation and IP communication.
727 This option should only be required if the peer is buggy and gets
728 confused by requests from
729 .Nm
730 for IPCP negotiation.
731 .It Cm noipdefault
732 Disables the default behaviour when no local IP address is specified,
733 which is to determine (if possible) the local IP address from the
734 hostname.
735 With this option, the peer will have to supply the local IP
736 address during IPCP negotiation (unless it specified explicitly on the
737 command line or in an options file).
738 .It Cm noipx
739 Disable the IPXCP and IPX protocols.
740 This option should only be
741 required if the peer is buggy and gets confused by requests from
742 .Nm
743 for IPXCP negotiation.
744 .It Cm nomagic
745 Disable magic number negotiation.
746 With this option,
747 .Nm
748 cannot detect a looped-back line.
749 This option should only be needed if the peer is buggy.
750 .It Cm nopcomp
751 Disable protocol field compression negotiation in both the receive and
752 the transmit direction.
753 .It Cm nopersist
754 Exit once a connection has been made and terminated.
755 This is the default unless the
756 .Cm persist
757 or
758 .Cm demand
759 option has been specified.
760 .It Cm nopredictor1
761 Do not accept or agree to Predictor-1 compression.
762 .It Cm noproxyarp
763 Disable the
764 .Cm proxyarp
765 option.
766 The system administrator who
767 wishes to prevent users from creating proxy ARP entries with
768 .Nm
769 can do so by placing this option in the
770 .Pa /etc/ppp/options
771 file.
772 .It Cm novj
773 Disable Van Jacobson style TCP/IP header compression in both the
774 transmit and the receive direction.
775 .It Cm novjccomp
776 Disable the connection-ID compression option in Van Jacobson style
777 TCP/IP header compression.
778 With this option,
779 .Nm
780 will not omit the connection-ID byte from Van Jacobson compressed
781 TCP/IP headers, nor ask the peer to do so.
782 .It Cm papcrypt
783 Indicates that all secrets in the
784 .Pa /etc/ppp/pap-secrets
785 file which are
786 used for checking the identity of the peer are encrypted, and thus
787 .Nm
788 should not accept a password which, before encryption, is
789 identical to the secret from the
790 .Pa /etc/ppp/pap-secrets
791 file.
792 .It Cm pap-max-authreq Ar number
793 Set the maximum number of PAP authenticate-request transmissions to
794 .Ar number .
795 The default is 10.
796 .It Cm pap-restart Ar number
797 Set the PAP restart interval (retransmission timeout) to
798 .Ar number
799 seconds.
800 The default is 3.
801 .It Cm pap-timeout Ar number
802 Set the maximum time that
803 .Nm
804 will wait for the peer to authenticate itself with PAP to
805 .Ar number
806 seconds (0 means no limit).
807 .It Cm pass-filter Ar filter-expression
808 Specifies a packet filter to applied to data packets being sent or
809 received to determine which packets should be allowed to pass.
810 Packets which are rejected by the filter are silently discarded.
811 This
812 option can be used to prevent specific network daemons (such as
813 routed) using up link bandwidth, or to provide a basic firewall
814 capability.
815 The
816 .Ar filter-expression
817 syntax is as described for
818 .Xr tcpdump 1 ,
819 except that qualifiers which are inappropriate for a PPP link, such as
820 .Cm ether
821 and
822 .Cm arp , are not permitted.
823 Generally the filter
824 expression should be enclosed in single-quotes to prevent whitespace
825 in the expression from being interpreted by the shell.
826 Note that it
827 is possible to apply different constraints to incoming and outgoing
828 packets using the
829 .Cm inbound
830 and
831 .Cm outbound
832 qualifiers.
833 This option is currently only available under
834 .Nx ,
835 and then only if both the kernel and
836 .Nm
837 were compiled with
839 defined.
840 .It Cm persist
841 Do not exit after a connection is terminated; instead try to reopen
842 the connection.
843 .It Cm predictor1
844 Request that the peer compress frames that it sends using Predictor-1
845 compression, and agree to compress transmitted frames with Predictor-1
846 if requested.
847 This option has no effect unless the kernel driver
848 supports Predictor-1 compression.
849 .It Cm proxyarp
850 Add an entry to this system's Address Resolution Protocol (ARP) table
851 with the IP address of the peer and the Ethernet address of this
852 system.
853 This will have the effect of making the peer appear to other
854 systems to be on the local ethernet.
855 .It Cm remotename Ar name
856 Set the assumed name of the remote system for authentication purposes
857 to
858 .Ar name .
859 .It Cm refuse-chap
860 With this option,
861 .Nm
862 will not agree to authenticate itself to the peer using CHAP.
863 .It Cm refuse-pap
864 With this option,
865 .Nm
866 will not agree to authenticate itself to the peer using PAP.
867 .It Cm require-chap
868 Require the peer to authenticate itself using Challenge
869 Handshake Authentication Protocol (CHAP) authentication.
870 .It Cm require-pap
871 Require the peer to authenticate itself using Password
872 Authentication Protocol (PAP) authentication.
873 .It Cm silent
874 With this option,
875 .Nm
876 will not transmit LCP packets to initiate a connection until
877 a valid LCP packet is received from the peer (as for the
878 .Sq passive
879 option with ancient versions of
880 .Nm ) .
881 .It Cm usehostname
882 Enforce the use of the hostname (with domain name appended, if given)
883 as the name of the local system for authentication purposes (overrides
884 the
885 .Cm name
886 option).
887 .It Cm user Ar name
888 Sets the name used for authenticating the local system to the peer to
889 .Ar name .
890 .It Cm vj-max-slots Ar number
891 Sets the number of connection slots to be used by the Van Jacobson
892 TCP/IP header compression and decompression code to
893 .Ar number ,
894 which must be between 2 and 16 inclusively.
895 .It Cm welcome Ar script
896 Run the executable or shell command specified by
897 .Ar script
898 before initiating PPP negotiation, after the connect script
899 (if any) has completed.
900 This option is privileged if the
901 .Cm noauth
902 option is used.
903 .It Cm xonxoff
904 Use software flow control (i.e. XON/XOFF) to control the flow of data on
905 the serial port.
906 .El
908 The following signals have the specified effect when sent to
909 .Nm :
910 .Bl -tag -width ".Dv SIGINT Ns , Dv SIGTERM" -offset indent
912 These signals cause
913 .Nm
914 to terminate the link (by closing LCP),
915 restore the serial device settings, and exit.
916 .It Dv SIGHUP
917 This signal causes
918 .Nm
919 to terminate the link, restore the serial
920 device settings, and close the serial device.
921 If the
922 .Cm persist
923 or
924 .Cm demand
925 option has been specified,
926 .Nm
927 will try to reopen the
928 serial device and start another connection (after the holdoff period).
929 Otherwise
930 .Nm
931 will exit.
932 If this signal is received during the holdoff period, it causes
933 .Nm
934 to end the holdoff period immediately.
935 .It Dv SIGUSR1
936 This signal toggles the state of the
937 .Cm debug
938 option.
939 .It Dv SIGUSR2
940 This signal causes
941 .Nm
942 to renegotiate compression.
943 This can be
944 useful to re-enable compression after it has been disabled as a result
945 of a fatal decompression error.
946 (Fatal decompression errors generally
947 indicate a bug in one or other implementation.)
948 .El
950 .Nm
951 provides system administrators with sufficient access control that PPP
952 access to a server machine can be provided to legitimate users without
953 fear of compromising the security of the server or the network it's on.
954 In part this is provided by the
955 .Pa /etc/ppp/options
956 file, where the administrator can place options to restrict the ways in which
957 .Nm
958 can be used, and in part by the PAP and CHAP secrets files, where the
959 administrator can restrict the set of IP addresses which individual
960 users may use.
961 .Pp
962 The normal way that
963 .Nm
964 should be set up is to have the
965 .Cm auth
966 option in the
967 .Pa /etc/ppp/options
968 file.
969 (This may become the default in later releases.)
970 If users wish to use
971 .Nm
972 to dial out to a peer which will refuse to authenticate itself
973 (such as an internet service provider), the system administrator
974 should create an options file under
975 .Pa /etc/ppp/peers
976 containing the
977 .Cm noauth
978 option, the name of the serial port to use, and the
979 .Cm connect
980 option (if required), plus any other appropriate options.
981 In this way,
982 .Nm
983 can be set up
984 to allow non-privileged users to make unauthenticated connections only
985 to trusted peers.
986 .Pp
987 As indicated above, some security-sensitive options are privileged,
988 which means that they may not be used by an ordinary non-privileged
989 user running a setuid-root
990 .Nm ,
991 either on the command line, in the user's
992 .Pa ~/.ppprc
993 file, or in an options file read using the
994 .Cm file
995 option.
996 Privileged options may be used in
997 .Pa /etc/ppp/options
998 file or in an options file read using the
999 .Cm call
1000 option.
1001 If
1002 .Nm
1003 is being run by the root user, privileged options can be used without
1004 restriction.
1006 Authentication is the process whereby one peer convinces the other of
1007 its identity.
1008 This involves the first peer sending its name to the
1009 other, together with some kind of secret information which could only
1010 come from the genuine authorized user of that name.
1011 In such an
1012 exchange, we will call the first peer the
1013 .Sy client
1014 and the other the
1015 .Sy server .
1016 The client has a name by which it identifies itself to the
1017 server, and the server also has a name by which it identifies itself
1018 to the client.
1019 Generally the genuine client shares some secret (or
1020 password) with the server, and authenticates itself by proving that it
1021 knows that secret.
1022 Very often, the names used for authentication
1023 correspond to the internet hostnames of the peers, but this is not
1024 essential.
1025 .Pp
1026 At present,
1027 .Nm
1028 supports two authentication protocols: the Password
1029 Authentication Protocol (PAP) and the Challenge Handshake
1030 Authentication Protocol (CHAP).
1031 PAP involves the client sending its
1032 name and a cleartext password to the server to authenticate itself.
1033 In contrast, the server initiates the CHAP authentication exchange by
1034 sending a challenge to the client (the challenge packet includes the
1035 server's name).
1036 The client must respond with a response which
1037 includes its name plus a hash value derived from the shared secret and
1038 the challenge, in order to prove that it knows the secret.
1039 .Pp
1040 The PPP protocol, being symmetrical, allows both peers to require the
1041 other to authenticate itself.
1042 In that case, two separate and
1043 independent authentication exchanges will occur.
1044 The two exchanges
1045 could use different authentication protocols, and in principle,
1046 different names could be used in the two exchanges.
1047 .Pp
1048 The default behaviour of
1049 .Nm
1050 is to agree to authenticate if
1051 requested, and to not require authentication from the peer.
1052 However,
1053 .Nm
1054 will not agree to authenticate itself with a particular protocol
1055 if it has no secrets which could be used to do so.
1056 .Pp
1057 .Nm
1058 stores secrets for use in authentication in secrets
1059 files (
1060 .Pa /etc/ppp/pap-secrets
1061 for PAP,
1062 .Pa /etc/ppp/chap-secrets
1063 for CHAP).
1064 Both secrets files have the same format.
1065 The secrets files can contain secrets for
1066 .Nm
1067 to use in authenticating itself to other
1068 systems, as well as secrets for
1069 .Nm
1070 to use when authenticating other systems to itself.
1071 .Pp
1072 Each line in a secrets file contains one secret.
1073 A given secret is
1074 specific to a particular combination of client and server \(em it can
1075 only be used by that client to authenticate itself to that server.
1076 Thus each line in a secrets file has at least 3 fields: the name of
1077 the client, the name of the server, and the secret.
1078 These fields may
1079 be followed by a list of the IP addresses that the specified client
1080 may use when connecting to the specified server.
1081 .Pp
1082 A secrets file is parsed into words as for an options file, so the
1083 client name, server name and secrets fields must each be one word,
1084 with any embedded spaces or other special characters quoted or
1085 escaped.
1086 Any following words on the same line are taken to be a list
1087 of acceptable IP addresses for that client, or an
1088 override for
1089 .Sy local:remote
1090 addresses (the same format used on the
1091 command line or in the options file) when on a line that contains a
1092 specific client name (not a wildcard nor empty).
1093 If there are only 3 words
1094 on the line, or if the first word is
1095 .Dq \- ,
1096 then all IP addresses are disallowed.
1097 To allow any address, use
1098 .Dq * .
1099 A word starting with
1100 .Dq !
1101 indicates that the specified address is not acceptable.
1102 An address may be followed by
1103 .Dq /
1104 and a number
1105 .Ar number ,
1106 to indicate a whole subnet, i.e. all addresses which have the same
1107 value in the most significant
1108 .Ar number
1109 bits.
1110 Note that case is significant in the client and server names
1111 and in the secret.
1112 .Pp
1113 If the secret starts with an
1114 .Dq @ ,
1115 what follows is assumed to be the
1116 name of a file from which to read the secret.
1117 A
1118 .Dq *
1119 as the client or server name matches any name.
1120 When selecting a secret,
1121 .Nm
1122 takes the best match, i.e. the match with the fewest wildcards.
1123 .Pp
1124 Thus a secrets file contains both secrets for use in authenticating
1125 other hosts, plus secrets which we use for authenticating ourselves to
1126 others.
1127 When
1128 .Nm
1129 is authenticating the peer (checking the peer's
1130 identity), it chooses a secret with the peer's name in the first
1131 field and the name of the local system in the second field.
1132 The name of the local system defaults to the hostname, with the domain
1133 name appended if the
1134 .Cm domain
1135 option is used.
1136 This default can be overridden with the
1137 .Cm name
1138 option, except when the
1139 .Cm usehostname
1140 option is used.
1141 .Pp
1142 When
1143 .Nm
1144 is choosing a secret to use in authenticating itself to the
1145 peer, it first determines what name it is going to use to identify
1146 itself to the peer.
1147 This name can be specified by the user with the
1148 .Cm user
1149 option.
1150 If this option is not used, the name defaults to
1151 the name of the local system, determined as described in the previous
1152 paragraph.
1153 Then
1154 .Nm
1155 looks for a secret with this name in the first
1156 field and the peer's name in the second field.
1157 .Nm
1158 will know the
1159 name of the peer if CHAP authentication is being used, because the
1160 peer will have sent it in the challenge packet.
1161 However, if PAP is being used,
1162 .Nm
1163 will have to determine the peer's name from the options
1164 specified by the user.
1165 The user can specify the peer's name directly with the
1166 .Cm remotename
1167 option.
1168 Otherwise, if the remote IP address
1169 was specified by a name (rather than in numeric form), that name will
1170 be used as the peer's name.
1171 Failing that,
1172 .Nm
1173 will use the null string as the peer's name.
1174 .Pp
1175 When authenticating the peer with PAP, the supplied password is first
1176 compared with the secret from the secrets file.
1177 If the password
1178 doesn't match the secret, the password is encrypted using
1179 .Xr crypt 3
1180 and checked against the secret again.
1181 Thus secrets for authenticating the
1182 peer can be stored in encrypted form if desired.
1183 If the
1184 .Cm papcrypt
1185 option is given, the first (unencrypted) comparison is
1186 omitted, for better security.
1187 .Pp
1188 Furthermore, if the
1189 .Cm login
1190 option was specified, the username and
1191 password are also checked against the system password database.
1192 Thus,
1193 the system administrator can set up the pap-secrets file to allow PPP
1194 access only to certain users, and to restrict the set of IP addresses
1195 that each user can use.
1196 Typically, when using the
1197 .Cm login
1198 option, the secret in
1199 .Pa /etc/ppp/pap-secrets
1200 would be
1201 .Dq \&"\&" ,
1202 which will match any password supplied by the peer.
1203 This avoids the need to have the same secret in two places.
1204 .Pp
1205 Additional checks are performed when the
1206 .Cm login
1207 option is used.
1208 If the file
1209 .Pa /etc/ppp/ppp.deny
1210 exists, and the user is listed in it, the authentication fails.
1211 If the file
1212 .Pa /etc/ppp/ppp.shells
1213 exists and
1214 the user's normal login shell is not listed, the authentication fails.
1215 .Pp
1216 Authentication must be satisfactorily completed before IPCP (or any
1217 other Network Control Protocol) can be started.
1218 If the peer is required to authenticate itself, and fails to do so,
1219 .Nm
1220 will terminated the link (by closing LCP).
1221 If IPCP negotiates an unacceptable IP address for the remote host,
1222 IPCP will be closed.
1223 IP packets can only be sent or received when IPCP is open.
1224 .Pp
1225 In some cases it is desirable to allow some hosts which can't
1226 authenticate themselves to connect and use one of a restricted set of
1227 IP addresses, even when the local host generally requires
1228 authentication.
1229 If the peer refuses to authenticate itself when requested,
1230 .Nm
1231 takes that as equivalent to authenticating with PAP
1232 using the empty string for the username and password.
1233 Thus, by adding
1234 a line to the pap-secrets file which specifies the empty string for
1235 the client and password, it is possible to allow restricted access to
1236 hosts which refuse to authenticate themselves.
1237 .Ss ROUTING
1238 When IPCP negotiation is completed successfully,
1239 .Nm
1240 will inform the
1241 kernel of the local and remote IP addresses for the ppp interface.
1242 This is sufficient to create a host route to the remote end of the
1243 link, which will enable the peers to exchange IP packets.
1244 Communication with other machines generally requires further
1245 modification to routing tables and/or ARP (Address Resolution
1246 Protocol) tables.
1247 In most cases the
1248 .Cm defaultroute
1249 and/or
1250 .Cm proxyarp
1251 options are sufficient for this, but in some cases
1252 further intervention is required.
1253 The
1254 .Pa /etc/ppp/ip-up
1255 script can be used for this.
1256 .Pp
1257 Sometimes it is desirable to add a default route through the remote
1258 host, as in the case of a machine whose only connection to the
1259 Internet is through the ppp interface.
1260 The
1261 .Cm defaultroute
1262 option causes
1263 .Nm
1264 to create such a default route when IPCP comes up, and
1265 delete it when the link is terminated.
1266 .Pp
1267 In some cases it is desirable to use proxy ARP, for example on a
1268 server machine connected to a LAN, in order to allow other hosts to
1269 communicate with the remote host.
1270 The
1271 .Cm proxyarp
1272 option causes
1273 .Nm
1274 to look for a network interface on the same subnet as the remote
1275 host (an interface supporting broadcast and ARP, which is up and not a
1276 point-to-point or loopback interface).
1277 If found,
1278 .Nm
1279 creates a
1280 permanent, published ARP entry with the IP address of the remote host
1281 and the hardware address of the network interface found.
1282 .Pp
1283 When the
1284 .Cm demand
1285 option is used, the interface IP addresses have
1286 already been set at the point when IPCP comes up.
1287 If
1288 .Nm
1289 has not
1290 been able to negotiate the same addresses that it used to configure
1291 the interface (for example when the peer is an ISP that uses dynamic
1292 IP address assignment),
1293 .Nm
1294 has to change the interface IP addresses to the negotiated addresses.
1295 This may disrupt existing connections,
1296 and the use of demand dialling with peers that do dynamic IP address
1297 assignment is not recommended.
1299 The environment variables that
1300 .Nm
1301 sets are:
1302 .Bl -tag -width "PEERNAME"
1303 .It Ev DEVICE
1304 The name of the serial tty device being used.
1305 .It Ev IFNAME
1306 The name of the network interface being used.
1307 .It Ev IPLOCAL
1308 The IP address for the local end of the link.
1309 This is only set when IPCP has come up.
1310 .It Ev IPREMOTE
1311 The IP address for the remote end of the link.
1312 This is only set when IPCP has come up.
1313 .It Ev PEERNAME
1314 The authenticated name of the peer.
1315 This is only set if the peer authenticates itself.
1316 .It Ev SPEED
1317 The baud rate of the tty device.
1318 .It Ev UID
1319 The real user-id of the user who invoked
1320 .Nm .
1321 .El
1322 .Sh FILES
1323 .Nm
1324 reads options from the files
1325 .Pa /etc/ppp/options ,
1326 .Pa ~/.ppprc
1327 and
1328 .Pa /etc/ppp/options. Ns Ar tty_name
1329 (in that order) before processing the options on the command line.
1330 (In fact, the command-line options are
1331 scanned to find the terminal name before the
1332 .Pa options. Ns Ar tty_name
1333 file is read.)
1334 .Pp
1335 An options file is parsed into a series of words, delimited by
1336 whitespace.
1337 Whitespace can be included in a word by enclosing the
1338 word in double-quotes (").
1339 A backslash (\\) quotes the following character.
1340 A hash (#) starts a comment, which continues until the end of the line.
1341 There is no restriction on using the
1342 .Cm file
1343 or
1344 .Cm call
1345 options within an options file.
1346 .Bl -tag -width ".Pa /usr/share/examples/pppd/"
1347 .It Pa /var/run/ppp Ns Ar unit Ns \&.pid
1348 Process-ID for
1349 .Nm
1350 process on ppp interface
1351 .Ar unit .
1352 .It Pa /etc/ppp/pap-secrets
1353 Usernames, passwords and IP addresses for PAP authentication.
1354 This file should be owned by root and not readable or writable
1355 by any other user.
1356 .Nm
1357 will log a warning if this is not the case.
1358 .It Pa /etc/ppp/chap-secrets
1359 Names, secrets and IP addresses for CHAP authentication.
1360 As for
1361 .Pa /etc/ppp/pap-secrets ,
1362 this file should be owned by root and not
1363 readable or writable by any other user.
1364 .Nm
1365 will log a warning if this is not the case.
1366 .It Pa /etc/ppp/options
1367 System default options for
1368 .Nm ,
1369 read before user default options or
1370 command-line options.
1371 .It Pa ~/.ppprc
1372 User default options, read before
1373 .Pa /etc/ppp/options. Ns Ar tty_name .
1374 .It Pa /etc/ppp/options. Ns Ar tty_name
1375 System default options for the serial port being used, read after
1376 .Pa ~/.ppprc .
1377 In forming the
1378 .Ar tty_name
1379 part of this filename, an initial
1380 .Dq /dev/
1381 is stripped from the port name (if present), and any slashes in the
1382 remaining part are converted to dots.
1383 .It Pa /etc/ppp/peers
1384 A directory containing options files which may contain privileged
1385 options, even if
1386 .Nm
1387 was invoked by a user other than root.
1388 The system administrator can create options files in this directory to
1389 permit non-privileged users to dial out without requiring the peer to
1390 authenticate, but only to certain trusted peers.
1391 .It Pa /etc/ppp/ppp.deny
1392 Lists users who may not use the system password PAP authentication.
1393 .It Pa /etc/ppp/ppp.shells
1394 Lists user shells which are approved for system password PAP authentication
1395 logins.
1396 .It Pa /usr/share/examples/pppd/
1397 Sample
1398 .Nm
1399 configuration files.
1400 .El
1401 .Pp
1402 .Nm
1403 also invokes scripts at various stages in its processing which can be
1404 used to perform site-specific ancillary processing.
1405 These scripts are
1406 usually shell scripts, but could be executable code files instead.
1407 .Nm
1408 does not wait for the scripts to finish.
1409 The scripts are
1410 executed as root (with the real and effective user-id set to 0), so
1411 that they can do things such as update routing tables or run
1412 privileged daemons.
1413 Be careful that the contents of these scripts do
1414 not compromise your system's security.
1415 .Nm
1416 runs the scripts with
1417 standard input, output and error redirected to
1418 .Pa /dev/null ,
1419 and with an
1420 environment that is empty except for some environment variables that
1421 give information about the link.
1422 .Nm
1423 invokes the following scripts, if they exist.
1424 It is not an error if they don't exist.
1425 .Bl -tag -width ".Pa /etc/ppp/auth-down"
1426 .It Pa /etc/ppp/auth-up
1427 A program or script which is executed after the remote system
1428 successfully authenticates itself.
1429 It is executed with the following parameters:
1430 .Pp
1431 .Sy iface-name peer-name user-name tty-dev speed
1432 .Pp
1433 Note that this script is not executed if the peer doesn't authenticate
1434 itself, for example when the
1435 .Cm noauth
1436 option is used.
1437 .It Pa /etc/ppp/auth-down
1438 A program or script which is executed when the link goes down, if
1439 .Pa /etc/ppp/auth-up
1440 was previously executed.
1441 It is executed in the same manner with the same parameters as
1442 .Pa /etc/ppp/auth-up .
1443 .It Pa /etc/ppp/ip-up
1444 A program or script which is executed when the link is available for
1445 sending and receiving IP packets (that is, IPCP has come up).
1446 It is executed with the following parameters:
1447 .Pp
1448 .Sy iface-name tty-dev speed local-IP remote-IP ipparam
1449 .It Pa /etc/ppp/ip-down
1450 A program or script which is executed when the link is no longer
1451 available for sending and receiving IP packets.
1452 This script can be used for undoing the effects of the
1453 .Pa /etc/ppp/ip-up
1454 script.
1455 It is invoked in the same manner and with the same parameters.
1456 .It Pa /etc/ppp/ipx-up
1457 A program or script which is executed when the link is available for
1458 sending and receiving IPX packets (that is, IPXCP has come up).
1459 It is executed with the following parameters:
1460 .Pp
1461 .Sy iface-name tty-dev speed network-number
1462 .Sy local-IPX-node-address remote-IPX-node-address
1463 .Sy local-IPX-routing-proto remote-IPX-routing-proto
1464 .Sy local-IPX-router-name remote-IPX-router-name
1465 .Sy ipparam pppd-pid
1466 .Pp
1467 The local-IPX-routing-protocol and remote-IPX-routing-protocol field
1468 may be one of the following:
1469 .Bl -hang
1470 .It Dq NONE
1471 to indicate that there is no routing protocol
1472 .It Dq RIP
1473 to indicate that RIP/SAP should be used
1474 .It Dq NLSP
1475 to indicate that Novell NLSP should be used
1476 .It Dq RIP NLSP
1477 to indicate that both RIP/SAP and NLSP should be used
1478 .El
1479 .It Pa /etc/ppp/ipx-down
1480 A program or script which is executed when the link is no longer
1481 available for sending and receiving IPX packets.
1482 This script can be used for undoing the effects of the
1483 .Pa /etc/ppp/ipx-up
1484 script.
1485 It is invoked in the same manner and with the same parameters.
1486 .El
1488 The following examples assume that the
1489 .Pa /etc/ppp/options
1490 file contains the
1491 .Cm auth
1492 option (as in the default
1493 .Pa /etc/ppp/options
1494 file in the ppp distribution).
1495 .Pp
1496 Probably the most common use of
1497 .Nm
1498 is to dial out to an ISP.
1499 This can be done with a command such as
1500 .Bd -literal -offset indent
1501 # pppd call isp
1502 .Ed
1503 .Pp
1504 where the
1505 .Pa /etc/ppp/peers/isp
1506 file is set up by the system
1507 administrator to contain something like this:
1508 .Bd -literal -offset indent
1509 ttyS0 19200 crtscts
1510 connect '/usr/sbin/chat -v -f /etc/ppp/chat-isp'
1511 noauth
1512 .Ed
1513 .Pp
1514 In this example, we are using chat to dial the ISP's modem and go
1515 through any logon sequence required.
1516 The
1517 .Pa /etc/ppp/chat-isp
1518 file contains the script used by chat; it could for example contain
1519 something like this:
1520 .Bd -literal -offset indent
1526 ABORT "Username/Password Incorrect"
1527 "" "at"
1528 OK "at&d0&c1"
1529 OK "atdt2468135"
1530 "name:" "^Umyuserid"
1531 "word:" "\\qmypassword"
1532 "ispts" "\\q^Uppp"
1533 "~-^Uppp-~"
1534 .Ed
1535 .Pp
1536 See the
1537 .Xr chat 8
1538 man page for details of chat scripts.
1539 .Pp
1540 .Nm
1541 can also be used to provide a dial-in ppp service for users.
1542 If the users already have login accounts, the simplest way to set up the
1543 ppp service is to let the users log in to their accounts and run
1544 .Nm
1545 (installed setuid-root) with a command such as
1546 .Bd -literal -offset indent
1547 # pppd proxyarp
1548 .Ed
1549 .Pp
1550 To allow a user to use the PPP facilities, you need to allocate an IP
1551 address for that user's machine and create an entry in
1552 .Pa /etc/ppp/pap-secrets
1553 or
1554 .Pa /etc/ppp/chap-secrets
1555 (depending on which authentication method the PPP implementation on
1556 the user's machine supports), so that the user's machine can authenticate
1557 itself.
1558 For example, if Joe has a machine called
1559 .Sy joespc
1560 which is to be allowed to dial in to the machine called
1561 .Sy server
1562 and use the IP address
1563 .Sy joespc.my.net ,
1564 you would add an entry like this to
1565 .Pa /etc/ppp/pap-secrets
1566 or
1567 .Pa /etc/ppp/chap-secrets :
1568 .Bd -literal -offset indent
1569 joespc  server  "joe's secret"  joespc.my.net
1570 .Ed
1571 .Pp
1572 Alternatively, you can create a username called (for example)
1573 .Sy ppp ,
1574 whose login shell is
1575 .Nm
1576 and whose home directory is
1577 .Pa /etc/ppp .
1578 Options to be used when
1579 .Nm
1580 is run this way can be put in
1581 .Pa /etc/ppp/.ppprc .
1582 .Pp
1583 If your serial connection is any more complicated than a piece of
1584 wire, you may need to arrange for some control characters to be
1585 escaped.
1586 In particular, it is often useful to escape XON (^Q) and
1587 XOFF (^S), using
1588 .Cm asyncmap Li a0000 .
1589 If the path includes a telnet, you probably should escape ^] as well
1590 .Pq Cm asyncmap Li 200a0000 .
1591 If the path includes an rlogin, you will need to use the
1592 .Cm escape Li ff
1593 option on the end which is running the rlogin client, since many
1594 rlogin implementations are not transparent; they will remove the
1595 sequence [0xff, 0xff, 0x73, 0x73, followed by any 8 bytes] from the
1596 stream.
1598 Messages are sent to the syslog daemon using facility
1599 .Dv LOG_DAEMON .
1600 (This can be overridden by recompiling
1601 .Nm
1602 with the macro
1603 .Dv LOG_PPP
1604 defined as the desired facility.)
1605 In order to see the error and debug messages, you will need to edit your
1606 .Pa /etc/syslog.conf
1607 file to direct the messages to the desired output device or file.
1608 .Pp
1609 The
1610 .Cm debug
1611 option causes the contents of all control packets sent
1612 or received to be logged, that is, all LCP, PAP, CHAP or IPCP packets.
1613 This can be useful if the PPP negotiation does not succeed or if
1614 authentication fails.
1615 If debugging is enabled at compile time, the
1616 .Cm debug
1617 option also causes other debugging messages to be logged.
1618 .Pp
1619 Debugging can also be enabled or disabled by sending a
1620 .Dv SIGUSR1
1621 signal to the
1622 .Nm
1623 process.
1624 This signal acts as a toggle.
1625 .Sh SEE ALSO
1626 .Xr syslog 1 ,
1627 .Xr tcpdump 1 ,
1628 .Xr crypt 3 ,
1629 .Xr syslog.conf 5 ,
1630 .Xr chat 8 ,
1631 .Xr ppp 8
1633 .Rs
1634 .%A V. Jacobson
1635 .%D February 1990
1636 .%R RFC 1144
1637 .%T Compressing TCP/IP headers for low-speed serial links
1638 .Re
1639 .Pp
1640 .Rs
1641 .%A R. Rivest
1642 .%D April 1992
1643 .%R RFC 1321
1644 .%T The MD5 Message-Digest Algorithm
1645 .Re
1646 .Pp
1647 .Rs
1648 .%A G. McGregor
1649 .%D May 1992
1650 .%R RFC 1332
1651 .%T PPP Internet Protocol Control Protocol (IPCP)
1652 .Re
1653 .Pp
1654 .Rs
1655 .%A B. Lloyd
1656 .%A W.A. Simpson
1657 .%D October 1992
1658 .%R RFC 1334
1659 .%T PPP authentication protocols
1660 .Re
1661 .Pp
1662 .Rs
1663 .%A W.A. Simpson
1664 .%D July 1994
1665 .%R RFC 1661
1666 .%T The Point-to-Point Protocol (PPP)
1667 .Re
1668 .Pp
1669 .Rs
1670 .%A W.A. Simpson
1671 .%D July 1994
1672 .%R RFC 1662
1673 .%T PPP in HDLC-like Framing
1674 .Re
1675 .Sh AUTHORS
1676 .An -nosplit
1677 .Nm
1678 was written by
1679 .An Paul Mackerras Aq Mt Paul.Mackerras@cs.anu.edu.au ,
1680 based on earlier work by
1681 .An Drew Perkins ,
1682 .An Brad Clements ,
1683 .An Karl Fox ,
1684 .An Greg Christy ,
1685 and
1686 .An Brad Parker .