2.Dd 20 September 1995
3.Os FreeBSD
4.Dt PPP 8
5.Sh NAME
6.Nm ppp
7.Nd
8Point to Point Protocol (aka iijppp)
9.Sh SYNOPSIS
10.Nm
11.Op Fl auto | background | ddial | direct | dedicated
12.Op Fl alias
13.Op Ar system
14.Sh DESCRIPTION
15This is a user process
16.Em PPP
17software package. Normally,
18.Em PPP
19is implemented as a part of the kernel (e.g. as managed by pppd) and it's
20thus somewhat hard to debug and/or modify its behavior. However, in this
21implementation
22.Em PPP
23is done as a user process with the help of the
24tunnel device driver (tun).
25
26.Sh Major Features
27
28.Bl -diag
29.It Provides interactive user interface.
30Using its command mode, the user can
31easily enter commands to establish the connection with the remote end, check
32the status of connection and close the connection. All functions can
33also be optionally password protected for security.
34
35.It Supports both manual and automatic dialing.
36Interactive mode has a
37.Dq term
38command which enables you to talk to your modem directly. When your
39modem is connected to the remote peer and it starts to talk
40.Em PPP
41, the
42.Em PPP
43software detects it and switches to packet
44mode automatically. Once you have determined the proper sequence for connecting
45with the remote host, you can write a chat script to define the necessary
46dialing and login procedure for later convenience.
47
48.It Supports on-demand dialup capability.
49By using auto mode,
50.Nm
51will act as a daemon and wait for a packet to be sent over the
52.Em PPP
53link. When this happens, the daemon automatically dials and establishes the
54connection.
55
56In almost the same manner ddial mode (dedicated or daemon dialing)
57also automatically dials and establishes the connection. However, it
58differs in that it will dial the remote site any time it detects the
59link is down, even if there are no packets to be sent. This mode is
60useful for full-time connections who worry less about line charges
61and more about being connected full time.
62
63.It Supports packet aliasing.
64Packet aliasing, more commonly known as masquerading, allows computers
65on a private, unregistered network to access the internet. The
66.Em PPP
67host acts as a masquerading gateway. IP addresses as well as TCP and
68UDP port numbers are aliased for outgoing packets and de-aliased for
69returning packets.
70
71.It Supports background PPP connections.
72In background mode, if
73.Nm
74successfully establishes the connection, it will become a daemon.
75Otherwise, it will exit with an error.
76
77.It Supports server-side PPP connections.
78In direct mode,
79.nm
80acts as server which accepts incoming
81.Em PPP
82connections on stdin/stdout.
83
84.It Supports PAP and CHAP authentication.
85
86.It Supports Proxy Arp.
87When
88.Em PPP
89is set up as server, you can also configure it to do proxy arp for your
90connection.
91
92.It Supports packet filtering.
93User can define four kinds of filters:
94.Em ifilter
95for incoming packets,
96.Em ofilter
97for outgoing packets,
98.Em dfilter
99to define a dialing trigger packet and
100.Em afilter
101for keeping a connection alive with the trigger packet.
102
103.It Tunnel driver supports bpf.
104The user can use
105.Xr tcpdump 1
106to check the packet flow over the
107.Em PPP
108link.
109
110.It Supports PPP over TCP capability.
111
112
113.It Supports IETF draft Predictor-1 compression.
114.Nm
115supports not only VJ-compression but also Predictor-1 compression.
116Normally, a modem has built-in compression (e.g. v42.bis) and the system
117may receive higher data rates from it as a result of such compression.
118While this is generally a good thing in most other situations, this
119higher speed data imposes a penalty on the system by increasing the
120number of serial interrupts the system has to process in talking to the
121modem and also increases latency. Unlike VJ-compression, Predictor-1
122compression pre-compresses
123.Em all
124data flowing through the link, thus reducing overhead to a minimum.
125
126.It Supports Microsofts IPCP extentions.
127Name Server Addresses and NetBIOS Name Server Addresses can be negotiated
128with clients using the Microsoft
129.Em PPP
130stack (ie. Win95, WinNT)
131
132.Sh GETTING STARTED
133
134When you first run
135.Nm
136you may need to deal with some initial configuration details. First,
137your kernel should include a tunnel device (the default in FreeBSD 2.0.5
138and later). If it doesn't, or if you require more than one tun interface,
139you'll need to rebuild your kernel with the following line in your kernel
140configuration file:
141
142.Dl pseudo-device tun N
143
144where
145.Ar N
146is the maximum number of
147.Em PPP
148connections you wish to support.
149
150Second, check your
151.Pa /dev
152directory for the tunnel device entries
153.Pa /dev/tunN ,
154where
155.Ar N
156represents the number of the tun device, starting at zero.
157If they don't exist, you can create them by running "sh ./MAKEDEV tunN".
158This will create tun devices 0 through
159.Ar N .
160
161Last of all, create a log file.
162.Nm Ppp
163uses
164.Xr syslog 3
165to log information. A common log file name is
166.Pa /var/log/ppp.log .
167To make output go to this file, put the following lines in the
168.Pa /etc/syslog.conf
169file:
170
171.Dl !ppp
172.Dl *.* /var/log/ppp.log
173
174It is possible to have more than one ppp log file by creating a link
175to the ppp executable:
176
177.Dl # cd /usr/sbin
178.Dl # ln ppp ppp0
179
180and using
181
182.Dl !ppp0
183.Dl *.* /var/log/ppp0.log
184
185in
186.Pa /etc/syslog.conf .
187Don't forget to send a
188.Dv HUP
189signal to
190.Nm syslogd
191after altering
192.Pa /etc/syslog.conf .
193
194.Sh MANUAL DIALING
195
196In the following examples, we assume that your machine name is
197.Nm awfulhak .
198
199If you set your hostname and password in
200.Pa /etc/ppp/ppp.secret ,
201you can't do anything except run the help, passwd and quit commands.
202
203.Bd -literal -offset indent
204ppp on "your hostname"> help
205 help : Display this message
206 passwd : Password for security
207 quit : Quit the PPP program
208ppp on awfulhak> pass <password>
209.Ed
210
211The "on" part of your prompt will change to "ON" if you specify the
212correct password.
213
214.Bd -literal -offset indent
215ppp ON awfulhak>
216.Ed
217
218You can now specify the device name, speed and parity for your modem,
219and whether CTS/RTS signalling should be used (CTS/RTS is used by
220default). If your hardware does not provide CTS/RTS lines (as
221may happen when you are connected directly to certain ppp-capable
222terminal servers),
223.Nm
224will never send any output through the port; it waits for a signal
225which never comes. Thus, if you have a direct line and can't seem
226to make a connection, try turning ctsrts off:
227
228
229.Bd -literal -offset indent
230ppp ON awfulhak> set line /dev/cuaa0
231ppp ON awfulhak> set speed 38400
232ppp ON awfulhak> set parity even
233ppp ON awfulhak> set ctsrts on
234ppp ON awfulhak> show modem
235
236* Modem related information is shown here *
237
238ppp ON awfulhak>
239.Ed
240
241The term command can now be used to talk directly with your modem:
242
243.Bd -literal -offset indent
244ppp ON awfulhak> term
245at
246OK
247atdt123456
248CONNECT
249login: ppp
250Password:
251Protocol: ppp
252.Ed
253
254When the peer starts to talk in PPP,
255.Nm
256detects this automatically and returns to command mode.
257
258.Bd -literal -offset indent
259ppp ON awfulhak>
260PPP ON awfulhak>
261.Ed
262
263You are now connected! Note that
264.Sq PPP
265in the prompt has changed to capital letters to indicate that you have
266a peer connection. The show command can be used to see how things are
267going:
268
269.Bd -literal -offset indent
270PPP ON awfulhak> show lcp
271
272* LCP related information is shown here *
273
274PPP ON awfulhak> show ipcp
275
276* IPCP related information is shown here *
277.Ed
278
279At this point, your machine has a host route to the peer. This means
280that you can only make a connection with the host on the other side
281of the link. If you want to add a default route entry (telling your
282machine to send all packets without another routing entry to the other
283side of the ppp link), enter the following command:
284
285.Bd -literal -offset indent
286PPP ON awfulhak> add 0 0 HISADDR
287.Ed
288
289The string
290.Sq HISADDR
291represents the IP address of the connected peer. This variable is only
292available once a connection has been established. A common error
293is to specify the above command in your
294.Pa ppp.conf
295file. This won't work as the remote IP address hasn't been
296established when this file is read.
297
298You can now use your network applications (ping, telnet, ftp etc.)
299in other windows on your machine.
300
301Refer to the PPP COMMAND LIST section for details on all available commands.
302
303.Sh AUTOMATIC DIALING
304
305To use automatic dialing, you must prepare some Dial and Login chat scripts.
306See the example definitions in
307.Pa /etc/ppp/ppp.conf.sample
308(the format of ppp.conf is pretty simple).
309
310.Bl -bullet -compact
311
312.It
313Each line contains one command, label or comment.
314
315.It
316A line starting with a
317.Sq #
318character is treated as a comment line.
319
320.It
321A label name starts in the first column and is followed by
322a colon (:).
323
324.It
325A command line must contain a space or tab in the first column.
326
327.El
328
329The
330.Pa ppp.conf
331file should consist of at least a
332.Dq default
333section. This section is always executed. It should also contain
334one or more sections, named according to their purpose, for example,
335.Dq MyISP
336would represent your ISP, and
337.Dq ppp-in
338would represent an incoming
339.Nm
340configuration.
341
342You can now specify the destination label name when you invoke
343.Nm ppp .
344Commands associated with the
345.Dq default
346label are executed, followed by those associated with the destination
347label provided. When
348.Nm
349is started with no arguments, the
350.Dq default
351section is still executed. The load command can be used to manually
352load a section from the
353.Pa ppp.conf
354file:
355
356.Bd -literal -offset indent
357PPP ON awfulhak> load MyISP
358.Ed
359
360Once the connection is made, the ppp portion of the prompt will change
361to PPP:
362
363.Bd -literal -offset indent
364# ppp MyISP
365...
366ppp ON awfulhak> dial
367dial OK!
368login OK!
369PPP ON awfulhak>
370.Ed
371
372If the
373.Pa /etc/ppp/ppp.linkup
374file is available, its contents are executed
375when the
376.Em PPP
377connection is established. See the provided
378.Dq pmdemand
379example in
380.Pa /etc/ppp/ppp.conf.sample
381which adds a default route. The string HISADDR is available as the IP
382address of the remote peer. Similarly, when a connection is closed, the
383contents of the
384.Pa /etc/ppp/ppp.linkdown
385file are executed.
386
387.Sh BACKGROUND DIALING
388
389If you want to establish a connection using
390.Nm
391non-interactively (such as from a
392.Xr crontab(5)
393entry or an
394.Xr at(1)
395job) you should use the
396.Fl background
397option. You must also specify the destination label in
398.Pa /etc/ppp/ppp.conf
399to use. This label must contain the
400.Dq set ifaddr
401command to define the remote peer's IP address. (refer to
402.Pa /etc/ppp/ppp.conf.sample )
403
404When
405.Fl background
406is specified,
407.Nm
408attempts to establish the connection immediately. If multiple phone
409numbers are specified, each phone number will be tried once. If the
410attempt fails,
411.Nm
412exits immediately with a non-zero exit code.
413
414If it succeeds, then
415.Nm
416becomes a daemon, and returns an exit status of zero to its caller.
417The daemon exits automatically if the connection is dropped by the
418remote system, or it receives a
419.Dv TERM
420signal.
421
422.Sh DIAL ON DEMAND
423
424Demand dialing is enabled with the
425.Fl auto
426or
427.Fl ddial
428options. You must also specify the destination label in
429.Pa /etc/ppp/ppp.conf
430to use. It must contain the
431.Dq set ifaddr
432command to define the remote peer's IP address. (refer to
433.Pa /etc/ppp/ppp.conf.sample )
434
435.Bd -literal -offset indent
436# ppp -auto pmdemand
437...
438#
439.Ed
440
441When
442.Fl auto
443or
444.Fl ddial
445is specified,
446.Nm
447runs as a daemon but you can still configure or examine its
448configuration by using the diagnostic port as follows (this
449can be done in
450.Fl background
451and
452.Fl direct
453mode too):
454
455
456.Bd -literal -offset indent
457# telnet localhost 3000
458Trying 127.0.0.1...
459Connected to awfulhak.
460Escape character is '^]'.
461....
462PPP on awfulhak> pass xxxx
463PPP ON awfulhak> show ipcp
464IPCP [OPEND]
465 his side: xxxx
466 ....
467.Ed
468
469.Pp
470Each
471.Nm
472daemon has an associated port number which is computed as "3000 +
473tunnel_device_number".
474
475In
476.Fl auto
477mode, when an outgoing packet is detected,
478.Nm
479will perform the dialing action (chat script) and try to connect
480with the peer. In
481.Fl ddial
482mode, the dialing action is performed any time the line is found
483to be down.
484
485If the connect fails, the default behavior is to wait 30 seconds
486and then attempt to connect when another outgoing packet is detected.
487This behavior can be changed with
488.Bd -literal -offset indent
489set redial seconds|random[.nseconds|random] [dial_attempts]
490.Ed
491.Pp
492.Sq Seconds
493is the number of seconds to wait before attempting
494to connect again. If the argument is
495.Sq random ,
496the delay period is a random value between 0 and 30 seconds.
497.Sq Nseconds
498is the number of seconds to wait before attempting
499to dial the next number in a list of numbers (see the
500.Dq set phone
501command). The default is 3 seconds. Again, if the argument is
502.Sq random ,
503the delay period is a random value between 0 and 30 seconds.
504.Sq dial_attempts
505is the number of times to try to connect for each outgoing packet
506that is received. The previous value is unchanged if this parameter
507is omitted. If a value of zero is specified for
508.Sq dial_attempts ,
509.Nm ppp
510will keep trying until a connection is made.
511.Bd -literal -offset indent
512set redial 10.3 4
513.Ed
514.Pp
515will attempt to connect 4 times for each outgoing packet that is
516detected with a 3 second delay between each number and a 10 second
517delay after all numbers have been tried. If multiple phone numbers
518are specified, the total number of attempts is still 4 (it does not
519attempt each number 4 times).
520
521Modifying the dial delay is very useful when running
522.Nm
523in demand
524dial mode on both ends of the link. If each end has the same timeout,
525both ends wind up calling each other at the same time if the link
526drops and both ends have packets queued.
527
528At some locations, the serial link may not be reliable, and carrier
529may be lost at inappropriate times. It is possible to have
530.Nm
531redial should carrier be unexpectedly lost during a session.
532.Bd -literal -offset indent
533set reconnect timeout ntries
534.Ed
535
536This command tells ppp to re-establish the connection
537.Ar ntries
538times on loss of carrier with a pause of
539.Ar timeout
540seconds before each try. For example,
541.Bd -literal -offset indent
542set reconnect 3 5
543.Ed
544
545tells
546.Nm
547that on an unexpected loss of carrier, it should wait
548.Ar 3
549seconds before attempting to reconnect. This may happen up to
550.Ar 5
551times before
552.Nm
553gives up. The default value of ntries is zero (no reconnect). Care
554should be taken with this option. If the local timeout is slightly
555longer than the remote timeout, the reconnect feature will always be
556triggered (up to the given number of times) after the remote side
557times out and hangs up.
558
559NOTE: In this context, losing too many LQRs constitutes a loss of
560carrier and will trigger a reconnect.
561
562If the
563.Fl background
564flag is specified, all phone numbers are dialed at most once until
565a connection is made. The next number redial period specified with
566the
567.Dq set redial
568command is honoured, as is the reconnect tries value. If your redial
569value is less than the number of phone numbers specified, not all
570the specified numbers will be tried.
571
572To terminate the program, type
573
574 PPP ON awfulhak> close
575 ppp ON awfulhak> quit all
576
577.Pp
578A simple
579.Dq quit
580command will terminate the telnet connection but not the program itself.
581You must use
582.Dq quit all
583to terminate the program as well.
584
585.Sh RECEIVING INCOMING PPP CONNECTIONS (Method 1)
586
587To handle an incoming
588.Em PPP
589connection request, follow these steps:
590
591.Bl -enum
592.It
593Make sure the modem and (optionally)
594.Pa /etc/rc.serial
595is configured correctly.
596.Bl -bullet -compact
597.It
598Use Hardware Handshake (CTS/RTS) for flow control.
599.It
600Modem should be set to NO echo back (ATE0) and NO results string (ATQ1).
601.El
602
603.It
604Edit
605.Pa /etc/ttys
606to enable a getty on the port where the modem is attached.
607
608For example:
609
610.Dl ttyd1 "/usr/libexec/getty std.38400" dialup on secure
611
612Don't forget to send a
613.Dv HUP
614signal to the init process to start the getty.
615
616.Dl # kill -HUP 1
617
618.It
619Prepare an account for the incoming user.
620.Bd -literal
621ppp:xxxx:66:66:PPP Login User:/home/ppp:/usr/local/bin/ppplogin
622.Ed
623
624.It
625Create a
626.Pa /usr/local/bin/ppplogin
627file with the following contents:
628.Bd -literal -offset indent
629#!/bin/sh -p
630exec /usr/sbin/ppp -direct
631.Ed
632
633(You can specify a label name for further control.)
634
635.Pp
636Direct mode (
637.Fl direct
638) lets
639.Nm
640work with stdin and stdout. You can also telnet to port 3000 plus
641the current tunnel device number to get command mode control in the
642same manner as client-side
643.Nm.
644
645.It
646Optional support for Microsoft's IPCP Name Server and NetBIOS
647Name Server negotiation can be enabled use
648.Dq enable msext
649and
650.Dq set ns pri-addr [sec-addr]
651along with
652.Dq set nbns pri-addr [sec-addr]
653in your ppp.conf file
654
655.El
656
657.Sh RECEIVING INCOMING PPP CONNECTIONS (Method 2)
658
659This method differs in that it recommends the use of
660.Em mgetty+sendfax
661to handle the modem connections. The latest version 0.99
662can be compiled with the
663.Dq AUTO_PPP
664option to allow detection of clients speaking PPP to the login
665prompt.
666
667Follow these steps:
668
669.Bl -enum
670
671.It
672Get, configure, and install mgetty+sendfax v0.99 or later making
673sure you have used the AUTO_PPP option.
674
675.It
676Edit
677.Pa /etc/ttys
678to enable a mgetty on the port where the modem is attached. For
679example:
680
681.Dl cuaa1 "/usr/local/sbin/mgetty -s 57600" dialup on
682
683.It
684Prepare an account for the incoming user.
685.Bd -literal
686Pfred:xxxx:66:66:Fred's PPP:/home/ppp:/etc/ppp/ppp-dialup
687.Ed
688
689.It
690Examine the files
691.Pa /etc/ppp/sample.ppp-dialup
692.Pa /etc/ppp/sample.ppp-pap-dialup
693and
694.Pa /etc/ppp/ppp.conf.sample
695for ideas. ppp-pap-dialup is supposed to be called from
696.Pa /usr/local/etc/mgetty+sendfax/login.conf
697from a line like
698
699.Dl /AutoPPP/ - - /etc/ppp/ppp-pap-dialup
700.El
701
702.Sh PPP OVER TCP (a.k.a Tunneling)
703
704Instead of running ppp over a serial link, it is possible to
705use a tcp connection instead by specifying a host and port as the
706device:
707
708.Dl set device ui-gate:6669
709
710Instead of opening a serial device,
711.Nm
712will open a tcp connection to the given machine on the given
713socket. It should be noted however that
714.Nm
715doesn't use the telnet protocol and will be unable to negotiate
716with a telnet server. You should set up a port for receiving
717this ppp connection on the receiving machine (ui-gate). This is
718done by first updating
719.Pa /etc/services
720to name the service:
721
722.Dl ppp-in 6669/tcp # Incoming ppp connections over tcp
723
724and updating
725.Pa /etc/inetd.conf
726to tell inetd how to deal with incoming connections on that port:
727
728.Dl ppp-in stream tcp nowait root /usr/sbin/ppp ppp -direct ppp-in
729
730Don't forget to send a
731.Dv HUP
732signal to
733.Nm inetd
734after you've updated
735.Pa /etc/inetd.conf .
736
737Here, we use a label named
738.Dq ppp-in .
739The entry in
740.Pa /etc/ppp/ppp.conf
741on ui-gate (the receiver) should contain the following:
742
743.Bd -literal -offset indent
744ppp-in:
745 set timeout 0
746 set ifaddr 10.0.4.1 10.0.4.2
747 add 10.0.4.1 255.255.255.255 127.0.0.1
748 add 10.0.1.0 255.255.255.0 10.0.4.1
749.Ed
750
751You may also want to enable PAP or CHAP for security. The entry in
752.Pa /etc/ppp/ppp.conf
753on awfulhak (the initiator) should contain the following:
754
755.Bd -literal -offset indent
756ui-gate:
757 set escape 0xff
758 set device ui-gate:ppp-in
759 set dial
760 set timeout 30 5 4
761 set log Phase Chat Connect Carrier hdlc LCP tun
762 set ifaddr 10.0.4.2 10.0.4.1
763 add 10.0.4.2 255.255.255.255 127.0.0.1
764 add 10.0.2.0 255.255.255.0 10.0.4.2
765.Ed
766
767We're assigning the address of 10.0.4.1 to ui-gate, and the address
76810.0.4.2 to awfulhak.
769
770To open the connection, just type
771
772.Dl awfulhak # ppp -background ui-gate
773
774The result will be an additional "route" on awfulhak to the
77510.0.2.0/24 network via the tcp connection, and an additional
776"route" on ui-gate to the 10.0.1.0/24 network.
777
778The networks are effectively bridged - the underlying tcp
779connection may be across a public network (such as the
780Internet), and the ppp traffic is conceptually encapsulated
781(although not packet by packet) inside the tcp stream between
782the two gateways.
783
784The major disadvantage of this mechanism is that there are two
785"guaranteed delivery" mechanisms in place - the underlying tcp
786stream and whatever protocol is used over the ppp link - probably
787tcp again. If packets are lost, both levels will get in eachothers
788way trying to negotiate sending of the missing packet.
789
790.Sh PACKET ALIASING
791
792The
793.Fl alias
794command line option enables packet aliasing. This allows the
795ppp host to act as a masquerading gateway for other computers over
796a local area network. Outgoing IP packets are aliased so that
797they appear to come from the ppp host, and incoming packets are
798de-aliased so that they are routed to the correct machine on the
799local area network.
800
801Packet aliasing allows computers on private, unregistered
802subnets to have internet access, although they are invisible
803from the outside world.
804
805In general, correct ppp operation should first be verified
806with packet aliasing disabled. Then, the
807.Fl alias
808option should be switched on, and network applications (web browser,
809telnet, ftp, ping, traceroute) should be checked on the ppp host.
810Finally, the same or similar applications should be checked on other
811computers in the LAN.
812
813If network applications work correctly on the ppp host, but not on
814other machines in the LAN, then the masquerading software is working
815properly, but the host is either not forwarding or possibly receiving
816IP packets. Check that IP forwarding is enabled in
817.Pa /etc/rc.conf
818and that other machines have designated the ppp host as the gateway
819for the LAN.
820
821.Sh PACKET FILTERING
822
823This implementation supports packet filtering. There are four kinds of
824filters; ifilter, ofilter, dfilter and afilter. Here are the basics:
825
826.Bl -bullet -compact
827.It
828A filter definition has the following syntax:
829
830set filter-name rule-no action [src_addr/src_width] [dst_addr/dst_width]
831[proto [src [lt|eq|gt] port ]] [dst [lt|eq|gt] port] [estab]
832.Bl -enum
833.It
834.Sq filter-name
835should be one of ifilter, ofilter, dfilter or afilter.
836.It
837There are two actions:
838.Sq permit
839and
840.Sq deny .
841If a given packet
842matches the rule, the associated action is taken immediately.
843.It
844.Sq src_width
845and
846.Sq dst_width
847work like a netmask to represent an address range.
848.It
849.Sq proto
850must be one of icmp, udp or tcp.
851.It
852.Sq port number
853can be specified by number and service name from
854.Pa /etc/services .
855
856.El
857
858.It
859Each filter can hold up to 20 rules, starting from rule 0.
860The entire rule set is not effective until rule 0 is defined,
861ie. the default is to allow everything through.
862
863.It
864If no rule is matched to a packet, that packet will be discarded
865(blocked).
866
867.It
868Use
869.Dq set filter-name -1
870to flush all rules.
871
872.El
873
874See
875.Pa /etc/ppp/ppp.conf.filter.example .
876
877
878.Sh SETTING IDLE, LINE QUALITY REQUEST, RETRY TIMER
879
880To check/set idletimer, use the
881.Dq show timeout
882and
883.Dq set timeout [lqrtimer [retrytimer]]
884commands:
885
886.Bd -literal -offset indent
887ppp ON awfulhak> set timeout 600
888.Ed
889
890The timeout period is measured in seconds, the default values for which
891are timeout = 180 or 3 min, lqrtimer = 30sec and retrytimer = 3sec.
892To disable the idle timer function, use the command
893
894.Bd -literal -offset indent
895ppp ON awfulhak> set timeout 0
896.Ed
897
898In
899.Fl auto
900mode, an idle timeout causes the
901.Em PPP
902session to be
903closed, though the
904.Nm
905program itself remains running. Another trigger packet will cause it to
906attempt to reestablish the link.
907
908.Sh PREDICTOR-1 COMPRESSION
909
910This version supports CCP and Predictor type 1 compression based on
911the current IETF-draft specs. As a default behavior,
912.Nm
913will attempt to use (or be willing to accept) this capability when the
914peer agrees (or requests it).
915
916To disable CCP/predictor functionality completely, use the
917.Dq disable pred1
918and
919.Dq deny pred1
920commands.
921
922.Sh CONTROLLING IP ADDRESS
923
924.Nm
925uses IPCP to negotiate IP addresses. Each side of the connection
926specifies the IP address that it's willing to use, and if the requested
927IP address is acceptable then
928.Nm
929returns ACK to the requester. Otherwise,
930.Nm
931returns NAK to suggest that the peer use a different IP address. When
932both sides of the connection agree to accept the received request (and
933send ACK), IPCP is set to the open state and a network level connection
934is established.
935
936To control this IPCP behavior, this implementation has the
937.Dq set ifaddr
938command for defining the local and remote IP address:
939
940.Nm set ifaddr
941.Op src_addr Op dst_addr Op netmask
942
943Where,
944.Sq src_addr
945is the IP address that the local side is willing to use and
946.Sq dst_addr
947is the IP address which the remote side should use.
948.Sq netmask
949is interface netmask.
950
951.Bd -literal -offset indent
952set ifaddr 192.244.177.38 192.244.177.2 255.255.255.0
953.Ed
954
955The above specification means:
956.Bl -bullet -compact
957.It
958I strongly want to use 192.244.177.38 as my IP address, and I'll
959disagree if the peer suggests that I use another address.
960
961.It
962I strongly insist that peer use 192.244.177.2 as own side address and
963don't permit it to use any IP address but 192.244.177.2. When peer
964request another IP address, I always suggest that it use 192.244.177.2.
965
966.It
967My interface netmask will be 255.255.255.0.
968.El
969
970This is all fine when each side has a pre-determined IP address, however
971it is often the case that one side is acting as a server which controls
972all IP addresses and the other side should obey the direction from it.
973
974In order to allow more flexible behavior, `ifaddr' variable allows the
975user to specify IP address more loosely:
976
977.Dl set ifaddr 192.244.177.38/24 192.244.177.2/20
978
979A number followed by a slash (/) represent the number of bits significant in
980the IP address. The above example signifies that:
981
982.Bl -bullet -compact
983.It
984I'd like to use 192.244.177.38 as my address if it is possible, but I'll
985also accept any IP address between 192.244.177.0 and 192.244.177.255.
986
987.It
988I'd like to make him use 192.244.177.2 as his own address, but I'll also
989permit him to use any IP address between 192.244.176.0 and
990192.244.191.255.
991
992.It
993As you may have already noticed, 192.244.177.2 is equivalent to saying
994192.244.177.2/32.
995
996.It
997As an exception, 0 is equivalent to 0.0.0.0/0, meaning that I have no
998preferred IP address and will obey the remote peer's selection. When
999using zero, no routing table entries will be made until a connection
1000is established.
1001
1002.It
1003192.244.177.2/0 means that I'll accept/permit any IP address but I'll
1004try to insist that 192.244.177.2 be used first.
1005.El
1006
1007.Sh CONNECTING WITH YOUR INTERNET SERVICE PROVIDER
1008
1009The following steps should be taken when connecting to your ISP:
1010
1011.Bl -enum
1012.It
1013Describe your provider's phone number(s) in the dial script using the
1014.Dq set phone
1015command. This command allows you to set multiple phone numbers for
1016dialing and redialing separated by a colon (:). For example:
1017.Bd -literal -offset indent
1018set phone "1234567:2345678"
1019.Ed
1020.Pp
1021Here, the first number is attempted. If the connection fails, the second
1022number is attempted after the next number redial period. If the second number
1023also fails, the first is tried again after the redial period has expired.
1024The selected phone number is substituted for the \\T string in the
1025.Dq set dial
1026command (see below).
1027
1028.It
1029Set up your redial requirements using
1030.Dq set redial .
1031For example, if you have a bad telephone line or your provider is
1032usually engaged (not so common these days), you may want to specify
1033the following:
1034.Bd -literal -offset indent
1035set redial 10 4
1036.Ed
1037.Pp
1038This says that up to 4 phone calls should be attempted with a pause of 10
1039seconds before dialing the first number again.
1040
1041.It
1042Describe your login procedure using the
1043.Dq set dial
1044and
1045.Dq set login
1046commands. The
1047.Dq set dial
1048command is used to talk to your modem and establish a link with your
1049ISP, for example:
1050.Bd -literal -offset indent
1051set dial "ABORT BUSY ABORT NO\\\\sCARRIER TIMEOUT 4 \\"\\" ATZ OK-ATZ-OK ATDT\\\\T TIMEOUT 60 CONNECT"
1052.Ed
1053.Pp
1054This modem "chat" string means:
1055
1056.Bl -bullet
1057.It
1058Abort if the string "BUSY" or "NO CARRIER" are received.
1059.It
1060Set the timeout to 4.
1061.It
1062Expect nothing.
1063.It
1064Send ATZ.
1065.It
1066Expect OK. If that's not received, send ATZ and expect OK.
1067.It
1068Send ATDTxxxxxxx where xxxxxxx is the next number in the phone list from
1069above.
1070.It
1071Set the timeout to 60.
1072.It
1073Wait for the CONNECT string.
1074.El
1075
1076Once the connection is established, the login script is executed. This
1077script is written in the same style as the dial script:
1078.Bd -literal -offset indent
1079set login "TIMEOUT 15 login:-\\\\r-login: awfulhak word: xxx ocol: PPP HELLO"
1080.Ed
1081.Pp
1082This login "chat" string means:
1083
1084.Bl -bullet
1085.It
1086Set the timeout to 15 seconds.
1087.It
1088Expect "login:". If it's not received, send a carriage return and expect
1089"login:" again.
1090.It
1091Send "awfulhak"
1092.It
1093Expect "word:" (the tail end of a "Password:" prompt).
1094.It
1095Send "xxx".
1096.It
1097Expect "ocol:" (the tail end of a "Protocol:" prompt).
1098.It
1099Send "PPP".
1100.It
1101Expect "HELLO".
1102.El
1103.Pp
1104Login scripts vary greatly between ISPs.
1105
1106.It
1107Use
1108.Dq set line
1109and
1110.Dq set sp
1111to specify your serial line and speed, for example:
1112.Bd -literal -offset indent
1113set line /dev/cuaa0
1114set sp 115200
1115.Ed
1116.Pp
1117Cuaa0 is the first serial port on FreeBSD. Cuaa1 is the second etc. A
1118speed of 115200 should be specified if you have a modem capable of bit
1119rates of 28800 or more. In general, the serial speed should be about
1120four times the modem speed.
1121
1122.It
1123Use
1124.Dq set ifaddr
1125command to define the IP address.
1126.Bl -bullet
1127.It
1128If you know what IP address your provider uses, then use it as the remote
1129address, otherwise choose something like 10.0.0.2/0 (see below).
1130.It
1131If your provider has assigned a particular IP address to you, then use
1132it as your address.
1133.It
1134If your provider assigns your address dynamically, choose a suitably
1135unobtrusive and unspecific IP number as your address. 10.0.0.1/0 would
1136be appropriate. The bit after the / specifies how many bits of the
1137address you consider to be important, so if you wanted to insist on
1138something in the class C network 1.2.3.0, you could specify 1.2.3.1/24.
1139.El
1140.Pp
1141An example for a connection where you don't know your IP number or your
1142ISPs IP number would be:
1143.Bd -literal -offset indent
1144set ifaddr 10.10.10.10/0 10.10.11.11/0 255.255.255.0
1145.Ed
1146
1147.It
1148In most cases, your ISP will also be your default router. If this is
1149the case, add the lines
1150
1151.Bd -literal -offset indent
1152delete ALL
1153add 0 0 10.10.11.11
1154.Ed
1155
1156.Pp
1157to
1158.Pa ppp.conf .
1159.Pp
1160This tells
1161.Nm
1162to delete all non-direct routing entries for the tun interface that
1163.Nm
1164is running on, then to add a default route to 10.10.11.11.
1165.Pp
1166If you're using dynamic IP numbers, you must also put these two lines
1167in the
1168.Pa ppp.linkup
1169file:
1170
1171.Bd -literal -offset indent
1172delete ALL
1173add 0 0 HISADDR
1174.Ed
1175
1176HISADDR is a macro meaning the "other side"s IP number, and is
1177available once an IP number has been agreed (using LCP).
1178Now, once a connection is established,
1179.Nm ppp
1180will delete all non-direct interface routes, and add a default route
1181pointing at the peers IP number. You should use the same label as the
1182one used in
1183.Pa ppp.conf .
1184.Pp
1185If commands are being typed interactively, the only requirement is
1186to type
1187.Bd -literal -offset indent
1188add 0 0 HISADDR
1189.Ed
1190.Pp
1191after a successful dial.
1192
1193.It
1194If your provider requests that you use PAP/CHAP authentication methods, add
1195the next lines to your
1196.Pa ppp.conf
1197file:
1198.Bd -literal -offset indent
1199enable pap (or enable chap)
1200disable chap (or disable pap)
1201set authname MyName
1202set authkey MyPassword
1203.Ed
1204
1205.El
1206
1207Please refer to
1208.Pa /etc/ppp/ppp.conf.sample
1209and
1210.Pa /etc/ppp/ppp.linkup.sample
1211for some real examples. The pmdemand label should be appropriate for most
1212ISPs.
1213
1214.Sh LOGGING FACILITY
1215
1216.Nm
1217is able to generate the following log info via
1218.Xr syslog 3 :
1219
1220.Bl -column SMMMMMM -offset indent
1221.It Li Async Dump async level packet in hex
1222.It Li Carrier Log Chat lines with 'CARRIER'
1223.It Li Chat Generate Chat script trace log
1224.It Li Command Log commands executed
1225.It Li Connect Generate complete Chat log
1226.It Li Debug Log (very verbose) debug information
1227.It Li HDLC Dump HDLC packet in hex
1228.It Li LCP Generate LCP/IPCP packet trace
1229.It Li Link Log address assignments and link up/down events
1230.It Li LQM Generate LQR report
1231.It Li Phase Phase transition log output
1232.It Li TCP/IP Dump all TCP/IP packets
1233.It Li TUN Include the tun device on each log line
1234.It Li Warning Output to the terminal device. If there is currently no
1235terminal, output is sent to the log file using LOG_WARNING.
1236.It Li Error Output to both the terminal device and the log file using
1237LOG_ERROR.
1238.It Li Alert Output to the log file using LOG_ALERT
1239.El
1240
1241The
1242.Dq set log
1243command allows you to set logging output level, of which
1244multiple levels can be specified. The default is equivalent to
1245.Dq set log Carrier Link Phase .
1246
1247If The first argument to
1248.Dq set log
1249begins with a '+' or a '-' character, the current log levels are
1250not cleared, for example:
1251
1252.Bd -literal -offset indent
1253PPP ON awfulhak> show log
1254Log: Carrier Link Phase
1255PPP ON awfulhak> set log -Link +tcp/ip
1256PPP ON awfulhak> show log
1257Log: Carrier Phase TCP/IP
1258.Ed
1259
1260Log messages of level Warning, Error and Alert are not controlable
1261using
1262.Dq set log .
1263
1264.Sh SIGNAL HANDLING
1265
1266.Nm Ppp
1267deals with the following signals:
1268
1269.Bl -tag -width 20
1270.It INT
1271Receipt of this signal causes the termination of the current connection
1272(if any). This will cause
1273.Nm
1274to exit unless it is in
1275.Fl auto
1276or
1277.Fl ddial
1278mode.
1279
1280.It HUP, TERM & QUIT
1281These signals tell
1282.Nm
1283to exit.
1284
1285.It USR1
1286This signal, when not in interactive mode, tells
1287.Nm
1288to close any existing server socket and open an internet socket using
1289the default rules for choosing a port number - that is, using port
12903000 plus the current tunnel device number.
1291
1292.El
1293
1294.Sh PPP COMMAND LIST
1295
1296This section lists the available commands and their effect. They are
1297usable either from an interactive ppp session, from a configuration
1298file or from a telnet session.
1299
1300.Bl -tag -width 20
1301.It accept|deny|enable|disable option....
1302These directives tell
1303.Nm
1304how to negotiate the initial connection with the peer. Each
1305.Dq option
1306has a default of either accept or deny and enable or disable.
1307.Dq Accept
1308means that the option will be ACK'd if the peer asks for it.
1309.Dq Deny
1310means that the option will be NAK'd if the peer asks for it.
1311.Dq Enable
1312means that the option will be requested by us.
1313.Dq Disable
1314means that the option will not be requested by us.
1315.Pp
1316.Dq Option
1317may be one of the following:
1318
1319.Bl -tag -width 20
1320.It vjcomp
1321Default: Enabled and Accepted. This option decides if Van Jacobson
1322header compression will be used.
1323
1324.It lqr
1325Default: Enabled and Accepted. This option decides if Link Quality
1326Requests will be sent. LQR is a protocol that allows
1327.Nm
1328to determine that the link is down without relying on the modems
1329carrier detect.
1330
1331.It chap
1332Default: Disabled and Accepted. CHAP stands for Challenge Handshake
1333Authentication Protocol. Only one of CHAP and PAP (below) may be
1334negotiated. With CHAP, the authenticator sends a "challenge" message
1335to its peer. The peer uses a one-way hash function to encrypt the
1336challenge and sends the result back. The authenticator does the same,
1337and compares the results. The advantage of this mechanism is that no
1338passwords are sent across the connection.
1339
1340A challenge is made when the connection is first made. Subsequent
1341challenges may occur.
1342
1343When using CHAP, an
1344.Dq AuthName
1345and an
1346.Dq AuthKey
1347must be specified either in
1348.Pa ppp.conf
1349or in
1350.Pa ppp.secret .
1351
1352.It pap
1353Default: Disabled and Accepted. PAP stands for Password Authentication
1354Protocol. Only one of PAP and CHAP (above) may be negotiated. With
1355PAP, the ID and Password are sent repeatedly to the peer until
1356authentication is acknowledged or the connection is terminated. This
1357is a rather poor security mechanism. It is only performed when the
1358connection is first established.
1359
1360When using PAP, an
1361.Dq AuthName
1362and an
1363.Dq AuthKey
1364must be specified either in
1365.Pa ppp.conf
1366or in
1367.Pa ppp.secret
1368(although see the
1369.Dq passwdauth
1370option below).
1371
1372.It acfcomp
1373Default: Enabled and Accepted. ACFComp stands for Address and Control
1374Field Compression. Non LCP packets usually have very similar address
1375and control fields - making them easily compressable.
1376
1377.It protocomp
1378Default: Enabled and Accepted. This option is used to negotiate
1379PFC (Protocol Field Compression), a mechanism where the protocol
1380field number is reduced to one octet rather than two.
1381
1382.It pred1
1383Default: Enabled and Accepted. This option decides if Predictor 1
1384compression will be used.
1385
1386.It proxy
1387Default: Disabled and Denied. Unlike the other options (except
1388passwdauth below), this is not negotiated with the peer. Therefore,
1389accepting or denying it is of no use. Enabling this option will tell
1390.Nm
1391to proxy ARP for the peer.
1392
1393.It msext
1394Default: Disabled and Accepted. This option allows the use
1395of Microsoft's ppp extensions, supporting the negotiation of
1396the Microsoft PPP DNS and the Microsoft NetBIOS NS.
1397
1398.It passwdauth
1399Default: Disabled and Denied. Unlike the other options (except
1400.Dq proxy
1401above), this is not negotiated with the peer. Therefore,
1402accepting or denying it is of no use. Enabling this option will
1403tell the PAP authentication code to use the
1404.Pa passwd
1405file to authenticate the caller rather than the
1406.Pa ppp.secret
1407file.
1408
1409.El
1410
1411.It add dest mask gateway
1412.Dq Dest
1413is the destination IP address and
1414.Dq mask
1415is its mask.
1416.Dq 0 0
1417refers to the default route.
1418.Dq Gateway
1419is the next hop gateway to get to the given
1420.Dq dest
1421machine/network.
1422
1423.It close
1424Close the current connection (but don't quit).
1425
1426.It delete ALL | dest [gateway [mask]]
1427If
1428.Dq ALL
1429is specified, all non-direct entries in the routing for the interface
1430that
1431.Nm
1432is using are deleted. This means all entries for tunX, except the entry
1433representing the actual link. When
1434.Dq ALL
1435is not used, any existing route with the given
1436.Dq dest ,
1437destination network
1438.Dq mask
1439and
1440.Dq gateway
1441is deleted. The default
1442.Dq mask
1443value is 0.0.0.0.
1444
1445.It dial|call [remote]
1446If
1447.Dq remote
1448is specified, a connection is established using the
1449.Dq dial
1450and
1451.Dq login
1452scripts for the given
1453.Dq remote
1454system. Otherwise, the current settings are used to establish
1455the connection.
1456
1457.It display
1458Displays the current status of the negotiable protocol
1459values as specified under
1460.Dq accept|deny|enable|disable option....
1461above.
1462
1463.It passwd pass
1464Specify the password required for access to the full
1465.Nm
1466command set.
1467
1468.It load [remote]
1469Load the given
1470.Dq remote
1471label. If
1472.Dq remote
1473is not given, the
1474.Dq default
1475label is assumed.
1476
1477.It save
1478This option is not (yet) implemented.
1479
1480.It set[up] var value
1481This option allows the setting of any of the following variables:
1482
1483.Bl -tag -width 20
1484.It set accmap hex-value
1485ACCMap stands for Asyncronous Control Character Map. This is always
1486negotiated with the peer, and defaults to a value of 0x00000000.
1487This protocol is required to defeat hardware that depends on passing
1488certain characters from end to end (such as XON/XOFF etc).
1489
1490.It set filter-name rule-no action [src_addr/src_width]
1491[dst_addr/dst_width] [proto [src [lt|eq|gt] port ]]
1492[dst [lt|eq|gt] port] [estab]
1493.Pp
1494.Nm Ppp
1495supports four filter sets. The afilter specifies packets that keep
1496the connection alive - reseting the idle timer. The dfilter specifies
1497packets that cause
1498.Nm
1499to dial when in
1500.Fl auto
1501mode. The ifilter specifies packets that are allowed to travel
1502into the machine and the ofilter specifies packets that are allowed
1503out of the machine. By default all filter sets allow all packets
1504to pass.
1505
1506Rules are processed in order according to
1507.Dq n .
1508Up to 20 rules may be given for each set. If a packet doesn't match
1509any of the rules in a given set, it is discarded. In the case of
1510ifilters and ofilters, this means that the packet is dropped. In
1511the case of afilters it means that the packet will not reset the
1512idle timer and in the case of dfilters it means that the packet will
1513not trigger a dial.
1514
1515Refer to the section on PACKET FILTERING above for further details.
1516
1517.It set authkey|key value
1518This sets the authentication key (or password) used in PAP or CHAP
1519negotiation to the given value. It can also be used to specify the
1520password to be used in the dial or login scripts, preventing the
1521actual password from being logged.
1522
1523.It set authname id
1524This sets the authentication id used in PAP or CHAP negotiation.
1525
1526.It set ctsrts
1527This sets hardware flow control and is the default.
1528
1529.It set device|line value
1530This sets the device to which ppp will talk to the given
1531.Dq value .
1532All serial device names are expected to begin with
1533.Pa /dev/ .
1534If
1535.Dq value
1536does not begin with
1537.Pa /dev/ ,
1538it must be of the format
1539.Dq host:port .
1540If this is the case,
1541.Nm
1542will attempt to connect to the given
1543.Dq host
1544on the given
1545.Dq port .
1546Refer to the section on PPP OVER TCP above for further details.
1547
1548.It set dial chat-script
1549This specifies the chat script that will be used to dial the other
1550side. See also the
1551.Dv set login
1552command below. Refer to
1553.Xr chat 8
1554and to the example configuration files for details of the chat script
1555format. The string \\\\T will be replaced with the current phone number
1556(see
1557.Dq set phone
1558below) and the string \\\\P will be replaced with the password (see
1559.Dq set key
1560above).
1561
1562.It set hangup chat-script
1563This specifies the chat script that will be used to reset the modem
1564before it is closed. It should not normally be necessary, but can
1565be used for devices that fail to reset themselves properly on close.
1566
1567.It set escape value...
1568This option is similar to the
1569.Dq set accmap
1570option above. It allows the user to specify a set of characters that
1571will be `escaped' as they travel across the link.
1572
1573.It set ifaddr myaddr hisaddr mask
1574This command specifies the IP addresses that will be used during
1575LCP negotiation. Addresses are specified using the format
1576
1577.Dl a.b.c.d/n
1578
1579Where a.b.c.d is the preferred IP, but n specifies how many bits
1580of the address we will insist on. If the /n bit is omitted, it
1581defaults to /32 unless the IP address is 0.0.0.0 in which case
1582the mask defaults to /0.
1583
1584.It set log [+|-]value...
1585This command allows the adjustment of the current log level. Please
1586refer to the Logging Facility section for further details.
1587
1588.It set login chat-script
1589This chat-script compliments the dial-script. If both are specified,
1590the login script will be executed after the dial script. Escape
1591sequences available in the dial script are also available here.
1592
1593.It set mru value
1594The default MRU is 1500. If it is increased, the other side *may*
1595increase its mtu. There is no use decreasing the MRU to below the
1596default as the PPP protocol *must* be able to accept packets of at
1597least 1500 octets.
1598
1599.It set mtu value
1600The default MTU is 1500. This may be increased by the MRU specified
1601by the peer. It may only be subsequently decreased by this option.
1602Increasing it is not valid as the peer is not necessarily able to
1603receive the increased packet size.
1604
1605.It set openmode active|passive
1606By default, openmode is always active. That is,
1607.Nm
1608will always initiate LCP negotiation. If you want to wait for the
1609peer to initiate LCP negotiation, you may use the value
1610.Dq passive .
1611
1612.It set parity odd|even|none|mark
1613This allows the line parity to be set. The default value is none.
1614
1615.It set phone telno[:telno]...
1616This allows the specification of the phone number to be used in
1617place of the \\\\T string in the dial and login chat scripts.
1618Multiple phone numbers may be given seperated by a colon (:).
1619If multiple numbers are given,
1620.Nm
1621will dial them in rotation until a connection is made, retrying
1622the maximum number of times specified by
1623.Dq set redial
1624below. In
1625.Fl background
1626mode, each number is attempted at most once.
1627
1628.It set reconnect timeout ntries
1629Should the line drop unexpectedly (due to loss of CD or LQR
1630failure), a connection will be re-established after the given
1631.Dq timeout .
1632The line will be re-connected at most
1633.Dq ntries
1634times.
1635.Dq Ntries
1636defaults to zero. A value of
1637.Dq random
1638for
1639.Dq timeout
1640will result in a variable pause, somewhere between 0 and 30 seconds.
1641
1642.It set redial seconds[.nseconds] [attempts]
1643.Nm Ppp
1644can be instructed to attempt to redial
1645.Dq attempts
1646times. If more than one number is specified (see
1647.Dq set phone
1648above), a pause of
1649.Dq nseconds
1650is taken before dialing each number. A pause of
1651.Dq seconds
1652is taken before starting at the first number again. A value of
1653.Dq random
1654may be used here too.
1655
1656.It set server|socket TcpPort|LocalName|none [mask]
1657Normally, when not in interactive mode,
1658.Nm
1659listens to a tcp socket for incoming command connections. The
1660socket number is calculated as 3000 plus the number of the
1661tunnel device that
1662.Nm
1663opened. So, for example, if
1664.Nm
1665opened tun2, socket 3002 would be used.
1666.Pp
1667Using this command, you can specify your own port number, a
1668local domain socket (specified as an absolute file name), or
1669you can tell
1670.Nm
1671not to accept any command connections. If a local domain socket
1672is specified, you may also specify an octal mask that should be
1673set before creating the socket. See also the use of
1674the
1675.Dv USR1
1676signal.
1677
1678.It set speed value
1679This sets the speed of the serial device.
1680
1681.It set timeout Idle [ lqr [ retry ] ]
1682This command allows the setting of the idle timer, the LQR timer (if
1683enabled) and the retry timer.
1684
1685.It set ns x.x.x.x
1686This option allows the setting of the Microsoft PPP DNS server that
1687will be negotiated.
1688
1689.It set nbns
1690This option allows the setting of the Microsoft NetBIOS DNS server that
1691will be negotiated.
1692
1693.It set help|?
1694This command gives a summary of available set commands.
1695.El
1696
1697.It shell|! [command]
1698Execute a shell according to the value of the
1699.Dv SHELL
1700environment variable. If
1701.Dq command
1702is specified, it is executed without a parent shell. Note, it's possible
1703to use the
1704.Dv HISADDR ,
1705.Dv INTERFACE
1706and
1707.Dv MYADDR
1708symbols here. Also note that if you use the ! character, you must have
1709a space between it and
1710.Dq command .
1711
1712.It show var
1713This command allows the user to examine the following:
1714
1715.Bl -tag -width 20
1716.It show [adio]filter
1717List the current rules for the given filter.
1718
1719.It show auth
1720Show the current authname and authkey.
1721
1722.It show ccp
1723Show the current CCP statistics.
1724
1725.It show compress
1726Show the current compress statistics.
1727
1728.It show escape
1729Show the current escape characters.
1730
1731.It show hdlc
1732Show the current HDLC statistics.
1733
1734.It show ipcp
1735Show the current IPCP statistics.
1736
1737.It show lcp
1738Show the current LCP statistics.
1739
1740.It show log
1741Show the current log values.
1742
1743.It show mem
1744Show current memory statistics.
1745
1746.It show modem
1747Show current modem statistics.
1748
1749.It show mru
1750Show the current MRU.
1751
1752.It show mtu
1753Show the current MTU.
1754
1755.It show proto
1756Show current protocol totals.
1757
1758.It show reconnect
1759Show the current reconnect values.
1760
1761.It show redial
1762Show the current redial values.
1763
1764.It show route
1765Show the current routing tables.
1766
1767.It show timeout
1768Show the current timeout values.
1769
1770.It show msext
1771Show the current Microsoft extension values.
1772
1773.It show version
1774Show the current version number of ppp.
1775
1776.It show help|?
1777Give a summary of available show commands.
1778.El
1779
1780.It term
1781Go into terminal mode. Characters typed at the keyboard are sent to
1782the modem. Characters read from the modem are displayed on the
1783screen. When a
1784.Nm
1785peer is detected on the other side of the modem,
1786.Nm
1787automatically enables Packet Mode and goes back into command mode.
1788
1789.It alias .....
1790This command allows the control of the aliasing (or masquerading)
1791facilities that are built into
1792.Nm ppp .
1793Until this code is required, it is not loaded by
1794.Nm ppp ,
1795and it is quite possible that the alias library is not installed
1796on your system (some administrators consider it a security risk).
1797
1798If aliasing is enabled on your system, the following commands are
1799possible:
1800
1801.Bl -tag -width 20
1802.It alias enable [yes|no]
1803This command either switches aliasing on or turns it off.
1804The
1805.Fl alias
1806command line flag is synonomous with
1807.Dq alias enable yes .
1808
1809.It alias port [proto targetIP:targetPORT [aliasIP:]aliasPORT]
1810This command allows us to redirect connections arriving at
1811.Dq aliasPORT
1812for machine [aliasIP] to
1813.Dq targetPORT
1814on
1815.Dq targetIP .
1816If proto is specified, only connections of the given protocol
1817are matched. This option is useful if you wish to things like
1818internet phone on the machines behind your gateway.
1819
1820.It alias addr [addr_local addr_alias]
1821This command allows data for
1822.Dq addr_alias
1823to be redirected to
1824.Dq addr_local .
1825It is useful if you own a small number of real IP numbers that
1826you wish to map to specific machines behind your gateway.
1827
1828.It alias deny_incoming [yes|no]
1829If set to yes, this command will refuse all incoming connections
1830by dropping the packets in much the same way as a firewall would.
1831
1832.It alias log [yes|no]
1833This option causes various aliasing statistics and information to
1834be logged to the file
1835.Pa /var/log/alias.log .
1836
1837.It alias same_ports [yes|no]
1838When enabled, this command will tell the alias library attempt to
1839avoid changing the port number on outgoing packets. This is useful
1840if you want to support protocols such as RPC and LPD which require
1841connections to come from a well known port.
1842
1843.It alias use_sockets [yes|no]
1844When enabled, this option tells the alias library to create a
1845socket so that it can guarantee a correct incoming ftp data or
1846IRC connection.
1847
1848.It alias unregistered_only [yes|no]
1849Only alter outgoing packets with an unregistered source ad-
1850dress. According to rfc 1918, unregistered source addresses
1851are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16.
1852
1853.It alias help|?
1854This command gives a summary of available alias commands.
1855
1856.El
1857
1858.It quit|bye [all]
1859Exit
1860.Nm ppp.
1861If
1862.Nm
1863is in interactive mode or if the
1864.Dq all
1865argument is given, ppp will exit, closing the connection. A simple
1866.Dq quit
1867issued from a telnet session will not close the current connection.
1868
1869.It help|? [command]
1870Show a list of available commands. If
1871.Dq command
1872is specified, show the usage string for that command.
1873
1874.It down
1875Bring the link down ungracefully. It's not considered polite to
1876use this command.
1877
1878.El
1879
1880.Sh MORE DETAILS
1881
1882.Bl -bullet -compact
1883
1884.It
1885Read the example configuration files. They are a good source of information.
1886
1887.It
1888Use
1889.Dq help ,
1890.Dq show ? ,
1891.Dq alias ? ,
1892.Dq set ?
1893and
1894.Dq set ? <var>
1895commands.
1896.El
1897
1898.Sh FILES
1899.Nm Ppp
1900refers to four files: ppp.conf, ppp.linkup, ppp.linkdown and
1901ppp.secret. These files are placed in
1902.Pa /etc/ppp ,
1903but the user can create his own files under his $HOME directory as
1904.Pa .ppp.conf ,
1905.Pa .ppp.linkup ,
1906.Pa .ppp.linkdown
1907and
1908.Pa .ppp.secret.
1909.Nm
1910will always try to consult the user's personal setup first.
1911
1912.Bl -tag -width flag
1913.Pa $HOME/ppp/.ppp.[conf|linkup|linkdown|secret]
1914User dependent configuration files.
1915
1916.Pa /etc/ppp/ppp.conf
1917System default configuration file.
1918
1919.Pa /etc/ppp/ppp.secret
1920An authorization file for each system.
1921
1922.Pa /etc/ppp/ppp.linkup
1923A file to check when
1924.Nm
1925establishes a network level connection.
1926
1927.Pa /etc/ppp/ppp.linkdown
1928A file to check when
1929.Nm
1930closes a network level connection.
1931
| 2.Dd 20 September 1995
3.Os FreeBSD
4.Dt PPP 8
5.Sh NAME
6.Nm ppp
7.Nd
8Point to Point Protocol (aka iijppp)
9.Sh SYNOPSIS
10.Nm
11.Op Fl auto | background | ddial | direct | dedicated
12.Op Fl alias
13.Op Ar system
14.Sh DESCRIPTION
15This is a user process
16.Em PPP
17software package. Normally,
18.Em PPP
19is implemented as a part of the kernel (e.g. as managed by pppd) and it's
20thus somewhat hard to debug and/or modify its behavior. However, in this
21implementation
22.Em PPP
23is done as a user process with the help of the
24tunnel device driver (tun).
25
26.Sh Major Features
27
28.Bl -diag
29.It Provides interactive user interface.
30Using its command mode, the user can
31easily enter commands to establish the connection with the remote end, check
32the status of connection and close the connection. All functions can
33also be optionally password protected for security.
34
35.It Supports both manual and automatic dialing.
36Interactive mode has a
37.Dq term
38command which enables you to talk to your modem directly. When your
39modem is connected to the remote peer and it starts to talk
40.Em PPP
41, the
42.Em PPP
43software detects it and switches to packet
44mode automatically. Once you have determined the proper sequence for connecting
45with the remote host, you can write a chat script to define the necessary
46dialing and login procedure for later convenience.
47
48.It Supports on-demand dialup capability.
49By using auto mode,
50.Nm
51will act as a daemon and wait for a packet to be sent over the
52.Em PPP
53link. When this happens, the daemon automatically dials and establishes the
54connection.
55
56In almost the same manner ddial mode (dedicated or daemon dialing)
57also automatically dials and establishes the connection. However, it
58differs in that it will dial the remote site any time it detects the
59link is down, even if there are no packets to be sent. This mode is
60useful for full-time connections who worry less about line charges
61and more about being connected full time.
62
63.It Supports packet aliasing.
64Packet aliasing, more commonly known as masquerading, allows computers
65on a private, unregistered network to access the internet. The
66.Em PPP
67host acts as a masquerading gateway. IP addresses as well as TCP and
68UDP port numbers are aliased for outgoing packets and de-aliased for
69returning packets.
70
71.It Supports background PPP connections.
72In background mode, if
73.Nm
74successfully establishes the connection, it will become a daemon.
75Otherwise, it will exit with an error.
76
77.It Supports server-side PPP connections.
78In direct mode,
79.nm
80acts as server which accepts incoming
81.Em PPP
82connections on stdin/stdout.
83
84.It Supports PAP and CHAP authentication.
85
86.It Supports Proxy Arp.
87When
88.Em PPP
89is set up as server, you can also configure it to do proxy arp for your
90connection.
91
92.It Supports packet filtering.
93User can define four kinds of filters:
94.Em ifilter
95for incoming packets,
96.Em ofilter
97for outgoing packets,
98.Em dfilter
99to define a dialing trigger packet and
100.Em afilter
101for keeping a connection alive with the trigger packet.
102
103.It Tunnel driver supports bpf.
104The user can use
105.Xr tcpdump 1
106to check the packet flow over the
107.Em PPP
108link.
109
110.It Supports PPP over TCP capability.
111
112
113.It Supports IETF draft Predictor-1 compression.
114.Nm
115supports not only VJ-compression but also Predictor-1 compression.
116Normally, a modem has built-in compression (e.g. v42.bis) and the system
117may receive higher data rates from it as a result of such compression.
118While this is generally a good thing in most other situations, this
119higher speed data imposes a penalty on the system by increasing the
120number of serial interrupts the system has to process in talking to the
121modem and also increases latency. Unlike VJ-compression, Predictor-1
122compression pre-compresses
123.Em all
124data flowing through the link, thus reducing overhead to a minimum.
125
126.It Supports Microsofts IPCP extentions.
127Name Server Addresses and NetBIOS Name Server Addresses can be negotiated
128with clients using the Microsoft
129.Em PPP
130stack (ie. Win95, WinNT)
131
132.Sh GETTING STARTED
133
134When you first run
135.Nm
136you may need to deal with some initial configuration details. First,
137your kernel should include a tunnel device (the default in FreeBSD 2.0.5
138and later). If it doesn't, or if you require more than one tun interface,
139you'll need to rebuild your kernel with the following line in your kernel
140configuration file:
141
142.Dl pseudo-device tun N
143
144where
145.Ar N
146is the maximum number of
147.Em PPP
148connections you wish to support.
149
150Second, check your
151.Pa /dev
152directory for the tunnel device entries
153.Pa /dev/tunN ,
154where
155.Ar N
156represents the number of the tun device, starting at zero.
157If they don't exist, you can create them by running "sh ./MAKEDEV tunN".
158This will create tun devices 0 through
159.Ar N .
160
161Last of all, create a log file.
162.Nm Ppp
163uses
164.Xr syslog 3
165to log information. A common log file name is
166.Pa /var/log/ppp.log .
167To make output go to this file, put the following lines in the
168.Pa /etc/syslog.conf
169file:
170
171.Dl !ppp
172.Dl *.* /var/log/ppp.log
173
174It is possible to have more than one ppp log file by creating a link
175to the ppp executable:
176
177.Dl # cd /usr/sbin
178.Dl # ln ppp ppp0
179
180and using
181
182.Dl !ppp0
183.Dl *.* /var/log/ppp0.log
184
185in
186.Pa /etc/syslog.conf .
187Don't forget to send a
188.Dv HUP
189signal to
190.Nm syslogd
191after altering
192.Pa /etc/syslog.conf .
193
194.Sh MANUAL DIALING
195
196In the following examples, we assume that your machine name is
197.Nm awfulhak .
198
199If you set your hostname and password in
200.Pa /etc/ppp/ppp.secret ,
201you can't do anything except run the help, passwd and quit commands.
202
203.Bd -literal -offset indent
204ppp on "your hostname"> help
205 help : Display this message
206 passwd : Password for security
207 quit : Quit the PPP program
208ppp on awfulhak> pass <password>
209.Ed
210
211The "on" part of your prompt will change to "ON" if you specify the
212correct password.
213
214.Bd -literal -offset indent
215ppp ON awfulhak>
216.Ed
217
218You can now specify the device name, speed and parity for your modem,
219and whether CTS/RTS signalling should be used (CTS/RTS is used by
220default). If your hardware does not provide CTS/RTS lines (as
221may happen when you are connected directly to certain ppp-capable
222terminal servers),
223.Nm
224will never send any output through the port; it waits for a signal
225which never comes. Thus, if you have a direct line and can't seem
226to make a connection, try turning ctsrts off:
227
228
229.Bd -literal -offset indent
230ppp ON awfulhak> set line /dev/cuaa0
231ppp ON awfulhak> set speed 38400
232ppp ON awfulhak> set parity even
233ppp ON awfulhak> set ctsrts on
234ppp ON awfulhak> show modem
235
236* Modem related information is shown here *
237
238ppp ON awfulhak>
239.Ed
240
241The term command can now be used to talk directly with your modem:
242
243.Bd -literal -offset indent
244ppp ON awfulhak> term
245at
246OK
247atdt123456
248CONNECT
249login: ppp
250Password:
251Protocol: ppp
252.Ed
253
254When the peer starts to talk in PPP,
255.Nm
256detects this automatically and returns to command mode.
257
258.Bd -literal -offset indent
259ppp ON awfulhak>
260PPP ON awfulhak>
261.Ed
262
263You are now connected! Note that
264.Sq PPP
265in the prompt has changed to capital letters to indicate that you have
266a peer connection. The show command can be used to see how things are
267going:
268
269.Bd -literal -offset indent
270PPP ON awfulhak> show lcp
271
272* LCP related information is shown here *
273
274PPP ON awfulhak> show ipcp
275
276* IPCP related information is shown here *
277.Ed
278
279At this point, your machine has a host route to the peer. This means
280that you can only make a connection with the host on the other side
281of the link. If you want to add a default route entry (telling your
282machine to send all packets without another routing entry to the other
283side of the ppp link), enter the following command:
284
285.Bd -literal -offset indent
286PPP ON awfulhak> add 0 0 HISADDR
287.Ed
288
289The string
290.Sq HISADDR
291represents the IP address of the connected peer. This variable is only
292available once a connection has been established. A common error
293is to specify the above command in your
294.Pa ppp.conf
295file. This won't work as the remote IP address hasn't been
296established when this file is read.
297
298You can now use your network applications (ping, telnet, ftp etc.)
299in other windows on your machine.
300
301Refer to the PPP COMMAND LIST section for details on all available commands.
302
303.Sh AUTOMATIC DIALING
304
305To use automatic dialing, you must prepare some Dial and Login chat scripts.
306See the example definitions in
307.Pa /etc/ppp/ppp.conf.sample
308(the format of ppp.conf is pretty simple).
309
310.Bl -bullet -compact
311
312.It
313Each line contains one command, label or comment.
314
315.It
316A line starting with a
317.Sq #
318character is treated as a comment line.
319
320.It
321A label name starts in the first column and is followed by
322a colon (:).
323
324.It
325A command line must contain a space or tab in the first column.
326
327.El
328
329The
330.Pa ppp.conf
331file should consist of at least a
332.Dq default
333section. This section is always executed. It should also contain
334one or more sections, named according to their purpose, for example,
335.Dq MyISP
336would represent your ISP, and
337.Dq ppp-in
338would represent an incoming
339.Nm
340configuration.
341
342You can now specify the destination label name when you invoke
343.Nm ppp .
344Commands associated with the
345.Dq default
346label are executed, followed by those associated with the destination
347label provided. When
348.Nm
349is started with no arguments, the
350.Dq default
351section is still executed. The load command can be used to manually
352load a section from the
353.Pa ppp.conf
354file:
355
356.Bd -literal -offset indent
357PPP ON awfulhak> load MyISP
358.Ed
359
360Once the connection is made, the ppp portion of the prompt will change
361to PPP:
362
363.Bd -literal -offset indent
364# ppp MyISP
365...
366ppp ON awfulhak> dial
367dial OK!
368login OK!
369PPP ON awfulhak>
370.Ed
371
372If the
373.Pa /etc/ppp/ppp.linkup
374file is available, its contents are executed
375when the
376.Em PPP
377connection is established. See the provided
378.Dq pmdemand
379example in
380.Pa /etc/ppp/ppp.conf.sample
381which adds a default route. The string HISADDR is available as the IP
382address of the remote peer. Similarly, when a connection is closed, the
383contents of the
384.Pa /etc/ppp/ppp.linkdown
385file are executed.
386
387.Sh BACKGROUND DIALING
388
389If you want to establish a connection using
390.Nm
391non-interactively (such as from a
392.Xr crontab(5)
393entry or an
394.Xr at(1)
395job) you should use the
396.Fl background
397option. You must also specify the destination label in
398.Pa /etc/ppp/ppp.conf
399to use. This label must contain the
400.Dq set ifaddr
401command to define the remote peer's IP address. (refer to
402.Pa /etc/ppp/ppp.conf.sample )
403
404When
405.Fl background
406is specified,
407.Nm
408attempts to establish the connection immediately. If multiple phone
409numbers are specified, each phone number will be tried once. If the
410attempt fails,
411.Nm
412exits immediately with a non-zero exit code.
413
414If it succeeds, then
415.Nm
416becomes a daemon, and returns an exit status of zero to its caller.
417The daemon exits automatically if the connection is dropped by the
418remote system, or it receives a
419.Dv TERM
420signal.
421
422.Sh DIAL ON DEMAND
423
424Demand dialing is enabled with the
425.Fl auto
426or
427.Fl ddial
428options. You must also specify the destination label in
429.Pa /etc/ppp/ppp.conf
430to use. It must contain the
431.Dq set ifaddr
432command to define the remote peer's IP address. (refer to
433.Pa /etc/ppp/ppp.conf.sample )
434
435.Bd -literal -offset indent
436# ppp -auto pmdemand
437...
438#
439.Ed
440
441When
442.Fl auto
443or
444.Fl ddial
445is specified,
446.Nm
447runs as a daemon but you can still configure or examine its
448configuration by using the diagnostic port as follows (this
449can be done in
450.Fl background
451and
452.Fl direct
453mode too):
454
455
456.Bd -literal -offset indent
457# telnet localhost 3000
458Trying 127.0.0.1...
459Connected to awfulhak.
460Escape character is '^]'.
461....
462PPP on awfulhak> pass xxxx
463PPP ON awfulhak> show ipcp
464IPCP [OPEND]
465 his side: xxxx
466 ....
467.Ed
468
469.Pp
470Each
471.Nm
472daemon has an associated port number which is computed as "3000 +
473tunnel_device_number".
474
475In
476.Fl auto
477mode, when an outgoing packet is detected,
478.Nm
479will perform the dialing action (chat script) and try to connect
480with the peer. In
481.Fl ddial
482mode, the dialing action is performed any time the line is found
483to be down.
484
485If the connect fails, the default behavior is to wait 30 seconds
486and then attempt to connect when another outgoing packet is detected.
487This behavior can be changed with
488.Bd -literal -offset indent
489set redial seconds|random[.nseconds|random] [dial_attempts]
490.Ed
491.Pp
492.Sq Seconds
493is the number of seconds to wait before attempting
494to connect again. If the argument is
495.Sq random ,
496the delay period is a random value between 0 and 30 seconds.
497.Sq Nseconds
498is the number of seconds to wait before attempting
499to dial the next number in a list of numbers (see the
500.Dq set phone
501command). The default is 3 seconds. Again, if the argument is
502.Sq random ,
503the delay period is a random value between 0 and 30 seconds.
504.Sq dial_attempts
505is the number of times to try to connect for each outgoing packet
506that is received. The previous value is unchanged if this parameter
507is omitted. If a value of zero is specified for
508.Sq dial_attempts ,
509.Nm ppp
510will keep trying until a connection is made.
511.Bd -literal -offset indent
512set redial 10.3 4
513.Ed
514.Pp
515will attempt to connect 4 times for each outgoing packet that is
516detected with a 3 second delay between each number and a 10 second
517delay after all numbers have been tried. If multiple phone numbers
518are specified, the total number of attempts is still 4 (it does not
519attempt each number 4 times).
520
521Modifying the dial delay is very useful when running
522.Nm
523in demand
524dial mode on both ends of the link. If each end has the same timeout,
525both ends wind up calling each other at the same time if the link
526drops and both ends have packets queued.
527
528At some locations, the serial link may not be reliable, and carrier
529may be lost at inappropriate times. It is possible to have
530.Nm
531redial should carrier be unexpectedly lost during a session.
532.Bd -literal -offset indent
533set reconnect timeout ntries
534.Ed
535
536This command tells ppp to re-establish the connection
537.Ar ntries
538times on loss of carrier with a pause of
539.Ar timeout
540seconds before each try. For example,
541.Bd -literal -offset indent
542set reconnect 3 5
543.Ed
544
545tells
546.Nm
547that on an unexpected loss of carrier, it should wait
548.Ar 3
549seconds before attempting to reconnect. This may happen up to
550.Ar 5
551times before
552.Nm
553gives up. The default value of ntries is zero (no reconnect). Care
554should be taken with this option. If the local timeout is slightly
555longer than the remote timeout, the reconnect feature will always be
556triggered (up to the given number of times) after the remote side
557times out and hangs up.
558
559NOTE: In this context, losing too many LQRs constitutes a loss of
560carrier and will trigger a reconnect.
561
562If the
563.Fl background
564flag is specified, all phone numbers are dialed at most once until
565a connection is made. The next number redial period specified with
566the
567.Dq set redial
568command is honoured, as is the reconnect tries value. If your redial
569value is less than the number of phone numbers specified, not all
570the specified numbers will be tried.
571
572To terminate the program, type
573
574 PPP ON awfulhak> close
575 ppp ON awfulhak> quit all
576
577.Pp
578A simple
579.Dq quit
580command will terminate the telnet connection but not the program itself.
581You must use
582.Dq quit all
583to terminate the program as well.
584
585.Sh RECEIVING INCOMING PPP CONNECTIONS (Method 1)
586
587To handle an incoming
588.Em PPP
589connection request, follow these steps:
590
591.Bl -enum
592.It
593Make sure the modem and (optionally)
594.Pa /etc/rc.serial
595is configured correctly.
596.Bl -bullet -compact
597.It
598Use Hardware Handshake (CTS/RTS) for flow control.
599.It
600Modem should be set to NO echo back (ATE0) and NO results string (ATQ1).
601.El
602
603.It
604Edit
605.Pa /etc/ttys
606to enable a getty on the port where the modem is attached.
607
608For example:
609
610.Dl ttyd1 "/usr/libexec/getty std.38400" dialup on secure
611
612Don't forget to send a
613.Dv HUP
614signal to the init process to start the getty.
615
616.Dl # kill -HUP 1
617
618.It
619Prepare an account for the incoming user.
620.Bd -literal
621ppp:xxxx:66:66:PPP Login User:/home/ppp:/usr/local/bin/ppplogin
622.Ed
623
624.It
625Create a
626.Pa /usr/local/bin/ppplogin
627file with the following contents:
628.Bd -literal -offset indent
629#!/bin/sh -p
630exec /usr/sbin/ppp -direct
631.Ed
632
633(You can specify a label name for further control.)
634
635.Pp
636Direct mode (
637.Fl direct
638) lets
639.Nm
640work with stdin and stdout. You can also telnet to port 3000 plus
641the current tunnel device number to get command mode control in the
642same manner as client-side
643.Nm.
644
645.It
646Optional support for Microsoft's IPCP Name Server and NetBIOS
647Name Server negotiation can be enabled use
648.Dq enable msext
649and
650.Dq set ns pri-addr [sec-addr]
651along with
652.Dq set nbns pri-addr [sec-addr]
653in your ppp.conf file
654
655.El
656
657.Sh RECEIVING INCOMING PPP CONNECTIONS (Method 2)
658
659This method differs in that it recommends the use of
660.Em mgetty+sendfax
661to handle the modem connections. The latest version 0.99
662can be compiled with the
663.Dq AUTO_PPP
664option to allow detection of clients speaking PPP to the login
665prompt.
666
667Follow these steps:
668
669.Bl -enum
670
671.It
672Get, configure, and install mgetty+sendfax v0.99 or later making
673sure you have used the AUTO_PPP option.
674
675.It
676Edit
677.Pa /etc/ttys
678to enable a mgetty on the port where the modem is attached. For
679example:
680
681.Dl cuaa1 "/usr/local/sbin/mgetty -s 57600" dialup on
682
683.It
684Prepare an account for the incoming user.
685.Bd -literal
686Pfred:xxxx:66:66:Fred's PPP:/home/ppp:/etc/ppp/ppp-dialup
687.Ed
688
689.It
690Examine the files
691.Pa /etc/ppp/sample.ppp-dialup
692.Pa /etc/ppp/sample.ppp-pap-dialup
693and
694.Pa /etc/ppp/ppp.conf.sample
695for ideas. ppp-pap-dialup is supposed to be called from
696.Pa /usr/local/etc/mgetty+sendfax/login.conf
697from a line like
698
699.Dl /AutoPPP/ - - /etc/ppp/ppp-pap-dialup
700.El
701
702.Sh PPP OVER TCP (a.k.a Tunneling)
703
704Instead of running ppp over a serial link, it is possible to
705use a tcp connection instead by specifying a host and port as the
706device:
707
708.Dl set device ui-gate:6669
709
710Instead of opening a serial device,
711.Nm
712will open a tcp connection to the given machine on the given
713socket. It should be noted however that
714.Nm
715doesn't use the telnet protocol and will be unable to negotiate
716with a telnet server. You should set up a port for receiving
717this ppp connection on the receiving machine (ui-gate). This is
718done by first updating
719.Pa /etc/services
720to name the service:
721
722.Dl ppp-in 6669/tcp # Incoming ppp connections over tcp
723
724and updating
725.Pa /etc/inetd.conf
726to tell inetd how to deal with incoming connections on that port:
727
728.Dl ppp-in stream tcp nowait root /usr/sbin/ppp ppp -direct ppp-in
729
730Don't forget to send a
731.Dv HUP
732signal to
733.Nm inetd
734after you've updated
735.Pa /etc/inetd.conf .
736
737Here, we use a label named
738.Dq ppp-in .
739The entry in
740.Pa /etc/ppp/ppp.conf
741on ui-gate (the receiver) should contain the following:
742
743.Bd -literal -offset indent
744ppp-in:
745 set timeout 0
746 set ifaddr 10.0.4.1 10.0.4.2
747 add 10.0.4.1 255.255.255.255 127.0.0.1
748 add 10.0.1.0 255.255.255.0 10.0.4.1
749.Ed
750
751You may also want to enable PAP or CHAP for security. The entry in
752.Pa /etc/ppp/ppp.conf
753on awfulhak (the initiator) should contain the following:
754
755.Bd -literal -offset indent
756ui-gate:
757 set escape 0xff
758 set device ui-gate:ppp-in
759 set dial
760 set timeout 30 5 4
761 set log Phase Chat Connect Carrier hdlc LCP tun
762 set ifaddr 10.0.4.2 10.0.4.1
763 add 10.0.4.2 255.255.255.255 127.0.0.1
764 add 10.0.2.0 255.255.255.0 10.0.4.2
765.Ed
766
767We're assigning the address of 10.0.4.1 to ui-gate, and the address
76810.0.4.2 to awfulhak.
769
770To open the connection, just type
771
772.Dl awfulhak # ppp -background ui-gate
773
774The result will be an additional "route" on awfulhak to the
77510.0.2.0/24 network via the tcp connection, and an additional
776"route" on ui-gate to the 10.0.1.0/24 network.
777
778The networks are effectively bridged - the underlying tcp
779connection may be across a public network (such as the
780Internet), and the ppp traffic is conceptually encapsulated
781(although not packet by packet) inside the tcp stream between
782the two gateways.
783
784The major disadvantage of this mechanism is that there are two
785"guaranteed delivery" mechanisms in place - the underlying tcp
786stream and whatever protocol is used over the ppp link - probably
787tcp again. If packets are lost, both levels will get in eachothers
788way trying to negotiate sending of the missing packet.
789
790.Sh PACKET ALIASING
791
792The
793.Fl alias
794command line option enables packet aliasing. This allows the
795ppp host to act as a masquerading gateway for other computers over
796a local area network. Outgoing IP packets are aliased so that
797they appear to come from the ppp host, and incoming packets are
798de-aliased so that they are routed to the correct machine on the
799local area network.
800
801Packet aliasing allows computers on private, unregistered
802subnets to have internet access, although they are invisible
803from the outside world.
804
805In general, correct ppp operation should first be verified
806with packet aliasing disabled. Then, the
807.Fl alias
808option should be switched on, and network applications (web browser,
809telnet, ftp, ping, traceroute) should be checked on the ppp host.
810Finally, the same or similar applications should be checked on other
811computers in the LAN.
812
813If network applications work correctly on the ppp host, but not on
814other machines in the LAN, then the masquerading software is working
815properly, but the host is either not forwarding or possibly receiving
816IP packets. Check that IP forwarding is enabled in
817.Pa /etc/rc.conf
818and that other machines have designated the ppp host as the gateway
819for the LAN.
820
821.Sh PACKET FILTERING
822
823This implementation supports packet filtering. There are four kinds of
824filters; ifilter, ofilter, dfilter and afilter. Here are the basics:
825
826.Bl -bullet -compact
827.It
828A filter definition has the following syntax:
829
830set filter-name rule-no action [src_addr/src_width] [dst_addr/dst_width]
831[proto [src [lt|eq|gt] port ]] [dst [lt|eq|gt] port] [estab]
832.Bl -enum
833.It
834.Sq filter-name
835should be one of ifilter, ofilter, dfilter or afilter.
836.It
837There are two actions:
838.Sq permit
839and
840.Sq deny .
841If a given packet
842matches the rule, the associated action is taken immediately.
843.It
844.Sq src_width
845and
846.Sq dst_width
847work like a netmask to represent an address range.
848.It
849.Sq proto
850must be one of icmp, udp or tcp.
851.It
852.Sq port number
853can be specified by number and service name from
854.Pa /etc/services .
855
856.El
857
858.It
859Each filter can hold up to 20 rules, starting from rule 0.
860The entire rule set is not effective until rule 0 is defined,
861ie. the default is to allow everything through.
862
863.It
864If no rule is matched to a packet, that packet will be discarded
865(blocked).
866
867.It
868Use
869.Dq set filter-name -1
870to flush all rules.
871
872.El
873
874See
875.Pa /etc/ppp/ppp.conf.filter.example .
876
877
878.Sh SETTING IDLE, LINE QUALITY REQUEST, RETRY TIMER
879
880To check/set idletimer, use the
881.Dq show timeout
882and
883.Dq set timeout [lqrtimer [retrytimer]]
884commands:
885
886.Bd -literal -offset indent
887ppp ON awfulhak> set timeout 600
888.Ed
889
890The timeout period is measured in seconds, the default values for which
891are timeout = 180 or 3 min, lqrtimer = 30sec and retrytimer = 3sec.
892To disable the idle timer function, use the command
893
894.Bd -literal -offset indent
895ppp ON awfulhak> set timeout 0
896.Ed
897
898In
899.Fl auto
900mode, an idle timeout causes the
901.Em PPP
902session to be
903closed, though the
904.Nm
905program itself remains running. Another trigger packet will cause it to
906attempt to reestablish the link.
907
908.Sh PREDICTOR-1 COMPRESSION
909
910This version supports CCP and Predictor type 1 compression based on
911the current IETF-draft specs. As a default behavior,
912.Nm
913will attempt to use (or be willing to accept) this capability when the
914peer agrees (or requests it).
915
916To disable CCP/predictor functionality completely, use the
917.Dq disable pred1
918and
919.Dq deny pred1
920commands.
921
922.Sh CONTROLLING IP ADDRESS
923
924.Nm
925uses IPCP to negotiate IP addresses. Each side of the connection
926specifies the IP address that it's willing to use, and if the requested
927IP address is acceptable then
928.Nm
929returns ACK to the requester. Otherwise,
930.Nm
931returns NAK to suggest that the peer use a different IP address. When
932both sides of the connection agree to accept the received request (and
933send ACK), IPCP is set to the open state and a network level connection
934is established.
935
936To control this IPCP behavior, this implementation has the
937.Dq set ifaddr
938command for defining the local and remote IP address:
939
940.Nm set ifaddr
941.Op src_addr Op dst_addr Op netmask
942
943Where,
944.Sq src_addr
945is the IP address that the local side is willing to use and
946.Sq dst_addr
947is the IP address which the remote side should use.
948.Sq netmask
949is interface netmask.
950
951.Bd -literal -offset indent
952set ifaddr 192.244.177.38 192.244.177.2 255.255.255.0
953.Ed
954
955The above specification means:
956.Bl -bullet -compact
957.It
958I strongly want to use 192.244.177.38 as my IP address, and I'll
959disagree if the peer suggests that I use another address.
960
961.It
962I strongly insist that peer use 192.244.177.2 as own side address and
963don't permit it to use any IP address but 192.244.177.2. When peer
964request another IP address, I always suggest that it use 192.244.177.2.
965
966.It
967My interface netmask will be 255.255.255.0.
968.El
969
970This is all fine when each side has a pre-determined IP address, however
971it is often the case that one side is acting as a server which controls
972all IP addresses and the other side should obey the direction from it.
973
974In order to allow more flexible behavior, `ifaddr' variable allows the
975user to specify IP address more loosely:
976
977.Dl set ifaddr 192.244.177.38/24 192.244.177.2/20
978
979A number followed by a slash (/) represent the number of bits significant in
980the IP address. The above example signifies that:
981
982.Bl -bullet -compact
983.It
984I'd like to use 192.244.177.38 as my address if it is possible, but I'll
985also accept any IP address between 192.244.177.0 and 192.244.177.255.
986
987.It
988I'd like to make him use 192.244.177.2 as his own address, but I'll also
989permit him to use any IP address between 192.244.176.0 and
990192.244.191.255.
991
992.It
993As you may have already noticed, 192.244.177.2 is equivalent to saying
994192.244.177.2/32.
995
996.It
997As an exception, 0 is equivalent to 0.0.0.0/0, meaning that I have no
998preferred IP address and will obey the remote peer's selection. When
999using zero, no routing table entries will be made until a connection
1000is established.
1001
1002.It
1003192.244.177.2/0 means that I'll accept/permit any IP address but I'll
1004try to insist that 192.244.177.2 be used first.
1005.El
1006
1007.Sh CONNECTING WITH YOUR INTERNET SERVICE PROVIDER
1008
1009The following steps should be taken when connecting to your ISP:
1010
1011.Bl -enum
1012.It
1013Describe your provider's phone number(s) in the dial script using the
1014.Dq set phone
1015command. This command allows you to set multiple phone numbers for
1016dialing and redialing separated by a colon (:). For example:
1017.Bd -literal -offset indent
1018set phone "1234567:2345678"
1019.Ed
1020.Pp
1021Here, the first number is attempted. If the connection fails, the second
1022number is attempted after the next number redial period. If the second number
1023also fails, the first is tried again after the redial period has expired.
1024The selected phone number is substituted for the \\T string in the
1025.Dq set dial
1026command (see below).
1027
1028.It
1029Set up your redial requirements using
1030.Dq set redial .
1031For example, if you have a bad telephone line or your provider is
1032usually engaged (not so common these days), you may want to specify
1033the following:
1034.Bd -literal -offset indent
1035set redial 10 4
1036.Ed
1037.Pp
1038This says that up to 4 phone calls should be attempted with a pause of 10
1039seconds before dialing the first number again.
1040
1041.It
1042Describe your login procedure using the
1043.Dq set dial
1044and
1045.Dq set login
1046commands. The
1047.Dq set dial
1048command is used to talk to your modem and establish a link with your
1049ISP, for example:
1050.Bd -literal -offset indent
1051set dial "ABORT BUSY ABORT NO\\\\sCARRIER TIMEOUT 4 \\"\\" ATZ OK-ATZ-OK ATDT\\\\T TIMEOUT 60 CONNECT"
1052.Ed
1053.Pp
1054This modem "chat" string means:
1055
1056.Bl -bullet
1057.It
1058Abort if the string "BUSY" or "NO CARRIER" are received.
1059.It
1060Set the timeout to 4.
1061.It
1062Expect nothing.
1063.It
1064Send ATZ.
1065.It
1066Expect OK. If that's not received, send ATZ and expect OK.
1067.It
1068Send ATDTxxxxxxx where xxxxxxx is the next number in the phone list from
1069above.
1070.It
1071Set the timeout to 60.
1072.It
1073Wait for the CONNECT string.
1074.El
1075
1076Once the connection is established, the login script is executed. This
1077script is written in the same style as the dial script:
1078.Bd -literal -offset indent
1079set login "TIMEOUT 15 login:-\\\\r-login: awfulhak word: xxx ocol: PPP HELLO"
1080.Ed
1081.Pp
1082This login "chat" string means:
1083
1084.Bl -bullet
1085.It
1086Set the timeout to 15 seconds.
1087.It
1088Expect "login:". If it's not received, send a carriage return and expect
1089"login:" again.
1090.It
1091Send "awfulhak"
1092.It
1093Expect "word:" (the tail end of a "Password:" prompt).
1094.It
1095Send "xxx".
1096.It
1097Expect "ocol:" (the tail end of a "Protocol:" prompt).
1098.It
1099Send "PPP".
1100.It
1101Expect "HELLO".
1102.El
1103.Pp
1104Login scripts vary greatly between ISPs.
1105
1106.It
1107Use
1108.Dq set line
1109and
1110.Dq set sp
1111to specify your serial line and speed, for example:
1112.Bd -literal -offset indent
1113set line /dev/cuaa0
1114set sp 115200
1115.Ed
1116.Pp
1117Cuaa0 is the first serial port on FreeBSD. Cuaa1 is the second etc. A
1118speed of 115200 should be specified if you have a modem capable of bit
1119rates of 28800 or more. In general, the serial speed should be about
1120four times the modem speed.
1121
1122.It
1123Use
1124.Dq set ifaddr
1125command to define the IP address.
1126.Bl -bullet
1127.It
1128If you know what IP address your provider uses, then use it as the remote
1129address, otherwise choose something like 10.0.0.2/0 (see below).
1130.It
1131If your provider has assigned a particular IP address to you, then use
1132it as your address.
1133.It
1134If your provider assigns your address dynamically, choose a suitably
1135unobtrusive and unspecific IP number as your address. 10.0.0.1/0 would
1136be appropriate. The bit after the / specifies how many bits of the
1137address you consider to be important, so if you wanted to insist on
1138something in the class C network 1.2.3.0, you could specify 1.2.3.1/24.
1139.El
1140.Pp
1141An example for a connection where you don't know your IP number or your
1142ISPs IP number would be:
1143.Bd -literal -offset indent
1144set ifaddr 10.10.10.10/0 10.10.11.11/0 255.255.255.0
1145.Ed
1146
1147.It
1148In most cases, your ISP will also be your default router. If this is
1149the case, add the lines
1150
1151.Bd -literal -offset indent
1152delete ALL
1153add 0 0 10.10.11.11
1154.Ed
1155
1156.Pp
1157to
1158.Pa ppp.conf .
1159.Pp
1160This tells
1161.Nm
1162to delete all non-direct routing entries for the tun interface that
1163.Nm
1164is running on, then to add a default route to 10.10.11.11.
1165.Pp
1166If you're using dynamic IP numbers, you must also put these two lines
1167in the
1168.Pa ppp.linkup
1169file:
1170
1171.Bd -literal -offset indent
1172delete ALL
1173add 0 0 HISADDR
1174.Ed
1175
1176HISADDR is a macro meaning the "other side"s IP number, and is
1177available once an IP number has been agreed (using LCP).
1178Now, once a connection is established,
1179.Nm ppp
1180will delete all non-direct interface routes, and add a default route
1181pointing at the peers IP number. You should use the same label as the
1182one used in
1183.Pa ppp.conf .
1184.Pp
1185If commands are being typed interactively, the only requirement is
1186to type
1187.Bd -literal -offset indent
1188add 0 0 HISADDR
1189.Ed
1190.Pp
1191after a successful dial.
1192
1193.It
1194If your provider requests that you use PAP/CHAP authentication methods, add
1195the next lines to your
1196.Pa ppp.conf
1197file:
1198.Bd -literal -offset indent
1199enable pap (or enable chap)
1200disable chap (or disable pap)
1201set authname MyName
1202set authkey MyPassword
1203.Ed
1204
1205.El
1206
1207Please refer to
1208.Pa /etc/ppp/ppp.conf.sample
1209and
1210.Pa /etc/ppp/ppp.linkup.sample
1211for some real examples. The pmdemand label should be appropriate for most
1212ISPs.
1213
1214.Sh LOGGING FACILITY
1215
1216.Nm
1217is able to generate the following log info via
1218.Xr syslog 3 :
1219
1220.Bl -column SMMMMMM -offset indent
1221.It Li Async Dump async level packet in hex
1222.It Li Carrier Log Chat lines with 'CARRIER'
1223.It Li Chat Generate Chat script trace log
1224.It Li Command Log commands executed
1225.It Li Connect Generate complete Chat log
1226.It Li Debug Log (very verbose) debug information
1227.It Li HDLC Dump HDLC packet in hex
1228.It Li LCP Generate LCP/IPCP packet trace
1229.It Li Link Log address assignments and link up/down events
1230.It Li LQM Generate LQR report
1231.It Li Phase Phase transition log output
1232.It Li TCP/IP Dump all TCP/IP packets
1233.It Li TUN Include the tun device on each log line
1234.It Li Warning Output to the terminal device. If there is currently no
1235terminal, output is sent to the log file using LOG_WARNING.
1236.It Li Error Output to both the terminal device and the log file using
1237LOG_ERROR.
1238.It Li Alert Output to the log file using LOG_ALERT
1239.El
1240
1241The
1242.Dq set log
1243command allows you to set logging output level, of which
1244multiple levels can be specified. The default is equivalent to
1245.Dq set log Carrier Link Phase .
1246
1247If The first argument to
1248.Dq set log
1249begins with a '+' or a '-' character, the current log levels are
1250not cleared, for example:
1251
1252.Bd -literal -offset indent
1253PPP ON awfulhak> show log
1254Log: Carrier Link Phase
1255PPP ON awfulhak> set log -Link +tcp/ip
1256PPP ON awfulhak> show log
1257Log: Carrier Phase TCP/IP
1258.Ed
1259
1260Log messages of level Warning, Error and Alert are not controlable
1261using
1262.Dq set log .
1263
1264.Sh SIGNAL HANDLING
1265
1266.Nm Ppp
1267deals with the following signals:
1268
1269.Bl -tag -width 20
1270.It INT
1271Receipt of this signal causes the termination of the current connection
1272(if any). This will cause
1273.Nm
1274to exit unless it is in
1275.Fl auto
1276or
1277.Fl ddial
1278mode.
1279
1280.It HUP, TERM & QUIT
1281These signals tell
1282.Nm
1283to exit.
1284
1285.It USR1
1286This signal, when not in interactive mode, tells
1287.Nm
1288to close any existing server socket and open an internet socket using
1289the default rules for choosing a port number - that is, using port
12903000 plus the current tunnel device number.
1291
1292.El
1293
1294.Sh PPP COMMAND LIST
1295
1296This section lists the available commands and their effect. They are
1297usable either from an interactive ppp session, from a configuration
1298file or from a telnet session.
1299
1300.Bl -tag -width 20
1301.It accept|deny|enable|disable option....
1302These directives tell
1303.Nm
1304how to negotiate the initial connection with the peer. Each
1305.Dq option
1306has a default of either accept or deny and enable or disable.
1307.Dq Accept
1308means that the option will be ACK'd if the peer asks for it.
1309.Dq Deny
1310means that the option will be NAK'd if the peer asks for it.
1311.Dq Enable
1312means that the option will be requested by us.
1313.Dq Disable
1314means that the option will not be requested by us.
1315.Pp
1316.Dq Option
1317may be one of the following:
1318
1319.Bl -tag -width 20
1320.It vjcomp
1321Default: Enabled and Accepted. This option decides if Van Jacobson
1322header compression will be used.
1323
1324.It lqr
1325Default: Enabled and Accepted. This option decides if Link Quality
1326Requests will be sent. LQR is a protocol that allows
1327.Nm
1328to determine that the link is down without relying on the modems
1329carrier detect.
1330
1331.It chap
1332Default: Disabled and Accepted. CHAP stands for Challenge Handshake
1333Authentication Protocol. Only one of CHAP and PAP (below) may be
1334negotiated. With CHAP, the authenticator sends a "challenge" message
1335to its peer. The peer uses a one-way hash function to encrypt the
1336challenge and sends the result back. The authenticator does the same,
1337and compares the results. The advantage of this mechanism is that no
1338passwords are sent across the connection.
1339
1340A challenge is made when the connection is first made. Subsequent
1341challenges may occur.
1342
1343When using CHAP, an
1344.Dq AuthName
1345and an
1346.Dq AuthKey
1347must be specified either in
1348.Pa ppp.conf
1349or in
1350.Pa ppp.secret .
1351
1352.It pap
1353Default: Disabled and Accepted. PAP stands for Password Authentication
1354Protocol. Only one of PAP and CHAP (above) may be negotiated. With
1355PAP, the ID and Password are sent repeatedly to the peer until
1356authentication is acknowledged or the connection is terminated. This
1357is a rather poor security mechanism. It is only performed when the
1358connection is first established.
1359
1360When using PAP, an
1361.Dq AuthName
1362and an
1363.Dq AuthKey
1364must be specified either in
1365.Pa ppp.conf
1366or in
1367.Pa ppp.secret
1368(although see the
1369.Dq passwdauth
1370option below).
1371
1372.It acfcomp
1373Default: Enabled and Accepted. ACFComp stands for Address and Control
1374Field Compression. Non LCP packets usually have very similar address
1375and control fields - making them easily compressable.
1376
1377.It protocomp
1378Default: Enabled and Accepted. This option is used to negotiate
1379PFC (Protocol Field Compression), a mechanism where the protocol
1380field number is reduced to one octet rather than two.
1381
1382.It pred1
1383Default: Enabled and Accepted. This option decides if Predictor 1
1384compression will be used.
1385
1386.It proxy
1387Default: Disabled and Denied. Unlike the other options (except
1388passwdauth below), this is not negotiated with the peer. Therefore,
1389accepting or denying it is of no use. Enabling this option will tell
1390.Nm
1391to proxy ARP for the peer.
1392
1393.It msext
1394Default: Disabled and Accepted. This option allows the use
1395of Microsoft's ppp extensions, supporting the negotiation of
1396the Microsoft PPP DNS and the Microsoft NetBIOS NS.
1397
1398.It passwdauth
1399Default: Disabled and Denied. Unlike the other options (except
1400.Dq proxy
1401above), this is not negotiated with the peer. Therefore,
1402accepting or denying it is of no use. Enabling this option will
1403tell the PAP authentication code to use the
1404.Pa passwd
1405file to authenticate the caller rather than the
1406.Pa ppp.secret
1407file.
1408
1409.El
1410
1411.It add dest mask gateway
1412.Dq Dest
1413is the destination IP address and
1414.Dq mask
1415is its mask.
1416.Dq 0 0
1417refers to the default route.
1418.Dq Gateway
1419is the next hop gateway to get to the given
1420.Dq dest
1421machine/network.
1422
1423.It close
1424Close the current connection (but don't quit).
1425
1426.It delete ALL | dest [gateway [mask]]
1427If
1428.Dq ALL
1429is specified, all non-direct entries in the routing for the interface
1430that
1431.Nm
1432is using are deleted. This means all entries for tunX, except the entry
1433representing the actual link. When
1434.Dq ALL
1435is not used, any existing route with the given
1436.Dq dest ,
1437destination network
1438.Dq mask
1439and
1440.Dq gateway
1441is deleted. The default
1442.Dq mask
1443value is 0.0.0.0.
1444
1445.It dial|call [remote]
1446If
1447.Dq remote
1448is specified, a connection is established using the
1449.Dq dial
1450and
1451.Dq login
1452scripts for the given
1453.Dq remote
1454system. Otherwise, the current settings are used to establish
1455the connection.
1456
1457.It display
1458Displays the current status of the negotiable protocol
1459values as specified under
1460.Dq accept|deny|enable|disable option....
1461above.
1462
1463.It passwd pass
1464Specify the password required for access to the full
1465.Nm
1466command set.
1467
1468.It load [remote]
1469Load the given
1470.Dq remote
1471label. If
1472.Dq remote
1473is not given, the
1474.Dq default
1475label is assumed.
1476
1477.It save
1478This option is not (yet) implemented.
1479
1480.It set[up] var value
1481This option allows the setting of any of the following variables:
1482
1483.Bl -tag -width 20
1484.It set accmap hex-value
1485ACCMap stands for Asyncronous Control Character Map. This is always
1486negotiated with the peer, and defaults to a value of 0x00000000.
1487This protocol is required to defeat hardware that depends on passing
1488certain characters from end to end (such as XON/XOFF etc).
1489
1490.It set filter-name rule-no action [src_addr/src_width]
1491[dst_addr/dst_width] [proto [src [lt|eq|gt] port ]]
1492[dst [lt|eq|gt] port] [estab]
1493.Pp
1494.Nm Ppp
1495supports four filter sets. The afilter specifies packets that keep
1496the connection alive - reseting the idle timer. The dfilter specifies
1497packets that cause
1498.Nm
1499to dial when in
1500.Fl auto
1501mode. The ifilter specifies packets that are allowed to travel
1502into the machine and the ofilter specifies packets that are allowed
1503out of the machine. By default all filter sets allow all packets
1504to pass.
1505
1506Rules are processed in order according to
1507.Dq n .
1508Up to 20 rules may be given for each set. If a packet doesn't match
1509any of the rules in a given set, it is discarded. In the case of
1510ifilters and ofilters, this means that the packet is dropped. In
1511the case of afilters it means that the packet will not reset the
1512idle timer and in the case of dfilters it means that the packet will
1513not trigger a dial.
1514
1515Refer to the section on PACKET FILTERING above for further details.
1516
1517.It set authkey|key value
1518This sets the authentication key (or password) used in PAP or CHAP
1519negotiation to the given value. It can also be used to specify the
1520password to be used in the dial or login scripts, preventing the
1521actual password from being logged.
1522
1523.It set authname id
1524This sets the authentication id used in PAP or CHAP negotiation.
1525
1526.It set ctsrts
1527This sets hardware flow control and is the default.
1528
1529.It set device|line value
1530This sets the device to which ppp will talk to the given
1531.Dq value .
1532All serial device names are expected to begin with
1533.Pa /dev/ .
1534If
1535.Dq value
1536does not begin with
1537.Pa /dev/ ,
1538it must be of the format
1539.Dq host:port .
1540If this is the case,
1541.Nm
1542will attempt to connect to the given
1543.Dq host
1544on the given
1545.Dq port .
1546Refer to the section on PPP OVER TCP above for further details.
1547
1548.It set dial chat-script
1549This specifies the chat script that will be used to dial the other
1550side. See also the
1551.Dv set login
1552command below. Refer to
1553.Xr chat 8
1554and to the example configuration files for details of the chat script
1555format. The string \\\\T will be replaced with the current phone number
1556(see
1557.Dq set phone
1558below) and the string \\\\P will be replaced with the password (see
1559.Dq set key
1560above).
1561
1562.It set hangup chat-script
1563This specifies the chat script that will be used to reset the modem
1564before it is closed. It should not normally be necessary, but can
1565be used for devices that fail to reset themselves properly on close.
1566
1567.It set escape value...
1568This option is similar to the
1569.Dq set accmap
1570option above. It allows the user to specify a set of characters that
1571will be `escaped' as they travel across the link.
1572
1573.It set ifaddr myaddr hisaddr mask
1574This command specifies the IP addresses that will be used during
1575LCP negotiation. Addresses are specified using the format
1576
1577.Dl a.b.c.d/n
1578
1579Where a.b.c.d is the preferred IP, but n specifies how many bits
1580of the address we will insist on. If the /n bit is omitted, it
1581defaults to /32 unless the IP address is 0.0.0.0 in which case
1582the mask defaults to /0.
1583
1584.It set log [+|-]value...
1585This command allows the adjustment of the current log level. Please
1586refer to the Logging Facility section for further details.
1587
1588.It set login chat-script
1589This chat-script compliments the dial-script. If both are specified,
1590the login script will be executed after the dial script. Escape
1591sequences available in the dial script are also available here.
1592
1593.It set mru value
1594The default MRU is 1500. If it is increased, the other side *may*
1595increase its mtu. There is no use decreasing the MRU to below the
1596default as the PPP protocol *must* be able to accept packets of at
1597least 1500 octets.
1598
1599.It set mtu value
1600The default MTU is 1500. This may be increased by the MRU specified
1601by the peer. It may only be subsequently decreased by this option.
1602Increasing it is not valid as the peer is not necessarily able to
1603receive the increased packet size.
1604
1605.It set openmode active|passive
1606By default, openmode is always active. That is,
1607.Nm
1608will always initiate LCP negotiation. If you want to wait for the
1609peer to initiate LCP negotiation, you may use the value
1610.Dq passive .
1611
1612.It set parity odd|even|none|mark
1613This allows the line parity to be set. The default value is none.
1614
1615.It set phone telno[:telno]...
1616This allows the specification of the phone number to be used in
1617place of the \\\\T string in the dial and login chat scripts.
1618Multiple phone numbers may be given seperated by a colon (:).
1619If multiple numbers are given,
1620.Nm
1621will dial them in rotation until a connection is made, retrying
1622the maximum number of times specified by
1623.Dq set redial
1624below. In
1625.Fl background
1626mode, each number is attempted at most once.
1627
1628.It set reconnect timeout ntries
1629Should the line drop unexpectedly (due to loss of CD or LQR
1630failure), a connection will be re-established after the given
1631.Dq timeout .
1632The line will be re-connected at most
1633.Dq ntries
1634times.
1635.Dq Ntries
1636defaults to zero. A value of
1637.Dq random
1638for
1639.Dq timeout
1640will result in a variable pause, somewhere between 0 and 30 seconds.
1641
1642.It set redial seconds[.nseconds] [attempts]
1643.Nm Ppp
1644can be instructed to attempt to redial
1645.Dq attempts
1646times. If more than one number is specified (see
1647.Dq set phone
1648above), a pause of
1649.Dq nseconds
1650is taken before dialing each number. A pause of
1651.Dq seconds
1652is taken before starting at the first number again. A value of
1653.Dq random
1654may be used here too.
1655
1656.It set server|socket TcpPort|LocalName|none [mask]
1657Normally, when not in interactive mode,
1658.Nm
1659listens to a tcp socket for incoming command connections. The
1660socket number is calculated as 3000 plus the number of the
1661tunnel device that
1662.Nm
1663opened. So, for example, if
1664.Nm
1665opened tun2, socket 3002 would be used.
1666.Pp
1667Using this command, you can specify your own port number, a
1668local domain socket (specified as an absolute file name), or
1669you can tell
1670.Nm
1671not to accept any command connections. If a local domain socket
1672is specified, you may also specify an octal mask that should be
1673set before creating the socket. See also the use of
1674the
1675.Dv USR1
1676signal.
1677
1678.It set speed value
1679This sets the speed of the serial device.
1680
1681.It set timeout Idle [ lqr [ retry ] ]
1682This command allows the setting of the idle timer, the LQR timer (if
1683enabled) and the retry timer.
1684
1685.It set ns x.x.x.x
1686This option allows the setting of the Microsoft PPP DNS server that
1687will be negotiated.
1688
1689.It set nbns
1690This option allows the setting of the Microsoft NetBIOS DNS server that
1691will be negotiated.
1692
1693.It set help|?
1694This command gives a summary of available set commands.
1695.El
1696
1697.It shell|! [command]
1698Execute a shell according to the value of the
1699.Dv SHELL
1700environment variable. If
1701.Dq command
1702is specified, it is executed without a parent shell. Note, it's possible
1703to use the
1704.Dv HISADDR ,
1705.Dv INTERFACE
1706and
1707.Dv MYADDR
1708symbols here. Also note that if you use the ! character, you must have
1709a space between it and
1710.Dq command .
1711
1712.It show var
1713This command allows the user to examine the following:
1714
1715.Bl -tag -width 20
1716.It show [adio]filter
1717List the current rules for the given filter.
1718
1719.It show auth
1720Show the current authname and authkey.
1721
1722.It show ccp
1723Show the current CCP statistics.
1724
1725.It show compress
1726Show the current compress statistics.
1727
1728.It show escape
1729Show the current escape characters.
1730
1731.It show hdlc
1732Show the current HDLC statistics.
1733
1734.It show ipcp
1735Show the current IPCP statistics.
1736
1737.It show lcp
1738Show the current LCP statistics.
1739
1740.It show log
1741Show the current log values.
1742
1743.It show mem
1744Show current memory statistics.
1745
1746.It show modem
1747Show current modem statistics.
1748
1749.It show mru
1750Show the current MRU.
1751
1752.It show mtu
1753Show the current MTU.
1754
1755.It show proto
1756Show current protocol totals.
1757
1758.It show reconnect
1759Show the current reconnect values.
1760
1761.It show redial
1762Show the current redial values.
1763
1764.It show route
1765Show the current routing tables.
1766
1767.It show timeout
1768Show the current timeout values.
1769
1770.It show msext
1771Show the current Microsoft extension values.
1772
1773.It show version
1774Show the current version number of ppp.
1775
1776.It show help|?
1777Give a summary of available show commands.
1778.El
1779
1780.It term
1781Go into terminal mode. Characters typed at the keyboard are sent to
1782the modem. Characters read from the modem are displayed on the
1783screen. When a
1784.Nm
1785peer is detected on the other side of the modem,
1786.Nm
1787automatically enables Packet Mode and goes back into command mode.
1788
1789.It alias .....
1790This command allows the control of the aliasing (or masquerading)
1791facilities that are built into
1792.Nm ppp .
1793Until this code is required, it is not loaded by
1794.Nm ppp ,
1795and it is quite possible that the alias library is not installed
1796on your system (some administrators consider it a security risk).
1797
1798If aliasing is enabled on your system, the following commands are
1799possible:
1800
1801.Bl -tag -width 20
1802.It alias enable [yes|no]
1803This command either switches aliasing on or turns it off.
1804The
1805.Fl alias
1806command line flag is synonomous with
1807.Dq alias enable yes .
1808
1809.It alias port [proto targetIP:targetPORT [aliasIP:]aliasPORT]
1810This command allows us to redirect connections arriving at
1811.Dq aliasPORT
1812for machine [aliasIP] to
1813.Dq targetPORT
1814on
1815.Dq targetIP .
1816If proto is specified, only connections of the given protocol
1817are matched. This option is useful if you wish to things like
1818internet phone on the machines behind your gateway.
1819
1820.It alias addr [addr_local addr_alias]
1821This command allows data for
1822.Dq addr_alias
1823to be redirected to
1824.Dq addr_local .
1825It is useful if you own a small number of real IP numbers that
1826you wish to map to specific machines behind your gateway.
1827
1828.It alias deny_incoming [yes|no]
1829If set to yes, this command will refuse all incoming connections
1830by dropping the packets in much the same way as a firewall would.
1831
1832.It alias log [yes|no]
1833This option causes various aliasing statistics and information to
1834be logged to the file
1835.Pa /var/log/alias.log .
1836
1837.It alias same_ports [yes|no]
1838When enabled, this command will tell the alias library attempt to
1839avoid changing the port number on outgoing packets. This is useful
1840if you want to support protocols such as RPC and LPD which require
1841connections to come from a well known port.
1842
1843.It alias use_sockets [yes|no]
1844When enabled, this option tells the alias library to create a
1845socket so that it can guarantee a correct incoming ftp data or
1846IRC connection.
1847
1848.It alias unregistered_only [yes|no]
1849Only alter outgoing packets with an unregistered source ad-
1850dress. According to rfc 1918, unregistered source addresses
1851are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16.
1852
1853.It alias help|?
1854This command gives a summary of available alias commands.
1855
1856.El
1857
1858.It quit|bye [all]
1859Exit
1860.Nm ppp.
1861If
1862.Nm
1863is in interactive mode or if the
1864.Dq all
1865argument is given, ppp will exit, closing the connection. A simple
1866.Dq quit
1867issued from a telnet session will not close the current connection.
1868
1869.It help|? [command]
1870Show a list of available commands. If
1871.Dq command
1872is specified, show the usage string for that command.
1873
1874.It down
1875Bring the link down ungracefully. It's not considered polite to
1876use this command.
1877
1878.El
1879
1880.Sh MORE DETAILS
1881
1882.Bl -bullet -compact
1883
1884.It
1885Read the example configuration files. They are a good source of information.
1886
1887.It
1888Use
1889.Dq help ,
1890.Dq show ? ,
1891.Dq alias ? ,
1892.Dq set ?
1893and
1894.Dq set ? <var>
1895commands.
1896.El
1897
1898.Sh FILES
1899.Nm Ppp
1900refers to four files: ppp.conf, ppp.linkup, ppp.linkdown and
1901ppp.secret. These files are placed in
1902.Pa /etc/ppp ,
1903but the user can create his own files under his $HOME directory as
1904.Pa .ppp.conf ,
1905.Pa .ppp.linkup ,
1906.Pa .ppp.linkdown
1907and
1908.Pa .ppp.secret.
1909.Nm
1910will always try to consult the user's personal setup first.
1911
1912.Bl -tag -width flag
1913.Pa $HOME/ppp/.ppp.[conf|linkup|linkdown|secret]
1914User dependent configuration files.
1915
1916.Pa /etc/ppp/ppp.conf
1917System default configuration file.
1918
1919.Pa /etc/ppp/ppp.secret
1920An authorization file for each system.
1921
1922.Pa /etc/ppp/ppp.linkup
1923A file to check when
1924.Nm
1925establishes a network level connection.
1926
1927.Pa /etc/ppp/ppp.linkdown
1928A file to check when
1929.Nm
1930closes a network level connection.
1931
|