Commit | Line | Data |
---|---|---|
984263bc MD |
1 | changequote({,})dnl |
2 | changecom(,)dnl | |
3 | .\" | |
4 | .\" Copyright (c) 2001 Brian Somers <brian@Awfulhak.org> | |
5 | .\" All rights reserved. | |
6 | .\" | |
7 | .\" Redistribution and use in source and binary forms, with or without | |
8 | .\" modification, are permitted provided that the following conditions | |
9 | .\" are met: | |
10 | .\" 1. Redistributions of source code must retain the above copyright | |
11 | .\" notice, this list of conditions and the following disclaimer. | |
12 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
13 | .\" notice, this list of conditions and the following disclaimer in the | |
14 | .\" documentation and/or other materials provided with the distribution. | |
15 | .\" | |
16 | .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND | |
17 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
18 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
19 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE | |
20 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
21 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
22 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
23 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
24 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
25 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
26 | .\" SUCH DAMAGE. | |
27 | .\" | |
28 | .\" $FreeBSD: src/usr.sbin/ppp/ppp.8.m4,v 1.301.2.1 2002/09/01 02:12:31 brian Exp $ | |
29 | .\" | |
49d37166 | 30 | .Dd October 10, 2019 |
984263bc MD |
31 | .Dt PPP 8 |
32 | .Os | |
33 | .Sh NAME | |
34 | .Nm ppp | |
35 | .Nd Point to Point Protocol (a.k.a. user-ppp) | |
36 | .Sh SYNOPSIS | |
37 | .Nm | |
38 | .Op Fl Va mode | |
39 | .Op Fl nat | |
40 | .Op Fl quiet | |
41 | .Op Fl unit Ns Ar N | |
42 | .Op Ar system ... | |
43 | .Sh DESCRIPTION | |
44 | This is a user process | |
45 | .Em PPP | |
d9d67b59 | 46 | software package with the help of the tunnel device driver |
e6fb0a49 | 47 | .Xr ( tun 4 ) . |
984263bc MD |
48 | .Pp |
49 | The | |
50 | .Fl nat | |
51 | flag does the equivalent of a | |
52 | .Dq nat enable yes , | |
53 | enabling | |
54 | .Nm Ns No 's | |
55 | network address translation features. | |
56 | This allows | |
57 | .Nm | |
58 | to act as a NAT or masquerading engine for all machines on an internal | |
59 | LAN. | |
60 | ifdef({LOCALNAT},{},{Refer to | |
61 | .Xr libalias 3 | |
62 | for details on the technical side of the NAT engine. | |
63 | })dnl | |
64 | Refer to the | |
65 | .Sx NETWORK ADDRESS TRANSLATION (PACKET ALIASING) | |
66 | section of this manual page for details on how to configure NAT in | |
67 | .Nm . | |
68 | .Pp | |
69 | The | |
70 | .Fl quiet | |
71 | flag tells | |
72 | .Nm | |
73 | to be silent at startup rather than displaying the mode and interface | |
74 | to standard output. | |
75 | .Pp | |
76 | The | |
77 | .Fl unit | |
78 | flag tells | |
79 | .Nm | |
80 | to only attempt to open | |
81 | .Pa /dev/tun Ns Ar N . | |
82 | Normally, | |
83 | .Nm | |
84 | will start with a value of 0 for | |
85 | .Ar N , | |
86 | and keep trying to open a tunnel device by incrementing the value of | |
87 | .Ar N | |
88 | by one each time until it succeeds. | |
89 | If it fails three times in a row | |
90 | because the device file is missing, it gives up. | |
91 | .Pp | |
92 | The following | |
93 | .Va mode Ns No s | |
94 | are understood by | |
95 | .Nm : | |
96 | .Bl -tag -width XXX -offset XXX | |
97 | .It Fl auto | |
98 | .Nm | |
99 | opens the tun interface, configures it then goes into the background. | |
100 | The link isn't brought up until outgoing data is detected on the tun | |
101 | interface at which point | |
102 | .Nm | |
103 | attempts to bring up the link. | |
104 | Packets received (including the first one) while | |
105 | .Nm | |
106 | is trying to bring the link up will remain queued for a default of | |
107 | 2 minutes. | |
108 | See the | |
109 | .Dq set choked | |
110 | command below. | |
111 | .Pp | |
112 | In | |
113 | .Fl auto | |
114 | mode, at least one | |
115 | .Dq system | |
116 | must be given on the command line (see below) and a | |
117 | .Dq set ifaddr | |
118 | must be done in the system profile that specifies a peer IP address to | |
119 | use when configuring the interface. | |
120 | Something like | |
121 | .Dq 10.0.0.1/0 | |
122 | is usually appropriate. | |
123 | See the | |
124 | .Dq pmdemand | |
125 | system in | |
126 | .Pa /usr/share/examples/ppp/ppp.conf.sample | |
127 | for an example. | |
128 | .It Fl background | |
129 | Here, | |
130 | .Nm | |
131 | attempts to establish a connection with the peer immediately. | |
132 | If it succeeds, | |
133 | .Nm | |
134 | goes into the background and the parent process returns an exit code | |
135 | of 0. | |
136 | If it fails, | |
137 | .Nm | |
138 | exits with a non-zero result. | |
139 | .It Fl foreground | |
140 | In foreground mode, | |
141 | .Nm | |
142 | attempts to establish a connection with the peer immediately, but never | |
143 | becomes a daemon. | |
144 | The link is created in background mode. | |
145 | This is useful if you wish to control | |
146 | .Nm Ns No 's | |
147 | invocation from another process. | |
148 | .It Fl direct | |
149 | This is used for receiving incoming connections. | |
150 | .Nm | |
151 | ignores the | |
152 | .Dq set device | |
153 | line and uses descriptor 0 as the link. | |
154 | .Pp | |
155 | If callback is configured, | |
156 | .Nm | |
157 | will use the | |
158 | .Dq set device | |
159 | information when dialing back. | |
160 | .It Fl dedicated | |
161 | This option is designed for machines connected with a dedicated | |
162 | wire. | |
163 | .Nm | |
164 | will always keep the device open and will never use any configured | |
165 | chat scripts. | |
166 | .It Fl ddial | |
167 | This mode is equivalent to | |
168 | .Fl auto | |
169 | mode except that | |
170 | .Nm | |
171 | will bring the link back up any time it's dropped for any reason. | |
172 | .It Fl interactive | |
173 | This is a no-op, and gives the same behaviour as if none of the above | |
174 | modes have been specified. | |
175 | .Nm | |
176 | loads any sections specified on the command line then provides an | |
177 | interactive prompt. | |
178 | .El | |
179 | .Pp | |
180 | One or more configuration entries or systems | |
181 | (as specified in | |
182 | .Pa /etc/ppp/ppp.conf ) | |
183 | may also be specified on the command line. | |
184 | .Nm | |
185 | will read the | |
186 | .Dq default | |
187 | system from | |
188 | .Pa /etc/ppp/ppp.conf | |
189 | at startup, followed by each of the systems specified on the command line. | |
190 | .Sh Major Features | |
191 | .Bl -diag | |
192 | .It Provides an interactive user interface. | |
193 | Using its command mode, the user can | |
194 | easily enter commands to establish the connection with the remote end, check | |
195 | the status of connection and close the connection. | |
196 | All functions can also be optionally password protected for security. | |
197 | .It Supports both manual and automatic dialing. | |
198 | Interactive mode has a | |
199 | .Dq term | |
200 | command which enables you to talk to the device directly. | |
201 | When you are connected to the remote peer and it starts to talk | |
202 | .Em PPP , | |
203 | .Nm | |
204 | detects it and switches to packet mode automatically. | |
205 | Once you have | |
206 | determined the proper sequence for connecting with the remote host, you | |
207 | can write a chat script to {define} the necessary dialing and login | |
208 | procedure for later convenience. | |
209 | .It Supports on-demand dialup capability. | |
210 | By using | |
211 | .Fl auto | |
212 | mode, | |
213 | .Nm | |
214 | will act as a daemon and wait for a packet to be sent over the | |
215 | .Em PPP | |
216 | link. | |
217 | When this happens, the daemon automatically dials and establishes the | |
218 | connection. | |
219 | In almost the same manner | |
220 | .Fl ddial | |
221 | mode (direct-dial mode) also automatically dials and establishes the | |
222 | connection. | |
223 | However, it differs in that it will dial the remote site | |
224 | any time it detects the link is down, even if there are no packets to be | |
225 | sent. | |
226 | This mode is useful for full-time connections where we worry less | |
227 | about line charges and more about being connected full time. | |
228 | A third | |
229 | .Fl dedicated | |
230 | mode is also available. | |
231 | This mode is targeted at a dedicated link between two machines. | |
232 | .Nm | |
233 | will never voluntarily quit from dedicated mode - you must send it the | |
234 | .Dq quit all | |
235 | command via its diagnostic socket. | |
236 | A | |
237 | .Dv SIGHUP | |
238 | will force an LCP renegotiation, and a | |
239 | .Dv SIGTERM | |
240 | will force it to exit. | |
241 | .It Supports client callback. | |
242 | .Nm | |
243 | can use either the standard LCP callback protocol or the Microsoft | |
cb5730a1 SW |
244 | CallBack Control Protocol |
245 | .Pa ( ftp://ftp.microsoft.com/developr/rfc/cbcp.txt ) . | |
984263bc MD |
246 | .It Supports NAT or packet aliasing. |
247 | Packet aliasing (a.k.a. IP masquerading) allows computers on a | |
248 | private, unregistered network to access the Internet. | |
249 | The | |
250 | .Em PPP | |
251 | host acts as a masquerading gateway. | |
252 | IP addresses as well as TCP and | |
253 | UDP port numbers are NAT'd for outgoing packets and de-NAT'd for | |
254 | returning packets. | |
255 | .It Supports background PPP connections. | |
256 | In background mode, if | |
257 | .Nm | |
258 | successfully establishes the connection, it will become a daemon. | |
259 | Otherwise, it will exit with an error. | |
260 | This allows the setup of | |
261 | scripts that wish to execute certain commands only if the connection | |
262 | is successfully established. | |
263 | .It Supports server-side PPP connections. | |
264 | In direct mode, | |
265 | .Nm | |
266 | acts as server which accepts incoming | |
267 | .Em PPP | |
268 | connections on stdin/stdout. | |
9f3fc534 | 269 | .It "Supports PAP and CHAP (rfc 1994, 2433 and 2759) authentication." |
984263bc MD |
270 | With PAP or CHAP, it is possible to skip the Unix style |
271 | .Xr login 1 | |
272 | procedure, and use the | |
273 | .Em PPP | |
274 | protocol for authentication instead. | |
275 | If the peer requests Microsoft CHAP authentication and | |
276 | .Nm | |
277 | is compiled with DES support, an appropriate MD4/DES response will be | |
278 | made. | |
279 | .It Supports RADIUS (rfc 2138 & 2548) authentication. | |
280 | An extension to PAP and CHAP, | |
281 | .Em \&R Ns No emote | |
282 | .Em \&A Ns No ccess | |
283 | .Em \&D Ns No ial | |
284 | .Em \&I Ns No n | |
285 | .Em \&U Ns No ser | |
286 | .Em \&S Ns No ervice | |
287 | allows authentication information to be stored in a central or | |
288 | distributed database along with various per-user framed connection | |
289 | characteristics. | |
290 | ifdef({LOCALRAD},{},{If | |
49d37166 | 291 | .Em RADIUS |
292 | support was enabled at compile time, | |
984263bc MD |
293 | .Nm |
294 | will use it to make | |
295 | .Em RADIUS | |
296 | requests when configured to do so. | |
297 | })dnl | |
298 | .It Supports Proxy Arp. | |
299 | .Nm | |
300 | can be configured to make one or more proxy arp entries on behalf of | |
301 | the peer. | |
302 | This allows routing from the peer to the LAN without | |
303 | configuring each machine on that LAN. | |
304 | .It Supports packet filtering. | |
305 | User can {define} four kinds of filters: the | |
306 | .Em in | |
307 | filter for incoming packets, the | |
308 | .Em out | |
309 | filter for outgoing packets, the | |
310 | .Em dial | |
311 | filter to {define} a dialing trigger packet and the | |
312 | .Em alive | |
313 | filter for keeping a connection alive with the trigger packet. | |
314 | .It Tunnel driver supports bpf. | |
315 | The user can use | |
316 | .Xr tcpdump 1 | |
317 | to check the packet flow over the | |
318 | .Em PPP | |
319 | link. | |
320 | .It Supports PPP over TCP and PPP over UDP. | |
321 | If a device name is specified as | |
322 | .Em host Ns No : Ns Em port Ns | |
323 | .Xo | |
324 | .Op / Ns tcp|udp , | |
325 | .Xc | |
326 | .Nm | |
327 | will open a TCP or UDP connection for transporting data rather than using a | |
328 | conventional serial device. | |
329 | UDP connections force | |
330 | .Nm | |
331 | into synchronous mode. | |
984263bc MD |
332 | .It Supports PPP over Ethernet (rfc 2516). |
333 | If | |
334 | .Nm | |
335 | is given a device specification of the format | |
336 | .No PPPoE: Ns Ar iface Ns Xo | |
337 | .Op \&: Ns Ar provider Ns | |
338 | .Xc | |
339 | and if | |
340 | .Xr netgraph 4 | |
341 | is available, | |
342 | .Nm | |
343 | will attempt talk | |
344 | .Em PPP | |
345 | over Ethernet to | |
346 | .Ar provider | |
347 | using the | |
348 | .Ar iface | |
349 | network interface. | |
350 | .Pp | |
351 | On systems that do not support | |
352 | .Xr netgraph 4 , | |
353 | an external program such as | |
354 | .Xr pppoe 8 | |
355 | may be used. | |
356 | .It "Supports IETF draft Predictor-1 (rfc 1978) and DEFLATE (rfc 1979) compression." | |
357 | .Nm | |
358 | supports not only VJ-compression but also Predictor-1 and DEFLATE compression. | |
359 | Normally, a modem has built-in compression (e.g., v42.bis) and the system | |
360 | may receive higher data rates from it as a result of such compression. | |
361 | While this is generally a good thing in most other situations, this | |
362 | higher speed data imposes a penalty on the system by increasing the | |
363 | number of serial interrupts the system has to process in talking to the | |
364 | modem and also increases latency. | |
365 | Unlike VJ-compression, Predictor-1 and DEFLATE compression pre-compresses | |
366 | .Em all | |
367 | network traffic flowing through the link, thus reducing overheads to a | |
368 | minimum. | |
369 | .It Supports Microsoft's IPCP extensions (rfc 1877). | |
370 | Name Server Addresses and NetBIOS Name Server Addresses can be negotiated | |
371 | with clients using the Microsoft | |
372 | .Em PPP | |
373 | stack (i.e., Win95, WinNT) | |
374 | .It Supports Multi-link PPP (rfc 1990) | |
375 | It is possible to configure | |
376 | .Nm | |
377 | to open more than one physical connection to the peer, combining the | |
378 | bandwidth of all links for better throughput. | |
379 | .It Supports MPPE (draft-ietf-pppext-mppe) | |
380 | MPPE is Microsoft Point to Point Encryption scheme. | |
381 | It is possible to configure | |
382 | .Nm | |
383 | to participate in Microsoft's Windows VPN. | |
384 | For now, | |
385 | .Nm | |
386 | can only get encryption keys from CHAP 81 authentication. | |
387 | .Nm | |
388 | must be compiled with DES for MPPE to operate. | |
389 | .It Supports IPV6CP (rfc 2023). | |
390 | An IPv6 connection can be made in addition to or instead of the normal | |
391 | IPv4 connection. | |
392 | .El | |
393 | .Sh PERMISSIONS | |
394 | .Nm | |
395 | is installed as user | |
396 | .Dv root | |
397 | and group | |
398 | .Dv network , | |
399 | with permissions | |
400 | .Dv 04554 . | |
401 | By default, | |
402 | .Nm | |
403 | will not run if the invoking user id is not zero. | |
404 | This may be overridden by using the | |
405 | .Dq allow users | |
406 | command in | |
407 | .Pa /etc/ppp/ppp.conf . | |
408 | When running as a normal user, | |
409 | .Nm | |
410 | switches to user id 0 in order to alter the system routing table, set up | |
411 | system lock files and read the ppp configuration files. | |
412 | All external commands (executed via the "shell" or "!bg" commands) are executed | |
413 | as the user id that invoked | |
414 | .Nm . | |
415 | Refer to the | |
416 | .Sq ID0 | |
417 | logging facility if you're interested in what exactly is done as user id | |
418 | zero. | |
419 | .Sh GETTING STARTED | |
420 | When you first run | |
421 | .Nm | |
422 | you may need to deal with some initial configuration details. | |
423 | .Bl -bullet | |
424 | .It | |
dd7331fe | 425 | Your kernel must {include} a tunnel device (the X86_64_GENERIC kernel includes |
984263bc MD |
426 | one by default). |
427 | If it doesn't, or if you require more than one tun | |
428 | interface, you'll need to rebuild your kernel with the following line in | |
429 | your kernel configuration file: | |
430 | .Pp | |
431 | .Dl pseudo-device tun N | |
432 | .Pp | |
433 | where | |
434 | .Ar N | |
435 | is the maximum number of | |
436 | .Em PPP | |
437 | connections you wish to support. | |
438 | .It | |
984263bc MD |
439 | Make sure that your system has a group named |
440 | .Dq network | |
441 | in the | |
442 | .Pa /etc/group | |
443 | file and that the group contains the names of all users expected to use | |
444 | .Nm . | |
445 | Refer to the | |
446 | .Xr group 5 | |
447 | manual page for details. | |
448 | Each of these users must also be given access using the | |
449 | .Dq allow users | |
450 | command in | |
451 | .Pa /etc/ppp/ppp.conf . | |
452 | .It | |
453 | Create a log file. | |
454 | .Nm | |
455 | uses | |
456 | .Xr syslog 3 | |
457 | to log information. | |
458 | A common log file name is | |
459 | .Pa /var/log/ppp.log . | |
460 | To make output go to this file, put the following lines in the | |
461 | .Pa /etc/syslog.conf | |
462 | file: | |
463 | .Bd -literal -offset indent | |
464 | !ppp | |
465 | *.*<TAB>/var/log/ppp.log | |
466 | .Ed | |
467 | .Pp | |
468 | It is possible to have more than one | |
469 | .Em PPP | |
470 | log file by creating a link to the | |
471 | .Nm | |
472 | executable: | |
473 | .Pp | |
474 | .Dl # cd /usr/sbin | |
475 | .Dl # ln ppp ppp0 | |
476 | .Pp | |
477 | and using | |
478 | .Bd -literal -offset indent | |
479 | !ppp0 | |
480 | *.*<TAB>/var/log/ppp0.log | |
481 | .Ed | |
482 | .Pp | |
483 | in | |
484 | .Pa /etc/syslog.conf . | |
485 | Don't forget to send a | |
486 | .Dv HUP | |
487 | signal to | |
488 | .Xr syslogd 8 | |
489 | after altering | |
490 | .Pa /etc/syslog.conf . | |
491 | .It | |
492 | Although not strictly relevant to | |
493 | .Nm Ns No 's | |
494 | operation, you should configure your resolver so that it works correctly. | |
495 | This can be done by configuring a local DNS | |
496 | (using | |
497 | .Xr named 8 ) | |
498 | or by adding the correct | |
499 | .Sq nameserver | |
500 | lines to the file | |
501 | .Pa /etc/resolv.conf . | |
502 | Refer to the | |
503 | .Xr resolv.conf 5 | |
504 | manual page for details. | |
505 | .Pp | |
506 | Alternatively, if the peer supports it, | |
507 | .Nm | |
508 | can be configured to ask the peer for the nameserver address(es) and to | |
509 | update | |
510 | .Pa /etc/resolv.conf | |
511 | automatically. | |
512 | Refer to the | |
513 | .Dq enable dns | |
514 | and | |
515 | .Dq resolv | |
516 | commands below for details. | |
517 | .El | |
518 | .Sh MANUAL DIALING | |
519 | In the following examples, we assume that your machine name is | |
520 | .Dv awfulhak . | |
521 | when you invoke | |
522 | .Nm | |
523 | (see | |
524 | .Sx PERMISSIONS | |
525 | above) with no arguments, you are presented with a prompt: | |
526 | .Bd -literal -offset indent | |
527 | ppp ON awfulhak> | |
528 | .Ed | |
529 | .Pp | |
530 | The | |
531 | .Sq ON | |
532 | part of your prompt should always be in upper case. | |
533 | If it is in lower case, it means that you must supply a password using the | |
534 | .Dq passwd | |
535 | command. | |
536 | This only ever happens if you connect to a running version of | |
537 | .Nm | |
538 | and have not authenticated yourself using the correct password. | |
539 | .Pp | |
540 | You can start by specifying the device name and speed: | |
541 | .Bd -literal -offset indent | |
542 | ppp ON awfulhak> set device /dev/cuaa0 | |
543 | ppp ON awfulhak> set speed 38400 | |
544 | .Ed | |
545 | .Pp | |
546 | Normally, hardware flow control (CTS/RTS) is used. | |
547 | However, under | |
548 | certain circumstances (as may happen when you are connected directly | |
549 | to certain PPP-capable terminal servers), this may result in | |
550 | .Nm | |
551 | hanging as soon as it tries to write data to your communications link | |
552 | as it is waiting for the CTS (clear to send) signal - which will never | |
553 | come. | |
554 | Thus, if you have a direct line and can't seem to make a | |
555 | connection, try turning CTS/RTS off with | |
556 | .Dq set ctsrts off . | |
557 | If you need to do this, check the | |
558 | .Dq set accmap | |
559 | description below too - you'll probably need to | |
560 | .Dq set accmap 000a0000 . | |
561 | .Pp | |
562 | Usually, parity is set to | |
563 | .Dq none , | |
564 | and this is | |
565 | .Nm Ns No 's | |
566 | default. | |
567 | Parity is a rather archaic error checking mechanism that is no | |
568 | longer used because modern modems do their own error checking, and most | |
569 | link-layer protocols (that's what | |
570 | .Nm | |
571 | is) use much more reliable checking mechanisms. | |
572 | Parity has a relatively | |
573 | huge overhead (a 12.5% increase in traffic) and as a result, it is always | |
574 | disabled | |
575 | (set to | |
576 | .Dq none ) | |
577 | when | |
578 | .Dv PPP | |
579 | is opened. | |
580 | However, some ISPs (Internet Service Providers) may use | |
581 | specific parity settings at connection time (before | |
582 | .Dv PPP | |
583 | is opened). | |
584 | Notably, Compuserve insist on even parity when logging in: | |
585 | .Bd -literal -offset indent | |
586 | ppp ON awfulhak> set parity even | |
587 | .Ed | |
588 | .Pp | |
589 | You can now see what your current device settings look like: | |
590 | .Bd -literal -offset indent | |
591 | ppp ON awfulhak> show physical | |
592 | Name: deflink | |
593 | State: closed | |
594 | Device: N/A | |
595 | Link Type: interactive | |
596 | Connect Count: 0 | |
597 | Queued Packets: 0 | |
598 | Phone Number: N/A | |
599 | ||
600 | Defaults: | |
601 | Device List: /dev/cuaa0 | |
602 | Characteristics: 38400bps, cs8, even parity, CTS/RTS on | |
603 | ||
604 | Connect time: 0 secs | |
605 | 0 octets in, 0 octets out | |
606 | Overall 0 bytes/sec | |
607 | ppp ON awfulhak> | |
608 | .Ed | |
609 | .Pp | |
610 | The term command can now be used to talk directly to the device: | |
611 | .Bd -literal -offset indent | |
612 | ppp ON awfulhak> term | |
613 | at | |
614 | OK | |
615 | atdt123456 | |
616 | CONNECT | |
617 | login: myispusername | |
618 | Password: myisppassword | |
619 | Protocol: ppp | |
620 | .Ed | |
621 | .Pp | |
622 | When the peer starts to talk in | |
623 | .Em PPP , | |
624 | .Nm | |
625 | detects this automatically and returns to command mode. | |
626 | .Bd -literal -offset indent | |
627 | ppp ON awfulhak> # No link has been established | |
628 | Ppp ON awfulhak> # We've connected & finished LCP | |
629 | PPp ON awfulhak> # We've authenticated | |
630 | PPP ON awfulhak> # We've agreed IP numbers | |
631 | .Ed | |
632 | .Pp | |
633 | If it does not, it's probable that the peer is waiting for your end to | |
634 | start negotiating. | |
635 | To force | |
636 | .Nm | |
637 | to start sending | |
638 | .Em PPP | |
639 | configuration packets to the peer, use the | |
640 | .Dq ~p | |
641 | command to drop out of terminal mode and enter packet mode. | |
642 | .Pp | |
643 | If you never even receive a login prompt, it is quite likely that the | |
644 | peer wants to use PAP or CHAP authentication instead of using Unix-style | |
645 | login/password authentication. | |
646 | To set things up properly, drop back to | |
647 | the prompt and set your authentication name and key, then reconnect: | |
648 | .Bd -literal -offset indent | |
649 | ~. | |
650 | ppp ON awfulhak> set authname myispusername | |
651 | ppp ON awfulhak> set authkey myisppassword | |
652 | ppp ON awfulhak> term | |
653 | at | |
654 | OK | |
655 | atdt123456 | |
656 | CONNECT | |
657 | .Ed | |
658 | .Pp | |
659 | You may need to tell ppp to initiate negotiations with the peer here too: | |
660 | .Bd -literal -offset indent | |
661 | ~p | |
662 | ppp ON awfulhak> # No link has been established | |
663 | Ppp ON awfulhak> # We've connected & finished LCP | |
664 | PPp ON awfulhak> # We've authenticated | |
665 | PPP ON awfulhak> # We've agreed IP numbers | |
666 | .Ed | |
667 | .Pp | |
668 | You are now connected! | |
669 | Note that | |
670 | .Sq PPP | |
671 | in the prompt has changed to capital letters to indicate that you have | |
672 | a peer connection. | |
673 | If only some of the three Ps go uppercase, wait until | |
674 | either everything is uppercase or lowercase. | |
675 | If they revert to lowercase, it means that | |
676 | .Nm | |
677 | couldn't successfully negotiate with the peer. | |
678 | A good first step for troubleshooting at this point would be to | |
679 | .Bd -literal -offset indent | |
680 | ppp ON awfulhak> set log local phase lcp ipcp | |
681 | .Ed | |
682 | .Pp | |
683 | and try again. | |
684 | Refer to the | |
685 | .Dq set log | |
686 | command description below for further details. | |
687 | If things fail at this point, | |
688 | it is quite important that you turn logging on and try again. | |
689 | It is also | |
690 | important that you note any prompt changes and report them to anyone trying | |
691 | to help you. | |
692 | .Pp | |
693 | When the link is established, the show command can be used to see how | |
694 | things are going: | |
695 | .Bd -literal -offset indent | |
696 | PPP ON awfulhak> show physical | |
697 | * Modem related information is shown here * | |
698 | PPP ON awfulhak> show ccp | |
699 | * CCP (compression) related information is shown here * | |
700 | PPP ON awfulhak> show lcp | |
701 | * LCP (line control) related information is shown here * | |
702 | PPP ON awfulhak> show ipcp | |
703 | * IPCP (IP) related information is shown here * | |
704 | PPP ON awfulhak> show ipv6cp | |
705 | * IPV6CP (IPv6) related information is shown here * | |
706 | PPP ON awfulhak> show link | |
707 | * Link (high level) related information is shown here * | |
708 | PPP ON awfulhak> show bundle | |
709 | * Logical (high level) connection related information is shown here * | |
710 | .Ed | |
711 | .Pp | |
712 | At this point, your machine has a host route to the peer. | |
713 | This means | |
714 | that you can only make a connection with the host on the other side | |
715 | of the link. | |
716 | If you want to add a default route entry (telling your | |
717 | machine to send all packets without another routing entry to the other | |
718 | side of the | |
719 | .Em PPP | |
720 | link), enter the following command: | |
721 | .Bd -literal -offset indent | |
722 | PPP ON awfulhak> add default HISADDR | |
723 | .Ed | |
724 | .Pp | |
725 | The string | |
726 | .Sq HISADDR | |
727 | represents the IP address of the connected peer. | |
728 | If the | |
729 | .Dq add | |
730 | command fails due to an existing route, you can overwrite the existing | |
731 | route using | |
732 | .Bd -literal -offset indent | |
733 | PPP ON awfulhak> add! default HISADDR | |
734 | .Ed | |
735 | .Pp | |
736 | This command can also be executed before actually making the connection. | |
737 | If a new IP address is negotiated at connection time, | |
738 | .Nm | |
739 | will update your default route accordingly. | |
740 | .Pp | |
741 | You can now use your network applications (ping, telnet, ftp etc.) | |
742 | in other windows or terminals on your machine. | |
743 | If you wish to reuse the current terminal, you can put | |
744 | .Nm | |
745 | into the background using your standard shell suspend and background | |
746 | commands (usually | |
747 | .Dq ^Z | |
748 | followed by | |
749 | .Dq bg ) . | |
750 | .Pp | |
751 | Refer to the | |
752 | .Sx PPP COMMAND LIST | |
753 | section for details on all available commands. | |
754 | .Sh AUTOMATIC DIALING | |
755 | To use automatic dialing, you must prepare some Dial and Login chat scripts. | |
756 | See the example definitions in | |
757 | .Pa /usr/share/examples/ppp/ppp.conf.sample | |
758 | (the format of | |
759 | .Pa /etc/ppp/ppp.conf | |
760 | is pretty simple). | |
761 | Each line contains one comment, inclusion, label or command: | |
762 | .Bl -bullet | |
763 | .It | |
764 | A line starting with a | |
765 | .Pq Dq # | |
766 | character is treated as a comment line. | |
767 | Leading whitespace are ignored when identifying comment lines. | |
768 | .It | |
769 | An inclusion is a line beginning with the word | |
770 | .Sq {!include} . | |
771 | It must have one argument - the file to {include}. | |
772 | You may wish to | |
773 | .Dq {!include} ~/.ppp.conf | |
774 | for compatibility with older versions of | |
775 | .Nm . | |
776 | .It | |
777 | A label name starts in the first column and is followed by | |
778 | a colon | |
779 | .Pq Dq \&: . | |
780 | .It | |
781 | A command line must contain a space or tab in the first column. | |
782 | .El | |
783 | .Pp | |
784 | The | |
785 | .Pa /etc/ppp/ppp.conf | |
786 | file should consist of at least a | |
787 | .Dq default | |
788 | section. | |
789 | This section is always executed. | |
790 | It should also contain | |
791 | one or more sections, named according to their purpose, for example, | |
792 | .Dq MyISP | |
793 | would represent your ISP, and | |
794 | .Dq ppp-in | |
795 | would represent an incoming | |
796 | .Nm | |
797 | configuration. | |
798 | You can now specify the destination label name when you invoke | |
799 | .Nm . | |
800 | Commands associated with the | |
801 | .Dq default | |
802 | label are executed, followed by those associated with the destination | |
803 | label provided. | |
804 | When | |
805 | .Nm | |
806 | is started with no arguments, the | |
807 | .Dq default | |
808 | section is still executed. | |
809 | The load command can be used to manually load a section from the | |
810 | .Pa /etc/ppp/ppp.conf | |
811 | file: | |
812 | .Bd -literal -offset indent | |
813 | ppp ON awfulhak> load MyISP | |
814 | .Ed | |
815 | .Pp | |
816 | Note, no action is taken by | |
817 | .Nm | |
818 | after a section is loaded, whether it's the result of passing a label on | |
819 | the command line or using the | |
820 | .Dq load | |
821 | command. | |
822 | Only the commands specified for that label in the configuration | |
823 | file are executed. | |
824 | However, when invoking | |
825 | .Nm | |
826 | with the | |
827 | .Fl background , | |
828 | .Fl ddial , | |
829 | or | |
830 | .Fl dedicated | |
831 | switches, the link mode tells | |
832 | .Nm | |
833 | to establish a connection. | |
834 | Refer to the | |
835 | .Dq set mode | |
836 | command below for further details. | |
837 | .Pp | |
838 | Once the connection is made, the | |
839 | .Sq ppp | |
840 | portion of the prompt will change to | |
841 | .Sq PPP : | |
842 | .Bd -literal -offset indent | |
843 | # ppp MyISP | |
844 | \&... | |
845 | ppp ON awfulhak> dial | |
846 | Ppp ON awfulhak> | |
847 | PPp ON awfulhak> | |
848 | PPP ON awfulhak> | |
849 | .Ed | |
850 | .Pp | |
851 | The Ppp prompt indicates that | |
852 | .Nm | |
853 | has entered the authentication phase. | |
854 | The PPp prompt indicates that | |
855 | .Nm | |
856 | has entered the network phase. | |
857 | The PPP prompt indicates that | |
858 | .Nm | |
859 | has successfully negotiated a network layer protocol and is in | |
860 | a usable state. | |
861 | .Pp | |
862 | If the | |
863 | .Pa /etc/ppp/ppp.linkup | |
864 | file is available, its contents are executed | |
865 | when the | |
866 | .Em PPP | |
867 | connection is established. | |
868 | See the provided | |
869 | .Dq pmdemand | |
870 | example in | |
871 | .Pa /usr/share/examples/ppp/ppp.conf.sample | |
872 | which runs a script in the background after the connection is established | |
873 | (refer to the | |
874 | .Dq shell | |
875 | and | |
876 | .Dq bg | |
877 | commands below for a description of possible substitution strings). | |
878 | Similarly, when a connection is closed, the contents of the | |
879 | .Pa /etc/ppp/ppp.linkdown | |
880 | file are executed. | |
881 | Both of these files have the same format as | |
882 | .Pa /etc/ppp/ppp.conf . | |
883 | .Pp | |
884 | In previous versions of | |
885 | .Nm , | |
886 | it was necessary to re-add routes such as the default route in the | |
887 | .Pa ppp.linkup | |
888 | file. | |
889 | .Nm | |
890 | supports | |
891 | .Sq sticky routes , | |
892 | where all routes that contain the | |
893 | .Dv HISADDR , | |
894 | .Dv MYADDR , | |
895 | .Dv HISADDR6 | |
896 | or | |
897 | .Dv MYADDR6 | |
898 | literals will automatically be updated when the values of these variables | |
899 | change. | |
900 | .Sh BACKGROUND DIALING | |
901 | If you want to establish a connection using | |
902 | .Nm | |
903 | non-interactively (such as from a | |
904 | .Xr crontab 5 | |
905 | entry or an | |
906 | .Xr at 1 | |
907 | job) you should use the | |
908 | .Fl background | |
909 | option. | |
910 | When | |
911 | .Fl background | |
912 | is specified, | |
913 | .Nm | |
914 | attempts to establish the connection immediately. | |
915 | If multiple phone | |
916 | numbers are specified, each phone number will be tried once. | |
917 | If the attempt fails, | |
918 | .Nm | |
919 | exits immediately with a non-zero exit code. | |
920 | If it succeeds, then | |
921 | .Nm | |
922 | becomes a daemon, and returns an exit status of zero to its caller. | |
923 | The daemon exits automatically if the connection is dropped by the | |
924 | remote system, or it receives a | |
925 | .Dv TERM | |
926 | signal. | |
927 | .Sh DIAL ON DEMAND | |
928 | Demand dialing is enabled with the | |
929 | .Fl auto | |
930 | or | |
931 | .Fl ddial | |
932 | options. | |
933 | You must also specify the destination label in | |
934 | .Pa /etc/ppp/ppp.conf | |
935 | to use. | |
936 | It must contain the | |
937 | .Dq set ifaddr | |
938 | command to {define} the remote peers IP address. | |
939 | (refer to | |
940 | .Pa /usr/share/examples/ppp/ppp.conf.sample ) | |
941 | .Bd -literal -offset indent | |
942 | # ppp -auto pmdemand | |
943 | .Ed | |
944 | .Pp | |
945 | When | |
946 | .Fl auto | |
947 | or | |
948 | .Fl ddial | |
949 | is specified, | |
950 | .Nm | |
951 | runs as a daemon but you can still configure or examine its | |
952 | configuration by using the | |
953 | .Dq set server | |
954 | command in | |
955 | .Pa /etc/ppp/ppp.conf , | |
956 | (for example, | |
957 | .Dq Li "set server +3000 mypasswd" ) | |
958 | and connecting to the diagnostic port as follows: | |
959 | .Bd -literal -offset indent | |
960 | # pppctl 3000 (assuming tun0) | |
961 | Password: | |
962 | PPP ON awfulhak> show who | |
963 | tcp (127.0.0.1:1028) * | |
964 | .Ed | |
965 | .Pp | |
966 | The | |
967 | .Dq show who | |
968 | command lists users that are currently connected to | |
969 | .Nm | |
970 | itself. | |
971 | If the diagnostic socket is closed or changed to a different | |
972 | socket, all connections are immediately dropped. | |
973 | .Pp | |
974 | In | |
975 | .Fl auto | |
976 | mode, when an outgoing packet is detected, | |
977 | .Nm | |
978 | will perform the dialing action (chat script) and try to connect | |
979 | with the peer. | |
980 | In | |
981 | .Fl ddial | |
982 | mode, the dialing action is performed any time the line is found | |
983 | to be down. | |
984 | If the connect fails, the default behaviour is to wait 30 seconds | |
985 | and then attempt to connect when another outgoing packet is detected. | |
986 | This behaviour can be changed using the | |
987 | .Dq set redial | |
988 | command: | |
989 | .Pp | |
990 | .No set redial Ar secs Ns Xo | |
991 | .Oo + Ns Ar inc Ns | |
992 | .Op - Ns Ar max Ns | |
993 | .Oc Ns Op . Ns Ar next | |
994 | .Op Ar attempts | |
995 | .Xc | |
996 | .Pp | |
997 | .Bl -tag -width attempts -compact | |
998 | .It Ar secs | |
999 | is the number of seconds to wait before attempting | |
1000 | to connect again. | |
1001 | If the argument is the literal string | |
1002 | .Sq Li random , | |
1003 | the delay period is a random value between 1 and 30 seconds inclusive. | |
1004 | .It Ar inc | |
1005 | is the number of seconds that | |
1006 | .Ar secs | |
1007 | should be incremented each time a new dial attempt is made. | |
1008 | The timeout reverts to | |
1009 | .Ar secs | |
1010 | only after a successful connection is established. | |
1011 | The default value for | |
1012 | .Ar inc | |
1013 | is zero. | |
1014 | .It Ar max | |
1015 | is the maximum number of times | |
1016 | .Nm | |
1017 | should increment | |
1018 | .Ar secs . | |
1019 | The default value for | |
1020 | .Ar max | |
1021 | is 10. | |
1022 | .It Ar next | |
1023 | is the number of seconds to wait before attempting | |
1024 | to dial the next number in a list of numbers (see the | |
1025 | .Dq set phone | |
1026 | command). | |
1027 | The default is 3 seconds. | |
1028 | Again, if the argument is the literal string | |
1029 | .Sq Li random , | |
1030 | the delay period is a random value between 1 and 30 seconds. | |
1031 | .It Ar attempts | |
1032 | is the maximum number of times to try to connect for each outgoing packet | |
1033 | that triggers a dial. | |
1034 | The previous value is unchanged if this parameter is omitted. | |
1035 | If a value of zero is specified for | |
1036 | .Ar attempts , | |
1037 | .Nm | |
1038 | will keep trying until a connection is made. | |
1039 | .El | |
1040 | .Pp | |
1041 | So, for example: | |
1042 | .Bd -literal -offset indent | |
1043 | set redial 10.3 4 | |
1044 | .Ed | |
1045 | .Pp | |
1046 | will attempt to connect 4 times for each outgoing packet that causes | |
1047 | a dial attempt with a 3 second delay between each number and a 10 second | |
1048 | delay after all numbers have been tried. | |
1049 | If multiple phone numbers | |
1050 | are specified, the total number of attempts is still 4 (it does not | |
1051 | attempt each number 4 times). | |
1052 | .Pp | |
1053 | Alternatively, | |
984263bc MD |
1054 | .Bd -literal -offset indent |
1055 | set redial 10+10-5.3 20 | |
1056 | .Ed | |
1057 | .Pp | |
1058 | tells | |
1059 | .Nm | |
1060 | to attempt to connect 20 times. | |
1061 | After the first attempt, | |
1062 | .Nm | |
1063 | pauses for 10 seconds. | |
1064 | After the next attempt it pauses for 20 seconds | |
1065 | and so on until after the sixth attempt it pauses for 1 minute. | |
1066 | The next 14 pauses will also have a duration of one minute. | |
1067 | If | |
1068 | .Nm | |
1069 | connects, disconnects and fails to connect again, the timeout starts again | |
1070 | at 10 seconds. | |
1071 | .Pp | |
1072 | Modifying the dial delay is very useful when running | |
1073 | .Nm | |
1074 | in | |
1075 | .Fl auto | |
1076 | mode on both ends of the link. | |
1077 | If each end has the same timeout, | |
1078 | both ends wind up calling each other at the same time if the link | |
1079 | drops and both ends have packets queued. | |
1080 | At some locations, the serial link may not be reliable, and carrier | |
1081 | may be lost at inappropriate times. | |
1082 | It is possible to have | |
1083 | .Nm | |
1084 | redial should carrier be unexpectedly lost during a session. | |
1085 | .Bd -literal -offset indent | |
1086 | set reconnect timeout ntries | |
1087 | .Ed | |
1088 | .Pp | |
1089 | This command tells | |
1090 | .Nm | |
1091 | to re-establish the connection | |
1092 | .Ar ntries | |
1093 | times on loss of carrier with a pause of | |
1094 | .Ar timeout | |
1095 | seconds before each try. | |
1096 | For example, | |
1097 | .Bd -literal -offset indent | |
1098 | set reconnect 3 5 | |
1099 | .Ed | |
1100 | .Pp | |
1101 | tells | |
1102 | .Nm | |
1103 | that on an unexpected loss of carrier, it should wait | |
1104 | .Ar 3 | |
1105 | seconds before attempting to reconnect. | |
1106 | This may happen up to | |
1107 | .Ar 5 | |
1108 | times before | |
1109 | .Nm | |
1110 | gives up. | |
1111 | The default value of ntries is zero (no reconnect). | |
1112 | Care should be taken with this option. | |
1113 | If the local timeout is slightly | |
1114 | longer than the remote timeout, the reconnect feature will always be | |
1115 | triggered (up to the given number of times) after the remote side | |
1116 | times out and hangs up. | |
1117 | NOTE: In this context, losing too many LQRs constitutes a loss of | |
1118 | carrier and will trigger a reconnect. | |
1119 | If the | |
1120 | .Fl background | |
1121 | flag is specified, all phone numbers are dialed at most once until | |
1122 | a connection is made. | |
1123 | The next number redial period specified with the | |
1124 | .Dq set redial | |
1125 | command is honoured, as is the reconnect tries value. | |
1126 | If your redial | |
1127 | value is less than the number of phone numbers specified, not all | |
1128 | the specified numbers will be tried. | |
1129 | To terminate the program, type | |
1130 | .Bd -literal -offset indent | |
1131 | PPP ON awfulhak> close | |
1132 | ppp ON awfulhak> quit all | |
1133 | .Ed | |
1134 | .Pp | |
1135 | A simple | |
1136 | .Dq quit | |
1137 | command will terminate the | |
1138 | .Xr pppctl 8 | |
1139 | or | |
1140 | .Xr telnet 1 | |
1141 | connection but not the | |
1142 | .Nm | |
1143 | program itself. | |
1144 | You must use | |
1145 | .Dq quit all | |
1146 | to terminate | |
1147 | .Nm | |
1148 | as well. | |
1149 | .Sh RECEIVING INCOMING PPP CONNECTIONS (Method 1) | |
1150 | To handle an incoming | |
1151 | .Em PPP | |
1152 | connection request, follow these steps: | |
1153 | .Bl -enum | |
1154 | .It | |
1155 | Make sure the modem and (optionally) | |
be67b412 | 1156 | .Pa /etc/rc.d/serial |
984263bc MD |
1157 | is configured correctly. |
1158 | .Bl -bullet -compact | |
1159 | .It | |
1160 | Use Hardware Handshake (CTS/RTS) for flow control. | |
1161 | .It | |
1162 | Modem should be set to NO echo back (ATE0) and NO results string (ATQ1). | |
1163 | .El | |
984263bc MD |
1164 | .It |
1165 | Edit | |
1166 | .Pa /etc/ttys | |
1167 | to enable a | |
1168 | .Xr getty 8 | |
1169 | on the port where the modem is attached. | |
1170 | For example: | |
1171 | .Pp | |
1172 | .Dl ttyd1 Qo /usr/libexec/getty std.38400 Qc dialup on secure | |
1173 | .Pp | |
1174 | Don't forget to send a | |
1175 | .Dv HUP | |
1176 | signal to the | |
1177 | .Xr init 8 | |
1178 | process to start the | |
1179 | .Xr getty 8 : | |
1180 | .Pp | |
1181 | .Dl # kill -HUP 1 | |
1182 | .Pp | |
1183 | It is usually also necessary to train your modem to the same DTR speed | |
1184 | as the getty: | |
1185 | .Bd -literal -offset indent | |
1186 | # ppp | |
1187 | ppp ON awfulhak> set device /dev/cuaa1 | |
1188 | ppp ON awfulhak> set speed 38400 | |
1189 | ppp ON awfulhak> term | |
1190 | deflink: Entering terminal mode on /dev/cuaa1 | |
1191 | Type `~?' for help | |
1192 | at | |
1193 | OK | |
1194 | at | |
1195 | OK | |
1196 | atz | |
1197 | OK | |
1198 | at | |
1199 | OK | |
1200 | ~. | |
1201 | ppp ON awfulhak> quit | |
1202 | .Ed | |
1203 | .It | |
1204 | Create a | |
1205 | .Pa /usr/local/bin/ppplogin | |
1206 | file with the following contents: | |
1207 | .Bd -literal -offset indent | |
1208 | #! /bin/sh | |
1209 | exec /usr/sbin/ppp -direct incoming | |
1210 | .Ed | |
1211 | .Pp | |
1212 | Direct mode | |
1213 | .Pq Fl direct | |
1214 | lets | |
1215 | .Nm | |
1216 | work with stdin and stdout. | |
1217 | You can also use | |
1218 | .Xr pppctl 8 | |
1219 | to connect to a configured diagnostic port, in the same manner as with | |
1220 | client-side | |
1221 | .Nm . | |
1222 | .Pp | |
1223 | Here, the | |
1224 | .Ar incoming | |
1225 | section must be set up in | |
1226 | .Pa /etc/ppp/ppp.conf . | |
1227 | .Pp | |
1228 | Make sure that the | |
1229 | .Ar incoming | |
1230 | section contains the | |
1231 | .Dq allow users | |
1232 | command as appropriate. | |
1233 | .It | |
1234 | Prepare an account for the incoming user. | |
1235 | .Bd -literal | |
1236 | ppp:xxxx:66:66:PPP Login User:/home/ppp:/usr/local/bin/ppplogin | |
1237 | .Ed | |
1238 | .Pp | |
1239 | Refer to the manual entries for | |
1240 | .Xr adduser 8 | |
1241 | and | |
1242 | .Xr vipw 8 | |
1243 | for details. | |
1244 | .It | |
1245 | Support for IPCP Domain Name Server and NetBIOS Name Server negotiation | |
1246 | can be enabled using the | |
1247 | .Dq accept dns | |
1248 | and | |
1249 | .Dq set nbns | |
1250 | commands. | |
1251 | Refer to their descriptions below. | |
1252 | .El | |
1253 | .Sh RECEIVING INCOMING PPP CONNECTIONS (Method 2) | |
1254 | This method differs in that we use | |
1255 | .Nm | |
1256 | to authenticate the connection rather than | |
1257 | .Xr login 1 : | |
1258 | .Bl -enum | |
1259 | .It | |
1260 | Configure your default section in | |
1261 | .Pa /etc/gettytab | |
1262 | with automatic ppp recognition by specifying the | |
1263 | .Dq pp | |
1264 | capability: | |
1265 | .Bd -literal | |
1266 | default:\\ | |
1267 | :pp=/usr/local/bin/ppplogin:\\ | |
1268 | ..... | |
1269 | .Ed | |
1270 | .It | |
1271 | Configure your serial device(s), enable a | |
1272 | .Xr getty 8 | |
1273 | and create | |
1274 | .Pa /usr/local/bin/ppplogin | |
1275 | as in the first three steps for method 1 above. | |
1276 | .It | |
1277 | Add either | |
1278 | .Dq enable chap | |
1279 | or | |
1280 | .Dq enable pap | |
1281 | (or both) | |
1282 | to | |
1283 | .Pa /etc/ppp/ppp.conf | |
1284 | under the | |
1285 | .Sq incoming | |
1286 | label (or whatever label | |
1287 | .Pa ppplogin | |
1288 | uses). | |
1289 | .It | |
1290 | Create an entry in | |
1291 | .Pa /etc/ppp/ppp.secret | |
1292 | for each incoming user: | |
1293 | .Bd -literal | |
1294 | Pfred<TAB>xxxx | |
1295 | Pgeorge<TAB>yyyy | |
1296 | .Ed | |
1297 | .El | |
1298 | .Pp | |
1299 | Now, as soon as | |
1300 | .Xr getty 8 | |
1301 | detects a ppp connection (by recognising the HDLC frame headers), it runs | |
1302 | .Dq /usr/local/bin/ppplogin . | |
1303 | .Pp | |
1304 | It is | |
1305 | .Em VITAL | |
1306 | that either PAP or CHAP are enabled as above. | |
1307 | If they are not, you are | |
1308 | allowing anybody to establish a ppp session with your machine | |
1309 | .Em without | |
1310 | a password, opening yourself up to all sorts of potential attacks. | |
1311 | .Sh AUTHENTICATING INCOMING CONNECTIONS | |
1312 | Normally, the receiver of a connection requires that the peer | |
1313 | authenticates itself. | |
1314 | This may be done using | |
1315 | .Xr login 1 , | |
1316 | but alternatively, you can use PAP or CHAP. | |
1317 | CHAP is the more secure of the two, but some clients may not support it. | |
1318 | Once you decide which you wish to use, add the command | |
1319 | .Sq enable chap | |
1320 | or | |
1321 | .Sq enable pap | |
1322 | to the relevant section of | |
1323 | .Pa ppp.conf . | |
1324 | .Pp | |
1325 | You must then configure the | |
1326 | .Pa /etc/ppp/ppp.secret | |
1327 | file. | |
1328 | This file contains one line per possible client, each line | |
1329 | containing up to five fields: | |
1330 | .Pp | |
1331 | .Ar name Ar key Oo | |
1332 | .Ar hisaddr Op Ar label Op Ar callback-number | |
1333 | .Oc | |
1334 | .Pp | |
1335 | The | |
1336 | .Ar name | |
1337 | and | |
1338 | .Ar key | |
1339 | specify the client username and password. | |
1340 | If | |
1341 | .Ar key | |
1342 | is | |
1343 | .Dq \&* | |
1344 | and PAP is being used, | |
1345 | .Nm | |
1346 | will look up the password database | |
1347 | .Pq Xr passwd 5 | |
1348 | when authenticating. | |
1349 | If the client does not offer a suitable response based on any | |
1350 | .Ar name Ns No / Ns Ar key | |
1351 | combination in | |
1352 | .Pa ppp.secret , | |
1353 | authentication fails. | |
1354 | .Pp | |
1355 | If authentication is successful, | |
1356 | .Ar hisaddr | |
1357 | (if specified) | |
1358 | is used when negotiating IP numbers. | |
1359 | See the | |
1360 | .Dq set ifaddr | |
1361 | command for details. | |
1362 | .Pp | |
1363 | If authentication is successful and | |
1364 | .Ar label | |
1365 | is specified, the current system label is changed to match the given | |
1366 | .Ar label . | |
1367 | This will change the subsequent parsing of the | |
1368 | .Pa ppp.linkup | |
1369 | and | |
1370 | .Pa ppp.linkdown | |
1371 | files. | |
1372 | .Pp | |
1373 | If authentication is successful and | |
1374 | .Ar callback-number | |
1375 | is specified and | |
1376 | .Dq set callback | |
1377 | has been used in | |
1378 | .Pa ppp.conf , | |
1379 | the client will be called back on the given number. | |
1380 | If CBCP is being used, | |
1381 | .Ar callback-number | |
1382 | may also contain a list of numbers or a | |
1383 | .Dq \&* , | |
1384 | as if passed to the | |
1385 | .Dq set cbcp | |
1386 | command. | |
1387 | The value will be used in | |
1388 | .Nm Ns No 's | |
1389 | subsequent CBCP phase. | |
1390 | .Sh PPP OVER TCP and UDP (a.k.a Tunnelling) | |
1391 | Instead of running | |
1392 | .Nm | |
1393 | over a serial link, it is possible to | |
1394 | use a TCP connection instead by specifying the host, port and protocol as the | |
1395 | device: | |
1396 | .Pp | |
1397 | .Dl set device ui-gate:6669/tcp | |
1398 | .Pp | |
1399 | Instead of opening a serial device, | |
1400 | .Nm | |
1401 | will open a TCP connection to the given machine on the given | |
1402 | socket. | |
1403 | It should be noted however that | |
1404 | .Nm | |
1405 | doesn't use the telnet protocol and will be unable to negotiate | |
1406 | with a telnet server. | |
1407 | You should set up a port for receiving this | |
1408 | .Em PPP | |
1409 | connection on the receiving machine (ui-gate). | |
1410 | This is done by first updating | |
1411 | .Pa /etc/services | |
1412 | to name the service: | |
1413 | .Pp | |
1414 | .Dl ppp-in 6669/tcp # Incoming PPP connections over TCP | |
1415 | .Pp | |
1416 | and updating | |
1417 | .Pa /etc/inetd.conf | |
1418 | to tell | |
1419 | .Xr inetd 8 | |
1420 | how to deal with incoming connections on that port: | |
1421 | .Pp | |
1422 | .Dl ppp-in stream tcp nowait root /usr/sbin/ppp ppp -direct ppp-in | |
1423 | .Pp | |
1424 | Don't forget to send a | |
1425 | .Dv HUP | |
1426 | signal to | |
1427 | .Xr inetd 8 | |
1428 | after you've updated | |
1429 | .Pa /etc/inetd.conf . | |
1430 | Here, we use a label named | |
1431 | .Dq ppp-in . | |
1432 | The entry in | |
1433 | .Pa /etc/ppp/ppp.conf | |
1434 | on ui-gate (the receiver) should contain the following: | |
1435 | .Bd -literal -offset indent | |
1436 | ppp-in: | |
1437 | set timeout 0 | |
1438 | set ifaddr 10.0.4.1 10.0.4.2 | |
1439 | .Ed | |
1440 | .Pp | |
1441 | and the entry in | |
1442 | .Pa /etc/ppp/ppp.linkup | |
1443 | should contain: | |
1444 | .Bd -literal -offset indent | |
1445 | ppp-in: | |
1446 | add 10.0.1.0/24 HISADDR | |
1447 | .Ed | |
1448 | .Pp | |
1449 | It is necessary to put the | |
1450 | .Dq add | |
1451 | command in | |
1452 | .Pa ppp.linkup | |
1453 | to ensure that the route is only added after | |
1454 | .Nm | |
1455 | has negotiated and assigned addresses to its interface. | |
1456 | .Pp | |
1457 | You may also want to enable PAP or CHAP for security. | |
1458 | To enable PAP, add the following line: | |
1459 | .Bd -literal -offset indent | |
1460 | enable PAP | |
1461 | .Ed | |
1462 | .Pp | |
1463 | You'll also need to create the following entry in | |
1464 | .Pa /etc/ppp/ppp.secret : | |
1465 | .Bd -literal -offset indent | |
1466 | MyAuthName MyAuthPasswd | |
1467 | .Ed | |
1468 | .Pp | |
1469 | If | |
1470 | .Ar MyAuthPasswd | |
1471 | is a | |
1472 | .Dq * , | |
1473 | the password is looked up in the | |
1474 | .Xr passwd 5 | |
1475 | database. | |
1476 | .Pp | |
1477 | The entry in | |
1478 | .Pa /etc/ppp/ppp.conf | |
1479 | on awfulhak (the initiator) should contain the following: | |
1480 | .Bd -literal -offset indent | |
1481 | ui-gate: | |
1482 | set escape 0xff | |
1483 | set device ui-gate:ppp-in/tcp | |
1484 | set dial | |
1485 | set timeout 30 | |
1486 | set log Phase Chat Connect hdlc LCP IPCP IPV6CP CCP tun | |
1487 | set ifaddr 10.0.4.2 10.0.4.1 | |
1488 | .Ed | |
1489 | .Pp | |
1490 | with the route setup in | |
1491 | .Pa /etc/ppp/ppp.linkup : | |
1492 | .Bd -literal -offset indent | |
1493 | ui-gate: | |
1494 | add 10.0.2.0/24 HISADDR | |
1495 | .Ed | |
1496 | .Pp | |
1497 | Again, if you're enabling PAP, you'll also need this in the | |
1498 | .Pa /etc/ppp/ppp.conf | |
1499 | profile: | |
1500 | .Bd -literal -offset indent | |
1501 | set authname MyAuthName | |
1502 | set authkey MyAuthKey | |
1503 | .Ed | |
1504 | .Pp | |
1505 | We're assigning the address of 10.0.4.1 to ui-gate, and the address | |
1506 | 10.0.4.2 to awfulhak. | |
1507 | To open the connection, just type | |
1508 | .Pp | |
1509 | .Dl awfulhak # ppp -background ui-gate | |
1510 | .Pp | |
1511 | The result will be an additional "route" on awfulhak to the | |
1512 | 10.0.2.0/24 network via the TCP connection, and an additional | |
1513 | "route" on ui-gate to the 10.0.1.0/24 network. | |
1514 | The networks are effectively bridged - the underlying TCP | |
1515 | connection may be across a public network (such as the | |
1516 | Internet), and the | |
1517 | .Em PPP | |
1518 | traffic is conceptually encapsulated | |
1519 | (although not packet by packet) inside the TCP stream between | |
1520 | the two gateways. | |
1521 | .Pp | |
1522 | The major disadvantage of this mechanism is that there are two | |
1523 | "guaranteed delivery" mechanisms in place - the underlying TCP | |
1524 | stream and whatever protocol is used over the | |
1525 | .Em PPP | |
1526 | link - probably TCP again. | |
1527 | If packets are lost, both levels will | |
1528 | get in each others way trying to negotiate sending of the missing | |
1529 | packet. | |
1530 | .Pp | |
1531 | To avoid this overhead, it is also possible to do all this using | |
1532 | UDP instead of TCP as the transport by simply changing the protocol | |
1533 | from "tcp" to "udp". | |
1534 | When using UDP as a transport, | |
1535 | .Nm | |
1536 | will operate in synchronous mode. | |
1537 | This is another gain as the incoming | |
1538 | data does not have to be rearranged into packets. | |
1539 | .Pp | |
1540 | Care should be taken when adding a default route through a tunneled | |
1541 | setup like this. | |
1542 | It is quite common for the default route | |
1543 | (added in | |
1544 | .Pa /etc/ppp/ppp.linkup ) | |
1545 | to end up routing the link's TCP connection through the tunnel, | |
1546 | effectively garrotting the connection. | |
1547 | To avoid this, make sure you add a static route for the benefit of | |
1548 | the link: | |
1549 | .Bd -literal -offset indent | |
1550 | ui-gate: | |
1551 | set escape 0xff | |
1552 | set device ui-gate:ppp-in/tcp | |
1553 | add ui-gate x.x.x.x | |
1554 | ..... | |
1555 | .Ed | |
1556 | .Pp | |
1557 | where | |
1558 | .Dq x.x.x.x | |
1559 | is the IP number that your route to | |
1560 | .Dq ui-gate | |
1561 | would normally use. | |
1562 | .Pp | |
163ffa07 | 1563 | When routing your connection across a public network such as the Internet, |
984263bc MD |
1564 | it is preferable to encrypt the data. |
1565 | This can be done with the help of the MPPE protocol, although currently this | |
1566 | means that you will not be able to also compress the traffic as MPPE is | |
1567 | implemented as a compression layer (thank Microsoft for this). | |
1568 | To enable MPPE encryption, add the following lines to | |
1569 | .Pa /etc/ppp/ppp.conf | |
1570 | on the server: | |
1571 | .Bd -literal -offset indent | |
1572 | enable MSCHAPv2 | |
1573 | disable deflate pred1 | |
1574 | deny deflate pred1 | |
1575 | .Ed | |
1576 | .Pp | |
1577 | ensuring that you've put the requisite entry in | |
1578 | .Pa /etc/ppp/ppp.secret | |
1579 | (MSCHAPv2 is challenge based, so | |
1580 | .Xr passwd 5 | |
1581 | cannot be used) | |
1582 | .Pp | |
1583 | MSCHAPv2 and MPPE are accepted by default, so the client end should work | |
1584 | without any additional changes (although ensure you have | |
1585 | .Dq set authname | |
1586 | and | |
1587 | .Dq set authkey | |
1588 | in your profile). | |
1589 | .Sh NETWORK ADDRESS TRANSLATION (PACKET ALIASING) | |
1590 | The | |
1591 | .Fl nat | |
1592 | command line option enables network address translation (a.k.a. packet | |
1593 | aliasing). | |
1594 | This allows the | |
1595 | .Nm | |
1596 | host to act as a masquerading gateway for other computers over | |
1597 | a local area network. | |
1598 | Outgoing IP packets are NAT'd so that they appear to come from the | |
1599 | .Nm | |
1600 | host, and incoming packets are de-NAT'd so that they are routed | |
1601 | to the correct machine on the local area network. | |
1602 | NAT allows computers on private, unregistered subnets to have Internet | |
1603 | access, although they are invisible from the outside world. | |
1604 | In general, correct | |
1605 | .Nm | |
1606 | operation should first be verified with network address translation disabled. | |
1607 | Then, the | |
1608 | .Fl nat | |
1609 | option should be switched on, and network applications (web browser, | |
1610 | .Xr telnet 1 , | |
1611 | .Xr ftp 1 , | |
1612 | .Xr ping 8 , | |
1613 | .Xr traceroute 8 ) | |
1614 | should be checked on the | |
1615 | .Nm | |
1616 | host. | |
1617 | Finally, the same or similar applications should be checked on other | |
1618 | computers in the LAN. | |
1619 | If network applications work correctly on the | |
1620 | .Nm | |
1621 | host, but not on other machines in the LAN, then the masquerading | |
1622 | software is working properly, but the host is either not forwarding | |
1623 | or possibly receiving IP packets. | |
1624 | Check that IP forwarding is enabled in | |
1625 | .Pa /etc/rc.conf | |
1626 | and that other machines have designated the | |
1627 | .Nm | |
1628 | host as the gateway for the LAN. | |
1629 | .Sh PACKET FILTERING | |
1630 | This implementation supports packet filtering. | |
1631 | There are four kinds of | |
1632 | filters: the | |
1633 | .Em in | |
1634 | filter, the | |
1635 | .Em out | |
1636 | filter, the | |
1637 | .Em dial | |
1638 | filter and the | |
1639 | .Em alive | |
1640 | filter. | |
1641 | Here are the basics: | |
1642 | .Bl -bullet | |
1643 | .It | |
1644 | A filter definition has the following syntax: | |
1645 | .Pp | |
1646 | set filter | |
1647 | .Ar name | |
1648 | .Ar rule-no | |
1649 | .Ar action | |
1650 | .Op !\& | |
1651 | .Oo | |
1652 | .Op host | |
1653 | .Ar src_addr Ns Op / Ns Ar width | |
1654 | .Op Ar dst_addr Ns Op / Ns Ar width | |
1655 | .Oc | |
1656 | .Ar [ proto Op src Ar cmp port | |
1657 | .Op dst Ar cmp port | |
1658 | .Op estab | |
1659 | .Op syn | |
1660 | .Op finrst | |
1661 | .Op timeout Ar secs ] | |
1662 | .Bl -enum | |
1663 | .It | |
1664 | .Ar Name | |
1665 | should be one of | |
1666 | .Sq in , | |
1667 | .Sq out , | |
1668 | .Sq dial | |
1669 | or | |
1670 | .Sq alive . | |
1671 | .It | |
1672 | .Ar Rule-no | |
1673 | is a numeric value between | |
1674 | .Sq 0 | |
1675 | and | |
1676 | .Sq 39 | |
1677 | specifying the rule number. | |
1678 | Rules are specified in numeric order according to | |
1679 | .Ar rule-no , | |
1680 | but only if rule | |
1681 | .Sq 0 | |
1682 | is defined. | |
1683 | .It | |
1684 | .Ar Action | |
1685 | may be specified as | |
1686 | .Sq permit | |
1687 | or | |
1688 | .Sq deny , | |
1689 | in which case, if a given packet matches the rule, the associated action | |
1690 | is taken immediately. | |
1691 | .Ar Action | |
1692 | can also be specified as | |
1693 | .Sq clear | |
1694 | to clear the action associated with that particular rule, or as a new | |
1695 | rule number greater than the current rule. | |
1696 | In this case, if a given | |
1697 | packet matches the current rule, the packet will next be matched against | |
1698 | the new rule number (rather than the next rule number). | |
1699 | .Pp | |
1700 | The | |
1701 | .Ar action | |
1702 | may optionally be followed with an exclamation mark | |
1703 | .Pq Dq !\& , | |
1704 | telling | |
1705 | .Nm | |
1706 | to reverse the sense of the following match. | |
1707 | .It | |
1708 | .Op Ar src_addr Ns Op / Ns Ar width | |
1709 | and | |
1710 | .Op Ar dst_addr Ns Op / Ns Ar width | |
1711 | are the source and destination IP number specifications. | |
1712 | If | |
1713 | .Op / Ns Ar width | |
1714 | is specified, it gives the number of relevant netmask bits, | |
1715 | allowing the specification of an address range. | |
1716 | .Pp | |
1717 | Either | |
1718 | .Ar src_addr | |
1719 | or | |
1720 | .Ar dst_addr | |
1721 | may be given the values | |
1722 | .Dv MYADDR , | |
1723 | .Dv HISADDR , | |
1724 | .Dv MYADDR6 | |
1725 | or | |
1726 | .Dv HISADDR6 | |
1727 | (refer to the description of the | |
1728 | .Dq bg | |
1729 | command for a description of these values). | |
1730 | When these values are used, | |
1731 | the filters will be updated any time the values change. | |
1732 | This is similar to the behaviour of the | |
1733 | .Dq add | |
1734 | command below. | |
1735 | .It | |
1736 | .Ar Proto | |
1737 | may be any protocol from | |
1738 | .Xr protocols 5 . | |
1739 | .It | |
1740 | .Ar Cmp | |
1741 | is one of | |
1742 | .Sq \< , | |
1743 | .Sq \&eq | |
1744 | or | |
1745 | .Sq \> , | |
1746 | meaning less-than, equal and greater-than respectively. | |
1747 | .Ar Port | |
1748 | can be specified as a numeric port or by service name from | |
1749 | .Pa /etc/services . | |
1750 | .It | |
1751 | The | |
1752 | .Sq estab , | |
1753 | .Sq syn , | |
1754 | and | |
1755 | .Sq finrst | |
1756 | flags are only allowed when | |
1757 | .Ar proto | |
1758 | is set to | |
1759 | .Sq tcp , | |
1760 | and represent the TH_ACK, TH_SYN and TH_FIN or TH_RST TCP flags respectively. | |
1761 | .It | |
1762 | The timeout value adjusts the current idle timeout to at least | |
1763 | .Ar secs | |
1764 | seconds. | |
1765 | If a timeout is given in the alive filter as well as in the in/out | |
1766 | filter, the in/out value is used. | |
1767 | If no timeout is given, the default timeout (set using | |
1768 | .Ic set timeout | |
1769 | and defaulting to 180 seconds) is used. | |
1770 | .El | |
984263bc MD |
1771 | .It |
1772 | Each filter can hold up to 40 rules, starting from rule 0. | |
1773 | The entire rule set is not effective until rule 0 is defined, | |
1774 | i.e., the default is to allow everything through. | |
1775 | .It | |
1776 | If no rule in a defined set of rules matches a packet, that packet will | |
1777 | be discarded (blocked). | |
1778 | If there are no rules in a given filter, the packet will be permitted. | |
1779 | .It | |
1780 | It's possible to filter based on the payload of UDP frames where those | |
1781 | frames contain a | |
1782 | .Em PROTO_IP | |
1783 | .Em PPP | |
1784 | frame header. | |
1785 | See the | |
1786 | .Ar filter-decapsulation | |
1787 | option below for further details. | |
1788 | .It | |
1789 | Use | |
1790 | .Dq set filter Ar name No -1 | |
1791 | to flush all rules. | |
1792 | .El | |
1793 | .Pp | |
1794 | See | |
1795 | .Pa /usr/share/examples/ppp/ppp.conf.sample . | |
1796 | .Sh SETTING THE IDLE TIMER | |
1797 | To check/set the idle timer, use the | |
1798 | .Dq show bundle | |
1799 | and | |
1800 | .Dq set timeout | |
1801 | commands: | |
1802 | .Bd -literal -offset indent | |
1803 | ppp ON awfulhak> set timeout 600 | |
1804 | .Ed | |
1805 | .Pp | |
1806 | The timeout period is measured in seconds, the default value for which | |
1807 | is 180 seconds | |
1808 | (or 3 min). | |
1809 | To disable the idle timer function, use the command | |
1810 | .Bd -literal -offset indent | |
1811 | ppp ON awfulhak> set timeout 0 | |
1812 | .Ed | |
1813 | .Pp | |
1814 | In | |
1815 | .Fl ddial | |
1816 | and | |
1817 | .Fl dedicated | |
1818 | modes, the idle timeout is ignored. | |
1819 | In | |
1820 | .Fl auto | |
1821 | mode, when the idle timeout causes the | |
1822 | .Em PPP | |
1823 | session to be | |
1824 | closed, the | |
1825 | .Nm | |
1826 | program itself remains running. | |
1827 | Another trigger packet will cause it to attempt to re-establish the link. | |
1828 | .Sh PREDICTOR-1 and DEFLATE COMPRESSION | |
1829 | .Nm | |
1830 | supports both Predictor type 1 and deflate compression. | |
1831 | By default, | |
1832 | .Nm | |
1833 | will attempt to use (or be willing to accept) both compression protocols | |
1834 | when the peer agrees | |
1835 | (or requests them). | |
1836 | The deflate protocol is preferred by | |
1837 | .Nm . | |
1838 | Refer to the | |
1839 | .Dq disable | |
1840 | and | |
1841 | .Dq deny | |
1842 | commands if you wish to disable this functionality. | |
1843 | .Pp | |
1844 | It is possible to use a different compression algorithm in each direction | |
1845 | by using only one of | |
1846 | .Dq disable deflate | |
1847 | and | |
1848 | .Dq deny deflate | |
1849 | (assuming that the peer supports both algorithms). | |
1850 | .Pp | |
1851 | By default, when negotiating DEFLATE, | |
1852 | .Nm | |
1853 | will use a window size of 15. | |
1854 | Refer to the | |
1855 | .Dq set deflate | |
1856 | command if you wish to change this behaviour. | |
1857 | .Pp | |
1858 | A special algorithm called DEFLATE24 is also available, and is disabled | |
1859 | and denied by default. | |
1860 | This is exactly the same as DEFLATE except that | |
1861 | it uses CCP ID 24 to negotiate. | |
1862 | This allows | |
1863 | .Nm | |
1864 | to successfully negotiate DEFLATE with | |
1865 | .Nm pppd | |
1866 | version 2.3.*. | |
1867 | .Sh CONTROLLING IP ADDRESS | |
1868 | For IPv4, | |
1869 | .Nm | |
1870 | uses IPCP to negotiate IP addresses. | |
1871 | Each side of the connection | |
1872 | specifies the IP address that it's willing to use, and if the requested | |
1873 | IP address is acceptable then | |
1874 | .Nm | |
1875 | returns an ACK to the requester. | |
1876 | Otherwise, | |
1877 | .Nm | |
1878 | returns NAK to suggest that the peer use a different IP address. | |
1879 | When | |
1880 | both sides of the connection agree to accept the received request (and | |
1881 | send an ACK), IPCP is set to the open state and a network level connection | |
1882 | is established. | |
1883 | To control this IPCP behaviour, this implementation has the | |
1884 | .Dq set ifaddr | |
1885 | command for defining the local and remote IP address: | |
1886 | .Bd -ragged -offset indent | |
1887 | .No set ifaddr Oo Ar src_addr Ns | |
1888 | .Op / Ns Ar \&nn | |
1889 | .Oo Ar dst_addr Ns Op / Ns Ar \&nn | |
1890 | .Oo Ar netmask | |
1891 | .Op Ar trigger_addr | |
1892 | .Oc | |
1893 | .Oc | |
1894 | .Oc | |
1895 | .Ed | |
1896 | .Pp | |
1897 | where, | |
1898 | .Sq src_addr | |
1899 | is the IP address that the local side is willing to use, | |
1900 | .Sq dst_addr | |
1901 | is the IP address which the remote side should use and | |
1902 | .Sq netmask | |
1903 | is the netmask that should be used. | |
1904 | .Sq Src_addr | |
1905 | defaults to the current | |
1906 | .Xr hostname 1 , | |
1907 | .Sq dst_addr | |
1908 | defaults to 0.0.0.0, and | |
1909 | .Sq netmask | |
1910 | defaults to whatever mask is appropriate for | |
1911 | .Sq src_addr . | |
1912 | It is only possible to make | |
1913 | .Sq netmask | |
1914 | smaller than the default. | |
1915 | The usual value is 255.255.255.255, as | |
1916 | most kernels ignore the netmask of a POINTOPOINT interface. | |
1917 | .Pp | |
1918 | Some incorrect | |
1919 | .Em PPP | |
1920 | implementations require that the peer negotiates a specific IP | |
1921 | address instead of | |
1922 | .Sq src_addr . | |
1923 | If this is the case, | |
1924 | .Sq trigger_addr | |
1925 | may be used to specify this IP number. | |
1926 | This will not affect the | |
1927 | routing table unless the other side agrees with this proposed number. | |
1928 | .Bd -literal -offset indent | |
1929 | set ifaddr 192.244.177.38 192.244.177.2 255.255.255.255 0.0.0.0 | |
1930 | .Ed | |
1931 | .Pp | |
1932 | The above specification means: | |
1933 | .Pp | |
1934 | .Bl -bullet -compact | |
1935 | .It | |
1936 | I will first suggest that my IP address should be 0.0.0.0, but I | |
1937 | will only accept an address of 192.244.177.38. | |
1938 | .It | |
1939 | I strongly insist that the peer uses 192.244.177.2 as his own | |
1940 | address and won't permit the use of any IP address but 192.244.177.2. | |
1941 | When the peer requests another IP address, I will always suggest that | |
1942 | it uses 192.244.177.2. | |
1943 | .It | |
1944 | The routing table entry will have a netmask of 0xffffffff. | |
1945 | .El | |
1946 | .Pp | |
1947 | This is all fine when each side has a pre-determined IP address, however | |
1948 | it is often the case that one side is acting as a server which controls | |
1949 | all IP addresses and the other side should go along with it. | |
1950 | In order to allow more flexible behaviour, the | |
1951 | .Dq set ifaddr | |
1952 | command allows the user to specify IP addresses more loosely: | |
1953 | .Pp | |
1954 | .Dl set ifaddr 192.244.177.38/24 192.244.177.2/20 | |
1955 | .Pp | |
1956 | A number followed by a slash | |
1957 | .Pq Dq / | |
1958 | represents the number of bits significant in the IP address. | |
1959 | The above example means: | |
1960 | .Pp | |
1961 | .Bl -bullet -compact | |
1962 | .It | |
1963 | I'd like to use 192.244.177.38 as my address if it is possible, but I'll | |
1964 | also accept any IP address between 192.244.177.0 and 192.244.177.255. | |
1965 | .It | |
1966 | I'd like to make him use 192.244.177.2 as his own address, but I'll also | |
1967 | permit him to use any IP address between 192.244.176.0 and | |
1968 | 192.244.191.255. | |
1969 | .It | |
1970 | As you may have already noticed, 192.244.177.2 is equivalent to saying | |
1971 | 192.244.177.2/32. | |
1972 | .It | |
1973 | As an exception, 0 is equivalent to 0.0.0.0/0, meaning that I have no | |
1974 | preferred IP address and will obey the remote peers selection. | |
1975 | When using zero, no routing table entries will be made until a connection | |
1976 | is established. | |
1977 | .It | |
1978 | 192.244.177.2/0 means that I'll accept/permit any IP address but I'll | |
1979 | suggest that 192.244.177.2 be used first. | |
1980 | .El | |
1981 | .Pp | |
1982 | When negotiating IPv6 addresses, no control is given to the user. | |
1983 | IPV6CP negotiation is fully automatic. | |
1984 | .Sh CONNECTING WITH YOUR INTERNET SERVICE PROVIDER | |
1985 | The following steps should be taken when connecting to your ISP: | |
1986 | .Bl -enum | |
1987 | .It | |
1988 | Describe your providers phone number(s) in the dial script using the | |
1989 | .Dq set phone | |
1990 | command. | |
1991 | This command allows you to set multiple phone numbers for | |
1992 | dialing and redialing separated by either a pipe | |
1993 | .Pq Dq \&| | |
1994 | or a colon | |
1995 | .Pq Dq \&: : | |
1996 | .Bd -ragged -offset indent | |
1997 | .No set phone Ar telno Ns Xo | |
1998 | .Oo \&| Ns Ar backupnumber | |
1999 | .Oc Ns ... Ns Oo : Ns Ar nextnumber | |
2000 | .Oc Ns ... | |
2001 | .Xc | |
2002 | .Ed | |
2003 | .Pp | |
2004 | Numbers after the first in a pipe-separated list are only used if the | |
2005 | previous number was used in a failed dial or login script. | |
2006 | Numbers | |
2007 | separated by a colon are used sequentially, irrespective of what happened | |
2008 | as a result of using the previous number. | |
2009 | For example: | |
2010 | .Bd -literal -offset indent | |
2011 | set phone "1234567|2345678:3456789|4567890" | |
2012 | .Ed | |
2013 | .Pp | |
2014 | Here, the 1234567 number is attempted. | |
2015 | If the dial or login script fails, | |
2016 | the 2345678 number is used next time, but *only* if the dial or login script | |
2017 | fails. | |
2018 | On the dial after this, the 3456789 number is used. | |
2019 | The 4567890 | |
2020 | number is only used if the dial or login script using the 3456789 fails. | |
2021 | If the login script of the 2345678 number fails, the next number is still the | |
2022 | 3456789 number. | |
2023 | As many pipes and colons can be used as are necessary | |
2024 | (although a given site would usually prefer to use either the pipe or the | |
2025 | colon, but not both). | |
2026 | The next number redial timeout is used between all numbers. | |
2027 | When the end of the list is reached, the normal redial period is | |
2028 | used before starting at the beginning again. | |
2029 | The selected phone number is substituted for the \\\\T string in the | |
2030 | .Dq set dial | |
2031 | command (see below). | |
2032 | .It | |
2033 | Set up your redial requirements using | |
2034 | .Dq set redial . | |
2035 | For example, if you have a bad telephone line or your provider is | |
2036 | usually engaged (not so common these days), you may want to specify | |
2037 | the following: | |
2038 | .Bd -literal -offset indent | |
2039 | set redial 10 4 | |
2040 | .Ed | |
2041 | .Pp | |
2042 | This says that up to 4 phone calls should be attempted with a pause of 10 | |
2043 | seconds before dialing the first number again. | |
2044 | .It | |
2045 | Describe your login procedure using the | |
2046 | .Dq set dial | |
2047 | and | |
2048 | .Dq set login | |
2049 | commands. | |
2050 | The | |
2051 | .Dq set dial | |
2052 | command is used to talk to your modem and establish a link with your | |
2053 | ISP, for example: | |
2054 | .Bd -literal -offset indent | |
2055 | set dial "ABORT BUSY ABORT NO\\\\sCARRIER TIMEOUT 4 \\"\\" \e | |
2056 | ATZ OK-ATZ-OK ATDT\\\\T TIMEOUT 60 CONNECT" | |
2057 | .Ed | |
2058 | .Pp | |
2059 | This modem "chat" string means: | |
2060 | .Bl -bullet | |
2061 | .It | |
2062 | Abort if the string "BUSY" or "NO CARRIER" are received. | |
2063 | .It | |
2064 | Set the timeout to 4 seconds. | |
2065 | .It | |
2066 | Expect nothing. | |
2067 | .It | |
2068 | Send ATZ. | |
2069 | .It | |
2070 | Expect OK. | |
2071 | If that's not received within the 4 second timeout, send ATZ | |
2072 | and expect OK. | |
2073 | .It | |
2074 | Send ATDTxxxxxxx where xxxxxxx is the next number in the phone list from | |
2075 | above. | |
2076 | .It | |
2077 | Set the timeout to 60. | |
2078 | .It | |
2079 | Wait for the CONNECT string. | |
2080 | .El | |
2081 | .Pp | |
2082 | Once the connection is established, the login script is executed. | |
2083 | This script is written in the same style as the dial script, but care should | |
2084 | be taken to avoid having your password logged: | |
2085 | .Bd -literal -offset indent | |
2086 | set authkey MySecret | |
2087 | set login "TIMEOUT 15 login:-\\\\r-login: awfulhak \e | |
2088 | word: \\\\P ocol: PPP HELLO" | |
2089 | .Ed | |
2090 | .Pp | |
2091 | This login "chat" string means: | |
2092 | .Bl -bullet | |
2093 | .It | |
2094 | Set the timeout to 15 seconds. | |
2095 | .It | |
2096 | Expect "login:". | |
2097 | If it's not received, send a carriage return and expect | |
2098 | "login:" again. | |
2099 | .It | |
2100 | Send "awfulhak" | |
2101 | .It | |
2102 | Expect "word:" (the tail end of a "Password:" prompt). | |
2103 | .It | |
2104 | Send whatever our current | |
2105 | .Ar authkey | |
2106 | value is set to. | |
2107 | .It | |
2108 | Expect "ocol:" (the tail end of a "Protocol:" prompt). | |
2109 | .It | |
2110 | Send "PPP". | |
2111 | .It | |
2112 | Expect "HELLO". | |
2113 | .El | |
2114 | .Pp | |
2115 | The | |
2116 | .Dq set authkey | |
2117 | command is logged specially. | |
2118 | When | |
2119 | .Ar command | |
2120 | or | |
2121 | .Ar chat | |
2122 | logging is enabled, the actual password is not logged; | |
2123 | .Sq ******** | |
2124 | is logged instead. | |
2125 | .Pp | |
2126 | Login scripts vary greatly between ISPs. | |
2127 | If you're setting one up for the first time, | |
2128 | .Em ENABLE CHAT LOGGING | |
2129 | so that you can see if your script is behaving as you expect. | |
2130 | .It | |
2131 | Use | |
2132 | .Dq set device | |
2133 | and | |
2134 | .Dq set speed | |
2135 | to specify your serial line and speed, for example: | |
2136 | .Bd -literal -offset indent | |
2137 | set device /dev/cuaa0 | |
2138 | set speed 115200 | |
2139 | .Ed | |
2140 | .Pp | |
2141 | Cuaa0 is the first serial port on | |
9bb2a92d | 2142 | .Dx . |
984263bc MD |
2143 | If you're running |
2144 | .Nm | |
2145 | on | |
2146 | .Ox , | |
2147 | cua00 is the first. | |
2148 | A speed of 115200 should be specified | |
2149 | if you have a modem capable of bit rates of 28800 or more. | |
2150 | In general, the serial speed should be about four times the modem speed. | |
2151 | .It | |
2152 | Use the | |
2153 | .Dq set ifaddr | |
2154 | command to {define} the IP address. | |
2155 | .Bl -bullet | |
2156 | .It | |
2157 | If you know what IP address your provider uses, then use it as the remote | |
2158 | address (dst_addr), otherwise choose something like 10.0.0.2/0 (see below). | |
2159 | .It | |
2160 | If your provider has assigned a particular IP address to you, then use | |
2161 | it as your address (src_addr). | |
2162 | .It | |
2163 | If your provider assigns your address dynamically, choose a suitably | |
2164 | unobtrusive and unspecific IP number as your address. | |
2165 | 10.0.0.1/0 would be appropriate. | |
2166 | The bit after the / specifies how many bits of the | |
2167 | address you consider to be important, so if you wanted to insist on | |
2168 | something in the class C network 1.2.3.0, you could specify 1.2.3.1/24. | |
2169 | .It | |
2170 | If you find that your ISP accepts the first IP number that you suggest, | |
2171 | specify third and forth arguments of | |
2172 | .Dq 0.0.0.0 . | |
2173 | This will force your ISP to assign a number. | |
2174 | (The third argument will | |
2175 | be ignored as it is less restrictive than the default mask for your | |
2176 | .Sq src_addr ) . | |
2177 | .El | |
2178 | .Pp | |
2179 | An example for a connection where you don't know your IP number or your | |
2180 | ISPs IP number would be: | |
2181 | .Bd -literal -offset indent | |
2182 | set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0 | |
2183 | .Ed | |
984263bc MD |
2184 | .It |
2185 | In most cases, your ISP will also be your default router. | |
2186 | If this is the case, add the line | |
2187 | .Bd -literal -offset indent | |
2188 | add default HISADDR | |
2189 | .Ed | |
2190 | .Pp | |
2191 | to | |
2192 | .Pa /etc/ppp/ppp.conf | |
2193 | (or to | |
2194 | .Pa /etc/ppp/ppp.linkup | |
2195 | for setups that don't use | |
2196 | .Fl auto | |
2197 | mode). | |
2198 | .Pp | |
2199 | This tells | |
2200 | .Nm | |
2201 | to add a default route to whatever the peer address is | |
2202 | (10.0.0.2 in this example). | |
2203 | This route is | |
2204 | .Sq sticky , | |
2205 | meaning that should the value of | |
2206 | .Dv HISADDR | |
2207 | change, the route will be updated accordingly. | |
2208 | .It | |
2209 | If your provider requests that you use PAP/CHAP authentication methods, add | |
2210 | the next lines to your | |
2211 | .Pa /etc/ppp/ppp.conf | |
2212 | file: | |
2213 | .Bd -literal -offset indent | |
2214 | set authname MyName | |
2215 | set authkey MyPassword | |
2216 | .Ed | |
2217 | .Pp | |
2218 | Both are accepted by default, so | |
2219 | .Nm | |
2220 | will provide whatever your ISP requires. | |
2221 | .Pp | |
2222 | It should be noted that a login script is rarely (if ever) required | |
2223 | when PAP or CHAP are in use. | |
2224 | .It | |
2225 | Ask your ISP to authenticate your nameserver address(es) with the line | |
2226 | .Bd -literal -offset indent | |
2227 | enable dns | |
2228 | .Ed | |
2229 | .Pp | |
2230 | Do | |
2231 | .Em NOT | |
2232 | do this if you are running a local DNS unless you also either use | |
2233 | .Dq resolv readonly | |
2234 | or have | |
2235 | .Dq resolv restore | |
2236 | in | |
2237 | .Pa /etc/ppp/ppp.linkdown , | |
2238 | as | |
2239 | .Nm | |
2240 | will simply circumvent its use by entering some nameserver lines in | |
2241 | .Pa /etc/resolv.conf . | |
2242 | .El | |
2243 | .Pp | |
2244 | Please refer to | |
2245 | .Pa /usr/share/examples/ppp/ppp.conf.sample | |
2246 | and | |
2247 | .Pa /usr/share/examples/ppp/ppp.linkup.sample | |
2248 | for some real examples. | |
2249 | The pmdemand label should be appropriate for most ISPs. | |
2250 | .Sh LOGGING FACILITY | |
2251 | .Nm | |
2252 | is able to generate the following log info either via | |
2253 | .Xr syslog 3 | |
2254 | or directly to the screen: | |
2255 | .Pp | |
2256 | .Bl -tag -width XXXXXXXXX -offset XXX -compact | |
2257 | .It Li All | |
2258 | Enable all logging facilities. | |
2259 | This generates a lot of log. | |
2260 | The most common use of 'all' is as a basis, where you remove some facilities | |
2261 | after enabling 'all' ('debug' and 'timer' are usually best disabled.) | |
2262 | .It Li Async | |
2263 | Dump async level packet in hex. | |
2264 | .It Li CBCP | |
2265 | Generate CBCP (CallBack Control Protocol) logs. | |
2266 | .It Li CCP | |
2267 | Generate a CCP packet trace. | |
2268 | .It Li Chat | |
2269 | Generate | |
2270 | .Sq dial , | |
2271 | .Sq login , | |
2272 | .Sq logout | |
2273 | and | |
2274 | .Sq hangup | |
2275 | chat script trace logs. | |
2276 | .It Li Command | |
2277 | Log commands executed either from the command line or any of the configuration | |
2278 | files. | |
2279 | .It Li Connect | |
2280 | Log Chat lines containing the string "CONNECT". | |
2281 | .It Li Debug | |
2282 | Log debug information. | |
2283 | .It Li DNS | |
2284 | Log DNS QUERY packets. | |
2285 | .It Li Filter | |
2286 | Log packets permitted by the dial filter and denied by any filter. | |
2287 | .It Li HDLC | |
2288 | Dump HDLC packet in hex. | |
2289 | .It Li ID0 | |
2290 | Log all function calls specifically made as user id 0. | |
2291 | .It Li IPCP | |
2292 | Generate an IPCP packet trace. | |
2293 | .It Li LCP | |
2294 | Generate an LCP packet trace. | |
2295 | .It Li LQM | |
2296 | Generate LQR reports. | |
2297 | .It Li Phase | |
2298 | Phase transition log output. | |
2299 | .It Li Physical | |
2300 | Dump physical level packet in hex. | |
2301 | .It Li Sync | |
2302 | Dump sync level packet in hex. | |
2303 | .It Li TCP/IP | |
2304 | Dump all TCP/IP packets. | |
2305 | .It Li Timer | |
2306 | Log timer manipulation. | |
2307 | .It Li TUN | |
2308 | Include the tun device on each log line. | |
2309 | .It Li Warning | |
2310 | Output to the terminal device. | |
2311 | If there is currently no terminal, | |
2312 | output is sent to the log file using syslogs | |
2313 | .Dv LOG_WARNING . | |
2314 | .It Li Error | |
2315 | Output to both the terminal device | |
2316 | and the log file using syslogs | |
2317 | .Dv LOG_ERROR . | |
2318 | .It Li Alert | |
2319 | Output to the log file using | |
2320 | .Dv LOG_ALERT . | |
2321 | .El | |
2322 | .Pp | |
2323 | The | |
2324 | .Dq set log | |
2325 | command allows you to set the logging output level. | |
2326 | Multiple levels can be specified on a single command line. | |
2327 | The default is equivalent to | |
2328 | .Dq set log Phase . | |
2329 | .Pp | |
2330 | It is also possible to log directly to the screen. | |
2331 | The syntax is the same except that the word | |
2332 | .Dq local | |
2333 | should immediately follow | |
2334 | .Dq set log . | |
2335 | The default is | |
2336 | .Dq set log local | |
2337 | (i.e., only the un-maskable warning, error and alert output). | |
2338 | .Pp | |
2339 | If The first argument to | |
2340 | .Dq set log Op local | |
2341 | begins with a | |
2342 | .Sq + | |
2343 | or a | |
2344 | .Sq - | |
2345 | character, the current log levels are | |
2346 | not cleared, for example: | |
2347 | .Bd -literal -offset indent | |
2348 | PPP ON awfulhak> set log phase | |
2349 | PPP ON awfulhak> show log | |
2350 | Log: Phase Warning Error Alert | |
2351 | Local: Warning Error Alert | |
2352 | PPP ON awfulhak> set log +tcp/ip -warning | |
2353 | PPP ON awfulhak> set log local +command | |
2354 | PPP ON awfulhak> show log | |
2355 | Log: Phase TCP/IP Warning Error Alert | |
2356 | Local: Command Warning Error Alert | |
2357 | .Ed | |
2358 | .Pp | |
2359 | Log messages of level Warning, Error and Alert are not controllable | |
2360 | using | |
2361 | .Dq set log Op local . | |
2362 | .Pp | |
2363 | The | |
2364 | .Ar Warning | |
2365 | level is special in that it will not be logged if it can be displayed | |
2366 | locally. | |
2367 | .Sh SIGNAL HANDLING | |
2368 | .Nm | |
2369 | deals with the following signals: | |
2370 | .Bl -tag -width "USR2" | |
2371 | .It INT | |
2372 | Receipt of this signal causes the termination of the current connection | |
2373 | (if any). | |
2374 | This will cause | |
2375 | .Nm | |
2376 | to exit unless it is in | |
2377 | .Fl auto | |
2378 | or | |
2379 | .Fl ddial | |
2380 | mode. | |
2381 | .It HUP, TERM & QUIT | |
2382 | These signals tell | |
2383 | .Nm | |
2384 | to exit. | |
2385 | .It USR1 | |
2386 | This signal, tells | |
2387 | .Nm | |
2388 | to re-open any existing server socket, dropping all existing diagnostic | |
2389 | connections. | |
2390 | Sockets that couldn't previously be opened will be retried. | |
2391 | .It USR2 | |
2392 | This signal, tells | |
2393 | .Nm | |
2394 | to close any existing server socket, dropping all existing diagnostic | |
2395 | connections. | |
2396 | .Dv SIGUSR1 | |
2397 | can still be used to re-open the socket. | |
2398 | .El | |
2399 | .Sh MULTI-LINK PPP | |
2400 | If you wish to use more than one physical link to connect to a | |
2401 | .Em PPP | |
2402 | peer, that peer must also understand the | |
2403 | .Em MULTI-LINK PPP | |
2404 | protocol. | |
2405 | Refer to RFC 1990 for specification details. | |
2406 | .Pp | |
2407 | The peer is identified using a combination of his | |
2408 | .Dq endpoint discriminator | |
2409 | and his | |
2410 | .Dq authentication id . | |
2411 | Either or both of these may be specified. | |
2412 | It is recommended that | |
2413 | at least one is specified, otherwise there is no way of ensuring that | |
2414 | all links are actually connected to the same peer program, and some | |
2415 | confusing lock-ups may result. | |
2416 | Locally, these identification variables are specified using the | |
2417 | .Dq set enddisc | |
2418 | and | |
2419 | .Dq set authname | |
2420 | commands. | |
2421 | The | |
2422 | .Sq authname | |
2423 | (and | |
2424 | .Sq authkey ) | |
2425 | must be agreed in advance with the peer. | |
2426 | .Pp | |
2427 | Multi-link capabilities are enabled using the | |
2428 | .Dq set mrru | |
2429 | command (set maximum reconstructed receive unit). | |
2430 | Once multi-link is enabled, | |
2431 | .Nm | |
2432 | will attempt to negotiate a multi-link connection with the peer. | |
2433 | .Pp | |
2434 | By default, only one | |
2435 | .Sq link | |
2436 | is available | |
2437 | (called | |
2438 | .Sq deflink ) . | |
2439 | To create more links, the | |
2440 | .Dq clone | |
2441 | command is used. | |
2442 | This command will clone existing links, where all | |
2443 | characteristics are the same except: | |
2444 | .Bl -enum | |
2445 | .It | |
2446 | The new link has its own name as specified on the | |
2447 | .Dq clone | |
2448 | command line. | |
2449 | .It | |
2450 | The new link is an | |
2451 | .Sq interactive | |
2452 | link. | |
2453 | Its mode may subsequently be changed using the | |
2454 | .Dq set mode | |
2455 | command. | |
2456 | .It | |
2457 | The new link is in a | |
2458 | .Sq closed | |
2459 | state. | |
2460 | .El | |
2461 | .Pp | |
2462 | A summary of all available links can be seen using the | |
2463 | .Dq show links | |
2464 | command. | |
2465 | .Pp | |
2466 | Once a new link has been created, command usage varies. | |
2467 | All link specific commands must be prefixed with the | |
2468 | .Dq link Ar name | |
2469 | command, specifying on which link the command is to be applied. | |
2470 | When only a single link is available, | |
2471 | .Nm | |
2472 | is smart enough not to require the | |
2473 | .Dq link Ar name | |
2474 | prefix. | |
2475 | .Pp | |
2476 | Some commands can still be used without specifying a link - resulting | |
2477 | in an operation at the | |
2478 | .Sq bundle | |
2479 | level. | |
2480 | For example, once two or more links are available, the command | |
2481 | .Dq show ccp | |
2482 | will show CCP configuration and statistics at the multi-link level, and | |
2483 | .Dq link deflink show ccp | |
2484 | will show the same information at the | |
2485 | .Dq deflink | |
2486 | link level. | |
2487 | .Pp | |
2488 | Armed with this information, the following configuration might be used: | |
984263bc MD |
2489 | .Bd -literal -offset indent |
2490 | mp: | |
2491 | set timeout 0 | |
2492 | set log phase chat | |
2493 | set device /dev/cuaa0 /dev/cuaa1 /dev/cuaa2 | |
2494 | set phone "123456789" | |
2495 | set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \\"\\" ATZ \e | |
2496 | OK-AT-OK \\\\dATDT\\\\T TIMEOUT 45 CONNECT" | |
2497 | set login | |
2498 | set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0 | |
2499 | set authname ppp | |
2500 | set authkey ppppassword | |
2501 | ||
2502 | set mrru 1500 | |
2503 | clone 1,2,3 # Create 3 new links - duplicates of the default | |
2504 | link deflink remove # Delete the default link (called ``deflink'') | |
2505 | .Ed | |
2506 | .Pp | |
2507 | Note how all cloning is done at the end of the configuration. | |
2508 | Usually, the link will be configured first, then cloned. | |
2509 | If you wish all links | |
2510 | to be up all the time, you can add the following line to the end of your | |
2511 | configuration. | |
984263bc MD |
2512 | .Bd -literal -offset indent |
2513 | link 1,2,3 set mode ddial | |
2514 | .Ed | |
2515 | .Pp | |
2516 | If you want the links to dial on demand, this command could be used: | |
984263bc MD |
2517 | .Bd -literal -offset indent |
2518 | link * set mode auto | |
2519 | .Ed | |
2520 | .Pp | |
2521 | Links may be tied to specific names by removing the | |
2522 | .Dq set device | |
2523 | line above, and specifying the following after the | |
2524 | .Dq clone | |
2525 | command: | |
984263bc MD |
2526 | .Bd -literal -offset indent |
2527 | link 1 set device /dev/cuaa0 | |
2528 | link 2 set device /dev/cuaa1 | |
2529 | link 3 set device /dev/cuaa2 | |
2530 | .Ed | |
2531 | .Pp | |
2532 | Use the | |
2533 | .Dq help | |
2534 | command to see which commands require context (using the | |
2535 | .Dq link | |
2536 | command), which have optional | |
2537 | context and which should not have any context. | |
2538 | .Pp | |
2539 | When | |
2540 | .Nm | |
2541 | has negotiated | |
2542 | .Em MULTI-LINK | |
2543 | mode with the peer, it creates a local domain socket in the | |
2544 | .Pa /var/run | |
2545 | directory. | |
2546 | This socket is used to pass link information (including | |
2547 | the actual link file descriptor) between different | |
2548 | .Nm | |
2549 | invocations. | |
2550 | This facilitates | |
2551 | .Nm Ns No 's | |
2552 | ability to be run from a | |
2553 | .Xr getty 8 | |
2554 | or directly from | |
2555 | .Pa /etc/gettydefs | |
2556 | (using the | |
2557 | .Sq pp= | |
2558 | capability), without needing to have initial control of the serial | |
2559 | line. | |
2560 | Once | |
2561 | .Nm | |
2562 | negotiates multi-link mode, it will pass its open link to any | |
2563 | already running process. | |
2564 | If there is no already running process, | |
2565 | .Nm | |
2566 | will act as the master, creating the socket and listening for new | |
2567 | connections. | |
2568 | .Sh PPP COMMAND LIST | |
2569 | This section lists the available commands and their effect. | |
2570 | They are usable either from an interactive | |
2571 | .Nm | |
2572 | session, from a configuration file or from a | |
2573 | .Xr pppctl 8 | |
2574 | or | |
2575 | .Xr telnet 1 | |
2576 | session. | |
2577 | .Bl -tag -width 2n | |
2578 | .It accept|deny|enable|disable Ar option.... | |
2579 | These directives tell | |
2580 | .Nm | |
2581 | how to negotiate the initial connection with the peer. | |
2582 | Each | |
2583 | .Dq option | |
2584 | has a default of either accept or deny and enable or disable. | |
2585 | .Dq Accept | |
2586 | means that the option will be ACK'd if the peer asks for it. | |
2587 | .Dq Deny | |
2588 | means that the option will be NAK'd if the peer asks for it. | |
2589 | .Dq Enable | |
2590 | means that the option will be requested by us. | |
2591 | .Dq Disable | |
2592 | means that the option will not be requested by us. | |
2593 | .Pp | |
2594 | .Dq Option | |
2595 | may be one of the following: | |
2596 | .Bl -tag -width 2n | |
2597 | .It acfcomp | |
2598 | Default: Enabled and Accepted. | |
2599 | ACFComp stands for Address and Control Field Compression. | |
2600 | Non LCP packets will usually have an address | |
2601 | field of 0xff (the All-Stations address) and a control field of | |
2602 | 0x03 (the Unnumbered Information command). | |
2603 | If this option is | |
2604 | negotiated, these two bytes are simply not sent, thus minimising | |
2605 | traffic. | |
2606 | .Pp | |
2607 | See | |
2608 | .Pa rfc1662 | |
2609 | for details. | |
2610 | .It chap Ns Op \&05 | |
2611 | Default: Disabled and Accepted. | |
2612 | CHAP stands for Challenge Handshake Authentication Protocol. | |
2613 | Only one of CHAP and PAP (below) may be negotiated. | |
2614 | With CHAP, the authenticator sends a "challenge" message to its peer. | |
2615 | The peer uses a one-way hash function to encrypt the | |
2616 | challenge and sends the result back. | |
2617 | The authenticator does the same, and compares the results. | |
2618 | The advantage of this mechanism is that no | |
2619 | passwords are sent across the connection. | |
2620 | A challenge is made when the connection is first made. | |
2621 | Subsequent challenges may occur. | |
2622 | If you want to have your peer authenticate itself, you must | |
2623 | .Dq enable chap . | |
2624 | in | |
2625 | .Pa /etc/ppp/ppp.conf , | |
2626 | and have an entry in | |
2627 | .Pa /etc/ppp/ppp.secret | |
2628 | for the peer. | |
2629 | .Pp | |
2630 | When using CHAP as the client, you need only specify | |
2631 | .Dq AuthName | |
2632 | and | |
2633 | .Dq AuthKey | |
2634 | in | |
2635 | .Pa /etc/ppp/ppp.conf . | |
2636 | CHAP is accepted by default. | |
2637 | Some | |
2638 | .Em PPP | |
2639 | implementations use "MS-CHAP" rather than MD5 when encrypting the | |
2640 | challenge. | |
2641 | MS-CHAP is a combination of MD4 and DES. | |
2642 | If | |
2643 | .Nm | |
2644 | was built on a machine with DES libraries available, it will respond | |
2645 | to MS-CHAP authentication requests, but will never request them. | |
2646 | .It deflate | |
2647 | Default: Enabled and Accepted. | |
2648 | This option decides if deflate | |
2649 | compression will be used by the Compression Control Protocol (CCP). | |
2650 | This is the same algorithm as used by the | |
2651 | .Xr gzip 1 | |
2652 | program. | |
2653 | Note: There is a problem negotiating | |
2654 | .Ar deflate | |
2655 | capabilities with | |
d9d67b59 | 2656 | .Nm pppd |
984263bc MD |
2657 | - a |
2658 | .Em PPP | |
2659 | implementation available under many operating systems. | |
2660 | .Nm pppd | |
2661 | (version 2.3.1) incorrectly attempts to negotiate | |
2662 | .Ar deflate | |
2663 | compression using type | |
2664 | .Em 24 | |
2665 | as the CCP configuration type rather than type | |
2666 | .Em 26 | |
2667 | as specified in | |
2668 | .Pa rfc1979 . | |
2669 | Type | |
2670 | .Ar 24 | |
2671 | is actually specified as | |
2672 | .Dq PPP Magna-link Variable Resource Compression | |
2673 | in | |
2674 | .Pa rfc1975 ! | |
2675 | .Nm | |
2676 | is capable of negotiating with | |
2677 | .Nm pppd , | |
2678 | but only if | |
2679 | .Dq deflate24 | |
2680 | is | |
2681 | .Ar enable Ns No d | |
2682 | and | |
2683 | .Ar accept Ns No ed . | |
2684 | .It deflate24 | |
2685 | Default: Disabled and Denied. | |
2686 | This is a variance of the | |
2687 | .Ar deflate | |
2688 | option, allowing negotiation with the | |
d9d67b59 | 2689 | .Nm pppd |
984263bc MD |
2690 | program. |
2691 | Refer to the | |
2692 | .Ar deflate | |
2693 | section above for details. | |
2694 | It is disabled by default as it violates | |
2695 | .Pa rfc1975 . | |
2696 | .It dns | |
2697 | Default: Disabled and Denied. | |
2698 | This option allows DNS negotiation. | |
2699 | .Pp | |
2700 | If | |
2701 | .Dq enable Ns No d, | |
2702 | .Nm | |
2703 | will request that the peer confirms the entries in | |
2704 | .Pa /etc/resolv.conf . | |
2705 | If the peer NAKs our request (suggesting new IP numbers), | |
2706 | .Pa /etc/resolv.conf | |
2707 | is updated and another request is sent to confirm the new entries. | |
2708 | .Pp | |
2709 | If | |
2710 | .Dq accept Ns No ed, | |
2711 | .Nm | |
2712 | will answer any DNS queries requested by the peer rather than rejecting | |
2713 | them. | |
2714 | The answer is taken from | |
2715 | .Pa /etc/resolv.conf | |
2716 | unless the | |
2717 | .Dq set dns | |
2718 | command is used as an override. | |
2719 | .It enddisc | |
2720 | Default: Enabled and Accepted. | |
2721 | This option allows control over whether we | |
2722 | negotiate an endpoint discriminator. | |
2723 | We only send our discriminator if | |
2724 | .Dq set enddisc | |
2725 | is used and | |
2726 | .Ar enddisc | |
2727 | is enabled. | |
2728 | We reject the peers discriminator if | |
2729 | .Ar enddisc | |
2730 | is denied. | |
2731 | .It LANMan|chap80lm | |
2732 | Default: Disabled and Accepted. | |
2733 | The use of this authentication protocol | |
2734 | is discouraged as it partially violates the authentication protocol by | |
2735 | implementing two different mechanisms (LANMan & NT) under the guise of | |
2736 | a single CHAP type (0x80). | |
2737 | .Dq LANMan | |
2738 | uses a simple DES encryption mechanism and is the least secure of the | |
2739 | CHAP alternatives (although is still more secure than PAP). | |
2740 | .Pp | |
2741 | Refer to the | |
2742 | .Dq MSChap | |
2743 | description below for more details. | |
2744 | .It lqr | |
2745 | Default: Disabled and Accepted. | |
2746 | This option decides if Link Quality Requests will be sent or accepted. | |
2747 | LQR is a protocol that allows | |
2748 | .Nm | |
2749 | to determine that the link is down without relying on the modems | |
2750 | carrier detect. | |
2751 | When LQR is enabled, | |
2752 | .Nm | |
2753 | sends the | |
2754 | .Em QUALPROTO | |
2755 | option (see | |
2756 | .Dq set lqrperiod | |
2757 | below) as part of the LCP request. | |
2758 | If the peer agrees, both sides will | |
2759 | exchange LQR packets at the agreed frequency, allowing detailed link | |
2760 | quality monitoring by enabling LQM logging. | |
2761 | If the peer doesn't agree, | |
2762 | .Nm | |
2763 | will send ECHO LQR requests instead. | |
2764 | These packets pass no information of interest, but they | |
2765 | .Em MUST | |
2766 | be replied to by the peer. | |
2767 | .Pp | |
2768 | Whether using LQR or ECHO LQR, | |
2769 | .Nm | |
2770 | will abruptly drop the connection if 5 unacknowledged packets have been | |
2771 | sent rather than sending a 6th. | |
2772 | A message is logged at the | |
2773 | .Em PHASE | |
2774 | level, and any appropriate | |
2775 | .Dq reconnect | |
2776 | values are honoured as if the peer were responsible for dropping the | |
2777 | connection. | |
2778 | .It mppe | |
2779 | Default: Enabled and Accepted. | |
2780 | This is Microsoft Point to Point Encryption scheme. | |
2781 | MPPE key size can be | |
2782 | 40-, 56- and 128-bits. | |
2783 | Refer to | |
2784 | .Dq set mppe | |
2785 | command. | |
2786 | .It MSChapV2|chap81 | |
2787 | Default: Disabled and Accepted. | |
2788 | It is very similar to standard CHAP (type 0x05) | |
2789 | except that it issues challenges of a fixed 16 bytes in length and uses a | |
2790 | combination of MD4, SHA-1 and DES to encrypt the challenge rather than using the | |
2791 | standard MD5 mechanism. | |
2792 | .It MSChap|chap80nt | |
2793 | Default: Disabled and Accepted. | |
2794 | The use of this authentication protocol | |
2795 | is discouraged as it partially violates the authentication protocol by | |
2796 | implementing two different mechanisms (LANMan & NT) under the guise of | |
2797 | a single CHAP type (0x80). | |
2798 | It is very similar to standard CHAP (type 0x05) | |
2799 | except that it issues challenges of a fixed 8 bytes in length and uses a | |
2800 | combination of MD4 and DES to encrypt the challenge rather than using the | |
2801 | standard MD5 mechanism. | |
2802 | CHAP type 0x80 for LANMan is also supported - see | |
2803 | .Dq enable LANMan | |
2804 | for details. | |
2805 | .Pp | |
2806 | Because both | |
2807 | .Dq LANMan | |
2808 | and | |
2809 | .Dq NT | |
2810 | use CHAP type 0x80, when acting as authenticator with both | |
2811 | .Dq enable Ns No d , | |
2812 | .Nm | |
2813 | will rechallenge the peer up to three times if it responds using the wrong | |
2814 | one of the two protocols. | |
2815 | This gives the peer a chance to attempt using both protocols. | |
2816 | .Pp | |
2817 | Conversely, when | |
2818 | .Nm | |
2819 | acts as the authenticatee with both protocols | |
2820 | .Dq accept Ns No ed , | |
2821 | the protocols are used alternately in response to challenges. | |
2822 | .Pp | |
2823 | Note: If only LANMan is enabled, | |
d9d67b59 | 2824 | .Nm pppd |
984263bc MD |
2825 | (version 2.3.5) misbehaves when acting as authenticatee. |
2826 | It provides both | |
2827 | the NT and the LANMan answers, but also suggests that only the NT answer | |
2828 | should be used. | |
2829 | .It pap | |
2830 | Default: Disabled and Accepted. | |
2831 | PAP stands for Password Authentication Protocol. | |
2832 | Only one of PAP and CHAP (above) may be negotiated. | |
2833 | With PAP, the ID and Password are sent repeatedly to the peer until | |
2834 | authentication is acknowledged or the connection is terminated. | |
2835 | This is a rather poor security mechanism. | |
2836 | It is only performed when the connection is first established. | |
2837 | If you want to have your peer authenticate itself, you must | |
2838 | .Dq enable pap . | |
2839 | in | |
2840 | .Pa /etc/ppp/ppp.conf , | |
2841 | and have an entry in | |
2842 | .Pa /etc/ppp/ppp.secret | |
2843 | for the peer (although see the | |
2844 | .Dq passwdauth | |
2845 | and | |
2846 | .Dq set radius | |
2847 | options below). | |
2848 | .Pp | |
2849 | When using PAP as the client, you need only specify | |
2850 | .Dq AuthName | |
2851 | and | |
2852 | .Dq AuthKey | |
2853 | in | |
2854 | .Pa /etc/ppp/ppp.conf . | |
2855 | PAP is accepted by default. | |
2856 | .It pred1 | |
2857 | Default: Enabled and Accepted. | |
2858 | This option decides if Predictor 1 | |
2859 | compression will be used by the Compression Control Protocol (CCP). | |
2860 | .It protocomp | |
2861 | Default: Enabled and Accepted. | |
2862 | This option is used to negotiate | |
2863 | PFC (Protocol Field Compression), a mechanism where the protocol | |
2864 | field number is reduced to one octet rather than two. | |
2865 | .It shortseq | |
2866 | Default: Enabled and Accepted. | |
2867 | This option determines if | |
2868 | .Nm | |
2869 | will request and accept requests for short | |
2870 | (12 bit) | |
2871 | sequence numbers when negotiating multi-link mode. | |
2872 | This is only applicable if our MRRU is set (thus enabling multi-link). | |
2873 | .It vjcomp | |
2874 | Default: Enabled and Accepted. | |
2875 | This option determines if Van Jacobson header compression will be used. | |
2876 | .El | |
2877 | .Pp | |
2878 | The following options are not actually negotiated with the peer. | |
2879 | Therefore, accepting or denying them makes no sense. | |
2880 | .Bl -tag -width 2n | |
2881 | .It filter-decapsulation | |
2882 | Default: Disabled. | |
2883 | When this option is enabled, | |
2884 | .Nm | |
2885 | will examine UDP frames to see if they actually contain a | |
2886 | .Em PPP | |
2887 | frame as their payload. | |
2888 | If this is the case, all filters will operate on the payload rather | |
2889 | than the actual packet. | |
2890 | .Pp | |
2891 | This is useful if you want to send PPPoUDP traffic over a | |
2892 | .Em PPP | |
2893 | link, but want that link to do smart things with the real data rather than | |
2894 | the UDP wrapper. | |
2895 | .Pp | |
2896 | The UDP frame payload must not be compressed in any way, otherwise | |
2897 | .Nm | |
2898 | will not be able to interpret it. | |
2899 | It's therefore recommended that you | |
2900 | .Ic disable vj pred1 deflate | |
2901 | and | |
2902 | .Ic deny vj pred1 deflate | |
2903 | in the configuration for the | |
2904 | .Nm | |
2905 | invocation with the udp link. | |
2906 | .It idcheck | |
2907 | Default: Enabled. | |
2908 | When | |
2909 | .Nm | |
2910 | exchanges low-level LCP, CCP and IPCP configuration traffic, the | |
2911 | .Em Identifier | |
2912 | field of any replies is expected to be the same as that of the request. | |
2913 | By default, | |
2914 | .Nm | |
2915 | drops any reply packets that do not contain the expected identifier | |
2916 | field, reporting the fact at the respective log level. | |
2917 | If | |
2918 | .Ar idcheck | |
2919 | is disabled, | |
2920 | .Nm | |
2921 | will ignore the identifier field. | |
2922 | .It iface-alias | |
2923 | Default: Enabled if | |
2924 | .Fl nat | |
2925 | is specified. | |
2926 | This option simply tells | |
2927 | .Nm | |
2928 | to add new interface addresses to the interface rather than replacing them. | |
2929 | The option can only be enabled if network address translation is enabled | |
2930 | .Pq Dq nat enable yes . | |
2931 | .Pp | |
2932 | With this option enabled, | |
2933 | .Nm | |
2934 | will pass traffic for old interface addresses through the NAT | |
2935 | ifdef({LOCALNAT},{engine,},{engine | |
2936 | (see | |
2937 | .Xr libalias 3 ) ,}) | |
2938 | resulting in the ability (in | |
2939 | .Fl auto | |
2940 | mode) to properly connect the process that caused the PPP link to | |
2941 | come up in the first place. | |
2942 | .Pp | |
2943 | Disabling NAT with | |
2944 | .Dq nat enable no | |
2945 | will also disable | |
2946 | .Sq iface-alias . | |
2947 | .It ipcp | |
2948 | Default: Enabled. | |
2949 | This option allows | |
2950 | .Nm | |
2951 | to attempt to negotiate IP control protocol capabilities and if | |
2952 | successful to exchange IP datagrams with the peer. | |
2953 | .It ipv6cp | |
2954 | Default: Enabled. | |
2955 | This option allows | |
2956 | .Nm | |
2957 | to attempt to negotiate IPv6 control protocol capabilities and if | |
2958 | successful to exchange IPv6 datagrams with the peer. | |
2959 | .It keep-session | |
2960 | Default: Disabled. | |
2961 | When | |
2962 | .Nm | |
2963 | runs as a Multi-link server, a different | |
2964 | .Nm | |
2965 | instance initially receives each connection. | |
2966 | After determining that | |
2967 | the link belongs to an already existing bundle (controlled by another | |
2968 | .Nm | |
2969 | invocation), | |
2970 | .Nm | |
2971 | will transfer the link to that process. | |
2972 | .Pp | |
2973 | If the link is a tty device or if this option is enabled, | |
2974 | .Nm | |
2975 | will not exit, but will change its process name to | |
2976 | .Dq session owner | |
2977 | and wait for the controlling | |
2978 | .Nm | |
2979 | to finish with the link and deliver a signal back to the idle process. | |
2980 | This prevents the confusion that results from | |
2981 | .Nm Ns No 's | |
2982 | parent considering the link resource available again. | |
2983 | .Pp | |
2984 | For tty devices that have entries in | |
2985 | .Pa /etc/ttys , | |
2986 | this is necessary to prevent another | |
2987 | .Xr getty 8 | |
2988 | from being started, and for program links such as | |
2989 | .Xr sshd 8 , | |
2990 | it prevents | |
2991 | .Xr sshd 8 | |
2992 | from exiting due to the death of its child. | |
2993 | As | |
2994 | .Nm | |
2995 | cannot determine its parents requirements (except for the tty case), this | |
2996 | option must be enabled manually depending on the circumstances. | |
2997 | .It loopback | |
2998 | Default: Enabled. | |
2999 | When | |
3000 | .Ar loopback | |
3001 | is enabled, | |
3002 | .Nm | |
3003 | will automatically loop back packets being sent | |
3004 | out with a destination address equal to that of the | |
3005 | .Em PPP | |
3006 | interface. | |
3007 | If disabled, | |
3008 | .Nm | |
3009 | will send the packet, probably resulting in an ICMP redirect from | |
3010 | the other end. | |
3011 | It is convenient to have this option enabled when | |
3012 | the interface is also the default route as it avoids the necessity | |
3013 | of a loopback route. | |
3014 | .It passwdauth | |
3015 | Default: Disabled. | |
3016 | Enabling this option will tell the PAP authentication | |
3017 | code to use the password database (see | |
3018 | .Xr passwd 5 ) | |
3019 | to authenticate the caller if they cannot be found in the | |
3020 | .Pa /etc/ppp/ppp.secret | |
3021 | file. | |
3022 | .Pa /etc/ppp/ppp.secret | |
3023 | is always checked first. | |
3024 | If you wish to use passwords from | |
3025 | .Xr passwd 5 , | |
3026 | but also to specify an IP number or label for a given client, use | |
3027 | .Dq \&* | |
3028 | as the client password in | |
3029 | .Pa /etc/ppp/ppp.secret . | |
3030 | .It proxy | |
3031 | Default: Disabled. | |
3032 | Enabling this option will tell | |
3033 | .Nm | |
3034 | to proxy ARP for the peer. | |
3035 | This means that | |
3036 | .Nm | |
3037 | will make an entry in the ARP table using | |
3038 | .Dv HISADDR | |
3039 | and the | |
3040 | .Dv MAC | |
3041 | address of the local network in which | |
3042 | .Dv HISADDR | |
3043 | appears. | |
3f5e28f4 | 3044 | This allows other machines connected to the LAN to talk to |
984263bc MD |
3045 | the peer as if the peer itself was connected to the LAN. |
3046 | The proxy entry cannot be made unless | |
3047 | .Dv HISADDR | |
3048 | is an address from a LAN. | |
3049 | .It proxyall | |
3050 | Default: Disabled. | |
3051 | Enabling this will tell | |
3052 | .Nm | |
3053 | to add proxy arp entries for every IP address in all class C or | |
3054 | smaller subnets routed via the tun interface. | |
3055 | .Pp | |
3056 | Proxy arp entries are only made for sticky routes that are added | |
3057 | using the | |
3058 | .Dq add | |
3059 | command. | |
3060 | No proxy arp entries are made for the interface address itself | |
3061 | (as created by the | |
3062 | .Dq set ifaddr | |
3063 | command). | |
3064 | .It sroutes | |
3065 | Default: Enabled. | |
3066 | When the | |
3067 | .Dq add | |
3068 | command is used with the | |
3069 | .Dv HISADDR , | |
3070 | .Dv MYADDR , | |
3071 | .Dv HISADDR6 | |
3072 | or | |
3073 | .Dv MYADDR6 | |
3074 | values, entries are stored in the | |
3075 | .Sq sticky route | |
3076 | list. | |
3077 | Each time these variables change, this list is re-applied to the routing table. | |
3078 | .Pp | |
3079 | Disabling this option will prevent the re-application of sticky routes, | |
3080 | although the | |
3081 | .Sq stick route | |
3082 | list will still be maintained. | |
bc536631 | 3083 | .It Oo tcp Oc Ns Xo |
984263bc MD |
3084 | .No mssfixup |
3085 | .Xc | |
3086 | Default: Enabled. | |
3087 | This option tells | |
3088 | .Nm | |
3089 | to adjust TCP SYN packets so that the maximum receive segment | |
3090 | size is not greater than the amount allowed by the interface MTU. | |
3091 | .It throughput | |
3092 | Default: Enabled. | |
3093 | This option tells | |
3094 | .Nm | |
3095 | to gather throughput statistics. | |
3096 | Input and output is sampled over | |
3097 | a rolling 5 second window, and current, best and total figures are retained. | |
3098 | This data is output when the relevant | |
3099 | .Em PPP | |
3100 | layer shuts down, and is also available using the | |
3101 | .Dq show | |
3102 | command. | |
3103 | Throughput statistics are available at the | |
3104 | .Dq IPCP | |
3105 | and | |
3106 | .Dq physical | |
3107 | levels. | |
3108 | .It utmp | |
3109 | Default: Enabled. | |
3110 | Normally, when a user is authenticated using PAP or CHAP, and when | |
3111 | .Nm | |
3112 | is running in | |
3113 | .Fl direct | |
25606b42 | 3114 | mode, an entry is made in the utmpx and wtmpx files for that user. |
984263bc MD |
3115 | Disabling this option will tell |
3116 | .Nm | |
25606b42 | 3117 | not to make any utmpx or wtmpx entries. |
984263bc MD |
3118 | This is usually only necessary if |
3119 | you require the user to both login and authenticate themselves. | |
3120 | .El | |
984263bc MD |
3121 | .It add Ns Xo |
3122 | .Op !\& | |
3123 | .Ar dest Ns Op / Ns Ar nn | |
3124 | .Op Ar mask | |
3125 | .Op Ar gateway | |
3126 | .Xc | |
3127 | .Ar Dest | |
3128 | is the destination IP address. | |
3129 | The netmask is specified either as a number of bits with | |
3130 | .Ar /nn | |
3131 | or as an IP number using | |
3132 | .Ar mask . | |
3133 | .Ar 0 0 | |
3134 | or simply | |
3135 | .Ar 0 | |
3136 | with no mask refers to the default route. | |
3137 | It is also possible to use the literal name | |
3138 | .Sq default | |
3139 | instead of | |
3140 | .Ar 0 . | |
3141 | .Ar Gateway | |
3142 | is the next hop gateway to get to the given | |
3143 | .Ar dest | |
3144 | machine/network. | |
3145 | Refer to the | |
3146 | .Xr route 8 | |
3147 | command for further details. | |
3148 | .Pp | |
3149 | It is possible to use the symbolic names | |
3150 | .Sq MYADDR , | |
3151 | .Sq HISADDR , | |
3152 | .Sq MYADDR6 | |
3153 | or | |
3154 | .Sq HISADDR6 | |
3155 | as the destination, and | |
3156 | .Sq HISADDR | |
3157 | or | |
3158 | .Sq HISADDR6 | |
3159 | as the | |
3160 | .Ar gateway . | |
3161 | .Sq MYADDR | |
3162 | is replaced with the interface IP address, | |
3163 | .Sq HISADDR | |
3164 | is replaced with the interface IP destination (peer) address, | |
3165 | .Sq MYADDR6 | |
3166 | is replaced with the interface IPv6 address, and | |
3167 | .Sq HISADDR6 | |
3168 | is replaced with the interface IPv6 destination address, | |
3169 | .Pp | |
3170 | If the | |
3171 | .Ar add!\& | |
3172 | command is used | |
3173 | (note the trailing | |
3174 | .Dq !\& ) , | |
3175 | then if the route already exists, it will be updated as with the | |
3176 | .Sq route change | |
3177 | command (see | |
3178 | .Xr route 8 | |
3179 | for further details). | |
3180 | .Pp | |
3181 | Routes that contain the | |
3182 | .Dq HISADDR , | |
3183 | .Dq MYADDR , | |
3184 | .Dq HISADDR6 , | |
3185 | .Dq MYADDR6 , | |
3186 | .Dq DNS0 , | |
3187 | or | |
3188 | .Dq DNS1 | |
3189 | constants are considered | |
3190 | .Sq sticky . | |
3191 | They are stored in a list (use | |
3192 | .Dq show ncp | |
3193 | to see the list), and each time the value of one of these variables | |
3194 | changes, the appropriate routing table entries are updated. | |
3195 | This facility may be disabled using | |
3196 | .Dq disable sroutes . | |
3197 | .It allow Ar command Op Ar args | |
3198 | This command controls access to | |
3199 | .Nm | |
3200 | and its configuration files. | |
3201 | It is possible to allow user-level access, | |
3202 | depending on the configuration file label and on the mode that | |
3203 | .Nm | |
3204 | is being run in. | |
3205 | For example, you may wish to configure | |
3206 | .Nm | |
3207 | so that only user | |
3208 | .Sq fred | |
3209 | may access label | |
3210 | .Sq fredlabel | |
3211 | in | |
3212 | .Fl background | |
3213 | mode. | |
3214 | .Pp | |
3215 | User id 0 is immune to these commands. | |
3216 | .Bl -tag -width 2n | |
3217 | .It allow user Ns Xo | |
3218 | .Op s | |
3219 | .Ar logname Ns No ... | |
3220 | .Xc | |
3221 | By default, only user id 0 is allowed access to | |
3222 | .Nm . | |
3223 | If this command is used, all of the listed users are allowed access to | |
3224 | the section in which the | |
3225 | .Dq allow users | |
3226 | command is found. | |
3227 | The | |
3228 | .Sq default | |
3229 | section is always checked first (even though it is only ever automatically | |
3230 | loaded at startup). | |
3231 | .Dq allow users | |
3232 | commands are cumulative in a given section, but users allowed in any given | |
3233 | section override users allowed in the default section, so it's possible to | |
3234 | allow users access to everything except a given label by specifying default | |
3235 | users in the | |
3236 | .Sq default | |
3237 | section, and then specifying a new user list for that label. | |
3238 | .Pp | |
3239 | If user | |
3240 | .Sq * | |
3241 | is specified, access is allowed to all users. | |
3242 | .It allow mode Ns Xo | |
3243 | .Op s | |
3244 | .Ar mode Ns No ... | |
3245 | .Xc | |
3246 | By default, access using any | |
3247 | .Nm | |
3248 | mode is possible. | |
3249 | If this command is used, it restricts the access | |
3250 | .Ar modes | |
3251 | allowed to load the label under which this command is specified. | |
3252 | Again, as with the | |
3253 | .Dq allow users | |
3254 | command, each | |
3255 | .Dq allow modes | |
3256 | command overrides any previous settings, and the | |
3257 | .Sq default | |
3258 | section is always checked first. | |
3259 | .Pp | |
3260 | Possible modes are: | |
3261 | .Sq interactive , | |
3262 | .Sq auto , | |
3263 | .Sq direct , | |
3264 | .Sq dedicated , | |
3265 | .Sq ddial , | |
3266 | .Sq background | |
3267 | and | |
3268 | .Sq * . | |
3269 | .Pp | |
3270 | When running in multi-link mode, a section can be loaded if it allows | |
3271 | .Em any | |
3272 | of the currently existing line modes. | |
3273 | .El | |
984263bc MD |
3274 | .It nat Ar command Op Ar args |
3275 | This command allows the control of the network address translation (also | |
3276 | known as masquerading or IP aliasing) facilities that are built into | |
3277 | .Nm . | |
3278 | NAT is done on the external interface only, and is unlikely to make sense | |
3279 | if used with the | |
3280 | .Fl direct | |
3281 | flag. | |
3282 | .Pp | |
3283 | If nat is enabled on your system (it may be omitted at compile time), | |
3284 | the following commands are possible: | |
3285 | .Bl -tag -width 2n | |
3286 | .It nat enable yes|no | |
3287 | This command either switches network address translation on or turns it off. | |
3288 | The | |
3289 | .Fl nat | |
3290 | command line flag is synonymous with | |
3291 | .Dq nat enable yes . | |
3292 | .It nat addr Op Ar addr_local addr_alias | |
3293 | This command allows data for | |
3294 | .Ar addr_alias | |
3295 | to be redirected to | |
3296 | .Ar addr_local . | |
3297 | It is useful if you own a small number of real IP numbers that | |
3298 | you wish to map to specific machines behind your gateway. | |
3299 | .It nat deny_incoming yes|no | |
3300 | If set to yes, this command will refuse all incoming packets where an | |
3301 | aliasing link doesn't already exist. | |
3302 | ifdef({LOCALNAT},{},{Refer to the | |
3303 | .Sx CONCEPTUAL BACKGROUND | |
3304 | section of | |
3305 | .Xr libalias 3 | |
3306 | for a description of what an | |
3307 | .Dq aliasing link | |
3308 | is. | |
3309 | })dnl | |
3310 | .Pp | |
3311 | It should be noted under what circumstances an aliasing link is | |
3312 | ifdef({LOCALNAT},{created.},{created by | |
3313 | .Xr libalias 3 .}) | |
3314 | It may be necessary to further protect your network from outside | |
3315 | connections using the | |
3316 | .Dq set filter | |
3317 | or | |
3318 | .Dq nat target | |
3319 | commands. | |
3320 | .It nat help|? | |
3321 | This command gives a summary of available nat commands. | |
3322 | .It nat log yes|no | |
3323 | This option causes various NAT statistics and information to | |
3324 | be logged to the file | |
3325 | .Pa /var/log/alias.log . | |
3326 | .It nat port Ar proto Ar targetIP Ns Xo | |
3327 | .No : Ns Ar targetPort Ns | |
3328 | .Oo | |
3329 | .No - Ns Ar targetPort | |
3330 | .Oc Ar aliasPort Ns | |
3331 | .Oo | |
3332 | .No - Ns Ar aliasPort | |
3333 | .Oc Oo Ar remoteIP : Ns | |
3334 | .Ar remotePort Ns | |
3335 | .Oo | |
3336 | .No - Ns Ar remotePort | |
3337 | .Oc Ns | |
3338 | .Oc | |
3339 | .Xc | |
3340 | This command causes incoming | |
3341 | .Ar proto | |
3342 | connections to | |
3343 | .Ar aliasPort | |
3344 | to be redirected to | |
3345 | .Ar targetPort | |
3346 | on | |
3347 | .Ar targetIP . | |
3348 | .Ar proto | |
3349 | is either | |
3350 | .Dq tcp | |
3351 | or | |
3352 | .Dq udp . | |
3353 | .Pp | |
3354 | A range of port numbers may be specified as shown above. | |
3355 | The ranges must be of the same size. | |
3356 | .Pp | |
3357 | If | |
3358 | .Ar remoteIP | |
3359 | is specified, only data coming from that IP number is redirected. | |
3360 | .Ar remotePort | |
3361 | must either be | |
3362 | .Dq 0 | |
3363 | (indicating any source port) | |
3364 | or a range of ports the same size as the other ranges. | |
3365 | .Pp | |
3366 | This option is useful if you wish to run things like Internet phone on | |
3367 | machines behind your gateway, but is limited in that connections to only | |
3368 | one interior machine per source machine and target port are possible. | |
3369 | .It nat proto Ar proto localIP Oo | |
3370 | .Ar publicIP Op Ar remoteIP | |
3371 | .Oc | |
3372 | This command tells | |
3373 | .Nm | |
3374 | to redirect packets of protocol type | |
3375 | .Ar proto | |
3376 | (see | |
3377 | .Xr protocols 5 ) | |
3378 | to the internal address | |
3379 | .Ar localIP . | |
3380 | .Pp | |
3381 | If | |
3382 | .Ar publicIP | |
3383 | is specified, only packets destined for that address are matched, | |
3384 | otherwise the default alias address is used. | |
3385 | .Pp | |
3386 | If | |
3387 | .Ar remoteIP | |
3388 | is specified, only packets matching that source address are matched, | |
3389 | .Pp | |
3390 | This command is useful for redirecting tunnel endpoints to an internal machine, | |
3391 | for example: | |
3392 | .Pp | |
3393 | .Dl nat proto ipencap 10.0.0.1 | |
3394 | .It "nat proxy cmd" Ar arg Ns No ... | |
3395 | This command tells | |
3396 | .Nm | |
3397 | to proxy certain connections, redirecting them to a given server. | |
3398 | ifdef({LOCALNAT},{},{Refer to the description of | |
3399 | .Fn PacketAliasProxyRule | |
3400 | in | |
3401 | .Xr libalias 3 | |
3402 | for details of the available commands. | |
3403 | })dnl | |
3404 | .It nat punch_fw Op Ar base count | |
3405 | This command tells | |
3406 | .Nm | |
3407 | to punch holes in the firewall for FTP or IRC DCC connections. | |
3f5e28f4 | 3408 | This is done dynamically by installing temporary firewall rules which |
984263bc MD |
3409 | allow a particular connection (and only that connection) to go through |
3410 | the firewall. | |
3411 | The rules are removed once the corresponding connection terminates. | |
3412 | .Pp | |
3413 | A maximum of | |
3414 | .Ar count | |
3415 | rules starting from rule number | |
3416 | .Ar base | |
3417 | will be used for punching firewall holes. | |
3418 | The range will be cleared when the | |
3419 | .Dq nat punch_fw | |
3420 | command is run. | |
3421 | .Pp | |
3422 | If no arguments are given, firewall punching is disabled. | |
3423 | .It nat same_ports yes|no | |
3424 | When enabled, this command will tell the network address translation engine to | |
3425 | attempt to avoid changing the port number on outgoing packets. | |
3426 | This is useful | |
3427 | if you want to support protocols such as RPC and LPD which require | |
3428 | connections to come from a well known port. | |
3429 | .It nat target Op Ar address | |
3430 | Set the given target address or clear it if no address is given. | |
3431 | The target address is used | |
3432 | ifdef({LOCALNAT},{},{by libalias })dnl | |
3433 | to specify how to NAT incoming packets by default. | |
3434 | If a target address is not set or if | |
3435 | .Dq default | |
3436 | is given, packets are not altered and are allowed to route to the internal | |
3437 | network. | |
3438 | .Pp | |
3439 | The target address may be set to | |
3440 | .Dq MYADDR , | |
3441 | in which case | |
3442 | ifdef({LOCALNAT},{all packets will be redirected}, | |
3443 | {libalias will redirect all packets}) | |
3444 | to the interface address. | |
3445 | .It nat use_sockets yes|no | |
3446 | When enabled, this option tells the network address translation engine to | |
3447 | create a socket so that it can guarantee a correct incoming ftp data or | |
3448 | IRC connection. | |
3449 | .It nat unregistered_only yes|no | |
3450 | Only alter outgoing packets with an unregistered source address. | |
3451 | According to RFC 1918, unregistered source addresses | |
3452 | are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16. | |
3453 | .El | |
3454 | .Pp | |
3455 | These commands are also discussed in the file | |
3456 | .Pa README.nat | |
3457 | which comes with the source distribution. | |
bc536631 | 3458 | .It Oo !\& Oc Ns Xo |
984263bc MD |
3459 | .No bg Ar command |
3460 | .Xc | |
3461 | The given | |
3462 | .Ar command | |
3463 | is executed in the background with the following words replaced: | |
3464 | .Bl -tag -width COMPILATIONDATE | |
3465 | .It Li AUTHNAME | |
3466 | This is replaced with the local | |
3467 | .Ar authname | |
3468 | value. | |
3469 | See the | |
3470 | .Dq set authname | |
3471 | command below. | |
3472 | .It Li COMPILATIONDATE | |
3473 | This is replaced with the date on which | |
3474 | .Nm | |
3475 | was compiled. | |
3476 | .It Li DNS0 & DNS1 | |
3477 | These are replaced with the primary and secondary nameserver IP numbers. | |
3478 | If nameservers are negotiated by IPCP, the values of these macros will change. | |
3479 | .It Li ENDDISC | |
3480 | This is replaced with the local endpoint discriminator value. | |
3481 | See the | |
3482 | .Dq set enddisc | |
3483 | command below. | |
3484 | .It Li HISADDR | |
3485 | This is replaced with the peers IP number. | |
3486 | .It Li HISADDR6 | |
3487 | This is replaced with the peers IPv6 number. | |
3488 | .It Li INTERFACE | |
3489 | This is replaced with the name of the interface that's in use. | |
3490 | .It Li IPOCTETSIN | |
3491 | This is replaced with the number of IP bytes received since the connection | |
3492 | was established. | |
3493 | .It Li IPOCTETSOUT | |
3494 | This is replaced with the number of IP bytes sent since the connection | |
3495 | was established. | |
3496 | .It Li IPPACKETSIN | |
3497 | This is replaced with the number of IP packets received since the connection | |
3498 | was established. | |
3499 | .It Li IPPACKETSOUT | |
3500 | This is replaced with the number of IP packets sent since the connection | |
3501 | was established. | |
3502 | .It Li IPV6OCTETSIN | |
3503 | This is replaced with the number of IPv6 bytes received since the connection | |
3504 | was established. | |
3505 | .It Li IPV6OCTETSOUT | |
3506 | This is replaced with the number of IPv6 bytes sent since the connection | |
3507 | was established. | |
3508 | .It Li IPV6PACKETSIN | |
3509 | This is replaced with the number of IPv6 packets received since the connection | |
3510 | was established. | |
3511 | .It Li IPV6PACKETSOUT | |
3512 | This is replaced with the number of IPv6 packets sent since the connection | |
3513 | was established. | |
3514 | .It Li LABEL | |
3515 | This is replaced with the last label name used. | |
3516 | A label may be specified on the | |
3517 | .Nm | |
3518 | command line, via the | |
3519 | .Dq load | |
3520 | or | |
3521 | .Dq dial | |
3522 | commands and in the | |
3523 | .Pa ppp.secret | |
3524 | file. | |
3525 | .It Li MYADDR | |
3526 | This is replaced with the IP number assigned to the local interface. | |
3527 | .It Li MYADDR6 | |
3528 | This is replaced with the IPv6 number assigned to the local interface. | |
3529 | .It Li OCTETSIN | |
3530 | This is replaced with the number of bytes received since the connection | |
3531 | was established. | |
3532 | .It Li OCTETSOUT | |
3533 | This is replaced with the number of bytes sent since the connection | |
3534 | was established. | |
3535 | .It Li PACKETSIN | |
3536 | This is replaced with the number of packets received since the connection | |
3537 | was established. | |
3538 | .It Li PACKETSOUT | |
3539 | This is replaced with the number of packets sent since the connection | |
3540 | was established. | |
3541 | .It Li PEER_ENDDISC | |
3542 | This is replaced with the value of the peers endpoint discriminator. | |
3543 | .It Li PROCESSID | |
3544 | This is replaced with the current process id. | |
3545 | .It Li SOCKNAME | |
3546 | This is replaced with the name of the diagnostic socket. | |
3547 | .It Li UPTIME | |
3548 | This is replaced with the bundle uptime in HH:MM:SS format. | |
3549 | .It Li USER | |
3550 | This is replaced with the username that has been authenticated with PAP or | |
3551 | CHAP. | |
3552 | Normally, this variable is assigned only in -direct mode. | |
25606b42 | 3553 | This value is available irrespective of whether utmpx logging is enabled. |
984263bc MD |
3554 | .It Li VERSION |
3555 | This is replaced with the current version number of | |
3556 | .Nm . | |
3557 | .El | |
3558 | .Pp | |
3559 | These substitutions are also done by the | |
3560 | .Dq set proctitle , | |
3561 | .Dq ident | |
3562 | and | |
3563 | .Dq log | |
3564 | commands. | |
3565 | .Pp | |
3566 | If you wish to pause | |
3567 | .Nm | |
3568 | while the command executes, use the | |
3569 | .Dq shell | |
3570 | command instead. | |
3571 | .It clear physical|ipcp|ipv6 Op current|overall|peak... | |
3572 | Clear the specified throughput values at either the | |
3573 | .Dq physical , | |
3574 | .Dq ipcp | |
3575 | or | |
3576 | .Dq ipv6cp | |
3577 | level. | |
3578 | If | |
3579 | .Dq physical | |
3580 | is specified, context must be given (see the | |
3581 | .Dq link | |
3582 | command below). | |
3583 | If no second argument is given, all values are cleared. | |
3584 | .It clone Ar name Ns Xo | |
3585 | .Op \&, Ns Ar name Ns | |
3586 | .No ... | |
3587 | .Xc | |
3588 | Clone the specified link, creating one or more new links according to the | |
3589 | .Ar name | |
3590 | argument(s). | |
3591 | This command must be used from the | |
3592 | .Dq link | |
3593 | command below unless you've only got a single link (in which case that | |
3594 | link becomes the default). | |
3595 | Links may be removed using the | |
3596 | .Dq remove | |
3597 | command below. | |
3598 | .Pp | |
3599 | The default link name is | |
3600 | .Dq deflink . | |
3601 | .It close Op lcp|ccp Ns Op !\& | |
3602 | If no arguments are given, the relevant protocol layers will be brought | |
3603 | down and the link will be closed. | |
3604 | If | |
3605 | .Dq lcp | |
3606 | is specified, the LCP layer is brought down, but | |
3607 | .Nm | |
3608 | will not bring the link offline. | |
3609 | It is subsequently possible to use | |
3610 | .Dq term | |
3611 | (see below) | |
3612 | to talk to the peer machine if, for example, something like | |
3613 | .Dq slirp | |
3614 | is being used. | |
3615 | If | |
3616 | .Dq ccp | |
3617 | is specified, only the relevant compression layer is closed. | |
3618 | If the | |
3619 | .Dq !\& | |
3620 | is used, the compression layer will remain in the closed state, otherwise | |
3621 | it will re-enter the STOPPED state, waiting for the peer to initiate | |
3622 | further CCP negotiation. | |
3623 | In any event, this command does not disconnect the user from | |
3624 | .Nm | |
3625 | or exit | |
3626 | .Nm . | |
3627 | See the | |
3628 | .Dq quit | |
3629 | command below. | |
3630 | .It delete Ns Xo | |
3631 | .Op !\& | |
3632 | .Ar dest | |
3633 | .Xc | |
3634 | This command deletes the route with the given | |
3635 | .Ar dest | |
3636 | IP address. | |
3637 | If | |
3638 | .Ar dest | |
3639 | is specified as | |
3640 | .Sq ALL , | |
3641 | all non-direct entries in the routing table for the current interface, | |
3642 | and all | |
3643 | .Sq sticky route | |
3644 | entries are deleted. | |
3645 | If | |
3646 | .Ar dest | |
3647 | is specified as | |
3648 | .Sq default , | |
3649 | the default route is deleted. | |
3650 | .Pp | |
3651 | If the | |
3652 | .Ar delete!\& | |
3653 | command is used | |
3654 | (note the trailing | |
3655 | .Dq !\& ) , | |
3656 | .Nm | |
3657 | will not complain if the route does not already exist. | |
bc536631 SW |
3658 | .It Xo |
3659 | .Ic dial No \&| | |
3660 | .Ic call | |
3661 | .Op Ar label ... | |
984263bc MD |
3662 | .Xc |
3663 | This command is the equivalent of | |
3664 | .Dq load label | |
3665 | followed by | |
3666 | .Dq open , | |
3667 | and is provided for backwards compatibility. | |
3668 | .It down Op Ar lcp|ccp | |
3669 | Bring the relevant layer down ungracefully, as if the underlying layer | |
3670 | had become unavailable. | |
3671 | It's not considered polite to use this command on | |
3672 | a Finite State Machine that's in the OPEN state. | |
3673 | If no arguments are | |
3674 | supplied, the entire link is closed (or if no context is given, all links | |
3675 | are terminated). | |
3676 | If | |
3677 | .Sq lcp | |
3678 | is specified, the | |
3679 | .Em LCP | |
3680 | layer is terminated but the device is not brought offline and the link | |
3681 | is not closed. | |
3682 | If | |
3683 | .Sq ccp | |
3684 | is specified, only the relevant compression layer(s) are terminated. | |
3685 | .It help|? Op Ar command | |
3686 | Show a list of available commands. | |
3687 | If | |
3688 | .Ar command | |
3689 | is specified, show the usage string for that command. | |
3690 | .It ident Op Ar text Ns No ... | |
3691 | Identify the link to the peer using | |
3692 | .Ar text . | |
3693 | If | |
3694 | .Ar text | |
3695 | is empty, link identification is disabled. | |
3696 | It is possible to use any of the words described for the | |
3697 | .Ic bg | |
3698 | command above. | |
3699 | Refer to the | |
3700 | .Ic sendident | |
3701 | command for details of when | |
3702 | .Nm | |
3703 | identifies itself to the peer. | |
3704 | .It iface Ar command Op args | |
3705 | This command is used to control the interface used by | |
3706 | .Nm . | |
3707 | .Ar Command | |
3708 | may be one of the following: | |
3709 | .Bl -tag -width 2n | |
3710 | .It iface add Ns Xo | |
3711 | .Op !\& | |
3712 | .Ar addr Ns Op / Ns Ar bits | |
3713 | .Op Ar peer | |
3714 | .Xc | |
3715 | .It iface add Ns Xo | |
3716 | .Op !\& | |
3717 | .Ar addr | |
3718 | .Ar mask | |
3719 | .Ar peer | |
3720 | .Xc | |
3721 | Add the given | |
3722 | .Ar addr mask peer | |
3723 | combination to the interface. | |
3724 | Instead of specifying | |
3725 | .Ar mask , | |
3726 | .Ar /bits | |
3727 | can be used | |
3728 | (with no space between it and | |
3729 | .Ar addr ) . | |
3730 | If the given address already exists, the command fails unless the | |
3731 | .Dq !\& | |
3732 | is used - in which case the previous interface address entry is overwritten | |
3733 | with the new one, allowing a change of netmask or peer address. | |
3734 | .Pp | |
3735 | If only | |
3736 | .Ar addr | |
3737 | is specified, | |
3738 | .Ar bits | |
3739 | defaults to | |
3740 | .Dq 32 | |
3741 | and | |
3742 | .Ar peer | |
3743 | defaults to | |
3744 | .Dq 255.255.255.255 . | |
3745 | This address (the broadcast address) is the only duplicate peer address that | |
3746 | .Nm | |
3747 | allows. | |
3748 | .It iface clear Op INET | INET6 | |
3749 | If this command is used while | |
3750 | .Nm | |
3751 | is in the OPENED state or while in | |
3752 | .Fl auto | |
3753 | mode, all addresses except for the NCP negotiated address are deleted | |
3754 | from the interface. | |
3755 | If | |
3756 | .Nm | |
3757 | is not in the OPENED state and is not in | |
3758 | .Fl auto | |
3759 | mode, all interface addresses are deleted. | |
3760 | .Pp | |
3761 | If the INET or INET6 arguments are used, only addresses for that address | |
3762 | family are cleared. | |
984263bc MD |
3763 | .It iface delete Ns Xo |
3764 | .Op !\& Ns | |
3765 | .No |rm Ns Op !\& | |
3766 | .Ar addr | |
3767 | .Xc | |
3768 | This command deletes the given | |
3769 | .Ar addr | |
3770 | from the interface. | |
3771 | If the | |
3772 | .Dq !\& | |
3773 | is used, no error is given if the address isn't currently assigned to | |
3774 | the interface (and no deletion takes place). | |
3775 | .It iface show | |
3776 | Shows the current state and current addresses for the interface. | |
3777 | It is much the same as running | |
3778 | .Dq ifconfig INTERFACE . | |
3779 | .It iface help Op Ar sub-command | |
3780 | This command, when invoked without | |
3781 | .Ar sub-command , | |
3782 | will show a list of possible | |
3783 | .Dq iface | |
3784 | sub-commands and a brief synopsis for each. | |
3785 | When invoked with | |
3786 | .Ar sub-command , | |
3787 | only the synopsis for the given sub-command is shown. | |
3788 | .El | |
bc536631 SW |
3789 | .It Oo Ic data Oc Ns Xo |
3790 | .Ic link | |
984263bc MD |
3791 | .Ar name Ns Op , Ns Ar name Ns |
3792 | .No ... Ar command Op Ar args | |
3793 | .Xc | |
3794 | This command may prefix any other command if the user wishes to | |
3795 | specify which link the command should affect. | |
3796 | This is only applicable after multiple links have been created in Multi-link | |
3797 | mode using the | |
3798 | .Dq clone | |
3799 | command. | |
3800 | .Pp | |
3801 | .Ar Name | |
3802 | specifies the name of an existing link. | |
3803 | If | |
3804 | .Ar name | |
3805 | is a comma separated list, | |
3806 | .Ar command | |
3807 | is executed on each link. | |
3808 | If | |
3809 | .Ar name | |
3810 | is | |
3811 | .Dq * , | |
3812 | .Ar command | |
3813 | is executed on all links. | |
bc536631 | 3814 | .It Ic load Oo Ar label Oc Ns Xo |
984263bc MD |
3815 | .No ... |
3816 | .Xc | |
3817 | Load the given | |
3818 | .Ar label Ns No (s) | |
3819 | from the | |
3820 | .Pa ppp.conf | |
3821 | file. | |
3822 | If | |
3823 | .Ar label | |
3824 | is not given, the | |
3825 | .Ar default | |
3826 | label is used. | |
3827 | .Pp | |
3828 | Unless the | |
3829 | .Ar label | |
3830 | section uses the | |
3831 | .Dq set mode , | |
3832 | .Dq open | |
3833 | or | |
3834 | .Dq dial | |
3835 | commands, | |
3836 | .Nm | |
3837 | will not attempt to make an immediate connection. | |
3838 | .It log Ar word Ns No ... | |
3839 | Send the given word(s) to the log file with the prefix | |
3840 | .Dq LOG: . | |
3841 | Word substitutions are done as explained under the | |
3842 | .Dq !bg | |
3843 | command above. | |
3844 | .It open Op lcp|ccp|ipcp | |
3845 | This is the opposite of the | |
3846 | .Dq close | |
3847 | command. | |
3848 | All closed links are immediately brought up apart from second and subsequent | |
3849 | .Ar demand-dial | |
3850 | links - these will come up based on the | |
3851 | .Dq set autoload | |
3852 | command that has been used. | |
3853 | .Pp | |
3854 | If the | |
3855 | .Dq lcp | |
3856 | argument is used while the LCP layer is already open, LCP will be | |
3857 | renegotiated. | |
3858 | This allows various LCP options to be changed, after which | |
3859 | .Dq open lcp | |
3860 | can be used to put them into effect. | |
3861 | After renegotiating LCP, | |
3862 | any agreed authentication will also take place. | |
3863 | .Pp | |
3864 | If the | |
3865 | .Dq ccp | |
3866 | argument is used, the relevant compression layer is opened. | |
3867 | Again, if it is already open, it will be renegotiated. | |
3868 | .Pp | |
3869 | If the | |
3870 | .Dq ipcp | |
3871 | argument is used, the link will be brought up as normal, but if | |
3872 | IPCP is already open, it will be renegotiated and the network | |
3873 | interface will be reconfigured. | |
3874 | .Pp | |
3875 | It is probably not good practice to re-open the PPP state machines | |
3876 | like this as it's possible that the peer will not behave correctly. | |
3877 | It | |
3878 | .Em is | |
3879 | however useful as a way of forcing the CCP or VJ dictionaries to be reset. | |
3880 | .It passwd Ar pass | |
3881 | Specify the password required for access to the full | |
3882 | .Nm | |
3883 | command set. | |
3884 | This password is required when connecting to the diagnostic port (see the | |
3885 | .Dq set server | |
3886 | command). | |
3887 | .Ar Pass | |
3888 | is specified on the | |
3889 | .Dq set server | |
3890 | command line. | |
3891 | The value of | |
3892 | .Ar pass | |
3893 | is not logged when | |
3894 | .Ar command | |
3895 | logging is active, instead, the literal string | |
3896 | .Sq ******** | |
3897 | is logged. | |
3898 | .It quit|bye Op all | |
3899 | If | |
3900 | .Dq quit | |
3901 | is executed from the controlling connection or from a command file, | |
3902 | ppp will exit after closing all connections. | |
3903 | Otherwise, if the user | |
3904 | is connected to a diagnostic socket, the connection is simply dropped. | |
3905 | .Pp | |
3906 | If the | |
3907 | .Ar all | |
3908 | argument is given, | |
3909 | .Nm | |
3910 | will exit despite the source of the command after closing all existing | |
3911 | connections. | |
3912 | .It remove|rm | |
3913 | This command removes the given link. | |
3914 | It is only really useful in multi-link mode. | |
3915 | A link must be in the | |
3916 | .Dv CLOSED | |
3917 | state before it is removed. | |
3918 | .It rename|mv Ar name | |
3919 | This command renames the given link to | |
3920 | .Ar name . | |
3921 | It will fail if | |
3922 | .Ar name | |
3923 | is already used by another link. | |
3924 | .Pp | |
3925 | The default link name is | |
3926 | .Sq deflink . | |
3927 | Renaming it to | |
3928 | .Sq modem , | |
3929 | .Sq cuaa0 | |
3930 | or | |
3931 | .Sq USR | |
3932 | may make the log file more readable. | |
3933 | .It resolv Ar command | |
3934 | This command controls | |
3935 | .Nm Ns No 's | |
3936 | manipulation of the | |
3937 | .Xr resolv.conf 5 | |
3938 | file. | |
3939 | When | |
3940 | .Nm | |
3941 | starts up, it loads the contents of this file into memory and retains this | |
3942 | image for future use. | |
3943 | .Ar command | |
3944 | is one of the following: | |
3945 | .Bl -tag -width readonly | |
3946 | .It Em readonly | |
3947 | Treat | |
3948 | .Pa /etc/resolv.conf | |
3949 | as read only. | |
3950 | If | |
3951 | .Dq dns | |
3952 | is enabled, | |
3953 | .Nm | |
3954 | will still attempt to negotiate nameservers with the peer, making the results | |
3955 | available via the | |
3956 | .Dv DNS0 | |
3957 | and | |
3958 | .Dv DNS1 | |
3959 | macros. | |
3960 | This is the opposite of the | |
3961 | .Dq resolv writable | |
3962 | command. | |
3963 | .It Em reload | |
3964 | Reload | |
3965 | .Pa /etc/resolv.conf | |
3966 | into memory. | |
3967 | This may be necessary if for example a DHCP client overwrote | |
3968 | .Pa /etc/resolv.conf . | |
3969 | .It Em restore | |
3970 | Replace | |
3971 | .Pa /etc/resolv.conf | |
3972 | with the version originally read at startup or with the last | |
3973 | .Dq resolv reload | |
3974 | command. | |
3975 | This is sometimes a useful command to put in the | |
3976 | .Pa /etc/ppp/ppp.linkdown | |
3977 | file. | |
3978 | .It Em rewrite | |
3979 | Rewrite the | |
3980 | .Pa /etc/resolv.conf | |
3981 | file. | |
3982 | This command will work even if the | |
3983 | .Dq resolv readonly | |
3984 | command has been used. | |
3985 | It may be useful as a command in the | |
3986 | .Pa /etc/ppp/ppp.linkup | |
3987 | file if you wish to defer updating | |
3988 | .Pa /etc/resolv.conf | |
3989 | until after other commands have finished. | |
3990 | .It Em writable | |
3991 | Allow | |
3992 | .Nm | |
3993 | to update | |
3994 | .Pa /etc/resolv.conf | |
3995 | if | |
3996 | .Dq dns | |
3997 | is enabled and | |
3998 | .Nm | |
3999 | successfully negotiates a DNS. | |
4000 | This is the opposite of the | |
4001 | .Dq resolv readonly | |
4002 | command. | |
4003 | .El | |
4004 | .It save | |
4005 | This option is not (yet) implemented. | |
4006 | .It sendident | |
4007 | This command tells | |
4008 | .Nm | |
4009 | to identify itself to the peer. | |
4010 | The link must be in LCP state or higher. | |
4011 | If no identity has been set (via the | |
4012 | .Ic ident | |
4013 | command), | |
4014 | .Ic sendident | |
4015 | will fail. | |
4016 | .Pp | |
4017 | When an identity has been set, | |
4018 | .Nm | |
4019 | will automatically identify itself when it sends or receives a configure | |
4020 | reject, when negotiation fails or when LCP reaches the opened state. | |
4021 | .Pp | |
4022 | Received identification packets are logged to the LCP log (see | |
4023 | .Ic set log | |
4024 | for details) and are never responded to. | |
4025 | .It set Ns Xo | |
4026 | .Op up | |
4027 | .Ar var value | |
4028 | .Xc | |
4029 | This option allows the setting of any of the following variables: | |
4030 | .Bl -tag -width 2n | |
4031 | .It set accmap Ar hex-value | |
4032 | ACCMap stands for Asynchronous Control Character Map. | |
4033 | This is always | |
4034 | negotiated with the peer, and defaults to a value of 00000000 in hex. | |
4035 | This protocol is required to defeat hardware that depends on passing | |
4036 | certain characters from end to end (such as XON/XOFF etc). | |
4037 | .Pp | |
4038 | For the XON/XOFF scenario, use | |
4039 | .Dq set accmap 000a0000 . | |
bc536631 SW |
4040 | .It Ic set Oo Ic auth Oc Ns Xo |
4041 | .Ic key Ar value | |
984263bc MD |
4042 | .Xc |
4043 | This sets the authentication key (or password) used in client mode | |
4044 | PAP or CHAP negotiation to the given value. | |
4045 | It also specifies the | |
4046 | password to be used in the dial or login scripts in place of the | |
4047 | .Sq \eP | |
4048 | sequence, preventing the actual password from being logged. | |
4049 | If | |
4050 | .Ar command | |
4051 | or | |
4052 | .Ar chat | |
4053 | logging is in effect, | |
4054 | .Ar value | |
4055 | is logged as | |
4056 | .Sq ******** | |
4057 | for security reasons. | |
4058 | .Pp | |
4059 | If the first character of | |
4060 | .Ar value | |
4061 | is an exclamation mark | |
4062 | .Pq Dq !\& , | |
4063 | .Nm | |
4064 | treats the remainder of the string as a program that must be executed | |
4065 | to determine the | |
4066 | .Dq authname | |
4067 | and | |
4068 | .Dq authkey | |
4069 | values. | |
4070 | .Pp | |
4071 | If the | |
4072 | .Dq !\& | |
4073 | is doubled up | |
4074 | (to | |
4075 | .Dq !! ) , | |
4076 | it is treated as a single literal | |
4077 | .Dq !\& , | |
4078 | otherwise, ignoring the | |
4079 | .Dq !\& , | |
4080 | .Ar value | |
4081 | is parsed as a program to execute in the same was as the | |
4082 | .Dq !bg | |
4083 | command above, substituting special names in the same manner. | |
4084 | Once executed, | |
4085 | .Nm | |
4086 | will feed the program three lines of input, each terminated by a newline | |
4087 | character: | |
4088 | .Bl -bullet | |
4089 | .It | |
4090 | The host name as sent in the CHAP challenge. | |
4091 | .It | |
4092 | The challenge string as sent in the CHAP challenge. | |
4093 | .It | |
4094 | The locally defined | |
4095 | .Dq authname . | |
4096 | .El | |
4097 | .Pp | |
4098 | Two lines of output are expected: | |
4099 | .Bl -bullet | |
4100 | .It | |
4101 | The | |
4102 | .Dq authname | |
4103 | to be sent with the CHAP response. | |
4104 | .It | |
4105 | The | |
4106 | .Dq authkey , | |
4107 | which is encrypted with the challenge and request id, the answer being sent | |
4108 | in the CHAP response packet. | |
4109 | .El | |
4110 | .Pp | |
4111 | When configuring | |
4112 | .Nm | |
4113 | in this manner, it's expected that the host challenge is a series of ASCII | |
4114 | digits or characters. | |
4115 | An encryption device or Secure ID card is usually | |
4116 | required to calculate the secret appropriate for the given challenge. | |
4117 | .It set authname Ar id | |
4118 | This sets the authentication id used in client mode PAP or CHAP negotiation. | |
4119 | .Pp | |
4120 | If used in | |
4121 | .Fl direct | |
4122 | mode with CHAP enabled, | |
4123 | .Ar id | |
4124 | is used in the initial authentication challenge and should normally be set to | |
4125 | the local machine name. | |
4126 | .It set autoload Xo | |
4127 | .Ar min-percent max-percent period | |
4128 | .Xc | |
4129 | These settings apply only in multi-link mode and default to zero, zero and | |
4130 | five respectively. | |
4131 | When more than one | |
4132 | .Ar demand-dial | |
4133 | (also known as | |
4134 | .Fl auto ) | |
4135 | mode link is available, only the first link is made active when | |
4136 | .Nm | |
4137 | first reads data from the tun device. | |
4138 | The next | |
4139 | .Ar demand-dial | |
4140 | link will be opened only when the current bundle throughput is at least | |
4141 | .Ar max-percent | |
4142 | percent of the total bundle bandwidth for | |
4143 | .Ar period | |
4144 | seconds. | |
4145 | When the current bundle throughput decreases to | |
4146 | .Ar min-percent | |
4147 | percent or less of the total bundle bandwidth for | |
4148 | .Ar period | |
4149 | seconds, a | |
4150 | .Ar demand-dial | |
4151 | link will be brought down as long as it's not the last active link. | |
4152 | .Pp | |
4153 | Bundle throughput is measured as the maximum of inbound and outbound | |
4154 | traffic. | |
4155 | .Pp | |
4156 | The default values cause | |
4157 | .Ar demand-dial | |
4158 | links to simply come up one at a time. | |
4159 | .Pp | |
4160 | Certain devices cannot determine their physical bandwidth, so it | |
4161 | is sometimes necessary to use the | |
4162 | .Dq set bandwidth | |
4163 | command (described below) to make | |
4164 | .Dq set autoload | |
4165 | work correctly. | |
4166 | .It set bandwidth Ar value | |
4167 | This command sets the connection bandwidth in bits per second. | |
4168 | .Ar value | |
4169 | must be greater than zero. | |
4170 | It is currently only used by the | |
4171 | .Dq set autoload | |
4172 | command above. | |
4173 | .It set callback Ar option Ns No ... | |
4174 | If no arguments are given, callback is disabled, otherwise, | |
4175 | .Nm | |
4176 | will request (or in | |
4177 | .Fl direct | |
4178 | mode, will accept) one of the given | |
4179 | .Ar option Ns No s . | |
4180 | In client mode, if an | |
4181 | .Ar option | |
4182 | is NAK'd | |
4183 | .Nm | |
4184 | will request a different | |
4185 | .Ar option , | |
4186 | until no options remain at which point | |
4187 | .Nm | |
4188 | will terminate negotiations (unless | |
4189 | .Dq none | |
4190 | is one of the specified | |
4191 | .Ar option ) . | |
4192 | In server mode, | |
4193 | .Nm | |
4194 | will accept any of the given protocols - but the client | |
4195 | .Em must | |
4196 | request one of them. | |
4197 | If you wish callback to be optional, you must {include} | |
4198 | .Ar none | |
4199 | as an option. | |
4200 | .Pp | |
4201 | The | |
4202 | .Ar option Ns No s | |
4203 | are as follows (in this order of preference): | |
984263bc MD |
4204 | .Bl -tag -width Ds |
4205 | .It auth | |
4206 | The callee is expected to decide the callback number based on | |
4207 | authentication. | |
4208 | If | |
4209 | .Nm | |
4210 | is the callee, the number should be specified as the fifth field of | |
4211 | the peers entry in | |
4212 | .Pa /etc/ppp/ppp.secret . | |
4213 | .It cbcp | |
4214 | Microsoft's callback control protocol is used. | |
4215 | See | |
4216 | .Dq set cbcp | |
4217 | below. | |
4218 | .Pp | |
4219 | If you wish to negotiate | |
4220 | .Ar cbcp | |
4221 | in client mode but also wish to allow the server to request no callback at | |
4222 | CBCP negotiation time, you must specify both | |
4223 | .Ar cbcp | |
4224 | and | |
4225 | .Ar none | |
4226 | as callback options. | |
4227 | .It E.164 *| Ns Xo | |
4228 | .Ar number Ns Op , Ns Ar number Ns | |
4229 | .No ... | |
4230 | .Xc | |
4231 | The caller specifies the | |
4232 | .Ar number . | |
4233 | If | |
4234 | .Nm | |
4235 | is the callee, | |
4236 | .Ar number | |
4237 | should be either a comma separated list of allowable numbers or a | |
4238 | .Dq \&* , | |
4239 | meaning any number is permitted. | |
4240 | If | |
4241 | .Nm | |
4242 | is the caller, only a single number should be specified. | |
4243 | .Pp | |
4244 | Note, this option is very unsafe when used with a | |
4245 | .Dq \&* | |
4246 | as a malicious caller can tell | |
4247 | .Nm | |
4248 | to call any (possibly international) number without first authenticating | |
4249 | themselves. | |
4250 | .It none | |
4251 | If the peer does not wish to do callback at all, | |
4252 | .Nm | |
4253 | will accept the fact and continue without callback rather than terminating | |
4254 | the connection. | |
4255 | This is required (in addition to one or more other callback | |
4256 | options) if you wish callback to be optional. | |
4257 | .El | |
984263bc MD |
4258 | .It set cbcp Oo |
4259 | .No *| Ns Ar number Ns Oo | |
4260 | .No , Ns Ar number Ns ...\& Oc | |
4261 | .Op Ar delay Op Ar retry | |
4262 | .Oc | |
4263 | If no arguments are given, CBCP (Microsoft's CallBack Control Protocol) | |
4264 | is disabled - ie, configuring CBCP in the | |
4265 | .Dq set callback | |
4266 | command will result in | |
4267 | .Nm | |
4268 | requesting no callback in the CBCP phase. | |
4269 | Otherwise, | |
4270 | .Nm | |
4271 | attempts to use the given phone | |
4272 | .Ar number Ns No (s). | |
4273 | .Pp | |
4274 | In server mode | |
4275 | .Pq Fl direct , | |
4276 | .Nm | |
4277 | will insist that the client uses one of these numbers, unless | |
4278 | .Dq \&* | |
4279 | is used in which case the client is expected to specify the number. | |
4280 | .Pp | |
4281 | In client mode, | |
4282 | .Nm | |
4283 | will attempt to use one of the given numbers (whichever it finds to | |
4284 | be agreeable with the peer), or if | |
4285 | .Dq \&* | |
4286 | is specified, | |
4287 | .Nm | |
4288 | will expect the peer to specify the number. | |
4289 | .It set cd Oo | |
4290 | .No off| Ns Ar seconds Ns Op !\& | |
4291 | .Oc | |
4292 | Normally, | |
4293 | .Nm | |
4294 | checks for the existence of carrier depending on the type of device | |
4295 | that has been opened: | |
4296 | .Bl -tag -width XXX -offset XXX | |
4297 | .It Terminal Devices | |
4298 | Carrier is checked one second after the login script is complete. | |
4299 | If it's not set, | |
4300 | .Nm | |
4301 | assumes that this is because the device doesn't support carrier (which | |
4302 | is true for most | |
4303 | .Dq laplink | |
4304 | NULL-modem cables), logs the fact and stops checking | |
4305 | for carrier. | |
4306 | .Pp | |
b1c94e87 SW |
4307 | As ptys don't support the |
4308 | .Dv TIOCMGET | |
4309 | ioctl, the tty device will switch all | |
984263bc | 4310 | carrier detection off when it detects that the device is a pty. |
984263bc MD |
4311 | .It PPPoE (netgraph) Devices |
4312 | Carrier is checked once per second for 5 seconds. | |
4313 | If it's not set after | |
4314 | the fifth second, the connection attempt is considered to have failed and | |
4315 | the device is closed. | |
4316 | Carrier is always required for PPPoE devices. | |
4317 | .El | |
4318 | .Pp | |
4319 | All other device types don't support carrier. | |
4320 | Setting a carrier value will | |
4321 | result in a warning when the device is opened. | |
4322 | .Pp | |
4323 | Some modems take more than one second after connecting to assert the carrier | |
4324 | signal. | |
4325 | If this delay isn't increased, this will result in | |
4326 | .Nm Ns No 's | |
4327 | inability to detect when the link is dropped, as | |
4328 | .Nm | |
4329 | assumes that the device isn't asserting carrier. | |
4330 | .Pp | |
4331 | The | |
4332 | .Dq set cd | |
4333 | command overrides the default carrier behaviour. | |
4334 | .Ar seconds | |
4335 | specifies the maximum number of seconds that | |
4336 | .Nm | |
4337 | should wait after the dial script has finished before deciding if | |
4338 | carrier is available or not. | |
4339 | .Pp | |
4340 | If | |
4341 | .Dq off | |
4342 | is specified, | |
4343 | .Nm | |
4344 | will not check for carrier on the device, otherwise | |
4345 | .Nm | |
4346 | will not proceed to the login script until either carrier is detected | |
4347 | or until | |
4348 | .Ar seconds | |
4349 | has elapsed, at which point | |
4350 | .Nm | |
4351 | assumes that the device will not set carrier. | |
4352 | .Pp | |
4353 | If no arguments are given, carrier settings will go back to their default | |
4354 | values. | |
4355 | .Pp | |
4356 | If | |
4357 | .Ar seconds | |
4358 | is followed immediately by an exclamation mark | |
4359 | .Pq Dq !\& , | |
4360 | .Nm | |
4361 | will | |
4362 | .Em require | |
4363 | carrier. | |
4364 | If carrier is not detected after | |
4365 | .Ar seconds | |
4366 | seconds, the link will be disconnected. | |
4367 | .It set choked Op Ar timeout | |
4368 | This sets the number of seconds that | |
4369 | .Nm | |
4370 | will keep a choked output queue before dropping all pending output packets. | |
4371 | If | |
4372 | .Ar timeout | |
4373 | is less than or equal to zero or if | |
4374 | .Ar timeout | |
4375 | isn't specified, it is set to the default value of | |
4376 | .Em 120 seconds . | |
4377 | .Pp | |
4378 | A choked output queue occurs when | |
4379 | .Nm | |
4380 | has read a certain number of packets from the local network for transmission, | |
4381 | but cannot send the data due to link failure (the peer is busy etc.). | |
4382 | .Nm | |
4383 | will not read packets indefinitely. | |
4384 | Instead, it reads up to | |
4385 | .Em 30 | |
4386 | packets (or | |
4387 | .Em 30 No + | |
4388 | .Em nlinks No * | |
4389 | .Em 2 | |
4390 | packets in multi-link mode), then stops reading the network interface | |
4391 | until either | |
4392 | .Ar timeout | |
4393 | seconds have passed or at least one packet has been sent. | |
4394 | .Pp | |
4395 | If | |
4396 | .Ar timeout | |
4397 | seconds pass, all pending output packets are dropped. | |
4398 | .It set ctsrts|crtscts on|off | |
4399 | This sets hardware flow control. | |
4400 | Hardware flow control is | |
4401 | .Ar on | |
4402 | by default. | |
4403 | .It set deflate Ar out-winsize Op Ar in-winsize | |
4404 | This sets the DEFLATE algorithms default outgoing and incoming window | |
4405 | sizes. | |
4406 | Both | |
4407 | .Ar out-winsize | |
4408 | and | |
4409 | .Ar in-winsize | |
4410 | must be values between | |
4411 | .Em 8 | |
4412 | and | |
4413 | .Em 15 . | |
4414 | If | |
4415 | .Ar in-winsize | |
4416 | is specified, | |
4417 | .Nm | |
4418 | will insist that this window size is used and will not accept any other | |
4419 | values from the peer. | |
4420 | .It set dns Op Ar primary Op Ar secondary | |
4421 | This command specifies DNS overrides for the | |
4422 | .Dq accept dns | |
4423 | command. | |
4424 | Refer to the | |
4425 | .Dq accept | |
4426 | command description above for details. | |
4427 | This command does not affect the IP numbers requested using | |
4428 | .Dq enable dns . | |
4429 | .It set device|line Xo | |
4430 | .Ar value Ns No ... | |
4431 | .Xc | |
4432 | This sets the device(s) to which | |
4433 | .Nm | |
4434 | will talk to the given | |
4435 | .Dq value . | |
4436 | .Pp | |
9118151a SW |
4437 | All serial device names are expected to begin with |
4438 | .Pa /dev/ | |
4439 | and are usually called | |
984263bc MD |
4440 | .Pa cuaXX . |
4441 | .Pp | |
4442 | If | |
4443 | .Dq value | |
4444 | does not begin with | |
4445 | .Pa /dev/ , | |
4446 | it must either begin with an exclamation mark | |
4447 | .Pq Dq !\& , | |
4448 | be of the format | |
4449 | .No PPPoE: Ns Ar iface Ns Xo | |
4450 | .Op \&: Ns Ar provider Ns | |
4451 | .Xc | |
4452 | (on | |
4453 | .Xr netgraph 4 | |
4454 | enabled systems), or be of the format | |
4455 | .Sm off | |
4456 | .Ar host : port Op /tcp|udp . | |
4457 | .Sm on | |
4458 | .Pp | |
4459 | If it begins with an exclamation mark, the rest of the device name is | |
4460 | treated as a program name, and that program is executed when the device | |
4461 | is opened. | |
4462 | Standard input, output and error are fed back to | |
4463 | .Nm | |
4464 | and are read and written as if they were a regular device. | |
4465 | .Pp | |
4466 | If a | |
4467 | .No PPPoE: Ns Ar iface Ns Xo | |
4468 | .Op \&: Ns Ar provider Ns | |
4469 | .Xc | |
4470 | specification is given, | |
4471 | .Nm | |
4472 | will attempt to create a | |
4473 | .Em PPP | |
4474 | over Ethernet connection using the given | |
4475 | .Ar iface | |
4476 | interface by using | |
4477 | .Xr netgraph 4 . | |
4478 | If | |
4479 | .Xr netgraph 4 | |
4480 | is not available, | |
4481 | .Nm | |
4482 | will attempt to load it using | |
4483 | .Xr kldload 2 . | |
4484 | If this fails, an external program must be used such as the | |
4485 | .Xr pppoe 8 | |
4486 | program available under | |
4487 | .Ox . | |
4488 | The given | |
4489 | .Ar provider | |
4490 | is passed as the service name in the PPPoE Discovery Initiation (PADI) | |
4491 | packet. | |
4492 | If no provider is given, an empty value will be used. | |
4493 | .Pp | |
4494 | When a PPPoE connection is established, | |
4495 | .Nm | |
4496 | will place the name of the Access Concentrator in the environment variable | |
4497 | .Ev ACNAME . | |
4498 | .Pp | |
4499 | Refer to | |
4500 | .Xr netgraph 4 | |
4501 | and | |
4502 | .Xr ng_pppoe 4 | |
4503 | for further details. | |
4504 | .Pp | |
4505 | If a | |
4506 | .Ar host Ns No : Ns Ar port Ns Oo | |
4507 | .No /tcp|udp | |
4508 | .Oc | |
4509 | specification is given, | |
4510 | .Nm | |
4511 | will attempt to connect to the given | |
4512 | .Ar host | |
4513 | on the given | |
4514 | .Ar port . | |
4515 | If a | |
4516 | .Dq /tcp | |
4517 | or | |
4518 | .Dq /udp | |
4519 | suffix is not provided, the default is | |
4520 | .Dq /tcp . | |
4521 | Refer to the section on | |
4522 | .Em PPP OVER TCP and UDP | |
4523 | above for further details. | |
4524 | .Pp | |
4525 | If multiple | |
4526 | .Dq values | |
4527 | are specified, | |
4528 | .Nm | |
4529 | will attempt to open each one in turn until it succeeds or runs out of | |
4530 | devices. | |
4531 | .It set dial Ar chat-script | |
4532 | This specifies the chat script that will be used to dial the other | |
4533 | side. | |
4534 | See also the | |
4535 | .Dq set login | |
4536 | command below. | |
4537 | Refer to | |
4538 | .Xr chat 8 | |
4539 | and to the example configuration files for details of the chat script | |
4540 | format. | |
4541 | It is possible to specify some special | |
4542 | .Sq values | |
4543 | in your chat script as follows: | |
4544 | .Bl -tag -width 2n | |
4545 | .It Li \ec | |
4546 | When used as the last character in a | |
4547 | .Sq send | |
4548 | string, this indicates that a newline should not be appended. | |
4549 | .It Li \ed | |
4550 | When the chat script encounters this sequence, it delays two seconds. | |
4551 | .It Li \ep | |
4552 | When the chat script encounters this sequence, it delays for one quarter of | |
4553 | a second. | |
4554 | .It Li \en | |
4555 | This is replaced with a newline character. | |
4556 | .It Li \er | |
4557 | This is replaced with a carriage return character. | |
4558 | .It Li \es | |
4559 | This is replaced with a space character. | |
4560 | .It Li \et | |
4561 | This is replaced with a tab character. | |
4562 | .It Li \eT | |
4563 | This is replaced by the current phone number (see | |
4564 | .Dq set phone | |
4565 | below). | |
4566 | .It Li \eP | |
4567 | This is replaced by the current | |
4568 | .Ar authkey | |
4569 | value (see | |
4570 | .Dq set authkey | |
4571 | above). | |
4572 | .It Li \eU | |
4573 | This is replaced by the current | |
4574 | .Ar authname | |
4575 | value (see | |
4576 | .Dq set authname | |
4577 | above). | |
4578 | .El | |
4579 | .Pp | |
4580 | Note that two parsers will examine these escape sequences, so in order to | |
4581 | have the | |
4582 | .Sq chat parser | |
4583 | see the escape character, it is necessary to escape it from the | |
4584 | .Sq command parser . | |
4585 | This means that in practice you should use two escapes, for example: | |
4586 | .Bd -literal -offset indent | |
4587 | set dial "... ATDT\\\\T CONNECT" | |
4588 | .Ed | |
4589 | .Pp | |
4590 | It is also possible to execute external commands from the chat script. | |
4591 | To do this, the first character of the expect or send string is an | |
4592 | exclamation mark | |
4593 | .Pq Dq !\& . | |
4594 | If a literal exclamation mark is required, double it up to | |
4595 | .Dq !!\& | |
4596 | and it will be treated as a single literal | |
4597 | .Dq !\& . | |
4598 | When the command is executed, standard input and standard output are | |
4599 | directed to the open device (see the | |
4600 | .Dq set device | |
4601 | command), and standard error is read by | |
4602 | .Nm | |
4603 | and substituted as the expect or send string. | |
4604 | If | |
4605 | .Nm | |
4606 | is running in interactive mode, file descriptor 3 is attached to | |
4607 | .Pa /dev/tty . | |
4608 | .Pp | |
4609 | For example (wrapped for readability): | |
4610 | .Bd -literal -offset indent | |
4611 | set login "TIMEOUT 5 \\"\\" \\"\\" login:--login: ppp \e | |
4612 | word: ppp \\"!sh \\\\-c \\\\\\"echo \\\\-n label: >&2\\\\\\"\\" \e | |
4613 | \\"!/bin/echo in\\" HELLO" | |
4614 | .Ed | |
4615 | .Pp | |
4616 | would result in the following chat sequence (output using the | |
4617 | .Sq set log local chat | |
4618 | command before dialing): | |
4619 | .Bd -literal -offset indent | |
4620 | Dial attempt 1 of 1 | |
4621 | dial OK! | |
4622 | Chat: Expecting: | |
4623 | Chat: Sending: | |
4624 | Chat: Expecting: login:--login: | |
4625 | Chat: Wait for (5): login: | |
4626 | Chat: Sending: ppp | |
4627 | Chat: Expecting: word: | |
4628 | Chat: Wait for (5): word: | |
4629 | Chat: Sending: ppp | |
4630 | Chat: Expecting: !sh \\-c "echo \\-n label: >&2" | |
4631 | Chat: Exec: sh -c "echo -n label: >&2" | |
4632 | Chat: Wait for (5): !sh \\-c "echo \\-n label: >&2" --> label: | |
4633 | Chat: Exec: /bin/echo in | |
4634 | Chat: Sending: | |
4635 | Chat: Expecting: HELLO | |
4636 | Chat: Wait for (5): HELLO | |
4637 | login OK! | |
4638 | .Ed | |
4639 | .Pp | |
4640 | Note (again) the use of the escape character, allowing many levels of | |
4641 | nesting. | |
4642 | Here, there are four parsers at work. | |
4643 | The first parses the original line, reading it as three arguments. | |
4644 | The second parses the third argument, reading it as 11 arguments. | |
4645 | At this point, it is | |
4646 | important that the | |
4647 | .Dq \&- | |
4648 | signs are escaped, otherwise this parser will see them as constituting | |
4649 | an expect-send-expect sequence. | |
4650 | When the | |
4651 | .Dq !\& | |
4652 | character is seen, the execution parser reads the first command as three | |
4653 | arguments, and then | |
4654 | .Xr sh 1 | |
4655 | itself expands the argument after the | |
4656 | .Fl c . | |
4657 | As we wish to send the output back to the modem, in the first example | |
4658 | we redirect our output to file descriptor 2 (stderr) so that | |
4659 | .Nm | |
4660 | itself sends and logs it, and in the second example, we just output to stdout, | |
4661 | which is attached directly to the modem. | |
4662 | .Pp | |
4663 | This, of course means that it is possible to execute an entirely external | |
4664 | .Dq chat | |
4665 | command rather than using the internal one. | |
4666 | See | |
4667 | .Xr chat 8 | |
4668 | for a good alternative. | |
4669 | .Pp | |
4670 | The external command that is executed is subjected to the same special | |
4671 | word expansions as the | |
4672 | .Dq !bg | |
4673 | command. | |
4674 | .It set enddisc Op label|IP|MAC|magic|psn value | |
4675 | This command sets our local endpoint discriminator. | |
4676 | If set prior to LCP negotiation, and if no | |
4677 | .Dq disable enddisc | |
4678 | command has been used, | |
4679 | .Nm | |
4680 | will send the information to the peer using the LCP endpoint discriminator | |
4681 | option. | |
4682 | The following discriminators may be set: | |
4683 | .Bl -tag -width indent | |
4684 | .It Li label | |
4685 | The current label is used. | |
4686 | .It Li IP | |
4687 | Our local IP number is used. | |
4688 | As LCP is negotiated prior to IPCP, it is | |
4689 | possible that the IPCP layer will subsequently change this value. | |
4690 | If | |
4691 | it does, the endpoint discriminator stays at the old value unless manually | |
4692 | reset. | |
4693 | .It Li MAC | |
4694 | This is similar to the | |
4695 | .Ar IP | |
4696 | option above, except that the MAC address associated with the local IP | |
4697 | number is used. | |
4698 | If the local IP number is not resident on any Ethernet | |
4699 | interface, the command will fail. | |
4700 | .Pp | |
4701 | As the local IP number defaults to whatever the machine host name is, | |
4702 | .Dq set enddisc mac | |
4703 | is usually done prior to any | |
4704 | .Dq set ifaddr | |
4705 | commands. | |
4706 | .It Li magic | |
4707 | A 20 digit random number is used. | |
4708 | Care should be taken when using magic numbers as restarting | |
4709 | .Nm | |
4710 | or creating a link using a different | |
4711 | .Nm | |
4712 | invocation will also use a different magic number and will therefore not | |
4713 | be recognised by the peer as belonging to the same bundle. | |
4714 | This makes it unsuitable for | |
4715 | .Fl direct | |
4716 | connections. | |
4717 | .It Li psn Ar value | |
4718 | The given | |
4719 | .Ar value | |
4720 | is used. | |
4721 | .Ar Value | |
4722 | should be set to an absolute public switched network number with the | |
4723 | country code first. | |
4724 | .El | |
4725 | .Pp | |
4726 | If no arguments are given, the endpoint discriminator is reset. | |
4727 | .It set escape Ar value... | |
4728 | This option is similar to the | |
4729 | .Dq set accmap | |
4730 | option above. | |
4731 | It allows the user to specify a set of characters that will be | |
4732 | .Sq escaped | |
4733 | as they travel across the link. | |
4734 | .It set filter dial|alive|in|out Ar rule-no Xo | |
4735 | .No permit|deny|clear| Ns Ar rule-no | |
4736 | .Op !\& | |
4737 | .Oo Op host | |
4738 | .Ar src_addr Ns Op / Ns Ar width | |
4739 | .Op Ar dst_addr Ns Op / Ns Ar width | |
4740 | .Oc [ Ns Ar proto | |
4741 | .Op src lt|eq|gt Ar port | |
4742 | .Op dst lt|eq|gt Ar port | |
4743 | .Op estab | |
4744 | .Op syn | |
4745 | .Op finrst | |
4746 | .Op timeout Ar secs ] | |
4747 | .Xc | |
4748 | .Nm | |
4749 | supports four filter sets. | |
4750 | The | |
4751 | .Em alive | |
4752 | filter specifies packets that keep the connection alive - resetting the | |
4753 | idle timer. | |
4754 | The | |
4755 | .Em dial | |
4756 | filter specifies packets that cause | |
4757 | .Nm | |
4758 | to dial when in | |
4759 | .Fl auto | |
4760 | mode. | |
4761 | The | |
4762 | .Em in | |
4763 | filter specifies packets that are allowed to travel | |
4764 | into the machine and the | |
4765 | .Em out | |
4766 | filter specifies packets that are allowed out of the machine. | |
4767 | .Pp | |
4768 | Filtering is done prior to any IP alterations that might be done by the | |
4769 | NAT engine on outgoing packets and after any IP alterations that might | |
4770 | be done by the NAT engine on incoming packets. | |
4771 | By default all empty filter sets allow all packets to pass. | |
4772 | Rules are processed in order according to | |
4773 | .Ar rule-no | |
4774 | (unless skipped by specifying a rule number as the | |
4775 | .Ar action ) . | |
4776 | Up to 40 rules may be given for each set. | |
4777 | If a packet doesn't match | |
4778 | any of the rules in a given set, it is discarded. | |
4779 | In the case of | |
4780 | .Em in | |
4781 | and | |
4782 | .Em out | |
4783 | filters, this means that the packet is dropped. | |
4784 | In the case of | |
4785 | .Em alive | |
4786 | filters it means that the packet will not reset the idle timer (even if | |
4787 | the | |
4788 | .Ar in Ns No / Ns Ar out | |
4789 | filter has a | |
4790 | .Dq timeout | |
4791 | value) and in the case of | |
4792 | .Em dial | |
4793 | filters it means that the packet will not trigger a dial. | |
4794 | A packet failing to trigger a dial will be dropped rather than queued. | |
4795 | Refer to the | |
4796 | section on | |
4797 | .Sx PACKET FILTERING | |
4798 | above for further details. | |
4799 | .It set hangup Ar chat-script | |
4800 | This specifies the chat script that will be used to reset the device | |
4801 | before it is closed. | |
4802 | It should not normally be necessary, but can | |
4803 | be used for devices that fail to reset themselves properly on close. | |
4804 | .It set help|? Op Ar command | |
4805 | This command gives a summary of available set commands, or if | |
4806 | .Ar command | |
4807 | is specified, the command usage is shown. | |
4808 | .It set ifaddr Oo Ar myaddr Ns | |
4809 | .Op / Ns Ar \&nn | |
4810 | .Oo Ar hisaddr Ns Op / Ns Ar \&nn | |
4811 | .Oo Ar netmask | |
4812 | .Op Ar triggeraddr | |
4813 | .Oc Oc | |
4814 | .Oc | |
4815 | This command specifies the IP addresses that will be used during | |
4816 | IPCP negotiation. | |
4817 | Addresses are specified using the format | |
4818 | .Pp | |
4819 | .Dl a.b.c.d/nn | |
4820 | .Pp | |
4821 | Where | |
4822 | .Dq a.b.c.d | |
4823 | is the preferred IP, but | |
4824 | .Ar nn | |
4825 | specifies how many bits of the address we will insist on. | |
4826 | If | |
4827 | .No / Ns Ar nn | |
4828 | is omitted, it defaults to | |
4829 | .Dq /32 | |
4830 | unless the IP address is 0.0.0.0 in which case it defaults to | |
4831 | .Dq /0 . | |
4832 | .Pp | |
4833 | If you wish to assign a dynamic IP number to the peer, | |
4834 | .Ar hisaddr | |
4835 | may also be specified as a range of IP numbers in the format | |
4836 | .Bd -ragged -offset indent | |
bc536631 SW |
4837 | .Sm off |
4838 | .Ar \&IP Oo \&- Ar \&IP Oc Oo , | |
4839 | .Ar \&IP Oo \&- Ar \&IP Oc Oc ... | |
4840 | .Sm on | |
984263bc MD |
4841 | .Ed |
4842 | .Pp | |
4843 | for example: | |
4844 | .Pp | |
4845 | .Dl set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20 | |
4846 | .Pp | |
4847 | will only negotiate | |
4848 | .Dq 10.0.0.1 | |
4849 | as the local IP number, but may assign any of the given 10 IP | |
4850 | numbers to the peer. | |
4851 | If the peer requests one of these numbers, | |
4852 | and that number is not already in use, | |
4853 | .Nm | |
4854 | will grant the peers request. | |
4855 | This is useful if the peer wants | |
4856 | to re-establish a link using the same IP number as was previously | |
4857 | allocated (thus maintaining any existing tcp or udp connections). | |
4858 | .Pp | |
4859 | If the peer requests an IP number that's either outside | |
4860 | of this range or is already in use, | |
4861 | .Nm | |
4862 | will suggest a random unused IP number from the range. | |
4863 | .Pp | |
4864 | If | |
4865 | .Ar triggeraddr | |
4866 | is specified, it is used in place of | |
4867 | .Ar myaddr | |
4868 | in the initial IPCP negotiation. | |
4869 | However, only an address in the | |
4870 | .Ar myaddr | |
4871 | range will be accepted. | |
4872 | This is useful when negotiating with some | |
4873 | .Dv PPP | |
4874 | implementations that will not assign an IP number unless their peer | |
4875 | requests | |
4876 | .Dq 0.0.0.0 . | |
4877 | .Pp | |
4878 | It should be noted that in | |
4879 | .Fl auto | |
4880 | mode, | |
4881 | .Nm | |
4882 | will configure the interface immediately upon reading the | |
4883 | .Dq set ifaddr | |
4884 | line in the config file. | |
4885 | In any other mode, these values are just | |
4886 | used for IPCP negotiations, and the interface isn't configured | |
4887 | until the IPCP layer is up. | |
4888 | .Pp | |
4889 | Note that the | |
4890 | .Ar HISADDR | |
4891 | argument may be overridden by the third field in the | |
4892 | .Pa ppp.secret | |
4893 | file once the client has authenticated itself | |
4894 | (if PAP or CHAP are | |
4895 | .Dq enabled ) . | |
4896 | Refer to the | |
4897 | .Sx AUTHENTICATING INCOMING CONNECTIONS | |
4898 | section for details. | |
4899 | .Pp | |
4900 | In all cases, if the interface is already configured, | |
4901 | .Nm | |
4902 | will try to maintain the interface IP numbers so that any existing | |
4903 | bound sockets will remain valid. | |
4904 | .It set ifqueue Ar packets | |
4905 | Set the maximum number of packets that | |
4906 | .Nm | |
4907 | will read from the tunnel interface while data cannot be sent to any of | |
4908 | the available links. | |
4909 | This queue limit is necessary to flow control outgoing data as the tunnel | |
4910 | interface is likely to be far faster than the combined links available to | |
4911 | .Nm . | |
4912 | .Pp | |
4913 | If | |
4914 | .Ar packets | |
4915 | is set to a value less than the number of links, | |
4916 | .Nm | |
4917 | will read up to that value regardless. | |
4918 | This prevents any possible latency problems. | |
4919 | .Pp | |
4920 | The default value for | |
4921 | .Ar packets | |
4922 | is | |
4923 | .Dq 30 . | |
4924 | .It set ccpretry|ccpretries Oo Ar timeout | |
4925 | .Op Ar reqtries Op Ar trmtries | |
4926 | .Oc | |
4927 | .It set chapretry|chapretries Oo Ar timeout | |
4928 | .Op Ar reqtries | |
4929 | .Oc | |
4930 | .It set ipcpretry|ipcpretries Oo Ar timeout | |
4931 | .Op Ar reqtries Op Ar trmtries | |
4932 | .Oc | |
4933 | .It set ipv6cpretry|ipv6cpretries Oo Ar timeout | |
4934 | .Op Ar reqtries Op Ar trmtries | |
4935 | .Oc | |
4936 | .It set lcpretry|lcpretries Oo Ar timeout | |
4937 | .Op Ar reqtries Op Ar trmtries | |
4938 | .Oc | |
4939 | .It set papretry|papretries Oo Ar timeout | |
4940 | .Op Ar reqtries | |
4941 | .Oc | |
4942 | These commands set the number of seconds that | |
4943 | .Nm | |
4944 | will wait before resending Finite State Machine (FSM) Request packets. | |
4945 | The default | |
4946 | .Ar timeout | |
4947 | for all FSMs is 3 seconds (which should suffice in most cases). | |
4948 | .Pp | |
4949 | If | |
4950 | .Ar reqtries | |
4951 | is specified, it tells | |
4952 | .Nm | |
4953 | how many configuration request attempts it should make while receiving | |
4954 | no reply from the peer before giving up. | |
4955 | The default is 5 attempts for | |
4956 | CCP, LCP and IPCP and 3 attempts for PAP and CHAP. | |
4957 | .Pp | |
4958 | If | |
4959 | .Ar trmtries | |
4960 | is specified, it tells | |
4961 | .Nm | |
4962 | how many terminate requests should be sent before giving up waiting for the | |
4963 | peers response. | |
4964 | The default is 3 attempts. | |
4965 | Authentication protocols are | |
4966 | not terminated and it is therefore invalid to specify | |
4967 | .Ar trmtries | |
4968 | for PAP or CHAP. | |
4969 | .Pp | |
4970 | In order to avoid negotiations with the peer that will never converge, | |
4971 | .Nm | |
4972 | will only send at most 3 times the configured number of | |
4973 | .Ar reqtries | |
4974 | in any given negotiation session before giving up and closing that layer. | |
4975 | .It set log Xo | |
4976 | .Op local | |
4977 | .Op +|- Ns | |
4978 | .Ar value Ns No ... | |
4979 | .Xc | |
4980 | This command allows the adjustment of the current log level. | |
4981 | Refer to the Logging Facility section for further details. | |
4982 | .It set login Ar chat-script | |
4983 | This | |
4984 | .Ar chat-script | |
1a0c0988 | 4985 | complements the dial-script. |
984263bc MD |
4986 | If both are specified, the login |
4987 | script will be executed after the dial script. | |
4988 | Escape sequences available in the dial script are also available here. | |
4989 | .It set logout Ar chat-script | |
4990 | This specifies the chat script that will be used to logout | |
4991 | before the hangup script is called. | |
4992 | It should not normally be necessary. | |
4993 | .It set lqrperiod Ar frequency | |
4994 | This command sets the | |
4995 | .Ar frequency | |
4996 | in seconds at which | |
4997 | .Em LQR | |
4998 | or | |
4999 | .Em ECHO LQR | |
5000 | packets are sent. | |
5001 | The default is 30 seconds. | |
5002 | You must also use the | |
5003 | .Dq enable lqr | |
5004 | command if you wish to send LQR requests to the peer. | |
5005 | .It set mode Ar interactive|auto|ddial|background | |
5006 | This command allows you to change the | |
5007 | .Sq mode | |
5008 | of the specified link. | |
5009 | This is normally only useful in multi-link mode, | |
5010 | but may also be used in uni-link mode. | |
5011 | .Pp | |
5012 | It is not possible to change a link that is | |
5013 | .Sq direct | |
5014 | or | |
5015 | .Sq dedicated . | |
5016 | .Pp | |
5017 | Note: If you issue the command | |
5018 | .Dq set mode auto , | |
5019 | and have network address translation enabled, it may be useful to | |
5020 | .Dq enable iface-alias | |
5021 | afterwards. | |
5022 | This will allow | |
5023 | .Nm | |
5024 | to do the necessary address translations to enable the process that | |
5025 | triggers the connection to connect once the link is up despite the | |
5026 | peer assigning us a new (dynamic) IP address. | |
5027 | .It set mppe Op 40|56|128|* Op stateless|stateful|* | |
5028 | This option selects the encryption parameters used when negotiation | |
5029 | MPPE. | |
5030 | MPPE can be disabled entirely with the | |
5031 | .Dq disable mppe | |
5032 | command. | |
5033 | If no arguments are given, | |
5034 | .Nm | |
5035 | will attempt to negotiate a stateful link with a 128 bit key, but | |
5036 | will agree to whatever the peer requests (including no encryption | |
5037 | at all). | |
5038 | .Pp | |
5039 | If any arguments are given, | |
5040 | .Nm | |
5041 | will | |
5042 | .Em insist | |
5043 | on using MPPE and will close the link if it's rejected by the peer (Note; | |
5044 | this behaviour can be overridden by a configured RADIUS server). | |
5045 | .Pp | |
5046 | The first argument specifies the number of bits that | |
5047 | .Nm | |
5048 | should insist on during negotiations and the second specifies whether | |
5049 | .Nm | |
5050 | should insist on stateful or stateless mode. | |
5051 | In stateless mode, the | |
5052 | encryption dictionary is re-initialised with every packet according to | |
5053 | an encryption key that is changed with every packet. | |
5054 | In stateful mode, | |
5055 | the encryption dictionary is re-initialised every 256 packets or after | |
5056 | the loss of any data and the key is changed every 256 packets. | |
5057 | Stateless mode is less efficient but is better for unreliable transport | |
5058 | layers. | |
5059 | .It set mrru Op Ar value | |
5060 | Setting this option enables Multi-link PPP negotiations, also known as | |
5061 | Multi-link Protocol or MP. | |
5062 | There is no default MRRU (Maximum Reconstructed Receive Unit) value. | |
5063 | If no argument is given, multi-link mode is disabled. | |
5064 | .It set mru Xo | |
5065 | .Op max Ns Op imum | |
5066 | .Op Ar value | |
5067 | .Xc | |
5068 | The default MRU (Maximum Receive Unit) is 1500. | |
5069 | If it is increased, the other side *may* increase its MTU. | |
5070 | In theory there is no point in decreasing the MRU to below the default as the | |
5071 | .Em PPP | |
5072 | protocol says implementations *must* be able to accept packets of at | |
5073 | least 1500 octets. | |
5074 | .Pp | |
5075 | If the | |
5076 | .Dq maximum | |
5077 | keyword is used, | |
5078 | .Nm | |
5079 | will refuse to negotiate a higher value. | |
5080 | The maximum MRU can be set to 2048 at most. | |
5081 | Setting a maximum of less than 1500 violates the | |
5082 | .Em PPP | |
5083 | rfc, but may sometimes be necessary. | |
5084 | For example, | |
5085 | .Em PPPoE | |
5086 | imposes a maximum of 1492 due to hardware limitations. | |
5087 | .Pp | |
5088 | If no argument is given, 1500 is assumed. | |
5089 | A value must be given when | |
5090 | .Dq maximum | |
5091 | is specified. | |
5092 | .It set mtu Xo | |
5093 | .Op max Ns Op imum | |
5094 | .Op Ar value | |
5095 | .Xc | |
5096 | The default MTU is 1500. | |
5097 | At negotiation time, | |
5098 | .Nm | |
5099 | will accept whatever MRU the peer requests (assuming it's | |
5100 | not less than 296 bytes or greater than the assigned maximum). | |
5101 | If the MTU is set, | |
5102 | .Nm | |
5103 | will not accept MRU values less than | |
5104 | .Ar value . | |
5105 | When negotiations are complete, the MTU is used when writing to the | |
5106 | interface, even if the peer requested a higher value MRU. | |
5107 | This can be useful for | |
5108 | limiting your packet size (giving better bandwidth sharing at the expense | |
5109 | of more header data). | |
5110 | .Pp | |
5111 | If the | |
5112 | .Dq maximum | |
5113 | keyword is used, | |
5114 | .Nm | |
5115 | will refuse to negotiate a higher value. | |
5116 | The maximum MTU can be set to 2048 at most. | |
5117 | .Pp | |
5118 | If no | |
5119 | .Ar value | |
5120 | is given, 1500, or whatever the peer asks for is used. | |
5121 | A value must be given when | |
5122 | .Dq maximum | |
5123 | is specified. | |
5124 | .It set nbns Op Ar x.x.x.x Op Ar y.y.y.y | |
5125 | This option allows the setting of the Microsoft NetBIOS name server | |
5126 | values to be returned at the peers request. | |
5127 | If no values are given, | |
5128 | .Nm | |
5129 | will reject any such requests. | |
5130 | .It set openmode active|passive Op Ar delay | |
5131 | By default, | |
5132 | .Ar openmode | |
5133 | is always | |
5134 | .Ar active | |
5135 | with a one second | |
5136 | .Ar delay . | |
5137 | That is, | |
5138 | .Nm | |
5139 | will always initiate LCP/IPCP/CCP negotiation one second after the line | |
5140 | comes up. | |
5141 | If you want to wait for the peer to initiate negotiations, you | |
5142 | can use the value | |
5143 | .Ar passive . | |
5144 | If you want to initiate negotiations immediately or after more than one | |
5145 | second, the appropriate | |
5146 | .Ar delay | |
5147 | may be specified here in seconds. | |
5148 | .It set parity odd|even|none|mark | |
5149 | This allows the line parity to be set. | |
5150 | The default value is | |
5151 | .Ar none . | |
5152 | .It set phone Ar telno Ns Xo | |
5153 | .Oo \&| Ns Ar backupnumber | |
5154 | .Oc Ns ... Ns Oo : Ns Ar nextnumber | |
5155 | .Oc Ns ... | |
5156 | .Xc | |
5157 | This allows the specification of the phone number to be used in | |
5158 | place of the \\\\T string in the dial and login chat scripts. | |
5159 | Multiple phone numbers may be given separated either by a pipe | |
5160 | .Pq Dq \&| | |
5161 | or a colon | |
5162 | .Pq Dq \&: . | |
5163 | .Pp | |
5164 | Numbers after the pipe are only dialed if the dial or login | |
5165 | script for the previous number failed. | |
5166 | .Pp | |
5167 | Numbers after the colon are tried sequentially, irrespective of | |
5168 | the reason the line was dropped. | |
5169 | .Pp | |
5170 | If multiple numbers are given, | |
5171 | .Nm | |
5172 | will dial them according to these rules until a connection is made, retrying | |
5173 | the maximum number of times specified by | |
5174 | .Dq set redial | |
5175 | below. | |
5176 | In | |
5177 | .Fl background | |
5178 | mode, each number is attempted at most once. | |
bc536631 SW |
5179 | .It Ic set Oo Ic proc Oc Ns Xo |
5180 | .Ic title Op Ar value | |
984263bc MD |
5181 | .Xc |
5182 | The current process title as displayed by | |
5183 | .Xr ps 1 | |
5184 | is changed according to | |
5185 | .Ar value . | |
5186 | If | |
5187 | .Ar value | |
5188 | is not specified, the original process title is restored. | |
5189 | All the | |
5190 | word replacements done by the shell commands (see the | |
5191 | .Dq bg | |
5192 | command above) are done here too. | |
5193 | .Pp | |
5194 | Note, if USER is required in the process title, the | |
5195 | .Dq set proctitle | |
5196 | command must appear in | |
5197 | .Pa ppp.linkup , | |
5198 | as it is not known when the commands in | |
5199 | .Pa ppp.conf | |
5200 | are executed. | |
5201 | .It set radius Op Ar config-file | |
5202 | This command enables RADIUS support (if it's compiled in). | |
5203 | .Ar config-file | |
49d37166 | 5204 | refers to the radius client configuration file. |
984263bc MD |
5205 | If PAP, CHAP, MSCHAP or MSCHAPv2 are |
5206 | .Dq enable Ns No d , | |
5207 | .Nm | |
5208 | behaves as a | |
5209 | .Em \&N Ns No etwork | |
5210 | .Em \&A Ns No ccess | |
5211 | .Em \&S Ns No erver | |
5212 | and uses the configured RADIUS server to authenticate rather than | |
5213 | authenticating from the | |
5214 | .Pa ppp.secret | |
5215 | file or from the passwd database. | |
5216 | .Pp | |
5217 | If none of PAP, CHAP, MSCHAP or MSCHAPv2 are enabled, | |
5218 | .Dq set radius | |
5219 | will do nothing. | |
5220 | .Pp | |
5221 | .Nm | |
5222 | uses the following attributes from the RADIUS reply: | |
5223 | .Bl -tag -width XXX -offset XXX | |
5224 | .It RAD_FRAMED_IP_ADDRESS | |
5225 | The peer IP address is set to the given value. | |
5226 | .It RAD_FRAMED_IP_NETMASK | |
5227 | The tun interface netmask is set to the given value. | |
5228 | .It RAD_FRAMED_MTU | |
5229 | If the given MTU is less than the peers MRU as agreed during LCP | |
dda92f98 | 5230 | negotiation, *and* it is less than any configured MTU (see the |
984263bc MD |
5231 | .Dq set mru |
5232 | command), the tun interface MTU is set to the given value. | |
5233 | .It RAD_FRAMED_COMPRESSION | |
5234 | If the received compression type is | |
5235 | .Dq 1 , | |
5236 | .Nm | |
5237 | will request VJ compression during IPCP negotiations despite any | |
5238 | .Dq disable vj | |
5239 | configuration command. | |
5240 | .It RAD_FILTER_ID | |
5241 | If this attribute is supplied, | |
5242 | .Nm | |
5243 | will attempt to use it as an additional label to load from the | |
5244 | .Pa ppp.linkup | |
5245 | and | |
5246 | .Pa ppp.linkdown | |
5247 | files. | |
5248 | The load will be attempted before (and in addition to) the normal | |
5249 | label search. | |
5250 | If the label doesn't exist, no action is taken and | |
5251 | .Nm | |
5252 | proceeds to the normal load using the current label. | |
5253 | .It RAD_FRAMED_ROUTE | |
5254 | The received string is expected to be in the format | |
5255 | .Ar dest Ns Op / Ns Ar bits | |
5256 | .Ar gw | |
5257 | .Op Ar metrics . | |
5258 | Any specified metrics are ignored. | |
5259 | .Dv MYADDR | |
5260 | and | |
5261 | .Dv HISADDR | |
5262 | are understood as valid values for | |
5263 | .Ar dest | |
5264 | and | |
5265 | .Ar gw , | |
5266 | .Dq default | |
5267 | can be used for | |
5268 | .Ar dest | |
3f5e28f4 | 5269 | to specify the default route, and |
984263bc MD |
5270 | .Dq 0.0.0.0 |
5271 | is understood to be the same as | |
5272 | .Dq default | |
5273 | for | |
5274 | .Ar dest | |
5275 | and | |
5276 | .Dv HISADDR | |
5277 | for | |
5278 | .Ar gw . | |
5279 | .Pp | |
5280 | For example, a returned value of | |
5281 | .Dq 1.2.3.4/24 0.0.0.0 1 2 -1 3 400 | |
5282 | would result in a routing table entry to the 1.2.3.0/24 network via | |
5283 | .Dv HISADDR | |
5284 | and a returned value of | |
5285 | .Dq 0.0.0.0 0.0.0.0 | |
5286 | or | |
5287 | .Dq default HISADDR | |
5288 | would result in a default route to | |
5289 | .Dv HISADDR . | |
5290 | .Pp | |
5291 | All RADIUS routes are applied after any sticky routes are applied, making | |
5292 | RADIUS routes override configured routes. | |
5293 | This also applies for RADIUS routes that don't {include} the | |
5294 | .Dv MYADDR | |
5295 | or | |
5296 | .Dv HISADDR | |
5297 | keywords. | |
984263bc MD |
5298 | .It RAD_SESSION_TIMEOUT |
5299 | If supplied, the client connection is closed after the given number of | |
5300 | seconds. | |
5301 | .It RAD_REPLY_MESSAGE | |
5302 | If supplied, this message is passed back to the peer as the authentication | |
5303 | SUCCESS text. | |
5304 | .It RAD_MICROSOFT_MS_CHAP_ERROR | |
5305 | If this | |
5306 | .Dv RAD_VENDOR_MICROSOFT | |
5307 | vendor specific attribute is supplied, it is passed back to the peer as the | |
5308 | authentication FAILURE text. | |
5309 | .It RAD_MICROSOFT_MS_CHAP2_SUCCESS | |
5310 | If this | |
5311 | .Dv RAD_VENDOR_MICROSOFT | |
5312 | vendor specific attribute is supplied and if MS-CHAPv2 authentication is | |
5313 | being used, it is passed back to the peer as the authentication SUCCESS text. | |
5314 | .It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY | |
5315 | If this | |
5316 | .Dv RAD_VENDOR_MICROSOFT | |
5317 | vendor specific attribute is supplied and has a value of 2 (Required), | |
5318 | .Nm | |
5319 | will insist that MPPE encryption is used (even if no | |
5320 | .Dq set mppe | |
5321 | configuration command has been given with arguments). | |
5322 | If it is supplied with a value of 1 (Allowed), encryption is made optional | |
5323 | (despite any | |
5324 | .Dq set mppe | |
5325 | configuration commands with arguments). | |
5326 | .It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES | |
5327 | If this | |
5328 | .Dv RAD_VENDOR_MICROSOFT | |
5329 | vendor specific attribute is supplied, bits 1 and 2 are examined. | |
5330 | If either or both are set, 40 bit and/or 128 bit (respectively) encryption | |
5331 | options are set, overriding any given first argument to the | |
5332 | .Dq set mppe | |
5333 | command. | |
5334 | Note, it is not currently possible for the RADIUS server to specify 56 bit | |
5335 | encryption. | |
5336 | .It RAD_MICROSOFT_MS_MPPE_RECV_KEY | |
5337 | If this | |
5338 | .Dv RAD_VENDOR_MICROSOFT | |
a42bad2d | 5339 | vendor specific attribute is supplied, its value is used as the master |
984263bc MD |
5340 | key for decryption of incoming data. When clients are authenticated using |
5341 | MSCHAPv2, the RADIUS server MUST provide this attribute if inbound MPPE is | |
5342 | to function. | |
5343 | .It RAD_MICROSOFT_MS_MPPE_SEND_KEY | |
5344 | If this | |
5345 | .Dv RAD_VENDOR_MICROSOFT | |
a42bad2d | 5346 | vendor specific attribute is supplied, its value is used as the master |
984263bc MD |
5347 | key for encryption of outgoing data. When clients are authenticated using |
5348 | MSCHAPv2, the RADIUS server MUST provide this attribute if outbound MPPE is | |
5349 | to function. | |
5350 | .El | |
5351 | .Pp | |
5352 | Values received from the RADIUS server may be viewed using | |
5353 | .Dq show bundle . | |
5354 | .It set reconnect Ar timeout ntries | |
5355 | Should the line drop unexpectedly (due to loss of CD or LQR | |
5356 | failure), a connection will be re-established after the given | |
5357 | .Ar timeout . | |
5358 | The line will be re-connected at most | |
5359 | .Ar ntries | |
5360 | times. | |
5361 | .Ar Ntries | |
5362 | defaults to zero. | |
5363 | A value of | |
5364 | .Ar random | |
5365 | for | |
5366 | .Ar timeout | |
5367 | will result in a variable pause, somewhere between 1 and 30 seconds. | |
5368 | .It set recvpipe Op Ar value | |
5369 | This sets the routing table RECVPIPE value. | |
5370 | The optimum value is just over twice the MTU value. | |
5371 | If | |
5372 | .Ar value | |
5373 | is unspecified or zero, the default kernel controlled value is used. | |
5374 | .It set redial Ar secs Ns Xo | |
5375 | .Oo + Ns Ar inc Ns | |
5376 | .Op - Ns Ar max Ns | |
5377 | .Oc Ns Op . Ns Ar next | |
5378 | .Op Ar attempts | |
5379 | .Xc | |
5380 | .Nm | |
5381 | can be instructed to attempt to redial | |
5382 | .Ar attempts | |
5383 | times. | |
5384 | If more than one phone number is specified (see | |
5385 | .Dq set phone | |
5386 | above), a pause of | |
5387 | .Ar next | |
5388 | is taken before dialing each number. | |
5389 | A pause of | |
5390 | .Ar secs | |
5391 | is taken before starting at the first number again. | |
5392 | A literal value of | |
5393 | .Dq Li random | |
5394 | may be used here in place of | |
5395 | .Ar secs | |
5396 | and | |
5397 | .Ar next , | |
5398 | causing a random delay of between 1 and 30 seconds. | |
5399 | .Pp | |
5400 | If | |
5401 | .Ar inc | |
5402 | is specified, its value is added onto | |
5403 | .Ar secs | |
5404 | each time | |
5405 | .Nm | |
5406 | tries a new number. | |
5407 | .Ar secs | |
5408 | will only be incremented at most | |
5409 | .Ar max | |
5410 | times. | |
5411 | .Ar max | |
5412 | defaults to 10. | |
5413 | .Pp | |
5414 | Note, the | |
5415 | .Ar secs | |
5416 | delay will be effective, even after | |
5417 | .Ar attempts | |
5418 | has been exceeded, so an immediate manual dial may appear to have | |
5419 | done nothing. | |
5420 | If an immediate dial is required, a | |
5421 | .Dq !\& | |
5422 | should immediately follow the | |
5423 | .Dq open | |
5424 | keyword. | |
5425 | See the | |
5426 | .Dq open | |
5427 | description above for further details. | |
5428 | .It set sendpipe Op Ar value | |
5429 | This sets the routing table SENDPIPE value. | |
5430 | The optimum value is just over twice the MTU value. | |
5431 | If | |
5432 | .Ar value | |
5433 | is unspecified or zero, the default kernel controlled value is used. | |
5434 | .It "set server|socket" Ar TcpPort Ns No \&| Ns Xo | |
5435 | .Ar LocalName Ns No |none|open|closed | |
5436 | .Op password Op Ar mask | |
5437 | .Xc | |
5438 | This command tells | |
5439 | .Nm | |
5440 | to listen on the given socket or | |
5441 | .Sq diagnostic port | |
5442 | for incoming command connections. | |
5443 | .Pp | |
5444 | The word | |
5445 | .Dq none | |
5446 | instructs | |
5447 | .Nm | |
5448 | to close any existing socket and clear the socket configuration. | |
5449 | The word | |
5450 | .Dq open | |
5451 | instructs | |
5452 | .Nm | |
5453 | to attempt to re-open the port. | |
5454 | The word | |
5455 | .Dq closed | |
5456 | instructs | |
5457 | .Nm | |
5458 | to close the open port. | |
5459 | .Pp | |
5460 | If you wish to specify a local domain socket, | |
5461 | .Ar LocalName | |
5462 | must be specified as an absolute file name, otherwise it is assumed | |
5463 | to be the name or number of a TCP port. | |
5464 | You may specify the octal umask to be used with a local domain socket. | |
5465 | Refer to | |
5466 | .Xr umask 2 | |
5467 | for umask details. | |
5468 | Refer to | |
5469 | .Xr services 5 | |
5470 | for details of how to translate TCP port names. | |
5471 | .Pp | |
5472 | You must also specify the password that must be entered by the client | |
5473 | (using the | |
5474 | .Dq passwd | |
5475 | variable above) when connecting to this socket. | |
5476 | If the password is | |
5477 | specified as an empty string, no password is required for connecting clients. | |
5478 | .Pp | |
5479 | When specifying a local domain socket, the first | |
5480 | .Dq %d | |
5481 | sequence found in the socket name will be replaced with the current | |
5482 | interface unit number. | |
5483 | This is useful when you wish to use the same | |
5484 | profile for more than one connection. | |
5485 | .Pp | |
5486 | In a similar manner TCP sockets may be prefixed with the | |
5487 | .Dq + | |
5488 | character, in which case the current interface unit number is added to | |
5489 | the port number. | |
5490 | .Pp | |
5491 | When using | |
5492 | .Nm | |
5493 | with a server socket, the | |
5494 | .Xr pppctl 8 | |
5495 | command is the preferred mechanism of communications. | |
5496 | Currently, | |
5497 | .Xr telnet 1 | |
5498 | can also be used, but link encryption may be implemented in the future, so | |
5499 | .Xr telnet 1 | |
5500 | should be avoided. | |
5501 | .Pp | |
5502 | Note; | |
5503 | .Dv SIGUSR1 | |
5504 | and | |
5505 | .Dv SIGUSR2 | |
5506 | interact with the diagnostic socket. | |
5507 | .It set speed Ar value | |
5508 | This sets the speed of the serial device. | |
5509 | If speed is specified as | |
5510 | .Dq sync , | |
5511 | .Nm | |
5512 | treats the device as a synchronous device. | |
5513 | .Pp | |
5514 | Certain device types will know whether they should be specified as | |
5515 | synchronous or asynchronous. | |
5516 | These devices will override incorrect | |
5517 | settings and log a warning to this effect. | |
5518 | .It set stopped Op Ar LCPseconds Op Ar CCPseconds | |
5519 | If this option is set, | |
5520 | .Nm | |
5521 | will time out after the given FSM (Finite State Machine) has been in | |
5522 | the stopped state for the given number of | |
5523 | .Dq seconds . | |
5524 | This option may be useful if the peer sends a terminate request, | |
5525 | but never actually closes the connection despite our sending a terminate | |
5526 | acknowledgement. | |
5527 | This is also useful if you wish to | |
5528 | .Dq set openmode passive | |
5529 | and time out if the peer doesn't send a Configure Request within the | |
5530 | given time. | |
5531 | Use | |
5532 | .Dq set log +lcp +ccp | |
5533 | to make | |
5534 | .Nm | |
5535 | log the appropriate state transitions. | |
5536 | .Pp | |
5537 | The default value is zero, where | |
5538 | .Nm | |
5539 | doesn't time out in the stopped state. | |
5540 | .Pp | |
5541 | This value should not be set to less than the openmode delay (see | |
5542 | .Dq set openmode | |
5543 | above). | |
5544 | .It set timeout Ar idleseconds Op Ar mintimeout | |
5545 | This command allows the setting of the idle timer. | |
5546 | Refer to the section titled | |
5547 | .Sx SETTING THE IDLE TIMER | |
5548 | for further details. | |
5549 | .Pp | |
5550 | If | |
5551 | .Ar mintimeout | |
5552 | is specified, | |
5553 | .Nm | |
5554 | will never idle out before the link has been up for at least that number | |
5555 | of seconds. | |
5556 | .It set urgent Xo | |
5557 | .Op tcp|udp|none | |
5558 | .Oo Op +|- Ns | |
5559 | .Ar port | |
5560 | .Oc No ... | |
5561 | .Xc | |
5562 | This command controls the ports that | |
5563 | .Nm | |
5564 | prioritizes when transmitting data. | |
5565 | The default priority TCP ports | |
5566 | are ports 21 (ftp control), 22 (ssh), 23 (telnet), 513 (login), 514 (shell), | |
5567 | 543 (klogin) and 544 (kshell). | |
5568 | There are no priority UDP ports by default. | |
5569 | See | |
5570 | .Xr services 5 | |
5571 | for details. | |
5572 | .Pp | |
5573 | If neither | |
5574 | .Dq tcp | |
5575 | or | |
5576 | .Dq udp | |
5577 | are specified, | |
5578 | .Dq tcp | |
5579 | is assumed. | |
5580 | .Pp | |
5581 | If no | |
5582 | .Ar port Ns No s | |
5583 | are given, the priority port lists are cleared (although if | |
5584 | .Dq tcp | |
5585 | or | |
5586 | .Dq udp | |
5587 | is specified, only that list is cleared). | |
5588 | If the first | |
5589 | .Ar port | |
5590 | argument is prefixed with a plus | |
5591 | .Pq Dq \&+ | |
5592 | or a minus | |
5593 | .Pq Dq \&- , | |
5594 | the current list is adjusted, otherwise the list is reassigned. | |
5595 | .Ar port Ns No s | |
5596 | prefixed with a plus or not prefixed at all are added to the list and | |
5597 | .Ar port Ns No s | |
5598 | prefixed with a minus are removed from the list. | |
5599 | .Pp | |
5600 | If | |
5601 | .Dq none | |
5602 | is specified, all priority port lists are disabled and even | |
5603 | .Dv IPTOS_LOWDELAY | |
5604 | packets are not prioritised. | |
5605 | .It set vj slotcomp on|off | |
5606 | This command tells | |
5607 | .Nm | |
5608 | whether it should attempt to negotiate VJ slot compression. | |
5609 | By default, slot compression is turned | |
5610 | .Ar on . | |
5611 | .It set vj slots Ar nslots | |
5612 | This command sets the initial number of slots that | |
5613 | .Nm | |
5614 | will try to negotiate with the peer when VJ compression is enabled (see the | |
5615 | .Sq enable | |
5616 | command above). | |
5617 | It defaults to a value of 16. | |
5618 | .Ar Nslots | |
5619 | must be between | |
5620 | .Ar 4 | |
5621 | and | |
5622 | .Ar 16 | |
5623 | inclusive. | |
5624 | .El | |
984263bc MD |
5625 | .It shell|! Op Ar command |
5626 | If | |
5627 | .Ar command | |
5628 | is not specified a shell is invoked according to the | |
5629 | .Dv SHELL | |
5630 | environment variable. | |
5631 | Otherwise, the given | |
5632 | .Ar command | |
5633 | is executed. | |
5634 | Word replacement is done in the same way as for the | |
5635 | .Dq !bg | |
5636 | command as described above. | |
5637 | .Pp | |
5638 | Use of the ! character | |
5639 | requires a following space as with any of the other commands. | |
5640 | You should note that this command is executed in the foreground; | |
5641 | .Nm | |
5642 | will not continue running until this process has exited. | |
5643 | Use the | |
5644 | .Dv bg | |
5645 | command if you wish processing to happen in the background. | |
5646 | .It show Ar var | |
5647 | This command allows the user to examine the following: | |
5648 | .Bl -tag -width 2n | |
5649 | .It show bundle | |
5650 | Show the current bundle settings. | |
5651 | .It show ccp | |
5652 | Show the current CCP compression statistics. | |
5653 | .It show compress | |
5654 | Show the current VJ compression statistics. | |
5655 | .It show escape | |
5656 | Show the current escape characters. | |
5657 | .It show filter Op Ar name | |
5658 | List the current rules for the given filter. | |
5659 | If | |
5660 | .Ar name | |
5661 | is not specified, all filters are shown. | |
5662 | .It show hdlc | |
5663 | Show the current HDLC statistics. | |
5664 | .It show help|? | |
5665 | Give a summary of available show commands. | |
5666 | .It show iface | |
5667 | Show the current interface information | |
5668 | (the same as | |
5669 | .Dq iface show ) . | |
5670 | .It show ipcp | |
5671 | Show the current IPCP statistics. | |
5672 | .It show layers | |
5673 | Show the protocol layers currently in use. | |
5674 | .It show lcp | |
5675 | Show the current LCP statistics. | |
bc536631 SW |
5676 | .It Ic show Oo Ic data Oc Ns Xo |
5677 | .Ic link | |
984263bc MD |
5678 | .Xc |
5679 | Show high level link information. | |
5680 | .It show links | |
5681 | Show a list of available logical links. | |
5682 | .It show log | |
5683 | Show the current log values. | |
5684 | .It show mem | |
5685 | Show current memory statistics. | |
5686 | .It show ncp | |
5687 | Show the current NCP statistics. | |
5688 | .It show physical | |
5689 | Show low level link information. | |
5690 | .It show mp | |
5691 | Show Multi-link information. | |
5692 | .It show proto | |
5693 | Show current protocol totals. | |
5694 | .It show route | |
5695 | Show the current routing tables. | |
5696 | .It show stopped | |
5697 | Show the current stopped timeouts. | |
5698 | .It show timer | |
5699 | Show the active alarm timers. | |
5700 | .It show version | |
5701 | Show the current version number of | |
5702 | .Nm . | |
5703 | .El | |
984263bc MD |
5704 | .It term |
5705 | Go into terminal mode. | |
5706 | Characters typed at the keyboard are sent to the device. | |
5707 | Characters read from the device are displayed on the screen. | |
5708 | When a remote | |
5709 | .Em PPP | |
5710 | peer is detected, | |
5711 | .Nm | |
5712 | automatically enables Packet Mode and goes back into command mode. | |
5713 | .El | |
5714 | .Sh MORE DETAILS | |
5715 | .Bl -bullet | |
5716 | .It | |
5717 | Read the example configuration files. | |
5718 | They are a good source of information. | |
5719 | .It | |
5720 | Use | |
5721 | .Dq help , | |
5722 | .Dq nat \&? , | |
5723 | .Dq enable \&? , | |
5724 | .Dq set ?\& | |
5725 | and | |
5726 | .Dq show ?\& | |
5727 | to get online information about what's available. | |
5728 | .It | |
5729 | The following URLs contain useful information: | |
5730 | .Bl -bullet -compact | |
5731 | .It | |
a754a615 | 5732 | .Pa http://www.dragonflybsd.org/docs/handbook/handbook-userppp/ |
984263bc | 5733 | .El |
984263bc MD |
5734 | .El |
5735 | .Sh FILES | |
5736 | .Nm | |
5737 | refers to four files: | |
5738 | .Pa ppp.conf , | |
5739 | .Pa ppp.linkup , | |
5740 | .Pa ppp.linkdown | |
5741 | and | |
5742 | .Pa ppp.secret . | |
5743 | These files are placed in the | |
5744 | .Pa /etc/ppp | |
5745 | directory. | |
5746 | .Bl -tag -width 2n | |
5747 | .It Pa /etc/ppp/ppp.conf | |
5748 | System default configuration file. | |
5749 | .It Pa /etc/ppp/ppp.secret | |
5750 | An authorisation file for each system. | |
5751 | .It Pa /etc/ppp/ppp.linkup | |
5752 | A file to check when | |
5753 | .Nm | |
5754 | establishes a network level connection. | |
5755 | .It Pa /etc/ppp/ppp.linkdown | |
5756 | A file to check when | |
5757 | .Nm | |
5758 | closes a network level connection. | |
5759 | .It Pa /var/log/ppp.log | |
5760 | Logging and debugging information file. | |
5761 | Note, this name is specified in | |
5762 | .Pa /etc/syslog.conf . | |
5763 | See | |
5764 | .Xr syslog.conf 5 | |
5765 | for further details. | |
5766 | .It Pa /var/spool/lock/LCK..* | |
5767 | tty port locking file. | |
5768 | Refer to | |
5769 | .Xr uucplock 3 | |
5770 | for further details. | |
5771 | .It Pa /var/run/tunN.pid | |
5772 | The process id (pid) of the | |
5773 | .Nm | |
5774 | program connected to the tunN device, where | |
5775 | .Sq N | |
5776 | is the number of the device. | |
5777 | .It Pa /var/run/ttyXX.if | |
5778 | The tun interface used by this port. | |
5779 | Again, this file is only created in | |
5780 | .Fl background , | |
5781 | .Fl auto | |
5782 | and | |
5783 | .Fl ddial | |
5784 | modes. | |
5785 | .It Pa /etc/services | |
5786 | Get port number if port number is using service name. | |
5787 | .It Pa /var/run/ppp-authname-class-value | |
5788 | In multi-link mode, local domain sockets are created using the peer | |
5789 | authentication name | |
5790 | .Pq Sq authname , | |
5791 | the peer endpoint discriminator class | |
5792 | .Pq Sq class | |
5793 | and the peer endpoint discriminator value | |
5794 | .Pq Sq value . | |
5795 | As the endpoint discriminator value may be a binary value, it is turned | |
5796 | to HEX to determine the actual file name. | |
5797 | .Pp | |
5798 | This socket is used to pass links between different instances of | |
5799 | .Nm . | |
5800 | .El | |
5801 | .Sh SEE ALSO | |
5802 | .Xr at 1 , | |
5803 | .Xr ftp 1 , | |
5804 | .Xr gzip 1 , | |
5805 | .Xr hostname 1 , | |
5806 | .Xr login 1 , | |
5807 | .Xr tcpdump 1 , | |
5808 | .Xr telnet 1 , | |
5809 | .Xr kldload 2 , | |
5810 | ifdef({LOCALNAT},{},{.Xr libalias 3 , | |
5811 | })dnl | |
984263bc MD |
5812 | .Xr syslog 3 , |
5813 | .Xr uucplock 3 , | |
5814 | .Xr netgraph 4 , | |
5815 | .Xr ng_pppoe 4 , | |
5816 | .Xr crontab 5 , | |
5817 | .Xr group 5 , | |
5818 | .Xr passwd 5 , | |
5819 | .Xr protocols 5 , | |
984263bc MD |
5820 | .Xr resolv.conf 5 , |
5821 | .Xr syslog.conf 5 , | |
5822 | .Xr adduser 8 , | |
5823 | .Xr chat 8 , | |
5824 | .Xr getty 8 , | |
5825 | .Xr inetd 8 , | |
5826 | .Xr init 8 , | |
984263bc MD |
5827 | .Xr named 8 , |
5828 | .Xr ping 8 , | |
5829 | .Xr pppctl 8 , | |
984263bc MD |
5830 | .Xr pppoe 8 , |
5831 | .Xr route 8 , | |
5832 | .Xr sshd 8 , | |
5833 | .Xr syslogd 8 , | |
5834 | .Xr traceroute 8 , | |
5835 | .Xr vipw 8 | |
5836 | .Sh HISTORY | |
5837 | This program was originally written by | |
e65bc1c3 | 5838 | .An Toshiharu OHNO Aq Mt tony-o@iij.ad.jp , |
984263bc MD |
5839 | and was submitted to |
5840 | .Fx 2.0.5 | |
5841 | by | |
e65bc1c3 | 5842 | .An Atsushi Murai Aq Mt amurai@spec.co.jp . |
984263bc MD |
5843 | .Pp |
5844 | It was substantially modified during 1997 by | |
e65bc1c3 | 5845 | .An Brian Somers Aq Mt brian@Awfulhak.org , |
984263bc MD |
5846 | and was ported to |
5847 | .Ox | |
5848 | in November that year | |
5849 | (just after the 2.2 release). | |
5850 | .Pp | |
5851 | Most of the code was rewritten by | |
5852 | .An Brian Somers | |
5853 | in early 1998 when multi-link ppp support was added. |