4 .\" Copyright (c) 2001 Brian Somers <brian@Awfulhak.org>
5 .\" All rights reserved.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35 .Nd Point to Point Protocol (a.k.a. user-ppp)
44 This is a user process
49 is implemented as a part of the kernel (e.g., as managed by
51 and it is thus somewhat hard to debug and/or modify its behaviour.
52 However, in this implementation
54 is done as a user process with the help of the
55 tunnel device driver (tun).
59 flag does the equivalent of a
63 network address translation features.
66 to act as a NAT or masquerading engine for all machines on an internal
68 ifdef({LOCALNAT},{},{Refer to
70 for details on the technical side of the NAT engine.
73 .Sx NETWORK ADDRESS TRANSLATION (PACKET ALIASING)
74 section of this manual page for details on how to configure NAT in
81 to be silent at startup rather than displaying the mode and interface
88 to only attempt to open
89 .Pa /dev/tun Ns Ar N .
92 will start with a value of 0 for
94 and keep trying to open a tunnel device by incrementing the value of
96 by one each time until it succeeds.
97 If it fails three times in a row
98 because the device file is missing, it gives up.
104 .Bl -tag -width XXX -offset XXX
107 opens the tun interface, configures it then goes into the background.
108 The link is not brought up until outgoing data is detected on the tun
109 interface at which point
111 attempts to bring up the link.
112 Packets received (including the first one) while
114 is trying to bring the link up will remain queued for a default of
124 must be given on the command line (see below) and a
126 must be done in the system profile that specifies a peer IP address to
127 use when configuring the interface.
130 is usually appropriate.
134 .Pa /usr/share/examples/ppp/ppp.conf.sample
139 attempts to establish a connection with the peer immediately.
142 goes into the background and the parent process returns an exit code
146 exits with a non-zero result.
150 attempts to establish a connection with the peer immediately, but never
152 The link is created in background mode.
153 This is useful if you wish to control
155 invocation from another process.
157 This is used for communicating over an already established connection,
158 usually when receiving incoming connections accepted by
163 line and uses descriptor 0 as the link.
165 will also ignore any configured chat scripts unless the
167 option has been enabled.
169 If callback is configured,
173 information when dialing back.
179 will behave slightly differently if descriptor 0 was created by
181 As pipes are not bi-directional, ppp will redirect all writes to descriptor
182 1 (standard output), leaving only reads acting on descriptor 0.
183 No special action is taken if descriptor 0 was created by
186 This option is designed for machines connected with a dedicated
189 will always keep the device open and will ignore any configured
190 chat scripts unless the
192 option has been enabled.
194 This mode is equivalent to
198 will bring the link back up any time it is dropped for any reason.
200 This is a no-op, and gives the same behaviour as if none of the above
201 modes have been specified.
203 loads any sections specified on the command line then provides an
207 One or more configuration entries or systems
209 .Pa /etc/ppp/ppp.conf )
210 may also be specified on the command line.
215 .Pa /etc/ppp/ppp.conf
216 at startup, followed by each of the systems specified on the command line.
219 .It Provides an interactive user interface.
220 Using its command mode, the user can
221 easily enter commands to establish the connection with the remote end, check
222 the status of connection and close the connection.
223 All functions can also be optionally password protected for security.
224 .It Supports both manual and automatic dialing.
225 Interactive mode has a
227 command which enables you to talk to the device directly.
228 When you are connected to the remote peer and it starts to talk
231 detects it and switches to packet mode automatically.
233 determined the proper sequence for connecting with the remote host, you
234 can write a chat script to {define} the necessary dialing and login
235 procedure for later convenience.
236 .It Supports on-demand dialup capability.
241 will act as a daemon and wait for a packet to be sent over the
244 When this happens, the daemon automatically dials and establishes the
246 In almost the same manner
248 mode (direct-dial mode) also automatically dials and establishes the
250 However, it differs in that it will dial the remote site
251 any time it detects the link is down, even if there are no packets to be
253 This mode is useful for full-time connections where we worry less
254 about line charges and more about being connected full time.
257 mode is also available.
258 This mode is targeted at a dedicated link between two machines.
260 will never voluntarily quit from dedicated mode - you must send it the
262 command via its diagnostic socket.
265 will force an LCP renegotiation, and a
267 will force it to exit.
268 .It Supports client callback.
270 can use either the standard LCP callback protocol or the Microsoft
271 CallBack Control Protocol (ftp://ftp.microsoft.com/developr/rfc/cbcp.txt).
272 .It Supports NAT or packet aliasing.
273 Packet aliasing (a.k.a.\& IP masquerading) allows computers on a
274 private, unregistered network to access the Internet.
277 host acts as a masquerading gateway.
278 IP addresses as well as TCP and
279 UDP port numbers are NAT'd for outgoing packets and de-NAT'd for
281 .It Supports background PPP connections.
282 In background mode, if
284 successfully establishes the connection, it will become a daemon.
285 Otherwise, it will exit with an error.
286 This allows the setup of
287 scripts that wish to execute certain commands only if the connection
288 is successfully established.
289 .It Supports server-side PPP connections.
292 acts as server which accepts incoming
294 connections on stdin/stdout.
295 .It "Supports PAP and CHAP (rfc 1994, 2433 and 2759) authentication.
296 With PAP or CHAP, it is possible to skip the Unix style
298 procedure, and use the
300 protocol for authentication instead.
301 If the peer requests Microsoft CHAP authentication and
303 is compiled with DES support, an appropriate MD4/DES response will be
305 .It Supports RADIUS (rfc 2138 & 2548) authentication.
306 An extension to PAP and CHAP,
313 allows authentication information to be stored in a central or
314 distributed database along with various per-user framed connection
316 ifdef({LOCALRAD},{},{If
318 is available at compile time,
322 requests when configured to do so.
324 .It Supports Proxy Arp.
326 can be configured to make one or more proxy arp entries on behalf of
328 This allows routing from the peer to the LAN without
329 configuring each machine on that LAN.
330 .It Supports packet filtering.
331 User can {define} four kinds of filters: the
333 filter for incoming packets, the
335 filter for outgoing packets, the
337 filter to {define} a dialing trigger packet and the
339 filter for keeping a connection alive with the trigger packet.
340 .It Tunnel driver supports bpf.
343 to check the packet flow over the
346 .It Supports PPP over TCP and PPP over UDP.
347 If a device name is specified as
348 .Em host Ns No : Ns Em port Ns
353 will open a TCP or UDP connection for transporting data rather than using a
354 conventional serial device.
355 UDP connections force
357 into synchronous mode.
358 .It Supports PPP over Ethernet (rfc 2516).
361 is given a device specification of the format
362 .No PPPoE: Ns Ar iface Ns Xo
363 .Op \&: Ns Ar provider Ns
377 On systems that do not support
379 an external program such as
382 .It "Supports IETF draft Predictor-1 (rfc 1978) and DEFLATE (rfc 1979) compression."
384 supports not only VJ-compression but also Predictor-1 and DEFLATE compression.
385 Normally, a modem has built-in compression (e.g., v42.bis) and the system
386 may receive higher data rates from it as a result of such compression.
387 While this is generally a good thing in most other situations, this
388 higher speed data imposes a penalty on the system by increasing the
389 number of serial interrupts the system has to process in talking to the
390 modem and also increases latency.
391 Unlike VJ-compression, Predictor-1 and DEFLATE compression pre-compresses
393 network traffic flowing through the link, thus reducing overheads to a
395 .It Supports Microsoft's IPCP extensions (rfc 1877).
396 Name Server Addresses and NetBIOS Name Server Addresses can be negotiated
397 with clients using the Microsoft
399 stack (i.e., Win95, WinNT)
400 .It Supports Multi-link PPP (rfc 1990)
401 It is possible to configure
403 to open more than one physical connection to the peer, combining the
404 bandwidth of all links for better throughput.
405 .It Supports MPPE (draft-ietf-pppext-mppe)
406 MPPE is Microsoft Point to Point Encryption scheme.
407 It is possible to configure
409 to participate in Microsoft's Windows VPN.
412 can only get encryption keys from CHAP 81 authentication.
414 must be compiled with DES for MPPE to operate.
415 .It Supports IPV6CP (rfc 2023).
416 An IPv6 connection can be made in addition to or instead of the normal
429 will not run if the invoking user id is not zero.
430 This may be overridden by using the
433 .Pa /etc/ppp/ppp.conf .
434 When running as a normal user,
436 switches to user id 0 in order to alter the system routing table, set up
437 system lock files and read the ppp configuration files.
438 All external commands (executed via the "shell" or "!bg" commands) are executed
439 as the user id that invoked
443 logging facility if you are interested in what exactly is done as user id
448 you may need to deal with some initial configuration details.
451 Make sure that your system has a group named
455 file and that the group contains the names of all users expected to use
459 manual page for details.
460 Each of these users must also be given access using the
463 .Pa /etc/ppp/ppp.conf .
470 A common log file name is
471 .Pa /var/log/ppp.log .
472 To make output go to this file, put the following lines in the
475 .Bd -literal -offset indent
477 *.*<TAB>/var/log/ppp.log
480 It is possible to have more than one
482 log file by creating a link to the
490 .Bd -literal -offset indent
492 *.*<TAB>/var/log/ppp0.log
496 .Pa /etc/syslog.conf .
497 Do not forget to send a
502 .Pa /etc/syslog.conf .
504 Although not strictly relevant to
506 operation, you should configure your resolver so that it works correctly.
507 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/cuad0
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 cannot 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 will 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 is 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
592 However, some ISPs (Internet Service Providers) may use
593 specific parity settings at connection time (before
596 Notably, Compuserve insist on even parity when logging in:
597 .Bd -literal -offset indent
598 ppp ON awfulhak> set parity even
601 You can now see what your current device settings look like:
602 .Bd -literal -offset indent
603 ppp ON awfulhak> show physical
607 Link Type: interactive
613 Device List: /dev/cuad0
614 Characteristics: 38400bps, cs8, even parity, CTS/RTS on
617 0 octets in, 0 octets out
622 The term command can now be used to talk directly to the device:
623 .Bd -literal -offset indent
624 ppp ON awfulhak> term
630 Password: myisppassword
634 When the peer starts to talk in
637 detects this automatically and returns to command mode.
638 .Bd -literal -offset indent
639 ppp ON awfulhak> # No link has been established
640 Ppp ON awfulhak> # We've connected & finished LCP
641 PPp ON awfulhak> # We've authenticated
642 PPP ON awfulhak> # We've agreed IP numbers
645 If it does not, it is probable that the peer is waiting for your end to
651 configuration packets to the peer, use the
653 command to drop out of terminal mode and enter packet mode.
655 If you never even receive a login prompt, it is quite likely that the
656 peer wants to use PAP or CHAP authentication instead of using Unix-style
657 login/password authentication.
658 To set things up properly, drop back to
659 the prompt and set your authentication name and key, then reconnect:
660 .Bd -literal -offset indent
662 ppp ON awfulhak> set authname myispusername
663 ppp ON awfulhak> set authkey myisppassword
664 ppp ON awfulhak> term
671 You may need to tell ppp to initiate negotiations with the peer here too:
672 .Bd -literal -offset indent
674 ppp ON awfulhak> # No link has been established
675 Ppp ON awfulhak> # We've connected & finished LCP
676 PPp ON awfulhak> # We've authenticated
677 PPP ON awfulhak> # We've agreed IP numbers
680 You are now connected!
683 in the prompt has changed to capital letters to indicate that you have
685 If only some of the three Ps go uppercase, wait until
686 either everything is uppercase or lowercase.
687 If they revert to lowercase, it means that
689 could not successfully negotiate with the peer.
690 A good first step for troubleshooting at this point would be to
691 .Bd -literal -offset indent
692 ppp ON awfulhak> set log local phase lcp ipcp
698 command description below for further details.
699 If things fail at this point,
700 it is quite important that you turn logging on and try again.
702 important that you note any prompt changes and report them to anyone trying
705 When the link is established, the show command can be used to see how
707 .Bd -literal -offset indent
708 PPP ON awfulhak> show physical
709 * Modem related information is shown here *
710 PPP ON awfulhak> show ccp
711 * CCP (compression) related information is shown here *
712 PPP ON awfulhak> show lcp
713 * LCP (line control) related information is shown here *
714 PPP ON awfulhak> show ipcp
715 * IPCP (IP) related information is shown here *
716 PPP ON awfulhak> show ipv6cp
717 * IPV6CP (IPv6) related information is shown here *
718 PPP ON awfulhak> show link
719 * Link (high level) related information is shown here *
720 PPP ON awfulhak> show bundle
721 * Logical (high level) connection related information is shown here *
724 At this point, your machine has a host route to the peer.
726 that you can only make a connection with the host on the other side
728 If you want to add a default route entry (telling your
729 machine to send all packets without another routing entry to the other
732 link), enter the following command:
733 .Bd -literal -offset indent
734 PPP ON awfulhak> add default HISADDR
739 represents the IP address of the connected peer.
742 command fails due to an existing route, you can overwrite the existing
744 .Bd -literal -offset indent
745 PPP ON awfulhak> add! default HISADDR
748 This command can also be executed before actually making the connection.
749 If a new IP address is negotiated at connection time,
751 will update your default route accordingly.
753 You can now use your network applications (ping, telnet, ftp, etc.)
754 in other windows or terminals on your machine.
755 If you wish to reuse the current terminal, you can put
757 into the background using your standard shell suspend and background
765 section for details on all available commands.
766 .Sh AUTOMATIC DIALING
767 To use automatic dialing, you must prepare some Dial and Login chat scripts.
768 See the example definitions in
769 .Pa /usr/share/examples/ppp/ppp.conf.sample
771 .Pa /etc/ppp/ppp.conf
773 Each line contains one comment, inclusion, label or command:
776 A line starting with a
778 character is treated as a comment line.
779 Leading whitespace are ignored when identifying comment lines.
781 An inclusion is a line beginning with the word
783 It must have one argument - the file to {include}.
785 .Dq {!include} ~/.ppp.conf
786 for compatibility with older versions of
789 A label name starts in the first column and is followed by
793 A command line must contain a space or tab in the first column.
795 A string starting with the
797 character is substituted with the value of the environment variable by
799 Likewise, a string starting with the
801 character is substituted with the full path to the home directory of
802 the user account by the same name, and the
804 character by itself is substituted with the full path to the home directory
806 If you want to include a literal
810 character in a command or argument, enclose them in double quotes, e.g.,
811 .Bd -literal -offset indent
812 set password "pa$ss~word"
817 .Pa /etc/ppp/ppp.conf
818 file should consist of at least a
821 This section is always executed.
822 It should also contain
823 one or more sections, named according to their purpose, for example,
825 would represent your ISP, and
827 would represent an incoming
830 You can now specify the destination label name when you invoke
832 Commands associated with the
834 label are executed, followed by those associated with the destination
838 is started with no arguments, the
840 section is still executed.
841 The load command can be used to manually load a section from the
842 .Pa /etc/ppp/ppp.conf
844 .Bd -literal -offset indent
845 ppp ON awfulhak> load MyISP
848 Note, no action is taken by
850 after a section is loaded, whether it is the result of passing a label on
851 the command line or using the
854 Only the commands specified for that label in the configuration
856 However, when invoking
863 switches, the link mode tells
865 to establish a connection.
868 command below for further details.
870 Once the connection is made, the
872 portion of the prompt will change to
874 .Bd -literal -offset indent
877 ppp ON awfulhak> dial
883 The Ppp prompt indicates that
885 has entered the authentication phase.
886 The PPp prompt indicates that
888 has entered the network phase.
889 The PPP prompt indicates that
891 has successfully negotiated a network layer protocol and is in
895 .Pa /etc/ppp/ppp.linkup
896 file is available, its contents are executed
899 connection is established.
903 .Pa /usr/share/examples/ppp/ppp.conf.sample
904 which runs a script in the background after the connection is established
909 commands below for a description of possible substitution strings).
910 Similarly, when a connection is closed, the contents of the
911 .Pa /etc/ppp/ppp.linkdown
913 Both of these files have the same format as
914 .Pa /etc/ppp/ppp.conf .
916 In previous versions of
918 it was necessary to re-add routes such as the default route in the
924 where all routes that contain the
930 literals will automatically be updated when the values of these variables
932 .Sh BACKGROUND DIALING
933 If you want to establish a connection using
935 non-interactively (such as from a
939 job) you should use the
946 attempts to establish the connection immediately.
948 numbers are specified, each phone number will be tried once.
949 If the attempt fails,
951 exits immediately with a non-zero exit code.
954 becomes a daemon, and returns an exit status of zero to its caller.
955 The daemon exits automatically if the connection is dropped by the
956 remote system, or it receives a
960 Demand dialing is enabled with the
965 You must also specify the destination label in
966 .Pa /etc/ppp/ppp.conf
970 command to {define} the remote peers IP address.
972 .Pa /usr/share/examples/ppp/ppp.conf.sample )
973 .Bd -literal -offset indent
983 runs as a daemon but you can still configure or examine its
984 configuration by using the
987 .Pa /etc/ppp/ppp.conf ,
989 .Dq Li "set server +3000 mypasswd" )
990 and connecting to the diagnostic port as follows:
991 .Bd -literal -offset indent
992 # pppctl 3000 (assuming tun0)
994 PPP ON awfulhak> show who
995 tcp (127.0.0.1:1028) *
1000 command lists users that are currently connected to
1003 If the diagnostic socket is closed or changed to a different
1004 socket, all connections are immediately dropped.
1008 mode, when an outgoing packet is detected,
1010 will perform the dialing action (chat script) and try to connect
1014 mode, the dialing action is performed any time the line is found
1016 If the connect fails, the default behaviour is to wait 30 seconds
1017 and then attempt to connect when another outgoing packet is detected.
1018 This behaviour can be changed using the
1022 .No set redial Ar secs Ns Xo
1025 .Oc Ns Op . Ns Ar next
1029 .Bl -tag -width attempts -compact
1031 is the number of seconds to wait before attempting
1033 If the argument is the literal string
1035 the delay period is a random value between 1 and 30 seconds inclusive.
1037 is the number of seconds that
1039 should be incremented each time a new dial attempt is made.
1040 The timeout reverts to
1042 only after a successful connection is established.
1043 The default value for
1047 is the maximum number of times
1051 The default value for
1055 is the number of seconds to wait before attempting
1056 to dial the next number in a list of numbers (see the
1059 The default is 3 seconds.
1060 Again, if the argument is the literal string
1062 the delay period is a random value between 1 and 30 seconds.
1064 is the maximum number of times to try to connect for each outgoing packet
1065 that triggers a dial.
1066 The previous value is unchanged if this parameter is omitted.
1067 If a value of zero is specified for
1070 will keep trying until a connection is made.
1074 .Bd -literal -offset indent
1078 will attempt to connect 4 times for each outgoing packet that causes
1079 a dial attempt with a 3 second delay between each number and a 10 second
1080 delay after all numbers have been tried.
1081 If multiple phone numbers
1082 are specified, the total number of attempts is still 4 (it does not
1083 attempt each number 4 times).
1087 .Bd -literal -offset indent
1088 set redial 10+10-5.3 20
1093 to attempt to connect 20 times.
1094 After the first attempt,
1096 pauses for 10 seconds.
1097 After the next attempt it pauses for 20 seconds
1098 and so on until after the sixth attempt it pauses for 1 minute.
1099 The next 14 pauses will also have a duration of one minute.
1102 connects, disconnects and fails to connect again, the timeout starts again
1105 Modifying the dial delay is very useful when running
1109 mode on both ends of the link.
1110 If each end has the same timeout,
1111 both ends wind up calling each other at the same time if the link
1112 drops and both ends have packets queued.
1113 At some locations, the serial link may not be reliable, and carrier
1114 may be lost at inappropriate times.
1115 It is possible to have
1117 redial should carrier be unexpectedly lost during a session.
1118 .Bd -literal -offset indent
1119 set reconnect timeout ntries
1124 to re-establish the connection
1126 times on loss of carrier with a pause of
1128 seconds before each try.
1130 .Bd -literal -offset indent
1136 that on an unexpected loss of carrier, it should wait
1138 seconds before attempting to reconnect.
1139 This may happen up to
1144 The default value of ntries is zero (no reconnect).
1145 Care should be taken with this option.
1146 If the local timeout is slightly
1147 longer than the remote timeout, the reconnect feature will always be
1148 triggered (up to the given number of times) after the remote side
1149 times out and hangs up.
1150 NOTE: In this context, losing too many LQRs constitutes a loss of
1151 carrier and will trigger a reconnect.
1154 flag is specified, all phone numbers are dialed at most once until
1155 a connection is made.
1156 The next number redial period specified with the
1158 command is honoured, as is the reconnect tries value.
1160 value is less than the number of phone numbers specified, not all
1161 the specified numbers will be tried.
1162 To terminate the program, type
1163 .Bd -literal -offset indent
1164 PPP ON awfulhak> close
1165 ppp ON awfulhak> quit all
1170 command will terminate the
1174 connection but not the
1182 .Sh RECEIVING INCOMING PPP CONNECTIONS (Method 1)
1183 To handle an incoming
1185 connection request, follow these steps:
1188 Make sure the modem and (optionally)
1190 is configured correctly.
1191 .Bl -bullet -compact
1193 Use Hardware Handshake (CTS/RTS) for flow control.
1195 Modem should be set to NO echo back (ATE0) and NO results string (ATQ1).
1203 on the port where the modem is attached.
1206 .Dl ttyd1 Qo /usr/libexec/getty std.38400 Qc dialup on secure
1208 Do not forget to send a
1212 process to start the
1217 It is usually also necessary to train your modem to the same DTR speed
1219 .Bd -literal -offset indent
1221 ppp ON awfulhak> set device /dev/cuad1
1222 ppp ON awfulhak> set speed 38400
1223 ppp ON awfulhak> term
1224 deflink: Entering terminal mode on /dev/cuad1
1235 ppp ON awfulhak> quit
1239 .Pa /usr/local/bin/ppplogin
1240 file with the following contents:
1241 .Bd -literal -offset indent
1243 exec /usr/sbin/ppp -direct incoming
1250 work with stdin and stdout.
1253 to connect to a configured diagnostic port, in the same manner as with
1259 section must be set up in
1260 .Pa /etc/ppp/ppp.conf .
1264 section contains the
1266 command as appropriate.
1268 Prepare an account for the incoming user.
1270 ppp:xxxx:66:66:PPP Login User:/home/ppp:/usr/local/bin/ppplogin
1273 Refer to the manual entries for
1279 Support for IPCP Domain Name Server and NetBIOS Name Server negotiation
1280 can be enabled using the
1285 Refer to their descriptions below.
1287 .Sh RECEIVING INCOMING PPP CONNECTIONS (Method 2)
1288 This method differs in that we use
1290 to authenticate the connection rather than
1294 Configure your default section in
1296 with automatic ppp recognition by specifying the
1301 :pp=/usr/local/bin/ppplogin:\\
1305 Configure your serial device(s), enable a
1308 .Pa /usr/local/bin/ppplogin
1309 as in the first three steps for method 1 above.
1317 .Pa /etc/ppp/ppp.conf
1320 label (or whatever label
1325 .Pa /etc/ppp/ppp.secret
1326 for each incoming user:
1335 detects a ppp connection (by recognising the HDLC frame headers), it runs
1336 .Dq /usr/local/bin/ppplogin .
1340 that either PAP or CHAP are enabled as above.
1341 If they are not, you are
1342 allowing anybody to establish a ppp session with your machine
1344 a password, opening yourself up to all sorts of potential attacks.
1345 .Sh AUTHENTICATING INCOMING CONNECTIONS
1346 Normally, the receiver of a connection requires that the peer
1347 authenticates itself.
1348 This may be done using
1350 but alternatively, you can use PAP or CHAP.
1351 CHAP is the more secure of the two, but some clients may not support it.
1352 Once you decide which you wish to use, add the command
1356 to the relevant section of
1359 You must then configure the
1360 .Pa /etc/ppp/ppp.secret
1362 This file contains one line per possible client, each line
1363 containing up to five fields:
1366 .Ar hisaddr Op Ar label Op Ar callback-number
1373 specify the client username and password.
1378 and PAP is being used,
1380 will look up the password database
1382 when authenticating.
1383 If the client does not offer a suitable response based on any
1384 .Ar name Ns No / Ns Ar key
1387 authentication fails.
1389 If authentication is successful,
1392 is used when negotiating IP numbers.
1395 command for details.
1397 If authentication is successful and
1399 is specified, the current system label is changed to match the given
1401 This will change the subsequent parsing of the
1407 If authentication is successful and
1413 the client will be called back on the given number.
1414 If CBCP is being used,
1416 may also contain a list of numbers or a
1421 The value will be used in
1423 subsequent CBCP phase.
1424 .Sh PPP OVER TCP and UDP (a.k.a Tunnelling)
1427 over a serial link, it is possible to
1428 use a TCP connection instead by specifying the host, port and protocol as the
1431 .Dl set device ui-gate:6669/tcp
1433 Instead of opening a serial device,
1435 will open a TCP connection to the given machine on the given
1437 It should be noted however that
1439 does not use the telnet protocol and will be unable to negotiate
1440 with a telnet server.
1441 You should set up a port for receiving this
1443 connection on the receiving machine (ui-gate).
1444 This is done by first updating
1446 to name the service:
1448 .Dl ppp-in 6669/tcp # Incoming PPP connections over TCP
1454 how to deal with incoming connections on that port:
1456 .Dl ppp-in stream tcp nowait root /usr/sbin/ppp ppp -direct ppp-in
1458 Do not forget to send a
1462 after you have updated
1463 .Pa /etc/inetd.conf .
1464 Here, we use a label named
1467 .Pa /etc/ppp/ppp.conf
1468 on ui-gate (the receiver) should contain the following:
1469 .Bd -literal -offset indent
1472 set ifaddr 10.0.4.1 10.0.4.2
1476 .Pa /etc/ppp/ppp.linkup
1478 .Bd -literal -offset indent
1480 add 10.0.1.0/24 HISADDR
1483 It is necessary to put the
1487 to ensure that the route is only added after
1489 has negotiated and assigned addresses to its interface.
1491 You may also want to enable PAP or CHAP for security.
1492 To enable PAP, add the following line:
1493 .Bd -literal -offset indent
1497 You will also need to create the following entry in
1498 .Pa /etc/ppp/ppp.secret :
1499 .Bd -literal -offset indent
1500 MyAuthName MyAuthPasswd
1507 the password is looked up in the
1512 .Pa /etc/ppp/ppp.conf
1513 on awfulhak (the initiator) should contain the following:
1514 .Bd -literal -offset indent
1517 set device ui-gate:ppp-in/tcp
1520 set log Phase Chat Connect hdlc LCP IPCP IPV6CP CCP tun
1521 set ifaddr 10.0.4.2 10.0.4.1
1524 with the route setup in
1525 .Pa /etc/ppp/ppp.linkup :
1526 .Bd -literal -offset indent
1528 add 10.0.2.0/24 HISADDR
1531 Again, if you are enabling PAP, you will also need this in the
1532 .Pa /etc/ppp/ppp.conf
1534 .Bd -literal -offset indent
1535 set authname MyAuthName
1536 set authkey MyAuthKey
1539 We are assigning the address of 10.0.4.1 to ui-gate, and the address
1540 10.0.4.2 to awfulhak.
1541 To open the connection, just type
1543 .Dl awfulhak # ppp -background ui-gate
1545 The result will be an additional "route" on awfulhak to the
1546 10.0.2.0/24 network via the TCP connection, and an additional
1547 "route" on ui-gate to the 10.0.1.0/24 network.
1548 The networks are effectively bridged - the underlying TCP
1549 connection may be across a public network (such as the
1552 traffic is conceptually encapsulated
1553 (although not packet by packet) inside the TCP stream between
1556 The major disadvantage of this mechanism is that there are two
1557 "guaranteed delivery" mechanisms in place - the underlying TCP
1558 stream and whatever protocol is used over the
1560 link - probably TCP again.
1561 If packets are lost, both levels will
1562 get in each others way trying to negotiate sending of the missing
1565 To avoid this overhead, it is also possible to do all this using
1566 UDP instead of TCP as the transport by simply changing the protocol
1567 from "tcp" to "udp".
1568 When using UDP as a transport,
1570 will operate in synchronous mode.
1571 This is another gain as the incoming
1572 data does not have to be rearranged into packets.
1574 Care should be taken when adding a default route through a tunneled
1576 It is quite common for the default route
1578 .Pa /etc/ppp/ppp.linkup )
1579 to end up routing the link's TCP connection through the tunnel,
1580 effectively garrotting the connection.
1581 To avoid this, make sure you add a static route for the benefit of
1583 .Bd -literal -offset indent
1586 set device ui-gate:ppp-in/tcp
1593 is the IP number that your route to
1597 When routing your connection accross a public network such as the Internet,
1598 it is preferable to encrypt the data.
1599 This can be done with the help of the MPPE protocol, although currently this
1600 means that you will not be able to also compress the traffic as MPPE is
1601 implemented as a compression layer (thank Microsoft for this).
1602 To enable MPPE encryption, add the following lines to
1603 .Pa /etc/ppp/ppp.conf
1605 .Bd -literal -offset indent
1607 disable deflate pred1
1611 ensuring that you have put the requisite entry in
1612 .Pa /etc/ppp/ppp.secret
1613 (MSCHAPv2 is challenge based, so
1617 MSCHAPv2 and MPPE are accepted by default, so the client end should work
1618 without any additional changes (although ensure you have
1623 .Sh NETWORK ADDRESS TRANSLATION (PACKET ALIASING)
1626 command line option enables network address translation (a.k.a.\& packet
1630 host to act as a masquerading gateway for other computers over
1631 a local area network.
1632 Outgoing IP packets are NAT'd so that they appear to come from the
1634 host, and incoming packets are de-NAT'd so that they are routed
1635 to the correct machine on the local area network.
1636 NAT allows computers on private, unregistered subnets to have Internet
1637 access, although they are invisible from the outside world.
1640 operation should first be verified with network address translation disabled.
1643 option should be switched on, and network applications (web browser,
1648 should be checked on the
1651 Finally, the same or similar applications should be checked on other
1652 computers in the LAN.
1653 If network applications work correctly on the
1655 host, but not on other machines in the LAN, then the masquerading
1656 software is working properly, but the host is either not forwarding
1657 or possibly receiving IP packets.
1658 Check that IP forwarding is enabled in
1660 and that other machines have designated the
1662 host as the gateway for the LAN.
1663 .Sh PACKET FILTERING
1664 This implementation supports packet filtering.
1665 There are four kinds of
1675 Here are the basics:
1678 A filter definition has the following syntax:
1687 .Ar src_addr Ns Op / Ns Ar width
1688 .Op Ar dst_addr Ns Op / Ns Ar width
1690 .Ar [ proto Op src Ar cmp port
1695 .Op timeout Ar secs ]
1707 is a numeric value between
1711 specifying the rule number.
1712 Rules are specified in numeric order according to
1723 in which case, if a given packet matches the rule, the associated action
1724 is taken immediately.
1726 can also be specified as
1728 to clear the action associated with that particular rule, or as a new
1729 rule number greater than the current rule.
1730 In this case, if a given
1731 packet matches the current rule, the packet will next be matched against
1732 the new rule number (rather than the next rule number).
1736 may optionally be followed with an exclamation mark
1740 to reverse the sense of the following match.
1742 .Op Ar src_addr Ns Op / Ns Ar width
1744 .Op Ar dst_addr Ns Op / Ns Ar width
1745 are the source and destination IP number specifications.
1748 is specified, it gives the number of relevant netmask bits,
1749 allowing the specification of an address range.
1755 may be given the values
1761 (refer to the description of the
1763 command for a description of these values).
1764 When these values are used,
1765 the filters will be updated any time the values change.
1766 This is similar to the behaviour of the
1771 may be any protocol from
1780 meaning less-than, equal and greater-than respectively.
1782 can be specified as a numeric port or by service name from
1790 flags are only allowed when
1794 and represent the TH_ACK, TH_SYN and TH_FIN or TH_RST TCP flags respectively.
1796 The timeout value adjusts the current idle timeout to at least
1799 If a timeout is given in the alive filter as well as in the in/out
1800 filter, the in/out value is used.
1801 If no timeout is given, the default timeout (set using
1803 and defaulting to 180 seconds) is used.
1807 Each filter can hold up to 40 rules, starting from rule 0.
1808 The entire rule set is not effective until rule 0 is defined,
1809 i.e., the default is to allow everything through.
1811 If no rule in a defined set of rules matches a packet, that packet will
1812 be discarded (blocked).
1813 If there are no rules in a given filter, the packet will be permitted.
1815 It is possible to filter based on the payload of UDP frames where those
1821 .Ar filter-decapsulation
1822 option below for further details.
1825 .Dq set filter Ar name No -1
1830 .Pa /usr/share/examples/ppp/ppp.conf.sample .
1831 .Sh SETTING THE IDLE TIMER
1832 To check/set the idle timer, use the
1837 .Bd -literal -offset indent
1838 ppp ON awfulhak> set timeout 600
1841 The timeout period is measured in seconds, the default value for which
1844 To disable the idle timer function, use the command
1845 .Bd -literal -offset indent
1846 ppp ON awfulhak> set timeout 0
1853 modes, the idle timeout is ignored.
1856 mode, when the idle timeout causes the
1861 program itself remains running.
1862 Another trigger packet will cause it to attempt to re-establish the link.
1863 .Sh PREDICTOR-1 and DEFLATE COMPRESSION
1865 supports both Predictor type 1 and deflate compression.
1868 will attempt to use (or be willing to accept) both compression protocols
1869 when the peer agrees
1871 The deflate protocol is preferred by
1877 commands if you wish to disable this functionality.
1879 It is possible to use a different compression algorithm in each direction
1880 by using only one of
1884 (assuming that the peer supports both algorithms).
1886 By default, when negotiating DEFLATE,
1888 will use a window size of 15.
1891 command if you wish to change this behaviour.
1893 A special algorithm called DEFLATE24 is also available, and is disabled
1894 and denied by default.
1895 This is exactly the same as DEFLATE except that
1896 it uses CCP ID 24 to negotiate.
1899 to successfully negotiate DEFLATE with
1902 .Sh CONTROLLING IP ADDRESS
1905 uses IPCP to negotiate IP addresses.
1906 Each side of the connection
1907 specifies the IP address that it is willing to use, and if the requested
1908 IP address is acceptable then
1910 returns an ACK to the requester.
1913 returns NAK to suggest that the peer use a different IP address.
1915 both sides of the connection agree to accept the received request (and
1916 send an ACK), IPCP is set to the open state and a network level connection
1918 To control this IPCP behaviour, this implementation has the
1920 command for defining the local and remote IP address:
1921 .Bd -ragged -offset indent
1922 .No set ifaddr Oo Ar src_addr Ns
1924 .Oo Ar dst_addr Ns Op / Ns Ar \&nn
1934 is the IP address that the local side is willing to use,
1936 is the IP address which the remote side should use and
1938 is the netmask that should be used.
1940 defaults to the current
1943 defaults to 0.0.0.0, and
1945 defaults to whatever mask is appropriate for
1947 It is only possible to make
1949 smaller than the default.
1950 The usual value is 255.255.255.255, as
1951 most kernels ignore the netmask of a POINTOPOINT interface.
1955 implementations require that the peer negotiates a specific IP
1958 If this is the case,
1960 may be used to specify this IP number.
1961 This will not affect the
1962 routing table unless the other side agrees with this proposed number.
1963 .Bd -literal -offset indent
1964 set ifaddr 192.244.177.38 192.244.177.2 255.255.255.255 0.0.0.0
1967 The above specification means:
1969 .Bl -bullet -compact
1971 I will first suggest that my IP address should be 0.0.0.0, but I
1972 will only accept an address of 192.244.177.38.
1974 I strongly insist that the peer uses 192.244.177.2 as his own
1975 address and will not permit the use of any IP address but 192.244.177.2.
1976 When the peer requests another IP address, I will always suggest that
1977 it uses 192.244.177.2.
1979 The routing table entry will have a netmask of 0xffffffff.
1982 This is all fine when each side has a pre-determined IP address, however
1983 it is often the case that one side is acting as a server which controls
1984 all IP addresses and the other side should go along with it.
1985 In order to allow more flexible behaviour, the
1987 command allows the user to specify IP addresses more loosely:
1989 .Dl set ifaddr 192.244.177.38/24 192.244.177.2/20
1991 A number followed by a slash
1993 represents the number of bits significant in the IP address.
1994 The above example means:
1996 .Bl -bullet -compact
1998 I would like to use 192.244.177.38 as my address if it is possible, but I will
1999 also accept any IP address between 192.244.177.0 and 192.244.177.255.
2001 I would like to make him use 192.244.177.2 as his own address, but I will also
2002 permit him to use any IP address between 192.244.176.0 and
2005 As you may have already noticed, 192.244.177.2 is equivalent to saying
2008 As an exception, 0 is equivalent to 0.0.0.0/0, meaning that I have no
2009 preferred IP address and will obey the remote peers selection.
2010 When using zero, no routing table entries will be made until a connection
2013 192.244.177.2/0 means that I will accept/permit any IP address but I will
2014 suggest that 192.244.177.2 be used first.
2017 When negotiating IPv6 addresses, no control is given to the user.
2018 IPV6CP negotiation is fully automatic.
2019 .Sh CONNECTING WITH YOUR INTERNET SERVICE PROVIDER
2020 The following steps should be taken when connecting to your ISP:
2023 Describe your providers phone number(s) in the dial script using the
2026 This command allows you to set multiple phone numbers for
2027 dialing and redialing separated by either a pipe
2031 .Bd -ragged -offset indent
2032 .No set phone Ar telno Ns Xo
2033 .Oo \&| Ns Ar backupnumber
2034 .Oc Ns ... Ns Oo : Ns Ar nextnumber
2039 Numbers after the first in a pipe-separated list are only used if the
2040 previous number was used in a failed dial or login script.
2042 separated by a colon are used sequentially, irrespective of what happened
2043 as a result of using the previous number.
2045 .Bd -literal -offset indent
2046 set phone "1234567|2345678:3456789|4567890"
2049 Here, the 1234567 number is attempted.
2050 If the dial or login script fails,
2051 the 2345678 number is used next time, but *only* if the dial or login script
2053 On the dial after this, the 3456789 number is used.
2055 number is only used if the dial or login script using the 3456789 fails.
2056 If the login script of the 2345678 number fails, the next number is still the
2058 As many pipes and colons can be used as are necessary
2059 (although a given site would usually prefer to use either the pipe or the
2060 colon, but not both).
2061 The next number redial timeout is used between all numbers.
2062 When the end of the list is reached, the normal redial period is
2063 used before starting at the beginning again.
2064 The selected phone number is substituted for the \\\\T string in the
2066 command (see below).
2068 Set up your redial requirements using
2070 For example, if you have a bad telephone line or your provider is
2071 usually engaged (not so common these days), you may want to specify
2073 .Bd -literal -offset indent
2077 This says that up to 4 phone calls should be attempted with a pause of 10
2078 seconds before dialing the first number again.
2080 Describe your login procedure using the
2087 command is used to talk to your modem and establish a link with your
2089 .Bd -literal -offset indent
2090 set dial "ABORT BUSY ABORT NO\\\\sCARRIER TIMEOUT 4 \\"\\" \e
2091 ATZ OK-ATZ-OK ATDT\\\\T TIMEOUT 60 CONNECT"
2094 This modem "chat" string means:
2097 Abort if the string "BUSY" or "NO CARRIER" are received.
2099 Set the timeout to 4 seconds.
2106 If that is not received within the 4 second timeout, send ATZ
2109 Send ATDTxxxxxxx where xxxxxxx is the next number in the phone list from
2112 Set the timeout to 60.
2114 Wait for the CONNECT string.
2117 Once the connection is established, the login script is executed.
2118 This script is written in the same style as the dial script, but care should
2119 be taken to avoid having your password logged:
2120 .Bd -literal -offset indent
2121 set authkey MySecret
2122 set login "TIMEOUT 15 login:-\\\\r-login: awfulhak \e
2123 word: \\\\P ocol: PPP HELLO"
2126 This login "chat" string means:
2129 Set the timeout to 15 seconds.
2132 If it is not received, send a carriage return and expect
2137 Expect "word:" (the tail end of a "Password:" prompt).
2139 Send whatever our current
2143 Expect "ocol:" (the tail end of a "Protocol:" prompt).
2152 command is logged specially.
2157 logging is enabled, the actual password is not logged;
2161 Login scripts vary greatly between ISPs.
2162 If you are setting one up for the first time,
2163 .Em ENABLE CHAT LOGGING
2164 so that you can see if your script is behaving as you expect.
2170 to specify your serial line and speed, for example:
2171 .Bd -literal -offset indent
2172 set device /dev/cuad0
2176 Cuad0 is the first serial port on
2183 A speed of 115200 should be specified
2184 if you have a modem capable of bit rates of 28800 or more.
2185 In general, the serial speed should be about four times the modem speed.
2189 command to {define} the IP address.
2192 If you know what IP address your provider uses, then use it as the remote
2193 address (dst_addr), otherwise choose something like 10.0.0.2/0 (see below).
2195 If your provider has assigned a particular IP address to you, then use
2196 it as your address (src_addr).
2198 If your provider assigns your address dynamically, choose a suitably
2199 unobtrusive and unspecific IP number as your address.
2200 10.0.0.1/0 would be appropriate.
2201 The bit after the / specifies how many bits of the
2202 address you consider to be important, so if you wanted to insist on
2203 something in the class C network 1.2.3.0, you could specify 1.2.3.1/24.
2205 If you find that your ISP accepts the first IP number that you suggest,
2206 specify third and forth arguments of
2208 This will force your ISP to assign a number.
2209 (The third argument will
2210 be ignored as it is less restrictive than the default mask for your
2214 An example for a connection where you do not know your IP number or your
2215 ISPs IP number would be:
2216 .Bd -literal -offset indent
2217 set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0
2221 In most cases, your ISP will also be your default router.
2222 If this is the case, add the line
2223 .Bd -literal -offset indent
2228 .Pa /etc/ppp/ppp.conf
2230 .Pa /etc/ppp/ppp.linkup
2231 for setups that do not use
2237 to add a default route to whatever the peer address is
2238 (10.0.0.2 in this example).
2241 meaning that should the value of
2243 change, the route will be updated accordingly.
2245 If your provider requests that you use PAP/CHAP authentication methods, add
2246 the next lines to your
2247 .Pa /etc/ppp/ppp.conf
2249 .Bd -literal -offset indent
2251 set authkey MyPassword
2254 Both are accepted by default, so
2256 will provide whatever your ISP requires.
2258 It should be noted that a login script is rarely (if ever) required
2259 when PAP or CHAP are in use.
2261 Ask your ISP to authenticate your nameserver address(es) with the line
2262 .Bd -literal -offset indent
2268 do this if you are running a local DNS unless you also either use
2273 .Pa /etc/ppp/ppp.linkdown ,
2276 will simply circumvent its use by entering some nameserver lines in
2277 .Pa /etc/resolv.conf .
2281 .Pa /usr/share/examples/ppp/ppp.conf.sample
2283 .Pa /usr/share/examples/ppp/ppp.linkup.sample
2284 for some real examples.
2285 The pmdemand label should be appropriate for most ISPs.
2286 .Sh LOGGING FACILITY
2288 is able to generate the following log info either via
2290 or directly to the screen:
2292 .Bl -tag -width XXXXXXXXX -offset XXX -compact
2294 Enable all logging facilities.
2295 This generates a lot of log.
2296 The most common use of 'all' is as a basis, where you remove some facilities
2297 after enabling 'all' ('debug' and 'timer' are usually best disabled.)
2299 Dump async level packet in hex.
2301 Generate CBCP (CallBack Control Protocol) logs.
2303 Generate a CCP packet trace.
2311 chat script trace logs.
2313 Log commands executed either from the command line or any of the configuration
2316 Log Chat lines containing the string "CONNECT".
2318 Log debug information.
2320 Log DNS QUERY packets.
2322 Log packets permitted by the dial filter and denied by any filter.
2324 Dump HDLC packet in hex.
2326 Log all function calls specifically made as user id 0.
2328 Generate an IPCP packet trace.
2330 Generate an LCP packet trace.
2332 Generate LQR reports.
2334 Phase transition log output.
2336 Dump physical level packet in hex.
2338 Dump RADIUS information.
2339 RADIUS information resulting from the link coming up or down is logged at
2344 This log level is most useful for monitoring RADIUS alive information.
2346 Dump sync level packet in hex.
2348 Dump all TCP/IP packets.
2350 Log timer manipulation.
2352 Include the tun device on each log line.
2354 Output to the terminal device.
2355 If there is currently no terminal,
2356 output is sent to the log file using syslogs
2359 Output to both the terminal device
2360 and the log file using syslogs
2363 Output to the log file using
2369 command allows you to set the logging output level.
2370 Multiple levels can be specified on a single command line.
2371 The default is equivalent to
2374 It is also possible to log directly to the screen.
2375 The syntax is the same except that the word
2377 should immediately follow
2381 (i.e., only the un-maskable warning, error and alert output).
2383 If The first argument to
2384 .Dq set log Op local
2389 character, the current log levels are
2390 not cleared, for example:
2391 .Bd -literal -offset indent
2392 PPP ON awfulhak> set log phase
2393 PPP ON awfulhak> show log
2394 Log: Phase Warning Error Alert
2395 Local: Warning Error Alert
2396 PPP ON awfulhak> set log +tcp/ip -warning
2397 PPP ON awfulhak> set log local +command
2398 PPP ON awfulhak> show log
2399 Log: Phase TCP/IP Warning Error Alert
2400 Local: Command Warning Error Alert
2403 Log messages of level Warning, Error and Alert are not controllable
2405 .Dq set log Op local .
2409 level is special in that it will not be logged if it can be displayed
2413 deals with the following signals:
2414 .Bl -tag -width "USR2"
2416 Receipt of this signal causes the termination of the current connection
2420 to exit unless it is in
2425 .It HUP, TERM & QUIT
2432 to re-open any existing server socket, dropping all existing diagnostic
2434 Sockets that could not previously be opened will be retried.
2438 to close any existing server socket, dropping all existing diagnostic
2441 can still be used to re-open the socket.
2444 If you wish to use more than one physical link to connect to a
2446 peer, that peer must also understand the
2449 Refer to RFC 1990 for specification details.
2451 The peer is identified using a combination of his
2452 .Dq endpoint discriminator
2454 .Dq authentication id .
2455 Either or both of these may be specified.
2456 It is recommended that
2457 at least one is specified, otherwise there is no way of ensuring that
2458 all links are actually connected to the same peer program, and some
2459 confusing lock-ups may result.
2460 Locally, these identification variables are specified using the
2469 must be agreed in advance with the peer.
2471 Multi-link capabilities are enabled using the
2473 command (set maximum reconstructed receive unit).
2474 Once multi-link is enabled,
2476 will attempt to negotiate a multi-link connection with the peer.
2478 By default, only one
2483 To create more links, the
2486 This command will clone existing links, where all
2487 characteristics are the same except:
2490 The new link has its own name as specified on the
2497 Its mode may subsequently be changed using the
2501 The new link is in a
2506 A summary of all available links can be seen using the
2510 Once a new link has been created, command usage varies.
2511 All link specific commands must be prefixed with the
2513 command, specifying on which link the command is to be applied.
2514 When only a single link is available,
2516 is smart enough not to require the
2520 Some commands can still be used without specifying a link - resulting
2521 in an operation at the
2524 For example, once two or more links are available, the command
2526 will show CCP configuration and statistics at the multi-link level, and
2527 .Dq link deflink show ccp
2528 will show the same information at the
2532 Armed with this information, the following configuration might be used:
2534 .Bd -literal -offset indent
2538 set device /dev/cuad0 /dev/cuad1 /dev/cuad2
2539 set phone "123456789"
2540 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \\"\\" ATZ \e
2541 OK-AT-OK \\\\dATDT\\\\T TIMEOUT 45 CONNECT"
2543 set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0
2545 set authkey ppppassword
2548 clone 1,2,3 # Create 3 new links - duplicates of the default
2549 link deflink remove # Delete the default link (called ``deflink'')
2552 Note how all cloning is done at the end of the configuration.
2553 Usually, the link will be configured first, then cloned.
2554 If you wish all links
2555 to be up all the time, you can add the following line to the end of your
2558 .Bd -literal -offset indent
2559 link 1,2,3 set mode ddial
2562 If you want the links to dial on demand, this command could be used:
2564 .Bd -literal -offset indent
2565 link * set mode auto
2568 Links may be tied to specific names by removing the
2570 line above, and specifying the following after the
2574 .Bd -literal -offset indent
2575 link 1 set device /dev/cuad0
2576 link 2 set device /dev/cuad1
2577 link 3 set device /dev/cuad2
2582 command to see which commands require context (using the
2584 command), which have optional
2585 context and which should not have any context.
2591 mode with the peer, it creates a local domain socket in the
2594 This socket is used to pass link information (including
2595 the actual link file descriptor) between different
2600 ability to be run from a
2606 capability), without needing to have initial control of the serial
2610 negotiates multi-link mode, it will pass its open link to any
2611 already running process.
2612 If there is no already running process,
2614 will act as the master, creating the socket and listening for new
2616 .Sh PPP COMMAND LIST
2617 This section lists the available commands and their effect.
2618 They are usable either from an interactive
2620 session, from a configuration file or from a
2626 .It accept|deny|enable|disable Ar option....
2627 These directives tell
2629 how to negotiate the initial connection with the peer.
2632 has a default of either accept or deny and enable or disable.
2634 means that the option will be ACK'd if the peer asks for it.
2636 means that the option will be NAK'd if the peer asks for it.
2638 means that the option will be requested by us.
2640 means that the option will not be requested by us.
2643 may be one of the following:
2646 Default: Enabled and Accepted.
2647 ACFComp stands for Address and Control Field Compression.
2648 Non LCP packets will usually have an address
2649 field of 0xff (the All-Stations address) and a control field of
2650 0x03 (the Unnumbered Information command).
2652 negotiated, these two bytes are simply not sent, thus minimising
2659 Default: Disabled and Accepted.
2660 CHAP stands for Challenge Handshake Authentication Protocol.
2661 Only one of CHAP and PAP (below) may be negotiated.
2662 With CHAP, the authenticator sends a "challenge" message to its peer.
2663 The peer uses a one-way hash function to encrypt the
2664 challenge and sends the result back.
2665 The authenticator does the same, and compares the results.
2666 The advantage of this mechanism is that no
2667 passwords are sent across the connection.
2668 A challenge is made when the connection is first made.
2669 Subsequent challenges may occur.
2670 If you want to have your peer authenticate itself, you must
2673 .Pa /etc/ppp/ppp.conf ,
2674 and have an entry in
2675 .Pa /etc/ppp/ppp.secret
2678 When using CHAP as the client, you need only specify
2683 .Pa /etc/ppp/ppp.conf .
2684 CHAP is accepted by default.
2687 implementations use "MS-CHAP" rather than MD5 when encrypting the
2689 MS-CHAP is a combination of MD4 and DES.
2692 was built on a machine with DES libraries available, it will respond
2693 to MS-CHAP authentication requests, but will never request them.
2695 Default: Enabled and Accepted.
2696 This option decides if deflate
2697 compression will be used by the Compression Control Protocol (CCP).
2698 This is the same algorithm as used by the
2701 Note: There is a problem negotiating
2707 implementation available under many operating systems.
2709 (version 2.3.1) incorrectly attempts to negotiate
2711 compression using type
2713 as the CCP configuration type rather than type
2719 is actually specified as
2720 .Dq PPP Magna-link Variable Resource Compression
2724 is capable of negotiating with
2731 .Ar accept Ns No ed .
2733 Default: Disabled and Denied.
2734 This is a variance of the
2736 option, allowing negotiation with the
2741 section above for details.
2742 It is disabled by default as it violates
2745 Default: Disabled and Denied.
2746 This option allows DNS negotiation.
2751 will request that the peer confirms the entries in
2752 .Pa /etc/resolv.conf .
2753 If the peer NAKs our request (suggesting new IP numbers),
2754 .Pa /etc/resolv.conf
2755 is updated and another request is sent to confirm the new entries.
2758 .Dq accept Ns No ed,
2760 will answer any DNS queries requested by the peer rather than rejecting
2762 The answer is taken from
2763 .Pa /etc/resolv.conf
2766 command is used as an override.
2768 Default: Enabled and Accepted.
2769 This option allows control over whether we
2770 negotiate an endpoint discriminator.
2771 We only send our discriminator if
2776 We reject the peers discriminator if
2780 Default: Disabled and Accepted.
2781 The use of this authentication protocol
2782 is discouraged as it partially violates the authentication protocol by
2783 implementing two different mechanisms (LANMan & NT) under the guise of
2784 a single CHAP type (0x80).
2786 uses a simple DES encryption mechanism and is the least secure of the
2787 CHAP alternatives (although is still more secure than PAP).
2791 description below for more details.
2793 Default: Disabled and Accepted.
2794 This option decides if Link Quality Requests will be sent or accepted.
2795 LQR is a protocol that allows
2797 to determine that the link is down without relying on the modems
2799 When LQR is enabled,
2805 below) as part of the LCP request.
2806 If the peer agrees, both sides will
2807 exchange LQR packets at the agreed frequency, allowing detailed link
2808 quality monitoring by enabling LQM logging.
2809 If the peer does not agree, and if the
2816 These packets pass no information of interest, but they
2818 be replied to by the peer.
2825 will abruptly drop the connection if 5 unacknowledged packets have been
2826 sent rather than sending a 6th.
2827 A message is logged at the
2829 level, and any appropriate
2831 values are honoured as if the peer were responsible for dropping the
2836 command description for differences in behaviour prior to
2840 Default: Enabled and Accepted.
2841 This is Microsoft Point to Point Encryption scheme.
2842 MPPE key size can be
2843 40-, 56- and 128-bits.
2848 Default: Disabled and Accepted.
2849 It is very similar to standard CHAP (type 0x05)
2850 except that it issues challenges of a fixed 16 bytes in length and uses a
2851 combination of MD4, SHA-1 and DES to encrypt the challenge rather than using the
2852 standard MD5 mechanism.
2854 Default: Disabled and Accepted.
2855 The use of this authentication protocol
2856 is discouraged as it partially violates the authentication protocol by
2857 implementing two different mechanisms (LANMan & NT) under the guise of
2858 a single CHAP type (0x80).
2859 It is very similar to standard CHAP (type 0x05)
2860 except that it issues challenges of a fixed 8 bytes in length and uses a
2861 combination of MD4 and DES to encrypt the challenge rather than using the
2862 standard MD5 mechanism.
2863 CHAP type 0x80 for LANMan is also supported - see
2871 use CHAP type 0x80, when acting as authenticator with both
2872 .Dq enable Ns No d ,
2874 will rechallenge the peer up to three times if it responds using the wrong
2875 one of the two protocols.
2876 This gives the peer a chance to attempt using both protocols.
2880 acts as the authenticatee with both protocols
2881 .Dq accept Ns No ed ,
2882 the protocols are used alternately in response to challenges.
2884 Note: If only LANMan is enabled,
2886 (version 2.3.5) misbehaves when acting as authenticatee.
2888 the NT and the LANMan answers, but also suggests that only the NT answer
2891 Default: Disabled and Accepted.
2892 PAP stands for Password Authentication Protocol.
2893 Only one of PAP and CHAP (above) may be negotiated.
2894 With PAP, the ID and Password are sent repeatedly to the peer until
2895 authentication is acknowledged or the connection is terminated.
2896 This is a rather poor security mechanism.
2897 It is only performed when the connection is first established.
2898 If you want to have your peer authenticate itself, you must
2901 .Pa /etc/ppp/ppp.conf ,
2902 and have an entry in
2903 .Pa /etc/ppp/ppp.secret
2904 for the peer (although see the
2910 When using PAP as the client, you need only specify
2915 .Pa /etc/ppp/ppp.conf .
2916 PAP is accepted by default.
2918 Default: Enabled and Accepted.
2919 This option decides if Predictor 1
2920 compression will be used by the Compression Control Protocol (CCP).
2922 Default: Enabled and Accepted.
2923 This option is used to negotiate
2924 PFC (Protocol Field Compression), a mechanism where the protocol
2925 field number is reduced to one octet rather than two.
2927 Default: Enabled and Accepted.
2928 This option determines if
2930 will request and accept requests for short
2932 sequence numbers when negotiating multi-link mode.
2933 This is only applicable if our MRRU is set (thus enabling multi-link).
2935 Default: Enabled and Accepted.
2936 This option determines if Van Jacobson header compression will be used.
2939 The following options are not actually negotiated with the peer.
2940 Therefore, accepting or denying them makes no sense.
2944 When this option is enabled,
2948 requests to the peer at the frequency defined by
2952 requests will supersede
2954 requests if enabled and negotiated.
2963 was considered enabled if lqr was enabled and negotiated, otherwise it was
2964 considered disabled.
2965 For the same behaviour, it is now necessary to
2969 .It filter-decapsulation
2971 When this option is enabled,
2973 will examine UDP frames to see if they actually contain a
2975 frame as their payload.
2976 If this is the case, all filters will operate on the payload rather
2977 than the actual packet.
2979 This is useful if you want to send PPPoUDP traffic over a
2981 link, but want that link to do smart things with the real data rather than
2984 The UDP frame payload must not be compressed in any way, otherwise
2986 will not be able to interpret it.
2987 It is therefore recommended that you
2988 .Ic disable vj pred1 deflate
2990 .Ic deny vj pred1 deflate
2991 in the configuration for the
2993 invocation with the udp link.
2996 Forces execution of the configured chat scripts in
3005 exchanges low-level LCP, CCP and IPCP configuration traffic, the
3007 field of any replies is expected to be the same as that of the request.
3010 drops any reply packets that do not contain the expected identifier
3011 field, reporting the fact at the respective log level.
3016 will ignore the identifier field.
3021 This option simply tells
3023 to add new interface addresses to the interface rather than replacing them.
3024 The option can only be enabled if network address translation is enabled
3025 .Pq Dq nat enable yes .
3027 With this option enabled,
3029 will pass traffic for old interface addresses through the NAT
3030 ifdef({LOCALNAT},{engine,},{engine
3032 .Xr libalias 3 ) ,})
3033 resulting in the ability (in
3035 mode) to properly connect the process that caused the PPP link to
3036 come up in the first place.
3046 to attempt to negotiate IP control protocol capabilities and if
3047 successful to exchange IP datagrams with the peer.
3052 to attempt to negotiate IPv6 control protocol capabilities and if
3053 successful to exchange IPv6 datagrams with the peer.
3058 runs as a Multi-link server, a different
3060 instance initially receives each connection.
3061 After determining that
3062 the link belongs to an already existing bundle (controlled by another
3066 will transfer the link to that process.
3068 If the link is a tty device or if this option is enabled,
3070 will not exit, but will change its process name to
3072 and wait for the controlling
3074 to finish with the link and deliver a signal back to the idle process.
3075 This prevents the confusion that results from
3077 parent considering the link resource available again.
3079 For tty devices that have entries in
3081 this is necessary to prevent another
3083 from being started, and for program links such as
3087 from exiting due to the death of its child.
3090 cannot determine its parents requirements (except for the tty case), this
3091 option must be enabled manually depending on the circumstances.
3098 will automatically loop back packets being sent
3099 out with a destination address equal to that of the
3104 will send the packet, probably resulting in an ICMP redirect from
3106 It is convenient to have this option enabled when
3107 the interface is also the default route as it avoids the necessity
3108 of a loopback route.
3111 This option controls whether
3115 attribute to the RADIUS server when RADIUS is in use
3116 .Pq see Dq set radius .
3118 Note, at least one of
3126 prior to version 3.4.1 did not send the
3128 attribute as it was reported to break the Radiator RADIUS server.
3129 As the latest rfc (2865) no longer hints that only one of
3133 should be sent (as rfc 2138 did),
3135 now sends both and leaves it up to the administrator that chooses to use
3136 bad RADIUS implementations to
3137 .Dq disable NAS-IP-Address .
3140 This option controls whether
3144 attribute to the RADIUS server when RADIUS is in use
3145 .Pq see Dq set radius .
3147 Note, at least one of
3154 Enabling this option will tell the PAP authentication
3155 code to use the password database (see
3157 to authenticate the caller if they cannot be found in the
3158 .Pa /etc/ppp/ppp.secret
3160 .Pa /etc/ppp/ppp.secret
3161 is always checked first.
3162 If you wish to use passwords from
3164 but also to specify an IP number or label for a given client, use
3166 as the client password in
3167 .Pa /etc/ppp/ppp.secret .
3170 Enabling this option will tell
3172 to proxy ARP for the peer.
3175 will make an entry in the ARP table using
3179 address of the local network in which
3182 This allows other machines connecteed to the LAN to talk to
3183 the peer as if the peer itself was connected to the LAN.
3184 The proxy entry cannot be made unless
3186 is an address from a LAN.
3189 Enabling this will tell
3191 to add proxy arp entries for every IP address in all class C or
3192 smaller subnets routed via the tun interface.
3194 Proxy arp entries are only made for sticky routes that are added
3198 No proxy arp entries are made for the interface address itself
3206 command is used with the
3212 values, entries are stored in the
3215 Each time these variables change, this list is re-applied to the routing table.
3217 Disabling this option will prevent the re-application of sticky routes,
3220 list will still be maintained.
3227 to adjust TCP SYN packets so that the maximum receive segment
3228 size is not greater than the amount allowed by the interface MTU.
3233 to gather throughput statistics.
3234 Input and output is sampled over
3235 a rolling 5 second window, and current, best and total figures are retained.
3236 This data is output when the relevant
3238 layer shuts down, and is also available using the
3241 Throughput statistics are available at the
3248 Normally, when a user is authenticated using PAP or CHAP, and when
3252 mode, an entry is made in the utmp and wtmp files for that user.
3253 Disabling this option will tell
3255 not to make any utmp or wtmp entries.
3256 This is usually only necessary if
3257 you require the user to both login and authenticate themselves.
3262 .Ar dest Ns Op / Ns Ar nn
3267 is the destination IP address.
3268 The netmask is specified either as a number of bits with
3270 or as an IP number using
3275 with no mask refers to the default route.
3276 It is also possible to use the literal name
3281 is the next hop gateway to get to the given
3286 command for further details.
3288 It is possible to use the symbolic names
3294 as the destination, and
3301 is replaced with the interface IP address,
3303 is replaced with the interface IP destination (peer) address,
3305 is replaced with the interface IPv6 address, and
3307 is replaced with the interface IPv6 destination address,
3314 then if the route already exists, it will be updated as with the
3318 for further details).
3320 Routes that contain the
3328 constants are considered
3330 They are stored in a list (use
3332 to see the list), and each time the value of one of these variables
3333 changes, the appropriate routing table entries are updated.
3334 This facility may be disabled using
3335 .Dq disable sroutes .
3336 .It allow Ar command Op Ar args
3337 This command controls access to
3339 and its configuration files.
3340 It is possible to allow user-level access,
3341 depending on the configuration file label and on the mode that
3344 For example, you may wish to configure
3354 User id 0 is immune to these commands.
3356 .It allow user Ns Xo
3358 .Ar logname Ns No ...
3360 By default, only user id 0 is allowed access to
3362 If this command is used, all of the listed users are allowed access to
3363 the section in which the
3368 section is always checked first (even though it is only ever automatically
3371 commands are cumulative in a given section, but users allowed in any given
3372 section override users allowed in the default section, so it is possible to
3373 allow users access to everything except a given label by specifying default
3376 section, and then specifying a new user list for that label.
3380 is specified, access is allowed to all users.
3381 .It allow mode Ns Xo
3385 By default, access using any
3388 If this command is used, it restricts the access
3390 allowed to load the label under which this command is specified.
3395 command overrides any previous settings, and the
3397 section is always checked first.
3409 When running in multi-link mode, a section can be loaded if it allows
3411 of the currently existing line modes.
3414 .It nat Ar command Op Ar args
3415 This command allows the control of the network address translation (also
3416 known as masquerading or IP aliasing) facilities that are built into
3418 NAT is done on the external interface only, and is unlikely to make sense
3423 If nat is enabled on your system (it may be omitted at compile time),
3424 the following commands are possible:
3426 .It nat enable yes|no
3427 This command either switches network address translation on or turns it off.
3430 command line flag is synonymous with
3431 .Dq nat enable yes .
3432 .It nat addr Op Ar addr_local addr_alias
3433 This command allows data for
3437 It is useful if you own a small number of real IP numbers that
3438 you wish to map to specific machines behind your gateway.
3439 .It nat deny_incoming yes|no
3440 If set to yes, this command will refuse all incoming packets where an
3441 aliasing link does not already exist.
3442 ifdef({LOCALNAT},{},{Refer to the
3443 .Sx CONCEPTUAL BACKGROUND
3446 for a description of what an
3451 It should be noted under what circumstances an aliasing link is
3452 ifdef({LOCALNAT},{created.},{created by
3454 It may be necessary to further protect your network from outside
3455 connections using the
3461 This command gives a summary of available nat commands.
3463 This option causes various NAT statistics and information to
3464 be logged to the file
3465 .Pa /var/log/alias.log .
3466 .It nat port Ar proto Ar targetIP Ns Xo
3467 .No : Ns Ar targetPort Ns
3469 .No - Ns Ar targetPort
3472 .No - Ns Ar aliasPort
3473 .Oc Oo Ar remoteIP : Ns
3476 .No - Ns Ar remotePort
3480 This command causes incoming
3494 A range of port numbers may be specified as shown above.
3495 The ranges must be of the same size.
3499 is specified, only data coming from that IP number is redirected.
3503 (indicating any source port)
3504 or a range of ports the same size as the other ranges.
3506 This option is useful if you wish to run things like Internet phone on
3507 machines behind your gateway, but is limited in that connections to only
3508 one interior machine per source machine and target port are possible.
3509 .It nat proto Ar proto localIP Oo
3510 .Ar publicIP Op Ar remoteIP
3514 to redirect packets of protocol type
3518 to the internal address
3523 is specified, only packets destined for that address are matched,
3524 otherwise the default alias address is used.
3528 is specified, only packets matching that source address are matched,
3530 This command is useful for redirecting tunnel endpoints to an internal machine,
3533 .Dl nat proto ipencap 10.0.0.1
3534 .It "nat proxy cmd" Ar arg Ns No ...
3537 to proxy certain connections, redirecting them to a given server.
3538 ifdef({LOCALNAT},{},{Refer to the description of
3539 .Fn PacketAliasProxyRule
3542 for details of the available commands.
3544 .It nat punch_fw Op Ar base count
3547 to punch holes in the firewall for FTP or IRC DCC connections.
3548 This is done dynamically by installing termporary firewall rules which
3549 allow a particular connection (and only that connection) to go through
3551 The rules are removed once the corresponding connection terminates.
3555 rules starting from rule number
3557 will be used for punching firewall holes.
3558 The range will be cleared when the
3562 If no arguments are given, firewall punching is disabled.
3563 .It nat skinny_port Op Ar port
3566 which TCP port is used by the Skinny Station protocol.
3568 Cisco IP phones to communicate with Cisco Call Managers to setup voice
3570 The typical port used by Skinny is 2000.
3572 If no argument is given, skinny aliasing is disabled.
3573 .It nat same_ports yes|no
3574 When enabled, this command will tell the network address translation engine to
3575 attempt to avoid changing the port number on outgoing packets.
3577 if you want to support protocols such as RPC and LPD which require
3578 connections to come from a well known port.
3579 .It nat target Op Ar address
3580 Set the given target address or clear it if no address is given.
3581 The target address is used
3582 ifdef({LOCALNAT},{},{by libalias })dnl
3583 to specify how to NAT incoming packets by default.
3584 If a target address is not set or if
3586 is given, packets are not altered and are allowed to route to the internal
3589 The target address may be set to
3592 ifdef({LOCALNAT},{all packets will be redirected},
3593 {libalias will redirect all packets})
3594 to the interface address.
3595 .It nat use_sockets yes|no
3596 When enabled, this option tells the network address translation engine to
3597 create a socket so that it can guarantee a correct incoming ftp data or
3599 .It nat unregistered_only yes|no
3600 Only alter outgoing packets with an unregistered source address.
3601 According to RFC 1918, unregistered source addresses
3602 are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16.
3605 These commands are also discussed in the file
3607 which comes with the source distribution.
3614 is executed in the background with the following words replaced:
3615 .Bl -tag -width COMPILATIONDATE
3617 This is replaced with the local
3623 .It Li COMPILATIONDATE
3624 In previous software revisions, this was replaced with the date on which
3627 This is no longer supported as it breaks the ability to recompile the same
3628 code to produce an exact duplicate of a previous compilation.
3630 These are replaced with the primary and secondary nameserver IP numbers.
3631 If nameservers are negotiated by IPCP, the values of these macros will change.
3633 This is replaced with the local endpoint discriminator value.
3638 This is replaced with the peers IP number.
3640 This is replaced with the peers IPv6 number.
3642 This is replaced with the name of the interface that is in use.
3644 This is replaced with the number of IP bytes received since the connection
3647 This is replaced with the number of IP bytes sent since the connection
3650 This is replaced with the number of IP packets received since the connection
3653 This is replaced with the number of IP packets sent since the connection
3656 This is replaced with the number of IPv6 bytes received since the connection
3658 .It Li IPV6OCTETSOUT
3659 This is replaced with the number of IPv6 bytes sent since the connection
3661 .It Li IPV6PACKETSIN
3662 This is replaced with the number of IPv6 packets received since the connection
3664 .It Li IPV6PACKETSOUT
3665 This is replaced with the number of IPv6 packets sent since the connection
3668 This is replaced with the last label name used.
3669 A label may be specified on the
3671 command line, via the
3679 This is replaced with the IP number assigned to the local interface.
3681 This is replaced with the IPv6 number assigned to the local interface.
3683 This is replaced with the number of bytes received since the connection
3686 This is replaced with the number of bytes sent since the connection
3689 This is replaced with the number of packets received since the connection
3692 This is replaced with the number of packets sent since the connection
3695 This is replaced with the value of the peers endpoint discriminator.
3697 This is replaced with the current process id.
3699 This is replaced with the name of the diagnostic socket.
3701 This is replaced with the bundle uptime in HH:MM:SS format.
3703 This is replaced with the username that has been authenticated with PAP or
3705 Normally, this variable is assigned only in -direct mode.
3706 This value is available irrespective of whether utmp logging is enabled.
3708 This is replaced with the current version number of
3712 These substitutions are also done by the
3719 If you wish to pause
3721 while the command executes, use the
3724 .It clear physical|ipcp|ipv6 Op current|overall|peak...
3725 Clear the specified throughput values at either the
3733 is specified, context must be given (see the
3736 If no second argument is given, all values are cleared.
3737 .It clone Ar name Ns Xo
3738 .Op \&, Ns Ar name Ns
3741 Clone the specified link, creating one or more new links according to the
3744 This command must be used from the
3746 command below unless you have only got a single link (in which case that
3747 link becomes the default).
3748 Links may be removed using the
3752 The default link name is
3754 .It close Op lcp|ccp Ns Op !\&
3755 If no arguments are given, the relevant protocol layers will be brought
3756 down and the link will be closed.
3759 is specified, the LCP layer is brought down, but
3761 will not bring the link offline.
3762 It is subsequently possible to use
3765 to talk to the peer machine if, for example, something like
3770 is specified, only the relevant compression layer is closed.
3773 is used, the compression layer will remain in the closed state, otherwise
3774 it will re-enter the STOPPED state, waiting for the peer to initiate
3775 further CCP negotiation.
3776 In any event, this command does not disconnect the user from
3787 This command deletes the route with the given
3794 all non-direct entries in the routing table for the current interface,
3797 entries are deleted.
3802 the default route is deleted.
3810 will not complain if the route does not already exist.
3811 .It dial|call Op Ar label Ns Xo
3814 This command is the equivalent of
3818 and is provided for backwards compatibility.
3819 .It down Op Ar lcp|ccp
3820 Bring the relevant layer down ungracefully, as if the underlying layer
3821 had become unavailable.
3822 It is not considered polite to use this command on
3823 a Finite State Machine that is in the OPEN state.
3825 supplied, the entire link is closed (or if no context is given, all links
3831 layer is terminated but the device is not brought offline and the link
3835 is specified, only the relevant compression layer(s) are terminated.
3836 .It help|? Op Ar command
3837 Show a list of available commands.
3840 is specified, show the usage string for that command.
3841 .It ident Op Ar text Ns No ...
3842 Identify the link to the peer using
3846 is empty, link identification is disabled.
3847 It is possible to use any of the words described for the
3852 command for details of when
3854 identifies itself to the peer.
3855 .It iface Ar command Op args
3856 This command is used to control the interface used by
3859 may be one of the following:
3863 .Ar addr Ns Op / Ns Ar bits
3874 combination to the interface.
3875 Instead of specifying
3879 (with no space between it and
3881 If the given address already exists, the command fails unless the
3883 is used - in which case the previous interface address entry is overwritten
3884 with the new one, allowing a change of netmask or peer address.
3895 .Dq 255.255.255.255 .
3896 This address (the broadcast address) is the only duplicate peer address that
3899 .It iface clear Op INET | INET6
3900 If this command is used while
3902 is in the OPENED state or while in
3904 mode, all addresses except for the NCP negotiated address are deleted
3908 is not in the OPENED state and is not in
3910 mode, all interface addresses are deleted.
3912 If the INET or INET6 arguments are used, only addresses for that address
3915 .It iface delete Ns Xo
3920 This command deletes the given
3925 is used, no error is given if the address is not currently assigned to
3926 the interface (and no deletion takes place).
3927 .It iface name Ar name
3928 Renames the interface to
3930 .It iface description Ar description
3931 Sets the interface description to
3933 Useful if you have many interfaces on your system.
3935 Shows the current state and current addresses for the interface.
3936 It is much the same as running
3937 .Dq ifconfig INTERFACE .
3938 .It iface help Op Ar sub-command
3939 This command, when invoked without
3941 will show a list of possible
3943 sub-commands and a brief synopsis for each.
3946 only the synopsis for the given sub-command is shown.
3950 .Ar name Ns Op , Ns Ar name Ns
3951 .No ... Ar command Op Ar args
3953 This command may prefix any other command if the user wishes to
3954 specify which link the command should affect.
3955 This is only applicable after multiple links have been created in Multi-link
3961 specifies the name of an existing link.
3964 is a comma separated list,
3966 is executed on each link.
3972 is executed on all links.
3973 .It load Op Ar label Ns Xo
3996 will not attempt to make an immediate connection.
3997 .It log Ar word Ns No ...
3998 Send the given word(s) to the log file with the prefix
4000 Word substitutions are done as explained under the
4003 .It open Op lcp|ccp|ipcp
4004 This is the opposite of the
4007 All closed links are immediately brought up apart from second and subsequent
4009 links - these will come up based on the
4011 command that has been used.
4015 argument is used while the LCP layer is already open, LCP will be
4017 This allows various LCP options to be changed, after which
4019 can be used to put them into effect.
4020 After renegotiating LCP,
4021 any agreed authentication will also take place.
4025 argument is used, the relevant compression layer is opened.
4026 Again, if it is already open, it will be renegotiated.
4030 argument is used, the link will be brought up as normal, but if
4031 IPCP is already open, it will be renegotiated and the network
4032 interface will be reconfigured.
4034 It is probably not good practice to re-open the PPP state machines
4035 like this as it is possible that the peer will not behave correctly.
4038 however useful as a way of forcing the CCP or VJ dictionaries to be reset.
4040 Specify the password required for access to the full
4043 This password is required when connecting to the diagnostic port (see the
4054 logging is active, instead, the literal string
4060 is executed from the controlling connection or from a command file,
4061 ppp will exit after closing all connections.
4062 Otherwise, if the user
4063 is connected to a diagnostic socket, the connection is simply dropped.
4069 will exit despite the source of the command after closing all existing
4072 This command removes the given link.
4073 It is only really useful in multi-link mode.
4074 A link must be in the
4076 state before it is removed.
4077 .It rename|mv Ar name
4078 This command renames the given link to
4082 is already used by another link.
4084 The default link name is
4091 may make the log file more readable.
4092 .It resolv Ar command
4093 This command controls
4100 starts up, it loads the contents of this file into memory and retains this
4101 image for future use.
4103 is one of the following:
4104 .Bl -tag -width readonly
4107 .Pa /etc/resolv.conf
4113 will still attempt to negotiate nameservers with the peer, making the results
4119 This is the opposite of the
4124 .Pa /etc/resolv.conf
4126 This may be necessary if for example a DHCP client overwrote
4127 .Pa /etc/resolv.conf .
4130 .Pa /etc/resolv.conf
4131 with the version originally read at startup or with the last
4134 This is sometimes a useful command to put in the
4135 .Pa /etc/ppp/ppp.linkdown
4139 .Pa /etc/resolv.conf
4141 This command will work even if the
4143 command has been used.
4144 It may be useful as a command in the
4145 .Pa /etc/ppp/ppp.linkup
4146 file if you wish to defer updating
4147 .Pa /etc/resolv.conf
4148 until after other commands have finished.
4153 .Pa /etc/resolv.conf
4158 successfully negotiates a DNS.
4159 This is the opposite of the
4164 This option is not (yet) implemented.
4168 to identify itself to the peer.
4169 The link must be in LCP state or higher.
4170 If no identity has been set (via the
4176 When an identity has been set,
4178 will automatically identify itself when it sends or receives a configure
4179 reject, when negotiation fails or when LCP reaches the opened state.
4181 Received identification packets are logged to the LCP log (see
4183 for details) and are never responded to.
4188 This option allows the setting of any of the following variables:
4190 .It set accmap Ar hex-value
4191 ACCMap stands for Asynchronous Control Character Map.
4193 negotiated with the peer, and defaults to a value of 00000000 in hex.
4194 This protocol is required to defeat hardware that depends on passing
4195 certain characters from end to end (such as XON/XOFF etc).
4197 For the XON/XOFF scenario, use
4198 .Dq set accmap 000a0000 .
4199 .It set Op auth Ns Xo
4202 This sets the authentication key (or password) used in client mode
4203 PAP or CHAP negotiation to the given value.
4204 It also specifies the
4205 password to be used in the dial or login scripts in place of the
4207 sequence, preventing the actual password from being logged.
4212 logging is in effect,
4216 for security reasons.
4218 If the first character of
4220 is an exclamation mark
4223 treats the remainder of the string as a program that must be executed
4235 it is treated as a single literal
4237 otherwise, ignoring the
4240 is parsed as a program to execute in the same was as the
4242 command above, substituting special names in the same manner.
4245 will feed the program three lines of input, each terminated by a newline
4249 The host name as sent in the CHAP challenge.
4251 The challenge string as sent in the CHAP challenge.
4257 Two lines of output are expected:
4262 to be sent with the CHAP response.
4266 which is encrypted with the challenge and request id, the answer being sent
4267 in the CHAP response packet.
4272 in this manner, it is expected that the host challenge is a series of ASCII
4273 digits or characters.
4274 An encryption device or Secure ID card is usually
4275 required to calculate the secret appropriate for the given challenge.
4276 .It set authname Ar id
4277 This sets the authentication id used in client mode PAP or CHAP negotiation.
4281 mode with CHAP enabled,
4283 is used in the initial authentication challenge and should normally be set to
4284 the local machine name.
4286 .Ar min-percent max-percent period
4288 These settings apply only in multi-link mode and default to zero, zero and
4294 mode link is available, only the first link is made active when
4296 first reads data from the tun device.
4299 link will be opened only when the current bundle throughput is at least
4301 percent of the total bundle bandwidth for
4304 When the current bundle throughput decreases to
4306 percent or less of the total bundle bandwidth for
4310 link will be brought down as long as it is not the last active link.
4312 Bundle throughput is measured as the maximum of inbound and outbound
4315 The default values cause
4317 links to simply come up one at a time.
4319 Certain devices cannot determine their physical bandwidth, so it
4320 is sometimes necessary to use the
4322 command (described below) to make
4325 .It set bandwidth Ar value
4326 This command sets the connection bandwidth in bits per second.
4328 must be greater than zero.
4329 It is currently only used by the
4332 .It set callback Ar option Ns No ...
4333 If no arguments are given, callback is disabled, otherwise,
4337 mode, will accept) one of the given
4338 .Ar option Ns No s .
4339 In client mode, if an
4343 will request a different
4345 until no options remain at which point
4347 will terminate negotiations (unless
4349 is one of the specified
4353 will accept any of the given protocols - but the client
4355 request one of them.
4356 If you wish callback to be optional, you must {include}
4362 are as follows (in this order of preference):
4366 The callee is expected to decide the callback number based on
4370 is the callee, the number should be specified as the fifth field of
4372 .Pa /etc/ppp/ppp.secret .
4374 Microsoft's callback control protocol is used.
4379 If you wish to negotiate
4381 in client mode but also wish to allow the server to request no callback at
4382 CBCP negotiation time, you must specify both
4386 as callback options.
4388 .Ar number Ns Op , Ns Ar number Ns
4391 The caller specifies the
4397 should be either a comma separated list of allowable numbers or a
4399 meaning any number is permitted.
4402 is the caller, only a single number should be specified.
4404 Note, this option is very unsafe when used with a
4406 as a malicious caller can tell
4408 to call any (possibly international) number without first authenticating
4411 If the peer does not wish to do callback at all,
4413 will accept the fact and continue without callback rather than terminating
4415 This is required (in addition to one or more other callback
4416 options) if you wish callback to be optional.
4420 .No *| Ns Ar number Ns Oo
4421 .No , Ns Ar number Ns ...\& Oc
4422 .Op Ar delay Op Ar retry
4424 If no arguments are given, CBCP (Microsoft's CallBack Control Protocol)
4425 is disabled - ie, configuring CBCP in the
4427 command will result in
4429 requesting no callback in the CBCP phase.
4432 attempts to use the given phone
4433 .Ar number Ns No (s).
4438 will insist that the client uses one of these numbers, unless
4440 is used in which case the client is expected to specify the number.
4444 will attempt to use one of the given numbers (whichever it finds to
4445 be agreeable with the peer), or if
4449 will expect the peer to specify the number.
4451 .No off| Ns Ar seconds Ns Op !\&
4455 checks for the existence of carrier depending on the type of device
4456 that has been opened:
4457 .Bl -tag -width XXX -offset XXX
4458 .It Terminal Devices
4459 Carrier is checked one second after the login script is complete.
4462 assumes that this is because the device does not support carrier (which
4465 NULL-modem cables), logs the fact and stops checking
4468 As ptys do not support the TIOCMGET ioctl, the tty device will switch all
4469 carrier detection off when it detects that the device is a pty.
4470 .It PPPoE (netgraph) Devices
4471 Carrier is checked once per second for 5 seconds.
4472 If it is not set after
4473 the fifth second, the connection attempt is considered to have failed and
4474 the device is closed.
4475 Carrier is always required for PPPoE devices.
4478 All other device types do not support carrier.
4479 Setting a carrier value will
4480 result in a warning when the device is opened.
4482 Some modems take more than one second after connecting to assert the carrier
4484 If this delay is not increased, this will result in
4486 inability to detect when the link is dropped, as
4488 assumes that the device is not asserting carrier.
4492 command overrides the default carrier behaviour.
4494 specifies the maximum number of seconds that
4496 should wait after the dial script has finished before deciding if
4497 carrier is available or not.
4503 will not check for carrier on the device, otherwise
4505 will not proceed to the login script until either carrier is detected
4508 has elapsed, at which point
4510 assumes that the device will not set carrier.
4512 If no arguments are given, carrier settings will go back to their default
4517 is followed immediately by an exclamation mark
4523 If carrier is not detected after
4525 seconds, the link will be disconnected.
4526 .It set choked Op Ar timeout
4527 This sets the number of seconds that
4529 will keep a choked output queue before dropping all pending output packets.
4532 is less than or equal to zero or if
4534 is not specified, it is set to the default value of
4537 A choked output queue occurs when
4539 has read a certain number of packets from the local network for transmission,
4540 but cannot send the data due to link failure (the peer is busy etc.).
4542 will not read packets indefinitely.
4543 Instead, it reads up to
4549 packets in multi-link mode), then stops reading the network interface
4552 seconds have passed or at least one packet has been sent.
4556 seconds pass, all pending output packets are dropped.
4557 .It set ctsrts|crtscts on|off
4558 This sets hardware flow control.
4559 Hardware flow control is
4562 .It set deflate Ar out-winsize Op Ar in-winsize
4563 This sets the DEFLATE algorithms default outgoing and incoming window
4569 must be values between
4577 will insist that this window size is used and will not accept any other
4578 values from the peer.
4579 .It set dns Op Ar primary Op Ar secondary
4580 This command specifies DNS overrides for the
4585 command description above for details.
4586 This command does not affect the IP numbers requested using
4588 .It set device|line Xo
4591 This sets the device(s) to which
4593 will talk to the given
4596 All serial device names are expected to begin with
4598 Serial devices are usually called
4605 it must either begin with an exclamation mark
4608 .No PPPoE: Ns Ar iface Ns Xo
4609 .Op \&: Ns Ar provider Ns
4613 enabled systems), or be of the format
4615 .Ar host : port Op /tcp|udp .
4618 If it begins with an exclamation mark, the rest of the device name is
4619 treated as a program name, and that program is executed when the device
4621 Standard input, output and error are fed back to
4623 and are read and written as if they were a regular device.
4626 .No PPPoE: Ns Ar iface Ns Xo
4627 .Op \&: Ns Ar provider Ns
4629 specification is given,
4631 will attempt to create a
4633 over Ethernet connection using the given
4641 will attempt to load it using
4643 If this fails, an external program must be used such as the
4645 program available under
4649 is passed as the service name in the PPPoE Discovery Initiation (PADI)
4651 If no provider is given, an empty value will be used.
4653 When a PPPoE connection is established,
4655 will place the name of the Access Concentrator in the environment variable
4662 for further details.
4665 .Ar host Ns No : Ns Ar port Ns Oo
4668 specification is given,
4670 will attempt to connect to the given
4678 suffix is not provided, the default is
4680 Refer to the section on
4681 .Em PPP OVER TCP and UDP
4682 above for further details.
4688 will attempt to open each one in turn until it succeeds or runs out of
4690 .It set dial Ar chat-script
4691 This specifies the chat script that will be used to dial the other
4698 and to the example configuration files for details of the chat script
4700 It is possible to specify some special
4702 in your chat script as follows:
4705 When used as the last character in a
4707 string, this indicates that a newline should not be appended.
4709 When the chat script encounters this sequence, it delays two seconds.
4711 When the chat script encounters this sequence, it delays for one quarter of
4714 This is replaced with a newline character.
4716 This is replaced with a carriage return character.
4718 This is replaced with a space character.
4720 This is replaced with a tab character.
4722 This is replaced by the current phone number (see
4726 This is replaced by the current
4732 This is replaced by the current
4739 Note that two parsers will examine these escape sequences, so in order to
4742 see the escape character, it is necessary to escape it from the
4743 .Sq command parser .
4744 This means that in practice you should use two escapes, for example:
4745 .Bd -literal -offset indent
4746 set dial "... ATDT\\\\T CONNECT"
4749 It is also possible to execute external commands from the chat script.
4750 To do this, the first character of the expect or send string is an
4753 If a literal exclamation mark is required, double it up to
4755 and it will be treated as a single literal
4757 When the command is executed, standard input and standard output are
4758 directed to the open device (see the
4760 command), and standard error is read by
4762 and substituted as the expect or send string.
4765 is running in interactive mode, file descriptor 3 is attached to
4768 For example (wrapped for readability):
4769 .Bd -literal -offset indent
4770 set login "TIMEOUT 5 \\"\\" \\"\\" login:--login: ppp \e
4771 word: ppp \\"!sh \\\\-c \\\\\\"echo \\\\-n label: >&2\\\\\\"\\" \e
4772 \\"!/bin/echo in\\" HELLO"
4775 would result in the following chat sequence (output using the
4776 .Sq set log local chat
4777 command before dialing):
4778 .Bd -literal -offset indent
4783 Chat: Expecting: login:--login:
4784 Chat: Wait for (5): login:
4786 Chat: Expecting: word:
4787 Chat: Wait for (5): word:
4789 Chat: Expecting: !sh \\-c "echo \\-n label: >&2"
4790 Chat: Exec: sh -c "echo -n label: >&2"
4791 Chat: Wait for (5): !sh \\-c "echo \\-n label: >&2" --> label:
4792 Chat: Exec: /bin/echo in
4794 Chat: Expecting: HELLO
4795 Chat: Wait for (5): HELLO
4799 Note (again) the use of the escape character, allowing many levels of
4801 Here, there are four parsers at work.
4802 The first parses the original line, reading it as three arguments.
4803 The second parses the third argument, reading it as 11 arguments.
4804 At this point, it is
4807 signs are escaped, otherwise this parser will see them as constituting
4808 an expect-send-expect sequence.
4811 character is seen, the execution parser reads the first command as three
4814 itself expands the argument after the
4816 As we wish to send the output back to the modem, in the first example
4817 we redirect our output to file descriptor 2 (stderr) so that
4819 itself sends and logs it, and in the second example, we just output to stdout,
4820 which is attached directly to the modem.
4822 This, of course means that it is possible to execute an entirely external
4824 command rather than using the internal one.
4827 for a good alternative.
4829 The external command that is executed is subjected to the same special
4830 word expansions as the
4833 .It set enddisc Op label|IP|MAC|magic|psn value
4834 This command sets our local endpoint discriminator.
4835 If set prior to LCP negotiation, and if no
4837 command has been used,
4839 will send the information to the peer using the LCP endpoint discriminator
4841 The following discriminators may be set:
4842 .Bl -tag -width indent
4844 The current label is used.
4846 Our local IP number is used.
4847 As LCP is negotiated prior to IPCP, it is
4848 possible that the IPCP layer will subsequently change this value.
4850 it does, the endpoint discriminator stays at the old value unless manually
4853 This is similar to the
4855 option above, except that the MAC address associated with the local IP
4857 If the local IP number is not resident on any Ethernet
4858 interface, the command will fail.
4860 As the local IP number defaults to whatever the machine host name is,
4862 is usually done prior to any
4866 A 20 digit random number is used.
4867 Care should be taken when using magic numbers as restarting
4869 or creating a link using a different
4871 invocation will also use a different magic number and will therefore not
4872 be recognised by the peer as belonging to the same bundle.
4873 This makes it unsuitable for
4881 should be set to an absolute public switched network number with the
4885 If no arguments are given, the endpoint discriminator is reset.
4886 .It set escape Ar value...
4887 This option is similar to the
4890 It allows the user to specify a set of characters that will be
4892 as they travel across the link.
4893 .It set filter dial|alive|in|out Ar rule-no Xo
4894 .No permit|deny|clear| Ns Ar rule-no
4897 .Ar src_addr Ns Op / Ns Ar width
4898 .Op Ar dst_addr Ns Op / Ns Ar width
4900 .Op src lt|eq|gt Ar port
4901 .Op dst lt|eq|gt Ar port
4905 .Op timeout Ar secs ]
4908 supports four filter sets.
4911 filter specifies packets that keep the connection alive - resetting the
4915 filter specifies packets that cause
4922 filter specifies packets that are allowed to travel
4923 into the machine and the
4925 filter specifies packets that are allowed out of the machine.
4927 Filtering is done prior to any IP alterations that might be done by the
4928 NAT engine on outgoing packets and after any IP alterations that might
4929 be done by the NAT engine on incoming packets.
4930 By default all empty filter sets allow all packets to pass.
4931 Rules are processed in order according to
4933 (unless skipped by specifying a rule number as the
4935 Up to 40 rules may be given for each set.
4936 If a packet does not match
4937 any of the rules in a given set, it is discarded.
4942 filters, this means that the packet is dropped.
4945 filters it means that the packet will not reset the idle timer (even if
4947 .Ar in Ns No / Ns Ar out
4950 value) and in the case of
4952 filters it means that the packet will not trigger a dial.
4953 A packet failing to trigger a dial will be dropped rather than queued.
4956 .Sx PACKET FILTERING
4957 above for further details.
4958 .It set hangup Ar chat-script
4959 This specifies the chat script that will be used to reset the device
4960 before it is closed.
4961 It should not normally be necessary, but can
4962 be used for devices that fail to reset themselves properly on close.
4963 .It set help|? Op Ar command
4964 This command gives a summary of available set commands, or if
4966 is specified, the command usage is shown.
4967 .It set ifaddr Oo Ar myaddr Ns
4969 .Oo Ar hisaddr Ns Op / Ns Ar \&nn
4974 This command specifies the IP addresses that will be used during
4976 Addresses are specified using the format
4982 is the preferred IP, but
4984 specifies how many bits of the address we will insist on.
4987 is omitted, it defaults to
4989 unless the IP address is 0.0.0.0 in which case it defaults to
4992 If you wish to assign a dynamic IP number to the peer,
4994 may also be specified as a range of IP numbers in the format
4995 .Bd -ragged -offset indent
4996 .Ar \&IP Ns Oo \&- Ns Ar \&IP Ns Xo
4997 .Oc Ns Oo , Ns Ar \&IP Ns
4998 .Op \&- Ns Ar \&IP Ns
5005 .Dl set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20
5009 as the local IP number, but may assign any of the given 10 IP
5010 numbers to the peer.
5011 If the peer requests one of these numbers,
5012 and that number is not already in use,
5014 will grant the peers request.
5015 This is useful if the peer wants
5016 to re-establish a link using the same IP number as was previously
5017 allocated (thus maintaining any existing tcp or udp connections).
5019 If the peer requests an IP number that is either outside
5020 of this range or is already in use,
5022 will suggest a random unused IP number from the range.
5026 is specified, it is used in place of
5028 in the initial IPCP negotiation.
5029 However, only an address in the
5031 range will be accepted.
5032 This is useful when negotiating with some
5034 implementations that will not assign an IP number unless their peer
5038 It should be noted that in
5042 will configure the interface immediately upon reading the
5044 line in the config file.
5045 In any other mode, these values are just
5046 used for IPCP negotiations, and the interface is not configured
5047 until the IPCP layer is up.
5051 argument may be overridden by the third field in the
5053 file once the client has authenticated itself
5057 .Sx AUTHENTICATING INCOMING CONNECTIONS
5058 section for details.
5060 In all cases, if the interface is already configured,
5062 will try to maintain the interface IP numbers so that any existing
5063 bound sockets will remain valid.
5064 .It set ifqueue Ar packets
5065 Set the maximum number of packets that
5067 will read from the tunnel interface while data cannot be sent to any of
5068 the available links.
5069 This queue limit is necessary to flow control outgoing data as the tunnel
5070 interface is likely to be far faster than the combined links available to
5075 is set to a value less than the number of links,
5077 will read up to that value regardless.
5078 This prevents any possible latency problems.
5080 The default value for
5084 .It set ccpretry|ccpretries Oo Ar timeout
5085 .Op Ar reqtries Op Ar trmtries
5087 .It set chapretry|chapretries Oo Ar timeout
5090 .It set ipcpretry|ipcpretries Oo Ar timeout
5091 .Op Ar reqtries Op Ar trmtries
5093 .It set ipv6cpretry|ipv6cpretries Oo Ar timeout
5094 .Op Ar reqtries Op Ar trmtries
5096 .It set lcpretry|lcpretries Oo Ar timeout
5097 .Op Ar reqtries Op Ar trmtries
5099 .It set papretry|papretries Oo Ar timeout
5102 These commands set the number of seconds that
5104 will wait before resending Finite State Machine (FSM) Request packets.
5107 for all FSMs is 3 seconds (which should suffice in most cases).
5111 is specified, it tells
5113 how many configuration request attempts it should make while receiving
5114 no reply from the peer before giving up.
5115 The default is 5 attempts for
5116 CCP, LCP and IPCP and 3 attempts for PAP and CHAP.
5120 is specified, it tells
5122 how many terminate requests should be sent before giving up waiting for the
5124 The default is 3 attempts.
5125 Authentication protocols are
5126 not terminated and it is therefore invalid to specify
5130 In order to avoid negotiations with the peer that will never converge,
5132 will only send at most 3 times the configured number of
5134 in any given negotiation session before giving up and closing that layer.
5140 This command allows the adjustment of the current log level.
5141 Refer to the Logging Facility section for further details.
5142 .It set login Ar chat-script
5145 compliments the dial-script.
5146 If both are specified, the login
5147 script will be executed after the dial script.
5148 Escape sequences available in the dial script are also available here.
5149 .It set logout Ar chat-script
5150 This specifies the chat script that will be used to logout
5151 before the hangup script is called.
5152 It should not normally be necessary.
5153 .It set lqrperiod|echoperiod Ar frequency
5154 This command sets the
5161 The default is 30 seconds.
5162 You must also use the
5166 commands if you wish to send
5170 requests to the peer.
5171 .It set mode Ar interactive|auto|ddial|background
5172 This command allows you to change the
5174 of the specified link.
5175 This is normally only useful in multi-link mode,
5176 but may also be used in uni-link mode.
5178 It is not possible to change a link that is
5183 Note: If you issue the command
5185 and have network address translation enabled, it may be useful to
5186 .Dq enable iface-alias
5190 to do the necessary address translations to enable the process that
5191 triggers the connection to connect once the link is up despite the
5192 peer assigning us a new (dynamic) IP address.
5193 .It set mppe Op 40|56|128|* Op stateless|stateful|*
5194 This option selects the encryption parameters used when negotiation
5196 MPPE can be disabled entirely with the
5199 If no arguments are given,
5201 will attempt to negotiate a stateful link with a 128 bit key, but
5202 will agree to whatever the peer requests (including no encryption
5205 If any arguments are given,
5209 on using MPPE and will close the link if it is rejected by the peer (Note;
5210 this behaviour can be overridden by a configured RADIUS server).
5212 The first argument specifies the number of bits that
5214 should insist on during negotiations and the second specifies whether
5216 should insist on stateful or stateless mode.
5217 In stateless mode, the
5218 encryption dictionary is re-initialised with every packet according to
5219 an encryption key that is changed with every packet.
5221 the encryption dictionary is re-initialised every 256 packets or after
5222 the loss of any data and the key is changed every 256 packets.
5223 Stateless mode is less efficient but is better for unreliable transport
5225 .It set mrru Op Ar value
5226 Setting this option enables Multi-link PPP negotiations, also known as
5227 Multi-link Protocol or MP.
5228 There is no default MRRU (Maximum Reconstructed Receive Unit) value.
5229 If no argument is given, multi-link mode is disabled.
5234 The default MRU (Maximum Receive Unit) is 1500.
5235 If it is increased, the other side *may* increase its MTU.
5236 In theory there is no point in decreasing the MRU to below the default as the
5238 protocol says implementations *must* be able to accept packets of at
5245 will refuse to negotiate a higher value.
5246 The maximum MRU can be set to 2048 at most.
5247 Setting a maximum of less than 1500 violates the
5249 rfc, but may sometimes be necessary.
5252 imposes a maximum of 1492 due to hardware limitations.
5254 If no argument is given, 1500 is assumed.
5255 A value must be given when
5262 The default MTU is 1500.
5263 At negotiation time,
5265 will accept whatever MRU the peer requests (assuming it is
5266 not less than 296 bytes or greater than the assigned maximum).
5269 will not accept MRU values less than
5271 When negotiations are complete, the MTU is used when writing to the
5272 interface, even if the peer requested a higher value MRU.
5273 This can be useful for
5274 limiting your packet size (giving better bandwidth sharing at the expense
5275 of more header data).
5281 will refuse to negotiate a higher value.
5282 The maximum MTU can be set to 2048 at most.
5283 Note, it is necessary to use the
5285 keyword to limit the MTU when using PPPoE.
5289 is given, 1500, or whatever the peer asks for is used.
5290 A value must be given when
5293 .It set nbns Op Ar x.x.x.x Op Ar y.y.y.y
5294 This option allows the setting of the Microsoft NetBIOS name server
5295 values to be returned at the peers request.
5296 If no values are given,
5298 will reject any such requests.
5299 .It set openmode active|passive Op Ar delay
5308 will always initiate LCP/IPCP/CCP negotiation one second after the line
5310 If you want to wait for the peer to initiate negotiations, you
5313 If you want to initiate negotiations immediately or after more than one
5314 second, the appropriate
5316 may be specified here in seconds.
5317 .It set parity odd|even|none|mark
5318 This allows the line parity to be set.
5319 The default value is
5321 .It set phone Ar telno Ns Xo
5322 .Oo \&| Ns Ar backupnumber
5323 .Oc Ns ... Ns Oo : Ns Ar nextnumber
5326 This allows the specification of the phone number to be used in
5327 place of the \\\\T string in the dial and login chat scripts.
5328 Multiple phone numbers may be given separated either by a pipe
5333 Numbers after the pipe are only dialed if the dial or login
5334 script for the previous number failed.
5336 Numbers after the colon are tried sequentially, irrespective of
5337 the reason the line was dropped.
5339 If multiple numbers are given,
5341 will dial them according to these rules until a connection is made, retrying
5342 the maximum number of times specified by
5347 mode, each number is attempted at most once.
5348 .It set pppoe Op standard|3Com
5349 This option configures the underlying
5351 node to either standard RFC2516 PPPoE or proprietary 3Com mode.
5352 If not set the system default will be used.
5353 .It set Op proc Ns Xo
5354 .No title Op Ar value
5356 The current process title as displayed by
5358 is changed according to
5362 is not specified, the original process title is restored.
5364 word replacements done by the shell commands (see the
5366 command above) are done here too.
5368 Note, if USER is required in the process title, the
5370 command must appear in
5372 as it is not known when the commands in
5375 .It set radius Op Ar config-file
5376 This command enables RADIUS support (if it is compiled in).
5378 refers to the radius client configuration file as described in
5380 If PAP, CHAP, MSCHAP or MSCHAPv2 are
5381 .Dq enable Ns No d ,
5384 .Em \&N Ns No etwork
5387 and uses the configured RADIUS server to authenticate rather than
5388 authenticating from the
5390 file or from the passwd database.
5392 If none of PAP, CHAP, MSCHAP or MSCHAPv2 are enabled,
5397 uses the following attributes from the RADIUS reply:
5398 .Bl -tag -width XXX -offset XXX
5399 .It RAD_FRAMED_IP_ADDRESS
5400 The peer IP address is set to the given value.
5401 .It RAD_FRAMED_IP_NETMASK
5402 The tun interface netmask is set to the given value.
5404 If the given MTU is less than the peers MRU as agreed during LCP
5405 negotiation, *and* it is less that any configured MTU (see the
5407 command), the tun interface MTU is set to the given value.
5408 .It RAD_FRAMED_COMPRESSION
5409 If the received compression type is
5412 will request VJ compression during IPCP negotiations despite any
5414 configuration command.
5416 If this attribute is supplied,
5418 will attempt to use it as an additional label to load from the
5423 The load will be attempted before (and in addition to) the normal
5425 If the label does not exist, no action is taken and
5427 proceeds to the normal load using the current label.
5428 .It RAD_FRAMED_ROUTE
5429 The received string is expected to be in the format
5430 .Ar dest Ns Op / Ns Ar bits
5433 Any specified metrics are ignored.
5437 are understood as valid values for
5444 to sepcify the default route, and
5446 is understood to be the same as
5455 For example, a returned value of
5456 .Dq 1.2.3.4/24 0.0.0.0 1 2 -1 3 400
5457 would result in a routing table entry to the 1.2.3.0/24 network via
5459 and a returned value of
5463 would result in a default route to
5466 All RADIUS routes are applied after any sticky routes are applied, making
5467 RADIUS routes override configured routes.
5468 This also applies for RADIUS routes that do not {include} the
5474 .It RAD_FRAMED_IPV6_PREFIX
5475 If this attribute is supplied, the value is substituted for IPV6PREFIX
5477 You may pass it to an upper layer protocol such as DHCPv6 for delegating an
5478 IPv6 prefix to a peer.
5479 .It RAD_FRAMED_IPV6_ROUTE
5480 The received string is expected to be in the format
5481 .Ar dest Ns Op / Ns Ar bits
5484 Any specified metrics are ignored.
5488 are understood as valid values for
5495 to sepcify the default route, and
5497 is understood to be the same as
5506 For example, a returned value of
5507 .Dq 3ffe:505:abcd::/48 ::
5508 would result in a routing table entry to the 3ffe:505:abcd::/48 network via
5510 and a returned value of
5513 .Dq default HISADDR6
5514 would result in a default route to
5517 All RADIUS IPv6 routes are applied after any sticky routes are
5518 applied, making RADIUS IPv6 routes override configured routes.
5520 also applies for RADIUS IPv6 routes that do not {include} the
5526 .It RAD_SESSION_TIMEOUT
5527 If supplied, the client connection is closed after the given number of
5529 .It RAD_REPLY_MESSAGE
5530 If supplied, this message is passed back to the peer as the authentication
5532 .It RAD_MICROSOFT_MS_CHAP_ERROR
5534 .Dv RAD_VENDOR_MICROSOFT
5535 vendor specific attribute is supplied, it is passed back to the peer as the
5536 authentication FAILURE text.
5537 .It RAD_MICROSOFT_MS_CHAP2_SUCCESS
5539 .Dv RAD_VENDOR_MICROSOFT
5540 vendor specific attribute is supplied and if MS-CHAPv2 authentication is
5541 being used, it is passed back to the peer as the authentication SUCCESS text.
5542 .It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY
5544 .Dv RAD_VENDOR_MICROSOFT
5545 vendor specific attribute is supplied and has a value of 2 (Required),
5547 will insist that MPPE encryption is used (even if no
5549 configuration command has been given with arguments).
5550 If it is supplied with a value of 1 (Allowed), encryption is made optional
5553 configuration commands with arguments).
5554 .It RAD_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES
5556 .Dv RAD_VENDOR_MICROSOFT
5557 vendor specific attribute is supplied, bits 1 and 2 are examined.
5558 If either or both are set, 40 bit and/or 128 bit (respectively) encryption
5559 options are set, overriding any given first argument to the
5562 Note, it is not currently possible for the RADIUS server to specify 56 bit
5564 .It RAD_MICROSOFT_MS_MPPE_RECV_KEY
5566 .Dv RAD_VENDOR_MICROSOFT
5567 vendor specific attribute is supplied, it is value is used as the master
5568 key for decryption of incoming data.
5569 When clients are authenticated using
5570 MSCHAPv2, the RADIUS server MUST provide this attribute if inbound MPPE is
5572 .It RAD_MICROSOFT_MS_MPPE_SEND_KEY
5574 .Dv RAD_VENDOR_MICROSOFT
5575 vendor specific attribute is supplied, it is value is used as the master
5576 key for encryption of outgoing data.
5577 When clients are authenticated using
5578 MSCHAPv2, the RADIUS server MUST provide this attribute if outbound MPPE is
5582 Values received from the RADIUS server may be viewed using
5584 .It set rad_alive Ar timeout
5585 When RADIUS is configured, setting
5591 to sent RADIUS accounting information to the RADIUS server every
5594 .It set rad_port_id Ar option
5595 When RADIUS is configured, setting the
5597 value allows to specify what should be sent to the RADIUS server as
5605 PID of the corresponding tunnel.
5610 index of the interface as returned by
5611 .Xr if_nametoindex 3 .
5613 keeps the default behavior.
5615 .It set reconnect Ar timeout ntries
5616 Should the line drop unexpectedly (due to loss of CD or LQR
5617 failure), a connection will be re-established after the given
5619 The line will be re-connected at most
5628 will result in a variable pause, somewhere between 1 and 30 seconds.
5629 .It set recvpipe Op Ar value
5630 This sets the routing table RECVPIPE value.
5631 The optimum value is just over twice the MTU value.
5634 is unspecified or zero, the default kernel controlled value is used.
5635 .It set redial Ar secs Ns Xo
5638 .Oc Ns Op . Ns Ar next
5642 can be instructed to attempt to redial
5645 If more than one phone number is specified (see
5649 is taken before dialing each number.
5652 is taken before starting at the first number again.
5655 may be used here in place of
5659 causing a random delay of between 1 and 30 seconds.
5663 is specified, its value is added onto
5669 will only be incremented at most
5677 delay will be effective, even after
5679 has been exceeded, so an immediate manual dial may appear to have
5681 If an immediate dial is required, a
5683 should immediately follow the
5688 description above for further details.
5689 .It set sendpipe Op Ar value
5690 This sets the routing table SENDPIPE value.
5691 The optimum value is just over twice the MTU value.
5694 is unspecified or zero, the default kernel controlled value is used.
5695 .It "set server|socket" Ar TcpPort Ns No \&| Ns Xo
5696 .Ar LocalName Ns No |none|open|closed
5697 .Op password Op Ar mask
5701 to listen on the given socket or
5703 for incoming command connections.
5709 to close any existing socket and clear the socket configuration.
5714 to attempt to re-open the port.
5719 to close the open port.
5721 If you wish to specify a local domain socket,
5723 must be specified as an absolute file name, otherwise it is assumed
5724 to be the name or number of a TCP port.
5725 You may specify the octal umask to be used with a local domain socket.
5731 for details of how to translate TCP port names.
5733 You must also specify the password that must be entered by the client
5736 variable above) when connecting to this socket.
5738 specified as an empty string, no password is required for connecting clients.
5740 When specifying a local domain socket, the first
5742 sequence found in the socket name will be replaced with the current
5743 interface unit number.
5744 This is useful when you wish to use the same
5745 profile for more than one connection.
5747 In a similar manner TCP sockets may be prefixed with the
5749 character, in which case the current interface unit number is added to
5754 with a server socket, the
5756 command is the preferred mechanism of communications.
5759 can also be used, but link encryption may be implemented in the future, so
5767 interact with the diagnostic socket.
5768 .It set speed Ar value
5769 This sets the speed of the serial device.
5770 If speed is specified as
5773 treats the device as a synchronous device.
5775 Certain device types will know whether they should be specified as
5776 synchronous or asynchronous.
5777 These devices will override incorrect
5778 settings and log a warning to this effect.
5779 .It set stopped Op Ar LCPseconds Op Ar CCPseconds
5780 If this option is set,
5782 will time out after the given FSM (Finite State Machine) has been in
5783 the stopped state for the given number of
5785 This option may be useful if the peer sends a terminate request,
5786 but never actually closes the connection despite our sending a terminate
5788 This is also useful if you wish to
5789 .Dq set openmode passive
5790 and time out if the peer does not send a Configure Request within the
5793 .Dq set log +lcp +ccp
5796 log the appropriate state transitions.
5798 The default value is zero, where
5800 does not time out in the stopped state.
5802 This value should not be set to less than the openmode delay (see
5805 .It set timeout Ar idleseconds Op Ar mintimeout
5806 This command allows the setting of the idle timer.
5807 Refer to the section titled
5808 .Sx SETTING THE IDLE TIMER
5809 for further details.
5815 will never idle out before the link has been up for at least that number
5823 This command controls the ports that
5825 prioritizes when transmitting data.
5826 The default priority TCP ports
5827 are ports 21 (ftp control), 22 (ssh), 23 (telnet), 513 (login), 514 (shell),
5828 543 (klogin) and 544 (kshell).
5829 There are no priority UDP ports by default.
5844 are given, the priority port lists are cleared (although if
5848 is specified, only that list is cleared).
5851 argument is prefixed with a plus
5855 the current list is adjusted, otherwise the list is reassigned.
5857 prefixed with a plus or not prefixed at all are added to the list and
5859 prefixed with a minus are removed from the list.
5863 is specified, all priority port lists are disabled and even
5865 packets are not prioritised.
5866 .It set vj slotcomp on|off
5869 whether it should attempt to negotiate VJ slot compression.
5870 By default, slot compression is turned
5872 .It set vj slots Ar nslots
5873 This command sets the initial number of slots that
5875 will try to negotiate with the peer when VJ compression is enabled (see the
5878 It defaults to a value of 16.
5887 .It shell|! Op Ar command
5890 is not specified a shell is invoked according to the
5892 environment variable.
5893 Otherwise, the given
5896 Word replacement is done in the same way as for the
5898 command as described above.
5900 Use of the !\& character
5901 requires a following space as with any of the other commands.
5902 You should note that this command is executed in the foreground;
5904 will not continue running until this process has exited.
5907 command if you wish processing to happen in the background.
5909 This command allows the user to examine the following:
5912 Show the current bundle settings.
5914 Show the current CCP compression statistics.
5916 Show the current VJ compression statistics.
5918 Show the current escape characters.
5919 .It show filter Op Ar name
5920 List the current rules for the given filter.
5923 is not specified, all filters are shown.
5925 Show the current HDLC statistics.
5927 Give a summary of available show commands.
5929 Show the current interface information
5933 Show the current IPCP statistics.
5935 Show the protocol layers currently in use.
5937 Show the current LCP statistics.
5938 .It show Op data Ns Xo
5941 Show high level link information.
5943 Show a list of available logical links.
5945 Show the current log values.
5947 Show current memory statistics.
5949 Show the current NCP statistics.
5951 Show low level link information.
5953 Show Multi-link information.
5955 Show current protocol totals.
5957 Show the current routing tables.
5959 Show the current stopped timeouts.
5961 Show the active alarm timers.
5963 Show the current version number of
5968 Go into terminal mode.
5969 Characters typed at the keyboard are sent to the device.
5970 Characters read from the device are displayed on the screen.
5975 automatically enables Packet Mode and goes back into command mode.
5980 Read the example configuration files.
5981 They are a good source of information.
5990 to get online information about what is available.
5992 The following URLs contain useful information:
5993 .Bl -bullet -compact
5995 http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/faq/ppp.html
5997 http://www.FreeBSD.org/doc/handbook/userppp.html
6003 refers to four files:
6009 These files are placed in the
6013 .It Pa /etc/ppp/ppp.conf
6014 System default configuration file.
6015 .It Pa /etc/ppp/ppp.secret
6016 An authorisation file for each system.
6017 .It Pa /etc/ppp/ppp.linkup
6018 A file to check when
6020 establishes a network level connection.
6021 .It Pa /etc/ppp/ppp.linkdown
6022 A file to check when
6024 closes a network level connection.
6025 .It Pa /var/log/ppp.log
6026 Logging and debugging information file.
6027 Note, this name is specified in
6028 .Pa /etc/syslog.conf .
6031 for further details.
6032 .It Pa /var/spool/lock/LCK..*
6033 tty port locking file.
6036 for further details.
6037 .It Pa /var/run/tunN.pid
6038 The process id (pid) of the
6040 program connected to the tunN device, where
6042 is the number of the device.
6043 .It Pa /var/run/ttyXX.if
6044 The tun interface used by this port.
6045 Again, this file is only created in
6051 .It Pa /etc/services
6052 Get port number if port number is using service name.
6053 .It Pa /var/run/ppp-authname-class-value
6054 In multi-link mode, local domain sockets are created using the peer
6057 the peer endpoint discriminator class
6059 and the peer endpoint discriminator value
6061 As the endpoint discriminator value may be a binary value, it is turned
6062 to HEX to determine the actual file name.
6064 This socket is used to pass links between different instances of
6078 ifdef({LOCALNAT},{},{.Xr libalias 3 ,
6080 ifdef({LOCALRAD},{},{.Xr libradius 3 ,
6108 This program was originally written by
6109 .An Toshiharu OHNO Aq tony-o@iij.ad.jp ,
6110 and was submitted to
6113 .An Atsushi Murai Aq amurai@spec.co.jp .
6115 It was substantially modified during 1997 by
6116 .An Brian Somers Aq brian@Awfulhak.org ,
6119 in November that year
6120 (just after the 2.2 release).
6122 Most of the code was rewritten by
6124 in early 1998 when multi-link ppp support was added.
projects / FreeBSD / releng / 9.2.git / blob