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