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 ISDN.
350 is given a raw B-channel i4b device to open as a link, it is able to talk
353 daemon to establish an ISDN connection.
354 .It Supports PPP over Ethernet (rfc 2516).
357 is given a device specification of the format
358 .No PPPoE: Ns Ar iface Ns Xo
359 .Op \&: Ns Ar provider Ns
373 On systems that do not support
375 an external program such as
378 .It "Supports IETF draft Predictor-1 (rfc 1978) and DEFLATE (rfc 1979) compression."
380 supports not only VJ-compression but also Predictor-1 and DEFLATE compression.
381 Normally, a modem has built-in compression (e.g., v42.bis) and the system
382 may receive higher data rates from it as a result of such compression.
383 While this is generally a good thing in most other situations, this
384 higher speed data imposes a penalty on the system by increasing the
385 number of serial interrupts the system has to process in talking to the
386 modem and also increases latency.
387 Unlike VJ-compression, Predictor-1 and DEFLATE compression pre-compresses
389 network traffic flowing through the link, thus reducing overheads to a
391 .It Supports Microsoft's IPCP extensions (rfc 1877).
392 Name Server Addresses and NetBIOS Name Server Addresses can be negotiated
393 with clients using the Microsoft
395 stack (i.e., Win95, WinNT)
396 .It Supports Multi-link PPP (rfc 1990)
397 It is possible to configure
399 to open more than one physical connection to the peer, combining the
400 bandwidth of all links for better throughput.
401 .It Supports MPPE (draft-ietf-pppext-mppe)
402 MPPE is Microsoft Point to Point Encryption scheme.
403 It is possible to configure
405 to participate in Microsoft's Windows VPN.
408 can only get encryption keys from CHAP 81 authentication.
410 must be compiled with DES for MPPE to operate.
411 .It Supports IPV6CP (rfc 2023).
412 An IPv6 connection can be made in addition to or instead of the normal
425 will not run if the invoking user id is not zero.
426 This may be overridden by using the
429 .Pa /etc/ppp/ppp.conf .
430 When running as a normal user,
432 switches to user id 0 in order to alter the system routing table, set up
433 system lock files and read the ppp configuration files.
434 All external commands (executed via the "shell" or "!bg" commands) are executed
435 as the user id that invoked
439 logging facility if you are interested in what exactly is done as user id
444 you may need to deal with some initial configuration details.
447 Make sure that your system has a group named
451 file and that the group contains the names of all users expected to use
455 manual page for details.
456 Each of these users must also be given access using the
459 .Pa /etc/ppp/ppp.conf .
466 A common log file name is
467 .Pa /var/log/ppp.log .
468 To make output go to this file, put the following lines in the
471 .Bd -literal -offset indent
473 *.*<TAB>/var/log/ppp.log
476 It is possible to have more than one
478 log file by creating a link to the
486 .Bd -literal -offset indent
488 *.*<TAB>/var/log/ppp0.log
492 .Pa /etc/syslog.conf .
493 Do not forget to send a
498 .Pa /etc/syslog.conf .
500 Although not strictly relevant to
502 operation, you should configure your resolver so that it works correctly.
503 This can be done by configuring a local DNS
506 or by adding the correct
509 .Pa /etc/resolv.conf .
512 manual page for details.
514 Alternatively, if the peer supports it,
516 can be configured to ask the peer for the nameserver address(es) and to
524 commands below for details.
527 In the following examples, we assume that your machine name is
533 above) with no arguments, you are presented with a prompt:
534 .Bd -literal -offset indent
540 part of your prompt should always be in upper case.
541 If it is in lower case, it means that you must supply a password using the
544 This only ever happens if you connect to a running version of
546 and have not authenticated yourself using the correct password.
548 You can start by specifying the device name and speed:
549 .Bd -literal -offset indent
550 ppp ON awfulhak> set device /dev/cuad0
551 ppp ON awfulhak> set speed 38400
554 Normally, hardware flow control (CTS/RTS) is used.
556 certain circumstances (as may happen when you are connected directly
557 to certain PPP-capable terminal servers), this may result in
559 hanging as soon as it tries to write data to your communications link
560 as it is waiting for the CTS (clear to send) signal - which will never
562 Thus, if you have a direct line and cannot seem to make a
563 connection, try turning CTS/RTS off with
565 If you need to do this, check the
567 description below too - you will probably need to
568 .Dq set accmap 000a0000 .
570 Usually, parity is set to
575 Parity is a rather archaic error checking mechanism that is no
576 longer used because modern modems do their own error checking, and most
577 link-layer protocols (that is what
579 is) use much more reliable checking mechanisms.
580 Parity has a relatively
581 huge overhead (a 12.5% increase in traffic) and as a result, it is always
588 However, some ISPs (Internet Service Providers) may use
589 specific parity settings at connection time (before
592 Notably, Compuserve insist on even parity when logging in:
593 .Bd -literal -offset indent
594 ppp ON awfulhak> set parity even
597 You can now see what your current device settings look like:
598 .Bd -literal -offset indent
599 ppp ON awfulhak> show physical
603 Link Type: interactive
609 Device List: /dev/cuad0
610 Characteristics: 38400bps, cs8, even parity, CTS/RTS on
613 0 octets in, 0 octets out
618 The term command can now be used to talk directly to the device:
619 .Bd -literal -offset indent
620 ppp ON awfulhak> term
626 Password: myisppassword
630 When the peer starts to talk in
633 detects this automatically and returns to command mode.
634 .Bd -literal -offset indent
635 ppp ON awfulhak> # No link has been established
636 Ppp ON awfulhak> # We've connected & finished LCP
637 PPp ON awfulhak> # We've authenticated
638 PPP ON awfulhak> # We've agreed IP numbers
641 If it does not, it is probable that the peer is waiting for your end to
647 configuration packets to the peer, use the
649 command to drop out of terminal mode and enter packet mode.
651 If you never even receive a login prompt, it is quite likely that the
652 peer wants to use PAP or CHAP authentication instead of using Unix-style
653 login/password authentication.
654 To set things up properly, drop back to
655 the prompt and set your authentication name and key, then reconnect:
656 .Bd -literal -offset indent
658 ppp ON awfulhak> set authname myispusername
659 ppp ON awfulhak> set authkey myisppassword
660 ppp ON awfulhak> term
667 You may need to tell ppp to initiate negotiations with the peer here too:
668 .Bd -literal -offset indent
670 ppp ON awfulhak> # No link has been established
671 Ppp ON awfulhak> # We've connected & finished LCP
672 PPp ON awfulhak> # We've authenticated
673 PPP ON awfulhak> # We've agreed IP numbers
676 You are now connected!
679 in the prompt has changed to capital letters to indicate that you have
681 If only some of the three Ps go uppercase, wait until
682 either everything is uppercase or lowercase.
683 If they revert to lowercase, it means that
685 could not successfully negotiate with the peer.
686 A good first step for troubleshooting at this point would be to
687 .Bd -literal -offset indent
688 ppp ON awfulhak> set log local phase lcp ipcp
694 command description below for further details.
695 If things fail at this point,
696 it is quite important that you turn logging on and try again.
698 important that you note any prompt changes and report them to anyone trying
701 When the link is established, the show command can be used to see how
703 .Bd -literal -offset indent
704 PPP ON awfulhak> show physical
705 * Modem related information is shown here *
706 PPP ON awfulhak> show ccp
707 * CCP (compression) related information is shown here *
708 PPP ON awfulhak> show lcp
709 * LCP (line control) related information is shown here *
710 PPP ON awfulhak> show ipcp
711 * IPCP (IP) related information is shown here *
712 PPP ON awfulhak> show ipv6cp
713 * IPV6CP (IPv6) related information is shown here *
714 PPP ON awfulhak> show link
715 * Link (high level) related information is shown here *
716 PPP ON awfulhak> show bundle
717 * Logical (high level) connection related information is shown here *
720 At this point, your machine has a host route to the peer.
722 that you can only make a connection with the host on the other side
724 If you want to add a default route entry (telling your
725 machine to send all packets without another routing entry to the other
728 link), enter the following command:
729 .Bd -literal -offset indent
730 PPP ON awfulhak> add default HISADDR
735 represents the IP address of the connected peer.
738 command fails due to an existing route, you can overwrite the existing
740 .Bd -literal -offset indent
741 PPP ON awfulhak> add! default HISADDR
744 This command can also be executed before actually making the connection.
745 If a new IP address is negotiated at connection time,
747 will update your default route accordingly.
749 You can now use your network applications (ping, telnet, ftp, etc.)
750 in other windows or terminals on your machine.
751 If you wish to reuse the current terminal, you can put
753 into the background using your standard shell suspend and background
761 section for details on all available commands.
762 .Sh AUTOMATIC DIALING
763 To use automatic dialing, you must prepare some Dial and Login chat scripts.
764 See the example definitions in
765 .Pa /usr/share/examples/ppp/ppp.conf.sample
767 .Pa /etc/ppp/ppp.conf
769 Each line contains one comment, inclusion, label or command:
772 A line starting with a
774 character is treated as a comment line.
775 Leading whitespace are ignored when identifying comment lines.
777 An inclusion is a line beginning with the word
779 It must have one argument - the file to {include}.
781 .Dq {!include} ~/.ppp.conf
782 for compatibility with older versions of
785 A label name starts in the first column and is followed by
789 A command line must contain a space or tab in the first column.
791 A string starting with the
793 character is substituted with the value of the environment variable by
795 Likewise, a string starting with the
797 character is substituted with the full path to the home directory of
798 the user account by the same name, and the
800 character by itself is substituted with the full path to the home directory
802 If you want to include a literal
806 character in a command or argument, enclose them in double quotes, e.g.,
807 .Bd -literal -offset indent
808 set password "pa$ss~word"
813 .Pa /etc/ppp/ppp.conf
814 file should consist of at least a
817 This section is always executed.
818 It should also contain
819 one or more sections, named according to their purpose, for example,
821 would represent your ISP, and
823 would represent an incoming
826 You can now specify the destination label name when you invoke
828 Commands associated with the
830 label are executed, followed by those associated with the destination
834 is started with no arguments, the
836 section is still executed.
837 The load command can be used to manually load a section from the
838 .Pa /etc/ppp/ppp.conf
840 .Bd -literal -offset indent
841 ppp ON awfulhak> load MyISP
844 Note, no action is taken by
846 after a section is loaded, whether it is the result of passing a label on
847 the command line or using the
850 Only the commands specified for that label in the configuration
852 However, when invoking
859 switches, the link mode tells
861 to establish a connection.
864 command below for further details.
866 Once the connection is made, the
868 portion of the prompt will change to
870 .Bd -literal -offset indent
873 ppp ON awfulhak> dial
879 The Ppp prompt indicates that
881 has entered the authentication phase.
882 The PPp prompt indicates that
884 has entered the network phase.
885 The PPP prompt indicates that
887 has successfully negotiated a network layer protocol and is in
891 .Pa /etc/ppp/ppp.linkup
892 file is available, its contents are executed
895 connection is established.
899 .Pa /usr/share/examples/ppp/ppp.conf.sample
900 which runs a script in the background after the connection is established
905 commands below for a description of possible substitution strings).
906 Similarly, when a connection is closed, the contents of the
907 .Pa /etc/ppp/ppp.linkdown
909 Both of these files have the same format as
910 .Pa /etc/ppp/ppp.conf .
912 In previous versions of
914 it was necessary to re-add routes such as the default route in the
920 where all routes that contain the
926 literals will automatically be updated when the values of these variables
928 .Sh BACKGROUND DIALING
929 If you want to establish a connection using
931 non-interactively (such as from a
935 job) you should use the
942 attempts to establish the connection immediately.
944 numbers are specified, each phone number will be tried once.
945 If the attempt fails,
947 exits immediately with a non-zero exit code.
950 becomes a daemon, and returns an exit status of zero to its caller.
951 The daemon exits automatically if the connection is dropped by the
952 remote system, or it receives a
956 Demand dialing is enabled with the
961 You must also specify the destination label in
962 .Pa /etc/ppp/ppp.conf
966 command to {define} the remote peers IP address.
968 .Pa /usr/share/examples/ppp/ppp.conf.sample )
969 .Bd -literal -offset indent
979 runs as a daemon but you can still configure or examine its
980 configuration by using the
983 .Pa /etc/ppp/ppp.conf ,
985 .Dq Li "set server +3000 mypasswd" )
986 and connecting to the diagnostic port as follows:
987 .Bd -literal -offset indent
988 # pppctl 3000 (assuming tun0)
990 PPP ON awfulhak> show who
991 tcp (127.0.0.1:1028) *
996 command lists users that are currently connected to
999 If the diagnostic socket is closed or changed to a different
1000 socket, all connections are immediately dropped.
1004 mode, when an outgoing packet is detected,
1006 will perform the dialing action (chat script) and try to connect
1010 mode, the dialing action is performed any time the line is found
1012 If the connect fails, the default behaviour is to wait 30 seconds
1013 and then attempt to connect when another outgoing packet is detected.
1014 This behaviour can be changed using the
1018 .No set redial Ar secs Ns Xo
1021 .Oc Ns Op . Ns Ar next
1025 .Bl -tag -width attempts -compact
1027 is the number of seconds to wait before attempting
1029 If the argument is the literal string
1031 the delay period is a random value between 1 and 30 seconds inclusive.
1033 is the number of seconds that
1035 should be incremented each time a new dial attempt is made.
1036 The timeout reverts to
1038 only after a successful connection is established.
1039 The default value for
1043 is the maximum number of times
1047 The default value for
1051 is the number of seconds to wait before attempting
1052 to dial the next number in a list of numbers (see the
1055 The default is 3 seconds.
1056 Again, if the argument is the literal string
1058 the delay period is a random value between 1 and 30 seconds.
1060 is the maximum number of times to try to connect for each outgoing packet
1061 that triggers a dial.
1062 The previous value is unchanged if this parameter is omitted.
1063 If a value of zero is specified for
1066 will keep trying until a connection is made.
1070 .Bd -literal -offset indent
1074 will attempt to connect 4 times for each outgoing packet that causes
1075 a dial attempt with a 3 second delay between each number and a 10 second
1076 delay after all numbers have been tried.
1077 If multiple phone numbers
1078 are specified, the total number of attempts is still 4 (it does not
1079 attempt each number 4 times).
1083 .Bd -literal -offset indent
1084 set redial 10+10-5.3 20
1089 to attempt to connect 20 times.
1090 After the first attempt,
1092 pauses for 10 seconds.
1093 After the next attempt it pauses for 20 seconds
1094 and so on until after the sixth attempt it pauses for 1 minute.
1095 The next 14 pauses will also have a duration of one minute.
1098 connects, disconnects and fails to connect again, the timeout starts again
1101 Modifying the dial delay is very useful when running
1105 mode on both ends of the link.
1106 If each end has the same timeout,
1107 both ends wind up calling each other at the same time if the link
1108 drops and both ends have packets queued.
1109 At some locations, the serial link may not be reliable, and carrier
1110 may be lost at inappropriate times.
1111 It is possible to have
1113 redial should carrier be unexpectedly lost during a session.
1114 .Bd -literal -offset indent
1115 set reconnect timeout ntries
1120 to re-establish the connection
1122 times on loss of carrier with a pause of
1124 seconds before each try.
1126 .Bd -literal -offset indent
1132 that on an unexpected loss of carrier, it should wait
1134 seconds before attempting to reconnect.
1135 This may happen up to
1140 The default value of ntries is zero (no reconnect).
1141 Care should be taken with this option.
1142 If the local timeout is slightly
1143 longer than the remote timeout, the reconnect feature will always be
1144 triggered (up to the given number of times) after the remote side
1145 times out and hangs up.
1146 NOTE: In this context, losing too many LQRs constitutes a loss of
1147 carrier and will trigger a reconnect.
1150 flag is specified, all phone numbers are dialed at most once until
1151 a connection is made.
1152 The next number redial period specified with the
1154 command is honoured, as is the reconnect tries value.
1156 value is less than the number of phone numbers specified, not all
1157 the specified numbers will be tried.
1158 To terminate the program, type
1159 .Bd -literal -offset indent
1160 PPP ON awfulhak> close
1161 ppp ON awfulhak> quit all
1166 command will terminate the
1170 connection but not the
1178 .Sh RECEIVING INCOMING PPP CONNECTIONS (Method 1)
1179 To handle an incoming
1181 connection request, follow these steps:
1184 Make sure the modem and (optionally)
1186 is configured correctly.
1187 .Bl -bullet -compact
1189 Use Hardware Handshake (CTS/RTS) for flow control.
1191 Modem should be set to NO echo back (ATE0) and NO results string (ATQ1).
1199 on the port where the modem is attached.
1202 .Dl ttyd1 Qo /usr/libexec/getty std.38400 Qc dialup on secure
1204 Do not forget to send a
1208 process to start the
1213 It is usually also necessary to train your modem to the same DTR speed
1215 .Bd -literal -offset indent
1217 ppp ON awfulhak> set device /dev/cuad1
1218 ppp ON awfulhak> set speed 38400
1219 ppp ON awfulhak> term
1220 deflink: Entering terminal mode on /dev/cuad1
1231 ppp ON awfulhak> quit
1235 .Pa /usr/local/bin/ppplogin
1236 file with the following contents:
1237 .Bd -literal -offset indent
1239 exec /usr/sbin/ppp -direct incoming
1246 work with stdin and stdout.
1249 to connect to a configured diagnostic port, in the same manner as with
1255 section must be set up in
1256 .Pa /etc/ppp/ppp.conf .
1260 section contains the
1262 command as appropriate.
1264 Prepare an account for the incoming user.
1266 ppp:xxxx:66:66:PPP Login User:/home/ppp:/usr/local/bin/ppplogin
1269 Refer to the manual entries for
1275 Support for IPCP Domain Name Server and NetBIOS Name Server negotiation
1276 can be enabled using the
1281 Refer to their descriptions below.
1283 .Sh RECEIVING INCOMING PPP CONNECTIONS (Method 2)
1284 This method differs in that we use
1286 to authenticate the connection rather than
1290 Configure your default section in
1292 with automatic ppp recognition by specifying the
1297 :pp=/usr/local/bin/ppplogin:\\
1301 Configure your serial device(s), enable a
1304 .Pa /usr/local/bin/ppplogin
1305 as in the first three steps for method 1 above.
1313 .Pa /etc/ppp/ppp.conf
1316 label (or whatever label
1321 .Pa /etc/ppp/ppp.secret
1322 for each incoming user:
1331 detects a ppp connection (by recognising the HDLC frame headers), it runs
1332 .Dq /usr/local/bin/ppplogin .
1336 that either PAP or CHAP are enabled as above.
1337 If they are not, you are
1338 allowing anybody to establish a ppp session with your machine
1340 a password, opening yourself up to all sorts of potential attacks.
1341 .Sh AUTHENTICATING INCOMING CONNECTIONS
1342 Normally, the receiver of a connection requires that the peer
1343 authenticates itself.
1344 This may be done using
1346 but alternatively, you can use PAP or CHAP.
1347 CHAP is the more secure of the two, but some clients may not support it.
1348 Once you decide which you wish to use, add the command
1352 to the relevant section of
1355 You must then configure the
1356 .Pa /etc/ppp/ppp.secret
1358 This file contains one line per possible client, each line
1359 containing up to five fields:
1362 .Ar hisaddr Op Ar label Op Ar callback-number
1369 specify the client username and password.
1374 and PAP is being used,
1376 will look up the password database
1378 when authenticating.
1379 If the client does not offer a suitable response based on any
1380 .Ar name Ns No / Ns Ar key
1383 authentication fails.
1385 If authentication is successful,
1388 is used when negotiating IP numbers.
1391 command for details.
1393 If authentication is successful and
1395 is specified, the current system label is changed to match the given
1397 This will change the subsequent parsing of the
1403 If authentication is successful and
1409 the client will be called back on the given number.
1410 If CBCP is being used,
1412 may also contain a list of numbers or a
1417 The value will be used in
1419 subsequent CBCP phase.
1420 .Sh PPP OVER TCP and UDP (a.k.a Tunnelling)
1423 over a serial link, it is possible to
1424 use a TCP connection instead by specifying the host, port and protocol as the
1427 .Dl set device ui-gate:6669/tcp
1429 Instead of opening a serial device,
1431 will open a TCP connection to the given machine on the given
1433 It should be noted however that
1435 does not use the telnet protocol and will be unable to negotiate
1436 with a telnet server.
1437 You should set up a port for receiving this
1439 connection on the receiving machine (ui-gate).
1440 This is done by first updating
1442 to name the service:
1444 .Dl ppp-in 6669/tcp # Incoming PPP connections over TCP
1450 how to deal with incoming connections on that port:
1452 .Dl ppp-in stream tcp nowait root /usr/sbin/ppp ppp -direct ppp-in
1454 Do not forget to send a
1458 after you have updated
1459 .Pa /etc/inetd.conf .
1460 Here, we use a label named
1463 .Pa /etc/ppp/ppp.conf
1464 on ui-gate (the receiver) should contain the following:
1465 .Bd -literal -offset indent
1468 set ifaddr 10.0.4.1 10.0.4.2
1472 .Pa /etc/ppp/ppp.linkup
1474 .Bd -literal -offset indent
1476 add 10.0.1.0/24 HISADDR
1479 It is necessary to put the
1483 to ensure that the route is only added after
1485 has negotiated and assigned addresses to its interface.
1487 You may also want to enable PAP or CHAP for security.
1488 To enable PAP, add the following line:
1489 .Bd -literal -offset indent
1493 You will also need to create the following entry in
1494 .Pa /etc/ppp/ppp.secret :
1495 .Bd -literal -offset indent
1496 MyAuthName MyAuthPasswd
1503 the password is looked up in the
1508 .Pa /etc/ppp/ppp.conf
1509 on awfulhak (the initiator) should contain the following:
1510 .Bd -literal -offset indent
1513 set device ui-gate:ppp-in/tcp
1516 set log Phase Chat Connect hdlc LCP IPCP IPV6CP CCP tun
1517 set ifaddr 10.0.4.2 10.0.4.1
1520 with the route setup in
1521 .Pa /etc/ppp/ppp.linkup :
1522 .Bd -literal -offset indent
1524 add 10.0.2.0/24 HISADDR
1527 Again, if you are enabling PAP, you will also need this in the
1528 .Pa /etc/ppp/ppp.conf
1530 .Bd -literal -offset indent
1531 set authname MyAuthName
1532 set authkey MyAuthKey
1535 We are assigning the address of 10.0.4.1 to ui-gate, and the address
1536 10.0.4.2 to awfulhak.
1537 To open the connection, just type
1539 .Dl awfulhak # ppp -background ui-gate
1541 The result will be an additional "route" on awfulhak to the
1542 10.0.2.0/24 network via the TCP connection, and an additional
1543 "route" on ui-gate to the 10.0.1.0/24 network.
1544 The networks are effectively bridged - the underlying TCP
1545 connection may be across a public network (such as the
1548 traffic is conceptually encapsulated
1549 (although not packet by packet) inside the TCP stream between
1552 The major disadvantage of this mechanism is that there are two
1553 "guaranteed delivery" mechanisms in place - the underlying TCP
1554 stream and whatever protocol is used over the
1556 link - probably TCP again.
1557 If packets are lost, both levels will
1558 get in each others way trying to negotiate sending of the missing
1561 To avoid this overhead, it is also possible to do all this using
1562 UDP instead of TCP as the transport by simply changing the protocol
1563 from "tcp" to "udp".
1564 When using UDP as a transport,
1566 will operate in synchronous mode.
1567 This is another gain as the incoming
1568 data does not have to be rearranged into packets.
1570 Care should be taken when adding a default route through a tunneled
1572 It is quite common for the default route
1574 .Pa /etc/ppp/ppp.linkup )
1575 to end up routing the link's TCP connection through the tunnel,
1576 effectively garrotting the connection.
1577 To avoid this, make sure you add a static route for the benefit of
1579 .Bd -literal -offset indent
1582 set device ui-gate:ppp-in/tcp
1589 is the IP number that your route to
1593 When routing your connection accross a public network such as the Internet,
1594 it is preferable to encrypt the data.
1595 This can be done with the help of the MPPE protocol, although currently this
1596 means that you will not be able to also compress the traffic as MPPE is
1597 implemented as a compression layer (thank Microsoft for this).
1598 To enable MPPE encryption, add the following lines to
1599 .Pa /etc/ppp/ppp.conf
1601 .Bd -literal -offset indent
1603 disable deflate pred1
1607 ensuring that you have put the requisite entry in
1608 .Pa /etc/ppp/ppp.secret
1609 (MSCHAPv2 is challenge based, so
1613 MSCHAPv2 and MPPE are accepted by default, so the client end should work
1614 without any additional changes (although ensure you have
1619 .Sh NETWORK ADDRESS TRANSLATION (PACKET ALIASING)
1622 command line option enables network address translation (a.k.a.\& packet
1626 host to act as a masquerading gateway for other computers over
1627 a local area network.
1628 Outgoing IP packets are NAT'd so that they appear to come from the
1630 host, and incoming packets are de-NAT'd so that they are routed
1631 to the correct machine on the local area network.
1632 NAT allows computers on private, unregistered subnets to have Internet
1633 access, although they are invisible from the outside world.
1636 operation should first be verified with network address translation disabled.
1639 option should be switched on, and network applications (web browser,
1644 should be checked on the
1647 Finally, the same or similar applications should be checked on other
1648 computers in the LAN.
1649 If network applications work correctly on the
1651 host, but not on other machines in the LAN, then the masquerading
1652 software is working properly, but the host is either not forwarding
1653 or possibly receiving IP packets.
1654 Check that IP forwarding is enabled in
1656 and that other machines have designated the
1658 host as the gateway for the LAN.
1659 .Sh PACKET FILTERING
1660 This implementation supports packet filtering.
1661 There are four kinds of
1671 Here are the basics:
1674 A filter definition has the following syntax:
1683 .Ar src_addr Ns Op / Ns Ar width
1684 .Op Ar dst_addr Ns Op / Ns Ar width
1686 .Ar [ proto Op src Ar cmp port
1691 .Op timeout Ar secs ]
1703 is a numeric value between
1707 specifying the rule number.
1708 Rules are specified in numeric order according to
1719 in which case, if a given packet matches the rule, the associated action
1720 is taken immediately.
1722 can also be specified as
1724 to clear the action associated with that particular rule, or as a new
1725 rule number greater than the current rule.
1726 In this case, if a given
1727 packet matches the current rule, the packet will next be matched against
1728 the new rule number (rather than the next rule number).
1732 may optionally be followed with an exclamation mark
1736 to reverse the sense of the following match.
1738 .Op Ar src_addr Ns Op / Ns Ar width
1740 .Op Ar dst_addr Ns Op / Ns Ar width
1741 are the source and destination IP number specifications.
1744 is specified, it gives the number of relevant netmask bits,
1745 allowing the specification of an address range.
1751 may be given the values
1757 (refer to the description of the
1759 command for a description of these values).
1760 When these values are used,
1761 the filters will be updated any time the values change.
1762 This is similar to the behaviour of the
1767 may be any protocol from
1776 meaning less-than, equal and greater-than respectively.
1778 can be specified as a numeric port or by service name from
1786 flags are only allowed when
1790 and represent the TH_ACK, TH_SYN and TH_FIN or TH_RST TCP flags respectively.
1792 The timeout value adjusts the current idle timeout to at least
1795 If a timeout is given in the alive filter as well as in the in/out
1796 filter, the in/out value is used.
1797 If no timeout is given, the default timeout (set using
1799 and defaulting to 180 seconds) is used.
1803 Each filter can hold up to 40 rules, starting from rule 0.
1804 The entire rule set is not effective until rule 0 is defined,
1805 i.e., the default is to allow everything through.
1807 If no rule in a defined set of rules matches a packet, that packet will
1808 be discarded (blocked).
1809 If there are no rules in a given filter, the packet will be permitted.
1811 It is possible to filter based on the payload of UDP frames where those
1817 .Ar filter-decapsulation
1818 option below for further details.
1821 .Dq set filter Ar name No -1
1826 .Pa /usr/share/examples/ppp/ppp.conf.sample .
1827 .Sh SETTING THE IDLE TIMER
1828 To check/set the idle timer, use the
1833 .Bd -literal -offset indent
1834 ppp ON awfulhak> set timeout 600
1837 The timeout period is measured in seconds, the default value for which
1840 To disable the idle timer function, use the command
1841 .Bd -literal -offset indent
1842 ppp ON awfulhak> set timeout 0
1849 modes, the idle timeout is ignored.
1852 mode, when the idle timeout causes the
1857 program itself remains running.
1858 Another trigger packet will cause it to attempt to re-establish the link.
1859 .Sh PREDICTOR-1 and DEFLATE COMPRESSION
1861 supports both Predictor type 1 and deflate compression.
1864 will attempt to use (or be willing to accept) both compression protocols
1865 when the peer agrees
1867 The deflate protocol is preferred by
1873 commands if you wish to disable this functionality.
1875 It is possible to use a different compression algorithm in each direction
1876 by using only one of
1880 (assuming that the peer supports both algorithms).
1882 By default, when negotiating DEFLATE,
1884 will use a window size of 15.
1887 command if you wish to change this behaviour.
1889 A special algorithm called DEFLATE24 is also available, and is disabled
1890 and denied by default.
1891 This is exactly the same as DEFLATE except that
1892 it uses CCP ID 24 to negotiate.
1895 to successfully negotiate DEFLATE with
1898 .Sh CONTROLLING IP ADDRESS
1901 uses IPCP to negotiate IP addresses.
1902 Each side of the connection
1903 specifies the IP address that it is willing to use, and if the requested
1904 IP address is acceptable then
1906 returns an ACK to the requester.
1909 returns NAK to suggest that the peer use a different IP address.
1911 both sides of the connection agree to accept the received request (and
1912 send an ACK), IPCP is set to the open state and a network level connection
1914 To control this IPCP behaviour, this implementation has the
1916 command for defining the local and remote IP address:
1917 .Bd -ragged -offset indent
1918 .No set ifaddr Oo Ar src_addr Ns
1920 .Oo Ar dst_addr Ns Op / Ns Ar \&nn
1930 is the IP address that the local side is willing to use,
1932 is the IP address which the remote side should use and
1934 is the netmask that should be used.
1936 defaults to the current
1939 defaults to 0.0.0.0, and
1941 defaults to whatever mask is appropriate for
1943 It is only possible to make
1945 smaller than the default.
1946 The usual value is 255.255.255.255, as
1947 most kernels ignore the netmask of a POINTOPOINT interface.
1951 implementations require that the peer negotiates a specific IP
1954 If this is the case,
1956 may be used to specify this IP number.
1957 This will not affect the
1958 routing table unless the other side agrees with this proposed number.
1959 .Bd -literal -offset indent
1960 set ifaddr 192.244.177.38 192.244.177.2 255.255.255.255 0.0.0.0
1963 The above specification means:
1965 .Bl -bullet -compact
1967 I will first suggest that my IP address should be 0.0.0.0, but I
1968 will only accept an address of 192.244.177.38.
1970 I strongly insist that the peer uses 192.244.177.2 as his own
1971 address and will not permit the use of any IP address but 192.244.177.2.
1972 When the peer requests another IP address, I will always suggest that
1973 it uses 192.244.177.2.
1975 The routing table entry will have a netmask of 0xffffffff.
1978 This is all fine when each side has a pre-determined IP address, however
1979 it is often the case that one side is acting as a server which controls
1980 all IP addresses and the other side should go along with it.
1981 In order to allow more flexible behaviour, the
1983 command allows the user to specify IP addresses more loosely:
1985 .Dl set ifaddr 192.244.177.38/24 192.244.177.2/20
1987 A number followed by a slash
1989 represents the number of bits significant in the IP address.
1990 The above example means:
1992 .Bl -bullet -compact
1994 I would like to use 192.244.177.38 as my address if it is possible, but I will
1995 also accept any IP address between 192.244.177.0 and 192.244.177.255.
1997 I would like to make him use 192.244.177.2 as his own address, but I will also
1998 permit him to use any IP address between 192.244.176.0 and
2001 As you may have already noticed, 192.244.177.2 is equivalent to saying
2004 As an exception, 0 is equivalent to 0.0.0.0/0, meaning that I have no
2005 preferred IP address and will obey the remote peers selection.
2006 When using zero, no routing table entries will be made until a connection
2009 192.244.177.2/0 means that I will accept/permit any IP address but I will
2010 suggest that 192.244.177.2 be used first.
2013 When negotiating IPv6 addresses, no control is given to the user.
2014 IPV6CP negotiation is fully automatic.
2015 .Sh CONNECTING WITH YOUR INTERNET SERVICE PROVIDER
2016 The following steps should be taken when connecting to your ISP:
2019 Describe your providers phone number(s) in the dial script using the
2022 This command allows you to set multiple phone numbers for
2023 dialing and redialing separated by either a pipe
2027 .Bd -ragged -offset indent
2028 .No set phone Ar telno Ns Xo
2029 .Oo \&| Ns Ar backupnumber
2030 .Oc Ns ... Ns Oo : Ns Ar nextnumber
2035 Numbers after the first in a pipe-separated list are only used if the
2036 previous number was used in a failed dial or login script.
2038 separated by a colon are used sequentially, irrespective of what happened
2039 as a result of using the previous number.
2041 .Bd -literal -offset indent
2042 set phone "1234567|2345678:3456789|4567890"
2045 Here, the 1234567 number is attempted.
2046 If the dial or login script fails,
2047 the 2345678 number is used next time, but *only* if the dial or login script
2049 On the dial after this, the 3456789 number is used.
2051 number is only used if the dial or login script using the 3456789 fails.
2052 If the login script of the 2345678 number fails, the next number is still the
2054 As many pipes and colons can be used as are necessary
2055 (although a given site would usually prefer to use either the pipe or the
2056 colon, but not both).
2057 The next number redial timeout is used between all numbers.
2058 When the end of the list is reached, the normal redial period is
2059 used before starting at the beginning again.
2060 The selected phone number is substituted for the \\\\T string in the
2062 command (see below).
2064 Set up your redial requirements using
2066 For example, if you have a bad telephone line or your provider is
2067 usually engaged (not so common these days), you may want to specify
2069 .Bd -literal -offset indent
2073 This says that up to 4 phone calls should be attempted with a pause of 10
2074 seconds before dialing the first number again.
2076 Describe your login procedure using the
2083 command is used to talk to your modem and establish a link with your
2085 .Bd -literal -offset indent
2086 set dial "ABORT BUSY ABORT NO\\\\sCARRIER TIMEOUT 4 \\"\\" \e
2087 ATZ OK-ATZ-OK ATDT\\\\T TIMEOUT 60 CONNECT"
2090 This modem "chat" string means:
2093 Abort if the string "BUSY" or "NO CARRIER" are received.
2095 Set the timeout to 4 seconds.
2102 If that is not received within the 4 second timeout, send ATZ
2105 Send ATDTxxxxxxx where xxxxxxx is the next number in the phone list from
2108 Set the timeout to 60.
2110 Wait for the CONNECT string.
2113 Once the connection is established, the login script is executed.
2114 This script is written in the same style as the dial script, but care should
2115 be taken to avoid having your password logged:
2116 .Bd -literal -offset indent
2117 set authkey MySecret
2118 set login "TIMEOUT 15 login:-\\\\r-login: awfulhak \e
2119 word: \\\\P ocol: PPP HELLO"
2122 This login "chat" string means:
2125 Set the timeout to 15 seconds.
2128 If it is not received, send a carriage return and expect
2133 Expect "word:" (the tail end of a "Password:" prompt).
2135 Send whatever our current
2139 Expect "ocol:" (the tail end of a "Protocol:" prompt).
2148 command is logged specially.
2153 logging is enabled, the actual password is not logged;
2157 Login scripts vary greatly between ISPs.
2158 If you are setting one up for the first time,
2159 .Em ENABLE CHAT LOGGING
2160 so that you can see if your script is behaving as you expect.
2166 to specify your serial line and speed, for example:
2167 .Bd -literal -offset indent
2168 set device /dev/cuad0
2172 Cuad0 is the first serial port on
2179 A speed of 115200 should be specified
2180 if you have a modem capable of bit rates of 28800 or more.
2181 In general, the serial speed should be about four times the modem speed.
2185 command to {define} the IP address.
2188 If you know what IP address your provider uses, then use it as the remote
2189 address (dst_addr), otherwise choose something like 10.0.0.2/0 (see below).
2191 If your provider has assigned a particular IP address to you, then use
2192 it as your address (src_addr).
2194 If your provider assigns your address dynamically, choose a suitably
2195 unobtrusive and unspecific IP number as your address.
2196 10.0.0.1/0 would be appropriate.
2197 The bit after the / specifies how many bits of the
2198 address you consider to be important, so if you wanted to insist on
2199 something in the class C network 1.2.3.0, you could specify 1.2.3.1/24.
2201 If you find that your ISP accepts the first IP number that you suggest,
2202 specify third and forth arguments of
2204 This will force your ISP to assign a number.
2205 (The third argument will
2206 be ignored as it is less restrictive than the default mask for your
2210 An example for a connection where you do not know your IP number or your
2211 ISPs IP number would be:
2212 .Bd -literal -offset indent
2213 set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0
2217 In most cases, your ISP will also be your default router.
2218 If this is the case, add the line
2219 .Bd -literal -offset indent
2224 .Pa /etc/ppp/ppp.conf
2226 .Pa /etc/ppp/ppp.linkup
2227 for setups that do not use
2233 to add a default route to whatever the peer address is
2234 (10.0.0.2 in this example).
2237 meaning that should the value of
2239 change, the route will be updated accordingly.
2241 If your provider requests that you use PAP/CHAP authentication methods, add
2242 the next lines to your
2243 .Pa /etc/ppp/ppp.conf
2245 .Bd -literal -offset indent
2247 set authkey MyPassword
2250 Both are accepted by default, so
2252 will provide whatever your ISP requires.
2254 It should be noted that a login script is rarely (if ever) required
2255 when PAP or CHAP are in use.
2257 Ask your ISP to authenticate your nameserver address(es) with the line
2258 .Bd -literal -offset indent
2264 do this if you are running a local DNS unless you also either use
2269 .Pa /etc/ppp/ppp.linkdown ,
2272 will simply circumvent its use by entering some nameserver lines in
2273 .Pa /etc/resolv.conf .
2277 .Pa /usr/share/examples/ppp/ppp.conf.sample
2279 .Pa /usr/share/examples/ppp/ppp.linkup.sample
2280 for some real examples.
2281 The pmdemand label should be appropriate for most ISPs.
2282 .Sh LOGGING FACILITY
2284 is able to generate the following log info either via
2286 or directly to the screen:
2288 .Bl -tag -width XXXXXXXXX -offset XXX -compact
2290 Enable all logging facilities.
2291 This generates a lot of log.
2292 The most common use of 'all' is as a basis, where you remove some facilities
2293 after enabling 'all' ('debug' and 'timer' are usually best disabled.)
2295 Dump async level packet in hex.
2297 Generate CBCP (CallBack Control Protocol) logs.
2299 Generate a CCP packet trace.
2307 chat script trace logs.
2309 Log commands executed either from the command line or any of the configuration
2312 Log Chat lines containing the string "CONNECT".
2314 Log debug information.
2316 Log DNS QUERY packets.
2318 Log packets permitted by the dial filter and denied by any filter.
2320 Dump HDLC packet in hex.
2322 Log all function calls specifically made as user id 0.
2324 Generate an IPCP packet trace.
2326 Generate an LCP packet trace.
2328 Generate LQR reports.
2330 Phase transition log output.
2332 Dump physical level packet in hex.
2334 Dump RADIUS information.
2335 RADIUS information resulting from the link coming up or down is logged at
2340 This log level is most useful for monitoring RADIUS alive information.
2342 Dump sync level packet in hex.
2344 Dump all TCP/IP packets.
2346 Log timer manipulation.
2348 Include the tun device on each log line.
2350 Output to the terminal device.
2351 If there is currently no terminal,
2352 output is sent to the log file using syslogs
2355 Output to both the terminal device
2356 and the log file using syslogs
2359 Output to the log file using
2365 command allows you to set the logging output level.
2366 Multiple levels can be specified on a single command line.
2367 The default is equivalent to
2370 It is also possible to log directly to the screen.
2371 The syntax is the same except that the word
2373 should immediately follow
2377 (i.e., only the un-maskable warning, error and alert output).
2379 If The first argument to
2380 .Dq set log Op local
2385 character, the current log levels are
2386 not cleared, for example:
2387 .Bd -literal -offset indent
2388 PPP ON awfulhak> set log phase
2389 PPP ON awfulhak> show log
2390 Log: Phase Warning Error Alert
2391 Local: Warning Error Alert
2392 PPP ON awfulhak> set log +tcp/ip -warning
2393 PPP ON awfulhak> set log local +command
2394 PPP ON awfulhak> show log
2395 Log: Phase TCP/IP Warning Error Alert
2396 Local: Command Warning Error Alert
2399 Log messages of level Warning, Error and Alert are not controllable
2401 .Dq set log Op local .
2405 level is special in that it will not be logged if it can be displayed
2409 deals with the following signals:
2410 .Bl -tag -width "USR2"
2412 Receipt of this signal causes the termination of the current connection
2416 to exit unless it is in
2421 .It HUP, TERM & QUIT
2428 to re-open any existing server socket, dropping all existing diagnostic
2430 Sockets that could not previously be opened will be retried.
2434 to close any existing server socket, dropping all existing diagnostic
2437 can still be used to re-open the socket.
2440 If you wish to use more than one physical link to connect to a
2442 peer, that peer must also understand the
2445 Refer to RFC 1990 for specification details.
2447 The peer is identified using a combination of his
2448 .Dq endpoint discriminator
2450 .Dq authentication id .
2451 Either or both of these may be specified.
2452 It is recommended that
2453 at least one is specified, otherwise there is no way of ensuring that
2454 all links are actually connected to the same peer program, and some
2455 confusing lock-ups may result.
2456 Locally, these identification variables are specified using the
2465 must be agreed in advance with the peer.
2467 Multi-link capabilities are enabled using the
2469 command (set maximum reconstructed receive unit).
2470 Once multi-link is enabled,
2472 will attempt to negotiate a multi-link connection with the peer.
2474 By default, only one
2479 To create more links, the
2482 This command will clone existing links, where all
2483 characteristics are the same except:
2486 The new link has its own name as specified on the
2493 Its mode may subsequently be changed using the
2497 The new link is in a
2502 A summary of all available links can be seen using the
2506 Once a new link has been created, command usage varies.
2507 All link specific commands must be prefixed with the
2509 command, specifying on which link the command is to be applied.
2510 When only a single link is available,
2512 is smart enough not to require the
2516 Some commands can still be used without specifying a link - resulting
2517 in an operation at the
2520 For example, once two or more links are available, the command
2522 will show CCP configuration and statistics at the multi-link level, and
2523 .Dq link deflink show ccp
2524 will show the same information at the
2528 Armed with this information, the following configuration might be used:
2530 .Bd -literal -offset indent
2534 set device /dev/cuad0 /dev/cuad1 /dev/cuad2
2535 set phone "123456789"
2536 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \\"\\" ATZ \e
2537 OK-AT-OK \\\\dATDT\\\\T TIMEOUT 45 CONNECT"
2539 set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0
2541 set authkey ppppassword
2544 clone 1,2,3 # Create 3 new links - duplicates of the default
2545 link deflink remove # Delete the default link (called ``deflink'')
2548 Note how all cloning is done at the end of the configuration.
2549 Usually, the link will be configured first, then cloned.
2550 If you wish all links
2551 to be up all the time, you can add the following line to the end of your
2554 .Bd -literal -offset indent
2555 link 1,2,3 set mode ddial
2558 If you want the links to dial on demand, this command could be used:
2560 .Bd -literal -offset indent
2561 link * set mode auto
2564 Links may be tied to specific names by removing the
2566 line above, and specifying the following after the
2570 .Bd -literal -offset indent
2571 link 1 set device /dev/cuad0
2572 link 2 set device /dev/cuad1
2573 link 3 set device /dev/cuad2
2578 command to see which commands require context (using the
2580 command), which have optional
2581 context and which should not have any context.
2587 mode with the peer, it creates a local domain socket in the
2590 This socket is used to pass link information (including
2591 the actual link file descriptor) between different
2596 ability to be run from a
2602 capability), without needing to have initial control of the serial
2606 negotiates multi-link mode, it will pass its open link to any
2607 already running process.
2608 If there is no already running process,
2610 will act as the master, creating the socket and listening for new
2612 .Sh PPP COMMAND LIST
2613 This section lists the available commands and their effect.
2614 They are usable either from an interactive
2616 session, from a configuration file or from a
2622 .It accept|deny|enable|disable Ar option....
2623 These directives tell
2625 how to negotiate the initial connection with the peer.
2628 has a default of either accept or deny and enable or disable.
2630 means that the option will be ACK'd if the peer asks for it.
2632 means that the option will be NAK'd if the peer asks for it.
2634 means that the option will be requested by us.
2636 means that the option will not be requested by us.
2639 may be one of the following:
2642 Default: Enabled and Accepted.
2643 ACFComp stands for Address and Control Field Compression.
2644 Non LCP packets will usually have an address
2645 field of 0xff (the All-Stations address) and a control field of
2646 0x03 (the Unnumbered Information command).
2648 negotiated, these two bytes are simply not sent, thus minimising
2655 Default: Disabled and Accepted.
2656 CHAP stands for Challenge Handshake Authentication Protocol.
2657 Only one of CHAP and PAP (below) may be negotiated.
2658 With CHAP, the authenticator sends a "challenge" message to its peer.
2659 The peer uses a one-way hash function to encrypt the
2660 challenge and sends the result back.
2661 The authenticator does the same, and compares the results.
2662 The advantage of this mechanism is that no
2663 passwords are sent across the connection.
2664 A challenge is made when the connection is first made.
2665 Subsequent challenges may occur.
2666 If you want to have your peer authenticate itself, you must
2669 .Pa /etc/ppp/ppp.conf ,
2670 and have an entry in
2671 .Pa /etc/ppp/ppp.secret
2674 When using CHAP as the client, you need only specify
2679 .Pa /etc/ppp/ppp.conf .
2680 CHAP is accepted by default.
2683 implementations use "MS-CHAP" rather than MD5 when encrypting the
2685 MS-CHAP is a combination of MD4 and DES.
2688 was built on a machine with DES libraries available, it will respond
2689 to MS-CHAP authentication requests, but will never request them.
2691 Default: Enabled and Accepted.
2692 This option decides if deflate
2693 compression will be used by the Compression Control Protocol (CCP).
2694 This is the same algorithm as used by the
2697 Note: There is a problem negotiating
2703 implementation available under many operating systems.
2705 (version 2.3.1) incorrectly attempts to negotiate
2707 compression using type
2709 as the CCP configuration type rather than type
2715 is actually specified as
2716 .Dq PPP Magna-link Variable Resource Compression
2720 is capable of negotiating with
2727 .Ar accept Ns No ed .
2729 Default: Disabled and Denied.
2730 This is a variance of the
2732 option, allowing negotiation with the
2737 section above for details.
2738 It is disabled by default as it violates
2741 Default: Disabled and Denied.
2742 This option allows DNS negotiation.
2747 will request that the peer confirms the entries in
2748 .Pa /etc/resolv.conf .
2749 If the peer NAKs our request (suggesting new IP numbers),
2750 .Pa /etc/resolv.conf
2751 is updated and another request is sent to confirm the new entries.
2754 .Dq accept Ns No ed,
2756 will answer any DNS queries requested by the peer rather than rejecting
2758 The answer is taken from
2759 .Pa /etc/resolv.conf
2762 command is used as an override.
2764 Default: Enabled and Accepted.
2765 This option allows control over whether we
2766 negotiate an endpoint discriminator.
2767 We only send our discriminator if
2772 We reject the peers discriminator if
2776 Default: Disabled and Accepted.
2777 The use of this authentication protocol
2778 is discouraged as it partially violates the authentication protocol by
2779 implementing two different mechanisms (LANMan & NT) under the guise of
2780 a single CHAP type (0x80).
2782 uses a simple DES encryption mechanism and is the least secure of the
2783 CHAP alternatives (although is still more secure than PAP).
2787 description below for more details.
2789 Default: Disabled and Accepted.
2790 This option decides if Link Quality Requests will be sent or accepted.
2791 LQR is a protocol that allows
2793 to determine that the link is down without relying on the modems
2795 When LQR is enabled,
2801 below) as part of the LCP request.
2802 If the peer agrees, both sides will
2803 exchange LQR packets at the agreed frequency, allowing detailed link
2804 quality monitoring by enabling LQM logging.
2805 If the peer does not agree, and if the
2812 These packets pass no information of interest, but they
2814 be replied to by the peer.
2821 will abruptly drop the connection if 5 unacknowledged packets have been
2822 sent rather than sending a 6th.
2823 A message is logged at the
2825 level, and any appropriate
2827 values are honoured as if the peer were responsible for dropping the
2832 command description for differences in behaviour prior to
2836 Default: Enabled and Accepted.
2837 This is Microsoft Point to Point Encryption scheme.
2838 MPPE key size can be
2839 40-, 56- and 128-bits.
2844 Default: Disabled and Accepted.
2845 It is very similar to standard CHAP (type 0x05)
2846 except that it issues challenges of a fixed 16 bytes in length and uses a
2847 combination of MD4, SHA-1 and DES to encrypt the challenge rather than using the
2848 standard MD5 mechanism.
2850 Default: Disabled and Accepted.
2851 The use of this authentication protocol
2852 is discouraged as it partially violates the authentication protocol by
2853 implementing two different mechanisms (LANMan & NT) under the guise of
2854 a single CHAP type (0x80).
2855 It is very similar to standard CHAP (type 0x05)
2856 except that it issues challenges of a fixed 8 bytes in length and uses a
2857 combination of MD4 and DES to encrypt the challenge rather than using the
2858 standard MD5 mechanism.
2859 CHAP type 0x80 for LANMan is also supported - see
2867 use CHAP type 0x80, when acting as authenticator with both
2868 .Dq enable Ns No d ,
2870 will rechallenge the peer up to three times if it responds using the wrong
2871 one of the two protocols.
2872 This gives the peer a chance to attempt using both protocols.
2876 acts as the authenticatee with both protocols
2877 .Dq accept Ns No ed ,
2878 the protocols are used alternately in response to challenges.
2880 Note: If only LANMan is enabled,
2882 (version 2.3.5) misbehaves when acting as authenticatee.
2884 the NT and the LANMan answers, but also suggests that only the NT answer
2887 Default: Disabled and Accepted.
2888 PAP stands for Password Authentication Protocol.
2889 Only one of PAP and CHAP (above) may be negotiated.
2890 With PAP, the ID and Password are sent repeatedly to the peer until
2891 authentication is acknowledged or the connection is terminated.
2892 This is a rather poor security mechanism.
2893 It is only performed when the connection is first established.
2894 If you want to have your peer authenticate itself, you must
2897 .Pa /etc/ppp/ppp.conf ,
2898 and have an entry in
2899 .Pa /etc/ppp/ppp.secret
2900 for the peer (although see the
2906 When using PAP as the client, you need only specify
2911 .Pa /etc/ppp/ppp.conf .
2912 PAP is accepted by default.
2914 Default: Enabled and Accepted.
2915 This option decides if Predictor 1
2916 compression will be used by the Compression Control Protocol (CCP).
2918 Default: Enabled and Accepted.
2919 This option is used to negotiate
2920 PFC (Protocol Field Compression), a mechanism where the protocol
2921 field number is reduced to one octet rather than two.
2923 Default: Enabled and Accepted.
2924 This option determines if
2926 will request and accept requests for short
2928 sequence numbers when negotiating multi-link mode.
2929 This is only applicable if our MRRU is set (thus enabling multi-link).
2931 Default: Enabled and Accepted.
2932 This option determines if Van Jacobson header compression will be used.
2935 The following options are not actually negotiated with the peer.
2936 Therefore, accepting or denying them makes no sense.
2940 When this option is enabled,
2944 requests to the peer at the frequency defined by
2948 requests will supersede
2950 requests if enabled and negotiated.
2959 was considered enabled if lqr was enabled and negotiated, otherwise it was
2960 considered disabled.
2961 For the same behaviour, it is now necessary to
2965 .It filter-decapsulation
2967 When this option is enabled,
2969 will examine UDP frames to see if they actually contain a
2971 frame as their payload.
2972 If this is the case, all filters will operate on the payload rather
2973 than the actual packet.
2975 This is useful if you want to send PPPoUDP traffic over a
2977 link, but want that link to do smart things with the real data rather than
2980 The UDP frame payload must not be compressed in any way, otherwise
2982 will not be able to interpret it.
2983 It is therefore recommended that you
2984 .Ic disable vj pred1 deflate
2986 .Ic deny vj pred1 deflate
2987 in the configuration for the
2989 invocation with the udp link.
2992 Forces execution of the configured chat scripts in
3001 exchanges low-level LCP, CCP and IPCP configuration traffic, the
3003 field of any replies is expected to be the same as that of the request.
3006 drops any reply packets that do not contain the expected identifier
3007 field, reporting the fact at the respective log level.
3012 will ignore the identifier field.
3017 This option simply tells
3019 to add new interface addresses to the interface rather than replacing them.
3020 The option can only be enabled if network address translation is enabled
3021 .Pq Dq nat enable yes .
3023 With this option enabled,
3025 will pass traffic for old interface addresses through the NAT
3026 ifdef({LOCALNAT},{engine,},{engine
3028 .Xr libalias 3 ) ,})
3029 resulting in the ability (in
3031 mode) to properly connect the process that caused the PPP link to
3032 come up in the first place.
3042 to attempt to negotiate IP control protocol capabilities and if
3043 successful to exchange IP datagrams with the peer.
3048 to attempt to negotiate IPv6 control protocol capabilities and if
3049 successful to exchange IPv6 datagrams with the peer.
3054 runs as a Multi-link server, a different
3056 instance initially receives each connection.
3057 After determining that
3058 the link belongs to an already existing bundle (controlled by another
3062 will transfer the link to that process.
3064 If the link is a tty device or if this option is enabled,
3066 will not exit, but will change its process name to
3068 and wait for the controlling
3070 to finish with the link and deliver a signal back to the idle process.
3071 This prevents the confusion that results from
3073 parent considering the link resource available again.
3075 For tty devices that have entries in
3077 this is necessary to prevent another
3079 from being started, and for program links such as
3083 from exiting due to the death of its child.
3086 cannot determine its parents requirements (except for the tty case), this
3087 option must be enabled manually depending on the circumstances.
3094 will automatically loop back packets being sent
3095 out with a destination address equal to that of the
3100 will send the packet, probably resulting in an ICMP redirect from
3102 It is convenient to have this option enabled when
3103 the interface is also the default route as it avoids the necessity
3104 of a loopback route.
3107 This option controls whether
3111 attribute to the RADIUS server when RADIUS is in use
3112 .Pq see Dq set radius .
3114 Note, at least one of
3122 prior to version 3.4.1 did not send the
3124 attribute as it was reported to break the Radiator RADIUS server.
3125 As the latest rfc (2865) no longer hints that only one of
3129 should be sent (as rfc 2138 did),
3131 now sends both and leaves it up to the administrator that chooses to use
3132 bad RADIUS implementations to
3133 .Dq disable NAS-IP-Address .
3136 This option controls whether
3140 attribute to the RADIUS server when RADIUS is in use
3141 .Pq see Dq set radius .
3143 Note, at least one of
3150 Enabling this option will tell the PAP authentication
3151 code to use the password database (see
3153 to authenticate the caller if they cannot be found in the
3154 .Pa /etc/ppp/ppp.secret
3156 .Pa /etc/ppp/ppp.secret
3157 is always checked first.
3158 If you wish to use passwords from
3160 but also to specify an IP number or label for a given client, use
3162 as the client password in
3163 .Pa /etc/ppp/ppp.secret .
3166 Enabling this option will tell
3168 to proxy ARP for the peer.
3171 will make an entry in the ARP table using
3175 address of the local network in which
3178 This allows other machines connecteed to the LAN to talk to
3179 the peer as if the peer itself was connected to the LAN.
3180 The proxy entry cannot be made unless
3182 is an address from a LAN.
3185 Enabling this will tell
3187 to add proxy arp entries for every IP address in all class C or
3188 smaller subnets routed via the tun interface.
3190 Proxy arp entries are only made for sticky routes that are added
3194 No proxy arp entries are made for the interface address itself
3202 command is used with the
3208 values, entries are stored in the
3211 Each time these variables change, this list is re-applied to the routing table.
3213 Disabling this option will prevent the re-application of sticky routes,
3216 list will still be maintained.
3223 to adjust TCP SYN packets so that the maximum receive segment
3224 size is not greater than the amount allowed by the interface MTU.
3229 to gather throughput statistics.
3230 Input and output is sampled over
3231 a rolling 5 second window, and current, best and total figures are retained.
3232 This data is output when the relevant
3234 layer shuts down, and is also available using the
3237 Throughput statistics are available at the
3244 Normally, when a user is authenticated using PAP or CHAP, and when
3248 mode, an entry is made in the utmp and wtmp files for that user.
3249 Disabling this option will tell
3251 not to make any utmp or wtmp entries.
3252 This is usually only necessary if
3253 you require the user to both login and authenticate themselves.
3258 .Ar dest Ns Op / Ns Ar nn
3263 is the destination IP address.
3264 The netmask is specified either as a number of bits with
3266 or as an IP number using
3271 with no mask refers to the default route.
3272 It is also possible to use the literal name
3277 is the next hop gateway to get to the given
3282 command for further details.
3284 It is possible to use the symbolic names
3290 as the destination, and
3297 is replaced with the interface IP address,
3299 is replaced with the interface IP destination (peer) address,
3301 is replaced with the interface IPv6 address, and
3303 is replaced with the interface IPv6 destination address,
3310 then if the route already exists, it will be updated as with the
3314 for further details).
3316 Routes that contain the
3324 constants are considered
3326 They are stored in a list (use
3328 to see the list), and each time the value of one of these variables
3329 changes, the appropriate routing table entries are updated.
3330 This facility may be disabled using
3331 .Dq disable sroutes .
3332 .It allow Ar command Op Ar args
3333 This command controls access to
3335 and its configuration files.
3336 It is possible to allow user-level access,
3337 depending on the configuration file label and on the mode that
3340 For example, you may wish to configure
3350 User id 0 is immune to these commands.
3352 .It allow user Ns Xo
3354 .Ar logname Ns No ...
3356 By default, only user id 0 is allowed access to
3358 If this command is used, all of the listed users are allowed access to
3359 the section in which the
3364 section is always checked first (even though it is only ever automatically
3367 commands are cumulative in a given section, but users allowed in any given
3368 section override users allowed in the default section, so it is possible to
3369 allow users access to everything except a given label by specifying default
3372 section, and then specifying a new user list for that label.
3376 is specified, access is allowed to all users.
3377 .It allow mode Ns Xo
3381 By default, access using any
3384 If this command is used, it restricts the access
3386 allowed to load the label under which this command is specified.
3391 command overrides any previous settings, and the
3393 section is always checked first.
3405 When running in multi-link mode, a section can be loaded if it allows
3407 of the currently existing line modes.
3410 .It nat Ar command Op Ar args
3411 This command allows the control of the network address translation (also
3412 known as masquerading or IP aliasing) facilities that are built into
3414 NAT is done on the external interface only, and is unlikely to make sense
3419 If nat is enabled on your system (it may be omitted at compile time),
3420 the following commands are possible:
3422 .It nat enable yes|no
3423 This command either switches network address translation on or turns it off.
3426 command line flag is synonymous with
3427 .Dq nat enable yes .
3428 .It nat addr Op Ar addr_local addr_alias
3429 This command allows data for
3433 It is useful if you own a small number of real IP numbers that
3434 you wish to map to specific machines behind your gateway.
3435 .It nat deny_incoming yes|no
3436 If set to yes, this command will refuse all incoming packets where an
3437 aliasing link does not already exist.
3438 ifdef({LOCALNAT},{},{Refer to the
3439 .Sx CONCEPTUAL BACKGROUND
3442 for a description of what an
3447 It should be noted under what circumstances an aliasing link is
3448 ifdef({LOCALNAT},{created.},{created by
3450 It may be necessary to further protect your network from outside
3451 connections using the
3457 This command gives a summary of available nat commands.
3459 This option causes various NAT statistics and information to
3460 be logged to the file
3461 .Pa /var/log/alias.log .
3462 .It nat port Ar proto Ar targetIP Ns Xo
3463 .No : Ns Ar targetPort Ns
3465 .No - Ns Ar targetPort
3468 .No - Ns Ar aliasPort
3469 .Oc Oo Ar remoteIP : Ns
3472 .No - Ns Ar remotePort
3476 This command causes incoming
3490 A range of port numbers may be specified as shown above.
3491 The ranges must be of the same size.
3495 is specified, only data coming from that IP number is redirected.
3499 (indicating any source port)
3500 or a range of ports the same size as the other ranges.
3502 This option is useful if you wish to run things like Internet phone on
3503 machines behind your gateway, but is limited in that connections to only
3504 one interior machine per source machine and target port are possible.
3505 .It nat proto Ar proto localIP Oo
3506 .Ar publicIP Op Ar remoteIP
3510 to redirect packets of protocol type
3514 to the internal address
3519 is specified, only packets destined for that address are matched,
3520 otherwise the default alias address is used.
3524 is specified, only packets matching that source address are matched,
3526 This command is useful for redirecting tunnel endpoints to an internal machine,
3529 .Dl nat proto ipencap 10.0.0.1
3530 .It "nat proxy cmd" Ar arg Ns No ...
3533 to proxy certain connections, redirecting them to a given server.
3534 ifdef({LOCALNAT},{},{Refer to the description of
3535 .Fn PacketAliasProxyRule
3538 for details of the available commands.
3540 .It nat punch_fw Op Ar base count
3543 to punch holes in the firewall for FTP or IRC DCC connections.
3544 This is done dynamically by installing termporary firewall rules which
3545 allow a particular connection (and only that connection) to go through
3547 The rules are removed once the corresponding connection terminates.
3551 rules starting from rule number
3553 will be used for punching firewall holes.
3554 The range will be cleared when the
3558 If no arguments are given, firewall punching is disabled.
3559 .It nat skinny_port Op Ar port
3562 which TCP port is used by the Skinny Station protocol.
3564 Cisco IP phones to communicate with Cisco Call Managers to setup voice
3566 The typical port used by Skinny is 2000.
3568 If no argument is given, skinny aliasing is disabled.
3569 .It nat same_ports yes|no
3570 When enabled, this command will tell the network address translation engine to
3571 attempt to avoid changing the port number on outgoing packets.
3573 if you want to support protocols such as RPC and LPD which require
3574 connections to come from a well known port.
3575 .It nat target Op Ar address
3576 Set the given target address or clear it if no address is given.
3577 The target address is used
3578 ifdef({LOCALNAT},{},{by libalias })dnl
3579 to specify how to NAT incoming packets by default.
3580 If a target address is not set or if
3582 is given, packets are not altered and are allowed to route to the internal
3585 The target address may be set to
3588 ifdef({LOCALNAT},{all packets will be redirected},
3589 {libalias will redirect all packets})
3590 to the interface address.
3591 .It nat use_sockets yes|no
3592 When enabled, this option tells the network address translation engine to
3593 create a socket so that it can guarantee a correct incoming ftp data or
3595 .It nat unregistered_only yes|no
3596 Only alter outgoing packets with an unregistered source address.
3597 According to RFC 1918, unregistered source addresses
3598 are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16.
3601 These commands are also discussed in the file
3603 which comes with the source distribution.
3610 is executed in the background with the following words replaced:
3611 .Bl -tag -width COMPILATIONDATE
3613 This is replaced with the local
3619 .It Li COMPILATIONDATE
3620 In previous software revisions, this was replaced with the date on which
3623 This is no longer supported as it breaks the ability to recompile the same
3624 code to produce an exact duplicate of a previous compilation.
3626 These are replaced with the primary and secondary nameserver IP numbers.
3627 If nameservers are negotiated by IPCP, the values of these macros will change.
3629 This is replaced with the local endpoint discriminator value.
3634 This is replaced with the peers IP number.
3636 This is replaced with the peers IPv6 number.
3638 This is replaced with the name of the interface that is in use.
3640 This is replaced with the number of IP bytes received since the connection
3643 This is replaced with the number of IP bytes sent since the connection
3646 This is replaced with the number of IP packets received since the connection
3649 This is replaced with the number of IP packets sent since the connection
3652 This is replaced with the number of IPv6 bytes received since the connection
3654 .It Li IPV6OCTETSOUT
3655 This is replaced with the number of IPv6 bytes sent since the connection
3657 .It Li IPV6PACKETSIN
3658 This is replaced with the number of IPv6 packets received since the connection
3660 .It Li IPV6PACKETSOUT
3661 This is replaced with the number of IPv6 packets sent since the connection
3664 This is replaced with the last label name used.
3665 A label may be specified on the
3667 command line, via the
3675 This is replaced with the IP number assigned to the local interface.
3677 This is replaced with the IPv6 number assigned to the local interface.
3679 This is replaced with the number of bytes received since the connection
3682 This is replaced with the number of bytes sent since the connection
3685 This is replaced with the number of packets received since the connection
3688 This is replaced with the number of packets sent since the connection
3691 This is replaced with the value of the peers endpoint discriminator.
3693 This is replaced with the current process id.
3695 This is replaced with the name of the diagnostic socket.
3697 This is replaced with the bundle uptime in HH:MM:SS format.
3699 This is replaced with the username that has been authenticated with PAP or
3701 Normally, this variable is assigned only in -direct mode.
3702 This value is available irrespective of whether utmp logging is enabled.
3704 This is replaced with the current version number of
3708 These substitutions are also done by the
3715 If you wish to pause
3717 while the command executes, use the
3720 .It clear physical|ipcp|ipv6 Op current|overall|peak...
3721 Clear the specified throughput values at either the
3729 is specified, context must be given (see the
3732 If no second argument is given, all values are cleared.
3733 .It clone Ar name Ns Xo
3734 .Op \&, Ns Ar name Ns
3737 Clone the specified link, creating one or more new links according to the
3740 This command must be used from the
3742 command below unless you have only got a single link (in which case that
3743 link becomes the default).
3744 Links may be removed using the
3748 The default link name is
3750 .It close Op lcp|ccp Ns Op !\&
3751 If no arguments are given, the relevant protocol layers will be brought
3752 down and the link will be closed.
3755 is specified, the LCP layer is brought down, but
3757 will not bring the link offline.
3758 It is subsequently possible to use
3761 to talk to the peer machine if, for example, something like
3766 is specified, only the relevant compression layer is closed.
3769 is used, the compression layer will remain in the closed state, otherwise
3770 it will re-enter the STOPPED state, waiting for the peer to initiate
3771 further CCP negotiation.
3772 In any event, this command does not disconnect the user from
3783 This command deletes the route with the given
3790 all non-direct entries in the routing table for the current interface,
3793 entries are deleted.
3798 the default route is deleted.
3806 will not complain if the route does not already exist.
3807 .It dial|call Op Ar label Ns Xo
3810 This command is the equivalent of
3814 and is provided for backwards compatibility.
3815 .It down Op Ar lcp|ccp
3816 Bring the relevant layer down ungracefully, as if the underlying layer
3817 had become unavailable.
3818 It is not considered polite to use this command on
3819 a Finite State Machine that is in the OPEN state.
3821 supplied, the entire link is closed (or if no context is given, all links
3827 layer is terminated but the device is not brought offline and the link
3831 is specified, only the relevant compression layer(s) are terminated.
3832 .It help|? Op Ar command
3833 Show a list of available commands.
3836 is specified, show the usage string for that command.
3837 .It ident Op Ar text Ns No ...
3838 Identify the link to the peer using
3842 is empty, link identification is disabled.
3843 It is possible to use any of the words described for the
3848 command for details of when
3850 identifies itself to the peer.
3851 .It iface Ar command Op args
3852 This command is used to control the interface used by
3855 may be one of the following:
3859 .Ar addr Ns Op / Ns Ar bits
3870 combination to the interface.
3871 Instead of specifying
3875 (with no space between it and
3877 If the given address already exists, the command fails unless the
3879 is used - in which case the previous interface address entry is overwritten
3880 with the new one, allowing a change of netmask or peer address.
3891 .Dq 255.255.255.255 .
3892 This address (the broadcast address) is the only duplicate peer address that
3895 .It iface clear Op INET | INET6
3896 If this command is used while
3898 is in the OPENED state or while in
3900 mode, all addresses except for the NCP negotiated address are deleted
3904 is not in the OPENED state and is not in
3906 mode, all interface addresses are deleted.
3908 If the INET or INET6 arguments are used, only addresses for that address
3911 .It iface delete Ns Xo
3916 This command deletes the given
3921 is used, no error is given if the address is not currently assigned to
3922 the interface (and no deletion takes place).
3924 Shows the current state and current addresses for the interface.
3925 It is much the same as running
3926 .Dq ifconfig INTERFACE .
3927 .It iface help Op Ar sub-command
3928 This command, when invoked without
3930 will show a list of possible
3932 sub-commands and a brief synopsis for each.
3935 only the synopsis for the given sub-command is shown.
3939 .Ar name Ns Op , Ns Ar name Ns
3940 .No ... Ar command Op Ar args
3942 This command may prefix any other command if the user wishes to
3943 specify which link the command should affect.
3944 This is only applicable after multiple links have been created in Multi-link
3950 specifies the name of an existing link.
3953 is a comma separated list,
3955 is executed on each link.
3961 is executed on all links.
3962 .It load Op Ar label Ns Xo
3985 will not attempt to make an immediate connection.
3986 .It log Ar word Ns No ...
3987 Send the given word(s) to the log file with the prefix
3989 Word substitutions are done as explained under the
3992 .It open Op lcp|ccp|ipcp
3993 This is the opposite of the
3996 All closed links are immediately brought up apart from second and subsequent
3998 links - these will come up based on the
4000 command that has been used.
4004 argument is used while the LCP layer is already open, LCP will be
4006 This allows various LCP options to be changed, after which
4008 can be used to put them into effect.
4009 After renegotiating LCP,
4010 any agreed authentication will also take place.
4014 argument is used, the relevant compression layer is opened.
4015 Again, if it is already open, it will be renegotiated.
4019 argument is used, the link will be brought up as normal, but if
4020 IPCP is already open, it will be renegotiated and the network
4021 interface will be reconfigured.
4023 It is probably not good practice to re-open the PPP state machines
4024 like this as it is possible that the peer will not behave correctly.
4027 however useful as a way of forcing the CCP or VJ dictionaries to be reset.
4029 Specify the password required for access to the full
4032 This password is required when connecting to the diagnostic port (see the
4043 logging is active, instead, the literal string
4049 is executed from the controlling connection or from a command file,
4050 ppp will exit after closing all connections.
4051 Otherwise, if the user
4052 is connected to a diagnostic socket, the connection is simply dropped.
4058 will exit despite the source of the command after closing all existing
4061 This command removes the given link.
4062 It is only really useful in multi-link mode.
4063 A link must be in the
4065 state before it is removed.
4066 .It rename|mv Ar name
4067 This command renames the given link to
4071 is already used by another link.
4073 The default link name is
4080 may make the log file more readable.
4081 .It resolv Ar command
4082 This command controls
4089 starts up, it loads the contents of this file into memory and retains this
4090 image for future use.
4092 is one of the following:
4093 .Bl -tag -width readonly
4096 .Pa /etc/resolv.conf
4102 will still attempt to negotiate nameservers with the peer, making the results
4108 This is the opposite of the
4113 .Pa /etc/resolv.conf
4115 This may be necessary if for example a DHCP client overwrote
4116 .Pa /etc/resolv.conf .
4119 .Pa /etc/resolv.conf
4120 with the version originally read at startup or with the last
4123 This is sometimes a useful command to put in the
4124 .Pa /etc/ppp/ppp.linkdown
4128 .Pa /etc/resolv.conf
4130 This command will work even if the
4132 command has been used.
4133 It may be useful as a command in the
4134 .Pa /etc/ppp/ppp.linkup
4135 file if you wish to defer updating
4136 .Pa /etc/resolv.conf
4137 until after other commands have finished.
4142 .Pa /etc/resolv.conf
4147 successfully negotiates a DNS.
4148 This is the opposite of the
4153 This option is not (yet) implemented.
4157 to identify itself to the peer.
4158 The link must be in LCP state or higher.
4159 If no identity has been set (via the
4165 When an identity has been set,
4167 will automatically identify itself when it sends or receives a configure
4168 reject, when negotiation fails or when LCP reaches the opened state.
4170 Received identification packets are logged to the LCP log (see
4172 for details) and are never responded to.
4177 This option allows the setting of any of the following variables:
4179 .It set accmap Ar hex-value
4180 ACCMap stands for Asynchronous Control Character Map.
4182 negotiated with the peer, and defaults to a value of 00000000 in hex.
4183 This protocol is required to defeat hardware that depends on passing
4184 certain characters from end to end (such as XON/XOFF etc).
4186 For the XON/XOFF scenario, use
4187 .Dq set accmap 000a0000 .
4188 .It set Op auth Ns Xo
4191 This sets the authentication key (or password) used in client mode
4192 PAP or CHAP negotiation to the given value.
4193 It also specifies the
4194 password to be used in the dial or login scripts in place of the
4196 sequence, preventing the actual password from being logged.
4201 logging is in effect,
4205 for security reasons.
4207 If the first character of
4209 is an exclamation mark
4212 treats the remainder of the string as a program that must be executed
4224 it is treated as a single literal
4226 otherwise, ignoring the
4229 is parsed as a program to execute in the same was as the
4231 command above, substituting special names in the same manner.
4234 will feed the program three lines of input, each terminated by a newline
4238 The host name as sent in the CHAP challenge.
4240 The challenge string as sent in the CHAP challenge.
4246 Two lines of output are expected:
4251 to be sent with the CHAP response.
4255 which is encrypted with the challenge and request id, the answer being sent
4256 in the CHAP response packet.
4261 in this manner, it is expected that the host challenge is a series of ASCII
4262 digits or characters.
4263 An encryption device or Secure ID card is usually
4264 required to calculate the secret appropriate for the given challenge.
4265 .It set authname Ar id
4266 This sets the authentication id used in client mode PAP or CHAP negotiation.
4270 mode with CHAP enabled,
4272 is used in the initial authentication challenge and should normally be set to
4273 the local machine name.
4275 .Ar min-percent max-percent period
4277 These settings apply only in multi-link mode and default to zero, zero and
4283 mode link is available, only the first link is made active when
4285 first reads data from the tun device.
4288 link will be opened only when the current bundle throughput is at least
4290 percent of the total bundle bandwidth for
4293 When the current bundle throughput decreases to
4295 percent or less of the total bundle bandwidth for
4299 link will be brought down as long as it is not the last active link.
4301 Bundle throughput is measured as the maximum of inbound and outbound
4304 The default values cause
4306 links to simply come up one at a time.
4308 Certain devices cannot determine their physical bandwidth, so it
4309 is sometimes necessary to use the
4311 command (described below) to make
4314 .It set bandwidth Ar value
4315 This command sets the connection bandwidth in bits per second.
4317 must be greater than zero.
4318 It is currently only used by the
4321 .It set callback Ar option Ns No ...
4322 If no arguments are given, callback is disabled, otherwise,
4326 mode, will accept) one of the given
4327 .Ar option Ns No s .
4328 In client mode, if an
4332 will request a different
4334 until no options remain at which point
4336 will terminate negotiations (unless
4338 is one of the specified
4342 will accept any of the given protocols - but the client
4344 request one of them.
4345 If you wish callback to be optional, you must {include}
4351 are as follows (in this order of preference):
4355 The callee is expected to decide the callback number based on
4359 is the callee, the number should be specified as the fifth field of
4361 .Pa /etc/ppp/ppp.secret .
4363 Microsoft's callback control protocol is used.
4368 If you wish to negotiate
4370 in client mode but also wish to allow the server to request no callback at
4371 CBCP negotiation time, you must specify both
4375 as callback options.
4377 .Ar number Ns Op , Ns Ar number Ns
4380 The caller specifies the
4386 should be either a comma separated list of allowable numbers or a
4388 meaning any number is permitted.
4391 is the caller, only a single number should be specified.
4393 Note, this option is very unsafe when used with a
4395 as a malicious caller can tell
4397 to call any (possibly international) number without first authenticating
4400 If the peer does not wish to do callback at all,
4402 will accept the fact and continue without callback rather than terminating
4404 This is required (in addition to one or more other callback
4405 options) if you wish callback to be optional.
4409 .No *| Ns Ar number Ns Oo
4410 .No , Ns Ar number Ns ...\& Oc
4411 .Op Ar delay Op Ar retry
4413 If no arguments are given, CBCP (Microsoft's CallBack Control Protocol)
4414 is disabled - ie, configuring CBCP in the
4416 command will result in
4418 requesting no callback in the CBCP phase.
4421 attempts to use the given phone
4422 .Ar number Ns No (s).
4427 will insist that the client uses one of these numbers, unless
4429 is used in which case the client is expected to specify the number.
4433 will attempt to use one of the given numbers (whichever it finds to
4434 be agreeable with the peer), or if
4438 will expect the peer to specify the number.
4440 .No off| Ns Ar seconds Ns Op !\&
4444 checks for the existence of carrier depending on the type of device
4445 that has been opened:
4446 .Bl -tag -width XXX -offset XXX
4447 .It Terminal Devices
4448 Carrier is checked one second after the login script is complete.
4451 assumes that this is because the device does not support carrier (which
4454 NULL-modem cables), logs the fact and stops checking
4457 As ptys do not support the TIOCMGET ioctl, the tty device will switch all
4458 carrier detection off when it detects that the device is a pty.
4459 .It ISDN (i4b) Devices
4460 Carrier is checked once per second for 6 seconds.
4461 If it is not set after
4462 the sixth second, the connection attempt is considered to have failed and
4463 the device is closed.
4464 Carrier is always required for i4b devices.
4465 .It PPPoE (netgraph) Devices
4466 Carrier is checked once per second for 5 seconds.
4467 If it is not set after
4468 the fifth second, the connection attempt is considered to have failed and
4469 the device is closed.
4470 Carrier is always required for PPPoE devices.
4473 All other device types do not support carrier.
4474 Setting a carrier value will
4475 result in a warning when the device is opened.
4477 Some modems take more than one second after connecting to assert the carrier
4479 If this delay is not increased, this will result in
4481 inability to detect when the link is dropped, as
4483 assumes that the device is not asserting carrier.
4487 command overrides the default carrier behaviour.
4489 specifies the maximum number of seconds that
4491 should wait after the dial script has finished before deciding if
4492 carrier is available or not.
4498 will not check for carrier on the device, otherwise
4500 will not proceed to the login script until either carrier is detected
4503 has elapsed, at which point
4505 assumes that the device will not set carrier.
4507 If no arguments are given, carrier settings will go back to their default
4512 is followed immediately by an exclamation mark
4518 If carrier is not detected after
4520 seconds, the link will be disconnected.
4521 .It set choked Op Ar timeout
4522 This sets the number of seconds that
4524 will keep a choked output queue before dropping all pending output packets.
4527 is less than or equal to zero or if
4529 is not specified, it is set to the default value of
4532 A choked output queue occurs when
4534 has read a certain number of packets from the local network for transmission,
4535 but cannot send the data due to link failure (the peer is busy etc.).
4537 will not read packets indefinitely.
4538 Instead, it reads up to
4544 packets in multi-link mode), then stops reading the network interface
4547 seconds have passed or at least one packet has been sent.
4551 seconds pass, all pending output packets are dropped.
4552 .It set ctsrts|crtscts on|off
4553 This sets hardware flow control.
4554 Hardware flow control is
4557 .It set deflate Ar out-winsize Op Ar in-winsize
4558 This sets the DEFLATE algorithms default outgoing and incoming window
4564 must be values between
4572 will insist that this window size is used and will not accept any other
4573 values from the peer.
4574 .It set dns Op Ar primary Op Ar secondary
4575 This command specifies DNS overrides for the
4580 command description above for details.
4581 This command does not affect the IP numbers requested using
4583 .It set device|line Xo
4586 This sets the device(s) to which
4588 will talk to the given
4591 All ISDN and serial device names are expected to begin with
4593 ISDN devices are usually called
4595 and serial devices are usually called
4602 it must either begin with an exclamation mark
4605 .No PPPoE: Ns Ar iface Ns Xo
4606 .Op \&: Ns Ar provider Ns
4610 enabled systems), or be of the format
4612 .Ar host : port Op /tcp|udp .
4615 If it begins with an exclamation mark, the rest of the device name is
4616 treated as a program name, and that program is executed when the device
4618 Standard input, output and error are fed back to
4620 and are read and written as if they were a regular device.
4623 .No PPPoE: Ns Ar iface Ns Xo
4624 .Op \&: Ns Ar provider Ns
4626 specification is given,
4628 will attempt to create a
4630 over Ethernet connection using the given
4638 will attempt to load it using
4640 If this fails, an external program must be used such as the
4642 program available under
4646 is passed as the service name in the PPPoE Discovery Initiation (PADI)
4648 If no provider is given, an empty value will be used.
4650 When a PPPoE connection is established,
4652 will place the name of the Access Concentrator in the environment variable
4659 for further details.
4662 .Ar host Ns No : Ns Ar port Ns Oo
4665 specification is given,
4667 will attempt to connect to the given
4675 suffix is not provided, the default is
4677 Refer to the section on
4678 .Em PPP OVER TCP and UDP
4679 above for further details.
4685 will attempt to open each one in turn until it succeeds or runs out of
4687 .It set dial Ar chat-script
4688 This specifies the chat script that will be used to dial the other
4695 and to the example configuration files for details of the chat script
4697 It is possible to specify some special
4699 in your chat script as follows:
4702 When used as the last character in a
4704 string, this indicates that a newline should not be appended.
4706 When the chat script encounters this sequence, it delays two seconds.
4708 When the chat script encounters this sequence, it delays for one quarter of
4711 This is replaced with a newline character.
4713 This is replaced with a carriage return character.
4715 This is replaced with a space character.
4717 This is replaced with a tab character.
4719 This is replaced by the current phone number (see
4723 This is replaced by the current
4729 This is replaced by the current
4736 Note that two parsers will examine these escape sequences, so in order to
4739 see the escape character, it is necessary to escape it from the
4740 .Sq command parser .
4741 This means that in practice you should use two escapes, for example:
4742 .Bd -literal -offset indent
4743 set dial "... ATDT\\\\T CONNECT"
4746 It is also possible to execute external commands from the chat script.
4747 To do this, the first character of the expect or send string is an
4750 If a literal exclamation mark is required, double it up to
4752 and it will be treated as a single literal
4754 When the command is executed, standard input and standard output are
4755 directed to the open device (see the
4757 command), and standard error is read by
4759 and substituted as the expect or send string.
4762 is running in interactive mode, file descriptor 3 is attached to
4765 For example (wrapped for readability):
4766 .Bd -literal -offset indent
4767 set login "TIMEOUT 5 \\"\\" \\"\\" login:--login: ppp \e
4768 word: ppp \\"!sh \\\\-c \\\\\\"echo \\\\-n label: >&2\\\\\\"\\" \e
4769 \\"!/bin/echo in\\" HELLO"
4772 would result in the following chat sequence (output using the
4773 .Sq set log local chat
4774 command before dialing):
4775 .Bd -literal -offset indent
4780 Chat: Expecting: login:--login:
4781 Chat: Wait for (5): login:
4783 Chat: Expecting: word:
4784 Chat: Wait for (5): word:
4786 Chat: Expecting: !sh \\-c "echo \\-n label: >&2"
4787 Chat: Exec: sh -c "echo -n label: >&2"
4788 Chat: Wait for (5): !sh \\-c "echo \\-n label: >&2" --> label:
4789 Chat: Exec: /bin/echo in
4791 Chat: Expecting: HELLO
4792 Chat: Wait for (5): HELLO
4796 Note (again) the use of the escape character, allowing many levels of
4798 Here, there are four parsers at work.
4799 The first parses the original line, reading it as three arguments.
4800 The second parses the third argument, reading it as 11 arguments.
4801 At this point, it is
4804 signs are escaped, otherwise this parser will see them as constituting
4805 an expect-send-expect sequence.
4808 character is seen, the execution parser reads the first command as three
4811 itself expands the argument after the
4813 As we wish to send the output back to the modem, in the first example
4814 we redirect our output to file descriptor 2 (stderr) so that
4816 itself sends and logs it, and in the second example, we just output to stdout,
4817 which is attached directly to the modem.
4819 This, of course means that it is possible to execute an entirely external
4821 command rather than using the internal one.
4824 for a good alternative.
4826 The external command that is executed is subjected to the same special
4827 word expansions as the
4830 .It set enddisc Op label|IP|MAC|magic|psn value
4831 This command sets our local endpoint discriminator.
4832 If set prior to LCP negotiation, and if no
4834 command has been used,
4836 will send the information to the peer using the LCP endpoint discriminator
4838 The following discriminators may be set:
4839 .Bl -tag -width indent
4841 The current label is used.
4843 Our local IP number is used.
4844 As LCP is negotiated prior to IPCP, it is
4845 possible that the IPCP layer will subsequently change this value.
4847 it does, the endpoint discriminator stays at the old value unless manually
4850 This is similar to the
4852 option above, except that the MAC address associated with the local IP
4854 If the local IP number is not resident on any Ethernet
4855 interface, the command will fail.
4857 As the local IP number defaults to whatever the machine host name is,
4859 is usually done prior to any
4863 A 20 digit random number is used.
4864 Care should be taken when using magic numbers as restarting
4866 or creating a link using a different
4868 invocation will also use a different magic number and will therefore not
4869 be recognised by the peer as belonging to the same bundle.
4870 This makes it unsuitable for
4878 should be set to an absolute public switched network number with the
4882 If no arguments are given, the endpoint discriminator is reset.
4883 .It set escape Ar value...
4884 This option is similar to the
4887 It allows the user to specify a set of characters that will be
4889 as they travel across the link.
4890 .It set filter dial|alive|in|out Ar rule-no Xo
4891 .No permit|deny|clear| Ns Ar rule-no
4894 .Ar src_addr Ns Op / Ns Ar width
4895 .Op Ar dst_addr Ns Op / Ns Ar width
4897 .Op src lt|eq|gt Ar port
4898 .Op dst lt|eq|gt Ar port
4902 .Op timeout Ar secs ]
4905 supports four filter sets.
4908 filter specifies packets that keep the connection alive - resetting the
4912 filter specifies packets that cause
4919 filter specifies packets that are allowed to travel
4920 into the machine and the
4922 filter specifies packets that are allowed out of the machine.
4924 Filtering is done prior to any IP alterations that might be done by the
4925 NAT engine on outgoing packets and after any IP alterations that might
4926 be done by the NAT engine on incoming packets.
4927 By default all empty filter sets allow all packets to pass.
4928 Rules are processed in order according to
4930 (unless skipped by specifying a rule number as the
4932 Up to 40 rules may be given for each set.
4933 If a packet does not match
4934 any of the rules in a given set, it is discarded.
4939 filters, this means that the packet is dropped.
4942 filters it means that the packet will not reset the idle timer (even if
4944 .Ar in Ns No / Ns Ar out
4947 value) and in the case of
4949 filters it means that the packet will not trigger a dial.
4950 A packet failing to trigger a dial will be dropped rather than queued.
4953 .Sx PACKET FILTERING
4954 above for further details.
4955 .It set hangup Ar chat-script
4956 This specifies the chat script that will be used to reset the device
4957 before it is closed.
4958 It should not normally be necessary, but can
4959 be used for devices that fail to reset themselves properly on close.
4960 .It set help|? Op Ar command
4961 This command gives a summary of available set commands, or if
4963 is specified, the command usage is shown.
4964 .It set ifaddr Oo Ar myaddr Ns
4966 .Oo Ar hisaddr Ns Op / Ns Ar \&nn
4971 This command specifies the IP addresses that will be used during
4973 Addresses are specified using the format
4979 is the preferred IP, but
4981 specifies how many bits of the address we will insist on.
4984 is omitted, it defaults to
4986 unless the IP address is 0.0.0.0 in which case it defaults to
4989 If you wish to assign a dynamic IP number to the peer,
4991 may also be specified as a range of IP numbers in the format
4992 .Bd -ragged -offset indent
4993 .Ar \&IP Ns Oo \&- Ns Ar \&IP Ns Xo
4994 .Oc Ns Oo , Ns Ar \&IP Ns
4995 .Op \&- Ns Ar \&IP Ns
5002 .Dl set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20
5006 as the local IP number, but may assign any of the given 10 IP
5007 numbers to the peer.
5008 If the peer requests one of these numbers,
5009 and that number is not already in use,
5011 will grant the peers request.
5012 This is useful if the peer wants
5013 to re-establish a link using the same IP number as was previously
5014 allocated (thus maintaining any existing tcp or udp connections).
5016 If the peer requests an IP number that is either outside
5017 of this range or is already in use,
5019 will suggest a random unused IP number from the range.
5023 is specified, it is used in place of
5025 in the initial IPCP negotiation.
5026 However, only an address in the
5028 range will be accepted.
5029 This is useful when negotiating with some
5031 implementations that will not assign an IP number unless their peer
5035 It should be noted that in
5039 will configure the interface immediately upon reading the
5041 line in the config file.
5042 In any other mode, these values are just
5043 used for IPCP negotiations, and the interface is not configured
5044 until the IPCP layer is up.
5048 argument may be overridden by the third field in the
5050 file once the client has authenticated itself
5054 .Sx AUTHENTICATING INCOMING CONNECTIONS
5055 section for details.
5057 In all cases, if the interface is already configured,
5059 will try to maintain the interface IP numbers so that any existing
5060 bound sockets will remain valid.
5061 .It set ifqueue Ar packets
5062 Set the maximum number of packets that
5064 will read from the tunnel interface while data cannot be sent to any of
5065 the available links.
5066 This queue limit is necessary to flow control outgoing data as the tunnel
5067 interface is likely to be far faster than the combined links available to
5072 is set to a value less than the number of links,
5074 will read up to that value regardless.
5075 This prevents any possible latency problems.
5077 The default value for
5081 .It set ccpretry|ccpretries Oo Ar timeout
5082 .Op Ar reqtries Op Ar trmtries
5084 .It set chapretry|chapretries Oo Ar timeout
5087 .It set ipcpretry|ipcpretries Oo Ar timeout
5088 .Op Ar reqtries Op Ar trmtries
5090 .It set ipv6cpretry|ipv6cpretries Oo Ar timeout
5091 .Op Ar reqtries Op Ar trmtries
5093 .It set lcpretry|lcpretries Oo Ar timeout
5094 .Op Ar reqtries Op Ar trmtries
5096 .It set papretry|papretries Oo Ar timeout
5099 These commands set the number of seconds that
5101 will wait before resending Finite State Machine (FSM) Request packets.
5104 for all FSMs is 3 seconds (which should suffice in most cases).
5108 is specified, it tells
5110 how many configuration request attempts it should make while receiving
5111 no reply from the peer before giving up.
5112 The default is 5 attempts for
5113 CCP, LCP and IPCP and 3 attempts for PAP and CHAP.
5117 is specified, it tells
5119 how many terminate requests should be sent before giving up waiting for the
5121 The default is 3 attempts.
5122 Authentication protocols are
5123 not terminated and it is therefore invalid to specify
5127 In order to avoid negotiations with the peer that will never converge,
5129 will only send at most 3 times the configured number of
5131 in any given negotiation session before giving up and closing that layer.
5137 This command allows the adjustment of the current log level.
5138 Refer to the Logging Facility section for further details.
5139 .It set login Ar chat-script
5142 compliments the dial-script.
5143 If both are specified, the login
5144 script will be executed after the dial script.
5145 Escape sequences available in the dial script are also available here.
5146 .It set logout Ar chat-script
5147 This specifies the chat script that will be used to logout
5148 before the hangup script is called.
5149 It should not normally be necessary.
5150 .It set lqrperiod|echoperiod Ar frequency
5151 This command sets the
5158 The default is 30 seconds.
5159 You must also use the
5163 commands if you wish to send
5167 requests to the peer.
5168 .It set mode Ar interactive|auto|ddial|background
5169 This command allows you to change the
5171 of the specified link.
5172 This is normally only useful in multi-link mode,
5173 but may also be used in uni-link mode.
5175 It is not possible to change a link that is
5180 Note: If you issue the command
5182 and have network address translation enabled, it may be useful to
5183 .Dq enable iface-alias
5187 to do the necessary address translations to enable the process that
5188 triggers the connection to connect once the link is up despite the
5189 peer assigning us a new (dynamic) IP address.
5190 .It set mppe Op 40|56|128|* Op stateless|stateful|*
5191 This option selects the encryption parameters used when negotiation
5193 MPPE can be disabled entirely with the
5196 If no arguments are given,
5198 will attempt to negotiate a stateful link with a 128 bit key, but
5199 will agree to whatever the peer requests (including no encryption
5202 If any arguments are given,
5206 on using MPPE and will close the link if it is rejected by the peer (Note;
5207 this behaviour can be overridden by a configured RADIUS server).
5209 The first argument specifies the number of bits that
5211 should insist on during negotiations and the second specifies whether
5213 should insist on stateful or stateless mode.
5214 In stateless mode, the
5215 encryption dictionary is re-initialised with every packet according to
5216 an encryption key that is changed with every packet.
5218 the encryption dictionary is re-initialised every 256 packets or after
5219 the loss of any data and the key is changed every 256 packets.
5220 Stateless mode is less efficient but is better for unreliable transport
5222 .It set mrru Op Ar value
5223 Setting this option enables Multi-link PPP negotiations, also known as
5224 Multi-link Protocol or MP.
5225 There is no default MRRU (Maximum Reconstructed Receive Unit) value.
5226 If no argument is given, multi-link mode is disabled.
5231 The default MRU (Maximum Receive Unit) is 1500.
5232 If it is increased, the other side *may* increase its MTU.
5233 In theory there is no point in decreasing the MRU to below the default as the
5235 protocol says implementations *must* be able to accept packets of at
5242 will refuse to negotiate a higher value.
5243 The maximum MRU can be set to 2048 at most.
5244 Setting a maximum of less than 1500 violates the
5246 rfc, but may sometimes be necessary.
5249 imposes a maximum of 1492 due to hardware limitations.
5251 If no argument is given, 1500 is assumed.
5252 A value must be given when
5259 The default MTU is 1500.
5260 At negotiation time,
5262 will accept whatever MRU the peer requests (assuming it is
5263 not less than 296 bytes or greater than the assigned maximum).
5266 will not accept MRU values less than
5268 When negotiations are complete, the MTU is used when writing to the
5269 interface, even if the peer requested a higher value MRU.
5270 This can be useful for
5271 limiting your packet size (giving better bandwidth sharing at the expense
5272 of more header data).
5278 will refuse to negotiate a higher value.
5279 The maximum MTU can be set to 2048 at most.
5280 Note, it is necessary to use the
5282 keyword to limit the MTU when using PPPoE.
5286 is given, 1500, or whatever the peer asks for is used.
5287 A value must be given when
5290 .It set nbns Op Ar x.x.x.x Op Ar y.y.y.y
5291 This option allows the setting of the Microsoft NetBIOS name server
5292 values to be returned at the peers request.
5293 If no values are given,
5295 will reject any such requests.
5296 .It set openmode active|passive Op Ar delay
5305 will always initiate LCP/IPCP/CCP negotiation one second after the line
5307 If you want to wait for the peer to initiate negotiations, you
5310 If you want to initiate negotiations immediately or after more than one
5311 second, the appropriate
5313 may be specified here in seconds.
5314 .It set parity odd|even|none|mark
5315 This allows the line parity to be set.
5316 The default value is
5318 .It set phone Ar telno Ns Xo
5319 .Oo \&| Ns Ar backupnumber
5320 .Oc Ns ... Ns Oo : Ns Ar nextnumber
5323 This allows the specification of the phone number to be used in
5324 place of the \\\\T string in the dial and login chat scripts.
5325 Multiple phone numbers may be given separated either by a pipe
5330 Numbers after the pipe are only dialed if the dial or login
5331 script for the previous number failed.
5333 Numbers after the colon are tried sequentially, irrespective of
5334 the reason the line was dropped.
5336 If multiple numbers are given,
5338 will dial them according to these rules until a connection is made, retrying
5339 the maximum number of times specified by
5344 mode, each number is attempted at most once.
5345 .It set pppoe Op standard|3Com
5346 This option configures the underlying
5348 node to either standard RFC2516 PPPoE or proprietary 3Com mode.
5349 If not set the system default will be used.
5350 .It set Op proc Ns Xo
5351 .No title Op Ar value
5353 The current process title as displayed by
5355 is changed according to
5359 is not specified, the original process title is restored.
5361 word replacements done by the shell commands (see the
5363 command above) are done here too.
5365 Note, if USER is required in the process title, the
5367 command must appear in
5369 as it is not known when the commands in
5372 .It set radius Op Ar config-file
5373 This command enables RADIUS support (if it is compiled in).
5375 refers to the radius client configuration file as described in
5377 If PAP, CHAP, MSCHAP or MSCHAPv2 are
5378 .Dq enable Ns No d ,
5381 .Em \&N Ns No etwork
5384 and uses the configured RADIUS server to authenticate rather than
5385 authenticating from the
5387 file or from the passwd database.
5389 If none of PAP, CHAP, MSCHAP or MSCHAPv2 are enabled,
5394 uses the following attributes from the RADIUS reply:
5395 .Bl -tag -width XXX -offset XXX
5396 .It RAD_FRAMED_IP_ADDRESS
5397 The peer IP address is set to the given value.
5398 .It RAD_FRAMED_IP_NETMASK
5399 The tun interface netmask is set to the given value.
5401 If the given MTU is less than the peers MRU as agreed during LCP
5402 negotiation, *and* it is less that any configured MTU (see the
5404 command), the tun interface MTU is set to the given value.
5405 .It RAD_FRAMED_COMPRESSION
5406 If the received compression type is
5409 will request VJ compression during IPCP negotiations despite any
5411 configuration command.
5413 If this attribute is supplied,
5415 will attempt to use it as an additional label to load from the
5420 The load will be attempted before (and in addition to) the normal
5422 If the label does not exist, no action is taken and
5424 proceeds to the normal load using the current label.
5425 .It RAD_FRAMED_ROUTE
5426 The received string is expected to be in the format
5427 .Ar dest Ns Op / Ns Ar bits
5430 Any specified metrics are ignored.
5434 are understood as valid values for
5441 to sepcify the default route, and
5443 is understood to be the same as
5452 For example, a returned value of
5453 .Dq 1.2.3.4/24 0.0.0.0 1 2 -1 3 400
5454 would result in a routing table entry to the 1.2.3.0/24 network via
5456 and a returned value of
5460 would result in a default route to
5463 All RADIUS routes are applied after any sticky routes are applied, making
5464 RADIUS routes override configured routes.
5465 This also applies for RADIUS routes that do not {include} the
5471 .It RAD_FRAMED_IPV6_PREFIX
5472 If this attribute is supplied, the value is substituted for IPV6PREFIX
5474 You may pass it to such as DHCPv6 for delegating an
5475 IPv6 prefix to a peer.
5476 .It RAD_FRAMED_IPV6_ROUTE
5477 The received string is expected to be in the format
5478 .Ar dest Ns Op / Ns Ar bits
5481 Any specified metrics are ignored.
5485 are understood as valid values for
5492 to sepcify the default route, and
5494 is understood to be the same as
5503 For example, a returned value of
5504 .Dq 3ffe:505:abcd::/48 ::
5505 would result in a routing table entry to the 3ffe:505:abcd::/48 network via
5507 and a returned value of
5510 .Dq default HISADDR6
5511 would result in a default route to
5514 All RADIUS IPv6 routes are applied after any sticky routes are
5515 applied, making RADIUS IPv6 routes override configured routes.
5517 also applies for RADIUS IPv6 routes that do not {include} the
5523 .It RAD_SESSION_TIMEOUT
5524 If supplied, the client connection is closed after the given number of
5526 .It RAD_REPLY_MESSAGE
5527 If supplied, this message is passed back to the peer as the authentication
5529 .It RAD_MICROSOFT_MS_CHAP_ERROR
5531 .Dv RAD_VENDOR_MICROSOFT
5532 vendor specific attribute is supplied, it is passed back to the peer as the
5533 authentication FAILURE text.
5534 .It RAD_MICROSOFT_MS_CHAP2_SUCCESS
5536 .Dv RAD_VENDOR_MICROSOFT
5537 vendor specific attribute is supplied and if MS-CHAPv2 authentication is
5538 being used, it is passed back to the peer as the authentication SUCCESS text.
5539 .It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY
5541 .Dv RAD_VENDOR_MICROSOFT
5542 vendor specific attribute is supplied and has a value of 2 (Required),
5544 will insist that MPPE encryption is used (even if no
5546 configuration command has been given with arguments).
5547 If it is supplied with a value of 1 (Allowed), encryption is made optional
5550 configuration commands with arguments).
5551 .It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES
5553 .Dv RAD_VENDOR_MICROSOFT
5554 vendor specific attribute is supplied, bits 1 and 2 are examined.
5555 If either or both are set, 40 bit and/or 128 bit (respectively) encryption
5556 options are set, overriding any given first argument to the
5559 Note, it is not currently possible for the RADIUS server to specify 56 bit
5561 .It RAD_MICROSOFT_MS_MPPE_RECV_KEY
5563 .Dv RAD_VENDOR_MICROSOFT
5564 vendor specific attribute is supplied, it is value is used as the master
5565 key for decryption of incoming data.
5566 When clients are authenticated using
5567 MSCHAPv2, the RADIUS server MUST provide this attribute if inbound MPPE is
5569 .It RAD_MICROSOFT_MS_MPPE_SEND_KEY
5571 .Dv RAD_VENDOR_MICROSOFT
5572 vendor specific attribute is supplied, it is value is used as the master
5573 key for encryption of outgoing data.
5574 When clients are authenticated using
5575 MSCHAPv2, the RADIUS server MUST provide this attribute if outbound MPPE is
5579 Values received from the RADIUS server may be viewed using
5581 .It set rad_alive Ar timeout
5582 When RADIUS is configured, setting
5588 to sent RADIUS accounting information to the RADIUS server every
5591 .It set rad_port_id Ar option
5592 When RADIUS is configured, setting the
5594 value allows to specify what should be sent to the RADIUS server as
5602 PID of the corresponding tunnel.
5607 index of the interface as returned by
5608 .Xr if_nametoindex 3 .
5610 keeps the default behavior.
5612 .It set reconnect Ar timeout ntries
5613 Should the line drop unexpectedly (due to loss of CD or LQR
5614 failure), a connection will be re-established after the given
5616 The line will be re-connected at most
5625 will result in a variable pause, somewhere between 1 and 30 seconds.
5626 .It set recvpipe Op Ar value
5627 This sets the routing table RECVPIPE value.
5628 The optimum value is just over twice the MTU value.
5631 is unspecified or zero, the default kernel controlled value is used.
5632 .It set redial Ar secs Ns Xo
5635 .Oc Ns Op . Ns Ar next
5639 can be instructed to attempt to redial
5642 If more than one phone number is specified (see
5646 is taken before dialing each number.
5649 is taken before starting at the first number again.
5652 may be used here in place of
5656 causing a random delay of between 1 and 30 seconds.
5660 is specified, its value is added onto
5666 will only be incremented at most
5674 delay will be effective, even after
5676 has been exceeded, so an immediate manual dial may appear to have
5678 If an immediate dial is required, a
5680 should immediately follow the
5685 description above for further details.
5686 .It set sendpipe Op Ar value
5687 This sets the routing table SENDPIPE value.
5688 The optimum value is just over twice the MTU value.
5691 is unspecified or zero, the default kernel controlled value is used.
5692 .It "set server|socket" Ar TcpPort Ns No \&| Ns Xo
5693 .Ar LocalName Ns No |none|open|closed
5694 .Op password Op Ar mask
5698 to listen on the given socket or
5700 for incoming command connections.
5706 to close any existing socket and clear the socket configuration.
5711 to attempt to re-open the port.
5716 to close the open port.
5718 If you wish to specify a local domain socket,
5720 must be specified as an absolute file name, otherwise it is assumed
5721 to be the name or number of a TCP port.
5722 You may specify the octal umask to be used with a local domain socket.
5728 for details of how to translate TCP port names.
5730 You must also specify the password that must be entered by the client
5733 variable above) when connecting to this socket.
5735 specified as an empty string, no password is required for connecting clients.
5737 When specifying a local domain socket, the first
5739 sequence found in the socket name will be replaced with the current
5740 interface unit number.
5741 This is useful when you wish to use the same
5742 profile for more than one connection.
5744 In a similar manner TCP sockets may be prefixed with the
5746 character, in which case the current interface unit number is added to
5751 with a server socket, the
5753 command is the preferred mechanism of communications.
5756 can also be used, but link encryption may be implemented in the future, so
5764 interact with the diagnostic socket.
5765 .It set speed Ar value
5766 This sets the speed of the serial device.
5767 If speed is specified as
5770 treats the device as a synchronous device.
5772 Certain device types will know whether they should be specified as
5773 synchronous or asynchronous.
5774 These devices will override incorrect
5775 settings and log a warning to this effect.
5776 .It set stopped Op Ar LCPseconds Op Ar CCPseconds
5777 If this option is set,
5779 will time out after the given FSM (Finite State Machine) has been in
5780 the stopped state for the given number of
5782 This option may be useful if the peer sends a terminate request,
5783 but never actually closes the connection despite our sending a terminate
5785 This is also useful if you wish to
5786 .Dq set openmode passive
5787 and time out if the peer does not send a Configure Request within the
5790 .Dq set log +lcp +ccp
5793 log the appropriate state transitions.
5795 The default value is zero, where
5797 does not time out in the stopped state.
5799 This value should not be set to less than the openmode delay (see
5802 .It set timeout Ar idleseconds Op Ar mintimeout
5803 This command allows the setting of the idle timer.
5804 Refer to the section titled
5805 .Sx SETTING THE IDLE TIMER
5806 for further details.
5812 will never idle out before the link has been up for at least that number
5820 This command controls the ports that
5822 prioritizes when transmitting data.
5823 The default priority TCP ports
5824 are ports 21 (ftp control), 22 (ssh), 23 (telnet), 513 (login), 514 (shell),
5825 543 (klogin) and 544 (kshell).
5826 There are no priority UDP ports by default.
5841 are given, the priority port lists are cleared (although if
5845 is specified, only that list is cleared).
5848 argument is prefixed with a plus
5852 the current list is adjusted, otherwise the list is reassigned.
5854 prefixed with a plus or not prefixed at all are added to the list and
5856 prefixed with a minus are removed from the list.
5860 is specified, all priority port lists are disabled and even
5862 packets are not prioritised.
5863 .It set vj slotcomp on|off
5866 whether it should attempt to negotiate VJ slot compression.
5867 By default, slot compression is turned
5869 .It set vj slots Ar nslots
5870 This command sets the initial number of slots that
5872 will try to negotiate with the peer when VJ compression is enabled (see the
5875 It defaults to a value of 16.
5884 .It shell|! Op Ar command
5887 is not specified a shell is invoked according to the
5889 environment variable.
5890 Otherwise, the given
5893 Word replacement is done in the same way as for the
5895 command as described above.
5897 Use of the !\& character
5898 requires a following space as with any of the other commands.
5899 You should note that this command is executed in the foreground;
5901 will not continue running until this process has exited.
5904 command if you wish processing to happen in the background.
5906 This command allows the user to examine the following:
5909 Show the current bundle settings.
5911 Show the current CCP compression statistics.
5913 Show the current VJ compression statistics.
5915 Show the current escape characters.
5916 .It show filter Op Ar name
5917 List the current rules for the given filter.
5920 is not specified, all filters are shown.
5922 Show the current HDLC statistics.
5924 Give a summary of available show commands.
5926 Show the current interface information
5930 Show the current IPCP statistics.
5932 Show the protocol layers currently in use.
5934 Show the current LCP statistics.
5935 .It show Op data Ns Xo
5938 Show high level link information.
5940 Show a list of available logical links.
5942 Show the current log values.
5944 Show current memory statistics.
5946 Show the current NCP statistics.
5948 Show low level link information.
5950 Show Multi-link information.
5952 Show current protocol totals.
5954 Show the current routing tables.
5956 Show the current stopped timeouts.
5958 Show the active alarm timers.
5960 Show the current version number of
5965 Go into terminal mode.
5966 Characters typed at the keyboard are sent to the device.
5967 Characters read from the device are displayed on the screen.
5972 automatically enables Packet Mode and goes back into command mode.
5977 Read the example configuration files.
5978 They are a good source of information.
5987 to get online information about what is available.
5989 The following URLs contain useful information:
5990 .Bl -bullet -compact
5992 http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/faq/ppp.html
5994 http://www.FreeBSD.org/doc/handbook/userppp.html
6000 refers to four files:
6006 These files are placed in the
6010 .It Pa /etc/ppp/ppp.conf
6011 System default configuration file.
6012 .It Pa /etc/ppp/ppp.secret
6013 An authorisation file for each system.
6014 .It Pa /etc/ppp/ppp.linkup
6015 A file to check when
6017 establishes a network level connection.
6018 .It Pa /etc/ppp/ppp.linkdown
6019 A file to check when
6021 closes a network level connection.
6022 .It Pa /var/log/ppp.log
6023 Logging and debugging information file.
6024 Note, this name is specified in
6025 .Pa /etc/syslog.conf .
6028 for further details.
6029 .It Pa /var/spool/lock/LCK..*
6030 tty port locking file.
6033 for further details.
6034 .It Pa /var/run/tunN.pid
6035 The process id (pid) of the
6037 program connected to the tunN device, where
6039 is the number of the device.
6040 .It Pa /var/run/ttyXX.if
6041 The tun interface used by this port.
6042 Again, this file is only created in
6048 .It Pa /etc/services
6049 Get port number if port number is using service name.
6050 .It Pa /var/run/ppp-authname-class-value
6051 In multi-link mode, local domain sockets are created using the peer
6054 the peer endpoint discriminator class
6056 and the peer endpoint discriminator value
6058 As the endpoint discriminator value may be a binary value, it is turned
6059 to HEX to determine the actual file name.
6061 This socket is used to pass links between different instances of
6073 ifdef({LOCALNAT},{},{.Xr libalias 3 ,
6075 ifdef({LOCALRAD},{},{.Xr libradius 3 ,
6105 This program was originally written by
6106 .An Toshiharu OHNO Aq tony-o@iij.ad.jp ,
6107 and was submitted to
6110 .An Atsushi Murai Aq amurai@spec.co.jp .
6112 It was substantially modified during 1997 by
6113 .An Brian Somers Aq brian@Awfulhak.org ,
6116 in November that year
6117 (just after the 2.2 release).
6119 Most of the code was rewritten by
6121 in early 1998 when multi-link ppp support was added.
projects / FreeBSD / releng / 7.2.git / blob