4 .\" Copyright (c) 2001 Brian Somers <brian@Awfulhak.org>
5 .\" All rights reserved.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" $FreeBSD: src/usr.sbin/ppp/ppp.8.m4,v 1.301.2.1 2002/09/01 02:12:31 brian Exp $
35 .Nd Point to Point Protocol (a.k.a. user-ppp)
44 This is a user process
49 is implemented as a part of the kernel (e.g., as managed by
51 and it's thus somewhat hard to debug and/or modify its behaviour.
52 However, in this implementation
54 is done as a user process with the help of the
55 tunnel device driver (tun).
59 flag does the equivalent of a
63 network address translation features.
66 to act as a NAT or masquerading engine for all machines on an internal
68 ifdef({LOCALNAT},{},{Refer to
70 for details on the technical side of the NAT engine.
73 .Sx NETWORK ADDRESS TRANSLATION (PACKET ALIASING)
74 section of this manual page for details on how to configure NAT in
81 to be silent at startup rather than displaying the mode and interface
88 to only attempt to open
89 .Pa /dev/tun Ns Ar N .
92 will start with a value of 0 for
94 and keep trying to open a tunnel device by incrementing the value of
96 by one each time until it succeeds.
97 If it fails three times in a row
98 because the device file is missing, it gives up.
104 .Bl -tag -width XXX -offset XXX
107 opens the tun interface, configures it then goes into the background.
108 The link isn't brought up until outgoing data is detected on the tun
109 interface at which point
111 attempts to bring up the link.
112 Packets received (including the first one) while
114 is trying to bring the link up will remain queued for a default of
124 must be given on the command line (see below) and a
126 must be done in the system profile that specifies a peer IP address to
127 use when configuring the interface.
130 is usually appropriate.
134 .Pa /usr/share/examples/ppp/ppp.conf.sample
139 attempts to establish a connection with the peer immediately.
142 goes into the background and the parent process returns an exit code
146 exits with a non-zero result.
150 attempts to establish a connection with the peer immediately, but never
152 The link is created in background mode.
153 This is useful if you wish to control
155 invocation from another process.
157 This is used for receiving incoming connections.
161 line and uses descriptor 0 as the link.
163 If callback is configured,
167 information when dialing back.
169 This option is designed for machines connected with a dedicated
172 will always keep the device open and will never use any configured
175 This mode is equivalent to
179 will bring the link back up any time it's dropped for any reason.
181 This is a no-op, and gives the same behaviour as if none of the above
182 modes have been specified.
184 loads any sections specified on the command line then provides an
188 One or more configuration entries or systems
190 .Pa /etc/ppp/ppp.conf )
191 may also be specified on the command line.
196 .Pa /etc/ppp/ppp.conf
197 at startup, followed by each of the systems specified on the command line.
200 .It Provides an interactive user interface.
201 Using its command mode, the user can
202 easily enter commands to establish the connection with the remote end, check
203 the status of connection and close the connection.
204 All functions can also be optionally password protected for security.
205 .It Supports both manual and automatic dialing.
206 Interactive mode has a
208 command which enables you to talk to the device directly.
209 When you are connected to the remote peer and it starts to talk
212 detects it and switches to packet mode automatically.
214 determined the proper sequence for connecting with the remote host, you
215 can write a chat script to {define} the necessary dialing and login
216 procedure for later convenience.
217 .It Supports on-demand dialup capability.
222 will act as a daemon and wait for a packet to be sent over the
225 When this happens, the daemon automatically dials and establishes the
227 In almost the same manner
229 mode (direct-dial mode) also automatically dials and establishes the
231 However, it differs in that it will dial the remote site
232 any time it detects the link is down, even if there are no packets to be
234 This mode is useful for full-time connections where we worry less
235 about line charges and more about being connected full time.
238 mode is also available.
239 This mode is targeted at a dedicated link between two machines.
241 will never voluntarily quit from dedicated mode - you must send it the
243 command via its diagnostic socket.
246 will force an LCP renegotiation, and a
248 will force it to exit.
249 .It Supports client callback.
251 can use either the standard LCP callback protocol or the Microsoft
252 CallBack Control Protocol
253 .Pa ( ftp://ftp.microsoft.com/developr/rfc/cbcp.txt ) .
254 .It Supports NAT or packet aliasing.
255 Packet aliasing (a.k.a. IP masquerading) allows computers on a
256 private, unregistered network to access the Internet.
259 host acts as a masquerading gateway.
260 IP addresses as well as TCP and
261 UDP port numbers are NAT'd for outgoing packets and de-NAT'd for
263 .It Supports background PPP connections.
264 In background mode, if
266 successfully establishes the connection, it will become a daemon.
267 Otherwise, it will exit with an error.
268 This allows the setup of
269 scripts that wish to execute certain commands only if the connection
270 is successfully established.
271 .It Supports server-side PPP connections.
274 acts as server which accepts incoming
276 connections on stdin/stdout.
277 .It "Supports PAP and CHAP (rfc 1994, 2433 and 2759) authentication."
278 With PAP or CHAP, it is possible to skip the Unix style
280 procedure, and use the
282 protocol for authentication instead.
283 If the peer requests Microsoft CHAP authentication and
285 is compiled with DES support, an appropriate MD4/DES response will be
287 .It Supports RADIUS (rfc 2138 & 2548) authentication.
288 An extension to PAP and CHAP,
295 allows authentication information to be stored in a central or
296 distributed database along with various per-user framed connection
298 ifdef({LOCALRAD},{},{If
300 is available at compile time,
304 requests when configured to do so.
306 .It Supports Proxy Arp.
308 can be configured to make one or more proxy arp entries on behalf of
310 This allows routing from the peer to the LAN without
311 configuring each machine on that LAN.
312 .It Supports packet filtering.
313 User can {define} four kinds of filters: the
315 filter for incoming packets, the
317 filter for outgoing packets, the
319 filter to {define} a dialing trigger packet and the
321 filter for keeping a connection alive with the trigger packet.
322 .It Tunnel driver supports bpf.
325 to check the packet flow over the
328 .It Supports PPP over TCP and PPP over UDP.
329 If a device name is specified as
330 .Em host Ns No : Ns Em port Ns
335 will open a TCP or UDP connection for transporting data rather than using a
336 conventional serial device.
337 UDP connections force
339 into synchronous mode.
340 .It Supports PPP over Ethernet (rfc 2516).
343 is given a device specification of the format
344 .No PPPoE: Ns Ar iface Ns Xo
345 .Op \&: Ns Ar provider Ns
359 On systems that do not support
361 an external program such as
364 .It "Supports IETF draft Predictor-1 (rfc 1978) and DEFLATE (rfc 1979) compression."
366 supports not only VJ-compression but also Predictor-1 and DEFLATE compression.
367 Normally, a modem has built-in compression (e.g., v42.bis) and the system
368 may receive higher data rates from it as a result of such compression.
369 While this is generally a good thing in most other situations, this
370 higher speed data imposes a penalty on the system by increasing the
371 number of serial interrupts the system has to process in talking to the
372 modem and also increases latency.
373 Unlike VJ-compression, Predictor-1 and DEFLATE compression pre-compresses
375 network traffic flowing through the link, thus reducing overheads to a
377 .It Supports Microsoft's IPCP extensions (rfc 1877).
378 Name Server Addresses and NetBIOS Name Server Addresses can be negotiated
379 with clients using the Microsoft
381 stack (i.e., Win95, WinNT)
382 .It Supports Multi-link PPP (rfc 1990)
383 It is possible to configure
385 to open more than one physical connection to the peer, combining the
386 bandwidth of all links for better throughput.
387 .It Supports MPPE (draft-ietf-pppext-mppe)
388 MPPE is Microsoft Point to Point Encryption scheme.
389 It is possible to configure
391 to participate in Microsoft's Windows VPN.
394 can only get encryption keys from CHAP 81 authentication.
396 must be compiled with DES for MPPE to operate.
397 .It Supports IPV6CP (rfc 2023).
398 An IPv6 connection can be made in addition to or instead of the normal
411 will not run if the invoking user id is not zero.
412 This may be overridden by using the
415 .Pa /etc/ppp/ppp.conf .
416 When running as a normal user,
418 switches to user id 0 in order to alter the system routing table, set up
419 system lock files and read the ppp configuration files.
420 All external commands (executed via the "shell" or "!bg" commands) are executed
421 as the user id that invoked
425 logging facility if you're interested in what exactly is done as user id
430 you may need to deal with some initial configuration details.
433 Your kernel must {include} a tunnel device (the GENERIC kernel includes
435 If it doesn't, or if you require more than one tun
436 interface, you'll need to rebuild your kernel with the following line in
437 your kernel configuration file:
439 .Dl pseudo-device tun N
443 is the maximum number of
445 connections you wish to support.
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 Don't 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/cuaa0
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 can't 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'll 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's 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/cuaa0
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's 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 couldn't 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.
793 .Pa /etc/ppp/ppp.conf
794 file should consist of at least a
797 This section is always executed.
798 It should also contain
799 one or more sections, named according to their purpose, for example,
801 would represent your ISP, and
803 would represent an incoming
806 You can now specify the destination label name when you invoke
808 Commands associated with the
810 label are executed, followed by those associated with the destination
814 is started with no arguments, the
816 section is still executed.
817 The load command can be used to manually load a section from the
818 .Pa /etc/ppp/ppp.conf
820 .Bd -literal -offset indent
821 ppp ON awfulhak> load MyISP
824 Note, no action is taken by
826 after a section is loaded, whether it's the result of passing a label on
827 the command line or using the
830 Only the commands specified for that label in the configuration
832 However, when invoking
839 switches, the link mode tells
841 to establish a connection.
844 command below for further details.
846 Once the connection is made, the
848 portion of the prompt will change to
850 .Bd -literal -offset indent
853 ppp ON awfulhak> dial
859 The Ppp prompt indicates that
861 has entered the authentication phase.
862 The PPp prompt indicates that
864 has entered the network phase.
865 The PPP prompt indicates that
867 has successfully negotiated a network layer protocol and is in
871 .Pa /etc/ppp/ppp.linkup
872 file is available, its contents are executed
875 connection is established.
879 .Pa /usr/share/examples/ppp/ppp.conf.sample
880 which runs a script in the background after the connection is established
885 commands below for a description of possible substitution strings).
886 Similarly, when a connection is closed, the contents of the
887 .Pa /etc/ppp/ppp.linkdown
889 Both of these files have the same format as
890 .Pa /etc/ppp/ppp.conf .
892 In previous versions of
894 it was necessary to re-add routes such as the default route in the
900 where all routes that contain the
906 literals will automatically be updated when the values of these variables
908 .Sh BACKGROUND DIALING
909 If you want to establish a connection using
911 non-interactively (such as from a
915 job) you should use the
922 attempts to establish the connection immediately.
924 numbers are specified, each phone number will be tried once.
925 If the attempt fails,
927 exits immediately with a non-zero exit code.
930 becomes a daemon, and returns an exit status of zero to its caller.
931 The daemon exits automatically if the connection is dropped by the
932 remote system, or it receives a
936 Demand dialing is enabled with the
941 You must also specify the destination label in
942 .Pa /etc/ppp/ppp.conf
946 command to {define} the remote peers IP address.
948 .Pa /usr/share/examples/ppp/ppp.conf.sample )
949 .Bd -literal -offset indent
959 runs as a daemon but you can still configure or examine its
960 configuration by using the
963 .Pa /etc/ppp/ppp.conf ,
965 .Dq Li "set server +3000 mypasswd" )
966 and connecting to the diagnostic port as follows:
967 .Bd -literal -offset indent
968 # pppctl 3000 (assuming tun0)
970 PPP ON awfulhak> show who
971 tcp (127.0.0.1:1028) *
976 command lists users that are currently connected to
979 If the diagnostic socket is closed or changed to a different
980 socket, all connections are immediately dropped.
984 mode, when an outgoing packet is detected,
986 will perform the dialing action (chat script) and try to connect
990 mode, the dialing action is performed any time the line is found
992 If the connect fails, the default behaviour is to wait 30 seconds
993 and then attempt to connect when another outgoing packet is detected.
994 This behaviour can be changed using the
998 .No set redial Ar secs Ns Xo
1001 .Oc Ns Op . Ns Ar next
1005 .Bl -tag -width attempts -compact
1007 is the number of seconds to wait before attempting
1009 If the argument is the literal string
1011 the delay period is a random value between 1 and 30 seconds inclusive.
1013 is the number of seconds that
1015 should be incremented each time a new dial attempt is made.
1016 The timeout reverts to
1018 only after a successful connection is established.
1019 The default value for
1023 is the maximum number of times
1027 The default value for
1031 is the number of seconds to wait before attempting
1032 to dial the next number in a list of numbers (see the
1035 The default is 3 seconds.
1036 Again, if the argument is the literal string
1038 the delay period is a random value between 1 and 30 seconds.
1040 is the maximum number of times to try to connect for each outgoing packet
1041 that triggers a dial.
1042 The previous value is unchanged if this parameter is omitted.
1043 If a value of zero is specified for
1046 will keep trying until a connection is made.
1050 .Bd -literal -offset indent
1054 will attempt to connect 4 times for each outgoing packet that causes
1055 a dial attempt with a 3 second delay between each number and a 10 second
1056 delay after all numbers have been tried.
1057 If multiple phone numbers
1058 are specified, the total number of attempts is still 4 (it does not
1059 attempt each number 4 times).
1062 .Bd -literal -offset indent
1063 set redial 10+10-5.3 20
1068 to attempt to connect 20 times.
1069 After the first attempt,
1071 pauses for 10 seconds.
1072 After the next attempt it pauses for 20 seconds
1073 and so on until after the sixth attempt it pauses for 1 minute.
1074 The next 14 pauses will also have a duration of one minute.
1077 connects, disconnects and fails to connect again, the timeout starts again
1080 Modifying the dial delay is very useful when running
1084 mode on both ends of the link.
1085 If each end has the same timeout,
1086 both ends wind up calling each other at the same time if the link
1087 drops and both ends have packets queued.
1088 At some locations, the serial link may not be reliable, and carrier
1089 may be lost at inappropriate times.
1090 It is possible to have
1092 redial should carrier be unexpectedly lost during a session.
1093 .Bd -literal -offset indent
1094 set reconnect timeout ntries
1099 to re-establish the connection
1101 times on loss of carrier with a pause of
1103 seconds before each try.
1105 .Bd -literal -offset indent
1111 that on an unexpected loss of carrier, it should wait
1113 seconds before attempting to reconnect.
1114 This may happen up to
1119 The default value of ntries is zero (no reconnect).
1120 Care should be taken with this option.
1121 If the local timeout is slightly
1122 longer than the remote timeout, the reconnect feature will always be
1123 triggered (up to the given number of times) after the remote side
1124 times out and hangs up.
1125 NOTE: In this context, losing too many LQRs constitutes a loss of
1126 carrier and will trigger a reconnect.
1129 flag is specified, all phone numbers are dialed at most once until
1130 a connection is made.
1131 The next number redial period specified with the
1133 command is honoured, as is the reconnect tries value.
1135 value is less than the number of phone numbers specified, not all
1136 the specified numbers will be tried.
1137 To terminate the program, type
1138 .Bd -literal -offset indent
1139 PPP ON awfulhak> close
1140 ppp ON awfulhak> quit all
1145 command will terminate the
1149 connection but not the
1157 .Sh RECEIVING INCOMING PPP CONNECTIONS (Method 1)
1158 To handle an incoming
1160 connection request, follow these steps:
1163 Make sure the modem and (optionally)
1164 .Pa /etc/rc.d/serial
1165 is configured correctly.
1166 .Bl -bullet -compact
1168 Use Hardware Handshake (CTS/RTS) for flow control.
1170 Modem should be set to NO echo back (ATE0) and NO results string (ATQ1).
1178 on the port where the modem is attached.
1181 .Dl ttyd1 Qo /usr/libexec/getty std.38400 Qc dialup on secure
1183 Don't forget to send a
1187 process to start the
1192 It is usually also necessary to train your modem to the same DTR speed
1194 .Bd -literal -offset indent
1196 ppp ON awfulhak> set device /dev/cuaa1
1197 ppp ON awfulhak> set speed 38400
1198 ppp ON awfulhak> term
1199 deflink: Entering terminal mode on /dev/cuaa1
1210 ppp ON awfulhak> quit
1214 .Pa /usr/local/bin/ppplogin
1215 file with the following contents:
1216 .Bd -literal -offset indent
1218 exec /usr/sbin/ppp -direct incoming
1225 work with stdin and stdout.
1228 to connect to a configured diagnostic port, in the same manner as with
1234 section must be set up in
1235 .Pa /etc/ppp/ppp.conf .
1239 section contains the
1241 command as appropriate.
1243 Prepare an account for the incoming user.
1245 ppp:xxxx:66:66:PPP Login User:/home/ppp:/usr/local/bin/ppplogin
1248 Refer to the manual entries for
1254 Support for IPCP Domain Name Server and NetBIOS Name Server negotiation
1255 can be enabled using the
1260 Refer to their descriptions below.
1262 .Sh RECEIVING INCOMING PPP CONNECTIONS (Method 2)
1263 This method differs in that we use
1265 to authenticate the connection rather than
1269 Configure your default section in
1271 with automatic ppp recognition by specifying the
1276 :pp=/usr/local/bin/ppplogin:\\
1280 Configure your serial device(s), enable a
1283 .Pa /usr/local/bin/ppplogin
1284 as in the first three steps for method 1 above.
1292 .Pa /etc/ppp/ppp.conf
1295 label (or whatever label
1300 .Pa /etc/ppp/ppp.secret
1301 for each incoming user:
1310 detects a ppp connection (by recognising the HDLC frame headers), it runs
1311 .Dq /usr/local/bin/ppplogin .
1315 that either PAP or CHAP are enabled as above.
1316 If they are not, you are
1317 allowing anybody to establish a ppp session with your machine
1319 a password, opening yourself up to all sorts of potential attacks.
1320 .Sh AUTHENTICATING INCOMING CONNECTIONS
1321 Normally, the receiver of a connection requires that the peer
1322 authenticates itself.
1323 This may be done using
1325 but alternatively, you can use PAP or CHAP.
1326 CHAP is the more secure of the two, but some clients may not support it.
1327 Once you decide which you wish to use, add the command
1331 to the relevant section of
1334 You must then configure the
1335 .Pa /etc/ppp/ppp.secret
1337 This file contains one line per possible client, each line
1338 containing up to five fields:
1341 .Ar hisaddr Op Ar label Op Ar callback-number
1348 specify the client username and password.
1353 and PAP is being used,
1355 will look up the password database
1357 when authenticating.
1358 If the client does not offer a suitable response based on any
1359 .Ar name Ns No / Ns Ar key
1362 authentication fails.
1364 If authentication is successful,
1367 is used when negotiating IP numbers.
1370 command for details.
1372 If authentication is successful and
1374 is specified, the current system label is changed to match the given
1376 This will change the subsequent parsing of the
1382 If authentication is successful and
1388 the client will be called back on the given number.
1389 If CBCP is being used,
1391 may also contain a list of numbers or a
1396 The value will be used in
1398 subsequent CBCP phase.
1399 .Sh PPP OVER TCP and UDP (a.k.a Tunnelling)
1402 over a serial link, it is possible to
1403 use a TCP connection instead by specifying the host, port and protocol as the
1406 .Dl set device ui-gate:6669/tcp
1408 Instead of opening a serial device,
1410 will open a TCP connection to the given machine on the given
1412 It should be noted however that
1414 doesn't use the telnet protocol and will be unable to negotiate
1415 with a telnet server.
1416 You should set up a port for receiving this
1418 connection on the receiving machine (ui-gate).
1419 This is done by first updating
1421 to name the service:
1423 .Dl ppp-in 6669/tcp # Incoming PPP connections over TCP
1429 how to deal with incoming connections on that port:
1431 .Dl ppp-in stream tcp nowait root /usr/sbin/ppp ppp -direct ppp-in
1433 Don't forget to send a
1437 after you've updated
1438 .Pa /etc/inetd.conf .
1439 Here, we use a label named
1442 .Pa /etc/ppp/ppp.conf
1443 on ui-gate (the receiver) should contain the following:
1444 .Bd -literal -offset indent
1447 set ifaddr 10.0.4.1 10.0.4.2
1451 .Pa /etc/ppp/ppp.linkup
1453 .Bd -literal -offset indent
1455 add 10.0.1.0/24 HISADDR
1458 It is necessary to put the
1462 to ensure that the route is only added after
1464 has negotiated and assigned addresses to its interface.
1466 You may also want to enable PAP or CHAP for security.
1467 To enable PAP, add the following line:
1468 .Bd -literal -offset indent
1472 You'll also need to create the following entry in
1473 .Pa /etc/ppp/ppp.secret :
1474 .Bd -literal -offset indent
1475 MyAuthName MyAuthPasswd
1482 the password is looked up in the
1487 .Pa /etc/ppp/ppp.conf
1488 on awfulhak (the initiator) should contain the following:
1489 .Bd -literal -offset indent
1492 set device ui-gate:ppp-in/tcp
1495 set log Phase Chat Connect hdlc LCP IPCP IPV6CP CCP tun
1496 set ifaddr 10.0.4.2 10.0.4.1
1499 with the route setup in
1500 .Pa /etc/ppp/ppp.linkup :
1501 .Bd -literal -offset indent
1503 add 10.0.2.0/24 HISADDR
1506 Again, if you're enabling PAP, you'll also need this in the
1507 .Pa /etc/ppp/ppp.conf
1509 .Bd -literal -offset indent
1510 set authname MyAuthName
1511 set authkey MyAuthKey
1514 We're assigning the address of 10.0.4.1 to ui-gate, and the address
1515 10.0.4.2 to awfulhak.
1516 To open the connection, just type
1518 .Dl awfulhak # ppp -background ui-gate
1520 The result will be an additional "route" on awfulhak to the
1521 10.0.2.0/24 network via the TCP connection, and an additional
1522 "route" on ui-gate to the 10.0.1.0/24 network.
1523 The networks are effectively bridged - the underlying TCP
1524 connection may be across a public network (such as the
1527 traffic is conceptually encapsulated
1528 (although not packet by packet) inside the TCP stream between
1531 The major disadvantage of this mechanism is that there are two
1532 "guaranteed delivery" mechanisms in place - the underlying TCP
1533 stream and whatever protocol is used over the
1535 link - probably TCP again.
1536 If packets are lost, both levels will
1537 get in each others way trying to negotiate sending of the missing
1540 To avoid this overhead, it is also possible to do all this using
1541 UDP instead of TCP as the transport by simply changing the protocol
1542 from "tcp" to "udp".
1543 When using UDP as a transport,
1545 will operate in synchronous mode.
1546 This is another gain as the incoming
1547 data does not have to be rearranged into packets.
1549 Care should be taken when adding a default route through a tunneled
1551 It is quite common for the default route
1553 .Pa /etc/ppp/ppp.linkup )
1554 to end up routing the link's TCP connection through the tunnel,
1555 effectively garrotting the connection.
1556 To avoid this, make sure you add a static route for the benefit of
1558 .Bd -literal -offset indent
1561 set device ui-gate:ppp-in/tcp
1568 is the IP number that your route to
1572 When routing your connection across a public network such as the Internet,
1573 it is preferable to encrypt the data.
1574 This can be done with the help of the MPPE protocol, although currently this
1575 means that you will not be able to also compress the traffic as MPPE is
1576 implemented as a compression layer (thank Microsoft for this).
1577 To enable MPPE encryption, add the following lines to
1578 .Pa /etc/ppp/ppp.conf
1580 .Bd -literal -offset indent
1582 disable deflate pred1
1586 ensuring that you've put the requisite entry in
1587 .Pa /etc/ppp/ppp.secret
1588 (MSCHAPv2 is challenge based, so
1592 MSCHAPv2 and MPPE are accepted by default, so the client end should work
1593 without any additional changes (although ensure you have
1598 .Sh NETWORK ADDRESS TRANSLATION (PACKET ALIASING)
1601 command line option enables network address translation (a.k.a. packet
1605 host to act as a masquerading gateway for other computers over
1606 a local area network.
1607 Outgoing IP packets are NAT'd so that they appear to come from the
1609 host, and incoming packets are de-NAT'd so that they are routed
1610 to the correct machine on the local area network.
1611 NAT allows computers on private, unregistered subnets to have Internet
1612 access, although they are invisible from the outside world.
1615 operation should first be verified with network address translation disabled.
1618 option should be switched on, and network applications (web browser,
1623 should be checked on the
1626 Finally, the same or similar applications should be checked on other
1627 computers in the LAN.
1628 If network applications work correctly on the
1630 host, but not on other machines in the LAN, then the masquerading
1631 software is working properly, but the host is either not forwarding
1632 or possibly receiving IP packets.
1633 Check that IP forwarding is enabled in
1635 and that other machines have designated the
1637 host as the gateway for the LAN.
1638 .Sh PACKET FILTERING
1639 This implementation supports packet filtering.
1640 There are four kinds of
1650 Here are the basics:
1653 A filter definition has the following syntax:
1662 .Ar src_addr Ns Op / Ns Ar width
1663 .Op Ar dst_addr Ns Op / Ns Ar width
1665 .Ar [ proto Op src Ar cmp port
1670 .Op timeout Ar secs ]
1682 is a numeric value between
1686 specifying the rule number.
1687 Rules are specified in numeric order according to
1698 in which case, if a given packet matches the rule, the associated action
1699 is taken immediately.
1701 can also be specified as
1703 to clear the action associated with that particular rule, or as a new
1704 rule number greater than the current rule.
1705 In this case, if a given
1706 packet matches the current rule, the packet will next be matched against
1707 the new rule number (rather than the next rule number).
1711 may optionally be followed with an exclamation mark
1715 to reverse the sense of the following match.
1717 .Op Ar src_addr Ns Op / Ns Ar width
1719 .Op Ar dst_addr Ns Op / Ns Ar width
1720 are the source and destination IP number specifications.
1723 is specified, it gives the number of relevant netmask bits,
1724 allowing the specification of an address range.
1730 may be given the values
1736 (refer to the description of the
1738 command for a description of these values).
1739 When these values are used,
1740 the filters will be updated any time the values change.
1741 This is similar to the behaviour of the
1746 may be any protocol from
1755 meaning less-than, equal and greater-than respectively.
1757 can be specified as a numeric port or by service name from
1765 flags are only allowed when
1769 and represent the TH_ACK, TH_SYN and TH_FIN or TH_RST TCP flags respectively.
1771 The timeout value adjusts the current idle timeout to at least
1774 If a timeout is given in the alive filter as well as in the in/out
1775 filter, the in/out value is used.
1776 If no timeout is given, the default timeout (set using
1778 and defaulting to 180 seconds) is used.
1782 Each filter can hold up to 40 rules, starting from rule 0.
1783 The entire rule set is not effective until rule 0 is defined,
1784 i.e., the default is to allow everything through.
1786 If no rule in a defined set of rules matches a packet, that packet will
1787 be discarded (blocked).
1788 If there are no rules in a given filter, the packet will be permitted.
1790 It's possible to filter based on the payload of UDP frames where those
1796 .Ar filter-decapsulation
1797 option below for further details.
1800 .Dq set filter Ar name No -1
1805 .Pa /usr/share/examples/ppp/ppp.conf.sample .
1806 .Sh SETTING THE IDLE TIMER
1807 To check/set the idle timer, use the
1812 .Bd -literal -offset indent
1813 ppp ON awfulhak> set timeout 600
1816 The timeout period is measured in seconds, the default value for which
1819 To disable the idle timer function, use the command
1820 .Bd -literal -offset indent
1821 ppp ON awfulhak> set timeout 0
1828 modes, the idle timeout is ignored.
1831 mode, when the idle timeout causes the
1836 program itself remains running.
1837 Another trigger packet will cause it to attempt to re-establish the link.
1838 .Sh PREDICTOR-1 and DEFLATE COMPRESSION
1840 supports both Predictor type 1 and deflate compression.
1843 will attempt to use (or be willing to accept) both compression protocols
1844 when the peer agrees
1846 The deflate protocol is preferred by
1852 commands if you wish to disable this functionality.
1854 It is possible to use a different compression algorithm in each direction
1855 by using only one of
1859 (assuming that the peer supports both algorithms).
1861 By default, when negotiating DEFLATE,
1863 will use a window size of 15.
1866 command if you wish to change this behaviour.
1868 A special algorithm called DEFLATE24 is also available, and is disabled
1869 and denied by default.
1870 This is exactly the same as DEFLATE except that
1871 it uses CCP ID 24 to negotiate.
1874 to successfully negotiate DEFLATE with
1877 .Sh CONTROLLING IP ADDRESS
1880 uses IPCP to negotiate IP addresses.
1881 Each side of the connection
1882 specifies the IP address that it's willing to use, and if the requested
1883 IP address is acceptable then
1885 returns an ACK to the requester.
1888 returns NAK to suggest that the peer use a different IP address.
1890 both sides of the connection agree to accept the received request (and
1891 send an ACK), IPCP is set to the open state and a network level connection
1893 To control this IPCP behaviour, this implementation has the
1895 command for defining the local and remote IP address:
1896 .Bd -ragged -offset indent
1897 .No set ifaddr Oo Ar src_addr Ns
1899 .Oo Ar dst_addr Ns Op / Ns Ar \&nn
1909 is the IP address that the local side is willing to use,
1911 is the IP address which the remote side should use and
1913 is the netmask that should be used.
1915 defaults to the current
1918 defaults to 0.0.0.0, and
1920 defaults to whatever mask is appropriate for
1922 It is only possible to make
1924 smaller than the default.
1925 The usual value is 255.255.255.255, as
1926 most kernels ignore the netmask of a POINTOPOINT interface.
1930 implementations require that the peer negotiates a specific IP
1933 If this is the case,
1935 may be used to specify this IP number.
1936 This will not affect the
1937 routing table unless the other side agrees with this proposed number.
1938 .Bd -literal -offset indent
1939 set ifaddr 192.244.177.38 192.244.177.2 255.255.255.255 0.0.0.0
1942 The above specification means:
1944 .Bl -bullet -compact
1946 I will first suggest that my IP address should be 0.0.0.0, but I
1947 will only accept an address of 192.244.177.38.
1949 I strongly insist that the peer uses 192.244.177.2 as his own
1950 address and won't permit the use of any IP address but 192.244.177.2.
1951 When the peer requests another IP address, I will always suggest that
1952 it uses 192.244.177.2.
1954 The routing table entry will have a netmask of 0xffffffff.
1957 This is all fine when each side has a pre-determined IP address, however
1958 it is often the case that one side is acting as a server which controls
1959 all IP addresses and the other side should go along with it.
1960 In order to allow more flexible behaviour, the
1962 command allows the user to specify IP addresses more loosely:
1964 .Dl set ifaddr 192.244.177.38/24 192.244.177.2/20
1966 A number followed by a slash
1968 represents the number of bits significant in the IP address.
1969 The above example means:
1971 .Bl -bullet -compact
1973 I'd like to use 192.244.177.38 as my address if it is possible, but I'll
1974 also accept any IP address between 192.244.177.0 and 192.244.177.255.
1976 I'd like to make him use 192.244.177.2 as his own address, but I'll also
1977 permit him to use any IP address between 192.244.176.0 and
1980 As you may have already noticed, 192.244.177.2 is equivalent to saying
1983 As an exception, 0 is equivalent to 0.0.0.0/0, meaning that I have no
1984 preferred IP address and will obey the remote peers selection.
1985 When using zero, no routing table entries will be made until a connection
1988 192.244.177.2/0 means that I'll accept/permit any IP address but I'll
1989 suggest that 192.244.177.2 be used first.
1992 When negotiating IPv6 addresses, no control is given to the user.
1993 IPV6CP negotiation is fully automatic.
1994 .Sh CONNECTING WITH YOUR INTERNET SERVICE PROVIDER
1995 The following steps should be taken when connecting to your ISP:
1998 Describe your providers phone number(s) in the dial script using the
2001 This command allows you to set multiple phone numbers for
2002 dialing and redialing separated by either a pipe
2006 .Bd -ragged -offset indent
2007 .No set phone Ar telno Ns Xo
2008 .Oo \&| Ns Ar backupnumber
2009 .Oc Ns ... Ns Oo : Ns Ar nextnumber
2014 Numbers after the first in a pipe-separated list are only used if the
2015 previous number was used in a failed dial or login script.
2017 separated by a colon are used sequentially, irrespective of what happened
2018 as a result of using the previous number.
2020 .Bd -literal -offset indent
2021 set phone "1234567|2345678:3456789|4567890"
2024 Here, the 1234567 number is attempted.
2025 If the dial or login script fails,
2026 the 2345678 number is used next time, but *only* if the dial or login script
2028 On the dial after this, the 3456789 number is used.
2030 number is only used if the dial or login script using the 3456789 fails.
2031 If the login script of the 2345678 number fails, the next number is still the
2033 As many pipes and colons can be used as are necessary
2034 (although a given site would usually prefer to use either the pipe or the
2035 colon, but not both).
2036 The next number redial timeout is used between all numbers.
2037 When the end of the list is reached, the normal redial period is
2038 used before starting at the beginning again.
2039 The selected phone number is substituted for the \\\\T string in the
2041 command (see below).
2043 Set up your redial requirements using
2045 For example, if you have a bad telephone line or your provider is
2046 usually engaged (not so common these days), you may want to specify
2048 .Bd -literal -offset indent
2052 This says that up to 4 phone calls should be attempted with a pause of 10
2053 seconds before dialing the first number again.
2055 Describe your login procedure using the
2062 command is used to talk to your modem and establish a link with your
2064 .Bd -literal -offset indent
2065 set dial "ABORT BUSY ABORT NO\\\\sCARRIER TIMEOUT 4 \\"\\" \e
2066 ATZ OK-ATZ-OK ATDT\\\\T TIMEOUT 60 CONNECT"
2069 This modem "chat" string means:
2072 Abort if the string "BUSY" or "NO CARRIER" are received.
2074 Set the timeout to 4 seconds.
2081 If that's not received within the 4 second timeout, send ATZ
2084 Send ATDTxxxxxxx where xxxxxxx is the next number in the phone list from
2087 Set the timeout to 60.
2089 Wait for the CONNECT string.
2092 Once the connection is established, the login script is executed.
2093 This script is written in the same style as the dial script, but care should
2094 be taken to avoid having your password logged:
2095 .Bd -literal -offset indent
2096 set authkey MySecret
2097 set login "TIMEOUT 15 login:-\\\\r-login: awfulhak \e
2098 word: \\\\P ocol: PPP HELLO"
2101 This login "chat" string means:
2104 Set the timeout to 15 seconds.
2107 If it's not received, send a carriage return and expect
2112 Expect "word:" (the tail end of a "Password:" prompt).
2114 Send whatever our current
2118 Expect "ocol:" (the tail end of a "Protocol:" prompt).
2127 command is logged specially.
2132 logging is enabled, the actual password is not logged;
2136 Login scripts vary greatly between ISPs.
2137 If you're setting one up for the first time,
2138 .Em ENABLE CHAT LOGGING
2139 so that you can see if your script is behaving as you expect.
2145 to specify your serial line and speed, for example:
2146 .Bd -literal -offset indent
2147 set device /dev/cuaa0
2151 Cuaa0 is the first serial port on
2158 A speed of 115200 should be specified
2159 if you have a modem capable of bit rates of 28800 or more.
2160 In general, the serial speed should be about four times the modem speed.
2164 command to {define} the IP address.
2167 If you know what IP address your provider uses, then use it as the remote
2168 address (dst_addr), otherwise choose something like 10.0.0.2/0 (see below).
2170 If your provider has assigned a particular IP address to you, then use
2171 it as your address (src_addr).
2173 If your provider assigns your address dynamically, choose a suitably
2174 unobtrusive and unspecific IP number as your address.
2175 10.0.0.1/0 would be appropriate.
2176 The bit after the / specifies how many bits of the
2177 address you consider to be important, so if you wanted to insist on
2178 something in the class C network 1.2.3.0, you could specify 1.2.3.1/24.
2180 If you find that your ISP accepts the first IP number that you suggest,
2181 specify third and forth arguments of
2183 This will force your ISP to assign a number.
2184 (The third argument will
2185 be ignored as it is less restrictive than the default mask for your
2189 An example for a connection where you don't know your IP number or your
2190 ISPs IP number would be:
2191 .Bd -literal -offset indent
2192 set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0
2196 In most cases, your ISP will also be your default router.
2197 If this is the case, add the line
2198 .Bd -literal -offset indent
2203 .Pa /etc/ppp/ppp.conf
2205 .Pa /etc/ppp/ppp.linkup
2206 for setups that don't use
2212 to add a default route to whatever the peer address is
2213 (10.0.0.2 in this example).
2216 meaning that should the value of
2218 change, the route will be updated accordingly.
2220 If your provider requests that you use PAP/CHAP authentication methods, add
2221 the next lines to your
2222 .Pa /etc/ppp/ppp.conf
2224 .Bd -literal -offset indent
2226 set authkey MyPassword
2229 Both are accepted by default, so
2231 will provide whatever your ISP requires.
2233 It should be noted that a login script is rarely (if ever) required
2234 when PAP or CHAP are in use.
2236 Ask your ISP to authenticate your nameserver address(es) with the line
2237 .Bd -literal -offset indent
2243 do this if you are running a local DNS unless you also either use
2248 .Pa /etc/ppp/ppp.linkdown ,
2251 will simply circumvent its use by entering some nameserver lines in
2252 .Pa /etc/resolv.conf .
2256 .Pa /usr/share/examples/ppp/ppp.conf.sample
2258 .Pa /usr/share/examples/ppp/ppp.linkup.sample
2259 for some real examples.
2260 The pmdemand label should be appropriate for most ISPs.
2261 .Sh LOGGING FACILITY
2263 is able to generate the following log info either via
2265 or directly to the screen:
2267 .Bl -tag -width XXXXXXXXX -offset XXX -compact
2269 Enable all logging facilities.
2270 This generates a lot of log.
2271 The most common use of 'all' is as a basis, where you remove some facilities
2272 after enabling 'all' ('debug' and 'timer' are usually best disabled.)
2274 Dump async level packet in hex.
2276 Generate CBCP (CallBack Control Protocol) logs.
2278 Generate a CCP packet trace.
2286 chat script trace logs.
2288 Log commands executed either from the command line or any of the configuration
2291 Log Chat lines containing the string "CONNECT".
2293 Log debug information.
2295 Log DNS QUERY packets.
2297 Log packets permitted by the dial filter and denied by any filter.
2299 Dump HDLC packet in hex.
2301 Log all function calls specifically made as user id 0.
2303 Generate an IPCP packet trace.
2305 Generate an LCP packet trace.
2307 Generate LQR reports.
2309 Phase transition log output.
2311 Dump physical level packet in hex.
2313 Dump sync level packet in hex.
2315 Dump all TCP/IP packets.
2317 Log timer manipulation.
2319 Include the tun device on each log line.
2321 Output to the terminal device.
2322 If there is currently no terminal,
2323 output is sent to the log file using syslogs
2326 Output to both the terminal device
2327 and the log file using syslogs
2330 Output to the log file using
2336 command allows you to set the logging output level.
2337 Multiple levels can be specified on a single command line.
2338 The default is equivalent to
2341 It is also possible to log directly to the screen.
2342 The syntax is the same except that the word
2344 should immediately follow
2348 (i.e., only the un-maskable warning, error and alert output).
2350 If The first argument to
2351 .Dq set log Op local
2356 character, the current log levels are
2357 not cleared, for example:
2358 .Bd -literal -offset indent
2359 PPP ON awfulhak> set log phase
2360 PPP ON awfulhak> show log
2361 Log: Phase Warning Error Alert
2362 Local: Warning Error Alert
2363 PPP ON awfulhak> set log +tcp/ip -warning
2364 PPP ON awfulhak> set log local +command
2365 PPP ON awfulhak> show log
2366 Log: Phase TCP/IP Warning Error Alert
2367 Local: Command Warning Error Alert
2370 Log messages of level Warning, Error and Alert are not controllable
2372 .Dq set log Op local .
2376 level is special in that it will not be logged if it can be displayed
2380 deals with the following signals:
2381 .Bl -tag -width "USR2"
2383 Receipt of this signal causes the termination of the current connection
2387 to exit unless it is in
2392 .It HUP, TERM & QUIT
2399 to re-open any existing server socket, dropping all existing diagnostic
2401 Sockets that couldn't previously be opened will be retried.
2405 to close any existing server socket, dropping all existing diagnostic
2408 can still be used to re-open the socket.
2411 If you wish to use more than one physical link to connect to a
2413 peer, that peer must also understand the
2416 Refer to RFC 1990 for specification details.
2418 The peer is identified using a combination of his
2419 .Dq endpoint discriminator
2421 .Dq authentication id .
2422 Either or both of these may be specified.
2423 It is recommended that
2424 at least one is specified, otherwise there is no way of ensuring that
2425 all links are actually connected to the same peer program, and some
2426 confusing lock-ups may result.
2427 Locally, these identification variables are specified using the
2436 must be agreed in advance with the peer.
2438 Multi-link capabilities are enabled using the
2440 command (set maximum reconstructed receive unit).
2441 Once multi-link is enabled,
2443 will attempt to negotiate a multi-link connection with the peer.
2445 By default, only one
2450 To create more links, the
2453 This command will clone existing links, where all
2454 characteristics are the same except:
2457 The new link has its own name as specified on the
2464 Its mode may subsequently be changed using the
2468 The new link is in a
2473 A summary of all available links can be seen using the
2477 Once a new link has been created, command usage varies.
2478 All link specific commands must be prefixed with the
2480 command, specifying on which link the command is to be applied.
2481 When only a single link is available,
2483 is smart enough not to require the
2487 Some commands can still be used without specifying a link - resulting
2488 in an operation at the
2491 For example, once two or more links are available, the command
2493 will show CCP configuration and statistics at the multi-link level, and
2494 .Dq link deflink show ccp
2495 will show the same information at the
2499 Armed with this information, the following configuration might be used:
2500 .Bd -literal -offset indent
2504 set device /dev/cuaa0 /dev/cuaa1 /dev/cuaa2
2505 set phone "123456789"
2506 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \\"\\" ATZ \e
2507 OK-AT-OK \\\\dATDT\\\\T TIMEOUT 45 CONNECT"
2509 set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0
2511 set authkey ppppassword
2514 clone 1,2,3 # Create 3 new links - duplicates of the default
2515 link deflink remove # Delete the default link (called ``deflink'')
2518 Note how all cloning is done at the end of the configuration.
2519 Usually, the link will be configured first, then cloned.
2520 If you wish all links
2521 to be up all the time, you can add the following line to the end of your
2523 .Bd -literal -offset indent
2524 link 1,2,3 set mode ddial
2527 If you want the links to dial on demand, this command could be used:
2528 .Bd -literal -offset indent
2529 link * set mode auto
2532 Links may be tied to specific names by removing the
2534 line above, and specifying the following after the
2537 .Bd -literal -offset indent
2538 link 1 set device /dev/cuaa0
2539 link 2 set device /dev/cuaa1
2540 link 3 set device /dev/cuaa2
2545 command to see which commands require context (using the
2547 command), which have optional
2548 context and which should not have any context.
2554 mode with the peer, it creates a local domain socket in the
2557 This socket is used to pass link information (including
2558 the actual link file descriptor) between different
2563 ability to be run from a
2569 capability), without needing to have initial control of the serial
2573 negotiates multi-link mode, it will pass its open link to any
2574 already running process.
2575 If there is no already running process,
2577 will act as the master, creating the socket and listening for new
2579 .Sh PPP COMMAND LIST
2580 This section lists the available commands and their effect.
2581 They are usable either from an interactive
2583 session, from a configuration file or from a
2589 .It accept|deny|enable|disable Ar option....
2590 These directives tell
2592 how to negotiate the initial connection with the peer.
2595 has a default of either accept or deny and enable or disable.
2597 means that the option will be ACK'd if the peer asks for it.
2599 means that the option will be NAK'd if the peer asks for it.
2601 means that the option will be requested by us.
2603 means that the option will not be requested by us.
2606 may be one of the following:
2609 Default: Enabled and Accepted.
2610 ACFComp stands for Address and Control Field Compression.
2611 Non LCP packets will usually have an address
2612 field of 0xff (the All-Stations address) and a control field of
2613 0x03 (the Unnumbered Information command).
2615 negotiated, these two bytes are simply not sent, thus minimising
2622 Default: Disabled and Accepted.
2623 CHAP stands for Challenge Handshake Authentication Protocol.
2624 Only one of CHAP and PAP (below) may be negotiated.
2625 With CHAP, the authenticator sends a "challenge" message to its peer.
2626 The peer uses a one-way hash function to encrypt the
2627 challenge and sends the result back.
2628 The authenticator does the same, and compares the results.
2629 The advantage of this mechanism is that no
2630 passwords are sent across the connection.
2631 A challenge is made when the connection is first made.
2632 Subsequent challenges may occur.
2633 If you want to have your peer authenticate itself, you must
2636 .Pa /etc/ppp/ppp.conf ,
2637 and have an entry in
2638 .Pa /etc/ppp/ppp.secret
2641 When using CHAP as the client, you need only specify
2646 .Pa /etc/ppp/ppp.conf .
2647 CHAP is accepted by default.
2650 implementations use "MS-CHAP" rather than MD5 when encrypting the
2652 MS-CHAP is a combination of MD4 and DES.
2655 was built on a machine with DES libraries available, it will respond
2656 to MS-CHAP authentication requests, but will never request them.
2658 Default: Enabled and Accepted.
2659 This option decides if deflate
2660 compression will be used by the Compression Control Protocol (CCP).
2661 This is the same algorithm as used by the
2664 Note: There is a problem negotiating
2670 implementation available under many operating systems.
2672 (version 2.3.1) incorrectly attempts to negotiate
2674 compression using type
2676 as the CCP configuration type rather than type
2682 is actually specified as
2683 .Dq PPP Magna-link Variable Resource Compression
2687 is capable of negotiating with
2694 .Ar accept Ns No ed .
2696 Default: Disabled and Denied.
2697 This is a variance of the
2699 option, allowing negotiation with the
2704 section above for details.
2705 It is disabled by default as it violates
2708 Default: Disabled and Denied.
2709 This option allows DNS negotiation.
2714 will request that the peer confirms the entries in
2715 .Pa /etc/resolv.conf .
2716 If the peer NAKs our request (suggesting new IP numbers),
2717 .Pa /etc/resolv.conf
2718 is updated and another request is sent to confirm the new entries.
2721 .Dq accept Ns No ed,
2723 will answer any DNS queries requested by the peer rather than rejecting
2725 The answer is taken from
2726 .Pa /etc/resolv.conf
2729 command is used as an override.
2731 Default: Enabled and Accepted.
2732 This option allows control over whether we
2733 negotiate an endpoint discriminator.
2734 We only send our discriminator if
2739 We reject the peers discriminator if
2743 Default: Disabled and Accepted.
2744 The use of this authentication protocol
2745 is discouraged as it partially violates the authentication protocol by
2746 implementing two different mechanisms (LANMan & NT) under the guise of
2747 a single CHAP type (0x80).
2749 uses a simple DES encryption mechanism and is the least secure of the
2750 CHAP alternatives (although is still more secure than PAP).
2754 description below for more details.
2756 Default: Disabled and Accepted.
2757 This option decides if Link Quality Requests will be sent or accepted.
2758 LQR is a protocol that allows
2760 to determine that the link is down without relying on the modems
2762 When LQR is enabled,
2768 below) as part of the LCP request.
2769 If the peer agrees, both sides will
2770 exchange LQR packets at the agreed frequency, allowing detailed link
2771 quality monitoring by enabling LQM logging.
2772 If the peer doesn't agree,
2774 will send ECHO LQR requests instead.
2775 These packets pass no information of interest, but they
2777 be replied to by the peer.
2779 Whether using LQR or ECHO LQR,
2781 will abruptly drop the connection if 5 unacknowledged packets have been
2782 sent rather than sending a 6th.
2783 A message is logged at the
2785 level, and any appropriate
2787 values are honoured as if the peer were responsible for dropping the
2790 Default: Enabled and Accepted.
2791 This is Microsoft Point to Point Encryption scheme.
2792 MPPE key size can be
2793 40-, 56- and 128-bits.
2798 Default: Disabled and Accepted.
2799 It is very similar to standard CHAP (type 0x05)
2800 except that it issues challenges of a fixed 16 bytes in length and uses a
2801 combination of MD4, SHA-1 and DES to encrypt the challenge rather than using the
2802 standard MD5 mechanism.
2804 Default: Disabled and Accepted.
2805 The use of this authentication protocol
2806 is discouraged as it partially violates the authentication protocol by
2807 implementing two different mechanisms (LANMan & NT) under the guise of
2808 a single CHAP type (0x80).
2809 It is very similar to standard CHAP (type 0x05)
2810 except that it issues challenges of a fixed 8 bytes in length and uses a
2811 combination of MD4 and DES to encrypt the challenge rather than using the
2812 standard MD5 mechanism.
2813 CHAP type 0x80 for LANMan is also supported - see
2821 use CHAP type 0x80, when acting as authenticator with both
2822 .Dq enable Ns No d ,
2824 will rechallenge the peer up to three times if it responds using the wrong
2825 one of the two protocols.
2826 This gives the peer a chance to attempt using both protocols.
2830 acts as the authenticatee with both protocols
2831 .Dq accept Ns No ed ,
2832 the protocols are used alternately in response to challenges.
2834 Note: If only LANMan is enabled,
2836 (version 2.3.5) misbehaves when acting as authenticatee.
2838 the NT and the LANMan answers, but also suggests that only the NT answer
2841 Default: Disabled and Accepted.
2842 PAP stands for Password Authentication Protocol.
2843 Only one of PAP and CHAP (above) may be negotiated.
2844 With PAP, the ID and Password are sent repeatedly to the peer until
2845 authentication is acknowledged or the connection is terminated.
2846 This is a rather poor security mechanism.
2847 It is only performed when the connection is first established.
2848 If you want to have your peer authenticate itself, you must
2851 .Pa /etc/ppp/ppp.conf ,
2852 and have an entry in
2853 .Pa /etc/ppp/ppp.secret
2854 for the peer (although see the
2860 When using PAP as the client, you need only specify
2865 .Pa /etc/ppp/ppp.conf .
2866 PAP is accepted by default.
2868 Default: Enabled and Accepted.
2869 This option decides if Predictor 1
2870 compression will be used by the Compression Control Protocol (CCP).
2872 Default: Enabled and Accepted.
2873 This option is used to negotiate
2874 PFC (Protocol Field Compression), a mechanism where the protocol
2875 field number is reduced to one octet rather than two.
2877 Default: Enabled and Accepted.
2878 This option determines if
2880 will request and accept requests for short
2882 sequence numbers when negotiating multi-link mode.
2883 This is only applicable if our MRRU is set (thus enabling multi-link).
2885 Default: Enabled and Accepted.
2886 This option determines if Van Jacobson header compression will be used.
2889 The following options are not actually negotiated with the peer.
2890 Therefore, accepting or denying them makes no sense.
2892 .It filter-decapsulation
2894 When this option is enabled,
2896 will examine UDP frames to see if they actually contain a
2898 frame as their payload.
2899 If this is the case, all filters will operate on the payload rather
2900 than the actual packet.
2902 This is useful if you want to send PPPoUDP traffic over a
2904 link, but want that link to do smart things with the real data rather than
2907 The UDP frame payload must not be compressed in any way, otherwise
2909 will not be able to interpret it.
2910 It's therefore recommended that you
2911 .Ic disable vj pred1 deflate
2913 .Ic deny vj pred1 deflate
2914 in the configuration for the
2916 invocation with the udp link.
2921 exchanges low-level LCP, CCP and IPCP configuration traffic, the
2923 field of any replies is expected to be the same as that of the request.
2926 drops any reply packets that do not contain the expected identifier
2927 field, reporting the fact at the respective log level.
2932 will ignore the identifier field.
2937 This option simply tells
2939 to add new interface addresses to the interface rather than replacing them.
2940 The option can only be enabled if network address translation is enabled
2941 .Pq Dq nat enable yes .
2943 With this option enabled,
2945 will pass traffic for old interface addresses through the NAT
2946 ifdef({LOCALNAT},{engine,},{engine
2948 .Xr libalias 3 ) ,})
2949 resulting in the ability (in
2951 mode) to properly connect the process that caused the PPP link to
2952 come up in the first place.
2962 to attempt to negotiate IP control protocol capabilities and if
2963 successful to exchange IP datagrams with the peer.
2968 to attempt to negotiate IPv6 control protocol capabilities and if
2969 successful to exchange IPv6 datagrams with the peer.
2974 runs as a Multi-link server, a different
2976 instance initially receives each connection.
2977 After determining that
2978 the link belongs to an already existing bundle (controlled by another
2982 will transfer the link to that process.
2984 If the link is a tty device or if this option is enabled,
2986 will not exit, but will change its process name to
2988 and wait for the controlling
2990 to finish with the link and deliver a signal back to the idle process.
2991 This prevents the confusion that results from
2993 parent considering the link resource available again.
2995 For tty devices that have entries in
2997 this is necessary to prevent another
2999 from being started, and for program links such as
3003 from exiting due to the death of its child.
3006 cannot determine its parents requirements (except for the tty case), this
3007 option must be enabled manually depending on the circumstances.
3014 will automatically loop back packets being sent
3015 out with a destination address equal to that of the
3020 will send the packet, probably resulting in an ICMP redirect from
3022 It is convenient to have this option enabled when
3023 the interface is also the default route as it avoids the necessity
3024 of a loopback route.
3027 Enabling this option will tell the PAP authentication
3028 code to use the password database (see
3030 to authenticate the caller if they cannot be found in the
3031 .Pa /etc/ppp/ppp.secret
3033 .Pa /etc/ppp/ppp.secret
3034 is always checked first.
3035 If you wish to use passwords from
3037 but also to specify an IP number or label for a given client, use
3039 as the client password in
3040 .Pa /etc/ppp/ppp.secret .
3043 Enabling this option will tell
3045 to proxy ARP for the peer.
3048 will make an entry in the ARP table using
3052 address of the local network in which
3055 This allows other machines connected to the LAN to talk to
3056 the peer as if the peer itself was connected to the LAN.
3057 The proxy entry cannot be made unless
3059 is an address from a LAN.
3062 Enabling this will tell
3064 to add proxy arp entries for every IP address in all class C or
3065 smaller subnets routed via the tun interface.
3067 Proxy arp entries are only made for sticky routes that are added
3071 No proxy arp entries are made for the interface address itself
3079 command is used with the
3085 values, entries are stored in the
3088 Each time these variables change, this list is re-applied to the routing table.
3090 Disabling this option will prevent the re-application of sticky routes,
3093 list will still be maintained.
3100 to adjust TCP SYN packets so that the maximum receive segment
3101 size is not greater than the amount allowed by the interface MTU.
3106 to gather throughput statistics.
3107 Input and output is sampled over
3108 a rolling 5 second window, and current, best and total figures are retained.
3109 This data is output when the relevant
3111 layer shuts down, and is also available using the
3114 Throughput statistics are available at the
3121 Normally, when a user is authenticated using PAP or CHAP, and when
3125 mode, an entry is made in the utmp and wtmp files for that user.
3126 Disabling this option will tell
3128 not to make any utmp or wtmp entries.
3129 This is usually only necessary if
3130 you require the user to both login and authenticate themselves.
3135 .Ar dest Ns Op / Ns Ar nn
3140 is the destination IP address.
3141 The netmask is specified either as a number of bits with
3143 or as an IP number using
3148 with no mask refers to the default route.
3149 It is also possible to use the literal name
3154 is the next hop gateway to get to the given
3159 command for further details.
3161 It is possible to use the symbolic names
3167 as the destination, and
3174 is replaced with the interface IP address,
3176 is replaced with the interface IP destination (peer) address,
3178 is replaced with the interface IPv6 address, and
3180 is replaced with the interface IPv6 destination address,
3187 then if the route already exists, it will be updated as with the
3191 for further details).
3193 Routes that contain the
3201 constants are considered
3203 They are stored in a list (use
3205 to see the list), and each time the value of one of these variables
3206 changes, the appropriate routing table entries are updated.
3207 This facility may be disabled using
3208 .Dq disable sroutes .
3209 .It allow Ar command Op Ar args
3210 This command controls access to
3212 and its configuration files.
3213 It is possible to allow user-level access,
3214 depending on the configuration file label and on the mode that
3217 For example, you may wish to configure
3227 User id 0 is immune to these commands.
3229 .It allow user Ns Xo
3231 .Ar logname Ns No ...
3233 By default, only user id 0 is allowed access to
3235 If this command is used, all of the listed users are allowed access to
3236 the section in which the
3241 section is always checked first (even though it is only ever automatically
3244 commands are cumulative in a given section, but users allowed in any given
3245 section override users allowed in the default section, so it's possible to
3246 allow users access to everything except a given label by specifying default
3249 section, and then specifying a new user list for that label.
3253 is specified, access is allowed to all users.
3254 .It allow mode Ns Xo
3258 By default, access using any
3261 If this command is used, it restricts the access
3263 allowed to load the label under which this command is specified.
3268 command overrides any previous settings, and the
3270 section is always checked first.
3282 When running in multi-link mode, a section can be loaded if it allows
3284 of the currently existing line modes.
3287 .It nat Ar command Op Ar args
3288 This command allows the control of the network address translation (also
3289 known as masquerading or IP aliasing) facilities that are built into
3291 NAT is done on the external interface only, and is unlikely to make sense
3296 If nat is enabled on your system (it may be omitted at compile time),
3297 the following commands are possible:
3299 .It nat enable yes|no
3300 This command either switches network address translation on or turns it off.
3303 command line flag is synonymous with
3304 .Dq nat enable yes .
3305 .It nat addr Op Ar addr_local addr_alias
3306 This command allows data for
3310 It is useful if you own a small number of real IP numbers that
3311 you wish to map to specific machines behind your gateway.
3312 .It nat deny_incoming yes|no
3313 If set to yes, this command will refuse all incoming packets where an
3314 aliasing link doesn't already exist.
3315 ifdef({LOCALNAT},{},{Refer to the
3316 .Sx CONCEPTUAL BACKGROUND
3319 for a description of what an
3324 It should be noted under what circumstances an aliasing link is
3325 ifdef({LOCALNAT},{created.},{created by
3327 It may be necessary to further protect your network from outside
3328 connections using the
3334 This command gives a summary of available nat commands.
3336 This option causes various NAT statistics and information to
3337 be logged to the file
3338 .Pa /var/log/alias.log .
3339 .It nat port Ar proto Ar targetIP Ns Xo
3340 .No : Ns Ar targetPort Ns
3342 .No - Ns Ar targetPort
3345 .No - Ns Ar aliasPort
3346 .Oc Oo Ar remoteIP : Ns
3349 .No - Ns Ar remotePort
3353 This command causes incoming
3367 A range of port numbers may be specified as shown above.
3368 The ranges must be of the same size.
3372 is specified, only data coming from that IP number is redirected.
3376 (indicating any source port)
3377 or a range of ports the same size as the other ranges.
3379 This option is useful if you wish to run things like Internet phone on
3380 machines behind your gateway, but is limited in that connections to only
3381 one interior machine per source machine and target port are possible.
3382 .It nat proto Ar proto localIP Oo
3383 .Ar publicIP Op Ar remoteIP
3387 to redirect packets of protocol type
3391 to the internal address
3396 is specified, only packets destined for that address are matched,
3397 otherwise the default alias address is used.
3401 is specified, only packets matching that source address are matched,
3403 This command is useful for redirecting tunnel endpoints to an internal machine,
3406 .Dl nat proto ipencap 10.0.0.1
3407 .It "nat proxy cmd" Ar arg Ns No ...
3410 to proxy certain connections, redirecting them to a given server.
3411 ifdef({LOCALNAT},{},{Refer to the description of
3412 .Fn PacketAliasProxyRule
3415 for details of the available commands.
3417 .It nat punch_fw Op Ar base count
3420 to punch holes in the firewall for FTP or IRC DCC connections.
3421 This is done dynamically by installing temporary firewall rules which
3422 allow a particular connection (and only that connection) to go through
3424 The rules are removed once the corresponding connection terminates.
3428 rules starting from rule number
3430 will be used for punching firewall holes.
3431 The range will be cleared when the
3435 If no arguments are given, firewall punching is disabled.
3436 .It nat same_ports yes|no
3437 When enabled, this command will tell the network address translation engine to
3438 attempt to avoid changing the port number on outgoing packets.
3440 if you want to support protocols such as RPC and LPD which require
3441 connections to come from a well known port.
3442 .It nat target Op Ar address
3443 Set the given target address or clear it if no address is given.
3444 The target address is used
3445 ifdef({LOCALNAT},{},{by libalias })dnl
3446 to specify how to NAT incoming packets by default.
3447 If a target address is not set or if
3449 is given, packets are not altered and are allowed to route to the internal
3452 The target address may be set to
3455 ifdef({LOCALNAT},{all packets will be redirected},
3456 {libalias will redirect all packets})
3457 to the interface address.
3458 .It nat use_sockets yes|no
3459 When enabled, this option tells the network address translation engine to
3460 create a socket so that it can guarantee a correct incoming ftp data or
3462 .It nat unregistered_only yes|no
3463 Only alter outgoing packets with an unregistered source address.
3464 According to RFC 1918, unregistered source addresses
3465 are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16.
3468 These commands are also discussed in the file
3470 which comes with the source distribution.
3477 is executed in the background with the following words replaced:
3478 .Bl -tag -width COMPILATIONDATE
3480 This is replaced with the local
3486 .It Li COMPILATIONDATE
3487 This is replaced with the date on which
3491 These are replaced with the primary and secondary nameserver IP numbers.
3492 If nameservers are negotiated by IPCP, the values of these macros will change.
3494 This is replaced with the local endpoint discriminator value.
3499 This is replaced with the peers IP number.
3501 This is replaced with the peers IPv6 number.
3503 This is replaced with the name of the interface that's in use.
3505 This is replaced with the number of IP bytes received since the connection
3508 This is replaced with the number of IP bytes sent since the connection
3511 This is replaced with the number of IP packets received since the connection
3514 This is replaced with the number of IP packets sent since the connection
3517 This is replaced with the number of IPv6 bytes received since the connection
3519 .It Li IPV6OCTETSOUT
3520 This is replaced with the number of IPv6 bytes sent since the connection
3522 .It Li IPV6PACKETSIN
3523 This is replaced with the number of IPv6 packets received since the connection
3525 .It Li IPV6PACKETSOUT
3526 This is replaced with the number of IPv6 packets sent since the connection
3529 This is replaced with the last label name used.
3530 A label may be specified on the
3532 command line, via the
3540 This is replaced with the IP number assigned to the local interface.
3542 This is replaced with the IPv6 number assigned to the local interface.
3544 This is replaced with the number of bytes received since the connection
3547 This is replaced with the number of bytes sent since the connection
3550 This is replaced with the number of packets received since the connection
3553 This is replaced with the number of packets sent since the connection
3556 This is replaced with the value of the peers endpoint discriminator.
3558 This is replaced with the current process id.
3560 This is replaced with the name of the diagnostic socket.
3562 This is replaced with the bundle uptime in HH:MM:SS format.
3564 This is replaced with the username that has been authenticated with PAP or
3566 Normally, this variable is assigned only in -direct mode.
3567 This value is available irrespective of whether utmp logging is enabled.
3569 This is replaced with the current version number of
3573 These substitutions are also done by the
3580 If you wish to pause
3582 while the command executes, use the
3585 .It clear physical|ipcp|ipv6 Op current|overall|peak...
3586 Clear the specified throughput values at either the
3594 is specified, context must be given (see the
3597 If no second argument is given, all values are cleared.
3598 .It clone Ar name Ns Xo
3599 .Op \&, Ns Ar name Ns
3602 Clone the specified link, creating one or more new links according to the
3605 This command must be used from the
3607 command below unless you've only got a single link (in which case that
3608 link becomes the default).
3609 Links may be removed using the
3613 The default link name is
3615 .It close Op lcp|ccp Ns Op !\&
3616 If no arguments are given, the relevant protocol layers will be brought
3617 down and the link will be closed.
3620 is specified, the LCP layer is brought down, but
3622 will not bring the link offline.
3623 It is subsequently possible to use
3626 to talk to the peer machine if, for example, something like
3631 is specified, only the relevant compression layer is closed.
3634 is used, the compression layer will remain in the closed state, otherwise
3635 it will re-enter the STOPPED state, waiting for the peer to initiate
3636 further CCP negotiation.
3637 In any event, this command does not disconnect the user from
3648 This command deletes the route with the given
3655 all non-direct entries in the routing table for the current interface,
3658 entries are deleted.
3663 the default route is deleted.
3671 will not complain if the route does not already exist.
3672 .It dial|call Op Ar label Ns Xo
3675 This command is the equivalent of
3679 and is provided for backwards compatibility.
3680 .It down Op Ar lcp|ccp
3681 Bring the relevant layer down ungracefully, as if the underlying layer
3682 had become unavailable.
3683 It's not considered polite to use this command on
3684 a Finite State Machine that's in the OPEN state.
3686 supplied, the entire link is closed (or if no context is given, all links
3692 layer is terminated but the device is not brought offline and the link
3696 is specified, only the relevant compression layer(s) are terminated.
3697 .It help|? Op Ar command
3698 Show a list of available commands.
3701 is specified, show the usage string for that command.
3702 .It ident Op Ar text Ns No ...
3703 Identify the link to the peer using
3707 is empty, link identification is disabled.
3708 It is possible to use any of the words described for the
3713 command for details of when
3715 identifies itself to the peer.
3716 .It iface Ar command Op args
3717 This command is used to control the interface used by
3720 may be one of the following:
3724 .Ar addr Ns Op / Ns Ar bits
3735 combination to the interface.
3736 Instead of specifying
3740 (with no space between it and
3742 If the given address already exists, the command fails unless the
3744 is used - in which case the previous interface address entry is overwritten
3745 with the new one, allowing a change of netmask or peer address.
3756 .Dq 255.255.255.255 .
3757 This address (the broadcast address) is the only duplicate peer address that
3760 .It iface clear Op INET | INET6
3761 If this command is used while
3763 is in the OPENED state or while in
3765 mode, all addresses except for the NCP negotiated address are deleted
3769 is not in the OPENED state and is not in
3771 mode, all interface addresses are deleted.
3773 If the INET or INET6 arguments are used, only addresses for that address
3776 .It iface delete Ns Xo
3781 This command deletes the given
3786 is used, no error is given if the address isn't currently assigned to
3787 the interface (and no deletion takes place).
3789 Shows the current state and current addresses for the interface.
3790 It is much the same as running
3791 .Dq ifconfig INTERFACE .
3792 .It iface help Op Ar sub-command
3793 This command, when invoked without
3795 will show a list of possible
3797 sub-commands and a brief synopsis for each.
3800 only the synopsis for the given sub-command is shown.
3804 .Ar name Ns Op , Ns Ar name Ns
3805 .No ... Ar command Op Ar args
3807 This command may prefix any other command if the user wishes to
3808 specify which link the command should affect.
3809 This is only applicable after multiple links have been created in Multi-link
3815 specifies the name of an existing link.
3818 is a comma separated list,
3820 is executed on each link.
3826 is executed on all links.
3827 .It load Op Ar label Ns Xo
3850 will not attempt to make an immediate connection.
3851 .It log Ar word Ns No ...
3852 Send the given word(s) to the log file with the prefix
3854 Word substitutions are done as explained under the
3857 .It open Op lcp|ccp|ipcp
3858 This is the opposite of the
3861 All closed links are immediately brought up apart from second and subsequent
3863 links - these will come up based on the
3865 command that has been used.
3869 argument is used while the LCP layer is already open, LCP will be
3871 This allows various LCP options to be changed, after which
3873 can be used to put them into effect.
3874 After renegotiating LCP,
3875 any agreed authentication will also take place.
3879 argument is used, the relevant compression layer is opened.
3880 Again, if it is already open, it will be renegotiated.
3884 argument is used, the link will be brought up as normal, but if
3885 IPCP is already open, it will be renegotiated and the network
3886 interface will be reconfigured.
3888 It is probably not good practice to re-open the PPP state machines
3889 like this as it's possible that the peer will not behave correctly.
3892 however useful as a way of forcing the CCP or VJ dictionaries to be reset.
3894 Specify the password required for access to the full
3897 This password is required when connecting to the diagnostic port (see the
3908 logging is active, instead, the literal string
3914 is executed from the controlling connection or from a command file,
3915 ppp will exit after closing all connections.
3916 Otherwise, if the user
3917 is connected to a diagnostic socket, the connection is simply dropped.
3923 will exit despite the source of the command after closing all existing
3926 This command removes the given link.
3927 It is only really useful in multi-link mode.
3928 A link must be in the
3930 state before it is removed.
3931 .It rename|mv Ar name
3932 This command renames the given link to
3936 is already used by another link.
3938 The default link name is
3945 may make the log file more readable.
3946 .It resolv Ar command
3947 This command controls
3954 starts up, it loads the contents of this file into memory and retains this
3955 image for future use.
3957 is one of the following:
3958 .Bl -tag -width readonly
3961 .Pa /etc/resolv.conf
3967 will still attempt to negotiate nameservers with the peer, making the results
3973 This is the opposite of the
3978 .Pa /etc/resolv.conf
3980 This may be necessary if for example a DHCP client overwrote
3981 .Pa /etc/resolv.conf .
3984 .Pa /etc/resolv.conf
3985 with the version originally read at startup or with the last
3988 This is sometimes a useful command to put in the
3989 .Pa /etc/ppp/ppp.linkdown
3993 .Pa /etc/resolv.conf
3995 This command will work even if the
3997 command has been used.
3998 It may be useful as a command in the
3999 .Pa /etc/ppp/ppp.linkup
4000 file if you wish to defer updating
4001 .Pa /etc/resolv.conf
4002 until after other commands have finished.
4007 .Pa /etc/resolv.conf
4012 successfully negotiates a DNS.
4013 This is the opposite of the
4018 This option is not (yet) implemented.
4022 to identify itself to the peer.
4023 The link must be in LCP state or higher.
4024 If no identity has been set (via the
4030 When an identity has been set,
4032 will automatically identify itself when it sends or receives a configure
4033 reject, when negotiation fails or when LCP reaches the opened state.
4035 Received identification packets are logged to the LCP log (see
4037 for details) and are never responded to.
4042 This option allows the setting of any of the following variables:
4044 .It set accmap Ar hex-value
4045 ACCMap stands for Asynchronous Control Character Map.
4047 negotiated with the peer, and defaults to a value of 00000000 in hex.
4048 This protocol is required to defeat hardware that depends on passing
4049 certain characters from end to end (such as XON/XOFF etc).
4051 For the XON/XOFF scenario, use
4052 .Dq set accmap 000a0000 .
4053 .It set Op auth Ns Xo
4056 This sets the authentication key (or password) used in client mode
4057 PAP or CHAP negotiation to the given value.
4058 It also specifies the
4059 password to be used in the dial or login scripts in place of the
4061 sequence, preventing the actual password from being logged.
4066 logging is in effect,
4070 for security reasons.
4072 If the first character of
4074 is an exclamation mark
4077 treats the remainder of the string as a program that must be executed
4089 it is treated as a single literal
4091 otherwise, ignoring the
4094 is parsed as a program to execute in the same was as the
4096 command above, substituting special names in the same manner.
4099 will feed the program three lines of input, each terminated by a newline
4103 The host name as sent in the CHAP challenge.
4105 The challenge string as sent in the CHAP challenge.
4111 Two lines of output are expected:
4116 to be sent with the CHAP response.
4120 which is encrypted with the challenge and request id, the answer being sent
4121 in the CHAP response packet.
4126 in this manner, it's expected that the host challenge is a series of ASCII
4127 digits or characters.
4128 An encryption device or Secure ID card is usually
4129 required to calculate the secret appropriate for the given challenge.
4130 .It set authname Ar id
4131 This sets the authentication id used in client mode PAP or CHAP negotiation.
4135 mode with CHAP enabled,
4137 is used in the initial authentication challenge and should normally be set to
4138 the local machine name.
4140 .Ar min-percent max-percent period
4142 These settings apply only in multi-link mode and default to zero, zero and
4148 mode link is available, only the first link is made active when
4150 first reads data from the tun device.
4153 link will be opened only when the current bundle throughput is at least
4155 percent of the total bundle bandwidth for
4158 When the current bundle throughput decreases to
4160 percent or less of the total bundle bandwidth for
4164 link will be brought down as long as it's not the last active link.
4166 Bundle throughput is measured as the maximum of inbound and outbound
4169 The default values cause
4171 links to simply come up one at a time.
4173 Certain devices cannot determine their physical bandwidth, so it
4174 is sometimes necessary to use the
4176 command (described below) to make
4179 .It set bandwidth Ar value
4180 This command sets the connection bandwidth in bits per second.
4182 must be greater than zero.
4183 It is currently only used by the
4186 .It set callback Ar option Ns No ...
4187 If no arguments are given, callback is disabled, otherwise,
4191 mode, will accept) one of the given
4192 .Ar option Ns No s .
4193 In client mode, if an
4197 will request a different
4199 until no options remain at which point
4201 will terminate negotiations (unless
4203 is one of the specified
4207 will accept any of the given protocols - but the client
4209 request one of them.
4210 If you wish callback to be optional, you must {include}
4216 are as follows (in this order of preference):
4219 The callee is expected to decide the callback number based on
4223 is the callee, the number should be specified as the fifth field of
4225 .Pa /etc/ppp/ppp.secret .
4227 Microsoft's callback control protocol is used.
4232 If you wish to negotiate
4234 in client mode but also wish to allow the server to request no callback at
4235 CBCP negotiation time, you must specify both
4239 as callback options.
4241 .Ar number Ns Op , Ns Ar number Ns
4244 The caller specifies the
4250 should be either a comma separated list of allowable numbers or a
4252 meaning any number is permitted.
4255 is the caller, only a single number should be specified.
4257 Note, this option is very unsafe when used with a
4259 as a malicious caller can tell
4261 to call any (possibly international) number without first authenticating
4264 If the peer does not wish to do callback at all,
4266 will accept the fact and continue without callback rather than terminating
4268 This is required (in addition to one or more other callback
4269 options) if you wish callback to be optional.
4273 .No *| Ns Ar number Ns Oo
4274 .No , Ns Ar number Ns ...\& Oc
4275 .Op Ar delay Op Ar retry
4277 If no arguments are given, CBCP (Microsoft's CallBack Control Protocol)
4278 is disabled - ie, configuring CBCP in the
4280 command will result in
4282 requesting no callback in the CBCP phase.
4285 attempts to use the given phone
4286 .Ar number Ns No (s).
4291 will insist that the client uses one of these numbers, unless
4293 is used in which case the client is expected to specify the number.
4297 will attempt to use one of the given numbers (whichever it finds to
4298 be agreeable with the peer), or if
4302 will expect the peer to specify the number.
4304 .No off| Ns Ar seconds Ns Op !\&
4308 checks for the existence of carrier depending on the type of device
4309 that has been opened:
4310 .Bl -tag -width XXX -offset XXX
4311 .It Terminal Devices
4312 Carrier is checked one second after the login script is complete.
4315 assumes that this is because the device doesn't support carrier (which
4318 NULL-modem cables), logs the fact and stops checking
4321 As ptys don't support the
4323 ioctl, the tty device will switch all
4324 carrier detection off when it detects that the device is a pty.
4325 .It PPPoE (netgraph) Devices
4326 Carrier is checked once per second for 5 seconds.
4327 If it's not set after
4328 the fifth second, the connection attempt is considered to have failed and
4329 the device is closed.
4330 Carrier is always required for PPPoE devices.
4333 All other device types don't support carrier.
4334 Setting a carrier value will
4335 result in a warning when the device is opened.
4337 Some modems take more than one second after connecting to assert the carrier
4339 If this delay isn't increased, this will result in
4341 inability to detect when the link is dropped, as
4343 assumes that the device isn't asserting carrier.
4347 command overrides the default carrier behaviour.
4349 specifies the maximum number of seconds that
4351 should wait after the dial script has finished before deciding if
4352 carrier is available or not.
4358 will not check for carrier on the device, otherwise
4360 will not proceed to the login script until either carrier is detected
4363 has elapsed, at which point
4365 assumes that the device will not set carrier.
4367 If no arguments are given, carrier settings will go back to their default
4372 is followed immediately by an exclamation mark
4378 If carrier is not detected after
4380 seconds, the link will be disconnected.
4381 .It set choked Op Ar timeout
4382 This sets the number of seconds that
4384 will keep a choked output queue before dropping all pending output packets.
4387 is less than or equal to zero or if
4389 isn't specified, it is set to the default value of
4392 A choked output queue occurs when
4394 has read a certain number of packets from the local network for transmission,
4395 but cannot send the data due to link failure (the peer is busy etc.).
4397 will not read packets indefinitely.
4398 Instead, it reads up to
4404 packets in multi-link mode), then stops reading the network interface
4407 seconds have passed or at least one packet has been sent.
4411 seconds pass, all pending output packets are dropped.
4412 .It set ctsrts|crtscts on|off
4413 This sets hardware flow control.
4414 Hardware flow control is
4417 .It set deflate Ar out-winsize Op Ar in-winsize
4418 This sets the DEFLATE algorithms default outgoing and incoming window
4424 must be values between
4432 will insist that this window size is used and will not accept any other
4433 values from the peer.
4434 .It set dns Op Ar primary Op Ar secondary
4435 This command specifies DNS overrides for the
4440 command description above for details.
4441 This command does not affect the IP numbers requested using
4443 .It set device|line Xo
4446 This sets the device(s) to which
4448 will talk to the given
4451 All serial device names are expected to begin with
4453 and are usually called
4460 it must either begin with an exclamation mark
4463 .No PPPoE: Ns Ar iface Ns Xo
4464 .Op \&: Ns Ar provider Ns
4468 enabled systems), or be of the format
4470 .Ar host : port Op /tcp|udp .
4473 If it begins with an exclamation mark, the rest of the device name is
4474 treated as a program name, and that program is executed when the device
4476 Standard input, output and error are fed back to
4478 and are read and written as if they were a regular device.
4481 .No PPPoE: Ns Ar iface Ns Xo
4482 .Op \&: Ns Ar provider Ns
4484 specification is given,
4486 will attempt to create a
4488 over Ethernet connection using the given
4496 will attempt to load it using
4498 If this fails, an external program must be used such as the
4500 program available under
4504 is passed as the service name in the PPPoE Discovery Initiation (PADI)
4506 If no provider is given, an empty value will be used.
4508 When a PPPoE connection is established,
4510 will place the name of the Access Concentrator in the environment variable
4517 for further details.
4520 .Ar host Ns No : Ns Ar port Ns Oo
4523 specification is given,
4525 will attempt to connect to the given
4533 suffix is not provided, the default is
4535 Refer to the section on
4536 .Em PPP OVER TCP and UDP
4537 above for further details.
4543 will attempt to open each one in turn until it succeeds or runs out of
4545 .It set dial Ar chat-script
4546 This specifies the chat script that will be used to dial the other
4553 and to the example configuration files for details of the chat script
4555 It is possible to specify some special
4557 in your chat script as follows:
4560 When used as the last character in a
4562 string, this indicates that a newline should not be appended.
4564 When the chat script encounters this sequence, it delays two seconds.
4566 When the chat script encounters this sequence, it delays for one quarter of
4569 This is replaced with a newline character.
4571 This is replaced with a carriage return character.
4573 This is replaced with a space character.
4575 This is replaced with a tab character.
4577 This is replaced by the current phone number (see
4581 This is replaced by the current
4587 This is replaced by the current
4594 Note that two parsers will examine these escape sequences, so in order to
4597 see the escape character, it is necessary to escape it from the
4598 .Sq command parser .
4599 This means that in practice you should use two escapes, for example:
4600 .Bd -literal -offset indent
4601 set dial "... ATDT\\\\T CONNECT"
4604 It is also possible to execute external commands from the chat script.
4605 To do this, the first character of the expect or send string is an
4608 If a literal exclamation mark is required, double it up to
4610 and it will be treated as a single literal
4612 When the command is executed, standard input and standard output are
4613 directed to the open device (see the
4615 command), and standard error is read by
4617 and substituted as the expect or send string.
4620 is running in interactive mode, file descriptor 3 is attached to
4623 For example (wrapped for readability):
4624 .Bd -literal -offset indent
4625 set login "TIMEOUT 5 \\"\\" \\"\\" login:--login: ppp \e
4626 word: ppp \\"!sh \\\\-c \\\\\\"echo \\\\-n label: >&2\\\\\\"\\" \e
4627 \\"!/bin/echo in\\" HELLO"
4630 would result in the following chat sequence (output using the
4631 .Sq set log local chat
4632 command before dialing):
4633 .Bd -literal -offset indent
4638 Chat: Expecting: login:--login:
4639 Chat: Wait for (5): login:
4641 Chat: Expecting: word:
4642 Chat: Wait for (5): word:
4644 Chat: Expecting: !sh \\-c "echo \\-n label: >&2"
4645 Chat: Exec: sh -c "echo -n label: >&2"
4646 Chat: Wait for (5): !sh \\-c "echo \\-n label: >&2" --> label:
4647 Chat: Exec: /bin/echo in
4649 Chat: Expecting: HELLO
4650 Chat: Wait for (5): HELLO
4654 Note (again) the use of the escape character, allowing many levels of
4656 Here, there are four parsers at work.
4657 The first parses the original line, reading it as three arguments.
4658 The second parses the third argument, reading it as 11 arguments.
4659 At this point, it is
4662 signs are escaped, otherwise this parser will see them as constituting
4663 an expect-send-expect sequence.
4666 character is seen, the execution parser reads the first command as three
4669 itself expands the argument after the
4671 As we wish to send the output back to the modem, in the first example
4672 we redirect our output to file descriptor 2 (stderr) so that
4674 itself sends and logs it, and in the second example, we just output to stdout,
4675 which is attached directly to the modem.
4677 This, of course means that it is possible to execute an entirely external
4679 command rather than using the internal one.
4682 for a good alternative.
4684 The external command that is executed is subjected to the same special
4685 word expansions as the
4688 .It set enddisc Op label|IP|MAC|magic|psn value
4689 This command sets our local endpoint discriminator.
4690 If set prior to LCP negotiation, and if no
4692 command has been used,
4694 will send the information to the peer using the LCP endpoint discriminator
4696 The following discriminators may be set:
4697 .Bl -tag -width indent
4699 The current label is used.
4701 Our local IP number is used.
4702 As LCP is negotiated prior to IPCP, it is
4703 possible that the IPCP layer will subsequently change this value.
4705 it does, the endpoint discriminator stays at the old value unless manually
4708 This is similar to the
4710 option above, except that the MAC address associated with the local IP
4712 If the local IP number is not resident on any Ethernet
4713 interface, the command will fail.
4715 As the local IP number defaults to whatever the machine host name is,
4717 is usually done prior to any
4721 A 20 digit random number is used.
4722 Care should be taken when using magic numbers as restarting
4724 or creating a link using a different
4726 invocation will also use a different magic number and will therefore not
4727 be recognised by the peer as belonging to the same bundle.
4728 This makes it unsuitable for
4736 should be set to an absolute public switched network number with the
4740 If no arguments are given, the endpoint discriminator is reset.
4741 .It set escape Ar value...
4742 This option is similar to the
4745 It allows the user to specify a set of characters that will be
4747 as they travel across the link.
4748 .It set filter dial|alive|in|out Ar rule-no Xo
4749 .No permit|deny|clear| Ns Ar rule-no
4752 .Ar src_addr Ns Op / Ns Ar width
4753 .Op Ar dst_addr Ns Op / Ns Ar width
4755 .Op src lt|eq|gt Ar port
4756 .Op dst lt|eq|gt Ar port
4760 .Op timeout Ar secs ]
4763 supports four filter sets.
4766 filter specifies packets that keep the connection alive - resetting the
4770 filter specifies packets that cause
4777 filter specifies packets that are allowed to travel
4778 into the machine and the
4780 filter specifies packets that are allowed out of the machine.
4782 Filtering is done prior to any IP alterations that might be done by the
4783 NAT engine on outgoing packets and after any IP alterations that might
4784 be done by the NAT engine on incoming packets.
4785 By default all empty filter sets allow all packets to pass.
4786 Rules are processed in order according to
4788 (unless skipped by specifying a rule number as the
4790 Up to 40 rules may be given for each set.
4791 If a packet doesn't match
4792 any of the rules in a given set, it is discarded.
4797 filters, this means that the packet is dropped.
4800 filters it means that the packet will not reset the idle timer (even if
4802 .Ar in Ns No / Ns Ar out
4805 value) and in the case of
4807 filters it means that the packet will not trigger a dial.
4808 A packet failing to trigger a dial will be dropped rather than queued.
4811 .Sx PACKET FILTERING
4812 above for further details.
4813 .It set hangup Ar chat-script
4814 This specifies the chat script that will be used to reset the device
4815 before it is closed.
4816 It should not normally be necessary, but can
4817 be used for devices that fail to reset themselves properly on close.
4818 .It set help|? Op Ar command
4819 This command gives a summary of available set commands, or if
4821 is specified, the command usage is shown.
4822 .It set ifaddr Oo Ar myaddr Ns
4824 .Oo Ar hisaddr Ns Op / Ns Ar \&nn
4829 This command specifies the IP addresses that will be used during
4831 Addresses are specified using the format
4837 is the preferred IP, but
4839 specifies how many bits of the address we will insist on.
4842 is omitted, it defaults to
4844 unless the IP address is 0.0.0.0 in which case it defaults to
4847 If you wish to assign a dynamic IP number to the peer,
4849 may also be specified as a range of IP numbers in the format
4850 .Bd -ragged -offset indent
4851 .Ar \&IP Ns Oo \&- Ns Ar \&IP Ns Xo
4852 .Oc Ns Oo , Ns Ar \&IP Ns
4853 .Op \&- Ns Ar \&IP Ns
4860 .Dl set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20
4864 as the local IP number, but may assign any of the given 10 IP
4865 numbers to the peer.
4866 If the peer requests one of these numbers,
4867 and that number is not already in use,
4869 will grant the peers request.
4870 This is useful if the peer wants
4871 to re-establish a link using the same IP number as was previously
4872 allocated (thus maintaining any existing tcp or udp connections).
4874 If the peer requests an IP number that's either outside
4875 of this range or is already in use,
4877 will suggest a random unused IP number from the range.
4881 is specified, it is used in place of
4883 in the initial IPCP negotiation.
4884 However, only an address in the
4886 range will be accepted.
4887 This is useful when negotiating with some
4889 implementations that will not assign an IP number unless their peer
4893 It should be noted that in
4897 will configure the interface immediately upon reading the
4899 line in the config file.
4900 In any other mode, these values are just
4901 used for IPCP negotiations, and the interface isn't configured
4902 until the IPCP layer is up.
4906 argument may be overridden by the third field in the
4908 file once the client has authenticated itself
4912 .Sx AUTHENTICATING INCOMING CONNECTIONS
4913 section for details.
4915 In all cases, if the interface is already configured,
4917 will try to maintain the interface IP numbers so that any existing
4918 bound sockets will remain valid.
4919 .It set ifqueue Ar packets
4920 Set the maximum number of packets that
4922 will read from the tunnel interface while data cannot be sent to any of
4923 the available links.
4924 This queue limit is necessary to flow control outgoing data as the tunnel
4925 interface is likely to be far faster than the combined links available to
4930 is set to a value less than the number of links,
4932 will read up to that value regardless.
4933 This prevents any possible latency problems.
4935 The default value for
4939 .It set ccpretry|ccpretries Oo Ar timeout
4940 .Op Ar reqtries Op Ar trmtries
4942 .It set chapretry|chapretries Oo Ar timeout
4945 .It set ipcpretry|ipcpretries Oo Ar timeout
4946 .Op Ar reqtries Op Ar trmtries
4948 .It set ipv6cpretry|ipv6cpretries Oo Ar timeout
4949 .Op Ar reqtries Op Ar trmtries
4951 .It set lcpretry|lcpretries Oo Ar timeout
4952 .Op Ar reqtries Op Ar trmtries
4954 .It set papretry|papretries Oo Ar timeout
4957 These commands set the number of seconds that
4959 will wait before resending Finite State Machine (FSM) Request packets.
4962 for all FSMs is 3 seconds (which should suffice in most cases).
4966 is specified, it tells
4968 how many configuration request attempts it should make while receiving
4969 no reply from the peer before giving up.
4970 The default is 5 attempts for
4971 CCP, LCP and IPCP and 3 attempts for PAP and CHAP.
4975 is specified, it tells
4977 how many terminate requests should be sent before giving up waiting for the
4979 The default is 3 attempts.
4980 Authentication protocols are
4981 not terminated and it is therefore invalid to specify
4985 In order to avoid negotiations with the peer that will never converge,
4987 will only send at most 3 times the configured number of
4989 in any given negotiation session before giving up and closing that layer.
4995 This command allows the adjustment of the current log level.
4996 Refer to the Logging Facility section for further details.
4997 .It set login Ar chat-script
5000 complements the dial-script.
5001 If both are specified, the login
5002 script will be executed after the dial script.
5003 Escape sequences available in the dial script are also available here.
5004 .It set logout Ar chat-script
5005 This specifies the chat script that will be used to logout
5006 before the hangup script is called.
5007 It should not normally be necessary.
5008 .It set lqrperiod Ar frequency
5009 This command sets the
5016 The default is 30 seconds.
5017 You must also use the
5019 command if you wish to send LQR requests to the peer.
5020 .It set mode Ar interactive|auto|ddial|background
5021 This command allows you to change the
5023 of the specified link.
5024 This is normally only useful in multi-link mode,
5025 but may also be used in uni-link mode.
5027 It is not possible to change a link that is
5032 Note: If you issue the command
5034 and have network address translation enabled, it may be useful to
5035 .Dq enable iface-alias
5039 to do the necessary address translations to enable the process that
5040 triggers the connection to connect once the link is up despite the
5041 peer assigning us a new (dynamic) IP address.
5042 .It set mppe Op 40|56|128|* Op stateless|stateful|*
5043 This option selects the encryption parameters used when negotiation
5045 MPPE can be disabled entirely with the
5048 If no arguments are given,
5050 will attempt to negotiate a stateful link with a 128 bit key, but
5051 will agree to whatever the peer requests (including no encryption
5054 If any arguments are given,
5058 on using MPPE and will close the link if it's rejected by the peer (Note;
5059 this behaviour can be overridden by a configured RADIUS server).
5061 The first argument specifies the number of bits that
5063 should insist on during negotiations and the second specifies whether
5065 should insist on stateful or stateless mode.
5066 In stateless mode, the
5067 encryption dictionary is re-initialised with every packet according to
5068 an encryption key that is changed with every packet.
5070 the encryption dictionary is re-initialised every 256 packets or after
5071 the loss of any data and the key is changed every 256 packets.
5072 Stateless mode is less efficient but is better for unreliable transport
5074 .It set mrru Op Ar value
5075 Setting this option enables Multi-link PPP negotiations, also known as
5076 Multi-link Protocol or MP.
5077 There is no default MRRU (Maximum Reconstructed Receive Unit) value.
5078 If no argument is given, multi-link mode is disabled.
5083 The default MRU (Maximum Receive Unit) is 1500.
5084 If it is increased, the other side *may* increase its MTU.
5085 In theory there is no point in decreasing the MRU to below the default as the
5087 protocol says implementations *must* be able to accept packets of at
5094 will refuse to negotiate a higher value.
5095 The maximum MRU can be set to 2048 at most.
5096 Setting a maximum of less than 1500 violates the
5098 rfc, but may sometimes be necessary.
5101 imposes a maximum of 1492 due to hardware limitations.
5103 If no argument is given, 1500 is assumed.
5104 A value must be given when
5111 The default MTU is 1500.
5112 At negotiation time,
5114 will accept whatever MRU the peer requests (assuming it's
5115 not less than 296 bytes or greater than the assigned maximum).
5118 will not accept MRU values less than
5120 When negotiations are complete, the MTU is used when writing to the
5121 interface, even if the peer requested a higher value MRU.
5122 This can be useful for
5123 limiting your packet size (giving better bandwidth sharing at the expense
5124 of more header data).
5130 will refuse to negotiate a higher value.
5131 The maximum MTU can be set to 2048 at most.
5135 is given, 1500, or whatever the peer asks for is used.
5136 A value must be given when
5139 .It set nbns Op Ar x.x.x.x Op Ar y.y.y.y
5140 This option allows the setting of the Microsoft NetBIOS name server
5141 values to be returned at the peers request.
5142 If no values are given,
5144 will reject any such requests.
5145 .It set openmode active|passive Op Ar delay
5154 will always initiate LCP/IPCP/CCP negotiation one second after the line
5156 If you want to wait for the peer to initiate negotiations, you
5159 If you want to initiate negotiations immediately or after more than one
5160 second, the appropriate
5162 may be specified here in seconds.
5163 .It set parity odd|even|none|mark
5164 This allows the line parity to be set.
5165 The default value is
5167 .It set phone Ar telno Ns Xo
5168 .Oo \&| Ns Ar backupnumber
5169 .Oc Ns ... Ns Oo : Ns Ar nextnumber
5172 This allows the specification of the phone number to be used in
5173 place of the \\\\T string in the dial and login chat scripts.
5174 Multiple phone numbers may be given separated either by a pipe
5179 Numbers after the pipe are only dialed if the dial or login
5180 script for the previous number failed.
5182 Numbers after the colon are tried sequentially, irrespective of
5183 the reason the line was dropped.
5185 If multiple numbers are given,
5187 will dial them according to these rules until a connection is made, retrying
5188 the maximum number of times specified by
5193 mode, each number is attempted at most once.
5194 .It set Op proc Ns Xo
5195 .No title Op Ar value
5197 The current process title as displayed by
5199 is changed according to
5203 is not specified, the original process title is restored.
5205 word replacements done by the shell commands (see the
5207 command above) are done here too.
5209 Note, if USER is required in the process title, the
5211 command must appear in
5213 as it is not known when the commands in
5216 .It set radius Op Ar config-file
5217 This command enables RADIUS support (if it's compiled in).
5219 refers to the radius client configuration file as described in
5221 If PAP, CHAP, MSCHAP or MSCHAPv2 are
5222 .Dq enable Ns No d ,
5225 .Em \&N Ns No etwork
5228 and uses the configured RADIUS server to authenticate rather than
5229 authenticating from the
5231 file or from the passwd database.
5233 If none of PAP, CHAP, MSCHAP or MSCHAPv2 are enabled,
5238 uses the following attributes from the RADIUS reply:
5239 .Bl -tag -width XXX -offset XXX
5240 .It RAD_FRAMED_IP_ADDRESS
5241 The peer IP address is set to the given value.
5242 .It RAD_FRAMED_IP_NETMASK
5243 The tun interface netmask is set to the given value.
5245 If the given MTU is less than the peers MRU as agreed during LCP
5246 negotiation, *and* it is less that any configured MTU (see the
5248 command), the tun interface MTU is set to the given value.
5249 .It RAD_FRAMED_COMPRESSION
5250 If the received compression type is
5253 will request VJ compression during IPCP negotiations despite any
5255 configuration command.
5257 If this attribute is supplied,
5259 will attempt to use it as an additional label to load from the
5264 The load will be attempted before (and in addition to) the normal
5266 If the label doesn't exist, no action is taken and
5268 proceeds to the normal load using the current label.
5269 .It RAD_FRAMED_ROUTE
5270 The received string is expected to be in the format
5271 .Ar dest Ns Op / Ns Ar bits
5274 Any specified metrics are ignored.
5278 are understood as valid values for
5285 to specify the default route, and
5287 is understood to be the same as
5296 For example, a returned value of
5297 .Dq 1.2.3.4/24 0.0.0.0 1 2 -1 3 400
5298 would result in a routing table entry to the 1.2.3.0/24 network via
5300 and a returned value of
5304 would result in a default route to
5307 All RADIUS routes are applied after any sticky routes are applied, making
5308 RADIUS routes override configured routes.
5309 This also applies for RADIUS routes that don't {include} the
5315 .It RAD_SESSION_TIMEOUT
5316 If supplied, the client connection is closed after the given number of
5318 .It RAD_REPLY_MESSAGE
5319 If supplied, this message is passed back to the peer as the authentication
5321 .It RAD_MICROSOFT_MS_CHAP_ERROR
5323 .Dv RAD_VENDOR_MICROSOFT
5324 vendor specific attribute is supplied, it is passed back to the peer as the
5325 authentication FAILURE text.
5326 .It RAD_MICROSOFT_MS_CHAP2_SUCCESS
5328 .Dv RAD_VENDOR_MICROSOFT
5329 vendor specific attribute is supplied and if MS-CHAPv2 authentication is
5330 being used, it is passed back to the peer as the authentication SUCCESS text.
5331 .It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY
5333 .Dv RAD_VENDOR_MICROSOFT
5334 vendor specific attribute is supplied and has a value of 2 (Required),
5336 will insist that MPPE encryption is used (even if no
5338 configuration command has been given with arguments).
5339 If it is supplied with a value of 1 (Allowed), encryption is made optional
5342 configuration commands with arguments).
5343 .It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES
5345 .Dv RAD_VENDOR_MICROSOFT
5346 vendor specific attribute is supplied, bits 1 and 2 are examined.
5347 If either or both are set, 40 bit and/or 128 bit (respectively) encryption
5348 options are set, overriding any given first argument to the
5351 Note, it is not currently possible for the RADIUS server to specify 56 bit
5353 .It RAD_MICROSOFT_MS_MPPE_RECV_KEY
5355 .Dv RAD_VENDOR_MICROSOFT
5356 vendor specific attribute is supplied, it's value is used as the master
5357 key for decryption of incoming data. When clients are authenticated using
5358 MSCHAPv2, the RADIUS server MUST provide this attribute if inbound MPPE is
5360 .It RAD_MICROSOFT_MS_MPPE_SEND_KEY
5362 .Dv RAD_VENDOR_MICROSOFT
5363 vendor specific attribute is supplied, it's value is used as the master
5364 key for encryption of outgoing data. When clients are authenticated using
5365 MSCHAPv2, the RADIUS server MUST provide this attribute if outbound MPPE is
5369 Values received from the RADIUS server may be viewed using
5371 .It set reconnect Ar timeout ntries
5372 Should the line drop unexpectedly (due to loss of CD or LQR
5373 failure), a connection will be re-established after the given
5375 The line will be re-connected at most
5384 will result in a variable pause, somewhere between 1 and 30 seconds.
5385 .It set recvpipe Op Ar value
5386 This sets the routing table RECVPIPE value.
5387 The optimum value is just over twice the MTU value.
5390 is unspecified or zero, the default kernel controlled value is used.
5391 .It set redial Ar secs Ns Xo
5394 .Oc Ns Op . Ns Ar next
5398 can be instructed to attempt to redial
5401 If more than one phone number is specified (see
5405 is taken before dialing each number.
5408 is taken before starting at the first number again.
5411 may be used here in place of
5415 causing a random delay of between 1 and 30 seconds.
5419 is specified, its value is added onto
5425 will only be incremented at most
5433 delay will be effective, even after
5435 has been exceeded, so an immediate manual dial may appear to have
5437 If an immediate dial is required, a
5439 should immediately follow the
5444 description above for further details.
5445 .It set sendpipe Op Ar value
5446 This sets the routing table SENDPIPE value.
5447 The optimum value is just over twice the MTU value.
5450 is unspecified or zero, the default kernel controlled value is used.
5451 .It "set server|socket" Ar TcpPort Ns No \&| Ns Xo
5452 .Ar LocalName Ns No |none|open|closed
5453 .Op password Op Ar mask
5457 to listen on the given socket or
5459 for incoming command connections.
5465 to close any existing socket and clear the socket configuration.
5470 to attempt to re-open the port.
5475 to close the open port.
5477 If you wish to specify a local domain socket,
5479 must be specified as an absolute file name, otherwise it is assumed
5480 to be the name or number of a TCP port.
5481 You may specify the octal umask to be used with a local domain socket.
5487 for details of how to translate TCP port names.
5489 You must also specify the password that must be entered by the client
5492 variable above) when connecting to this socket.
5494 specified as an empty string, no password is required for connecting clients.
5496 When specifying a local domain socket, the first
5498 sequence found in the socket name will be replaced with the current
5499 interface unit number.
5500 This is useful when you wish to use the same
5501 profile for more than one connection.
5503 In a similar manner TCP sockets may be prefixed with the
5505 character, in which case the current interface unit number is added to
5510 with a server socket, the
5512 command is the preferred mechanism of communications.
5515 can also be used, but link encryption may be implemented in the future, so
5523 interact with the diagnostic socket.
5524 .It set speed Ar value
5525 This sets the speed of the serial device.
5526 If speed is specified as
5529 treats the device as a synchronous device.
5531 Certain device types will know whether they should be specified as
5532 synchronous or asynchronous.
5533 These devices will override incorrect
5534 settings and log a warning to this effect.
5535 .It set stopped Op Ar LCPseconds Op Ar CCPseconds
5536 If this option is set,
5538 will time out after the given FSM (Finite State Machine) has been in
5539 the stopped state for the given number of
5541 This option may be useful if the peer sends a terminate request,
5542 but never actually closes the connection despite our sending a terminate
5544 This is also useful if you wish to
5545 .Dq set openmode passive
5546 and time out if the peer doesn't send a Configure Request within the
5549 .Dq set log +lcp +ccp
5552 log the appropriate state transitions.
5554 The default value is zero, where
5556 doesn't time out in the stopped state.
5558 This value should not be set to less than the openmode delay (see
5561 .It set timeout Ar idleseconds Op Ar mintimeout
5562 This command allows the setting of the idle timer.
5563 Refer to the section titled
5564 .Sx SETTING THE IDLE TIMER
5565 for further details.
5571 will never idle out before the link has been up for at least that number
5579 This command controls the ports that
5581 prioritizes when transmitting data.
5582 The default priority TCP ports
5583 are ports 21 (ftp control), 22 (ssh), 23 (telnet), 513 (login), 514 (shell),
5584 543 (klogin) and 544 (kshell).
5585 There are no priority UDP ports by default.
5600 are given, the priority port lists are cleared (although if
5604 is specified, only that list is cleared).
5607 argument is prefixed with a plus
5611 the current list is adjusted, otherwise the list is reassigned.
5613 prefixed with a plus or not prefixed at all are added to the list and
5615 prefixed with a minus are removed from the list.
5619 is specified, all priority port lists are disabled and even
5621 packets are not prioritised.
5622 .It set vj slotcomp on|off
5625 whether it should attempt to negotiate VJ slot compression.
5626 By default, slot compression is turned
5628 .It set vj slots Ar nslots
5629 This command sets the initial number of slots that
5631 will try to negotiate with the peer when VJ compression is enabled (see the
5634 It defaults to a value of 16.
5643 .It shell|! Op Ar command
5646 is not specified a shell is invoked according to the
5648 environment variable.
5649 Otherwise, the given
5652 Word replacement is done in the same way as for the
5654 command as described above.
5656 Use of the ! character
5657 requires a following space as with any of the other commands.
5658 You should note that this command is executed in the foreground;
5660 will not continue running until this process has exited.
5663 command if you wish processing to happen in the background.
5665 This command allows the user to examine the following:
5668 Show the current bundle settings.
5670 Show the current CCP compression statistics.
5672 Show the current VJ compression statistics.
5674 Show the current escape characters.
5675 .It show filter Op Ar name
5676 List the current rules for the given filter.
5679 is not specified, all filters are shown.
5681 Show the current HDLC statistics.
5683 Give a summary of available show commands.
5685 Show the current interface information
5689 Show the current IPCP statistics.
5691 Show the protocol layers currently in use.
5693 Show the current LCP statistics.
5694 .It show Op data Ns Xo
5697 Show high level link information.
5699 Show a list of available logical links.
5701 Show the current log values.
5703 Show current memory statistics.
5705 Show the current NCP statistics.
5707 Show low level link information.
5709 Show Multi-link information.
5711 Show current protocol totals.
5713 Show the current routing tables.
5715 Show the current stopped timeouts.
5717 Show the active alarm timers.
5719 Show the current version number of
5724 Go into terminal mode.
5725 Characters typed at the keyboard are sent to the device.
5726 Characters read from the device are displayed on the screen.
5731 automatically enables Packet Mode and goes back into command mode.
5736 Read the example configuration files.
5737 They are a good source of information.
5746 to get online information about what's available.
5748 The following URLs contain useful information:
5749 .Bl -bullet -compact
5751 .Pa http://www.dragonflybsd.org/docs/handbook/handbook-userppp/
5756 refers to four files:
5762 These files are placed in the
5766 .It Pa /etc/ppp/ppp.conf
5767 System default configuration file.
5768 .It Pa /etc/ppp/ppp.secret
5769 An authorisation file for each system.
5770 .It Pa /etc/ppp/ppp.linkup
5771 A file to check when
5773 establishes a network level connection.
5774 .It Pa /etc/ppp/ppp.linkdown
5775 A file to check when
5777 closes a network level connection.
5778 .It Pa /var/log/ppp.log
5779 Logging and debugging information file.
5780 Note, this name is specified in
5781 .Pa /etc/syslog.conf .
5784 for further details.
5785 .It Pa /var/spool/lock/LCK..*
5786 tty port locking file.
5789 for further details.
5790 .It Pa /var/run/tunN.pid
5791 The process id (pid) of the
5793 program connected to the tunN device, where
5795 is the number of the device.
5796 .It Pa /var/run/ttyXX.if
5797 The tun interface used by this port.
5798 Again, this file is only created in
5804 .It Pa /etc/services
5805 Get port number if port number is using service name.
5806 .It Pa /var/run/ppp-authname-class-value
5807 In multi-link mode, local domain sockets are created using the peer
5810 the peer endpoint discriminator class
5812 and the peer endpoint discriminator value
5814 As the endpoint discriminator value may be a binary value, it is turned
5815 to HEX to determine the actual file name.
5817 This socket is used to pass links between different instances of
5829 ifdef({LOCALNAT},{},{.Xr libalias 3 ,
5831 ifdef({LOCALRAD},{},{.Xr libradius 3 ,
5860 This program was originally written by
5861 .An Toshiharu OHNO Aq tony-o@iij.ad.jp ,
5862 and was submitted to
5865 .An Atsushi Murai Aq amurai@spec.co.jp .
5867 It was substantially modified during 1997 by
5868 .An Brian Somers Aq brian@Awfulhak.org ,
5871 in November that year
5872 (just after the 2.2 release).
5874 Most of the code was rewritten by
5876 in early 1998 when multi-link ppp support was added.
projects / dragonfly.git / blob