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 $
29 .\" $DragonFly: src/usr.sbin/ppp/ppp.8.m4,v 1.12 2008/05/02 02:05:08 swildner Exp $
36 .Nd Point to Point Protocol (a.k.a. user-ppp)
45 This is a user process
50 is implemented as a part of the kernel (e.g., as managed by
52 and it's thus somewhat hard to debug and/or modify its behaviour.
53 However, in this implementation
55 is done as a user process with the help of the
56 tunnel device driver (tun).
60 flag does the equivalent of a
64 network address translation features.
67 to act as a NAT or masquerading engine for all machines on an internal
69 ifdef({LOCALNAT},{},{Refer to
71 for details on the technical side of the NAT engine.
74 .Sx NETWORK ADDRESS TRANSLATION (PACKET ALIASING)
75 section of this manual page for details on how to configure NAT in
82 to be silent at startup rather than displaying the mode and interface
89 to only attempt to open
90 .Pa /dev/tun Ns Ar N .
93 will start with a value of 0 for
95 and keep trying to open a tunnel device by incrementing the value of
97 by one each time until it succeeds.
98 If it fails three times in a row
99 because the device file is missing, it gives up.
105 .Bl -tag -width XXX -offset XXX
108 opens the tun interface, configures it then goes into the background.
109 The link isn't brought up until outgoing data is detected on the tun
110 interface at which point
112 attempts to bring up the link.
113 Packets received (including the first one) while
115 is trying to bring the link up will remain queued for a default of
125 must be given on the command line (see below) and a
127 must be done in the system profile that specifies a peer IP address to
128 use when configuring the interface.
131 is usually appropriate.
135 .Pa /usr/share/examples/ppp/ppp.conf.sample
140 attempts to establish a connection with the peer immediately.
143 goes into the background and the parent process returns an exit code
147 exits with a non-zero result.
151 attempts to establish a connection with the peer immediately, but never
153 The link is created in background mode.
154 This is useful if you wish to control
156 invocation from another process.
158 This is used for receiving incoming connections.
162 line and uses descriptor 0 as the link.
164 If callback is configured,
168 information when dialing back.
170 This option is designed for machines connected with a dedicated
173 will always keep the device open and will never use any configured
176 This mode is equivalent to
180 will bring the link back up any time it's dropped for any reason.
182 This is a no-op, and gives the same behaviour as if none of the above
183 modes have been specified.
185 loads any sections specified on the command line then provides an
189 One or more configuration entries or systems
191 .Pa /etc/ppp/ppp.conf )
192 may also be specified on the command line.
197 .Pa /etc/ppp/ppp.conf
198 at startup, followed by each of the systems specified on the command line.
201 .It Provides an interactive user interface.
202 Using its command mode, the user can
203 easily enter commands to establish the connection with the remote end, check
204 the status of connection and close the connection.
205 All functions can also be optionally password protected for security.
206 .It Supports both manual and automatic dialing.
207 Interactive mode has a
209 command which enables you to talk to the device directly.
210 When you are connected to the remote peer and it starts to talk
213 detects it and switches to packet mode automatically.
215 determined the proper sequence for connecting with the remote host, you
216 can write a chat script to {define} the necessary dialing and login
217 procedure for later convenience.
218 .It Supports on-demand dialup capability.
223 will act as a daemon and wait for a packet to be sent over the
226 When this happens, the daemon automatically dials and establishes the
228 In almost the same manner
230 mode (direct-dial mode) also automatically dials and establishes the
232 However, it differs in that it will dial the remote site
233 any time it detects the link is down, even if there are no packets to be
235 This mode is useful for full-time connections where we worry less
236 about line charges and more about being connected full time.
239 mode is also available.
240 This mode is targeted at a dedicated link between two machines.
242 will never voluntarily quit from dedicated mode - you must send it the
244 command via its diagnostic socket.
247 will force an LCP renegotiation, and a
249 will force it to exit.
250 .It Supports client callback.
252 can use either the standard LCP callback protocol or the Microsoft
253 CallBack Control Protocol
254 .Pa ( ftp://ftp.microsoft.com/developr/rfc/cbcp.txt ) .
255 .It Supports NAT or packet aliasing.
256 Packet aliasing (a.k.a. IP masquerading) allows computers on a
257 private, unregistered network to access the Internet.
260 host acts as a masquerading gateway.
261 IP addresses as well as TCP and
262 UDP port numbers are NAT'd for outgoing packets and de-NAT'd for
264 .It Supports background PPP connections.
265 In background mode, if
267 successfully establishes the connection, it will become a daemon.
268 Otherwise, it will exit with an error.
269 This allows the setup of
270 scripts that wish to execute certain commands only if the connection
271 is successfully established.
272 .It Supports server-side PPP connections.
275 acts as server which accepts incoming
277 connections on stdin/stdout.
278 .It "Supports PAP and CHAP (rfc 1994, 2433 and 2759) authentication."
279 With PAP or CHAP, it is possible to skip the Unix style
281 procedure, and use the
283 protocol for authentication instead.
284 If the peer requests Microsoft CHAP authentication and
286 is compiled with DES support, an appropriate MD4/DES response will be
288 .It Supports RADIUS (rfc 2138 & 2548) authentication.
289 An extension to PAP and CHAP,
296 allows authentication information to be stored in a central or
297 distributed database along with various per-user framed connection
299 ifdef({LOCALRAD},{},{If
301 is available at compile time,
305 requests when configured to do so.
307 .It Supports Proxy Arp.
309 can be configured to make one or more proxy arp entries on behalf of
311 This allows routing from the peer to the LAN without
312 configuring each machine on that LAN.
313 .It Supports packet filtering.
314 User can {define} four kinds of filters: the
316 filter for incoming packets, the
318 filter for outgoing packets, the
320 filter to {define} a dialing trigger packet and the
322 filter for keeping a connection alive with the trigger packet.
323 .It Tunnel driver supports bpf.
326 to check the packet flow over the
329 .It Supports PPP over TCP and PPP over UDP.
330 If a device name is specified as
331 .Em host Ns No : Ns Em port Ns
336 will open a TCP or UDP connection for transporting data rather than using a
337 conventional serial device.
338 UDP connections force
340 into synchronous mode.
341 .It Supports PPP over ISDN.
344 is given a raw B-channel i4b device to open as a link, it's able to talk
347 daemon to establish an ISDN connection.
348 .It Supports PPP over Ethernet (rfc 2516).
351 is given a device specification of the format
352 .No PPPoE: Ns Ar iface Ns Xo
353 .Op \&: Ns Ar provider Ns
367 On systems that do not support
369 an external program such as
372 .It "Supports IETF draft Predictor-1 (rfc 1978) and DEFLATE (rfc 1979) compression."
374 supports not only VJ-compression but also Predictor-1 and DEFLATE compression.
375 Normally, a modem has built-in compression (e.g., v42.bis) and the system
376 may receive higher data rates from it as a result of such compression.
377 While this is generally a good thing in most other situations, this
378 higher speed data imposes a penalty on the system by increasing the
379 number of serial interrupts the system has to process in talking to the
380 modem and also increases latency.
381 Unlike VJ-compression, Predictor-1 and DEFLATE compression pre-compresses
383 network traffic flowing through the link, thus reducing overheads to a
385 .It Supports Microsoft's IPCP extensions (rfc 1877).
386 Name Server Addresses and NetBIOS Name Server Addresses can be negotiated
387 with clients using the Microsoft
389 stack (i.e., Win95, WinNT)
390 .It Supports Multi-link PPP (rfc 1990)
391 It is possible to configure
393 to open more than one physical connection to the peer, combining the
394 bandwidth of all links for better throughput.
395 .It Supports MPPE (draft-ietf-pppext-mppe)
396 MPPE is Microsoft Point to Point Encryption scheme.
397 It is possible to configure
399 to participate in Microsoft's Windows VPN.
402 can only get encryption keys from CHAP 81 authentication.
404 must be compiled with DES for MPPE to operate.
405 .It Supports IPV6CP (rfc 2023).
406 An IPv6 connection can be made in addition to or instead of the normal
419 will not run if the invoking user id is not zero.
420 This may be overridden by using the
423 .Pa /etc/ppp/ppp.conf .
424 When running as a normal user,
426 switches to user id 0 in order to alter the system routing table, set up
427 system lock files and read the ppp configuration files.
428 All external commands (executed via the "shell" or "!bg" commands) are executed
429 as the user id that invoked
433 logging facility if you're interested in what exactly is done as user id
438 you may need to deal with some initial configuration details.
441 Your kernel must {include} a tunnel device (the GENERIC kernel includes
443 If it doesn't, or if you require more than one tun
444 interface, you'll need to rebuild your kernel with the following line in
445 your kernel configuration file:
447 .Dl pseudo-device tun N
451 is the maximum number of
453 connections you wish to support.
455 Make sure that your system has a group named
459 file and that the group contains the names of all users expected to use
463 manual page for details.
464 Each of these users must also be given access using the
467 .Pa /etc/ppp/ppp.conf .
474 A common log file name is
475 .Pa /var/log/ppp.log .
476 To make output go to this file, put the following lines in the
479 .Bd -literal -offset indent
481 *.*<TAB>/var/log/ppp.log
484 It is possible to have more than one
486 log file by creating a link to the
494 .Bd -literal -offset indent
496 *.*<TAB>/var/log/ppp0.log
500 .Pa /etc/syslog.conf .
501 Don't forget to send a
506 .Pa /etc/syslog.conf .
508 Although not strictly relevant to
510 operation, you should configure your resolver so that it works correctly.
511 This can be done by configuring a local DNS
514 or by adding the correct
517 .Pa /etc/resolv.conf .
520 manual page for details.
522 Alternatively, if the peer supports it,
524 can be configured to ask the peer for the nameserver address(es) and to
532 commands below for details.
535 In the following examples, we assume that your machine name is
541 above) with no arguments, you are presented with a prompt:
542 .Bd -literal -offset indent
548 part of your prompt should always be in upper case.
549 If it is in lower case, it means that you must supply a password using the
552 This only ever happens if you connect to a running version of
554 and have not authenticated yourself using the correct password.
556 You can start by specifying the device name and speed:
557 .Bd -literal -offset indent
558 ppp ON awfulhak> set device /dev/cuaa0
559 ppp ON awfulhak> set speed 38400
562 Normally, hardware flow control (CTS/RTS) is used.
564 certain circumstances (as may happen when you are connected directly
565 to certain PPP-capable terminal servers), this may result in
567 hanging as soon as it tries to write data to your communications link
568 as it is waiting for the CTS (clear to send) signal - which will never
570 Thus, if you have a direct line and can't seem to make a
571 connection, try turning CTS/RTS off with
573 If you need to do this, check the
575 description below too - you'll probably need to
576 .Dq set accmap 000a0000 .
578 Usually, parity is set to
583 Parity is a rather archaic error checking mechanism that is no
584 longer used because modern modems do their own error checking, and most
585 link-layer protocols (that's what
587 is) use much more reliable checking mechanisms.
588 Parity has a relatively
589 huge overhead (a 12.5% increase in traffic) and as a result, it is always
596 However, some ISPs (Internet Service Providers) may use
597 specific parity settings at connection time (before
600 Notably, Compuserve insist on even parity when logging in:
601 .Bd -literal -offset indent
602 ppp ON awfulhak> set parity even
605 You can now see what your current device settings look like:
606 .Bd -literal -offset indent
607 ppp ON awfulhak> show physical
611 Link Type: interactive
617 Device List: /dev/cuaa0
618 Characteristics: 38400bps, cs8, even parity, CTS/RTS on
621 0 octets in, 0 octets out
626 The term command can now be used to talk directly to the device:
627 .Bd -literal -offset indent
628 ppp ON awfulhak> term
634 Password: myisppassword
638 When the peer starts to talk in
641 detects this automatically and returns to command mode.
642 .Bd -literal -offset indent
643 ppp ON awfulhak> # No link has been established
644 Ppp ON awfulhak> # We've connected & finished LCP
645 PPp ON awfulhak> # We've authenticated
646 PPP ON awfulhak> # We've agreed IP numbers
649 If it does not, it's probable that the peer is waiting for your end to
655 configuration packets to the peer, use the
657 command to drop out of terminal mode and enter packet mode.
659 If you never even receive a login prompt, it is quite likely that the
660 peer wants to use PAP or CHAP authentication instead of using Unix-style
661 login/password authentication.
662 To set things up properly, drop back to
663 the prompt and set your authentication name and key, then reconnect:
664 .Bd -literal -offset indent
666 ppp ON awfulhak> set authname myispusername
667 ppp ON awfulhak> set authkey myisppassword
668 ppp ON awfulhak> term
675 You may need to tell ppp to initiate negotiations with the peer here too:
676 .Bd -literal -offset indent
678 ppp ON awfulhak> # No link has been established
679 Ppp ON awfulhak> # We've connected & finished LCP
680 PPp ON awfulhak> # We've authenticated
681 PPP ON awfulhak> # We've agreed IP numbers
684 You are now connected!
687 in the prompt has changed to capital letters to indicate that you have
689 If only some of the three Ps go uppercase, wait until
690 either everything is uppercase or lowercase.
691 If they revert to lowercase, it means that
693 couldn't successfully negotiate with the peer.
694 A good first step for troubleshooting at this point would be to
695 .Bd -literal -offset indent
696 ppp ON awfulhak> set log local phase lcp ipcp
702 command description below for further details.
703 If things fail at this point,
704 it is quite important that you turn logging on and try again.
706 important that you note any prompt changes and report them to anyone trying
709 When the link is established, the show command can be used to see how
711 .Bd -literal -offset indent
712 PPP ON awfulhak> show physical
713 * Modem related information is shown here *
714 PPP ON awfulhak> show ccp
715 * CCP (compression) related information is shown here *
716 PPP ON awfulhak> show lcp
717 * LCP (line control) related information is shown here *
718 PPP ON awfulhak> show ipcp
719 * IPCP (IP) related information is shown here *
720 PPP ON awfulhak> show ipv6cp
721 * IPV6CP (IPv6) related information is shown here *
722 PPP ON awfulhak> show link
723 * Link (high level) related information is shown here *
724 PPP ON awfulhak> show bundle
725 * Logical (high level) connection related information is shown here *
728 At this point, your machine has a host route to the peer.
730 that you can only make a connection with the host on the other side
732 If you want to add a default route entry (telling your
733 machine to send all packets without another routing entry to the other
736 link), enter the following command:
737 .Bd -literal -offset indent
738 PPP ON awfulhak> add default HISADDR
743 represents the IP address of the connected peer.
746 command fails due to an existing route, you can overwrite the existing
748 .Bd -literal -offset indent
749 PPP ON awfulhak> add! default HISADDR
752 This command can also be executed before actually making the connection.
753 If a new IP address is negotiated at connection time,
755 will update your default route accordingly.
757 You can now use your network applications (ping, telnet, ftp etc.)
758 in other windows or terminals on your machine.
759 If you wish to reuse the current terminal, you can put
761 into the background using your standard shell suspend and background
769 section for details on all available commands.
770 .Sh AUTOMATIC DIALING
771 To use automatic dialing, you must prepare some Dial and Login chat scripts.
772 See the example definitions in
773 .Pa /usr/share/examples/ppp/ppp.conf.sample
775 .Pa /etc/ppp/ppp.conf
777 Each line contains one comment, inclusion, label or command:
780 A line starting with a
782 character is treated as a comment line.
783 Leading whitespace are ignored when identifying comment lines.
785 An inclusion is a line beginning with the word
787 It must have one argument - the file to {include}.
789 .Dq {!include} ~/.ppp.conf
790 for compatibility with older versions of
793 A label name starts in the first column and is followed by
797 A command line must contain a space or tab in the first column.
801 .Pa /etc/ppp/ppp.conf
802 file should consist of at least a
805 This section is always executed.
806 It should also contain
807 one or more sections, named according to their purpose, for example,
809 would represent your ISP, and
811 would represent an incoming
814 You can now specify the destination label name when you invoke
816 Commands associated with the
818 label are executed, followed by those associated with the destination
822 is started with no arguments, the
824 section is still executed.
825 The load command can be used to manually load a section from the
826 .Pa /etc/ppp/ppp.conf
828 .Bd -literal -offset indent
829 ppp ON awfulhak> load MyISP
832 Note, no action is taken by
834 after a section is loaded, whether it's the result of passing a label on
835 the command line or using the
838 Only the commands specified for that label in the configuration
840 However, when invoking
847 switches, the link mode tells
849 to establish a connection.
852 command below for further details.
854 Once the connection is made, the
856 portion of the prompt will change to
858 .Bd -literal -offset indent
861 ppp ON awfulhak> dial
867 The Ppp prompt indicates that
869 has entered the authentication phase.
870 The PPp prompt indicates that
872 has entered the network phase.
873 The PPP prompt indicates that
875 has successfully negotiated a network layer protocol and is in
879 .Pa /etc/ppp/ppp.linkup
880 file is available, its contents are executed
883 connection is established.
887 .Pa /usr/share/examples/ppp/ppp.conf.sample
888 which runs a script in the background after the connection is established
893 commands below for a description of possible substitution strings).
894 Similarly, when a connection is closed, the contents of the
895 .Pa /etc/ppp/ppp.linkdown
897 Both of these files have the same format as
898 .Pa /etc/ppp/ppp.conf .
900 In previous versions of
902 it was necessary to re-add routes such as the default route in the
908 where all routes that contain the
914 literals will automatically be updated when the values of these variables
916 .Sh BACKGROUND DIALING
917 If you want to establish a connection using
919 non-interactively (such as from a
923 job) you should use the
930 attempts to establish the connection immediately.
932 numbers are specified, each phone number will be tried once.
933 If the attempt fails,
935 exits immediately with a non-zero exit code.
938 becomes a daemon, and returns an exit status of zero to its caller.
939 The daemon exits automatically if the connection is dropped by the
940 remote system, or it receives a
944 Demand dialing is enabled with the
949 You must also specify the destination label in
950 .Pa /etc/ppp/ppp.conf
954 command to {define} the remote peers IP address.
956 .Pa /usr/share/examples/ppp/ppp.conf.sample )
957 .Bd -literal -offset indent
967 runs as a daemon but you can still configure or examine its
968 configuration by using the
971 .Pa /etc/ppp/ppp.conf ,
973 .Dq Li "set server +3000 mypasswd" )
974 and connecting to the diagnostic port as follows:
975 .Bd -literal -offset indent
976 # pppctl 3000 (assuming tun0)
978 PPP ON awfulhak> show who
979 tcp (127.0.0.1:1028) *
984 command lists users that are currently connected to
987 If the diagnostic socket is closed or changed to a different
988 socket, all connections are immediately dropped.
992 mode, when an outgoing packet is detected,
994 will perform the dialing action (chat script) and try to connect
998 mode, the dialing action is performed any time the line is found
1000 If the connect fails, the default behaviour is to wait 30 seconds
1001 and then attempt to connect when another outgoing packet is detected.
1002 This behaviour can be changed using the
1006 .No set redial Ar secs Ns Xo
1009 .Oc Ns Op . Ns Ar next
1013 .Bl -tag -width attempts -compact
1015 is the number of seconds to wait before attempting
1017 If the argument is the literal string
1019 the delay period is a random value between 1 and 30 seconds inclusive.
1021 is the number of seconds that
1023 should be incremented each time a new dial attempt is made.
1024 The timeout reverts to
1026 only after a successful connection is established.
1027 The default value for
1031 is the maximum number of times
1035 The default value for
1039 is the number of seconds to wait before attempting
1040 to dial the next number in a list of numbers (see the
1043 The default is 3 seconds.
1044 Again, if the argument is the literal string
1046 the delay period is a random value between 1 and 30 seconds.
1048 is the maximum number of times to try to connect for each outgoing packet
1049 that triggers a dial.
1050 The previous value is unchanged if this parameter is omitted.
1051 If a value of zero is specified for
1054 will keep trying until a connection is made.
1058 .Bd -literal -offset indent
1062 will attempt to connect 4 times for each outgoing packet that causes
1063 a dial attempt with a 3 second delay between each number and a 10 second
1064 delay after all numbers have been tried.
1065 If multiple phone numbers
1066 are specified, the total number of attempts is still 4 (it does not
1067 attempt each number 4 times).
1070 .Bd -literal -offset indent
1071 set redial 10+10-5.3 20
1076 to attempt to connect 20 times.
1077 After the first attempt,
1079 pauses for 10 seconds.
1080 After the next attempt it pauses for 20 seconds
1081 and so on until after the sixth attempt it pauses for 1 minute.
1082 The next 14 pauses will also have a duration of one minute.
1085 connects, disconnects and fails to connect again, the timeout starts again
1088 Modifying the dial delay is very useful when running
1092 mode on both ends of the link.
1093 If each end has the same timeout,
1094 both ends wind up calling each other at the same time if the link
1095 drops and both ends have packets queued.
1096 At some locations, the serial link may not be reliable, and carrier
1097 may be lost at inappropriate times.
1098 It is possible to have
1100 redial should carrier be unexpectedly lost during a session.
1101 .Bd -literal -offset indent
1102 set reconnect timeout ntries
1107 to re-establish the connection
1109 times on loss of carrier with a pause of
1111 seconds before each try.
1113 .Bd -literal -offset indent
1119 that on an unexpected loss of carrier, it should wait
1121 seconds before attempting to reconnect.
1122 This may happen up to
1127 The default value of ntries is zero (no reconnect).
1128 Care should be taken with this option.
1129 If the local timeout is slightly
1130 longer than the remote timeout, the reconnect feature will always be
1131 triggered (up to the given number of times) after the remote side
1132 times out and hangs up.
1133 NOTE: In this context, losing too many LQRs constitutes a loss of
1134 carrier and will trigger a reconnect.
1137 flag is specified, all phone numbers are dialed at most once until
1138 a connection is made.
1139 The next number redial period specified with the
1141 command is honoured, as is the reconnect tries value.
1143 value is less than the number of phone numbers specified, not all
1144 the specified numbers will be tried.
1145 To terminate the program, type
1146 .Bd -literal -offset indent
1147 PPP ON awfulhak> close
1148 ppp ON awfulhak> quit all
1153 command will terminate the
1157 connection but not the
1165 .Sh RECEIVING INCOMING PPP CONNECTIONS (Method 1)
1166 To handle an incoming
1168 connection request, follow these steps:
1171 Make sure the modem and (optionally)
1172 .Pa /etc/rc.d/serial
1173 is configured correctly.
1174 .Bl -bullet -compact
1176 Use Hardware Handshake (CTS/RTS) for flow control.
1178 Modem should be set to NO echo back (ATE0) and NO results string (ATQ1).
1186 on the port where the modem is attached.
1189 .Dl ttyd1 Qo /usr/libexec/getty std.38400 Qc dialup on secure
1191 Don't forget to send a
1195 process to start the
1200 It is usually also necessary to train your modem to the same DTR speed
1202 .Bd -literal -offset indent
1204 ppp ON awfulhak> set device /dev/cuaa1
1205 ppp ON awfulhak> set speed 38400
1206 ppp ON awfulhak> term
1207 deflink: Entering terminal mode on /dev/cuaa1
1218 ppp ON awfulhak> quit
1222 .Pa /usr/local/bin/ppplogin
1223 file with the following contents:
1224 .Bd -literal -offset indent
1226 exec /usr/sbin/ppp -direct incoming
1233 work with stdin and stdout.
1236 to connect to a configured diagnostic port, in the same manner as with
1242 section must be set up in
1243 .Pa /etc/ppp/ppp.conf .
1247 section contains the
1249 command as appropriate.
1251 Prepare an account for the incoming user.
1253 ppp:xxxx:66:66:PPP Login User:/home/ppp:/usr/local/bin/ppplogin
1256 Refer to the manual entries for
1262 Support for IPCP Domain Name Server and NetBIOS Name Server negotiation
1263 can be enabled using the
1268 Refer to their descriptions below.
1270 .Sh RECEIVING INCOMING PPP CONNECTIONS (Method 2)
1271 This method differs in that we use
1273 to authenticate the connection rather than
1277 Configure your default section in
1279 with automatic ppp recognition by specifying the
1284 :pp=/usr/local/bin/ppplogin:\\
1288 Configure your serial device(s), enable a
1291 .Pa /usr/local/bin/ppplogin
1292 as in the first three steps for method 1 above.
1300 .Pa /etc/ppp/ppp.conf
1303 label (or whatever label
1308 .Pa /etc/ppp/ppp.secret
1309 for each incoming user:
1318 detects a ppp connection (by recognising the HDLC frame headers), it runs
1319 .Dq /usr/local/bin/ppplogin .
1323 that either PAP or CHAP are enabled as above.
1324 If they are not, you are
1325 allowing anybody to establish a ppp session with your machine
1327 a password, opening yourself up to all sorts of potential attacks.
1328 .Sh AUTHENTICATING INCOMING CONNECTIONS
1329 Normally, the receiver of a connection requires that the peer
1330 authenticates itself.
1331 This may be done using
1333 but alternatively, you can use PAP or CHAP.
1334 CHAP is the more secure of the two, but some clients may not support it.
1335 Once you decide which you wish to use, add the command
1339 to the relevant section of
1342 You must then configure the
1343 .Pa /etc/ppp/ppp.secret
1345 This file contains one line per possible client, each line
1346 containing up to five fields:
1349 .Ar hisaddr Op Ar label Op Ar callback-number
1356 specify the client username and password.
1361 and PAP is being used,
1363 will look up the password database
1365 when authenticating.
1366 If the client does not offer a suitable response based on any
1367 .Ar name Ns No / Ns Ar key
1370 authentication fails.
1372 If authentication is successful,
1375 is used when negotiating IP numbers.
1378 command for details.
1380 If authentication is successful and
1382 is specified, the current system label is changed to match the given
1384 This will change the subsequent parsing of the
1390 If authentication is successful and
1396 the client will be called back on the given number.
1397 If CBCP is being used,
1399 may also contain a list of numbers or a
1404 The value will be used in
1406 subsequent CBCP phase.
1407 .Sh PPP OVER TCP and UDP (a.k.a Tunnelling)
1410 over a serial link, it is possible to
1411 use a TCP connection instead by specifying the host, port and protocol as the
1414 .Dl set device ui-gate:6669/tcp
1416 Instead of opening a serial device,
1418 will open a TCP connection to the given machine on the given
1420 It should be noted however that
1422 doesn't use the telnet protocol and will be unable to negotiate
1423 with a telnet server.
1424 You should set up a port for receiving this
1426 connection on the receiving machine (ui-gate).
1427 This is done by first updating
1429 to name the service:
1431 .Dl ppp-in 6669/tcp # Incoming PPP connections over TCP
1437 how to deal with incoming connections on that port:
1439 .Dl ppp-in stream tcp nowait root /usr/sbin/ppp ppp -direct ppp-in
1441 Don't forget to send a
1445 after you've updated
1446 .Pa /etc/inetd.conf .
1447 Here, we use a label named
1450 .Pa /etc/ppp/ppp.conf
1451 on ui-gate (the receiver) should contain the following:
1452 .Bd -literal -offset indent
1455 set ifaddr 10.0.4.1 10.0.4.2
1459 .Pa /etc/ppp/ppp.linkup
1461 .Bd -literal -offset indent
1463 add 10.0.1.0/24 HISADDR
1466 It is necessary to put the
1470 to ensure that the route is only added after
1472 has negotiated and assigned addresses to its interface.
1474 You may also want to enable PAP or CHAP for security.
1475 To enable PAP, add the following line:
1476 .Bd -literal -offset indent
1480 You'll also need to create the following entry in
1481 .Pa /etc/ppp/ppp.secret :
1482 .Bd -literal -offset indent
1483 MyAuthName MyAuthPasswd
1490 the password is looked up in the
1495 .Pa /etc/ppp/ppp.conf
1496 on awfulhak (the initiator) should contain the following:
1497 .Bd -literal -offset indent
1500 set device ui-gate:ppp-in/tcp
1503 set log Phase Chat Connect hdlc LCP IPCP IPV6CP CCP tun
1504 set ifaddr 10.0.4.2 10.0.4.1
1507 with the route setup in
1508 .Pa /etc/ppp/ppp.linkup :
1509 .Bd -literal -offset indent
1511 add 10.0.2.0/24 HISADDR
1514 Again, if you're enabling PAP, you'll also need this in the
1515 .Pa /etc/ppp/ppp.conf
1517 .Bd -literal -offset indent
1518 set authname MyAuthName
1519 set authkey MyAuthKey
1522 We're assigning the address of 10.0.4.1 to ui-gate, and the address
1523 10.0.4.2 to awfulhak.
1524 To open the connection, just type
1526 .Dl awfulhak # ppp -background ui-gate
1528 The result will be an additional "route" on awfulhak to the
1529 10.0.2.0/24 network via the TCP connection, and an additional
1530 "route" on ui-gate to the 10.0.1.0/24 network.
1531 The networks are effectively bridged - the underlying TCP
1532 connection may be across a public network (such as the
1535 traffic is conceptually encapsulated
1536 (although not packet by packet) inside the TCP stream between
1539 The major disadvantage of this mechanism is that there are two
1540 "guaranteed delivery" mechanisms in place - the underlying TCP
1541 stream and whatever protocol is used over the
1543 link - probably TCP again.
1544 If packets are lost, both levels will
1545 get in each others way trying to negotiate sending of the missing
1548 To avoid this overhead, it is also possible to do all this using
1549 UDP instead of TCP as the transport by simply changing the protocol
1550 from "tcp" to "udp".
1551 When using UDP as a transport,
1553 will operate in synchronous mode.
1554 This is another gain as the incoming
1555 data does not have to be rearranged into packets.
1557 Care should be taken when adding a default route through a tunneled
1559 It is quite common for the default route
1561 .Pa /etc/ppp/ppp.linkup )
1562 to end up routing the link's TCP connection through the tunnel,
1563 effectively garrotting the connection.
1564 To avoid this, make sure you add a static route for the benefit of
1566 .Bd -literal -offset indent
1569 set device ui-gate:ppp-in/tcp
1576 is the IP number that your route to
1580 When routing your connection across a public network such as the Internet,
1581 it is preferable to encrypt the data.
1582 This can be done with the help of the MPPE protocol, although currently this
1583 means that you will not be able to also compress the traffic as MPPE is
1584 implemented as a compression layer (thank Microsoft for this).
1585 To enable MPPE encryption, add the following lines to
1586 .Pa /etc/ppp/ppp.conf
1588 .Bd -literal -offset indent
1590 disable deflate pred1
1594 ensuring that you've put the requisite entry in
1595 .Pa /etc/ppp/ppp.secret
1596 (MSCHAPv2 is challenge based, so
1600 MSCHAPv2 and MPPE are accepted by default, so the client end should work
1601 without any additional changes (although ensure you have
1606 .Sh NETWORK ADDRESS TRANSLATION (PACKET ALIASING)
1609 command line option enables network address translation (a.k.a. packet
1613 host to act as a masquerading gateway for other computers over
1614 a local area network.
1615 Outgoing IP packets are NAT'd so that they appear to come from the
1617 host, and incoming packets are de-NAT'd so that they are routed
1618 to the correct machine on the local area network.
1619 NAT allows computers on private, unregistered subnets to have Internet
1620 access, although they are invisible from the outside world.
1623 operation should first be verified with network address translation disabled.
1626 option should be switched on, and network applications (web browser,
1631 should be checked on the
1634 Finally, the same or similar applications should be checked on other
1635 computers in the LAN.
1636 If network applications work correctly on the
1638 host, but not on other machines in the LAN, then the masquerading
1639 software is working properly, but the host is either not forwarding
1640 or possibly receiving IP packets.
1641 Check that IP forwarding is enabled in
1643 and that other machines have designated the
1645 host as the gateway for the LAN.
1646 .Sh PACKET FILTERING
1647 This implementation supports packet filtering.
1648 There are four kinds of
1658 Here are the basics:
1661 A filter definition has the following syntax:
1670 .Ar src_addr Ns Op / Ns Ar width
1671 .Op Ar dst_addr Ns Op / Ns Ar width
1673 .Ar [ proto Op src Ar cmp port
1678 .Op timeout Ar secs ]
1690 is a numeric value between
1694 specifying the rule number.
1695 Rules are specified in numeric order according to
1706 in which case, if a given packet matches the rule, the associated action
1707 is taken immediately.
1709 can also be specified as
1711 to clear the action associated with that particular rule, or as a new
1712 rule number greater than the current rule.
1713 In this case, if a given
1714 packet matches the current rule, the packet will next be matched against
1715 the new rule number (rather than the next rule number).
1719 may optionally be followed with an exclamation mark
1723 to reverse the sense of the following match.
1725 .Op Ar src_addr Ns Op / Ns Ar width
1727 .Op Ar dst_addr Ns Op / Ns Ar width
1728 are the source and destination IP number specifications.
1731 is specified, it gives the number of relevant netmask bits,
1732 allowing the specification of an address range.
1738 may be given the values
1744 (refer to the description of the
1746 command for a description of these values).
1747 When these values are used,
1748 the filters will be updated any time the values change.
1749 This is similar to the behaviour of the
1754 may be any protocol from
1763 meaning less-than, equal and greater-than respectively.
1765 can be specified as a numeric port or by service name from
1773 flags are only allowed when
1777 and represent the TH_ACK, TH_SYN and TH_FIN or TH_RST TCP flags respectively.
1779 The timeout value adjusts the current idle timeout to at least
1782 If a timeout is given in the alive filter as well as in the in/out
1783 filter, the in/out value is used.
1784 If no timeout is given, the default timeout (set using
1786 and defaulting to 180 seconds) is used.
1790 Each filter can hold up to 40 rules, starting from rule 0.
1791 The entire rule set is not effective until rule 0 is defined,
1792 i.e., the default is to allow everything through.
1794 If no rule in a defined set of rules matches a packet, that packet will
1795 be discarded (blocked).
1796 If there are no rules in a given filter, the packet will be permitted.
1798 It's possible to filter based on the payload of UDP frames where those
1804 .Ar filter-decapsulation
1805 option below for further details.
1808 .Dq set filter Ar name No -1
1813 .Pa /usr/share/examples/ppp/ppp.conf.sample .
1814 .Sh SETTING THE IDLE TIMER
1815 To check/set the idle timer, use the
1820 .Bd -literal -offset indent
1821 ppp ON awfulhak> set timeout 600
1824 The timeout period is measured in seconds, the default value for which
1827 To disable the idle timer function, use the command
1828 .Bd -literal -offset indent
1829 ppp ON awfulhak> set timeout 0
1836 modes, the idle timeout is ignored.
1839 mode, when the idle timeout causes the
1844 program itself remains running.
1845 Another trigger packet will cause it to attempt to re-establish the link.
1846 .Sh PREDICTOR-1 and DEFLATE COMPRESSION
1848 supports both Predictor type 1 and deflate compression.
1851 will attempt to use (or be willing to accept) both compression protocols
1852 when the peer agrees
1854 The deflate protocol is preferred by
1860 commands if you wish to disable this functionality.
1862 It is possible to use a different compression algorithm in each direction
1863 by using only one of
1867 (assuming that the peer supports both algorithms).
1869 By default, when negotiating DEFLATE,
1871 will use a window size of 15.
1874 command if you wish to change this behaviour.
1876 A special algorithm called DEFLATE24 is also available, and is disabled
1877 and denied by default.
1878 This is exactly the same as DEFLATE except that
1879 it uses CCP ID 24 to negotiate.
1882 to successfully negotiate DEFLATE with
1885 .Sh CONTROLLING IP ADDRESS
1888 uses IPCP to negotiate IP addresses.
1889 Each side of the connection
1890 specifies the IP address that it's willing to use, and if the requested
1891 IP address is acceptable then
1893 returns an ACK to the requester.
1896 returns NAK to suggest that the peer use a different IP address.
1898 both sides of the connection agree to accept the received request (and
1899 send an ACK), IPCP is set to the open state and a network level connection
1901 To control this IPCP behaviour, this implementation has the
1903 command for defining the local and remote IP address:
1904 .Bd -ragged -offset indent
1905 .No set ifaddr Oo Ar src_addr Ns
1907 .Oo Ar dst_addr Ns Op / Ns Ar \&nn
1917 is the IP address that the local side is willing to use,
1919 is the IP address which the remote side should use and
1921 is the netmask that should be used.
1923 defaults to the current
1926 defaults to 0.0.0.0, and
1928 defaults to whatever mask is appropriate for
1930 It is only possible to make
1932 smaller than the default.
1933 The usual value is 255.255.255.255, as
1934 most kernels ignore the netmask of a POINTOPOINT interface.
1938 implementations require that the peer negotiates a specific IP
1941 If this is the case,
1943 may be used to specify this IP number.
1944 This will not affect the
1945 routing table unless the other side agrees with this proposed number.
1946 .Bd -literal -offset indent
1947 set ifaddr 192.244.177.38 192.244.177.2 255.255.255.255 0.0.0.0
1950 The above specification means:
1952 .Bl -bullet -compact
1954 I will first suggest that my IP address should be 0.0.0.0, but I
1955 will only accept an address of 192.244.177.38.
1957 I strongly insist that the peer uses 192.244.177.2 as his own
1958 address and won't permit the use of any IP address but 192.244.177.2.
1959 When the peer requests another IP address, I will always suggest that
1960 it uses 192.244.177.2.
1962 The routing table entry will have a netmask of 0xffffffff.
1965 This is all fine when each side has a pre-determined IP address, however
1966 it is often the case that one side is acting as a server which controls
1967 all IP addresses and the other side should go along with it.
1968 In order to allow more flexible behaviour, the
1970 command allows the user to specify IP addresses more loosely:
1972 .Dl set ifaddr 192.244.177.38/24 192.244.177.2/20
1974 A number followed by a slash
1976 represents the number of bits significant in the IP address.
1977 The above example means:
1979 .Bl -bullet -compact
1981 I'd like to use 192.244.177.38 as my address if it is possible, but I'll
1982 also accept any IP address between 192.244.177.0 and 192.244.177.255.
1984 I'd like to make him use 192.244.177.2 as his own address, but I'll also
1985 permit him to use any IP address between 192.244.176.0 and
1988 As you may have already noticed, 192.244.177.2 is equivalent to saying
1991 As an exception, 0 is equivalent to 0.0.0.0/0, meaning that I have no
1992 preferred IP address and will obey the remote peers selection.
1993 When using zero, no routing table entries will be made until a connection
1996 192.244.177.2/0 means that I'll accept/permit any IP address but I'll
1997 suggest that 192.244.177.2 be used first.
2000 When negotiating IPv6 addresses, no control is given to the user.
2001 IPV6CP negotiation is fully automatic.
2002 .Sh CONNECTING WITH YOUR INTERNET SERVICE PROVIDER
2003 The following steps should be taken when connecting to your ISP:
2006 Describe your providers phone number(s) in the dial script using the
2009 This command allows you to set multiple phone numbers for
2010 dialing and redialing separated by either a pipe
2014 .Bd -ragged -offset indent
2015 .No set phone Ar telno Ns Xo
2016 .Oo \&| Ns Ar backupnumber
2017 .Oc Ns ... Ns Oo : Ns Ar nextnumber
2022 Numbers after the first in a pipe-separated list are only used if the
2023 previous number was used in a failed dial or login script.
2025 separated by a colon are used sequentially, irrespective of what happened
2026 as a result of using the previous number.
2028 .Bd -literal -offset indent
2029 set phone "1234567|2345678:3456789|4567890"
2032 Here, the 1234567 number is attempted.
2033 If the dial or login script fails,
2034 the 2345678 number is used next time, but *only* if the dial or login script
2036 On the dial after this, the 3456789 number is used.
2038 number is only used if the dial or login script using the 3456789 fails.
2039 If the login script of the 2345678 number fails, the next number is still the
2041 As many pipes and colons can be used as are necessary
2042 (although a given site would usually prefer to use either the pipe or the
2043 colon, but not both).
2044 The next number redial timeout is used between all numbers.
2045 When the end of the list is reached, the normal redial period is
2046 used before starting at the beginning again.
2047 The selected phone number is substituted for the \\\\T string in the
2049 command (see below).
2051 Set up your redial requirements using
2053 For example, if you have a bad telephone line or your provider is
2054 usually engaged (not so common these days), you may want to specify
2056 .Bd -literal -offset indent
2060 This says that up to 4 phone calls should be attempted with a pause of 10
2061 seconds before dialing the first number again.
2063 Describe your login procedure using the
2070 command is used to talk to your modem and establish a link with your
2072 .Bd -literal -offset indent
2073 set dial "ABORT BUSY ABORT NO\\\\sCARRIER TIMEOUT 4 \\"\\" \e
2074 ATZ OK-ATZ-OK ATDT\\\\T TIMEOUT 60 CONNECT"
2077 This modem "chat" string means:
2080 Abort if the string "BUSY" or "NO CARRIER" are received.
2082 Set the timeout to 4 seconds.
2089 If that's not received within the 4 second timeout, send ATZ
2092 Send ATDTxxxxxxx where xxxxxxx is the next number in the phone list from
2095 Set the timeout to 60.
2097 Wait for the CONNECT string.
2100 Once the connection is established, the login script is executed.
2101 This script is written in the same style as the dial script, but care should
2102 be taken to avoid having your password logged:
2103 .Bd -literal -offset indent
2104 set authkey MySecret
2105 set login "TIMEOUT 15 login:-\\\\r-login: awfulhak \e
2106 word: \\\\P ocol: PPP HELLO"
2109 This login "chat" string means:
2112 Set the timeout to 15 seconds.
2115 If it's not received, send a carriage return and expect
2120 Expect "word:" (the tail end of a "Password:" prompt).
2122 Send whatever our current
2126 Expect "ocol:" (the tail end of a "Protocol:" prompt).
2135 command is logged specially.
2140 logging is enabled, the actual password is not logged;
2144 Login scripts vary greatly between ISPs.
2145 If you're setting one up for the first time,
2146 .Em ENABLE CHAT LOGGING
2147 so that you can see if your script is behaving as you expect.
2153 to specify your serial line and speed, for example:
2154 .Bd -literal -offset indent
2155 set device /dev/cuaa0
2159 Cuaa0 is the first serial port on
2166 A speed of 115200 should be specified
2167 if you have a modem capable of bit rates of 28800 or more.
2168 In general, the serial speed should be about four times the modem speed.
2172 command to {define} the IP address.
2175 If you know what IP address your provider uses, then use it as the remote
2176 address (dst_addr), otherwise choose something like 10.0.0.2/0 (see below).
2178 If your provider has assigned a particular IP address to you, then use
2179 it as your address (src_addr).
2181 If your provider assigns your address dynamically, choose a suitably
2182 unobtrusive and unspecific IP number as your address.
2183 10.0.0.1/0 would be appropriate.
2184 The bit after the / specifies how many bits of the
2185 address you consider to be important, so if you wanted to insist on
2186 something in the class C network 1.2.3.0, you could specify 1.2.3.1/24.
2188 If you find that your ISP accepts the first IP number that you suggest,
2189 specify third and forth arguments of
2191 This will force your ISP to assign a number.
2192 (The third argument will
2193 be ignored as it is less restrictive than the default mask for your
2197 An example for a connection where you don't know your IP number or your
2198 ISPs IP number would be:
2199 .Bd -literal -offset indent
2200 set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0
2204 In most cases, your ISP will also be your default router.
2205 If this is the case, add the line
2206 .Bd -literal -offset indent
2211 .Pa /etc/ppp/ppp.conf
2213 .Pa /etc/ppp/ppp.linkup
2214 for setups that don't use
2220 to add a default route to whatever the peer address is
2221 (10.0.0.2 in this example).
2224 meaning that should the value of
2226 change, the route will be updated accordingly.
2228 If your provider requests that you use PAP/CHAP authentication methods, add
2229 the next lines to your
2230 .Pa /etc/ppp/ppp.conf
2232 .Bd -literal -offset indent
2234 set authkey MyPassword
2237 Both are accepted by default, so
2239 will provide whatever your ISP requires.
2241 It should be noted that a login script is rarely (if ever) required
2242 when PAP or CHAP are in use.
2244 Ask your ISP to authenticate your nameserver address(es) with the line
2245 .Bd -literal -offset indent
2251 do this if you are running a local DNS unless you also either use
2256 .Pa /etc/ppp/ppp.linkdown ,
2259 will simply circumvent its use by entering some nameserver lines in
2260 .Pa /etc/resolv.conf .
2264 .Pa /usr/share/examples/ppp/ppp.conf.sample
2266 .Pa /usr/share/examples/ppp/ppp.linkup.sample
2267 for some real examples.
2268 The pmdemand label should be appropriate for most ISPs.
2269 .Sh LOGGING FACILITY
2271 is able to generate the following log info either via
2273 or directly to the screen:
2275 .Bl -tag -width XXXXXXXXX -offset XXX -compact
2277 Enable all logging facilities.
2278 This generates a lot of log.
2279 The most common use of 'all' is as a basis, where you remove some facilities
2280 after enabling 'all' ('debug' and 'timer' are usually best disabled.)
2282 Dump async level packet in hex.
2284 Generate CBCP (CallBack Control Protocol) logs.
2286 Generate a CCP packet trace.
2294 chat script trace logs.
2296 Log commands executed either from the command line or any of the configuration
2299 Log Chat lines containing the string "CONNECT".
2301 Log debug information.
2303 Log DNS QUERY packets.
2305 Log packets permitted by the dial filter and denied by any filter.
2307 Dump HDLC packet in hex.
2309 Log all function calls specifically made as user id 0.
2311 Generate an IPCP packet trace.
2313 Generate an LCP packet trace.
2315 Generate LQR reports.
2317 Phase transition log output.
2319 Dump physical level packet in hex.
2321 Dump sync level packet in hex.
2323 Dump all TCP/IP packets.
2325 Log timer manipulation.
2327 Include the tun device on each log line.
2329 Output to the terminal device.
2330 If there is currently no terminal,
2331 output is sent to the log file using syslogs
2334 Output to both the terminal device
2335 and the log file using syslogs
2338 Output to the log file using
2344 command allows you to set the logging output level.
2345 Multiple levels can be specified on a single command line.
2346 The default is equivalent to
2349 It is also possible to log directly to the screen.
2350 The syntax is the same except that the word
2352 should immediately follow
2356 (i.e., only the un-maskable warning, error and alert output).
2358 If The first argument to
2359 .Dq set log Op local
2364 character, the current log levels are
2365 not cleared, for example:
2366 .Bd -literal -offset indent
2367 PPP ON awfulhak> set log phase
2368 PPP ON awfulhak> show log
2369 Log: Phase Warning Error Alert
2370 Local: Warning Error Alert
2371 PPP ON awfulhak> set log +tcp/ip -warning
2372 PPP ON awfulhak> set log local +command
2373 PPP ON awfulhak> show log
2374 Log: Phase TCP/IP Warning Error Alert
2375 Local: Command Warning Error Alert
2378 Log messages of level Warning, Error and Alert are not controllable
2380 .Dq set log Op local .
2384 level is special in that it will not be logged if it can be displayed
2388 deals with the following signals:
2389 .Bl -tag -width "USR2"
2391 Receipt of this signal causes the termination of the current connection
2395 to exit unless it is in
2400 .It HUP, TERM & QUIT
2407 to re-open any existing server socket, dropping all existing diagnostic
2409 Sockets that couldn't previously be opened will be retried.
2413 to close any existing server socket, dropping all existing diagnostic
2416 can still be used to re-open the socket.
2419 If you wish to use more than one physical link to connect to a
2421 peer, that peer must also understand the
2424 Refer to RFC 1990 for specification details.
2426 The peer is identified using a combination of his
2427 .Dq endpoint discriminator
2429 .Dq authentication id .
2430 Either or both of these may be specified.
2431 It is recommended that
2432 at least one is specified, otherwise there is no way of ensuring that
2433 all links are actually connected to the same peer program, and some
2434 confusing lock-ups may result.
2435 Locally, these identification variables are specified using the
2444 must be agreed in advance with the peer.
2446 Multi-link capabilities are enabled using the
2448 command (set maximum reconstructed receive unit).
2449 Once multi-link is enabled,
2451 will attempt to negotiate a multi-link connection with the peer.
2453 By default, only one
2458 To create more links, the
2461 This command will clone existing links, where all
2462 characteristics are the same except:
2465 The new link has its own name as specified on the
2472 Its mode may subsequently be changed using the
2476 The new link is in a
2481 A summary of all available links can be seen using the
2485 Once a new link has been created, command usage varies.
2486 All link specific commands must be prefixed with the
2488 command, specifying on which link the command is to be applied.
2489 When only a single link is available,
2491 is smart enough not to require the
2495 Some commands can still be used without specifying a link - resulting
2496 in an operation at the
2499 For example, once two or more links are available, the command
2501 will show CCP configuration and statistics at the multi-link level, and
2502 .Dq link deflink show ccp
2503 will show the same information at the
2507 Armed with this information, the following configuration might be used:
2508 .Bd -literal -offset indent
2512 set device /dev/cuaa0 /dev/cuaa1 /dev/cuaa2
2513 set phone "123456789"
2514 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \\"\\" ATZ \e
2515 OK-AT-OK \\\\dATDT\\\\T TIMEOUT 45 CONNECT"
2517 set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0
2519 set authkey ppppassword
2522 clone 1,2,3 # Create 3 new links - duplicates of the default
2523 link deflink remove # Delete the default link (called ``deflink'')
2526 Note how all cloning is done at the end of the configuration.
2527 Usually, the link will be configured first, then cloned.
2528 If you wish all links
2529 to be up all the time, you can add the following line to the end of your
2531 .Bd -literal -offset indent
2532 link 1,2,3 set mode ddial
2535 If you want the links to dial on demand, this command could be used:
2536 .Bd -literal -offset indent
2537 link * set mode auto
2540 Links may be tied to specific names by removing the
2542 line above, and specifying the following after the
2545 .Bd -literal -offset indent
2546 link 1 set device /dev/cuaa0
2547 link 2 set device /dev/cuaa1
2548 link 3 set device /dev/cuaa2
2553 command to see which commands require context (using the
2555 command), which have optional
2556 context and which should not have any context.
2562 mode with the peer, it creates a local domain socket in the
2565 This socket is used to pass link information (including
2566 the actual link file descriptor) between different
2571 ability to be run from a
2577 capability), without needing to have initial control of the serial
2581 negotiates multi-link mode, it will pass its open link to any
2582 already running process.
2583 If there is no already running process,
2585 will act as the master, creating the socket and listening for new
2587 .Sh PPP COMMAND LIST
2588 This section lists the available commands and their effect.
2589 They are usable either from an interactive
2591 session, from a configuration file or from a
2597 .It accept|deny|enable|disable Ar option....
2598 These directives tell
2600 how to negotiate the initial connection with the peer.
2603 has a default of either accept or deny and enable or disable.
2605 means that the option will be ACK'd if the peer asks for it.
2607 means that the option will be NAK'd if the peer asks for it.
2609 means that the option will be requested by us.
2611 means that the option will not be requested by us.
2614 may be one of the following:
2617 Default: Enabled and Accepted.
2618 ACFComp stands for Address and Control Field Compression.
2619 Non LCP packets will usually have an address
2620 field of 0xff (the All-Stations address) and a control field of
2621 0x03 (the Unnumbered Information command).
2623 negotiated, these two bytes are simply not sent, thus minimising
2630 Default: Disabled and Accepted.
2631 CHAP stands for Challenge Handshake Authentication Protocol.
2632 Only one of CHAP and PAP (below) may be negotiated.
2633 With CHAP, the authenticator sends a "challenge" message to its peer.
2634 The peer uses a one-way hash function to encrypt the
2635 challenge and sends the result back.
2636 The authenticator does the same, and compares the results.
2637 The advantage of this mechanism is that no
2638 passwords are sent across the connection.
2639 A challenge is made when the connection is first made.
2640 Subsequent challenges may occur.
2641 If you want to have your peer authenticate itself, you must
2644 .Pa /etc/ppp/ppp.conf ,
2645 and have an entry in
2646 .Pa /etc/ppp/ppp.secret
2649 When using CHAP as the client, you need only specify
2654 .Pa /etc/ppp/ppp.conf .
2655 CHAP is accepted by default.
2658 implementations use "MS-CHAP" rather than MD5 when encrypting the
2660 MS-CHAP is a combination of MD4 and DES.
2663 was built on a machine with DES libraries available, it will respond
2664 to MS-CHAP authentication requests, but will never request them.
2666 Default: Enabled and Accepted.
2667 This option decides if deflate
2668 compression will be used by the Compression Control Protocol (CCP).
2669 This is the same algorithm as used by the
2672 Note: There is a problem negotiating
2678 implementation available under many operating systems.
2680 (version 2.3.1) incorrectly attempts to negotiate
2682 compression using type
2684 as the CCP configuration type rather than type
2690 is actually specified as
2691 .Dq PPP Magna-link Variable Resource Compression
2695 is capable of negotiating with
2702 .Ar accept Ns No ed .
2704 Default: Disabled and Denied.
2705 This is a variance of the
2707 option, allowing negotiation with the
2712 section above for details.
2713 It is disabled by default as it violates
2716 Default: Disabled and Denied.
2717 This option allows DNS negotiation.
2722 will request that the peer confirms the entries in
2723 .Pa /etc/resolv.conf .
2724 If the peer NAKs our request (suggesting new IP numbers),
2725 .Pa /etc/resolv.conf
2726 is updated and another request is sent to confirm the new entries.
2729 .Dq accept Ns No ed,
2731 will answer any DNS queries requested by the peer rather than rejecting
2733 The answer is taken from
2734 .Pa /etc/resolv.conf
2737 command is used as an override.
2739 Default: Enabled and Accepted.
2740 This option allows control over whether we
2741 negotiate an endpoint discriminator.
2742 We only send our discriminator if
2747 We reject the peers discriminator if
2751 Default: Disabled and Accepted.
2752 The use of this authentication protocol
2753 is discouraged as it partially violates the authentication protocol by
2754 implementing two different mechanisms (LANMan & NT) under the guise of
2755 a single CHAP type (0x80).
2757 uses a simple DES encryption mechanism and is the least secure of the
2758 CHAP alternatives (although is still more secure than PAP).
2762 description below for more details.
2764 Default: Disabled and Accepted.
2765 This option decides if Link Quality Requests will be sent or accepted.
2766 LQR is a protocol that allows
2768 to determine that the link is down without relying on the modems
2770 When LQR is enabled,
2776 below) as part of the LCP request.
2777 If the peer agrees, both sides will
2778 exchange LQR packets at the agreed frequency, allowing detailed link
2779 quality monitoring by enabling LQM logging.
2780 If the peer doesn't agree,
2782 will send ECHO LQR requests instead.
2783 These packets pass no information of interest, but they
2785 be replied to by the peer.
2787 Whether using LQR or ECHO LQR,
2789 will abruptly drop the connection if 5 unacknowledged packets have been
2790 sent rather than sending a 6th.
2791 A message is logged at the
2793 level, and any appropriate
2795 values are honoured as if the peer were responsible for dropping the
2798 Default: Enabled and Accepted.
2799 This is Microsoft Point to Point Encryption scheme.
2800 MPPE key size can be
2801 40-, 56- and 128-bits.
2806 Default: Disabled and Accepted.
2807 It is very similar to standard CHAP (type 0x05)
2808 except that it issues challenges of a fixed 16 bytes in length and uses a
2809 combination of MD4, SHA-1 and DES to encrypt the challenge rather than using the
2810 standard MD5 mechanism.
2812 Default: Disabled and Accepted.
2813 The use of this authentication protocol
2814 is discouraged as it partially violates the authentication protocol by
2815 implementing two different mechanisms (LANMan & NT) under the guise of
2816 a single CHAP type (0x80).
2817 It is very similar to standard CHAP (type 0x05)
2818 except that it issues challenges of a fixed 8 bytes in length and uses a
2819 combination of MD4 and DES to encrypt the challenge rather than using the
2820 standard MD5 mechanism.
2821 CHAP type 0x80 for LANMan is also supported - see
2829 use CHAP type 0x80, when acting as authenticator with both
2830 .Dq enable Ns No d ,
2832 will rechallenge the peer up to three times if it responds using the wrong
2833 one of the two protocols.
2834 This gives the peer a chance to attempt using both protocols.
2838 acts as the authenticatee with both protocols
2839 .Dq accept Ns No ed ,
2840 the protocols are used alternately in response to challenges.
2842 Note: If only LANMan is enabled,
2844 (version 2.3.5) misbehaves when acting as authenticatee.
2846 the NT and the LANMan answers, but also suggests that only the NT answer
2849 Default: Disabled and Accepted.
2850 PAP stands for Password Authentication Protocol.
2851 Only one of PAP and CHAP (above) may be negotiated.
2852 With PAP, the ID and Password are sent repeatedly to the peer until
2853 authentication is acknowledged or the connection is terminated.
2854 This is a rather poor security mechanism.
2855 It is only performed when the connection is first established.
2856 If you want to have your peer authenticate itself, you must
2859 .Pa /etc/ppp/ppp.conf ,
2860 and have an entry in
2861 .Pa /etc/ppp/ppp.secret
2862 for the peer (although see the
2868 When using PAP as the client, you need only specify
2873 .Pa /etc/ppp/ppp.conf .
2874 PAP is accepted by default.
2876 Default: Enabled and Accepted.
2877 This option decides if Predictor 1
2878 compression will be used by the Compression Control Protocol (CCP).
2880 Default: Enabled and Accepted.
2881 This option is used to negotiate
2882 PFC (Protocol Field Compression), a mechanism where the protocol
2883 field number is reduced to one octet rather than two.
2885 Default: Enabled and Accepted.
2886 This option determines if
2888 will request and accept requests for short
2890 sequence numbers when negotiating multi-link mode.
2891 This is only applicable if our MRRU is set (thus enabling multi-link).
2893 Default: Enabled and Accepted.
2894 This option determines if Van Jacobson header compression will be used.
2897 The following options are not actually negotiated with the peer.
2898 Therefore, accepting or denying them makes no sense.
2900 .It filter-decapsulation
2902 When this option is enabled,
2904 will examine UDP frames to see if they actually contain a
2906 frame as their payload.
2907 If this is the case, all filters will operate on the payload rather
2908 than the actual packet.
2910 This is useful if you want to send PPPoUDP traffic over a
2912 link, but want that link to do smart things with the real data rather than
2915 The UDP frame payload must not be compressed in any way, otherwise
2917 will not be able to interpret it.
2918 It's therefore recommended that you
2919 .Ic disable vj pred1 deflate
2921 .Ic deny vj pred1 deflate
2922 in the configuration for the
2924 invocation with the udp link.
2929 exchanges low-level LCP, CCP and IPCP configuration traffic, the
2931 field of any replies is expected to be the same as that of the request.
2934 drops any reply packets that do not contain the expected identifier
2935 field, reporting the fact at the respective log level.
2940 will ignore the identifier field.
2945 This option simply tells
2947 to add new interface addresses to the interface rather than replacing them.
2948 The option can only be enabled if network address translation is enabled
2949 .Pq Dq nat enable yes .
2951 With this option enabled,
2953 will pass traffic for old interface addresses through the NAT
2954 ifdef({LOCALNAT},{engine,},{engine
2956 .Xr libalias 3 ) ,})
2957 resulting in the ability (in
2959 mode) to properly connect the process that caused the PPP link to
2960 come up in the first place.
2970 to attempt to negotiate IP control protocol capabilities and if
2971 successful to exchange IP datagrams with the peer.
2976 to attempt to negotiate IPv6 control protocol capabilities and if
2977 successful to exchange IPv6 datagrams with the peer.
2982 runs as a Multi-link server, a different
2984 instance initially receives each connection.
2985 After determining that
2986 the link belongs to an already existing bundle (controlled by another
2990 will transfer the link to that process.
2992 If the link is a tty device or if this option is enabled,
2994 will not exit, but will change its process name to
2996 and wait for the controlling
2998 to finish with the link and deliver a signal back to the idle process.
2999 This prevents the confusion that results from
3001 parent considering the link resource available again.
3003 For tty devices that have entries in
3005 this is necessary to prevent another
3007 from being started, and for program links such as
3011 from exiting due to the death of its child.
3014 cannot determine its parents requirements (except for the tty case), this
3015 option must be enabled manually depending on the circumstances.
3022 will automatically loop back packets being sent
3023 out with a destination address equal to that of the
3028 will send the packet, probably resulting in an ICMP redirect from
3030 It is convenient to have this option enabled when
3031 the interface is also the default route as it avoids the necessity
3032 of a loopback route.
3035 Enabling this option will tell the PAP authentication
3036 code to use the password database (see
3038 to authenticate the caller if they cannot be found in the
3039 .Pa /etc/ppp/ppp.secret
3041 .Pa /etc/ppp/ppp.secret
3042 is always checked first.
3043 If you wish to use passwords from
3045 but also to specify an IP number or label for a given client, use
3047 as the client password in
3048 .Pa /etc/ppp/ppp.secret .
3051 Enabling this option will tell
3053 to proxy ARP for the peer.
3056 will make an entry in the ARP table using
3060 address of the local network in which
3063 This allows other machines connected to the LAN to talk to
3064 the peer as if the peer itself was connected to the LAN.
3065 The proxy entry cannot be made unless
3067 is an address from a LAN.
3070 Enabling this will tell
3072 to add proxy arp entries for every IP address in all class C or
3073 smaller subnets routed via the tun interface.
3075 Proxy arp entries are only made for sticky routes that are added
3079 No proxy arp entries are made for the interface address itself
3087 command is used with the
3093 values, entries are stored in the
3096 Each time these variables change, this list is re-applied to the routing table.
3098 Disabling this option will prevent the re-application of sticky routes,
3101 list will still be maintained.
3108 to adjust TCP SYN packets so that the maximum receive segment
3109 size is not greater than the amount allowed by the interface MTU.
3114 to gather throughput statistics.
3115 Input and output is sampled over
3116 a rolling 5 second window, and current, best and total figures are retained.
3117 This data is output when the relevant
3119 layer shuts down, and is also available using the
3122 Throughput statistics are available at the
3129 Normally, when a user is authenticated using PAP or CHAP, and when
3133 mode, an entry is made in the utmp and wtmp files for that user.
3134 Disabling this option will tell
3136 not to make any utmp or wtmp entries.
3137 This is usually only necessary if
3138 you require the user to both login and authenticate themselves.
3143 .Ar dest Ns Op / Ns Ar nn
3148 is the destination IP address.
3149 The netmask is specified either as a number of bits with
3151 or as an IP number using
3156 with no mask refers to the default route.
3157 It is also possible to use the literal name
3162 is the next hop gateway to get to the given
3167 command for further details.
3169 It is possible to use the symbolic names
3175 as the destination, and
3182 is replaced with the interface IP address,
3184 is replaced with the interface IP destination (peer) address,
3186 is replaced with the interface IPv6 address, and
3188 is replaced with the interface IPv6 destination address,
3195 then if the route already exists, it will be updated as with the
3199 for further details).
3201 Routes that contain the
3209 constants are considered
3211 They are stored in a list (use
3213 to see the list), and each time the value of one of these variables
3214 changes, the appropriate routing table entries are updated.
3215 This facility may be disabled using
3216 .Dq disable sroutes .
3217 .It allow Ar command Op Ar args
3218 This command controls access to
3220 and its configuration files.
3221 It is possible to allow user-level access,
3222 depending on the configuration file label and on the mode that
3225 For example, you may wish to configure
3235 User id 0 is immune to these commands.
3237 .It allow user Ns Xo
3239 .Ar logname Ns No ...
3241 By default, only user id 0 is allowed access to
3243 If this command is used, all of the listed users are allowed access to
3244 the section in which the
3249 section is always checked first (even though it is only ever automatically
3252 commands are cumulative in a given section, but users allowed in any given
3253 section override users allowed in the default section, so it's possible to
3254 allow users access to everything except a given label by specifying default
3257 section, and then specifying a new user list for that label.
3261 is specified, access is allowed to all users.
3262 .It allow mode Ns Xo
3266 By default, access using any
3269 If this command is used, it restricts the access
3271 allowed to load the label under which this command is specified.
3276 command overrides any previous settings, and the
3278 section is always checked first.
3290 When running in multi-link mode, a section can be loaded if it allows
3292 of the currently existing line modes.
3295 .It nat Ar command Op Ar args
3296 This command allows the control of the network address translation (also
3297 known as masquerading or IP aliasing) facilities that are built into
3299 NAT is done on the external interface only, and is unlikely to make sense
3304 If nat is enabled on your system (it may be omitted at compile time),
3305 the following commands are possible:
3307 .It nat enable yes|no
3308 This command either switches network address translation on or turns it off.
3311 command line flag is synonymous with
3312 .Dq nat enable yes .
3313 .It nat addr Op Ar addr_local addr_alias
3314 This command allows data for
3318 It is useful if you own a small number of real IP numbers that
3319 you wish to map to specific machines behind your gateway.
3320 .It nat deny_incoming yes|no
3321 If set to yes, this command will refuse all incoming packets where an
3322 aliasing link doesn't already exist.
3323 ifdef({LOCALNAT},{},{Refer to the
3324 .Sx CONCEPTUAL BACKGROUND
3327 for a description of what an
3332 It should be noted under what circumstances an aliasing link is
3333 ifdef({LOCALNAT},{created.},{created by
3335 It may be necessary to further protect your network from outside
3336 connections using the
3342 This command gives a summary of available nat commands.
3344 This option causes various NAT statistics and information to
3345 be logged to the file
3346 .Pa /var/log/alias.log .
3347 .It nat port Ar proto Ar targetIP Ns Xo
3348 .No : Ns Ar targetPort Ns
3350 .No - Ns Ar targetPort
3353 .No - Ns Ar aliasPort
3354 .Oc Oo Ar remoteIP : Ns
3357 .No - Ns Ar remotePort
3361 This command causes incoming
3375 A range of port numbers may be specified as shown above.
3376 The ranges must be of the same size.
3380 is specified, only data coming from that IP number is redirected.
3384 (indicating any source port)
3385 or a range of ports the same size as the other ranges.
3387 This option is useful if you wish to run things like Internet phone on
3388 machines behind your gateway, but is limited in that connections to only
3389 one interior machine per source machine and target port are possible.
3390 .It nat proto Ar proto localIP Oo
3391 .Ar publicIP Op Ar remoteIP
3395 to redirect packets of protocol type
3399 to the internal address
3404 is specified, only packets destined for that address are matched,
3405 otherwise the default alias address is used.
3409 is specified, only packets matching that source address are matched,
3411 This command is useful for redirecting tunnel endpoints to an internal machine,
3414 .Dl nat proto ipencap 10.0.0.1
3415 .It "nat proxy cmd" Ar arg Ns No ...
3418 to proxy certain connections, redirecting them to a given server.
3419 ifdef({LOCALNAT},{},{Refer to the description of
3420 .Fn PacketAliasProxyRule
3423 for details of the available commands.
3425 .It nat punch_fw Op Ar base count
3428 to punch holes in the firewall for FTP or IRC DCC connections.
3429 This is done dynamically by installing temporary firewall rules which
3430 allow a particular connection (and only that connection) to go through
3432 The rules are removed once the corresponding connection terminates.
3436 rules starting from rule number
3438 will be used for punching firewall holes.
3439 The range will be cleared when the
3443 If no arguments are given, firewall punching is disabled.
3444 .It nat same_ports yes|no
3445 When enabled, this command will tell the network address translation engine to
3446 attempt to avoid changing the port number on outgoing packets.
3448 if you want to support protocols such as RPC and LPD which require
3449 connections to come from a well known port.
3450 .It nat target Op Ar address
3451 Set the given target address or clear it if no address is given.
3452 The target address is used
3453 ifdef({LOCALNAT},{},{by libalias })dnl
3454 to specify how to NAT incoming packets by default.
3455 If a target address is not set or if
3457 is given, packets are not altered and are allowed to route to the internal
3460 The target address may be set to
3463 ifdef({LOCALNAT},{all packets will be redirected},
3464 {libalias will redirect all packets})
3465 to the interface address.
3466 .It nat use_sockets yes|no
3467 When enabled, this option tells the network address translation engine to
3468 create a socket so that it can guarantee a correct incoming ftp data or
3470 .It nat unregistered_only yes|no
3471 Only alter outgoing packets with an unregistered source address.
3472 According to RFC 1918, unregistered source addresses
3473 are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16.
3476 These commands are also discussed in the file
3478 which comes with the source distribution.
3485 is executed in the background with the following words replaced:
3486 .Bl -tag -width COMPILATIONDATE
3488 This is replaced with the local
3494 .It Li COMPILATIONDATE
3495 This is replaced with the date on which
3499 These are replaced with the primary and secondary nameserver IP numbers.
3500 If nameservers are negotiated by IPCP, the values of these macros will change.
3502 This is replaced with the local endpoint discriminator value.
3507 This is replaced with the peers IP number.
3509 This is replaced with the peers IPv6 number.
3511 This is replaced with the name of the interface that's in use.
3513 This is replaced with the number of IP bytes received since the connection
3516 This is replaced with the number of IP bytes sent since the connection
3519 This is replaced with the number of IP packets received since the connection
3522 This is replaced with the number of IP packets sent since the connection
3525 This is replaced with the number of IPv6 bytes received since the connection
3527 .It Li IPV6OCTETSOUT
3528 This is replaced with the number of IPv6 bytes sent since the connection
3530 .It Li IPV6PACKETSIN
3531 This is replaced with the number of IPv6 packets received since the connection
3533 .It Li IPV6PACKETSOUT
3534 This is replaced with the number of IPv6 packets sent since the connection
3537 This is replaced with the last label name used.
3538 A label may be specified on the
3540 command line, via the
3548 This is replaced with the IP number assigned to the local interface.
3550 This is replaced with the IPv6 number assigned to the local interface.
3552 This is replaced with the number of bytes received since the connection
3555 This is replaced with the number of bytes sent since the connection
3558 This is replaced with the number of packets received since the connection
3561 This is replaced with the number of packets sent since the connection
3564 This is replaced with the value of the peers endpoint discriminator.
3566 This is replaced with the current process id.
3568 This is replaced with the name of the diagnostic socket.
3570 This is replaced with the bundle uptime in HH:MM:SS format.
3572 This is replaced with the username that has been authenticated with PAP or
3574 Normally, this variable is assigned only in -direct mode.
3575 This value is available irrespective of whether utmp logging is enabled.
3577 This is replaced with the current version number of
3581 These substitutions are also done by the
3588 If you wish to pause
3590 while the command executes, use the
3593 .It clear physical|ipcp|ipv6 Op current|overall|peak...
3594 Clear the specified throughput values at either the
3602 is specified, context must be given (see the
3605 If no second argument is given, all values are cleared.
3606 .It clone Ar name Ns Xo
3607 .Op \&, Ns Ar name Ns
3610 Clone the specified link, creating one or more new links according to the
3613 This command must be used from the
3615 command below unless you've only got a single link (in which case that
3616 link becomes the default).
3617 Links may be removed using the
3621 The default link name is
3623 .It close Op lcp|ccp Ns Op !\&
3624 If no arguments are given, the relevant protocol layers will be brought
3625 down and the link will be closed.
3628 is specified, the LCP layer is brought down, but
3630 will not bring the link offline.
3631 It is subsequently possible to use
3634 to talk to the peer machine if, for example, something like
3639 is specified, only the relevant compression layer is closed.
3642 is used, the compression layer will remain in the closed state, otherwise
3643 it will re-enter the STOPPED state, waiting for the peer to initiate
3644 further CCP negotiation.
3645 In any event, this command does not disconnect the user from
3656 This command deletes the route with the given
3663 all non-direct entries in the routing table for the current interface,
3666 entries are deleted.
3671 the default route is deleted.
3679 will not complain if the route does not already exist.
3680 .It dial|call Op Ar label Ns Xo
3683 This command is the equivalent of
3687 and is provided for backwards compatibility.
3688 .It down Op Ar lcp|ccp
3689 Bring the relevant layer down ungracefully, as if the underlying layer
3690 had become unavailable.
3691 It's not considered polite to use this command on
3692 a Finite State Machine that's in the OPEN state.
3694 supplied, the entire link is closed (or if no context is given, all links
3700 layer is terminated but the device is not brought offline and the link
3704 is specified, only the relevant compression layer(s) are terminated.
3705 .It help|? Op Ar command
3706 Show a list of available commands.
3709 is specified, show the usage string for that command.
3710 .It ident Op Ar text Ns No ...
3711 Identify the link to the peer using
3715 is empty, link identification is disabled.
3716 It is possible to use any of the words described for the
3721 command for details of when
3723 identifies itself to the peer.
3724 .It iface Ar command Op args
3725 This command is used to control the interface used by
3728 may be one of the following:
3732 .Ar addr Ns Op / Ns Ar bits
3743 combination to the interface.
3744 Instead of specifying
3748 (with no space between it and
3750 If the given address already exists, the command fails unless the
3752 is used - in which case the previous interface address entry is overwritten
3753 with the new one, allowing a change of netmask or peer address.
3764 .Dq 255.255.255.255 .
3765 This address (the broadcast address) is the only duplicate peer address that
3768 .It iface clear Op INET | INET6
3769 If this command is used while
3771 is in the OPENED state or while in
3773 mode, all addresses except for the NCP negotiated address are deleted
3777 is not in the OPENED state and is not in
3779 mode, all interface addresses are deleted.
3781 If the INET or INET6 arguments are used, only addresses for that address
3784 .It iface delete Ns Xo
3789 This command deletes the given
3794 is used, no error is given if the address isn't currently assigned to
3795 the interface (and no deletion takes place).
3797 Shows the current state and current addresses for the interface.
3798 It is much the same as running
3799 .Dq ifconfig INTERFACE .
3800 .It iface help Op Ar sub-command
3801 This command, when invoked without
3803 will show a list of possible
3805 sub-commands and a brief synopsis for each.
3808 only the synopsis for the given sub-command is shown.
3812 .Ar name Ns Op , Ns Ar name Ns
3813 .No ... Ar command Op Ar args
3815 This command may prefix any other command if the user wishes to
3816 specify which link the command should affect.
3817 This is only applicable after multiple links have been created in Multi-link
3823 specifies the name of an existing link.
3826 is a comma separated list,
3828 is executed on each link.
3834 is executed on all links.
3835 .It load Op Ar label Ns Xo
3858 will not attempt to make an immediate connection.
3859 .It log Ar word Ns No ...
3860 Send the given word(s) to the log file with the prefix
3862 Word substitutions are done as explained under the
3865 .It open Op lcp|ccp|ipcp
3866 This is the opposite of the
3869 All closed links are immediately brought up apart from second and subsequent
3871 links - these will come up based on the
3873 command that has been used.
3877 argument is used while the LCP layer is already open, LCP will be
3879 This allows various LCP options to be changed, after which
3881 can be used to put them into effect.
3882 After renegotiating LCP,
3883 any agreed authentication will also take place.
3887 argument is used, the relevant compression layer is opened.
3888 Again, if it is already open, it will be renegotiated.
3892 argument is used, the link will be brought up as normal, but if
3893 IPCP is already open, it will be renegotiated and the network
3894 interface will be reconfigured.
3896 It is probably not good practice to re-open the PPP state machines
3897 like this as it's possible that the peer will not behave correctly.
3900 however useful as a way of forcing the CCP or VJ dictionaries to be reset.
3902 Specify the password required for access to the full
3905 This password is required when connecting to the diagnostic port (see the
3916 logging is active, instead, the literal string
3922 is executed from the controlling connection or from a command file,
3923 ppp will exit after closing all connections.
3924 Otherwise, if the user
3925 is connected to a diagnostic socket, the connection is simply dropped.
3931 will exit despite the source of the command after closing all existing
3934 This command removes the given link.
3935 It is only really useful in multi-link mode.
3936 A link must be in the
3938 state before it is removed.
3939 .It rename|mv Ar name
3940 This command renames the given link to
3944 is already used by another link.
3946 The default link name is
3953 may make the log file more readable.
3954 .It resolv Ar command
3955 This command controls
3962 starts up, it loads the contents of this file into memory and retains this
3963 image for future use.
3965 is one of the following:
3966 .Bl -tag -width readonly
3969 .Pa /etc/resolv.conf
3975 will still attempt to negotiate nameservers with the peer, making the results
3981 This is the opposite of the
3986 .Pa /etc/resolv.conf
3988 This may be necessary if for example a DHCP client overwrote
3989 .Pa /etc/resolv.conf .
3992 .Pa /etc/resolv.conf
3993 with the version originally read at startup or with the last
3996 This is sometimes a useful command to put in the
3997 .Pa /etc/ppp/ppp.linkdown
4001 .Pa /etc/resolv.conf
4003 This command will work even if the
4005 command has been used.
4006 It may be useful as a command in the
4007 .Pa /etc/ppp/ppp.linkup
4008 file if you wish to defer updating
4009 .Pa /etc/resolv.conf
4010 until after other commands have finished.
4015 .Pa /etc/resolv.conf
4020 successfully negotiates a DNS.
4021 This is the opposite of the
4026 This option is not (yet) implemented.
4030 to identify itself to the peer.
4031 The link must be in LCP state or higher.
4032 If no identity has been set (via the
4038 When an identity has been set,
4040 will automatically identify itself when it sends or receives a configure
4041 reject, when negotiation fails or when LCP reaches the opened state.
4043 Received identification packets are logged to the LCP log (see
4045 for details) and are never responded to.
4050 This option allows the setting of any of the following variables:
4052 .It set accmap Ar hex-value
4053 ACCMap stands for Asynchronous Control Character Map.
4055 negotiated with the peer, and defaults to a value of 00000000 in hex.
4056 This protocol is required to defeat hardware that depends on passing
4057 certain characters from end to end (such as XON/XOFF etc).
4059 For the XON/XOFF scenario, use
4060 .Dq set accmap 000a0000 .
4061 .It set Op auth Ns Xo
4064 This sets the authentication key (or password) used in client mode
4065 PAP or CHAP negotiation to the given value.
4066 It also specifies the
4067 password to be used in the dial or login scripts in place of the
4069 sequence, preventing the actual password from being logged.
4074 logging is in effect,
4078 for security reasons.
4080 If the first character of
4082 is an exclamation mark
4085 treats the remainder of the string as a program that must be executed
4097 it is treated as a single literal
4099 otherwise, ignoring the
4102 is parsed as a program to execute in the same was as the
4104 command above, substituting special names in the same manner.
4107 will feed the program three lines of input, each terminated by a newline
4111 The host name as sent in the CHAP challenge.
4113 The challenge string as sent in the CHAP challenge.
4119 Two lines of output are expected:
4124 to be sent with the CHAP response.
4128 which is encrypted with the challenge and request id, the answer being sent
4129 in the CHAP response packet.
4134 in this manner, it's expected that the host challenge is a series of ASCII
4135 digits or characters.
4136 An encryption device or Secure ID card is usually
4137 required to calculate the secret appropriate for the given challenge.
4138 .It set authname Ar id
4139 This sets the authentication id used in client mode PAP or CHAP negotiation.
4143 mode with CHAP enabled,
4145 is used in the initial authentication challenge and should normally be set to
4146 the local machine name.
4148 .Ar min-percent max-percent period
4150 These settings apply only in multi-link mode and default to zero, zero and
4156 mode link is available, only the first link is made active when
4158 first reads data from the tun device.
4161 link will be opened only when the current bundle throughput is at least
4163 percent of the total bundle bandwidth for
4166 When the current bundle throughput decreases to
4168 percent or less of the total bundle bandwidth for
4172 link will be brought down as long as it's not the last active link.
4174 Bundle throughput is measured as the maximum of inbound and outbound
4177 The default values cause
4179 links to simply come up one at a time.
4181 Certain devices cannot determine their physical bandwidth, so it
4182 is sometimes necessary to use the
4184 command (described below) to make
4187 .It set bandwidth Ar value
4188 This command sets the connection bandwidth in bits per second.
4190 must be greater than zero.
4191 It is currently only used by the
4194 .It set callback Ar option Ns No ...
4195 If no arguments are given, callback is disabled, otherwise,
4199 mode, will accept) one of the given
4200 .Ar option Ns No s .
4201 In client mode, if an
4205 will request a different
4207 until no options remain at which point
4209 will terminate negotiations (unless
4211 is one of the specified
4215 will accept any of the given protocols - but the client
4217 request one of them.
4218 If you wish callback to be optional, you must {include}
4224 are as follows (in this order of preference):
4227 The callee is expected to decide the callback number based on
4231 is the callee, the number should be specified as the fifth field of
4233 .Pa /etc/ppp/ppp.secret .
4235 Microsoft's callback control protocol is used.
4240 If you wish to negotiate
4242 in client mode but also wish to allow the server to request no callback at
4243 CBCP negotiation time, you must specify both
4247 as callback options.
4249 .Ar number Ns Op , Ns Ar number Ns
4252 The caller specifies the
4258 should be either a comma separated list of allowable numbers or a
4260 meaning any number is permitted.
4263 is the caller, only a single number should be specified.
4265 Note, this option is very unsafe when used with a
4267 as a malicious caller can tell
4269 to call any (possibly international) number without first authenticating
4272 If the peer does not wish to do callback at all,
4274 will accept the fact and continue without callback rather than terminating
4276 This is required (in addition to one or more other callback
4277 options) if you wish callback to be optional.
4281 .No *| Ns Ar number Ns Oo
4282 .No , Ns Ar number Ns ...\& Oc
4283 .Op Ar delay Op Ar retry
4285 If no arguments are given, CBCP (Microsoft's CallBack Control Protocol)
4286 is disabled - ie, configuring CBCP in the
4288 command will result in
4290 requesting no callback in the CBCP phase.
4293 attempts to use the given phone
4294 .Ar number Ns No (s).
4299 will insist that the client uses one of these numbers, unless
4301 is used in which case the client is expected to specify the number.
4305 will attempt to use one of the given numbers (whichever it finds to
4306 be agreeable with the peer), or if
4310 will expect the peer to specify the number.
4312 .No off| Ns Ar seconds Ns Op !\&
4316 checks for the existence of carrier depending on the type of device
4317 that has been opened:
4318 .Bl -tag -width XXX -offset XXX
4319 .It Terminal Devices
4320 Carrier is checked one second after the login script is complete.
4323 assumes that this is because the device doesn't support carrier (which
4326 NULL-modem cables), logs the fact and stops checking
4329 As ptys don't support the
4331 ioctl, the tty device will switch all
4332 carrier detection off when it detects that the device is a pty.
4333 .It ISDN (i4b) Devices
4334 Carrier is checked once per second for 6 seconds.
4335 If it's not set after
4336 the sixth second, the connection attempt is considered to have failed and
4337 the device is closed.
4338 Carrier is always required for i4b devices.
4339 .It PPPoE (netgraph) Devices
4340 Carrier is checked once per second for 5 seconds.
4341 If it's not set after
4342 the fifth second, the connection attempt is considered to have failed and
4343 the device is closed.
4344 Carrier is always required for PPPoE devices.
4347 All other device types don't support carrier.
4348 Setting a carrier value will
4349 result in a warning when the device is opened.
4351 Some modems take more than one second after connecting to assert the carrier
4353 If this delay isn't increased, this will result in
4355 inability to detect when the link is dropped, as
4357 assumes that the device isn't asserting carrier.
4361 command overrides the default carrier behaviour.
4363 specifies the maximum number of seconds that
4365 should wait after the dial script has finished before deciding if
4366 carrier is available or not.
4372 will not check for carrier on the device, otherwise
4374 will not proceed to the login script until either carrier is detected
4377 has elapsed, at which point
4379 assumes that the device will not set carrier.
4381 If no arguments are given, carrier settings will go back to their default
4386 is followed immediately by an exclamation mark
4392 If carrier is not detected after
4394 seconds, the link will be disconnected.
4395 .It set choked Op Ar timeout
4396 This sets the number of seconds that
4398 will keep a choked output queue before dropping all pending output packets.
4401 is less than or equal to zero or if
4403 isn't specified, it is set to the default value of
4406 A choked output queue occurs when
4408 has read a certain number of packets from the local network for transmission,
4409 but cannot send the data due to link failure (the peer is busy etc.).
4411 will not read packets indefinitely.
4412 Instead, it reads up to
4418 packets in multi-link mode), then stops reading the network interface
4421 seconds have passed or at least one packet has been sent.
4425 seconds pass, all pending output packets are dropped.
4426 .It set ctsrts|crtscts on|off
4427 This sets hardware flow control.
4428 Hardware flow control is
4431 .It set deflate Ar out-winsize Op Ar in-winsize
4432 This sets the DEFLATE algorithms default outgoing and incoming window
4438 must be values between
4446 will insist that this window size is used and will not accept any other
4447 values from the peer.
4448 .It set dns Op Ar primary Op Ar secondary
4449 This command specifies DNS overrides for the
4454 command description above for details.
4455 This command does not affect the IP numbers requested using
4457 .It set device|line Xo
4460 This sets the device(s) to which
4462 will talk to the given
4465 All ISDN and serial device names are expected to begin with
4467 ISDN devices are usually called
4469 and serial devices are usually called
4476 it must either begin with an exclamation mark
4479 .No PPPoE: Ns Ar iface Ns Xo
4480 .Op \&: Ns Ar provider Ns
4484 enabled systems), or be of the format
4486 .Ar host : port Op /tcp|udp .
4489 If it begins with an exclamation mark, the rest of the device name is
4490 treated as a program name, and that program is executed when the device
4492 Standard input, output and error are fed back to
4494 and are read and written as if they were a regular device.
4497 .No PPPoE: Ns Ar iface Ns Xo
4498 .Op \&: Ns Ar provider Ns
4500 specification is given,
4502 will attempt to create a
4504 over Ethernet connection using the given
4512 will attempt to load it using
4514 If this fails, an external program must be used such as the
4516 program available under
4520 is passed as the service name in the PPPoE Discovery Initiation (PADI)
4522 If no provider is given, an empty value will be used.
4524 When a PPPoE connection is established,
4526 will place the name of the Access Concentrator in the environment variable
4533 for further details.
4536 .Ar host Ns No : Ns Ar port Ns Oo
4539 specification is given,
4541 will attempt to connect to the given
4549 suffix is not provided, the default is
4551 Refer to the section on
4552 .Em PPP OVER TCP and UDP
4553 above for further details.
4559 will attempt to open each one in turn until it succeeds or runs out of
4561 .It set dial Ar chat-script
4562 This specifies the chat script that will be used to dial the other
4569 and to the example configuration files for details of the chat script
4571 It is possible to specify some special
4573 in your chat script as follows:
4576 When used as the last character in a
4578 string, this indicates that a newline should not be appended.
4580 When the chat script encounters this sequence, it delays two seconds.
4582 When the chat script encounters this sequence, it delays for one quarter of
4585 This is replaced with a newline character.
4587 This is replaced with a carriage return character.
4589 This is replaced with a space character.
4591 This is replaced with a tab character.
4593 This is replaced by the current phone number (see
4597 This is replaced by the current
4603 This is replaced by the current
4610 Note that two parsers will examine these escape sequences, so in order to
4613 see the escape character, it is necessary to escape it from the
4614 .Sq command parser .
4615 This means that in practice you should use two escapes, for example:
4616 .Bd -literal -offset indent
4617 set dial "... ATDT\\\\T CONNECT"
4620 It is also possible to execute external commands from the chat script.
4621 To do this, the first character of the expect or send string is an
4624 If a literal exclamation mark is required, double it up to
4626 and it will be treated as a single literal
4628 When the command is executed, standard input and standard output are
4629 directed to the open device (see the
4631 command), and standard error is read by
4633 and substituted as the expect or send string.
4636 is running in interactive mode, file descriptor 3 is attached to
4639 For example (wrapped for readability):
4640 .Bd -literal -offset indent
4641 set login "TIMEOUT 5 \\"\\" \\"\\" login:--login: ppp \e
4642 word: ppp \\"!sh \\\\-c \\\\\\"echo \\\\-n label: >&2\\\\\\"\\" \e
4643 \\"!/bin/echo in\\" HELLO"
4646 would result in the following chat sequence (output using the
4647 .Sq set log local chat
4648 command before dialing):
4649 .Bd -literal -offset indent
4654 Chat: Expecting: login:--login:
4655 Chat: Wait for (5): login:
4657 Chat: Expecting: word:
4658 Chat: Wait for (5): word:
4660 Chat: Expecting: !sh \\-c "echo \\-n label: >&2"
4661 Chat: Exec: sh -c "echo -n label: >&2"
4662 Chat: Wait for (5): !sh \\-c "echo \\-n label: >&2" --> label:
4663 Chat: Exec: /bin/echo in
4665 Chat: Expecting: HELLO
4666 Chat: Wait for (5): HELLO
4670 Note (again) the use of the escape character, allowing many levels of
4672 Here, there are four parsers at work.
4673 The first parses the original line, reading it as three arguments.
4674 The second parses the third argument, reading it as 11 arguments.
4675 At this point, it is
4678 signs are escaped, otherwise this parser will see them as constituting
4679 an expect-send-expect sequence.
4682 character is seen, the execution parser reads the first command as three
4685 itself expands the argument after the
4687 As we wish to send the output back to the modem, in the first example
4688 we redirect our output to file descriptor 2 (stderr) so that
4690 itself sends and logs it, and in the second example, we just output to stdout,
4691 which is attached directly to the modem.
4693 This, of course means that it is possible to execute an entirely external
4695 command rather than using the internal one.
4698 for a good alternative.
4700 The external command that is executed is subjected to the same special
4701 word expansions as the
4704 .It set enddisc Op label|IP|MAC|magic|psn value
4705 This command sets our local endpoint discriminator.
4706 If set prior to LCP negotiation, and if no
4708 command has been used,
4710 will send the information to the peer using the LCP endpoint discriminator
4712 The following discriminators may be set:
4713 .Bl -tag -width indent
4715 The current label is used.
4717 Our local IP number is used.
4718 As LCP is negotiated prior to IPCP, it is
4719 possible that the IPCP layer will subsequently change this value.
4721 it does, the endpoint discriminator stays at the old value unless manually
4724 This is similar to the
4726 option above, except that the MAC address associated with the local IP
4728 If the local IP number is not resident on any Ethernet
4729 interface, the command will fail.
4731 As the local IP number defaults to whatever the machine host name is,
4733 is usually done prior to any
4737 A 20 digit random number is used.
4738 Care should be taken when using magic numbers as restarting
4740 or creating a link using a different
4742 invocation will also use a different magic number and will therefore not
4743 be recognised by the peer as belonging to the same bundle.
4744 This makes it unsuitable for
4752 should be set to an absolute public switched network number with the
4756 If no arguments are given, the endpoint discriminator is reset.
4757 .It set escape Ar value...
4758 This option is similar to the
4761 It allows the user to specify a set of characters that will be
4763 as they travel across the link.
4764 .It set filter dial|alive|in|out Ar rule-no Xo
4765 .No permit|deny|clear| Ns Ar rule-no
4768 .Ar src_addr Ns Op / Ns Ar width
4769 .Op Ar dst_addr Ns Op / Ns Ar width
4771 .Op src lt|eq|gt Ar port
4772 .Op dst lt|eq|gt Ar port
4776 .Op timeout Ar secs ]
4779 supports four filter sets.
4782 filter specifies packets that keep the connection alive - resetting the
4786 filter specifies packets that cause
4793 filter specifies packets that are allowed to travel
4794 into the machine and the
4796 filter specifies packets that are allowed out of the machine.
4798 Filtering is done prior to any IP alterations that might be done by the
4799 NAT engine on outgoing packets and after any IP alterations that might
4800 be done by the NAT engine on incoming packets.
4801 By default all empty filter sets allow all packets to pass.
4802 Rules are processed in order according to
4804 (unless skipped by specifying a rule number as the
4806 Up to 40 rules may be given for each set.
4807 If a packet doesn't match
4808 any of the rules in a given set, it is discarded.
4813 filters, this means that the packet is dropped.
4816 filters it means that the packet will not reset the idle timer (even if
4818 .Ar in Ns No / Ns Ar out
4821 value) and in the case of
4823 filters it means that the packet will not trigger a dial.
4824 A packet failing to trigger a dial will be dropped rather than queued.
4827 .Sx PACKET FILTERING
4828 above for further details.
4829 .It set hangup Ar chat-script
4830 This specifies the chat script that will be used to reset the device
4831 before it is closed.
4832 It should not normally be necessary, but can
4833 be used for devices that fail to reset themselves properly on close.
4834 .It set help|? Op Ar command
4835 This command gives a summary of available set commands, or if
4837 is specified, the command usage is shown.
4838 .It set ifaddr Oo Ar myaddr Ns
4840 .Oo Ar hisaddr Ns Op / Ns Ar \&nn
4845 This command specifies the IP addresses that will be used during
4847 Addresses are specified using the format
4853 is the preferred IP, but
4855 specifies how many bits of the address we will insist on.
4858 is omitted, it defaults to
4860 unless the IP address is 0.0.0.0 in which case it defaults to
4863 If you wish to assign a dynamic IP number to the peer,
4865 may also be specified as a range of IP numbers in the format
4866 .Bd -ragged -offset indent
4867 .Ar \&IP Ns Oo \&- Ns Ar \&IP Ns Xo
4868 .Oc Ns Oo , Ns Ar \&IP Ns
4869 .Op \&- Ns Ar \&IP Ns
4876 .Dl set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20
4880 as the local IP number, but may assign any of the given 10 IP
4881 numbers to the peer.
4882 If the peer requests one of these numbers,
4883 and that number is not already in use,
4885 will grant the peers request.
4886 This is useful if the peer wants
4887 to re-establish a link using the same IP number as was previously
4888 allocated (thus maintaining any existing tcp or udp connections).
4890 If the peer requests an IP number that's either outside
4891 of this range or is already in use,
4893 will suggest a random unused IP number from the range.
4897 is specified, it is used in place of
4899 in the initial IPCP negotiation.
4900 However, only an address in the
4902 range will be accepted.
4903 This is useful when negotiating with some
4905 implementations that will not assign an IP number unless their peer
4909 It should be noted that in
4913 will configure the interface immediately upon reading the
4915 line in the config file.
4916 In any other mode, these values are just
4917 used for IPCP negotiations, and the interface isn't configured
4918 until the IPCP layer is up.
4922 argument may be overridden by the third field in the
4924 file once the client has authenticated itself
4928 .Sx AUTHENTICATING INCOMING CONNECTIONS
4929 section for details.
4931 In all cases, if the interface is already configured,
4933 will try to maintain the interface IP numbers so that any existing
4934 bound sockets will remain valid.
4935 .It set ifqueue Ar packets
4936 Set the maximum number of packets that
4938 will read from the tunnel interface while data cannot be sent to any of
4939 the available links.
4940 This queue limit is necessary to flow control outgoing data as the tunnel
4941 interface is likely to be far faster than the combined links available to
4946 is set to a value less than the number of links,
4948 will read up to that value regardless.
4949 This prevents any possible latency problems.
4951 The default value for
4955 .It set ccpretry|ccpretries Oo Ar timeout
4956 .Op Ar reqtries Op Ar trmtries
4958 .It set chapretry|chapretries Oo Ar timeout
4961 .It set ipcpretry|ipcpretries Oo Ar timeout
4962 .Op Ar reqtries Op Ar trmtries
4964 .It set ipv6cpretry|ipv6cpretries Oo Ar timeout
4965 .Op Ar reqtries Op Ar trmtries
4967 .It set lcpretry|lcpretries Oo Ar timeout
4968 .Op Ar reqtries Op Ar trmtries
4970 .It set papretry|papretries Oo Ar timeout
4973 These commands set the number of seconds that
4975 will wait before resending Finite State Machine (FSM) Request packets.
4978 for all FSMs is 3 seconds (which should suffice in most cases).
4982 is specified, it tells
4984 how many configuration request attempts it should make while receiving
4985 no reply from the peer before giving up.
4986 The default is 5 attempts for
4987 CCP, LCP and IPCP and 3 attempts for PAP and CHAP.
4991 is specified, it tells
4993 how many terminate requests should be sent before giving up waiting for the
4995 The default is 3 attempts.
4996 Authentication protocols are
4997 not terminated and it is therefore invalid to specify
5001 In order to avoid negotiations with the peer that will never converge,
5003 will only send at most 3 times the configured number of
5005 in any given negotiation session before giving up and closing that layer.
5011 This command allows the adjustment of the current log level.
5012 Refer to the Logging Facility section for further details.
5013 .It set login Ar chat-script
5016 complements the dial-script.
5017 If both are specified, the login
5018 script will be executed after the dial script.
5019 Escape sequences available in the dial script are also available here.
5020 .It set logout Ar chat-script
5021 This specifies the chat script that will be used to logout
5022 before the hangup script is called.
5023 It should not normally be necessary.
5024 .It set lqrperiod Ar frequency
5025 This command sets the
5032 The default is 30 seconds.
5033 You must also use the
5035 command if you wish to send LQR requests to the peer.
5036 .It set mode Ar interactive|auto|ddial|background
5037 This command allows you to change the
5039 of the specified link.
5040 This is normally only useful in multi-link mode,
5041 but may also be used in uni-link mode.
5043 It is not possible to change a link that is
5048 Note: If you issue the command
5050 and have network address translation enabled, it may be useful to
5051 .Dq enable iface-alias
5055 to do the necessary address translations to enable the process that
5056 triggers the connection to connect once the link is up despite the
5057 peer assigning us a new (dynamic) IP address.
5058 .It set mppe Op 40|56|128|* Op stateless|stateful|*
5059 This option selects the encryption parameters used when negotiation
5061 MPPE can be disabled entirely with the
5064 If no arguments are given,
5066 will attempt to negotiate a stateful link with a 128 bit key, but
5067 will agree to whatever the peer requests (including no encryption
5070 If any arguments are given,
5074 on using MPPE and will close the link if it's rejected by the peer (Note;
5075 this behaviour can be overridden by a configured RADIUS server).
5077 The first argument specifies the number of bits that
5079 should insist on during negotiations and the second specifies whether
5081 should insist on stateful or stateless mode.
5082 In stateless mode, the
5083 encryption dictionary is re-initialised with every packet according to
5084 an encryption key that is changed with every packet.
5086 the encryption dictionary is re-initialised every 256 packets or after
5087 the loss of any data and the key is changed every 256 packets.
5088 Stateless mode is less efficient but is better for unreliable transport
5090 .It set mrru Op Ar value
5091 Setting this option enables Multi-link PPP negotiations, also known as
5092 Multi-link Protocol or MP.
5093 There is no default MRRU (Maximum Reconstructed Receive Unit) value.
5094 If no argument is given, multi-link mode is disabled.
5099 The default MRU (Maximum Receive Unit) is 1500.
5100 If it is increased, the other side *may* increase its MTU.
5101 In theory there is no point in decreasing the MRU to below the default as the
5103 protocol says implementations *must* be able to accept packets of at
5110 will refuse to negotiate a higher value.
5111 The maximum MRU can be set to 2048 at most.
5112 Setting a maximum of less than 1500 violates the
5114 rfc, but may sometimes be necessary.
5117 imposes a maximum of 1492 due to hardware limitations.
5119 If no argument is given, 1500 is assumed.
5120 A value must be given when
5127 The default MTU is 1500.
5128 At negotiation time,
5130 will accept whatever MRU the peer requests (assuming it's
5131 not less than 296 bytes or greater than the assigned maximum).
5134 will not accept MRU values less than
5136 When negotiations are complete, the MTU is used when writing to the
5137 interface, even if the peer requested a higher value MRU.
5138 This can be useful for
5139 limiting your packet size (giving better bandwidth sharing at the expense
5140 of more header data).
5146 will refuse to negotiate a higher value.
5147 The maximum MTU can be set to 2048 at most.
5151 is given, 1500, or whatever the peer asks for is used.
5152 A value must be given when
5155 .It set nbns Op Ar x.x.x.x Op Ar y.y.y.y
5156 This option allows the setting of the Microsoft NetBIOS name server
5157 values to be returned at the peers request.
5158 If no values are given,
5160 will reject any such requests.
5161 .It set openmode active|passive Op Ar delay
5170 will always initiate LCP/IPCP/CCP negotiation one second after the line
5172 If you want to wait for the peer to initiate negotiations, you
5175 If you want to initiate negotiations immediately or after more than one
5176 second, the appropriate
5178 may be specified here in seconds.
5179 .It set parity odd|even|none|mark
5180 This allows the line parity to be set.
5181 The default value is
5183 .It set phone Ar telno Ns Xo
5184 .Oo \&| Ns Ar backupnumber
5185 .Oc Ns ... Ns Oo : Ns Ar nextnumber
5188 This allows the specification of the phone number to be used in
5189 place of the \\\\T string in the dial and login chat scripts.
5190 Multiple phone numbers may be given separated either by a pipe
5195 Numbers after the pipe are only dialed if the dial or login
5196 script for the previous number failed.
5198 Numbers after the colon are tried sequentially, irrespective of
5199 the reason the line was dropped.
5201 If multiple numbers are given,
5203 will dial them according to these rules until a connection is made, retrying
5204 the maximum number of times specified by
5209 mode, each number is attempted at most once.
5210 .It set Op proc Ns Xo
5211 .No title Op Ar value
5213 The current process title as displayed by
5215 is changed according to
5219 is not specified, the original process title is restored.
5221 word replacements done by the shell commands (see the
5223 command above) are done here too.
5225 Note, if USER is required in the process title, the
5227 command must appear in
5229 as it is not known when the commands in
5232 .It set radius Op Ar config-file
5233 This command enables RADIUS support (if it's compiled in).
5235 refers to the radius client configuration file as described in
5237 If PAP, CHAP, MSCHAP or MSCHAPv2 are
5238 .Dq enable Ns No d ,
5241 .Em \&N Ns No etwork
5244 and uses the configured RADIUS server to authenticate rather than
5245 authenticating from the
5247 file or from the passwd database.
5249 If none of PAP, CHAP, MSCHAP or MSCHAPv2 are enabled,
5254 uses the following attributes from the RADIUS reply:
5255 .Bl -tag -width XXX -offset XXX
5256 .It RAD_FRAMED_IP_ADDRESS
5257 The peer IP address is set to the given value.
5258 .It RAD_FRAMED_IP_NETMASK
5259 The tun interface netmask is set to the given value.
5261 If the given MTU is less than the peers MRU as agreed during LCP
5262 negotiation, *and* it is less that any configured MTU (see the
5264 command), the tun interface MTU is set to the given value.
5265 .It RAD_FRAMED_COMPRESSION
5266 If the received compression type is
5269 will request VJ compression during IPCP negotiations despite any
5271 configuration command.
5273 If this attribute is supplied,
5275 will attempt to use it as an additional label to load from the
5280 The load will be attempted before (and in addition to) the normal
5282 If the label doesn't exist, no action is taken and
5284 proceeds to the normal load using the current label.
5285 .It RAD_FRAMED_ROUTE
5286 The received string is expected to be in the format
5287 .Ar dest Ns Op / Ns Ar bits
5290 Any specified metrics are ignored.
5294 are understood as valid values for
5301 to specify the default route, and
5303 is understood to be the same as
5312 For example, a returned value of
5313 .Dq 1.2.3.4/24 0.0.0.0 1 2 -1 3 400
5314 would result in a routing table entry to the 1.2.3.0/24 network via
5316 and a returned value of
5320 would result in a default route to
5323 All RADIUS routes are applied after any sticky routes are applied, making
5324 RADIUS routes override configured routes.
5325 This also applies for RADIUS routes that don't {include} the
5331 .It RAD_SESSION_TIMEOUT
5332 If supplied, the client connection is closed after the given number of
5334 .It RAD_REPLY_MESSAGE
5335 If supplied, this message is passed back to the peer as the authentication
5337 .It RAD_MICROSOFT_MS_CHAP_ERROR
5339 .Dv RAD_VENDOR_MICROSOFT
5340 vendor specific attribute is supplied, it is passed back to the peer as the
5341 authentication FAILURE text.
5342 .It RAD_MICROSOFT_MS_CHAP2_SUCCESS
5344 .Dv RAD_VENDOR_MICROSOFT
5345 vendor specific attribute is supplied and if MS-CHAPv2 authentication is
5346 being used, it is passed back to the peer as the authentication SUCCESS text.
5347 .It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY
5349 .Dv RAD_VENDOR_MICROSOFT
5350 vendor specific attribute is supplied and has a value of 2 (Required),
5352 will insist that MPPE encryption is used (even if no
5354 configuration command has been given with arguments).
5355 If it is supplied with a value of 1 (Allowed), encryption is made optional
5358 configuration commands with arguments).
5359 .It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES
5361 .Dv RAD_VENDOR_MICROSOFT
5362 vendor specific attribute is supplied, bits 1 and 2 are examined.
5363 If either or both are set, 40 bit and/or 128 bit (respectively) encryption
5364 options are set, overriding any given first argument to the
5367 Note, it is not currently possible for the RADIUS server to specify 56 bit
5369 .It RAD_MICROSOFT_MS_MPPE_RECV_KEY
5371 .Dv RAD_VENDOR_MICROSOFT
5372 vendor specific attribute is supplied, it's value is used as the master
5373 key for decryption of incoming data. When clients are authenticated using
5374 MSCHAPv2, the RADIUS server MUST provide this attribute if inbound MPPE is
5376 .It RAD_MICROSOFT_MS_MPPE_SEND_KEY
5378 .Dv RAD_VENDOR_MICROSOFT
5379 vendor specific attribute is supplied, it's value is used as the master
5380 key for encryption of outgoing data. When clients are authenticated using
5381 MSCHAPv2, the RADIUS server MUST provide this attribute if outbound MPPE is
5385 Values received from the RADIUS server may be viewed using
5387 .It set reconnect Ar timeout ntries
5388 Should the line drop unexpectedly (due to loss of CD or LQR
5389 failure), a connection will be re-established after the given
5391 The line will be re-connected at most
5400 will result in a variable pause, somewhere between 1 and 30 seconds.
5401 .It set recvpipe Op Ar value
5402 This sets the routing table RECVPIPE value.
5403 The optimum value is just over twice the MTU value.
5406 is unspecified or zero, the default kernel controlled value is used.
5407 .It set redial Ar secs Ns Xo
5410 .Oc Ns Op . Ns Ar next
5414 can be instructed to attempt to redial
5417 If more than one phone number is specified (see
5421 is taken before dialing each number.
5424 is taken before starting at the first number again.
5427 may be used here in place of
5431 causing a random delay of between 1 and 30 seconds.
5435 is specified, its value is added onto
5441 will only be incremented at most
5449 delay will be effective, even after
5451 has been exceeded, so an immediate manual dial may appear to have
5453 If an immediate dial is required, a
5455 should immediately follow the
5460 description above for further details.
5461 .It set sendpipe Op Ar value
5462 This sets the routing table SENDPIPE value.
5463 The optimum value is just over twice the MTU value.
5466 is unspecified or zero, the default kernel controlled value is used.
5467 .It "set server|socket" Ar TcpPort Ns No \&| Ns Xo
5468 .Ar LocalName Ns No |none|open|closed
5469 .Op password Op Ar mask
5473 to listen on the given socket or
5475 for incoming command connections.
5481 to close any existing socket and clear the socket configuration.
5486 to attempt to re-open the port.
5491 to close the open port.
5493 If you wish to specify a local domain socket,
5495 must be specified as an absolute file name, otherwise it is assumed
5496 to be the name or number of a TCP port.
5497 You may specify the octal umask to be used with a local domain socket.
5503 for details of how to translate TCP port names.
5505 You must also specify the password that must be entered by the client
5508 variable above) when connecting to this socket.
5510 specified as an empty string, no password is required for connecting clients.
5512 When specifying a local domain socket, the first
5514 sequence found in the socket name will be replaced with the current
5515 interface unit number.
5516 This is useful when you wish to use the same
5517 profile for more than one connection.
5519 In a similar manner TCP sockets may be prefixed with the
5521 character, in which case the current interface unit number is added to
5526 with a server socket, the
5528 command is the preferred mechanism of communications.
5531 can also be used, but link encryption may be implemented in the future, so
5539 interact with the diagnostic socket.
5540 .It set speed Ar value
5541 This sets the speed of the serial device.
5542 If speed is specified as
5545 treats the device as a synchronous device.
5547 Certain device types will know whether they should be specified as
5548 synchronous or asynchronous.
5549 These devices will override incorrect
5550 settings and log a warning to this effect.
5551 .It set stopped Op Ar LCPseconds Op Ar CCPseconds
5552 If this option is set,
5554 will time out after the given FSM (Finite State Machine) has been in
5555 the stopped state for the given number of
5557 This option may be useful if the peer sends a terminate request,
5558 but never actually closes the connection despite our sending a terminate
5560 This is also useful if you wish to
5561 .Dq set openmode passive
5562 and time out if the peer doesn't send a Configure Request within the
5565 .Dq set log +lcp +ccp
5568 log the appropriate state transitions.
5570 The default value is zero, where
5572 doesn't time out in the stopped state.
5574 This value should not be set to less than the openmode delay (see
5577 .It set timeout Ar idleseconds Op Ar mintimeout
5578 This command allows the setting of the idle timer.
5579 Refer to the section titled
5580 .Sx SETTING THE IDLE TIMER
5581 for further details.
5587 will never idle out before the link has been up for at least that number
5595 This command controls the ports that
5597 prioritizes when transmitting data.
5598 The default priority TCP ports
5599 are ports 21 (ftp control), 22 (ssh), 23 (telnet), 513 (login), 514 (shell),
5600 543 (klogin) and 544 (kshell).
5601 There are no priority UDP ports by default.
5616 are given, the priority port lists are cleared (although if
5620 is specified, only that list is cleared).
5623 argument is prefixed with a plus
5627 the current list is adjusted, otherwise the list is reassigned.
5629 prefixed with a plus or not prefixed at all are added to the list and
5631 prefixed with a minus are removed from the list.
5635 is specified, all priority port lists are disabled and even
5637 packets are not prioritised.
5638 .It set vj slotcomp on|off
5641 whether it should attempt to negotiate VJ slot compression.
5642 By default, slot compression is turned
5644 .It set vj slots Ar nslots
5645 This command sets the initial number of slots that
5647 will try to negotiate with the peer when VJ compression is enabled (see the
5650 It defaults to a value of 16.
5659 .It shell|! Op Ar command
5662 is not specified a shell is invoked according to the
5664 environment variable.
5665 Otherwise, the given
5668 Word replacement is done in the same way as for the
5670 command as described above.
5672 Use of the ! character
5673 requires a following space as with any of the other commands.
5674 You should note that this command is executed in the foreground;
5676 will not continue running until this process has exited.
5679 command if you wish processing to happen in the background.
5681 This command allows the user to examine the following:
5684 Show the current bundle settings.
5686 Show the current CCP compression statistics.
5688 Show the current VJ compression statistics.
5690 Show the current escape characters.
5691 .It show filter Op Ar name
5692 List the current rules for the given filter.
5695 is not specified, all filters are shown.
5697 Show the current HDLC statistics.
5699 Give a summary of available show commands.
5701 Show the current interface information
5705 Show the current IPCP statistics.
5707 Show the protocol layers currently in use.
5709 Show the current LCP statistics.
5710 .It show Op data Ns Xo
5713 Show high level link information.
5715 Show a list of available logical links.
5717 Show the current log values.
5719 Show current memory statistics.
5721 Show the current NCP statistics.
5723 Show low level link information.
5725 Show Multi-link information.
5727 Show current protocol totals.
5729 Show the current routing tables.
5731 Show the current stopped timeouts.
5733 Show the active alarm timers.
5735 Show the current version number of
5740 Go into terminal mode.
5741 Characters typed at the keyboard are sent to the device.
5742 Characters read from the device are displayed on the screen.
5747 automatically enables Packet Mode and goes back into command mode.
5752 Read the example configuration files.
5753 They are a good source of information.
5762 to get online information about what's available.
5764 The following URLs contain useful information:
5765 .Bl -bullet -compact
5767 .Pa http://www.dragonflybsd.org/docs/handbook/handbook-userppp/
5772 refers to four files:
5778 These files are placed in the
5782 .It Pa /etc/ppp/ppp.conf
5783 System default configuration file.
5784 .It Pa /etc/ppp/ppp.secret
5785 An authorisation file for each system.
5786 .It Pa /etc/ppp/ppp.linkup
5787 A file to check when
5789 establishes a network level connection.
5790 .It Pa /etc/ppp/ppp.linkdown
5791 A file to check when
5793 closes a network level connection.
5794 .It Pa /var/log/ppp.log
5795 Logging and debugging information file.
5796 Note, this name is specified in
5797 .Pa /etc/syslog.conf .
5800 for further details.
5801 .It Pa /var/spool/lock/LCK..*
5802 tty port locking file.
5805 for further details.
5806 .It Pa /var/run/tunN.pid
5807 The process id (pid) of the
5809 program connected to the tunN device, where
5811 is the number of the device.
5812 .It Pa /var/run/ttyXX.if
5813 The tun interface used by this port.
5814 Again, this file is only created in
5820 .It Pa /etc/services
5821 Get port number if port number is using service name.
5822 .It Pa /var/run/ppp-authname-class-value
5823 In multi-link mode, local domain sockets are created using the peer
5826 the peer endpoint discriminator class
5828 and the peer endpoint discriminator value
5830 As the endpoint discriminator value may be a binary value, it is turned
5831 to HEX to determine the actual file name.
5833 This socket is used to pass links between different instances of
5845 ifdef({LOCALNAT},{},{.Xr libalias 3 ,
5847 ifdef({LOCALRAD},{},{.Xr libradius 3 ,
5877 This program was originally written by
5878 .An Toshiharu OHNO Aq tony-o@iij.ad.jp ,
5879 and was submitted to
5882 .An Atsushi Murai Aq amurai@spec.co.jp .
5884 It was substantially modified during 1997 by
5885 .An Brian Somers Aq brian@Awfulhak.org ,
5888 in November that year
5889 (just after the 2.2 release).
5891 Most of the code was rewritten by
5893 in early 1998 when multi-link ppp support was added.
projects / dragonfly.git / blob