bc0cb7031c677c3bd2b2d565c9eb9bacd255ff87
[ppp.git] / pppd / pppd.8
1 .\" manual page [] for pppd 2.0
2 .\" $Id: pppd.8,v 1.19 1996/07/01 01:19:01 paulus Exp $
3 .\" SH section heading
4 .\" SS subsection heading
5 .\" LP paragraph
6 .\" IP indented paragraph
7 .\" TP hanging label
8 .TH PPPD 8
9 .SH NAME
10 pppd \- Point to Point Protocol daemon
11 .SH SYNOPSIS
12 .B pppd
13 [
14 .I tty_name
15 ] [
16 .I speed
17 ] [
18 .I options
19 ]
20 .SH DESCRIPTION
21 .LP
22 The Point-to-Point Protocol (PPP) provides a method for transmitting
23 datagrams over serial point-to-point links.  PPP
24 is composed of three parts: a method for encapsulating datagrams over
25 serial links, an extensible Link Control Protocol (LCP), and
26 a family of Network Control Protocols (NCP) for establishing
27 and configuring different network-layer protocols.
28 .LP
29 The encapsulation scheme is provided by driver code in the kernel.
30 .B pppd
31 provides the basic LCP, authentication support, and an
32 NCP for establishing and configuring the Internet Protocol (IP)
33 (called the IP Control Protocol, IPCP).
34 .SH FREQUENTLY USED OPTIONS
35 .TP
36 .I <tty_name>
37 Communicate over the named device.  The string "/dev/"
38 is prepended if necessary.  If no device name is given,
39 or if the name of the controlling terminal is given,
40 .I pppd
41 will use the controlling terminal, and will not fork to put itself in
42 the background.
43 .TP
44 .I <speed>
45 Set the baud rate to <speed> (a decimal number).  On systems such as
46 4.4BSD and NetBSD, any speed can be specified.  Other systems
47 (e.g. SunOS) allow only a limited set of speeds.
48 .TP
49 .B asyncmap \fI<map>
50 Set the async character map to <map>.
51 This map describes which control characters cannot be successfully
52 received over the serial line.
53 .I pppd
54 will ask the peer to send these characters as a 2-byte escape sequence.
55 The argument is a 32 bit hex number
56 with each bit representing a character to escape. 
57 Bit 0 (00000001) represents the character 0x00;
58 bit 31 (80000000) represents the character 0x1f or ^_.
59 If multiple \fBasyncmap\fR options are
60 given, the values are ORed together.
61 If no \fBasyncmap\fR option is given, no async character map will be
62 negotiated for the receive direction; the peer should then escape
63 \fIall\fR control characters.
64 .TP
65 .B auth
66 Require the peer to authenticate itself before allowing network
67 packets to be sent or received.
68 .TP
69 .B connect \fI<p>
70 Use the executable or shell command specified by \fI<p>\fR to set up the
71 serial line.  This script would typically use the chat(8) program to
72 dial the modem and start the remote ppp session.
73 .TP
74 .B crtscts
75 Use hardware flow control (i.e. RTS/CTS) to control the flow of data
76 on the serial port.  If neither the \fBcrtscts\fR nor the
77 \fB\-crtscts\fR option is given, the hardware flow control setting for
78 the serial port is left unchanged.
79 .TP
80 .B defaultroute
81 Add a default route to the system routing tables, using the peer as
82 the gateway, when IPCP negotiation is successfully completed.
83 This entry is removed when the PPP connection is broken.
84 .TP
85 .B disconnect \fI<p>
86 Run the executable or shell command specified by \fI<p>\fR after
87 \fIpppd\fR has terminated the link.  This script could, for example,
88 issue commands to the modem to cause it to hang up if hardware modem
89 control signals were not available.
90 .TP
91 .B escape \fIxx,yy,...
92 Specifies that certain characters should be escaped on transmission
93 (regardless of whether the peer requests them to be escaped with its
94 async control character map).  The characters to be escaped are
95 specified as a list of hex numbers separated by commas.  Note that
96 almost any character can be specified for the \fBescape\fR option,
97 unlike the \fBasyncmap\fR option which only allows control characters
98 to be specified.  The characters which may not be escaped are those
99 with hex values 0x20 - 0x3f or 0x5e.
100 .TP
101 .B file \fI<f>
102 Read options from file <f> (the format is described below).
103 .TP
104 .B lock
105 Specifies that \fIpppd\fR should create a UUCP-style lock file for the
106 serial device to ensure exclusive access to the device.
107 .TP
108 .B mru \fI<n>
109 Set the MRU [Maximum Receive Unit] value to <n> for negotiation.
110 .I pppd
111 will ask the peer to send packets of no more than <n> bytes.  The
112 minimum MRU value is 128.  The default MRU value is 1500.  A value of
113 296 is recommended for slow links (40 bytes for TCP/IP header + 256
114 bytes of data).
115 .TP
116 .B mtu \fI<n>
117 Set the MTU [Maximum Transmit Unit] value to \fI<n>\fR.  Unless the
118 peer requests a smaller value via MRU negotiation, \fIpppd\fR will
119 request that the kernel networking code send data packets of no more
120 than \fIn\fR bytes through the PPP network interface. 
121 .TP
122 .B passive
123 Enables the "passive" option in the LCP.  With this option,
124 .I pppd
125 will attempt to initiate a connection; if no reply is received from
126 the peer,
127 .I pppd
128 will then just wait passively for a valid LCP packet from the peer
129 (instead of exiting, as it does without this option).
130 .SH OPTIONS
131 .TP
132 .I <local_IP_address>\fB:\fI<remote_IP_address>
133 Set the local and/or remote interface IP addresses.  Either one may be
134 omitted.  The IP addresses can be specified with a host name or in
135 decimal dot notation (e.g. 150.234.56.78).  The default local
136 address is the (first) IP address of the system (unless the
137 .B noipdefault
138 option is given).  The remote address will be obtained from the peer
139 if not specified in any option.  Thus, in simple cases, this option is
140 not required.  If a local and/or remote IP address is specified with
141 this option,
142 .I pppd
143 will not accept a different value from the peer in the IPCP
144 negotiation, unless the
145 .B ipcp-accept-local
146 and/or
147 .B ipcp-accept-remote
148 options are given, respectively.
149 .TP
150 .B active-filter \fIfilter-expression
151 Specifies a packet filter to be applied to data packets to determine
152 which packets are to be regarded as link activity, and therefore reset
153 the idle timer, or cause the link to be brought up in demand-dialling
154 mode.  This option is useful in conjunction with the
155 \fBidle\fR option if there are packets being sent or received
156 regularly over the link (for example, routing information packets)
157 which would otherwise prevent the link from ever appearing to be idle.
158 The \fIfilter-expression\fR syntax is as described for tcpdump(1),
159 except that qualifiers which are inappropriate for a PPP link, such as
160 \fBether\fR and \fBarp\fR, are not permitted.  Generally the filter
161 expression should be enclosed in single-quotes to prevent whitespace
162 in the expression from being interpreted by the shell.
163 .TP
164 .B bsdcomp \fInr,nt
165 Request that the peer compress packets that it sends, using the
166 BSD-Compress scheme, with a maximum code size of \fInr\fR bits, and
167 agree to compress packets sent to the peer with a maximum code size of
168 \fInt\fR bits.  If \fInt\fR is not specified, it defaults to the value
169 given for \fInr\fR.  Values in the range 9 to 15 may be used for
170 \fInr\fR and \fInt\fR; larger values give better compression but
171 consume more kernel memory for compression dictionaries.
172 Alternatively, a value of 0 for \fInr\fR or \fInt\fR disables
173 compression in the corresponding direction.
174 .TP
175 .B chap-interval \fI<n>
176 If this option is given,
177 .I pppd
178 will rechallenge the peer every <n> seconds.
179 .TP
180 .B chap-max-challenge \fI<n>
181 Set the maximum number of CHAP challenge transmissions to <n> (default
182 10).
183 .TP
184 .B chap-restart \fI<n>
185 Set the CHAP restart interval (retransmission timeout for challenges)
186 to <n> seconds (default 3).
187 .TP
188 .B debug
189 Increase debugging level.
190 If this option is given, \fIpppd\fR will log the contents of all
191 control packets sent or received in a readable form.  The packets are
192 logged through syslog with facility \fIdaemon\fR and level
193 \fIdebug\fR.  This information can be directed to a file by setting up
194 /etc/syslog.conf appropriately (see syslog.conf(5)).
195 .TP
196 .B default-asyncmap
197 Disable asyncmap negotiation, forcing all control characters to be
198 escaped for both the transmit and the receive direction.
199 .TP
200 .B default-mru
201 Disable MRU [Maximum Receive Unit] negotiation.  With this option,
202 \fIpppd\fR will use the default MRU value of 1500 bytes for both the
203 transmit and receive direction.
204 .TP
205 .B deflate \fInr,nt
206 Request that the peer compress packets that it sends, using the
207 Deflate scheme, with a maximum window size of \fI2**nr\fR bytes, and
208 agree to compress packets sent to the peer with a maximum window size of
209 \fI2**nt\fR bytes.  If \fInt\fR is not specified, it defaults to the value
210 given for \fInr\fR.  Values in the range 8 to 15 may be used for
211 \fInr\fR and \fInt\fR; larger values give better compression but
212 consume more kernel memory for compression dictionaries.
213 Alternatively, a value of 0 for \fInr\fR or \fInt\fR disables
214 compression in the corresponding direction.  (Note: \fBpppd\fR
215 requests Deflate compression in preference to BSD-Compress
216 if the peer can do either.)
217 .TP
218 .B demand
219 Initiate the link only on demand, i.e. when data traffic is present.
220 With this option, the remote IP address must be specific by the user
221 on the command line or in an options file.  \fBpppd\fR will initially
222 configure the interface and enable it for IP traffic without
223 connecting to the peer.  When traffic is available, \fBpppd\fR will
224 connect to the peer and perform negotiation, authentication, etc.
225 When this is completed, \fBpppd\fR will commence passing data packets
226 (i.e., IP packets) across the link.  The persist, idle and holdoff
227 options are often useful in conjuction with this option.
228 .TP
229 .B domain \fI<d>
230 Append the domain name <d> to the local host name for authentication
231 purposes.  For example, if gethostname() returns the name porsche, but the
232 fully qualified domain name is porsche.Quotron.COM, you would use the
233 domain option to set the domain name to Quotron.COM.
234 .TP
235 .B holdoff \fI<n>
236 Specifies how many seconds to wait before re-initiating the link after
237 it terminates.  This option only has effect if the persist option is
238 used.
239 .TP
240 .B idle \fI<n>
241 Specifies that \fBpppd\fR should disconnect if it is idle for
242 \fI<n>\fR seconds.  The link is idle when no data packets (i.e. IP
243 packets) are being sent or received.  If the \fBactive-filter\fR
244 option is given, data packets which are rejected by the specified
245 activity filter also count as the link being idle.
246 .TP
247 .B ipx
248 Enable the IPXCP and IPX protocols.  Under Linux, this is the default
249 condition if your kernel supports IPX.  This option is presently only
250 supported under Linux.
251 .TP
252 .B ipcp-accept-local
253 With this option,
254 .I pppd
255 will accept the peer's idea of our local IP address, even if the
256 local IP address was specified in an option.
257 .TP
258 .B ipcp-accept-remote
259 With this option,
260 .I pppd
261 will accept the peer's idea of its (remote) IP address, even if the
262 remote IP address was specified in an option.
263 .TP
264 .B ipcp-max-configure \fI<n>
265 Set the maximum number of IPCP configure-request transmissions to <n>
266 (default 10).
267 .TP
268 .B ipcp-max-failure \fI<n>
269 Set the maximum number of IPCP configure-NAKs returned before starting
270 to send configure-Rejects instead to <n> (default 10).
271 .TP
272 .B ipcp-max-terminate \fI<n>
273 Set the maximum number of IPCP terminate-request transmissions to <n>
274 (default 3).
275 .TP
276 .B ipcp-restart \fI<n>
277 Set the IPCP restart interval (retransmission timeout) to <n> seconds
278 (default 3).
279 .TP
280 .B ipparam \fIstring
281 Provides an extra parameter to the ip-up and ip-down scripts.  If this
282 option is given, the \fIstring\fR supplied is given as the 6th
283 parameter to those scripts.
284 .TP
285 .B ipx-network \fI<n>
286 Set the IPX network number in the IPXCP configure request frame to
287 <n>. There is no valid default. If this option is not specified then
288 the network number is obtained from the peer. If the peer does not
289 have the network number, the IPX protocol will not be started. This is
290 a hexadecimal number and is entered without any leading sequence such
291 as 0x. It is related to the \fIipxcp-accept-network\fR option.
292 .TP
293 .B ipx-node \fI<n>:<m>
294 Set the IPX node numbers. The two node numbers are separated from each
295 other with a colon character. The first number <n> is the local node
296 number. The second number <m> is the peer's node number. Each node number
297 is a hexadecimal number, to the maximum of ten significant digits. The
298 node numbers on the ipx-network must be unique. There is no valid
299 default. If this option is not specified then the node number is
300 obtained from the peer. This option is a related to the
301 \fIipxcp-accept-local\fR and \fIipxcp-accept-remote\fR options.
302 .TP
303 .B ipx-router-name \fI<string>
304 Set the name of the router. This is a string and is sent to the peer
305 as information data.
306 .TP
307 .B ipx-routing \fI<n>
308 Set the routing protocol to be received by this option. More than one
309 instance of \fIipx-routing\fR may be specified. The '\fInone\fR'
310 option (0) may be specified as the only instance of ipx-routing. The
311 values may be \fI0\fR for \fINONE\fR, \fI2\fR for \fIRIP/SAP\fR, and
312 \fI4\fR for \fINLSP\fR.
313 .TP
314 .B ipxcp-accept-local
315 Accept the peer's NAK for the node number specified in the ipx-node
316 option. If a node number was specified, and non-zero, the default is
317 to insist that the value be used. If you include this option then you
318 will permit the peer to override the entry of the node number.
319 .TP
320 .B ipxcp-accept-network
321 Accept the peer's NAK for the network number specified in the
322 ipx-network option. If a network number was specified, and non-zero, the
323 default is to insist that the value be used. If you include this
324 option then you will permit the peer to override the entry of the node
325 number.
326 .TP
327 .B ipxcp-accept-remote
328 Use the peer's network number specified in the configure request
329 frame. If a node number was specified for the peer and this option was
330 not specified, the peer will be forced to use the value which you have
331 specified.
332 .TP
333 .B ipxcp-max-configure \fI<n>
334 Set the maximum number of IPXCP configure request frames which the
335 system will send to <n>. The default is 10.
336 .TP
337 .B ipxcp-max-failure \fI<n>
338 Set the maximum number of IPXCP NAK frames which the local system will
339 send before it rejects the options. The default value is 3.
340 .TP
341 .B ipxcp-max-terminate \fI<n>
342 Set the maximum nuber of IPXCP terminate request frames before the
343 local system considers that the peer is not listening to them. The
344 default value is 3.
345 .TP
346 .B kdebug \fIn
347 Enable debugging code in the kernel-level PPP driver.  The argument
348 \fIn\fR is a number which is the sum of the following values: 1 to
349 enable general debug messages, 2 to request that the contents of
350 received packets be printed, and 4 to request that the contents of
351 transmitted packets be printed.
352 .TP
353 .B lcp-echo-failure \fI<n>
354 If this option is given, \fIpppd\fR will presume the peer to be dead
355 if \fIn\fR LCP echo-requests are sent without receiving a valid LCP
356 echo-reply.  If this happens, \fIpppd\fR will terminate the
357 connection.  Use of this option requires a non-zero value for the
358 \fIlcp-echo-interval\fR parameter.  This option can be used to enable
359 \fIpppd\fR to terminate after the physical connection has been broken
360 (e.g., the modem has hung up) in situations where no hardware modem
361 control lines are available.
362 .TP
363 .B lcp-echo-interval \fI<n>
364 If this option is given, \fIpppd\fR will send an LCP echo-request
365 frame to the peer every \fIn\fR seconds.  Under Linux, the
366 echo-request is sent when no packets have been received from the peer
367 for \fIn\fR seconds.  Normally the peer should respond to the
368 echo-request by sending an echo-reply.  This option can be used with
369 the \fIlcp-echo-failure\fR option to detect that the peer is no longer
370 connected.
371 .TP
372 .B lcp-max-configure \fI<n>
373 Set the maximum number of LCP configure-request transmissions to <n>
374 (default 10).
375 .TP
376 .B lcp-max-failure \fI<n>
377 Set the maximum number of LCP configure-NAKs returned before starting
378 to send configure-Rejects instead to <n> (default 10).
379 .TP
380 .B lcp-max-terminate \fI<n>
381 Set the maximum number of LCP terminate-request transmissions to <n>
382 (default 3).
383 .TP
384 .B lcp-restart \fI<n>
385 Set the LCP restart interval (retransmission timeout) to <n> seconds
386 (default 3).
387 .TP
388 .B local
389 Don't use the modem control lines.  With this option,
390 .B pppd
391 will ignore the state of the CD (Carrier Detect) signal from the modem and
392 will not change the state of the DTR (Data Terminal Ready) signal.
393 .TP
394 .B login
395 Use the system password database for authenticating the peer using
396 PAP, and record the user in the system wtmp file.
397 .TP
398 .B modem
399 Use the modem control lines.  This option is the default.  With this
400 option,
401 .B pppd
402 will wait for the CD (Carrier Detect) signal from the modem to be asserted
403 when opening the serial device
404 (unless a connect script is specified), and it will drop the DTR (Data
405 Terminal Ready) signal briefly when the connection is terminated and before
406 executing the connect script.
407 On Ultrix, this option implies hardware
408 flow control, as for the \fBcrtscts\fR option.  
409 .TP
410 .B ms-dns \fI<addr>
411 If
412 .I pppd
413 is acting as a server for Microsoft Windows clients, this option
414 allows
415 .I pppd
416 to supply one or two DNS (Domain Name Server) addresses to the
417 clients.  The first instance of this option specifies the primary DNS
418 address; the second instance (if given) specifies the secondary DNS
419 address.
420 .TP
421 .B name \fI<n>
422 Set the name of the local system for authentication purposes to <n>.
423 .TP
424 .B netmask \fI<n>
425 Set the interface netmask to <n>, a 32 bit netmask in "decimal dot"
426 notation (e.g. 255.255.255.0).  If this option is given, the value
427 specified is ORed with the default netmask.  The default netmask is
428 chosen based on the negotiated remote IP address; it is the
429 appropriate network mask for the class of the remote IP address, ORed
430 with the netmasks for any non point-to-point network interfaces in the
431 system which are on the same network.
432 .TP
433 .B noaccomp
434 Disable Address/Control compression in both directions (send and
435 receive).
436 .TP
437 .B nobsdcomp
438 Disables BSD-Compress compression; \fBpppd\fR will not request or
439 agree to compress packets using the BSD-Compress scheme.
440 .TP
441 .B noccp
442 Disable CCP (Compression Control Protocol) negotiation.  This option
443 should only be required if the peer is buggy and gets confused by
444 requests from
445 .I pppd
446 for CCP negotiation.
447 .TP
448 .B nocrtscts
449 Disable hardware flow control (i.e. RTS/CTS) on the serial port.  If
450 neither the \fBcrtscts\fR nor the \fB\-crtscts\fR option is given,
451 the hardware flow control setting for the serial port is left
452 unchanged.
453 .TP
454 .B nodefaultroute
455 Disable the \fBdefaultroute\fR option.  The system administrator who
456 wishes to prevent users from creating default routes with \fIpppd\fR
457 can do so by placing this option in the /etc/ppp/options file.
458 .TP
459 .B nodeflate
460 Disables Deflate compression; \fBpppd\fR will not request or agree to
461 compress packets using the Deflate scheme.
462 .TP
463 .B nodetach
464 Don't detach from the controlling terminal.  Without this option,
465 if a serial device other than its controlling terminal is specified,
466 .I pppd
467 will fork to become a background process.
468 .TP
469 .B noip
470 Disable IPCP negotiation and IP communication.  This option should
471 only be required if the peer is buggy and gets confused by requests
472 from
473 .I pppd
474 for IPCP negotiation.
475 .TP
476 .B noipdefault
477 Disables the default behaviour when no local IP address is specified,
478 which is to determine (if possible) the local IP address from the
479 hostname.  With this option, the peer will have to supply the local IP
480 address during IPCP negotiation (unless it specified explicitly on the
481 command line or in an options file).
482 .TP
483 .B noipx
484 Disable the IPXCP and IPX protocols.  This option should only be
485 required if the peer is buggy and gets confused by requests from
486 .I pppd
487 for IPXCP negotiation.
488 .TP
489 .B nomagic
490 Disable magic number negotiation.  With this option,
491 .I pppd
492 cannot detect a looped-back line.  This option should only be needed
493 if the peer is buggy.
494 .TP
495 .B nopcomp
496 Disable protocol field compression negotiation in both the receive and
497 the transmit direction.
498 .TP
499 .B nopredictor1
500 Do not accept or agree to Predictor-1 comprssion.
501 .TP
502 .B noproxyarp
503 Disable the \fBproxyarp\fR option.  The system administrator who
504 wishes to prevent users from creating proxy ARP entries with
505 \fIpppd\fR can do so by placing this option in the /etc/ppp/options
506 file.
507 .TP
508 .B novj
509 Disable Van Jacobson style TCP/IP header compression in both the
510 transmit and the receive direction.
511 .TP
512 .B novjccomp
513 Disable the connection-ID compression option in Van Jacobson style
514 TCP/IP header compression.  With this option, \fIpppd\fR will not omit
515 the connection-ID byte from Van Jacobson compressed TCP/IP headers,
516 nor ask the peer to do so.
517 .TP
518 .B papcrypt
519 Indicates that all secrets in the /etc/ppp/pap-secrets file which
520 are used for checking the identity of the peer are encrypted, and thus
521 pppd should not accept a password which (before encryption) is
522 identical to the secret from the /etc/ppp/pap-secrets file.
523 .TP
524 .B pap-max-authreq \fI<n>
525 Set the maximum number of PAP authenticate-request transmissions to
526 <n> (default 10).
527 .TP
528 .B pap-restart \fI<n>
529 Set the PAP restart interval (retransmission timeout) to <n> seconds
530 (default 3).
531 .TP
532 .B pap-timeout \fI<n>
533 Set the maximum time that
534 .I pppd
535 will wait for the peer to authenticate itself with PAP to
536 <n> seconds (0 means no limit).
537 .TP
538 .B pass-filter \fIfilter-expression
539 Specifies a packet filter to applied to data packets being sent or
540 received to determine which packets should be allowed to pass.
541 Packets which are rejected by the filter are silently discarded.  This
542 option can be used to provide protection against IP address spoofing
543 and other attacks.
544 The \fIfilter-expression\fR syntax is as described for tcpdump(1),
545 except that qualifiers which are inappropriate for a PPP link, such as
546 \fBether\fR and \fBarp\fR, are not permitted.  Generally the filter
547 expression should be enclosed in single-quotes to prevent whitespace
548 in the expression from being interpreted by the shell.  Note that it
549 is possible to apply different constraints to incoming and outgoing
550 packets using the \fBinbound\fR and \fBoutbound\fR qualifiers.
551 .TP
552 .B persist
553 Do not exit after a connection is terminated; instead try to reopen
554 the connection.
555 .TP
556 .B predictor1
557 Attempt to request that the peer send frames which
558 have been compressed using Predictor-1 compression.  This option will
559 be ignored unless Predictor-1 code has been loaded into the kernel.
560 .TP
561 .B proxyarp
562 Add an entry to this system's ARP [Address Resolution Protocol] table
563 with the IP address of the peer and the Ethernet address of this
564 system.
565 .TP
566 .B remotename \fI<n>
567 Set the assumed name of the remote system for authentication purposes
568 to <n>.
569 .TP
570 .B refuse-chap
571 With this option, \fIpppd\fR will not agree to authenticate itself
572 to the peer using CHAP.
573 .TP
574 .B refuse-pap
575 With this option, \fIpppd\fR will not agree to authenticate itself
576 to the peer using PAP.
577 .TP
578 .B require-chap
579 Require the peer to authenticate itself using CHAP [Cryptographic
580 Handshake Authentication Protocol] authentication.
581 .TP
582 .B require-pap
583 Require the peer to authenticate itself using PAP [Password
584 Authentication Protocol] authentication.
585 .TP
586 .B silent
587 With this option,
588 .I pppd
589 will not transmit LCP packets to initiate a connection until a valid
590 LCP packet is received from the peer (as for the `passive' option with
591 ancient versions of \fIpppd\fR).
592 .TP
593 .B usehostname
594 Enforce the use of the hostname as the name of the local system for
595 authentication purposes (overrides the
596 .B name
597 option).
598 .TP
599 .B user \fI<u>
600 Set the user name to use for authenticating this machine with the peer
601 using PAP to <u>.
602 .TP
603 .B vj-max-slots \fIn
604 Sets the number of connection slots to be used by the Van Jacobson
605 TCP/IP header compression and decompression code to \fIn\fR, which
606 must be between 2 and 16 (inclusive).
607 .TP
608 .B xonxoff
609 Use software flow control (i.e. XON/XOFF) to control the flow of data on
610 the serial port.  This option is only implemented on Linux systems
611 at present.
612 .SH OPTIONS FILES
613 Options can be taken from files as well as the command line.  
614 .I pppd
615 reads options from the files /etc/ppp/options and ~/.ppprc before
616 looking at the command line.  An options file is parsed into a series
617 of words, delimited by whitespace.  Whitespace can be included in a
618 word by enclosing the word in quotes (").  A backslash (\\) quotes the
619 following character.  A hash (#) starts a comment, which continues
620 until the end of the line.
621 .SH AUTHENTICATION
622 .I pppd
623 provides system administrators with sufficient access control that PPP
624 access to a server machine can be provided to legitimate users without
625 fear of compromising the security of the server or the network it's
626 on.  In part this is provided by the /etc/ppp/options file, where the
627 administrator can place options to require authentication whenever
628 .I pppd
629 is run, and in part by the PAP and CHAP secrets files, where the
630 administrator can restrict the set of IP addresses which individual
631 users may use.
632 .LP
633 The default behaviour of
634 .I pppd
635 is to agree to authenticate if requested, and to not
636 require authentication from the peer.  However, 
637 .I pppd
638 will not agree to
639 authenticate itself with a particular protocol if it has no secrets
640 which could be used to do so.
641 .LP
642 Authentication is based on secrets, which are selected from secrets
643 files (/etc/ppp/pap-secrets for PAP, /etc/ppp/chap-secrets for CHAP).
644 Both secrets files have the same format, and both can store secrets
645 for several combinations of server (authenticating peer) and client
646 (peer being authenticated).  Note that
647 .I pppd
648 can be both a server
649 and client, and that different protocols can be used in the two
650 directions if desired.
651 .LP
652 A secrets file is parsed into words as for a options file.  A secret
653 is specified by a line containing at least 3 words, in the order
654 client name, server name, secret.  Any following words on the same line are
655 taken to be a list of acceptable IP addresses for that client.  If
656 there are only 3 words on the line, it is assumed that any IP address
657 is OK; to disallow all IP addresses, use "-".  If the secret starts
658 with an `@', what follows is assumed to be the name of a file from
659 which to read the secret.  A "*" as the client or server name matches
660 any name.  When selecting a secret, \fIpppd\fR takes the best match, i.e.
661 the match with the fewest wildcards.
662 .LP
663 Thus a secrets file contains both secrets for use in authenticating
664 other hosts, plus secrets which we use for authenticating ourselves to
665 others.  Which secret to use is chosen based on the names of the host
666 (the `local name') and its peer (the `remote name').  The local name
667 is set as follows:
668 .TP 3
669 if the \fBusehostname\fR option is given,
670 then the local name is the hostname of this machine
671 (with the domain appended, if given)
672 .TP 3
673 else if the \fBname\fR option is given,
674 then use the argument of the first \fBname\fR option seen
675 .TP 3
676 else if the local IP address is specified with a hostname,
677 then use that name
678 .TP 3
679 else use the hostname of this machine (with the domain appended, if given)
680 .LP
681 When authenticating ourselves using PAP, there is also a `username'
682 which is the local name by default, but can be set with the \fBuser\fR
683 option or the \fB+ua\fR option.
684 .LP
685 The remote name is set as follows:
686 .TP 3
687 if the \fBremotename\fR option is given,
688 then use the argument of the last \fBremotename\fR option seen
689 .TP 3
690 else if the remote IP address is specified with a hostname,
691 then use that host name
692 .TP 3
693 else the remote name is the null string "".
694 .LP
695 Secrets are selected from the PAP secrets file as follows:
696 .TP 2
697 *
698 For authenticating the peer, look for a secret with client ==
699 username specified in the PAP authenticate-request, and server ==
700 local name.
701 .TP 2
702 *
703 For authenticating ourselves to the peer, look for a secret with
704 client == our username, server == remote name.
705 .LP
706 When authenticating the peer with PAP, a secret of "" matches any
707 password supplied by the peer.  If the password doesn't match the
708 secret, the password is encrypted using crypt() and checked against
709 the secret again; thus secrets for authenticating the peer can be
710 stored in encrypted form.  If the \fBpapcrypt\fR option is given, the
711 first (unencrypted) comparison is omitted, for better security.
712 .LP
713 If the \fBlogin\fR option was specified, the
714 username and password are also checked against the system password
715 database.  Thus, the system administrator can set up the pap-secrets
716 file to allow PPP access only to certain users, and to restrict the
717 set of IP addresses that each user can use.  Typically, when using the
718 \fBlogin\fR option, the secret in /etc/ppp/pap-secrets would be "", to
719 avoid the need to have the same secret in two places.
720 .LP
721 Secrets are selected from the CHAP secrets file as follows:
722 .TP 2
723 *
724 For authenticating the peer, look for a secret with client == name
725 specified in the CHAP-Response message, and server == local name.
726 .TP 2
727 *
728 For authenticating ourselves to the peer, look for a secret with
729 client == local name, and server == name specified in the
730 CHAP-Challenge message.
731 .LP
732 Authentication must be satisfactorily completed before IPCP (or any
733 other Network Control Protocol) can be started.  If authentication
734 fails, \fIpppd\fR will terminated the link (by closing LCP).  If IPCP
735 negotiates an unacceptable IP address for the remote host, IPCP will
736 be closed.  IP packets can only be sent or received when IPCP is open.
737 .LP
738 In some cases it is desirable to allow some hosts which can't
739 authenticate themselves to connect and use one of a restricted set of
740 IP addresses, even when the local host generally requires
741 authentication.  If the peer refuses to authenticate itself when
742 requested, \fIpppd\fR takes that as equivalent to authenticating with
743 PAP using the empty string for the username and password.  Thus, by
744 adding a line to the pap-secrets file which specifies the empty string
745 for the client and password, it is possible to allow restricted access
746 to hosts which refuse to authenticate themselves.
747 .SH ROUTING
748 .LP
749 When IPCP negotiation is completed successfully,
750 .I pppd
751 will inform the kernel of the local and remote IP addresses for the
752 ppp interface.  This is sufficient to create a
753 host route to the remote end of the link, which will enable the peers
754 to exchange IP packets.  Communication with other machines generally
755 requires further modification to routing tables and/or ARP (Address
756 Resolution Protocol) tables.  In some cases this will be done
757 automatically through the actions of the \fIrouted\fR or \fIgated\fR
758 daemons, but in most cases some further intervention is required.
759 .LP
760 Sometimes it is desirable
761 to add a default route through the remote host, as in the case of a
762 machine whose only connection to the Internet is through the ppp
763 interface.  The \fBdefaultroute\fR option causes \fIpppd\fR to create such a
764 default route when IPCP comes up, and delete it when the link is
765 terminated.
766 .LP
767 In some cases it is desirable to use proxy ARP, for example on a
768 server machine connected to a LAN, in order to allow other hosts to
769 communicate with the remote host.  The \fBproxyarp\fR option causes \fIpppd\fR
770 to look for a network interface on the same subnet as the remote host
771 (an interface supporting broadcast and ARP, which is up and not a
772 point-to-point or loopback interface).  If found, \fIpppd\fR creates a
773 permanent, published ARP entry with the IP address of the remote host
774 and the hardware address of the network interface found.
775 .SH EXAMPLES
776 .LP
777 In the simplest case, you can connect the serial ports of two machines
778 and issue a command like
779 .IP
780 pppd /dev/ttya 9600 passive
781 .LP
782 to each machine, assuming there is no \fIgetty\fR running on the
783 serial ports.  If one machine has a \fIgetty\fR running, you can use
784 \fIkermit\fR or \fItip\fR on the other machine to log in to the first
785 machine and issue a command like
786 .IP
787 pppd passive
788 .LP
789 Then exit from the communications program (making sure the connection
790 isn't dropped), and issue a command like
791 .IP
792 pppd /dev/ttya 9600
793 .LP
794 The process of logging in to the other machine and starting \fIpppd\fR
795 can be automated by using the \fBconnect\fR option to run \fIchat\fR,
796 for example:
797 .IP
798 pppd /dev/ttya 38400 connect 'chat "" "" "login:" "username"
799 "Password:" "password" "% " "exec pppd passive"'
800 .LP
801 (Note however that running chat like this will leave the password
802 visible in the parameter list of pppd and chat.)
803 .LP
804 If your serial connection is any more complicated than a piece of
805 wire, you may need to arrange for some control characters to be
806 escaped.  In particular, it is often useful to escape XON (^Q) and
807 XOFF (^S), using \fBasyncmap a0000\fR.  If the path includes a telnet,
808 you probably should escape ^] as well (\fBasyncmap 200a0000\fR).
809 If the path includes an rlogin, you will need to use the \fBescape
810 ff\fR option on the end which is running the rlogin client, since many
811 rlogin implementations are not
812 transparent; they will remove the sequence [0xff, 0xff, 0x73, 0x73,
813 followed by any 8 bytes] from the stream.
814 .SH DIAGNOSTICS
815 .LP
816 Messages are sent to the syslog daemon using facility LOG_DAEMON.
817 (This can be overriden by recompiling \fIpppd\fR with the macro
818 LOG_PPP defined as the desired facility.)  In order to see the error
819 and debug messages, you will need to edit your /etc/syslog.conf file
820 to direct the messages to the desired output device or file.
821 .LP
822 The \fBdebug\fR option causes the contents of all control packets sent
823 or received to be logged, that is, all LCP, PAP, CHAP or IPCP packets.
824 This can be useful if the PPP negotiation does not succeed.
825 If debugging is enabled at compile time, the \fBdebug\fR option also
826 causes other debugging messages to be logged.
827 .LP
828 Debugging can also be enabled or disabled by sending a
829 SIGUSR1 to the
830 .I pppd
831 process.  This signal acts as a toggle.
832 .SH FILES
833 .TP
834 .B /var/run/ppp\fIn\fB.pid \fR(BSD or Linux), \fB/etc/ppp/ppp\fIn\fB.pid \fR(others)
835 Process-ID for \fIpppd\fR process on ppp interface unit \fIn\fR.
836 .TP
837 .B /etc/ppp/ip-up
838 A program or script which is executed when the link is available for
839 sending and receiving IP packets (that is, IPCP has come up).  It is
840 executed with the parameters
841 .IP
842 \fIinterface-name tty-device speed local-IP-address
843 remote-IP-address\fR
844 .IP
845 and with its standard input,
846 output and error streams redirected to \fB/dev/null\fR.
847 .IP
848 This program or script is executed with the same real and effective
849 user-ID as \fIpppd\fR, that is, at least the effective user-ID and
850 possibly the real user-ID will be \fBroot\fR.  This is so that it can
851 be used to manipulate routes, run privileged daemons (e.g.
852 \fBsendmail\fR), etc.  Be careful that the contents of the
853 /etc/ppp/ip-up and /etc/ppp/ip-down scripts do not compromise your
854 system's security.
855 .IP
856 This program or script is executed without an environment, so you
857 must either specify a PATH or use full pathnames (e.g. \fI/sbin/route\fR,
858 as opposed to \fIroute\fR).
859 .TP
860 .B /etc/ppp/ip-down
861 A program or script which is executed when the link is no longer
862 available for sending and receiving IP packets.  This script can be
863 used for undoing the effects of the /etc/ppp/ip-up script.  It is
864 invoked with the same parameters as the ip-up script, and the same
865 security considerations apply, since it is executed with the same
866 effective and real user-IDs as \fIpppd\fR.
867 .TP
868 .B /etc/ppp/ipx-up
869 A program or script which is executed when the link is available for
870 sending and receiving IPX packets (that is, IPXCP has come up).  It is
871 executed with the parameters
872 .IP
873 \fIinterface-name tty-device speed network-number local-IPX-node-address
874 remote-IPX-node-address local-IPX-routing-protocol remote-IPX-routing-protocol
875 local-IPX-router-name remote-IPX-router-name ipparam pppd-pid\fR 
876 .IP
877 and with its standard input,
878 output and error streams redirected to \fB/dev/null\fR.
879 .br
880 .IP
881 The local-IPX-routing-protocol and remote-IPX-routing-protocol field
882 may be one of the following:
883 .IP
884 NONE      to indicate that there is no routing protocol
885 .br
886 RIP       to indicate that RIP/SAP should be used
887 .br
888 NLSP      to indicate that Novell NLSP should be used
889 .br
890 RIP NLSP  to indicate that both RIP/SAP and NLSP should be used
891 .br
892 .IP
893 This program or script is executed with the same real and effective
894 user-ID as \fIpppd\fR, that is, at least the effective user-ID and
895 possibly the real user-ID will be \fBroot\fR.  This is so that it can
896 be used to manipulate routes, run privileged daemons (e.g.
897 \fBripd\fR), etc.  Be careful that the contents of the
898 /etc/ppp/ipx-up and /etc/ppp/ipx-down scripts do not compromise your
899 system's security.
900 .TP
901 .B /etc/ppp/ipx-down
902 A program or script which is executed when the link is no longer
903 available for sending and receiving IPX packets.  This script can be
904 used for undoing the effects of the /etc/ppp/ipx-up script.  It is
905 invoked with the same parameters as the ipx-up script, and the same
906 security considerations apply, since it is executed with the same
907 effective and real user-IDs as \fIpppd\fR.
908 .TP
909 .B /etc/ppp/pap-secrets
910 Usernames, passwords and IP addresses for PAP authentication.
911 .TP
912 .B /etc/ppp/chap-secrets
913 Names, secrets and IP addresses for CHAP authentication.
914 .TP
915 .B /etc/ppp/options
916 System default options for
917 .I pppd,
918 read before user default options or command-line options.
919 .TP
920 .B ~/.ppprc
921 User default options, read before command-line options.
922 .TP
923 .B /etc/ppp/options.\fIttyname
924 System default options for the serial port being used, read after
925 command-line options.  In forming the \fIttyname\fR part of this
926 filename, an initial /dev/ is stripped from the port name (if
927 present), and any slashes in the remaining part are converted to
928 dots.
929 .SH SEE ALSO
930 .TP
931 .B RFC1144
932 Jacobson, V.
933 .I Compressing TCP/IP headers for low-speed serial links.
934 February 1990.
935 .TP
936 .B RFC1321
937 Rivest, R.
938 .I The MD5 Message-Digest Algorithm.
939 April 1992.
940 .TP
941 .B RFC1332
942 McGregor, G.
943 .I PPP Internet Protocol Control Protocol (IPCP).
944 May 1992.
945 .TP
946 .B RFC1334
947 Lloyd, B.; Simpson, W.A.
948 .I PPP authentication protocols.
949 October 1992.
950 .TP
951 .B RFC1661
952 Simpson, W.A.
953 .I The Point\-to\-Point Protocol (PPP).
954 July 1994.
955 .TP
956 .B RFC1662
957 Simpson, W.A.
958 .I PPP in HDLC-like Framing.
959 July 1994.
960 .SH NOTES
961 The following signals have the specified effect when sent to the
962 .I pppd
963 process.
964 .TP
965 .B SIGINT, SIGTERM
966 These signals cause \fBpppd\fR to terminate the link (by closing LCP),
967 restore the serial device settings, and exit.
968 .TP
969 .B SIGHUP
970 This signal causes \fBpppd\fR to terminate the link, restore the
971 serial device settings, and close the serial device.  If the
972 \fBpersist\fR option has been specified, \fBpppd\fR will try to reopen
973 the serial device and start another connection.  Otherwise \fBpppd\fR
974 will exit.
975 .TP
976 .B SIGUSR2
977 This signal causes
978 .B pppd
979 to renegotiate compression.  This can be useful to re-enable
980 compression after it has been disabled as a result of a fatal
981 decompression error.  With the BSD Compress scheme, fatal
982 decompression errors generally indicate a bug in one or other
983 implementation.
984
985 .SH AUTHORS
986 Paul Mackerras (paulus@cs.anu.edu.au), based on earlier work by
987 Drew Perkins,
988 Brad Clements,
989 Karl Fox,
990 Greg Christy,
991 and
992 Brad Parker.