4 .\" Copyright (c) 2001 Brian Somers <brian@Awfulhak.org>
5 .\" All rights reserved.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" $FreeBSD: src/usr.sbin/ppp/ppp.8.m4,v 1.301.2.1 2002/09/01 02:12:31 brian Exp $
30 .Dd September 20, 1995
35 .Nd Point to Point Protocol (a.k.a. user-ppp)
44 This is a user process
49 is implemented as a part of the kernel (e.g., as managed by
51 and it's thus somewhat hard to debug and/or modify its behaviour.
52 However, in this implementation
54 is done as a user process with the help of the
55 tunnel device driver (tun).
59 flag does the equivalent of a
63 network address translation features.
66 to act as a NAT or masquerading engine for all machines on an internal
68 ifdef({LOCALNAT},{},{Refer to
70 for details on the technical side of the NAT engine.
73 .Sx NETWORK ADDRESS TRANSLATION (PACKET ALIASING)
74 section of this manual page for details on how to configure NAT in
81 to be silent at startup rather than displaying the mode and interface
88 to only attempt to open
89 .Pa /dev/tun Ns Ar N .
92 will start with a value of 0 for
94 and keep trying to open a tunnel device by incrementing the value of
96 by one each time until it succeeds.
97 If it fails three times in a row
98 because the device file is missing, it gives up.
104 .Bl -tag -width XXX -offset XXX
107 opens the tun interface, configures it then goes into the background.
108 The link isn't brought up until outgoing data is detected on the tun
109 interface at which point
111 attempts to bring up the link.
112 Packets received (including the first one) while
114 is trying to bring the link up will remain queued for a default of
124 must be given on the command line (see below) and a
126 must be done in the system profile that specifies a peer IP address to
127 use when configuring the interface.
130 is usually appropriate.
134 .Pa /usr/share/examples/ppp/ppp.conf.sample
139 attempts to establish a connection with the peer immediately.
142 goes into the background and the parent process returns an exit code
146 exits with a non-zero result.
150 attempts to establish a connection with the peer immediately, but never
152 The link is created in background mode.
153 This is useful if you wish to control
155 invocation from another process.
157 This is used for receiving incoming connections.
161 line and uses descriptor 0 as the link.
163 If callback is configured,
167 information when dialing back.
169 This option is designed for machines connected with a dedicated
172 will always keep the device open and will never use any configured
175 This mode is equivalent to
179 will bring the link back up any time it's dropped for any reason.
181 This is a no-op, and gives the same behaviour as if none of the above
182 modes have been specified.
184 loads any sections specified on the command line then provides an
188 One or more configuration entries or systems
190 .Pa /etc/ppp/ppp.conf )
191 may also be specified on the command line.
196 .Pa /etc/ppp/ppp.conf
197 at startup, followed by each of the systems specified on the command line.
200 .It Provides an interactive user interface.
201 Using its command mode, the user can
202 easily enter commands to establish the connection with the remote end, check
203 the status of connection and close the connection.
204 All functions can also be optionally password protected for security.
205 .It Supports both manual and automatic dialing.
206 Interactive mode has a
208 command which enables you to talk to the device directly.
209 When you are connected to the remote peer and it starts to talk
212 detects it and switches to packet mode automatically.
214 determined the proper sequence for connecting with the remote host, you
215 can write a chat script to {define} the necessary dialing and login
216 procedure for later convenience.
217 .It Supports on-demand dialup capability.
222 will act as a daemon and wait for a packet to be sent over the
225 When this happens, the daemon automatically dials and establishes the
227 In almost the same manner
229 mode (direct-dial mode) also automatically dials and establishes the
231 However, it differs in that it will dial the remote site
232 any time it detects the link is down, even if there are no packets to be
234 This mode is useful for full-time connections where we worry less
235 about line charges and more about being connected full time.
238 mode is also available.
239 This mode is targeted at a dedicated link between two machines.
241 will never voluntarily quit from dedicated mode - you must send it the
243 command via its diagnostic socket.
246 will force an LCP renegotiation, and a
248 will force it to exit.
249 .It Supports client callback.
251 can use either the standard LCP callback protocol or the Microsoft
252 CallBack Control Protocol (ftp://ftp.microsoft.com/developr/rfc/cbcp.txt).
253 .It Supports NAT or packet aliasing.
254 Packet aliasing (a.k.a. IP masquerading) allows computers on a
255 private, unregistered network to access the Internet.
258 host acts as a masquerading gateway.
259 IP addresses as well as TCP and
260 UDP port numbers are NAT'd for outgoing packets and de-NAT'd for
262 .It Supports background PPP connections.
263 In background mode, if
265 successfully establishes the connection, it will become a daemon.
266 Otherwise, it will exit with an error.
267 This allows the setup of
268 scripts that wish to execute certain commands only if the connection
269 is successfully established.
270 .It Supports server-side PPP connections.
273 acts as server which accepts incoming
275 connections on stdin/stdout.
276 .It "Supports PAP and CHAP (rfc 1994, 2433 and 2759) authentication.
277 With PAP or CHAP, it is possible to skip the Unix style
279 procedure, and use the
281 protocol for authentication instead.
282 If the peer requests Microsoft CHAP authentication and
284 is compiled with DES support, an appropriate MD4/DES response will be
286 .It Supports RADIUS (rfc 2138 & 2548) authentication.
287 An extension to PAP and CHAP,
294 allows authentication information to be stored in a central or
295 distributed database along with various per-user framed connection
297 ifdef({LOCALRAD},{},{If
299 is available at compile time,
303 requests when configured to do so.
305 .It Supports Proxy Arp.
307 can be configured to make one or more proxy arp entries on behalf of
309 This allows routing from the peer to the LAN without
310 configuring each machine on that LAN.
311 .It Supports packet filtering.
312 User can {define} four kinds of filters: the
314 filter for incoming packets, the
316 filter for outgoing packets, the
318 filter to {define} a dialing trigger packet and the
320 filter for keeping a connection alive with the trigger packet.
321 .It Tunnel driver supports bpf.
324 to check the packet flow over the
327 .It Supports PPP over TCP and PPP over UDP.
328 If a device name is specified as
329 .Em host Ns No : Ns Em port Ns
334 will open a TCP or UDP connection for transporting data rather than using a
335 conventional serial device.
336 UDP connections force
338 into synchronous mode.
339 .It Supports PPP over ISDN.
342 is given a raw B-channel i4b device to open as a link, it's able to talk
345 daemon to establish an ISDN connection.
346 .It Supports PPP over Ethernet (rfc 2516).
349 is given a device specification of the format
350 .No PPPoE: Ns Ar iface Ns Xo
351 .Op \&: Ns Ar provider Ns
365 On systems that do not support
367 an external program such as
370 .It "Supports IETF draft Predictor-1 (rfc 1978) and DEFLATE (rfc 1979) compression."
372 supports not only VJ-compression but also Predictor-1 and DEFLATE compression.
373 Normally, a modem has built-in compression (e.g., v42.bis) and the system
374 may receive higher data rates from it as a result of such compression.
375 While this is generally a good thing in most other situations, this
376 higher speed data imposes a penalty on the system by increasing the
377 number of serial interrupts the system has to process in talking to the
378 modem and also increases latency.
379 Unlike VJ-compression, Predictor-1 and DEFLATE compression pre-compresses
381 network traffic flowing through the link, thus reducing overheads to a
383 .It Supports Microsoft's IPCP extensions (rfc 1877).
384 Name Server Addresses and NetBIOS Name Server Addresses can be negotiated
385 with clients using the Microsoft
387 stack (i.e., Win95, WinNT)
388 .It Supports Multi-link PPP (rfc 1990)
389 It is possible to configure
391 to open more than one physical connection to the peer, combining the
392 bandwidth of all links for better throughput.
393 .It Supports MPPE (draft-ietf-pppext-mppe)
394 MPPE is Microsoft Point to Point Encryption scheme.
395 It is possible to configure
397 to participate in Microsoft's Windows VPN.
400 can only get encryption keys from CHAP 81 authentication.
402 must be compiled with DES for MPPE to operate.
403 .It Supports IPV6CP (rfc 2023).
404 An IPv6 connection can be made in addition to or instead of the normal
417 will not run if the invoking user id is not zero.
418 This may be overridden by using the
421 .Pa /etc/ppp/ppp.conf .
422 When running as a normal user,
424 switches to user id 0 in order to alter the system routing table, set up
425 system lock files and read the ppp configuration files.
426 All external commands (executed via the "shell" or "!bg" commands) are executed
427 as the user id that invoked
431 logging facility if you're interested in what exactly is done as user id
436 you may need to deal with some initial configuration details.
439 Your kernel must {include} a tunnel device (the GENERIC kernel includes
441 If it doesn't, or if you require more than one tun
442 interface, you'll need to rebuild your kernel with the following line in
443 your kernel configuration file:
445 .Dl pseudo-device tun N
449 is the maximum number of
451 connections you wish to support.
455 directory for the tunnel device entries
459 represents the number of the tun device, starting at zero.
460 If they don't exist, you can create them by running "sh ./MAKEDEV tunN".
461 This will create tun devices 0 through
464 Make sure that your system has a group named
468 file and that the group contains the names of all users expected to use
472 manual page for details.
473 Each of these users must also be given access using the
476 .Pa /etc/ppp/ppp.conf .
483 A common log file name is
484 .Pa /var/log/ppp.log .
485 To make output go to this file, put the following lines in the
488 .Bd -literal -offset indent
490 *.*<TAB>/var/log/ppp.log
493 It is possible to have more than one
495 log file by creating a link to the
503 .Bd -literal -offset indent
505 *.*<TAB>/var/log/ppp0.log
509 .Pa /etc/syslog.conf .
510 Don't forget to send a
515 .Pa /etc/syslog.conf .
517 Although not strictly relevant to
519 operation, you should configure your resolver so that it works correctly.
520 This can be done by configuring a local DNS
523 or by adding the correct
526 .Pa /etc/resolv.conf .
529 manual page for details.
531 Alternatively, if the peer supports it,
533 can be configured to ask the peer for the nameserver address(es) and to
541 commands below for details.
544 In the following examples, we assume that your machine name is
550 above) with no arguments, you are presented with a prompt:
551 .Bd -literal -offset indent
557 part of your prompt should always be in upper case.
558 If it is in lower case, it means that you must supply a password using the
561 This only ever happens if you connect to a running version of
563 and have not authenticated yourself using the correct password.
565 You can start by specifying the device name and speed:
566 .Bd -literal -offset indent
567 ppp ON awfulhak> set device /dev/cuaa0
568 ppp ON awfulhak> set speed 38400
571 Normally, hardware flow control (CTS/RTS) is used.
573 certain circumstances (as may happen when you are connected directly
574 to certain PPP-capable terminal servers), this may result in
576 hanging as soon as it tries to write data to your communications link
577 as it is waiting for the CTS (clear to send) signal - which will never
579 Thus, if you have a direct line and can't seem to make a
580 connection, try turning CTS/RTS off with
582 If you need to do this, check the
584 description below too - you'll probably need to
585 .Dq set accmap 000a0000 .
587 Usually, parity is set to
592 Parity is a rather archaic error checking mechanism that is no
593 longer used because modern modems do their own error checking, and most
594 link-layer protocols (that's what
596 is) use much more reliable checking mechanisms.
597 Parity has a relatively
598 huge overhead (a 12.5% increase in traffic) and as a result, it is always
605 However, some ISPs (Internet Service Providers) may use
606 specific parity settings at connection time (before
609 Notably, Compuserve insist on even parity when logging in:
610 .Bd -literal -offset indent
611 ppp ON awfulhak> set parity even
614 You can now see what your current device settings look like:
615 .Bd -literal -offset indent
616 ppp ON awfulhak> show physical
620 Link Type: interactive
626 Device List: /dev/cuaa0
627 Characteristics: 38400bps, cs8, even parity, CTS/RTS on
630 0 octets in, 0 octets out
635 The term command can now be used to talk directly to the device:
636 .Bd -literal -offset indent
637 ppp ON awfulhak> term
643 Password: myisppassword
647 When the peer starts to talk in
650 detects this automatically and returns to command mode.
651 .Bd -literal -offset indent
652 ppp ON awfulhak> # No link has been established
653 Ppp ON awfulhak> # We've connected & finished LCP
654 PPp ON awfulhak> # We've authenticated
655 PPP ON awfulhak> # We've agreed IP numbers
658 If it does not, it's probable that the peer is waiting for your end to
664 configuration packets to the peer, use the
666 command to drop out of terminal mode and enter packet mode.
668 If you never even receive a login prompt, it is quite likely that the
669 peer wants to use PAP or CHAP authentication instead of using Unix-style
670 login/password authentication.
671 To set things up properly, drop back to
672 the prompt and set your authentication name and key, then reconnect:
673 .Bd -literal -offset indent
675 ppp ON awfulhak> set authname myispusername
676 ppp ON awfulhak> set authkey myisppassword
677 ppp ON awfulhak> term
684 You may need to tell ppp to initiate negotiations with the peer here too:
685 .Bd -literal -offset indent
687 ppp ON awfulhak> # No link has been established
688 Ppp ON awfulhak> # We've connected & finished LCP
689 PPp ON awfulhak> # We've authenticated
690 PPP ON awfulhak> # We've agreed IP numbers
693 You are now connected!
696 in the prompt has changed to capital letters to indicate that you have
698 If only some of the three Ps go uppercase, wait until
699 either everything is uppercase or lowercase.
700 If they revert to lowercase, it means that
702 couldn't successfully negotiate with the peer.
703 A good first step for troubleshooting at this point would be to
704 .Bd -literal -offset indent
705 ppp ON awfulhak> set log local phase lcp ipcp
711 command description below for further details.
712 If things fail at this point,
713 it is quite important that you turn logging on and try again.
715 important that you note any prompt changes and report them to anyone trying
718 When the link is established, the show command can be used to see how
720 .Bd -literal -offset indent
721 PPP ON awfulhak> show physical
722 * Modem related information is shown here *
723 PPP ON awfulhak> show ccp
724 * CCP (compression) related information is shown here *
725 PPP ON awfulhak> show lcp
726 * LCP (line control) related information is shown here *
727 PPP ON awfulhak> show ipcp
728 * IPCP (IP) related information is shown here *
729 PPP ON awfulhak> show ipv6cp
730 * IPV6CP (IPv6) related information is shown here *
731 PPP ON awfulhak> show link
732 * Link (high level) related information is shown here *
733 PPP ON awfulhak> show bundle
734 * Logical (high level) connection related information is shown here *
737 At this point, your machine has a host route to the peer.
739 that you can only make a connection with the host on the other side
741 If you want to add a default route entry (telling your
742 machine to send all packets without another routing entry to the other
745 link), enter the following command:
746 .Bd -literal -offset indent
747 PPP ON awfulhak> add default HISADDR
752 represents the IP address of the connected peer.
755 command fails due to an existing route, you can overwrite the existing
757 .Bd -literal -offset indent
758 PPP ON awfulhak> add! default HISADDR
761 This command can also be executed before actually making the connection.
762 If a new IP address is negotiated at connection time,
764 will update your default route accordingly.
766 You can now use your network applications (ping, telnet, ftp etc.)
767 in other windows or terminals on your machine.
768 If you wish to reuse the current terminal, you can put
770 into the background using your standard shell suspend and background
778 section for details on all available commands.
779 .Sh AUTOMATIC DIALING
780 To use automatic dialing, you must prepare some Dial and Login chat scripts.
781 See the example definitions in
782 .Pa /usr/share/examples/ppp/ppp.conf.sample
784 .Pa /etc/ppp/ppp.conf
786 Each line contains one comment, inclusion, label or command:
789 A line starting with a
791 character is treated as a comment line.
792 Leading whitespace are ignored when identifying comment lines.
794 An inclusion is a line beginning with the word
796 It must have one argument - the file to {include}.
798 .Dq {!include} ~/.ppp.conf
799 for compatibility with older versions of
802 A label name starts in the first column and is followed by
806 A command line must contain a space or tab in the first column.
810 .Pa /etc/ppp/ppp.conf
811 file should consist of at least a
814 This section is always executed.
815 It should also contain
816 one or more sections, named according to their purpose, for example,
818 would represent your ISP, and
820 would represent an incoming
823 You can now specify the destination label name when you invoke
825 Commands associated with the
827 label are executed, followed by those associated with the destination
831 is started with no arguments, the
833 section is still executed.
834 The load command can be used to manually load a section from the
835 .Pa /etc/ppp/ppp.conf
837 .Bd -literal -offset indent
838 ppp ON awfulhak> load MyISP
841 Note, no action is taken by
843 after a section is loaded, whether it's the result of passing a label on
844 the command line or using the
847 Only the commands specified for that label in the configuration
849 However, when invoking
856 switches, the link mode tells
858 to establish a connection.
861 command below for further details.
863 Once the connection is made, the
865 portion of the prompt will change to
867 .Bd -literal -offset indent
870 ppp ON awfulhak> dial
876 The Ppp prompt indicates that
878 has entered the authentication phase.
879 The PPp prompt indicates that
881 has entered the network phase.
882 The PPP prompt indicates that
884 has successfully negotiated a network layer protocol and is in
888 .Pa /etc/ppp/ppp.linkup
889 file is available, its contents are executed
892 connection is established.
896 .Pa /usr/share/examples/ppp/ppp.conf.sample
897 which runs a script in the background after the connection is established
902 commands below for a description of possible substitution strings).
903 Similarly, when a connection is closed, the contents of the
904 .Pa /etc/ppp/ppp.linkdown
906 Both of these files have the same format as
907 .Pa /etc/ppp/ppp.conf .
909 In previous versions of
911 it was necessary to re-add routes such as the default route in the
917 where all routes that contain the
923 literals will automatically be updated when the values of these variables
925 .Sh BACKGROUND DIALING
926 If you want to establish a connection using
928 non-interactively (such as from a
932 job) you should use the
939 attempts to establish the connection immediately.
941 numbers are specified, each phone number will be tried once.
942 If the attempt fails,
944 exits immediately with a non-zero exit code.
947 becomes a daemon, and returns an exit status of zero to its caller.
948 The daemon exits automatically if the connection is dropped by the
949 remote system, or it receives a
953 Demand dialing is enabled with the
958 You must also specify the destination label in
959 .Pa /etc/ppp/ppp.conf
963 command to {define} the remote peers IP address.
965 .Pa /usr/share/examples/ppp/ppp.conf.sample )
966 .Bd -literal -offset indent
976 runs as a daemon but you can still configure or examine its
977 configuration by using the
980 .Pa /etc/ppp/ppp.conf ,
982 .Dq Li "set server +3000 mypasswd" )
983 and connecting to the diagnostic port as follows:
984 .Bd -literal -offset indent
985 # pppctl 3000 (assuming tun0)
987 PPP ON awfulhak> show who
988 tcp (127.0.0.1:1028) *
993 command lists users that are currently connected to
996 If the diagnostic socket is closed or changed to a different
997 socket, all connections are immediately dropped.
1001 mode, when an outgoing packet is detected,
1003 will perform the dialing action (chat script) and try to connect
1007 mode, the dialing action is performed any time the line is found
1009 If the connect fails, the default behaviour is to wait 30 seconds
1010 and then attempt to connect when another outgoing packet is detected.
1011 This behaviour can be changed using the
1015 .No set redial Ar secs Ns Xo
1018 .Oc Ns Op . Ns Ar next
1022 .Bl -tag -width attempts -compact
1024 is the number of seconds to wait before attempting
1026 If the argument is the literal string
1028 the delay period is a random value between 1 and 30 seconds inclusive.
1030 is the number of seconds that
1032 should be incremented each time a new dial attempt is made.
1033 The timeout reverts to
1035 only after a successful connection is established.
1036 The default value for
1040 is the maximum number of times
1044 The default value for
1048 is the number of seconds to wait before attempting
1049 to dial the next number in a list of numbers (see the
1052 The default is 3 seconds.
1053 Again, if the argument is the literal string
1055 the delay period is a random value between 1 and 30 seconds.
1057 is the maximum number of times to try to connect for each outgoing packet
1058 that triggers a dial.
1059 The previous value is unchanged if this parameter is omitted.
1060 If a value of zero is specified for
1063 will keep trying until a connection is made.
1067 .Bd -literal -offset indent
1071 will attempt to connect 4 times for each outgoing packet that causes
1072 a dial attempt with a 3 second delay between each number and a 10 second
1073 delay after all numbers have been tried.
1074 If multiple phone numbers
1075 are specified, the total number of attempts is still 4 (it does not
1076 attempt each number 4 times).
1080 .Bd -literal -offset indent
1081 set redial 10+10-5.3 20
1086 to attempt to connect 20 times.
1087 After the first attempt,
1089 pauses for 10 seconds.
1090 After the next attempt it pauses for 20 seconds
1091 and so on until after the sixth attempt it pauses for 1 minute.
1092 The next 14 pauses will also have a duration of one minute.
1095 connects, disconnects and fails to connect again, the timeout starts again
1098 Modifying the dial delay is very useful when running
1102 mode on both ends of the link.
1103 If each end has the same timeout,
1104 both ends wind up calling each other at the same time if the link
1105 drops and both ends have packets queued.
1106 At some locations, the serial link may not be reliable, and carrier
1107 may be lost at inappropriate times.
1108 It is possible to have
1110 redial should carrier be unexpectedly lost during a session.
1111 .Bd -literal -offset indent
1112 set reconnect timeout ntries
1117 to re-establish the connection
1119 times on loss of carrier with a pause of
1121 seconds before each try.
1123 .Bd -literal -offset indent
1129 that on an unexpected loss of carrier, it should wait
1131 seconds before attempting to reconnect.
1132 This may happen up to
1137 The default value of ntries is zero (no reconnect).
1138 Care should be taken with this option.
1139 If the local timeout is slightly
1140 longer than the remote timeout, the reconnect feature will always be
1141 triggered (up to the given number of times) after the remote side
1142 times out and hangs up.
1143 NOTE: In this context, losing too many LQRs constitutes a loss of
1144 carrier and will trigger a reconnect.
1147 flag is specified, all phone numbers are dialed at most once until
1148 a connection is made.
1149 The next number redial period specified with the
1151 command is honoured, as is the reconnect tries value.
1153 value is less than the number of phone numbers specified, not all
1154 the specified numbers will be tried.
1155 To terminate the program, type
1156 .Bd -literal -offset indent
1157 PPP ON awfulhak> close
1158 ppp ON awfulhak> quit all
1163 command will terminate the
1167 connection but not the
1175 .Sh RECEIVING INCOMING PPP CONNECTIONS (Method 1)
1176 To handle an incoming
1178 connection request, follow these steps:
1181 Make sure the modem and (optionally)
1183 is configured correctly.
1184 .Bl -bullet -compact
1186 Use Hardware Handshake (CTS/RTS) for flow control.
1188 Modem should be set to NO echo back (ATE0) and NO results string (ATQ1).
1196 on the port where the modem is attached.
1199 .Dl ttyd1 Qo /usr/libexec/getty std.38400 Qc dialup on secure
1201 Don't forget to send a
1205 process to start the
1210 It is usually also necessary to train your modem to the same DTR speed
1212 .Bd -literal -offset indent
1214 ppp ON awfulhak> set device /dev/cuaa1
1215 ppp ON awfulhak> set speed 38400
1216 ppp ON awfulhak> term
1217 deflink: Entering terminal mode on /dev/cuaa1
1228 ppp ON awfulhak> quit
1232 .Pa /usr/local/bin/ppplogin
1233 file with the following contents:
1234 .Bd -literal -offset indent
1236 exec /usr/sbin/ppp -direct incoming
1243 work with stdin and stdout.
1246 to connect to a configured diagnostic port, in the same manner as with
1252 section must be set up in
1253 .Pa /etc/ppp/ppp.conf .
1257 section contains the
1259 command as appropriate.
1261 Prepare an account for the incoming user.
1263 ppp:xxxx:66:66:PPP Login User:/home/ppp:/usr/local/bin/ppplogin
1266 Refer to the manual entries for
1272 Support for IPCP Domain Name Server and NetBIOS Name Server negotiation
1273 can be enabled using the
1278 Refer to their descriptions below.
1280 .Sh RECEIVING INCOMING PPP CONNECTIONS (Method 2)
1281 This method differs in that we use
1283 to authenticate the connection rather than
1287 Configure your default section in
1289 with automatic ppp recognition by specifying the
1294 :pp=/usr/local/bin/ppplogin:\\
1298 Configure your serial device(s), enable a
1301 .Pa /usr/local/bin/ppplogin
1302 as in the first three steps for method 1 above.
1310 .Pa /etc/ppp/ppp.conf
1313 label (or whatever label
1318 .Pa /etc/ppp/ppp.secret
1319 for each incoming user:
1328 detects a ppp connection (by recognising the HDLC frame headers), it runs
1329 .Dq /usr/local/bin/ppplogin .
1333 that either PAP or CHAP are enabled as above.
1334 If they are not, you are
1335 allowing anybody to establish a ppp session with your machine
1337 a password, opening yourself up to all sorts of potential attacks.
1338 .Sh AUTHENTICATING INCOMING CONNECTIONS
1339 Normally, the receiver of a connection requires that the peer
1340 authenticates itself.
1341 This may be done using
1343 but alternatively, you can use PAP or CHAP.
1344 CHAP is the more secure of the two, but some clients may not support it.
1345 Once you decide which you wish to use, add the command
1349 to the relevant section of
1352 You must then configure the
1353 .Pa /etc/ppp/ppp.secret
1355 This file contains one line per possible client, each line
1356 containing up to five fields:
1359 .Ar hisaddr Op Ar label Op Ar callback-number
1366 specify the client username and password.
1371 and PAP is being used,
1373 will look up the password database
1375 when authenticating.
1376 If the client does not offer a suitable response based on any
1377 .Ar name Ns No / Ns Ar key
1380 authentication fails.
1382 If authentication is successful,
1385 is used when negotiating IP numbers.
1388 command for details.
1390 If authentication is successful and
1392 is specified, the current system label is changed to match the given
1394 This will change the subsequent parsing of the
1400 If authentication is successful and
1406 the client will be called back on the given number.
1407 If CBCP is being used,
1409 may also contain a list of numbers or a
1414 The value will be used in
1416 subsequent CBCP phase.
1417 .Sh PPP OVER TCP and UDP (a.k.a Tunnelling)
1420 over a serial link, it is possible to
1421 use a TCP connection instead by specifying the host, port and protocol as the
1424 .Dl set device ui-gate:6669/tcp
1426 Instead of opening a serial device,
1428 will open a TCP connection to the given machine on the given
1430 It should be noted however that
1432 doesn't use the telnet protocol and will be unable to negotiate
1433 with a telnet server.
1434 You should set up a port for receiving this
1436 connection on the receiving machine (ui-gate).
1437 This is done by first updating
1439 to name the service:
1441 .Dl ppp-in 6669/tcp # Incoming PPP connections over TCP
1447 how to deal with incoming connections on that port:
1449 .Dl ppp-in stream tcp nowait root /usr/sbin/ppp ppp -direct ppp-in
1451 Don't forget to send a
1455 after you've updated
1456 .Pa /etc/inetd.conf .
1457 Here, we use a label named
1460 .Pa /etc/ppp/ppp.conf
1461 on ui-gate (the receiver) should contain the following:
1462 .Bd -literal -offset indent
1465 set ifaddr 10.0.4.1 10.0.4.2
1469 .Pa /etc/ppp/ppp.linkup
1471 .Bd -literal -offset indent
1473 add 10.0.1.0/24 HISADDR
1476 It is necessary to put the
1480 to ensure that the route is only added after
1482 has negotiated and assigned addresses to its interface.
1484 You may also want to enable PAP or CHAP for security.
1485 To enable PAP, add the following line:
1486 .Bd -literal -offset indent
1490 You'll also need to create the following entry in
1491 .Pa /etc/ppp/ppp.secret :
1492 .Bd -literal -offset indent
1493 MyAuthName MyAuthPasswd
1500 the password is looked up in the
1505 .Pa /etc/ppp/ppp.conf
1506 on awfulhak (the initiator) should contain the following:
1507 .Bd -literal -offset indent
1510 set device ui-gate:ppp-in/tcp
1513 set log Phase Chat Connect hdlc LCP IPCP IPV6CP CCP tun
1514 set ifaddr 10.0.4.2 10.0.4.1
1517 with the route setup in
1518 .Pa /etc/ppp/ppp.linkup :
1519 .Bd -literal -offset indent
1521 add 10.0.2.0/24 HISADDR
1524 Again, if you're enabling PAP, you'll also need this in the
1525 .Pa /etc/ppp/ppp.conf
1527 .Bd -literal -offset indent
1528 set authname MyAuthName
1529 set authkey MyAuthKey
1532 We're assigning the address of 10.0.4.1 to ui-gate, and the address
1533 10.0.4.2 to awfulhak.
1534 To open the connection, just type
1536 .Dl awfulhak # ppp -background ui-gate
1538 The result will be an additional "route" on awfulhak to the
1539 10.0.2.0/24 network via the TCP connection, and an additional
1540 "route" on ui-gate to the 10.0.1.0/24 network.
1541 The networks are effectively bridged - the underlying TCP
1542 connection may be across a public network (such as the
1545 traffic is conceptually encapsulated
1546 (although not packet by packet) inside the TCP stream between
1549 The major disadvantage of this mechanism is that there are two
1550 "guaranteed delivery" mechanisms in place - the underlying TCP
1551 stream and whatever protocol is used over the
1553 link - probably TCP again.
1554 If packets are lost, both levels will
1555 get in each others way trying to negotiate sending of the missing
1558 To avoid this overhead, it is also possible to do all this using
1559 UDP instead of TCP as the transport by simply changing the protocol
1560 from "tcp" to "udp".
1561 When using UDP as a transport,
1563 will operate in synchronous mode.
1564 This is another gain as the incoming
1565 data does not have to be rearranged into packets.
1567 Care should be taken when adding a default route through a tunneled
1569 It is quite common for the default route
1571 .Pa /etc/ppp/ppp.linkup )
1572 to end up routing the link's TCP connection through the tunnel,
1573 effectively garrotting the connection.
1574 To avoid this, make sure you add a static route for the benefit of
1576 .Bd -literal -offset indent
1579 set device ui-gate:ppp-in/tcp
1586 is the IP number that your route to
1590 When routing your connection accross a public network such as the Internet,
1591 it is preferable to encrypt the data.
1592 This can be done with the help of the MPPE protocol, although currently this
1593 means that you will not be able to also compress the traffic as MPPE is
1594 implemented as a compression layer (thank Microsoft for this).
1595 To enable MPPE encryption, add the following lines to
1596 .Pa /etc/ppp/ppp.conf
1598 .Bd -literal -offset indent
1600 disable deflate pred1
1604 ensuring that you've put the requisite entry in
1605 .Pa /etc/ppp/ppp.secret
1606 (MSCHAPv2 is challenge based, so
1610 MSCHAPv2 and MPPE are accepted by default, so the client end should work
1611 without any additional changes (although ensure you have
1616 .Sh NETWORK ADDRESS TRANSLATION (PACKET ALIASING)
1619 command line option enables network address translation (a.k.a. packet
1623 host to act as a masquerading gateway for other computers over
1624 a local area network.
1625 Outgoing IP packets are NAT'd so that they appear to come from the
1627 host, and incoming packets are de-NAT'd so that they are routed
1628 to the correct machine on the local area network.
1629 NAT allows computers on private, unregistered subnets to have Internet
1630 access, although they are invisible from the outside world.
1633 operation should first be verified with network address translation disabled.
1636 option should be switched on, and network applications (web browser,
1641 should be checked on the
1644 Finally, the same or similar applications should be checked on other
1645 computers in the LAN.
1646 If network applications work correctly on the
1648 host, but not on other machines in the LAN, then the masquerading
1649 software is working properly, but the host is either not forwarding
1650 or possibly receiving IP packets.
1651 Check that IP forwarding is enabled in
1653 and that other machines have designated the
1655 host as the gateway for the LAN.
1656 .Sh PACKET FILTERING
1657 This implementation supports packet filtering.
1658 There are four kinds of
1668 Here are the basics:
1671 A filter definition has the following syntax:
1680 .Ar src_addr Ns Op / Ns Ar width
1681 .Op Ar dst_addr Ns Op / Ns Ar width
1683 .Ar [ proto Op src Ar cmp port
1688 .Op timeout Ar secs ]
1700 is a numeric value between
1704 specifying the rule number.
1705 Rules are specified in numeric order according to
1716 in which case, if a given packet matches the rule, the associated action
1717 is taken immediately.
1719 can also be specified as
1721 to clear the action associated with that particular rule, or as a new
1722 rule number greater than the current rule.
1723 In this case, if a given
1724 packet matches the current rule, the packet will next be matched against
1725 the new rule number (rather than the next rule number).
1729 may optionally be followed with an exclamation mark
1733 to reverse the sense of the following match.
1735 .Op Ar src_addr Ns Op / Ns Ar width
1737 .Op Ar dst_addr Ns Op / Ns Ar width
1738 are the source and destination IP number specifications.
1741 is specified, it gives the number of relevant netmask bits,
1742 allowing the specification of an address range.
1748 may be given the values
1754 (refer to the description of the
1756 command for a description of these values).
1757 When these values are used,
1758 the filters will be updated any time the values change.
1759 This is similar to the behaviour of the
1764 may be any protocol from
1773 meaning less-than, equal and greater-than respectively.
1775 can be specified as a numeric port or by service name from
1783 flags are only allowed when
1787 and represent the TH_ACK, TH_SYN and TH_FIN or TH_RST TCP flags respectively.
1789 The timeout value adjusts the current idle timeout to at least
1792 If a timeout is given in the alive filter as well as in the in/out
1793 filter, the in/out value is used.
1794 If no timeout is given, the default timeout (set using
1796 and defaulting to 180 seconds) is used.
1800 Each filter can hold up to 40 rules, starting from rule 0.
1801 The entire rule set is not effective until rule 0 is defined,
1802 i.e., the default is to allow everything through.
1804 If no rule in a defined set of rules matches a packet, that packet will
1805 be discarded (blocked).
1806 If there are no rules in a given filter, the packet will be permitted.
1808 It's possible to filter based on the payload of UDP frames where those
1814 .Ar filter-decapsulation
1815 option below for further details.
1818 .Dq set filter Ar name No -1
1823 .Pa /usr/share/examples/ppp/ppp.conf.sample .
1824 .Sh SETTING THE IDLE TIMER
1825 To check/set the idle timer, use the
1830 .Bd -literal -offset indent
1831 ppp ON awfulhak> set timeout 600
1834 The timeout period is measured in seconds, the default value for which
1837 To disable the idle timer function, use the command
1838 .Bd -literal -offset indent
1839 ppp ON awfulhak> set timeout 0
1846 modes, the idle timeout is ignored.
1849 mode, when the idle timeout causes the
1854 program itself remains running.
1855 Another trigger packet will cause it to attempt to re-establish the link.
1856 .Sh PREDICTOR-1 and DEFLATE COMPRESSION
1858 supports both Predictor type 1 and deflate compression.
1861 will attempt to use (or be willing to accept) both compression protocols
1862 when the peer agrees
1864 The deflate protocol is preferred by
1870 commands if you wish to disable this functionality.
1872 It is possible to use a different compression algorithm in each direction
1873 by using only one of
1877 (assuming that the peer supports both algorithms).
1879 By default, when negotiating DEFLATE,
1881 will use a window size of 15.
1884 command if you wish to change this behaviour.
1886 A special algorithm called DEFLATE24 is also available, and is disabled
1887 and denied by default.
1888 This is exactly the same as DEFLATE except that
1889 it uses CCP ID 24 to negotiate.
1892 to successfully negotiate DEFLATE with
1895 .Sh CONTROLLING IP ADDRESS
1898 uses IPCP to negotiate IP addresses.
1899 Each side of the connection
1900 specifies the IP address that it's willing to use, and if the requested
1901 IP address is acceptable then
1903 returns an ACK to the requester.
1906 returns NAK to suggest that the peer use a different IP address.
1908 both sides of the connection agree to accept the received request (and
1909 send an ACK), IPCP is set to the open state and a network level connection
1911 To control this IPCP behaviour, this implementation has the
1913 command for defining the local and remote IP address:
1914 .Bd -ragged -offset indent
1915 .No set ifaddr Oo Ar src_addr Ns
1917 .Oo Ar dst_addr Ns Op / Ns Ar \&nn
1927 is the IP address that the local side is willing to use,
1929 is the IP address which the remote side should use and
1931 is the netmask that should be used.
1933 defaults to the current
1936 defaults to 0.0.0.0, and
1938 defaults to whatever mask is appropriate for
1940 It is only possible to make
1942 smaller than the default.
1943 The usual value is 255.255.255.255, as
1944 most kernels ignore the netmask of a POINTOPOINT interface.
1948 implementations require that the peer negotiates a specific IP
1951 If this is the case,
1953 may be used to specify this IP number.
1954 This will not affect the
1955 routing table unless the other side agrees with this proposed number.
1956 .Bd -literal -offset indent
1957 set ifaddr 192.244.177.38 192.244.177.2 255.255.255.255 0.0.0.0
1960 The above specification means:
1962 .Bl -bullet -compact
1964 I will first suggest that my IP address should be 0.0.0.0, but I
1965 will only accept an address of 192.244.177.38.
1967 I strongly insist that the peer uses 192.244.177.2 as his own
1968 address and won't permit the use of any IP address but 192.244.177.2.
1969 When the peer requests another IP address, I will always suggest that
1970 it uses 192.244.177.2.
1972 The routing table entry will have a netmask of 0xffffffff.
1975 This is all fine when each side has a pre-determined IP address, however
1976 it is often the case that one side is acting as a server which controls
1977 all IP addresses and the other side should go along with it.
1978 In order to allow more flexible behaviour, the
1980 command allows the user to specify IP addresses more loosely:
1982 .Dl set ifaddr 192.244.177.38/24 192.244.177.2/20
1984 A number followed by a slash
1986 represents the number of bits significant in the IP address.
1987 The above example means:
1989 .Bl -bullet -compact
1991 I'd like to use 192.244.177.38 as my address if it is possible, but I'll
1992 also accept any IP address between 192.244.177.0 and 192.244.177.255.
1994 I'd like to make him use 192.244.177.2 as his own address, but I'll also
1995 permit him to use any IP address between 192.244.176.0 and
1998 As you may have already noticed, 192.244.177.2 is equivalent to saying
2001 As an exception, 0 is equivalent to 0.0.0.0/0, meaning that I have no
2002 preferred IP address and will obey the remote peers selection.
2003 When using zero, no routing table entries will be made until a connection
2006 192.244.177.2/0 means that I'll accept/permit any IP address but I'll
2007 suggest that 192.244.177.2 be used first.
2010 When negotiating IPv6 addresses, no control is given to the user.
2011 IPV6CP negotiation is fully automatic.
2012 .Sh CONNECTING WITH YOUR INTERNET SERVICE PROVIDER
2013 The following steps should be taken when connecting to your ISP:
2016 Describe your providers phone number(s) in the dial script using the
2019 This command allows you to set multiple phone numbers for
2020 dialing and redialing separated by either a pipe
2024 .Bd -ragged -offset indent
2025 .No set phone Ar telno Ns Xo
2026 .Oo \&| Ns Ar backupnumber
2027 .Oc Ns ... Ns Oo : Ns Ar nextnumber
2032 Numbers after the first in a pipe-separated list are only used if the
2033 previous number was used in a failed dial or login script.
2035 separated by a colon are used sequentially, irrespective of what happened
2036 as a result of using the previous number.
2038 .Bd -literal -offset indent
2039 set phone "1234567|2345678:3456789|4567890"
2042 Here, the 1234567 number is attempted.
2043 If the dial or login script fails,
2044 the 2345678 number is used next time, but *only* if the dial or login script
2046 On the dial after this, the 3456789 number is used.
2048 number is only used if the dial or login script using the 3456789 fails.
2049 If the login script of the 2345678 number fails, the next number is still the
2051 As many pipes and colons can be used as are necessary
2052 (although a given site would usually prefer to use either the pipe or the
2053 colon, but not both).
2054 The next number redial timeout is used between all numbers.
2055 When the end of the list is reached, the normal redial period is
2056 used before starting at the beginning again.
2057 The selected phone number is substituted for the \\\\T string in the
2059 command (see below).
2061 Set up your redial requirements using
2063 For example, if you have a bad telephone line or your provider is
2064 usually engaged (not so common these days), you may want to specify
2066 .Bd -literal -offset indent
2070 This says that up to 4 phone calls should be attempted with a pause of 10
2071 seconds before dialing the first number again.
2073 Describe your login procedure using the
2080 command is used to talk to your modem and establish a link with your
2082 .Bd -literal -offset indent
2083 set dial "ABORT BUSY ABORT NO\\\\sCARRIER TIMEOUT 4 \\"\\" \e
2084 ATZ OK-ATZ-OK ATDT\\\\T TIMEOUT 60 CONNECT"
2087 This modem "chat" string means:
2090 Abort if the string "BUSY" or "NO CARRIER" are received.
2092 Set the timeout to 4 seconds.
2099 If that's not received within the 4 second timeout, send ATZ
2102 Send ATDTxxxxxxx where xxxxxxx is the next number in the phone list from
2105 Set the timeout to 60.
2107 Wait for the CONNECT string.
2110 Once the connection is established, the login script is executed.
2111 This script is written in the same style as the dial script, but care should
2112 be taken to avoid having your password logged:
2113 .Bd -literal -offset indent
2114 set authkey MySecret
2115 set login "TIMEOUT 15 login:-\\\\r-login: awfulhak \e
2116 word: \\\\P ocol: PPP HELLO"
2119 This login "chat" string means:
2122 Set the timeout to 15 seconds.
2125 If it's not received, send a carriage return and expect
2130 Expect "word:" (the tail end of a "Password:" prompt).
2132 Send whatever our current
2136 Expect "ocol:" (the tail end of a "Protocol:" prompt).
2145 command is logged specially.
2150 logging is enabled, the actual password is not logged;
2154 Login scripts vary greatly between ISPs.
2155 If you're setting one up for the first time,
2156 .Em ENABLE CHAT LOGGING
2157 so that you can see if your script is behaving as you expect.
2163 to specify your serial line and speed, for example:
2164 .Bd -literal -offset indent
2165 set device /dev/cuaa0
2169 Cuaa0 is the first serial port on
2176 A speed of 115200 should be specified
2177 if you have a modem capable of bit rates of 28800 or more.
2178 In general, the serial speed should be about four times the modem speed.
2182 command to {define} the IP address.
2185 If you know what IP address your provider uses, then use it as the remote
2186 address (dst_addr), otherwise choose something like 10.0.0.2/0 (see below).
2188 If your provider has assigned a particular IP address to you, then use
2189 it as your address (src_addr).
2191 If your provider assigns your address dynamically, choose a suitably
2192 unobtrusive and unspecific IP number as your address.
2193 10.0.0.1/0 would be appropriate.
2194 The bit after the / specifies how many bits of the
2195 address you consider to be important, so if you wanted to insist on
2196 something in the class C network 1.2.3.0, you could specify 1.2.3.1/24.
2198 If you find that your ISP accepts the first IP number that you suggest,
2199 specify third and forth arguments of
2201 This will force your ISP to assign a number.
2202 (The third argument will
2203 be ignored as it is less restrictive than the default mask for your
2207 An example for a connection where you don't know your IP number or your
2208 ISPs IP number would be:
2209 .Bd -literal -offset indent
2210 set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0
2214 In most cases, your ISP will also be your default router.
2215 If this is the case, add the line
2216 .Bd -literal -offset indent
2221 .Pa /etc/ppp/ppp.conf
2223 .Pa /etc/ppp/ppp.linkup
2224 for setups that don't use
2230 to add a default route to whatever the peer address is
2231 (10.0.0.2 in this example).
2234 meaning that should the value of
2236 change, the route will be updated accordingly.
2238 If your provider requests that you use PAP/CHAP authentication methods, add
2239 the next lines to your
2240 .Pa /etc/ppp/ppp.conf
2242 .Bd -literal -offset indent
2244 set authkey MyPassword
2247 Both are accepted by default, so
2249 will provide whatever your ISP requires.
2251 It should be noted that a login script is rarely (if ever) required
2252 when PAP or CHAP are in use.
2254 Ask your ISP to authenticate your nameserver address(es) with the line
2255 .Bd -literal -offset indent
2261 do this if you are running a local DNS unless you also either use
2266 .Pa /etc/ppp/ppp.linkdown ,
2269 will simply circumvent its use by entering some nameserver lines in
2270 .Pa /etc/resolv.conf .
2274 .Pa /usr/share/examples/ppp/ppp.conf.sample
2276 .Pa /usr/share/examples/ppp/ppp.linkup.sample
2277 for some real examples.
2278 The pmdemand label should be appropriate for most ISPs.
2279 .Sh LOGGING FACILITY
2281 is able to generate the following log info either via
2283 or directly to the screen:
2285 .Bl -tag -width XXXXXXXXX -offset XXX -compact
2287 Enable all logging facilities.
2288 This generates a lot of log.
2289 The most common use of 'all' is as a basis, where you remove some facilities
2290 after enabling 'all' ('debug' and 'timer' are usually best disabled.)
2292 Dump async level packet in hex.
2294 Generate CBCP (CallBack Control Protocol) logs.
2296 Generate a CCP packet trace.
2304 chat script trace logs.
2306 Log commands executed either from the command line or any of the configuration
2309 Log Chat lines containing the string "CONNECT".
2311 Log debug information.
2313 Log DNS QUERY packets.
2315 Log packets permitted by the dial filter and denied by any filter.
2317 Dump HDLC packet in hex.
2319 Log all function calls specifically made as user id 0.
2321 Generate an IPCP packet trace.
2323 Generate an LCP packet trace.
2325 Generate LQR reports.
2327 Phase transition log output.
2329 Dump physical level packet in hex.
2331 Dump sync level packet in hex.
2333 Dump all TCP/IP packets.
2335 Log timer manipulation.
2337 Include the tun device on each log line.
2339 Output to the terminal device.
2340 If there is currently no terminal,
2341 output is sent to the log file using syslogs
2344 Output to both the terminal device
2345 and the log file using syslogs
2348 Output to the log file using
2354 command allows you to set the logging output level.
2355 Multiple levels can be specified on a single command line.
2356 The default is equivalent to
2359 It is also possible to log directly to the screen.
2360 The syntax is the same except that the word
2362 should immediately follow
2366 (i.e., only the un-maskable warning, error and alert output).
2368 If The first argument to
2369 .Dq set log Op local
2374 character, the current log levels are
2375 not cleared, for example:
2376 .Bd -literal -offset indent
2377 PPP ON awfulhak> set log phase
2378 PPP ON awfulhak> show log
2379 Log: Phase Warning Error Alert
2380 Local: Warning Error Alert
2381 PPP ON awfulhak> set log +tcp/ip -warning
2382 PPP ON awfulhak> set log local +command
2383 PPP ON awfulhak> show log
2384 Log: Phase TCP/IP Warning Error Alert
2385 Local: Command Warning Error Alert
2388 Log messages of level Warning, Error and Alert are not controllable
2390 .Dq set log Op local .
2394 level is special in that it will not be logged if it can be displayed
2398 deals with the following signals:
2399 .Bl -tag -width "USR2"
2401 Receipt of this signal causes the termination of the current connection
2405 to exit unless it is in
2410 .It HUP, TERM & QUIT
2417 to re-open any existing server socket, dropping all existing diagnostic
2419 Sockets that couldn't previously be opened will be retried.
2423 to close any existing server socket, dropping all existing diagnostic
2426 can still be used to re-open the socket.
2429 If you wish to use more than one physical link to connect to a
2431 peer, that peer must also understand the
2434 Refer to RFC 1990 for specification details.
2436 The peer is identified using a combination of his
2437 .Dq endpoint discriminator
2439 .Dq authentication id .
2440 Either or both of these may be specified.
2441 It is recommended that
2442 at least one is specified, otherwise there is no way of ensuring that
2443 all links are actually connected to the same peer program, and some
2444 confusing lock-ups may result.
2445 Locally, these identification variables are specified using the
2454 must be agreed in advance with the peer.
2456 Multi-link capabilities are enabled using the
2458 command (set maximum reconstructed receive unit).
2459 Once multi-link is enabled,
2461 will attempt to negotiate a multi-link connection with the peer.
2463 By default, only one
2468 To create more links, the
2471 This command will clone existing links, where all
2472 characteristics are the same except:
2475 The new link has its own name as specified on the
2482 Its mode may subsequently be changed using the
2486 The new link is in a
2491 A summary of all available links can be seen using the
2495 Once a new link has been created, command usage varies.
2496 All link specific commands must be prefixed with the
2498 command, specifying on which link the command is to be applied.
2499 When only a single link is available,
2501 is smart enough not to require the
2505 Some commands can still be used without specifying a link - resulting
2506 in an operation at the
2509 For example, once two or more links are available, the command
2511 will show CCP configuration and statistics at the multi-link level, and
2512 .Dq link deflink show ccp
2513 will show the same information at the
2517 Armed with this information, the following configuration might be used:
2519 .Bd -literal -offset indent
2523 set device /dev/cuaa0 /dev/cuaa1 /dev/cuaa2
2524 set phone "123456789"
2525 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \\"\\" ATZ \e
2526 OK-AT-OK \\\\dATDT\\\\T TIMEOUT 45 CONNECT"
2528 set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0
2530 set authkey ppppassword
2533 clone 1,2,3 # Create 3 new links - duplicates of the default
2534 link deflink remove # Delete the default link (called ``deflink'')
2537 Note how all cloning is done at the end of the configuration.
2538 Usually, the link will be configured first, then cloned.
2539 If you wish all links
2540 to be up all the time, you can add the following line to the end of your
2543 .Bd -literal -offset indent
2544 link 1,2,3 set mode ddial
2547 If you want the links to dial on demand, this command could be used:
2549 .Bd -literal -offset indent
2550 link * set mode auto
2553 Links may be tied to specific names by removing the
2555 line above, and specifying the following after the
2559 .Bd -literal -offset indent
2560 link 1 set device /dev/cuaa0
2561 link 2 set device /dev/cuaa1
2562 link 3 set device /dev/cuaa2
2567 command to see which commands require context (using the
2569 command), which have optional
2570 context and which should not have any context.
2576 mode with the peer, it creates a local domain socket in the
2579 This socket is used to pass link information (including
2580 the actual link file descriptor) between different
2585 ability to be run from a
2591 capability), without needing to have initial control of the serial
2595 negotiates multi-link mode, it will pass its open link to any
2596 already running process.
2597 If there is no already running process,
2599 will act as the master, creating the socket and listening for new
2601 .Sh PPP COMMAND LIST
2602 This section lists the available commands and their effect.
2603 They are usable either from an interactive
2605 session, from a configuration file or from a
2611 .It accept|deny|enable|disable Ar option....
2612 These directives tell
2614 how to negotiate the initial connection with the peer.
2617 has a default of either accept or deny and enable or disable.
2619 means that the option will be ACK'd if the peer asks for it.
2621 means that the option will be NAK'd if the peer asks for it.
2623 means that the option will be requested by us.
2625 means that the option will not be requested by us.
2628 may be one of the following:
2631 Default: Enabled and Accepted.
2632 ACFComp stands for Address and Control Field Compression.
2633 Non LCP packets will usually have an address
2634 field of 0xff (the All-Stations address) and a control field of
2635 0x03 (the Unnumbered Information command).
2637 negotiated, these two bytes are simply not sent, thus minimising
2644 Default: Disabled and Accepted.
2645 CHAP stands for Challenge Handshake Authentication Protocol.
2646 Only one of CHAP and PAP (below) may be negotiated.
2647 With CHAP, the authenticator sends a "challenge" message to its peer.
2648 The peer uses a one-way hash function to encrypt the
2649 challenge and sends the result back.
2650 The authenticator does the same, and compares the results.
2651 The advantage of this mechanism is that no
2652 passwords are sent across the connection.
2653 A challenge is made when the connection is first made.
2654 Subsequent challenges may occur.
2655 If you want to have your peer authenticate itself, you must
2658 .Pa /etc/ppp/ppp.conf ,
2659 and have an entry in
2660 .Pa /etc/ppp/ppp.secret
2663 When using CHAP as the client, you need only specify
2668 .Pa /etc/ppp/ppp.conf .
2669 CHAP is accepted by default.
2672 implementations use "MS-CHAP" rather than MD5 when encrypting the
2674 MS-CHAP is a combination of MD4 and DES.
2677 was built on a machine with DES libraries available, it will respond
2678 to MS-CHAP authentication requests, but will never request them.
2680 Default: Enabled and Accepted.
2681 This option decides if deflate
2682 compression will be used by the Compression Control Protocol (CCP).
2683 This is the same algorithm as used by the
2686 Note: There is a problem negotiating
2692 implementation available under many operating systems.
2694 (version 2.3.1) incorrectly attempts to negotiate
2696 compression using type
2698 as the CCP configuration type rather than type
2704 is actually specified as
2705 .Dq PPP Magna-link Variable Resource Compression
2709 is capable of negotiating with
2716 .Ar accept Ns No ed .
2718 Default: Disabled and Denied.
2719 This is a variance of the
2721 option, allowing negotiation with the
2726 section above for details.
2727 It is disabled by default as it violates
2730 Default: Disabled and Denied.
2731 This option allows DNS negotiation.
2736 will request that the peer confirms the entries in
2737 .Pa /etc/resolv.conf .
2738 If the peer NAKs our request (suggesting new IP numbers),
2739 .Pa /etc/resolv.conf
2740 is updated and another request is sent to confirm the new entries.
2743 .Dq accept Ns No ed,
2745 will answer any DNS queries requested by the peer rather than rejecting
2747 The answer is taken from
2748 .Pa /etc/resolv.conf
2751 command is used as an override.
2753 Default: Enabled and Accepted.
2754 This option allows control over whether we
2755 negotiate an endpoint discriminator.
2756 We only send our discriminator if
2761 We reject the peers discriminator if
2765 Default: Disabled and Accepted.
2766 The use of this authentication protocol
2767 is discouraged as it partially violates the authentication protocol by
2768 implementing two different mechanisms (LANMan & NT) under the guise of
2769 a single CHAP type (0x80).
2771 uses a simple DES encryption mechanism and is the least secure of the
2772 CHAP alternatives (although is still more secure than PAP).
2776 description below for more details.
2778 Default: Disabled and Accepted.
2779 This option decides if Link Quality Requests will be sent or accepted.
2780 LQR is a protocol that allows
2782 to determine that the link is down without relying on the modems
2784 When LQR is enabled,
2790 below) as part of the LCP request.
2791 If the peer agrees, both sides will
2792 exchange LQR packets at the agreed frequency, allowing detailed link
2793 quality monitoring by enabling LQM logging.
2794 If the peer doesn't agree,
2796 will send ECHO LQR requests instead.
2797 These packets pass no information of interest, but they
2799 be replied to by the peer.
2801 Whether using LQR or ECHO LQR,
2803 will abruptly drop the connection if 5 unacknowledged packets have been
2804 sent rather than sending a 6th.
2805 A message is logged at the
2807 level, and any appropriate
2809 values are honoured as if the peer were responsible for dropping the
2812 Default: Enabled and Accepted.
2813 This is Microsoft Point to Point Encryption scheme.
2814 MPPE key size can be
2815 40-, 56- and 128-bits.
2820 Default: Disabled and Accepted.
2821 It is very similar to standard CHAP (type 0x05)
2822 except that it issues challenges of a fixed 16 bytes in length and uses a
2823 combination of MD4, SHA-1 and DES to encrypt the challenge rather than using the
2824 standard MD5 mechanism.
2826 Default: Disabled and Accepted.
2827 The use of this authentication protocol
2828 is discouraged as it partially violates the authentication protocol by
2829 implementing two different mechanisms (LANMan & NT) under the guise of
2830 a single CHAP type (0x80).
2831 It is very similar to standard CHAP (type 0x05)
2832 except that it issues challenges of a fixed 8 bytes in length and uses a
2833 combination of MD4 and DES to encrypt the challenge rather than using the
2834 standard MD5 mechanism.
2835 CHAP type 0x80 for LANMan is also supported - see
2843 use CHAP type 0x80, when acting as authenticator with both
2844 .Dq enable Ns No d ,
2846 will rechallenge the peer up to three times if it responds using the wrong
2847 one of the two protocols.
2848 This gives the peer a chance to attempt using both protocols.
2852 acts as the authenticatee with both protocols
2853 .Dq accept Ns No ed ,
2854 the protocols are used alternately in response to challenges.
2856 Note: If only LANMan is enabled,
2858 (version 2.3.5) misbehaves when acting as authenticatee.
2860 the NT and the LANMan answers, but also suggests that only the NT answer
2863 Default: Disabled and Accepted.
2864 PAP stands for Password Authentication Protocol.
2865 Only one of PAP and CHAP (above) may be negotiated.
2866 With PAP, the ID and Password are sent repeatedly to the peer until
2867 authentication is acknowledged or the connection is terminated.
2868 This is a rather poor security mechanism.
2869 It is only performed when the connection is first established.
2870 If you want to have your peer authenticate itself, you must
2873 .Pa /etc/ppp/ppp.conf ,
2874 and have an entry in
2875 .Pa /etc/ppp/ppp.secret
2876 for the peer (although see the
2882 When using PAP as the client, you need only specify
2887 .Pa /etc/ppp/ppp.conf .
2888 PAP is accepted by default.
2890 Default: Enabled and Accepted.
2891 This option decides if Predictor 1
2892 compression will be used by the Compression Control Protocol (CCP).
2894 Default: Enabled and Accepted.
2895 This option is used to negotiate
2896 PFC (Protocol Field Compression), a mechanism where the protocol
2897 field number is reduced to one octet rather than two.
2899 Default: Enabled and Accepted.
2900 This option determines if
2902 will request and accept requests for short
2904 sequence numbers when negotiating multi-link mode.
2905 This is only applicable if our MRRU is set (thus enabling multi-link).
2907 Default: Enabled and Accepted.
2908 This option determines if Van Jacobson header compression will be used.
2911 The following options are not actually negotiated with the peer.
2912 Therefore, accepting or denying them makes no sense.
2914 .It filter-decapsulation
2916 When this option is enabled,
2918 will examine UDP frames to see if they actually contain a
2920 frame as their payload.
2921 If this is the case, all filters will operate on the payload rather
2922 than the actual packet.
2924 This is useful if you want to send PPPoUDP traffic over a
2926 link, but want that link to do smart things with the real data rather than
2929 The UDP frame payload must not be compressed in any way, otherwise
2931 will not be able to interpret it.
2932 It's therefore recommended that you
2933 .Ic disable vj pred1 deflate
2935 .Ic deny vj pred1 deflate
2936 in the configuration for the
2938 invocation with the udp link.
2943 exchanges low-level LCP, CCP and IPCP configuration traffic, the
2945 field of any replies is expected to be the same as that of the request.
2948 drops any reply packets that do not contain the expected identifier
2949 field, reporting the fact at the respective log level.
2954 will ignore the identifier field.
2959 This option simply tells
2961 to add new interface addresses to the interface rather than replacing them.
2962 The option can only be enabled if network address translation is enabled
2963 .Pq Dq nat enable yes .
2965 With this option enabled,
2967 will pass traffic for old interface addresses through the NAT
2968 ifdef({LOCALNAT},{engine,},{engine
2970 .Xr libalias 3 ) ,})
2971 resulting in the ability (in
2973 mode) to properly connect the process that caused the PPP link to
2974 come up in the first place.
2984 to attempt to negotiate IP control protocol capabilities and if
2985 successful to exchange IP datagrams with the peer.
2990 to attempt to negotiate IPv6 control protocol capabilities and if
2991 successful to exchange IPv6 datagrams with the peer.
2996 runs as a Multi-link server, a different
2998 instance initially receives each connection.
2999 After determining that
3000 the link belongs to an already existing bundle (controlled by another
3004 will transfer the link to that process.
3006 If the link is a tty device or if this option is enabled,
3008 will not exit, but will change its process name to
3010 and wait for the controlling
3012 to finish with the link and deliver a signal back to the idle process.
3013 This prevents the confusion that results from
3015 parent considering the link resource available again.
3017 For tty devices that have entries in
3019 this is necessary to prevent another
3021 from being started, and for program links such as
3025 from exiting due to the death of its child.
3028 cannot determine its parents requirements (except for the tty case), this
3029 option must be enabled manually depending on the circumstances.
3036 will automatically loop back packets being sent
3037 out with a destination address equal to that of the
3042 will send the packet, probably resulting in an ICMP redirect from
3044 It is convenient to have this option enabled when
3045 the interface is also the default route as it avoids the necessity
3046 of a loopback route.
3049 Enabling this option will tell the PAP authentication
3050 code to use the password database (see
3052 to authenticate the caller if they cannot be found in the
3053 .Pa /etc/ppp/ppp.secret
3055 .Pa /etc/ppp/ppp.secret
3056 is always checked first.
3057 If you wish to use passwords from
3059 but also to specify an IP number or label for a given client, use
3061 as the client password in
3062 .Pa /etc/ppp/ppp.secret .
3065 Enabling this option will tell
3067 to proxy ARP for the peer.
3070 will make an entry in the ARP table using
3074 address of the local network in which
3077 This allows other machines connecteed to the LAN to talk to
3078 the peer as if the peer itself was connected to the LAN.
3079 The proxy entry cannot be made unless
3081 is an address from a LAN.
3084 Enabling this will tell
3086 to add proxy arp entries for every IP address in all class C or
3087 smaller subnets routed via the tun interface.
3089 Proxy arp entries are only made for sticky routes that are added
3093 No proxy arp entries are made for the interface address itself
3101 command is used with the
3107 values, entries are stored in the
3110 Each time these variables change, this list is re-applied to the routing table.
3112 Disabling this option will prevent the re-application of sticky routes,
3115 list will still be maintained.
3122 to adjust TCP SYN packets so that the maximum receive segment
3123 size is not greater than the amount allowed by the interface MTU.
3128 to gather throughput statistics.
3129 Input and output is sampled over
3130 a rolling 5 second window, and current, best and total figures are retained.
3131 This data is output when the relevant
3133 layer shuts down, and is also available using the
3136 Throughput statistics are available at the
3143 Normally, when a user is authenticated using PAP or CHAP, and when
3147 mode, an entry is made in the utmp and wtmp files for that user.
3148 Disabling this option will tell
3150 not to make any utmp or wtmp entries.
3151 This is usually only necessary if
3152 you require the user to both login and authenticate themselves.
3157 .Ar dest Ns Op / Ns Ar nn
3162 is the destination IP address.
3163 The netmask is specified either as a number of bits with
3165 or as an IP number using
3170 with no mask refers to the default route.
3171 It is also possible to use the literal name
3176 is the next hop gateway to get to the given
3181 command for further details.
3183 It is possible to use the symbolic names
3189 as the destination, and
3196 is replaced with the interface IP address,
3198 is replaced with the interface IP destination (peer) address,
3200 is replaced with the interface IPv6 address, and
3202 is replaced with the interface IPv6 destination address,
3209 then if the route already exists, it will be updated as with the
3213 for further details).
3215 Routes that contain the
3223 constants are considered
3225 They are stored in a list (use
3227 to see the list), and each time the value of one of these variables
3228 changes, the appropriate routing table entries are updated.
3229 This facility may be disabled using
3230 .Dq disable sroutes .
3231 .It allow Ar command Op Ar args
3232 This command controls access to
3234 and its configuration files.
3235 It is possible to allow user-level access,
3236 depending on the configuration file label and on the mode that
3239 For example, you may wish to configure
3249 User id 0 is immune to these commands.
3251 .It allow user Ns Xo
3253 .Ar logname Ns No ...
3255 By default, only user id 0 is allowed access to
3257 If this command is used, all of the listed users are allowed access to
3258 the section in which the
3263 section is always checked first (even though it is only ever automatically
3266 commands are cumulative in a given section, but users allowed in any given
3267 section override users allowed in the default section, so it's possible to
3268 allow users access to everything except a given label by specifying default
3271 section, and then specifying a new user list for that label.
3275 is specified, access is allowed to all users.
3276 .It allow mode Ns Xo
3280 By default, access using any
3283 If this command is used, it restricts the access
3285 allowed to load the label under which this command is specified.
3290 command overrides any previous settings, and the
3292 section is always checked first.
3304 When running in multi-link mode, a section can be loaded if it allows
3306 of the currently existing line modes.
3309 .It nat Ar command Op Ar args
3310 This command allows the control of the network address translation (also
3311 known as masquerading or IP aliasing) facilities that are built into
3313 NAT is done on the external interface only, and is unlikely to make sense
3318 If nat is enabled on your system (it may be omitted at compile time),
3319 the following commands are possible:
3321 .It nat enable yes|no
3322 This command either switches network address translation on or turns it off.
3325 command line flag is synonymous with
3326 .Dq nat enable yes .
3327 .It nat addr Op Ar addr_local addr_alias
3328 This command allows data for
3332 It is useful if you own a small number of real IP numbers that
3333 you wish to map to specific machines behind your gateway.
3334 .It nat deny_incoming yes|no
3335 If set to yes, this command will refuse all incoming packets where an
3336 aliasing link doesn't already exist.
3337 ifdef({LOCALNAT},{},{Refer to the
3338 .Sx CONCEPTUAL BACKGROUND
3341 for a description of what an
3346 It should be noted under what circumstances an aliasing link is
3347 ifdef({LOCALNAT},{created.},{created by
3349 It may be necessary to further protect your network from outside
3350 connections using the
3356 This command gives a summary of available nat commands.
3358 This option causes various NAT statistics and information to
3359 be logged to the file
3360 .Pa /var/log/alias.log .
3361 .It nat port Ar proto Ar targetIP Ns Xo
3362 .No : Ns Ar targetPort Ns
3364 .No - Ns Ar targetPort
3367 .No - Ns Ar aliasPort
3368 .Oc Oo Ar remoteIP : Ns
3371 .No - Ns Ar remotePort
3375 This command causes incoming
3389 A range of port numbers may be specified as shown above.
3390 The ranges must be of the same size.
3394 is specified, only data coming from that IP number is redirected.
3398 (indicating any source port)
3399 or a range of ports the same size as the other ranges.
3401 This option is useful if you wish to run things like Internet phone on
3402 machines behind your gateway, but is limited in that connections to only
3403 one interior machine per source machine and target port are possible.
3404 .It nat proto Ar proto localIP Oo
3405 .Ar publicIP Op Ar remoteIP
3409 to redirect packets of protocol type
3413 to the internal address
3418 is specified, only packets destined for that address are matched,
3419 otherwise the default alias address is used.
3423 is specified, only packets matching that source address are matched,
3425 This command is useful for redirecting tunnel endpoints to an internal machine,
3428 .Dl nat proto ipencap 10.0.0.1
3429 .It "nat proxy cmd" Ar arg Ns No ...
3432 to proxy certain connections, redirecting them to a given server.
3433 ifdef({LOCALNAT},{},{Refer to the description of
3434 .Fn PacketAliasProxyRule
3437 for details of the available commands.
3439 .It nat punch_fw Op Ar base count
3442 to punch holes in the firewall for FTP or IRC DCC connections.
3443 This is done dynamically by installing termporary firewall rules which
3444 allow a particular connection (and only that connection) to go through
3446 The rules are removed once the corresponding connection terminates.
3450 rules starting from rule number
3452 will be used for punching firewall holes.
3453 The range will be cleared when the
3457 If no arguments are given, firewall punching is disabled.
3458 .It nat same_ports yes|no
3459 When enabled, this command will tell the network address translation engine to
3460 attempt to avoid changing the port number on outgoing packets.
3462 if you want to support protocols such as RPC and LPD which require
3463 connections to come from a well known port.
3464 .It nat target Op Ar address
3465 Set the given target address or clear it if no address is given.
3466 The target address is used
3467 ifdef({LOCALNAT},{},{by libalias })dnl
3468 to specify how to NAT incoming packets by default.
3469 If a target address is not set or if
3471 is given, packets are not altered and are allowed to route to the internal
3474 The target address may be set to
3477 ifdef({LOCALNAT},{all packets will be redirected},
3478 {libalias will redirect all packets})
3479 to the interface address.
3480 .It nat use_sockets yes|no
3481 When enabled, this option tells the network address translation engine to
3482 create a socket so that it can guarantee a correct incoming ftp data or
3484 .It nat unregistered_only yes|no
3485 Only alter outgoing packets with an unregistered source address.
3486 According to RFC 1918, unregistered source addresses
3487 are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16.
3490 These commands are also discussed in the file
3492 which comes with the source distribution.
3499 is executed in the background with the following words replaced:
3500 .Bl -tag -width COMPILATIONDATE
3502 This is replaced with the local
3508 .It Li COMPILATIONDATE
3509 This is replaced with the date on which
3513 These are replaced with the primary and secondary nameserver IP numbers.
3514 If nameservers are negotiated by IPCP, the values of these macros will change.
3516 This is replaced with the local endpoint discriminator value.
3521 This is replaced with the peers IP number.
3523 This is replaced with the peers IPv6 number.
3525 This is replaced with the name of the interface that's in use.
3527 This is replaced with the number of IP bytes received since the connection
3530 This is replaced with the number of IP bytes sent since the connection
3533 This is replaced with the number of IP packets received since the connection
3536 This is replaced with the number of IP packets sent since the connection
3539 This is replaced with the number of IPv6 bytes received since the connection
3541 .It Li IPV6OCTETSOUT
3542 This is replaced with the number of IPv6 bytes sent since the connection
3544 .It Li IPV6PACKETSIN
3545 This is replaced with the number of IPv6 packets received since the connection
3547 .It Li IPV6PACKETSOUT
3548 This is replaced with the number of IPv6 packets sent since the connection
3551 This is replaced with the last label name used.
3552 A label may be specified on the
3554 command line, via the
3562 This is replaced with the IP number assigned to the local interface.
3564 This is replaced with the IPv6 number assigned to the local interface.
3566 This is replaced with the number of bytes received since the connection
3569 This is replaced with the number of bytes sent since the connection
3572 This is replaced with the number of packets received since the connection
3575 This is replaced with the number of packets sent since the connection
3578 This is replaced with the value of the peers endpoint discriminator.
3580 This is replaced with the current process id.
3582 This is replaced with the name of the diagnostic socket.
3584 This is replaced with the bundle uptime in HH:MM:SS format.
3586 This is replaced with the username that has been authenticated with PAP or
3588 Normally, this variable is assigned only in -direct mode.
3589 This value is available irrespective of whether utmp logging is enabled.
3591 This is replaced with the current version number of
3595 These substitutions are also done by the
3602 If you wish to pause
3604 while the command executes, use the
3607 .It clear physical|ipcp|ipv6 Op current|overall|peak...
3608 Clear the specified throughput values at either the
3616 is specified, context must be given (see the
3619 If no second argument is given, all values are cleared.
3620 .It clone Ar name Ns Xo
3621 .Op \&, Ns Ar name Ns
3624 Clone the specified link, creating one or more new links according to the
3627 This command must be used from the
3629 command below unless you've only got a single link (in which case that
3630 link becomes the default).
3631 Links may be removed using the
3635 The default link name is
3637 .It close Op lcp|ccp Ns Op !\&
3638 If no arguments are given, the relevant protocol layers will be brought
3639 down and the link will be closed.
3642 is specified, the LCP layer is brought down, but
3644 will not bring the link offline.
3645 It is subsequently possible to use
3648 to talk to the peer machine if, for example, something like
3653 is specified, only the relevant compression layer is closed.
3656 is used, the compression layer will remain in the closed state, otherwise
3657 it will re-enter the STOPPED state, waiting for the peer to initiate
3658 further CCP negotiation.
3659 In any event, this command does not disconnect the user from
3670 This command deletes the route with the given
3677 all non-direct entries in the routing table for the current interface,
3680 entries are deleted.
3685 the default route is deleted.
3693 will not complain if the route does not already exist.
3694 .It dial|call Op Ar label Ns Xo
3697 This command is the equivalent of
3701 and is provided for backwards compatibility.
3702 .It down Op Ar lcp|ccp
3703 Bring the relevant layer down ungracefully, as if the underlying layer
3704 had become unavailable.
3705 It's not considered polite to use this command on
3706 a Finite State Machine that's in the OPEN state.
3708 supplied, the entire link is closed (or if no context is given, all links
3714 layer is terminated but the device is not brought offline and the link
3718 is specified, only the relevant compression layer(s) are terminated.
3719 .It help|? Op Ar command
3720 Show a list of available commands.
3723 is specified, show the usage string for that command.
3724 .It ident Op Ar text Ns No ...
3725 Identify the link to the peer using
3729 is empty, link identification is disabled.
3730 It is possible to use any of the words described for the
3735 command for details of when
3737 identifies itself to the peer.
3738 .It iface Ar command Op args
3739 This command is used to control the interface used by
3742 may be one of the following:
3746 .Ar addr Ns Op / Ns Ar bits
3757 combination to the interface.
3758 Instead of specifying
3762 (with no space between it and
3764 If the given address already exists, the command fails unless the
3766 is used - in which case the previous interface address entry is overwritten
3767 with the new one, allowing a change of netmask or peer address.
3778 .Dq 255.255.255.255 .
3779 This address (the broadcast address) is the only duplicate peer address that
3782 .It iface clear Op INET | INET6
3783 If this command is used while
3785 is in the OPENED state or while in
3787 mode, all addresses except for the NCP negotiated address are deleted
3791 is not in the OPENED state and is not in
3793 mode, all interface addresses are deleted.
3795 If the INET or INET6 arguments are used, only addresses for that address
3798 .It iface delete Ns Xo
3803 This command deletes the given
3808 is used, no error is given if the address isn't currently assigned to
3809 the interface (and no deletion takes place).
3811 Shows the current state and current addresses for the interface.
3812 It is much the same as running
3813 .Dq ifconfig INTERFACE .
3814 .It iface help Op Ar sub-command
3815 This command, when invoked without
3817 will show a list of possible
3819 sub-commands and a brief synopsis for each.
3822 only the synopsis for the given sub-command is shown.
3826 .Ar name Ns Op , Ns Ar name Ns
3827 .No ... Ar command Op Ar args
3829 This command may prefix any other command if the user wishes to
3830 specify which link the command should affect.
3831 This is only applicable after multiple links have been created in Multi-link
3837 specifies the name of an existing link.
3840 is a comma separated list,
3842 is executed on each link.
3848 is executed on all links.
3849 .It load Op Ar label Ns Xo
3872 will not attempt to make an immediate connection.
3873 .It log Ar word Ns No ...
3874 Send the given word(s) to the log file with the prefix
3876 Word substitutions are done as explained under the
3879 .It open Op lcp|ccp|ipcp
3880 This is the opposite of the
3883 All closed links are immediately brought up apart from second and subsequent
3885 links - these will come up based on the
3887 command that has been used.
3891 argument is used while the LCP layer is already open, LCP will be
3893 This allows various LCP options to be changed, after which
3895 can be used to put them into effect.
3896 After renegotiating LCP,
3897 any agreed authentication will also take place.
3901 argument is used, the relevant compression layer is opened.
3902 Again, if it is already open, it will be renegotiated.
3906 argument is used, the link will be brought up as normal, but if
3907 IPCP is already open, it will be renegotiated and the network
3908 interface will be reconfigured.
3910 It is probably not good practice to re-open the PPP state machines
3911 like this as it's possible that the peer will not behave correctly.
3914 however useful as a way of forcing the CCP or VJ dictionaries to be reset.
3916 Specify the password required for access to the full
3919 This password is required when connecting to the diagnostic port (see the
3930 logging is active, instead, the literal string
3936 is executed from the controlling connection or from a command file,
3937 ppp will exit after closing all connections.
3938 Otherwise, if the user
3939 is connected to a diagnostic socket, the connection is simply dropped.
3945 will exit despite the source of the command after closing all existing
3948 This command removes the given link.
3949 It is only really useful in multi-link mode.
3950 A link must be in the
3952 state before it is removed.
3953 .It rename|mv Ar name
3954 This command renames the given link to
3958 is already used by another link.
3960 The default link name is
3967 may make the log file more readable.
3968 .It resolv Ar command
3969 This command controls
3976 starts up, it loads the contents of this file into memory and retains this
3977 image for future use.
3979 is one of the following:
3980 .Bl -tag -width readonly
3983 .Pa /etc/resolv.conf
3989 will still attempt to negotiate nameservers with the peer, making the results
3995 This is the opposite of the
4000 .Pa /etc/resolv.conf
4002 This may be necessary if for example a DHCP client overwrote
4003 .Pa /etc/resolv.conf .
4006 .Pa /etc/resolv.conf
4007 with the version originally read at startup or with the last
4010 This is sometimes a useful command to put in the
4011 .Pa /etc/ppp/ppp.linkdown
4015 .Pa /etc/resolv.conf
4017 This command will work even if the
4019 command has been used.
4020 It may be useful as a command in the
4021 .Pa /etc/ppp/ppp.linkup
4022 file if you wish to defer updating
4023 .Pa /etc/resolv.conf
4024 until after other commands have finished.
4029 .Pa /etc/resolv.conf
4034 successfully negotiates a DNS.
4035 This is the opposite of the
4040 This option is not (yet) implemented.
4044 to identify itself to the peer.
4045 The link must be in LCP state or higher.
4046 If no identity has been set (via the
4052 When an identity has been set,
4054 will automatically identify itself when it sends or receives a configure
4055 reject, when negotiation fails or when LCP reaches the opened state.
4057 Received identification packets are logged to the LCP log (see
4059 for details) and are never responded to.
4064 This option allows the setting of any of the following variables:
4066 .It set accmap Ar hex-value
4067 ACCMap stands for Asynchronous Control Character Map.
4069 negotiated with the peer, and defaults to a value of 00000000 in hex.
4070 This protocol is required to defeat hardware that depends on passing
4071 certain characters from end to end (such as XON/XOFF etc).
4073 For the XON/XOFF scenario, use
4074 .Dq set accmap 000a0000 .
4075 .It set Op auth Ns Xo
4078 This sets the authentication key (or password) used in client mode
4079 PAP or CHAP negotiation to the given value.
4080 It also specifies the
4081 password to be used in the dial or login scripts in place of the
4083 sequence, preventing the actual password from being logged.
4088 logging is in effect,
4092 for security reasons.
4094 If the first character of
4096 is an exclamation mark
4099 treats the remainder of the string as a program that must be executed
4111 it is treated as a single literal
4113 otherwise, ignoring the
4116 is parsed as a program to execute in the same was as the
4118 command above, substituting special names in the same manner.
4121 will feed the program three lines of input, each terminated by a newline
4125 The host name as sent in the CHAP challenge.
4127 The challenge string as sent in the CHAP challenge.
4133 Two lines of output are expected:
4138 to be sent with the CHAP response.
4142 which is encrypted with the challenge and request id, the answer being sent
4143 in the CHAP response packet.
4148 in this manner, it's expected that the host challenge is a series of ASCII
4149 digits or characters.
4150 An encryption device or Secure ID card is usually
4151 required to calculate the secret appropriate for the given challenge.
4152 .It set authname Ar id
4153 This sets the authentication id used in client mode PAP or CHAP negotiation.
4157 mode with CHAP enabled,
4159 is used in the initial authentication challenge and should normally be set to
4160 the local machine name.
4162 .Ar min-percent max-percent period
4164 These settings apply only in multi-link mode and default to zero, zero and
4170 mode link is available, only the first link is made active when
4172 first reads data from the tun device.
4175 link will be opened only when the current bundle throughput is at least
4177 percent of the total bundle bandwidth for
4180 When the current bundle throughput decreases to
4182 percent or less of the total bundle bandwidth for
4186 link will be brought down as long as it's not the last active link.
4188 Bundle throughput is measured as the maximum of inbound and outbound
4191 The default values cause
4193 links to simply come up one at a time.
4195 Certain devices cannot determine their physical bandwidth, so it
4196 is sometimes necessary to use the
4198 command (described below) to make
4201 .It set bandwidth Ar value
4202 This command sets the connection bandwidth in bits per second.
4204 must be greater than zero.
4205 It is currently only used by the
4208 .It set callback Ar option Ns No ...
4209 If no arguments are given, callback is disabled, otherwise,
4213 mode, will accept) one of the given
4214 .Ar option Ns No s .
4215 In client mode, if an
4219 will request a different
4221 until no options remain at which point
4223 will terminate negotiations (unless
4225 is one of the specified
4229 will accept any of the given protocols - but the client
4231 request one of them.
4232 If you wish callback to be optional, you must {include}
4238 are as follows (in this order of preference):
4242 The callee is expected to decide the callback number based on
4246 is the callee, the number should be specified as the fifth field of
4248 .Pa /etc/ppp/ppp.secret .
4250 Microsoft's callback control protocol is used.
4255 If you wish to negotiate
4257 in client mode but also wish to allow the server to request no callback at
4258 CBCP negotiation time, you must specify both
4262 as callback options.
4264 .Ar number Ns Op , Ns Ar number Ns
4267 The caller specifies the
4273 should be either a comma separated list of allowable numbers or a
4275 meaning any number is permitted.
4278 is the caller, only a single number should be specified.
4280 Note, this option is very unsafe when used with a
4282 as a malicious caller can tell
4284 to call any (possibly international) number without first authenticating
4287 If the peer does not wish to do callback at all,
4289 will accept the fact and continue without callback rather than terminating
4291 This is required (in addition to one or more other callback
4292 options) if you wish callback to be optional.
4296 .No *| Ns Ar number Ns Oo
4297 .No , Ns Ar number Ns ...\& Oc
4298 .Op Ar delay Op Ar retry
4300 If no arguments are given, CBCP (Microsoft's CallBack Control Protocol)
4301 is disabled - ie, configuring CBCP in the
4303 command will result in
4305 requesting no callback in the CBCP phase.
4308 attempts to use the given phone
4309 .Ar number Ns No (s).
4314 will insist that the client uses one of these numbers, unless
4316 is used in which case the client is expected to specify the number.
4320 will attempt to use one of the given numbers (whichever it finds to
4321 be agreeable with the peer), or if
4325 will expect the peer to specify the number.
4327 .No off| Ns Ar seconds Ns Op !\&
4331 checks for the existence of carrier depending on the type of device
4332 that has been opened:
4333 .Bl -tag -width XXX -offset XXX
4334 .It Terminal Devices
4335 Carrier is checked one second after the login script is complete.
4338 assumes that this is because the device doesn't support carrier (which
4341 NULL-modem cables), logs the fact and stops checking
4344 As ptys don't support the TIOCMGET ioctl, the tty device will switch all
4345 carrier detection off when it detects that the device is a pty.
4346 .It ISDN (i4b) Devices
4347 Carrier is checked once per second for 6 seconds.
4348 If it's not set after
4349 the sixth second, the connection attempt is considered to have failed and
4350 the device is closed.
4351 Carrier is always required for i4b devices.
4352 .It PPPoE (netgraph) Devices
4353 Carrier is checked once per second for 5 seconds.
4354 If it's not set after
4355 the fifth second, the connection attempt is considered to have failed and
4356 the device is closed.
4357 Carrier is always required for PPPoE devices.
4360 All other device types don't support carrier.
4361 Setting a carrier value will
4362 result in a warning when the device is opened.
4364 Some modems take more than one second after connecting to assert the carrier
4366 If this delay isn't increased, this will result in
4368 inability to detect when the link is dropped, as
4370 assumes that the device isn't asserting carrier.
4374 command overrides the default carrier behaviour.
4376 specifies the maximum number of seconds that
4378 should wait after the dial script has finished before deciding if
4379 carrier is available or not.
4385 will not check for carrier on the device, otherwise
4387 will not proceed to the login script until either carrier is detected
4390 has elapsed, at which point
4392 assumes that the device will not set carrier.
4394 If no arguments are given, carrier settings will go back to their default
4399 is followed immediately by an exclamation mark
4405 If carrier is not detected after
4407 seconds, the link will be disconnected.
4408 .It set choked Op Ar timeout
4409 This sets the number of seconds that
4411 will keep a choked output queue before dropping all pending output packets.
4414 is less than or equal to zero or if
4416 isn't specified, it is set to the default value of
4419 A choked output queue occurs when
4421 has read a certain number of packets from the local network for transmission,
4422 but cannot send the data due to link failure (the peer is busy etc.).
4424 will not read packets indefinitely.
4425 Instead, it reads up to
4431 packets in multi-link mode), then stops reading the network interface
4434 seconds have passed or at least one packet has been sent.
4438 seconds pass, all pending output packets are dropped.
4439 .It set ctsrts|crtscts on|off
4440 This sets hardware flow control.
4441 Hardware flow control is
4444 .It set deflate Ar out-winsize Op Ar in-winsize
4445 This sets the DEFLATE algorithms default outgoing and incoming window
4451 must be values between
4459 will insist that this window size is used and will not accept any other
4460 values from the peer.
4461 .It set dns Op Ar primary Op Ar secondary
4462 This command specifies DNS overrides for the
4467 command description above for details.
4468 This command does not affect the IP numbers requested using
4470 .It set device|line Xo
4473 This sets the device(s) to which
4475 will talk to the given
4478 All ISDN and serial device names are expected to begin with
4480 ISDN devices are usually called
4482 and serial devices are usually called
4489 it must either begin with an exclamation mark
4492 .No PPPoE: Ns Ar iface Ns Xo
4493 .Op \&: Ns Ar provider Ns
4497 enabled systems), or be of the format
4499 .Ar host : port Op /tcp|udp .
4502 If it begins with an exclamation mark, the rest of the device name is
4503 treated as a program name, and that program is executed when the device
4505 Standard input, output and error are fed back to
4507 and are read and written as if they were a regular device.
4510 .No PPPoE: Ns Ar iface Ns Xo
4511 .Op \&: Ns Ar provider Ns
4513 specification is given,
4515 will attempt to create a
4517 over Ethernet connection using the given
4525 will attempt to load it using
4527 If this fails, an external program must be used such as the
4529 program available under
4533 is passed as the service name in the PPPoE Discovery Initiation (PADI)
4535 If no provider is given, an empty value will be used.
4537 When a PPPoE connection is established,
4539 will place the name of the Access Concentrator in the environment variable
4546 for further details.
4549 .Ar host Ns No : Ns Ar port Ns Oo
4552 specification is given,
4554 will attempt to connect to the given
4562 suffix is not provided, the default is
4564 Refer to the section on
4565 .Em PPP OVER TCP and UDP
4566 above for further details.
4572 will attempt to open each one in turn until it succeeds or runs out of
4574 .It set dial Ar chat-script
4575 This specifies the chat script that will be used to dial the other
4582 and to the example configuration files for details of the chat script
4584 It is possible to specify some special
4586 in your chat script as follows:
4589 When used as the last character in a
4591 string, this indicates that a newline should not be appended.
4593 When the chat script encounters this sequence, it delays two seconds.
4595 When the chat script encounters this sequence, it delays for one quarter of
4598 This is replaced with a newline character.
4600 This is replaced with a carriage return character.
4602 This is replaced with a space character.
4604 This is replaced with a tab character.
4606 This is replaced by the current phone number (see
4610 This is replaced by the current
4616 This is replaced by the current
4623 Note that two parsers will examine these escape sequences, so in order to
4626 see the escape character, it is necessary to escape it from the
4627 .Sq command parser .
4628 This means that in practice you should use two escapes, for example:
4629 .Bd -literal -offset indent
4630 set dial "... ATDT\\\\T CONNECT"
4633 It is also possible to execute external commands from the chat script.
4634 To do this, the first character of the expect or send string is an
4637 If a literal exclamation mark is required, double it up to
4639 and it will be treated as a single literal
4641 When the command is executed, standard input and standard output are
4642 directed to the open device (see the
4644 command), and standard error is read by
4646 and substituted as the expect or send string.
4649 is running in interactive mode, file descriptor 3 is attached to
4652 For example (wrapped for readability):
4653 .Bd -literal -offset indent
4654 set login "TIMEOUT 5 \\"\\" \\"\\" login:--login: ppp \e
4655 word: ppp \\"!sh \\\\-c \\\\\\"echo \\\\-n label: >&2\\\\\\"\\" \e
4656 \\"!/bin/echo in\\" HELLO"
4659 would result in the following chat sequence (output using the
4660 .Sq set log local chat
4661 command before dialing):
4662 .Bd -literal -offset indent
4667 Chat: Expecting: login:--login:
4668 Chat: Wait for (5): login:
4670 Chat: Expecting: word:
4671 Chat: Wait for (5): word:
4673 Chat: Expecting: !sh \\-c "echo \\-n label: >&2"
4674 Chat: Exec: sh -c "echo -n label: >&2"
4675 Chat: Wait for (5): !sh \\-c "echo \\-n label: >&2" --> label:
4676 Chat: Exec: /bin/echo in
4678 Chat: Expecting: HELLO
4679 Chat: Wait for (5): HELLO
4683 Note (again) the use of the escape character, allowing many levels of
4685 Here, there are four parsers at work.
4686 The first parses the original line, reading it as three arguments.
4687 The second parses the third argument, reading it as 11 arguments.
4688 At this point, it is
4691 signs are escaped, otherwise this parser will see them as constituting
4692 an expect-send-expect sequence.
4695 character is seen, the execution parser reads the first command as three
4698 itself expands the argument after the
4700 As we wish to send the output back to the modem, in the first example
4701 we redirect our output to file descriptor 2 (stderr) so that
4703 itself sends and logs it, and in the second example, we just output to stdout,
4704 which is attached directly to the modem.
4706 This, of course means that it is possible to execute an entirely external
4708 command rather than using the internal one.
4711 for a good alternative.
4713 The external command that is executed is subjected to the same special
4714 word expansions as the
4717 .It set enddisc Op label|IP|MAC|magic|psn value
4718 This command sets our local endpoint discriminator.
4719 If set prior to LCP negotiation, and if no
4721 command has been used,
4723 will send the information to the peer using the LCP endpoint discriminator
4725 The following discriminators may be set:
4726 .Bl -tag -width indent
4728 The current label is used.
4730 Our local IP number is used.
4731 As LCP is negotiated prior to IPCP, it is
4732 possible that the IPCP layer will subsequently change this value.
4734 it does, the endpoint discriminator stays at the old value unless manually
4737 This is similar to the
4739 option above, except that the MAC address associated with the local IP
4741 If the local IP number is not resident on any Ethernet
4742 interface, the command will fail.
4744 As the local IP number defaults to whatever the machine host name is,
4746 is usually done prior to any
4750 A 20 digit random number is used.
4751 Care should be taken when using magic numbers as restarting
4753 or creating a link using a different
4755 invocation will also use a different magic number and will therefore not
4756 be recognised by the peer as belonging to the same bundle.
4757 This makes it unsuitable for
4765 should be set to an absolute public switched network number with the
4769 If no arguments are given, the endpoint discriminator is reset.
4770 .It set escape Ar value...
4771 This option is similar to the
4774 It allows the user to specify a set of characters that will be
4776 as they travel across the link.
4777 .It set filter dial|alive|in|out Ar rule-no Xo
4778 .No permit|deny|clear| Ns Ar rule-no
4781 .Ar src_addr Ns Op / Ns Ar width
4782 .Op Ar dst_addr Ns Op / Ns Ar width
4784 .Op src lt|eq|gt Ar port
4785 .Op dst lt|eq|gt Ar port
4789 .Op timeout Ar secs ]
4792 supports four filter sets.
4795 filter specifies packets that keep the connection alive - resetting the
4799 filter specifies packets that cause
4806 filter specifies packets that are allowed to travel
4807 into the machine and the
4809 filter specifies packets that are allowed out of the machine.
4811 Filtering is done prior to any IP alterations that might be done by the
4812 NAT engine on outgoing packets and after any IP alterations that might
4813 be done by the NAT engine on incoming packets.
4814 By default all empty filter sets allow all packets to pass.
4815 Rules are processed in order according to
4817 (unless skipped by specifying a rule number as the
4819 Up to 40 rules may be given for each set.
4820 If a packet doesn't match
4821 any of the rules in a given set, it is discarded.
4826 filters, this means that the packet is dropped.
4829 filters it means that the packet will not reset the idle timer (even if
4831 .Ar in Ns No / Ns Ar out
4834 value) and in the case of
4836 filters it means that the packet will not trigger a dial.
4837 A packet failing to trigger a dial will be dropped rather than queued.
4840 .Sx PACKET FILTERING
4841 above for further details.
4842 .It set hangup Ar chat-script
4843 This specifies the chat script that will be used to reset the device
4844 before it is closed.
4845 It should not normally be necessary, but can
4846 be used for devices that fail to reset themselves properly on close.
4847 .It set help|? Op Ar command
4848 This command gives a summary of available set commands, or if
4850 is specified, the command usage is shown.
4851 .It set ifaddr Oo Ar myaddr Ns
4853 .Oo Ar hisaddr Ns Op / Ns Ar \&nn
4858 This command specifies the IP addresses that will be used during
4860 Addresses are specified using the format
4866 is the preferred IP, but
4868 specifies how many bits of the address we will insist on.
4871 is omitted, it defaults to
4873 unless the IP address is 0.0.0.0 in which case it defaults to
4876 If you wish to assign a dynamic IP number to the peer,
4878 may also be specified as a range of IP numbers in the format
4879 .Bd -ragged -offset indent
4880 .Ar \&IP Ns Oo \&- Ns Ar \&IP Ns Xo
4881 .Oc Ns Oo , Ns Ar \&IP Ns
4882 .Op \&- Ns Ar \&IP Ns
4889 .Dl set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20
4893 as the local IP number, but may assign any of the given 10 IP
4894 numbers to the peer.
4895 If the peer requests one of these numbers,
4896 and that number is not already in use,
4898 will grant the peers request.
4899 This is useful if the peer wants
4900 to re-establish a link using the same IP number as was previously
4901 allocated (thus maintaining any existing tcp or udp connections).
4903 If the peer requests an IP number that's either outside
4904 of this range or is already in use,
4906 will suggest a random unused IP number from the range.
4910 is specified, it is used in place of
4912 in the initial IPCP negotiation.
4913 However, only an address in the
4915 range will be accepted.
4916 This is useful when negotiating with some
4918 implementations that will not assign an IP number unless their peer
4922 It should be noted that in
4926 will configure the interface immediately upon reading the
4928 line in the config file.
4929 In any other mode, these values are just
4930 used for IPCP negotiations, and the interface isn't configured
4931 until the IPCP layer is up.
4935 argument may be overridden by the third field in the
4937 file once the client has authenticated itself
4941 .Sx AUTHENTICATING INCOMING CONNECTIONS
4942 section for details.
4944 In all cases, if the interface is already configured,
4946 will try to maintain the interface IP numbers so that any existing
4947 bound sockets will remain valid.
4948 .It set ifqueue Ar packets
4949 Set the maximum number of packets that
4951 will read from the tunnel interface while data cannot be sent to any of
4952 the available links.
4953 This queue limit is necessary to flow control outgoing data as the tunnel
4954 interface is likely to be far faster than the combined links available to
4959 is set to a value less than the number of links,
4961 will read up to that value regardless.
4962 This prevents any possible latency problems.
4964 The default value for
4968 .It set ccpretry|ccpretries Oo Ar timeout
4969 .Op Ar reqtries Op Ar trmtries
4971 .It set chapretry|chapretries Oo Ar timeout
4974 .It set ipcpretry|ipcpretries Oo Ar timeout
4975 .Op Ar reqtries Op Ar trmtries
4977 .It set ipv6cpretry|ipv6cpretries Oo Ar timeout
4978 .Op Ar reqtries Op Ar trmtries
4980 .It set lcpretry|lcpretries Oo Ar timeout
4981 .Op Ar reqtries Op Ar trmtries
4983 .It set papretry|papretries Oo Ar timeout
4986 These commands set the number of seconds that
4988 will wait before resending Finite State Machine (FSM) Request packets.
4991 for all FSMs is 3 seconds (which should suffice in most cases).
4995 is specified, it tells
4997 how many configuration request attempts it should make while receiving
4998 no reply from the peer before giving up.
4999 The default is 5 attempts for
5000 CCP, LCP and IPCP and 3 attempts for PAP and CHAP.
5004 is specified, it tells
5006 how many terminate requests should be sent before giving up waiting for the
5008 The default is 3 attempts.
5009 Authentication protocols are
5010 not terminated and it is therefore invalid to specify
5014 In order to avoid negotiations with the peer that will never converge,
5016 will only send at most 3 times the configured number of
5018 in any given negotiation session before giving up and closing that layer.
5024 This command allows the adjustment of the current log level.
5025 Refer to the Logging Facility section for further details.
5026 .It set login Ar chat-script
5029 compliments the dial-script.
5030 If both are specified, the login
5031 script will be executed after the dial script.
5032 Escape sequences available in the dial script are also available here.
5033 .It set logout Ar chat-script
5034 This specifies the chat script that will be used to logout
5035 before the hangup script is called.
5036 It should not normally be necessary.
5037 .It set lqrperiod Ar frequency
5038 This command sets the
5045 The default is 30 seconds.
5046 You must also use the
5048 command if you wish to send LQR requests to the peer.
5049 .It set mode Ar interactive|auto|ddial|background
5050 This command allows you to change the
5052 of the specified link.
5053 This is normally only useful in multi-link mode,
5054 but may also be used in uni-link mode.
5056 It is not possible to change a link that is
5061 Note: If you issue the command
5063 and have network address translation enabled, it may be useful to
5064 .Dq enable iface-alias
5068 to do the necessary address translations to enable the process that
5069 triggers the connection to connect once the link is up despite the
5070 peer assigning us a new (dynamic) IP address.
5071 .It set mppe Op 40|56|128|* Op stateless|stateful|*
5072 This option selects the encryption parameters used when negotiation
5074 MPPE can be disabled entirely with the
5077 If no arguments are given,
5079 will attempt to negotiate a stateful link with a 128 bit key, but
5080 will agree to whatever the peer requests (including no encryption
5083 If any arguments are given,
5087 on using MPPE and will close the link if it's rejected by the peer (Note;
5088 this behaviour can be overridden by a configured RADIUS server).
5090 The first argument specifies the number of bits that
5092 should insist on during negotiations and the second specifies whether
5094 should insist on stateful or stateless mode.
5095 In stateless mode, the
5096 encryption dictionary is re-initialised with every packet according to
5097 an encryption key that is changed with every packet.
5099 the encryption dictionary is re-initialised every 256 packets or after
5100 the loss of any data and the key is changed every 256 packets.
5101 Stateless mode is less efficient but is better for unreliable transport
5103 .It set mrru Op Ar value
5104 Setting this option enables Multi-link PPP negotiations, also known as
5105 Multi-link Protocol or MP.
5106 There is no default MRRU (Maximum Reconstructed Receive Unit) value.
5107 If no argument is given, multi-link mode is disabled.
5112 The default MRU (Maximum Receive Unit) is 1500.
5113 If it is increased, the other side *may* increase its MTU.
5114 In theory there is no point in decreasing the MRU to below the default as the
5116 protocol says implementations *must* be able to accept packets of at
5123 will refuse to negotiate a higher value.
5124 The maximum MRU can be set to 2048 at most.
5125 Setting a maximum of less than 1500 violates the
5127 rfc, but may sometimes be necessary.
5130 imposes a maximum of 1492 due to hardware limitations.
5132 If no argument is given, 1500 is assumed.
5133 A value must be given when
5140 The default MTU is 1500.
5141 At negotiation time,
5143 will accept whatever MRU the peer requests (assuming it's
5144 not less than 296 bytes or greater than the assigned maximum).
5147 will not accept MRU values less than
5149 When negotiations are complete, the MTU is used when writing to the
5150 interface, even if the peer requested a higher value MRU.
5151 This can be useful for
5152 limiting your packet size (giving better bandwidth sharing at the expense
5153 of more header data).
5159 will refuse to negotiate a higher value.
5160 The maximum MTU can be set to 2048 at most.
5164 is given, 1500, or whatever the peer asks for is used.
5165 A value must be given when
5168 .It set nbns Op Ar x.x.x.x Op Ar y.y.y.y
5169 This option allows the setting of the Microsoft NetBIOS name server
5170 values to be returned at the peers request.
5171 If no values are given,
5173 will reject any such requests.
5174 .It set openmode active|passive Op Ar delay
5183 will always initiate LCP/IPCP/CCP negotiation one second after the line
5185 If you want to wait for the peer to initiate negotiations, you
5188 If you want to initiate negotiations immediately or after more than one
5189 second, the appropriate
5191 may be specified here in seconds.
5192 .It set parity odd|even|none|mark
5193 This allows the line parity to be set.
5194 The default value is
5196 .It set phone Ar telno Ns Xo
5197 .Oo \&| Ns Ar backupnumber
5198 .Oc Ns ... Ns Oo : Ns Ar nextnumber
5201 This allows the specification of the phone number to be used in
5202 place of the \\\\T string in the dial and login chat scripts.
5203 Multiple phone numbers may be given separated either by a pipe
5208 Numbers after the pipe are only dialed if the dial or login
5209 script for the previous number failed.
5211 Numbers after the colon are tried sequentially, irrespective of
5212 the reason the line was dropped.
5214 If multiple numbers are given,
5216 will dial them according to these rules until a connection is made, retrying
5217 the maximum number of times specified by
5222 mode, each number is attempted at most once.
5223 .It set Op proc Ns Xo
5224 .No title Op Ar value
5226 The current process title as displayed by
5228 is changed according to
5232 is not specified, the original process title is restored.
5234 word replacements done by the shell commands (see the
5236 command above) are done here too.
5238 Note, if USER is required in the process title, the
5240 command must appear in
5242 as it is not known when the commands in
5245 .It set radius Op Ar config-file
5246 This command enables RADIUS support (if it's compiled in).
5248 refers to the radius client configuration file as described in
5250 If PAP, CHAP, MSCHAP or MSCHAPv2 are
5251 .Dq enable Ns No d ,
5254 .Em \&N Ns No etwork
5257 and uses the configured RADIUS server to authenticate rather than
5258 authenticating from the
5260 file or from the passwd database.
5262 If none of PAP, CHAP, MSCHAP or MSCHAPv2 are enabled,
5267 uses the following attributes from the RADIUS reply:
5268 .Bl -tag -width XXX -offset XXX
5269 .It RAD_FRAMED_IP_ADDRESS
5270 The peer IP address is set to the given value.
5271 .It RAD_FRAMED_IP_NETMASK
5272 The tun interface netmask is set to the given value.
5274 If the given MTU is less than the peers MRU as agreed during LCP
5275 negotiation, *and* it is less that any configured MTU (see the
5277 command), the tun interface MTU is set to the given value.
5278 .It RAD_FRAMED_COMPRESSION
5279 If the received compression type is
5282 will request VJ compression during IPCP negotiations despite any
5284 configuration command.
5286 If this attribute is supplied,
5288 will attempt to use it as an additional label to load from the
5293 The load will be attempted before (and in addition to) the normal
5295 If the label doesn't exist, no action is taken and
5297 proceeds to the normal load using the current label.
5298 .It RAD_FRAMED_ROUTE
5299 The received string is expected to be in the format
5300 .Ar dest Ns Op / Ns Ar bits
5303 Any specified metrics are ignored.
5307 are understood as valid values for
5314 to sepcify the default route, and
5316 is understood to be the same as
5325 For example, a returned value of
5326 .Dq 1.2.3.4/24 0.0.0.0 1 2 -1 3 400
5327 would result in a routing table entry to the 1.2.3.0/24 network via
5329 and a returned value of
5333 would result in a default route to
5336 All RADIUS routes are applied after any sticky routes are applied, making
5337 RADIUS routes override configured routes.
5338 This also applies for RADIUS routes that don't {include} the
5344 .It RAD_SESSION_TIMEOUT
5345 If supplied, the client connection is closed after the given number of
5347 .It RAD_REPLY_MESSAGE
5348 If supplied, this message is passed back to the peer as the authentication
5350 .It RAD_MICROSOFT_MS_CHAP_ERROR
5352 .Dv RAD_VENDOR_MICROSOFT
5353 vendor specific attribute is supplied, it is passed back to the peer as the
5354 authentication FAILURE text.
5355 .It RAD_MICROSOFT_MS_CHAP2_SUCCESS
5357 .Dv RAD_VENDOR_MICROSOFT
5358 vendor specific attribute is supplied and if MS-CHAPv2 authentication is
5359 being used, it is passed back to the peer as the authentication SUCCESS text.
5360 .It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY
5362 .Dv RAD_VENDOR_MICROSOFT
5363 vendor specific attribute is supplied and has a value of 2 (Required),
5365 will insist that MPPE encryption is used (even if no
5367 configuration command has been given with arguments).
5368 If it is supplied with a value of 1 (Allowed), encryption is made optional
5371 configuration commands with arguments).
5372 .It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES
5374 .Dv RAD_VENDOR_MICROSOFT
5375 vendor specific attribute is supplied, bits 1 and 2 are examined.
5376 If either or both are set, 40 bit and/or 128 bit (respectively) encryption
5377 options are set, overriding any given first argument to the
5380 Note, it is not currently possible for the RADIUS server to specify 56 bit
5382 .It RAD_MICROSOFT_MS_MPPE_RECV_KEY
5384 .Dv RAD_VENDOR_MICROSOFT
5385 vendor specific attribute is supplied, it's value is used as the master
5386 key for decryption of incoming data. When clients are authenticated using
5387 MSCHAPv2, the RADIUS server MUST provide this attribute if inbound MPPE is
5389 .It RAD_MICROSOFT_MS_MPPE_SEND_KEY
5391 .Dv RAD_VENDOR_MICROSOFT
5392 vendor specific attribute is supplied, it's value is used as the master
5393 key for encryption of outgoing data. When clients are authenticated using
5394 MSCHAPv2, the RADIUS server MUST provide this attribute if outbound MPPE is
5398 Values received from the RADIUS server may be viewed using
5400 .It set reconnect Ar timeout ntries
5401 Should the line drop unexpectedly (due to loss of CD or LQR
5402 failure), a connection will be re-established after the given
5404 The line will be re-connected at most
5413 will result in a variable pause, somewhere between 1 and 30 seconds.
5414 .It set recvpipe Op Ar value
5415 This sets the routing table RECVPIPE value.
5416 The optimum value is just over twice the MTU value.
5419 is unspecified or zero, the default kernel controlled value is used.
5420 .It set redial Ar secs Ns Xo
5423 .Oc Ns Op . Ns Ar next
5427 can be instructed to attempt to redial
5430 If more than one phone number is specified (see
5434 is taken before dialing each number.
5437 is taken before starting at the first number again.
5440 may be used here in place of
5444 causing a random delay of between 1 and 30 seconds.
5448 is specified, its value is added onto
5454 will only be incremented at most
5462 delay will be effective, even after
5464 has been exceeded, so an immediate manual dial may appear to have
5466 If an immediate dial is required, a
5468 should immediately follow the
5473 description above for further details.
5474 .It set sendpipe Op Ar value
5475 This sets the routing table SENDPIPE value.
5476 The optimum value is just over twice the MTU value.
5479 is unspecified or zero, the default kernel controlled value is used.
5480 .It "set server|socket" Ar TcpPort Ns No \&| Ns Xo
5481 .Ar LocalName Ns No |none|open|closed
5482 .Op password Op Ar mask
5486 to listen on the given socket or
5488 for incoming command connections.
5494 to close any existing socket and clear the socket configuration.
5499 to attempt to re-open the port.
5504 to close the open port.
5506 If you wish to specify a local domain socket,
5508 must be specified as an absolute file name, otherwise it is assumed
5509 to be the name or number of a TCP port.
5510 You may specify the octal umask to be used with a local domain socket.
5516 for details of how to translate TCP port names.
5518 You must also specify the password that must be entered by the client
5521 variable above) when connecting to this socket.
5523 specified as an empty string, no password is required for connecting clients.
5525 When specifying a local domain socket, the first
5527 sequence found in the socket name will be replaced with the current
5528 interface unit number.
5529 This is useful when you wish to use the same
5530 profile for more than one connection.
5532 In a similar manner TCP sockets may be prefixed with the
5534 character, in which case the current interface unit number is added to
5539 with a server socket, the
5541 command is the preferred mechanism of communications.
5544 can also be used, but link encryption may be implemented in the future, so
5552 interact with the diagnostic socket.
5553 .It set speed Ar value
5554 This sets the speed of the serial device.
5555 If speed is specified as
5558 treats the device as a synchronous device.
5560 Certain device types will know whether they should be specified as
5561 synchronous or asynchronous.
5562 These devices will override incorrect
5563 settings and log a warning to this effect.
5564 .It set stopped Op Ar LCPseconds Op Ar CCPseconds
5565 If this option is set,
5567 will time out after the given FSM (Finite State Machine) has been in
5568 the stopped state for the given number of
5570 This option may be useful if the peer sends a terminate request,
5571 but never actually closes the connection despite our sending a terminate
5573 This is also useful if you wish to
5574 .Dq set openmode passive
5575 and time out if the peer doesn't send a Configure Request within the
5578 .Dq set log +lcp +ccp
5581 log the appropriate state transitions.
5583 The default value is zero, where
5585 doesn't time out in the stopped state.
5587 This value should not be set to less than the openmode delay (see
5590 .It set timeout Ar idleseconds Op Ar mintimeout
5591 This command allows the setting of the idle timer.
5592 Refer to the section titled
5593 .Sx SETTING THE IDLE TIMER
5594 for further details.
5600 will never idle out before the link has been up for at least that number
5608 This command controls the ports that
5610 prioritizes when transmitting data.
5611 The default priority TCP ports
5612 are ports 21 (ftp control), 22 (ssh), 23 (telnet), 513 (login), 514 (shell),
5613 543 (klogin) and 544 (kshell).
5614 There are no priority UDP ports by default.
5629 are given, the priority port lists are cleared (although if
5633 is specified, only that list is cleared).
5636 argument is prefixed with a plus
5640 the current list is adjusted, otherwise the list is reassigned.
5642 prefixed with a plus or not prefixed at all are added to the list and
5644 prefixed with a minus are removed from the list.
5648 is specified, all priority port lists are disabled and even
5650 packets are not prioritised.
5651 .It set vj slotcomp on|off
5654 whether it should attempt to negotiate VJ slot compression.
5655 By default, slot compression is turned
5657 .It set vj slots Ar nslots
5658 This command sets the initial number of slots that
5660 will try to negotiate with the peer when VJ compression is enabled (see the
5663 It defaults to a value of 16.
5672 .It shell|! Op Ar command
5675 is not specified a shell is invoked according to the
5677 environment variable.
5678 Otherwise, the given
5681 Word replacement is done in the same way as for the
5683 command as described above.
5685 Use of the ! character
5686 requires a following space as with any of the other commands.
5687 You should note that this command is executed in the foreground;
5689 will not continue running until this process has exited.
5692 command if you wish processing to happen in the background.
5694 This command allows the user to examine the following:
5697 Show the current bundle settings.
5699 Show the current CCP compression statistics.
5701 Show the current VJ compression statistics.
5703 Show the current escape characters.
5704 .It show filter Op Ar name
5705 List the current rules for the given filter.
5708 is not specified, all filters are shown.
5710 Show the current HDLC statistics.
5712 Give a summary of available show commands.
5714 Show the current interface information
5718 Show the current IPCP statistics.
5720 Show the protocol layers currently in use.
5722 Show the current LCP statistics.
5723 .It show Op data Ns Xo
5726 Show high level link information.
5728 Show a list of available logical links.
5730 Show the current log values.
5732 Show current memory statistics.
5734 Show the current NCP statistics.
5736 Show low level link information.
5738 Show Multi-link information.
5740 Show current protocol totals.
5742 Show the current routing tables.
5744 Show the current stopped timeouts.
5746 Show the active alarm timers.
5748 Show the current version number of
5753 Go into terminal mode.
5754 Characters typed at the keyboard are sent to the device.
5755 Characters read from the device are displayed on the screen.
5760 automatically enables Packet Mode and goes back into command mode.
5765 Read the example configuration files.
5766 They are a good source of information.
5775 to get online information about what's available.
5777 The following URLs contain useful information:
5778 .Bl -bullet -compact
5780 http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/faq/ppp.html
5782 http://www.FreeBSD.org/doc/handbook/userppp.html
5788 refers to four files:
5794 These files are placed in the
5798 .It Pa /etc/ppp/ppp.conf
5799 System default configuration file.
5800 .It Pa /etc/ppp/ppp.secret
5801 An authorisation file for each system.
5802 .It Pa /etc/ppp/ppp.linkup
5803 A file to check when
5805 establishes a network level connection.
5806 .It Pa /etc/ppp/ppp.linkdown
5807 A file to check when
5809 closes a network level connection.
5810 .It Pa /var/log/ppp.log
5811 Logging and debugging information file.
5812 Note, this name is specified in
5813 .Pa /etc/syslog.conf .
5816 for further details.
5817 .It Pa /var/spool/lock/LCK..*
5818 tty port locking file.
5821 for further details.
5822 .It Pa /var/run/tunN.pid
5823 The process id (pid) of the
5825 program connected to the tunN device, where
5827 is the number of the device.
5828 .It Pa /var/run/ttyXX.if
5829 The tun interface used by this port.
5830 Again, this file is only created in
5836 .It Pa /etc/services
5837 Get port number if port number is using service name.
5838 .It Pa /var/run/ppp-authname-class-value
5839 In multi-link mode, local domain sockets are created using the peer
5842 the peer endpoint discriminator class
5844 and the peer endpoint discriminator value
5846 As the endpoint discriminator value may be a binary value, it is turned
5847 to HEX to determine the actual file name.
5849 This socket is used to pass links between different instances of
5861 ifdef({LOCALNAT},{},{.Xr libalias 3 ,
5863 ifdef({LOCALRAD},{},{.Xr libradius 3 ,
5893 This program was originally written by
5894 .An Toshiharu OHNO Aq tony-o@iij.ad.jp ,
5895 and was submitted to
5898 .An Atsushi Murai Aq amurai@spec.co.jp .
5900 It was substantially modified during 1997 by
5901 .An Brian Somers Aq brian@Awfulhak.org ,
5904 in November that year
5905 (just after the 2.2 release).
5907 Most of the code was rewritten by
5909 in early 1998 when multi-link ppp support was added.
nant's projects / dragonfly.git / blob