2 .\" Copyright (c) 2001 Brian Somers <brian@Awfulhak.org>
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .Nd Point to Point Protocol (a.k.a. user-ppp)
42 This is a user process
47 is implemented as a part of the kernel (e.g., as managed by
49 and it is thus somewhat hard to debug and/or modify its behaviour.
50 However, in this implementation
52 is done as a user process with the help of the
53 tunnel device driver (tun).
57 flag does the equivalent of a
61 network address translation features.
64 to act as a NAT or masquerading engine for all machines on an internal
68 for details on the technical side of the NAT engine.
70 .Sx NETWORK ADDRESS TRANSLATION (PACKET ALIASING)
71 section of this manual page for details on how to configure NAT in
78 to be silent at startup rather than displaying the mode and interface
85 to only attempt to open
86 .Pa /dev/tun Ns Ar N .
89 will start with a value of 0 for
91 and keep trying to open a tunnel device by incrementing the value of
93 by one each time until it succeeds.
94 If it fails three times in a row
95 because the device file is missing, it gives up.
101 .Bl -tag -width XXX -offset XXX
104 opens the tun interface, configures it then goes into the background.
105 The link is not brought up until outgoing data is detected on the tun
106 interface at which point
108 attempts to bring up the link.
109 Packets received (including the first one) while
111 is trying to bring the link up will remain queued for a default of
121 must be given on the command line (see below) and a
123 must be done in the system profile that specifies a peer IP address to
124 use when configuring the interface.
127 is usually appropriate.
131 .Pa /usr/share/examples/ppp/ppp.conf.sample
136 attempts to establish a connection with the peer immediately.
139 goes into the background and the parent process returns an exit code
143 exits with a non-zero result.
147 attempts to establish a connection with the peer immediately, but never
149 The link is created in background mode.
150 This is useful if you wish to control
152 invocation from another process.
154 This is used for communicating over an already established connection,
155 usually when receiving incoming connections accepted by
160 line and uses descriptor 0 as the link.
162 will also ignore any configured chat scripts unless the
164 option has been enabled.
166 If callback is configured,
170 information when dialing back.
176 will behave slightly differently if descriptor 0 was created by
178 As pipes are not bi-directional, ppp will redirect all writes to descriptor
179 1 (standard output), leaving only reads acting on descriptor 0.
180 No special action is taken if descriptor 0 was created by
183 This option is designed for machines connected with a dedicated
186 will always keep the device open and will ignore any configured
187 chat scripts unless the
189 option has been enabled.
191 This mode is equivalent to
195 will bring the link back up any time it is dropped for any reason.
197 This is a no-op, and gives the same behaviour as if none of the above
198 modes have been specified.
200 loads any sections specified on the command line then provides an
204 One or more configuration entries or systems
206 .Pa /etc/ppp/ppp.conf )
207 may also be specified on the command line.
212 .Pa /etc/ppp/ppp.conf
213 at startup, followed by each of the systems specified on the command line.
216 .It Provides an interactive user interface.
217 Using its command mode, the user can
218 easily enter commands to establish the connection with the remote end, check
219 the status of connection and close the connection.
220 All functions can also be optionally password protected for security.
221 .It Supports both manual and automatic dialing.
222 Interactive mode has a
224 command which enables you to talk to the device directly.
225 When you are connected to the remote peer and it starts to talk
228 detects it and switches to packet mode automatically.
230 determined the proper sequence for connecting with the remote host, you
231 can write a chat script to {define} the necessary dialing and login
232 procedure for later convenience.
233 .It Supports on-demand dialup capability.
238 will act as a daemon and wait for a packet to be sent over the
241 When this happens, the daemon automatically dials and establishes the
243 In almost the same manner
245 mode (direct-dial mode) also automatically dials and establishes the
247 However, it differs in that it will dial the remote site
248 any time it detects the link is down, even if there are no packets to be
250 This mode is useful for full-time connections where we worry less
251 about line charges and more about being connected full time.
254 mode is also available.
255 This mode is targeted at a dedicated link between two machines.
257 will never voluntarily quit from dedicated mode - you must send it the
259 command via its diagnostic socket.
262 will force an LCP renegotiation, and a
264 will force it to exit.
265 .It Supports client callback.
267 can use either the standard LCP callback protocol or the Microsoft
268 CallBack Control Protocol (https://winprotocoldoc.blob.core.windows.net/productionwindowsarchives/MS-CBCP/[MS-CBCP].pdf).
269 .It Supports NAT or packet aliasing.
270 Packet aliasing (a.k.a.\& IP masquerading) allows computers on a
271 private, unregistered network to access the Internet.
274 host acts as a masquerading gateway.
275 IP addresses as well as TCP and
276 UDP port numbers are NAT'd for outgoing packets and de-NAT'd for
278 .It Supports background PPP connections.
279 In background mode, if
281 successfully establishes the connection, it will become a daemon.
282 Otherwise, it will exit with an error.
283 This allows the setup of
284 scripts that wish to execute certain commands only if the connection
285 is successfully established.
286 .It Supports server-side PPP connections.
289 acts as server which accepts incoming
291 connections on stdin/stdout.
292 .It Supports PAP and CHAP (rfc 1994, 2433 and 2759) authentication.
293 With PAP or CHAP, it is possible to skip the Unix style
295 procedure, and use the
297 protocol for authentication instead.
298 If the peer requests Microsoft CHAP authentication and
300 is compiled with DES support, an appropriate MD4/DES response will be
302 .It Supports RADIUS (rfc 2138 & 2548) authentication.
303 An extension to PAP and CHAP,
310 allows authentication information to be stored in a central or
311 distributed database along with various per-user framed connection
315 is available at compile time,
319 requests when configured to do so.
320 .It Supports Proxy Arp.
322 can be configured to make one or more proxy arp entries on behalf of
324 This allows routing from the peer to the LAN without
325 configuring each machine on that LAN.
326 .It Supports packet filtering.
327 User can {define} four kinds of filters: the
329 filter for incoming packets, the
331 filter for outgoing packets, the
333 filter to {define} a dialing trigger packet and the
335 filter for keeping a connection alive with the trigger packet.
336 .It Tunnel driver supports bpf.
339 to check the packet flow over the
342 .It Supports PPP over TCP and PPP over UDP.
343 If a device name is specified as
344 .Em host Ns No : Ns Em port Ns
349 will open a TCP or UDP connection for transporting data rather than using a
350 conventional serial device.
351 UDP connections force
353 into synchronous mode.
354 .It Supports PPP over Ethernet (rfc 2516).
357 is given a device specification of the format
358 .No PPPoE: Ns Ar iface Ns Xo
359 .Op \&: Ns Ar provider Ns
373 On systems that do not support
375 an external program such as
378 .It "Supports IETF draft Predictor-1 (rfc 1978) and DEFLATE (rfc 1979) compression."
380 supports not only VJ-compression but also Predictor-1 and DEFLATE compression.
381 Normally, a modem has built-in compression (e.g., v42.bis) and the system
382 may receive higher data rates from it as a result of such compression.
383 While this is generally a good thing in most other situations, this
384 higher speed data imposes a penalty on the system by increasing the
385 number of serial interrupts the system has to process in talking to the
386 modem and also increases latency.
387 Unlike VJ-compression, Predictor-1 and DEFLATE compression pre-compresses
389 network traffic flowing through the link, thus reducing overheads to a
391 .It Supports Microsoft's IPCP extensions (rfc 1877).
392 Name Server Addresses and NetBIOS Name Server Addresses can be negotiated
393 with clients using the Microsoft
395 stack (i.e., Win95, WinNT)
396 .It Supports Multi-link PPP (rfc 1990)
397 It is possible to configure
399 to open more than one physical connection to the peer, combining the
400 bandwidth of all links for better throughput.
401 .It Supports MPPE (draft-ietf-pppext-mppe)
402 MPPE is Microsoft Point to Point Encryption scheme.
403 It is possible to configure
405 to participate in Microsoft's Windows VPN.
408 can only get encryption keys from CHAP 81 authentication.
410 must be compiled with DES for MPPE to operate.
411 .It Supports IPV6CP (rfc 2023).
412 An IPv6 connection can be made in addition to or instead of the normal
425 will not run if the invoking user id is not zero.
426 This may be overridden by using the
429 .Pa /etc/ppp/ppp.conf .
430 When running as a normal user,
432 switches to user id 0 in order to alter the system routing table, set up
433 system lock files and read the ppp configuration files.
434 All external commands (executed via the "shell" or "!bg" commands) are executed
435 as the user id that invoked
439 logging facility if you are interested in what exactly is done as user id
444 you may need to deal with some initial configuration details.
447 Make sure that your system has a group named
451 file and that the group contains the names of all users expected to use
455 manual page for details.
456 Each of these users must also be given access using the
459 .Pa /etc/ppp/ppp.conf .
466 A common log file name is
467 .Pa /var/log/ppp.log .
468 To make output go to this file, put the following lines in the
471 .Bd -literal -offset indent
473 *.*<TAB>/var/log/ppp.log
476 It is possible to have more than one
478 log file by creating a link to the
486 .Bd -literal -offset indent
488 *.*<TAB>/var/log/ppp0.log
492 .Pa /etc/syslog.conf .
493 Do not forget to send a
498 .Pa /etc/syslog.conf .
500 Although not strictly relevant to
502 operation, you should configure your resolver so that it works correctly.
503 This can be done by configuring a local DNS resolver or by adding the correct
506 .Pa /etc/resolv.conf .
509 manual page for details.
511 Alternatively, if the peer supports it,
513 can be configured to ask the peer for the nameserver address(es) and to
521 commands below for details.
524 In the following examples, we assume that your machine name is
530 above) with no arguments, you are presented with a prompt:
531 .Bd -literal -offset indent
537 part of your prompt should always be in upper case.
538 If it is in lower case, it means that you must supply a password using the
541 This only ever happens if you connect to a running version of
543 and have not authenticated yourself using the correct password.
545 You can start by specifying the device name and speed:
546 .Bd -literal -offset indent
547 ppp ON awfulhak> set device /dev/cuau0
548 ppp ON awfulhak> set speed 38400
551 Normally, hardware flow control (CTS/RTS) is used.
553 certain circumstances (as may happen when you are connected directly
554 to certain PPP-capable terminal servers), this may result in
556 hanging as soon as it tries to write data to your communications link
557 as it is waiting for the CTS (clear to send) signal - which will never
559 Thus, if you have a direct line and cannot seem to make a
560 connection, try turning CTS/RTS off with
562 If you need to do this, check the
564 description below too - you will probably need to
565 .Dq set accmap 000a0000 .
567 Usually, parity is set to
572 Parity is a rather archaic error checking mechanism that is no
573 longer used because modern modems do their own error checking, and most
574 link-layer protocols (that is what
576 is) use much more reliable checking mechanisms.
577 Parity has a relatively
578 huge overhead (a 12.5% increase in traffic) and as a result, it is always
585 However, some ISPs (Internet Service Providers) may use
586 specific parity settings at connection time (before
589 Notably, Compuserve insist on even parity when logging in:
590 .Bd -literal -offset indent
591 ppp ON awfulhak> set parity even
594 You can now see what your current device settings look like:
595 .Bd -literal -offset indent
596 ppp ON awfulhak> show physical
600 Link Type: interactive
606 Device List: /dev/cuau0
607 Characteristics: 38400bps, cs8, even parity, CTS/RTS on
610 0 octets in, 0 octets out
615 The term command can now be used to talk directly to the device:
616 .Bd -literal -offset indent
617 ppp ON awfulhak> term
623 Password: myisppassword
627 When the peer starts to talk in
630 detects this automatically and returns to command mode.
631 .Bd -literal -offset indent
632 ppp ON awfulhak> # No link has been established
633 Ppp ON awfulhak> # We've connected & finished LCP
634 PPp ON awfulhak> # We've authenticated
635 PPP ON awfulhak> # We've agreed IP numbers
638 If it does not, it is probable that the peer is waiting for your end to
644 configuration packets to the peer, use the
646 command to drop out of terminal mode and enter packet mode.
648 If you never even receive a login prompt, it is quite likely that the
649 peer wants to use PAP or CHAP authentication instead of using Unix-style
650 login/password authentication.
651 To set things up properly, drop back to
652 the prompt and set your authentication name and key, then reconnect:
653 .Bd -literal -offset indent
655 ppp ON awfulhak> set authname myispusername
656 ppp ON awfulhak> set authkey myisppassword
657 ppp ON awfulhak> term
664 You may need to tell ppp to initiate negotiations with the peer here too:
665 .Bd -literal -offset indent
667 ppp ON awfulhak> # No link has been established
668 Ppp ON awfulhak> # We've connected & finished LCP
669 PPp ON awfulhak> # We've authenticated
670 PPP ON awfulhak> # We've agreed IP numbers
673 You are now connected!
676 in the prompt has changed to capital letters to indicate that you have
678 If only some of the three Ps go uppercase, wait until
679 either everything is uppercase or lowercase.
680 If they revert to lowercase, it means that
682 could not successfully negotiate with the peer.
683 A good first step for troubleshooting at this point would be to
684 .Bd -literal -offset indent
685 ppp ON awfulhak> set log local phase lcp ipcp
691 command description below for further details.
692 If things fail at this point,
693 it is quite important that you turn logging on and try again.
695 important that you note any prompt changes and report them to anyone trying
698 When the link is established, the show command can be used to see how
700 .Bd -literal -offset indent
701 PPP ON awfulhak> show physical
702 * Modem related information is shown here *
703 PPP ON awfulhak> show ccp
704 * CCP (compression) related information is shown here *
705 PPP ON awfulhak> show lcp
706 * LCP (line control) related information is shown here *
707 PPP ON awfulhak> show ipcp
708 * IPCP (IP) related information is shown here *
709 PPP ON awfulhak> show ipv6cp
710 * IPV6CP (IPv6) related information is shown here *
711 PPP ON awfulhak> show link
712 * Link (high level) related information is shown here *
713 PPP ON awfulhak> show bundle
714 * Logical (high level) connection related information is shown here *
717 At this point, your machine has a host route to the peer.
719 that you can only make a connection with the host on the other side
721 If you want to add a default route entry (telling your
722 machine to send all packets without another routing entry to the other
725 link), enter the following command:
726 .Bd -literal -offset indent
727 PPP ON awfulhak> add default HISADDR
732 represents the IP address of the connected peer.
735 command fails due to an existing route, you can overwrite the existing
737 .Bd -literal -offset indent
738 PPP ON awfulhak> add! default HISADDR
741 This command can also be executed before actually making the connection.
742 If a new IP address is negotiated at connection time,
744 will update your default route accordingly.
746 You can now use your network applications (ping, telnet, ftp, etc.)
747 in other windows or terminals on your machine.
748 If you wish to reuse the current terminal, you can put
750 into the background using your standard shell suspend and background
758 section for details on all available commands.
759 .Sh AUTOMATIC DIALING
760 To use automatic dialing, you must prepare some Dial and Login chat scripts.
761 See the example definitions in
762 .Pa /usr/share/examples/ppp/ppp.conf.sample
764 .Pa /etc/ppp/ppp.conf
766 Each line contains one comment, inclusion, label or command:
769 A line starting with a
771 character is treated as a comment line.
772 Leading whitespace are ignored when identifying comment lines.
774 An inclusion is a line beginning with the word
776 It must have one argument - the file to {include}.
778 .Dq {!include} ~/.ppp.conf
779 for compatibility with older versions of
782 A label name starts in the first column and is followed by
786 A command line must contain a space or tab in the first column.
788 A string starting with the
790 character is substituted with the value of the environment variable by
792 Likewise, a string starting with the
794 character is substituted with the full path to the home directory of
795 the user account by the same name, and the
797 character by itself is substituted with the full path to the home directory
799 If you want to include a literal
803 character in a command or argument, enclose them in double quotes, e.g.,
804 .Bd -literal -offset indent
805 set password "pa$ss~word"
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 is 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
1017 .Oo - Ns Ar max Ns Oc Oc Ns
1021 .Bl -tag -width attempts -compact
1023 is the number of seconds to wait before attempting
1025 If the argument is the literal string
1027 the delay period is a random value between 1 and 30 seconds inclusive.
1029 is the number of seconds that
1031 should be incremented each time a new dial attempt is made.
1032 The timeout reverts to
1034 only after a successful connection is established.
1035 The default value for
1039 is the maximum number of times
1043 The default value for
1047 is the number of seconds to wait before attempting
1048 to dial the next number in a list of numbers (see the
1051 The default is 3 seconds.
1052 Again, if the argument is the literal string
1054 the delay period is a random value between 1 and 30 seconds.
1056 is the maximum number of times to try to connect for each outgoing packet
1057 that triggers a dial.
1058 The previous value is unchanged if this parameter is omitted.
1059 If a value of zero is specified for
1062 will keep trying until a connection is made.
1066 .Bd -literal -offset indent
1070 will attempt to connect 4 times for each outgoing packet that causes
1071 a dial attempt with a 3 second delay between each number and a 10 second
1072 delay after all numbers have been tried.
1073 If multiple phone numbers
1074 are specified, the total number of attempts is still 4 (it does not
1075 attempt each number 4 times).
1078 .Bd -literal -offset indent
1079 set redial 10+10-5.3 20
1084 to attempt to connect 20 times.
1085 After the first attempt,
1087 pauses for 10 seconds.
1088 After the next attempt it pauses for 20 seconds
1089 and so on until after the sixth attempt it pauses for 1 minute.
1090 The next 14 pauses will also have a duration of one minute.
1093 connects, disconnects and fails to connect again, the timeout starts again
1096 Modifying the dial delay is very useful when running
1100 mode on both ends of the link.
1101 If each end has the same timeout,
1102 both ends wind up calling each other at the same time if the link
1103 drops and both ends have packets queued.
1104 At some locations, the serial link may not be reliable, and carrier
1105 may be lost at inappropriate times.
1106 It is possible to have
1108 redial should carrier be unexpectedly lost during a session.
1109 .Bd -literal -offset indent
1110 set reconnect timeout ntries
1115 to re-establish the connection
1117 times on loss of carrier with a pause of
1119 seconds before each try.
1121 .Bd -literal -offset indent
1127 that on an unexpected loss of carrier, it should wait
1129 seconds before attempting to reconnect.
1130 This may happen up to
1135 The default value of ntries is zero (no reconnect).
1136 Care should be taken with this option.
1137 If the local timeout is slightly
1138 longer than the remote timeout, the reconnect feature will always be
1139 triggered (up to the given number of times) after the remote side
1140 times out and hangs up.
1141 NOTE: In this context, losing too many LQRs constitutes a loss of
1142 carrier and will trigger a reconnect.
1145 flag is specified, all phone numbers are dialed at most once until
1146 a connection is made.
1147 The next number redial period specified with the
1149 command is honoured, as is the reconnect tries value.
1151 value is less than the number of phone numbers specified, not all
1152 the specified numbers will be tried.
1153 To terminate the program, type
1154 .Bd -literal -offset indent
1155 PPP ON awfulhak> close
1156 ppp ON awfulhak> quit all
1161 command will terminate the
1165 connection but not the
1173 .Sh RECEIVING INCOMING PPP CONNECTIONS (Method 1)
1174 To handle an incoming
1176 connection request, follow these steps:
1179 Make sure the modem and (optionally)
1181 is configured correctly.
1182 .Bl -bullet -compact
1184 Use Hardware Handshake (CTS/RTS) for flow control.
1186 Modem should be set to NO echo back (ATE0) and NO results string (ATQ1).
1193 on the port where the modem is attached.
1196 .Dl ttyd1 Qo /usr/libexec/getty std.38400 Qc dialup on secure
1198 Do not forget to send a
1202 process to start the
1207 It is usually also necessary to train your modem to the same DTR speed
1209 .Bd -literal -offset indent
1211 ppp ON awfulhak> set device /dev/cuau1
1212 ppp ON awfulhak> set speed 38400
1213 ppp ON awfulhak> term
1214 deflink: Entering terminal mode on /dev/cuau1
1225 ppp ON awfulhak> quit
1229 .Pa /usr/local/bin/ppplogin
1230 file with the following contents:
1231 .Bd -literal -offset indent
1233 exec /usr/sbin/ppp -direct incoming
1240 work with stdin and stdout.
1243 to connect to a configured diagnostic port, in the same manner as with
1249 section must be set up in
1250 .Pa /etc/ppp/ppp.conf .
1254 section contains the
1256 command as appropriate.
1258 Prepare an account for the incoming user.
1260 ppp:xxxx:66:66:PPP Login User:/home/ppp:/usr/local/bin/ppplogin
1263 Refer to the manual entries for
1269 Support for IPCP Domain Name Server and NetBIOS Name Server negotiation
1270 can be enabled using the
1275 Refer to their descriptions below.
1277 .Sh RECEIVING INCOMING PPP CONNECTIONS (Method 2)
1278 This method differs in that we use
1280 to authenticate the connection rather than
1284 Configure your default section in
1286 with automatic ppp recognition by specifying the
1291 :pp=/usr/local/bin/ppplogin:\\
1295 Configure your serial device(s), enable a
1298 .Pa /usr/local/bin/ppplogin
1299 as in the first three steps for method 1 above.
1307 .Pa /etc/ppp/ppp.conf
1310 label (or whatever label
1315 .Pa /etc/ppp/ppp.secret
1316 for each incoming user:
1325 detects a ppp connection (by recognising the HDLC frame headers), it runs
1326 .Dq /usr/local/bin/ppplogin .
1330 that either PAP or CHAP are enabled as above.
1331 If they are not, you are
1332 allowing anybody to establish a ppp session with your machine
1334 a password, opening yourself up to all sorts of potential attacks.
1335 .Sh AUTHENTICATING INCOMING CONNECTIONS
1336 Normally, the receiver of a connection requires that the peer
1337 authenticates itself.
1338 This may be done using
1340 but alternatively, you can use PAP or CHAP.
1341 CHAP is the more secure of the two, but some clients may not support it.
1342 Once you decide which you wish to use, add the command
1346 to the relevant section of
1349 You must then configure the
1350 .Pa /etc/ppp/ppp.secret
1352 This file contains one line per possible client, each line
1353 containing up to five fields:
1356 .Ar hisaddr Op Ar label Op Ar callback-number
1363 specify the client username and password.
1368 and PAP is being used,
1370 will look up the password database
1372 when authenticating.
1373 If the client does not offer a suitable response based on any
1374 .Ar name Ns No / Ns Ar key
1377 authentication fails.
1379 If authentication is successful,
1382 is used when negotiating IP numbers.
1385 command for details.
1387 If authentication is successful and
1389 is specified, the current system label is changed to match the given
1391 This will change the subsequent parsing of the
1397 If authentication is successful and
1403 the client will be called back on the given number.
1404 If CBCP is being used,
1406 may also contain a list of numbers or a
1411 The value will be used in
1413 subsequent CBCP phase.
1414 .Sh PPP OVER TCP and UDP (a.k.a Tunnelling)
1417 over a serial link, it is possible to
1418 use a TCP connection instead by specifying the host, port and protocol as the
1421 .Dl set device ui-gate:6669/tcp
1423 Instead of opening a serial device,
1425 will open a TCP connection to the given machine on the given
1427 It should be noted however that
1429 does not use the telnet protocol and will be unable to negotiate
1430 with a telnet server.
1431 You should set up a port for receiving this
1433 connection on the receiving machine (ui-gate).
1434 This is done by first updating
1436 to name the service:
1438 .Dl ppp-in 6669/tcp # Incoming PPP connections over TCP
1444 how to deal with incoming connections on that port:
1446 .Dl ppp-in stream tcp nowait root /usr/sbin/ppp ppp -direct ppp-in
1448 Do not forget to send a
1452 after you have updated
1453 .Pa /etc/inetd.conf .
1454 Here, we use a label named
1457 .Pa /etc/ppp/ppp.conf
1458 on ui-gate (the receiver) should contain the following:
1459 .Bd -literal -offset indent
1462 set ifaddr 10.0.4.1 10.0.4.2
1466 .Pa /etc/ppp/ppp.linkup
1468 .Bd -literal -offset indent
1470 add 10.0.1.0/24 HISADDR
1473 It is necessary to put the
1477 to ensure that the route is only added after
1479 has negotiated and assigned addresses to its interface.
1481 You may also want to enable PAP or CHAP for security.
1482 To enable PAP, add the following line:
1483 .Bd -literal -offset indent
1487 You will also need to create the following entry in
1488 .Pa /etc/ppp/ppp.secret :
1489 .Bd -literal -offset indent
1490 MyAuthName MyAuthPasswd
1497 the password is looked up in the
1502 .Pa /etc/ppp/ppp.conf
1503 on awfulhak (the initiator) should contain the following:
1504 .Bd -literal -offset indent
1507 set device ui-gate:ppp-in/tcp
1510 set log Phase Chat Connect hdlc LCP IPCP IPV6CP CCP tun
1511 set ifaddr 10.0.4.2 10.0.4.1
1514 with the route setup in
1515 .Pa /etc/ppp/ppp.linkup :
1516 .Bd -literal -offset indent
1518 add 10.0.2.0/24 HISADDR
1521 Again, if you are enabling PAP, you will also need this in the
1522 .Pa /etc/ppp/ppp.conf
1524 .Bd -literal -offset indent
1525 set authname MyAuthName
1526 set authkey MyAuthKey
1529 We are assigning the address of 10.0.4.1 to ui-gate, and the address
1530 10.0.4.2 to awfulhak.
1531 To open the connection, just type
1533 .Dl awfulhak # ppp -background ui-gate
1535 The result will be an additional "route" on awfulhak to the
1536 10.0.2.0/24 network via the TCP connection, and an additional
1537 "route" on ui-gate to the 10.0.1.0/24 network.
1538 The networks are effectively bridged - the underlying TCP
1539 connection may be across a public network (such as the
1542 traffic is conceptually encapsulated
1543 (although not packet by packet) inside the TCP stream between
1546 The major disadvantage of this mechanism is that there are two
1547 "guaranteed delivery" mechanisms in place - the underlying TCP
1548 stream and whatever protocol is used over the
1550 link - probably TCP again.
1551 If packets are lost, both levels will
1552 get in each others way trying to negotiate sending of the missing
1555 To avoid this overhead, it is also possible to do all this using
1556 UDP instead of TCP as the transport by simply changing the protocol
1557 from "tcp" to "udp".
1558 When using UDP as a transport,
1560 will operate in synchronous mode.
1561 This is another gain as the incoming
1562 data does not have to be rearranged into packets.
1564 Care should be taken when adding a default route through a tunneled
1566 It is quite common for the default route
1568 .Pa /etc/ppp/ppp.linkup )
1569 to end up routing the link's TCP connection through the tunnel,
1570 effectively garrotting the connection.
1571 To avoid this, make sure you add a static route for the benefit of
1573 .Bd -literal -offset indent
1576 set device ui-gate:ppp-in/tcp
1583 is the IP number that your route to
1587 When routing your connection across a public network such as the Internet,
1588 it is preferable to encrypt the data.
1589 This can be done with the help of the MPPE protocol, although currently this
1590 means that you will not be able to also compress the traffic as MPPE is
1591 implemented as a compression layer (thank Microsoft for this).
1592 To enable MPPE encryption, add the following lines to
1593 .Pa /etc/ppp/ppp.conf
1595 .Bd -literal -offset indent
1597 disable deflate pred1
1601 ensuring that you have put the requisite entry in
1602 .Pa /etc/ppp/ppp.secret
1603 (MSCHAPv2 is challenge based, so
1607 MSCHAPv2 and MPPE are accepted by default, so the client end should work
1608 without any additional changes (although ensure you have
1613 .Sh NETWORK ADDRESS TRANSLATION (PACKET ALIASING)
1616 command line option enables network address translation (a.k.a.\& packet
1620 host to act as a masquerading gateway for other computers over
1621 a local area network.
1622 Outgoing IP packets are NAT'd so that they appear to come from the
1624 host, and incoming packets are de-NAT'd so that they are routed
1625 to the correct machine on the local area network.
1626 NAT allows computers on private, unregistered subnets to have Internet
1627 access, although they are invisible from the outside world.
1630 operation should first be verified with network address translation disabled.
1633 option should be switched on, and network applications (web browser,
1638 should be checked on the
1641 Finally, the same or similar applications should be checked on other
1642 computers in the LAN.
1643 If network applications work correctly on the
1645 host, but not on other machines in the LAN, then the masquerading
1646 software is working properly, but the host is either not forwarding
1647 or possibly receiving IP packets.
1648 Check that IP forwarding is enabled in
1650 and that other machines have designated the
1652 host as the gateway for the LAN.
1655 with the provided rc script, the default is to
1661 .Pa /etc/defaults/rc.conf .
1662 .Sh PACKET FILTERING
1663 This implementation supports packet filtering.
1664 There are four kinds of
1674 Here are the basics:
1677 A filter definition has the following syntax:
1686 .Ar src_addr Ns Op / Ns Ar width
1687 .Op Ar dst_addr Ns Op / Ns Ar width
1689 .Ar [ proto Op src Ar cmp port
1694 .Op timeout Ar secs ]
1706 is a numeric value between
1710 specifying the rule number.
1711 Rules are specified in numeric order according to
1722 in which case, if a given packet matches the rule, the associated action
1723 is taken immediately.
1725 can also be specified as
1727 to clear the action associated with that particular rule, or as a new
1728 rule number greater than the current rule.
1729 In this case, if a given
1730 packet matches the current rule, the packet will next be matched against
1731 the new rule number (rather than the next rule number).
1735 may optionally be followed with an exclamation mark
1739 to reverse the sense of the following match.
1741 .Op Ar src_addr Ns Op / Ns Ar width
1743 .Op Ar dst_addr Ns Op / Ns Ar width
1744 are the source and destination IP number specifications.
1747 is specified, it gives the number of relevant netmask bits,
1748 allowing the specification of an address range.
1754 may be given the values
1760 (refer to the description of the
1762 command for a description of these values).
1763 When these values are used,
1764 the filters will be updated any time the values change.
1765 This is similar to the behaviour of the
1770 may be any protocol from
1779 meaning less-than, equal and greater-than respectively.
1781 can be specified as a numeric port or by service name from
1789 flags are only allowed when
1793 and represent the TH_ACK, TH_SYN and TH_FIN or TH_RST TCP flags respectively.
1795 The timeout value adjusts the current idle timeout to at least
1798 If a timeout is given in the alive filter as well as in the in/out
1799 filter, the in/out value is used.
1800 If no timeout is given, the default timeout (set using
1802 and defaulting to 180 seconds) is used.
1805 Each filter can hold up to 40 rules, starting from rule 0.
1806 The entire rule set is not effective until rule 0 is defined,
1807 i.e., the default is to allow everything through.
1809 If no rule in a defined set of rules matches a packet, that packet will
1810 be discarded (blocked).
1811 If there are no rules in a given filter, the packet will be permitted.
1813 It is possible to filter based on the payload of UDP frames where those
1819 .Ar filter-decapsulation
1820 option below for further details.
1823 .Dq set filter Ar name No -1
1828 .Pa /usr/share/examples/ppp/ppp.conf.sample .
1829 .Sh SETTING THE IDLE TIMER
1830 To check/set the idle timer, use the
1835 .Bd -literal -offset indent
1836 ppp ON awfulhak> set timeout 600
1839 The timeout period is measured in seconds, the default value for which
1842 To disable the idle timer function, use the command
1843 .Bd -literal -offset indent
1844 ppp ON awfulhak> set timeout 0
1851 modes, the idle timeout is ignored.
1854 mode, when the idle timeout causes the
1859 program itself remains running.
1860 Another trigger packet will cause it to attempt to re-establish the link.
1861 .Sh PREDICTOR-1 and DEFLATE COMPRESSION
1863 supports both Predictor type 1 and deflate compression.
1866 will attempt to use (or be willing to accept) both compression protocols
1867 when the peer agrees
1869 The deflate protocol is preferred by
1875 commands if you wish to disable this functionality.
1877 It is possible to use a different compression algorithm in each direction
1878 by using only one of
1882 (assuming that the peer supports both algorithms).
1884 By default, when negotiating DEFLATE,
1886 will use a window size of 15.
1889 command if you wish to change this behaviour.
1891 A special algorithm called DEFLATE24 is also available, and is disabled
1892 and denied by default.
1893 This is exactly the same as DEFLATE except that
1894 it uses CCP ID 24 to negotiate.
1897 to successfully negotiate DEFLATE with
1900 .Sh CONTROLLING IP ADDRESS
1903 uses IPCP to negotiate IP addresses.
1904 Each side of the connection
1905 specifies the IP address that it is willing to use, and if the requested
1906 IP address is acceptable then
1908 returns an ACK to the requester.
1911 returns NAK to suggest that the peer use a different IP address.
1913 both sides of the connection agree to accept the received request (and
1914 send an ACK), IPCP is set to the open state and a network level connection
1916 To control this IPCP behaviour, this implementation has the
1918 command for defining the local and remote IP address:
1919 .Bd -ragged -offset indent
1920 .No set ifaddr Oo Ar src_addr Ns
1922 .Oo Ar dst_addr Ns Op / Ns Ar \&nn
1932 is the IP address that the local side is willing to use,
1934 is the IP address which the remote side should use and
1936 is the netmask that should be used.
1938 defaults to the current
1941 defaults to 0.0.0.0, and
1943 defaults to whatever mask is appropriate for
1945 It is only possible to make
1947 smaller than the default.
1948 The usual value is 255.255.255.255, as
1949 most kernels ignore the netmask of a POINTOPOINT interface.
1953 implementations require that the peer negotiates a specific IP
1956 If this is the case,
1958 may be used to specify this IP number.
1959 This will not affect the
1960 routing table unless the other side agrees with this proposed number.
1961 .Bd -literal -offset indent
1962 set ifaddr 192.244.177.38 192.244.177.2 255.255.255.255 0.0.0.0
1965 The above specification means:
1967 .Bl -bullet -compact
1969 I will first suggest that my IP address should be 0.0.0.0, but I
1970 will only accept an address of 192.244.177.38.
1972 I strongly insist that the peer uses 192.244.177.2 as his own
1973 address and will not permit the use of any IP address but 192.244.177.2.
1974 When the peer requests another IP address, I will always suggest that
1975 it uses 192.244.177.2.
1977 The routing table entry will have a netmask of 0xffffffff.
1980 This is all fine when each side has a pre-determined IP address, however
1981 it is often the case that one side is acting as a server which controls
1982 all IP addresses and the other side should go along with it.
1983 In order to allow more flexible behaviour, the
1985 command allows the user to specify IP addresses more loosely:
1987 .Dl set ifaddr 192.244.177.38/24 192.244.177.2/20
1989 A number followed by a slash
1991 represents the number of bits significant in the IP address.
1992 The above example means:
1994 .Bl -bullet -compact
1996 I would like to use 192.244.177.38 as my address if it is possible, but I will
1997 also accept any IP address between 192.244.177.0 and 192.244.177.255.
1999 I would like to make him use 192.244.177.2 as his own address, but I will also
2000 permit him to use any IP address between 192.244.176.0 and
2003 As you may have already noticed, 192.244.177.2 is equivalent to saying
2006 As an exception, 0 is equivalent to 0.0.0.0/0, meaning that I have no
2007 preferred IP address and will obey the remote peers selection.
2008 When using zero, no routing table entries will be made until a connection
2011 192.244.177.2/0 means that I will accept/permit any IP address but I will
2012 suggest that 192.244.177.2 be used first.
2015 When negotiating IPv6 addresses, no control is given to the user.
2016 IPV6CP negotiation is fully automatic.
2017 .Sh CONNECTING WITH YOUR INTERNET SERVICE PROVIDER
2018 The following steps should be taken when connecting to your ISP:
2021 Describe your providers phone number(s) in the dial script using the
2024 This command allows you to set multiple phone numbers for
2025 dialing and redialing separated by either a pipe
2029 .Bd -ragged -offset indent
2030 .No set phone Ar telno Ns
2031 .Oo \&| Ns Ar backupnumber Oc Ns ... Ns Oo : Ns Ar nextnumber Oc Ns ...
2034 Numbers after the first in a pipe-separated list are only used if the
2035 previous number was used in a failed dial or login script.
2037 separated by a colon are used sequentially, irrespective of what happened
2038 as a result of using the previous number.
2040 .Bd -literal -offset indent
2041 set phone "1234567|2345678:3456789|4567890"
2044 Here, the 1234567 number is attempted.
2045 If the dial or login script fails,
2046 the 2345678 number is used next time, but *only* if the dial or login script
2048 On the dial after this, the 3456789 number is used.
2050 number is only used if the dial or login script using the 3456789 fails.
2051 If the login script of the 2345678 number fails, the next number is still the
2053 As many pipes and colons can be used as are necessary
2054 (although a given site would usually prefer to use either the pipe or the
2055 colon, but not both).
2056 The next number redial timeout is used between all numbers.
2057 When the end of the list is reached, the normal redial period is
2058 used before starting at the beginning again.
2059 The selected phone number is substituted for the \\\\T string in the
2061 command (see below).
2063 Set up your redial requirements using
2065 For example, if you have a bad telephone line or your provider is
2066 usually engaged (not so common these days), you may want to specify
2068 .Bd -literal -offset indent
2072 This says that up to 4 phone calls should be attempted with a pause of 10
2073 seconds before dialing the first number again.
2075 Describe your login procedure using the
2082 command is used to talk to your modem and establish a link with your
2084 .Bd -literal -offset indent
2085 set dial "ABORT BUSY ABORT NO\\\\sCARRIER TIMEOUT 4 \\"\\" \e
2086 ATZ OK-ATZ-OK ATDT\\\\T TIMEOUT 60 CONNECT"
2089 This modem "chat" string means:
2092 Abort if the string "BUSY" or "NO CARRIER" are received.
2094 Set the timeout to 4 seconds.
2101 If that is not received within the 4 second timeout, send ATZ
2104 Send ATDTxxxxxxx where xxxxxxx is the next number in the phone list from
2107 Set the timeout to 60.
2109 Wait for the CONNECT string.
2112 Once the connection is established, the login script is executed.
2113 This script is written in the same style as the dial script, but care should
2114 be taken to avoid having your password logged:
2115 .Bd -literal -offset indent
2116 set authkey MySecret
2117 set login "TIMEOUT 15 login:-\\\\r-login: awfulhak \e
2118 word: \\\\P ocol: PPP HELLO"
2121 This login "chat" string means:
2124 Set the timeout to 15 seconds.
2127 If it is not received, send a carriage return and expect
2132 Expect "word:" (the tail end of a "Password:" prompt).
2134 Send whatever our current
2138 Expect "ocol:" (the tail end of a "Protocol:" prompt).
2147 command is logged specially.
2152 logging is enabled, the actual password is not logged;
2156 Login scripts vary greatly between ISPs.
2157 If you are setting one up for the first time,
2158 .Em ENABLE CHAT LOGGING
2159 so that you can see if your script is behaving as you expect.
2165 to specify your serial line and speed, for example:
2166 .Bd -literal -offset indent
2167 set device /dev/cuau0
2171 Cuad0 is the first serial port on
2178 A speed of 115200 should be specified
2179 if you have a modem capable of bit rates of 28800 or more.
2180 In general, the serial speed should be about four times the modem speed.
2184 command to {define} the IP address.
2187 If you know what IP address your provider uses, then use it as the remote
2188 address (dst_addr), otherwise choose something like 10.0.0.2/0 (see below).
2190 If your provider has assigned a particular IP address to you, then use
2191 it as your address (src_addr).
2193 If your provider assigns your address dynamically, choose a suitably
2194 unobtrusive and unspecific IP number as your address.
2195 10.0.0.1/0 would be appropriate.
2196 The bit after the / specifies how many bits of the
2197 address you consider to be important, so if you wanted to insist on
2198 something in the class C network 1.2.3.0, you could specify 1.2.3.1/24.
2200 If you find that your ISP accepts the first IP number that you suggest,
2201 specify third and forth arguments of
2203 This will force your ISP to assign a number.
2204 (The third argument will
2205 be ignored as it is less restrictive than the default mask for your
2209 An example for a connection where you do not know your IP number or your
2210 ISPs IP number would be:
2211 .Bd -literal -offset indent
2212 set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0
2215 In most cases, your ISP will also be your default router.
2216 If this is the case, add the line
2217 .Bd -literal -offset indent
2222 .Pa /etc/ppp/ppp.conf
2224 .Pa /etc/ppp/ppp.linkup
2225 for setups that do not use
2231 to add a default route to whatever the peer address is
2232 (10.0.0.2 in this example).
2235 meaning that should the value of
2237 change, the route will be updated accordingly.
2239 If your provider requests that you use PAP/CHAP authentication methods, add
2240 the next lines to your
2241 .Pa /etc/ppp/ppp.conf
2243 .Bd -literal -offset indent
2245 set authkey MyPassword
2248 Both are accepted by default, so
2250 will provide whatever your ISP requires.
2252 It should be noted that a login script is rarely (if ever) required
2253 when PAP or CHAP are in use.
2255 Ask your ISP to authenticate your nameserver address(es) with the line
2256 .Bd -literal -offset indent
2262 do this if you are running a local DNS unless you also either use
2267 .Pa /etc/ppp/ppp.linkdown ,
2270 will simply circumvent its use by entering some nameserver lines in
2271 .Pa /etc/resolv.conf .
2275 .Pa /usr/share/examples/ppp/ppp.conf.sample
2277 .Pa /usr/share/examples/ppp/ppp.linkup.sample
2278 for some real examples.
2279 The pmdemand label should be appropriate for most ISPs.
2280 .Sh LOGGING FACILITY
2282 is able to generate the following log info either via
2284 or directly to the screen:
2286 .Bl -tag -width XXXXXXXXX -offset XXX -compact
2288 Enable all logging facilities.
2289 This generates a lot of log.
2290 The most common use of 'all' is as a basis, where you remove some facilities
2291 after enabling 'all' ('debug' and 'timer' are usually best disabled.)
2293 Dump async level packet in hex.
2295 Generate CBCP (CallBack Control Protocol) logs.
2297 Generate a CCP packet trace.
2305 chat script trace logs.
2307 Log commands executed either from the command line or any of the configuration
2310 Log Chat lines containing the string "CONNECT".
2312 Log debug information.
2314 Log DNS QUERY packets.
2316 Log packets permitted by the dial filter and denied by any filter.
2318 Dump HDLC packet in hex.
2320 Log all function calls specifically made as user id 0.
2322 Generate an IPCP packet trace.
2324 Generate an LCP packet trace.
2326 Generate LQR reports.
2328 Phase transition log output.
2330 Dump physical level packet in hex.
2332 Dump RADIUS information.
2333 RADIUS information resulting from the link coming up or down is logged at
2338 This log level is most useful for monitoring RADIUS alive information.
2340 Dump sync level packet in hex.
2342 Dump all TCP/IP packets.
2344 Log timer manipulation.
2346 Include the tun device on each log line.
2348 Output to the terminal device.
2349 If there is currently no terminal,
2350 output is sent to the log file using syslogs
2353 Output to both the terminal device
2354 and the log file using syslogs
2357 Output to the log file using
2363 command allows you to set the logging output level.
2364 Multiple levels can be specified on a single command line.
2365 The default is equivalent to
2368 It is also possible to log directly to the screen.
2369 The syntax is the same except that the word
2371 should immediately follow
2375 (i.e., only the un-maskable warning, error and alert output).
2377 If The first argument to
2378 .Dq set log Op local
2383 character, the current log levels are
2384 not cleared, for example:
2385 .Bd -literal -offset indent
2386 PPP ON awfulhak> set log phase
2387 PPP ON awfulhak> show log
2388 Log: Phase Warning Error Alert
2389 Local: Warning Error Alert
2390 PPP ON awfulhak> set log +tcp/ip -warning
2391 PPP ON awfulhak> set log local +command
2392 PPP ON awfulhak> show log
2393 Log: Phase TCP/IP Warning Error Alert
2394 Local: Command Warning Error Alert
2397 Log messages of level Warning, Error and Alert are not controllable
2399 .Dq set log Op local .
2403 level is special in that it will not be logged if it can be displayed
2407 deals with the following signals:
2408 .Bl -tag -width "USR2"
2410 Receipt of this signal causes the termination of the current connection
2414 to exit unless it is in
2419 .It HUP, TERM & QUIT
2426 to re-open any existing server socket, dropping all existing diagnostic
2428 Sockets that could not previously be opened will be retried.
2432 to close any existing server socket, dropping all existing diagnostic
2435 can still be used to re-open the socket.
2438 If you wish to use more than one physical link to connect to a
2440 peer, that peer must also understand the
2443 Refer to RFC 1990 for specification details.
2445 The peer is identified using a combination of his
2446 .Dq endpoint discriminator
2448 .Dq authentication id .
2449 Either or both of these may be specified.
2450 It is recommended that
2451 at least one is specified, otherwise there is no way of ensuring that
2452 all links are actually connected to the same peer program, and some
2453 confusing lock-ups may result.
2454 Locally, these identification variables are specified using the
2463 must be agreed in advance with the peer.
2465 Multi-link capabilities are enabled using the
2467 command (set maximum reconstructed receive unit).
2468 Once multi-link is enabled,
2470 will attempt to negotiate a multi-link connection with the peer.
2472 By default, only one
2477 To create more links, the
2480 This command will clone existing links, where all
2481 characteristics are the same except:
2484 The new link has its own name as specified on the
2491 Its mode may subsequently be changed using the
2495 The new link is in a
2500 A summary of all available links can be seen using the
2504 Once a new link has been created, command usage varies.
2505 All link specific commands must be prefixed with the
2507 command, specifying on which link the command is to be applied.
2508 When only a single link is available,
2510 is smart enough not to require the
2514 Some commands can still be used without specifying a link - resulting
2515 in an operation at the
2518 For example, once two or more links are available, the command
2520 will show CCP configuration and statistics at the multi-link level, and
2521 .Dq link deflink show ccp
2522 will show the same information at the
2526 Armed with this information, the following configuration might be used:
2527 .Bd -literal -offset indent
2531 set device /dev/cuau0 /dev/cuau1 /dev/cuau2
2532 set phone "123456789"
2533 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \\"\\" ATZ \e
2534 OK-AT-OK \\\\dATDT\\\\T TIMEOUT 45 CONNECT"
2536 set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0
2538 set authkey ppppassword
2541 clone 1,2,3 # Create 3 new links - duplicates of the default
2542 link deflink remove # Delete the default link (called ``deflink'')
2545 Note how all cloning is done at the end of the configuration.
2546 Usually, the link will be configured first, then cloned.
2547 If you wish all links
2548 to be up all the time, you can add the following line to the end of your
2550 .Bd -literal -offset indent
2551 link 1,2,3 set mode ddial
2554 If you want the links to dial on demand, this command could be used:
2555 .Bd -literal -offset indent
2556 link * set mode auto
2559 Links may be tied to specific names by removing the
2561 line above, and specifying the following after the
2564 .Bd -literal -offset indent
2565 link 1 set device /dev/cuau0
2566 link 2 set device /dev/cuau1
2567 link 3 set device /dev/cuau2
2572 command to see which commands require context (using the
2574 command), which have optional
2575 context and which should not have any context.
2581 mode with the peer, it creates a local domain socket in the
2584 This socket is used to pass link information (including
2585 the actual link file descriptor) between different
2590 ability to be run from a
2596 capability), without needing to have initial control of the serial
2600 negotiates multi-link mode, it will pass its open link to any
2601 already running process.
2602 If there is no already running process,
2604 will act as the master, creating the socket and listening for new
2606 .Sh PPP COMMAND LIST
2607 This section lists the available commands and their effect.
2608 They are usable either from an interactive
2610 session, from a configuration file or from a
2616 .It accept|deny|enable|disable Ar option....
2617 These directives tell
2619 how to negotiate the initial connection with the peer.
2622 has a default of either accept or deny and enable or disable.
2624 means that the option will be ACK'd if the peer asks for it.
2626 means that the option will be NAK'd if the peer asks for it.
2628 means that the option will be requested by us.
2630 means that the option will not be requested by us.
2633 may be one of the following:
2636 Default: Enabled and Accepted.
2637 ACFComp stands for Address and Control Field Compression.
2638 Non LCP packets will usually have an address
2639 field of 0xff (the All-Stations address) and a control field of
2640 0x03 (the Unnumbered Information command).
2642 negotiated, these two bytes are simply not sent, thus minimising
2649 Default: Disabled and Accepted.
2650 CHAP stands for Challenge Handshake Authentication Protocol.
2651 Only one of CHAP and PAP (below) may be negotiated.
2652 With CHAP, the authenticator sends a "challenge" message to its peer.
2653 The peer uses a one-way hash function to encrypt the
2654 challenge and sends the result back.
2655 The authenticator does the same, and compares the results.
2656 The advantage of this mechanism is that no
2657 passwords are sent across the connection.
2658 A challenge is made when the connection is first made.
2659 Subsequent challenges may occur.
2660 If you want to have your peer authenticate itself, you must
2663 .Pa /etc/ppp/ppp.conf ,
2664 and have an entry in
2665 .Pa /etc/ppp/ppp.secret
2668 When using CHAP as the client, you need only specify
2673 .Pa /etc/ppp/ppp.conf .
2674 CHAP is accepted by default.
2677 implementations use "MS-CHAP" rather than MD5 when encrypting the
2679 MS-CHAP is a combination of MD4 and DES.
2682 was built on a machine with DES libraries available, it will respond
2683 to MS-CHAP authentication requests, but will never request them.
2685 Default: Enabled and Accepted.
2686 This option decides if deflate
2687 compression will be used by the Compression Control Protocol (CCP).
2688 This is the same algorithm as used by the
2691 Note: There is a problem negotiating
2697 implementation available under many operating systems.
2699 (version 2.3.1) incorrectly attempts to negotiate
2701 compression using type
2703 as the CCP configuration type rather than type
2709 is actually specified as
2710 .Dq PPP Magna-link Variable Resource Compression
2714 is capable of negotiating with
2721 .Ar accept Ns No ed .
2723 Default: Disabled and Denied.
2724 This is a variance of the
2726 option, allowing negotiation with the
2731 section above for details.
2732 It is disabled by default as it violates
2735 Default: Disabled and Denied.
2736 This option allows DNS negotiation.
2741 will request that the peer confirms the entries in
2742 .Pa /etc/resolv.conf .
2743 If the peer NAKs our request (suggesting new IP numbers),
2744 .Pa /etc/resolv.conf
2745 is updated and another request is sent to confirm the new entries.
2748 .Dq accept Ns No ed,
2750 will answer any DNS queries requested by the peer rather than rejecting
2752 The answer is taken from
2753 .Pa /etc/resolv.conf
2756 command is used as an override.
2758 Default: Enabled and Accepted.
2759 This option allows control over whether we
2760 negotiate an endpoint discriminator.
2761 We only send our discriminator if
2766 We reject the peers discriminator if
2770 Default: Disabled and Accepted.
2771 The use of this authentication protocol
2772 is discouraged as it partially violates the authentication protocol by
2773 implementing two different mechanisms (LANMan & NT) under the guise of
2774 a single CHAP type (0x80).
2776 uses a simple DES encryption mechanism and is the least secure of the
2777 CHAP alternatives (although is still more secure than PAP).
2781 description below for more details.
2783 Default: Disabled and Accepted.
2784 This option decides if Link Quality Requests will be sent or accepted.
2785 LQR is a protocol that allows
2787 to determine that the link is down without relying on the modems
2789 When LQR is enabled,
2795 below) as part of the LCP request.
2796 If the peer agrees, both sides will
2797 exchange LQR packets at the agreed frequency, allowing detailed link
2798 quality monitoring by enabling LQM logging.
2799 If the peer does not agree, and if the
2806 These packets pass no information of interest, but they
2808 be replied to by the peer.
2815 will abruptly drop the connection if 5 unacknowledged packets have been
2816 sent rather than sending a 6th.
2817 A message is logged at the
2819 level, and any appropriate
2821 values are honoured as if the peer were responsible for dropping the
2826 command description for differences in behaviour prior to
2830 Default: Enabled and Accepted.
2831 This is Microsoft Point to Point Encryption scheme.
2832 MPPE key size can be
2833 40-, 56- and 128-bits.
2838 Default: Disabled and Accepted.
2839 It is very similar to standard CHAP (type 0x05)
2840 except that it issues challenges of a fixed 16 bytes in length and uses a
2841 combination of MD4, SHA-1 and DES to encrypt the challenge rather than using the
2842 standard MD5 mechanism.
2844 Default: Disabled and Accepted.
2845 The use of this authentication protocol
2846 is discouraged as it partially violates the authentication protocol by
2847 implementing two different mechanisms (LANMan & NT) under the guise of
2848 a single CHAP type (0x80).
2849 It is very similar to standard CHAP (type 0x05)
2850 except that it issues challenges of a fixed 8 bytes in length and uses a
2851 combination of MD4 and DES to encrypt the challenge rather than using the
2852 standard MD5 mechanism.
2853 CHAP type 0x80 for LANMan is also supported - see
2861 use CHAP type 0x80, when acting as authenticator with both
2862 .Dq enable Ns No d ,
2864 will rechallenge the peer up to three times if it responds using the wrong
2865 one of the two protocols.
2866 This gives the peer a chance to attempt using both protocols.
2870 acts as the authenticatee with both protocols
2871 .Dq accept Ns No ed ,
2872 the protocols are used alternately in response to challenges.
2874 Note: If only LANMan is enabled,
2876 (version 2.3.5) misbehaves when acting as authenticatee.
2878 the NT and the LANMan answers, but also suggests that only the NT answer
2881 Default: Disabled and Accepted.
2882 PAP stands for Password Authentication Protocol.
2883 Only one of PAP and CHAP (above) may be negotiated.
2884 With PAP, the ID and Password are sent repeatedly to the peer until
2885 authentication is acknowledged or the connection is terminated.
2886 This is a rather poor security mechanism.
2887 It is only performed when the connection is first established.
2888 If you want to have your peer authenticate itself, you must
2891 .Pa /etc/ppp/ppp.conf ,
2892 and have an entry in
2893 .Pa /etc/ppp/ppp.secret
2894 for the peer (although see the
2900 When using PAP as the client, you need only specify
2905 .Pa /etc/ppp/ppp.conf .
2906 PAP is accepted by default.
2908 Default: Enabled and Accepted.
2909 This option decides if Predictor 1
2910 compression will be used by the Compression Control Protocol (CCP).
2912 Default: Enabled and Accepted.
2913 This option is used to negotiate
2914 PFC (Protocol Field Compression), a mechanism where the protocol
2915 field number is reduced to one octet rather than two.
2917 Default: Enabled and Accepted.
2918 This option determines if
2920 will request and accept requests for short
2922 sequence numbers when negotiating multi-link mode.
2923 This is only applicable if our MRRU is set (thus enabling multi-link).
2925 Default: Enabled and Accepted.
2926 This option determines if Van Jacobson header compression will be used.
2929 The following options are not actually negotiated with the peer.
2930 Therefore, accepting or denying them makes no sense.
2934 When this option is enabled,
2938 requests to the peer at the frequency defined by
2942 requests will supersede
2944 requests if enabled and negotiated.
2953 was considered enabled if lqr was enabled and negotiated, otherwise it was
2954 considered disabled.
2955 For the same behaviour, it is now necessary to
2959 .It filter-decapsulation
2961 When this option is enabled,
2963 will examine UDP frames to see if they actually contain a
2965 frame as their payload.
2966 If this is the case, all filters will operate on the payload rather
2967 than the actual packet.
2969 This is useful if you want to send PPPoUDP traffic over a
2971 link, but want that link to do smart things with the real data rather than
2974 The UDP frame payload must not be compressed in any way, otherwise
2976 will not be able to interpret it.
2977 It is therefore recommended that you
2978 .Ic disable vj pred1 deflate
2980 .Ic deny vj pred1 deflate
2981 in the configuration for the
2983 invocation with the udp link.
2986 Forces execution of the configured chat scripts in
2995 exchanges low-level LCP, CCP and IPCP configuration traffic, the
2997 field of any replies is expected to be the same as that of the request.
3000 drops any reply packets that do not contain the expected identifier
3001 field, reporting the fact at the respective log level.
3006 will ignore the identifier field.
3011 This option simply tells
3013 to add new interface addresses to the interface rather than replacing them.
3014 The option can only be enabled if network address translation is enabled
3015 .Pq Dq nat enable yes .
3017 With this option enabled,
3019 will pass traffic for old interface addresses through the NAT
3023 resulting in the ability (in
3025 mode) to properly connect the process that caused the PPP link to
3026 come up in the first place.
3036 to attempt to negotiate IP control protocol capabilities and if
3037 successful to exchange IP datagrams with the peer.
3042 to attempt to negotiate IPv6 control protocol capabilities and if
3043 successful to exchange IPv6 datagrams with the peer.
3048 runs as a Multi-link server, a different
3050 instance initially receives each connection.
3051 After determining that
3052 the link belongs to an already existing bundle (controlled by another
3056 will transfer the link to that process.
3058 If the link is a tty device or if this option is enabled,
3060 will not exit, but will change its process name to
3062 and wait for the controlling
3064 to finish with the link and deliver a signal back to the idle process.
3065 This prevents the confusion that results from
3067 parent considering the link resource available again.
3069 For tty devices that have entries in
3071 this is necessary to prevent another
3073 from being started, and for program links such as
3077 from exiting due to the death of its child.
3080 cannot determine its parents requirements (except for the tty case), this
3081 option must be enabled manually depending on the circumstances.
3088 will automatically loop back packets being sent
3089 out with a destination address equal to that of the
3094 will send the packet, probably resulting in an ICMP redirect from
3096 It is convenient to have this option enabled when
3097 the interface is also the default route as it avoids the necessity
3098 of a loopback route.
3101 This option controls whether
3105 attribute to the RADIUS server when RADIUS is in use
3106 .Pq see Dq set radius .
3108 Note, at least one of
3116 prior to version 3.4.1 did not send the
3118 attribute as it was reported to break the Radiator RADIUS server.
3119 As the latest rfc (2865) no longer hints that only one of
3123 should be sent (as rfc 2138 did),
3125 now sends both and leaves it up to the administrator that chooses to use
3126 bad RADIUS implementations to
3127 .Dq disable NAS-IP-Address .
3130 This option controls whether
3134 attribute to the RADIUS server when RADIUS is in use
3135 .Pq see Dq set radius .
3137 Note, at least one of
3144 Enabling this option will tell the PAP authentication
3145 code to use the password database (see
3147 to authenticate the caller if they cannot be found in the
3148 .Pa /etc/ppp/ppp.secret
3150 .Pa /etc/ppp/ppp.secret
3151 is always checked first.
3152 If you wish to use passwords from
3154 but also to specify an IP number or label for a given client, use
3156 as the client password in
3157 .Pa /etc/ppp/ppp.secret .
3160 Enabling this option will tell
3162 to proxy ARP for the peer.
3165 will make an entry in the ARP table using
3169 address of the local network in which
3172 This allows other machines connecteed to the LAN to talk to
3173 the peer as if the peer itself was connected to the LAN.
3174 The proxy entry cannot be made unless
3176 is an address from a LAN.
3179 Enabling this will tell
3181 to add proxy arp entries for every IP address in all class C or
3182 smaller subnets routed via the tun interface.
3184 Proxy arp entries are only made for sticky routes that are added
3188 No proxy arp entries are made for the interface address itself
3196 command is used with the
3202 values, entries are stored in the
3205 Each time these variables change, this list is re-applied to the routing table.
3207 Disabling this option will prevent the re-application of sticky routes,
3210 list will still be maintained.
3211 .It Oo tcp Oc Ns No mssfixup
3215 to adjust TCP SYN packets so that the maximum receive segment
3216 size is not greater than the amount allowed by the interface MTU.
3221 to gather throughput statistics.
3222 Input and output is sampled over
3223 a rolling 5 second window, and current, best and total figures are retained.
3224 This data is output when the relevant
3226 layer shuts down, and is also available using the
3229 Throughput statistics are available at the
3236 Normally, when a user is authenticated using PAP or CHAP, and when
3240 mode, an entry is made in the utmp and wtmp files for that user.
3241 Disabling this option will tell
3243 not to make any utmp or wtmp entries.
3244 This is usually only necessary if
3245 you require the user to both login and authenticate themselves.
3249 .Ar dest Ns Op / Ns Ar nn
3254 is the destination IP address.
3255 The netmask is specified either as a number of bits with
3257 or as an IP number using
3262 with no mask refers to the default route.
3263 It is also possible to use the literal name
3268 is the next hop gateway to get to the given
3273 command for further details.
3275 It is possible to use the symbolic names
3281 as the destination, and
3288 is replaced with the interface IP address,
3290 is replaced with the interface IP destination (peer) address,
3292 is replaced with the interface IPv6 address, and
3294 is replaced with the interface IPv6 destination address,
3301 then if the route already exists, it will be updated as with the
3305 for further details).
3307 Routes that contain the
3315 constants are considered
3317 They are stored in a list (use
3319 to see the list), and each time the value of one of these variables
3320 changes, the appropriate routing table entries are updated.
3321 This facility may be disabled using
3322 .Dq disable sroutes .
3323 .It allow Ar command Op Ar args
3324 This command controls access to
3326 and its configuration files.
3327 It is possible to allow user-level access,
3328 depending on the configuration file label and on the mode that
3331 For example, you may wish to configure
3341 User id 0 is immune to these commands.
3343 .It allow user Ns Xo
3345 .Ar logname Ns No ...
3347 By default, only user id 0 is allowed access to
3349 If this command is used, all of the listed users are allowed access to
3350 the section in which the
3355 section is always checked first (even though it is only ever automatically
3358 commands are cumulative in a given section, but users allowed in any given
3359 section override users allowed in the default section, so it is possible to
3360 allow users access to everything except a given label by specifying default
3363 section, and then specifying a new user list for that label.
3367 is specified, access is allowed to all users.
3368 .It allow mode Ns Xo
3372 By default, access using any
3375 If this command is used, it restricts the access
3377 allowed to load the label under which this command is specified.
3382 command overrides any previous settings, and the
3384 section is always checked first.
3396 When running in multi-link mode, a section can be loaded if it allows
3398 of the currently existing line modes.
3400 .It nat Ar command Op Ar args
3401 This command allows the control of the network address translation (also
3402 known as masquerading or IP aliasing) facilities that are built into
3404 NAT is done on the external interface only, and is unlikely to make sense
3409 If nat is enabled on your system (it may be omitted at compile time),
3410 the following commands are possible:
3412 .It nat enable yes|no
3413 This command either switches network address translation on or turns it off.
3416 command line flag is synonymous with
3417 .Dq nat enable yes .
3418 .It nat addr Op Ar addr_local addr_alias
3419 This command allows data for
3423 It is useful if you own a small number of real IP numbers that
3424 you wish to map to specific machines behind your gateway.
3425 .It nat deny_incoming yes|no
3426 If set to yes, this command will refuse all incoming packets where an
3427 aliasing link does not already exist.
3429 .Sx CONCEPTUAL BACKGROUND
3432 for a description of what an
3436 It should be noted under what circumstances an aliasing link is
3439 It may be necessary to further protect your network from outside
3440 connections using the
3446 This command gives a summary of available nat commands.
3448 This option causes various NAT statistics and information to
3449 be logged to the file
3450 .Pa /var/log/alias.log .
3451 .It nat port Ar proto Ar targetIP Ns Xo
3452 .No : Ns Ar targetPort Ns
3454 .No - Ns Ar targetPort
3457 .No - Ns Ar aliasPort
3458 .Oc Oo Ar remoteIP : Ns
3461 .No - Ns Ar remotePort
3465 This command causes incoming
3479 A range of port numbers may be specified as shown above.
3480 The ranges must be of the same size.
3484 is specified, only data coming from that IP number is redirected.
3488 (indicating any source port)
3489 or a range of ports the same size as the other ranges.
3491 This option is useful if you wish to run things like Internet phone on
3492 machines behind your gateway, but is limited in that connections to only
3493 one interior machine per source machine and target port are possible.
3494 .It nat proto Ar proto localIP Oo
3495 .Ar publicIP Op Ar remoteIP
3499 to redirect packets of protocol type
3503 to the internal address
3508 is specified, only packets destined for that address are matched,
3509 otherwise the default alias address is used.
3513 is specified, only packets matching that source address are matched,
3515 This command is useful for redirecting tunnel endpoints to an internal machine,
3518 .Dl nat proto ipencap 10.0.0.1
3519 .It "nat proxy cmd" Ar arg Ns No ...
3522 to proxy certain connections, redirecting them to a given server.
3523 Refer to the description of
3524 .Fn PacketAliasProxyRule
3527 for details of the available commands.
3528 .It nat punch_fw Op Ar base count
3531 to punch holes in the firewall for FTP or IRC DCC connections.
3532 This is done dynamically by installing temporary firewall rules which
3533 allow a particular connection (and only that connection) to go through
3535 The rules are removed once the corresponding connection terminates.
3539 rules starting from rule number
3541 will be used for punching firewall holes.
3542 The range will be cleared when the
3546 If no arguments are given, firewall punching is disabled.
3547 .It nat skinny_port Op Ar port
3550 which TCP port is used by the Skinny Station protocol.
3552 Cisco IP phones to communicate with Cisco Call Managers to setup voice
3554 The typical port used by Skinny is 2000.
3556 If no argument is given, skinny aliasing is disabled.
3557 .It nat same_ports yes|no
3558 When enabled, this command will tell the network address translation engine to
3559 attempt to avoid changing the port number on outgoing packets.
3561 if you want to support protocols such as RPC and LPD which require
3562 connections to come from a well known port.
3563 .It nat target Op Ar address
3564 Set the given target address or clear it if no address is given.
3565 The target address is used by libalias to specify how to NAT incoming packets
3567 If a target address is not set or if
3569 is given, packets are not altered and are allowed to route to the internal
3572 The target address may be set to
3574 in which case libalias will redirect all packets to the interface address.
3575 .It nat use_sockets yes|no
3576 When enabled, this option tells the network address translation engine to
3577 create a socket so that it can guarantee a correct incoming ftp data or
3579 .It nat unregistered_only yes|no
3580 Only alter outgoing packets with an unregistered source address.
3581 According to RFC 1918, unregistered source addresses
3582 are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16.
3585 These commands are also discussed in the file
3587 which comes with the source distribution.
3593 is executed in the background with the following words replaced:
3594 .Bl -tag -width COMPILATIONDATE
3596 This is replaced with the local
3602 .It Li COMPILATIONDATE
3603 In previous software revisions, this was replaced with the date on which
3606 This is no longer supported as it breaks the ability to recompile the same
3607 code to produce an exact duplicate of a previous compilation.
3609 These are replaced with the primary and secondary nameserver IP numbers.
3610 If nameservers are negotiated by IPCP, the values of these macros will change.
3612 This is replaced with the local endpoint discriminator value.
3617 This is replaced with the peers IP number.
3619 This is replaced with the peers IPv6 number.
3621 This is replaced with the name of the interface that is in use.
3623 This is replaced with the number of IP bytes received since the connection
3626 This is replaced with the number of IP bytes sent since the connection
3629 This is replaced with the number of IP packets received since the connection
3632 This is replaced with the number of IP packets sent since the connection
3635 This is replaced with the number of IPv6 bytes received since the connection
3637 .It Li IPV6OCTETSOUT
3638 This is replaced with the number of IPv6 bytes sent since the connection
3640 .It Li IPV6PACKETSIN
3641 This is replaced with the number of IPv6 packets received since the connection
3643 .It Li IPV6PACKETSOUT
3644 This is replaced with the number of IPv6 packets sent since the connection
3647 This is replaced with the last label name used.
3648 A label may be specified on the
3650 command line, via the
3658 This is replaced with the IP number assigned to the local interface.
3660 This is replaced with the IPv6 number assigned to the local interface.
3662 This is replaced with the number of bytes received since the connection
3665 This is replaced with the number of bytes sent since the connection
3668 This is replaced with the number of packets received since the connection
3671 This is replaced with the number of packets sent since the connection
3674 This is replaced with the value of the peers endpoint discriminator.
3676 This is replaced with the current process id.
3678 This is replaced with the name of the diagnostic socket.
3680 This is replaced with the bundle uptime in HH:MM:SS format.
3682 This is replaced with the username that has been authenticated with PAP or
3684 Normally, this variable is assigned only in -direct mode.
3685 This value is available irrespective of whether utmp logging is enabled.
3687 This is replaced with the current version number of
3691 These substitutions are also done by the
3698 If you wish to pause
3700 while the command executes, use the
3703 .It clear physical|ipcp|ipv6 Op current|overall|peak...
3704 Clear the specified throughput values at either the
3712 is specified, context must be given (see the
3715 If no second argument is given, all values are cleared.
3716 .It clone Ar name Ns Xo
3717 .Op \&, Ns Ar name Ns
3720 Clone the specified link, creating one or more new links according to the
3723 This command must be used from the
3725 command below unless you have only got a single link (in which case that
3726 link becomes the default).
3727 Links may be removed using the
3731 The default link name is
3733 .It close Op lcp|ccp Ns Op !\&
3734 If no arguments are given, the relevant protocol layers will be brought
3735 down and the link will be closed.
3738 is specified, the LCP layer is brought down, but
3740 will not bring the link offline.
3741 It is subsequently possible to use
3744 to talk to the peer machine if, for example, something like
3749 is specified, only the relevant compression layer is closed.
3752 is used, the compression layer will remain in the closed state, otherwise
3753 it will re-enter the STOPPED state, waiting for the peer to initiate
3754 further CCP negotiation.
3755 In any event, this command does not disconnect the user from
3766 This command deletes the route with the given
3773 all non-direct entries in the routing table for the current interface,
3776 entries are deleted.
3781 the default route is deleted.
3789 will not complain if the route does not already exist.
3790 .It dial|call Oo Ar label Oc Ns Xo
3793 This command is the equivalent of
3797 and is provided for backwards compatibility.
3798 .It down Op Ar lcp|ccp
3799 Bring the relevant layer down ungracefully, as if the underlying layer
3800 had become unavailable.
3801 It is not considered polite to use this command on
3802 a Finite State Machine that is in the OPEN state.
3804 supplied, the entire link is closed (or if no context is given, all links
3810 layer is terminated but the device is not brought offline and the link
3814 is specified, only the relevant compression layer(s) are terminated.
3815 .It help|? Op Ar command
3816 Show a list of available commands.
3819 is specified, show the usage string for that command.
3820 .It ident Op Ar text Ns No ...
3821 Identify the link to the peer using
3825 is empty, link identification is disabled.
3826 It is possible to use any of the words described for the
3831 command for details of when
3833 identifies itself to the peer.
3834 .It iface Ar command Op args
3835 This command is used to control the interface used by
3838 may be one of the following:
3842 .Ar addr Ns Op / Ns Ar bits
3853 combination to the interface.
3854 Instead of specifying
3858 (with no space between it and
3860 If the given address already exists, the command fails unless the
3862 is used - in which case the previous interface address entry is overwritten
3863 with the new one, allowing a change of netmask or peer address.
3874 .Dq 255.255.255.255 .
3875 This address (the broadcast address) is the only duplicate peer address that
3878 .It iface clear Op INET | INET6
3879 If this command is used while
3881 is in the OPENED state or while in
3883 mode, all addresses except for the NCP negotiated address are deleted
3887 is not in the OPENED state and is not in
3889 mode, all interface addresses are deleted.
3891 If the INET or INET6 arguments are used, only addresses for that address
3893 .It iface delete Ns Xo
3898 This command deletes the given
3903 is used, no error is given if the address is not currently assigned to
3904 the interface (and no deletion takes place).
3905 .It iface name Ar name
3906 Renames the interface to
3908 .It iface description Ar description
3909 Sets the interface description to
3911 Useful if you have many interfaces on your system.
3913 Shows the current state and current addresses for the interface.
3914 It is much the same as running
3915 .Dq ifconfig INTERFACE .
3916 .It iface help Op Ar sub-command
3917 This command, when invoked without
3919 will show a list of possible
3921 sub-commands and a brief synopsis for each.
3924 only the synopsis for the given sub-command is shown.
3926 .It Oo data Oc Ns Xo
3928 .Ar name Ns Oo , Ns Ar name Oc Ns ... Ar command Op Ar args
3930 This command may prefix any other command if the user wishes to
3931 specify which link the command should affect.
3932 This is only applicable after multiple links have been created in Multi-link
3938 specifies the name of an existing link.
3941 is a comma separated list,
3943 is executed on each link.
3949 is executed on all links.
3950 .It load Oo Ar label Oc Ns Xo
3973 will not attempt to make an immediate connection.
3974 .It log Ar word Ns No ...
3975 Send the given word(s) to the log file with the prefix
3977 Word substitutions are done as explained under the
3980 .It open Op lcp|ccp|ipcp
3981 This is the opposite of the
3984 All closed links are immediately brought up apart from second and subsequent
3986 links - these will come up based on the
3988 command that has been used.
3992 argument is used while the LCP layer is already open, LCP will be
3994 This allows various LCP options to be changed, after which
3996 can be used to put them into effect.
3997 After renegotiating LCP,
3998 any agreed authentication will also take place.
4002 argument is used, the relevant compression layer is opened.
4003 Again, if it is already open, it will be renegotiated.
4007 argument is used, the link will be brought up as normal, but if
4008 IPCP is already open, it will be renegotiated and the network
4009 interface will be reconfigured.
4011 It is probably not good practice to re-open the PPP state machines
4012 like this as it is possible that the peer will not behave correctly.
4015 however useful as a way of forcing the CCP or VJ dictionaries to be reset.
4017 Specify the password required for access to the full
4020 This password is required when connecting to the diagnostic port (see the
4031 logging is active, instead, the literal string
4037 is executed from the controlling connection or from a command file,
4038 ppp will exit after closing all connections.
4039 Otherwise, if the user
4040 is connected to a diagnostic socket, the connection is simply dropped.
4046 will exit despite the source of the command after closing all existing
4049 This command removes the given link.
4050 It is only really useful in multi-link mode.
4051 A link must be in the
4053 state before it is removed.
4054 .It rename|mv Ar name
4055 This command renames the given link to
4059 is already used by another link.
4061 The default link name is
4068 may make the log file more readable.
4069 .It resolv Ar command
4070 This command controls
4077 starts up, it loads the contents of this file into memory and retains this
4078 image for future use.
4080 is one of the following:
4081 .Bl -tag -width readonly
4084 .Pa /etc/resolv.conf
4090 will still attempt to negotiate nameservers with the peer, making the results
4096 This is the opposite of the
4101 .Pa /etc/resolv.conf
4103 This may be necessary if for example a DHCP client overwrote
4104 .Pa /etc/resolv.conf .
4107 .Pa /etc/resolv.conf
4108 with the version originally read at startup or with the last
4111 This is sometimes a useful command to put in the
4112 .Pa /etc/ppp/ppp.linkdown
4116 .Pa /etc/resolv.conf
4118 This command will work even if the
4120 command has been used.
4121 It may be useful as a command in the
4122 .Pa /etc/ppp/ppp.linkup
4123 file if you wish to defer updating
4124 .Pa /etc/resolv.conf
4125 until after other commands have finished.
4130 .Pa /etc/resolv.conf
4135 successfully negotiates a DNS.
4136 This is the opposite of the
4141 This option is not (yet) implemented.
4145 to identify itself to the peer.
4146 The link must be in LCP state or higher.
4147 If no identity has been set (via the
4153 When an identity has been set,
4155 will automatically identify itself when it sends or receives a configure
4156 reject, when negotiation fails or when LCP reaches the opened state.
4158 Received identification packets are logged to the LCP log (see
4160 for details) and are never responded to.
4165 This option allows the setting of any of the following variables:
4167 .It set accmap Ar hex-value
4168 ACCMap stands for Asynchronous Control Character Map.
4170 negotiated with the peer, and defaults to a value of 00000000 in hex.
4171 This protocol is required to defeat hardware that depends on passing
4172 certain characters from end to end (such as XON/XOFF etc).
4174 For the XON/XOFF scenario, use
4175 .Dq set accmap 000a0000 .
4176 .It set Oo auth Oc Ns Xo
4179 This sets the authentication key (or password) used in client mode
4180 PAP or CHAP negotiation to the given value.
4181 It also specifies the
4182 password to be used in the dial or login scripts in place of the
4184 sequence, preventing the actual password from being logged.
4189 logging is in effect,
4193 for security reasons.
4195 If the first character of
4197 is an exclamation mark
4200 treats the remainder of the string as a program that must be executed
4212 it is treated as a single literal
4214 otherwise, ignoring the
4217 is parsed as a program to execute in the same was as the
4219 command above, substituting special names in the same manner.
4222 will feed the program three lines of input, each terminated by a newline
4226 The host name as sent in the CHAP challenge.
4228 The challenge string as sent in the CHAP challenge.
4234 Two lines of output are expected:
4239 to be sent with the CHAP response.
4243 which is encrypted with the challenge and request id, the answer being sent
4244 in the CHAP response packet.
4249 in this manner, it is expected that the host challenge is a series of ASCII
4250 digits or characters.
4251 An encryption device or Secure ID card is usually
4252 required to calculate the secret appropriate for the given challenge.
4253 .It set authname Ar id
4254 This sets the authentication id used in client mode PAP or CHAP negotiation.
4258 mode with CHAP enabled,
4260 is used in the initial authentication challenge and should normally be set to
4261 the local machine name.
4263 .Ar min-percent max-percent period
4265 These settings apply only in multi-link mode and default to zero, zero and
4271 mode link is available, only the first link is made active when
4273 first reads data from the tun device.
4276 link will be opened only when the current bundle throughput is at least
4278 percent of the total bundle bandwidth for
4281 When the current bundle throughput decreases to
4283 percent or less of the total bundle bandwidth for
4287 link will be brought down as long as it is not the last active link.
4289 Bundle throughput is measured as the maximum of inbound and outbound
4292 The default values cause
4294 links to simply come up one at a time.
4296 Certain devices cannot determine their physical bandwidth, so it
4297 is sometimes necessary to use the
4299 command (described below) to make
4302 .It set bandwidth Ar value
4303 This command sets the connection bandwidth in bits per second.
4305 must be greater than zero.
4306 It is currently only used by the
4309 .It set callback Ar option Ns No ...
4310 If no arguments are given, callback is disabled, otherwise,
4314 mode, will accept) one of the given
4315 .Ar option Ns No s .
4316 In client mode, if an
4320 will request a different
4322 until no options remain at which point
4324 will terminate negotiations (unless
4326 is one of the specified
4330 will accept any of the given protocols - but the client
4332 request one of them.
4333 If you wish callback to be optional, you must {include}
4339 are as follows (in this order of preference):
4342 The callee is expected to decide the callback number based on
4346 is the callee, the number should be specified as the fifth field of
4348 .Pa /etc/ppp/ppp.secret .
4350 Microsoft's callback control protocol is used.
4355 If you wish to negotiate
4357 in client mode but also wish to allow the server to request no callback at
4358 CBCP negotiation time, you must specify both
4362 as callback options.
4364 .Ar number Ns Op , Ns Ar number Ns
4367 The caller specifies the
4373 should be either a comma separated list of allowable numbers or a
4375 meaning any number is permitted.
4378 is the caller, only a single number should be specified.
4380 Note, this option is very unsafe when used with a
4382 as a malicious caller can tell
4384 to call any (possibly international) number without first authenticating
4387 If the peer does not wish to do callback at all,
4389 will accept the fact and continue without callback rather than terminating
4391 This is required (in addition to one or more other callback
4392 options) if you wish callback to be optional.
4395 .No *| Ns Ar number Ns Oo
4396 .No , Ns Ar number Ns ...\& Oc
4397 .Op Ar delay Op Ar retry
4399 If no arguments are given, CBCP (Microsoft's CallBack Control Protocol)
4400 is disabled - ie, configuring CBCP in the
4402 command will result in
4404 requesting no callback in the CBCP phase.
4407 attempts to use the given phone
4408 .Ar number Ns No (s).
4413 will insist that the client uses one of these numbers, unless
4415 is used in which case the client is expected to specify the number.
4419 will attempt to use one of the given numbers (whichever it finds to
4420 be agreeable with the peer), or if
4424 will expect the peer to specify the number.
4426 .No off| Ns Ar seconds Ns Op !\&
4430 checks for the existence of carrier depending on the type of device
4431 that has been opened:
4432 .Bl -tag -width XXX -offset XXX
4433 .It Terminal Devices
4434 Carrier is checked one second after the login script is complete.
4437 assumes that this is because the device does not support carrier (which
4440 NULL-modem cables), logs the fact and stops checking
4443 As ptys do not support the TIOCMGET ioctl, the tty device will switch all
4444 carrier detection off when it detects that the device is a pty.
4445 .It PPPoE (netgraph) Devices
4446 Carrier is checked once per second for 5 seconds.
4447 If it is not set after
4448 the fifth second, the connection attempt is considered to have failed and
4449 the device is closed.
4450 Carrier is always required for PPPoE devices.
4453 All other device types do not support carrier.
4454 Setting a carrier value will
4455 result in a warning when the device is opened.
4457 Some modems take more than one second after connecting to assert the carrier
4459 If this delay is not increased, this will result in
4461 inability to detect when the link is dropped, as
4463 assumes that the device is not asserting carrier.
4467 command overrides the default carrier behaviour.
4469 specifies the maximum number of seconds that
4471 should wait after the dial script has finished before deciding if
4472 carrier is available or not.
4478 will not check for carrier on the device, otherwise
4480 will not proceed to the login script until either carrier is detected
4483 has elapsed, at which point
4485 assumes that the device will not set carrier.
4487 If no arguments are given, carrier settings will go back to their default
4492 is followed immediately by an exclamation mark
4498 If carrier is not detected after
4500 seconds, the link will be disconnected.
4501 .It set choked Op Ar timeout
4502 This sets the number of seconds that
4504 will keep a choked output queue before dropping all pending output packets.
4507 is less than or equal to zero or if
4509 is not specified, it is set to the default value of
4512 A choked output queue occurs when
4514 has read a certain number of packets from the local network for transmission,
4515 but cannot send the data due to link failure (the peer is busy etc.).
4517 will not read packets indefinitely.
4518 Instead, it reads up to
4524 packets in multi-link mode), then stops reading the network interface
4527 seconds have passed or at least one packet has been sent.
4531 seconds pass, all pending output packets are dropped.
4532 .It set ctsrts|crtscts on|off
4533 This sets hardware flow control.
4534 Hardware flow control is
4537 .It set deflate Ar out-winsize Op Ar in-winsize
4538 This sets the DEFLATE algorithms default outgoing and incoming window
4544 must be values between
4552 will insist that this window size is used and will not accept any other
4553 values from the peer.
4554 .It set dns Op Ar primary Op Ar secondary
4555 This command specifies DNS overrides for the
4560 command description above for details.
4561 This command does not affect the IP numbers requested using
4563 .It set device|line Xo
4566 This sets the device(s) to which
4568 will talk to the given
4571 All serial device names are expected to begin with
4573 Serial devices are usually called
4580 it must either begin with an exclamation mark
4583 .No PPPoE: Ns Ar iface Ns Xo
4584 .Op \&: Ns Ar provider Ns
4588 enabled systems), or be of the format
4590 .Ar host : port Op /tcp|udp .
4593 If it begins with an exclamation mark, the rest of the device name is
4594 treated as a program name, and that program is executed when the device
4596 Standard input, output and error are fed back to
4598 and are read and written as if they were a regular device.
4601 .No PPPoE: Ns Ar iface Ns Xo
4602 .Op \&: Ns Ar provider Ns
4604 specification is given,
4606 will attempt to create a
4608 over Ethernet connection using the given
4616 will attempt to load it using
4618 If this fails, an external program must be used such as the
4620 program available under
4624 is passed as the service name in the PPPoE Discovery Initiation (PADI)
4626 If no provider is given, an empty value will be used.
4628 When a PPPoE connection is established,
4630 will place the name of the Access Concentrator in the environment variable
4637 for further details.
4640 .Ar host Ns No : Ns Ar port Ns Oo
4643 specification is given,
4645 will attempt to connect to the given
4653 suffix is not provided, the default is
4655 Refer to the section on
4656 .Em PPP OVER TCP and UDP
4657 above for further details.
4663 will attempt to open each one in turn until it succeeds or runs out of
4665 .It set dial Ar chat-script
4666 This specifies the chat script that will be used to dial the other
4673 and to the example configuration files for details of the chat script
4675 It is possible to specify some special
4677 in your chat script as follows:
4680 When used as the last character in a
4682 string, this indicates that a newline should not be appended.
4684 When the chat script encounters this sequence, it delays two seconds.
4686 When the chat script encounters this sequence, it delays for one quarter of
4689 This is replaced with a newline character.
4691 This is replaced with a carriage return character.
4693 This is replaced with a space character.
4695 This is replaced with a tab character.
4697 This is replaced by the current phone number (see
4701 This is replaced by the current
4707 This is replaced by the current
4714 Note that two parsers will examine these escape sequences, so in order to
4717 see the escape character, it is necessary to escape it from the
4718 .Sq command parser .
4719 This means that in practice you should use two escapes, for example:
4720 .Bd -literal -offset indent
4721 set dial "... ATDT\\\\T CONNECT"
4724 It is also possible to execute external commands from the chat script.
4725 To do this, the first character of the expect or send string is an
4728 If a literal exclamation mark is required, double it up to
4730 and it will be treated as a single literal
4732 When the command is executed, standard input and standard output are
4733 directed to the open device (see the
4735 command), and standard error is read by
4737 and substituted as the expect or send string.
4740 is running in interactive mode, file descriptor 3 is attached to
4743 For example (wrapped for readability):
4744 .Bd -literal -offset indent
4745 set login "TIMEOUT 5 \\"\\" \\"\\" login:--login: ppp \e
4746 word: ppp \\"!sh \\\\-c \\\\\\"echo \\\\-n label: >&2\\\\\\"\\" \e
4747 \\"!/bin/echo in\\" HELLO"
4750 would result in the following chat sequence (output using the
4751 .Sq set log local chat
4752 command before dialing):
4753 .Bd -literal -offset indent
4758 Chat: Expecting: login:--login:
4759 Chat: Wait for (5): login:
4761 Chat: Expecting: word:
4762 Chat: Wait for (5): word:
4764 Chat: Expecting: !sh \\-c "echo \\-n label: >&2"
4765 Chat: Exec: sh -c "echo -n label: >&2"
4766 Chat: Wait for (5): !sh \\-c "echo \\-n label: >&2" --> label:
4767 Chat: Exec: /bin/echo in
4769 Chat: Expecting: HELLO
4770 Chat: Wait for (5): HELLO
4774 Note (again) the use of the escape character, allowing many levels of
4776 Here, there are four parsers at work.
4777 The first parses the original line, reading it as three arguments.
4778 The second parses the third argument, reading it as 11 arguments.
4779 At this point, it is
4782 signs are escaped, otherwise this parser will see them as constituting
4783 an expect-send-expect sequence.
4786 character is seen, the execution parser reads the first command as three
4789 itself expands the argument after the
4791 As we wish to send the output back to the modem, in the first example
4792 we redirect our output to file descriptor 2 (stderr) so that
4794 itself sends and logs it, and in the second example, we just output to stdout,
4795 which is attached directly to the modem.
4797 This, of course means that it is possible to execute an entirely external
4799 command rather than using the internal one.
4802 for a good alternative.
4804 The external command that is executed is subjected to the same special
4805 word expansions as the
4808 .It set enddisc Op label|IP|MAC|magic|psn value
4809 This command sets our local endpoint discriminator.
4810 If set prior to LCP negotiation, and if no
4812 command has been used,
4814 will send the information to the peer using the LCP endpoint discriminator
4816 The following discriminators may be set:
4817 .Bl -tag -width indent
4819 The current label is used.
4821 Our local IP number is used.
4822 As LCP is negotiated prior to IPCP, it is
4823 possible that the IPCP layer will subsequently change this value.
4825 it does, the endpoint discriminator stays at the old value unless manually
4828 This is similar to the
4830 option above, except that the MAC address associated with the local IP
4832 If the local IP number is not resident on any Ethernet
4833 interface, the command will fail.
4835 As the local IP number defaults to whatever the machine host name is,
4837 is usually done prior to any
4841 A 20 digit random number is used.
4842 Care should be taken when using magic numbers as restarting
4844 or creating a link using a different
4846 invocation will also use a different magic number and will therefore not
4847 be recognised by the peer as belonging to the same bundle.
4848 This makes it unsuitable for
4856 should be set to an absolute public switched network number with the
4860 If no arguments are given, the endpoint discriminator is reset.
4861 .It set escape Ar value...
4862 This option is similar to the
4865 It allows the user to specify a set of characters that will be
4867 as they travel across the link.
4868 .It set filter dial|alive|in|out Ar rule-no Xo
4869 .No permit|deny|clear| Ns Ar rule-no
4872 .Ar src_addr Ns Op / Ns Ar width
4873 .Op Ar dst_addr Ns Op / Ns Ar width
4875 .Op src lt|eq|gt Ar port
4876 .Op dst lt|eq|gt Ar port
4880 .Op timeout Ar secs ]
4883 supports four filter sets.
4886 filter specifies packets that keep the connection alive - resetting the
4890 filter specifies packets that cause
4897 filter specifies packets that are allowed to travel
4898 into the machine and the
4900 filter specifies packets that are allowed out of the machine.
4902 Filtering is done prior to any IP alterations that might be done by the
4903 NAT engine on outgoing packets and after any IP alterations that might
4904 be done by the NAT engine on incoming packets.
4905 By default all empty filter sets allow all packets to pass.
4906 Rules are processed in order according to
4908 (unless skipped by specifying a rule number as the
4910 Up to 40 rules may be given for each set.
4911 If a packet does not match
4912 any of the rules in a given set, it is discarded.
4917 filters, this means that the packet is dropped.
4920 filters it means that the packet will not reset the idle timer (even if
4922 .Ar in Ns No / Ns Ar out
4925 value) and in the case of
4927 filters it means that the packet will not trigger a dial.
4928 A packet failing to trigger a dial will be dropped rather than queued.
4931 .Sx PACKET FILTERING
4932 above for further details.
4933 .It set hangup Ar chat-script
4934 This specifies the chat script that will be used to reset the device
4935 before it is closed.
4936 It should not normally be necessary, but can
4937 be used for devices that fail to reset themselves properly on close.
4938 .It set help|? Op Ar command
4939 This command gives a summary of available set commands, or if
4941 is specified, the command usage is shown.
4942 .It set ifaddr Oo Ar myaddr Ns
4944 .Oo Ar hisaddr Ns Op / Ns Ar \&nn
4949 This command specifies the IP addresses that will be used during
4951 Addresses are specified using the format
4957 is the preferred IP, but
4959 specifies how many bits of the address we will insist on.
4962 is omitted, it defaults to
4964 unless the IP address is 0.0.0.0 in which case it defaults to
4967 If you wish to assign a dynamic IP number to the peer,
4969 may also be specified as a range of IP numbers in the format
4970 .Bd -ragged -offset indent
4971 .Ar \&IP Ns Oo \&- Ns Ar \&IP Ns Oc Ns Oo , Ns Ar \&IP Ns
4972 .Oo \&- Ns Ar \&IP Ns Oc Oc Ns ...
4977 .Dl set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20
4981 as the local IP number, but may assign any of the given 10 IP
4982 numbers to the peer.
4983 If the peer requests one of these numbers,
4984 and that number is not already in use,
4986 will grant the peers request.
4987 This is useful if the peer wants
4988 to re-establish a link using the same IP number as was previously
4989 allocated (thus maintaining any existing tcp or udp connections).
4991 If the peer requests an IP number that is either outside
4992 of this range or is already in use,
4994 will suggest a random unused IP number from the range.
4998 is specified, it is used in place of
5000 in the initial IPCP negotiation.
5001 However, only an address in the
5003 range will be accepted.
5004 This is useful when negotiating with some
5006 implementations that will not assign an IP number unless their peer
5010 It should be noted that in
5014 will configure the interface immediately upon reading the
5016 line in the config file.
5017 In any other mode, these values are just
5018 used for IPCP negotiations, and the interface is not configured
5019 until the IPCP layer is up.
5023 argument may be overridden by the third field in the
5025 file once the client has authenticated itself
5029 .Sx AUTHENTICATING INCOMING CONNECTIONS
5030 section for details.
5032 In all cases, if the interface is already configured,
5034 will try to maintain the interface IP numbers so that any existing
5035 bound sockets will remain valid.
5036 .It set ifqueue Ar packets
5037 Set the maximum number of packets that
5039 will read from the tunnel interface while data cannot be sent to any of
5040 the available links.
5041 This queue limit is necessary to flow control outgoing data as the tunnel
5042 interface is likely to be far faster than the combined links available to
5047 is set to a value less than the number of links,
5049 will read up to that value regardless.
5050 This prevents any possible latency problems.
5052 The default value for
5056 .It set ccpretry|ccpretries Oo Ar timeout
5057 .Op Ar reqtries Op Ar trmtries
5059 .It set chapretry|chapretries Oo Ar timeout
5062 .It set ipcpretry|ipcpretries Oo Ar timeout
5063 .Op Ar reqtries Op Ar trmtries
5065 .It set ipv6cpretry|ipv6cpretries Oo Ar timeout
5066 .Op Ar reqtries Op Ar trmtries
5068 .It set lcpretry|lcpretries Oo Ar timeout
5069 .Op Ar reqtries Op Ar trmtries
5071 .It set papretry|papretries Oo Ar timeout
5074 These commands set the number of seconds that
5076 will wait before resending Finite State Machine (FSM) Request packets.
5079 for all FSMs is 3 seconds (which should suffice in most cases).
5083 is specified, it tells
5085 how many configuration request attempts it should make while receiving
5086 no reply from the peer before giving up.
5087 The default is 5 attempts for
5088 CCP, LCP and IPCP and 3 attempts for PAP and CHAP.
5092 is specified, it tells
5094 how many terminate requests should be sent before giving up waiting for the
5096 The default is 3 attempts.
5097 Authentication protocols are
5098 not terminated and it is therefore invalid to specify
5102 In order to avoid negotiations with the peer that will never converge,
5104 will only send at most 3 times the configured number of
5106 in any given negotiation session before giving up and closing that layer.
5112 This command allows the adjustment of the current log level.
5113 Refer to the Logging Facility section for further details.
5114 .It set login Ar chat-script
5117 compliments the dial-script.
5118 If both are specified, the login
5119 script will be executed after the dial script.
5120 Escape sequences available in the dial script are also available here.
5121 .It set logout Ar chat-script
5122 This specifies the chat script that will be used to logout
5123 before the hangup script is called.
5124 It should not normally be necessary.
5125 .It set lqrperiod|echoperiod Ar frequency
5126 This command sets the
5133 The default is 30 seconds.
5134 You must also use the
5138 commands if you wish to send
5142 requests to the peer.
5143 .It set mode Ar interactive|auto|ddial|background
5144 This command allows you to change the
5146 of the specified link.
5147 This is normally only useful in multi-link mode,
5148 but may also be used in uni-link mode.
5150 It is not possible to change a link that is
5155 Note: If you issue the command
5157 and have network address translation enabled, it may be useful to
5158 .Dq enable iface-alias
5162 to do the necessary address translations to enable the process that
5163 triggers the connection to connect once the link is up despite the
5164 peer assigning us a new (dynamic) IP address.
5165 .It set mppe Op 40|56|128|* Op stateless|stateful|*
5166 This option selects the encryption parameters used when negotiation
5168 MPPE can be disabled entirely with the
5171 If no arguments are given,
5173 will attempt to negotiate a stateful link with a 128 bit key, but
5174 will agree to whatever the peer requests (including no encryption
5177 If any arguments are given,
5181 on using MPPE and will close the link if it is rejected by the peer (Note;
5182 this behaviour can be overridden by a configured RADIUS server).
5184 The first argument specifies the number of bits that
5186 should insist on during negotiations and the second specifies whether
5188 should insist on stateful or stateless mode.
5189 In stateless mode, the
5190 encryption dictionary is re-initialised with every packet according to
5191 an encryption key that is changed with every packet.
5193 the encryption dictionary is re-initialised every 256 packets or after
5194 the loss of any data and the key is changed every 256 packets.
5195 Stateless mode is less efficient but is better for unreliable transport
5197 .It set mrru Op Ar value
5198 Setting this option enables Multi-link PPP negotiations, also known as
5199 Multi-link Protocol or MP.
5200 There is no default MRRU (Maximum Reconstructed Receive Unit) value.
5201 If no argument is given, multi-link mode is disabled.
5206 The default MRU (Maximum Receive Unit) is 1500.
5207 If it is increased, the other side *may* increase its MTU.
5208 In theory there is no point in decreasing the MRU to below the default as the
5210 protocol says implementations *must* be able to accept packets of at
5217 will refuse to negotiate a higher value.
5218 The maximum MRU can be set to 2048 at most.
5219 Setting a maximum of less than 1500 violates the
5221 rfc, but may sometimes be necessary.
5224 imposes a maximum of 1492 due to hardware limitations.
5226 If no argument is given, 1500 is assumed.
5227 A value must be given when
5234 The default MTU is 1500.
5235 At negotiation time,
5237 will accept whatever MRU the peer requests (assuming it is
5238 not less than 296 bytes or greater than the assigned maximum).
5241 will not accept MRU values less than
5243 When negotiations are complete, the MTU is used when writing to the
5244 interface, even if the peer requested a higher value MRU.
5245 This can be useful for
5246 limiting your packet size (giving better bandwidth sharing at the expense
5247 of more header data).
5253 will refuse to negotiate a higher value.
5254 The maximum MTU can be set to 2048 at most.
5255 Note, it is necessary to use the
5257 keyword to limit the MTU when using PPPoE.
5261 is given, 1500, or whatever the peer asks for is used.
5262 A value must be given when
5265 .It set nbns Op Ar x.x.x.x Op Ar y.y.y.y
5266 This option allows the setting of the Microsoft NetBIOS name server
5267 values to be returned at the peers request.
5268 If no values are given,
5270 will reject any such requests.
5271 .It set openmode active|passive Op Ar delay
5280 will always initiate LCP/IPCP/CCP negotiation one second after the line
5282 If you want to wait for the peer to initiate negotiations, you
5285 If you want to initiate negotiations immediately or after more than one
5286 second, the appropriate
5288 may be specified here in seconds.
5289 .It set parity odd|even|none|mark
5290 This allows the line parity to be set.
5291 The default value is
5293 .It set phone Ar telno Ns Xo
5294 .Oo \&| Ns Ar backupnumber Oc Ns ... Ns Oo : Ns Ar nextnumber Oc Ns ... Xc
5295 This allows the specification of the phone number to be used in
5296 place of the \\\\T string in the dial and login chat scripts.
5297 Multiple phone numbers may be given separated either by a pipe
5302 Numbers after the pipe are only dialed if the dial or login
5303 script for the previous number failed.
5305 Numbers after the colon are tried sequentially, irrespective of
5306 the reason the line was dropped.
5308 If multiple numbers are given,
5310 will dial them according to these rules until a connection is made, retrying
5311 the maximum number of times specified by
5316 mode, each number is attempted at most once.
5317 .It set pppoe Op standard|3Com
5318 This option configures the underlying
5320 node to either standard RFC2516 PPPoE or proprietary 3Com mode.
5321 If not set the system default will be used.
5322 .It set Oo proc Oc Ns Xo
5323 .No title Op Ar value
5325 The current process title as displayed by
5327 is changed according to
5331 is not specified, the original process title is restored.
5333 word replacements done by the shell commands (see the
5335 command above) are done here too.
5337 Note, if USER is required in the process title, the
5339 command must appear in
5341 as it is not known when the commands in
5344 .It set radius Op Ar config-file
5345 This command enables RADIUS support (if it is compiled in).
5347 refers to the radius client configuration file as described in
5349 If PAP, CHAP, MSCHAP or MSCHAPv2 are
5350 .Dq enable Ns No d ,
5353 .Em \&N Ns No etwork
5356 and uses the configured RADIUS server to authenticate rather than
5357 authenticating from the
5359 file or from the passwd database.
5361 If none of PAP, CHAP, MSCHAP or MSCHAPv2 are enabled,
5366 uses the following attributes from the RADIUS reply:
5367 .Bl -tag -width XXX -offset XXX
5368 .It RAD_FRAMED_IP_ADDRESS
5369 The peer IP address is set to the given value.
5370 .It RAD_FRAMED_IP_NETMASK
5371 The tun interface netmask is set to the given value.
5373 If the given MTU is less than the peers MRU as agreed during LCP
5374 negotiation, *and* it is less that any configured MTU (see the
5376 command), the tun interface MTU is set to the given value.
5377 .It RAD_FRAMED_COMPRESSION
5378 If the received compression type is
5381 will request VJ compression during IPCP negotiations despite any
5383 configuration command.
5385 If this attribute is supplied,
5387 will attempt to use it as an additional label to load from the
5392 The load will be attempted before (and in addition to) the normal
5394 If the label does not exist, no action is taken and
5396 proceeds to the normal load using the current label.
5397 .It RAD_FRAMED_ROUTE
5398 The received string is expected to be in the format
5399 .Ar dest Ns Op / Ns Ar bits
5402 Any specified metrics are ignored.
5406 are understood as valid values for
5413 to specify the default route, and
5415 is understood to be the same as
5424 For example, a returned value of
5425 .Dq 1.2.3.4/24 0.0.0.0 1 2 -1 3 400
5426 would result in a routing table entry to the 1.2.3.0/24 network via
5428 and a returned value of
5432 would result in a default route to
5435 All RADIUS routes are applied after any sticky routes are applied, making
5436 RADIUS routes override configured routes.
5437 This also applies for RADIUS routes that do not {include} the
5442 .It RAD_FRAMED_IPV6_PREFIX
5443 If this attribute is supplied, the value is substituted for IPV6PREFIX
5445 You may pass it to an upper layer protocol such as DHCPv6 for delegating an
5446 IPv6 prefix to a peer.
5447 .It RAD_FRAMED_IPV6_ROUTE
5448 The received string is expected to be in the format
5449 .Ar dest Ns Op / Ns Ar bits
5452 Any specified metrics are ignored.
5456 are understood as valid values for
5463 to specify the default route, and
5465 is understood to be the same as
5474 For example, a returned value of
5475 .Dq 3ffe:505:abcd::/48 ::
5476 would result in a routing table entry to the 3ffe:505:abcd::/48 network via
5478 and a returned value of
5481 .Dq default HISADDR6
5482 would result in a default route to
5485 All RADIUS IPv6 routes are applied after any sticky routes are
5486 applied, making RADIUS IPv6 routes override configured routes.
5488 also applies for RADIUS IPv6 routes that do not {include} the
5493 .It RAD_SESSION_TIMEOUT
5494 If supplied, the client connection is closed after the given number of
5496 .It RAD_REPLY_MESSAGE
5497 If supplied, this message is passed back to the peer as the authentication
5499 .It RAD_MICROSOFT_MS_CHAP_ERROR
5501 .Dv RAD_VENDOR_MICROSOFT
5502 vendor specific attribute is supplied, it is passed back to the peer as the
5503 authentication FAILURE text.
5504 .It RAD_MICROSOFT_MS_CHAP2_SUCCESS
5506 .Dv RAD_VENDOR_MICROSOFT
5507 vendor specific attribute is supplied and if MS-CHAPv2 authentication is
5508 being used, it is passed back to the peer as the authentication SUCCESS text.
5509 .It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY
5511 .Dv RAD_VENDOR_MICROSOFT
5512 vendor specific attribute is supplied and has a value of 2 (Required),
5514 will insist that MPPE encryption is used (even if no
5516 configuration command has been given with arguments).
5517 If it is supplied with a value of 1 (Allowed), encryption is made optional
5520 configuration commands with arguments).
5521 .It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES
5523 .Dv RAD_VENDOR_MICROSOFT
5524 vendor specific attribute is supplied, bits 1 and 2 are examined.
5525 If either or both are set, 40 bit and/or 128 bit (respectively) encryption
5526 options are set, overriding any given first argument to the
5529 Note, it is not currently possible for the RADIUS server to specify 56 bit
5531 .It RAD_MICROSOFT_MS_MPPE_RECV_KEY
5533 .Dv RAD_VENDOR_MICROSOFT
5534 vendor specific attribute is supplied, it is value is used as the master
5535 key for decryption of incoming data.
5536 When clients are authenticated using
5537 MSCHAPv2, the RADIUS server MUST provide this attribute if inbound MPPE is
5539 .It RAD_MICROSOFT_MS_MPPE_SEND_KEY
5541 .Dv RAD_VENDOR_MICROSOFT
5542 vendor specific attribute is supplied, it is value is used as the master
5543 key for encryption of outgoing data.
5544 When clients are authenticated using
5545 MSCHAPv2, the RADIUS server MUST provide this attribute if outbound MPPE is
5549 Values received from the RADIUS server may be viewed using
5551 .It set rad_alive Ar timeout
5552 When RADIUS is configured, setting
5558 to sent RADIUS accounting information to the RADIUS server every
5561 .It set rad_port_id Ar option
5562 When RADIUS is configured, setting the
5564 value specifies what should be sent to the RADIUS server as
5571 PID of the corresponding tunnel.
5576 index of the interface as returned by
5577 .Xr if_nametoindex 3 .
5579 keeps the default behavior.
5581 .It set reconnect Ar timeout ntries
5582 Should the line drop unexpectedly (due to loss of CD or LQR
5583 failure), a connection will be re-established after the given
5585 The line will be re-connected at most
5594 will result in a variable pause, somewhere between 1 and 30 seconds.
5595 .It set recvpipe Op Ar value
5596 This sets the routing table RECVPIPE value.
5597 The optimum value is just over twice the MTU value.
5600 is unspecified or zero, the default kernel controlled value is used.
5601 .It set redial Ar secs Ns Xo
5603 .Oo - Ns Ar max Ns Oc Oc Ns
5608 can be instructed to attempt to redial
5611 If more than one phone number is specified (see
5615 is taken before dialing each number.
5618 is taken before starting at the first number again.
5621 may be used here in place of
5625 causing a random delay of between 1 and 30 seconds.
5629 is specified, its value is added onto
5635 will only be incremented at most
5643 delay will be effective, even after
5645 has been exceeded, so an immediate manual dial may appear to have
5647 If an immediate dial is required, a
5649 should immediately follow the
5654 description above for further details.
5655 .It set sendpipe Op Ar value
5656 This sets the routing table SENDPIPE value.
5657 The optimum value is just over twice the MTU value.
5660 is unspecified or zero, the default kernel controlled value is used.
5661 .It "set server|socket" Ar TcpPort Ns No \&| Ns Xo
5662 .Ar LocalName Ns No |none|open|closed
5663 .Op password Op Ar mask
5667 to listen on the given socket or
5669 for incoming command connections.
5675 to close any existing socket and clear the socket configuration.
5680 to attempt to re-open the port.
5685 to close the open port.
5687 If you wish to specify a local domain socket,
5689 must be specified as an absolute file name, otherwise it is assumed
5690 to be the name or number of a TCP port.
5691 You may specify the octal umask to be used with a local domain socket.
5697 for details of how to translate TCP port names.
5699 You must also specify the password that must be entered by the client
5702 variable above) when connecting to this socket.
5704 specified as an empty string, no password is required for connecting clients.
5706 When specifying a local domain socket, the first
5708 sequence found in the socket name will be replaced with the current
5709 interface unit number.
5710 This is useful when you wish to use the same
5711 profile for more than one connection.
5713 In a similar manner TCP sockets may be prefixed with the
5715 character, in which case the current interface unit number is added to
5720 with a server socket, the
5722 command is the preferred mechanism of communications.
5725 can also be used, but link encryption may be implemented in the future, so
5733 interact with the diagnostic socket.
5734 .It set speed Ar value
5735 This sets the speed of the serial device.
5736 If speed is specified as
5739 treats the device as a synchronous device.
5741 Certain device types will know whether they should be specified as
5742 synchronous or asynchronous.
5743 These devices will override incorrect
5744 settings and log a warning to this effect.
5745 .It set stopped Op Ar LCPseconds Op Ar CCPseconds
5746 If this option is set,
5748 will time out after the given FSM (Finite State Machine) has been in
5749 the stopped state for the given number of
5751 This option may be useful if the peer sends a terminate request,
5752 but never actually closes the connection despite our sending a terminate
5754 This is also useful if you wish to
5755 .Dq set openmode passive
5756 and time out if the peer does not send a Configure Request within the
5759 .Dq set log +lcp +ccp
5762 log the appropriate state transitions.
5764 The default value is zero, where
5766 does not time out in the stopped state.
5768 This value should not be set to less than the openmode delay (see
5771 .It set timeout Ar idleseconds Op Ar mintimeout
5772 This command allows the setting of the idle timer.
5773 Refer to the section titled
5774 .Sx SETTING THE IDLE TIMER
5775 for further details.
5781 will never idle out before the link has been up for at least that number
5789 This command controls the ports that
5791 prioritizes when transmitting data.
5792 The default priority TCP ports
5793 are ports 21 (ftp control), 22 (ssh), 23 (telnet), 513 (login), 514 (shell),
5794 543 (klogin) and 544 (kshell).
5795 There are no priority UDP ports by default.
5810 are given, the priority port lists are cleared (although if
5814 is specified, only that list is cleared).
5817 argument is prefixed with a plus
5821 the current list is adjusted, otherwise the list is reassigned.
5823 prefixed with a plus or not prefixed at all are added to the list and
5825 prefixed with a minus are removed from the list.
5829 is specified, all priority port lists are disabled and even
5831 packets are not prioritised.
5832 .It set urgent length Ar length
5833 This command tells ppp to prioritize small packets up to
5838 is not specified, or 0, this feature is disabled.
5839 .It set vj slotcomp on|off
5842 whether it should attempt to negotiate VJ slot compression.
5843 By default, slot compression is turned
5845 .It set vj slots Ar nslots
5846 This command sets the initial number of slots that
5848 will try to negotiate with the peer when VJ compression is enabled (see the
5851 It defaults to a value of 16.
5859 .It shell|! Op Ar command
5862 is not specified a shell is invoked according to the
5864 environment variable.
5865 Otherwise, the given
5868 Word replacement is done in the same way as for the
5870 command as described above.
5872 Use of the !\& character
5873 requires a following space as with any of the other commands.
5874 You should note that this command is executed in the foreground;
5876 will not continue running until this process has exited.
5879 command if you wish processing to happen in the background.
5881 This command allows the user to examine the following:
5884 Show the current bundle settings.
5886 Show the current CCP compression statistics.
5888 Show the current VJ compression statistics.
5890 Show the current escape characters.
5891 .It show filter Op Ar name
5892 List the current rules for the given filter.
5895 is not specified, all filters are shown.
5897 Show the current HDLC statistics.
5899 Give a summary of available show commands.
5901 Show the current interface information
5905 Show the current IPCP statistics.
5907 Show the protocol layers currently in use.
5909 Show the current LCP statistics.
5910 .It show Oo data Oc Ns Xo
5913 Show high level link information.
5915 Show a list of available logical links.
5917 Show the current log values.
5919 Show current memory statistics.
5921 Show the current NCP statistics.
5923 Show low level link information.
5925 Show Multi-link information.
5927 Show current protocol totals.
5929 Show the current routing tables.
5931 Show the current stopped timeouts.
5933 Show the active alarm timers.
5935 Show the current version number of
5939 Go into terminal mode.
5940 Characters typed at the keyboard are sent to the device.
5941 Characters read from the device are displayed on the screen.
5946 automatically enables Packet Mode and goes back into command mode.
5951 Read the example configuration files.
5952 They are a good source of information.
5961 to get online information about what is available.
5963 The following URL contains useful information:
5964 .Bl -bullet -compact
5966 https://docs.freebsd.org/en/books/handbook/ppp-and-slip/
5971 refers to four files:
5977 These files are placed in the
5981 .It Pa /etc/ppp/ppp.conf
5982 System default configuration file.
5983 .It Pa /etc/ppp/ppp.secret
5984 An authorisation file for each system.
5985 .It Pa /etc/ppp/ppp.linkup
5986 A file to check when
5988 establishes a network level connection.
5989 .It Pa /etc/ppp/ppp.linkdown
5990 A file to check when
5992 closes a network level connection.
5993 .It Pa /var/log/ppp.log
5994 Logging and debugging information file.
5995 Note, this name is specified in
5996 .Pa /etc/syslog.conf .
5999 for further details.
6000 .It Pa /var/spool/lock/LCK..*
6001 tty port locking file.
6004 for further details.
6005 .It Pa /var/run/tunN.pid
6006 The process id (pid) of the
6008 program connected to the tunN device, where
6010 is the number of the device.
6011 .It Pa /var/run/ttyXX.if
6012 The tun interface used by this port.
6013 Again, this file is only created in
6019 .It Pa /etc/services
6020 Get port number if port number is using service name.
6021 .It Pa /var/run/ppp-authname-class-value
6022 In multi-link mode, local domain sockets are created using the peer
6025 the peer endpoint discriminator class
6027 and the peer endpoint discriminator value
6029 As the endpoint discriminator value may be a binary value, it is turned
6030 to HEX to determine the actual file name.
6032 This socket is used to pass links between different instances of
6073 This program was originally written by
6074 .An Toshiharu OHNO Aq Mt tony-o@iij.ad.jp ,
6075 and was submitted to
6078 .An Atsushi Murai Aq Mt amurai@spec.co.jp .
6080 It was substantially modified during 1997 by
6081 .An Brian Somers Aq Mt brian@Awfulhak.org ,
6084 in November that year
6085 (just after the 2.2 release).
6087 Most of the code was rewritten by
6089 in early 1998 when multi-link ppp support was added.
projects / FreeBSD / FreeBSD.git / blob