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