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