Commit | Line | Data |
---|---|---|
984263bc MD |
1 | .\" manual page [] for pppd 2.3 |
2 | .\" $FreeBSD: src/usr.sbin/pppd/pppd.8,v 1.20.2.4 2003/03/11 22:31:30 trhodes Exp $ | |
cabeba47 | 3 | .\" $DragonFly: src/usr.sbin/pppd/pppd.8,v 1.5 2007/11/23 23:16:37 swildner Exp $ |
984263bc MD |
4 | .\" SH section heading |
5 | .\" SS subsection heading | |
6 | .\" LP paragraph | |
7 | .\" IP indented paragraph | |
8 | .\" TP hanging label | |
9 | .TH PPPD 8 | |
10 | .SH NAME | |
11 | pppd \- Point to Point Protocol daemon | |
12 | .SH SYNOPSIS | |
13 | .B pppd | |
14 | [ | |
15 | .I tty_name | |
16 | ] [ | |
17 | .I speed | |
18 | ] [ | |
19 | .I options | |
20 | ] | |
21 | .SH DESCRIPTION | |
22 | .LP | |
23 | The Point-to-Point Protocol (PPP) provides a method for transmitting | |
24 | datagrams over serial point-to-point links. PPP | |
25 | is composed of three parts: a method for encapsulating datagrams over | |
26 | serial links, an extensible Link Control Protocol (LCP), and | |
27 | a family of Network Control Protocols (NCP) for establishing | |
28 | and configuring different network-layer protocols. | |
29 | .LP | |
30 | The encapsulation scheme is provided by driver code in the kernel. | |
31 | Pppd provides the basic LCP, authentication support, and an NCP for | |
32 | establishing and configuring the Internet Protocol (IP) (called the IP | |
33 | Control Protocol, IPCP). | |
34 | .SH FREQUENTLY USED OPTIONS | |
35 | .TP | |
36 | .I <tty_name> | |
37 | Communicate over the named device. The string "/dev/" is prepended if | |
38 | necessary. If no device name is given, or if the name of the terminal | |
39 | connected to the standard input is given, pppd | |
40 | will use that terminal, and will not fork to put itself in the | |
41 | background. This option is privileged if the \fInoauth\fR option is | |
42 | used. | |
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, providing that it is | |
47 | supported by the serial device driver. Other systems | |
48 | (e.g. SunOS, Linux) allow only a limited set of speeds. | |
49 | .TP | |
50 | .B active-filter \fIfilter-expression | |
51 | Specifies a packet filter to be applied to data packets to determine | |
52 | which packets are to be regarded as link activity, and therefore reset | |
53 | the idle timer, or cause the link to be brought up in demand-dialling | |
54 | mode. This option is useful in conjunction with the | |
55 | \fBidle\fR option if there are packets being sent or received | |
56 | regularly over the link (for example, routing information packets) | |
57 | which would otherwise prevent the link from ever appearing to be idle. | |
58 | The \fIfilter-expression\fR syntax is as described for tcpdump(1), | |
59 | except that qualifiers which are inappropriate for a PPP link, such as | |
60 | \fBether\fR and \fBarp\fR, are not permitted. Generally the filter | |
61 | expression should be enclosed in single-quotes to prevent whitespace | |
62 | in the expression from being interpreted by the shell. | |
63 | This option | |
64 | only available | |
65 | if both the kernel and pppd were compiled with PPP_FILTER defined. | |
66 | .TP | |
67 | .B asyncmap \fI<map> | |
68 | Set the async character map to <map>. This map describes which | |
69 | control characters cannot be successfully received over the serial | |
70 | line. Pppd will ask the peer to send these characters as a 2-byte | |
71 | escape sequence. The argument is a 32 bit hex number with each bit | |
72 | representing a character to escape. Bit 0 (00000001) represents the | |
73 | character 0x00; bit 31 (80000000) represents the character 0x1f or ^_. | |
74 | If multiple \fIasyncmap\fR options are given, the values are ORed | |
75 | together. If no \fIasyncmap\fR option is given, no async character | |
76 | map will be negotiated for the receive direction; the peer should then | |
77 | escape \fIall\fR control characters. To escape transmitted | |
78 | characters, use the \fIescape\fR option. | |
79 | .TP | |
80 | .B auth | |
81 | Require the peer to authenticate itself before allowing network | |
82 | packets to be sent or received. | |
83 | .TP | |
84 | .B call \fIname | |
85 | Read options from the file /etc/ppp/peers/\fIname\fR. This file may | |
86 | 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 | Use the executable or shell command specified by \fIscript\fR to set | |
93 | up the serial line. This script would typically use the chat(8) | |
94 | program to dial the modem and start the remote ppp session. This | |
95 | option is privileged if the \fInoauth\fR option is used. | |
96 | .TP | |
97 | .B connect-max-attempts \fI<n> | |
98 | Attempt dial-out connection to remote system no more than specified number | |
99 | of times (default = 1). If the connection is not made, pppd will exit. | |
100 | Requires that \fBpersist\fR has been specified. | |
101 | .TP | |
102 | .B crtscts | |
103 | Use hardware flow control (i.e. RTS/CTS) to control the flow of data | |
104 | on the serial port. If neither the \fIcrtscts\fR nor the | |
105 | \fInocrtscts\fR option is given, the hardware flow control setting | |
106 | for the serial port is left unchanged. | |
107 | .TP | |
108 | .B defaultroute | |
109 | Add a default route to the system routing tables, using the peer as | |
110 | the gateway, when IPCP negotiation is successfully completed. | |
111 | This entry is removed when the PPP connection is broken. This option | |
112 | is privileged if the \fInodefaultroute\fR option has been specified. | |
113 | .TP | |
114 | .B disconnect \fIscript | |
115 | Run the executable or shell command specified by \fIscript\fR after | |
116 | pppd has terminated the link. This script could, for example, issue | |
117 | commands to the modem to cause it to hang up if hardware modem control | |
118 | signals were not available. The disconnect script is not run if the | |
119 | modem has already hung up. This option is privileged if the | |
120 | \fInoauth\fR option is used. | |
121 | .TP | |
122 | .B escape \fIxx,yy,... | |
123 | Specifies that certain characters should be escaped on transmission | |
124 | (regardless of whether the peer requests them to be escaped with its | |
125 | async control character map). The characters to be escaped are | |
126 | specified as a list of hex numbers separated by commas. Note that | |
127 | almost any character can be specified for the \fIescape\fR option, | |
128 | unlike the \fIasyncmap\fR option which only allows control characters | |
129 | to be specified. The characters which may not be escaped are those | |
130 | with hex values 0x20 - 0x3f or 0x5e. | |
131 | .TP | |
132 | .B file \fIname | |
133 | Read options from file \fIname\fR (the format is described below). | |
134 | The file must be readable by the user who has invoked pppd. | |
135 | .TP | |
136 | .B lock | |
137 | Specifies that pppd should create a UUCP-style lock file for the | |
138 | serial device to ensure exclusive access to the device. | |
139 | .TP | |
140 | .B mru \fIn | |
141 | Set the MRU [Maximum Receive Unit] value to \fIn\fR. | |
142 | Pppd | |
143 | will ask the peer to send packets of no more than \fIn\fR bytes. The | |
144 | minimum MRU value is 128. The default MRU value is 1500. A value of | |
145 | 296 is recommended for slow links (40 bytes for TCP/IP header + 256 | |
146 | bytes of data). | |
147 | .TP | |
148 | .B mtu \fIn | |
149 | Set the MTU [Maximum Transmit Unit] value to \fIn\fR. Unless the | |
150 | peer requests a smaller value via MRU negotiation, pppd will | |
151 | request that the kernel networking code send data packets of no more | |
152 | than \fIn\fR bytes through the PPP network interface. | |
153 | .TP | |
154 | .B passive | |
155 | Enables the "passive" option in the LCP. With this option, pppd will | |
156 | attempt to initiate a connection; if no reply is received from the | |
157 | peer, pppd will then just wait passively for a valid LCP packet from | |
158 | the peer, instead of exiting, as it would without this option. | |
159 | .SH OPTIONS | |
160 | .TP | |
161 | .I <local_IP_address>\fB:\fI<remote_IP_address> | |
162 | Set the local and/or remote interface IP addresses. Either one may be | |
163 | omitted. The IP addresses can be specified with a host name or in | |
164 | decimal dot notation (e.g. 150.234.56.78). The default local | |
165 | address is the (first) IP address of the system (unless the | |
166 | \fInoipdefault\fR | |
167 | option is given). The remote address will be obtained from the peer | |
168 | if not specified in any option. Thus, in simple cases, this option is | |
169 | not required. If a local and/or remote IP address is specified with | |
170 | this option, pppd | |
171 | will not accept a different value from the peer in the IPCP | |
172 | negotiation, unless the \fIipcp-accept-local\fR and/or | |
173 | \fIipcp-accept-remote\fR options are given, respectively. | |
174 | .TP | |
175 | .B bsdcomp \fInr,nt | |
176 | Request that the peer compress packets that it sends, using the | |
177 | BSD-Compress scheme, with a maximum code size of \fInr\fR bits, and | |
178 | agree to compress packets sent to the peer with a maximum code size of | |
179 | \fInt\fR bits. If \fInt\fR is not specified, it defaults to the value | |
180 | given for \fInr\fR. Values in the range 9 to 15 may be used for | |
181 | \fInr\fR and \fInt\fR; larger values give better compression but | |
182 | consume more kernel memory for compression dictionaries. | |
183 | Alternatively, a value of 0 for \fInr\fR or \fInt\fR disables | |
184 | compression in the corresponding direction. Use \fInobsdcomp\fR or | |
185 | \fIbsdcomp 0\fR to disable BSD-Compress compression entirely. | |
186 | .TP | |
187 | .B chap-interval \fIn | |
188 | If this option is given, pppd will rechallenge the peer every \fIn\fR | |
189 | seconds. | |
190 | .TP | |
191 | .B chap-max-challenge \fIn | |
192 | Set the maximum number of CHAP challenge transmissions to \fIn\fR | |
193 | (default 10). | |
194 | .TP | |
195 | .B chap-restart \fIn | |
196 | Set the CHAP restart interval (retransmission timeout for challenges) | |
197 | to \fIn\fR seconds (default 3). | |
198 | .TP | |
199 | .B debug | |
200 | Enables connection debugging facilities. | |
201 | If this option is given, pppd will log the contents of all | |
202 | control packets sent or received in a readable form. The packets are | |
203 | logged through syslog with facility \fIdaemon\fR and level | |
204 | \fIdebug\fR. This information can be directed to a file by setting up | |
205 | /etc/syslog.conf appropriately (see syslog.conf(5)). | |
206 | .TP | |
207 | .B default-asyncmap | |
208 | Disable asyncmap negotiation, forcing all control characters to be | |
209 | escaped for both the transmit and the receive direction. | |
210 | .TP | |
211 | .B default-mru | |
212 | Disable MRU [Maximum Receive Unit] negotiation. With this option, | |
213 | pppd will use the default MRU value of 1500 bytes for both the | |
214 | transmit and receive direction. | |
215 | .TP | |
216 | .B deflate \fInr,nt | |
217 | Request that the peer compress packets that it sends, using the | |
218 | Deflate scheme, with a maximum window size of \fI2**nr\fR bytes, and | |
219 | agree to compress packets sent to the peer with a maximum window size | |
220 | of \fI2**nt\fR bytes. If \fInt\fR is not specified, it defaults to | |
221 | the value given for \fInr\fR. Values in the range 8 to 15 may be used | |
222 | for \fInr\fR and \fInt\fR; larger values give better compression but | |
223 | consume more kernel memory for compression dictionaries. | |
224 | Alternatively, a value of 0 for \fInr\fR or \fInt\fR disables | |
225 | compression in the corresponding direction. Use \fInodeflate\fR or | |
226 | \fIdeflate 0\fR to disable Deflate compression entirely. (Note: pppd | |
227 | requests Deflate compression in preference to BSD-Compress if the peer | |
228 | can do either.) | |
229 | .TP | |
230 | .B demand | |
231 | Initiate the link only on demand, i.e. when data traffic is present. | |
232 | With this option, the remote IP address must be specified by the user | |
233 | on the command line or in an options file. Pppd will initially | |
234 | configure the interface and enable it for IP traffic without | |
235 | connecting to the peer. When traffic is available, pppd will | |
236 | connect to the peer and perform negotiation, authentication, etc. | |
237 | When this is completed, pppd will commence passing data packets | |
238 | (i.e., IP packets) across the link. | |
239 | ||
240 | The \fIdemand\fR option implies the \fIpersist\fR option. If this | |
241 | behaviour is not desired, use the \fInopersist\fR option after the | |
242 | \fIdemand\fR option. The \fIidle\fR and \fIholdoff\fR | |
3f5e28f4 | 243 | options are also useful in conjunction with the \fIdemand\fR option. |
984263bc MD |
244 | .TP |
245 | .B domain \fId | |
246 | Append the domain name \fId\fR to the local host name for authentication | |
247 | purposes. For example, if gethostname() returns the name porsche, but | |
248 | the fully qualified domain name is porsche.Quotron.COM, you could | |
249 | specify \fIdomain Quotron.COM\fR. Pppd would then use the name | |
250 | \fIporsche.Quotron.COM\fR for looking up secrets in the secrets file, | |
251 | and as the default name to send to the peer when authenticating itself | |
252 | to the peer. This option is privileged. | |
253 | .TP | |
254 | .B holdoff \fIn | |
255 | Specifies how many seconds to wait before re-initiating the link after | |
256 | it terminates. This option only has any effect if the \fIpersist\fR | |
257 | or \fIdemand\fR option is used. The holdoff period is not applied if | |
258 | the link was terminated because it was idle. | |
259 | .TP | |
260 | .B idle \fIn | |
261 | Specifies that pppd should disconnect if the link is idle for \fIn\fR | |
262 | seconds. The link is idle when no data packets (i.e. IP packets) are | |
263 | being sent or received. Note: it is not advisable to use this option | |
264 | with the \fIpersist\fR option without the \fIdemand\fR option. | |
265 | If the \fBactive-filter\fR | |
266 | option is given, data packets which are rejected by the specified | |
267 | activity filter also count as the link being idle. | |
268 | .TP | |
269 | .B ipcp-accept-local | |
270 | With this option, pppd will accept the peer's idea of our local IP | |
271 | address, even if the local IP address was specified in an option. | |
272 | .TP | |
273 | .B ipcp-accept-remote | |
274 | With this option, pppd will accept the peer's idea of its (remote) IP | |
275 | address, even if the remote IP address was specified in an option. | |
276 | .TP | |
277 | .B ipcp-max-configure \fIn | |
278 | Set the maximum number of IPCP configure-request transmissions to | |
279 | \fIn\fR (default 10). | |
280 | .TP | |
281 | .B ipcp-max-failure \fIn | |
282 | Set the maximum number of IPCP configure-NAKs returned before starting | |
283 | to send configure-Rejects instead to \fIn\fR (default 10). | |
284 | .TP | |
285 | .B ipcp-max-terminate \fIn | |
286 | Set the maximum number of IPCP terminate-request transmissions to | |
287 | \fIn\fR (default 3). | |
288 | .TP | |
289 | .B ipcp-restart \fIn | |
290 | Set the IPCP restart interval (retransmission timeout) to \fIn\fR | |
291 | seconds (default 3). | |
292 | .TP | |
293 | .B ipparam \fIstring | |
294 | Provides an extra parameter to the ip-up and ip-down scripts. If this | |
295 | option is given, the \fIstring\fR supplied is given as the 6th | |
296 | parameter to those scripts. | |
297 | .TP | |
298 | .B ipx | |
299 | Enable the IPXCP and IPX protocols. This option is presently only | |
300 | supported under Linux, and only if your kernel has been configured to | |
301 | include IPX support. | |
302 | .TP | |
303 | .B ipx-network \fIn | |
304 | Set the IPX network number in the IPXCP configure request frame to | |
305 | \fIn\fR, a hexadecimal number (without a leading 0x). There is no | |
306 | valid default. If this option is not specified, the network number is | |
307 | obtained from the peer. If the peer does not have the network number, | |
308 | the IPX protocol will not be started. | |
309 | .TP | |
310 | .B ipx-node \fIn\fB:\fIm | |
311 | Set the IPX node numbers. | |
312 | The two node numbers are separated from each | |
313 | other with a colon character. | |
314 | The first number \fIn\fR is the local | |
315 | node number. | |
316 | The second number \fIm\fR is the peer's node number. | |
317 | Each | |
318 | node number is a hexadecimal number, at most 10 digits long. | |
319 | The node | |
320 | numbers on the ipx-network must be unique. | |
321 | There is no valid | |
322 | default. | |
323 | If this option is not specified then the node numbers are | |
324 | obtained from the peer. | |
325 | .TP | |
326 | .B ipx-router-name \fI<string> | |
327 | Set the name of the router. | |
328 | This is a string and is sent to the peer | |
329 | as information data. | |
330 | .TP | |
331 | .B ipx-routing \fIn | |
332 | Set the routing protocol to be received by this option. | |
333 | More than one | |
334 | instance of \fIipx-routing\fR may be specified. | |
335 | The '\fInone\fR' | |
336 | option (0) may be specified as the only instance of ipx-routing. | |
337 | The | |
338 | values may be \fI0\fR for \fINONE\fR, \fI2\fR for \fIRIP/SAP\fR, and | |
339 | \fI4\fR for \fINLSP\fR. | |
340 | .TP | |
341 | .B ipxcp-accept-local | |
342 | Accept the peer's NAK for the node number specified in the ipx-node | |
343 | option. | |
344 | If a node number was specified, and non-zero, the default is | |
345 | to insist that the value be used. | |
346 | If you include this option then you | |
347 | will permit the peer to override the entry of the node number. | |
348 | .TP | |
349 | .B ipxcp-accept-network | |
350 | Accept the peer's NAK for the network number specified in the | |
351 | ipx-network option. | |
352 | If a network number was specified, and non-zero, the | |
353 | default is to insist that the value be used. | |
354 | If you include this | |
355 | option then you will permit the peer to override the entry of the node | |
356 | number. | |
357 | .TP | |
358 | .B ipxcp-accept-remote | |
359 | Use the peer's network number specified in the configure request | |
360 | frame. | |
361 | If a node number was specified for the peer and this option was | |
362 | not specified, the peer will be forced to use the value which you have | |
363 | specified. | |
364 | .TP | |
365 | .B ipxcp-max-configure \fIn | |
366 | Set the maximum number of IPXCP configure request frames which the | |
367 | system will send to \fIn\fR. | |
368 | The default is 10. | |
369 | .TP | |
370 | .B ipxcp-max-failure \fIn | |
371 | Set the maximum number of IPXCP NAK frames which the local system will | |
372 | send before it rejects the options. | |
373 | The default value is 3. | |
374 | .TP | |
375 | .B ipxcp-max-terminate \fIn | |
3f5e28f4 | 376 | Set the maximum number of IPXCP terminate request frames before the |
984263bc MD |
377 | local system considers that the peer is not listening to them. |
378 | The | |
379 | default value is 3. | |
380 | .TP | |
381 | .B kdebug \fIn | |
382 | Enable debugging code in the kernel-level PPP driver. The argument | |
383 | \fIn\fR is a number which is the sum of the following values: 1 to | |
384 | enable general debug messages, 2 to request that the contents of | |
385 | received packets be printed, and 4 to request that the contents of | |
386 | transmitted packets be printed. On most systems, messages printed by | |
387 | the kernel are logged by syslog(1) to a file as directed in the | |
388 | /etc/syslog.conf configuration file. | |
389 | .TP | |
390 | .B lcp-echo-failure \fIn | |
391 | If this option is given, pppd will presume the peer to be dead | |
392 | if \fIn\fR LCP echo-requests are sent without receiving a valid LCP | |
393 | echo-reply. If this happens, pppd will terminate the | |
394 | connection. Use of this option requires a non-zero value for the | |
395 | \fIlcp-echo-interval\fR parameter. This option can be used to enable | |
396 | pppd to terminate after the physical connection has been broken | |
397 | (e.g., the modem has hung up) in situations where no hardware modem | |
398 | control lines are available. | |
399 | .TP | |
400 | .B lcp-echo-interval \fIn | |
401 | If this option is given, pppd will send an LCP echo-request frame to | |
402 | the peer every \fIn\fR seconds. Normally the peer should respond to | |
403 | the echo-request by sending an echo-reply. This option can be used | |
404 | with the \fIlcp-echo-failure\fR option to detect that the peer is no | |
405 | longer connected. | |
406 | .TP | |
407 | .B lcp-max-configure \fIn | |
408 | Set the maximum number of LCP configure-request transmissions to | |
409 | \fIn\fR (default 10). | |
410 | .TP | |
411 | .B lcp-max-failure \fIn | |
412 | Set the maximum number of LCP configure-NAKs returned before starting | |
413 | to send configure-Rejects instead to \fIn\fR (default 10). | |
414 | .TP | |
415 | .B lcp-max-terminate \fIn | |
416 | Set the maximum number of LCP terminate-request transmissions to | |
417 | \fIn\fR (default 3). | |
418 | .TP | |
419 | .B lcp-restart \fIn | |
420 | Set the LCP restart interval (retransmission timeout) to \fIn\fR | |
421 | seconds (default 3). | |
422 | .TP | |
423 | .B local | |
424 | Don't use the modem control lines. With this option, pppd will ignore | |
425 | the state of the CD (Carrier Detect) signal from the modem and will | |
426 | not change the state of the DTR (Data Terminal Ready) signal. | |
427 | .TP | |
428 | .B login | |
429 | Use the system password database for authenticating the peer using | |
430 | PAP, and record the user in the system wtmp file. Note that the peer | |
431 | must have an entry in the /etc/ppp/pap-secrets file as well as the | |
432 | system password database to be allowed access. | |
433 | .TP | |
434 | .B maxconnect \fIn | |
435 | Terminate the connection when it has been available for network | |
436 | traffic for \fIn\fR seconds (i.e. \fIn\fR seconds after the first | |
437 | network control protocol comes up). | |
438 | .TP | |
439 | .B modem | |
440 | Use the modem control lines. This option is the default. With this | |
441 | option, pppd will wait for the CD (Carrier Detect) signal from the | |
442 | modem to be asserted when opening the serial device (unless a connect | |
443 | script is specified), and it will drop the DTR (Data Terminal Ready) | |
444 | signal briefly when the connection is terminated and before executing | |
445 | the connect script. On Ultrix, this option implies hardware flow | |
446 | control, as for the \fIcrtscts\fR option. | |
447 | .TP | |
448 | .B ms-dns \fI<addr> | |
449 | If pppd is acting as a server for Microsoft Windows clients, this | |
450 | option allows pppd to supply one or two DNS (Domain Name Server) | |
451 | addresses to the clients. The first instance of this option specifies | |
452 | the primary DNS address; the second instance (if given) specifies the | |
453 | secondary DNS address. (This option was present in some older | |
454 | versions of pppd under the name \fBdns-addr\fR.) | |
455 | .TP | |
456 | .B ms-wins \fI<addr> | |
457 | If pppd is acting as a server for Microsoft Windows or "Samba" | |
458 | clients, this option allows pppd to supply one or two WINS (Windows | |
459 | Internet Name Services) server addresses to the clients. The first | |
460 | instance of this option specifies the primary WINS address; the second | |
461 | instance (if given) specifies the secondary WINS address. | |
462 | .TP | |
463 | .B name \fIname | |
464 | Set the name of the local system for authentication purposes to | |
465 | \fIname\fR. This is a privileged option. With this option, pppd will | |
466 | use lines in the secrets files which have \fIname\fR as the second | |
467 | field when looking for a secret to use in authenticating the peer. In | |
468 | addition, unless overridden with the \fIuser\fR option, \fIname\fR | |
469 | will be used as the name to send to the peer when authenticating the | |
470 | local system to the peer. (Note that pppd does not append the domain | |
471 | name to \fIname\fR.) | |
472 | .TP | |
473 | .B netmask \fIn | |
474 | Set the interface netmask to \fIn\fR, a 32 bit netmask in "decimal dot" | |
475 | notation (e.g. 255.255.255.0). If this option is given, the value | |
476 | specified is ORed with the default netmask. The default netmask is | |
477 | chosen based on the negotiated remote IP address; it is the | |
478 | appropriate network mask for the class of the remote IP address, ORed | |
479 | with the netmasks for any non point-to-point network interfaces in the | |
480 | system which are on the same network. | |
481 | .TP | |
482 | .B noaccomp | |
483 | Disable Address/Control compression in both directions (send and | |
484 | receive). | |
485 | .TP | |
486 | .B noauth | |
487 | Do not require the peer to authenticate itself. This option is | |
488 | privileged if the \fIauth\fR option is specified in /etc/ppp/options. | |
489 | .TP | |
490 | .B nobsdcomp | |
491 | Disables BSD-Compress compression; \fBpppd\fR will not request or | |
492 | agree to compress packets using the BSD-Compress scheme. | |
493 | .TP | |
494 | .B noccp | |
495 | Disable CCP (Compression Control Protocol) negotiation. This option | |
496 | should only be required if the peer is buggy and gets confused by | |
497 | requests from pppd for CCP negotiation. | |
498 | .TP | |
499 | .B nocrtscts | |
500 | Disable hardware flow control (i.e. RTS/CTS) on the serial port. If | |
501 | neither the \fIcrtscts\fR nor the \fInocrtscts\fR option is given, | |
502 | the hardware flow control setting for the serial port is left | |
503 | unchanged. | |
504 | .TP | |
505 | .B nodefaultroute | |
506 | Disable the \fIdefaultroute\fR option. The system administrator who | |
507 | wishes to prevent users from creating default routes with pppd | |
508 | can do so by placing this option in the /etc/ppp/options file. | |
509 | .TP | |
510 | .B nodeflate | |
511 | Disables Deflate compression; pppd will not request or agree to | |
512 | compress packets using the Deflate scheme. | |
513 | .TP | |
514 | .B nodetach | |
515 | Don't detach from the controlling terminal. Without this option, if a | |
516 | serial device other than the terminal on the standard input is | |
517 | specified, pppd will fork to become a background process. | |
518 | .TP | |
519 | .B noip | |
520 | Disable IPCP negotiation and IP communication. This option should | |
521 | only be required if the peer is buggy and gets confused by requests | |
522 | from pppd for IPCP negotiation. | |
523 | .TP | |
524 | .B noipdefault | |
525 | Disables the default behaviour when no local IP address is specified, | |
526 | which is to determine (if possible) the local IP address from the | |
527 | hostname. With this option, the peer will have to supply the local IP | |
528 | address during IPCP negotiation (unless it specified explicitly on the | |
529 | command line or in an options file). | |
530 | .TP | |
531 | .B noipx | |
532 | Disable the IPXCP and IPX protocols. This option should only be | |
533 | required if the peer is buggy and gets confused by requests from pppd | |
534 | for IPXCP negotiation. | |
535 | .TP | |
536 | .B nomagic | |
537 | Disable magic number negotiation. With this option, pppd cannot | |
538 | detect a looped-back line. This option should only be needed if the | |
539 | peer is buggy. | |
540 | .TP | |
541 | .B nopcomp | |
542 | Disable protocol field compression negotiation in both the receive and | |
543 | the transmit direction. | |
544 | .TP | |
545 | .B nopersist | |
546 | Exit once a connection has been made and terminated. This is the | |
547 | default unless the \fIpersist\fR or \fIdemand\fR option has been | |
548 | specified. | |
549 | .TP | |
550 | .B nopredictor1 | |
551 | Do not accept or agree to Predictor-1 compression. | |
552 | .TP | |
553 | .B noproxyarp | |
554 | Disable the \fIproxyarp\fR option. The system administrator who | |
555 | wishes to prevent users from creating proxy ARP entries with pppd can | |
556 | do so by placing this option in the /etc/ppp/options file. | |
557 | .TP | |
558 | .B novj | |
559 | Disable Van Jacobson style TCP/IP header compression in both the | |
560 | transmit and the receive direction. | |
561 | .TP | |
562 | .B novjccomp | |
563 | Disable the connection-ID compression option in Van Jacobson style | |
564 | TCP/IP header compression. With this option, pppd will not omit the | |
565 | connection-ID byte from Van Jacobson compressed TCP/IP headers, nor | |
566 | ask the peer to do so. | |
567 | .TP | |
568 | .B papcrypt | |
569 | Indicates that all secrets in the /etc/ppp/pap-secrets file which are | |
570 | used for checking the identity of the peer are encrypted, and thus | |
571 | pppd should not accept a password which, before encryption, is | |
572 | identical to the secret from the /etc/ppp/pap-secrets file. | |
573 | .TP | |
574 | .B pap-max-authreq \fIn | |
575 | Set the maximum number of PAP authenticate-request transmissions to | |
576 | \fIn\fR (default 10). | |
577 | .TP | |
578 | .B pap-restart \fIn | |
579 | Set the PAP restart interval (retransmission timeout) to \fIn\fR | |
580 | seconds (default 3). | |
581 | .TP | |
582 | .B pap-timeout \fIn | |
583 | Set the maximum time that pppd will wait for the peer to authenticate | |
584 | itself with PAP to \fIn\fR seconds (0 means no limit). | |
585 | .TP | |
586 | .B pass-filter \fIfilter-expression | |
587 | Specifies a packet filter to applied to data packets being sent or | |
588 | received to determine which packets should be allowed to pass. | |
589 | Packets which are rejected by the filter are silently discarded. This | |
590 | option can be used to prevent specific network daemons (such as | |
591 | routed) using up link bandwidth, or to provide a basic firewall | |
592 | capability. | |
593 | The \fIfilter-expression\fR syntax is as described for tcpdump(1), | |
594 | except that qualifiers which are inappropriate for a PPP link, such as | |
595 | \fBether\fR and \fBarp\fR, are not permitted. Generally the filter | |
596 | expression should be enclosed in single-quotes to prevent whitespace | |
597 | in the expression from being interpreted by the shell. Note that it | |
598 | is possible to apply different constraints to incoming and outgoing | |
599 | packets using the \fBinbound\fR and \fBoutbound\fR qualifiers. | |
600 | This | |
601 | option is currently only available under NetBSD, and then only if both | |
602 | the kernel and pppd were compiled with PPP_FILTER defined. | |
603 | .TP | |
604 | .B persist | |
605 | Do not exit after a connection is terminated; instead try to reopen | |
606 | the connection. | |
607 | .TP | |
608 | .B predictor1 | |
609 | Request that the peer compress frames that it sends using Predictor-1 | |
610 | compression, and agree to compress transmitted frames with Predictor-1 | |
611 | if requested. This option has no effect unless the kernel driver | |
612 | supports Predictor-1 compression. | |
613 | .TP | |
614 | .B proxyarp | |
615 | Add an entry to this system's ARP [Address Resolution Protocol] table | |
616 | with the IP address of the peer and the Ethernet address of this | |
617 | system. This will have the effect of making the peer appear to other | |
618 | systems to be on the local ethernet. | |
619 | .TP | |
620 | .B remotename \fIname | |
621 | Set the assumed name of the remote system for authentication purposes | |
622 | to \fIname\fR. | |
623 | .TP | |
624 | .B refuse-chap | |
625 | With this option, pppd will not agree to authenticate itself to the | |
626 | peer using CHAP. | |
627 | .TP | |
628 | .B refuse-pap | |
629 | With this option, pppd will not agree to authenticate itself to the | |
630 | peer using PAP. | |
631 | .TP | |
632 | .B require-chap | |
633 | Require the peer to authenticate itself using CHAP [Challenge | |
634 | Handshake Authentication Protocol] authentication. | |
635 | .TP | |
636 | .B require-pap | |
637 | Require the peer to authenticate itself using PAP [Password | |
638 | Authentication Protocol] authentication. | |
639 | .TP | |
640 | .B silent | |
641 | With this option, pppd will not transmit LCP packets to initiate a | |
642 | connection until a valid LCP packet is received from the peer (as for | |
643 | the `passive' option with ancient versions of pppd). | |
644 | .TP | |
645 | .B usehostname | |
646 | Enforce the use of the hostname (with domain name appended, if given) | |
647 | as the name of the local system for authentication purposes (overrides | |
648 | the \fIname\fR option). | |
649 | .TP | |
650 | .B user \fIname | |
651 | Sets the name used for authenticating the local system to the peer to | |
652 | \fIname\fR. | |
653 | .TP | |
654 | .B vj-max-slots \fIn | |
655 | Sets the number of connection slots to be used by the Van Jacobson | |
656 | TCP/IP header compression and decompression code to \fIn\fR, which | |
657 | must be between 2 and 16 (inclusive). | |
658 | .TP | |
659 | .B welcome \fIscript | |
660 | Run the executable or shell command specified by \fIscript\fR before | |
661 | initiating PPP negotiation, after the connect script (if any) has | |
662 | completed. This option is privileged if the \fInoauth\fR option is | |
663 | used. | |
664 | .TP | |
665 | .B xonxoff | |
666 | Use software flow control (i.e. XON/XOFF) to control the flow of data on | |
667 | the serial port. | |
668 | .SH OPTIONS FILES | |
669 | Options can be taken from files as well as the command line. Pppd | |
670 | reads options from the files /etc/ppp/options, ~/.ppprc and | |
671 | /etc/ppp/options.\fIttyname\fR (in that order) before processing the | |
672 | options on the command line. (In fact, the command-line options are | |
673 | scanned to find the terminal name before the options.\fIttyname\fR | |
674 | file is read.) In forming the name of the options.\fIttyname\fR file, | |
675 | the initial /dev/ is removed from the terminal name, and any remaining | |
676 | / characters are replaced with dots. | |
677 | .PP | |
678 | An options file is parsed into a series of words, delimited by | |
679 | whitespace. Whitespace can be included in a word by enclosing the | |
680 | word in double-quotes ("). A backslash (\\) quotes the following character. | |
681 | A hash (#) starts a comment, which continues until the end of the | |
682 | line. There is no restriction on using the \fIfile\fR or \fIcall\fR | |
683 | options within an options file. | |
684 | .SH SECURITY | |
685 | .I pppd | |
686 | provides system administrators with sufficient access control that PPP | |
687 | access to a server machine can be provided to legitimate users without | |
688 | fear of compromising the security of the server or the network it's | |
689 | on. In part this is provided by the /etc/ppp/options file, where the | |
690 | administrator can place options to restrict the ways in which pppd can | |
691 | be used, and in part by the PAP and CHAP secrets files, where the | |
692 | administrator can restrict the set of IP addresses which individual | |
693 | users may use. | |
694 | .PP | |
695 | The normal way that pppd should be set up is to have the \fIauth\fR | |
696 | option in the /etc/ppp/options file. (This may become the default in | |
697 | later releases.) If users wish to use pppd to dial out to a peer | |
698 | which will refuse to authenticate itself (such as an internet service | |
699 | provider), the system administrator should create an options file | |
700 | under /etc/ppp/peers containing the \fInoauth\fR option, the name of | |
701 | the serial port to use, and the \fIconnect\fR option (if required), | |
702 | plus any other appropriate options. In this way, pppd can be set up | |
703 | to allow non-privileged users to make unauthenticated connections only | |
704 | to trusted peers. | |
705 | .PP | |
706 | As indicated above, some security-sensitive options are privileged, | |
707 | which means that they may not be used by an ordinary non-privileged | |
708 | user running a setuid-root pppd, either on the command line, in the | |
709 | user's ~/.ppprc file, or in an options file read using the \fIfile\fR | |
710 | option. Privileged options may be used in /etc/ppp/options file or in | |
711 | an options file read using the \fIcall\fR option. If pppd is being | |
712 | run by the root user, privileged options can be used without | |
713 | restriction. | |
714 | .SH AUTHENTICATION | |
715 | Authentication is the process whereby one peer convinces the other of | |
716 | its identity. This involves the first peer sending its name to the | |
717 | other, together with some kind of secret information which could only | |
718 | come from the genuine authorized user of that name. In such an | |
719 | exchange, we will call the first peer the "client" and the other the | |
720 | "server". The client has a name by which it identifies itself to the | |
721 | server, and the server also has a name by which it identifies itself | |
722 | to the client. Generally the genuine client shares some secret (or | |
723 | password) with the server, and authenticates itself by proving that it | |
724 | knows that secret. Very often, the names used for authentication | |
725 | correspond to the internet hostnames of the peers, but this is not | |
726 | essential. | |
727 | .LP | |
728 | At present, pppd supports two authentication protocols: the Password | |
729 | Authentication Protocol (PAP) and the Challenge Handshake | |
730 | Authentication Protocol (CHAP). PAP involves the client sending its | |
731 | name and a cleartext password to the server to authenticate itself. | |
732 | In contrast, the server initiates the CHAP authentication exchange by | |
733 | sending a challenge to the client (the challenge packet includes the | |
734 | server's name). The client must respond with a response which | |
735 | includes its name plus a hash value derived from the shared secret and | |
736 | the challenge, in order to prove that it knows the secret. | |
737 | .LP | |
738 | The PPP protocol, being symmetrical, allows both peers to require the | |
739 | other to authenticate itself. In that case, two separate and | |
740 | independent authentication exchanges will occur. The two exchanges | |
741 | could use different authentication protocols, and in principle, | |
742 | different names could be used in the two exchanges. | |
743 | .LP | |
744 | The default behaviour of pppd is to agree to authenticate if | |
745 | requested, and to not require authentication from the peer. However, | |
746 | pppd will not agree to authenticate itself with a particular protocol | |
747 | if it has no secrets which could be used to do so. | |
748 | .LP | |
749 | Pppd stores secrets for use in authentication in secrets | |
750 | files (/etc/ppp/pap-secrets for PAP, /etc/ppp/chap-secrets for CHAP). | |
751 | Both secrets files have the same format. The secrets files can | |
752 | contain secrets for pppd to use in authenticating itself to other | |
753 | systems, as well as secrets for pppd to use when authenticating other | |
754 | systems to itself. | |
755 | .LP | |
756 | Each line in a secrets file contains one secret. A given secret is | |
757 | specific to a particular combination of client and server - it can | |
758 | only be used by that client to authenticate itself to that server. | |
759 | Thus each line in a secrets file has at least 3 fields: the name of | |
760 | the client, the name of the server, and the secret. These fields may | |
761 | be followed by a list of the IP addresses that the specified client | |
762 | may use when connecting to the specified server. | |
763 | .LP | |
764 | A secrets file is parsed into words as for an options file, so the | |
765 | client name, server name and secrets fields must each be one word, | |
766 | with any embedded spaces or other special characters quoted or | |
767 | escaped. Any following words on the same line are taken to be a list | |
768 | of acceptable IP addresses for that client, or an | |
769 | override for "local:remote" addresses (the same format used on the | |
770 | command line or in the options file) when on a line that contains a | |
771 | specific client name (not a wildcard nor empty). | |
772 | If there are only 3 words | |
773 | on the line, or if the first word is "-", then all IP addresses are | |
774 | disallowed. To allow any address, use "*". | |
775 | A word starting with "!" indicates that the | |
776 | specified address is \fInot\fR acceptable. An address may be followed | |
777 | by "/" and a number \fIn\fR, to indicate a whole subnet, i.e. all | |
778 | addresses which have the same value in the most significant \fIn\fR | |
779 | bits. Note that case is significant in the client and server names | |
780 | and in the secret. | |
781 | .LP | |
782 | If the secret starts with an `@', what follows is assumed to be the | |
783 | name of a file from which to read the secret. A "*" as the client or | |
784 | server name matches any name. When selecting a secret, pppd takes the | |
785 | best match, i.e. the match with the fewest wildcards. | |
786 | .LP | |
787 | Thus a secrets file contains both secrets for use in authenticating | |
788 | other hosts, plus secrets which we use for authenticating ourselves to | |
789 | others. When pppd is authenticating the peer (checking the peer's | |
790 | identity), it chooses a secret with the peer's name in the first | |
791 | field and the name of the local system in the second field. The | |
792 | name of the local system defaults to the hostname, with the domain | |
793 | name appended if the \fIdomain\fR option is used. This default can be | |
794 | overridden with the \fIname\fR option, except when the | |
795 | \fIusehostname\fR option is used. | |
796 | .LP | |
797 | When pppd is choosing a secret to use in authenticating itself to the | |
798 | peer, it first determines what name it is going to use to identify | |
799 | itself to the peer. This name can be specified by the user with the | |
800 | \fIuser\fR option. If this option is not used, the name defaults to | |
801 | the name of the local system, determined as described in the previous | |
802 | paragraph. Then pppd looks for a secret with this name in the first | |
803 | field and the peer's name in the second field. Pppd will know the | |
804 | name of the peer if CHAP authentication is being used, because the | |
805 | peer will have sent it in the challenge packet. However, if PAP is being | |
806 | used, pppd will have to determine the peer's name from the options | |
807 | specified by the user. The user can specify the peer's name directly | |
808 | with the \fIremotename\fR option. Otherwise, if the remote IP address | |
809 | was specified by a name (rather than in numeric form), that name will | |
810 | be used as the peer's name. Failing that, pppd will use the null | |
811 | string as the peer's name. | |
812 | .LP | |
813 | When authenticating the peer with PAP, the supplied password is first | |
814 | compared with the secret from the secrets file. If the password | |
815 | doesn't match the secret, the password is encrypted using crypt() and | |
816 | checked against the secret again. Thus secrets for authenticating the | |
817 | peer can be stored in encrypted form if desired. If the | |
818 | \fIpapcrypt\fR option is given, the first (unencrypted) comparison is | |
819 | omitted, for better security. | |
820 | .LP | |
821 | Furthermore, if the \fIlogin\fR option was specified, the username and | |
822 | password are also checked against the system password database. Thus, | |
823 | the system administrator can set up the pap-secrets file to allow PPP | |
824 | access only to certain users, and to restrict the set of IP addresses | |
825 | that each user can use. Typically, when using the \fIlogin\fR option, | |
826 | the secret in /etc/ppp/pap-secrets would be "", which will match any | |
827 | password supplied by the peer. This avoids the need to have the same | |
828 | secret in two places. | |
829 | .LP | |
830 | Additional checks are performed when the \fBlogin\fR option is used. | |
831 | If the file /etc/ppp/ppp.deny exists, and the user is listed in it, | |
832 | the authentication fails. If the file /etc/ppp/ppp.shells exists and | |
833 | the user's normal login shell is not listed, the authentication fails. | |
834 | .LP | |
835 | Authentication must be satisfactorily completed before IPCP (or any | |
836 | other Network Control Protocol) can be started. If the peer is | |
837 | required to authenticate itself, and fails to do so, pppd will | |
838 | terminated the link (by closing LCP). If IPCP negotiates an | |
839 | unacceptable IP address for the remote host, IPCP will be closed. IP | |
840 | packets can only be sent or received when IPCP is open. | |
841 | .LP | |
842 | In some cases it is desirable to allow some hosts which can't | |
843 | authenticate themselves to connect and use one of a restricted set of | |
844 | IP addresses, even when the local host generally requires | |
845 | authentication. If the peer refuses to authenticate itself when | |
846 | requested, pppd takes that as equivalent to authenticating with PAP | |
847 | using the empty string for the username and password. Thus, by adding | |
848 | a line to the pap-secrets file which specifies the empty string for | |
849 | the client and password, it is possible to allow restricted access to | |
850 | hosts which refuse to authenticate themselves. | |
851 | .SH ROUTING | |
852 | .LP | |
853 | When IPCP negotiation is completed successfully, pppd will inform the | |
854 | kernel of the local and remote IP addresses for the ppp interface. | |
855 | This is sufficient to create a host route to the remote end of the | |
856 | link, which will enable the peers to exchange IP packets. | |
857 | Communication with other machines generally requires further | |
858 | modification to routing tables and/or ARP (Address Resolution | |
859 | Protocol) tables. In most cases the \fIdefaultroute\fR and/or | |
860 | \fIproxyarp\fR options are sufficient for this, but in some cases | |
861 | further intervention is required. The /etc/ppp/ip-up script can be | |
862 | used for this. | |
863 | .LP | |
864 | Sometimes it is desirable to add a default route through the remote | |
865 | host, as in the case of a machine whose only connection to the | |
866 | Internet is through the ppp interface. The \fIdefaultroute\fR option | |
867 | causes pppd to create such a default route when IPCP comes up, and | |
868 | delete it when the link is terminated. | |
869 | .LP | |
870 | In some cases it is desirable to use proxy ARP, for example on a | |
871 | server machine connected to a LAN, in order to allow other hosts to | |
872 | communicate with the remote host. The \fIproxyarp\fR option causes | |
873 | pppd to look for a network interface on the same subnet as the remote | |
874 | host (an interface supporting broadcast and ARP, which is up and not a | |
875 | point-to-point or loopback interface). If found, pppd creates a | |
876 | permanent, published ARP entry with the IP address of the remote host | |
877 | and the hardware address of the network interface found. | |
878 | .LP | |
879 | When the \fIdemand\fR option is used, the interface IP addresses have | |
880 | already been set at the point when IPCP comes up. If pppd has not | |
881 | been able to negotiate the same addresses that it used to configure | |
882 | the interface (for example when the peer is an ISP that uses dynamic | |
883 | IP address assignment), pppd has to change the interface IP addresses | |
884 | to the negotiated addresses. This may disrupt existing connections, | |
885 | and the use of demand dialling with peers that do dynamic IP address | |
886 | assignment is not recommended. | |
887 | .SH EXAMPLES | |
888 | .LP | |
889 | The following examples assume that the /etc/ppp/options file contains | |
890 | the \fIauth\fR option (as in the default /etc/ppp/options file in the | |
891 | ppp distribution). | |
892 | .LP | |
893 | Probably the most common use of pppd is to dial out to an ISP. This | |
894 | can be done with a command such as | |
895 | .IP | |
896 | pppd call isp | |
897 | .LP | |
898 | where the /etc/ppp/peers/isp file is set up by the system | |
899 | administrator to contain something like this: | |
900 | .IP | |
901 | ttyS0 19200 crtscts | |
902 | .br | |
903 | connect '/usr/sbin/chat -v -f /etc/ppp/chat-isp' | |
904 | .br | |
905 | noauth | |
906 | .LP | |
907 | In this example, we are using chat to dial the ISP's modem and go | |
908 | through any logon sequence required. The /etc/ppp/chat-isp file | |
909 | contains the script used by chat; it could for example contain | |
910 | something like this: | |
911 | .IP | |
912 | ABORT "NO CARRIER" | |
913 | .br | |
914 | ABORT "NO DIALTONE" | |
915 | .br | |
916 | ABORT "ERROR" | |
917 | .br | |
918 | ABORT "NO ANSWER" | |
919 | .br | |
920 | ABORT "BUSY" | |
921 | .br | |
922 | ABORT "Username/Password Incorrect" | |
923 | .br | |
924 | "" "at" | |
925 | .br | |
926 | OK "at&d0&c1" | |
927 | .br | |
928 | OK "atdt2468135" | |
929 | .br | |
930 | "name:" "^Umyuserid" | |
931 | .br | |
932 | "word:" "\\qmypassword" | |
933 | .br | |
934 | "ispts" "\\q^Uppp" | |
935 | .br | |
936 | "~-^Uppp-~" | |
937 | .LP | |
938 | See the chat(8) man page for details of chat scripts. | |
939 | .LP | |
940 | Pppd can also be used to provide a dial-in ppp service for users. If | |
941 | the users already have login accounts, the simplest way to set up the | |
942 | ppp service is to let the users log in to their accounts and run pppd | |
943 | (installed setuid-root) with a command such as | |
944 | .IP | |
945 | pppd proxyarp | |
946 | .LP | |
947 | To allow a user to use the PPP facilities, you need to allocate an IP | |
948 | address for that user's machine and create an entry in | |
949 | /etc/ppp/pap-secrets or /etc/ppp/chap-secrets (depending on which | |
950 | authentication method the PPP implementation on the user's machine | |
951 | supports), so that the user's | |
952 | machine can authenticate itself. For example, if Joe has a machine | |
953 | called "joespc" which is to be allowed to dial in to the machine | |
954 | called "server" and use the IP address joespc.my.net, you would add an | |
955 | entry like this to /etc/ppp/pap-secrets or /etc/ppp/chap-secrets: | |
956 | .IP | |
957 | joespc server "joe's secret" joespc.my.net | |
958 | .LP | |
959 | Alternatively, you can create a username called (for example) "ppp", | |
960 | whose login shell is pppd and whose home directory is /etc/ppp. | |
961 | Options to be used when pppd is run this way can be put in | |
962 | /etc/ppp/.ppprc. | |
963 | .LP | |
964 | If your serial connection is any more complicated than a piece of | |
965 | wire, you may need to arrange for some control characters to be | |
966 | escaped. In particular, it is often useful to escape XON (^Q) and | |
967 | XOFF (^S), using \fIasyncmap a0000\fR. If the path includes a telnet, | |
968 | you probably should escape ^] as well (\fIasyncmap 200a0000\fR). If | |
969 | the path includes an rlogin, you will need to use the \fIescape ff\fR | |
970 | option on the end which is running the rlogin client, since many | |
971 | rlogin implementations are not transparent; they will remove the | |
972 | sequence [0xff, 0xff, 0x73, 0x73, followed by any 8 bytes] from the | |
973 | stream. | |
974 | .SH DIAGNOSTICS | |
975 | .LP | |
976 | Messages are sent to the syslog daemon using facility LOG_DAEMON. | |
56be8454 | 977 | (This can be overridden by recompiling pppd with the macro |
984263bc MD |
978 | LOG_PPP defined as the desired facility.) In order to see the error |
979 | and debug messages, you will need to edit your /etc/syslog.conf file | |
980 | to direct the messages to the desired output device or file. | |
981 | .LP | |
982 | The \fIdebug\fR option causes the contents of all control packets sent | |
983 | or received to be logged, that is, all LCP, PAP, CHAP or IPCP packets. | |
984 | This can be useful if the PPP negotiation does not succeed or if | |
985 | authentication fails. | |
986 | If debugging is enabled at compile time, the \fIdebug\fR option also | |
987 | causes other debugging messages to be logged. | |
988 | .LP | |
989 | Debugging can also be enabled or disabled by sending a SIGUSR1 signal | |
990 | to the pppd process. This signal acts as a toggle. | |
991 | .SH SCRIPTS | |
992 | Pppd invokes scripts at various stages in its processing which can be | |
993 | used to perform site-specific ancillary processing. These scripts are | |
994 | usually shell scripts, but could be executable code files instead. | |
995 | Pppd does not wait for the scripts to finish. The scripts are | |
996 | executed as root (with the real and effective user-id set to 0), so | |
997 | that they can do things such as update routing tables or run | |
998 | privileged daemons. Be careful that the contents of these scripts do | |
999 | not compromise your system's security. Pppd runs the scripts with | |
1000 | standard input, output and error redirected to /dev/null, and with an | |
1001 | environment that is empty except for some environment variables that | |
1002 | give information about the link. The environment variables that pppd | |
1003 | sets are: | |
1004 | .TP | |
1005 | .B DEVICE | |
1006 | The name of the serial tty device being used. | |
1007 | .TP | |
1008 | .B IFNAME | |
1009 | The name of the network interface being used. | |
1010 | .TP | |
1011 | .B IPLOCAL | |
1012 | The IP address for the local end of the link. This is only set when | |
1013 | IPCP has come up. | |
1014 | .TP | |
1015 | .B IPREMOTE | |
1016 | The IP address for the remote end of the link. This is only set when | |
1017 | IPCP has come up. | |
1018 | .TP | |
1019 | .B PEERNAME | |
1020 | The authenticated name of the peer. This is only set if the peer | |
1021 | authenticates itself. | |
1022 | .TP | |
1023 | .B SPEED | |
1024 | The baud rate of the tty device. | |
1025 | .TP | |
1026 | .B UID | |
1027 | The real user-id of the user who invoked pppd. | |
1028 | .P | |
1029 | Pppd invokes the following scripts, if they exist. It is not an error | |
1030 | if they don't exist. | |
1031 | .TP | |
1032 | .B /etc/ppp/auth-up | |
1033 | A program or script which is executed after the remote system | |
1034 | successfully authenticates itself. It is executed with the parameters | |
1035 | .IP | |
1036 | \fIinterface-name peer-name user-name tty-device speed\fR | |
1037 | .IP | |
1038 | Note that this script is not executed if the peer doesn't authenticate | |
1039 | itself, for example when the \fInoauth\fR option is used. | |
1040 | .TP | |
1041 | .B /etc/ppp/auth-down | |
1042 | A program or script which is executed when the link goes down, if | |
1043 | /etc/ppp/auth-up was previously executed. It is executed in the same | |
1044 | manner with the same parameters as /etc/ppp/auth-up. | |
1045 | .TP | |
1046 | .B /etc/ppp/ip-up | |
1047 | A program or script which is executed when the link is available for | |
1048 | sending and receiving IP packets (that is, IPCP has come up). It is | |
1049 | executed with the parameters | |
1050 | .IP | |
1051 | \fIinterface-name tty-device speed local-IP-address | |
1052 | remote-IP-address ipparam\fR | |
1053 | .TP | |
1054 | .B /etc/ppp/ip-down | |
1055 | A program or script which is executed when the link is no longer | |
1056 | available for sending and receiving IP packets. This script can be | |
1057 | used for undoing the effects of the /etc/ppp/ip-up script. It is | |
1058 | invoked in the same manner and with the same parameters as the ip-up | |
1059 | script. | |
1060 | .TP | |
1061 | .B /etc/ppp/ipx-up | |
1062 | A program or script which is executed when the link is available for | |
1063 | sending and receiving IPX packets (that is, IPXCP has come up). It is | |
1064 | executed with the parameters | |
1065 | .IP | |
1066 | \fIinterface-name tty-device speed network-number local-IPX-node-address | |
1067 | remote-IPX-node-address local-IPX-routing-protocol remote-IPX-routing-protocol | |
1068 | local-IPX-router-name remote-IPX-router-name ipparam pppd-pid\fR | |
1069 | .IP | |
1070 | The local-IPX-routing-protocol and remote-IPX-routing-protocol field | |
1071 | may be one of the following: | |
1072 | .IP | |
1073 | NONE to indicate that there is no routing protocol | |
1074 | .br | |
1075 | RIP to indicate that RIP/SAP should be used | |
1076 | .br | |
1077 | NLSP to indicate that Novell NLSP should be used | |
1078 | .br | |
1079 | RIP NLSP to indicate that both RIP/SAP and NLSP should be used | |
1080 | .TP | |
1081 | .B /etc/ppp/ipx-down | |
1082 | A program or script which is executed when the link is no longer | |
1083 | available for sending and receiving IPX packets. This script can be | |
1084 | used for undoing the effects of the /etc/ppp/ipx-up script. It is | |
1085 | invoked in the same manner and with the same parameters as the ipx-up | |
1086 | script. | |
1087 | .SH FILES | |
1088 | .TP | |
1089 | .B /var/run/ppp\fIn\fB.pid \fR(BSD or Linux), \fB/etc/ppp/ppp\fIn\fB.pid \fR(others) | |
1090 | Process-ID for pppd process on ppp interface unit \fIn\fR. | |
1091 | .TP | |
1092 | .B /etc/ppp/pap-secrets | |
1093 | Usernames, passwords and IP addresses for PAP authentication. This | |
1094 | file should be owned by root and not readable or writable by any other | |
1095 | user. Pppd will log a warning if this is not the case. | |
1096 | .TP | |
1097 | .B /etc/ppp/chap-secrets | |
1098 | Names, secrets and IP addresses for CHAP authentication. As for | |
1099 | /etc/ppp/pap-secrets, this file should be owned by root and not | |
1100 | readable or writable by any other user. Pppd will log a warning if | |
1101 | this is not the case. | |
1102 | .TP | |
1103 | .B /etc/ppp/options | |
1104 | System default options for pppd, read before user default options or | |
1105 | command-line options. | |
1106 | .TP | |
1107 | .B ~/.ppprc | |
1108 | User default options, read before /etc/ppp/options.\fIttyname\fR. | |
1109 | .TP | |
1110 | .B /etc/ppp/options.\fIttyname | |
1111 | System default options for the serial port being used, read after | |
1112 | ~/.ppprc. In forming the \fIttyname\fR part of this | |
1113 | filename, an initial /dev/ is stripped from the port name (if | |
1114 | present), and any slashes in the remaining part are converted to | |
1115 | dots. | |
1116 | .TP | |
1117 | .B /etc/ppp/peers | |
1118 | A directory containing options files which may contain privileged | |
1119 | options, even if pppd was invoked by a user other than root. The | |
1120 | system administrator can create options files in this directory to | |
1121 | permit non-privileged users to dial out without requiring the peer to | |
1122 | authenticate, but only to certain trusted peers. | |
1123 | .TP | |
1124 | .B /etc/ppp/ppp.deny | |
1125 | Lists users who may not use the system password PAP authentication. | |
1126 | .TP | |
1127 | .B /etc/ppp/ppp.shells | |
1128 | Lists user shells which are approved for system password PAP authentication | |
1129 | logins. | |
1130 | .TP | |
1131 | .B /usr/share/examples/pppd/ | |
1132 | Sample pppd configuration files. | |
1133 | .SH SEE ALSO | |
1134 | .IR chat(8), | |
1135 | .IR ppp(8) | |
1136 | .TP | |
cabeba47 | 1137 | .B RFC 1144 |
984263bc MD |
1138 | Jacobson, V. |
1139 | \fICompressing TCP/IP headers for low-speed serial links.\fR | |
1140 | February 1990. | |
1141 | .TP | |
cabeba47 | 1142 | .B RFC 1321 |
984263bc MD |
1143 | Rivest, R. |
1144 | .I The MD5 Message-Digest Algorithm. | |
1145 | April 1992. | |
1146 | .TP | |
cabeba47 | 1147 | .B RFC 1332 |
984263bc MD |
1148 | McGregor, G. |
1149 | .I PPP Internet Protocol Control Protocol (IPCP). | |
1150 | May 1992. | |
1151 | .TP | |
cabeba47 | 1152 | .B RFC 1334 |
984263bc MD |
1153 | Lloyd, B.; Simpson, W.A. |
1154 | .I PPP authentication protocols. | |
1155 | October 1992. | |
1156 | .TP | |
cabeba47 | 1157 | .B RFC 1661 |
984263bc MD |
1158 | Simpson, W.A. |
1159 | .I The Point\-to\-Point Protocol (PPP). | |
1160 | July 1994. | |
1161 | .TP | |
cabeba47 | 1162 | .B RFC 1662 |
984263bc MD |
1163 | Simpson, W.A. |
1164 | .I PPP in HDLC-like Framing. | |
1165 | July 1994. | |
1166 | .SH NOTES | |
1167 | The following signals have the specified effect when sent to pppd. | |
1168 | .TP | |
1169 | .B SIGINT, SIGTERM | |
1170 | These signals cause pppd to terminate the link (by closing LCP), | |
1171 | restore the serial device settings, and exit. | |
1172 | .TP | |
1173 | .B SIGHUP | |
1174 | This signal causes pppd to terminate the link, restore the serial | |
1175 | device settings, and close the serial device. If the \fIpersist\fR or | |
1176 | \fIdemand\fR option has been specified, pppd will try to reopen the | |
1177 | serial device and start another connection (after the holdoff period). | |
1178 | Otherwise pppd will exit. If this signal is received during the | |
1179 | holdoff period, it causes pppd to end the holdoff period immediately. | |
1180 | .TP | |
1181 | .B SIGUSR1 | |
1182 | This signal toggles the state of the \fIdebug\fR option. | |
1183 | .TP | |
1184 | .B SIGUSR2 | |
1185 | This signal causes pppd to renegotiate compression. This can be | |
1186 | useful to re-enable compression after it has been disabled as a result | |
1187 | of a fatal decompression error. (Fatal decompression errors generally | |
1188 | indicate a bug in one or other implementation.) | |
1189 | ||
1190 | .SH AUTHORS | |
1191 | Paul Mackerras (Paul.Mackerras@cs.anu.edu.au), based on earlier work by | |
1192 | Drew Perkins, | |
1193 | Brad Clements, | |
1194 | Karl Fox, | |
1195 | Greg Christy, | |
1196 | and | |
1197 | Brad Parker. |