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