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