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