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