4 .\" Copyright (c) 2001 Brian Somers <brian@Awfulhak.org>
5 .\" All rights reserved.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35 .Nd Point to Point Protocol (a.k.a. user-ppp)
44 This is a user process
49 is implemented as a part of the kernel (e.g., as managed by
51 and it is thus somewhat hard to debug and/or modify its behaviour.
52 However, in this implementation
54 is done as a user process with the help of the
55 tunnel device driver (tun).
59 flag does the equivalent of a
63 network address translation features.
66 to act as a NAT or masquerading engine for all machines on an internal
68 ifdef({LOCALNAT},{},{Refer to
70 for details on the technical side of the NAT engine.
73 .Sx NETWORK ADDRESS TRANSLATION (PACKET ALIASING)
74 section of this manual page for details on how to configure NAT in
81 to be silent at startup rather than displaying the mode and interface
88 to only attempt to open
89 .Pa /dev/tun Ns Ar N .
92 will start with a value of 0 for
94 and keep trying to open a tunnel device by incrementing the value of
96 by one each time until it succeeds.
97 If it fails three times in a row
98 because the device file is missing, it gives up.
104 .Bl -tag -width XXX -offset XXX
107 opens the tun interface, configures it then goes into the background.
108 The link is not brought up until outgoing data is detected on the tun
109 interface at which point
111 attempts to bring up the link.
112 Packets received (including the first one) while
114 is trying to bring the link up will remain queued for a default of
124 must be given on the command line (see below) and a
126 must be done in the system profile that specifies a peer IP address to
127 use when configuring the interface.
130 is usually appropriate.
134 .Pa /usr/share/examples/ppp/ppp.conf.sample
139 attempts to establish a connection with the peer immediately.
142 goes into the background and the parent process returns an exit code
146 exits with a non-zero result.
150 attempts to establish a connection with the peer immediately, but never
152 The link is created in background mode.
153 This is useful if you wish to control
155 invocation from another process.
157 This is used for communicating over an already established connection,
158 usually when receiving incoming connections accepted by
163 line and uses descriptor 0 as the link.
165 will also ignore any configured chat scripts unless the
167 option has been enabled.
169 If callback is configured,
173 information when dialing back.
175 This option is designed for machines connected with a dedicated
178 will always keep the device open and will ignore any configured
179 chat scripts unless the
181 option has been enabled.
183 This mode is equivalent to
187 will bring the link back up any time it is dropped for any reason.
189 This is a no-op, and gives the same behaviour as if none of the above
190 modes have been specified.
192 loads any sections specified on the command line then provides an
196 One or more configuration entries or systems
198 .Pa /etc/ppp/ppp.conf )
199 may also be specified on the command line.
204 .Pa /etc/ppp/ppp.conf
205 at startup, followed by each of the systems specified on the command line.
208 .It Provides an interactive user interface.
209 Using its command mode, the user can
210 easily enter commands to establish the connection with the remote end, check
211 the status of connection and close the connection.
212 All functions can also be optionally password protected for security.
213 .It Supports both manual and automatic dialing.
214 Interactive mode has a
216 command which enables you to talk to the device directly.
217 When you are connected to the remote peer and it starts to talk
220 detects it and switches to packet mode automatically.
222 determined the proper sequence for connecting with the remote host, you
223 can write a chat script to {define} the necessary dialing and login
224 procedure for later convenience.
225 .It Supports on-demand dialup capability.
230 will act as a daemon and wait for a packet to be sent over the
233 When this happens, the daemon automatically dials and establishes the
235 In almost the same manner
237 mode (direct-dial mode) also automatically dials and establishes the
239 However, it differs in that it will dial the remote site
240 any time it detects the link is down, even if there are no packets to be
242 This mode is useful for full-time connections where we worry less
243 about line charges and more about being connected full time.
246 mode is also available.
247 This mode is targeted at a dedicated link between two machines.
249 will never voluntarily quit from dedicated mode - you must send it the
251 command via its diagnostic socket.
254 will force an LCP renegotiation, and a
256 will force it to exit.
257 .It Supports client callback.
259 can use either the standard LCP callback protocol or the Microsoft
260 CallBack Control Protocol (ftp://ftp.microsoft.com/developr/rfc/cbcp.txt).
261 .It Supports NAT or packet aliasing.
262 Packet aliasing (a.k.a.\& IP masquerading) allows computers on a
263 private, unregistered network to access the Internet.
266 host acts as a masquerading gateway.
267 IP addresses as well as TCP and
268 UDP port numbers are NAT'd for outgoing packets and de-NAT'd for
270 .It Supports background PPP connections.
271 In background mode, if
273 successfully establishes the connection, it will become a daemon.
274 Otherwise, it will exit with an error.
275 This allows the setup of
276 scripts that wish to execute certain commands only if the connection
277 is successfully established.
278 .It Supports server-side PPP connections.
281 acts as server which accepts incoming
283 connections on stdin/stdout.
284 .It "Supports PAP and CHAP (rfc 1994, 2433 and 2759) authentication.
285 With PAP or CHAP, it is possible to skip the Unix style
287 procedure, and use the
289 protocol for authentication instead.
290 If the peer requests Microsoft CHAP authentication and
292 is compiled with DES support, an appropriate MD4/DES response will be
294 .It Supports RADIUS (rfc 2138 & 2548) authentication.
295 An extension to PAP and CHAP,
302 allows authentication information to be stored in a central or
303 distributed database along with various per-user framed connection
305 ifdef({LOCALRAD},{},{If
307 is available at compile time,
311 requests when configured to do so.
313 .It Supports Proxy Arp.
315 can be configured to make one or more proxy arp entries on behalf of
317 This allows routing from the peer to the LAN without
318 configuring each machine on that LAN.
319 .It Supports packet filtering.
320 User can {define} four kinds of filters: the
322 filter for incoming packets, the
324 filter for outgoing packets, the
326 filter to {define} a dialing trigger packet and the
328 filter for keeping a connection alive with the trigger packet.
329 .It Tunnel driver supports bpf.
332 to check the packet flow over the
335 .It Supports PPP over TCP and PPP over UDP.
336 If a device name is specified as
337 .Em host Ns No : Ns Em port Ns
342 will open a TCP or UDP connection for transporting data rather than using a
343 conventional serial device.
344 UDP connections force
346 into synchronous mode.
347 .It Supports PPP over Ethernet (rfc 2516).
350 is given a device specification of the format
351 .No PPPoE: Ns Ar iface Ns Xo
352 .Op \&: Ns Ar provider Ns
366 On systems that do not support
368 an external program such as
371 .It "Supports IETF draft Predictor-1 (rfc 1978) and DEFLATE (rfc 1979) compression."
373 supports not only VJ-compression but also Predictor-1 and DEFLATE compression.
374 Normally, a modem has built-in compression (e.g., v42.bis) and the system
375 may receive higher data rates from it as a result of such compression.
376 While this is generally a good thing in most other situations, this
377 higher speed data imposes a penalty on the system by increasing the
378 number of serial interrupts the system has to process in talking to the
379 modem and also increases latency.
380 Unlike VJ-compression, Predictor-1 and DEFLATE compression pre-compresses
382 network traffic flowing through the link, thus reducing overheads to a
384 .It Supports Microsoft's IPCP extensions (rfc 1877).
385 Name Server Addresses and NetBIOS Name Server Addresses can be negotiated
386 with clients using the Microsoft
388 stack (i.e., Win95, WinNT)
389 .It Supports Multi-link PPP (rfc 1990)
390 It is possible to configure
392 to open more than one physical connection to the peer, combining the
393 bandwidth of all links for better throughput.
394 .It Supports MPPE (draft-ietf-pppext-mppe)
395 MPPE is Microsoft Point to Point Encryption scheme.
396 It is possible to configure
398 to participate in Microsoft's Windows VPN.
401 can only get encryption keys from CHAP 81 authentication.
403 must be compiled with DES for MPPE to operate.
404 .It Supports IPV6CP (rfc 2023).
405 An IPv6 connection can be made in addition to or instead of the normal
418 will not run if the invoking user id is not zero.
419 This may be overridden by using the
422 .Pa /etc/ppp/ppp.conf .
423 When running as a normal user,
425 switches to user id 0 in order to alter the system routing table, set up
426 system lock files and read the ppp configuration files.
427 All external commands (executed via the "shell" or "!bg" commands) are executed
428 as the user id that invoked
432 logging facility if you are interested in what exactly is done as user id
437 you may need to deal with some initial configuration details.
440 Make sure that your system has a group named
444 file and that the group contains the names of all users expected to use
448 manual page for details.
449 Each of these users must also be given access using the
452 .Pa /etc/ppp/ppp.conf .
459 A common log file name is
460 .Pa /var/log/ppp.log .
461 To make output go to this file, put the following lines in the
464 .Bd -literal -offset indent
466 *.*<TAB>/var/log/ppp.log
469 It is possible to have more than one
471 log file by creating a link to the
479 .Bd -literal -offset indent
481 *.*<TAB>/var/log/ppp0.log
485 .Pa /etc/syslog.conf .
486 Do not forget to send a
491 .Pa /etc/syslog.conf .
493 Although not strictly relevant to
495 operation, you should configure your resolver so that it works correctly.
496 This can be done by configuring a local DNS
499 or by adding the correct
502 .Pa /etc/resolv.conf .
505 manual page for details.
507 Alternatively, if the peer supports it,
509 can be configured to ask the peer for the nameserver address(es) and to
517 commands below for details.
520 In the following examples, we assume that your machine name is
526 above) with no arguments, you are presented with a prompt:
527 .Bd -literal -offset indent
533 part of your prompt should always be in upper case.
534 If it is in lower case, it means that you must supply a password using the
537 This only ever happens if you connect to a running version of
539 and have not authenticated yourself using the correct password.
541 You can start by specifying the device name and speed:
542 .Bd -literal -offset indent
543 ppp ON awfulhak> set device /dev/cuad0
544 ppp ON awfulhak> set speed 38400
547 Normally, hardware flow control (CTS/RTS) is used.
549 certain circumstances (as may happen when you are connected directly
550 to certain PPP-capable terminal servers), this may result in
552 hanging as soon as it tries to write data to your communications link
553 as it is waiting for the CTS (clear to send) signal - which will never
555 Thus, if you have a direct line and cannot seem to make a
556 connection, try turning CTS/RTS off with
558 If you need to do this, check the
560 description below too - you will probably need to
561 .Dq set accmap 000a0000 .
563 Usually, parity is set to
568 Parity is a rather archaic error checking mechanism that is no
569 longer used because modern modems do their own error checking, and most
570 link-layer protocols (that is what
572 is) use much more reliable checking mechanisms.
573 Parity has a relatively
574 huge overhead (a 12.5% increase in traffic) and as a result, it is always
581 However, some ISPs (Internet Service Providers) may use
582 specific parity settings at connection time (before
585 Notably, Compuserve insist on even parity when logging in:
586 .Bd -literal -offset indent
587 ppp ON awfulhak> set parity even
590 You can now see what your current device settings look like:
591 .Bd -literal -offset indent
592 ppp ON awfulhak> show physical
596 Link Type: interactive
602 Device List: /dev/cuad0
603 Characteristics: 38400bps, cs8, even parity, CTS/RTS on
606 0 octets in, 0 octets out
611 The term command can now be used to talk directly to the device:
612 .Bd -literal -offset indent
613 ppp ON awfulhak> term
619 Password: myisppassword
623 When the peer starts to talk in
626 detects this automatically and returns to command mode.
627 .Bd -literal -offset indent
628 ppp ON awfulhak> # No link has been established
629 Ppp ON awfulhak> # We've connected & finished LCP
630 PPp ON awfulhak> # We've authenticated
631 PPP ON awfulhak> # We've agreed IP numbers
634 If it does not, it is probable that the peer is waiting for your end to
640 configuration packets to the peer, use the
642 command to drop out of terminal mode and enter packet mode.
644 If you never even receive a login prompt, it is quite likely that the
645 peer wants to use PAP or CHAP authentication instead of using Unix-style
646 login/password authentication.
647 To set things up properly, drop back to
648 the prompt and set your authentication name and key, then reconnect:
649 .Bd -literal -offset indent
651 ppp ON awfulhak> set authname myispusername
652 ppp ON awfulhak> set authkey myisppassword
653 ppp ON awfulhak> term
660 You may need to tell ppp to initiate negotiations with the peer here too:
661 .Bd -literal -offset indent
663 ppp ON awfulhak> # No link has been established
664 Ppp ON awfulhak> # We've connected & finished LCP
665 PPp ON awfulhak> # We've authenticated
666 PPP ON awfulhak> # We've agreed IP numbers
669 You are now connected!
672 in the prompt has changed to capital letters to indicate that you have
674 If only some of the three Ps go uppercase, wait until
675 either everything is uppercase or lowercase.
676 If they revert to lowercase, it means that
678 could not successfully negotiate with the peer.
679 A good first step for troubleshooting at this point would be to
680 .Bd -literal -offset indent
681 ppp ON awfulhak> set log local phase lcp ipcp
687 command description below for further details.
688 If things fail at this point,
689 it is quite important that you turn logging on and try again.
691 important that you note any prompt changes and report them to anyone trying
694 When the link is established, the show command can be used to see how
696 .Bd -literal -offset indent
697 PPP ON awfulhak> show physical
698 * Modem related information is shown here *
699 PPP ON awfulhak> show ccp
700 * CCP (compression) related information is shown here *
701 PPP ON awfulhak> show lcp
702 * LCP (line control) related information is shown here *
703 PPP ON awfulhak> show ipcp
704 * IPCP (IP) related information is shown here *
705 PPP ON awfulhak> show ipv6cp
706 * IPV6CP (IPv6) related information is shown here *
707 PPP ON awfulhak> show link
708 * Link (high level) related information is shown here *
709 PPP ON awfulhak> show bundle
710 * Logical (high level) connection related information is shown here *
713 At this point, your machine has a host route to the peer.
715 that you can only make a connection with the host on the other side
717 If you want to add a default route entry (telling your
718 machine to send all packets without another routing entry to the other
721 link), enter the following command:
722 .Bd -literal -offset indent
723 PPP ON awfulhak> add default HISADDR
728 represents the IP address of the connected peer.
731 command fails due to an existing route, you can overwrite the existing
733 .Bd -literal -offset indent
734 PPP ON awfulhak> add! default HISADDR
737 This command can also be executed before actually making the connection.
738 If a new IP address is negotiated at connection time,
740 will update your default route accordingly.
742 You can now use your network applications (ping, telnet, ftp, etc.)
743 in other windows or terminals on your machine.
744 If you wish to reuse the current terminal, you can put
746 into the background using your standard shell suspend and background
754 section for details on all available commands.
755 .Sh AUTOMATIC DIALING
756 To use automatic dialing, you must prepare some Dial and Login chat scripts.
757 See the example definitions in
758 .Pa /usr/share/examples/ppp/ppp.conf.sample
760 .Pa /etc/ppp/ppp.conf
762 Each line contains one comment, inclusion, label or command:
765 A line starting with a
767 character is treated as a comment line.
768 Leading whitespace are ignored when identifying comment lines.
770 An inclusion is a line beginning with the word
772 It must have one argument - the file to {include}.
774 .Dq {!include} ~/.ppp.conf
775 for compatibility with older versions of
778 A label name starts in the first column and is followed by
782 A command line must contain a space or tab in the first column.
784 A string starting with the
786 character is substituted with the value of the environment variable by
788 Likewise, a string starting with the
790 character is substituted with the full path to the home directory of
791 the user account by the same name, and the
793 character by itself is substituted with the full path to the home directory
795 If you want to include a literal
799 character in a command or argument, enclose them in double quotes, e.g.,
800 .Bd -literal -offset indent
801 set password "pa$ss~word"
806 .Pa /etc/ppp/ppp.conf
807 file should consist of at least a
810 This section is always executed.
811 It should also contain
812 one or more sections, named according to their purpose, for example,
814 would represent your ISP, and
816 would represent an incoming
819 You can now specify the destination label name when you invoke
821 Commands associated with the
823 label are executed, followed by those associated with the destination
827 is started with no arguments, the
829 section is still executed.
830 The load command can be used to manually load a section from the
831 .Pa /etc/ppp/ppp.conf
833 .Bd -literal -offset indent
834 ppp ON awfulhak> load MyISP
837 Note, no action is taken by
839 after a section is loaded, whether it is the result of passing a label on
840 the command line or using the
843 Only the commands specified for that label in the configuration
845 However, when invoking
852 switches, the link mode tells
854 to establish a connection.
857 command below for further details.
859 Once the connection is made, the
861 portion of the prompt will change to
863 .Bd -literal -offset indent
866 ppp ON awfulhak> dial
872 The Ppp prompt indicates that
874 has entered the authentication phase.
875 The PPp prompt indicates that
877 has entered the network phase.
878 The PPP prompt indicates that
880 has successfully negotiated a network layer protocol and is in
884 .Pa /etc/ppp/ppp.linkup
885 file is available, its contents are executed
888 connection is established.
892 .Pa /usr/share/examples/ppp/ppp.conf.sample
893 which runs a script in the background after the connection is established
898 commands below for a description of possible substitution strings).
899 Similarly, when a connection is closed, the contents of the
900 .Pa /etc/ppp/ppp.linkdown
902 Both of these files have the same format as
903 .Pa /etc/ppp/ppp.conf .
905 In previous versions of
907 it was necessary to re-add routes such as the default route in the
913 where all routes that contain the
919 literals will automatically be updated when the values of these variables
921 .Sh BACKGROUND DIALING
922 If you want to establish a connection using
924 non-interactively (such as from a
928 job) you should use the
935 attempts to establish the connection immediately.
937 numbers are specified, each phone number will be tried once.
938 If the attempt fails,
940 exits immediately with a non-zero exit code.
943 becomes a daemon, and returns an exit status of zero to its caller.
944 The daemon exits automatically if the connection is dropped by the
945 remote system, or it receives a
949 Demand dialing is enabled with the
954 You must also specify the destination label in
955 .Pa /etc/ppp/ppp.conf
959 command to {define} the remote peers IP address.
961 .Pa /usr/share/examples/ppp/ppp.conf.sample )
962 .Bd -literal -offset indent
972 runs as a daemon but you can still configure or examine its
973 configuration by using the
976 .Pa /etc/ppp/ppp.conf ,
978 .Dq Li "set server +3000 mypasswd" )
979 and connecting to the diagnostic port as follows:
980 .Bd -literal -offset indent
981 # pppctl 3000 (assuming tun0)
983 PPP ON awfulhak> show who
984 tcp (127.0.0.1:1028) *
989 command lists users that are currently connected to
992 If the diagnostic socket is closed or changed to a different
993 socket, all connections are immediately dropped.
997 mode, when an outgoing packet is detected,
999 will perform the dialing action (chat script) and try to connect
1003 mode, the dialing action is performed any time the line is found
1005 If the connect fails, the default behaviour is to wait 30 seconds
1006 and then attempt to connect when another outgoing packet is detected.
1007 This behaviour can be changed using the
1011 .No set redial Ar secs Ns Xo
1014 .Oc Ns Op . Ns Ar next
1018 .Bl -tag -width attempts -compact
1020 is the number of seconds to wait before attempting
1022 If the argument is the literal string
1024 the delay period is a random value between 1 and 30 seconds inclusive.
1026 is the number of seconds that
1028 should be incremented each time a new dial attempt is made.
1029 The timeout reverts to
1031 only after a successful connection is established.
1032 The default value for
1036 is the maximum number of times
1040 The default value for
1044 is the number of seconds to wait before attempting
1045 to dial the next number in a list of numbers (see the
1048 The default is 3 seconds.
1049 Again, if the argument is the literal string
1051 the delay period is a random value between 1 and 30 seconds.
1053 is the maximum number of times to try to connect for each outgoing packet
1054 that triggers a dial.
1055 The previous value is unchanged if this parameter is omitted.
1056 If a value of zero is specified for
1059 will keep trying until a connection is made.
1063 .Bd -literal -offset indent
1067 will attempt to connect 4 times for each outgoing packet that causes
1068 a dial attempt with a 3 second delay between each number and a 10 second
1069 delay after all numbers have been tried.
1070 If multiple phone numbers
1071 are specified, the total number of attempts is still 4 (it does not
1072 attempt each number 4 times).
1076 .Bd -literal -offset indent
1077 set redial 10+10-5.3 20
1082 to attempt to connect 20 times.
1083 After the first attempt,
1085 pauses for 10 seconds.
1086 After the next attempt it pauses for 20 seconds
1087 and so on until after the sixth attempt it pauses for 1 minute.
1088 The next 14 pauses will also have a duration of one minute.
1091 connects, disconnects and fails to connect again, the timeout starts again
1094 Modifying the dial delay is very useful when running
1098 mode on both ends of the link.
1099 If each end has the same timeout,
1100 both ends wind up calling each other at the same time if the link
1101 drops and both ends have packets queued.
1102 At some locations, the serial link may not be reliable, and carrier
1103 may be lost at inappropriate times.
1104 It is possible to have
1106 redial should carrier be unexpectedly lost during a session.
1107 .Bd -literal -offset indent
1108 set reconnect timeout ntries
1113 to re-establish the connection
1115 times on loss of carrier with a pause of
1117 seconds before each try.
1119 .Bd -literal -offset indent
1125 that on an unexpected loss of carrier, it should wait
1127 seconds before attempting to reconnect.
1128 This may happen up to
1133 The default value of ntries is zero (no reconnect).
1134 Care should be taken with this option.
1135 If the local timeout is slightly
1136 longer than the remote timeout, the reconnect feature will always be
1137 triggered (up to the given number of times) after the remote side
1138 times out and hangs up.
1139 NOTE: In this context, losing too many LQRs constitutes a loss of
1140 carrier and will trigger a reconnect.
1143 flag is specified, all phone numbers are dialed at most once until
1144 a connection is made.
1145 The next number redial period specified with the
1147 command is honoured, as is the reconnect tries value.
1149 value is less than the number of phone numbers specified, not all
1150 the specified numbers will be tried.
1151 To terminate the program, type
1152 .Bd -literal -offset indent
1153 PPP ON awfulhak> close
1154 ppp ON awfulhak> quit all
1159 command will terminate the
1163 connection but not the
1171 .Sh RECEIVING INCOMING PPP CONNECTIONS (Method 1)
1172 To handle an incoming
1174 connection request, follow these steps:
1177 Make sure the modem and (optionally)
1179 is configured correctly.
1180 .Bl -bullet -compact
1182 Use Hardware Handshake (CTS/RTS) for flow control.
1184 Modem should be set to NO echo back (ATE0) and NO results string (ATQ1).
1192 on the port where the modem is attached.
1195 .Dl ttyd1 Qo /usr/libexec/getty std.38400 Qc dialup on secure
1197 Do not forget to send a
1201 process to start the
1206 It is usually also necessary to train your modem to the same DTR speed
1208 .Bd -literal -offset indent
1210 ppp ON awfulhak> set device /dev/cuad1
1211 ppp ON awfulhak> set speed 38400
1212 ppp ON awfulhak> term
1213 deflink: Entering terminal mode on /dev/cuad1
1224 ppp ON awfulhak> quit
1228 .Pa /usr/local/bin/ppplogin
1229 file with the following contents:
1230 .Bd -literal -offset indent
1232 exec /usr/sbin/ppp -direct incoming
1239 work with stdin and stdout.
1242 to connect to a configured diagnostic port, in the same manner as with
1248 section must be set up in
1249 .Pa /etc/ppp/ppp.conf .
1253 section contains the
1255 command as appropriate.
1257 Prepare an account for the incoming user.
1259 ppp:xxxx:66:66:PPP Login User:/home/ppp:/usr/local/bin/ppplogin
1262 Refer to the manual entries for
1268 Support for IPCP Domain Name Server and NetBIOS Name Server negotiation
1269 can be enabled using the
1274 Refer to their descriptions below.
1276 .Sh RECEIVING INCOMING PPP CONNECTIONS (Method 2)
1277 This method differs in that we use
1279 to authenticate the connection rather than
1283 Configure your default section in
1285 with automatic ppp recognition by specifying the
1290 :pp=/usr/local/bin/ppplogin:\\
1294 Configure your serial device(s), enable a
1297 .Pa /usr/local/bin/ppplogin
1298 as in the first three steps for method 1 above.
1306 .Pa /etc/ppp/ppp.conf
1309 label (or whatever label
1314 .Pa /etc/ppp/ppp.secret
1315 for each incoming user:
1324 detects a ppp connection (by recognising the HDLC frame headers), it runs
1325 .Dq /usr/local/bin/ppplogin .
1329 that either PAP or CHAP are enabled as above.
1330 If they are not, you are
1331 allowing anybody to establish a ppp session with your machine
1333 a password, opening yourself up to all sorts of potential attacks.
1334 .Sh AUTHENTICATING INCOMING CONNECTIONS
1335 Normally, the receiver of a connection requires that the peer
1336 authenticates itself.
1337 This may be done using
1339 but alternatively, you can use PAP or CHAP.
1340 CHAP is the more secure of the two, but some clients may not support it.
1341 Once you decide which you wish to use, add the command
1345 to the relevant section of
1348 You must then configure the
1349 .Pa /etc/ppp/ppp.secret
1351 This file contains one line per possible client, each line
1352 containing up to five fields:
1355 .Ar hisaddr Op Ar label Op Ar callback-number
1362 specify the client username and password.
1367 and PAP is being used,
1369 will look up the password database
1371 when authenticating.
1372 If the client does not offer a suitable response based on any
1373 .Ar name Ns No / Ns Ar key
1376 authentication fails.
1378 If authentication is successful,
1381 is used when negotiating IP numbers.
1384 command for details.
1386 If authentication is successful and
1388 is specified, the current system label is changed to match the given
1390 This will change the subsequent parsing of the
1396 If authentication is successful and
1402 the client will be called back on the given number.
1403 If CBCP is being used,
1405 may also contain a list of numbers or a
1410 The value will be used in
1412 subsequent CBCP phase.
1413 .Sh PPP OVER TCP and UDP (a.k.a Tunnelling)
1416 over a serial link, it is possible to
1417 use a TCP connection instead by specifying the host, port and protocol as the
1420 .Dl set device ui-gate:6669/tcp
1422 Instead of opening a serial device,
1424 will open a TCP connection to the given machine on the given
1426 It should be noted however that
1428 does not use the telnet protocol and will be unable to negotiate
1429 with a telnet server.
1430 You should set up a port for receiving this
1432 connection on the receiving machine (ui-gate).
1433 This is done by first updating
1435 to name the service:
1437 .Dl ppp-in 6669/tcp # Incoming PPP connections over TCP
1443 how to deal with incoming connections on that port:
1445 .Dl ppp-in stream tcp nowait root /usr/sbin/ppp ppp -direct ppp-in
1447 Do not forget to send a
1451 after you have updated
1452 .Pa /etc/inetd.conf .
1453 Here, we use a label named
1456 .Pa /etc/ppp/ppp.conf
1457 on ui-gate (the receiver) should contain the following:
1458 .Bd -literal -offset indent
1461 set ifaddr 10.0.4.1 10.0.4.2
1465 .Pa /etc/ppp/ppp.linkup
1467 .Bd -literal -offset indent
1469 add 10.0.1.0/24 HISADDR
1472 It is necessary to put the
1476 to ensure that the route is only added after
1478 has negotiated and assigned addresses to its interface.
1480 You may also want to enable PAP or CHAP for security.
1481 To enable PAP, add the following line:
1482 .Bd -literal -offset indent
1486 You will also need to create the following entry in
1487 .Pa /etc/ppp/ppp.secret :
1488 .Bd -literal -offset indent
1489 MyAuthName MyAuthPasswd
1496 the password is looked up in the
1501 .Pa /etc/ppp/ppp.conf
1502 on awfulhak (the initiator) should contain the following:
1503 .Bd -literal -offset indent
1506 set device ui-gate:ppp-in/tcp
1509 set log Phase Chat Connect hdlc LCP IPCP IPV6CP CCP tun
1510 set ifaddr 10.0.4.2 10.0.4.1
1513 with the route setup in
1514 .Pa /etc/ppp/ppp.linkup :
1515 .Bd -literal -offset indent
1517 add 10.0.2.0/24 HISADDR
1520 Again, if you are enabling PAP, you will also need this in the
1521 .Pa /etc/ppp/ppp.conf
1523 .Bd -literal -offset indent
1524 set authname MyAuthName
1525 set authkey MyAuthKey
1528 We are assigning the address of 10.0.4.1 to ui-gate, and the address
1529 10.0.4.2 to awfulhak.
1530 To open the connection, just type
1532 .Dl awfulhak # ppp -background ui-gate
1534 The result will be an additional "route" on awfulhak to the
1535 10.0.2.0/24 network via the TCP connection, and an additional
1536 "route" on ui-gate to the 10.0.1.0/24 network.
1537 The networks are effectively bridged - the underlying TCP
1538 connection may be across a public network (such as the
1541 traffic is conceptually encapsulated
1542 (although not packet by packet) inside the TCP stream between
1545 The major disadvantage of this mechanism is that there are two
1546 "guaranteed delivery" mechanisms in place - the underlying TCP
1547 stream and whatever protocol is used over the
1549 link - probably TCP again.
1550 If packets are lost, both levels will
1551 get in each others way trying to negotiate sending of the missing
1554 To avoid this overhead, it is also possible to do all this using
1555 UDP instead of TCP as the transport by simply changing the protocol
1556 from "tcp" to "udp".
1557 When using UDP as a transport,
1559 will operate in synchronous mode.
1560 This is another gain as the incoming
1561 data does not have to be rearranged into packets.
1563 Care should be taken when adding a default route through a tunneled
1565 It is quite common for the default route
1567 .Pa /etc/ppp/ppp.linkup )
1568 to end up routing the link's TCP connection through the tunnel,
1569 effectively garrotting the connection.
1570 To avoid this, make sure you add a static route for the benefit of
1572 .Bd -literal -offset indent
1575 set device ui-gate:ppp-in/tcp
1582 is the IP number that your route to
1586 When routing your connection accross a public network such as the Internet,
1587 it is preferable to encrypt the data.
1588 This can be done with the help of the MPPE protocol, although currently this
1589 means that you will not be able to also compress the traffic as MPPE is
1590 implemented as a compression layer (thank Microsoft for this).
1591 To enable MPPE encryption, add the following lines to
1592 .Pa /etc/ppp/ppp.conf
1594 .Bd -literal -offset indent
1596 disable deflate pred1
1600 ensuring that you have put the requisite entry in
1601 .Pa /etc/ppp/ppp.secret
1602 (MSCHAPv2 is challenge based, so
1606 MSCHAPv2 and MPPE are accepted by default, so the client end should work
1607 without any additional changes (although ensure you have
1612 .Sh NETWORK ADDRESS TRANSLATION (PACKET ALIASING)
1615 command line option enables network address translation (a.k.a.\& packet
1619 host to act as a masquerading gateway for other computers over
1620 a local area network.
1621 Outgoing IP packets are NAT'd so that they appear to come from the
1623 host, and incoming packets are de-NAT'd so that they are routed
1624 to the correct machine on the local area network.
1625 NAT allows computers on private, unregistered subnets to have Internet
1626 access, although they are invisible from the outside world.
1629 operation should first be verified with network address translation disabled.
1632 option should be switched on, and network applications (web browser,
1637 should be checked on the
1640 Finally, the same or similar applications should be checked on other
1641 computers in the LAN.
1642 If network applications work correctly on the
1644 host, but not on other machines in the LAN, then the masquerading
1645 software is working properly, but the host is either not forwarding
1646 or possibly receiving IP packets.
1647 Check that IP forwarding is enabled in
1649 and that other machines have designated the
1651 host as the gateway for the LAN.
1652 .Sh PACKET FILTERING
1653 This implementation supports packet filtering.
1654 There are four kinds of
1664 Here are the basics:
1667 A filter definition has the following syntax:
1676 .Ar src_addr Ns Op / Ns Ar width
1677 .Op Ar dst_addr Ns Op / Ns Ar width
1679 .Ar [ proto Op src Ar cmp port
1684 .Op timeout Ar secs ]
1696 is a numeric value between
1700 specifying the rule number.
1701 Rules are specified in numeric order according to
1712 in which case, if a given packet matches the rule, the associated action
1713 is taken immediately.
1715 can also be specified as
1717 to clear the action associated with that particular rule, or as a new
1718 rule number greater than the current rule.
1719 In this case, if a given
1720 packet matches the current rule, the packet will next be matched against
1721 the new rule number (rather than the next rule number).
1725 may optionally be followed with an exclamation mark
1729 to reverse the sense of the following match.
1731 .Op Ar src_addr Ns Op / Ns Ar width
1733 .Op Ar dst_addr Ns Op / Ns Ar width
1734 are the source and destination IP number specifications.
1737 is specified, it gives the number of relevant netmask bits,
1738 allowing the specification of an address range.
1744 may be given the values
1750 (refer to the description of the
1752 command for a description of these values).
1753 When these values are used,
1754 the filters will be updated any time the values change.
1755 This is similar to the behaviour of the
1760 may be any protocol from
1769 meaning less-than, equal and greater-than respectively.
1771 can be specified as a numeric port or by service name from
1779 flags are only allowed when
1783 and represent the TH_ACK, TH_SYN and TH_FIN or TH_RST TCP flags respectively.
1785 The timeout value adjusts the current idle timeout to at least
1788 If a timeout is given in the alive filter as well as in the in/out
1789 filter, the in/out value is used.
1790 If no timeout is given, the default timeout (set using
1792 and defaulting to 180 seconds) is used.
1796 Each filter can hold up to 40 rules, starting from rule 0.
1797 The entire rule set is not effective until rule 0 is defined,
1798 i.e., the default is to allow everything through.
1800 If no rule in a defined set of rules matches a packet, that packet will
1801 be discarded (blocked).
1802 If there are no rules in a given filter, the packet will be permitted.
1804 It is possible to filter based on the payload of UDP frames where those
1810 .Ar filter-decapsulation
1811 option below for further details.
1814 .Dq set filter Ar name No -1
1819 .Pa /usr/share/examples/ppp/ppp.conf.sample .
1820 .Sh SETTING THE IDLE TIMER
1821 To check/set the idle timer, use the
1826 .Bd -literal -offset indent
1827 ppp ON awfulhak> set timeout 600
1830 The timeout period is measured in seconds, the default value for which
1833 To disable the idle timer function, use the command
1834 .Bd -literal -offset indent
1835 ppp ON awfulhak> set timeout 0
1842 modes, the idle timeout is ignored.
1845 mode, when the idle timeout causes the
1850 program itself remains running.
1851 Another trigger packet will cause it to attempt to re-establish the link.
1852 .Sh PREDICTOR-1 and DEFLATE COMPRESSION
1854 supports both Predictor type 1 and deflate compression.
1857 will attempt to use (or be willing to accept) both compression protocols
1858 when the peer agrees
1860 The deflate protocol is preferred by
1866 commands if you wish to disable this functionality.
1868 It is possible to use a different compression algorithm in each direction
1869 by using only one of
1873 (assuming that the peer supports both algorithms).
1875 By default, when negotiating DEFLATE,
1877 will use a window size of 15.
1880 command if you wish to change this behaviour.
1882 A special algorithm called DEFLATE24 is also available, and is disabled
1883 and denied by default.
1884 This is exactly the same as DEFLATE except that
1885 it uses CCP ID 24 to negotiate.
1888 to successfully negotiate DEFLATE with
1891 .Sh CONTROLLING IP ADDRESS
1894 uses IPCP to negotiate IP addresses.
1895 Each side of the connection
1896 specifies the IP address that it is willing to use, and if the requested
1897 IP address is acceptable then
1899 returns an ACK to the requester.
1902 returns NAK to suggest that the peer use a different IP address.
1904 both sides of the connection agree to accept the received request (and
1905 send an ACK), IPCP is set to the open state and a network level connection
1907 To control this IPCP behaviour, this implementation has the
1909 command for defining the local and remote IP address:
1910 .Bd -ragged -offset indent
1911 .No set ifaddr Oo Ar src_addr Ns
1913 .Oo Ar dst_addr Ns Op / Ns Ar \&nn
1923 is the IP address that the local side is willing to use,
1925 is the IP address which the remote side should use and
1927 is the netmask that should be used.
1929 defaults to the current
1932 defaults to 0.0.0.0, and
1934 defaults to whatever mask is appropriate for
1936 It is only possible to make
1938 smaller than the default.
1939 The usual value is 255.255.255.255, as
1940 most kernels ignore the netmask of a POINTOPOINT interface.
1944 implementations require that the peer negotiates a specific IP
1947 If this is the case,
1949 may be used to specify this IP number.
1950 This will not affect the
1951 routing table unless the other side agrees with this proposed number.
1952 .Bd -literal -offset indent
1953 set ifaddr 192.244.177.38 192.244.177.2 255.255.255.255 0.0.0.0
1956 The above specification means:
1958 .Bl -bullet -compact
1960 I will first suggest that my IP address should be 0.0.0.0, but I
1961 will only accept an address of 192.244.177.38.
1963 I strongly insist that the peer uses 192.244.177.2 as his own
1964 address and will not permit the use of any IP address but 192.244.177.2.
1965 When the peer requests another IP address, I will always suggest that
1966 it uses 192.244.177.2.
1968 The routing table entry will have a netmask of 0xffffffff.
1971 This is all fine when each side has a pre-determined IP address, however
1972 it is often the case that one side is acting as a server which controls
1973 all IP addresses and the other side should go along with it.
1974 In order to allow more flexible behaviour, the
1976 command allows the user to specify IP addresses more loosely:
1978 .Dl set ifaddr 192.244.177.38/24 192.244.177.2/20
1980 A number followed by a slash
1982 represents the number of bits significant in the IP address.
1983 The above example means:
1985 .Bl -bullet -compact
1987 I would like to use 192.244.177.38 as my address if it is possible, but I will
1988 also accept any IP address between 192.244.177.0 and 192.244.177.255.
1990 I would like to make him use 192.244.177.2 as his own address, but I will also
1991 permit him to use any IP address between 192.244.176.0 and
1994 As you may have already noticed, 192.244.177.2 is equivalent to saying
1997 As an exception, 0 is equivalent to 0.0.0.0/0, meaning that I have no
1998 preferred IP address and will obey the remote peers selection.
1999 When using zero, no routing table entries will be made until a connection
2002 192.244.177.2/0 means that I will accept/permit any IP address but I will
2003 suggest that 192.244.177.2 be used first.
2006 When negotiating IPv6 addresses, no control is given to the user.
2007 IPV6CP negotiation is fully automatic.
2008 .Sh CONNECTING WITH YOUR INTERNET SERVICE PROVIDER
2009 The following steps should be taken when connecting to your ISP:
2012 Describe your providers phone number(s) in the dial script using the
2015 This command allows you to set multiple phone numbers for
2016 dialing and redialing separated by either a pipe
2020 .Bd -ragged -offset indent
2021 .No set phone Ar telno Ns Xo
2022 .Oo \&| Ns Ar backupnumber
2023 .Oc Ns ... Ns Oo : Ns Ar nextnumber
2028 Numbers after the first in a pipe-separated list are only used if the
2029 previous number was used in a failed dial or login script.
2031 separated by a colon are used sequentially, irrespective of what happened
2032 as a result of using the previous number.
2034 .Bd -literal -offset indent
2035 set phone "1234567|2345678:3456789|4567890"
2038 Here, the 1234567 number is attempted.
2039 If the dial or login script fails,
2040 the 2345678 number is used next time, but *only* if the dial or login script
2042 On the dial after this, the 3456789 number is used.
2044 number is only used if the dial or login script using the 3456789 fails.
2045 If the login script of the 2345678 number fails, the next number is still the
2047 As many pipes and colons can be used as are necessary
2048 (although a given site would usually prefer to use either the pipe or the
2049 colon, but not both).
2050 The next number redial timeout is used between all numbers.
2051 When the end of the list is reached, the normal redial period is
2052 used before starting at the beginning again.
2053 The selected phone number is substituted for the \\\\T string in the
2055 command (see below).
2057 Set up your redial requirements using
2059 For example, if you have a bad telephone line or your provider is
2060 usually engaged (not so common these days), you may want to specify
2062 .Bd -literal -offset indent
2066 This says that up to 4 phone calls should be attempted with a pause of 10
2067 seconds before dialing the first number again.
2069 Describe your login procedure using the
2076 command is used to talk to your modem and establish a link with your
2078 .Bd -literal -offset indent
2079 set dial "ABORT BUSY ABORT NO\\\\sCARRIER TIMEOUT 4 \\"\\" \e
2080 ATZ OK-ATZ-OK ATDT\\\\T TIMEOUT 60 CONNECT"
2083 This modem "chat" string means:
2086 Abort if the string "BUSY" or "NO CARRIER" are received.
2088 Set the timeout to 4 seconds.
2095 If that is not received within the 4 second timeout, send ATZ
2098 Send ATDTxxxxxxx where xxxxxxx is the next number in the phone list from
2101 Set the timeout to 60.
2103 Wait for the CONNECT string.
2106 Once the connection is established, the login script is executed.
2107 This script is written in the same style as the dial script, but care should
2108 be taken to avoid having your password logged:
2109 .Bd -literal -offset indent
2110 set authkey MySecret
2111 set login "TIMEOUT 15 login:-\\\\r-login: awfulhak \e
2112 word: \\\\P ocol: PPP HELLO"
2115 This login "chat" string means:
2118 Set the timeout to 15 seconds.
2121 If it is not received, send a carriage return and expect
2126 Expect "word:" (the tail end of a "Password:" prompt).
2128 Send whatever our current
2132 Expect "ocol:" (the tail end of a "Protocol:" prompt).
2141 command is logged specially.
2146 logging is enabled, the actual password is not logged;
2150 Login scripts vary greatly between ISPs.
2151 If you are setting one up for the first time,
2152 .Em ENABLE CHAT LOGGING
2153 so that you can see if your script is behaving as you expect.
2159 to specify your serial line and speed, for example:
2160 .Bd -literal -offset indent
2161 set device /dev/cuad0
2165 Cuad0 is the first serial port on
2172 A speed of 115200 should be specified
2173 if you have a modem capable of bit rates of 28800 or more.
2174 In general, the serial speed should be about four times the modem speed.
2178 command to {define} the IP address.
2181 If you know what IP address your provider uses, then use it as the remote
2182 address (dst_addr), otherwise choose something like 10.0.0.2/0 (see below).
2184 If your provider has assigned a particular IP address to you, then use
2185 it as your address (src_addr).
2187 If your provider assigns your address dynamically, choose a suitably
2188 unobtrusive and unspecific IP number as your address.
2189 10.0.0.1/0 would be appropriate.
2190 The bit after the / specifies how many bits of the
2191 address you consider to be important, so if you wanted to insist on
2192 something in the class C network 1.2.3.0, you could specify 1.2.3.1/24.
2194 If you find that your ISP accepts the first IP number that you suggest,
2195 specify third and forth arguments of
2197 This will force your ISP to assign a number.
2198 (The third argument will
2199 be ignored as it is less restrictive than the default mask for your
2203 An example for a connection where you do not know your IP number or your
2204 ISPs IP number would be:
2205 .Bd -literal -offset indent
2206 set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0
2210 In most cases, your ISP will also be your default router.
2211 If this is the case, add the line
2212 .Bd -literal -offset indent
2217 .Pa /etc/ppp/ppp.conf
2219 .Pa /etc/ppp/ppp.linkup
2220 for setups that do not use
2226 to add a default route to whatever the peer address is
2227 (10.0.0.2 in this example).
2230 meaning that should the value of
2232 change, the route will be updated accordingly.
2234 If your provider requests that you use PAP/CHAP authentication methods, add
2235 the next lines to your
2236 .Pa /etc/ppp/ppp.conf
2238 .Bd -literal -offset indent
2240 set authkey MyPassword
2243 Both are accepted by default, so
2245 will provide whatever your ISP requires.
2247 It should be noted that a login script is rarely (if ever) required
2248 when PAP or CHAP are in use.
2250 Ask your ISP to authenticate your nameserver address(es) with the line
2251 .Bd -literal -offset indent
2257 do this if you are running a local DNS unless you also either use
2262 .Pa /etc/ppp/ppp.linkdown ,
2265 will simply circumvent its use by entering some nameserver lines in
2266 .Pa /etc/resolv.conf .
2270 .Pa /usr/share/examples/ppp/ppp.conf.sample
2272 .Pa /usr/share/examples/ppp/ppp.linkup.sample
2273 for some real examples.
2274 The pmdemand label should be appropriate for most ISPs.
2275 .Sh LOGGING FACILITY
2277 is able to generate the following log info either via
2279 or directly to the screen:
2281 .Bl -tag -width XXXXXXXXX -offset XXX -compact
2283 Enable all logging facilities.
2284 This generates a lot of log.
2285 The most common use of 'all' is as a basis, where you remove some facilities
2286 after enabling 'all' ('debug' and 'timer' are usually best disabled.)
2288 Dump async level packet in hex.
2290 Generate CBCP (CallBack Control Protocol) logs.
2292 Generate a CCP packet trace.
2300 chat script trace logs.
2302 Log commands executed either from the command line or any of the configuration
2305 Log Chat lines containing the string "CONNECT".
2307 Log debug information.
2309 Log DNS QUERY packets.
2311 Log packets permitted by the dial filter and denied by any filter.
2313 Dump HDLC packet in hex.
2315 Log all function calls specifically made as user id 0.
2317 Generate an IPCP packet trace.
2319 Generate an LCP packet trace.
2321 Generate LQR reports.
2323 Phase transition log output.
2325 Dump physical level packet in hex.
2327 Dump RADIUS information.
2328 RADIUS information resulting from the link coming up or down is logged at
2333 This log level is most useful for monitoring RADIUS alive information.
2335 Dump sync level packet in hex.
2337 Dump all TCP/IP packets.
2339 Log timer manipulation.
2341 Include the tun device on each log line.
2343 Output to the terminal device.
2344 If there is currently no terminal,
2345 output is sent to the log file using syslogs
2348 Output to both the terminal device
2349 and the log file using syslogs
2352 Output to the log file using
2358 command allows you to set the logging output level.
2359 Multiple levels can be specified on a single command line.
2360 The default is equivalent to
2363 It is also possible to log directly to the screen.
2364 The syntax is the same except that the word
2366 should immediately follow
2370 (i.e., only the un-maskable warning, error and alert output).
2372 If The first argument to
2373 .Dq set log Op local
2378 character, the current log levels are
2379 not cleared, for example:
2380 .Bd -literal -offset indent
2381 PPP ON awfulhak> set log phase
2382 PPP ON awfulhak> show log
2383 Log: Phase Warning Error Alert
2384 Local: Warning Error Alert
2385 PPP ON awfulhak> set log +tcp/ip -warning
2386 PPP ON awfulhak> set log local +command
2387 PPP ON awfulhak> show log
2388 Log: Phase TCP/IP Warning Error Alert
2389 Local: Command Warning Error Alert
2392 Log messages of level Warning, Error and Alert are not controllable
2394 .Dq set log Op local .
2398 level is special in that it will not be logged if it can be displayed
2402 deals with the following signals:
2403 .Bl -tag -width "USR2"
2405 Receipt of this signal causes the termination of the current connection
2409 to exit unless it is in
2414 .It HUP, TERM & QUIT
2421 to re-open any existing server socket, dropping all existing diagnostic
2423 Sockets that could not previously be opened will be retried.
2427 to close any existing server socket, dropping all existing diagnostic
2430 can still be used to re-open the socket.
2433 If you wish to use more than one physical link to connect to a
2435 peer, that peer must also understand the
2438 Refer to RFC 1990 for specification details.
2440 The peer is identified using a combination of his
2441 .Dq endpoint discriminator
2443 .Dq authentication id .
2444 Either or both of these may be specified.
2445 It is recommended that
2446 at least one is specified, otherwise there is no way of ensuring that
2447 all links are actually connected to the same peer program, and some
2448 confusing lock-ups may result.
2449 Locally, these identification variables are specified using the
2458 must be agreed in advance with the peer.
2460 Multi-link capabilities are enabled using the
2462 command (set maximum reconstructed receive unit).
2463 Once multi-link is enabled,
2465 will attempt to negotiate a multi-link connection with the peer.
2467 By default, only one
2472 To create more links, the
2475 This command will clone existing links, where all
2476 characteristics are the same except:
2479 The new link has its own name as specified on the
2486 Its mode may subsequently be changed using the
2490 The new link is in a
2495 A summary of all available links can be seen using the
2499 Once a new link has been created, command usage varies.
2500 All link specific commands must be prefixed with the
2502 command, specifying on which link the command is to be applied.
2503 When only a single link is available,
2505 is smart enough not to require the
2509 Some commands can still be used without specifying a link - resulting
2510 in an operation at the
2513 For example, once two or more links are available, the command
2515 will show CCP configuration and statistics at the multi-link level, and
2516 .Dq link deflink show ccp
2517 will show the same information at the
2521 Armed with this information, the following configuration might be used:
2523 .Bd -literal -offset indent
2527 set device /dev/cuad0 /dev/cuad1 /dev/cuad2
2528 set phone "123456789"
2529 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \\"\\" ATZ \e
2530 OK-AT-OK \\\\dATDT\\\\T TIMEOUT 45 CONNECT"
2532 set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0
2534 set authkey ppppassword
2537 clone 1,2,3 # Create 3 new links - duplicates of the default
2538 link deflink remove # Delete the default link (called ``deflink'')
2541 Note how all cloning is done at the end of the configuration.
2542 Usually, the link will be configured first, then cloned.
2543 If you wish all links
2544 to be up all the time, you can add the following line to the end of your
2547 .Bd -literal -offset indent
2548 link 1,2,3 set mode ddial
2551 If you want the links to dial on demand, this command could be used:
2553 .Bd -literal -offset indent
2554 link * set mode auto
2557 Links may be tied to specific names by removing the
2559 line above, and specifying the following after the
2563 .Bd -literal -offset indent
2564 link 1 set device /dev/cuad0
2565 link 2 set device /dev/cuad1
2566 link 3 set device /dev/cuad2
2571 command to see which commands require context (using the
2573 command), which have optional
2574 context and which should not have any context.
2580 mode with the peer, it creates a local domain socket in the
2583 This socket is used to pass link information (including
2584 the actual link file descriptor) between different
2589 ability to be run from a
2595 capability), without needing to have initial control of the serial
2599 negotiates multi-link mode, it will pass its open link to any
2600 already running process.
2601 If there is no already running process,
2603 will act as the master, creating the socket and listening for new
2605 .Sh PPP COMMAND LIST
2606 This section lists the available commands and their effect.
2607 They are usable either from an interactive
2609 session, from a configuration file or from a
2615 .It accept|deny|enable|disable Ar option....
2616 These directives tell
2618 how to negotiate the initial connection with the peer.
2621 has a default of either accept or deny and enable or disable.
2623 means that the option will be ACK'd if the peer asks for it.
2625 means that the option will be NAK'd if the peer asks for it.
2627 means that the option will be requested by us.
2629 means that the option will not be requested by us.
2632 may be one of the following:
2635 Default: Enabled and Accepted.
2636 ACFComp stands for Address and Control Field Compression.
2637 Non LCP packets will usually have an address
2638 field of 0xff (the All-Stations address) and a control field of
2639 0x03 (the Unnumbered Information command).
2641 negotiated, these two bytes are simply not sent, thus minimising
2648 Default: Disabled and Accepted.
2649 CHAP stands for Challenge Handshake Authentication Protocol.
2650 Only one of CHAP and PAP (below) may be negotiated.
2651 With CHAP, the authenticator sends a "challenge" message to its peer.
2652 The peer uses a one-way hash function to encrypt the
2653 challenge and sends the result back.
2654 The authenticator does the same, and compares the results.
2655 The advantage of this mechanism is that no
2656 passwords are sent across the connection.
2657 A challenge is made when the connection is first made.
2658 Subsequent challenges may occur.
2659 If you want to have your peer authenticate itself, you must
2662 .Pa /etc/ppp/ppp.conf ,
2663 and have an entry in
2664 .Pa /etc/ppp/ppp.secret
2667 When using CHAP as the client, you need only specify
2672 .Pa /etc/ppp/ppp.conf .
2673 CHAP is accepted by default.
2676 implementations use "MS-CHAP" rather than MD5 when encrypting the
2678 MS-CHAP is a combination of MD4 and DES.
2681 was built on a machine with DES libraries available, it will respond
2682 to MS-CHAP authentication requests, but will never request them.
2684 Default: Enabled and Accepted.
2685 This option decides if deflate
2686 compression will be used by the Compression Control Protocol (CCP).
2687 This is the same algorithm as used by the
2690 Note: There is a problem negotiating
2696 implementation available under many operating systems.
2698 (version 2.3.1) incorrectly attempts to negotiate
2700 compression using type
2702 as the CCP configuration type rather than type
2708 is actually specified as
2709 .Dq PPP Magna-link Variable Resource Compression
2713 is capable of negotiating with
2720 .Ar accept Ns No ed .
2722 Default: Disabled and Denied.
2723 This is a variance of the
2725 option, allowing negotiation with the
2730 section above for details.
2731 It is disabled by default as it violates
2734 Default: Disabled and Denied.
2735 This option allows DNS negotiation.
2740 will request that the peer confirms the entries in
2741 .Pa /etc/resolv.conf .
2742 If the peer NAKs our request (suggesting new IP numbers),
2743 .Pa /etc/resolv.conf
2744 is updated and another request is sent to confirm the new entries.
2747 .Dq accept Ns No ed,
2749 will answer any DNS queries requested by the peer rather than rejecting
2751 The answer is taken from
2752 .Pa /etc/resolv.conf
2755 command is used as an override.
2757 Default: Enabled and Accepted.
2758 This option allows control over whether we
2759 negotiate an endpoint discriminator.
2760 We only send our discriminator if
2765 We reject the peers discriminator if
2769 Default: Disabled and Accepted.
2770 The use of this authentication protocol
2771 is discouraged as it partially violates the authentication protocol by
2772 implementing two different mechanisms (LANMan & NT) under the guise of
2773 a single CHAP type (0x80).
2775 uses a simple DES encryption mechanism and is the least secure of the
2776 CHAP alternatives (although is still more secure than PAP).
2780 description below for more details.
2782 Default: Disabled and Accepted.
2783 This option decides if Link Quality Requests will be sent or accepted.
2784 LQR is a protocol that allows
2786 to determine that the link is down without relying on the modems
2788 When LQR is enabled,
2794 below) as part of the LCP request.
2795 If the peer agrees, both sides will
2796 exchange LQR packets at the agreed frequency, allowing detailed link
2797 quality monitoring by enabling LQM logging.
2798 If the peer does not agree, and if the
2805 These packets pass no information of interest, but they
2807 be replied to by the peer.
2814 will abruptly drop the connection if 5 unacknowledged packets have been
2815 sent rather than sending a 6th.
2816 A message is logged at the
2818 level, and any appropriate
2820 values are honoured as if the peer were responsible for dropping the
2825 command description for differences in behaviour prior to
2829 Default: Enabled and Accepted.
2830 This is Microsoft Point to Point Encryption scheme.
2831 MPPE key size can be
2832 40-, 56- and 128-bits.
2837 Default: Disabled and Accepted.
2838 It is very similar to standard CHAP (type 0x05)
2839 except that it issues challenges of a fixed 16 bytes in length and uses a
2840 combination of MD4, SHA-1 and DES to encrypt the challenge rather than using the
2841 standard MD5 mechanism.
2843 Default: Disabled and Accepted.
2844 The use of this authentication protocol
2845 is discouraged as it partially violates the authentication protocol by
2846 implementing two different mechanisms (LANMan & NT) under the guise of
2847 a single CHAP type (0x80).
2848 It is very similar to standard CHAP (type 0x05)
2849 except that it issues challenges of a fixed 8 bytes in length and uses a
2850 combination of MD4 and DES to encrypt the challenge rather than using the
2851 standard MD5 mechanism.
2852 CHAP type 0x80 for LANMan is also supported - see
2860 use CHAP type 0x80, when acting as authenticator with both
2861 .Dq enable Ns No d ,
2863 will rechallenge the peer up to three times if it responds using the wrong
2864 one of the two protocols.
2865 This gives the peer a chance to attempt using both protocols.
2869 acts as the authenticatee with both protocols
2870 .Dq accept Ns No ed ,
2871 the protocols are used alternately in response to challenges.
2873 Note: If only LANMan is enabled,
2875 (version 2.3.5) misbehaves when acting as authenticatee.
2877 the NT and the LANMan answers, but also suggests that only the NT answer
2880 Default: Disabled and Accepted.
2881 PAP stands for Password Authentication Protocol.
2882 Only one of PAP and CHAP (above) may be negotiated.
2883 With PAP, the ID and Password are sent repeatedly to the peer until
2884 authentication is acknowledged or the connection is terminated.
2885 This is a rather poor security mechanism.
2886 It is only performed when the connection is first established.
2887 If you want to have your peer authenticate itself, you must
2890 .Pa /etc/ppp/ppp.conf ,
2891 and have an entry in
2892 .Pa /etc/ppp/ppp.secret
2893 for the peer (although see the
2899 When using PAP as the client, you need only specify
2904 .Pa /etc/ppp/ppp.conf .
2905 PAP is accepted by default.
2907 Default: Enabled and Accepted.
2908 This option decides if Predictor 1
2909 compression will be used by the Compression Control Protocol (CCP).
2911 Default: Enabled and Accepted.
2912 This option is used to negotiate
2913 PFC (Protocol Field Compression), a mechanism where the protocol
2914 field number is reduced to one octet rather than two.
2916 Default: Enabled and Accepted.
2917 This option determines if
2919 will request and accept requests for short
2921 sequence numbers when negotiating multi-link mode.
2922 This is only applicable if our MRRU is set (thus enabling multi-link).
2924 Default: Enabled and Accepted.
2925 This option determines if Van Jacobson header compression will be used.
2928 The following options are not actually negotiated with the peer.
2929 Therefore, accepting or denying them makes no sense.
2933 When this option is enabled,
2937 requests to the peer at the frequency defined by
2941 requests will supersede
2943 requests if enabled and negotiated.
2952 was considered enabled if lqr was enabled and negotiated, otherwise it was
2953 considered disabled.
2954 For the same behaviour, it is now necessary to
2958 .It filter-decapsulation
2960 When this option is enabled,
2962 will examine UDP frames to see if they actually contain a
2964 frame as their payload.
2965 If this is the case, all filters will operate on the payload rather
2966 than the actual packet.
2968 This is useful if you want to send PPPoUDP traffic over a
2970 link, but want that link to do smart things with the real data rather than
2973 The UDP frame payload must not be compressed in any way, otherwise
2975 will not be able to interpret it.
2976 It is therefore recommended that you
2977 .Ic disable vj pred1 deflate
2979 .Ic deny vj pred1 deflate
2980 in the configuration for the
2982 invocation with the udp link.
2985 Forces execution of the configured chat scripts in
2994 exchanges low-level LCP, CCP and IPCP configuration traffic, the
2996 field of any replies is expected to be the same as that of the request.
2999 drops any reply packets that do not contain the expected identifier
3000 field, reporting the fact at the respective log level.
3005 will ignore the identifier field.
3010 This option simply tells
3012 to add new interface addresses to the interface rather than replacing them.
3013 The option can only be enabled if network address translation is enabled
3014 .Pq Dq nat enable yes .
3016 With this option enabled,
3018 will pass traffic for old interface addresses through the NAT
3019 ifdef({LOCALNAT},{engine,},{engine
3021 .Xr libalias 3 ) ,})
3022 resulting in the ability (in
3024 mode) to properly connect the process that caused the PPP link to
3025 come up in the first place.
3035 to attempt to negotiate IP control protocol capabilities and if
3036 successful to exchange IP datagrams with the peer.
3041 to attempt to negotiate IPv6 control protocol capabilities and if
3042 successful to exchange IPv6 datagrams with the peer.
3047 runs as a Multi-link server, a different
3049 instance initially receives each connection.
3050 After determining that
3051 the link belongs to an already existing bundle (controlled by another
3055 will transfer the link to that process.
3057 If the link is a tty device or if this option is enabled,
3059 will not exit, but will change its process name to
3061 and wait for the controlling
3063 to finish with the link and deliver a signal back to the idle process.
3064 This prevents the confusion that results from
3066 parent considering the link resource available again.
3068 For tty devices that have entries in
3070 this is necessary to prevent another
3072 from being started, and for program links such as
3076 from exiting due to the death of its child.
3079 cannot determine its parents requirements (except for the tty case), this
3080 option must be enabled manually depending on the circumstances.
3087 will automatically loop back packets being sent
3088 out with a destination address equal to that of the
3093 will send the packet, probably resulting in an ICMP redirect from
3095 It is convenient to have this option enabled when
3096 the interface is also the default route as it avoids the necessity
3097 of a loopback route.
3100 This option controls whether
3104 attribute to the RADIUS server when RADIUS is in use
3105 .Pq see Dq set radius .
3107 Note, at least one of
3115 prior to version 3.4.1 did not send the
3117 attribute as it was reported to break the Radiator RADIUS server.
3118 As the latest rfc (2865) no longer hints that only one of
3122 should be sent (as rfc 2138 did),
3124 now sends both and leaves it up to the administrator that chooses to use
3125 bad RADIUS implementations to
3126 .Dq disable NAS-IP-Address .
3129 This option controls whether
3133 attribute to the RADIUS server when RADIUS is in use
3134 .Pq see Dq set radius .
3136 Note, at least one of
3143 Enabling this option will tell the PAP authentication
3144 code to use the password database (see
3146 to authenticate the caller if they cannot be found in the
3147 .Pa /etc/ppp/ppp.secret
3149 .Pa /etc/ppp/ppp.secret
3150 is always checked first.
3151 If you wish to use passwords from
3153 but also to specify an IP number or label for a given client, use
3155 as the client password in
3156 .Pa /etc/ppp/ppp.secret .
3159 Enabling this option will tell
3161 to proxy ARP for the peer.
3164 will make an entry in the ARP table using
3168 address of the local network in which
3171 This allows other machines connecteed to the LAN to talk to
3172 the peer as if the peer itself was connected to the LAN.
3173 The proxy entry cannot be made unless
3175 is an address from a LAN.
3178 Enabling this will tell
3180 to add proxy arp entries for every IP address in all class C or
3181 smaller subnets routed via the tun interface.
3183 Proxy arp entries are only made for sticky routes that are added
3187 No proxy arp entries are made for the interface address itself
3195 command is used with the
3201 values, entries are stored in the
3204 Each time these variables change, this list is re-applied to the routing table.
3206 Disabling this option will prevent the re-application of sticky routes,
3209 list will still be maintained.
3216 to adjust TCP SYN packets so that the maximum receive segment
3217 size is not greater than the amount allowed by the interface MTU.
3222 to gather throughput statistics.
3223 Input and output is sampled over
3224 a rolling 5 second window, and current, best and total figures are retained.
3225 This data is output when the relevant
3227 layer shuts down, and is also available using the
3230 Throughput statistics are available at the
3237 Normally, when a user is authenticated using PAP or CHAP, and when
3241 mode, an entry is made in the utmp and wtmp files for that user.
3242 Disabling this option will tell
3244 not to make any utmp or wtmp entries.
3245 This is usually only necessary if
3246 you require the user to both login and authenticate themselves.
3251 .Ar dest Ns Op / Ns Ar nn
3256 is the destination IP address.
3257 The netmask is specified either as a number of bits with
3259 or as an IP number using
3264 with no mask refers to the default route.
3265 It is also possible to use the literal name
3270 is the next hop gateway to get to the given
3275 command for further details.
3277 It is possible to use the symbolic names
3283 as the destination, and
3290 is replaced with the interface IP address,
3292 is replaced with the interface IP destination (peer) address,
3294 is replaced with the interface IPv6 address, and
3296 is replaced with the interface IPv6 destination address,
3303 then if the route already exists, it will be updated as with the
3307 for further details).
3309 Routes that contain the
3317 constants are considered
3319 They are stored in a list (use
3321 to see the list), and each time the value of one of these variables
3322 changes, the appropriate routing table entries are updated.
3323 This facility may be disabled using
3324 .Dq disable sroutes .
3325 .It allow Ar command Op Ar args
3326 This command controls access to
3328 and its configuration files.
3329 It is possible to allow user-level access,
3330 depending on the configuration file label and on the mode that
3333 For example, you may wish to configure
3343 User id 0 is immune to these commands.
3345 .It allow user Ns Xo
3347 .Ar logname Ns No ...
3349 By default, only user id 0 is allowed access to
3351 If this command is used, all of the listed users are allowed access to
3352 the section in which the
3357 section is always checked first (even though it is only ever automatically
3360 commands are cumulative in a given section, but users allowed in any given
3361 section override users allowed in the default section, so it is possible to
3362 allow users access to everything except a given label by specifying default
3365 section, and then specifying a new user list for that label.
3369 is specified, access is allowed to all users.
3370 .It allow mode Ns Xo
3374 By default, access using any
3377 If this command is used, it restricts the access
3379 allowed to load the label under which this command is specified.
3384 command overrides any previous settings, and the
3386 section is always checked first.
3398 When running in multi-link mode, a section can be loaded if it allows
3400 of the currently existing line modes.
3403 .It nat Ar command Op Ar args
3404 This command allows the control of the network address translation (also
3405 known as masquerading or IP aliasing) facilities that are built into
3407 NAT is done on the external interface only, and is unlikely to make sense
3412 If nat is enabled on your system (it may be omitted at compile time),
3413 the following commands are possible:
3415 .It nat enable yes|no
3416 This command either switches network address translation on or turns it off.
3419 command line flag is synonymous with
3420 .Dq nat enable yes .
3421 .It nat addr Op Ar addr_local addr_alias
3422 This command allows data for
3426 It is useful if you own a small number of real IP numbers that
3427 you wish to map to specific machines behind your gateway.
3428 .It nat deny_incoming yes|no
3429 If set to yes, this command will refuse all incoming packets where an
3430 aliasing link does not already exist.
3431 ifdef({LOCALNAT},{},{Refer to the
3432 .Sx CONCEPTUAL BACKGROUND
3435 for a description of what an
3440 It should be noted under what circumstances an aliasing link is
3441 ifdef({LOCALNAT},{created.},{created by
3443 It may be necessary to further protect your network from outside
3444 connections using the
3450 This command gives a summary of available nat commands.
3452 This option causes various NAT statistics and information to
3453 be logged to the file
3454 .Pa /var/log/alias.log .
3455 .It nat port Ar proto Ar targetIP Ns Xo
3456 .No : Ns Ar targetPort Ns
3458 .No - Ns Ar targetPort
3461 .No - Ns Ar aliasPort
3462 .Oc Oo Ar remoteIP : Ns
3465 .No - Ns Ar remotePort
3469 This command causes incoming
3483 A range of port numbers may be specified as shown above.
3484 The ranges must be of the same size.
3488 is specified, only data coming from that IP number is redirected.
3492 (indicating any source port)
3493 or a range of ports the same size as the other ranges.
3495 This option is useful if you wish to run things like Internet phone on
3496 machines behind your gateway, but is limited in that connections to only
3497 one interior machine per source machine and target port are possible.
3498 .It nat proto Ar proto localIP Oo
3499 .Ar publicIP Op Ar remoteIP
3503 to redirect packets of protocol type
3507 to the internal address
3512 is specified, only packets destined for that address are matched,
3513 otherwise the default alias address is used.
3517 is specified, only packets matching that source address are matched,
3519 This command is useful for redirecting tunnel endpoints to an internal machine,
3522 .Dl nat proto ipencap 10.0.0.1
3523 .It "nat proxy cmd" Ar arg Ns No ...
3526 to proxy certain connections, redirecting them to a given server.
3527 ifdef({LOCALNAT},{},{Refer to the description of
3528 .Fn PacketAliasProxyRule
3531 for details of the available commands.
3533 .It nat punch_fw Op Ar base count
3536 to punch holes in the firewall for FTP or IRC DCC connections.
3537 This is done dynamically by installing termporary firewall rules which
3538 allow a particular connection (and only that connection) to go through
3540 The rules are removed once the corresponding connection terminates.
3544 rules starting from rule number
3546 will be used for punching firewall holes.
3547 The range will be cleared when the
3551 If no arguments are given, firewall punching is disabled.
3552 .It nat skinny_port Op Ar port
3555 which TCP port is used by the Skinny Station protocol.
3557 Cisco IP phones to communicate with Cisco Call Managers to setup voice
3559 The typical port used by Skinny is 2000.
3561 If no argument is given, skinny aliasing is disabled.
3562 .It nat same_ports yes|no
3563 When enabled, this command will tell the network address translation engine to
3564 attempt to avoid changing the port number on outgoing packets.
3566 if you want to support protocols such as RPC and LPD which require
3567 connections to come from a well known port.
3568 .It nat target Op Ar address
3569 Set the given target address or clear it if no address is given.
3570 The target address is used
3571 ifdef({LOCALNAT},{},{by libalias })dnl
3572 to specify how to NAT incoming packets by default.
3573 If a target address is not set or if
3575 is given, packets are not altered and are allowed to route to the internal
3578 The target address may be set to
3581 ifdef({LOCALNAT},{all packets will be redirected},
3582 {libalias will redirect all packets})
3583 to the interface address.
3584 .It nat use_sockets yes|no
3585 When enabled, this option tells the network address translation engine to
3586 create a socket so that it can guarantee a correct incoming ftp data or
3588 .It nat unregistered_only yes|no
3589 Only alter outgoing packets with an unregistered source address.
3590 According to RFC 1918, unregistered source addresses
3591 are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16.
3594 These commands are also discussed in the file
3596 which comes with the source distribution.
3603 is executed in the background with the following words replaced:
3604 .Bl -tag -width COMPILATIONDATE
3606 This is replaced with the local
3612 .It Li COMPILATIONDATE
3613 In previous software revisions, this was replaced with the date on which
3616 This is no longer supported as it breaks the ability to recompile the same
3617 code to produce an exact duplicate of a previous compilation.
3619 These are replaced with the primary and secondary nameserver IP numbers.
3620 If nameservers are negotiated by IPCP, the values of these macros will change.
3622 This is replaced with the local endpoint discriminator value.
3627 This is replaced with the peers IP number.
3629 This is replaced with the peers IPv6 number.
3631 This is replaced with the name of the interface that is in use.
3633 This is replaced with the number of IP bytes received since the connection
3636 This is replaced with the number of IP bytes sent since the connection
3639 This is replaced with the number of IP packets received since the connection
3642 This is replaced with the number of IP packets sent since the connection
3645 This is replaced with the number of IPv6 bytes received since the connection
3647 .It Li IPV6OCTETSOUT
3648 This is replaced with the number of IPv6 bytes sent since the connection
3650 .It Li IPV6PACKETSIN
3651 This is replaced with the number of IPv6 packets received since the connection
3653 .It Li IPV6PACKETSOUT
3654 This is replaced with the number of IPv6 packets sent since the connection
3657 This is replaced with the last label name used.
3658 A label may be specified on the
3660 command line, via the
3668 This is replaced with the IP number assigned to the local interface.
3670 This is replaced with the IPv6 number assigned to the local interface.
3672 This is replaced with the number of bytes received since the connection
3675 This is replaced with the number of bytes sent since the connection
3678 This is replaced with the number of packets received since the connection
3681 This is replaced with the number of packets sent since the connection
3684 This is replaced with the value of the peers endpoint discriminator.
3686 This is replaced with the current process id.
3688 This is replaced with the name of the diagnostic socket.
3690 This is replaced with the bundle uptime in HH:MM:SS format.
3692 This is replaced with the username that has been authenticated with PAP or
3694 Normally, this variable is assigned only in -direct mode.
3695 This value is available irrespective of whether utmp logging is enabled.
3697 This is replaced with the current version number of
3701 These substitutions are also done by the
3708 If you wish to pause
3710 while the command executes, use the
3713 .It clear physical|ipcp|ipv6 Op current|overall|peak...
3714 Clear the specified throughput values at either the
3722 is specified, context must be given (see the
3725 If no second argument is given, all values are cleared.
3726 .It clone Ar name Ns Xo
3727 .Op \&, Ns Ar name Ns
3730 Clone the specified link, creating one or more new links according to the
3733 This command must be used from the
3735 command below unless you have only got a single link (in which case that
3736 link becomes the default).
3737 Links may be removed using the
3741 The default link name is
3743 .It close Op lcp|ccp Ns Op !\&
3744 If no arguments are given, the relevant protocol layers will be brought
3745 down and the link will be closed.
3748 is specified, the LCP layer is brought down, but
3750 will not bring the link offline.
3751 It is subsequently possible to use
3754 to talk to the peer machine if, for example, something like
3759 is specified, only the relevant compression layer is closed.
3762 is used, the compression layer will remain in the closed state, otherwise
3763 it will re-enter the STOPPED state, waiting for the peer to initiate
3764 further CCP negotiation.
3765 In any event, this command does not disconnect the user from
3776 This command deletes the route with the given
3783 all non-direct entries in the routing table for the current interface,
3786 entries are deleted.
3791 the default route is deleted.
3799 will not complain if the route does not already exist.
3800 .It dial|call Op Ar label Ns Xo
3803 This command is the equivalent of
3807 and is provided for backwards compatibility.
3808 .It down Op Ar lcp|ccp
3809 Bring the relevant layer down ungracefully, as if the underlying layer
3810 had become unavailable.
3811 It is not considered polite to use this command on
3812 a Finite State Machine that is in the OPEN state.
3814 supplied, the entire link is closed (or if no context is given, all links
3820 layer is terminated but the device is not brought offline and the link
3824 is specified, only the relevant compression layer(s) are terminated.
3825 .It help|? Op Ar command
3826 Show a list of available commands.
3829 is specified, show the usage string for that command.
3830 .It ident Op Ar text Ns No ...
3831 Identify the link to the peer using
3835 is empty, link identification is disabled.
3836 It is possible to use any of the words described for the
3841 command for details of when
3843 identifies itself to the peer.
3844 .It iface Ar command Op args
3845 This command is used to control the interface used by
3848 may be one of the following:
3852 .Ar addr Ns Op / Ns Ar bits
3863 combination to the interface.
3864 Instead of specifying
3868 (with no space between it and
3870 If the given address already exists, the command fails unless the
3872 is used - in which case the previous interface address entry is overwritten
3873 with the new one, allowing a change of netmask or peer address.
3884 .Dq 255.255.255.255 .
3885 This address (the broadcast address) is the only duplicate peer address that
3888 .It iface clear Op INET | INET6
3889 If this command is used while
3891 is in the OPENED state or while in
3893 mode, all addresses except for the NCP negotiated address are deleted
3897 is not in the OPENED state and is not in
3899 mode, all interface addresses are deleted.
3901 If the INET or INET6 arguments are used, only addresses for that address
3904 .It iface delete Ns Xo
3909 This command deletes the given
3914 is used, no error is given if the address is not currently assigned to
3915 the interface (and no deletion takes place).
3917 Shows the current state and current addresses for the interface.
3918 It is much the same as running
3919 .Dq ifconfig INTERFACE .
3920 .It iface help Op Ar sub-command
3921 This command, when invoked without
3923 will show a list of possible
3925 sub-commands and a brief synopsis for each.
3928 only the synopsis for the given sub-command is shown.
3932 .Ar name Ns Op , Ns Ar name Ns
3933 .No ... Ar command Op Ar args
3935 This command may prefix any other command if the user wishes to
3936 specify which link the command should affect.
3937 This is only applicable after multiple links have been created in Multi-link
3943 specifies the name of an existing link.
3946 is a comma separated list,
3948 is executed on each link.
3954 is executed on all links.
3955 .It load Op Ar label Ns Xo
3978 will not attempt to make an immediate connection.
3979 .It log Ar word Ns No ...
3980 Send the given word(s) to the log file with the prefix
3982 Word substitutions are done as explained under the
3985 .It open Op lcp|ccp|ipcp
3986 This is the opposite of the
3989 All closed links are immediately brought up apart from second and subsequent
3991 links - these will come up based on the
3993 command that has been used.
3997 argument is used while the LCP layer is already open, LCP will be
3999 This allows various LCP options to be changed, after which
4001 can be used to put them into effect.
4002 After renegotiating LCP,
4003 any agreed authentication will also take place.
4007 argument is used, the relevant compression layer is opened.
4008 Again, if it is already open, it will be renegotiated.
4012 argument is used, the link will be brought up as normal, but if
4013 IPCP is already open, it will be renegotiated and the network
4014 interface will be reconfigured.
4016 It is probably not good practice to re-open the PPP state machines
4017 like this as it is possible that the peer will not behave correctly.
4020 however useful as a way of forcing the CCP or VJ dictionaries to be reset.
4022 Specify the password required for access to the full
4025 This password is required when connecting to the diagnostic port (see the
4036 logging is active, instead, the literal string
4042 is executed from the controlling connection or from a command file,
4043 ppp will exit after closing all connections.
4044 Otherwise, if the user
4045 is connected to a diagnostic socket, the connection is simply dropped.
4051 will exit despite the source of the command after closing all existing
4054 This command removes the given link.
4055 It is only really useful in multi-link mode.
4056 A link must be in the
4058 state before it is removed.
4059 .It rename|mv Ar name
4060 This command renames the given link to
4064 is already used by another link.
4066 The default link name is
4073 may make the log file more readable.
4074 .It resolv Ar command
4075 This command controls
4082 starts up, it loads the contents of this file into memory and retains this
4083 image for future use.
4085 is one of the following:
4086 .Bl -tag -width readonly
4089 .Pa /etc/resolv.conf
4095 will still attempt to negotiate nameservers with the peer, making the results
4101 This is the opposite of the
4106 .Pa /etc/resolv.conf
4108 This may be necessary if for example a DHCP client overwrote
4109 .Pa /etc/resolv.conf .
4112 .Pa /etc/resolv.conf
4113 with the version originally read at startup or with the last
4116 This is sometimes a useful command to put in the
4117 .Pa /etc/ppp/ppp.linkdown
4121 .Pa /etc/resolv.conf
4123 This command will work even if the
4125 command has been used.
4126 It may be useful as a command in the
4127 .Pa /etc/ppp/ppp.linkup
4128 file if you wish to defer updating
4129 .Pa /etc/resolv.conf
4130 until after other commands have finished.
4135 .Pa /etc/resolv.conf
4140 successfully negotiates a DNS.
4141 This is the opposite of the
4146 This option is not (yet) implemented.
4150 to identify itself to the peer.
4151 The link must be in LCP state or higher.
4152 If no identity has been set (via the
4158 When an identity has been set,
4160 will automatically identify itself when it sends or receives a configure
4161 reject, when negotiation fails or when LCP reaches the opened state.
4163 Received identification packets are logged to the LCP log (see
4165 for details) and are never responded to.
4170 This option allows the setting of any of the following variables:
4172 .It set accmap Ar hex-value
4173 ACCMap stands for Asynchronous Control Character Map.
4175 negotiated with the peer, and defaults to a value of 00000000 in hex.
4176 This protocol is required to defeat hardware that depends on passing
4177 certain characters from end to end (such as XON/XOFF etc).
4179 For the XON/XOFF scenario, use
4180 .Dq set accmap 000a0000 .
4181 .It set Op auth Ns Xo
4184 This sets the authentication key (or password) used in client mode
4185 PAP or CHAP negotiation to the given value.
4186 It also specifies the
4187 password to be used in the dial or login scripts in place of the
4189 sequence, preventing the actual password from being logged.
4194 logging is in effect,
4198 for security reasons.
4200 If the first character of
4202 is an exclamation mark
4205 treats the remainder of the string as a program that must be executed
4217 it is treated as a single literal
4219 otherwise, ignoring the
4222 is parsed as a program to execute in the same was as the
4224 command above, substituting special names in the same manner.
4227 will feed the program three lines of input, each terminated by a newline
4231 The host name as sent in the CHAP challenge.
4233 The challenge string as sent in the CHAP challenge.
4239 Two lines of output are expected:
4244 to be sent with the CHAP response.
4248 which is encrypted with the challenge and request id, the answer being sent
4249 in the CHAP response packet.
4254 in this manner, it is expected that the host challenge is a series of ASCII
4255 digits or characters.
4256 An encryption device or Secure ID card is usually
4257 required to calculate the secret appropriate for the given challenge.
4258 .It set authname Ar id
4259 This sets the authentication id used in client mode PAP or CHAP negotiation.
4263 mode with CHAP enabled,
4265 is used in the initial authentication challenge and should normally be set to
4266 the local machine name.
4268 .Ar min-percent max-percent period
4270 These settings apply only in multi-link mode and default to zero, zero and
4276 mode link is available, only the first link is made active when
4278 first reads data from the tun device.
4281 link will be opened only when the current bundle throughput is at least
4283 percent of the total bundle bandwidth for
4286 When the current bundle throughput decreases to
4288 percent or less of the total bundle bandwidth for
4292 link will be brought down as long as it is not the last active link.
4294 Bundle throughput is measured as the maximum of inbound and outbound
4297 The default values cause
4299 links to simply come up one at a time.
4301 Certain devices cannot determine their physical bandwidth, so it
4302 is sometimes necessary to use the
4304 command (described below) to make
4307 .It set bandwidth Ar value
4308 This command sets the connection bandwidth in bits per second.
4310 must be greater than zero.
4311 It is currently only used by the
4314 .It set callback Ar option Ns No ...
4315 If no arguments are given, callback is disabled, otherwise,
4319 mode, will accept) one of the given
4320 .Ar option Ns No s .
4321 In client mode, if an
4325 will request a different
4327 until no options remain at which point
4329 will terminate negotiations (unless
4331 is one of the specified
4335 will accept any of the given protocols - but the client
4337 request one of them.
4338 If you wish callback to be optional, you must {include}
4344 are as follows (in this order of preference):
4348 The callee is expected to decide the callback number based on
4352 is the callee, the number should be specified as the fifth field of
4354 .Pa /etc/ppp/ppp.secret .
4356 Microsoft's callback control protocol is used.
4361 If you wish to negotiate
4363 in client mode but also wish to allow the server to request no callback at
4364 CBCP negotiation time, you must specify both
4368 as callback options.
4370 .Ar number Ns Op , Ns Ar number Ns
4373 The caller specifies the
4379 should be either a comma separated list of allowable numbers or a
4381 meaning any number is permitted.
4384 is the caller, only a single number should be specified.
4386 Note, this option is very unsafe when used with a
4388 as a malicious caller can tell
4390 to call any (possibly international) number without first authenticating
4393 If the peer does not wish to do callback at all,
4395 will accept the fact and continue without callback rather than terminating
4397 This is required (in addition to one or more other callback
4398 options) if you wish callback to be optional.
4402 .No *| Ns Ar number Ns Oo
4403 .No , Ns Ar number Ns ...\& Oc
4404 .Op Ar delay Op Ar retry
4406 If no arguments are given, CBCP (Microsoft's CallBack Control Protocol)
4407 is disabled - ie, configuring CBCP in the
4409 command will result in
4411 requesting no callback in the CBCP phase.
4414 attempts to use the given phone
4415 .Ar number Ns No (s).
4420 will insist that the client uses one of these numbers, unless
4422 is used in which case the client is expected to specify the number.
4426 will attempt to use one of the given numbers (whichever it finds to
4427 be agreeable with the peer), or if
4431 will expect the peer to specify the number.
4433 .No off| Ns Ar seconds Ns Op !\&
4437 checks for the existence of carrier depending on the type of device
4438 that has been opened:
4439 .Bl -tag -width XXX -offset XXX
4440 .It Terminal Devices
4441 Carrier is checked one second after the login script is complete.
4444 assumes that this is because the device does not support carrier (which
4447 NULL-modem cables), logs the fact and stops checking
4450 As ptys do not support the TIOCMGET ioctl, the tty device will switch all
4451 carrier detection off when it detects that the device is a pty.
4452 .It PPPoE (netgraph) Devices
4453 Carrier is checked once per second for 5 seconds.
4454 If it is not set after
4455 the fifth second, the connection attempt is considered to have failed and
4456 the device is closed.
4457 Carrier is always required for PPPoE devices.
4460 All other device types do not support carrier.
4461 Setting a carrier value will
4462 result in a warning when the device is opened.
4464 Some modems take more than one second after connecting to assert the carrier
4466 If this delay is not increased, this will result in
4468 inability to detect when the link is dropped, as
4470 assumes that the device is not asserting carrier.
4474 command overrides the default carrier behaviour.
4476 specifies the maximum number of seconds that
4478 should wait after the dial script has finished before deciding if
4479 carrier is available or not.
4485 will not check for carrier on the device, otherwise
4487 will not proceed to the login script until either carrier is detected
4490 has elapsed, at which point
4492 assumes that the device will not set carrier.
4494 If no arguments are given, carrier settings will go back to their default
4499 is followed immediately by an exclamation mark
4505 If carrier is not detected after
4507 seconds, the link will be disconnected.
4508 .It set choked Op Ar timeout
4509 This sets the number of seconds that
4511 will keep a choked output queue before dropping all pending output packets.
4514 is less than or equal to zero or if
4516 is not specified, it is set to the default value of
4519 A choked output queue occurs when
4521 has read a certain number of packets from the local network for transmission,
4522 but cannot send the data due to link failure (the peer is busy etc.).
4524 will not read packets indefinitely.
4525 Instead, it reads up to
4531 packets in multi-link mode), then stops reading the network interface
4534 seconds have passed or at least one packet has been sent.
4538 seconds pass, all pending output packets are dropped.
4539 .It set ctsrts|crtscts on|off
4540 This sets hardware flow control.
4541 Hardware flow control is
4544 .It set deflate Ar out-winsize Op Ar in-winsize
4545 This sets the DEFLATE algorithms default outgoing and incoming window
4551 must be values between
4559 will insist that this window size is used and will not accept any other
4560 values from the peer.
4561 .It set dns Op Ar primary Op Ar secondary
4562 This command specifies DNS overrides for the
4567 command description above for details.
4568 This command does not affect the IP numbers requested using
4570 .It set device|line Xo
4573 This sets the device(s) to which
4575 will talk to the given
4578 All serial device names are expected to begin with
4580 Serial devices are usually called
4587 it must either begin with an exclamation mark
4590 .No PPPoE: Ns Ar iface Ns Xo
4591 .Op \&: Ns Ar provider Ns
4595 enabled systems), or be of the format
4597 .Ar host : port Op /tcp|udp .
4600 If it begins with an exclamation mark, the rest of the device name is
4601 treated as a program name, and that program is executed when the device
4603 Standard input, output and error are fed back to
4605 and are read and written as if they were a regular device.
4608 .No PPPoE: Ns Ar iface Ns Xo
4609 .Op \&: Ns Ar provider Ns
4611 specification is given,
4613 will attempt to create a
4615 over Ethernet connection using the given
4623 will attempt to load it using
4625 If this fails, an external program must be used such as the
4627 program available under
4631 is passed as the service name in the PPPoE Discovery Initiation (PADI)
4633 If no provider is given, an empty value will be used.
4635 When a PPPoE connection is established,
4637 will place the name of the Access Concentrator in the environment variable
4644 for further details.
4647 .Ar host Ns No : Ns Ar port Ns Oo
4650 specification is given,
4652 will attempt to connect to the given
4660 suffix is not provided, the default is
4662 Refer to the section on
4663 .Em PPP OVER TCP and UDP
4664 above for further details.
4670 will attempt to open each one in turn until it succeeds or runs out of
4672 .It set dial Ar chat-script
4673 This specifies the chat script that will be used to dial the other
4680 and to the example configuration files for details of the chat script
4682 It is possible to specify some special
4684 in your chat script as follows:
4687 When used as the last character in a
4689 string, this indicates that a newline should not be appended.
4691 When the chat script encounters this sequence, it delays two seconds.
4693 When the chat script encounters this sequence, it delays for one quarter of
4696 This is replaced with a newline character.
4698 This is replaced with a carriage return character.
4700 This is replaced with a space character.
4702 This is replaced with a tab character.
4704 This is replaced by the current phone number (see
4708 This is replaced by the current
4714 This is replaced by the current
4721 Note that two parsers will examine these escape sequences, so in order to
4724 see the escape character, it is necessary to escape it from the
4725 .Sq command parser .
4726 This means that in practice you should use two escapes, for example:
4727 .Bd -literal -offset indent
4728 set dial "... ATDT\\\\T CONNECT"
4731 It is also possible to execute external commands from the chat script.
4732 To do this, the first character of the expect or send string is an
4735 If a literal exclamation mark is required, double it up to
4737 and it will be treated as a single literal
4739 When the command is executed, standard input and standard output are
4740 directed to the open device (see the
4742 command), and standard error is read by
4744 and substituted as the expect or send string.
4747 is running in interactive mode, file descriptor 3 is attached to
4750 For example (wrapped for readability):
4751 .Bd -literal -offset indent
4752 set login "TIMEOUT 5 \\"\\" \\"\\" login:--login: ppp \e
4753 word: ppp \\"!sh \\\\-c \\\\\\"echo \\\\-n label: >&2\\\\\\"\\" \e
4754 \\"!/bin/echo in\\" HELLO"
4757 would result in the following chat sequence (output using the
4758 .Sq set log local chat
4759 command before dialing):
4760 .Bd -literal -offset indent
4765 Chat: Expecting: login:--login:
4766 Chat: Wait for (5): login:
4768 Chat: Expecting: word:
4769 Chat: Wait for (5): word:
4771 Chat: Expecting: !sh \\-c "echo \\-n label: >&2"
4772 Chat: Exec: sh -c "echo -n label: >&2"
4773 Chat: Wait for (5): !sh \\-c "echo \\-n label: >&2" --> label:
4774 Chat: Exec: /bin/echo in
4776 Chat: Expecting: HELLO
4777 Chat: Wait for (5): HELLO
4781 Note (again) the use of the escape character, allowing many levels of
4783 Here, there are four parsers at work.
4784 The first parses the original line, reading it as three arguments.
4785 The second parses the third argument, reading it as 11 arguments.
4786 At this point, it is
4789 signs are escaped, otherwise this parser will see them as constituting
4790 an expect-send-expect sequence.
4793 character is seen, the execution parser reads the first command as three
4796 itself expands the argument after the
4798 As we wish to send the output back to the modem, in the first example
4799 we redirect our output to file descriptor 2 (stderr) so that
4801 itself sends and logs it, and in the second example, we just output to stdout,
4802 which is attached directly to the modem.
4804 This, of course means that it is possible to execute an entirely external
4806 command rather than using the internal one.
4809 for a good alternative.
4811 The external command that is executed is subjected to the same special
4812 word expansions as the
4815 .It set enddisc Op label|IP|MAC|magic|psn value
4816 This command sets our local endpoint discriminator.
4817 If set prior to LCP negotiation, and if no
4819 command has been used,
4821 will send the information to the peer using the LCP endpoint discriminator
4823 The following discriminators may be set:
4824 .Bl -tag -width indent
4826 The current label is used.
4828 Our local IP number is used.
4829 As LCP is negotiated prior to IPCP, it is
4830 possible that the IPCP layer will subsequently change this value.
4832 it does, the endpoint discriminator stays at the old value unless manually
4835 This is similar to the
4837 option above, except that the MAC address associated with the local IP
4839 If the local IP number is not resident on any Ethernet
4840 interface, the command will fail.
4842 As the local IP number defaults to whatever the machine host name is,
4844 is usually done prior to any
4848 A 20 digit random number is used.
4849 Care should be taken when using magic numbers as restarting
4851 or creating a link using a different
4853 invocation will also use a different magic number and will therefore not
4854 be recognised by the peer as belonging to the same bundle.
4855 This makes it unsuitable for
4863 should be set to an absolute public switched network number with the
4867 If no arguments are given, the endpoint discriminator is reset.
4868 .It set escape Ar value...
4869 This option is similar to the
4872 It allows the user to specify a set of characters that will be
4874 as they travel across the link.
4875 .It set filter dial|alive|in|out Ar rule-no Xo
4876 .No permit|deny|clear| Ns Ar rule-no
4879 .Ar src_addr Ns Op / Ns Ar width
4880 .Op Ar dst_addr Ns Op / Ns Ar width
4882 .Op src lt|eq|gt Ar port
4883 .Op dst lt|eq|gt Ar port
4887 .Op timeout Ar secs ]
4890 supports four filter sets.
4893 filter specifies packets that keep the connection alive - resetting the
4897 filter specifies packets that cause
4904 filter specifies packets that are allowed to travel
4905 into the machine and the
4907 filter specifies packets that are allowed out of the machine.
4909 Filtering is done prior to any IP alterations that might be done by the
4910 NAT engine on outgoing packets and after any IP alterations that might
4911 be done by the NAT engine on incoming packets.
4912 By default all empty filter sets allow all packets to pass.
4913 Rules are processed in order according to
4915 (unless skipped by specifying a rule number as the
4917 Up to 40 rules may be given for each set.
4918 If a packet does not match
4919 any of the rules in a given set, it is discarded.
4924 filters, this means that the packet is dropped.
4927 filters it means that the packet will not reset the idle timer (even if
4929 .Ar in Ns No / Ns Ar out
4932 value) and in the case of
4934 filters it means that the packet will not trigger a dial.
4935 A packet failing to trigger a dial will be dropped rather than queued.
4938 .Sx PACKET FILTERING
4939 above for further details.
4940 .It set hangup Ar chat-script
4941 This specifies the chat script that will be used to reset the device
4942 before it is closed.
4943 It should not normally be necessary, but can
4944 be used for devices that fail to reset themselves properly on close.
4945 .It set help|? Op Ar command
4946 This command gives a summary of available set commands, or if
4948 is specified, the command usage is shown.
4949 .It set ifaddr Oo Ar myaddr Ns
4951 .Oo Ar hisaddr Ns Op / Ns Ar \&nn
4956 This command specifies the IP addresses that will be used during
4958 Addresses are specified using the format
4964 is the preferred IP, but
4966 specifies how many bits of the address we will insist on.
4969 is omitted, it defaults to
4971 unless the IP address is 0.0.0.0 in which case it defaults to
4974 If you wish to assign a dynamic IP number to the peer,
4976 may also be specified as a range of IP numbers in the format
4977 .Bd -ragged -offset indent
4978 .Ar \&IP Ns Oo \&- Ns Ar \&IP Ns Xo
4979 .Oc Ns Oo , Ns Ar \&IP Ns
4980 .Op \&- Ns Ar \&IP Ns
4987 .Dl set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20
4991 as the local IP number, but may assign any of the given 10 IP
4992 numbers to the peer.
4993 If the peer requests one of these numbers,
4994 and that number is not already in use,
4996 will grant the peers request.
4997 This is useful if the peer wants
4998 to re-establish a link using the same IP number as was previously
4999 allocated (thus maintaining any existing tcp or udp connections).
5001 If the peer requests an IP number that is either outside
5002 of this range or is already in use,
5004 will suggest a random unused IP number from the range.
5008 is specified, it is used in place of
5010 in the initial IPCP negotiation.
5011 However, only an address in the
5013 range will be accepted.
5014 This is useful when negotiating with some
5016 implementations that will not assign an IP number unless their peer
5020 It should be noted that in
5024 will configure the interface immediately upon reading the
5026 line in the config file.
5027 In any other mode, these values are just
5028 used for IPCP negotiations, and the interface is not configured
5029 until the IPCP layer is up.
5033 argument may be overridden by the third field in the
5035 file once the client has authenticated itself
5039 .Sx AUTHENTICATING INCOMING CONNECTIONS
5040 section for details.
5042 In all cases, if the interface is already configured,
5044 will try to maintain the interface IP numbers so that any existing
5045 bound sockets will remain valid.
5046 .It set ifqueue Ar packets
5047 Set the maximum number of packets that
5049 will read from the tunnel interface while data cannot be sent to any of
5050 the available links.
5051 This queue limit is necessary to flow control outgoing data as the tunnel
5052 interface is likely to be far faster than the combined links available to
5057 is set to a value less than the number of links,
5059 will read up to that value regardless.
5060 This prevents any possible latency problems.
5062 The default value for
5066 .It set ccpretry|ccpretries Oo Ar timeout
5067 .Op Ar reqtries Op Ar trmtries
5069 .It set chapretry|chapretries Oo Ar timeout
5072 .It set ipcpretry|ipcpretries Oo Ar timeout
5073 .Op Ar reqtries Op Ar trmtries
5075 .It set ipv6cpretry|ipv6cpretries Oo Ar timeout
5076 .Op Ar reqtries Op Ar trmtries
5078 .It set lcpretry|lcpretries Oo Ar timeout
5079 .Op Ar reqtries Op Ar trmtries
5081 .It set papretry|papretries Oo Ar timeout
5084 These commands set the number of seconds that
5086 will wait before resending Finite State Machine (FSM) Request packets.
5089 for all FSMs is 3 seconds (which should suffice in most cases).
5093 is specified, it tells
5095 how many configuration request attempts it should make while receiving
5096 no reply from the peer before giving up.
5097 The default is 5 attempts for
5098 CCP, LCP and IPCP and 3 attempts for PAP and CHAP.
5102 is specified, it tells
5104 how many terminate requests should be sent before giving up waiting for the
5106 The default is 3 attempts.
5107 Authentication protocols are
5108 not terminated and it is therefore invalid to specify
5112 In order to avoid negotiations with the peer that will never converge,
5114 will only send at most 3 times the configured number of
5116 in any given negotiation session before giving up and closing that layer.
5122 This command allows the adjustment of the current log level.
5123 Refer to the Logging Facility section for further details.
5124 .It set login Ar chat-script
5127 compliments the dial-script.
5128 If both are specified, the login
5129 script will be executed after the dial script.
5130 Escape sequences available in the dial script are also available here.
5131 .It set logout Ar chat-script
5132 This specifies the chat script that will be used to logout
5133 before the hangup script is called.
5134 It should not normally be necessary.
5135 .It set lqrperiod|echoperiod Ar frequency
5136 This command sets the
5143 The default is 30 seconds.
5144 You must also use the
5148 commands if you wish to send
5152 requests to the peer.
5153 .It set mode Ar interactive|auto|ddial|background
5154 This command allows you to change the
5156 of the specified link.
5157 This is normally only useful in multi-link mode,
5158 but may also be used in uni-link mode.
5160 It is not possible to change a link that is
5165 Note: If you issue the command
5167 and have network address translation enabled, it may be useful to
5168 .Dq enable iface-alias
5172 to do the necessary address translations to enable the process that
5173 triggers the connection to connect once the link is up despite the
5174 peer assigning us a new (dynamic) IP address.
5175 .It set mppe Op 40|56|128|* Op stateless|stateful|*
5176 This option selects the encryption parameters used when negotiation
5178 MPPE can be disabled entirely with the
5181 If no arguments are given,
5183 will attempt to negotiate a stateful link with a 128 bit key, but
5184 will agree to whatever the peer requests (including no encryption
5187 If any arguments are given,
5191 on using MPPE and will close the link if it is rejected by the peer (Note;
5192 this behaviour can be overridden by a configured RADIUS server).
5194 The first argument specifies the number of bits that
5196 should insist on during negotiations and the second specifies whether
5198 should insist on stateful or stateless mode.
5199 In stateless mode, the
5200 encryption dictionary is re-initialised with every packet according to
5201 an encryption key that is changed with every packet.
5203 the encryption dictionary is re-initialised every 256 packets or after
5204 the loss of any data and the key is changed every 256 packets.
5205 Stateless mode is less efficient but is better for unreliable transport
5207 .It set mrru Op Ar value
5208 Setting this option enables Multi-link PPP negotiations, also known as
5209 Multi-link Protocol or MP.
5210 There is no default MRRU (Maximum Reconstructed Receive Unit) value.
5211 If no argument is given, multi-link mode is disabled.
5216 The default MRU (Maximum Receive Unit) is 1500.
5217 If it is increased, the other side *may* increase its MTU.
5218 In theory there is no point in decreasing the MRU to below the default as the
5220 protocol says implementations *must* be able to accept packets of at
5227 will refuse to negotiate a higher value.
5228 The maximum MRU can be set to 2048 at most.
5229 Setting a maximum of less than 1500 violates the
5231 rfc, but may sometimes be necessary.
5234 imposes a maximum of 1492 due to hardware limitations.
5236 If no argument is given, 1500 is assumed.
5237 A value must be given when
5244 The default MTU is 1500.
5245 At negotiation time,
5247 will accept whatever MRU the peer requests (assuming it is
5248 not less than 296 bytes or greater than the assigned maximum).
5251 will not accept MRU values less than
5253 When negotiations are complete, the MTU is used when writing to the
5254 interface, even if the peer requested a higher value MRU.
5255 This can be useful for
5256 limiting your packet size (giving better bandwidth sharing at the expense
5257 of more header data).
5263 will refuse to negotiate a higher value.
5264 The maximum MTU can be set to 2048 at most.
5265 Note, it is necessary to use the
5267 keyword to limit the MTU when using PPPoE.
5271 is given, 1500, or whatever the peer asks for is used.
5272 A value must be given when
5275 .It set nbns Op Ar x.x.x.x Op Ar y.y.y.y
5276 This option allows the setting of the Microsoft NetBIOS name server
5277 values to be returned at the peers request.
5278 If no values are given,
5280 will reject any such requests.
5281 .It set openmode active|passive Op Ar delay
5290 will always initiate LCP/IPCP/CCP negotiation one second after the line
5292 If you want to wait for the peer to initiate negotiations, you
5295 If you want to initiate negotiations immediately or after more than one
5296 second, the appropriate
5298 may be specified here in seconds.
5299 .It set parity odd|even|none|mark
5300 This allows the line parity to be set.
5301 The default value is
5303 .It set phone Ar telno Ns Xo
5304 .Oo \&| Ns Ar backupnumber
5305 .Oc Ns ... Ns Oo : Ns Ar nextnumber
5308 This allows the specification of the phone number to be used in
5309 place of the \\\\T string in the dial and login chat scripts.
5310 Multiple phone numbers may be given separated either by a pipe
5315 Numbers after the pipe are only dialed if the dial or login
5316 script for the previous number failed.
5318 Numbers after the colon are tried sequentially, irrespective of
5319 the reason the line was dropped.
5321 If multiple numbers are given,
5323 will dial them according to these rules until a connection is made, retrying
5324 the maximum number of times specified by
5329 mode, each number is attempted at most once.
5330 .It set pppoe Op standard|3Com
5331 This option configures the underlying
5333 node to either standard RFC2516 PPPoE or proprietary 3Com mode.
5334 If not set the system default will be used.
5335 .It set Op proc Ns Xo
5336 .No title Op Ar value
5338 The current process title as displayed by
5340 is changed according to
5344 is not specified, the original process title is restored.
5346 word replacements done by the shell commands (see the
5348 command above) are done here too.
5350 Note, if USER is required in the process title, the
5352 command must appear in
5354 as it is not known when the commands in
5357 .It set radius Op Ar config-file
5358 This command enables RADIUS support (if it is compiled in).
5360 refers to the radius client configuration file as described in
5362 If PAP, CHAP, MSCHAP or MSCHAPv2 are
5363 .Dq enable Ns No d ,
5366 .Em \&N Ns No etwork
5369 and uses the configured RADIUS server to authenticate rather than
5370 authenticating from the
5372 file or from the passwd database.
5374 If none of PAP, CHAP, MSCHAP or MSCHAPv2 are enabled,
5379 uses the following attributes from the RADIUS reply:
5380 .Bl -tag -width XXX -offset XXX
5381 .It RAD_FRAMED_IP_ADDRESS
5382 The peer IP address is set to the given value.
5383 .It RAD_FRAMED_IP_NETMASK
5384 The tun interface netmask is set to the given value.
5386 If the given MTU is less than the peers MRU as agreed during LCP
5387 negotiation, *and* it is less that any configured MTU (see the
5389 command), the tun interface MTU is set to the given value.
5390 .It RAD_FRAMED_COMPRESSION
5391 If the received compression type is
5394 will request VJ compression during IPCP negotiations despite any
5396 configuration command.
5398 If this attribute is supplied,
5400 will attempt to use it as an additional label to load from the
5405 The load will be attempted before (and in addition to) the normal
5407 If the label does not exist, no action is taken and
5409 proceeds to the normal load using the current label.
5410 .It RAD_FRAMED_ROUTE
5411 The received string is expected to be in the format
5412 .Ar dest Ns Op / Ns Ar bits
5415 Any specified metrics are ignored.
5419 are understood as valid values for
5426 to sepcify the default route, and
5428 is understood to be the same as
5437 For example, a returned value of
5438 .Dq 1.2.3.4/24 0.0.0.0 1 2 -1 3 400
5439 would result in a routing table entry to the 1.2.3.0/24 network via
5441 and a returned value of
5445 would result in a default route to
5448 All RADIUS routes are applied after any sticky routes are applied, making
5449 RADIUS routes override configured routes.
5450 This also applies for RADIUS routes that do not {include} the
5456 .It RAD_FRAMED_IPV6_PREFIX
5457 If this attribute is supplied, the value is substituted for IPV6PREFIX
5459 You may pass it to an upper layer protocol such as DHCPv6 for delegating an
5460 IPv6 prefix to a peer.
5461 .It RAD_FRAMED_IPV6_ROUTE
5462 The received string is expected to be in the format
5463 .Ar dest Ns Op / Ns Ar bits
5466 Any specified metrics are ignored.
5470 are understood as valid values for
5477 to sepcify the default route, and
5479 is understood to be the same as
5488 For example, a returned value of
5489 .Dq 3ffe:505:abcd::/48 ::
5490 would result in a routing table entry to the 3ffe:505:abcd::/48 network via
5492 and a returned value of
5495 .Dq default HISADDR6
5496 would result in a default route to
5499 All RADIUS IPv6 routes are applied after any sticky routes are
5500 applied, making RADIUS IPv6 routes override configured routes.
5502 also applies for RADIUS IPv6 routes that do not {include} the
5508 .It RAD_SESSION_TIMEOUT
5509 If supplied, the client connection is closed after the given number of
5511 .It RAD_REPLY_MESSAGE
5512 If supplied, this message is passed back to the peer as the authentication
5514 .It RAD_MICROSOFT_MS_CHAP_ERROR
5516 .Dv RAD_VENDOR_MICROSOFT
5517 vendor specific attribute is supplied, it is passed back to the peer as the
5518 authentication FAILURE text.
5519 .It RAD_MICROSOFT_MS_CHAP2_SUCCESS
5521 .Dv RAD_VENDOR_MICROSOFT
5522 vendor specific attribute is supplied and if MS-CHAPv2 authentication is
5523 being used, it is passed back to the peer as the authentication SUCCESS text.
5524 .It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY
5526 .Dv RAD_VENDOR_MICROSOFT
5527 vendor specific attribute is supplied and has a value of 2 (Required),
5529 will insist that MPPE encryption is used (even if no
5531 configuration command has been given with arguments).
5532 If it is supplied with a value of 1 (Allowed), encryption is made optional
5535 configuration commands with arguments).
5536 .It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES
5538 .Dv RAD_VENDOR_MICROSOFT
5539 vendor specific attribute is supplied, bits 1 and 2 are examined.
5540 If either or both are set, 40 bit and/or 128 bit (respectively) encryption
5541 options are set, overriding any given first argument to the
5544 Note, it is not currently possible for the RADIUS server to specify 56 bit
5546 .It RAD_MICROSOFT_MS_MPPE_RECV_KEY
5548 .Dv RAD_VENDOR_MICROSOFT
5549 vendor specific attribute is supplied, it is value is used as the master
5550 key for decryption of incoming data.
5551 When clients are authenticated using
5552 MSCHAPv2, the RADIUS server MUST provide this attribute if inbound MPPE is
5554 .It RAD_MICROSOFT_MS_MPPE_SEND_KEY
5556 .Dv RAD_VENDOR_MICROSOFT
5557 vendor specific attribute is supplied, it is value is used as the master
5558 key for encryption of outgoing data.
5559 When clients are authenticated using
5560 MSCHAPv2, the RADIUS server MUST provide this attribute if outbound MPPE is
5564 Values received from the RADIUS server may be viewed using
5566 .It set rad_alive Ar timeout
5567 When RADIUS is configured, setting
5573 to sent RADIUS accounting information to the RADIUS server every
5576 .It set rad_port_id Ar option
5577 When RADIUS is configured, setting the
5579 value allows to specify what should be sent to the RADIUS server as
5587 PID of the corresponding tunnel.
5592 index of the interface as returned by
5593 .Xr if_nametoindex 3 .
5595 keeps the default behavior.
5597 .It set reconnect Ar timeout ntries
5598 Should the line drop unexpectedly (due to loss of CD or LQR
5599 failure), a connection will be re-established after the given
5601 The line will be re-connected at most
5610 will result in a variable pause, somewhere between 1 and 30 seconds.
5611 .It set recvpipe Op Ar value
5612 This sets the routing table RECVPIPE value.
5613 The optimum value is just over twice the MTU value.
5616 is unspecified or zero, the default kernel controlled value is used.
5617 .It set redial Ar secs Ns Xo
5620 .Oc Ns Op . Ns Ar next
5624 can be instructed to attempt to redial
5627 If more than one phone number is specified (see
5631 is taken before dialing each number.
5634 is taken before starting at the first number again.
5637 may be used here in place of
5641 causing a random delay of between 1 and 30 seconds.
5645 is specified, its value is added onto
5651 will only be incremented at most
5659 delay will be effective, even after
5661 has been exceeded, so an immediate manual dial may appear to have
5663 If an immediate dial is required, a
5665 should immediately follow the
5670 description above for further details.
5671 .It set sendpipe Op Ar value
5672 This sets the routing table SENDPIPE value.
5673 The optimum value is just over twice the MTU value.
5676 is unspecified or zero, the default kernel controlled value is used.
5677 .It "set server|socket" Ar TcpPort Ns No \&| Ns Xo
5678 .Ar LocalName Ns No |none|open|closed
5679 .Op password Op Ar mask
5683 to listen on the given socket or
5685 for incoming command connections.
5691 to close any existing socket and clear the socket configuration.
5696 to attempt to re-open the port.
5701 to close the open port.
5703 If you wish to specify a local domain socket,
5705 must be specified as an absolute file name, otherwise it is assumed
5706 to be the name or number of a TCP port.
5707 You may specify the octal umask to be used with a local domain socket.
5713 for details of how to translate TCP port names.
5715 You must also specify the password that must be entered by the client
5718 variable above) when connecting to this socket.
5720 specified as an empty string, no password is required for connecting clients.
5722 When specifying a local domain socket, the first
5724 sequence found in the socket name will be replaced with the current
5725 interface unit number.
5726 This is useful when you wish to use the same
5727 profile for more than one connection.
5729 In a similar manner TCP sockets may be prefixed with the
5731 character, in which case the current interface unit number is added to
5736 with a server socket, the
5738 command is the preferred mechanism of communications.
5741 can also be used, but link encryption may be implemented in the future, so
5749 interact with the diagnostic socket.
5750 .It set speed Ar value
5751 This sets the speed of the serial device.
5752 If speed is specified as
5755 treats the device as a synchronous device.
5757 Certain device types will know whether they should be specified as
5758 synchronous or asynchronous.
5759 These devices will override incorrect
5760 settings and log a warning to this effect.
5761 .It set stopped Op Ar LCPseconds Op Ar CCPseconds
5762 If this option is set,
5764 will time out after the given FSM (Finite State Machine) has been in
5765 the stopped state for the given number of
5767 This option may be useful if the peer sends a terminate request,
5768 but never actually closes the connection despite our sending a terminate
5770 This is also useful if you wish to
5771 .Dq set openmode passive
5772 and time out if the peer does not send a Configure Request within the
5775 .Dq set log +lcp +ccp
5778 log the appropriate state transitions.
5780 The default value is zero, where
5782 does not time out in the stopped state.
5784 This value should not be set to less than the openmode delay (see
5787 .It set timeout Ar idleseconds Op Ar mintimeout
5788 This command allows the setting of the idle timer.
5789 Refer to the section titled
5790 .Sx SETTING THE IDLE TIMER
5791 for further details.
5797 will never idle out before the link has been up for at least that number
5805 This command controls the ports that
5807 prioritizes when transmitting data.
5808 The default priority TCP ports
5809 are ports 21 (ftp control), 22 (ssh), 23 (telnet), 513 (login), 514 (shell),
5810 543 (klogin) and 544 (kshell).
5811 There are no priority UDP ports by default.
5826 are given, the priority port lists are cleared (although if
5830 is specified, only that list is cleared).
5833 argument is prefixed with a plus
5837 the current list is adjusted, otherwise the list is reassigned.
5839 prefixed with a plus or not prefixed at all are added to the list and
5841 prefixed with a minus are removed from the list.
5845 is specified, all priority port lists are disabled and even
5847 packets are not prioritised.
5848 .It set vj slotcomp on|off
5851 whether it should attempt to negotiate VJ slot compression.
5852 By default, slot compression is turned
5854 .It set vj slots Ar nslots
5855 This command sets the initial number of slots that
5857 will try to negotiate with the peer when VJ compression is enabled (see the
5860 It defaults to a value of 16.
5869 .It shell|! Op Ar command
5872 is not specified a shell is invoked according to the
5874 environment variable.
5875 Otherwise, the given
5878 Word replacement is done in the same way as for the
5880 command as described above.
5882 Use of the !\& character
5883 requires a following space as with any of the other commands.
5884 You should note that this command is executed in the foreground;
5886 will not continue running until this process has exited.
5889 command if you wish processing to happen in the background.
5891 This command allows the user to examine the following:
5894 Show the current bundle settings.
5896 Show the current CCP compression statistics.
5898 Show the current VJ compression statistics.
5900 Show the current escape characters.
5901 .It show filter Op Ar name
5902 List the current rules for the given filter.
5905 is not specified, all filters are shown.
5907 Show the current HDLC statistics.
5909 Give a summary of available show commands.
5911 Show the current interface information
5915 Show the current IPCP statistics.
5917 Show the protocol layers currently in use.
5919 Show the current LCP statistics.
5920 .It show Op data Ns Xo
5923 Show high level link information.
5925 Show a list of available logical links.
5927 Show the current log values.
5929 Show current memory statistics.
5931 Show the current NCP statistics.
5933 Show low level link information.
5935 Show Multi-link information.
5937 Show current protocol totals.
5939 Show the current routing tables.
5941 Show the current stopped timeouts.
5943 Show the active alarm timers.
5945 Show the current version number of
5950 Go into terminal mode.
5951 Characters typed at the keyboard are sent to the device.
5952 Characters read from the device are displayed on the screen.
5957 automatically enables Packet Mode and goes back into command mode.
5962 Read the example configuration files.
5963 They are a good source of information.
5972 to get online information about what is available.
5974 The following URLs contain useful information:
5975 .Bl -bullet -compact
5977 http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/faq/ppp.html
5979 http://www.FreeBSD.org/doc/handbook/userppp.html
5985 refers to four files:
5991 These files are placed in the
5995 .It Pa /etc/ppp/ppp.conf
5996 System default configuration file.
5997 .It Pa /etc/ppp/ppp.secret
5998 An authorisation file for each system.
5999 .It Pa /etc/ppp/ppp.linkup
6000 A file to check when
6002 establishes a network level connection.
6003 .It Pa /etc/ppp/ppp.linkdown
6004 A file to check when
6006 closes a network level connection.
6007 .It Pa /var/log/ppp.log
6008 Logging and debugging information file.
6009 Note, this name is specified in
6010 .Pa /etc/syslog.conf .
6013 for further details.
6014 .It Pa /var/spool/lock/LCK..*
6015 tty port locking file.
6018 for further details.
6019 .It Pa /var/run/tunN.pid
6020 The process id (pid) of the
6022 program connected to the tunN device, where
6024 is the number of the device.
6025 .It Pa /var/run/ttyXX.if
6026 The tun interface used by this port.
6027 Again, this file is only created in
6033 .It Pa /etc/services
6034 Get port number if port number is using service name.
6035 .It Pa /var/run/ppp-authname-class-value
6036 In multi-link mode, local domain sockets are created using the peer
6039 the peer endpoint discriminator class
6041 and the peer endpoint discriminator value
6043 As the endpoint discriminator value may be a binary value, it is turned
6044 to HEX to determine the actual file name.
6046 This socket is used to pass links between different instances of
6058 ifdef({LOCALNAT},{},{.Xr libalias 3 ,
6060 ifdef({LOCALRAD},{},{.Xr libradius 3 ,
6089 This program was originally written by
6090 .An Toshiharu OHNO Aq tony-o@iij.ad.jp ,
6091 and was submitted to
6094 .An Atsushi Murai Aq amurai@spec.co.jp .
6096 It was substantially modified during 1997 by
6097 .An Brian Somers Aq brian@Awfulhak.org ,
6100 in November that year
6101 (just after the 2.2 release).
6103 Most of the code was rewritten by
6105 in early 1998 when multi-link ppp support was added.
projects / FreeBSD / stable / 8.git / blob