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