Describe the /etc/ppp/ip-pre-up script.
[ppp.git] / pppd / pppd.8
1 .\" manual page [] for pppd 2.4
2 .\" $Id: pppd.8,v 1.86 2005/08/26 00:06:35 paulus Exp $
3 .\" SH section heading
4 .\" SS subsection heading
5 .\" LP paragraph
6 .\" IP indented paragraph
7 .\" TP hanging label
8 .\" 
9 .\" Copyright (c) 1993-2003 Paul Mackerras <paulus@samba.org>
10 .\"
11 .\" Permission to use, copy, modify, and distribute this software for any
12 .\" purpose with or without fee is hereby granted, provided that the above
13 .\" copyright notice and this permission notice appear in all copies.
14 .\"
15 .\" THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES
16 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
17 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
18 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
19 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
20 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
21 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
22 .\"
23 .TH PPPD 8
24 .SH NAME
25 pppd \- Point-to-Point Protocol Daemon
26 .SH SYNOPSIS
27 .B pppd
28 [
29 .I options
30 ]
31 .SH DESCRIPTION
32 .LP
33 PPP is the protocol used for establishing internet links over dial-up
34 modems, DSL connections, and many other types of point-to-point
35 links.  The \fIpppd\fR daemon works together with the kernel PPP
36 driver to establish and maintain a PPP link with another system
37 (called the \fIpeer\fR) and to negotiate Internet Protocol (IP)
38 addresses for each end of the link.  Pppd can also authenticate the
39 peer and/or supply authentication information to the peer.  PPP can be
40 used with other network protocols besides IP, but such use is becoming
41 increasingly rare.
42 .SH FREQUENTLY USED OPTIONS
43 .TP
44 .I ttyname
45 Use the serial port called \fIttyname\fR to communicate with the
46 peer.  If \fIttyname\fR does not begin with a slash (/),
47 the string "/dev/" is prepended to \fIttyname\fR to form the
48 name of the device to open.  If no device name is given, or if the
49 name of the terminal
50 connected to the standard input is given, pppd will use that terminal,
51 and will not fork to put itself in the background.  A value for this
52 option from a privileged source cannot be overridden by a
53 non-privileged user.
54 .TP
55 .I speed
56 An option that is a decimal number is taken as the desired baud rate
57 for the serial device.  On systems such as
58 4.4BSD and NetBSD, any speed can be specified.  Other systems
59 (e.g. Linux, SunOS) only support the commonly-used baud rates.
60 .TP
61 .B asyncmap \fImap
62 This option sets the Async-Control-Character-Map (ACCM) for this end
63 of the link.  The ACCM is a set of 32 bits, one for each of the
64 ASCII control characters with values from 0 to 31, where a 1 bit
65 indicates that the corresponding control character should not be used
66 in PPP packets sent to this system.  The map is encoded as a
67 hexadecimal number (without a leading 0x) where the least significant
68 bit (00000001) represents character 0 and the most significant bit
69 (80000000) represents character 31.
70 Pppd will ask the peer to send these characters as a 2-byte
71 escape sequence.
72 If multiple \fIasyncmap\fR options are given, the values are ORed
73 together.  If no \fIasyncmap\fR option is given, the default is zero,
74 so pppd will ask the peer not to escape any control characters.
75 To escape transmitted characters, use the \fIescape\fR option.
76 .TP
77 .B auth
78 Require the peer to authenticate itself before allowing network
79 packets to be sent or received.  This option is the default if the
80 system has a default route.  If neither this option nor the
81 \fInoauth\fR option is specified, pppd will only allow the peer to use
82 IP addresses to which the system does not already have a route.
83 .TP
84 .B call \fIname
85 Read additional options from the file /etc/ppp/peers/\fIname\fR.  This
86 file may contain privileged options, such as \fInoauth\fR, even if pppd
87 is not being run by root.  The \fIname\fR string may not begin with /
88 or include .. as a pathname component.  The format of the options file
89 is described below.
90 .TP
91 .B connect \fIscript
92 Usually there is something which needs to be done to prepare the link
93 before the PPP protocol can be started; for instance, with a dial-up
94 modem, commands need to be sent to the modem to dial the appropriate
95 phone number.  This option specifies an command for pppd to execute
96 (by passing it to a shell) before attempting to start PPP negotiation.
97 The chat (8) program is often useful here, as it provides a way to
98 send arbitrary strings to a modem and respond to received characters.
99 A value
100 for this option from a privileged source cannot be overridden by a
101 non-privileged user.
102 .TP
103 .B crtscts
104 Specifies that pppd should set the serial port to use hardware flow
105 control using the RTS and CTS signals in the RS-232 interface.
106 If neither the \fIcrtscts\fR, the
107 \fInocrtscts\fR, the \fIcdtrcts\fR nor the \fInocdtrcts\fR option
108 is given, the hardware flow control setting for the serial port is
109 left unchanged.
110 Some serial ports (such as Macintosh serial ports) lack a true
111 RTS output. Such serial ports use this mode to implement
112 unidirectional flow control. The serial port will
113 suspend transmission when requested by the modem (via CTS)
114 but will be unable to request the modem to stop sending to the
115 computer. This mode retains the ability to use DTR as
116 a modem control line.
117 .TP
118 .B defaultroute
119 Add a default route to the system routing tables, using the peer as
120 the gateway, when IPCP negotiation is successfully completed.
121 This entry is removed when the PPP connection is broken.  This option
122 is privileged if the \fInodefaultroute\fR option has been specified.
123 .TP
124 .B disconnect \fIscript
125 Execute the command specified by \fIscript\fR, by passing it to a
126 shell, after
127 pppd has terminated the link.  This command could, for example, issue
128 commands to the modem to cause it to hang up if hardware modem control
129 signals were not available.  The disconnect script is not run if the
130 modem has already hung up.  A value for this option from a privileged
131 source cannot be overridden by a non-privileged user.
132 .TP
133 .B escape \fIxx,yy,...
134 Specifies that certain characters should be escaped on transmission
135 (regardless of whether the peer requests them to be escaped with its
136 async control character map).  The characters to be escaped are
137 specified as a list of hex numbers separated by commas.  Note that
138 almost any character can be specified for the \fIescape\fR option,
139 unlike the \fIasyncmap\fR option which only allows control characters
140 to be specified.  The characters which may not be escaped are those
141 with hex values 0x20 - 0x3f or 0x5e.
142 .TP
143 .B file \fIname
144 Read options from file \fIname\fR (the format is described below).
145 The file must be readable by the user who has invoked pppd.
146 .TP
147 .B init \fIscript
148 Execute the command specified by \fIscript\fR, by passing it to a shell, to
149 initialize the serial line.  This script would typically use the
150 chat(8) program to configure the modem to enable auto answer.  A value
151 for this option from a privileged source cannot be overridden by a
152 non-privileged user.
153 .TP
154 .B lock
155 Specifies that pppd should create a UUCP-style lock file for the
156 serial device to ensure exclusive access to the device.
157 .TP
158 .B mru \fIn
159 Set the MRU [Maximum Receive Unit] value to \fIn\fR. Pppd
160 will ask the peer to send packets of no more than \fIn\fR bytes.
161 The value of \fIn\fR must be between 128 and 16384; the default is 1500.
162 A value of
163 296 works well on very slow links (40 bytes for TCP/IP header + 256
164 bytes of data).
165 Note that for the IPv6 protocol, the MRU must be at least 1280.
166 .TP
167 .B mtu \fIn
168 Set the MTU [Maximum Transmit Unit] value to \fIn\fR.  Unless the
169 peer requests a smaller value via MRU negotiation, pppd will
170 request that the kernel networking code send data packets of no more
171 than \fIn\fR bytes through the PPP network interface.  Note that for 
172 the IPv6 protocol, the MTU must be at least 1280.
173 .TP
174 .B passive
175 Enables the "passive" option in the LCP.  With this option, pppd will
176 attempt to initiate a connection; if no reply is received from the
177 peer, pppd will then just wait passively for a valid LCP packet from
178 the peer, instead of exiting, as it would without this option.
179 .SH OPTIONS
180 .TP
181 .I <local_IP_address>\fB:\fI<remote_IP_address>
182 Set the local and/or remote interface IP addresses.  Either one may be
183 omitted.  The IP addresses can be specified with a host name or in
184 decimal dot notation (e.g. 150.234.56.78).  The default local
185 address is the (first) IP address of the system (unless the
186 \fInoipdefault\fR
187 option is given).  The remote address will be obtained from the peer
188 if not specified in any option.  Thus, in simple cases, this option is
189 not required.  If a local and/or remote IP address is specified with
190 this option, pppd
191 will not accept a different value from the peer in the IPCP
192 negotiation, unless the \fIipcp\-accept\-local\fR and/or
193 \fIipcp\-accept\-remote\fR options are given, respectively.
194 .TP
195 .B ipv6 \fI<local_interface_identifier>\fR,\fI<remote_interface_identifier>
196 Set the local and/or remote 64-bit interface identifier. Either one may be
197 omitted. The identifier must be specified in standard ascii notation of
198 IPv6 addresses (e.g. ::dead:beef). If the
199 \fIipv6cp\-use\-ipaddr\fR
200 option is given, the local identifier is the local IPv4 address (see above).
201 On systems which supports a unique persistent id, such as EUI\-48 derived
202 from the Ethernet MAC address, \fIipv6cp\-use\-persistent\fR option can be
203 used to replace the \fIipv6 <local>,<remote>\fR option. Otherwise the 
204 identifier is randomized.
205 .TP
206 .B active\-filter \fIfilter\-expression
207 Specifies a packet filter to be applied to data packets to determine
208 which packets are to be regarded as link activity, and therefore reset
209 the idle timer, or cause the link to be brought up in demand-dialling
210 mode.  This option is useful in conjunction with the
211 \fBidle\fR option if there are packets being sent or received
212 regularly over the link (for example, routing information packets)
213 which would otherwise prevent the link from ever appearing to be idle.
214 The \fIfilter\-expression\fR syntax is as described for tcpdump(1),
215 except that qualifiers which are inappropriate for a PPP link, such as
216 \fBether\fR and \fBarp\fR, are not permitted.  Generally the filter
217 expression should be enclosed in single-quotes to prevent whitespace
218 in the expression from being interpreted by the shell. This option
219 is currently only available under Linux, and requires that the kernel
220 was configured to include PPP filtering support (CONFIG_PPP_FILTER).
221 Note that it
222 is possible to apply different constraints to incoming and outgoing
223 packets using the \fBinbound\fR and \fBoutbound\fR qualifiers.
224 .TP
225 .B allow\-ip \fIaddress(es)
226 Allow peers to use the given IP address or subnet without
227 authenticating themselves.  The parameter is parsed as for each
228 element of the list of allowed IP addresses in the secrets files (see
229 the AUTHENTICATION section below).
230 .TP
231 .B allow\-number \fInumber
232 Allow peers to connect from the given telephone number.  A trailing
233 `*' character will match all numbers beginning with the leading part.
234 .TP
235 .B bsdcomp \fInr,nt
236 Request that the peer compress packets that it sends, using the
237 BSD-Compress scheme, with a maximum code size of \fInr\fR bits, and
238 agree to compress packets sent to the peer with a maximum code size of
239 \fInt\fR bits.  If \fInt\fR is not specified, it defaults to the value
240 given for \fInr\fR.  Values in the range 9 to 15 may be used for
241 \fInr\fR and \fInt\fR; larger values give better compression but
242 consume more kernel memory for compression dictionaries.
243 Alternatively, a value of 0 for \fInr\fR or \fInt\fR disables
244 compression in the corresponding direction.  Use \fInobsdcomp\fR or
245 \fIbsdcomp 0\fR to disable BSD-Compress compression entirely.
246 .TP
247 .B cdtrcts
248 Use a non-standard hardware flow control (i.e. DTR/CTS) to control
249 the flow of data on the serial port.  If neither the \fIcrtscts\fR,
250 the \fInocrtscts\fR, the \fIcdtrcts\fR nor the \fInocdtrcts\fR
251 option is given, the hardware flow control setting for the serial
252 port is left unchanged.
253 Some serial ports (such as Macintosh serial ports) lack a true
254 RTS output. Such serial ports use this mode to implement true
255 bi-directional flow control. The sacrifice is that this flow
256 control mode does not permit using DTR as a modem control line.
257 .TP
258 .B chap\-interval \fIn
259 If this option is given, pppd will rechallenge the peer every \fIn\fR
260 seconds.
261 .TP
262 .B chap\-max\-challenge \fIn
263 Set the maximum number of CHAP challenge transmissions to \fIn\fR
264 (default 10).
265 .TP
266 .B chap\-restart \fIn
267 Set the CHAP restart interval (retransmission timeout for challenges)
268 to \fIn\fR seconds (default 3).
269 .TP
270 .B child\-timeout \fIn
271 When exiting, wait for up to \fIn\fR seconds for any child processes
272 (such as the command specified with the \fBpty\fR command) to exit
273 before exiting.  At the end of the timeout, pppd will send a SIGTERM
274 signal to any remaining child processes and exit.  A value of 0 means
275 no timeout, that is, pppd will wait until all child processes have
276 exited.
277 .TP
278 .B connect\-delay \fIn
279 Wait for up to \fIn\fR milliseconds after the connect script finishes for
280 a valid PPP packet from the peer.  At the end of this time, or when a
281 valid PPP packet is received from the peer, pppd will commence
282 negotiation by sending its first LCP packet.  The default value is
283 1000 (1 second).  This wait period only applies if the \fBconnect\fR
284 or \fBpty\fR option is used.
285 .TP
286 .B debug
287 Enables connection debugging facilities.
288 If this option is given, pppd will log the contents of all
289 control packets sent or received in a readable form.  The packets are
290 logged through syslog with facility \fIdaemon\fR and level
291 \fIdebug\fR.  This information can be directed to a file by setting up
292 /etc/syslog.conf appropriately (see syslog.conf(5)).
293 .TP
294 .B default\-asyncmap
295 Disable asyncmap negotiation, forcing all control characters to be
296 escaped for both the transmit and the receive direction.
297 .TP
298 .B default\-mru
299 Disable MRU [Maximum Receive Unit] negotiation.  With this option,
300 pppd will use the default MRU value of 1500 bytes for both the
301 transmit and receive direction.
302 .TP
303 .B deflate \fInr,nt
304 Request that the peer compress packets that it sends, using the
305 Deflate scheme, with a maximum window size of \fI2**nr\fR bytes, and
306 agree to compress packets sent to the peer with a maximum window size
307 of \fI2**nt\fR bytes.  If \fInt\fR is not specified, it defaults to
308 the value given for \fInr\fR.  Values in the range 9 to 15 may be used
309 for \fInr\fR and \fInt\fR; larger values give better compression but
310 consume more kernel memory for compression dictionaries.
311 Alternatively, a value of 0 for \fInr\fR or \fInt\fR disables
312 compression in the corresponding direction.  Use \fInodeflate\fR or
313 \fIdeflate 0\fR to disable Deflate compression entirely.  (Note: pppd
314 requests Deflate compression in preference to BSD-Compress if the peer
315 can do either.)
316 .TP
317 .B demand
318 Initiate the link only on demand, i.e. when data traffic is present.
319 With this option, the remote IP address must be specified by the user
320 on the command line or in an options file.  Pppd will initially
321 configure the interface and enable it for IP traffic without
322 connecting to the peer.  When traffic is available, pppd will
323 connect to the peer and perform negotiation, authentication, etc.
324 When this is completed, pppd will commence passing data packets
325 (i.e., IP packets) across the link.
326
327 The \fIdemand\fR option implies the \fIpersist\fR option.  If this
328 behaviour is not desired, use the \fInopersist\fR option after the
329 \fIdemand\fR option.  The \fIidle\fR and \fIholdoff\fR
330 options are also useful in conjuction with the \fIdemand\fR option.
331 .TP
332 .B domain \fId
333 Append the domain name \fId\fR to the local host name for authentication
334 purposes.  For example, if gethostname() returns the name porsche, but
335 the fully qualified domain name is porsche.Quotron.COM, you could
336 specify \fIdomain Quotron.COM\fR.  Pppd would then use the name
337 \fIporsche.Quotron.COM\fR for looking up secrets in the secrets file,
338 and as the default name to send to the peer when authenticating itself
339 to the peer.  This option is privileged.
340 .TP
341 .B dryrun
342 With the \fBdryrun\fR option, pppd will print out all the option
343 values which have been set and then exit, after parsing the command
344 line and options files and checking the option values, but before
345 initiating the link.  The option values are logged at level info, and
346 also printed to standard output unless the device on standard output
347 is the device that pppd would be using to communicate with the peer.
348 .TP
349 .B dump
350 With the \fBdump\fR option, pppd will print out all the option values
351 which have been set.  This option is like the \fBdryrun\fR option
352 except that pppd proceeds as normal rather than exiting.
353 .TP
354 .B endpoint \fI<epdisc>
355 Sets the endpoint discriminator sent by the local machine to the peer
356 during multilink negotiation to \fI<epdisc>\fR.  The default is to use
357 the MAC address of the first ethernet interface on the system, if any,
358 otherwise the IPv4 address corresponding to the hostname, if any,
359 provided it is not in the multicast or locally-assigned IP address
360 ranges, or the localhost address.  The endpoint discriminator can be
361 the string \fBnull\fR or of the form \fItype\fR:\fIvalue\fR, where
362 type is a decimal number or one of the strings \fBlocal\fR, \fBIP\fR,
363 \fBMAC\fR, \fBmagic\fR, or \fBphone\fR.  The value is an IP address in
364 dotted-decimal notation for the \fBIP\fR type, or a string of bytes in
365 hexadecimal, separated by periods or colons for the other types.  For
366 the MAC type, the value may also be the name of an ethernet or similar
367 network interface.  This option is currently only available under
368 Linux.
369 .TP
370 .B eap\-interval \fIn
371 If this option is given and pppd authenticates the peer with EAP
372 (i.e., is the server), pppd will restart EAP authentication every
373 \fIn\fR seconds.  For EAP SRP\-SHA1, see also the \fBsrp\-interval\fR
374 option, which enables lightweight rechallenge.
375 .TP
376 .B eap\-max\-rreq \fIn
377 Set the maximum number of EAP Requests to which pppd will respond (as
378 a client) without hearing EAP Success or Failure.  (Default is 20.)
379 .TP
380 .B eap\-max\-sreq \fIn
381 Set the maximum number of EAP Requests that pppd will issue (as a
382 server) while attempting authentication.  (Default is 10.)
383 .TP
384 .B eap\-restart \fIn
385 Set the retransmit timeout for EAP Requests when acting as a server
386 (authenticator).  (Default is 3 seconds.)
387 .TP
388 .B eap\-timeout \fIn
389 Set the maximum time to wait for the peer to send an EAP Request when
390 acting as a client (authenticatee).  (Default is 20 seconds.)
391 .TP
392 .B hide\-password
393 When logging the contents of PAP packets, this option causes pppd to
394 exclude the password string from the log.  This is the default.
395 .TP
396 .B holdoff \fIn
397 Specifies how many seconds to wait before re-initiating the link after
398 it terminates.  This option only has any effect if the \fIpersist\fR
399 or \fIdemand\fR option is used.  The holdoff period is not applied if
400 the link was terminated because it was idle.
401 .TP
402 .B idle \fIn
403 Specifies that pppd should disconnect if the link is idle for \fIn\fR
404 seconds.  The link is idle when no data packets (i.e. IP packets) are
405 being sent or received.  Note: it is not advisable to use this option
406 with the \fIpersist\fR option without the \fIdemand\fR option.
407 If the \fBactive\-filter\fR
408 option is given, data packets which are rejected by the specified
409 activity filter also count as the link being idle.
410 .TP
411 .B ipcp\-accept\-local
412 With this option, pppd will accept the peer's idea of our local IP
413 address, even if the local IP address was specified in an option.
414 .TP
415 .B ipcp\-accept\-remote
416 With this option, pppd will accept the peer's idea of its (remote) IP
417 address, even if the remote IP address was specified in an option.
418 .TP
419 .B ipcp\-max\-configure \fIn
420 Set the maximum number of IPCP configure-request transmissions to
421 \fIn\fR (default 10).
422 .TP
423 .B ipcp\-max\-failure \fIn
424 Set the maximum number of IPCP configure-NAKs returned before starting
425 to send configure-Rejects instead to \fIn\fR (default 10).
426 .TP
427 .B ipcp\-max\-terminate \fIn
428 Set the maximum number of IPCP terminate-request transmissions to
429 \fIn\fR (default 3).
430 .TP
431 .B ipcp\-restart \fIn
432 Set the IPCP restart interval (retransmission timeout) to \fIn\fR
433 seconds (default 3).
434 .TP
435 .B ipparam \fIstring
436 Provides an extra parameter to the ip\-up, ip\-pre\-up and ip\-down
437 scripts.  If this
438 option is given, the \fIstring\fR supplied is given as the 6th
439 parameter to those scripts.
440 .TP
441 .B ipv6cp\-max\-configure \fIn
442 Set the maximum number of IPv6CP configure-request transmissions to
443 \fIn\fR (default 10).
444 .TP
445 .B ipv6cp\-max\-failure \fIn
446 Set the maximum number of IPv6CP configure-NAKs returned before starting
447 to send configure-Rejects instead to \fIn\fR (default 10).
448 .TP
449 .B ipv6cp\-max\-terminate \fIn
450 Set the maximum number of IPv6CP terminate-request transmissions to
451 \fIn\fR (default 3).
452 .TP
453 .B ipv6cp\-restart \fIn
454 Set the IPv6CP restart interval (retransmission timeout) to \fIn\fR
455 seconds (default 3).
456 .TP
457 .B ipx
458 Enable the IPXCP and IPX protocols.  This option is presently only
459 supported under Linux, and only if your kernel has been configured to
460 include IPX support.
461 .TP
462 .B ipx\-network \fIn
463 Set the IPX network number in the IPXCP configure request frame to
464 \fIn\fR, a hexadecimal number (without a leading 0x).  There is no
465 valid default.  If this option is not specified, the network number is
466 obtained from the peer.  If the peer does not have the network number,
467 the IPX protocol will not be started.
468 .TP
469 .B ipx\-node \fIn\fB:\fIm
470 Set the IPX node numbers. The two node numbers are separated from each
471 other with a colon character. The first number \fIn\fR is the local
472 node number. The second number \fIm\fR is the peer's node number. Each
473 node number is a hexadecimal number, at most 10 digits long. The node
474 numbers on the ipx\-network must be unique. There is no valid
475 default. If this option is not specified then the node numbers are
476 obtained from the peer.
477 .TP
478 .B ipx\-router\-name \fI<string>
479 Set the name of the router. This is a string and is sent to the peer
480 as information data.
481 .TP
482 .B ipx\-routing \fIn
483 Set the routing protocol to be received by this option. More than one
484 instance of \fIipx\-routing\fR may be specified. The '\fInone\fR'
485 option (0) may be specified as the only instance of ipx\-routing. The
486 values may be \fI0\fR for \fINONE\fR, \fI2\fR for \fIRIP/SAP\fR, and
487 \fI4\fR for \fINLSP\fR.
488 .TP
489 .B ipxcp\-accept\-local
490 Accept the peer's NAK for the node number specified in the ipx\-node
491 option. If a node number was specified, and non-zero, the default is
492 to insist that the value be used. If you include this option then you
493 will permit the peer to override the entry of the node number.
494 .TP
495 .B ipxcp\-accept\-network
496 Accept the peer's NAK for the network number specified in the
497 ipx\-network option. If a network number was specified, and non-zero, the
498 default is to insist that the value be used. If you include this
499 option then you will permit the peer to override the entry of the node
500 number.
501 .TP
502 .B ipxcp\-accept\-remote
503 Use the peer's network number specified in the configure request
504 frame. If a node number was specified for the peer and this option was
505 not specified, the peer will be forced to use the value which you have
506 specified.
507 .TP
508 .B ipxcp\-max\-configure \fIn
509 Set the maximum number of IPXCP configure request frames which the
510 system will send to \fIn\fR. The default is 10.
511 .TP
512 .B ipxcp\-max\-failure \fIn
513 Set the maximum number of IPXCP NAK frames which the local system will
514 send before it rejects the options. The default value is 3.
515 .TP
516 .B ipxcp\-max\-terminate \fIn
517 Set the maximum nuber of IPXCP terminate request frames before the
518 local system considers that the peer is not listening to them. The
519 default value is 3.
520 .TP
521 .B kdebug \fIn
522 Enable debugging code in the kernel-level PPP driver.  The argument
523 values depend on the specific kernel driver, but in general a value of
524 1 will enable general kernel debug messages.  (Note that these
525 messages are usually only useful for debugging the kernel driver
526 itself.)  For the Linux 2.2.x kernel driver, the value is a sum of
527 bits: 1 to
528 enable general debug messages, 2 to request that the contents of
529 received packets be printed, and 4 to request that the contents of
530 transmitted packets be printed.  On most systems, messages printed by
531 the kernel are logged by syslog(1) to a file as directed in the
532 /etc/syslog.conf configuration file.
533 .TP
534 .B ktune
535 Enables pppd to alter kernel settings as appropriate.  Under Linux,
536 pppd will enable IP forwarding (i.e. set /proc/sys/net/ipv4/ip_forward
537 to 1) if the \fIproxyarp\fR option is used, and will enable the
538 dynamic IP address option (i.e. set /proc/sys/net/ipv4/ip_dynaddr to
539 1) in demand mode if the local address changes.
540 .TP
541 .B lcp\-echo\-failure \fIn
542 If this option is given, pppd will presume the peer to be dead
543 if \fIn\fR LCP echo\-requests are sent without receiving a valid LCP
544 echo\-reply.  If this happens, pppd will terminate the
545 connection.  Use of this option requires a non-zero value for the
546 \fIlcp\-echo\-interval\fR parameter.  This option can be used to enable
547 pppd to terminate after the physical connection has been broken
548 (e.g., the modem has hung up) in situations where no hardware modem
549 control lines are available.
550 .TP
551 .B lcp\-echo\-interval \fIn
552 If this option is given, pppd will send an LCP echo\-request frame to
553 the peer every \fIn\fR seconds.  Normally the peer should respond to
554 the echo\-request by sending an echo\-reply.  This option can be used
555 with the \fIlcp\-echo\-failure\fR option to detect that the peer is no
556 longer connected.
557 .TP
558 .B lcp\-max\-configure \fIn
559 Set the maximum number of LCP configure-request transmissions to
560 \fIn\fR (default 10).
561 .TP
562 .B lcp\-max\-failure \fIn
563 Set the maximum number of LCP configure-NAKs returned before starting
564 to send configure-Rejects instead to \fIn\fR (default 10).
565 .TP
566 .B lcp\-max\-terminate \fIn
567 Set the maximum number of LCP terminate-request transmissions to
568 \fIn\fR (default 3).
569 .TP
570 .B lcp\-restart \fIn
571 Set the LCP restart interval (retransmission timeout) to \fIn\fR
572 seconds (default 3).
573 .TP
574 .B linkname \fIname\fR
575 Sets the logical name of the link to \fIname\fR.  Pppd will create a
576 file named \fBppp\-\fIname\fB.pid\fR in /var/run (or /etc/ppp on some
577 systems) containing its process ID.  This can be useful in determining
578 which instance of pppd is responsible for the link to a given peer
579 system.  This is a privileged option.
580 .TP
581 .B local
582 Don't use the modem control lines.  With this option, pppd will ignore
583 the state of the CD (Carrier Detect) signal from the modem and will
584 not change the state of the DTR (Data Terminal Ready) signal.  This is
585 the opposite of the \fBmodem\fR option.
586 .TP
587 .B logfd \fIn
588 Send log messages to file descriptor \fIn\fR.  Pppd will send log
589 messages to at most one file or file descriptor (as well as sending
590 the log messages to syslog), so this option and the \fBlogfile\fR
591 option are mutually exclusive.  The default is for pppd to send log
592 messages to stdout (file descriptor 1), unless the serial port is
593 already open on stdout.
594 .TP
595 .B logfile \fIfilename
596 Append log messages to the file \fIfilename\fR (as well as sending the
597 log messages to syslog).  The file is opened with the privileges of
598 the user who invoked pppd, in append mode.
599 .TP
600 .B login
601 Use the system password database for authenticating the peer using
602 PAP, and record the user in the system wtmp file.  Note that the peer
603 must have an entry in the /etc/ppp/pap\-secrets file as well as the
604 system password database to be allowed access.
605 .TP
606 .B maxconnect \fIn
607 Terminate the connection when it has been available for network
608 traffic for \fIn\fR seconds (i.e. \fIn\fR seconds after the first
609 network control protocol comes up).
610 .TP
611 .B maxfail \fIn
612 Terminate after \fIn\fR consecutive failed connection attempts.  A
613 value of 0 means no limit.  The default value is 10.
614 .TP
615 .B modem
616 Use the modem control lines.  This option is the default.  With this
617 option, pppd will wait for the CD (Carrier Detect) signal from the
618 modem to be asserted when opening the serial device (unless a connect
619 script is specified), and it will drop the DTR (Data Terminal Ready)
620 signal briefly when the connection is terminated and before executing
621 the connect script.  On Ultrix, this option implies hardware flow
622 control, as for the \fIcrtscts\fR option.  This is the opposite of the
623 \fBlocal\fR option.
624 .TP
625 .B mp
626 Enables the use of PPP multilink; this is an alias for the `multilink'
627 option.  This option is currently only available under Linux.
628 .TP
629 .B mppe\-stateful
630 Allow MPPE to use stateful mode.  Stateless mode is still attempted first.
631 The default is to disallow stateful mode.  
632 .TP
633 .B mpshortseq
634 Enables the use of short (12-bit) sequence numbers in multilink
635 headers, as opposed to 24-bit sequence numbers.  This option is only
636 available under Linux, and only has any effect if multilink is
637 enabled (see the multilink option).
638 .TP
639 .B mrru \fIn
640 Sets the Maximum Reconstructed Receive Unit to \fIn\fR.  The MRRU is
641 the maximum size for a received packet on a multilink bundle, and is
642 analogous to the MRU for the individual links.  This option is
643 currently only available under Linux, and only has any effect if
644 multilink is enabled (see the multilink option).
645 .TP
646 .B ms\-dns \fI<addr>
647 If pppd is acting as a server for Microsoft Windows clients, this
648 option allows pppd to supply one or two DNS (Domain Name Server)
649 addresses to the clients.  The first instance of this option specifies
650 the primary DNS address; the second instance (if given) specifies the
651 secondary DNS address.  (This option was present in some older
652 versions of pppd under the name \fBdns\-addr\fR.)
653 .TP
654 .B ms\-wins \fI<addr>
655 If pppd is acting as a server for Microsoft Windows or "Samba"
656 clients, this option allows pppd to supply one or two WINS (Windows
657 Internet Name Services) server addresses to the clients.  The first
658 instance of this option specifies the primary WINS address; the second
659 instance (if given) specifies the secondary WINS address.
660 .TP
661 .B multilink
662 Enables the use of the PPP multilink protocol.  If the peer also
663 supports multilink, then this link can become part of a bundle between
664 the local system and the peer.  If there is an existing bundle to the
665 peer, pppd will join this link to that bundle, otherwise pppd will
666 create a new bundle.  See the MULTILINK section below.  This option is
667 currently only available under Linux.
668 .TP
669 .B name \fIname
670 Set the name of the local system for authentication purposes to
671 \fIname\fR.  This is a privileged option.  With this option, pppd will
672 use lines in the secrets files which have \fIname\fR as the second
673 field when looking for a secret to use in authenticating the peer.  In
674 addition, unless overridden with the \fIuser\fR option, \fIname\fR
675 will be used as the name to send to the peer when authenticating the
676 local system to the peer.  (Note that pppd does not append the domain
677 name to \fIname\fR.)
678 .TP
679 .B noaccomp
680 Disable Address/Control compression in both directions (send and
681 receive).
682 .TP
683 .B noauth
684 Do not require the peer to authenticate itself.  This option is
685 privileged.
686 .TP
687 .B nobsdcomp
688 Disables BSD-Compress compression; \fBpppd\fR will not request or
689 agree to compress packets using the BSD-Compress scheme.
690 .TP
691 .B noccp
692 Disable CCP (Compression Control Protocol) negotiation.  This option
693 should only be required if the peer is buggy and gets confused by
694 requests from pppd for CCP negotiation.
695 .TP
696 .B nocrtscts
697 Disable hardware flow control (i.e. RTS/CTS) on the serial port.
698 If neither the \fIcrtscts\fR nor the \fInocrtscts\fR nor the
699 \fIcdtrcts\fR nor the \fInocdtrcts\fR option is given, the hardware
700 flow control setting for the serial port is left unchanged.
701 .TP
702 .B nocdtrcts
703 This option is a synonym for \fInocrtscts\fR. Either of these options will
704 disable both forms of hardware flow control.
705 .TP
706 .B nodefaultroute
707 Disable the \fIdefaultroute\fR option.  The system administrator who
708 wishes to prevent users from creating default routes with pppd
709 can do so by placing this option in the /etc/ppp/options file.
710 .TP
711 .B nodeflate
712 Disables Deflate compression; pppd will not request or agree to
713 compress packets using the Deflate scheme.
714 .TP
715 .B nodetach
716 Don't detach from the controlling terminal.  Without this option, if a
717 serial device other than the terminal on the standard input is
718 specified, pppd will fork to become a background process.
719 .TP
720 .B noendpoint
721 Disables pppd from sending an endpoint discriminator to the peer or
722 accepting one from the peer (see the MULTILINK section below).  This
723 option should only be required if the peer is buggy.
724 .TP
725 .B noip
726 Disable IPCP negotiation and IP communication.  This option should
727 only be required if the peer is buggy and gets confused by requests
728 from pppd for IPCP negotiation.
729 .TP
730 .B noipv6
731 Disable IPv6CP negotiation and IPv6 communication. This option should
732 only be required if the peer is buggy and gets confused by requests
733 from pppd for IPv6CP negotiation.
734 .TP
735 .B noipdefault
736 Disables the default behaviour when no local IP address is specified,
737 which is to determine (if possible) the local IP address from the
738 hostname.  With this option, the peer will have to supply the local IP
739 address during IPCP negotiation (unless it specified explicitly on the
740 command line or in an options file).
741 .TP
742 .B noipx
743 Disable the IPXCP and IPX protocols.  This option should only be
744 required if the peer is buggy and gets confused by requests from pppd
745 for IPXCP negotiation.
746 .TP
747 .B noktune
748 Opposite of the \fIktune\fR option; disables pppd from changing system
749 settings.
750 .TP
751 .B nolog
752 Do not send log messages to a file or file descriptor.  This option
753 cancels the \fBlogfd\fR and \fBlogfile\fR options.
754 .TP
755 .B nomagic
756 Disable magic number negotiation.  With this option, pppd cannot
757 detect a looped-back line.  This option should only be needed if the
758 peer is buggy.
759 .TP
760 .B nomp
761 Disables the use of PPP multilink.  This option is currently only
762 available under Linux.
763 .TP
764 .B nomppe
765 Disables MPPE (Microsoft Point to Point Encryption).  This is the default.
766 .TP
767 .B nomppe\-40
768 Disable 40-bit encryption with MPPE.
769 .TP
770 .B nomppe\-128
771 Disable 128-bit encryption with MPPE.
772 .TP
773 .B nomppe\-stateful
774 Disable MPPE stateful mode.  This is the default.
775 .TP
776 .B nompshortseq
777 Disables the use of short (12-bit) sequence numbers in the PPP
778 multilink protocol, forcing the use of 24-bit sequence numbers.  This
779 option is currently only available under Linux, and only has any
780 effect if multilink is enabled.
781 .TP
782 .B nomultilink
783 Disables the use of PPP multilink.  This option is currently only
784 available under Linux.
785 .TP
786 .B nopcomp
787 Disable protocol field compression negotiation in both the receive and
788 the transmit direction.
789 .TP
790 .B nopersist
791 Exit once a connection has been made and terminated.  This is the
792 default unless the \fIpersist\fR or \fIdemand\fR option has been
793 specified.
794 .TP
795 .B nopredictor1
796 Do not accept or agree to Predictor\-1 compression.
797 .TP
798 .B noproxyarp
799 Disable the \fIproxyarp\fR option.  The system administrator who
800 wishes to prevent users from creating proxy ARP entries with pppd can
801 do so by placing this option in the /etc/ppp/options file.
802 .TP
803 .B notty
804 Normally, pppd requires a terminal device.  With this option, pppd
805 will allocate itself a pseudo-tty master/slave pair and use the slave
806 as its terminal device.  Pppd will create a child process to act as a
807 `character shunt' to transfer characters between the pseudo-tty master
808 and its standard input and output.  Thus pppd will transmit characters
809 on its standard output and receive characters on its standard input
810 even if they are not terminal devices.  This option increases the
811 latency and CPU overhead of transferring data over the ppp interface
812 as all of the characters sent and received must flow through the
813 character shunt process.  An explicit device name may not be given if
814 this option is used.
815 .TP
816 .B novj
817 Disable Van Jacobson style TCP/IP header compression in both the
818 transmit and the receive direction.
819 .TP
820 .B novjccomp
821 Disable the connection-ID compression option in Van Jacobson style
822 TCP/IP header compression.  With this option, pppd will not omit the
823 connection-ID byte from Van Jacobson compressed TCP/IP headers, nor
824 ask the peer to do so.
825 .TP
826 .B papcrypt
827 Indicates that all secrets in the /etc/ppp/pap\-secrets file which are
828 used for checking the identity of the peer are encrypted, and thus
829 pppd should not accept a password which, before encryption, is
830 identical to the secret from the /etc/ppp/pap\-secrets file.
831 .TP
832 .B pap\-max\-authreq \fIn
833 Set the maximum number of PAP authenticate-request transmissions to
834 \fIn\fR (default 10).
835 .TP
836 .B pap\-restart \fIn
837 Set the PAP restart interval (retransmission timeout) to \fIn\fR
838 seconds (default 3).
839 .TP
840 .B pap\-timeout \fIn
841 Set the maximum time that pppd will wait for the peer to authenticate
842 itself with PAP to \fIn\fR seconds (0 means no limit).
843 .TP
844 .B pass\-filter \fIfilter\-expression
845 Specifies a packet filter to applied to data packets being sent or
846 received to determine which packets should be allowed to pass.
847 Packets which are rejected by the filter are silently discarded.  This
848 option can be used to prevent specific network daemons (such as
849 routed) using up link bandwidth, or to provide a very basic firewall
850 capability.
851 The \fIfilter\-expression\fR syntax is as described for tcpdump(1),
852 except that qualifiers which are inappropriate for a PPP link, such as
853 \fBether\fR and \fBarp\fR, are not permitted.  Generally the filter
854 expression should be enclosed in single-quotes to prevent whitespace
855 in the expression from being interpreted by the shell.  Note that it
856 is possible to apply different constraints to incoming and outgoing
857 packets using the \fBinbound\fR and \fBoutbound\fR qualifiers. This
858 option is currently only available under Linux, and requires that the
859 kernel was configured to include PPP filtering support (CONFIG_PPP_FILTER).
860 .TP
861 .B password \fIpassword\-string
862 Specifies the password to use for authenticating to the peer.  Use
863 of this option is discouraged, as the password is likely to be visible
864 to other users on the system (for example, by using ps(1)).
865 .TP
866 .B persist
867 Do not exit after a connection is terminated; instead try to reopen
868 the connection. The \fBmaxfail\fR option still has an effect on
869 persistent connections.
870 .TP
871 .B plugin \fIfilename
872 Load the shared library object file \fIfilename\fR as a plugin.  This
873 is a privileged option.  If \fIfilename\fR does not contain a slash
874 (/), pppd will look in the \fB/usr/lib/pppd/\fIversion\fR directory
875 for the plugin, where
876 \fIversion\fR is the version number of pppd (for example, 2.4.2).
877 .TP
878 .B predictor1
879 Request that the peer compress frames that it sends using Predictor-1
880 compression, and agree to compress transmitted frames with Predictor-1
881 if requested.  This option has no effect unless the kernel driver
882 supports Predictor-1 compression.
883 .TP
884 .B privgroup \fIgroup\-name
885 Allows members of group \fIgroup\-name\fR to use privileged options.
886 This is a privileged option.  Use of this option requires care as
887 there is no guarantee that members of \fIgroup\-name\fR cannot use pppd
888 to become root themselves.  Consider it equivalent to putting the
889 members of \fIgroup\-name\fR in the kmem or disk group.
890 .TP
891 .B proxyarp
892 Add an entry to this system's ARP [Address Resolution Protocol] table
893 with the IP address of the peer and the Ethernet address of this
894 system.  This will have the effect of making the peer appear to other
895 systems to be on the local ethernet.
896 .TP
897 .B pty \fIscript
898 Specifies that the command \fIscript\fR is to be used to communicate
899 rather than a specific terminal device.  Pppd will allocate itself a
900 pseudo-tty master/slave pair and use the slave as its terminal
901 device.  The \fIscript\fR will be run in a child process with the
902 pseudo-tty master as its standard input and output.  An explicit
903 device name may not be given if this option is used.  (Note: if the
904 \fIrecord\fR option is used in conjuction with the \fIpty\fR option,
905 the child process will have pipes on its standard input and output.)
906 .TP
907 .B receive\-all
908 With this option, pppd will accept all control characters from the
909 peer, including those marked in the receive asyncmap.  Without this
910 option, pppd will discard those characters as specified in RFC1662.
911 This option should only be needed if the peer is buggy.
912 .TP
913 .B record \fIfilename
914 Specifies that pppd should record all characters sent and received to
915 a file named \fIfilename\fR.  This file is opened in append mode,
916 using the user's user-ID and permissions.  This option is implemented
917 using a pseudo-tty and a process to transfer characters between the
918 pseudo-tty and the real serial device, so it will increase the latency
919 and CPU overhead of transferring data over the ppp interface.  The
920 characters are stored in a tagged format with timestamps, which can be
921 displayed in readable form using the pppdump(8) program.
922 .TP
923 .B remotename \fIname
924 Set the assumed name of the remote system for authentication purposes
925 to \fIname\fR.
926 .TP
927 .B remotenumber \fInumber
928 Set the assumed telephone number of the remote system for authentication
929 purposes to \fInumber\fR.
930 .TP
931 .B refuse\-chap
932 With this option, pppd will not agree to authenticate itself to the
933 peer using CHAP.
934 .TP
935 .B refuse\-mschap
936 With this option, pppd will not agree to authenticate itself to the
937 peer using MS\-CHAP.
938 .TP
939 .B refuse\-mschap\-v2
940 With this option, pppd will not agree to authenticate itself to the
941 peer using MS\-CHAPv2.
942 .TP
943 .B refuse\-eap
944 With this option, pppd will not agree to authenticate itself to the
945 peer using EAP.
946 .TP
947 .B refuse\-pap
948 With this option, pppd will not agree to authenticate itself to the
949 peer using PAP.
950 .TP
951 .B require\-chap
952 Require the peer to authenticate itself using CHAP [Challenge
953 Handshake Authentication Protocol] authentication.
954 .TP
955 .B require\-mppe
956 Require the use of MPPE (Microsoft Point to Point Encryption).  This
957 option disables all other compression types.  This option enables
958 both 40-bit and 128-bit encryption.  In order for MPPE to successfully
959 come up, you must have authenticated with either MS\-CHAP or MS\-CHAPv2.
960 This option is presently only supported under Linux, and only if your
961 kernel has been configured to include MPPE support.
962 .TP
963 .B require\-mppe\-40
964 Require the use of MPPE, with 40-bit encryption.
965 .TP
966 .B require\-mppe\-128
967 Require the use of MPPE, with 128-bit encryption.
968 .TP
969 .B require\-mschap
970 Require the peer to authenticate itself using MS\-CHAP [Microsoft Challenge
971 Handshake Authentication Protocol] authentication.
972 .TP
973 .B require\-mschap\-v2
974 Require the peer to authenticate itself using MS\-CHAPv2 [Microsoft Challenge
975 Handshake Authentication Protocol, Version 2] authentication.
976 .TP
977 .B require\-eap
978 Require the peer to authenticate itself using EAP [Extensible
979 Authentication Protocol] authentication.
980 .TP
981 .B require\-pap
982 Require the peer to authenticate itself using PAP [Password
983 Authentication Protocol] authentication.
984 .TP
985 .B show\-password
986 When logging the contents of PAP packets, this option causes pppd to
987 show the password string in the log message.
988 .TP
989 .B silent
990 With this option, pppd will not transmit LCP packets to initiate a
991 connection until a valid LCP packet is received from the peer (as for
992 the `passive' option with ancient versions of pppd).
993 .TP
994 .B srp\-interval \fIn
995 If this parameter is given and pppd uses EAP SRP\-SHA1 to authenticate
996 the peer (i.e., is the server), then pppd will use the optional
997 lightweight SRP rechallenge mechanism at intervals of \fIn\fR
998 seconds.  This option is faster than \fBeap\-interval\fR
999 reauthentication because it uses a hash\-based mechanism and does not
1000 derive a new session key.
1001 .TP
1002 .B srp\-pn\-secret \fIstring
1003 Set the long-term pseudonym-generating secret for the server.  This
1004 value is optional and if set, needs to be known at the server
1005 (authenticator) side only, and should be different for each server (or
1006 poll of identical servers).  It is used along with the current date to
1007 generate a key to encrypt and decrypt the client's identity contained
1008 in the pseudonym.
1009 .TP
1010 .B srp\-use\-pseudonym
1011 When operating as an EAP SRP\-SHA1 client, attempt to use the pseudonym
1012 stored in ~/.ppp_psuedonym first as the identity, and save in this
1013 file any pseudonym offered by the peer during authentication.
1014 .TP
1015 .B sync
1016 Use synchronous HDLC serial encoding instead of asynchronous.
1017 The device used by pppd with this option must have sync support.
1018 Currently supports Microgate SyncLink adapters
1019 under Linux and FreeBSD 2.2.8 and later.
1020 .TP
1021 .B unit \fInum
1022 Sets the ppp unit number (for a ppp0 or ppp1 etc interface name) for outbound
1023 connections.
1024 .TP
1025 .B updetach
1026 With this option, pppd will detach from its controlling terminal once
1027 it has successfully established the ppp connection (to the point where
1028 the first network control protocol, usually the IP control protocol,
1029 has come up).
1030 .TP
1031 .B usehostname
1032 Enforce the use of the hostname (with domain name appended, if given)
1033 as the name of the local system for authentication purposes (overrides
1034 the \fIname\fR option).  This option is not normally needed since the
1035 \fIname\fR option is privileged.
1036 .TP
1037 .B usepeerdns
1038 Ask the peer for up to 2 DNS server addresses.  The addresses supplied
1039 by the peer (if any) are passed to the /etc/ppp/ip\-up script in the
1040 environment variables DNS1 and DNS2, and the environment variable
1041 USEPEERDNS will be set to 1.  In addition, pppd will create an
1042 /etc/ppp/resolv.conf file containing one or two nameserver lines with
1043 the address(es) supplied by the peer.
1044 .TP
1045 .B user \fIname
1046 Sets the name used for authenticating the local system to the peer to
1047 \fIname\fR.
1048 .TP
1049 .B vj\-max\-slots \fIn
1050 Sets the number of connection slots to be used by the Van Jacobson
1051 TCP/IP header compression and decompression code to \fIn\fR, which
1052 must be between 2 and 16 (inclusive).
1053 .TP
1054 .B welcome \fIscript
1055 Run the executable or shell command specified by \fIscript\fR before
1056 initiating PPP negotiation, after the connect script (if any) has
1057 completed.  A value for this option from a privileged source cannot be
1058 overridden by a non-privileged user.
1059 .TP
1060 .B xonxoff
1061 Use software flow control (i.e. XON/XOFF) to control the flow of data on
1062 the serial port.
1063 .SH OPTIONS FILES
1064 Options can be taken from files as well as the command line.  Pppd
1065 reads options from the files /etc/ppp/options, ~/.ppprc and
1066 /etc/ppp/options.\fIttyname\fR (in that order) before processing the
1067 options on the command line.  (In fact, the command-line options are
1068 scanned to find the terminal name before the options.\fIttyname\fR
1069 file is read.)  In forming the name of the options.\fIttyname\fR file,
1070 the initial /dev/ is removed from the terminal name, and any remaining
1071 / characters are replaced with dots.
1072 .PP
1073 An options file is parsed into a series of words, delimited by
1074 whitespace.  Whitespace can be included in a word by enclosing the
1075 word in double-quotes (").  A backslash (\\) quotes the following character.
1076 A hash (#) starts a comment, which continues until the end of the
1077 line.  There is no restriction on using the \fIfile\fR or \fIcall\fR
1078 options within an options file.
1079 .SH SECURITY
1080 .I pppd
1081 provides system administrators with sufficient access control that PPP
1082 access to a server machine can be provided to legitimate users without
1083 fear of compromising the security of the server or the network it's
1084 on.  This control is provided through restrictions on which IP
1085 addresses the peer may use, based on its authenticated identity (if
1086 any), and through restrictions on which options a non-privileged user
1087 may use.  Several of pppd's options are privileged, in particular
1088 those which permit potentially insecure configurations; these options
1089 are only accepted in files which are under the control of the system
1090 administrator, or if pppd is being run by root.
1091 .PP
1092 The default behaviour of pppd is to allow an unauthenticated peer to
1093 use a given IP address only if the system does not already have a
1094 route to that IP address.  For example, a system with a
1095 permanent connection to the wider internet will normally have a
1096 default route, and thus all peers will have to authenticate themselves
1097 in order to set up a connection.  On such a system, the \fIauth\fR
1098 option is the default.  On the other hand, a system where the
1099 PPP link is the only connection to the internet will not normally have
1100 a default route, so the peer will be able to use almost any IP address
1101 without authenticating itself.
1102 .PP
1103 As indicated above, some security-sensitive options are privileged,
1104 which means that they may not be used by an ordinary non-privileged
1105 user running a setuid-root pppd, either on the command line, in the
1106 user's ~/.ppprc file, or in an options file read using the \fIfile\fR
1107 option.  Privileged options may be used in /etc/ppp/options file or in
1108 an options file read using the \fIcall\fR option.  If pppd is being
1109 run by the root user, privileged options can be used without
1110 restriction.
1111 .PP
1112 When opening the device, pppd uses either the invoking user's user ID
1113 or the root UID (that is, 0), depending on whether the device name was
1114 specified by the user or the system administrator.  If the device name
1115 comes from a privileged source, that is, /etc/ppp/options or an
1116 options file read using the \fIcall\fR option, pppd uses full root
1117 privileges when opening the device.  Thus, by creating an appropriate
1118 file under /etc/ppp/peers, the system administrator can allow users to
1119 establish a ppp connection via a device which they would not normally
1120 have permission to access.  Otherwise pppd uses the invoking user's
1121 real UID when opening the device.
1122 .SH AUTHENTICATION
1123 Authentication is the process whereby one peer convinces the other of
1124 its identity.  This involves the first peer sending its name to the
1125 other, together with some kind of secret information which could only
1126 come from the genuine authorized user of that name.  In such an
1127 exchange, we will call the first peer the "client" and the other the
1128 "server".  The client has a name by which it identifies itself to the
1129 server, and the server also has a name by which it identifies itself
1130 to the client.  Generally the genuine client shares some secret (or
1131 password) with the server, and authenticates itself by proving that it
1132 knows that secret.  Very often, the names used for authentication
1133 correspond to the internet hostnames of the peers, but this is not
1134 essential.
1135 .LP
1136 At present, pppd supports three authentication protocols: the Password
1137 Authentication Protocol (PAP), Challenge Handshake Authentication
1138 Protocol (CHAP), and Extensible Authentication Protocol (EAP).  PAP
1139 involves the client sending its name and a cleartext password to the
1140 server to authenticate itself.  In contrast, the server initiates the
1141 CHAP authentication exchange by sending a challenge to the client (the
1142 challenge packet includes the server's name).  The client must respond
1143 with a response which includes its name plus a hash value derived from
1144 the shared secret and the challenge, in order to prove that it knows
1145 the secret.  EAP supports CHAP-style authentication, and also includes
1146 the SRP\-SHA1 mechanism, which is resistant to dictionary-based attacks
1147 and does not require a cleartext password on the server side.
1148 .LP
1149 The PPP protocol, being symmetrical, allows both peers to require the
1150 other to authenticate itself.  In that case, two separate and
1151 independent authentication exchanges will occur.  The two exchanges
1152 could use different authentication protocols, and in principle,
1153 different names could be used in the two exchanges.
1154 .LP
1155 The default behaviour of pppd is to agree to authenticate if
1156 requested, and to not require authentication from the peer.  However,
1157 pppd will not agree to authenticate itself with a particular protocol
1158 if it has no secrets which could be used to do so.
1159 .LP
1160 Pppd stores secrets for use in authentication in secrets
1161 files (/etc/ppp/pap\-secrets for PAP, /etc/ppp/chap\-secrets for CHAP,
1162 MS\-CHAP, MS\-CHAPv2, and EAP MD5-Challenge, and /etc/ppp/srp\-secrets
1163 for EAP SRP\-SHA1).
1164 All secrets files have the same format.  The secrets files can
1165 contain secrets for pppd to use in authenticating itself to other
1166 systems, as well as secrets for pppd to use when authenticating other
1167 systems to itself.
1168 .LP
1169 Each line in a secrets file contains one secret.  A given secret is
1170 specific to a particular combination of client and server - it can
1171 only be used by that client to authenticate itself to that server.
1172 Thus each line in a secrets file has at least 3 fields: the name of
1173 the client, the name of the server, and the secret.  These fields may
1174 be followed by a list of the IP addresses that the specified client
1175 may use when connecting to the specified server.
1176 .LP
1177 A secrets file is parsed into words as for a options file, so the
1178 client name, server name and secrets fields must each be one word,
1179 with any embedded spaces or other special characters quoted or
1180 escaped.  Note that case is significant in the client and server names
1181 and in the secret.
1182 .LP
1183 If the secret starts with an `@', what follows is assumed to be the
1184 name of a file from which to read the secret.  A "*" as the client or
1185 server name matches any name.  When selecting a secret, pppd takes the
1186 best match, i.e.  the match with the fewest wildcards.
1187 .LP
1188 Any following words on the same line are taken to be a list of
1189 acceptable IP addresses for that client.  If there are only 3 words on
1190 the line, or if the first word is "\-", then all IP addresses are
1191 disallowed.  To allow any address, use "*".  A word starting with "!"
1192 indicates that the specified address is \fInot\fR acceptable.  An
1193 address may be followed by "/" and a number \fIn\fR, to indicate a
1194 whole subnet, i.e. all addresses which have the same value in the most
1195 significant \fIn\fR bits.  In this form, the address may be followed
1196 by a plus sign ("+") to indicate that one address from the subnet is
1197 authorized, based on the ppp network interface unit number in use.
1198 In this case, the host part of the address will be set to the unit
1199 number plus one.
1200 .LP
1201 Thus a secrets file contains both secrets for use in authenticating
1202 other hosts, plus secrets which we use for authenticating ourselves to
1203 others.  When pppd is authenticating the peer (checking the peer's
1204 identity), it chooses a secret with the peer's name in the first
1205 field and the name of the local system in the second field.  The
1206 name of the local system defaults to the hostname, with the domain
1207 name appended if the \fIdomain\fR option is used.  This default can be
1208 overridden with the \fIname\fR option, except when the
1209 \fIusehostname\fR option is used.  (For EAP SRP\-SHA1, see the
1210 srp\-entry(8) utility for generating proper validator entries to be
1211 used in the "secret" field.)
1212 .LP
1213 When pppd is choosing a secret to use in authenticating itself to the
1214 peer, it first determines what name it is going to use to identify
1215 itself to the peer.  This name can be specified by the user with the
1216 \fIuser\fR option.  If this option is not used, the name defaults to
1217 the name of the local system, determined as described in the previous
1218 paragraph.  Then pppd looks for a secret with this name in the first
1219 field and the peer's name in the second field.  Pppd will know the
1220 name of the peer if CHAP or EAP authentication is being used, because
1221 the peer will have sent it in the challenge packet.  However, if PAP
1222 is being used, pppd will have to determine the peer's name from the
1223 options specified by the user.  The user can specify the peer's name
1224 directly with the \fIremotename\fR option.  Otherwise, if the remote
1225 IP address was specified by a name (rather than in numeric form), that
1226 name will be used as the peer's name.  Failing that, pppd will use the
1227 null string as the peer's name.
1228 .LP
1229 When authenticating the peer with PAP, the supplied password is first
1230 compared with the secret from the secrets file.  If the password
1231 doesn't match the secret, the password is encrypted using crypt() and
1232 checked against the secret again.  Thus secrets for authenticating the
1233 peer can be stored in encrypted form if desired.  If the
1234 \fIpapcrypt\fR option is given, the first (unencrypted) comparison is
1235 omitted, for better security.
1236 .LP
1237 Furthermore, if the \fIlogin\fR option was specified, the username and
1238 password are also checked against the system password database.  Thus,
1239 the system administrator can set up the pap\-secrets file to allow PPP
1240 access only to certain users, and to restrict the set of IP addresses
1241 that each user can use.  Typically, when using the \fIlogin\fR option,
1242 the secret in /etc/ppp/pap\-secrets would be "", which will match any
1243 password supplied by the peer.  This avoids the need to have the same
1244 secret in two places.
1245 .LP
1246 Authentication must be satisfactorily completed before IPCP (or any
1247 other Network Control Protocol) can be started.  If the peer is
1248 required to authenticate itself, and fails to do so, pppd will
1249 terminated the link (by closing LCP).  If IPCP negotiates an
1250 unacceptable IP address for the remote host, IPCP will be closed.  IP
1251 packets can only be sent or received when IPCP is open.
1252 .LP
1253 In some cases it is desirable to allow some hosts which can't
1254 authenticate themselves to connect and use one of a restricted set of
1255 IP addresses, even when the local host generally requires
1256 authentication.  If the peer refuses to authenticate itself when
1257 requested, pppd takes that as equivalent to authenticating with PAP
1258 using the empty string for the username and password.  Thus, by adding
1259 a line to the pap\-secrets file which specifies the empty string for
1260 the client and password, it is possible to allow restricted access to
1261 hosts which refuse to authenticate themselves.
1262 .SH ROUTING
1263 .LP
1264 When IPCP negotiation is completed successfully, pppd will inform the
1265 kernel of the local and remote IP addresses for the ppp interface.
1266 This is sufficient to create a host route to the remote end of the
1267 link, which will enable the peers to exchange IP packets.
1268 Communication with other machines generally requires further
1269 modification to routing tables and/or ARP (Address Resolution
1270 Protocol) tables.  In most cases the \fIdefaultroute\fR and/or
1271 \fIproxyarp\fR options are sufficient for this, but in some cases
1272 further intervention is required.  The /etc/ppp/ip\-up script can be
1273 used for this.
1274 .LP
1275 Sometimes it is desirable to add a default route through the remote
1276 host, as in the case of a machine whose only connection to the
1277 Internet is through the ppp interface.  The \fIdefaultroute\fR option
1278 causes pppd to create such a default route when IPCP comes up, and
1279 delete it when the link is terminated.
1280 .LP
1281 In some cases it is desirable to use proxy ARP, for example on a
1282 server machine connected to a LAN, in order to allow other hosts to
1283 communicate with the remote host.  The \fIproxyarp\fR option causes
1284 pppd to look for a network interface on the same subnet as the remote
1285 host (an interface supporting broadcast and ARP, which is up and not a
1286 point-to-point or loopback interface).  If found, pppd creates a
1287 permanent, published ARP entry with the IP address of the remote host
1288 and the hardware address of the network interface found.
1289 .LP
1290 When the \fIdemand\fR option is used, the interface IP addresses have
1291 already been set at the point when IPCP comes up.  If pppd has not
1292 been able to negotiate the same addresses that it used to configure
1293 the interface (for example when the peer is an ISP that uses dynamic
1294 IP address assignment), pppd has to change the interface IP addresses
1295 to the negotiated addresses.  This may disrupt existing connections,
1296 and the use of demand dialling with peers that do dynamic IP address
1297 assignment is not recommended.
1298 .SH MULTILINK
1299 Multilink PPP provides the capability to combine two or more PPP links
1300 between a pair of machines into a single `bundle', which appears as a
1301 single virtual PPP link which has the combined bandwidth of the
1302 individual links.  Currently, multilink PPP is only supported under
1303 Linux.
1304 .LP
1305 Pppd detects that the link it is controlling is connected to the same
1306 peer as another link using the peer's endpoint discriminator and the
1307 authenticated identity of the peer (if it authenticates itself).  The
1308 endpoint discriminator is a block of data which is hopefully unique
1309 for each peer.  Several types of data can be used, including
1310 locally-assigned strings of bytes, IP addresses, MAC addresses,
1311 randomly strings of bytes, or E\-164 phone numbers.  The endpoint
1312 discriminator sent to the peer by pppd can be set using the endpoint
1313 option.
1314 .LP
1315 In some circumstances the peer may send no endpoint discriminator or a
1316 non-unique value.  The bundle option adds an extra string which is
1317 added to the peer's endpoint discriminator and authenticated identity
1318 when matching up links to be joined together in a bundle.  The bundle
1319 option can also be used to allow the establishment of multiple bundles
1320 between the local system and the peer.  Pppd uses a TDB database in
1321 /var/run/pppd2.tdb to match up links.
1322 .LP
1323 Assuming that multilink is enabled and the peer is willing to
1324 negotiate multilink, then when pppd is invoked to bring up the first
1325 link to the peer, it will detect that no other link is connected to
1326 the peer and create a new bundle, that is, another ppp network
1327 interface unit.  When another pppd is invoked to bring up another link
1328 to the peer, it will detect the existing bundle and join its link to
1329 it.
1330 .LP
1331 If the first link terminates (for example, because of a hangup or a
1332 received LCP terminate-request) the bundle is not destroyed unless
1333 there are no other links remaining in the bundle.  Rather than
1334 exiting, the first pppd keeps running after its link terminates, until
1335 all the links in the bundle have terminated.  If the first pppd
1336 receives a SIGTERM or SIGINT signal, it will destroy the bundle and
1337 send a SIGHUP to the pppd processes for each of the links in the
1338 bundle.  If the first pppd receives a SIGHUP signal, it will terminate
1339 its link but not the bundle.
1340 .LP
1341 Note: demand mode is not currently supported with multilink.
1342 .SH EXAMPLES
1343 .LP
1344 The following examples assume that the /etc/ppp/options file contains
1345 the \fIauth\fR option (as in the default /etc/ppp/options file in the
1346 ppp distribution).
1347 .LP
1348 Probably the most common use of pppd is to dial out to an ISP.  This
1349 can be done with a command such as
1350 .IP
1351 pppd call isp
1352 .LP
1353 where the /etc/ppp/peers/isp file is set up by the system
1354 administrator to contain something like this:
1355 .IP
1356 ttyS0 19200 crtscts
1357 .br
1358 connect '/usr/sbin/chat \-v \-f /etc/ppp/chat\-isp'
1359 .br
1360 noauth
1361 .LP
1362 In this example, we are using chat to dial the ISP's modem and go
1363 through any logon sequence required.  The /etc/ppp/chat\-isp file
1364 contains the script used by chat; it could for example contain
1365 something like this:
1366 .IP
1367 ABORT "NO CARRIER"
1368 .br
1369 ABORT "NO DIALTONE"
1370 .br
1371 ABORT "ERROR"
1372 .br
1373 ABORT "NO ANSWER"
1374 .br
1375 ABORT "BUSY"
1376 .br
1377 ABORT "Username/Password Incorrect"
1378 .br
1379 "" "at"
1380 .br
1381 OK "at&d0&c1"
1382 .br
1383 OK "atdt2468135"
1384 .br
1385 "name:" "^Umyuserid"
1386 .br
1387 "word:" "\\qmypassword"
1388 .br
1389 "ispts" "\\q^Uppp"
1390 .br
1391 "~\-^Uppp\-~"
1392 .LP
1393 See the chat(8) man page for details of chat scripts.
1394 .LP
1395 Pppd can also be used to provide a dial-in ppp service for users.  If
1396 the users already have login accounts, the simplest way to set up the
1397 ppp service is to let the users log in to their accounts and run pppd
1398 (installed setuid-root) with a command such as
1399 .IP
1400 pppd proxyarp
1401 .LP
1402 To allow a user to use the PPP facilities, you need to allocate an IP
1403 address for that user's machine and create an entry in
1404 /etc/ppp/pap\-secrets, /etc/ppp/chap\-secrets, or /etc/ppp/srp\-secrets
1405 (depending on which authentication method the PPP implementation on
1406 the user's machine supports), so that the user's machine can
1407 authenticate itself.  For example, if Joe has a machine called
1408 "joespc" that is to be allowed to dial in to the machine called
1409 "server" and use the IP address joespc.my.net, you would add an entry
1410 like this to /etc/ppp/pap\-secrets or /etc/ppp/chap\-secrets:
1411 .IP
1412 joespc  server  "joe's secret"  joespc.my.net
1413 .LP
1414 (See srp\-entry(8) for a means to generate the server's entry when
1415 SRP\-SHA1 is in use.)
1416 Alternatively, you can create a username called (for example) "ppp",
1417 whose login shell is pppd and whose home directory is /etc/ppp.
1418 Options to be used when pppd is run this way can be put in
1419 /etc/ppp/.ppprc.
1420 .LP
1421 If your serial connection is any more complicated than a piece of
1422 wire, you may need to arrange for some control characters to be
1423 escaped.  In particular, it is often useful to escape XON (^Q) and
1424 XOFF (^S), using \fIasyncmap a0000\fR.  If the path includes a telnet,
1425 you probably should escape ^] as well (\fIasyncmap 200a0000\fR).  If
1426 the path includes an rlogin, you will need to use the \fIescape ff\fR
1427 option on the end which is running the rlogin client, since many
1428 rlogin implementations are not transparent; they will remove the
1429 sequence [0xff, 0xff, 0x73, 0x73, followed by any 8 bytes] from the
1430 stream.
1431 .SH DIAGNOSTICS
1432 .LP
1433 Messages are sent to the syslog daemon using facility LOG_DAEMON.
1434 (This can be overridden by recompiling pppd with the macro
1435 LOG_PPP defined as the desired facility.)  See the syslog(8)
1436 documentation for details of where the syslog daemon will write the
1437 messages.  On most systems, the syslog daemon uses the
1438 /etc/syslog.conf file to specify the destination(s) for syslog
1439 messages.  You may need to edit that file to suit.
1440 .LP
1441 The \fIdebug\fR option causes the contents of all control packets sent
1442 or received to be logged, that is, all LCP, PAP, CHAP, EAP, or IPCP packets.
1443 This can be useful if the PPP negotiation does not succeed or if
1444 authentication fails.
1445 If debugging is enabled at compile time, the \fIdebug\fR option also
1446 causes other debugging messages to be logged.
1447 .LP
1448 Debugging can also be enabled or disabled by sending a SIGUSR1 signal
1449 to the pppd process.  This signal acts as a toggle.
1450 .SH EXIT STATUS
1451 The exit status of pppd is set to indicate whether any error was
1452 detected, or the reason for the link being terminated.  The values
1453 used are:
1454 .TP
1455 .B 0
1456 Pppd has detached, or otherwise the connection was successfully
1457 established and terminated at the peer's request.
1458 .TP
1459 .B 1
1460 An immediately fatal error of some kind occurred, such as an essential
1461 system call failing, or running out of virtual memory.
1462 .TP
1463 .B 2
1464 An error was detected in processing the options given, such as two
1465 mutually exclusive options being used.
1466 .TP
1467 .B 3
1468 Pppd is not setuid-root and the invoking user is not root.
1469 .TP
1470 .B 4
1471 The kernel does not support PPP, for example, the PPP kernel driver is
1472 not included or cannot be loaded.
1473 .TP
1474 .B 5
1475 Pppd terminated because it was sent a SIGINT, SIGTERM or SIGHUP
1476 signal.
1477 .TP
1478 .B 6
1479 The serial port could not be locked.
1480 .TP
1481 .B 7
1482 The serial port could not be opened.
1483 .TP
1484 .B 8
1485 The connect script failed (returned a non-zero exit status).
1486 .TP
1487 .B 9
1488 The command specified as the argument to the \fIpty\fR option could
1489 not be run.
1490 .TP
1491 .B 10
1492 The PPP negotiation failed, that is, it didn't reach the point where
1493 at least one network protocol (e.g. IP) was running.
1494 .TP
1495 .B 11
1496 The peer system failed (or refused) to authenticate itself.
1497 .TP
1498 .B 12
1499 The link was established successfully and terminated because it was
1500 idle.
1501 .TP
1502 .B 13
1503 The link was established successfully and terminated because the
1504 connect time limit was reached.
1505 .TP
1506 .B 14
1507 Callback was negotiated and an incoming call should arrive shortly.
1508 .TP
1509 .B 15
1510 The link was terminated because the peer is not responding to echo
1511 requests.
1512 .TP
1513 .B 16
1514 The link was terminated by the modem hanging up.
1515 .TP
1516 .B 17
1517 The PPP negotiation failed because serial loopback was detected.
1518 .TP
1519 .B 18
1520 The init script failed (returned a non-zero exit status).
1521 .TP
1522 .B 19
1523 We failed to authenticate ourselves to the peer.
1524 .SH SCRIPTS
1525 Pppd invokes scripts at various stages in its processing which can be
1526 used to perform site-specific ancillary processing.  These scripts are
1527 usually shell scripts, but could be executable code files instead.
1528 Pppd does not wait for the scripts to finish (except for the ip-pre-up
1529 script).  The scripts are
1530 executed as root (with the real and effective user-id set to 0), so
1531 that they can do things such as update routing tables or run
1532 privileged daemons.  Be careful that the contents of these scripts do
1533 not compromise your system's security.  Pppd runs the scripts with
1534 standard input, output and error redirected to /dev/null, and with an
1535 environment that is empty except for some environment variables that
1536 give information about the link.  The environment variables that pppd
1537 sets are:
1538 .TP
1539 .B DEVICE
1540 The name of the serial tty device being used.
1541 .TP
1542 .B IFNAME
1543 The name of the network interface being used.
1544 .TP
1545 .B IPLOCAL
1546 The IP address for the local end of the link.  This is only set when
1547 IPCP has come up.
1548 .TP
1549 .B IPREMOTE
1550 The IP address for the remote end of the link.  This is only set when
1551 IPCP has come up.
1552 .TP
1553 .B PEERNAME
1554 The authenticated name of the peer.  This is only set if the peer
1555 authenticates itself.
1556 .TP
1557 .B SPEED
1558 The baud rate of the tty device.
1559 .TP
1560 .B ORIG_UID
1561 The real user-id of the user who invoked pppd.
1562 .TP
1563 .B PPPLOGNAME
1564 The username of the real user-id that invoked pppd. This is always set.
1565 .P
1566 For the ip-down and auth-down scripts, pppd also sets the following
1567 variables giving statistics for the connection:
1568 .TP
1569 .B CONNECT_TIME
1570 The number of seconds from when the PPP negotiation started until the
1571 connection was terminated.
1572 .TP
1573 .B BYTES_SENT
1574 The number of bytes sent (at the level of the serial port) during the
1575 connection.
1576 .TP
1577 .B BYTES_RCVD
1578 The number of bytes received (at the level of the serial port) during
1579 the connection.
1580 .TP
1581 .B LINKNAME
1582 The logical name of the link, set with the \fIlinkname\fR option.
1583 .TP
1584 .B DNS1
1585 If the peer supplies DNS server addresses, this variable is set to the
1586 first DNS server address supplied.
1587 .TP
1588 .B DNS2
1589 If the peer supplies DNS server addresses, this variable is set to the
1590 second DNS server address supplied.
1591 .P
1592 Pppd invokes the following scripts, if they exist.  It is not an error
1593 if they don't exist.
1594 .TP
1595 .B /etc/ppp/auth\-up
1596 A program or script which is executed after the remote system
1597 successfully authenticates itself.  It is executed with the parameters
1598 .IP
1599 \fIinterface\-name peer\-name user\-name tty\-device speed\fR
1600 .IP
1601 Note that this script is not executed if the peer doesn't authenticate
1602 itself, for example when the \fInoauth\fR option is used.
1603 .TP
1604 .B /etc/ppp/auth\-down
1605 A program or script which is executed when the link goes down, if
1606 /etc/ppp/auth\-up was previously executed.  It is executed in the same
1607 manner with the same parameters as /etc/ppp/auth\-up.
1608 .TP
1609 .B /etc/ppp/ip\-pre\-up
1610 A program or script which is executed just before the ppp network
1611 interface is brought up.  It is executed with the same parameters as
1612 the ip\-up script (below).  At this point the interface exists and has
1613 IP addresses assigned but is still down.  This can be used to
1614 add firewall rules before any IP traffic can pass through the
1615 interface.  Pppd will wait for this script to finish before bringing
1616 the interface up, so this script should run quickly.
1617 .TP
1618 .B /etc/ppp/ip\-up
1619 A program or script which is executed when the link is available for
1620 sending and receiving IP packets (that is, IPCP has come up).  It is
1621 executed with the parameters
1622 .IP
1623 \fIinterface\-name tty\-device speed local\-IP\-address
1624 remote\-IP\-address ipparam\fR
1625 .TP
1626 .B /etc/ppp/ip\-down
1627 A program or script which is executed when the link is no longer
1628 available for sending and receiving IP packets.  This script can be
1629 used for undoing the effects of the /etc/ppp/ip\-up and
1630 /etc/ppp/ip\-pre\-up scripts.  It is
1631 invoked in the same manner and with the same parameters as the ip\-up
1632 script.
1633 .TP
1634 .B /etc/ppp/ipv6\-up
1635 Like /etc/ppp/ip\-up, except that it is executed when the link is available 
1636 for sending and receiving IPv6 packets. It is executed with the parameters
1637 .IP
1638 \fIinterface\-name tty\-device speed local\-link\-local\-address
1639 remote\-link\-local\-address ipparam\fR
1640 .TP
1641 .B /etc/ppp/ipv6\-down
1642 Similar to /etc/ppp/ip\-down, but it is executed when IPv6 packets can no
1643 longer be transmitted on the link. It is executed with the same parameters 
1644 as the ipv6\-up script.
1645 .TP
1646 .B /etc/ppp/ipx\-up
1647 A program or script which is executed when the link is available for
1648 sending and receiving IPX packets (that is, IPXCP has come up).  It is
1649 executed with the parameters
1650 .IP
1651 \fIinterface\-name tty\-device speed network\-number local\-IPX\-node\-address
1652 remote\-IPX\-node\-address local\-IPX\-routing\-protocol remote\-IPX\-routing\-protocol
1653 local\-IPX\-router\-name remote\-IPX\-router\-name ipparam pppd\-pid\fR 
1654 .IP
1655 The local\-IPX\-routing\-protocol and remote\-IPX\-routing\-protocol field
1656 may be one of the following:
1657 .IP
1658 NONE      to indicate that there is no routing protocol
1659 .br
1660 RIP       to indicate that RIP/SAP should be used
1661 .br
1662 NLSP      to indicate that Novell NLSP should be used
1663 .br
1664 RIP NLSP  to indicate that both RIP/SAP and NLSP should be used
1665 .TP
1666 .B /etc/ppp/ipx\-down
1667 A program or script which is executed when the link is no longer
1668 available for sending and receiving IPX packets.  This script can be
1669 used for undoing the effects of the /etc/ppp/ipx\-up script.  It is
1670 invoked in the same manner and with the same parameters as the ipx\-up
1671 script.
1672 .SH FILES
1673 .TP
1674 .B /var/run/ppp\fIn\fB.pid \fR(BSD or Linux), \fB/etc/ppp/ppp\fIn\fB.pid \fR(others)
1675 Process-ID for pppd process on ppp interface unit \fIn\fR.
1676 .TP
1677 .B /var/run/ppp\-\fIname\fB.pid \fR(BSD or Linux),
1678 \fB/etc/ppp/ppp\-\fIname\fB.pid \fR(others)
1679 Process-ID for pppd process for logical link \fIname\fR (see the
1680 \fIlinkname\fR option).
1681 .TP
1682 .B /var/run/pppd2.tdb
1683 Database containing information about pppd processes, interfaces and
1684 links, used for matching links to bundles in multilink operation.  May
1685 be examined by external programs to obtain information about running
1686 pppd instances, the interfaces and devices they are using, IP address
1687 assignments, etc.
1688 .B /etc/ppp/pap\-secrets
1689 Usernames, passwords and IP addresses for PAP authentication.  This
1690 file should be owned by root and not readable or writable by any other
1691 user.  Pppd will log a warning if this is not the case.
1692 .TP
1693 .B /etc/ppp/chap\-secrets
1694 Names, secrets and IP addresses for CHAP/MS\-CHAP/MS\-CHAPv2 authentication.
1695 As for /etc/ppp/pap\-secrets, this file should be owned by root and not
1696 readable or writable by any other user.  Pppd will log a warning if
1697 this is not the case.
1698 .TP
1699 .B /etc/ppp/srp\-secrets
1700 Names, secrets, and IP addresses for EAP authentication.  As for
1701 /etc/ppp/pap\-secrets, this file should be owned by root and not
1702 readable or writable by any other user.  Pppd will log a warning if
1703 this is not the case.
1704 .TP
1705 .B ~/.ppp_pseudonym
1706 Saved client-side SRP\-SHA1 pseudonym.  See the \fIsrp\-use\-pseudonym\fR
1707 option for details.
1708 .TP
1709 .B /etc/ppp/options
1710 System default options for pppd, read before user default options or
1711 command-line options.
1712 .TP
1713 .B ~/.ppprc
1714 User default options, read before /etc/ppp/options.\fIttyname\fR.
1715 .TP
1716 .B /etc/ppp/options.\fIttyname
1717 System default options for the serial port being used, read after
1718 ~/.ppprc.  In forming the \fIttyname\fR part of this
1719 filename, an initial /dev/ is stripped from the port name (if
1720 present), and any slashes in the remaining part are converted to
1721 dots.
1722 .TP
1723 .B /etc/ppp/peers
1724 A directory containing options files which may contain privileged
1725 options, even if pppd was invoked by a user other than root.  The
1726 system administrator can create options files in this directory to
1727 permit non-privileged users to dial out without requiring the peer to
1728 authenticate, but only to certain trusted peers.
1729 .SH SEE ALSO
1730 .BR chat (8),
1731 .BR pppstats (8)
1732 .TP
1733 .B RFC1144
1734 Jacobson, V.
1735 \fICompressing TCP/IP headers for low-speed serial links.\fR
1736 February 1990.
1737 .TP
1738 .B RFC1321
1739 Rivest, R.
1740 .I The MD5 Message-Digest Algorithm.
1741 April 1992.
1742 .TP
1743 .B RFC1332
1744 McGregor, G.
1745 .I PPP Internet Protocol Control Protocol (IPCP).
1746 May 1992.
1747 .TP
1748 .B RFC1334
1749 Lloyd, B.; Simpson, W.A.
1750 .I PPP authentication protocols.
1751 October 1992.
1752 .TP
1753 .B RFC1661
1754 Simpson, W.A.
1755 .I The Point-to-Point Protocol (PPP).
1756 July 1994.
1757 .TP
1758 .B RFC1662
1759 Simpson, W.A.
1760 .I PPP in HDLC-like Framing.
1761 July 1994.
1762 .TP
1763 .B RFC2284
1764 Blunk, L.; Vollbrecht, J.,
1765 .I PPP Extensible Authentication Protocol (EAP).
1766 March 1998.
1767 .TP
1768 .B RFC2472
1769 Haskin, D.
1770 .I IP Version 6 over PPP
1771 December 1998.
1772 .TP
1773 .B RFC2945
1774 Wu, T.,
1775 .I The SRP Authentication and Key Exchange System
1776 September 2000.
1777 .TP
1778 .B draft\-ietf\-pppext\-eap\-srp\-03.txt
1779 Carlson, J.; et al.,
1780 .I EAP SRP\-SHA1 Authentication Protocol.
1781 July 2001.
1782 .SH NOTES
1783 Some limited degree of control can be exercised over a running pppd
1784 process by sending it a signal from the list below.
1785 .TP
1786 .B SIGINT, SIGTERM
1787 These signals cause pppd to terminate the link (by closing LCP),
1788 restore the serial device settings, and exit.
1789 .TP
1790 .B SIGHUP
1791 This signal causes pppd to terminate the link, restore the serial
1792 device settings, and close the serial device.  If the \fIpersist\fR or
1793 \fIdemand\fR option has been specified, pppd will try to reopen the
1794 serial device and start another connection (after the holdoff period).
1795 Otherwise pppd will exit.  If this signal is received during the
1796 holdoff period, it causes pppd to end the holdoff period immediately.
1797 .TP
1798 .B SIGUSR1
1799 This signal toggles the state of the \fIdebug\fR option.
1800 .TP
1801 .B SIGUSR2
1802 This signal causes pppd to renegotiate compression.  This can be
1803 useful to re-enable compression after it has been disabled as a result
1804 of a fatal decompression error.  (Fatal decompression errors generally
1805 indicate a bug in one or other implementation.)
1806
1807 .SH AUTHORS
1808 Paul Mackerras (paulus@samba.org), based on earlier work by
1809 Drew Perkins,
1810 Brad Clements,
1811 Karl Fox,
1812 Greg Christy,
1813 and
1814 Brad Parker.
1815
1816 .SH COPYRIGHT
1817 Pppd is copyrighted and made available under conditions which provide
1818 that it may be copied and used in source or binary forms provided that
1819 the conditions listed below are met.  Portions of pppd are covered by
1820 the following copyright notices:
1821 .LP
1822 Copyright (c) 1984-2000 Carnegie Mellon University. All rights
1823 reserved.
1824 .br
1825 Copyright (c) 1993-2004 Paul Mackerras. All rights reserved.
1826 .br
1827 Copyright (c) 1995 Pedro Roque Marques.  All rights reserved.
1828 .br
1829 Copyright (c) 1995 Eric Rosenquist.  All rights reserved.
1830 .br
1831 Copyright (c) 1999 Tommi Komulainen.  All rights reserved.
1832 .br
1833 Copyright (C) Andrew Tridgell 1999
1834 .br
1835 Copyright (c) 2000 by Sun Microsystems, Inc.  All rights reserved.
1836 .br
1837 Copyright (c) 2001 by Sun Microsystems, Inc.  All rights reserved.
1838 .br
1839 Copyright (c) 2002 Google, Inc.  All rights reserved.
1840 .LP
1841 The copyright notices contain the following statements.
1842 .LP
1843 Redistribution and use in source and binary forms, with or without
1844 modification, are permitted provided that the following conditions
1845 are met:
1846 .LP
1847 1. Redistributions of source code must retain the above copyright
1848    notice, this list of conditions and the following disclaimer.
1849 .LP
1850 2. Redistributions in binary form must reproduce the above copyright
1851    notice, this list of conditions and the following disclaimer in
1852    the documentation and/or other materials provided with the
1853    distribution.
1854 .LP
1855 3. The name "Carnegie Mellon University" must not be used to
1856    endorse or promote products derived from this software without
1857    prior written permission. For permission or any legal
1858    details, please contact
1859 .br
1860      Office of Technology Transfer
1861 .br
1862      Carnegie Mellon University
1863 .br
1864      5000 Forbes Avenue
1865 .br
1866      Pittsburgh, PA  15213-3890
1867 .br
1868      (412) 268-4387, fax: (412) 268-7395
1869 .br
1870      tech-transfer@andrew.cmu.edu
1871 .LP
1872 3b. The name(s) of the authors of this software must not be used to
1873    endorse or promote products derived from this software without
1874    prior written permission.
1875 .LP
1876 4. Redistributions of any form whatsoever must retain the following
1877    acknowledgments:
1878 .br
1879    "This product includes software developed by Computing Services
1880     at Carnegie Mellon University (http://www.cmu.edu/computing/)."
1881 .br
1882    "This product includes software developed by Paul Mackerras
1883     <paulus@samba.org>".
1884 .br
1885    "This product includes software developed by Pedro Roque Marques
1886     <pedro_m@yahoo.com>".
1887 .br
1888    "This product includes software developed by Tommi Komulainen
1889     <Tommi.Komulainen@iki.fi>".
1890 .LP
1891 CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO
1892 THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
1893 AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE
1894 FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
1895 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
1896 AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
1897 OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
1898 .LP
1899 THE AUTHORS OF THIS SOFTWARE DISCLAIM ALL WARRANTIES WITH REGARD TO
1900 THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
1901 AND FITNESS, IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY
1902 SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
1903 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
1904 AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
1905 OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.