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