2 .\" Copyright (c) 2001 Brian Somers <brian@Awfulhak.org>
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .Dd September 20, 1995
33 .Nd Point to Point Protocol (a.k.a. user-ppp)
42 This is a user process
47 is implemented as a part of the kernel (e.g., as managed by
49 and it's thus somewhat hard to debug and/or modify its behaviour.
50 However, in this implementation
52 is done as a user process with the help of the
53 tunnel device driver (tun).
57 flag does the equivalent of a
61 network address translation features.
64 to act as a NAT or masquerading engine for all machines on an internal
74 to be silent at startup rather than displaying the mode and interface
81 to only attempt to open
82 .Pa /dev/tun Ns Ar N .
85 will start with a value of 0 for
87 and keep trying to open a tunnel device by incrementing the value of
89 by one each time until it succeeds.
90 If it fails three times in a row
91 because the device file is missing, it gives up.
97 .Bl -tag -width XXX -offset XXX
100 opens the tun interface, configures it then goes into the background.
101 The link isn't brought up until outgoing data is detected on the tun
102 interface at which point
104 attempts to bring up the link.
105 Packets received (including the first one) while
107 is trying to bring the link up will remain queued for a default of
117 must be given on the command line (see below) and a
119 must be done in the system profile that specifies a peer IP address to
120 use when configuring the interface.
123 is usually appropriate.
127 .Pa /usr/share/examples/ppp/ppp.conf.sample
132 attempts to establish a connection with the peer immediately.
135 goes into the background and the parent process returns an exit code
139 exits with a non-zero result.
143 attempts to establish a connection with the peer immediately, but never
145 The link is created in background mode.
146 This is useful if you wish to control
148 invocation from another process.
150 This is used for receiving incoming connections.
154 line and uses descriptor 0 as the link.
156 If callback is configured,
160 information when dialing back.
162 This option is designed for machines connected with a dedicated
165 will always keep the device open and will never use any configured
168 This mode is equivalent to
172 will bring the link back up any time it's dropped for any reason.
174 This is a no-op, and gives the same behaviour as if none of the above
175 modes have been specified.
177 loads any sections specified on the command line then provides an
181 One or more configuration entries or systems
183 .Pa /etc/ppp/ppp.conf )
184 may also be specified on the command line.
189 .Pa /etc/ppp/ppp.conf
190 at startup, followed by each of the systems specified on the command line.
193 .It Provides an interactive user interface.
194 Using its command mode, the user can
195 easily enter commands to establish the connection with the remote end, check
196 the status of connection and close the connection.
197 All functions can also be optionally password protected for security.
198 .It Supports both manual and automatic dialing.
199 Interactive mode has a
201 command which enables you to talk to the device directly.
202 When you are connected to the remote peer and it starts to talk
205 detects it and switches to packet mode automatically.
207 determined the proper sequence for connecting with the remote host, you
208 can write a chat script to define the necessary dialing and login
209 procedure for later convenience.
210 .It Supports on-demand dialup capability.
215 will act as a daemon and wait for a packet to be sent over the
218 When this happens, the daemon automatically dials and establishes the
220 In almost the same manner
222 mode (direct-dial mode) also automatically dials and establishes the
224 However, it differs in that it will dial the remote site
225 any time it detects the link is down, even if there are no packets to be
227 This mode is useful for full-time connections where we worry less
228 about line charges and more about being connected full time.
231 mode is also available.
232 This mode is targeted at a dedicated link between two machines.
234 will never voluntarily quit from dedicated mode - you must send it the
236 command via its diagnostic socket.
239 will force an LCP renegotiation, and a
241 will force it to exit.
242 .It Supports client callback.
244 can use either the standard LCP callback protocol or the Microsoft
245 CallBack Control Protocol (ftp://ftp.microsoft.com/developr/rfc/cbcp.txt).
246 .It Supports NAT or packet aliasing.
247 Packet aliasing (a.k.a. IP masquerading) allows computers on a
248 private, unregistered network to access the Internet.
251 host acts as a masquerading gateway.
252 IP addresses as well as TCP and
253 UDP port numbers are NAT'd for outgoing packets and de-NAT'd for
255 .It Supports background PPP connections.
256 In background mode, if
258 successfully establishes the connection, it will become a daemon.
259 Otherwise, it will exit with an error.
260 This allows the setup of
261 scripts that wish to execute certain commands only if the connection
262 is successfully established.
263 .It Supports server-side PPP connections.
266 acts as server which accepts incoming
268 connections on stdin/stdout.
269 .It "Supports PAP and CHAP (rfc 1994, 2433 and 2759) authentication.
270 With PAP or CHAP, it is possible to skip the Unix style
272 procedure, and use the
274 protocol for authentication instead.
275 If the peer requests Microsoft CHAP authentication and
277 is compiled with DES support, an appropriate MD4/DES response will be
279 .It Supports RADIUS (rfc 2138) authentication.
280 An extension to PAP and CHAP,
287 allows authentication information to be stored in a central or
288 distributed database along with various per-user framed connection
292 is available at compile time,
296 requests when configured to do so.
297 .It Supports Proxy Arp.
299 can be configured to make one or more proxy arp entries on behalf of
301 This allows routing from the peer to the LAN without
302 configuring each machine on that LAN.
303 .It Supports packet filtering.
304 User can define four kinds of filters: the
306 filter for incoming packets, the
308 filter for outgoing packets, the
310 filter to define a dialing trigger packet and the
312 filter for keeping a connection alive with the trigger packet.
313 .It Tunnel driver supports bpf.
316 to check the packet flow over the
319 .It Supports PPP over TCP and PPP over UDP.
320 If a device name is specified as
321 .Em host Ns No : Ns Em port Ns
326 will open a TCP or UDP connection for transporting data rather than using a
327 conventional serial device.
328 UDP connections force
330 into synchronous mode.
331 .It Supports PPP over ISDN.
334 is given a raw B-channel i4b device to open as a link, it's able to talk
337 daemon to establish an ISDN connection.
338 .It Supports PPP over Ethernet (rfc 2516).
341 is given a device specification of the format
342 .No PPPoE: Ns Ar iface Ns Xo
343 .Op \&: Ns Ar provider Ns
357 On systems that do not support
359 an external program such as
362 .It "Supports IETF draft Predictor-1 (rfc 1978) and DEFLATE (rfc 1979) compression."
364 supports not only VJ-compression but also Predictor-1 and DEFLATE compression.
365 Normally, a modem has built-in compression (e.g., v42.bis) and the system
366 may receive higher data rates from it as a result of such compression.
367 While this is generally a good thing in most other situations, this
368 higher speed data imposes a penalty on the system by increasing the
369 number of serial interrupts the system has to process in talking to the
370 modem and also increases latency.
371 Unlike VJ-compression, Predictor-1 and DEFLATE compression pre-compresses
373 network traffic flowing through the link, thus reducing overheads to a
375 .It Supports Microsoft's IPCP extensions (rfc 1877).
376 Name Server Addresses and NetBIOS Name Server Addresses can be negotiated
377 with clients using the Microsoft
379 stack (i.e., Win95, WinNT)
380 .It Supports Multi-link PPP (rfc 1990)
381 It is possible to configure
383 to open more than one physical connection to the peer, combining the
384 bandwidth of all links for better throughput.
385 .It Supports MPPE (draft-ietf-pppext-mppe)
386 MPPE is Microsoft Point to Point Encryption scheme.
387 It is possible to configure
389 to participate in Microsoft's Windows VPN.
392 can only get encryption keys from CHAP 81 authentication.
394 must be compiled with DES for MPPE to operate.
406 will not run if the invoking user id is not zero.
407 This may be overridden by using the
410 .Pa /etc/ppp/ppp.conf .
411 When running as a normal user,
413 switches to user id 0 in order to alter the system routing table, set up
414 system lock files and read the ppp configuration files.
415 All external commands (executed via the "shell" or "!bg" commands) are executed
416 as the user id that invoked
420 logging facility if you're interested in what exactly is done as user id
425 you may need to deal with some initial configuration details.
428 Your kernel must include a tunnel device (the GENERIC kernel includes
430 If it doesn't, or if you require more than one tun
431 interface, you'll need to rebuild your kernel with the following line in
432 your kernel configuration file:
434 .Dl pseudo-device tun N
438 is the maximum number of
440 connections you wish to support.
444 directory for the tunnel device entries
448 represents the number of the tun device, starting at zero.
449 If they don't exist, you can create them by running "sh ./MAKEDEV tunN".
450 This will create tun devices 0 through
453 Make sure that your system has a group named
457 file and that the group contains the names of all users expected to use
461 manual page for details.
462 Each of these users must also be given access using the
465 .Pa /etc/ppp/ppp.conf .
472 A common log file name is
473 .Pa /var/log/ppp.log .
474 To make output go to this file, put the following lines in the
477 .Bd -literal -offset indent
479 *.*<TAB>/var/log/ppp.log
482 It is possible to have more than one
484 log file by creating a link to the
492 .Bd -literal -offset indent
494 *.*<TAB>/var/log/ppp0.log
498 .Pa /etc/syslog.conf .
499 Don't forget to send a
504 .Pa /etc/syslog.conf .
506 Although not strictly relevant to
508 operation, you should configure your resolver so that it works correctly.
509 This can be done by configuring a local DNS
512 or by adding the correct
515 .Pa /etc/resolv.conf .
518 manual page for details.
520 Alternatively, if the peer supports it,
522 can be configured to ask the peer for the nameserver address(es) and to
530 commands below for details.
533 In the following examples, we assume that your machine name is
539 above) with no arguments, you are presented with a prompt:
540 .Bd -literal -offset indent
546 part of your prompt should always be in upper case.
547 If it is in lower case, it means that you must supply a password using the
550 This only ever happens if you connect to a running version of
552 and have not authenticated yourself using the correct password.
554 You can start by specifying the device name and speed:
555 .Bd -literal -offset indent
556 ppp ON awfulhak> set device /dev/cuaa0
557 ppp ON awfulhak> set speed 38400
560 Normally, hardware flow control (CTS/RTS) is used.
562 certain circumstances (as may happen when you are connected directly
563 to certain PPP-capable terminal servers), this may result in
565 hanging as soon as it tries to write data to your communications link
566 as it is waiting for the CTS (clear to send) signal - which will never
568 Thus, if you have a direct line and can't seem to make a
569 connection, try turning CTS/RTS off with
571 If you need to do this, check the
573 description below too - you'll probably need to
574 .Dq set accmap 000a0000 .
576 Usually, parity is set to
581 Parity is a rather archaic error checking mechanism that is no
582 longer used because modern modems do their own error checking, and most
583 link-layer protocols (that's what
585 is) use much more reliable checking mechanisms.
586 Parity has a relatively
587 huge overhead (a 12.5% increase in traffic) and as a result, it is always
594 However, some ISPs (Internet Service Providers) may use
595 specific parity settings at connection time (before
598 Notably, Compuserve insist on even parity when logging in:
599 .Bd -literal -offset indent
600 ppp ON awfulhak> set parity even
603 You can now see what your current device settings look like:
604 .Bd -literal -offset indent
605 ppp ON awfulhak> show physical
609 Link Type: interactive
615 Device List: /dev/cuaa0
616 Characteristics: 38400bps, cs8, even parity, CTS/RTS on
619 0 octets in, 0 octets out
624 The term command can now be used to talk directly to the device:
625 .Bd -literal -offset indent
626 ppp ON awfulhak> term
632 Password: myisppassword
636 When the peer starts to talk in
639 detects this automatically and returns to command mode.
640 .Bd -literal -offset indent
641 ppp ON awfulhak> # No link has been established
642 Ppp ON awfulhak> # We've connected & finished LCP
643 PPp ON awfulhak> # We've authenticated
644 PPP ON awfulhak> # We've agreed IP numbers
647 If it does not, it's probable that the peer is waiting for your end to
653 configuration packets to the peer, use the
655 command to drop out of terminal mode and enter packet mode.
657 If you never even receive a login prompt, it is quite likely that the
658 peer wants to use PAP or CHAP authentication instead of using Unix-style
659 login/password authentication.
660 To set things up properly, drop back to
661 the prompt and set your authentication name and key, then reconnect:
662 .Bd -literal -offset indent
664 ppp ON awfulhak> set authname myispusername
665 ppp ON awfulhak> set authkey myisppassword
666 ppp ON awfulhak> term
673 You may need to tell ppp to initiate negotiations with the peer here too:
674 .Bd -literal -offset indent
676 ppp ON awfulhak> # No link has been established
677 Ppp ON awfulhak> # We've connected & finished LCP
678 PPp ON awfulhak> # We've authenticated
679 PPP ON awfulhak> # We've agreed IP numbers
682 You are now connected!
685 in the prompt has changed to capital letters to indicate that you have
687 If only some of the three Ps go uppercase, wait until
688 either everything is uppercase or lowercase.
689 If they revert to lowercase, it means that
691 couldn't successfully negotiate with the peer.
692 A good first step for troubleshooting at this point would be to
693 .Bd -literal -offset indent
694 ppp ON awfulhak> set log local phase lcp ipcp
700 command description below for further details.
701 If things fail at this point,
702 it is quite important that you turn logging on and try again.
704 important that you note any prompt changes and report them to anyone trying
707 When the link is established, the show command can be used to see how
709 .Bd -literal -offset indent
710 PPP ON awfulhak> show physical
711 * Modem related information is shown here *
712 PPP ON awfulhak> show ccp
713 * CCP (compression) related information is shown here *
714 PPP ON awfulhak> show lcp
715 * LCP (line control) related information is shown here *
716 PPP ON awfulhak> show ipcp
717 * IPCP (IP) related information is shown here *
718 PPP ON awfulhak> show link
719 * Link (high level) related information is shown here *
720 PPP ON awfulhak> show bundle
721 * Logical (high level) connection related information is shown here *
724 At this point, your machine has a host route to the peer.
726 that you can only make a connection with the host on the other side
728 If you want to add a default route entry (telling your
729 machine to send all packets without another routing entry to the other
732 link), enter the following command:
733 .Bd -literal -offset indent
734 PPP ON awfulhak> add default HISADDR
739 represents the IP address of the connected peer.
742 command fails due to an existing route, you can overwrite the existing
744 .Bd -literal -offset indent
745 PPP ON awfulhak> add! default HISADDR
748 This command can also be executed before actually making the connection.
749 If a new IP address is negotiated at connection time,
751 will update your default route accordingly.
753 You can now use your network applications (ping, telnet, ftp etc.)
754 in other windows or terminals on your machine.
755 If you wish to reuse the current terminal, you can put
757 into the background using your standard shell suspend and background
765 section for details on all available commands.
766 .Sh AUTOMATIC DIALING
767 To use automatic dialing, you must prepare some Dial and Login chat scripts.
768 See the example definitions in
769 .Pa /usr/share/examples/ppp/ppp.conf.sample
771 .Pa /etc/ppp/ppp.conf
773 Each line contains one comment, inclusion, label or command:
776 A line starting with a
778 character is treated as a comment line.
779 Leading whitespace are ignored when identifying comment lines.
781 An inclusion is a line beginning with the word
783 It must have one argument - the file to include.
785 .Dq !include ~/.ppp.conf
786 for compatibility with older versions of
789 A label name starts in the first column and is followed by
793 A command line must contain a space or tab in the first column.
797 .Pa /etc/ppp/ppp.conf
798 file should consist of at least a
801 This section is always executed.
802 It should also contain
803 one or more sections, named according to their purpose, for example,
805 would represent your ISP, and
807 would represent an incoming
810 You can now specify the destination label name when you invoke
812 Commands associated with the
814 label are executed, followed by those associated with the destination
818 is started with no arguments, the
820 section is still executed.
821 The load command can be used to manually load a section from the
822 .Pa /etc/ppp/ppp.conf
824 .Bd -literal -offset indent
825 ppp ON awfulhak> load MyISP
828 Note, no action is taken by
830 after a section is loaded, whether it's the result of passing a label on
831 the command line or using the
834 Only the commands specified for that label in the configuration
836 However, when invoking
843 switches, the link mode tells
845 to establish a connection.
848 command below for further details.
850 Once the connection is made, the
852 portion of the prompt will change to
854 .Bd -literal -offset indent
857 ppp ON awfulhak> dial
863 The Ppp prompt indicates that
865 has entered the authentication phase.
866 The PPp prompt indicates that
868 has entered the network phase.
869 The PPP prompt indicates that
871 has successfully negotiated a network layer protocol and is in
875 .Pa /etc/ppp/ppp.linkup
876 file is available, its contents are executed
879 connection is established.
883 .Pa /usr/share/examples/ppp/ppp.conf.sample
884 which runs a script in the background after the connection is established
889 commands below for a description of possible substitution strings).
890 Similarly, when a connection is closed, the contents of the
891 .Pa /etc/ppp/ppp.linkdown
893 Both of these files have the same format as
894 .Pa /etc/ppp/ppp.conf .
896 In previous versions of
898 it was necessary to re-add routes such as the default route in the
904 where all routes that contain the
908 literals will automatically be updated when the values of
913 .Sh BACKGROUND DIALING
914 If you want to establish a connection using
916 non-interactively (such as from a
920 job) you should use the
927 attempts to establish the connection immediately.
929 numbers are specified, each phone number will be tried once.
930 If the attempt fails,
932 exits immediately with a non-zero exit code.
935 becomes a daemon, and returns an exit status of zero to its caller.
936 The daemon exits automatically if the connection is dropped by the
937 remote system, or it receives a
941 Demand dialing is enabled with the
946 You must also specify the destination label in
947 .Pa /etc/ppp/ppp.conf
951 command to define the remote peers IP address.
953 .Pa /usr/share/examples/ppp/ppp.conf.sample )
954 .Bd -literal -offset indent
964 runs as a daemon but you can still configure or examine its
965 configuration by using the
968 .Pa /etc/ppp/ppp.conf ,
970 .Dq Li "set server +3000 mypasswd" )
971 and connecting to the diagnostic port as follows:
972 .Bd -literal -offset indent
973 # pppctl 3000 (assuming tun0)
975 PPP ON awfulhak> show who
976 tcp (127.0.0.1:1028) *
981 command lists users that are currently connected to
984 If the diagnostic socket is closed or changed to a different
985 socket, all connections are immediately dropped.
989 mode, when an outgoing packet is detected,
991 will perform the dialing action (chat script) and try to connect
995 mode, the dialing action is performed any time the line is found
997 If the connect fails, the default behaviour is to wait 30 seconds
998 and then attempt to connect when another outgoing packet is detected.
999 This behaviour can be changed using the
1003 .No set redial Ar secs Ns Xo
1006 .Oc Ns Op . Ns Ar next
1010 .Bl -tag -width attempts -compact
1012 is the number of seconds to wait before attempting
1014 If the argument is the literal string
1016 the delay period is a random value between 1 and 30 seconds inclusive.
1018 is the number of seconds that
1020 should be incremented each time a new dial attempt is made.
1021 The timeout reverts to
1023 only after a successful connection is established.
1024 The default value for
1028 is the maximum number of times
1032 The default value for
1036 is the number of seconds to wait before attempting
1037 to dial the next number in a list of numbers (see the
1040 The default is 3 seconds.
1041 Again, if the argument is the literal string
1043 the delay period is a random value between 1 and 30 seconds.
1045 is the maximum number of times to try to connect for each outgoing packet
1046 that triggers a dial.
1047 The previous value is unchanged if this parameter is omitted.
1048 If a value of zero is specified for
1051 will keep trying until a connection is made.
1055 .Bd -literal -offset indent
1059 will attempt to connect 4 times for each outgoing packet that causes
1060 a dial attempt with a 3 second delay between each number and a 10 second
1061 delay after all numbers have been tried.
1062 If multiple phone numbers
1063 are specified, the total number of attempts is still 4 (it does not
1064 attempt each number 4 times).
1068 .Bd -literal -offset indent
1069 set redial 10+10-5.3 20
1074 to attempt to connect 20 times.
1075 After the first attempt,
1077 pauses for 10 seconds.
1078 After the next attempt it pauses for 20 seconds
1079 and so on until after the sixth attempt it pauses for 1 minute.
1080 The next 14 pauses will also have a duration of one minute.
1083 connects, disconnects and fails to connect again, the timeout starts again
1086 Modifying the dial delay is very useful when running
1090 mode on both ends of the link.
1091 If each end has the same timeout,
1092 both ends wind up calling each other at the same time if the link
1093 drops and both ends have packets queued.
1094 At some locations, the serial link may not be reliable, and carrier
1095 may be lost at inappropriate times.
1096 It is possible to have
1098 redial should carrier be unexpectedly lost during a session.
1099 .Bd -literal -offset indent
1100 set reconnect timeout ntries
1105 to re-establish the connection
1107 times on loss of carrier with a pause of
1109 seconds before each try.
1111 .Bd -literal -offset indent
1117 that on an unexpected loss of carrier, it should wait
1119 seconds before attempting to reconnect.
1120 This may happen up to
1125 The default value of ntries is zero (no reconnect).
1126 Care should be taken with this option.
1127 If the local timeout is slightly
1128 longer than the remote timeout, the reconnect feature will always be
1129 triggered (up to the given number of times) after the remote side
1130 times out and hangs up.
1131 NOTE: In this context, losing too many LQRs constitutes a loss of
1132 carrier and will trigger a reconnect.
1135 flag is specified, all phone numbers are dialed at most once until
1136 a connection is made.
1137 The next number redial period specified with the
1139 command is honoured, as is the reconnect tries value.
1141 value is less than the number of phone numbers specified, not all
1142 the specified numbers will be tried.
1143 To terminate the program, type
1144 .Bd -literal -offset indent
1145 PPP ON awfulhak> close
1146 ppp ON awfulhak> quit all
1151 command will terminate the
1155 connection but not the
1163 .Sh RECEIVING INCOMING PPP CONNECTIONS (Method 1)
1164 To handle an incoming
1166 connection request, follow these steps:
1169 Make sure the modem and (optionally)
1171 is configured correctly.
1172 .Bl -bullet -compact
1174 Use Hardware Handshake (CTS/RTS) for flow control.
1176 Modem should be set to NO echo back (ATE0) and NO results string (ATQ1).
1184 on the port where the modem is attached.
1187 .Dl ttyd1 Qo /usr/libexec/getty std.38400 Qc dialup on secure
1189 Don't forget to send a
1193 process to start the
1198 It is usually also necessary to train your modem to the same DTR speed
1200 .Bd -literal -offset indent
1202 ppp ON awfulhak> set device /dev/cuaa1
1203 ppp ON awfulhak> set speed 38400
1204 ppp ON awfulhak> term
1205 deflink: Entering terminal mode on /dev/cuaa1
1216 ppp ON awfulhak> quit
1220 .Pa /usr/local/bin/ppplogin
1221 file with the following contents:
1222 .Bd -literal -offset indent
1224 exec /usr/sbin/ppp -direct incoming
1231 work with stdin and stdout.
1234 to connect to a configured diagnostic port, in the same manner as with
1240 section must be set up in
1241 .Pa /etc/ppp/ppp.conf .
1245 section contains the
1247 command as appropriate.
1249 Prepare an account for the incoming user.
1251 ppp:xxxx:66:66:PPP Login User:/home/ppp:/usr/local/bin/ppplogin
1254 Refer to the manual entries for
1260 Support for IPCP Domain Name Server and NetBIOS Name Server negotiation
1261 can be enabled using the
1266 Refer to their descriptions below.
1268 .Sh RECEIVING INCOMING PPP CONNECTIONS (Method 2)
1269 This method differs in that we use
1271 to authenticate the connection rather than
1275 Configure your default section in
1277 with automatic ppp recognition by specifying the
1282 :pp=/usr/local/bin/ppplogin:\\
1286 Configure your serial device(s), enable a
1289 .Pa /usr/local/bin/ppplogin
1290 as in the first three steps for method 1 above.
1298 .Pa /etc/ppp/ppp.conf
1301 label (or whatever label
1306 .Pa /etc/ppp/ppp.secret
1307 for each incoming user:
1316 detects a ppp connection (by recognising the HDLC frame headers), it runs
1317 .Dq /usr/local/bin/ppplogin .
1321 that either PAP or CHAP are enabled as above.
1322 If they are not, you are
1323 allowing anybody to establish ppp session with your machine
1325 a password, opening yourself up to all sorts of potential attacks.
1326 .Sh AUTHENTICATING INCOMING CONNECTIONS
1327 Normally, the receiver of a connection requires that the peer
1328 authenticates itself.
1329 This may be done using
1331 but alternatively, you can use PAP or CHAP.
1332 CHAP is the more secure of the two, but some clients may not support it.
1333 Once you decide which you wish to use, add the command
1337 to the relevant section of
1340 You must then configure the
1341 .Pa /etc/ppp/ppp.secret
1343 This file contains one line per possible client, each line
1344 containing up to five fields:
1347 .Ar hisaddr Op Ar label Op Ar callback-number
1354 specify the client username and password.
1359 and PAP is being used,
1361 will look up the password database
1363 when authenticating.
1364 If the client does not offer a suitable response based on any
1365 .Ar name Ns No / Ns Ar key
1368 authentication fails.
1370 If authentication is successful,
1373 is used when negotiating IP numbers.
1376 command for details.
1378 If authentication is successful and
1380 is specified, the current system label is changed to match the given
1382 This will change the subsequent parsing of the
1388 If authentication is successful and
1394 the client will be called back on the given number.
1395 If CBCP is being used,
1397 may also contain a list of numbers or a
1402 The value will be used in
1404 subsequent CBCP phase.
1405 .Sh PPP OVER TCP and UDP (a.k.a Tunnelling)
1408 over a serial link, it is possible to
1409 use a TCP connection instead by specifying the host, port and protocol as the
1412 .Dl set device ui-gate:6669/tcp
1414 Instead of opening a serial device,
1416 will open a TCP connection to the given machine on the given
1418 It should be noted however that
1420 doesn't use the telnet protocol and will be unable to negotiate
1421 with a telnet server.
1422 You should set up a port for receiving this
1424 connection on the receiving machine (ui-gate).
1425 This is done by first updating
1427 to name the service:
1429 .Dl ppp-in 6669/tcp # Incoming PPP connections over TCP
1435 how to deal with incoming connections on that port:
1437 .Dl ppp-in stream tcp nowait root /usr/sbin/ppp ppp -direct ppp-in
1439 Don't forget to send a
1443 after you've updated
1444 .Pa /etc/inetd.conf .
1445 Here, we use a label named
1448 .Pa /etc/ppp/ppp.conf
1449 on ui-gate (the receiver) should contain the following:
1450 .Bd -literal -offset indent
1453 set ifaddr 10.0.4.1 10.0.4.2
1457 .Pa /etc/ppp/ppp.linkup
1459 .Bd -literal -offset indent
1461 add 10.0.1.0/24 HISADDR
1464 It is necessary to put the
1468 to ensure that the route is only added after
1470 has negotiated and assigned addresses to its interface.
1472 You may also want to enable PAP or CHAP for security.
1473 To enable PAP, add the following line:
1474 .Bd -literal -offset indent
1478 You'll also need to create the following entry in
1479 .Pa /etc/ppp/ppp.secret :
1480 .Bd -literal -offset indent
1481 MyAuthName MyAuthPasswd
1488 the password is looked up in the
1493 .Pa /etc/ppp/ppp.conf
1494 on awfulhak (the initiator) should contain the following:
1495 .Bd -literal -offset indent
1498 set device ui-gate:ppp-in/tcp
1501 set log Phase Chat Connect hdlc LCP IPCP CCP tun
1502 set ifaddr 10.0.4.2 10.0.4.1
1505 with the route setup in
1506 .Pa /etc/ppp/ppp.linkup :
1507 .Bd -literal -offset indent
1509 add 10.0.2.0/24 HISADDR
1512 Again, if you're enabling PAP, you'll also need this in the
1513 .Pa /etc/ppp/ppp.conf
1515 .Bd -literal -offset indent
1516 set authname MyAuthName
1517 set authkey MyAuthKey
1520 We're assigning the address of 10.0.4.1 to ui-gate, and the address
1521 10.0.4.2 to awfulhak.
1522 To open the connection, just type
1524 .Dl awfulhak # ppp -background ui-gate
1526 The result will be an additional "route" on awfulhak to the
1527 10.0.2.0/24 network via the TCP connection, and an additional
1528 "route" on ui-gate to the 10.0.1.0/24 network.
1529 The networks are effectively bridged - the underlying TCP
1530 connection may be across a public network (such as the
1533 traffic is conceptually encapsulated
1534 (although not packet by packet) inside the TCP stream between
1537 The major disadvantage of this mechanism is that there are two
1538 "guaranteed delivery" mechanisms in place - the underlying TCP
1539 stream and whatever protocol is used over the
1541 link - probably TCP again.
1542 If packets are lost, both levels will
1543 get in each others way trying to negotiate sending of the missing
1546 To avoid this overhead, it is also possible to do all this using
1547 UDP instead of TCP as the transport by simply changing the protocol
1548 from "tcp" to "udp".
1549 When using UDP as a transport,
1551 will operate in synchronous mode.
1552 This is another gain as the incoming
1553 data does not have to be rearranged into packets.
1555 Care should be taken when adding a default route through a tunneled
1557 It is quite common for the default route
1559 .Pa /etc/ppp/ppp.linkup )
1560 to end up routing the link's TCP connection through the tunnel,
1561 effectively garrotting the connection.
1562 To avoid this, make sure you add a static route for the benefit of
1564 .Bd -literal -offset indent
1567 set device ui-gate:ppp-in/tcp
1574 is the IP number that your route to
1578 When routing your connection accross a public network such as the Internet,
1579 it is preferable to encrypt the data.
1580 This can be done with the help of the MPPE protocol, although currently this
1581 means that you will not be able to also compress the traffic as MPPE is
1582 implemented as a compression layer (thank Microsoft for this).
1583 To enable MPPE encryption, add the following lines to
1584 .Pa /etc/ppp/ppp.conf
1586 .Bd -literal -offset indent
1588 disable deflate pred1
1592 ensuring that you've put the requisite entry in
1593 .Pa /etc/ppp/ppp.secret
1594 (MSCHAPv2 is challenge based, so
1598 MSCHAPv2 and MPPE are accepted by default, so the client end should work
1599 without any additional changes (although ensure you have
1604 .Sh NETWORK ADDRESS TRANSLATION (PACKET ALIASING)
1607 command line option enables network address translation (a.k.a. packet
1611 host to act as a masquerading gateway for other computers over
1612 a local area network.
1613 Outgoing IP packets are NAT'd so that they appear to come from the
1615 host, and incoming packets are de-NAT'd so that they are routed
1616 to the correct machine on the local area network.
1617 NAT allows computers on private, unregistered subnets to have Internet
1618 access, although they are invisible from the outside world.
1621 operation should first be verified with network address translation disabled.
1624 option should be switched on, and network applications (web browser,
1629 should be checked on the
1632 Finally, the same or similar applications should be checked on other
1633 computers in the LAN.
1634 If network applications work correctly on the
1636 host, but not on other machines in the LAN, then the masquerading
1637 software is working properly, but the host is either not forwarding
1638 or possibly receiving IP packets.
1639 Check that IP forwarding is enabled in
1641 and that other machines have designated the
1643 host as the gateway for the LAN.
1644 .Sh PACKET FILTERING
1645 This implementation supports packet filtering.
1646 There are four kinds of
1656 Here are the basics:
1659 A filter definition has the following syntax:
1668 .Ar src_addr Ns Op / Ns Ar width
1669 .Op Ar dst_addr Ns Op / Ns Ar width
1671 .Ar [ proto Op src Ar cmp port
1676 .Op timeout Ar secs ]
1688 is a numeric value between
1692 specifying the rule number.
1693 Rules are specified in numeric order according to
1704 in which case, if a given packet matches the rule, the associated action
1705 is taken immediately.
1707 can also be specified as
1709 to clear the action associated with that particular rule, or as a new
1710 rule number greater than the current rule.
1711 In this case, if a given
1712 packet matches the current rule, the packet will next be matched against
1713 the new rule number (rather than the next rule number).
1717 may optionally be followed with an exclamation mark
1721 to reverse the sense of the following match.
1723 .Op Ar src_addr Ns Op / Ns Ar width
1725 .Op Ar dst_addr Ns Op / Ns Ar width
1726 are the source and destination IP number specifications.
1729 is specified, it gives the number of relevant netmask bits,
1730 allowing the specification of an address range.
1736 may be given the values
1740 (refer to the description of the
1742 command for a description of these values).
1743 When these values are used,
1744 the filters will be updated any time the values change.
1745 This is similar to the behaviour of the
1765 meaning less-than, equal and greater-than respectively.
1767 can be specified as a numeric port or by service name from
1775 flags are only allowed when
1779 and represent the TH_ACK, TH_SYN and TH_FIN or TH_RST TCP flags respectively.
1781 The timeout value adjusts the current idle timeout to at least
1784 If a timeout is given in the alive filter as well as in the in/out
1785 filter, the in/out value is used.
1786 If no timeout is given, the default timeout (set using
1788 and defaulting to 180 seconds) is used.
1792 Each filter can hold up to 40 rules, starting from rule 0.
1793 The entire rule set is not effective until rule 0 is defined,
1794 i.e., the default is to allow everything through.
1796 If no rule in a defined set of rules matches a packet, that packet will
1797 be discarded (blocked).
1798 If there are no rules in a given filter, the packet will be permitted.
1800 It's possible to filter based on the payload of UDP frames where those
1806 .Ar filter-decapsulation
1807 option below for further details.
1810 .Dq set filter Ar name No -1
1815 .Pa /usr/share/examples/ppp/ppp.conf.sample .
1816 .Sh SETTING THE IDLE TIMER
1817 To check/set the idle timer, use the
1822 .Bd -literal -offset indent
1823 ppp ON awfulhak> set timeout 600
1826 The timeout period is measured in seconds, the default value for which
1829 To disable the idle timer function, use the command
1830 .Bd -literal -offset indent
1831 ppp ON awfulhak> set timeout 0
1838 modes, the idle timeout is ignored.
1841 mode, when the idle timeout causes the
1846 program itself remains running.
1847 Another trigger packet will cause it to attempt to re-establish the link.
1848 .Sh PREDICTOR-1 and DEFLATE COMPRESSION
1850 supports both Predictor type 1 and deflate compression.
1853 will attempt to use (or be willing to accept) both compression protocols
1854 when the peer agrees
1856 The deflate protocol is preferred by
1862 commands if you wish to disable this functionality.
1864 It is possible to use a different compression algorithm in each direction
1865 by using only one of
1869 (assuming that the peer supports both algorithms).
1871 By default, when negotiating DEFLATE,
1873 will use a window size of 15.
1876 command if you wish to change this behaviour.
1878 A special algorithm called DEFLATE24 is also available, and is disabled
1879 and denied by default.
1880 This is exactly the same as DEFLATE except that
1881 it uses CCP ID 24 to negotiate.
1884 to successfully negotiate DEFLATE with
1887 .Sh CONTROLLING IP ADDRESS
1889 uses IPCP to negotiate IP addresses.
1890 Each side of the connection
1891 specifies the IP address that it's willing to use, and if the requested
1892 IP address is acceptable then
1894 returns ACK to the requester.
1897 returns NAK to suggest that the peer use a different IP address.
1899 both sides of the connection agree to accept the received request (and
1900 send ACK), IPCP is set to the open state and a network level connection
1902 To control this IPCP behaviour, this implementation has the
1904 command for defining the local and remote IP address:
1905 .Bd -ragged -offset indent
1906 .No set ifaddr Oo Ar src_addr Ns
1908 .Oo Ar dst_addr Ns Op / Ns Ar \&nn
1918 is the IP address that the local side is willing to use,
1920 is the IP address which the remote side should use and
1922 is the netmask that should be used.
1924 defaults to the current
1927 defaults to 0.0.0.0, and
1929 defaults to whatever mask is appropriate for
1931 It is only possible to make
1933 smaller than the default.
1934 The usual value is 255.255.255.255, as
1935 most kernels ignore the netmask of a POINTOPOINT interface.
1939 implementations require that the peer negotiates a specific IP
1942 If this is the case,
1944 may be used to specify this IP number.
1945 This will not affect the
1946 routing table unless the other side agrees with this proposed number.
1947 .Bd -literal -offset indent
1948 set ifaddr 192.244.177.38 192.244.177.2 255.255.255.255 0.0.0.0
1951 The above specification means:
1953 .Bl -bullet -compact
1955 I will first suggest that my IP address should be 0.0.0.0, but I
1956 will only accept an address of 192.244.177.38.
1958 I strongly insist that the peer uses 192.244.177.2 as his own
1959 address and won't permit the use of any IP address but 192.244.177.2.
1960 When the peer requests another IP address, I will always suggest that
1961 it uses 192.244.177.2.
1963 The routing table entry will have a netmask of 0xffffffff.
1966 This is all fine when each side has a pre-determined IP address, however
1967 it is often the case that one side is acting as a server which controls
1968 all IP addresses and the other side should go along with it.
1969 In order to allow more flexible behaviour, the
1971 command allows the user to specify IP addresses more loosely:
1973 .Dl set ifaddr 192.244.177.38/24 192.244.177.2/20
1975 A number followed by a slash
1977 represents the number of bits significant in the IP address.
1978 The above example means:
1980 .Bl -bullet -compact
1982 I'd like to use 192.244.177.38 as my address if it is possible, but I'll
1983 also accept any IP address between 192.244.177.0 and 192.244.177.255.
1985 I'd like to make him use 192.244.177.2 as his own address, but I'll also
1986 permit him to use any IP address between 192.244.176.0 and
1989 As you may have already noticed, 192.244.177.2 is equivalent to saying
1992 As an exception, 0 is equivalent to 0.0.0.0/0, meaning that I have no
1993 preferred IP address and will obey the remote peers selection.
1994 When using zero, no routing table entries will be made until a connection
1997 192.244.177.2/0 means that I'll accept/permit any IP address but I'll
1998 try to insist that 192.244.177.2 be used first.
2000 .Sh CONNECTING WITH YOUR INTERNET SERVICE PROVIDER
2001 The following steps should be taken when connecting to your ISP:
2004 Describe your providers phone number(s) in the dial script using the
2007 This command allows you to set multiple phone numbers for
2008 dialing and redialing separated by either a pipe
2012 .Bd -ragged -offset indent
2013 .No set phone Ar telno Ns Xo
2014 .Oo \&| Ns Ar backupnumber
2015 .Oc Ns ... Ns Oo : Ns Ar nextnumber
2020 Numbers after the first in a pipe-separated list are only used if the
2021 previous number was used in a failed dial or login script.
2023 separated by a colon are used sequentially, irrespective of what happened
2024 as a result of using the previous number.
2026 .Bd -literal -offset indent
2027 set phone "1234567|2345678:3456789|4567890"
2030 Here, the 1234567 number is attempted.
2031 If the dial or login script fails,
2032 the 2345678 number is used next time, but *only* if the dial or login script
2034 On the dial after this, the 3456789 number is used.
2036 number is only used if the dial or login script using the 3456789 fails.
2037 If the login script of the 2345678 number fails, the next number is still the
2039 As many pipes and colons can be used as are necessary
2040 (although a given site would usually prefer to use either the pipe or the
2041 colon, but not both).
2042 The next number redial timeout is used between all numbers.
2043 When the end of the list is reached, the normal redial period is
2044 used before starting at the beginning again.
2045 The selected phone number is substituted for the \\\\T string in the
2047 command (see below).
2049 Set up your redial requirements using
2051 For example, if you have a bad telephone line or your provider is
2052 usually engaged (not so common these days), you may want to specify
2054 .Bd -literal -offset indent
2058 This says that up to 4 phone calls should be attempted with a pause of 10
2059 seconds before dialing the first number again.
2061 Describe your login procedure using the
2068 command is used to talk to your modem and establish a link with your
2070 .Bd -literal -offset indent
2071 set dial "ABORT BUSY ABORT NO\\\\sCARRIER TIMEOUT 4 \\"\\" \e
2072 ATZ OK-ATZ-OK ATDT\\\\T TIMEOUT 60 CONNECT"
2075 This modem "chat" string means:
2078 Abort if the string "BUSY" or "NO CARRIER" are received.
2080 Set the timeout to 4 seconds.
2087 If that's not received within the 4 second timeout, send ATZ
2090 Send ATDTxxxxxxx where xxxxxxx is the next number in the phone list from
2093 Set the timeout to 60.
2095 Wait for the CONNECT string.
2098 Once the connection is established, the login script is executed.
2099 This script is written in the same style as the dial script, but care should
2100 be taken to avoid having your password logged:
2101 .Bd -literal -offset indent
2102 set authkey MySecret
2103 set login "TIMEOUT 15 login:-\\\\r-login: awfulhak \e
2104 word: \\\\P ocol: PPP HELLO"
2107 This login "chat" string means:
2110 Set the timeout to 15 seconds.
2113 If it's not received, send a carriage return and expect
2118 Expect "word:" (the tail end of a "Password:" prompt).
2120 Send whatever our current
2124 Expect "ocol:" (the tail end of a "Protocol:" prompt).
2133 command is logged specially.
2138 logging is enabled, the actual password is not logged;
2142 Login scripts vary greatly between ISPs.
2143 If you're setting one up for the first time,
2144 .Em ENABLE CHAT LOGGING
2145 so that you can see if your script is behaving as you expect.
2151 to specify your serial line and speed, for example:
2152 .Bd -literal -offset indent
2153 set device /dev/cuaa0
2157 Cuaa0 is the first serial port on
2164 A speed of 115200 should be specified
2165 if you have a modem capable of bit rates of 28800 or more.
2166 In general, the serial speed should be about four times the modem speed.
2170 command to define the IP address.
2173 If you know what IP address your provider uses, then use it as the remote
2174 address (dst_addr), otherwise choose something like 10.0.0.2/0 (see below).
2176 If your provider has assigned a particular IP address to you, then use
2177 it as your address (src_addr).
2179 If your provider assigns your address dynamically, choose a suitably
2180 unobtrusive and unspecific IP number as your address.
2181 10.0.0.1/0 would be appropriate.
2182 The bit after the / specifies how many bits of the
2183 address you consider to be important, so if you wanted to insist on
2184 something in the class C network 1.2.3.0, you could specify 1.2.3.1/24.
2186 If you find that your ISP accepts the first IP number that you suggest,
2187 specify third and forth arguments of
2189 This will force your ISP to assign a number.
2190 (The third argument will
2191 be ignored as it is less restrictive than the default mask for your
2195 An example for a connection where you don't know your IP number or your
2196 ISPs IP number would be:
2197 .Bd -literal -offset indent
2198 set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0
2202 In most cases, your ISP will also be your default router.
2203 If this is the case, add the line
2204 .Bd -literal -offset indent
2209 .Pa /etc/ppp/ppp.conf .
2213 to add a default route to whatever the peer address is
2214 (10.0.0.2 in this example).
2217 meaning that should the value of
2219 change, the route will be updated accordingly.
2221 Previous versions of
2223 required a similar entry in the
2224 .Pa /etc/ppp/ppp.linkup
2228 this is no longer required.
2230 If your provider requests that you use PAP/CHAP authentication methods, add
2231 the next lines to your
2232 .Pa /etc/ppp/ppp.conf
2234 .Bd -literal -offset indent
2236 set authkey MyPassword
2239 Both are accepted by default, so
2241 will provide whatever your ISP requires.
2243 It should be noted that a login script is rarely (if ever) required
2244 when PAP or CHAP are in use.
2246 Ask your ISP to authenticate your nameserver address(es) with the line
2247 .Bd -literal -offset indent
2253 do this if you are running a local DNS unless you also either use
2258 .Pa /etc/ppp/ppp.linkdown ,
2261 will simply circumvent its use by entering some nameserver lines in
2262 .Pa /etc/resolv.conf .
2266 .Pa /usr/share/examples/ppp/ppp.conf.sample
2268 .Pa /usr/share/examples/ppp/ppp.linkup.sample
2269 for some real examples.
2270 The pmdemand label should be appropriate for most ISPs.
2271 .Sh LOGGING FACILITY
2273 is able to generate the following log info either via
2275 or directly to the screen:
2277 .Bl -tag -width XXXXXXXXX -offset XXX -compact
2279 Enable all logging facilities.
2280 This generates a lot of log.
2281 The most common use of 'all' is as a basis, where you remove some facilities
2282 after enabling 'all' ('debug' and 'timer' are usually best disabled.)
2284 Dump async level packet in hex.
2286 Generate CBCP (CallBack Control Protocol) logs.
2288 Generate a CCP packet trace.
2296 chat script trace logs.
2298 Log commands executed either from the command line or any of the configuration
2301 Log Chat lines containing the string "CONNECT".
2303 Log debug information.
2305 Log DNS QUERY packets.
2307 Log packets permitted by the dial filter and denied by any filter.
2309 Dump HDLC packet in hex.
2311 Log all function calls specifically made as user id 0.
2313 Generate an IPCP packet trace.
2315 Generate an LCP packet trace.
2317 Generate LQR reports.
2319 Phase transition log output.
2321 Dump physical level packet in hex.
2323 Dump sync level packet in hex.
2325 Dump all TCP/IP packets.
2327 Log timer manipulation.
2329 Include the tun device on each log line.
2331 Output to the terminal device.
2332 If there is currently no terminal,
2333 output is sent to the log file using syslogs
2336 Output to both the terminal device
2337 and the log file using syslogs
2340 Output to the log file using
2346 command allows you to set the logging output level.
2347 Multiple levels can be specified on a single command line.
2348 The default is equivalent to
2351 It is also possible to log directly to the screen.
2352 The syntax is the same except that the word
2354 should immediately follow
2358 (i.e., only the un-maskable warning, error and alert output).
2360 If The first argument to
2361 .Dq set log Op local
2366 character, the current log levels are
2367 not cleared, for example:
2368 .Bd -literal -offset indent
2369 PPP ON awfulhak> set log phase
2370 PPP ON awfulhak> show log
2371 Log: Phase Warning Error Alert
2372 Local: Warning Error Alert
2373 PPP ON awfulhak> set log +tcp/ip -warning
2374 PPP ON awfulhak> set log local +command
2375 PPP ON awfulhak> show log
2376 Log: Phase TCP/IP Warning Error Alert
2377 Local: Command Warning Error Alert
2380 Log messages of level Warning, Error and Alert are not controllable
2382 .Dq set log Op local .
2386 level is special in that it will not be logged if it can be displayed
2390 deals with the following signals:
2391 .Bl -tag -width "USR2"
2393 Receipt of this signal causes the termination of the current connection
2397 to exit unless it is in
2402 .It HUP, TERM & QUIT
2409 to re-open any existing server socket, dropping all existing diagnostic
2411 Sockets that couldn't previously be opened will be retried.
2415 to close any existing server socket, dropping all existing diagnostic
2418 can still be used to re-open the socket.
2421 If you wish to use more than one physical link to connect to a
2423 peer, that peer must also understand the
2426 Refer to RFC 1990 for specification details.
2428 The peer is identified using a combination of his
2429 .Dq endpoint discriminator
2431 .Dq authentication id .
2432 Either or both of these may be specified.
2433 It is recommended that
2434 at least one is specified, otherwise there is no way of ensuring that
2435 all links are actually connected to the same peer program, and some
2436 confusing lock-ups may result.
2437 Locally, these identification variables are specified using the
2446 must be agreed in advance with the peer.
2448 Multi-link capabilities are enabled using the
2450 command (set maximum reconstructed receive unit).
2451 Once multi-link is enabled,
2453 will attempt to negotiate a multi-link connection with the peer.
2455 By default, only one
2460 To create more links, the
2463 This command will clone existing links, where all
2464 characteristics are the same except:
2467 The new link has its own name as specified on the
2474 Its mode may subsequently be changed using the
2478 The new link is in a
2483 A summary of all available links can be seen using the
2487 Once a new link has been created, command usage varies.
2488 All link specific commands must be prefixed with the
2490 command, specifying on which link the command is to be applied.
2491 When only a single link is available,
2493 is smart enough not to require the
2497 Some commands can still be used without specifying a link - resulting
2498 in an operation at the
2501 For example, once two or more links are available, the command
2503 will show CCP configuration and statistics at the multi-link level, and
2504 .Dq link deflink show ccp
2505 will show the same information at the
2509 Armed with this information, the following configuration might be used:
2511 .Bd -literal -offset indent
2515 set device /dev/cuaa0 /dev/cuaa1 /dev/cuaa2
2516 set phone "123456789"
2517 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \\"\\" ATZ \e
2518 OK-AT-OK \\\\dATDT\\\\T TIMEOUT 45 CONNECT"
2520 set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0
2522 set authkey ppppassword
2525 clone 1,2,3 # Create 3 new links - duplicates of the default
2526 link deflink remove # Delete the default link (called ``deflink'')
2529 Note how all cloning is done at the end of the configuration.
2530 Usually, the link will be configured first, then cloned.
2531 If you wish all links
2532 to be up all the time, you can add the following line to the end of your
2535 .Bd -literal -offset indent
2536 link 1,2,3 set mode ddial
2539 If you want the links to dial on demand, this command could be used:
2541 .Bd -literal -offset indent
2542 link * set mode auto
2545 Links may be tied to specific names by removing the
2547 line above, and specifying the following after the
2551 .Bd -literal -offset indent
2552 link 1 set device /dev/cuaa0
2553 link 2 set device /dev/cuaa1
2554 link 3 set device /dev/cuaa2
2559 command to see which commands require context (using the
2561 command), which have optional
2562 context and which should not have any context.
2568 mode with the peer, it creates a local domain socket in the
2571 This socket is used to pass link information (including
2572 the actual link file descriptor) between different
2577 ability to be run from a
2583 capability), without needing to have initial control of the serial
2587 negotiates multi-link mode, it will pass its open link to any
2588 already running process.
2589 If there is no already running process,
2591 will act as the master, creating the socket and listening for new
2593 .Sh PPP COMMAND LIST
2594 This section lists the available commands and their effect.
2595 They are usable either from an interactive
2597 session, from a configuration file or from a
2603 .It accept|deny|enable|disable Ar option....
2604 These directives tell
2606 how to negotiate the initial connection with the peer.
2609 has a default of either accept or deny and enable or disable.
2611 means that the option will be ACK'd if the peer asks for it.
2613 means that the option will be NAK'd if the peer asks for it.
2615 means that the option will be requested by us.
2617 means that the option will not be requested by us.
2620 may be one of the following:
2623 Default: Enabled and Accepted.
2624 ACFComp stands for Address and Control Field Compression.
2625 Non LCP packets will usually have an address
2626 field of 0xff (the All-Stations address) and a control field of
2627 0x03 (the Unnumbered Information command).
2629 negotiated, these two bytes are simply not sent, thus minimising
2636 Default: Disabled and Accepted.
2637 CHAP stands for Challenge Handshake Authentication Protocol.
2638 Only one of CHAP and PAP (below) may be negotiated.
2639 With CHAP, the authenticator sends a "challenge" message to its peer.
2640 The peer uses a one-way hash function to encrypt the
2641 challenge and sends the result back.
2642 The authenticator does the same, and compares the results.
2643 The advantage of this mechanism is that no
2644 passwords are sent across the connection.
2645 A challenge is made when the connection is first made.
2646 Subsequent challenges may occur.
2647 If you want to have your peer authenticate itself, you must
2650 .Pa /etc/ppp/ppp.conf ,
2651 and have an entry in
2652 .Pa /etc/ppp/ppp.secret
2655 When using CHAP as the client, you need only specify
2660 .Pa /etc/ppp/ppp.conf .
2661 CHAP is accepted by default.
2664 implementations use "MS-CHAP" rather than MD5 when encrypting the
2666 MS-CHAP is a combination of MD4 and DES.
2669 was built on a machine with DES libraries available, it will respond
2670 to MS-CHAP authentication requests, but will never request them.
2672 Default: Enabled and Accepted.
2673 This option decides if deflate
2674 compression will be used by the Compression Control Protocol (CCP).
2675 This is the same algorithm as used by the
2678 Note: There is a problem negotiating
2684 implementation available under many operating systems.
2686 (version 2.3.1) incorrectly attempts to negotiate
2688 compression using type
2690 as the CCP configuration type rather than type
2696 is actually specified as
2697 .Dq PPP Magna-link Variable Resource Compression
2701 is capable of negotiating with
2708 .Ar accept Ns No ed .
2710 Default: Disabled and Denied.
2711 This is a variance of the
2713 option, allowing negotiation with the
2718 section above for details.
2719 It is disabled by default as it violates
2722 Default: Disabled and Denied.
2723 This option allows DNS negotiation.
2728 will request that the peer confirms the entries in
2729 .Pa /etc/resolv.conf .
2730 If the peer NAKs our request (suggesting new IP numbers),
2731 .Pa /etc/resolv.conf
2732 is updated and another request is sent to confirm the new entries.
2735 .Dq accept Ns No ed,
2737 will answer any DNS queries requested by the peer rather than rejecting
2739 The answer is taken from
2740 .Pa /etc/resolv.conf
2743 command is used as an override.
2745 Default: Enabled and Accepted.
2746 This option allows control over whether we
2747 negotiate an endpoint discriminator.
2748 We only send our discriminator if
2753 We reject the peers discriminator if
2757 Default: Disabled and Accepted.
2758 The use of this authentication protocol
2759 is discouraged as it partially violates the authentication protocol by
2760 implementing two different mechanisms (LANMan & NT) under the guise of
2761 a single CHAP type (0x80).
2763 uses a simple DES encryption mechanism and is the least secure of the
2764 CHAP alternatives (although is still more secure than PAP).
2768 description below for more details.
2770 Default: Disabled and Accepted.
2771 This option decides if Link Quality Requests will be sent or accepted.
2772 LQR is a protocol that allows
2774 to determine that the link is down without relying on the modems
2776 When LQR is enabled,
2782 below) as part of the LCP request.
2783 If the peer agrees, both sides will
2784 exchange LQR packets at the agreed frequency, allowing detailed link
2785 quality monitoring by enabling LQM logging.
2786 If the peer doesn't agree,
2788 will send ECHO LQR requests instead.
2789 These packets pass no information of interest, but they
2791 be replied to by the peer.
2793 Whether using LQR or ECHO LQR,
2795 will abruptly drop the connection if 5 unacknowledged packets have been
2796 sent rather than sending a 6th.
2797 A message is logged at the
2799 level, and any appropriate
2801 values are honoured as if the peer were responsible for dropping the
2804 Default: Enabled and Accepted.
2805 This is Microsoft Point to Point Encryption scheme.
2806 MPPE key size can be
2807 40-, 56- and 128-bits.
2812 Default: Disabled and Accepted.
2813 It is very similar to standard CHAP (type 0x05)
2814 except that it issues challenges of a fixed 16 bytes in length and uses a
2815 combination of MD4, SHA-1 and DES to encrypt the challenge rather than using the
2816 standard MD5 mechanism.
2818 Default: Disabled and Accepted.
2819 The use of this authentication protocol
2820 is discouraged as it partially violates the authentication protocol by
2821 implementing two different mechanisms (LANMan & NT) under the guise of
2822 a single CHAP type (0x80).
2823 It is very similar to standard CHAP (type 0x05)
2824 except that it issues challenges of a fixed 8 bytes in length and uses a
2825 combination of MD4 and DES to encrypt the challenge rather than using the
2826 standard MD5 mechanism.
2827 CHAP type 0x80 for LANMan is also supported - see
2835 use CHAP type 0x80, when acting as authenticator with both
2836 .Dq enable Ns No d ,
2838 will rechallenge the peer up to three times if it responds using the wrong
2839 one of the two protocols.
2840 This gives the peer a chance to attempt using both protocols.
2844 acts as the authenticatee with both protocols
2845 .Dq accept Ns No ed ,
2846 the protocols are used alternately in response to challenges.
2848 Note: If only LANMan is enabled,
2850 (version 2.3.5) misbehaves when acting as authenticatee.
2852 the NT and the LANMan answers, but also suggests that only the NT answer
2855 Default: Disabled and Accepted.
2856 PAP stands for Password Authentication Protocol.
2857 Only one of PAP and CHAP (above) may be negotiated.
2858 With PAP, the ID and Password are sent repeatedly to the peer until
2859 authentication is acknowledged or the connection is terminated.
2860 This is a rather poor security mechanism.
2861 It is only performed when the connection is first established.
2862 If you want to have your peer authenticate itself, you must
2865 .Pa /etc/ppp/ppp.conf ,
2866 and have an entry in
2867 .Pa /etc/ppp/ppp.secret
2868 for the peer (although see the
2874 When using PAP as the client, you need only specify
2879 .Pa /etc/ppp/ppp.conf .
2880 PAP is accepted by default.
2882 Default: Enabled and Accepted.
2883 This option decides if Predictor 1
2884 compression will be used by the Compression Control Protocol (CCP).
2886 Default: Enabled and Accepted.
2887 This option is used to negotiate
2888 PFC (Protocol Field Compression), a mechanism where the protocol
2889 field number is reduced to one octet rather than two.
2891 Default: Enabled and Accepted.
2892 This option determines if
2894 will request and accept requests for short
2896 sequence numbers when negotiating multi-link mode.
2897 This is only applicable if our MRRU is set (thus enabling multi-link).
2899 Default: Enabled and Accepted.
2900 This option determines if Van Jacobson header compression will be used.
2903 The following options are not actually negotiated with the peer.
2904 Therefore, accepting or denying them makes no sense.
2906 .It filter-decapsulation
2908 When this option is enabled,
2910 will examine UDP frames to see if they actually contain a
2912 frame as their payload.
2913 If this is the case, all filters will operate on the payload rather
2914 than the actual packet.
2916 This is useful if you want to send PPPoUDP traffic over a
2918 link, but want that link to do smart things with the real data rather than
2921 The UDP frame payload must not be compressed in any way, otherwise
2923 will not be able to interpret it.
2924 It's therefore recommended that you
2925 .Ic disable vj pred1 deflate
2927 .Ic deny vj pred1 deflate
2928 in the configuration for the
2930 invocation with the udp link.
2935 exchanges low-level LCP, CCP and IPCP configuration traffic, the
2937 field of any replies is expected to be the same as that of the request.
2940 drops any reply packets that do not contain the expected identifier
2941 field, reporting the fact at the respective log level.
2946 will ignore the identifier field.
2951 runs as a Multi-link server, a different
2953 instance initially receives each connection.
2954 After determining that
2955 the link belongs to an already existing bundle (controlled by another
2959 will transfer the link to that process.
2961 If the link is a tty device or if this option is enabled,
2963 will not exit, but will change its process name to
2965 and wait for the controlling
2967 to finish with the link and deliver a signal back to the idle process.
2968 This prevents the confusion that results from
2970 parent considering the link resource available again.
2972 For tty devices that have entries in
2974 this is necessary to prevent another
2976 from being started, and for program links such as
2980 from exiting due to the death of its child.
2983 cannot determine its parents requirements (except for the tty case), this
2984 option must be enabled manually depending on the circumstances.
2991 will automatically loop back packets being sent
2992 out with a destination address equal to that of the
2997 will send the packet, probably resulting in an ICMP redirect from
2999 It is convenient to have this option enabled when
3000 the interface is also the default route as it avoids the necessity
3001 of a loopback route.
3004 Enabling this option will tell the PAP authentication
3005 code to use the password database (see
3007 to authenticate the caller if they cannot be found in the
3008 .Pa /etc/ppp/ppp.secret
3010 .Pa /etc/ppp/ppp.secret
3011 is always checked first.
3012 If you wish to use passwords from
3014 but also to specify an IP number or label for a given client, use
3016 as the client password in
3017 .Pa /etc/ppp/ppp.secret .
3020 Enabling this option will tell
3022 to proxy ARP for the peer.
3025 will make an entry in the ARP table using
3029 address of the local network in which
3032 This allows other machines connecteed to the LAN to talk to
3033 the peer as if the peer itself was connected to the LAN.
3034 The proxy entry cannot be made unless
3036 is an address from a LAN.
3039 Enabling this will tell
3041 to add proxy arp entries for every IP address in all class C or
3042 smaller subnets routed via the tun interface.
3044 Proxy arp entries are only made for sticky routes that are added
3048 No proxy arp entries are made for the interface address itself
3056 command is used with the
3060 values, entries are stored in the
3067 change, this list is re-applied to the routing table.
3069 Disabling this option will prevent the re-application of sticky routes,
3072 list will still be maintained.
3079 to adjust TCP SYN packets so that the maximum receive segment
3080 size is not greater than the amount allowed by the interface MTU.
3085 to gather throughput statistics.
3086 Input and output is sampled over
3087 a rolling 5 second window, and current, best and total figures are retained.
3088 This data is output when the relevant
3090 layer shuts down, and is also available using the
3093 Throughput statistics are available at the
3100 Normally, when a user is authenticated using PAP or CHAP, and when
3104 mode, an entry is made in the utmp and wtmp files for that user.
3105 Disabling this option will tell
3107 not to make any utmp or wtmp entries.
3108 This is usually only necessary if
3109 you require the user to both login and authenticate themselves.
3114 This option simply tells
3116 to add new interface addresses to the interface rather than replacing them.
3117 The option can only be enabled if network address translation is enabled
3118 .Pq Dq nat enable yes .
3120 With this option enabled,
3122 will pass traffic for old interface addresses through the NAT engine
3125 resulting in the ability (in
3127 mode) to properly connect the process that caused the PPP link to
3128 come up in the first place.
3138 .Ar dest Ns Op / Ns Ar nn
3143 is the destination IP address.
3144 The netmask is specified either as a number of bits with
3146 or as an IP number using
3151 with no mask refers to the default route.
3152 It is also possible to use the literal name
3157 is the next hop gateway to get to the given
3162 command for further details.
3164 It is possible to use the symbolic names
3168 as the destination, and
3173 is replaced with the interface address and
3175 is replaced with the interface destination (peer) address.
3182 then if the route already exists, it will be updated as with the
3186 for further details).
3188 Routes that contain the
3194 constants are considered
3196 They are stored in a list (use
3198 to see the list), and each time the value of
3204 changes, the appropriate routing table entries are updated.
3205 This facility may be disabled using
3206 .Dq disable sroutes .
3207 .It allow Ar command Op Ar args
3208 This command controls access to
3210 and its configuration files.
3211 It is possible to allow user-level access,
3212 depending on the configuration file label and on the mode that
3215 For example, you may wish to configure
3225 User id 0 is immune to these commands.
3227 .It allow user Ns Xo
3229 .Ar logname Ns No ...
3231 By default, only user id 0 is allowed access to
3233 If this command is used, all of the listed users are allowed access to
3234 the section in which the
3239 section is always checked first (even though it is only ever automatically
3242 commands are cumulative in a given section, but users allowed in any given
3243 section override users allowed in the default section, so it's possible to
3244 allow users access to everything except a given label by specifying default
3247 section, and then specifying a new user list for that label.
3251 is specified, access is allowed to all users.
3252 .It allow mode Ns Xo
3256 By default, access using any
3259 If this command is used, it restricts the access
3261 allowed to load the label under which this command is specified.
3266 command overrides any previous settings, and the
3268 section is always checked first.
3280 When running in multi-link mode, a section can be loaded if it allows
3282 of the currently existing line modes.
3285 .It nat Ar command Op Ar args
3286 This command allows the control of the network address translation (also
3287 known as masquerading or IP aliasing) facilities that are built into
3289 NAT is done on the external interface only, and is unlikely to make sense
3294 If nat is enabled on your system (it may be omitted at compile time),
3295 the following commands are possible:
3297 .It nat enable yes|no
3298 This command either switches network address translation on or turns it off.
3301 command line flag is synonymous with
3302 .Dq nat enable yes .
3303 .It nat addr Op Ar addr_local addr_alias
3304 This command allows data for
3308 It is useful if you own a small number of real IP numbers that
3309 you wish to map to specific machines behind your gateway.
3310 .It nat deny_incoming yes|no
3311 If set to yes, this command will refuse all incoming packets where an
3312 aliasing link doesn't already exist.
3314 .Sx CONCEPTUAL BACKGROUND
3317 for a description of what an
3321 It should be noted under what circumstances an aliasing link is created by
3323 It may be necessary to further protect your network from outside
3324 connections using the
3330 This command gives a summary of available nat commands.
3332 This option causes various NAT statistics and information to
3333 be logged to the file
3334 .Pa /var/log/alias.log .
3335 .It nat port Ar proto Ar targetIP Ns Xo
3336 .No : Ns Ar targetPort Ns
3338 .No - Ns Ar targetPort
3341 .No - Ns Ar aliasPort
3342 .Oc Oo Ar remoteIP : Ns
3345 .No - Ns Ar remotePort
3349 This command causes incoming
3363 A range of port numbers may be specified as shown above.
3364 The ranges must be of the same size.
3368 is specified, only data coming from that IP number is redirected.
3372 (indicating any source port)
3373 or a range of ports the same size as the other ranges.
3375 This option is useful if you wish to run things like Internet phone on
3376 machines behind your gateway, but is limited in that connections to only
3377 one interior machine per source machine and target port are possible.
3378 .It nat proto Ar proto localIP Oo
3379 .Ar publicIP Op Ar remoteIP
3383 to redirect packets of protocol type
3387 to the internall address
3392 is specified, only packets destined for that address are matched,
3393 otherwise the default alias address is used.
3397 is specified, only packets matching that source address are matched,
3399 This command is useful for redirecting tunnel endpoints to an internal machine,
3402 .Dl nat proto ipencap 10.0.0.1
3403 .It "nat proxy cmd" Ar arg Ns No ...
3406 to proxy certain connections, redirecting them to a given server.
3407 Refer to the description of
3408 .Fn PacketAliasProxyRule
3411 for details of the available commands.
3412 .It nat punch_fw Op Ar base count
3415 to punch holes in the firewall for FTP or IRC DCC connections.
3416 This is done dynamically by installing termporary firewall rules which
3417 allow a particular connection (and only that connection) to go through
3419 The rules are removed once the corresponding connection terminates.
3423 rules starting from rule number
3425 will be used for punching firewall holes.
3426 The range will be cleared when the
3430 If no arguments are given, firewall punching is disabled.
3431 .It nat same_ports yes|no
3432 When enabled, this command will tell the network address translation engine to
3433 attempt to avoid changing the port number on outgoing packets.
3435 if you want to support protocols such as RPC and LPD which require
3436 connections to come from a well known port.
3437 .It nat target Op Ar address
3438 Set the given target address or clear it if no address is given.
3439 The target address is used by libalias to specify how to NAT incoming
3441 If a target address is not set or if
3443 is given, packets are not altered and are allowed to route to the internal
3446 The target address may be set to
3448 in which case libalias will redirect all packets to the interface address.
3449 .It nat use_sockets yes|no
3450 When enabled, this option tells the network address translation engine to
3451 create a socket so that it can guarantee a correct incoming ftp data or
3453 .It nat unregistered_only yes|no
3454 Only alter outgoing packets with an unregistered source address.
3455 According to RFC 1918, unregistered source addresses
3456 are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16.
3459 These commands are also discussed in the file
3461 which comes with the source distribution.
3468 is executed in the background with the following words replaced:
3469 .Bl -tag -width PEER_ENDDISC
3471 This is replaced with the local
3477 .It Li COMPILATIONDATE
3478 This is replaced with the date on which
3482 These are replaced with the primary and secondary nameserver IP numbers.
3483 If nameservers are negotiated by IPCP, the values of these macros will change.
3485 This is replaced with the local endpoint discriminator value.
3490 This is replaced with the peers IP number.
3492 This is replaced with the name of the interface that's in use.
3494 This is replaced with the last label name used.
3495 A label may be specified on the
3497 command line, via the
3505 This is replaced with the IP number assigned to the local interface.
3507 This is replaced with the value of the peers endpoint discriminator.
3509 This is replaced with the current process id.
3511 This is replaced with the current version number of
3514 This is replaced with the username that has been authenticated with PAP or
3516 Normally, this variable is assigned only in -direct mode.
3517 This value is available irrespective of whether utmp logging is enabled.
3520 These substitutions are also done by the
3524 If you wish to pause
3526 while the command executes, use the
3529 .It clear physical|ipcp Op current|overall|peak...
3530 Clear the specified throughput values at either the
3537 is specified, context must be given (see the
3540 If no second argument is given, all values are cleared.
3541 .It clone Ar name Ns Xo
3542 .Op \&, Ns Ar name Ns
3545 Clone the specified link, creating one or more new links according to the
3548 This command must be used from the
3550 command below unless you've only got a single link (in which case that
3551 link becomes the default).
3552 Links may be removed using the
3556 The default link name is
3558 .It close Op lcp|ccp Ns Op !\&
3559 If no arguments are given, the relevant protocol layers will be brought
3560 down and the link will be closed.
3563 is specified, the LCP layer is brought down, but
3565 will not bring the link offline.
3566 It is subsequently possible to use
3569 to talk to the peer machine if, for example, something like
3574 is specified, only the relevant compression layer is closed.
3577 is used, the compression layer will remain in the closed state, otherwise
3578 it will re-enter the STOPPED state, waiting for the peer to initiate
3579 further CCP negotiation.
3580 In any event, this command does not disconnect the user from
3591 This command deletes the route with the given
3598 all non-direct entries in the routing table for the current interface,
3601 entries are deleted.
3606 the default route is deleted.
3614 will not complain if the route does not already exist.
3615 .It dial|call Op Ar label Ns Xo
3618 This command is the equivalent of
3622 and is provided for backwards compatibility.
3623 .It down Op Ar lcp|ccp
3624 Bring the relevant layer down ungracefully, as if the underlying layer
3625 had become unavailable.
3626 It's not considered polite to use this command on
3627 a Finite State Machine that's in the OPEN state.
3629 supplied, the entire link is closed (or if no context is given, all links
3635 layer is terminated but the device is not brought offline and the link
3639 is specified, only the relevant compression layer(s) are terminated.
3640 .It help|? Op Ar command
3641 Show a list of available commands.
3644 is specified, show the usage string for that command.
3645 .It ident Op Ar text Ns No ...
3646 Identify the link to the peer using
3650 is empty, link identification is disabled.
3651 It is possible to use any of the words described for the
3656 command for details of when
3658 identifies itself to the peer.
3659 .It iface Ar command Op args
3660 This command is used to control the interface used by
3663 may be one of the following:
3667 .Ar addr Ns Op / Ns Ar bits
3678 combination to the interface.
3679 Instead of specifying
3683 (with no space between it and
3685 If the given address already exists, the command fails unless the
3687 is used - in which case the previous interface address entry is overwritten
3688 with the new one, allowing a change of netmask or peer address.
3699 .Dq 255.255.255.255 .
3700 This address (the broadcast address) is the only duplicate peer address that
3704 If this command is used while
3706 is in the OPENED state or while in
3708 mode, all addresses except for the IPCP negotiated address are deleted
3712 is not in the OPENED state and is not in
3714 mode, all interface addresses are deleted.
3716 .It iface delete Ns Xo
3721 This command deletes the given
3726 is used, no error is given if the address isn't currently assigned to
3727 the interface (and no deletion takes place).
3729 Shows the current state and current addresses for the interface.
3730 It is much the same as running
3731 .Dq ifconfig INTERFACE .
3732 .It iface help Op Ar sub-command
3733 This command, when invoked without
3735 will show a list of possible
3737 sub-commands and a brief synopsis for each.
3740 only the synopsis for the given sub-command is shown.
3744 .Ar name Ns Op , Ns Ar name Ns
3745 .No ... Ar command Op Ar args
3747 This command may prefix any other command if the user wishes to
3748 specify which link the command should affect.
3749 This is only applicable after multiple links have been created in Multi-link
3755 specifies the name of an existing link.
3758 is a comma separated list,
3760 is executed on each link.
3766 is executed on all links.
3767 .It load Op Ar label Ns Xo
3790 will not attempt to make an immediate connection.
3791 .It open Op lcp|ccp|ipcp
3792 This is the opposite of the
3795 All closed links are immediately brought up apart from second and subsequent
3797 links - these will come up based on the
3799 command that has been used.
3803 argument is used while the LCP layer is already open, LCP will be
3805 This allows various LCP options to be changed, after which
3807 can be used to put them into effect.
3808 After renegotiating LCP,
3809 any agreed authentication will also take place.
3813 argument is used, the relevant compression layer is opened.
3814 Again, if it is already open, it will be renegotiated.
3818 argument is used, the link will be brought up as normal, but if
3819 IPCP is already open, it will be renegotiated and the network
3820 interface will be reconfigured.
3822 It is probably not good practice to re-open the PPP state machines
3823 like this as it's possible that the peer will not behave correctly.
3826 however useful as a way of forcing the CCP or VJ dictionaries to be reset.
3828 Specify the password required for access to the full
3831 This password is required when connecting to the diagnostic port (see the
3842 logging is active, instead, the literal string
3848 is executed from the controlling connection or from a command file,
3849 ppp will exit after closing all connections.
3850 Otherwise, if the user
3851 is connected to a diagnostic socket, the connection is simply dropped.
3857 will exit despite the source of the command after closing all existing
3860 This command removes the given link.
3861 It is only really useful in multi-link mode.
3862 A link must be in the
3864 state before it is removed.
3865 .It rename|mv Ar name
3866 This command renames the given link to
3870 is already used by another link.
3872 The default link name is
3879 may make the log file more readable.
3880 .It resolv Ar command
3881 This command controls
3888 starts up, it loads the contents of this file into memory and retains this
3889 image for future use.
3891 is one of the following:
3892 .Bl -tag -width readonly
3895 .Pa /etc/resolv.conf
3901 will still attempt to negotiate nameservers with the peer, making the results
3907 This is the opposite of the
3912 .Pa /etc/resolv.conf
3914 This may be necessary if for example a DHCP client overwrote
3915 .Pa /etc/resolv.conf .
3918 .Pa /etc/resolv.conf
3919 with the version originally read at startup or with the last
3922 This is sometimes a useful command to put in the
3923 .Pa /etc/ppp/ppp.linkdown
3927 .Pa /etc/resolv.conf
3929 This command will work even if the
3931 command has been used.
3932 It may be useful as a command in the
3933 .Pa /etc/ppp/ppp.linkup
3934 file if you wish to defer updating
3935 .Pa /etc/resolv.conf
3936 until after other commands have finished.
3941 .Pa /etc/resolv.conf
3946 successfully negotiates a DNS.
3947 This is the opposite of the
3952 This option is not (yet) implemented.
3956 to identify itself to the peer.
3957 The link must be in LCP state or higher.
3958 If no identity has been set (via the
3964 When an identity has been set,
3966 will automatically identify itself when it sends or receives a configure
3967 reject, when negotiation fails or when LCP reaches the opened state.
3969 Received identification packets are logged to the LCP log (see
3971 for details) and are never responded to.
3976 This option allows the setting of any of the following variables:
3978 .It set accmap Ar hex-value
3979 ACCMap stands for Asynchronous Control Character Map.
3981 negotiated with the peer, and defaults to a value of 00000000 in hex.
3982 This protocol is required to defeat hardware that depends on passing
3983 certain characters from end to end (such as XON/XOFF etc).
3985 For the XON/XOFF scenario, use
3986 .Dq set accmap 000a0000 .
3987 .It set Op auth Ns Xo
3990 This sets the authentication key (or password) used in client mode
3991 PAP or CHAP negotiation to the given value.
3992 It also specifies the
3993 password to be used in the dial or login scripts in place of the
3995 sequence, preventing the actual password from being logged.
4000 logging is in effect,
4004 for security reasons.
4006 If the first character of
4008 is an exclamation mark
4011 treats the remainder of the string as a program that must be executed
4023 it is treated as a single literal
4025 otherwise, ignoring the
4028 is parsed as a program to execute in the same was as the
4030 command above, substituting special names in the same manner.
4033 will feed the program three lines of input, each terminated by a newline
4037 The host name as sent in the CHAP challenge.
4039 The challenge string as sent in the CHAP challenge.
4045 Two lines of output are expected:
4050 to be sent with the CHAP response.
4054 which is encrypted with the challenge and request id, the answer being sent
4055 in the CHAP response packet.
4060 in this manner, it's expected that the host challenge is a series of ASCII
4061 digits or characters.
4062 An encryption device or Secure ID card is usually
4063 required to calculate the secret appropriate for the given challenge.
4064 .It set authname Ar id
4065 This sets the authentication id used in client mode PAP or CHAP negotiation.
4069 mode with CHAP enabled,
4071 is used in the initial authentication challenge and should normally be set to
4072 the local machine name.
4074 .Ar min-percent max-percent period
4076 These settings apply only in multi-link mode and default to zero, zero and
4082 mode link is available, only the first link is made active when
4084 first reads data from the tun device.
4087 link will be opened only when the current bundle throughput is at least
4089 percent of the total bundle bandwidth for
4092 When the current bundle throughput decreases to
4094 percent or less of the total bundle bandwidth for
4098 link will be brought down as long as it's not the last active link.
4100 Bundle throughput is measured as the maximum of inbound and outbound
4103 The default values cause
4105 links to simply come up one at a time.
4107 Certain devices cannot determine their physical bandwidth, so it
4108 is sometimes necessary to use the
4110 command (described below) to make
4113 .It set bandwidth Ar value
4114 This command sets the connection bandwidth in bits per second.
4116 must be greater than zero.
4117 It is currently only used by the
4120 .It set callback Ar option Ns No ...
4121 If no arguments are given, callback is disabled, otherwise,
4125 mode, will accept) one of the given
4126 .Ar option Ns No s .
4127 In client mode, if an
4131 will request a different
4133 until no options remain at which point
4135 will terminate negotiations (unless
4137 is one of the specified
4141 will accept any of the given protocols - but the client
4143 request one of them.
4144 If you wish callback to be optional, you must include
4150 are as follows (in this order of preference):
4154 The callee is expected to decide the callback number based on
4158 is the callee, the number should be specified as the fifth field of
4160 .Pa /etc/ppp/ppp.secret .
4162 Microsoft's callback control protocol is used.
4167 If you wish to negotiate
4169 in client mode but also wish to allow the server to request no callback at
4170 CBCP negotiation time, you must specify both
4174 as callback options.
4176 .Ar number Ns Op , Ns Ar number Ns
4179 The caller specifies the
4185 should be either a comma separated list of allowable numbers or a
4187 meaning any number is permitted.
4190 is the caller, only a single number should be specified.
4192 Note, this option is very unsafe when used with a
4194 as a malicious caller can tell
4196 to call any (possibly international) number without first authenticating
4199 If the peer does not wish to do callback at all,
4201 will accept the fact and continue without callback rather than terminating
4203 This is required (in addition to one or more other callback
4204 options) if you wish callback to be optional.
4208 .No *| Ns Ar number Ns Oo
4209 .No , Ns Ar number Ns ...\& Oc
4210 .Op Ar delay Op Ar retry
4212 If no arguments are given, CBCP (Microsoft's CallBack Control Protocol)
4213 is disabled - ie, configuring CBCP in the
4215 command will result in
4217 requesting no callback in the CBCP phase.
4220 attempts to use the given phone
4221 .Ar number Ns No (s).
4226 will insist that the client uses one of these numbers, unless
4228 is used in which case the client is expected to specify the number.
4232 will attempt to use one of the given numbers (whichever it finds to
4233 be agreeable with the peer), or if
4237 will expect the peer to specify the number.
4239 .No off| Ns Ar seconds Ns Op !\&
4243 checks for the existence of carrier depending on the type of device
4244 that has been opened:
4245 .Bl -tag -width XXX -offset XXX
4246 .It Terminal Devices
4247 Carrier is checked one second after the login script is complete.
4250 assumes that this is because the device doesn't support carrier (which
4253 NULL-modem cables), logs the fact and stops checking
4256 As ptys don't support the TIOCMGET ioctl, the tty device will switch all
4257 carrier detection off when it detects that the device is a pty.
4258 .It ISDN (i4b) Devices
4259 Carrier is checked once per second for 6 seconds.
4260 If it's not set after
4261 the sixth second, the connection attempt is considered to have failed and
4262 the device is closed.
4263 Carrier is always required for i4b devices.
4264 .It PPPoE (netgraph) Devices
4265 Carrier is checked once per second for 5 seconds.
4266 If it's not set after
4267 the fifth second, the connection attempt is considered to have failed and
4268 the device is closed.
4269 Carrier is always required for PPPoE devices.
4272 All other device types don't support carrier.
4273 Setting a carrier value will
4274 result in a warning when the device is opened.
4276 Some modems take more than one second after connecting to assert the carrier
4278 If this delay isn't increased, this will result in
4280 inability to detect when the link is dropped, as
4282 assumes that the device isn't asserting carrier.
4286 command overrides the default carrier behaviour.
4288 specifies the maximum number of seconds that
4290 should wait after the dial script has finished before deciding if
4291 carrier is available or not.
4297 will not check for carrier on the device, otherwise
4299 will not proceed to the login script until either carrier is detected
4302 has elapsed, at which point
4304 assumes that the device will not set carrier.
4306 If no arguments are given, carrier settings will go back to their default
4311 is followed immediately by an exclamation mark
4317 If carrier is not detected after
4319 seconds, the link will be disconnected.
4320 .It set choked Op Ar timeout
4321 This sets the number of seconds that
4323 will keep a choked output queue before dropping all pending output packets.
4326 is less than or equal to zero or if
4328 isn't specified, it is set to the default value of
4331 A choked output queue occurs when
4333 has read a certain number of packets from the local network for transmission,
4334 but cannot send the data due to link failure (the peer is busy etc.).
4336 will not read packets indefinitely.
4337 Instead, it reads up to
4343 packets in multi-link mode), then stops reading the network interface
4346 seconds have passed or at least one packet has been sent.
4350 seconds pass, all pending output packets are dropped.
4351 .It set ctsrts|crtscts on|off
4352 This sets hardware flow control.
4353 Hardware flow control is
4356 .It set deflate Ar out-winsize Op Ar in-winsize
4357 This sets the DEFLATE algorithms default outgoing and incoming window
4363 must be values between
4371 will insist that this window size is used and will not accept any other
4372 values from the peer.
4373 .It set dns Op Ar primary Op Ar secondary
4374 This command specifies DNS overrides for the
4379 command description above for details.
4380 This command does not affect the IP numbers requested using
4382 .It set device|line Xo
4385 This sets the device(s) to which
4387 will talk to the given
4390 All ISDN and serial device names are expected to begin with
4392 ISDN devices are usually called
4394 and serial devices are usually called
4401 it must either begin with an exclamation mark
4404 .No PPPoE: Ns Ar iface Ns Xo
4405 .Op \&: Ns Ar provider Ns
4409 enabled systems), or be of the format
4411 .Ar host : port Op /tcp|udp .
4414 If it begins with an exclamation mark, the rest of the device name is
4415 treated as a program name, and that program is executed when the device
4417 Standard input, output and error are fed back to
4419 and are read and written as if they were a regular device.
4422 .No PPPoE: Ns Ar iface Ns Xo
4423 .Op \&: Ns Ar provider Ns
4425 specification is given,
4427 will attempt to create a
4429 over Ethernet connection using the given
4437 will attempt to load it using
4439 If this fails, an external program must be used such as the
4441 program available under OpenBSD.
4444 is passed as the service name in the PPPoE Discovery Initiation (PADI)
4446 If no provider is given, an empty value will be used.
4451 for further details.
4454 .Ar host Ns No : Ns Ar port Ns Oo
4457 specification is given,
4459 will attempt to connect to the given
4467 suffix is not provided, the default is
4469 Refer to the section on
4470 .Em PPP OVER TCP and UDP
4471 above for further details.
4477 will attempt to open each one in turn until it succeeds or runs out of
4479 .It set dial Ar chat-script
4480 This specifies the chat script that will be used to dial the other
4487 and to the example configuration files for details of the chat script
4489 It is possible to specify some special
4491 in your chat script as follows:
4494 When used as the last character in a
4496 string, this indicates that a newline should not be appended.
4498 When the chat script encounters this sequence, it delays two seconds.
4500 When the chat script encounters this sequence, it delays for one quarter of
4503 This is replaced with a newline character.
4505 This is replaced with a carriage return character.
4507 This is replaced with a space character.
4509 This is replaced with a tab character.
4511 This is replaced by the current phone number (see
4515 This is replaced by the current
4521 This is replaced by the current
4528 Note that two parsers will examine these escape sequences, so in order to
4531 see the escape character, it is necessary to escape it from the
4532 .Sq command parser .
4533 This means that in practice you should use two escapes, for example:
4534 .Bd -literal -offset indent
4535 set dial "... ATDT\\\\T CONNECT"
4538 It is also possible to execute external commands from the chat script.
4539 To do this, the first character of the expect or send string is an
4542 If a literal exclamation mark is required, double it up to
4544 and it will be treated as a single literal
4546 When the command is executed, standard input and standard output are
4547 directed to the open device (see the
4549 command), and standard error is read by
4551 and substituted as the expect or send string.
4554 is running in interactive mode, file descriptor 3 is attached to
4557 For example (wrapped for readability):
4558 .Bd -literal -offset indent
4559 set login "TIMEOUT 5 \\"\\" \\"\\" login:--login: ppp \e
4560 word: ppp \\"!sh \\\\-c \\\\\\"echo \\\\-n label: >&2\\\\\\"\\" \e
4561 \\"!/bin/echo in\\" HELLO"
4564 would result in the following chat sequence (output using the
4565 .Sq set log local chat
4566 command before dialing):
4567 .Bd -literal -offset indent
4572 Chat: Expecting: login:--login:
4573 Chat: Wait for (5): login:
4575 Chat: Expecting: word:
4576 Chat: Wait for (5): word:
4578 Chat: Expecting: !sh \\-c "echo \\-n label: >&2"
4579 Chat: Exec: sh -c "echo -n label: >&2"
4580 Chat: Wait for (5): !sh \\-c "echo \\-n label: >&2" --> label:
4581 Chat: Exec: /bin/echo in
4583 Chat: Expecting: HELLO
4584 Chat: Wait for (5): HELLO
4588 Note (again) the use of the escape character, allowing many levels of
4590 Here, there are four parsers at work.
4591 The first parses the original line, reading it as three arguments.
4592 The second parses the third argument, reading it as 11 arguments.
4593 At this point, it is
4596 signs are escaped, otherwise this parser will see them as constituting
4597 an expect-send-expect sequence.
4600 character is seen, the execution parser reads the first command as three
4603 itself expands the argument after the
4605 As we wish to send the output back to the modem, in the first example
4606 we redirect our output to file descriptor 2 (stderr) so that
4608 itself sends and logs it, and in the second example, we just output to stdout,
4609 which is attached directly to the modem.
4611 This, of course means that it is possible to execute an entirely external
4613 command rather than using the internal one.
4616 for a good alternative.
4618 The external command that is executed is subjected to the same special
4619 word expansions as the
4622 .It set enddisc Op label|IP|MAC|magic|psn value
4623 This command sets our local endpoint discriminator.
4624 If set prior to LCP negotiation, and if no
4626 command has been used,
4628 will send the information to the peer using the LCP endpoint discriminator
4630 The following discriminators may be set:
4631 .Bl -tag -width indent
4633 The current label is used.
4635 Our local IP number is used.
4636 As LCP is negotiated prior to IPCP, it is
4637 possible that the IPCP layer will subsequently change this value.
4639 it does, the endpoint discriminator stays at the old value unless manually
4642 This is similar to the
4644 option above, except that the MAC address associated with the local IP
4646 If the local IP number is not resident on any Ethernet
4647 interface, the command will fail.
4649 As the local IP number defaults to whatever the machine host name is,
4651 is usually done prior to any
4655 A 20 digit random number is used.
4656 Care should be taken when using magic numbers as restarting
4658 or creating a link using a different
4660 invocation will also use a different magic number and will therefore not
4661 be recognised by the peer as belonging to the same bundle.
4662 This makes it unsuitable for
4670 should be set to an absolute public switched network number with the
4674 If no arguments are given, the endpoint discriminator is reset.
4675 .It set escape Ar value...
4676 This option is similar to the
4679 It allows the user to specify a set of characters that will be
4681 as they travel across the link.
4682 .It set filter dial|alive|in|out Ar rule-no Xo
4683 .No permit|deny|clear| Ns Ar rule-no
4686 .Ar src_addr Ns Op / Ns Ar width
4687 .Op Ar dst_addr Ns Op / Ns Ar width
4688 .Oc [ tcp|udp|ospf|ipip|igmp|icmp Op src lt|eq|gt Ar port
4689 .Op dst lt|eq|gt Ar port
4693 .Op timeout Ar secs ]
4696 supports four filter sets.
4699 filter specifies packets that keep the connection alive - resetting the
4703 filter specifies packets that cause
4710 filter specifies packets that are allowed to travel
4711 into the machine and the
4713 filter specifies packets that are allowed out of the machine.
4715 Filtering is done prior to any IP alterations that might be done by the
4716 NAT engine on outgoing packets and after any IP alterations that might
4717 be done by the NAT engine on incoming packets.
4718 By default all empty filter sets allow all packets to pass.
4719 Rules are processed in order according to
4721 (unless skipped by specifying a rule number as the
4723 Up to 40 rules may be given for each set.
4724 If a packet doesn't match
4725 any of the rules in a given set, it is discarded.
4730 filters, this means that the packet is dropped.
4733 filters it means that the packet will not reset the idle timer (even if
4735 .Ar in Ns No / Ns Ar out
4738 value) and in the case of
4740 filters it means that the packet will not trigger a dial.
4741 A packet failing to trigger a dial will be dropped rather than queued.
4744 .Sx PACKET FILTERING
4745 above for further details.
4746 .It set hangup Ar chat-script
4747 This specifies the chat script that will be used to reset the device
4748 before it is closed.
4749 It should not normally be necessary, but can
4750 be used for devices that fail to reset themselves properly on close.
4751 .It set help|? Op Ar command
4752 This command gives a summary of available set commands, or if
4754 is specified, the command usage is shown.
4755 .It set ifaddr Oo Ar myaddr Ns
4757 .Oo Ar hisaddr Ns Op / Ns Ar \&nn
4762 This command specifies the IP addresses that will be used during
4764 Addresses are specified using the format
4770 is the preferred IP, but
4772 specifies how many bits of the address we will insist on.
4775 is omitted, it defaults to
4777 unless the IP address is 0.0.0.0 in which case it defaults to
4780 If you wish to assign a dynamic IP number to the peer,
4782 may also be specified as a range of IP numbers in the format
4783 .Bd -ragged -offset indent
4784 .Ar \&IP Ns Oo \&- Ns Ar \&IP Ns Xo
4785 .Oc Ns Oo , Ns Ar \&IP Ns
4786 .Op \&- Ns Ar \&IP Ns
4793 .Dl set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20
4797 as the local IP number, but may assign any of the given 10 IP
4798 numbers to the peer.
4799 If the peer requests one of these numbers,
4800 and that number is not already in use,
4802 will grant the peers request.
4803 This is useful if the peer wants
4804 to re-establish a link using the same IP number as was previously
4805 allocated (thus maintaining any existing tcp or udp connections).
4807 If the peer requests an IP number that's either outside
4808 of this range or is already in use,
4810 will suggest a random unused IP number from the range.
4814 is specified, it is used in place of
4816 in the initial IPCP negotiation.
4817 However, only an address in the
4819 range will be accepted.
4820 This is useful when negotiating with some
4822 implementations that will not assign an IP number unless their peer
4826 It should be noted that in
4830 will configure the interface immediately upon reading the
4832 line in the config file.
4833 In any other mode, these values are just
4834 used for IPCP negotiations, and the interface isn't configured
4835 until the IPCP layer is up.
4839 argument may be overridden by the third field in the
4841 file once the client has authenticated itself
4845 .Sx AUTHENTICATING INCOMING CONNECTIONS
4846 section for details.
4848 In all cases, if the interface is already configured,
4850 will try to maintain the interface IP numbers so that any existing
4851 bound sockets will remain valid.
4852 .It set ifqueue Ar packets
4853 Set the maximum number of packets that
4855 will read from the tunnel interface while data cannot be sent to any of
4856 the available links.
4857 This queue limit is necessary to flow control outgoing data as the tunnel
4858 interface is likely to be far faster than the combined links available to
4863 is set to a value less than the number of links,
4865 will read up to that value regardless.
4866 This prevents any possible latency problems.
4868 The default value for
4872 .It set ccpretry|ccpretries Oo Ar timeout
4873 .Op Ar reqtries Op Ar trmtries
4875 .It set chapretry|chapretries Oo Ar timeout
4878 .It set ipcpretry|ipcpretries Oo Ar timeout
4879 .Op Ar reqtries Op Ar trmtries
4881 .It set lcpretry|lcpretries Oo Ar timeout
4882 .Op Ar reqtries Op Ar trmtries
4884 .It set papretry|papretries Oo Ar timeout
4887 These commands set the number of seconds that
4889 will wait before resending Finite State Machine (FSM) Request packets.
4892 for all FSMs is 3 seconds (which should suffice in most cases).
4896 is specified, it tells
4898 how many configuration request attempts it should make while receiving
4899 no reply from the peer before giving up.
4900 The default is 5 attempts for
4901 CCP, LCP and IPCP and 3 attempts for PAP and CHAP.
4905 is specified, it tells
4907 how many terminate requests should be sent before giving up waiting for the
4909 The default is 3 attempts.
4910 Authentication protocols are
4911 not terminated and it is therefore invalid to specify
4915 In order to avoid negotiations with the peer that will never converge,
4917 will only send at most 3 times the configured number of
4919 in any given negotiation session before giving up and closing that layer.
4925 This command allows the adjustment of the current log level.
4926 Refer to the Logging Facility section for further details.
4927 .It set login Ar chat-script
4930 compliments the dial-script.
4931 If both are specified, the login
4932 script will be executed after the dial script.
4933 Escape sequences available in the dial script are also available here.
4934 .It set logout Ar chat-script
4935 This specifies the chat script that will be used to logout
4936 before the hangup script is called.
4937 It should not normally be necessary.
4938 .It set lqrperiod Ar frequency
4939 This command sets the
4946 The default is 30 seconds.
4947 You must also use the
4949 command if you wish to send LQR requests to the peer.
4950 .It set mode Ar interactive|auto|ddial|background
4951 This command allows you to change the
4953 of the specified link.
4954 This is normally only useful in multi-link mode,
4955 but may also be used in uni-link mode.
4957 It is not possible to change a link that is
4962 Note: If you issue the command
4964 and have network address translation enabled, it may be useful to
4965 .Dq enable iface-alias
4969 to do the necessary address translations to enable the process that
4970 triggers the connection to connect once the link is up despite the
4971 peer assigning us a new (dynamic) IP address.
4972 .It set mppe Op 40|56|128|* Op stateless|stateful|*
4973 This option selects the encryption parameters used when negotiation
4975 MPPE can be disabled entirely with the
4978 If no arguments are given,
4980 will attempt to negotiate a stateful link with a 128 bit key, but
4981 will agree to whatever the peer requests (including no encryption
4984 If any arguments are given,
4988 on using MPPE and will close the link if it's rejected by the peer.
4990 The first argument specifies the number of bits that
4992 should insist on during negotiations and the second specifies whether
4994 should insist on stateful or stateless mode.
4995 In stateless mode, the
4996 encryption dictionary is re-initialised with every packet according to
4997 an encryption key that is changed with every packet.
4999 the encryption dictionary is re-initialised every 256 packets or after
5000 the loss of any data and the key is changed every 256 packets.
5001 Stateless mode is less efficient but is better for unreliable transport
5003 .It set mrru Op Ar value
5004 Setting this option enables Multi-link PPP negotiations, also known as
5005 Multi-link Protocol or MP.
5006 There is no default MRRU (Maximum Reconstructed Receive Unit) value.
5007 If no argument is given, multi-link mode is disabled.
5012 The default MRU (Maximum Receive Unit) is 1500.
5013 If it is increased, the other side *may* increase its MTU.
5014 In theory there is no point in decreasing the MRU to below the default as the
5016 protocol says implementations *must* be able to accept packets of at
5023 will refuse to negotiate a higher value.
5024 The maximum MRU can be set to 2048 at most.
5025 Setting a maximum of less than 1500 violates the
5027 rfc, but may sometimes be necessary.
5030 imposes a maximum of 1492 due to hardware limitations.
5032 If no argument is given, 1500 is assumed.
5033 A value must be given when
5040 The default MTU is 1500.
5041 At negotiation time,
5043 will accept whatever MRU the peer requests (assuming it's
5044 not less than 296 bytes or greater than the assigned maximum).
5047 will not accept MRU values less than
5049 When negotiations are complete, the MTU is used when writing to the
5050 interface, even if the peer requested a higher value MRU.
5051 This can be useful for
5052 limiting your packet size (giving better bandwidth sharing at the expense
5053 of more header data).
5059 will refuse to negotiate a higher value.
5060 The maximum MTU can be set to 2048 at most.
5064 is given, 1500, or whatever the peer asks for is used.
5065 A value must be given when
5068 .It set nbns Op Ar x.x.x.x Op Ar y.y.y.y
5069 This option allows the setting of the Microsoft NetBIOS name server
5070 values to be returned at the peers request.
5071 If no values are given,
5073 will reject any such requests.
5074 .It set openmode active|passive Op Ar delay
5083 will always initiate LCP/IPCP/CCP negotiation one second after the line
5085 If you want to wait for the peer to initiate negotiations, you
5088 If you want to initiate negotiations immediately or after more than one
5089 second, the appropriate
5091 may be specified here in seconds.
5092 .It set parity odd|even|none|mark
5093 This allows the line parity to be set.
5094 The default value is
5096 .It set phone Ar telno Ns Xo
5097 .Oo \&| Ns Ar backupnumber
5098 .Oc Ns ... Ns Oo : Ns Ar nextnumber
5101 This allows the specification of the phone number to be used in
5102 place of the \\\\T string in the dial and login chat scripts.
5103 Multiple phone numbers may be given separated either by a pipe
5108 Numbers after the pipe are only dialed if the dial or login
5109 script for the previous number failed.
5111 Numbers after the colon are tried sequentially, irrespective of
5112 the reason the line was dropped.
5114 If multiple numbers are given,
5116 will dial them according to these rules until a connection is made, retrying
5117 the maximum number of times specified by
5122 mode, each number is attempted at most once.
5123 .It set Op proc Ns Xo
5124 .No title Op Ar value
5126 The current process title as displayed by
5128 is changed according to
5132 is not specified, the original process title is restored.
5134 word replacements done by the shell commands (see the
5136 command above) are done here too.
5138 Note, if USER is required in the process title, the
5140 command must appear in
5142 as it is not known when the commands in
5145 .It set radius Op Ar config-file
5146 This command enables RADIUS support (if it's compiled in).
5148 refers to the radius client configuration file as described in
5151 .Dq enable Ns No d ,
5154 .Em \&N Ns No etwork
5157 and uses the configured RADIUS server to authenticate rather than
5158 authenticating from the
5160 file or from the passwd database.
5162 If neither PAP or CHAP are enabled,
5167 uses the following attributes from the RADIUS reply:
5168 .Bl -tag -width XXX -offset XXX
5169 .It RAD_FRAMED_IP_ADDRESS
5170 The peer IP address is set to the given value.
5171 .It RAD_FRAMED_IP_NETMASK
5172 The tun interface netmask is set to the given value.
5174 If the given MTU is less than the peers MRU as agreed during LCP
5175 negotiation, *and* it is less that any configured MTU (see the
5177 command), the tun interface MTU is set to the given value.
5178 .It RAD_FRAMED_COMPRESSION
5179 If the received compression type is
5182 will request VJ compression during IPCP negotiations despite any
5184 configuration command.
5185 .It RAD_FRAMED_ROUTE
5186 The received string is expected to be in the format
5187 .Ar dest Ns Op / Ns Ar bits
5190 Any specified metrics are ignored.
5194 are understood as valid values for
5201 to sepcify the default route, and
5203 is understood to be the same as
5212 For example, a returned value of
5213 .Dq 1.2.3.4/24 0.0.0.0 1 2 -1 3 400
5214 would result in a routing table entry to the 1.2.3.0/24 network via
5216 and a returned value of
5220 would result in a default route to
5223 All RADIUS routes are applied after any sticky routes are applied, making
5224 RADIUS routes override configured routes.
5225 This also applies for RADIUS routes that don't include the
5232 Values received from the RADIUS server may be viewed using
5234 .It set reconnect Ar timeout ntries
5235 Should the line drop unexpectedly (due to loss of CD or LQR
5236 failure), a connection will be re-established after the given
5238 The line will be re-connected at most
5247 will result in a variable pause, somewhere between 1 and 30 seconds.
5248 .It set recvpipe Op Ar value
5249 This sets the routing table RECVPIPE value.
5250 The optimum value is just over twice the MTU value.
5253 is unspecified or zero, the default kernel controlled value is used.
5254 .It set redial Ar secs Ns Xo
5257 .Oc Ns Op . Ns Ar next
5261 can be instructed to attempt to redial
5264 If more than one phone number is specified (see
5268 is taken before dialing each number.
5271 is taken before starting at the first number again.
5274 may be used here in place of
5278 causing a random delay of between 1 and 30 seconds.
5282 is specified, its value is added onto
5288 will only be incremented at most
5296 delay will be effective, even after
5298 has been exceeded, so an immediate manual dial may appear to have
5300 If an immediate dial is required, a
5302 should immediately follow the
5307 description above for further details.
5308 .It set sendpipe Op Ar value
5309 This sets the routing table SENDPIPE value.
5310 The optimum value is just over twice the MTU value.
5313 is unspecified or zero, the default kernel controlled value is used.
5314 .It "set server|socket" Ar TcpPort Ns No \&| Ns Xo
5315 .Ar LocalName Ns No |none|open|closed
5316 .Op password Op Ar mask
5320 to listen on the given socket or
5322 for incoming command connections.
5328 to close any existing socket and clear the socket configuration.
5333 to attempt to re-open the port.
5338 to close the open port.
5340 If you wish to specify a local domain socket,
5342 must be specified as an absolute file name, otherwise it is assumed
5343 to be the name or number of a TCP port.
5344 You may specify the octal umask to be used with a local domain socket.
5350 for details of how to translate TCP port names.
5352 You must also specify the password that must be entered by the client
5355 variable above) when connecting to this socket.
5357 specified as an empty string, no password is required for connecting clients.
5359 When specifying a local domain socket, the first
5361 sequence found in the socket name will be replaced with the current
5362 interface unit number.
5363 This is useful when you wish to use the same
5364 profile for more than one connection.
5366 In a similar manner TCP sockets may be prefixed with the
5368 character, in which case the current interface unit number is added to
5373 with a server socket, the
5375 command is the preferred mechanism of communications.
5378 can also be used, but link encryption may be implemented in the future, so
5386 interact with the diagnostic socket.
5387 .It set speed Ar value
5388 This sets the speed of the serial device.
5389 If speed is specified as
5392 treats the device as a synchronous device.
5394 Certain device types will know whether they should be specified as
5395 synchronous or asynchronous.
5396 These devices will override incorrect
5397 settings and log a warning to this effect.
5398 .It set stopped Op Ar LCPseconds Op Ar CCPseconds
5399 If this option is set,
5401 will time out after the given FSM (Finite State Machine) has been in
5402 the stopped state for the given number of
5404 This option may be useful if the peer sends a terminate request,
5405 but never actually closes the connection despite our sending a terminate
5407 This is also useful if you wish to
5408 .Dq set openmode passive
5409 and time out if the peer doesn't send a Configure Request within the
5412 .Dq set log +lcp +ccp
5415 log the appropriate state transitions.
5417 The default value is zero, where
5419 doesn't time out in the stopped state.
5421 This value should not be set to less than the openmode delay (see
5424 .It set timeout Ar idleseconds Op Ar mintimeout
5425 This command allows the setting of the idle timer.
5426 Refer to the section titled
5427 .Sx SETTING THE IDLE TIMER
5428 for further details.
5434 will never idle out before the link has been up for at least that number
5442 This command controls the ports that
5444 prioritizes when transmitting data.
5445 The default priority TCP ports
5446 are ports 21 (ftp control), 22 (ssh), 23 (telnet), 513 (login), 514 (shell),
5447 543 (klogin) and 544 (kshell).
5448 There are no priority UDP ports by default.
5463 are given, the priority port lists are cleared (although if
5467 is specified, only that list is cleared).
5470 argument is prefixed with a plus
5474 the current list is adjusted, otherwise the list is reassigned.
5476 prefixed with a plus or not prefixed at all are added to the list and
5478 prefixed with a minus are removed from the list.
5482 is specified, all priority port lists are disabled and even
5484 packets are not prioritised.
5485 .It set vj slotcomp on|off
5488 whether it should attempt to negotiate VJ slot compression.
5489 By default, slot compression is turned
5491 .It set vj slots Ar nslots
5492 This command sets the initial number of slots that
5494 will try to negotiate with the peer when VJ compression is enabled (see the
5497 It defaults to a value of 16.
5506 .It shell|! Op Ar command
5509 is not specified a shell is invoked according to the
5511 environment variable.
5512 Otherwise, the given
5515 Word replacement is done in the same way as for the
5517 command as described above.
5519 Use of the ! character
5520 requires a following space as with any of the other commands.
5521 You should note that this command is executed in the foreground;
5523 will not continue running until this process has exited.
5526 command if you wish processing to happen in the background.
5528 This command allows the user to examine the following:
5531 Show the current bundle settings.
5533 Show the current CCP compression statistics.
5535 Show the current VJ compression statistics.
5537 Show the current escape characters.
5538 .It show filter Op Ar name
5539 List the current rules for the given filter.
5542 is not specified, all filters are shown.
5544 Show the current HDLC statistics.
5546 Give a summary of available show commands.
5548 Show the current interface information
5552 Show the current IPCP statistics.
5554 Show the protocol layers currently in use.
5556 Show the current LCP statistics.
5557 .It show Op data Ns Xo
5560 Show high level link information.
5562 Show a list of available logical links.
5564 Show the current log values.
5566 Show current memory statistics.
5568 Show low level link information.
5570 Show Multi-link information.
5572 Show current protocol totals.
5574 Show the current routing tables.
5576 Show the current stopped timeouts.
5578 Show the active alarm timers.
5580 Show the current version number of
5585 Go into terminal mode.
5586 Characters typed at the keyboard are sent to the device.
5587 Characters read from the device are displayed on the screen.
5592 automatically enables Packet Mode and goes back into command mode.
5597 Read the example configuration files.
5598 They are a good source of information.
5607 to get online information about what's available.
5609 The following URLs contain useful information:
5610 .Bl -bullet -compact
5612 http://www.FreeBSD.org/FAQ/userppp.html
5614 http://www.FreeBSD.org/handbook/userppp.html
5620 refers to four files:
5626 These files are placed in the
5630 .It Pa /etc/ppp/ppp.conf
5631 System default configuration file.
5632 .It Pa /etc/ppp/ppp.secret
5633 An authorisation file for each system.
5634 .It Pa /etc/ppp/ppp.linkup
5635 A file to check when
5637 establishes a network level connection.
5638 .It Pa /etc/ppp/ppp.linkdown
5639 A file to check when
5641 closes a network level connection.
5642 .It Pa /var/log/ppp.log
5643 Logging and debugging information file.
5644 Note, this name is specified in
5645 .Pa /etc/syslogd.conf .
5648 for further details.
5649 .It Pa /var/spool/lock/LCK..*
5650 tty port locking file.
5653 for further details.
5654 .It Pa /var/run/tunN.pid
5655 The process id (pid) of the
5657 program connected to the tunN device, where
5659 is the number of the device.
5660 .It Pa /var/run/ttyXX.if
5661 The tun interface used by this port.
5662 Again, this file is only created in
5668 .It Pa /etc/services
5669 Get port number if port number is using service name.
5670 .It Pa /var/run/ppp-authname-class-value
5671 In multi-link mode, local domain sockets are created using the peer
5674 the peer endpoint discriminator class
5676 and the peer endpoint discriminator value
5678 As the endpoint discriminator value may be a binary value, it is turned
5679 to HEX to determine the actual file name.
5681 This socket is used to pass links between different instances of
5722 This program was originally written by
5723 .An Toshiharu OHNO Aq tony-o@iij.ad.jp ,
5724 and was submitted to
5727 .An Atsushi Murai Aq amurai@spec.co.jp .
5729 It was substantially modified during 1997 by
5730 .An Brian Somers Aq brian@Awfulhak.org ,
5733 in November that year
5734 (just after the 2.2 release).
5736 Most of the code was rewritten by
5738 in early 1998 when multi-link ppp support was added.
projects / FreeBSD / FreeBSD.git / blob