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
182 .Pq as specified in Pa /etc/ppp/ppp.conf
183 may also be specified on the command line.
188 .Pa /etc/ppp/ppp.conf
189 at startup, followed by each of the systems specified on the command line.
192 .It Provides an interactive user interface.
193 Using its command mode, the user can
194 easily enter commands to establish the connection with the remote end, check
195 the status of connection and close the connection.
196 All functions can also be optionally password protected for security.
197 .It Supports both manual and automatic dialing.
198 Interactive mode has a
200 command which enables you to talk to the device directly.
201 When you are connected to the remote peer and it starts to talk
204 detects it and switches to packet mode automatically.
206 determined the proper sequence for connecting with the remote host, you
207 can write a chat script to define the necessary dialing and login
208 procedure for later convenience.
209 .It Supports on-demand dialup capability.
214 will act as a daemon and wait for a packet to be sent over the
217 When this happens, the daemon automatically dials and establishes the
219 In almost the same manner
221 mode (direct-dial mode) also automatically dials and establishes the
223 However, it differs in that it will dial the remote site
224 any time it detects the link is down, even if there are no packets to be
226 This mode is useful for full-time connections where we worry less
227 about line charges and more about being connected full time.
230 mode is also available.
231 This mode is targeted at a dedicated link between two machines.
233 will never voluntarily quit from dedicated mode - you must send it the
235 command via its diagnostic socket.
238 will force an LCP renegotiation, and a
240 will force it to exit.
241 .It Supports client callback.
243 can use either the standard LCP callback protocol or the Microsoft
244 CallBack Control Protocol (ftp://ftp.microsoft.com/developr/rfc/cbcp.txt).
245 .It Supports NAT or packet aliasing.
246 Packet aliasing (a.k.a. IP masquerading) allows computers on a
247 private, unregistered network to access the Internet.
250 host acts as a masquerading gateway.
251 IP addresses as well as TCP and
252 UDP port numbers are NAT'd for outgoing packets and de-NAT'd for
254 .It Supports background PPP connections.
255 In background mode, if
257 successfully establishes the connection, it will become a daemon.
258 Otherwise, it will exit with an error.
259 This allows the setup of
260 scripts that wish to execute certain commands only if the connection
261 is successfully established.
262 .It Supports server-side PPP connections.
265 acts as server which accepts incoming
267 connections on stdin/stdout.
268 .It "Supports PAP and CHAP (rfc 1994, 2433 and 2759) authentication.
269 With PAP or CHAP, it is possible to skip the Unix style
271 procedure, and use the
273 protocol for authentication instead.
274 If the peer requests Microsoft CHAP authentication and
276 is compiled with DES support, an appropriate MD4/DES response will be
278 .It Supports RADIUS (rfc 2138) authentication.
279 An extension to PAP and CHAP,
286 allows authentication information to be stored in a central or
287 distributed database along with various per-user framed connection
291 is available at compile time,
295 requests when configured to do so.
296 .It Supports Proxy Arp.
298 can be configured to make one or more proxy arp entries on behalf of
300 This allows routing from the peer to the LAN without
301 configuring each machine on that LAN.
302 .It Supports packet filtering.
303 User can define four kinds of filters: the
305 filter for incoming packets, the
307 filter for outgoing packets, the
309 filter to define a dialing trigger packet and the
311 filter for keeping a connection alive with the trigger packet.
312 .It Tunnel driver supports bpf.
315 to check the packet flow over the
318 .It Supports PPP over TCP and PPP over UDP.
319 If a device name is specified as
320 .Em host Ns No : Ns Em port Ns
325 will open a TCP or UDP connection for transporting data rather than using a
326 conventional serial device.
327 UDP connections force
329 into synchronous mode.
330 .It Supports PPP over ISDN.
333 is given a raw B-channel i4b device to open as a link, it's able to talk
336 daemon to establish an ISDN connection.
337 .It Supports PPP over Ethernet (rfc 2516).
340 is given a device specification of the format
341 .No PPPoE: Ns Ar iface Ns Xo
342 .Op \&: Ns Ar provider Ns
356 On systems that do not support
358 an external program such as
361 .It "Supports IETF draft Predictor-1 (rfc 1978) and DEFLATE (rfc 1979) compression."
363 supports not only VJ-compression but also Predictor-1 and DEFLATE compression.
364 Normally, a modem has built-in compression (e.g., v42.bis) and the system
365 may receive higher data rates from it as a result of such compression.
366 While this is generally a good thing in most other situations, this
367 higher speed data imposes a penalty on the system by increasing the
368 number of serial interrupts the system has to process in talking to the
369 modem and also increases latency.
370 Unlike VJ-compression, Predictor-1 and DEFLATE compression pre-compresses
372 network traffic flowing through the link, thus reducing overheads to a
374 .It Supports Microsoft's IPCP extensions (rfc 1877).
375 Name Server Addresses and NetBIOS Name Server Addresses can be negotiated
376 with clients using the Microsoft
378 stack (i.e., Win95, WinNT)
379 .It Supports Multi-link PPP (rfc 1990)
380 It is possible to configure
382 to open more than one physical connection to the peer, combining the
383 bandwidth of all links for better throughput.
384 .It Supports MPPE (draft-ietf-pppext-mppe)
385 MPPE is Microsoft Point to Point Encryption scheme.
386 It is possible to configure
388 to participate in Microsoft's Windows VPN.
391 can only get encryption keys from CHAP 81 authentication.
393 must be compiled with DES for MPPE to operate.
405 will not run if the invoking user id is not zero.
406 This may be overridden by using the
409 .Pa /etc/ppp/ppp.conf .
410 When running as a normal user,
412 switches to user id 0 in order to alter the system routing table, set up
413 system lock files and read the ppp configuration files.
414 All external commands (executed via the "shell" or "!bg" commands) are executed
415 as the user id that invoked
419 logging facility if you're interested in what exactly is done as user id
424 you may need to deal with some initial configuration details.
427 Your kernel must include a tunnel device (the GENERIC kernel includes
429 If it doesn't, or if you require more than one tun
430 interface, you'll need to rebuild your kernel with the following line in
431 your kernel configuration file:
433 .Dl pseudo-device tun N
437 is the maximum number of
439 connections you wish to support.
443 directory for the tunnel device entries
447 represents the number of the tun device, starting at zero.
448 If they don't exist, you can create them by running "sh ./MAKEDEV tunN".
449 This will create tun devices 0 through
452 Make sure that your system has a group named
456 file and that the group contains the names of all users expected to use
460 manual page for details.
461 Each of these users must also be given access using the
464 .Pa /etc/ppp/ppp.conf .
471 A common log file name is
472 .Pa /var/log/ppp.log .
473 To make output go to this file, put the following lines in the
476 .Bd -literal -offset indent
478 *.*<TAB>/var/log/ppp.log
481 It is possible to have more than one
483 log file by creating a link to the
491 .Bd -literal -offset indent
493 *.*<TAB>/var/log/ppp0.log
497 .Pa /etc/syslog.conf .
498 Don't forget to send a
503 .Pa /etc/syslog.conf .
505 Although not strictly relevant to
507 operation, you should configure your resolver so that it works correctly.
508 This can be done by configuring a local DNS
510 or by adding the correct
513 .Pa /etc/resolv.conf .
516 manual page for details.
518 Alternatively, if the peer supports it,
520 can be configured to ask the peer for the nameserver address(es) and to
528 commands below for details.
531 In the following examples, we assume that your machine name is
537 above) with no arguments, you are presented with a prompt:
538 .Bd -literal -offset indent
544 part of your prompt should always be in upper case.
545 If it is in lower case, it means that you must supply a password using the
548 This only ever happens if you connect to a running version of
550 and have not authenticated yourself using the correct password.
552 You can start by specifying the device name and speed:
553 .Bd -literal -offset indent
554 ppp ON awfulhak> set device /dev/cuaa0
555 ppp ON awfulhak> set speed 38400
558 Normally, hardware flow control (CTS/RTS) is used.
560 certain circumstances (as may happen when you are connected directly
561 to certain PPP-capable terminal servers), this may result in
563 hanging as soon as it tries to write data to your communications link
564 as it is waiting for the CTS (clear to send) signal - which will never
566 Thus, if you have a direct line and can't seem to make a
567 connection, try turning CTS/RTS off with
569 If you need to do this, check the
571 description below too - you'll probably need to
572 .Dq set accmap 000a0000 .
574 Usually, parity is set to
579 Parity is a rather archaic error checking mechanism that is no
580 longer used because modern modems do their own error checking, and most
581 link-layer protocols (that's what
583 is) use much more reliable checking mechanisms.
584 Parity has a relatively
585 huge overhead (a 12.5% increase in traffic) and as a result, it is always
591 However, some ISPs (Internet Service Providers) may use
592 specific parity settings at connection time (before
595 Notably, Compuserve insist on even parity when logging in:
596 .Bd -literal -offset indent
597 ppp ON awfulhak> set parity even
600 You can now see what your current device settings look like:
601 .Bd -literal -offset indent
602 ppp ON awfulhak> show physical
606 Link Type: interactive
612 Device List: /dev/cuaa0
613 Characteristics: 38400bps, cs8, even parity, CTS/RTS on
616 0 octets in, 0 octets out
621 The term command can now be used to talk directly to the device:
622 .Bd -literal -offset indent
623 ppp ON awfulhak> term
629 Password: myisppassword
633 When the peer starts to talk in
636 detects this automatically and returns to command mode.
637 .Bd -literal -offset indent
638 ppp ON awfulhak> # No link has been established
639 Ppp ON awfulhak> # We've connected & finished LCP
640 PPp ON awfulhak> # We've authenticated
641 PPP ON awfulhak> # We've agreed IP numbers
644 If it does not, it's probable that the peer is waiting for your end to
650 configuration packets to the peer, use the
652 command to drop out of terminal mode and enter packet mode.
654 If you never even receive a login prompt, it is quite likely that the
655 peer wants to use PAP or CHAP authentication instead of using Unix-style
656 login/password authentication.
657 To set things up properly, drop back to
658 the prompt and set your authentication name and key, then reconnect:
659 .Bd -literal -offset indent
661 ppp ON awfulhak> set authname myispusername
662 ppp ON awfulhak> set authkey myisppassword
663 ppp ON awfulhak> term
670 You may need to tell ppp to initiate negotiations with the peer here too:
671 .Bd -literal -offset indent
673 ppp ON awfulhak> # No link has been established
674 Ppp ON awfulhak> # We've connected & finished LCP
675 PPp ON awfulhak> # We've authenticated
676 PPP ON awfulhak> # We've agreed IP numbers
679 You are now connected!
682 in the prompt has changed to capital letters to indicate that you have
684 If only some of the three Ps go uppercase, wait until
685 either everything is uppercase or lowercase.
686 If they revert to lowercase, it means that
688 couldn't successfully negotiate with the peer.
689 A good first step for troubleshooting at this point would be to
690 .Bd -literal -offset indent
691 ppp ON awfulhak> set log local phase lcp ipcp
697 command description below for further details.
698 If things fail at this point,
699 it is quite important that you turn logging on and try again.
701 important that you note any prompt changes and report them to anyone trying
704 When the link is established, the show command can be used to see how
706 .Bd -literal -offset indent
707 PPP ON awfulhak> show physical
708 * Modem related information is shown here *
709 PPP ON awfulhak> show ccp
710 * CCP (compression) related information is shown here *
711 PPP ON awfulhak> show lcp
712 * LCP (line control) related information is shown here *
713 PPP ON awfulhak> show ipcp
714 * IPCP (IP) related information is shown here *
715 PPP ON awfulhak> show link
716 * Link (high level) related information is shown here *
717 PPP ON awfulhak> show bundle
718 * Logical (high level) connection related information is shown here *
721 At this point, your machine has a host route to the peer.
723 that you can only make a connection with the host on the other side
725 If you want to add a default route entry (telling your
726 machine to send all packets without another routing entry to the other
729 link), enter the following command:
730 .Bd -literal -offset indent
731 PPP ON awfulhak> add default HISADDR
736 represents the IP address of the connected peer.
739 command fails due to an existing route, you can overwrite the existing
741 .Bd -literal -offset indent
742 PPP ON awfulhak> add! default HISADDR
745 This command can also be executed before actually making the connection.
746 If a new IP address is negotiated at connection time,
748 will update your default route accordingly.
750 You can now use your network applications (ping, telnet, ftp etc.)
751 in other windows or terminals on your machine.
752 If you wish to reuse the current terminal, you can put
754 into the background using your standard shell suspend and background
762 section for details on all available commands.
763 .Sh AUTOMATIC DIALING
764 To use automatic dialing, you must prepare some Dial and Login chat scripts.
765 See the example definitions in
766 .Pa /usr/share/examples/ppp/ppp.conf.sample
768 .Pa /etc/ppp/ppp.conf
770 Each line contains one comment, inclusion, label or command:
773 A line starting with a
775 character is treated as a comment line.
776 Leading whitespace are ignored when identifying comment lines.
778 An inclusion is a line beginning with the word
780 It must have one argument - the file to include.
782 .Dq !include ~/.ppp.conf
783 for compatibility with older versions of
786 A label name starts in the first column and is followed by
790 A command line must contain a space or tab in the first column.
794 .Pa /etc/ppp/ppp.conf
795 file should consist of at least a
798 This section is always executed.
799 It should also contain
800 one or more sections, named according to their purpose, for example,
802 would represent your ISP, and
804 would represent an incoming
807 You can now specify the destination label name when you invoke
809 Commands associated with the
811 label are executed, followed by those associated with the destination
815 is started with no arguments, the
817 section is still executed.
818 The load command can be used to manually load a section from the
819 .Pa /etc/ppp/ppp.conf
821 .Bd -literal -offset indent
822 ppp ON awfulhak> load MyISP
825 Note, no action is taken by
827 after a section is loaded, whether it's the result of passing a label on
828 the command line or using the
831 Only the commands specified for that label in the configuration
833 However, when invoking
840 switches, the link mode tells
842 to establish a connection.
845 command below for further details.
847 Once the connection is made, the
849 portion of the prompt will change to
851 .Bd -literal -offset indent
854 ppp ON awfulhak> dial
860 The Ppp prompt indicates that
862 has entered the authentication phase.
863 The PPp prompt indicates that
865 has entered the network phase.
866 The PPP prompt indicates that
868 has successfully negotiated a network layer protocol and is in
872 .Pa /etc/ppp/ppp.linkup
873 file is available, its contents are executed
876 connection is established.
880 .Pa /usr/share/examples/ppp/ppp.conf.sample
881 which runs a script in the background after the connection is established
886 commands below for a description of possible substitution strings).
887 Similarly, when a connection is closed, the contents of the
888 .Pa /etc/ppp/ppp.linkdown
890 Both of these files have the same format as
891 .Pa /etc/ppp/ppp.conf .
893 In previous versions of
895 it was necessary to re-add routes such as the default route in the
901 where all routes that contain the
905 literals will automatically be updated when the values of
910 .Sh BACKGROUND DIALING
911 If you want to establish a connection using
913 non-interactively (such as from a
917 job) you should use the
924 attempts to establish the connection immediately.
926 numbers are specified, each phone number will be tried once.
927 If the attempt fails,
929 exits immediately with a non-zero exit code.
932 becomes a daemon, and returns an exit status of zero to its caller.
933 The daemon exits automatically if the connection is dropped by the
934 remote system, or it receives a
938 Demand dialing is enabled with the
943 You must also specify the destination label in
944 .Pa /etc/ppp/ppp.conf
948 command to define the remote peers IP address.
950 .Pa /usr/share/examples/ppp/ppp.conf.sample )
951 .Bd -literal -offset indent
961 runs as a daemon but you can still configure or examine its
962 configuration by using the
965 .Pa /etc/ppp/ppp.conf ,
966 .Pq for example, Dq set server +3000 mypasswd
967 and connecting to the diagnostic port as follows:
968 .Bd -literal -offset indent
969 # pppctl 3000 (assuming tun0)
971 PPP ON awfulhak> show who
972 tcp (127.0.0.1:1028) *
977 command lists users that are currently connected to
980 If the diagnostic socket is closed or changed to a different
981 socket, all connections are immediately dropped.
985 mode, when an outgoing packet is detected,
987 will perform the dialing action (chat script) and try to connect
991 mode, the dialing action is performed any time the line is found
993 If the connect fails, the default behaviour is to wait 30 seconds
994 and then attempt to connect when another outgoing packet is detected.
995 This behaviour can be changed using the
999 .No set redial Ar secs Ns Xo
1002 .Oc Ns Op . Ns Ar next
1006 .Bl -tag -width attempts -compact
1008 is the number of seconds to wait before attempting
1010 If the argument is the literal string
1012 the delay period is a random value between 1 and 30 seconds inclusive.
1014 is the number of seconds that
1016 should be incremented each time a new dial attempt is made.
1017 The timeout reverts to
1019 only after a successful connection is established.
1020 The default value for
1024 is the maximum number of times
1028 The default value for
1032 is the number of seconds to wait before attempting
1033 to dial the next number in a list of numbers (see the
1036 The default is 3 seconds.
1037 Again, if the argument is the literal string
1039 the delay period is a random value between 1 and 30 seconds.
1041 is the maximum number of times to try to connect for each outgoing packet
1042 that triggers a dial.
1043 The previous value is unchanged if this parameter is omitted.
1044 If a value of zero is specified for
1047 will keep trying until a connection is made.
1051 .Bd -literal -offset indent
1055 will attempt to connect 4 times for each outgoing packet that causes
1056 a dial attempt with a 3 second delay between each number and a 10 second
1057 delay after all numbers have been tried.
1058 If multiple phone numbers
1059 are specified, the total number of attempts is still 4 (it does not
1060 attempt each number 4 times).
1064 .Bd -literal -offset indent
1065 set redial 10+10-5.3 20
1070 to attempt to connect 20 times.
1071 After the first attempt,
1073 pauses for 10 seconds.
1074 After the next attempt it pauses for 20 seconds
1075 and so on until after the sixth attempt it pauses for 1 minute.
1076 The next 14 pauses will also have a duration of one minute.
1079 connects, disconnects and fails to connect again, the timeout starts again
1082 Modifying the dial delay is very useful when running
1086 mode on both ends of the link.
1087 If each end has the same timeout,
1088 both ends wind up calling each other at the same time if the link
1089 drops and both ends have packets queued.
1090 At some locations, the serial link may not be reliable, and carrier
1091 may be lost at inappropriate times.
1092 It is possible to have
1094 redial should carrier be unexpectedly lost during a session.
1095 .Bd -literal -offset indent
1096 set reconnect timeout ntries
1101 to re-establish the connection
1103 times on loss of carrier with a pause of
1105 seconds before each try.
1107 .Bd -literal -offset indent
1113 that on an unexpected loss of carrier, it should wait
1115 seconds before attempting to reconnect.
1116 This may happen up to
1121 The default value of ntries is zero (no reconnect).
1122 Care should be taken with this option.
1123 If the local timeout is slightly
1124 longer than the remote timeout, the reconnect feature will always be
1125 triggered (up to the given number of times) after the remote side
1126 times out and hangs up.
1127 NOTE: In this context, losing too many LQRs constitutes a loss of
1128 carrier and will trigger a reconnect.
1131 flag is specified, all phone numbers are dialed at most once until
1132 a connection is made.
1133 The next number redial period specified with the
1135 command is honoured, as is the reconnect tries value.
1137 value is less than the number of phone numbers specified, not all
1138 the specified numbers will be tried.
1139 To terminate the program, type
1140 .Bd -literal -offset indent
1141 PPP ON awfulhak> close
1142 ppp ON awfulhak> quit all
1147 command will terminate the
1151 connection but not the
1159 .Sh RECEIVING INCOMING PPP CONNECTIONS (Method 1)
1160 To handle an incoming
1162 connection request, follow these steps:
1165 Make sure the modem and (optionally)
1167 is configured correctly.
1168 .Bl -bullet -compact
1170 Use Hardware Handshake (CTS/RTS) for flow control.
1172 Modem should be set to NO echo back (ATE0) and NO results string (ATQ1).
1180 on the port where the modem is attached.
1183 .Dl ttyd1 Qo /usr/libexec/getty std.38400 Qc dialup on secure
1185 Don't forget to send a
1189 process to start the
1194 It is usually also necessary to train your modem to the same DTR speed
1196 .Bd -literal -offset indent
1198 ppp ON awfulhak> set device /dev/cuaa1
1199 ppp ON awfulhak> set speed 38400
1200 ppp ON awfulhak> term
1201 deflink: Entering terminal mode on /dev/cuaa1
1212 ppp ON awfulhak> quit
1216 .Pa /usr/local/bin/ppplogin
1217 file with the following contents:
1218 .Bd -literal -offset indent
1220 exec /usr/sbin/ppp -direct incoming
1227 work with stdin and stdout.
1230 to connect to a configured diagnostic port, in the same manner as with
1236 section must be set up in
1237 .Pa /etc/ppp/ppp.conf .
1241 section contains the
1243 command as appropriate.
1245 Prepare an account for the incoming user.
1247 ppp:xxxx:66:66:PPP Login User:/home/ppp:/usr/local/bin/ppplogin
1250 Refer to the manual entries for
1256 Support for IPCP Domain Name Server and NetBIOS Name Server negotiation
1257 can be enabled using the
1262 Refer to their descriptions below.
1264 .Sh RECEIVING INCOMING PPP CONNECTIONS (Method 2)
1265 This method differs in that we use
1267 to authenticate the connection rather than
1271 Configure your default section in
1273 with automatic ppp recognition by specifying the
1278 :pp=/usr/local/bin/ppplogin:\\
1282 Configure your serial device(s), enable a
1285 .Pa /usr/local/bin/ppplogin
1286 as in the first three steps for method 1 above.
1294 .Pa /etc/ppp/ppp.conf
1297 label (or whatever label
1302 .Pa /etc/ppp/ppp.secret
1303 for each incoming user:
1312 detects a ppp connection (by recognising the HDLC frame headers), it runs
1313 .Dq /usr/local/bin/ppplogin .
1317 that either PAP or CHAP are enabled as above.
1318 If they are not, you are
1319 allowing anybody to establish ppp session with your machine
1321 a password, opening yourself up to all sorts of potential attacks.
1322 .Sh AUTHENTICATING INCOMING CONNECTIONS
1323 Normally, the receiver of a connection requires that the peer
1324 authenticates itself.
1325 This may be done using
1327 but alternatively, you can use PAP or CHAP.
1328 CHAP is the more secure of the two, but some clients may not support it.
1329 Once you decide which you wish to use, add the command
1333 to the relevant section of
1336 You must then configure the
1337 .Pa /etc/ppp/ppp.secret
1339 This file contains one line per possible client, each line
1340 containing up to five fields:
1343 .Ar hisaddr Op Ar label Op Ar callback-number
1350 specify the client username and password.
1355 and PAP is being used,
1357 will look up the password database
1359 when authenticating.
1360 If the client does not offer a suitable response based on any
1361 .Ar name Ns No / Ns Ar key
1364 authentication fails.
1366 If authentication is successful,
1369 is used when negotiating IP numbers.
1372 command for details.
1374 If authentication is successful and
1376 is specified, the current system label is changed to match the given
1378 This will change the subsequent parsing of the
1384 If authentication is successful and
1390 the client will be called back on the given number.
1391 If CBCP is being used,
1393 may also contain a list of numbers or a
1398 The value will be used in
1400 subsequent CBCP phase.
1401 .Sh PPP OVER TCP and UDP (a.k.a Tunnelling)
1404 over a serial link, it is possible to
1405 use a TCP connection instead by specifying the host, port and protocol as the
1408 .Dl set device ui-gate:6669/tcp
1410 Instead of opening a serial device,
1412 will open a TCP connection to the given machine on the given
1414 It should be noted however that
1416 doesn't use the telnet protocol and will be unable to negotiate
1417 with a telnet server.
1418 You should set up a port for receiving this
1420 connection on the receiving machine (ui-gate).
1421 This is done by first updating
1423 to name the service:
1425 .Dl ppp-in 6669/tcp # Incoming PPP connections over TCP
1431 how to deal with incoming connections on that port:
1433 .Dl ppp-in stream tcp nowait root /usr/sbin/ppp ppp -direct ppp-in
1435 Don't forget to send a
1439 after you've updated
1440 .Pa /etc/inetd.conf .
1441 Here, we use a label named
1444 .Pa /etc/ppp/ppp.conf
1445 on ui-gate (the receiver) should contain the following:
1446 .Bd -literal -offset indent
1449 set ifaddr 10.0.4.1 10.0.4.2
1453 .Pa /etc/ppp/ppp.linkup
1455 .Bd -literal -offset indent
1457 add 10.0.1.0/24 HISADDR
1460 It is necessary to put the
1464 to ensure that the route is only added after
1466 has negotiated and assigned addresses to its interface.
1468 You may also want to enable PAP or CHAP for security.
1469 To enable PAP, add the following line:
1470 .Bd -literal -offset indent
1474 You'll also need to create the following entry in
1475 .Pa /etc/ppp/ppp.secret :
1476 .Bd -literal -offset indent
1477 MyAuthName MyAuthPasswd
1484 the password is looked up in the
1489 .Pa /etc/ppp/ppp.conf
1490 on awfulhak (the initiator) should contain the following:
1491 .Bd -literal -offset indent
1494 set device ui-gate:ppp-in/tcp
1497 set log Phase Chat Connect hdlc LCP IPCP CCP tun
1498 set ifaddr 10.0.4.2 10.0.4.1
1501 with the route setup in
1502 .Pa /etc/ppp/ppp.linkup :
1503 .Bd -literal -offset indent
1505 add 10.0.2.0/24 HISADDR
1508 Again, if you're enabling PAP, you'll also need this in the
1509 .Pa /etc/ppp/ppp.conf
1511 .Bd -literal -offset indent
1512 set authname MyAuthName
1513 set authkey MyAuthKey
1516 We're assigning the address of 10.0.4.1 to ui-gate, and the address
1517 10.0.4.2 to awfulhak.
1518 To open the connection, just type
1520 .Dl awfulhak # ppp -background ui-gate
1522 The result will be an additional "route" on awfulhak to the
1523 10.0.2.0/24 network via the TCP connection, and an additional
1524 "route" on ui-gate to the 10.0.1.0/24 network.
1525 The networks are effectively bridged - the underlying TCP
1526 connection may be across a public network (such as the
1529 traffic is conceptually encapsulated
1530 (although not packet by packet) inside the TCP stream between
1533 The major disadvantage of this mechanism is that there are two
1534 "guaranteed delivery" mechanisms in place - the underlying TCP
1535 stream and whatever protocol is used over the
1537 link - probably TCP again.
1538 If packets are lost, both levels will
1539 get in each others way trying to negotiate sending of the missing
1542 To avoid this overhead, it is also possible to do all this using
1543 UDP instead of TCP as the transport by simply changing the protocol
1544 from "tcp" to "udp".
1545 When using UDP as a transport,
1547 will operate in synchronous mode.
1548 This is another gain as the incoming
1549 data does not have to be rearranged into packets.
1551 Care should be taken when adding a default route through a tunneled
1553 It is quite common for the default route
1554 .Pq added in Pa /etc/ppp/ppp.linkup
1555 to end up routing the link's TCP connection through the tunnel,
1556 effectively garrotting the connection.
1557 To avoid this, make sure you add a static route for the benefit of
1559 .Bd -literal -offset indent
1562 set device ui-gate:ppp-in/tcp
1569 is the IP number that your route to
1573 When routing your connection accross a public network such as the Internet,
1574 it is preferable to encrypt the data.
1575 This can be done with the help of the MPPE protocol, although currently this
1576 means that you will not be able to also compress the traffic as MPPE is
1577 implemented as a compression layer (thank Microsoft for this).
1578 To enable MPPE encryption, add the following lines to
1579 .Pa /etc/ppp/ppp.conf
1581 .Bd -literal -offset indent
1583 disable deflate pred1
1587 ensuring that you've put the requisite entry in
1588 .Pa /etc/ppp/ppp.secret
1589 (MSCHAPv2 is challenge based, so
1593 MSCHAPv2 and MPPE are accepted by default, so the client end should work
1594 without any additional changes (although ensure you have
1599 .Sh NETWORK ADDRESS TRANSLATION (PACKET ALIASING)
1602 command line option enables network address translation (a.k.a. packet
1606 host to act as a masquerading gateway for other computers over
1607 a local area network.
1608 Outgoing IP packets are NAT'd so that they appear to come from the
1610 host, and incoming packets are de-NAT'd so that they are routed
1611 to the correct machine on the local area network.
1612 NAT allows computers on private, unregistered subnets to have Internet
1613 access, although they are invisible from the outside world.
1616 operation should first be verified with network address translation disabled.
1619 option should be switched on, and network applications (web browser,
1624 should be checked on the
1627 Finally, the same or similar applications should be checked on other
1628 computers in the LAN.
1629 If network applications work correctly on the
1631 host, but not on other machines in the LAN, then the masquerading
1632 software is working properly, but the host is either not forwarding
1633 or possibly receiving IP packets.
1634 Check that IP forwarding is enabled in
1636 and that other machines have designated the
1638 host as the gateway for the LAN.
1639 .Sh PACKET FILTERING
1640 This implementation supports packet filtering.
1641 There are four kinds of
1651 Here are the basics:
1654 A filter definition has the following syntax:
1663 .Ar src_addr Ns Op / Ns Ar width
1664 .Op Ar dst_addr Ns Op / Ns Ar width
1666 .Ar [ proto Op src Ar cmp port
1671 .Op timeout Ar secs ]
1683 is a numeric value between
1687 specifying the rule number.
1688 Rules are specified in numeric order according to
1699 in which case, if a given packet matches the rule, the associated action
1700 is taken immediately.
1702 can also be specified as
1704 to clear the action associated with that particular rule, or as a new
1705 rule number greater than the current rule.
1706 In this case, if a given
1707 packet matches the current rule, the packet will next be matched against
1708 the new rule number (rather than the next rule number).
1712 may optionally be followed with an exclamation mark
1716 to reverse the sense of the following match.
1718 .Op Ar src_addr Ns Op / Ns Ar width
1720 .Op Ar dst_addr Ns Op / Ns Ar width
1721 are the source and destination IP number specifications.
1724 is specified, it gives the number of relevant netmask bits,
1725 allowing the specification of an address range.
1731 may be given the values
1735 (refer to the description of the
1737 command for a description of these values).
1738 When these values are used,
1739 the filters will be updated any time the values change.
1740 This is similar to the behaviour of the
1760 meaning less-than, equal and greater-than respectively.
1762 can be specified as a numeric port or by service name from
1770 flags are only allowed when
1774 and represent the TH_ACK, TH_SYN and TH_FIN or TH_RST TCP flags respectively.
1776 The timeout value adjusts the current idle timeout to at least
1779 If a timeout is given in the alive filter as well as in the in/out
1780 filter, the in/out value is used.
1781 If no timeout is given, the default timeout (set using
1783 and defaulting to 180 seconds) is used.
1787 Each filter can hold up to 40 rules, starting from rule 0.
1788 The entire rule set is not effective until rule 0 is defined,
1789 i.e., the default is to allow everything through.
1791 If no rule in a defined set of rules matches a packet, that packet will
1792 be discarded (blocked).
1793 If there are no rules in a given filter, the packet will be permitted.
1795 It's possible to filter based on the payload of UDP frames where those
1801 .Ar filter-decapsulation
1802 option below for further details.
1805 .Dq set filter Ar name No -1
1810 .Pa /usr/share/examples/ppp/ppp.conf.sample .
1811 .Sh SETTING THE IDLE TIMER
1812 To check/set the idle timer, use the
1817 .Bd -literal -offset indent
1818 ppp ON awfulhak> set timeout 600
1821 The timeout period is measured in seconds, the default value for which
1824 To disable the idle timer function, use the command
1825 .Bd -literal -offset indent
1826 ppp ON awfulhak> set timeout 0
1833 modes, the idle timeout is ignored.
1836 mode, when the idle timeout causes the
1841 program itself remains running.
1842 Another trigger packet will cause it to attempt to re-establish the link.
1843 .Sh PREDICTOR-1 and DEFLATE COMPRESSION
1845 supports both Predictor type 1 and deflate compression.
1848 will attempt to use (or be willing to accept) both compression protocols
1849 when the peer agrees
1850 .Pq or requests them .
1851 The deflate protocol is preferred by
1857 commands if you wish to disable this functionality.
1859 It is possible to use a different compression algorithm in each direction
1860 by using only one of
1864 .Pq assuming that the peer supports both algorithms .
1866 By default, when negotiating DEFLATE,
1868 will use a window size of 15.
1871 command if you wish to change this behaviour.
1873 A special algorithm called DEFLATE24 is also available, and is disabled
1874 and denied by default.
1875 This is exactly the same as DEFLATE except that
1876 it uses CCP ID 24 to negotiate.
1879 to successfully negotiate DEFLATE with
1882 .Sh CONTROLLING IP ADDRESS
1884 uses IPCP to negotiate IP addresses.
1885 Each side of the connection
1886 specifies the IP address that it's willing to use, and if the requested
1887 IP address is acceptable then
1889 returns ACK to the requester.
1892 returns NAK to suggest that the peer use a different IP address.
1894 both sides of the connection agree to accept the received request (and
1895 send ACK), IPCP is set to the open state and a network level connection
1897 To control this IPCP behaviour, this implementation has the
1899 command for defining the local and remote IP address:
1900 .Bd -ragged -offset indent
1901 .No set ifaddr Oo Ar src_addr Ns
1903 .Oo Ar dst_addr Ns Op / Ns Ar \&nn
1913 is the IP address that the local side is willing to use,
1915 is the IP address which the remote side should use and
1917 is the netmask that should be used.
1919 defaults to the current
1922 defaults to 0.0.0.0, and
1924 defaults to whatever mask is appropriate for
1926 It is only possible to make
1928 smaller than the default.
1929 The usual value is 255.255.255.255, as
1930 most kernels ignore the netmask of a POINTOPOINT interface.
1934 implementations require that the peer negotiates a specific IP
1937 If this is the case,
1939 may be used to specify this IP number.
1940 This will not affect the
1941 routing table unless the other side agrees with this proposed number.
1942 .Bd -literal -offset indent
1943 set ifaddr 192.244.177.38 192.244.177.2 255.255.255.255 0.0.0.0
1946 The above specification means:
1948 .Bl -bullet -compact
1950 I will first suggest that my IP address should be 0.0.0.0, but I
1951 will only accept an address of 192.244.177.38.
1953 I strongly insist that the peer uses 192.244.177.2 as his own
1954 address and won't permit the use of any IP address but 192.244.177.2.
1955 When the peer requests another IP address, I will always suggest that
1956 it uses 192.244.177.2.
1958 The routing table entry will have a netmask of 0xffffffff.
1961 This is all fine when each side has a pre-determined IP address, however
1962 it is often the case that one side is acting as a server which controls
1963 all IP addresses and the other side should go along with it.
1964 In order to allow more flexible behaviour, the
1966 command allows the user to specify IP addresses more loosely:
1968 .Dl set ifaddr 192.244.177.38/24 192.244.177.2/20
1970 A number followed by a slash
1972 represents the number of bits significant in the IP address.
1973 The above example means:
1975 .Bl -bullet -compact
1977 I'd like to use 192.244.177.38 as my address if it is possible, but I'll
1978 also accept any IP address between 192.244.177.0 and 192.244.177.255.
1980 I'd like to make him use 192.244.177.2 as his own address, but I'll also
1981 permit him to use any IP address between 192.244.176.0 and
1984 As you may have already noticed, 192.244.177.2 is equivalent to saying
1987 As an exception, 0 is equivalent to 0.0.0.0/0, meaning that I have no
1988 preferred IP address and will obey the remote peers selection.
1989 When using zero, no routing table entries will be made until a connection
1992 192.244.177.2/0 means that I'll accept/permit any IP address but I'll
1993 try to insist that 192.244.177.2 be used first.
1995 .Sh CONNECTING WITH YOUR INTERNET SERVICE PROVIDER
1996 The following steps should be taken when connecting to your ISP:
1999 Describe your providers phone number(s) in the dial script using the
2002 This command allows you to set multiple phone numbers for
2003 dialing and redialing separated by either a pipe
2007 .Bd -ragged -offset indent
2008 .No set phone Ar telno Ns Xo
2009 .Oo \&| Ns Ar backupnumber
2010 .Oc Ns ... Ns Oo : Ns Ar nextnumber
2015 Numbers after the first in a pipe-separated list are only used if the
2016 previous number was used in a failed dial or login script.
2018 separated by a colon are used sequentially, irrespective of what happened
2019 as a result of using the previous number.
2021 .Bd -literal -offset indent
2022 set phone "1234567|2345678:3456789|4567890"
2025 Here, the 1234567 number is attempted.
2026 If the dial or login script fails,
2027 the 2345678 number is used next time, but *only* if the dial or login script
2029 On the dial after this, the 3456789 number is used.
2031 number is only used if the dial or login script using the 3456789 fails.
2032 If the login script of the 2345678 number fails, the next number is still the
2034 As many pipes and colons can be used as are necessary
2035 (although a given site would usually prefer to use either the pipe or the
2036 colon, but not both).
2037 The next number redial timeout is used between all numbers.
2038 When the end of the list is reached, the normal redial period is
2039 used before starting at the beginning again.
2040 The selected phone number is substituted for the \\\\T string in the
2042 command (see below).
2044 Set up your redial requirements using
2046 For example, if you have a bad telephone line or your provider is
2047 usually engaged (not so common these days), you may want to specify
2049 .Bd -literal -offset indent
2053 This says that up to 4 phone calls should be attempted with a pause of 10
2054 seconds before dialing the first number again.
2056 Describe your login procedure using the
2063 command is used to talk to your modem and establish a link with your
2065 .Bd -literal -offset indent
2066 set dial "ABORT BUSY ABORT NO\\\\sCARRIER TIMEOUT 4 \\"\\" \e
2067 ATZ OK-ATZ-OK ATDT\\\\T TIMEOUT 60 CONNECT"
2070 This modem "chat" string means:
2073 Abort if the string "BUSY" or "NO CARRIER" are received.
2075 Set the timeout to 4 seconds.
2082 If that's not received within the 4 second timeout, send ATZ
2085 Send ATDTxxxxxxx where xxxxxxx is the next number in the phone list from
2088 Set the timeout to 60.
2090 Wait for the CONNECT string.
2093 Once the connection is established, the login script is executed.
2094 This script is written in the same style as the dial script, but care should
2095 be taken to avoid having your password logged:
2096 .Bd -literal -offset indent
2097 set authkey MySecret
2098 set login "TIMEOUT 15 login:-\\\\r-login: awfulhak \e
2099 word: \\\\P ocol: PPP HELLO"
2102 This login "chat" string means:
2105 Set the timeout to 15 seconds.
2108 If it's not received, send a carriage return and expect
2113 Expect "word:" (the tail end of a "Password:" prompt).
2115 Send whatever our current
2119 Expect "ocol:" (the tail end of a "Protocol:" prompt).
2128 command is logged specially.
2133 logging is enabled, the actual password is not logged;
2137 Login scripts vary greatly between ISPs.
2138 If you're setting one up for the first time,
2139 .Em ENABLE CHAT LOGGING
2140 so that you can see if your script is behaving as you expect.
2146 to specify your serial line and speed, for example:
2147 .Bd -literal -offset indent
2148 set device /dev/cuaa0
2152 Cuaa0 is the first serial port on
2159 A speed of 115200 should be specified
2160 if you have a modem capable of bit rates of 28800 or more.
2161 In general, the serial speed should be about four times the modem speed.
2165 command to define the IP address.
2168 If you know what IP address your provider uses, then use it as the remote
2169 address (dst_addr), otherwise choose something like 10.0.0.2/0 (see below).
2171 If your provider has assigned a particular IP address to you, then use
2172 it as your address (src_addr).
2174 If your provider assigns your address dynamically, choose a suitably
2175 unobtrusive and unspecific IP number as your address.
2176 10.0.0.1/0 would be appropriate.
2177 The bit after the / specifies how many bits of the
2178 address you consider to be important, so if you wanted to insist on
2179 something in the class C network 1.2.3.0, you could specify 1.2.3.1/24.
2181 If you find that your ISP accepts the first IP number that you suggest,
2182 specify third and forth arguments of
2184 This will force your ISP to assign a number.
2185 (The third argument will
2186 be ignored as it is less restrictive than the default mask for your
2190 An example for a connection where you don't know your IP number or your
2191 ISPs IP number would be:
2192 .Bd -literal -offset indent
2193 set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0
2197 In most cases, your ISP will also be your default router.
2198 If this is the case, add the line
2199 .Bd -literal -offset indent
2204 .Pa /etc/ppp/ppp.conf .
2208 to add a default route to whatever the peer address is
2209 .Pq 10.0.0.2 in this example .
2212 meaning that should the value of
2214 change, the route will be updated accordingly.
2216 Previous versions of
2218 required a similar entry in the
2219 .Pa /etc/ppp/ppp.linkup
2223 this is no longer required.
2225 If your provider requests that you use PAP/CHAP authentication methods, add
2226 the next lines to your
2227 .Pa /etc/ppp/ppp.conf
2229 .Bd -literal -offset indent
2231 set authkey MyPassword
2234 Both are accepted by default, so
2236 will provide whatever your ISP requires.
2238 It should be noted that a login script is rarely (if ever) required
2239 when PAP or CHAP are in use.
2241 Ask your ISP to authenticate your nameserver address(es) with the line
2242 .Bd -literal -offset indent
2248 do this if you are running a local DNS unless you also either use
2253 .Pa /etc/ppp/ppp.linkdown ,
2256 will simply circumvent its use by entering some nameserver lines in
2257 .Pa /etc/resolv.conf .
2261 .Pa /usr/share/examples/ppp/ppp.conf.sample
2263 .Pa /usr/share/examples/ppp/ppp.linkup.sample
2264 for some real examples.
2265 The pmdemand label should be appropriate for most ISPs.
2266 .Sh LOGGING FACILITY
2268 is able to generate the following log info either via
2270 or directly to the screen:
2272 .Bl -tag -width XXXXXXXXX -offset XXX -compact
2274 Enable all logging facilities.
2275 This generates a lot of log.
2276 The most common use of 'all' is as a basis, where you remove some facilities
2277 after enabling 'all' ('debug' and 'timer' are usually best disabled.)
2279 Dump async level packet in hex.
2281 Generate CBCP (CallBack Control Protocol) logs.
2283 Generate a CCP packet trace.
2291 chat script trace logs.
2293 Log commands executed either from the command line or any of the configuration
2296 Log Chat lines containing the string "CONNECT".
2298 Log debug information.
2300 Log DNS QUERY packets.
2302 Log packets permitted by the dial filter and denied by any filter.
2304 Dump HDLC packet in hex.
2306 Log all function calls specifically made as user id 0.
2308 Generate an IPCP packet trace.
2310 Generate an LCP packet trace.
2312 Generate LQR reports.
2314 Phase transition log output.
2316 Dump physical level packet in hex.
2318 Dump sync level packet in hex.
2320 Dump all TCP/IP packets.
2322 Log timer manipulation.
2324 Include the tun device on each log line.
2326 Output to the terminal device.
2327 If there is currently no terminal,
2328 output is sent to the log file using syslogs
2331 Output to both the terminal device
2332 and the log file using syslogs
2335 Output to the log file using
2341 command allows you to set the logging output level.
2342 Multiple levels can be specified on a single command line.
2343 The default is equivalent to
2346 It is also possible to log directly to the screen.
2347 The syntax is the same except that the word
2349 should immediately follow
2353 (i.e., only the un-maskable warning, error and alert output).
2355 If The first argument to
2356 .Dq set log Op local
2361 character, the current log levels are
2362 not cleared, for example:
2363 .Bd -literal -offset indent
2364 PPP ON awfulhak> set log phase
2365 PPP ON awfulhak> show log
2366 Log: Phase Warning Error Alert
2367 Local: Warning Error Alert
2368 PPP ON awfulhak> set log +tcp/ip -warning
2369 PPP ON awfulhak> set log local +command
2370 PPP ON awfulhak> show log
2371 Log: Phase TCP/IP Warning Error Alert
2372 Local: Command Warning Error Alert
2375 Log messages of level Warning, Error and Alert are not controllable
2377 .Dq set log Op local .
2381 level is special in that it will not be logged if it can be displayed
2385 deals with the following signals:
2386 .Bl -tag -width "USR2"
2388 Receipt of this signal causes the termination of the current connection
2392 to exit unless it is in
2397 .It HUP, TERM & QUIT
2404 to re-open any existing server socket, dropping all existing diagnostic
2406 Sockets that couldn't previously be opened will be retried.
2410 to close any existing server socket, dropping all existing diagnostic
2413 can still be used to re-open the socket.
2416 If you wish to use more than one physical link to connect to a
2418 peer, that peer must also understand the
2421 Refer to RFC 1990 for specification details.
2423 The peer is identified using a combination of his
2424 .Dq endpoint discriminator
2426 .Dq authentication id .
2427 Either or both of these may be specified.
2428 It is recommended that
2429 at least one is specified, otherwise there is no way of ensuring that
2430 all links are actually connected to the same peer program, and some
2431 confusing lock-ups may result.
2432 Locally, these identification variables are specified using the
2440 must be agreed in advance with the peer.
2442 Multi-link capabilities are enabled using the
2444 command (set maximum reconstructed receive unit).
2445 Once multi-link is enabled,
2447 will attempt to negotiate a multi-link connection with the peer.
2449 By default, only one
2452 .Pq called Sq deflink .
2453 To create more links, the
2456 This command will clone existing links, where all
2457 characteristics are the same except:
2460 The new link has its own name as specified on the
2467 Its mode may subsequently be changed using the
2471 The new link is in a
2476 A summary of all available links can be seen using the
2480 Once a new link has been created, command usage varies.
2481 All link specific commands must be prefixed with the
2483 command, specifying on which link the command is to be applied.
2484 When only a single link is available,
2486 is smart enough not to require the
2490 Some commands can still be used without specifying a link - resulting
2491 in an operation at the
2494 For example, once two or more links are available, the command
2496 will show CCP configuration and statistics at the multi-link level, and
2497 .Dq link deflink show ccp
2498 will show the same information at the
2502 Armed with this information, the following configuration might be used:
2504 .Bd -literal -offset indent
2508 set device /dev/cuaa0 /dev/cuaa1 /dev/cuaa2
2509 set phone "123456789"
2510 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \\"\\" ATZ \e
2511 OK-AT-OK \\\\dATDT\\\\T TIMEOUT 45 CONNECT"
2513 set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0
2515 set authkey ppppassword
2518 clone 1,2,3 # Create 3 new links - duplicates of the default
2519 link deflink remove # Delete the default link (called ``deflink'')
2522 Note how all cloning is done at the end of the configuration.
2523 Usually, the link will be configured first, then cloned.
2524 If you wish all links
2525 to be up all the time, you can add the following line to the end of your
2528 .Bd -literal -offset indent
2529 link 1,2,3 set mode ddial
2532 If you want the links to dial on demand, this command could be used:
2534 .Bd -literal -offset indent
2535 link * set mode auto
2538 Links may be tied to specific names by removing the
2540 line above, and specifying the following after the
2544 .Bd -literal -offset indent
2545 link 1 set device /dev/cuaa0
2546 link 2 set device /dev/cuaa1
2547 link 3 set device /dev/cuaa2
2552 command to see which commands require context (using the
2554 command), which have optional
2555 context and which should not have any context.
2561 mode with the peer, it creates a local domain socket in the
2564 This socket is used to pass link information (including
2565 the actual link file descriptor) between different
2570 ability to be run from a
2576 capability), without needing to have initial control of the serial
2580 negotiates multi-link mode, it will pass its open link to any
2581 already running process.
2582 If there is no already running process,
2584 will act as the master, creating the socket and listening for new
2586 .Sh PPP COMMAND LIST
2587 This section lists the available commands and their effect.
2588 They are usable either from an interactive
2590 session, from a configuration file or from a
2596 .It accept|deny|enable|disable Ar option....
2597 These directives tell
2599 how to negotiate the initial connection with the peer.
2602 has a default of either accept or deny and enable or disable.
2604 means that the option will be ACK'd if the peer asks for it.
2606 means that the option will be NAK'd if the peer asks for it.
2608 means that the option will be requested by us.
2610 means that the option will not be requested by us.
2613 may be one of the following:
2616 Default: Enabled and Accepted.
2617 ACFComp stands for Address and Control Field Compression.
2618 Non LCP packets will usually have an address
2619 field of 0xff (the All-Stations address) and a control field of
2620 0x03 (the Unnumbered Information command).
2622 negotiated, these two bytes are simply not sent, thus minimising
2629 Default: Disabled and Accepted.
2630 CHAP stands for Challenge Handshake Authentication Protocol.
2631 Only one of CHAP and PAP (below) may be negotiated.
2632 With CHAP, the authenticator sends a "challenge" message to its peer.
2633 The peer uses a one-way hash function to encrypt the
2634 challenge and sends the result back.
2635 The authenticator does the same, and compares the results.
2636 The advantage of this mechanism is that no
2637 passwords are sent across the connection.
2638 A challenge is made when the connection is first made.
2639 Subsequent challenges may occur.
2640 If you want to have your peer authenticate itself, you must
2643 .Pa /etc/ppp/ppp.conf ,
2644 and have an entry in
2645 .Pa /etc/ppp/ppp.secret
2648 When using CHAP as the client, you need only specify
2653 .Pa /etc/ppp/ppp.conf .
2654 CHAP is accepted by default.
2657 implementations use "MS-CHAP" rather than MD5 when encrypting the
2659 MS-CHAP is a combination of MD4 and DES.
2662 was built on a machine with DES libraries available, it will respond
2663 to MS-CHAP authentication requests, but will never request them.
2665 Default: Enabled and Accepted.
2666 This option decides if deflate
2667 compression will be used by the Compression Control Protocol (CCP).
2668 This is the same algorithm as used by the
2671 Note: There is a problem negotiating
2677 implementation available under many operating systems.
2679 (version 2.3.1) incorrectly attempts to negotiate
2681 compression using type
2683 as the CCP configuration type rather than type
2689 is actually specified as
2690 .Dq PPP Magna-link Variable Resource Compression
2694 is capable of negotiating with
2701 .Ar accept Ns No ed .
2703 Default: Disabled and Denied.
2704 This is a variance of the
2706 option, allowing negotiation with the
2711 section above for details.
2712 It is disabled by default as it violates
2715 Default: Disabled and Denied.
2716 This option allows DNS negotiation.
2721 will request that the peer confirms the entries in
2722 .Pa /etc/resolv.conf .
2723 If the peer NAKs our request (suggesting new IP numbers),
2724 .Pa /etc/resolv.conf
2725 is updated and another request is sent to confirm the new entries.
2728 .Dq accept Ns No ed,
2730 will answer any DNS queries requested by the peer rather than rejecting
2732 The answer is taken from
2733 .Pa /etc/resolv.conf
2736 command is used as an override.
2738 Default: Enabled and Accepted.
2739 This option allows control over whether we
2740 negotiate an endpoint discriminator.
2741 We only send our discriminator if
2746 We reject the peers discriminator if
2750 Default: Disabled and Accepted.
2751 The use of this authentication protocol
2752 is discouraged as it partially violates the authentication protocol by
2753 implementing two different mechanisms (LANMan & NT) under the guise of
2754 a single CHAP type (0x80).
2756 uses a simple DES encryption mechanism and is the least secure of the
2757 CHAP alternatives (although is still more secure than PAP).
2761 description below for more details.
2763 Default: Disabled and Accepted.
2764 This option decides if Link Quality Requests will be sent or accepted.
2765 LQR is a protocol that allows
2767 to determine that the link is down without relying on the modems
2769 When LQR is enabled,
2775 below) as part of the LCP request.
2776 If the peer agrees, both sides will
2777 exchange LQR packets at the agreed frequency, allowing detailed link
2778 quality monitoring by enabling LQM logging.
2779 If the peer doesn't agree,
2781 will send ECHO LQR requests instead.
2782 These packets pass no information of interest, but they
2784 be replied to by the peer.
2786 Whether using LQR or ECHO LQR,
2788 will abruptly drop the connection if 5 unacknowledged packets have been
2789 sent rather than sending a 6th.
2790 A message is logged at the
2792 level, and any appropriate
2794 values are honoured as if the peer were responsible for dropping the
2797 Default: Enabled and Accepted.
2798 This is Microsoft Point to Point Encryption scheme.
2799 MPPE key size can be
2800 40-, 56- and 128-bits.
2805 Default: Disabled and Accepted.
2806 It is very similar to standard CHAP (type 0x05)
2807 except that it issues challenges of a fixed 16 bytes in length and uses a
2808 combination of MD4, SHA-1 and DES to encrypt the challenge rather than using the
2809 standard MD5 mechanism.
2811 Default: Disabled and Accepted.
2812 The use of this authentication protocol
2813 is discouraged as it partially violates the authentication protocol by
2814 implementing two different mechanisms (LANMan & NT) under the guise of
2815 a single CHAP type (0x80).
2816 It is very similar to standard CHAP (type 0x05)
2817 except that it issues challenges of a fixed 8 bytes in length and uses a
2818 combination of MD4 and DES to encrypt the challenge rather than using the
2819 standard MD5 mechanism.
2820 CHAP type 0x80 for LANMan is also supported - see
2828 use CHAP type 0x80, when acting as authenticator with both
2829 .Dq enable Ns No d ,
2831 will rechallenge the peer up to three times if it responds using the wrong
2832 one of the two protocols.
2833 This gives the peer a chance to attempt using both protocols.
2837 acts as the authenticatee with both protocols
2838 .Dq accept Ns No ed ,
2839 the protocols are used alternately in response to challenges.
2841 Note: If only LANMan is enabled,
2843 (version 2.3.5) misbehaves when acting as authenticatee.
2845 the NT and the LANMan answers, but also suggests that only the NT answer
2848 Default: Disabled and Accepted.
2849 PAP stands for Password Authentication Protocol.
2850 Only one of PAP and CHAP (above) may be negotiated.
2851 With PAP, the ID and Password are sent repeatedly to the peer until
2852 authentication is acknowledged or the connection is terminated.
2853 This is a rather poor security mechanism.
2854 It is only performed when the connection is first established.
2855 If you want to have your peer authenticate itself, you must
2858 .Pa /etc/ppp/ppp.conf ,
2859 and have an entry in
2860 .Pa /etc/ppp/ppp.secret
2861 for the peer (although see the
2867 When using PAP as the client, you need only specify
2872 .Pa /etc/ppp/ppp.conf .
2873 PAP is accepted by default.
2875 Default: Enabled and Accepted.
2876 This option decides if Predictor 1
2877 compression will be used by the Compression Control Protocol (CCP).
2879 Default: Enabled and Accepted.
2880 This option is used to negotiate
2881 PFC (Protocol Field Compression), a mechanism where the protocol
2882 field number is reduced to one octet rather than two.
2884 Default: Enabled and Accepted.
2885 This option determines if
2887 will request and accept requests for short
2889 sequence numbers when negotiating multi-link mode.
2890 This is only applicable if our MRRU is set (thus enabling multi-link).
2892 Default: Enabled and Accepted.
2893 This option determines if Van Jacobson header compression will be used.
2896 The following options are not actually negotiated with the peer.
2897 Therefore, accepting or denying them makes no sense.
2899 .It filter-decapsulation
2901 When this option is enabled,
2903 will examine UDP frames to see if they actually contain a
2905 frame as their payload.
2906 If this is the case, all filters will operate on the payload rather
2907 than the actual packet.
2909 This is useful if you want to send PPPoUDP traffic over a
2911 link, but want that link to do smart things with the real data rather than
2914 The UDP frame payload must not be compressed in any way, otherwise
2916 will not be able to interpret it.
2917 It's therefore recommended that you
2918 .Ic disable vj pred1 deflate
2920 .Ic deny vj pred1 deflate
2921 in the configuration for the
2923 invocation with the udp link.
2928 exchanges low-level LCP, CCP and IPCP configuration traffic, the
2930 field of any replies is expected to be the same as that of the request.
2933 drops any reply packets that do not contain the expected identifier
2934 field, reporting the fact at the respective log level.
2939 will ignore the identifier field.
2944 runs as a Multi-link server, a different
2946 instance initially receives each connection.
2947 After determining that
2948 the link belongs to an already existing bundle (controlled by another
2952 will transfer the link to that process.
2954 If the link is a tty device or if this option is enabled,
2956 will not exit, but will change its process name to
2958 and wait for the controlling
2960 to finish with the link and deliver a signal back to the idle process.
2961 This prevents the confusion that results from
2963 parent considering the link resource available again.
2965 For tty devices that have entries in
2967 this is necessary to prevent another
2969 from being started, and for program links such as
2973 from exiting due to the death of its child.
2976 cannot determine its parents requirements (except for the tty case), this
2977 option must be enabled manually depending on the circumstances.
2984 will automatically loop back packets being sent
2985 out with a destination address equal to that of the
2990 will send the packet, probably resulting in an ICMP redirect from
2992 It is convenient to have this option enabled when
2993 the interface is also the default route as it avoids the necessity
2994 of a loopback route.
2997 Enabling this option will tell the PAP authentication
2998 code to use the password database (see
3000 to authenticate the caller if they cannot be found in the
3001 .Pa /etc/ppp/ppp.secret
3003 .Pa /etc/ppp/ppp.secret
3004 is always checked first.
3005 If you wish to use passwords from
3007 but also to specify an IP number or label for a given client, use
3009 as the client password in
3010 .Pa /etc/ppp/ppp.secret .
3013 Enabling this option will tell
3015 to proxy ARP for the peer.
3018 will make an entry in the ARP table using
3022 address of the local network in which
3025 This allows other machines connecteed to the LAN to talk to
3026 the peer as if the peer itself was connected to the LAN.
3027 The proxy entry cannot be made unless
3029 is an address from a LAN.
3032 Enabling this will tell
3034 to add proxy arp entries for every IP address in all class C or
3035 smaller subnets routed via the tun interface.
3037 Proxy arp entries are only made for sticky routes that are added
3041 No proxy arp entries are made for the interface address itself
3049 command is used with the
3053 values, entries are stored in the
3060 change, this list is re-applied to the routing table.
3062 Disabling this option will prevent the re-application of sticky routes,
3065 list will still be maintained.
3072 to adjust TCP SYN packets so that the maximum receive segment
3073 size is not greater than the amount allowed by the interface MTU.
3078 to gather throughput statistics.
3079 Input and output is sampled over
3080 a rolling 5 second window, and current, best and total figures are retained.
3081 This data is output when the relevant
3083 layer shuts down, and is also available using the
3086 Throughput statistics are available at the
3093 Normally, when a user is authenticated using PAP or CHAP, and when
3097 mode, an entry is made in the utmp and wtmp files for that user.
3098 Disabling this option will tell
3100 not to make any utmp or wtmp entries.
3101 This is usually only necessary if
3102 you require the user to both login and authenticate themselves.
3107 This option simply tells
3109 to add new interface addresses to the interface rather than replacing them.
3110 The option can only be enabled if network address translation is enabled
3111 .Pq Dq nat enable yes .
3113 With this option enabled,
3115 will pass traffic for old interface addresses through the NAT engine
3116 .Pq see Xr libalias 3 ,
3117 resulting in the ability (in
3119 mode) to properly connect the process that caused the PPP link to
3120 come up in the first place.
3130 .Ar dest Ns Op / Ns Ar nn
3135 is the destination IP address.
3136 The netmask is specified either as a number of bits with
3138 or as an IP number using
3143 with no mask refers to the default route.
3144 It is also possible to use the literal name
3149 is the next hop gateway to get to the given
3154 command for further details.
3156 It is possible to use the symbolic names
3160 as the destination, and
3165 is replaced with the interface address and
3167 is replaced with the interface destination (peer) address.
3172 .Pq note the trailing Dq !\& ,
3173 then if the route already exists, it will be updated as with the
3177 for further details).
3179 Routes that contain the
3185 constants are considered
3187 They are stored in a list (use
3189 to see the list), and each time the value of
3195 changes, the appropriate routing table entries are updated.
3196 This facility may be disabled using
3197 .Dq disable sroutes .
3198 .It allow Ar command Op Ar args
3199 This command controls access to
3201 and its configuration files.
3202 It is possible to allow user-level access,
3203 depending on the configuration file label and on the mode that
3206 For example, you may wish to configure
3216 User id 0 is immune to these commands.
3218 .It allow user Ns Xo
3220 .Ar logname Ns No ...
3222 By default, only user id 0 is allowed access to
3224 If this command is used, all of the listed users are allowed access to
3225 the section in which the
3230 section is always checked first (even though it is only ever automatically
3233 commands are cumulative in a given section, but users allowed in any given
3234 section override users allowed in the default section, so it's possible to
3235 allow users access to everything except a given label by specifying default
3238 section, and then specifying a new user list for that label.
3242 is specified, access is allowed to all users.
3243 .It allow mode Ns Xo
3247 By default, access using any
3250 If this command is used, it restricts the access
3252 allowed to load the label under which this command is specified.
3257 command overrides any previous settings, and the
3259 section is always checked first.
3271 When running in multi-link mode, a section can be loaded if it allows
3273 of the currently existing line modes.
3276 .It nat Ar command Op Ar args
3277 This command allows the control of the network address translation (also
3278 known as masquerading or IP aliasing) facilities that are built into
3280 NAT is done on the external interface only, and is unlikely to make sense
3285 If nat is enabled on your system (it may be omitted at compile time),
3286 the following commands are possible:
3288 .It nat enable yes|no
3289 This command either switches network address translation on or turns it off.
3292 command line flag is synonymous with
3293 .Dq nat enable yes .
3294 .It nat addr Op Ar addr_local addr_alias
3295 This command allows data for
3299 It is useful if you own a small number of real IP numbers that
3300 you wish to map to specific machines behind your gateway.
3301 .It nat deny_incoming yes|no
3302 If set to yes, this command will refuse all incoming packets where an
3303 aliasing link doesn't already exist.
3305 .Sx CONCEPTUAL BACKGROUND
3308 for a description of what an
3312 It should be noted under what circumstances an aliasing link is created by
3314 It may be necessary to further protect your network from outside
3315 connections using the
3321 This command gives a summary of available nat commands.
3323 This option causes various NAT statistics and information to
3324 be logged to the file
3325 .Pa /var/log/alias.log .
3326 .It nat port Ar proto Ar targetIP Ns Xo
3327 .No : Ns Ar targetPort Ns
3329 .No - Ns Ar targetPort
3332 .No - Ns Ar aliasPort
3333 .Oc Oo Ar remoteIP : Ns
3336 .No - Ns Ar remotePort
3340 This command causes incoming
3354 A range of port numbers may be specified as shown above.
3355 The ranges must be of the same size.
3359 is specified, only data coming from that IP number is redirected.
3363 .Pq indicating any source port
3364 or a range of ports the same size as the other ranges.
3366 This option is useful if you wish to run things like Internet phone on
3367 machines behind your gateway, but is limited in that connections to only
3368 one interior machine per source machine and target port are possible.
3369 .It nat proto Ar proto localIP Oo
3370 .Ar publicIP Op Ar remoteIP
3374 to redirect packets of protocol type
3376 .Pq see Xr protocols 5
3377 to the internall address
3382 is specified, only packets destined for that address are matched,
3383 otherwise the default alias address is used.
3387 is specified, only packets matching that source address are matched,
3389 This command is useful for redirecting tunnel endpoints to an internal machine,
3392 .Dl nat proto ipencap 10.0.0.1
3393 .It "nat proxy cmd" Ar arg Ns No ...
3396 to proxy certain connections, redirecting them to a given server.
3397 Refer to the description of
3398 .Fn PacketAliasProxyRule
3401 for details of the available commands.
3402 .It nat punch_fw Op Ar base count
3405 to punch holes in the firewall for FTP or IRC DCC connections.
3406 This is done dynamically by installing termporary firewall rules which
3407 allow a particular connection (and only that connection) to go through
3409 The rules are removed once the corresponding connection terminates.
3413 rules starting from rule number
3415 will be used for punching firewall holes.
3416 The range will be cleared when the
3420 If no arguments are given, firewall punching is disabled.
3421 .It nat same_ports yes|no
3422 When enabled, this command will tell the network address translation engine to
3423 attempt to avoid changing the port number on outgoing packets.
3425 if you want to support protocols such as RPC and LPD which require
3426 connections to come from a well known port.
3427 .It nat target Op Ar address
3428 Set the given target address or clear it if no address is given.
3429 The target address is used by libalias to specify how to NAT incoming
3431 If a target address is not set or if
3433 is given, packets are not altered and are allowed to route to the internal
3436 The target address may be set to
3438 in which case libalias will redirect all packets to the interface address.
3439 .It nat use_sockets yes|no
3440 When enabled, this option tells the network address translation engine to
3441 create a socket so that it can guarantee a correct incoming ftp data or
3443 .It nat unregistered_only yes|no
3444 Only alter outgoing packets with an unregistered source address.
3445 According to RFC 1918, unregistered source addresses
3446 are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16.
3449 These commands are also discussed in the file
3451 which comes with the source distribution.
3458 is executed in the background with the following words replaced:
3459 .Bl -tag -width PEER_ENDDISC
3461 This is replaced with the local
3467 .It Li COMPILATIONDATE
3468 This is replaced with the date on which
3472 These are replaced with the primary and secondary nameserver IP numbers.
3473 If nameservers are negotiated by IPCP, the values of these macros will change.
3475 This is replaced with the local endpoint discriminator value.
3480 This is replaced with the peers IP number.
3482 This is replaced with the name of the interface that's in use.
3484 This is replaced with the last label name used.
3485 A label may be specified on the
3487 command line, via the
3495 This is replaced with the IP number assigned to the local interface.
3497 This is replaced with the value of the peers endpoint discriminator.
3499 This is replaced with the current process id.
3501 This is replaced with the current version number of
3504 This is replaced with the username that has been authenticated with PAP or
3506 Normally, this variable is assigned only in -direct mode.
3507 This value is available irrespective of whether utmp logging is enabled.
3510 These substitutions are also done by the
3514 If you wish to pause
3516 while the command executes, use the
3519 .It clear physical|ipcp Op current|overall|peak...
3520 Clear the specified throughput values at either the
3527 is specified, context must be given (see the
3530 If no second argument is given, all values are cleared.
3531 .It clone Ar name Ns Xo
3532 .Op \&, Ns Ar name Ns
3535 Clone the specified link, creating one or more new links according to the
3538 This command must be used from the
3540 command below unless you've only got a single link (in which case that
3541 link becomes the default).
3542 Links may be removed using the
3546 The default link name is
3548 .It close Op lcp|ccp Ns Op !\&
3549 If no arguments are given, the relevant protocol layers will be brought
3550 down and the link will be closed.
3553 is specified, the LCP layer is brought down, but
3555 will not bring the link offline.
3556 It is subsequently possible to use
3559 to talk to the peer machine if, for example, something like
3564 is specified, only the relevant compression layer is closed.
3567 is used, the compression layer will remain in the closed state, otherwise
3568 it will re-enter the STOPPED state, waiting for the peer to initiate
3569 further CCP negotiation.
3570 In any event, this command does not disconnect the user from
3581 This command deletes the route with the given
3588 all non-direct entries in the routing table for the current interface,
3591 entries are deleted.
3596 the default route is deleted.
3601 .Pq note the trailing Dq !\& ,
3603 will not complain if the route does not already exist.
3604 .It dial|call Op Ar label Ns Xo
3607 This command is the equivalent of
3611 and is provided for backwards compatibility.
3612 .It down Op Ar lcp|ccp
3613 Bring the relevant layer down ungracefully, as if the underlying layer
3614 had become unavailable.
3615 It's not considered polite to use this command on
3616 a Finite State Machine that's in the OPEN state.
3618 supplied, the entire link is closed (or if no context is given, all links
3624 layer is terminated but the device is not brought offline and the link
3628 is specified, only the relevant compression layer(s) are terminated.
3629 .It help|? Op Ar command
3630 Show a list of available commands.
3633 is specified, show the usage string for that command.
3634 .It ident Op Ar text Ns No ...
3635 Identify the link to the peer using
3639 is empty, link identification is disabled.
3640 It is possible to use any of the words described for the
3645 command for details of when
3647 identifies itself to the peer.
3648 .It iface Ar command Op args
3649 This command is used to control the interface used by
3652 may be one of the following:
3656 .Ar addr Ns Op / Ns Ar bits
3667 combination to the interface.
3668 Instead of specifying
3672 .Pq with no space between \&it and Ar addr .
3673 If the given address already exists, the command fails unless the
3675 is used - in which case the previous interface address entry is overwritten
3676 with the new one, allowing a change of netmask or peer address.
3687 .Dq 255.255.255.255 .
3688 This address (the broadcast address) is the only duplicate peer address that
3692 If this command is used while
3694 is in the OPENED state or while in
3696 mode, all addresses except for the IPCP negotiated address are deleted
3700 is not in the OPENED state and is not in
3702 mode, all interface addresses are deleted.
3704 .It iface delete Ns Xo
3709 This command deletes the given
3714 is used, no error is given if the address isn't currently assigned to
3715 the interface (and no deletion takes place).
3717 Shows the current state and current addresses for the interface.
3718 It is much the same as running
3719 .Dq ifconfig INTERFACE .
3720 .It iface help Op Ar sub-command
3721 This command, when invoked without
3723 will show a list of possible
3725 sub-commands and a brief synopsis for each.
3728 only the synopsis for the given sub-command is shown.
3732 .Ar name Ns Op , Ns Ar name Ns
3733 .No ... Ar command Op Ar args
3735 This command may prefix any other command if the user wishes to
3736 specify which link the command should affect.
3737 This is only applicable after multiple links have been created in Multi-link
3743 specifies the name of an existing link.
3746 is a comma separated list,
3748 is executed on each link.
3754 is executed on all links.
3755 .It load Op Ar label Ns Xo
3778 will not attempt to make an immediate connection.
3779 .It open Op lcp|ccp|ipcp
3780 This is the opposite of the
3783 All closed links are immediately brought up apart from second and subsequent
3785 links - these will come up based on the
3787 command that has been used.
3791 argument is used while the LCP layer is already open, LCP will be
3793 This allows various LCP options to be changed, after which
3795 can be used to put them into effect.
3796 After renegotiating LCP,
3797 any agreed authentication will also take place.
3801 argument is used, the relevant compression layer is opened.
3802 Again, if it is already open, it will be renegotiated.
3806 argument is used, the link will be brought up as normal, but if
3807 IPCP is already open, it will be renegotiated and the network
3808 interface will be reconfigured.
3810 It is probably not good practice to re-open the PPP state machines
3811 like this as it's possible that the peer will not behave correctly.
3814 however useful as a way of forcing the CCP or VJ dictionaries to be reset.
3816 Specify the password required for access to the full
3819 This password is required when connecting to the diagnostic port (see the
3830 logging is active, instead, the literal string
3836 is executed from the controlling connection or from a command file,
3837 ppp will exit after closing all connections.
3838 Otherwise, if the user
3839 is connected to a diagnostic socket, the connection is simply dropped.
3845 will exit despite the source of the command after closing all existing
3848 This command removes the given link.
3849 It is only really useful in multi-link mode.
3850 A link must be in the
3852 state before it is removed.
3853 .It rename|mv Ar name
3854 This command renames the given link to
3858 is already used by another link.
3860 The default link name is
3867 may make the log file more readable.
3868 .It resolv Ar command
3869 This command controls
3876 starts up, it loads the contents of this file into memory and retains this
3877 image for future use.
3879 is one of the following:
3880 .Bl -tag -width readonly
3883 .Pa /etc/resolv.conf
3889 will still attempt to negotiate nameservers with the peer, making the results
3895 This is the opposite of the
3900 .Pa /etc/resolv.conf
3902 This may be necessary if for example a DHCP client overwrote
3903 .Pa /etc/resolv.conf .
3906 .Pa /etc/resolv.conf
3907 with the version originally read at startup or with the last
3910 This is sometimes a useful command to put in the
3911 .Pa /etc/ppp/ppp.linkdown
3915 .Pa /etc/resolv.conf
3917 This command will work even if the
3919 command has been used.
3920 It may be useful as a command in the
3921 .Pa /etc/ppp/ppp.linkup
3922 file if you wish to defer updating
3923 .Pa /etc/resolv.conf
3924 until after other commands have finished.
3929 .Pa /etc/resolv.conf
3934 successfully negotiates a DNS.
3935 This is the opposite of the
3940 This option is not (yet) implemented.
3944 to identify itself to the peer.
3945 The link must be in LCP state or higher.
3946 If no identity has been set (via the
3952 When an identity has been set,
3954 will automatically identify itself when it sends or receives a configure
3955 reject, when negotiation fails or when LCP reaches the opened state.
3957 Received identification packets are logged to the LCP log (see
3959 for details) and are never responded to.
3964 This option allows the setting of any of the following variables:
3966 .It set accmap Ar hex-value
3967 ACCMap stands for Asynchronous Control Character Map.
3969 negotiated with the peer, and defaults to a value of 00000000 in hex.
3970 This protocol is required to defeat hardware that depends on passing
3971 certain characters from end to end (such as XON/XOFF etc).
3973 For the XON/XOFF scenario, use
3974 .Dq set accmap 000a0000 .
3975 .It set Op auth Ns Xo
3978 This sets the authentication key (or password) used in client mode
3979 PAP or CHAP negotiation to the given value.
3980 It also specifies the
3981 password to be used in the dial or login scripts in place of the
3983 sequence, preventing the actual password from being logged.
3988 logging is in effect,
3992 for security reasons.
3994 If the first character of
3996 is an exclamation mark
3999 treats the remainder of the string as a program that must be executed
4010 it is treated as a single literal
4012 otherwise, ignoring the
4015 is parsed as a program to execute in the same was as the
4017 command above, substituting special names in the same manner.
4020 will feed the program three lines of input, each terminated by a newline
4024 The host name as sent in the CHAP challenge.
4026 The challenge string as sent in the CHAP challenge.
4032 Two lines of output are expected:
4037 to be sent with the CHAP response.
4041 which is encrypted with the challenge and request id, the answer being sent
4042 in the CHAP response packet.
4047 in this manner, it's expected that the host challenge is a series of ASCII
4048 digits or characters.
4049 An encryption device or Secure ID card is usually
4050 required to calculate the secret appropriate for the given challenge.
4051 .It set authname Ar id
4052 This sets the authentication id used in client mode PAP or CHAP negotiation.
4056 mode with CHAP enabled,
4058 is used in the initial authentication challenge and should normally be set to
4059 the local machine name.
4061 .Ar min-percent max-percent period
4063 These settings apply only in multi-link mode and default to zero, zero and
4067 .Pq also known as Fl auto
4068 mode link is available, only the first link is made active when
4070 first reads data from the tun device.
4073 link will be opened only when the current bundle throughput is at least
4075 percent of the total bundle bandwidth for
4078 When the current bundle throughput decreases to
4080 percent or less of the total bundle bandwidth for
4084 link will be brought down as long as it's not the last active link.
4086 Bundle throughput is measured as the maximum of inbound and outbound
4089 The default values cause
4091 links to simply come up one at a time.
4093 Certain devices cannot determine their physical bandwidth, so it
4094 is sometimes necessary to use the
4096 command (described below) to make
4099 .It set bandwidth Ar value
4100 This command sets the connection bandwidth in bits per second.
4102 must be greater than zero.
4103 It is currently only used by the
4106 .It set callback Ar option Ns No ...
4107 If no arguments are given, callback is disabled, otherwise,
4111 mode, will accept) one of the given
4112 .Ar option Ns No s .
4113 In client mode, if an
4117 will request a different
4119 until no options remain at which point
4121 will terminate negotiations (unless
4123 is one of the specified
4127 will accept any of the given protocols - but the client
4129 request one of them.
4130 If you wish callback to be optional, you must include
4136 are as follows (in this order of preference):
4140 The callee is expected to decide the callback number based on
4144 is the callee, the number should be specified as the fifth field of
4146 .Pa /etc/ppp/ppp.secret .
4148 Microsoft's callback control protocol is used.
4153 If you wish to negotiate
4155 in client mode but also wish to allow the server to request no callback at
4156 CBCP negotiation time, you must specify both
4160 as callback options.
4162 .Ar number Ns Op , Ns Ar number Ns
4165 The caller specifies the
4171 should be either a comma separated list of allowable numbers or a
4173 meaning any number is permitted.
4176 is the caller, only a single number should be specified.
4178 Note, this option is very unsafe when used with a
4180 as a malicious caller can tell
4182 to call any (possibly international) number without first authenticating
4185 If the peer does not wish to do callback at all,
4187 will accept the fact and continue without callback rather than terminating
4189 This is required (in addition to one or more other callback
4190 options) if you wish callback to be optional.
4194 .No *| Ns Ar number Ns Oo
4195 .No , Ns Ar number Ns ...\& Oc
4196 .Op Ar delay Op Ar retry
4198 If no arguments are given, CBCP (Microsoft's CallBack Control Protocol)
4199 is disabled - ie, configuring CBCP in the
4201 command will result in
4203 requesting no callback in the CBCP phase.
4206 attempts to use the given phone
4207 .Ar number Ns No (s).
4212 will insist that the client uses one of these numbers, unless
4214 is used in which case the client is expected to specify the number.
4218 will attempt to use one of the given numbers (whichever it finds to
4219 be agreeable with the peer), or if
4223 will expect the peer to specify the number.
4225 .No off| Ns Ar seconds Ns Op !\&
4229 checks for the existence of carrier depending on the type of device
4230 that has been opened:
4231 .Bl -tag -width XXX -offset XXX
4232 .It Terminal Devices
4233 Carrier is checked one second after the login script is complete.
4236 assumes that this is because the device doesn't support carrier (which
4239 NULL-modem cables), logs the fact and stops checking
4242 As ptys don't support the TIOCMGET ioctl, the tty device will switch all
4243 carrier detection off when it detects that the device is a pty.
4244 .It ISDN (i4b) Devices
4245 Carrier is checked once per second for 6 seconds.
4246 If it's not set after
4247 the sixth second, the connection attempt is considered to have failed and
4248 the device is closed.
4249 Carrier is always required for i4b devices.
4250 .It PPPoE (netgraph) Devices
4251 Carrier is checked once per second for 5 seconds.
4252 If it's not set after
4253 the fifth second, the connection attempt is considered to have failed and
4254 the device is closed.
4255 Carrier is always required for PPPoE devices.
4258 All other device types don't support carrier.
4259 Setting a carrier value will
4260 result in a warning when the device is opened.
4262 Some modems take more than one second after connecting to assert the carrier
4264 If this delay isn't increased, this will result in
4266 inability to detect when the link is dropped, as
4268 assumes that the device isn't asserting carrier.
4272 command overrides the default carrier behaviour.
4274 specifies the maximum number of seconds that
4276 should wait after the dial script has finished before deciding if
4277 carrier is available or not.
4283 will not check for carrier on the device, otherwise
4285 will not proceed to the login script until either carrier is detected
4288 has elapsed, at which point
4290 assumes that the device will not set carrier.
4292 If no arguments are given, carrier settings will go back to their default
4297 is followed immediately by an exclamation mark
4303 If carrier is not detected after
4305 seconds, the link will be disconnected.
4306 .It set choked Op Ar timeout
4307 This sets the number of seconds that
4309 will keep a choked output queue before dropping all pending output packets.
4312 is less than or equal to zero or if
4314 isn't specified, it is set to the default value of
4317 A choked output queue occurs when
4319 has read a certain number of packets from the local network for transmission,
4320 but cannot send the data due to link failure (the peer is busy etc.).
4322 will not read packets indefinitely.
4323 Instead, it reads up to
4329 packets in multi-link mode), then stops reading the network interface
4332 seconds have passed or at least one packet has been sent.
4336 seconds pass, all pending output packets are dropped.
4337 .It set ctsrts|crtscts on|off
4338 This sets hardware flow control.
4339 Hardware flow control is
4342 .It set deflate Ar out-winsize Op Ar in-winsize
4343 This sets the DEFLATE algorithms default outgoing and incoming window
4349 must be values between
4357 will insist that this window size is used and will not accept any other
4358 values from the peer.
4359 .It set dns Op Ar primary Op Ar secondary
4360 This command specifies DNS overrides for the
4365 command description above for details.
4366 This command does not affect the IP numbers requested using
4368 .It set device|line Xo
4371 This sets the device(s) to which
4373 will talk to the given
4376 All ISDN and serial device names are expected to begin with
4378 ISDN devices are usually called
4380 and serial devices are usually called
4387 it must either begin with an exclamation mark
4390 .No PPPoE: Ns Ar iface Ns Xo
4391 .Op \&: Ns Ar provider Ns
4395 enabled systems), or be of the format
4397 .Ar host : port Op /tcp|udp .
4400 If it begins with an exclamation mark, the rest of the device name is
4401 treated as a program name, and that program is executed when the device
4403 Standard input, output and error are fed back to
4405 and are read and written as if they were a regular device.
4408 .No PPPoE: Ns Ar iface Ns Xo
4409 .Op \&: Ns Ar provider Ns
4411 specification is given,
4413 will attempt to create a
4415 over Ethernet connection using the given
4423 will attempt to load it using
4425 If this fails, an external program must be used such as the
4427 program available under OpenBSD.
4430 is passed as the service name in the PPPoE Discovery Initiation (PADI)
4432 If no provider is given, an empty value will be used.
4437 for further details.
4440 .Ar host Ns No : Ns Ar port Ns Oo
4443 specification is given,
4445 will attempt to connect to the given
4453 suffix is not provided, the default is
4455 Refer to the section on
4456 .Em PPP OVER TCP and UDP
4457 above for further details.
4463 will attempt to open each one in turn until it succeeds or runs out of
4465 .It set dial Ar chat-script
4466 This specifies the chat script that will be used to dial the other
4473 and to the example configuration files for details of the chat script
4475 It is possible to specify some special
4477 in your chat script as follows:
4480 When used as the last character in a
4482 string, this indicates that a newline should not be appended.
4484 When the chat script encounters this sequence, it delays two seconds.
4486 When the chat script encounters this sequence, it delays for one quarter of
4489 This is replaced with a newline character.
4491 This is replaced with a carriage return character.
4493 This is replaced with a space character.
4495 This is replaced with a tab character.
4497 This is replaced by the current phone number (see
4501 This is replaced by the current
4507 This is replaced by the current
4514 Note that two parsers will examine these escape sequences, so in order to
4517 see the escape character, it is necessary to escape it from the
4518 .Sq command parser .
4519 This means that in practice you should use two escapes, for example:
4520 .Bd -literal -offset indent
4521 set dial "... ATDT\\\\T CONNECT"
4524 It is also possible to execute external commands from the chat script.
4525 To do this, the first character of the expect or send string is an
4528 If a literal exclamation mark is required, double it up to
4530 and it will be treated as a single literal
4532 When the command is executed, standard input and standard output are
4533 directed to the open device (see the
4535 command), and standard error is read by
4537 and substituted as the expect or send string.
4540 is running in interactive mode, file descriptor 3 is attached to
4543 For example (wrapped for readability):
4544 .Bd -literal -offset indent
4545 set login "TIMEOUT 5 \\"\\" \\"\\" login:--login: ppp \e
4546 word: ppp \\"!sh \\\\-c \\\\\\"echo \\\\-n label: >&2\\\\\\"\\" \e
4547 \\"!/bin/echo in\\" HELLO"
4550 would result in the following chat sequence (output using the
4551 .Sq set log local chat
4552 command before dialing):
4553 .Bd -literal -offset indent
4558 Chat: Expecting: login:--login:
4559 Chat: Wait for (5): login:
4561 Chat: Expecting: word:
4562 Chat: Wait for (5): word:
4564 Chat: Expecting: !sh \\-c "echo \\-n label: >&2"
4565 Chat: Exec: sh -c "echo -n label: >&2"
4566 Chat: Wait for (5): !sh \\-c "echo \\-n label: >&2" --> label:
4567 Chat: Exec: /bin/echo in
4569 Chat: Expecting: HELLO
4570 Chat: Wait for (5): HELLO
4574 Note (again) the use of the escape character, allowing many levels of
4576 Here, there are four parsers at work.
4577 The first parses the original line, reading it as three arguments.
4578 The second parses the third argument, reading it as 11 arguments.
4579 At this point, it is
4582 signs are escaped, otherwise this parser will see them as constituting
4583 an expect-send-expect sequence.
4586 character is seen, the execution parser reads the first command as three
4589 itself expands the argument after the
4591 As we wish to send the output back to the modem, in the first example
4592 we redirect our output to file descriptor 2 (stderr) so that
4594 itself sends and logs it, and in the second example, we just output to stdout,
4595 which is attached directly to the modem.
4597 This, of course means that it is possible to execute an entirely external
4599 command rather than using the internal one.
4602 for a good alternative.
4604 The external command that is executed is subjected to the same special
4605 word expansions as the
4608 .It set enddisc Op label|IP|MAC|magic|psn value
4609 This command sets our local endpoint discriminator.
4610 If set prior to LCP negotiation, and if no
4612 command has been used,
4614 will send the information to the peer using the LCP endpoint discriminator
4616 The following discriminators may be set:
4617 .Bl -tag -width indent
4619 The current label is used.
4621 Our local IP number is used.
4622 As LCP is negotiated prior to IPCP, it is
4623 possible that the IPCP layer will subsequently change this value.
4625 it does, the endpoint discriminator stays at the old value unless manually
4628 This is similar to the
4630 option above, except that the MAC address associated with the local IP
4632 If the local IP number is not resident on any Ethernet
4633 interface, the command will fail.
4635 As the local IP number defaults to whatever the machine host name is,
4637 is usually done prior to any
4641 A 20 digit random number is used.
4642 Care should be taken when using magic numbers as restarting
4644 or creating a link using a different
4646 invocation will also use a different magic number and will therefore not
4647 be recognised by the peer as belonging to the same bundle.
4648 This makes it unsuitable for
4656 should be set to an absolute public switched network number with the
4660 If no arguments are given, the endpoint discriminator is reset.
4661 .It set escape Ar value...
4662 This option is similar to the
4665 It allows the user to specify a set of characters that will be
4667 as they travel across the link.
4668 .It set filter dial|alive|in|out Ar rule-no Xo
4669 .No permit|deny|clear| Ns Ar rule-no
4672 .Ar src_addr Ns Op / Ns Ar width
4673 .Op Ar dst_addr Ns Op / Ns Ar width
4674 .Oc [ tcp|udp|ospf|ipip|igmp|icmp Op src lt|eq|gt Ar port
4675 .Op dst lt|eq|gt Ar port
4679 .Op timeout Ar secs ]
4682 supports four filter sets.
4685 filter specifies packets that keep the connection alive - resetting the
4689 filter specifies packets that cause
4696 filter specifies packets that are allowed to travel
4697 into the machine and the
4699 filter specifies packets that are allowed out of the machine.
4701 Filtering is done prior to any IP alterations that might be done by the
4702 NAT engine on outgoing packets and after any IP alterations that might
4703 be done by the NAT engine on incoming packets.
4704 By default all empty filter sets allow all packets to pass.
4705 Rules are processed in order according to
4707 (unless skipped by specifying a rule number as the
4709 Up to 40 rules may be given for each set.
4710 If a packet doesn't match
4711 any of the rules in a given set, it is discarded.
4716 filters, this means that the packet is dropped.
4719 filters it means that the packet will not reset the idle timer (even if
4721 .Ar in Ns No / Ns Ar out
4724 value) and in the case of
4726 filters it means that the packet will not trigger a dial.
4727 A packet failing to trigger a dial will be dropped rather than queued.
4730 .Sx PACKET FILTERING
4731 above for further details.
4732 .It set hangup Ar chat-script
4733 This specifies the chat script that will be used to reset the device
4734 before it is closed.
4735 It should not normally be necessary, but can
4736 be used for devices that fail to reset themselves properly on close.
4737 .It set help|? Op Ar command
4738 This command gives a summary of available set commands, or if
4740 is specified, the command usage is shown.
4741 .It set ifaddr Oo Ar myaddr Ns
4743 .Oo Ar hisaddr Ns Op / Ns Ar \&nn
4748 This command specifies the IP addresses that will be used during
4750 Addresses are specified using the format
4756 is the preferred IP, but
4758 specifies how many bits of the address we will insist on.
4761 is omitted, it defaults to
4763 unless the IP address is 0.0.0.0 in which case it defaults to
4766 If you wish to assign a dynamic IP number to the peer,
4768 may also be specified as a range of IP numbers in the format
4769 .Bd -ragged -offset indent
4770 .Ar \&IP Ns Oo \&- Ns Ar \&IP Ns Xo
4771 .Oc Ns Oo , Ns Ar \&IP Ns
4772 .Op \&- Ns Ar \&IP Ns
4779 .Dl set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20
4783 as the local IP number, but may assign any of the given 10 IP
4784 numbers to the peer.
4785 If the peer requests one of these numbers,
4786 and that number is not already in use,
4788 will grant the peers request.
4789 This is useful if the peer wants
4790 to re-establish a link using the same IP number as was previously
4791 allocated (thus maintaining any existing tcp or udp connections).
4793 If the peer requests an IP number that's either outside
4794 of this range or is already in use,
4796 will suggest a random unused IP number from the range.
4800 is specified, it is used in place of
4802 in the initial IPCP negotiation.
4803 However, only an address in the
4805 range will be accepted.
4806 This is useful when negotiating with some
4808 implementations that will not assign an IP number unless their peer
4812 It should be noted that in
4816 will configure the interface immediately upon reading the
4818 line in the config file.
4819 In any other mode, these values are just
4820 used for IPCP negotiations, and the interface isn't configured
4821 until the IPCP layer is up.
4825 argument may be overridden by the third field in the
4827 file once the client has authenticated itself
4828 .Pq if PAP or CHAP are Dq enabled .
4830 .Sx AUTHENTICATING INCOMING CONNECTIONS
4831 section for details.
4833 In all cases, if the interface is already configured,
4835 will try to maintain the interface IP numbers so that any existing
4836 bound sockets will remain valid.
4837 .It set ifqueue Ar packets
4838 Set the maximum number of packets that
4840 will read from the tunnel interface while data cannot be sent to any of
4841 the available links.
4842 This queue limit is necessary to flow control outgoing data as the tunnel
4843 interface is likely to be far faster than the combined links available to
4848 is set to a value less than the number of links,
4850 will read up to that value regardless.
4851 This prevents any possible latency problems.
4853 The default value for
4857 .It set ccpretry|ccpretries Oo Ar timeout
4858 .Op Ar reqtries Op Ar trmtries
4860 .It set chapretry|chapretries Oo Ar timeout
4863 .It set ipcpretry|ipcpretries Oo Ar timeout
4864 .Op Ar reqtries Op Ar trmtries
4866 .It set lcpretry|lcpretries Oo Ar timeout
4867 .Op Ar reqtries Op Ar trmtries
4869 .It set papretry|papretries Oo Ar timeout
4872 These commands set the number of seconds that
4874 will wait before resending Finite State Machine (FSM) Request packets.
4877 for all FSMs is 3 seconds (which should suffice in most cases).
4881 is specified, it tells
4883 how many configuration request attempts it should make while receiving
4884 no reply from the peer before giving up.
4885 The default is 5 attempts for
4886 CCP, LCP and IPCP and 3 attempts for PAP and CHAP.
4890 is specified, it tells
4892 how many terminate requests should be sent before giving up waiting for the
4894 The default is 3 attempts.
4895 Authentication protocols are
4896 not terminated and it is therefore invalid to specify
4900 In order to avoid negotiations with the peer that will never converge,
4902 will only send at most 3 times the configured number of
4904 in any given negotiation session before giving up and closing that layer.
4910 This command allows the adjustment of the current log level.
4911 Refer to the Logging Facility section for further details.
4912 .It set login Ar chat-script
4915 compliments the dial-script.
4916 If both are specified, the login
4917 script will be executed after the dial script.
4918 Escape sequences available in the dial script are also available here.
4919 .It set logout Ar chat-script
4920 This specifies the chat script that will be used to logout
4921 before the hangup script is called.
4922 It should not normally be necessary.
4923 .It set lqrperiod Ar frequency
4924 This command sets the
4931 The default is 30 seconds.
4932 You must also use the
4934 command if you wish to send LQR requests to the peer.
4935 .It set mode Ar interactive|auto|ddial|background
4936 This command allows you to change the
4938 of the specified link.
4939 This is normally only useful in multi-link mode,
4940 but may also be used in uni-link mode.
4942 It is not possible to change a link that is
4947 Note: If you issue the command
4949 and have network address translation enabled, it may be useful to
4950 .Dq enable iface-alias
4954 to do the necessary address translations to enable the process that
4955 triggers the connection to connect once the link is up despite the
4956 peer assigning us a new (dynamic) IP address.
4957 .It set mppe Op 40|56|128|* Op stateless|stateful|*
4958 This option selects the encryption parameters used when negotiation
4960 MPPE can be disabled entirely with the
4963 If no arguments are given,
4965 will attempt to negotiate a stateful link with a 128 bit key, but
4966 will agree to whatever the peer requests (including no encryption
4969 If any arguments are given,
4973 on using MPPE and will close the link if it's rejected by the peer.
4975 The first argument specifies the number of bits that
4977 should insist on during negotiations and the second specifies whether
4979 should insist on stateful or stateless mode.
4980 In stateless mode, the
4981 encryption dictionary is re-initialised with every packet according to
4982 an encryption key that is changed with every packet.
4984 the encryption dictionary is re-initialised every 256 packets or after
4985 the loss of any data and the key is changed every 256 packets.
4986 Stateless mode is less efficient but is better for unreliable transport
4988 .It set mrru Op Ar value
4989 Setting this option enables Multi-link PPP negotiations, also known as
4990 Multi-link Protocol or MP.
4991 There is no default MRRU (Maximum Reconstructed Receive Unit) value.
4992 If no argument is given, multi-link mode is disabled.
4997 The default MRU (Maximum Receive Unit) is 1500.
4998 If it is increased, the other side *may* increase its MTU.
4999 In theory there is no point in decreasing the MRU to below the default as the
5001 protocol says implementations *must* be able to accept packets of at
5008 will refuse to negotiate a higher value.
5009 The maximum MRU can be set to 2048 at most.
5010 Setting a maximum of less than 1500 violates the
5012 rfc, but may sometimes be necessary.
5015 imposes a maximum of 1492 due to hardware limitations.
5017 If no argument is given, 1500 is assumed.
5018 A value must be given when
5025 The default MTU is 1500.
5026 At negotiation time,
5028 will accept whatever MRU the peer requests (assuming it's
5029 not less than 296 bytes or greater than the assigned maximum).
5032 will not accept MRU values less than
5034 When negotiations are complete, the MTU is used when writing to the
5035 interface, even if the peer requested a higher value MRU.
5036 This can be useful for
5037 limiting your packet size (giving better bandwidth sharing at the expense
5038 of more header data).
5044 will refuse to negotiate a higher value.
5045 The maximum MTU can be set to 2048 at most.
5049 is given, 1500, or whatever the peer asks for is used.
5050 A value must be given when
5053 .It set nbns Op Ar x.x.x.x Op Ar y.y.y.y
5054 This option allows the setting of the Microsoft NetBIOS name server
5055 values to be returned at the peers request.
5056 If no values are given,
5058 will reject any such requests.
5059 .It set openmode active|passive Op Ar delay
5068 will always initiate LCP/IPCP/CCP negotiation one second after the line
5070 If you want to wait for the peer to initiate negotiations, you
5073 If you want to initiate negotiations immediately or after more than one
5074 second, the appropriate
5076 may be specified here in seconds.
5077 .It set parity odd|even|none|mark
5078 This allows the line parity to be set.
5079 The default value is
5081 .It set phone Ar telno Ns Xo
5082 .Oo \&| Ns Ar backupnumber
5083 .Oc Ns ... Ns Oo : Ns Ar nextnumber
5086 This allows the specification of the phone number to be used in
5087 place of the \\\\T string in the dial and login chat scripts.
5088 Multiple phone numbers may be given separated either by a pipe
5093 Numbers after the pipe are only dialed if the dial or login
5094 script for the previous number failed.
5096 Numbers after the colon are tried sequentially, irrespective of
5097 the reason the line was dropped.
5099 If multiple numbers are given,
5101 will dial them according to these rules until a connection is made, retrying
5102 the maximum number of times specified by
5107 mode, each number is attempted at most once.
5108 .It set Op proc Ns Xo
5109 .No title Op Ar value
5111 The current process title as displayed by
5113 is changed according to
5117 is not specified, the original process title is restored.
5119 word replacements done by the shell commands (see the
5121 command above) are done here too.
5123 Note, if USER is required in the process title, the
5125 command must appear in
5127 as it is not known when the commands in
5130 .It set radius Op Ar config-file
5131 This command enables RADIUS support (if it's compiled in).
5133 refers to the radius client configuration file as described in
5136 .Dq enable Ns No d ,
5139 .Em \&N Ns No etwork
5142 and uses the configured RADIUS server to authenticate rather than
5143 authenticating from the
5145 file or from the passwd database.
5147 If neither PAP or CHAP are enabled,
5152 uses the following attributes from the RADIUS reply:
5153 .Bl -tag -width XXX -offset XXX
5154 .It RAD_FRAMED_IP_ADDRESS
5155 The peer IP address is set to the given value.
5156 .It RAD_FRAMED_IP_NETMASK
5157 The tun interface netmask is set to the given value.
5159 If the given MTU is less than the peers MRU as agreed during LCP
5160 negotiation, *and* it is less that any configured MTU (see the
5162 command), the tun interface MTU is set to the given value.
5163 .It RAD_FRAMED_COMPRESSION
5164 If the received compression type is
5167 will request VJ compression during IPCP negotiations despite any
5169 configuration command.
5170 .It RAD_FRAMED_ROUTE
5171 The received string is expected to be in the format
5172 .Ar dest Ns Op / Ns Ar bits
5175 Any specified metrics are ignored.
5179 are understood as valid values for
5186 to sepcify the default route, and
5188 is understood to be the same as
5197 For example, a returned value of
5198 .Dq 1.2.3.4/24 0.0.0.0 1 2 -1 3 400
5199 would result in a routing table entry to the 1.2.3.0/24 network via
5201 and a returned value of
5205 would result in a default route to
5208 All RADIUS routes are applied after any sticky routes are applied, making
5209 RADIUS routes override configured routes.
5210 This also applies for RADIUS routes that don't include the
5217 Values received from the RADIUS server may be viewed using
5219 .It set reconnect Ar timeout ntries
5220 Should the line drop unexpectedly (due to loss of CD or LQR
5221 failure), a connection will be re-established after the given
5223 The line will be re-connected at most
5232 will result in a variable pause, somewhere between 1 and 30 seconds.
5233 .It set recvpipe Op Ar value
5234 This sets the routing table RECVPIPE value.
5235 The optimum value is just over twice the MTU value.
5238 is unspecified or zero, the default kernel controlled value is used.
5239 .It set redial Ar secs Ns Xo
5242 .Oc Ns Op . Ns Ar next
5246 can be instructed to attempt to redial
5249 If more than one phone number is specified (see
5253 is taken before dialing each number.
5256 is taken before starting at the first number again.
5259 may be used here in place of
5263 causing a random delay of between 1 and 30 seconds.
5267 is specified, its value is added onto
5273 will only be incremented at most
5281 delay will be effective, even after
5283 has been exceeded, so an immediate manual dial may appear to have
5285 If an immediate dial is required, a
5287 should immediately follow the
5292 description above for further details.
5293 .It set sendpipe Op Ar value
5294 This sets the routing table SENDPIPE value.
5295 The optimum value is just over twice the MTU value.
5298 is unspecified or zero, the default kernel controlled value is used.
5299 .It "set server|socket" Ar TcpPort Ns No \&| Ns Xo
5300 .Ar LocalName Ns No |none|open|closed
5301 .Op password Op Ar mask
5305 to listen on the given socket or
5307 for incoming command connections.
5313 to close any existing socket and clear the socket configuration.
5318 to attempt to re-open the port.
5323 to close the open port.
5325 If you wish to specify a local domain socket,
5327 must be specified as an absolute file name, otherwise it is assumed
5328 to be the name or number of a TCP port.
5329 You may specify the octal umask to be used with a local domain socket.
5335 for details of how to translate TCP port names.
5337 You must also specify the password that must be entered by the client
5340 variable above) when connecting to this socket.
5342 specified as an empty string, no password is required for connecting clients.
5344 When specifying a local domain socket, the first
5346 sequence found in the socket name will be replaced with the current
5347 interface unit number.
5348 This is useful when you wish to use the same
5349 profile for more than one connection.
5351 In a similar manner TCP sockets may be prefixed with the
5353 character, in which case the current interface unit number is added to
5358 with a server socket, the
5360 command is the preferred mechanism of communications.
5363 can also be used, but link encryption may be implemented in the future, so
5371 interact with the diagnostic socket.
5372 .It set speed Ar value
5373 This sets the speed of the serial device.
5374 If speed is specified as
5377 treats the device as a synchronous device.
5379 Certain device types will know whether they should be specified as
5380 synchronous or asynchronous.
5381 These devices will override incorrect
5382 settings and log a warning to this effect.
5383 .It set stopped Op Ar LCPseconds Op Ar CCPseconds
5384 If this option is set,
5386 will time out after the given FSM (Finite State Machine) has been in
5387 the stopped state for the given number of
5389 This option may be useful if the peer sends a terminate request,
5390 but never actually closes the connection despite our sending a terminate
5392 This is also useful if you wish to
5393 .Dq set openmode passive
5394 and time out if the peer doesn't send a Configure Request within the
5397 .Dq set log +lcp +ccp
5400 log the appropriate state transitions.
5402 The default value is zero, where
5404 doesn't time out in the stopped state.
5406 This value should not be set to less than the openmode delay (see
5409 .It set timeout Ar idleseconds Op Ar mintimeout
5410 This command allows the setting of the idle timer.
5411 Refer to the section titled
5412 .Sx SETTING THE IDLE TIMER
5413 for further details.
5419 will never idle out before the link has been up for at least that number
5427 This command controls the ports that
5429 prioritizes when transmitting data.
5430 The default priority TCP ports
5431 are ports 21 (ftp control), 22 (ssh), 23 (telnet), 513 (login), 514 (shell),
5432 543 (klogin) and 544 (kshell).
5433 There are no priority UDP ports by default.
5448 are given, the priority port lists are cleared (although if
5452 is specified, only that list is cleared).
5455 argument is prefixed with a plus
5459 the current list is adjusted, otherwise the list is reassigned.
5461 prefixed with a plus or not prefixed at all are added to the list and
5463 prefixed with a minus are removed from the list.
5467 is specified, all priority port lists are disabled and even
5469 packets are not prioritised.
5470 .It set vj slotcomp on|off
5473 whether it should attempt to negotiate VJ slot compression.
5474 By default, slot compression is turned
5476 .It set vj slots Ar nslots
5477 This command sets the initial number of slots that
5479 will try to negotiate with the peer when VJ compression is enabled (see the
5482 It defaults to a value of 16.
5491 .It shell|! Op Ar command
5494 is not specified a shell is invoked according to the
5496 environment variable.
5497 Otherwise, the given
5500 Word replacement is done in the same way as for the
5502 command as described above.
5504 Use of the ! character
5505 requires a following space as with any of the other commands.
5506 You should note that this command is executed in the foreground;
5508 will not continue running until this process has exited.
5511 command if you wish processing to happen in the background.
5513 This command allows the user to examine the following:
5516 Show the current bundle settings.
5518 Show the current CCP compression statistics.
5520 Show the current VJ compression statistics.
5522 Show the current escape characters.
5523 .It show filter Op Ar name
5524 List the current rules for the given filter.
5527 is not specified, all filters are shown.
5529 Show the current HDLC statistics.
5531 Give a summary of available show commands.
5533 Show the current interface information
5534 .Pq the same \&as Dq iface show .
5536 Show the current IPCP statistics.
5538 Show the protocol layers currently in use.
5540 Show the current LCP statistics.
5541 .It show Op data Ns Xo
5544 Show high level link information.
5546 Show a list of available logical links.
5548 Show the current log values.
5550 Show current memory statistics.
5552 Show low level link information.
5554 Show Multi-link information.
5556 Show current protocol totals.
5558 Show the current routing tables.
5560 Show the current stopped timeouts.
5562 Show the active alarm timers.
5564 Show the current version number of
5569 Go into terminal mode.
5570 Characters typed at the keyboard are sent to the device.
5571 Characters read from the device are displayed on the screen.
5576 automatically enables Packet Mode and goes back into command mode.
5581 Read the example configuration files.
5582 They are a good source of information.
5591 to get online information about what's available.
5593 The following URLs contain useful information:
5594 .Bl -bullet -compact
5596 http://www.FreeBSD.org/FAQ/userppp.html
5598 http://www.FreeBSD.org/handbook/userppp.html
5604 refers to four files:
5610 These files are placed in the
5614 .It Pa /etc/ppp/ppp.conf
5615 System default configuration file.
5616 .It Pa /etc/ppp/ppp.secret
5617 An authorisation file for each system.
5618 .It Pa /etc/ppp/ppp.linkup
5619 A file to check when
5621 establishes a network level connection.
5622 .It Pa /etc/ppp/ppp.linkdown
5623 A file to check when
5625 closes a network level connection.
5626 .It Pa /var/log/ppp.log
5627 Logging and debugging information file.
5628 Note, this name is specified in
5629 .Pa /etc/syslogd.conf .
5632 for further details.
5633 .It Pa /var/spool/lock/LCK..*
5634 tty port locking file.
5637 for further details.
5638 .It Pa /var/run/tunN.pid
5639 The process id (pid) of the
5641 program connected to the tunN device, where
5643 is the number of the device.
5644 .It Pa /var/run/ttyXX.if
5645 The tun interface used by this port.
5646 Again, this file is only created in
5652 .It Pa /etc/services
5653 Get port number if port number is using service name.
5654 .It Pa /var/run/ppp-authname-class-value
5655 In multi-link mode, local domain sockets are created using the peer
5658 the peer endpoint discriminator class
5660 and the peer endpoint discriminator value
5662 As the endpoint discriminator value may be a binary value, it is turned
5663 to HEX to determine the actual file name.
5665 This socket is used to pass links between different instances of
5706 This program was originally written by
5707 .An Toshiharu OHNO Aq tony-o@iij.ad.jp ,
5708 and was submitted to
5711 .An Atsushi Murai Aq amurai@spec.co.jp .
5713 It was substantially modified during 1997 by
5714 .An Brian Somers Aq brian@Awfulhak.org ,
5717 in November that year
5718 (just after the 2.2 release).
5720 Most of the code was rewritten by
5722 in early 1998 when multi-link ppp support was added.
projects / FreeBSD / FreeBSD.git / blob