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