7 .Nd Point to Point Protocol (a.k.a. user-ppp)
16 This is a user process
21 is implemented as a part of the kernel (e.g., as managed by
23 and it's thus somewhat hard to debug and/or modify its behaviour.
24 However, in this implementation
26 is done as a user process with the help of the
27 tunnel device driver (tun).
33 flag for backwards compatibility) does the equivalent of a
37 network address translation features.
40 to act as a NAT or masquerading engine for all machines on an internal
50 to be silent at startup rather than displaying the mode and interface
57 to only attempt to open
58 .Pa /dev/tun Ns Ar N .
61 will start with a value of 0 for
63 and keep trying to open a tunnel device by incrementing the value of
65 by one each time until it succeeds.
66 If it fails three times in a row
67 because the device file is missing, it gives up.
73 .Bl -tag -width XXX -offset XXX
76 opens the tun interface, configures it then goes into the background.
77 The link isn't brought up until outgoing data is detected on the tun
78 interface at which point
80 attempts to bring up the link.
81 Packets received (including the first one) while
83 is trying to bring the link up will remain queued for a default of
93 must be given on the command line (see below) and a
95 must be done in the system profile that specifies a peer IP address to
96 use when configuring the interface.
99 is usually appropriate.
103 .Pa /usr/share/examples/ppp/ppp.conf.sample
108 attempts to establish a connection with the peer immediately.
111 goes into the background and the parent process returns an exit code
115 exits with a non-zero result.
119 attempts to establish a connection with the peer immediately, but never
121 The link is created in background mode.
122 This is useful if you wish to control
124 invocation from another process.
126 This is used for receiving incoming connections.
130 line and uses descriptor 0 as the link.
132 If callback is configured,
136 information when dialing back.
138 This option is designed for machines connected with a dedicated
141 will always keep the device open and will never use any configured
144 This mode is equivalent to
148 will bring the link back up any time it's dropped for any reason.
150 This is a no-op, and gives the same behaviour as if none of the above
151 modes have been specified.
153 loads any sections specified on the command line then provides an
157 One or more configuration entries or systems
158 .Pq as specified in Pa /etc/ppp/ppp.conf
159 may also be specified on the command line.
164 .Pa /etc/ppp/ppp.conf
165 at startup, followed by each of the systems specified on the command line.
168 .It Provides an interactive user interface.
169 Using its command mode, the user can
170 easily enter commands to establish the connection with the remote end, check
171 the status of connection and close the connection.
172 All functions can also be optionally password protected for security.
173 .It Supports both manual and automatic dialing.
174 Interactive mode has a
176 command which enables you to talk to the device directly.
177 When you are connected to the remote peer and it starts to talk
180 detects it and switches to packet mode automatically.
182 determined the proper sequence for connecting with the remote host, you
183 can write a chat script to define the necessary dialing and login
184 procedure for later convenience.
185 .It Supports on-demand dialup capability.
190 will act as a daemon and wait for a packet to be sent over the
193 When this happens, the daemon automatically dials and establishes the
195 In almost the same manner
197 mode (direct-dial mode) also automatically dials and establishes the
199 However, it differs in that it will dial the remote site
200 any time it detects the link is down, even if there are no packets to be
202 This mode is useful for full-time connections where we worry less
203 about line charges and more about being connected full time.
206 mode is also available.
207 This mode is targeted at a dedicated link between two machines.
209 will never voluntarily quit from dedicated mode - you must send it the
211 command via its diagnostic socket.
214 will force an LCP renegotiation, and a
216 will force it to exit.
217 .It Supports client callback.
219 can use either the standard LCP callback protocol or the Microsoft
220 CallBack Control Protocol (ftp://ftp.microsoft.com/developr/rfc/cbcp.txt).
221 .It Supports NAT or packet aliasing.
222 Packet aliasing (a.k.a. IP masquerading) allows computers on a
223 private, unregistered network to access the Internet.
226 host acts as a masquerading gateway.
227 IP addresses as well as TCP and
228 UDP port numbers are aliased for outgoing packets and de-aliased for
230 .It Supports background PPP connections.
231 In background mode, if
233 successfully establishes the connection, it will become a daemon.
234 Otherwise, it will exit with an error.
235 This allows the setup of
236 scripts that wish to execute certain commands only if the connection
237 is successfully established.
238 .It Supports server-side PPP connections.
241 acts as server which accepts incoming
243 connections on stdin/stdout.
244 .It "Supports PAP and CHAP (rfc 1994, 2433 and 2759) authentication.
245 With PAP or CHAP, it is possible to skip the Unix style
247 procedure, and use the
249 protocol for authentication instead.
250 If the peer requests Microsoft CHAP authentication and
252 is compiled with DES support, an appropriate MD4/DES response will be
254 .It Supports RADIUS (rfc 2138) authentication.
255 An extension to PAP and CHAP,
262 allows authentication information to be stored in a central or
263 distributed database along with various per-user framed connection
267 is available at compile time,
271 requests when configured to do so.
272 .It Supports Proxy Arp.
274 can be configured to make one or more proxy arp entries on behalf of
276 This allows routing from the peer to the LAN without
277 configuring each machine on that LAN.
278 .It Supports packet filtering.
279 User can define four kinds of filters: the
281 filter for incoming packets, the
283 filter for outgoing packets, the
285 filter to define a dialing trigger packet and the
287 filter for keeping a connection alive with the trigger packet.
288 .It Tunnel driver supports bpf.
291 to check the packet flow over the
294 .It Supports PPP over TCP and PPP over UDP.
295 If a device name is specified as
296 .Em host Ns No : Ns Em port Ns
301 will open a TCP or UDP connection for transporting data rather than using a
302 conventional serial device.
303 UDP connections force
305 into synchronous mode.
306 .It Supports PPP over ISDN.
309 is given a raw B-channel i4b device to open as a link, it's able to talk
312 daemon to establish an ISDN connection.
313 .It Supports PPP over Ethernet (rfc 2516).
316 is given a device specification of the format
317 .No PPPoE: Ns Ar iface Ns Xo
318 .Op \&: Ns Ar provider Ns
331 .It "Supports IETF draft Predictor-1 (rfc 1978) and DEFLATE (rfc 1979) compression."
333 supports not only VJ-compression but also Predictor-1 and DEFLATE compression.
334 Normally, a modem has built-in compression (e.g., v42.bis) and the system
335 may receive higher data rates from it as a result of such compression.
336 While this is generally a good thing in most other situations, this
337 higher speed data imposes a penalty on the system by increasing the
338 number of serial interrupts the system has to process in talking to the
339 modem and also increases latency.
340 Unlike VJ-compression, Predictor-1 and DEFLATE compression pre-compresses
342 network traffic flowing through the link, thus reducing overheads to a
344 .It Supports Microsoft's IPCP extensions (rfc 1877).
345 Name Server Addresses and NetBIOS Name Server Addresses can be negotiated
346 with clients using the Microsoft
348 stack (i.e., Win95, WinNT)
349 .It Supports Multi-link PPP (rfc 1990)
350 It is possible to configure
352 to open more than one physical connection to the peer, combining the
353 bandwidth of all links for better throughput.
354 .It Supports MPPE (draft-ietf-pppext-mppe)
355 MPPE is Microsoft Point to Point Encryption scheme. It is possible to configure
357 to participate in Microsoft's Windows VPN. For now,
359 can only get encryption keys from CHAP 81 authentication.
361 must be compiled with DES for MPPE to operate.
373 will not run if the invoking user id is not zero.
374 This may be overridden by using the
377 .Pa /etc/ppp/ppp.conf .
378 When running as a normal user,
380 switches to user id 0 in order to alter the system routing table, set up
381 system lock files and read the ppp configuration files.
382 All external commands (executed via the "shell" or "!bg" commands) are executed
383 as the user id that invoked
387 logging facility if you're interested in what exactly is done as user id
392 you may need to deal with some initial configuration details.
395 Your kernel must include a tunnel device (the GENERIC kernel includes
397 If it doesn't, or if you require more than one tun
398 interface, you'll need to rebuild your kernel with the following line in
399 your kernel configuration file:
401 .Dl pseudo-device tun N
405 is the maximum number of
407 connections you wish to support.
411 directory for the tunnel device entries
415 represents the number of the tun device, starting at zero.
416 If they don't exist, you can create them by running "sh ./MAKEDEV tunN".
417 This will create tun devices 0 through
420 Make sure that your system has a group named
424 file and that the group contains the names of all users expected to use
428 manual page for details.
429 Each of these users must also be given access using the
432 .Pa /etc/ppp/ppp.conf .
439 A common log file name is
440 .Pa /var/log/ppp.log .
441 To make output go to this file, put the following lines in the
444 .Bd -literal -offset indent
446 *.*<TAB>/var/log/ppp.log
449 It is possible to have more than one
451 log file by creating a link to the
459 .Bd -literal -offset indent
461 *.*<TAB>/var/log/ppp0.log
465 .Pa /etc/syslog.conf .
466 Don't forget to send a
471 .Pa /etc/syslog.conf .
473 Although not strictly relevant to
475 operation, you should configure your resolver so that it works correctly.
476 This can be done by configuring a local DNS
478 or by adding the correct
481 .Pa /etc/resolv.conf .
484 manual page for details.
486 Alternatively, if the peer supports it,
488 can be configured to ask the peer for the nameserver address(es) and to
496 commands below for details.
499 In the following examples, we assume that your machine name is
505 above) with no arguments, you are presented with a prompt:
506 .Bd -literal -offset indent
512 part of your prompt should always be in upper case.
513 If it is in lower case, it means that you must supply a password using the
516 This only ever happens if you connect to a running version of
518 and have not authenticated yourself using the correct password.
520 You can start by specifying the device name and speed:
521 .Bd -literal -offset indent
522 ppp ON awfulhak> set device /dev/cuaa0
523 ppp ON awfulhak> set speed 38400
526 Normally, hardware flow control (CTS/RTS) is used.
528 certain circumstances (as may happen when you are connected directly
529 to certain PPP-capable terminal servers), this may result in
531 hanging as soon as it tries to write data to your communications link
532 as it is waiting for the CTS (clear to send) signal - which will never
534 Thus, if you have a direct line and can't seem to make a
535 connection, try turning CTS/RTS off with
537 If you need to do this, check the
539 description below too - you'll probably need to
540 .Dq set accmap 000a0000 .
542 Usually, parity is set to
547 Parity is a rather archaic error checking mechanism that is no
548 longer used because modern modems do their own error checking, and most
549 link-layer protocols (that's what
551 is) use much more reliable checking mechanisms.
552 Parity has a relatively
553 huge overhead (a 12.5% increase in traffic) and as a result, it is always
559 However, some ISPs (Internet Service Providers) may use
560 specific parity settings at connection time (before
563 Notably, Compuserve insist on even parity when logging in:
564 .Bd -literal -offset indent
565 ppp ON awfulhak> set parity even
568 You can now see what your current device settings look like:
569 .Bd -literal -offset indent
570 ppp ON awfulhak> show physical
574 Link Type: interactive
580 Device List: /dev/cuaa0
581 Characteristics: 38400bps, cs8, even parity, CTS/RTS on
584 0 octets in, 0 octets out
589 The term command can now be used to talk directly to the device:
590 .Bd -literal -offset indent
591 ppp ON awfulhak> term
597 Password: myisppassword
601 When the peer starts to talk in
604 detects this automatically and returns to command mode.
605 .Bd -literal -offset indent
606 ppp ON awfulhak> # No link has been established
607 Ppp ON awfulhak> # We've connected & finished LCP
608 PPp ON awfulhak> # We've authenticated
609 PPP ON awfulhak> # We've agreed IP numbers
612 If it does not, it's probable that the peer is waiting for your end to
618 configuration packets to the peer, use the
620 command to drop out of terminal mode and enter packet mode.
622 If you never even receive a login prompt, it is quite likely that the
623 peer wants to use PAP or CHAP authentication instead of using Unix-style
624 login/password authentication.
625 To set things up properly, drop back to
626 the prompt and set your authentication name and key, then reconnect:
627 .Bd -literal -offset indent
629 ppp ON awfulhak> set authname myispusername
630 ppp ON awfulhak> set authkey myisppassword
631 ppp ON awfulhak> term
638 You may need to tell ppp to initiate negotiations with the peer here too:
639 .Bd -literal -offset indent
641 ppp ON awfulhak> # No link has been established
642 Ppp ON awfulhak> # We've connected & finished LCP
643 PPp ON awfulhak> # We've authenticated
644 PPP ON awfulhak> # We've agreed IP numbers
647 You are now connected!
650 in the prompt has changed to capital letters to indicate that you have
652 If only some of the three Ps go uppercase, wait until
653 either everything is uppercase or lowercase.
654 If they revert to lowercase, it means that
656 couldn't successfully negotiate with the peer.
657 A good first step for troubleshooting at this point would be to
658 .Bd -literal -offset indent
659 ppp ON awfulhak> set log local phase lcp ipcp
665 command description below for further details.
666 If things fail at this point,
667 it is quite important that you turn logging on and try again.
669 important that you note any prompt changes and report them to anyone trying
672 When the link is established, the show command can be used to see how
674 .Bd -literal -offset indent
675 PPP ON awfulhak> show physical
676 * Modem related information is shown here *
677 PPP ON awfulhak> show ccp
678 * CCP (compression) related information is shown here *
679 PPP ON awfulhak> show lcp
680 * LCP (line control) related information is shown here *
681 PPP ON awfulhak> show ipcp
682 * IPCP (IP) related information is shown here *
683 PPP ON awfulhak> show link
684 * Link (high level) related information is shown here *
685 PPP ON awfulhak> show bundle
686 * Logical (high level) connection related information is shown here *
689 At this point, your machine has a host route to the peer.
691 that you can only make a connection with the host on the other side
693 If you want to add a default route entry (telling your
694 machine to send all packets without another routing entry to the other
697 link), enter the following command:
698 .Bd -literal -offset indent
699 PPP ON awfulhak> add default HISADDR
704 represents the IP address of the connected peer.
707 command fails due to an existing route, you can overwrite the existing
709 .Bd -literal -offset indent
710 PPP ON awfulhak> add! default HISADDR
713 This command can also be executed before actually making the connection.
714 If a new IP address is negotiated at connection time,
716 will update your default route accordingly.
718 You can now use your network applications (ping, telnet, ftp etc.)
719 in other windows or terminals on your machine.
720 If you wish to reuse the current terminal, you can put
722 into the background using your standard shell suspend and background
730 section for details on all available commands.
731 .Sh AUTOMATIC DIALING
732 To use automatic dialing, you must prepare some Dial and Login chat scripts.
733 See the example definitions in
734 .Pa /usr/share/examples/ppp/ppp.conf.sample
736 .Pa /etc/ppp/ppp.conf
738 Each line contains one comment, inclusion, label or command:
741 A line starting with a
743 character is treated as a comment line.
744 Leading whitespace are ignored when identifying comment lines.
746 An inclusion is a line beginning with the word
748 It must have one argument - the file to include.
750 .Dq !include ~/.ppp.conf
751 for compatibility with older versions of
754 A label name starts in the first column and is followed by
758 A command line must contain a space or tab in the first column.
762 .Pa /etc/ppp/ppp.conf
763 file should consist of at least a
766 This section is always executed.
767 It should also contain
768 one or more sections, named according to their purpose, for example,
770 would represent your ISP, and
772 would represent an incoming
775 You can now specify the destination label name when you invoke
777 Commands associated with the
779 label are executed, followed by those associated with the destination
783 is started with no arguments, the
785 section is still executed.
786 The load command can be used to manually load a section from the
787 .Pa /etc/ppp/ppp.conf
789 .Bd -literal -offset indent
790 ppp ON awfulhak> load MyISP
793 Note, no action is taken by
795 after a section is loaded, whether it's the result of passing a label on
796 the command line or using the
799 Only the commands specified for that label in the configuration
801 However, when invoking
808 switches, the link mode tells
810 to establish a connection.
813 command below for further details.
815 Once the connection is made, the
817 portion of the prompt will change to
819 .Bd -literal -offset indent
822 ppp ON awfulhak> dial
828 The Ppp prompt indicates that
830 has entered the authentication phase.
831 The PPp prompt indicates that
833 has entered the network phase.
834 The PPP prompt indicates that
836 has successfully negotiated a network layer protocol and is in
840 .Pa /etc/ppp/ppp.linkup
841 file is available, its contents are executed
844 connection is established.
848 .Pa /usr/share/examples/ppp/ppp.conf.sample
849 which runs a script in the background after the connection is established
854 commands below for a description of possible substitution strings).
855 Similarly, when a connection is closed, the contents of the
856 .Pa /etc/ppp/ppp.linkdown
858 Both of these files have the same format as
859 .Pa /etc/ppp/ppp.conf .
861 In previous versions of
863 it was necessary to re-add routes such as the default route in the
869 where all routes that contain the
873 literals will automatically be updated when the values of
878 .Sh BACKGROUND DIALING
879 If you want to establish a connection using
881 non-interactively (such as from a
885 job) you should use the
892 attempts to establish the connection immediately.
894 numbers are specified, each phone number will be tried once.
895 If the attempt fails,
897 exits immediately with a non-zero exit code.
900 becomes a daemon, and returns an exit status of zero to its caller.
901 The daemon exits automatically if the connection is dropped by the
902 remote system, or it receives a
906 Demand dialing is enabled with the
911 You must also specify the destination label in
912 .Pa /etc/ppp/ppp.conf
916 command to define the remote peers IP address.
918 .Pa /usr/share/examples/ppp/ppp.conf.sample )
919 .Bd -literal -offset indent
929 runs as a daemon but you can still configure or examine its
930 configuration by using the
933 .Pa /etc/ppp/ppp.conf ,
934 .Pq for example, Dq set server +3000 mypasswd
935 and connecting to the diagnostic port as follows:
936 .Bd -literal -offset indent
937 # pppctl 3000 (assuming tun0)
939 PPP ON awfulhak> show who
940 tcp (127.0.0.1:1028) *
945 command lists users that are currently connected to
948 If the diagnostic socket is closed or changed to a different
949 socket, all connections are immediately dropped.
953 mode, when an outgoing packet is detected,
955 will perform the dialing action (chat script) and try to connect
959 mode, the dialing action is performed any time the line is found
961 If the connect fails, the default behaviour is to wait 30 seconds
962 and then attempt to connect when another outgoing packet is detected.
963 This behaviour can be changed using the
967 .No set redial Ar secs Ns Xo
970 .Oc Ns Op . Ns Ar next
974 .Bl -tag -width attempts -compact
976 is the number of seconds to wait before attempting
978 If the argument is the literal string
980 the delay period is a random value between 1 and 30 seconds inclusive.
982 is the number of seconds that
984 should be incremented each time a new dial attempt is made.
985 The timeout reverts to
987 only after a successful connection is established.
988 The default value for
992 is the maximum number of times
996 The default value for
1000 is the number of seconds to wait before attempting
1001 to dial the next number in a list of numbers (see the
1004 The default is 3 seconds.
1005 Again, if the argument is the literal string
1007 the delay period is a random value between 1 and 30 seconds.
1009 is the maximum number of times to try to connect for each outgoing packet
1010 that triggers a dial.
1011 The previous value is unchanged if this parameter is omitted.
1012 If a value of zero is specified for
1015 will keep trying until a connection is made.
1019 .Bd -literal -offset indent
1023 will attempt to connect 4 times for each outgoing packet that causes
1024 a dial attempt with a 3 second delay between each number and a 10 second
1025 delay after all numbers have been tried.
1026 If multiple phone numbers
1027 are specified, the total number of attempts is still 4 (it does not
1028 attempt each number 4 times).
1032 .Bd -literal -offset indent
1033 set redial 10+10-5.3 20
1038 to attempt to connect 20 times.
1039 After the first attempt,
1041 pauses for 10 seconds.
1042 After the next attempt it pauses for 20 seconds
1043 and so on until after the sixth attempt it pauses for 1 minute.
1044 The next 14 pauses will also have a duration of one minute.
1047 connects, disconnects and fails to connect again, the timeout starts again
1050 Modifying the dial delay is very useful when running
1054 mode on both ends of the link.
1055 If each end has the same timeout,
1056 both ends wind up calling each other at the same time if the link
1057 drops and both ends have packets queued.
1058 At some locations, the serial link may not be reliable, and carrier
1059 may be lost at inappropriate times.
1060 It is possible to have
1062 redial should carrier be unexpectedly lost during a session.
1063 .Bd -literal -offset indent
1064 set reconnect timeout ntries
1069 to re-establish the connection
1071 times on loss of carrier with a pause of
1073 seconds before each try.
1075 .Bd -literal -offset indent
1081 that on an unexpected loss of carrier, it should wait
1083 seconds before attempting to reconnect.
1084 This may happen up to
1089 The default value of ntries is zero (no reconnect).
1090 Care should be taken with this option.
1091 If the local timeout is slightly
1092 longer than the remote timeout, the reconnect feature will always be
1093 triggered (up to the given number of times) after the remote side
1094 times out and hangs up.
1095 NOTE: In this context, losing too many LQRs constitutes a loss of
1096 carrier and will trigger a reconnect.
1099 flag is specified, all phone numbers are dialed at most once until
1100 a connection is made.
1101 The next number redial period specified with the
1103 command is honoured, as is the reconnect tries value.
1105 value is less than the number of phone numbers specified, not all
1106 the specified numbers will be tried.
1107 To terminate the program, type
1108 .Bd -literal -offset indent
1109 PPP ON awfulhak> close
1110 ppp ON awfulhak> quit all
1115 command will terminate the
1119 connection but not the
1127 .Sh RECEIVING INCOMING PPP CONNECTIONS (Method 1)
1128 To handle an incoming
1130 connection request, follow these steps:
1133 Make sure the modem and (optionally)
1135 is configured correctly.
1136 .Bl -bullet -compact
1138 Use Hardware Handshake (CTS/RTS) for flow control.
1140 Modem should be set to NO echo back (ATE0) and NO results string (ATQ1).
1148 on the port where the modem is attached.
1151 .Dl ttyd1 "/usr/libexec/getty std.38400" dialup on secure
1153 Don't forget to send a
1157 process to start the
1163 .Pa /usr/local/bin/ppplogin
1164 file with the following contents:
1165 .Bd -literal -offset indent
1167 exec /usr/sbin/ppp -direct incoming
1174 work with stdin and stdout.
1177 to connect to a configured diagnostic port, in the same manner as with
1183 section must be set up in
1184 .Pa /etc/ppp/ppp.conf .
1188 section contains the
1190 command as appropriate.
1192 Prepare an account for the incoming user.
1194 ppp:xxxx:66:66:PPP Login User:/home/ppp:/usr/local/bin/ppplogin
1197 Refer to the manual entries for
1203 Support for IPCP Domain Name Server and NetBIOS Name Server negotiation
1204 can be enabled using the
1209 Refer to their descriptions below.
1212 .Sh RECEIVING INCOMING PPP CONNECTIONS (Method 2)
1213 This method differs in that we use
1215 to authenticate the connection rather than
1219 Configure your default section in
1221 with automatic ppp recognition by specifying the
1226 :pp=/usr/local/bin/ppplogin:\\
1230 Configure your serial device(s), enable a
1233 .Pa /usr/local/bin/ppplogin
1234 as in the first three steps for method 1 above.
1242 .Pa /etc/ppp/ppp.conf
1245 label (or whatever label
1250 .Pa /etc/ppp/ppp.secret
1251 for each incoming user:
1260 detects a ppp connection (by recognising the HDLC frame headers), it runs
1261 .Dq /usr/local/bin/ppplogin .
1265 that either PAP or CHAP are enabled as above.
1266 If they are not, you are
1267 allowing anybody to establish ppp session with your machine
1269 a password, opening yourself up to all sorts of potential attacks.
1270 .Sh AUTHENTICATING INCOMING CONNECTIONS
1271 Normally, the receiver of a connection requires that the peer
1272 authenticates itself.
1273 This may be done using
1275 but alternatively, you can use PAP or CHAP.
1276 CHAP is the more secure of the two, but some clients may not support it.
1277 Once you decide which you wish to use, add the command
1281 to the relevant section of
1284 You must then configure the
1285 .Pa /etc/ppp/ppp.secret
1287 This file contains one line per possible client, each line
1288 containing up to five fields:
1291 .Ar hisaddr Op Ar label Op Ar callback-number
1298 specify the client username and password.
1303 and PAP is being used,
1305 will look up the password database
1307 when authenticating.
1308 If the client does not offer a suitable response based on any
1309 .Ar name Ns No / Ns Ar key
1312 authentication fails.
1314 If authentication is successful,
1317 is used when negotiating IP numbers.
1320 command for details.
1322 If authentication is successful and
1324 is specified, the current system label is changed to match the given
1326 This will change the subsequent parsing of the
1332 If authentication is successful and
1338 the client will be called back on the given number.
1339 If CBCP is being used,
1341 may also contain a list of numbers or a
1346 The value will be used in
1348 subsequent CBCP phase.
1349 .Sh PPP OVER TCP and UDP (a.k.a Tunnelling)
1352 over a serial link, it is possible to
1353 use a TCP connection instead by specifying the host, port and protocol as the
1356 .Dl set device ui-gate:6669/tcp
1358 Instead of opening a serial device,
1360 will open a TCP connection to the given machine on the given
1362 It should be noted however that
1364 doesn't use the telnet protocol and will be unable to negotiate
1365 with a telnet server.
1366 You should set up a port for receiving this
1368 connection on the receiving machine (ui-gate).
1369 This is done by first updating
1371 to name the service:
1373 .Dl ppp-in 6669/tcp # Incoming PPP connections over TCP
1379 how to deal with incoming connections on that port:
1381 .Dl ppp-in stream tcp nowait root /usr/sbin/ppp ppp -direct ppp-in
1383 Don't forget to send a
1387 after you've updated
1388 .Pa /etc/inetd.conf .
1389 Here, we use a label named
1392 .Pa /etc/ppp/ppp.conf
1393 on ui-gate (the receiver) should contain the following:
1394 .Bd -literal -offset indent
1397 set ifaddr 10.0.4.1 10.0.4.2
1401 .Pa /etc/ppp/ppp.linkup
1403 .Bd -literal -offset indent
1405 add 10.0.1.0/24 HISADDR
1408 It is necessary to put the
1412 to ensure that the route is only added after
1414 has negotiated and assigned addresses to its interface.
1416 You may also want to enable PAP or CHAP for security.
1417 To enable PAP, add the following line:
1418 .Bd -literal -offset indent
1422 You'll also need to create the following entry in
1423 .Pa /etc/ppp/ppp.secret :
1424 .Bd -literal -offset indent
1425 MyAuthName MyAuthPasswd
1432 the password is looked up in the
1437 .Pa /etc/ppp/ppp.conf
1438 on awfulhak (the initiator) should contain the following:
1439 .Bd -literal -offset indent
1442 set device ui-gate:ppp-in/tcp
1445 set log Phase Chat Connect hdlc LCP IPCP CCP tun
1446 set ifaddr 10.0.4.2 10.0.4.1
1449 with the route setup in
1450 .Pa /etc/ppp/ppp.linkup :
1451 .Bd -literal -offset indent
1453 add 10.0.2.0/24 HISADDR
1456 Again, if you're enabling PAP, you'll also need this in the
1457 .Pa /etc/ppp/ppp.conf
1459 .Bd -literal -offset indent
1460 set authname MyAuthName
1461 set authkey MyAuthKey
1464 We're assigning the address of 10.0.4.1 to ui-gate, and the address
1465 10.0.4.2 to awfulhak.
1466 To open the connection, just type
1468 .Dl awfulhak # ppp -background ui-gate
1470 The result will be an additional "route" on awfulhak to the
1471 10.0.2.0/24 network via the TCP connection, and an additional
1472 "route" on ui-gate to the 10.0.1.0/24 network.
1473 The networks are effectively bridged - the underlying TCP
1474 connection may be across a public network (such as the
1477 traffic is conceptually encapsulated
1478 (although not packet by packet) inside the TCP stream between
1481 The major disadvantage of this mechanism is that there are two
1482 "guaranteed delivery" mechanisms in place - the underlying TCP
1483 stream and whatever protocol is used over the
1485 link - probably TCP again.
1486 If packets are lost, both levels will
1487 get in each others way trying to negotiate sending of the missing
1490 To avoid this overhead, it is also possible to do all this using
1491 UDP instead of TCP as the transport by simply changing the protocol
1492 from "tcp" to "udp".
1493 When using UDP as a transport,
1495 will operate in synchronous mode.
1496 This is another gain as the incoming
1497 data does not have to be rearranged into packets.
1499 Care should be taken when adding a default route through a tunneled
1501 It is quite common for the default route
1502 .Pq added in Pa /etc/ppp/ppp.linkup
1503 to end up routing the link's TCP connection through the tunnel,
1504 effectively garrotting the connection.
1505 To avoid this, make sure you add a static route for the benefit of
1507 .Bd -literal -offset indent
1510 set device ui-gate:ppp-in/tcp
1517 is the IP number that your route to
1521 When routing your connection accross a public network such as the Internet,
1522 it is preferable to encrypt the data.
1523 This can be done with the help of the MPPE protocol, although currently this
1524 means that you will not be able to also compress the traffic as MPPE is
1525 implemented as a compression layer (thank Microsoft for this).
1526 To enable MPPE encryption, add the following lines to
1527 .Pa /etc/ppp/ppp.conf
1529 .Bd -literal -offset indent
1531 disable deflate pred1
1535 ensuring that you've put the requisite entry in
1536 .Pa /etc/ppp/ppp.secret
1537 (MSCHAPv2 is challenge based, so
1541 MSCHAPv2 and MPPE are accepted by default, so the client end should work
1542 without any additional changes (although ensure you have
1548 .Sh NETWORK ADDRESS TRANSLATION (PACKET ALIASING)
1552 command line option enables network address translation (a.k.a. packet
1556 host to act as a masquerading gateway for other computers over
1557 a local area network.
1558 Outgoing IP packets are aliased so that they appear to come from the
1560 host, and incoming packets are de-aliased so that they are routed
1561 to the correct machine on the local area network.
1562 Packet aliasing allows computers on private, unregistered
1563 subnets to have Internet access, although they are invisible
1564 from the outside world.
1567 operation should first be verified with network address translation disabled.
1570 option should be switched on, and network applications (web browser,
1575 should be checked on the
1578 Finally, the same or similar applications should be checked on other
1579 computers in the LAN.
1580 If network applications work correctly on the
1582 host, but not on other machines in the LAN, then the masquerading
1583 software is working properly, but the host is either not forwarding
1584 or possibly receiving IP packets.
1585 Check that IP forwarding is enabled in
1587 and that other machines have designated the
1589 host as the gateway for the LAN.
1590 .Sh PACKET FILTERING
1591 This implementation supports packet filtering.
1592 There are four kinds of
1602 Here are the basics:
1605 A filter definition has the following syntax:
1614 .Ar src_addr Ns Op / Ns Ar width
1615 .Op Ar dst_addr Ns Op / Ns Ar width
1617 .Ar [ proto Op src Ar cmp port
1622 .Op timeout Ar secs ]
1634 is a numeric value between
1638 specifying the rule number.
1639 Rules are specified in numeric order according to
1650 in which case, if a given packet matches the rule, the associated action
1651 is taken immediately.
1653 can also be specified as
1655 to clear the action associated with that particular rule, or as a new
1656 rule number greater than the current rule.
1657 In this case, if a given
1658 packet matches the current rule, the packet will next be matched against
1659 the new rule number (rather than the next rule number).
1663 may optionally be followed with an exclamation mark
1667 to reverse the sense of the following match.
1669 .Op Ar src_addr Ns Op / Ns Ar width
1671 .Op Ar dst_addr Ns Op / Ns Ar width
1672 are the source and destination IP number specifications.
1675 is specified, it gives the number of relevant netmask bits,
1676 allowing the specification of an address range.
1682 may be given the values
1686 (refer to the description of the
1688 command for a description of these values).
1689 When these values are used,
1690 the filters will be updated any time the values change.
1691 This is similar to the behaviour of the
1710 meaning less-than, equal and greater-than respectively.
1712 can be specified as a numeric port or by service name from
1720 flags are only allowed when
1724 and represent the TH_ACK, TH_SYN and TH_FIN or TH_RST TCP flags respectively.
1726 The timeout value adjusts the current idle timeout to at least
1729 If a timeout is given in the alive filter as well as in the in/out
1730 filter, the in/out value is used.
1731 If no timeout is given, the default timeout (set using
1733 and defaulting to 180 seconds) is used.
1737 Each filter can hold up to 40 rules, starting from rule 0.
1738 The entire rule set is not effective until rule 0 is defined,
1739 i.e., the default is to allow everything through.
1741 If no rule in a defined set of rules matches a packet, that packet will
1742 be discarded (blocked).
1743 If there are no rules in a given filter, the packet will be permitted.
1745 It's possible to filter based on the payload of UDP frames where those
1751 .Ar filter-decapsulation
1752 option below for further details.
1755 .Dq set filter Ar name No -1
1760 .Pa /usr/share/examples/ppp/ppp.conf.sample .
1761 .Sh SETTING THE IDLE TIMER
1762 To check/set the idle timer, use the
1767 .Bd -literal -offset indent
1768 ppp ON awfulhak> set timeout 600
1771 The timeout period is measured in seconds, the default value for which
1774 To disable the idle timer function, use the command
1775 .Bd -literal -offset indent
1776 ppp ON awfulhak> set timeout 0
1783 modes, the idle timeout is ignored.
1786 mode, when the idle timeout causes the
1791 program itself remains running.
1792 Another trigger packet will cause it to attempt to re-establish the link.
1793 .Sh PREDICTOR-1 and DEFLATE COMPRESSION
1795 supports both Predictor type 1 and deflate compression.
1798 will attempt to use (or be willing to accept) both compression protocols
1799 when the peer agrees
1800 .Pq or requests them .
1801 The deflate protocol is preferred by
1807 commands if you wish to disable this functionality.
1809 It is possible to use a different compression algorithm in each direction
1810 by using only one of
1814 .Pq assuming that the peer supports both algorithms .
1816 By default, when negotiating DEFLATE,
1818 will use a window size of 15.
1821 command if you wish to change this behaviour.
1823 A special algorithm called DEFLATE24 is also available, and is disabled
1824 and denied by default.
1825 This is exactly the same as DEFLATE except that
1826 it uses CCP ID 24 to negotiate.
1829 to successfully negotiate DEFLATE with
1832 .Sh CONTROLLING IP ADDRESS
1834 uses IPCP to negotiate IP addresses.
1835 Each side of the connection
1836 specifies the IP address that it's willing to use, and if the requested
1837 IP address is acceptable then
1839 returns ACK to the requester.
1842 returns NAK to suggest that the peer use a different IP address.
1844 both sides of the connection agree to accept the received request (and
1845 send ACK), IPCP is set to the open state and a network level connection
1847 To control this IPCP behaviour, this implementation has the
1849 command for defining the local and remote IP address:
1850 .Bd -ragged -offset indent
1851 .No set ifaddr Oo Ar src_addr Ns
1853 .Oo Ar dst_addr Ns Op / Ns Ar \&nn
1863 is the IP address that the local side is willing to use,
1865 is the IP address which the remote side should use and
1867 is the netmask that should be used.
1869 defaults to the current
1872 defaults to 0.0.0.0, and
1874 defaults to whatever mask is appropriate for
1876 It is only possible to make
1878 smaller than the default.
1879 The usual value is 255.255.255.255, as
1880 most kernels ignore the netmask of a POINTOPOINT interface.
1884 implementations require that the peer negotiates a specific IP
1887 If this is the case,
1889 may be used to specify this IP number.
1890 This will not affect the
1891 routing table unless the other side agrees with this proposed number.
1892 .Bd -literal -offset indent
1893 set ifaddr 192.244.177.38 192.244.177.2 255.255.255.255 0.0.0.0
1896 The above specification means:
1898 .Bl -bullet -compact
1900 I will first suggest that my IP address should be 0.0.0.0, but I
1901 will only accept an address of 192.244.177.38.
1903 I strongly insist that the peer uses 192.244.177.2 as his own
1904 address and won't permit the use of any IP address but 192.244.177.2.
1905 When the peer requests another IP address, I will always suggest that
1906 it uses 192.244.177.2.
1908 The routing table entry will have a netmask of 0xffffffff.
1911 This is all fine when each side has a pre-determined IP address, however
1912 it is often the case that one side is acting as a server which controls
1913 all IP addresses and the other side should go along with it.
1914 In order to allow more flexible behaviour, the
1916 command allows the user to specify IP addresses more loosely:
1918 .Dl set ifaddr 192.244.177.38/24 192.244.177.2/20
1920 A number followed by a slash
1922 represents the number of bits significant in the IP address.
1923 The above example means:
1925 .Bl -bullet -compact
1927 I'd like to use 192.244.177.38 as my address if it is possible, but I'll
1928 also accept any IP address between 192.244.177.0 and 192.244.177.255.
1930 I'd like to make him use 192.244.177.2 as his own address, but I'll also
1931 permit him to use any IP address between 192.244.176.0 and
1934 As you may have already noticed, 192.244.177.2 is equivalent to saying
1937 As an exception, 0 is equivalent to 0.0.0.0/0, meaning that I have no
1938 preferred IP address and will obey the remote peers selection.
1939 When using zero, no routing table entries will be made until a connection
1942 192.244.177.2/0 means that I'll accept/permit any IP address but I'll
1943 try to insist that 192.244.177.2 be used first.
1946 .Sh CONNECTING WITH YOUR INTERNET SERVICE PROVIDER
1947 The following steps should be taken when connecting to your ISP:
1950 Describe your providers phone number(s) in the dial script using the
1953 This command allows you to set multiple phone numbers for
1954 dialing and redialing separated by either a pipe
1958 .Bd -ragged -offset indent
1959 .No set phone Ar telno Ns Xo
1960 .Oo \&| Ns Ar backupnumber
1961 .Oc Ns ... Ns Oo : Ns Ar nextnumber
1966 Numbers after the first in a pipe-separated list are only used if the
1967 previous number was used in a failed dial or login script.
1969 separated by a colon are used sequentially, irrespective of what happened
1970 as a result of using the previous number.
1972 .Bd -literal -offset indent
1973 set phone "1234567|2345678:3456789|4567890"
1976 Here, the 1234567 number is attempted.
1977 If the dial or login script fails,
1978 the 2345678 number is used next time, but *only* if the dial or login script
1980 On the dial after this, the 3456789 number is used.
1982 number is only used if the dial or login script using the 3456789 fails.
1983 If the login script of the 2345678 number fails, the next number is still the
1985 As many pipes and colons can be used as are necessary
1986 (although a given site would usually prefer to use either the pipe or the
1987 colon, but not both).
1988 The next number redial timeout is used between all numbers.
1989 When the end of the list is reached, the normal redial period is
1990 used before starting at the beginning again.
1991 The selected phone number is substituted for the \\\\T string in the
1993 command (see below).
1995 Set up your redial requirements using
1997 For example, if you have a bad telephone line or your provider is
1998 usually engaged (not so common these days), you may want to specify
2000 .Bd -literal -offset indent
2004 This says that up to 4 phone calls should be attempted with a pause of 10
2005 seconds before dialing the first number again.
2007 Describe your login procedure using the
2014 command is used to talk to your modem and establish a link with your
2016 .Bd -literal -offset indent
2017 set dial "ABORT BUSY ABORT NO\\\\sCARRIER TIMEOUT 4 \\"\\" \e
2018 ATZ OK-ATZ-OK ATDT\\\\T TIMEOUT 60 CONNECT"
2021 This modem "chat" string means:
2024 Abort if the string "BUSY" or "NO CARRIER" are received.
2026 Set the timeout to 4 seconds.
2033 If that's not received within the 4 second timeout, send ATZ
2036 Send ATDTxxxxxxx where xxxxxxx is the next number in the phone list from
2039 Set the timeout to 60.
2041 Wait for the CONNECT string.
2044 Once the connection is established, the login script is executed.
2045 This script is written in the same style as the dial script, but care should
2046 be taken to avoid having your password logged:
2047 .Bd -literal -offset indent
2048 set authkey MySecret
2049 set login "TIMEOUT 15 login:-\\\\r-login: awfulhak \e
2050 word: \\\\P ocol: PPP HELLO"
2053 This login "chat" string means:
2056 Set the timeout to 15 seconds.
2059 If it's not received, send a carriage return and expect
2064 Expect "word:" (the tail end of a "Password:" prompt).
2066 Send whatever our current
2070 Expect "ocol:" (the tail end of a "Protocol:" prompt).
2079 command is logged specially.
2084 logging is enabled, the actual password is not logged;
2088 Login scripts vary greatly between ISPs.
2089 If you're setting one up for the first time,
2090 .Em ENABLE CHAT LOGGING
2091 so that you can see if your script is behaving as you expect.
2097 to specify your serial line and speed, for example:
2098 .Bd -literal -offset indent
2099 set device /dev/cuaa0
2103 Cuaa0 is the first serial port on
2110 A speed of 115200 should be specified
2111 if you have a modem capable of bit rates of 28800 or more.
2112 In general, the serial speed should be about four times the modem speed.
2116 command to define the IP address.
2119 If you know what IP address your provider uses, then use it as the remote
2120 address (dst_addr), otherwise choose something like 10.0.0.2/0 (see below).
2122 If your provider has assigned a particular IP address to you, then use
2123 it as your address (src_addr).
2125 If your provider assigns your address dynamically, choose a suitably
2126 unobtrusive and unspecific IP number as your address.
2127 10.0.0.1/0 would be appropriate.
2128 The bit after the / specifies how many bits of the
2129 address you consider to be important, so if you wanted to insist on
2130 something in the class C network 1.2.3.0, you could specify 1.2.3.1/24.
2132 If you find that your ISP accepts the first IP number that you suggest,
2133 specify third and forth arguments of
2135 This will force your ISP to assign a number.
2136 (The third argument will
2137 be ignored as it is less restrictive than the default mask for your
2141 An example for a connection where you don't know your IP number or your
2142 ISPs IP number would be:
2143 .Bd -literal -offset indent
2144 set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0
2148 In most cases, your ISP will also be your default router.
2149 If this is the case, add the line
2150 .Bd -literal -offset indent
2155 .Pa /etc/ppp/ppp.conf .
2159 to add a default route to whatever the peer address is
2160 .Pq 10.0.0.2 in this example .
2163 meaning that should the value of
2165 change, the route will be updated accordingly.
2167 Previous versions of
2169 required a similar entry in the
2170 .Pa /etc/ppp/ppp.linkup
2174 this is no longer required.
2176 If your provider requests that you use PAP/CHAP authentication methods, add
2177 the next lines to your
2178 .Pa /etc/ppp/ppp.conf
2180 .Bd -literal -offset indent
2182 set authkey MyPassword
2185 Both are accepted by default, so
2187 will provide whatever your ISP requires.
2189 It should be noted that a login script is rarely (if ever) required
2190 when PAP or CHAP are in use.
2192 Ask your ISP to authenticate your nameserver address(es) with the line
2193 .Bd -literal -offset indent
2199 do this if you are running a local DNS unless you also either use
2204 .Pa /etc/ppp/ppp.linkdown ,
2207 will simply circumvent its use by entering some nameserver lines in
2208 .Pa /etc/resolv.conf .
2212 .Pa /usr/share/examples/ppp/ppp.conf.sample
2214 .Pa /usr/share/examples/ppp/ppp.linkup.sample
2215 for some real examples.
2216 The pmdemand label should be appropriate for most ISPs.
2217 .Sh LOGGING FACILITY
2219 is able to generate the following log info either via
2221 or directly to the screen:
2223 .Bl -tag -width XXXXXXXXX -offset XXX -compact
2225 Enable all logging facilities.
2226 This generates a lot of log.
2227 The most common use of 'all' is as a basis, where you remove some facilities
2228 after enabling 'all' ('debug' and 'timer' are usually best disabled.)
2230 Dump async level packet in hex.
2232 Generate CBCP (CallBack Control Protocol) logs.
2234 Generate a CCP packet trace.
2242 chat script trace logs.
2244 Log commands executed either from the command line or any of the configuration
2247 Log Chat lines containing the string "CONNECT".
2249 Log debug information.
2251 Log DNS QUERY packets.
2253 Log packets permitted by the dial filter and denied by any filter.
2255 Dump HDLC packet in hex.
2257 Log all function calls specifically made as user id 0.
2259 Generate an IPCP packet trace.
2261 Generate an LCP packet trace.
2263 Generate LQR reports.
2265 Phase transition log output.
2267 Dump physical level packet in hex.
2269 Dump sync level packet in hex.
2271 Dump all TCP/IP packets.
2273 Log timer manipulation.
2275 Include the tun device on each log line.
2277 Output to the terminal device.
2278 If there is currently no terminal,
2279 output is sent to the log file using syslogs
2282 Output to both the terminal device
2283 and the log file using syslogs
2286 Output to the log file using
2292 command allows you to set the logging output level.
2293 Multiple levels can be specified on a single command line.
2294 The default is equivalent to
2297 It is also possible to log directly to the screen.
2298 The syntax is the same except that the word
2300 should immediately follow
2304 (i.e., only the un-maskable warning, error and alert output).
2306 If The first argument to
2307 .Dq set log Op local
2312 character, the current log levels are
2313 not cleared, for example:
2314 .Bd -literal -offset indent
2315 PPP ON awfulhak> set log phase
2316 PPP ON awfulhak> show log
2317 Log: Phase Warning Error Alert
2318 Local: Warning Error Alert
2319 PPP ON awfulhak> set log +tcp/ip -warning
2320 PPP ON awfulhak> set log local +command
2321 PPP ON awfulhak> show log
2322 Log: Phase TCP/IP Warning Error Alert
2323 Local: Command Warning Error Alert
2326 Log messages of level Warning, Error and Alert are not controllable
2328 .Dq set log Op local .
2332 level is special in that it will not be logged if it can be displayed
2336 deals with the following signals:
2337 .Bl -tag -width "USR2"
2339 Receipt of this signal causes the termination of the current connection
2343 to exit unless it is in
2348 .It HUP, TERM & QUIT
2355 to re-open any existing server socket, dropping all existing diagnostic
2356 connections. Sockets that couldn't previously be opened will be retried.
2360 to close any existing server socket, dropping all existing diagnostic
2363 can still be used to re-open the socket.
2367 If you wish to use more than one physical link to connect to a
2369 peer, that peer must also understand the
2372 Refer to RFC 1990 for specification details.
2374 The peer is identified using a combination of his
2375 .Dq endpoint discriminator
2377 .Dq authentication id .
2378 Either or both of these may be specified.
2379 It is recommended that
2380 at least one is specified, otherwise there is no way of ensuring that
2381 all links are actually connected to the same peer program, and some
2382 confusing lock-ups may result.
2383 Locally, these identification variables are specified using the
2391 must be agreed in advance with the peer.
2393 Multi-link capabilities are enabled using the
2395 command (set maximum reconstructed receive unit).
2396 Once multi-link is enabled,
2398 will attempt to negotiate a multi-link connection with the peer.
2400 By default, only one
2403 .Pq called Sq deflink .
2404 To create more links, the
2407 This command will clone existing links, where all
2408 characteristics are the same except:
2411 The new link has its own name as specified on the
2418 Its mode may subsequently be changed using the
2422 The new link is in a
2427 A summary of all available links can be seen using the
2431 Once a new link has been created, command usage varies.
2432 All link specific commands must be prefixed with the
2434 command, specifying on which link the command is to be applied.
2435 When only a single link is available,
2437 is smart enough not to require the
2441 Some commands can still be used without specifying a link - resulting
2442 in an operation at the
2445 For example, once two or more links are available, the command
2447 will show CCP configuration and statistics at the multi-link level, and
2448 .Dq link deflink show ccp
2449 will show the same information at the
2453 Armed with this information, the following configuration might be used:
2455 .Bd -literal -offset indent
2459 set device /dev/cuaa0 /dev/cuaa1 /dev/cuaa2
2460 set phone "123456789"
2461 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \\"\\" ATZ \e
2462 OK-AT-OK \\\\dATDT\\\\T TIMEOUT 45 CONNECT"
2464 set ifaddr 10.0.0.1/0 10.0.0.2/0
2466 set authkey ppppassword
2473 Note how all cloning is done at the end of the configuration.
2474 Usually, the link will be configured first, then cloned.
2475 If you wish all links
2476 to be up all the time, you can add the following line to the end of your
2479 .Bd -literal -offset indent
2480 link 1,2,3 set mode ddial
2483 If you want the links to dial on demand, this command could be used:
2485 .Bd -literal -offset indent
2486 link * set mode auto
2489 Links may be tied to specific names by removing the
2491 line above, and specifying the following after the
2495 .Bd -literal -offset indent
2496 link 1 set device /dev/cuaa0
2497 link 2 set device /dev/cuaa1
2498 link 3 set device /dev/cuaa2
2503 command to see which commands require context (using the
2505 command), which have optional
2506 context and which should not have any context.
2512 mode with the peer, it creates a local domain socket in the
2515 This socket is used to pass link information (including
2516 the actual link file descriptor) between different
2521 ability to be run from a
2527 capability), without needing to have initial control of the serial
2531 negotiates multi-link mode, it will pass its open link to any
2532 already running process.
2533 If there is no already running process,
2535 will act as the master, creating the socket and listening for new
2537 .Sh PPP COMMAND LIST
2538 This section lists the available commands and their effect.
2539 They are usable either from an interactive
2541 session, from a configuration file or from a
2547 .It accept|deny|enable|disable Ar option....
2548 These directives tell
2550 how to negotiate the initial connection with the peer.
2553 has a default of either accept or deny and enable or disable.
2555 means that the option will be ACK'd if the peer asks for it.
2557 means that the option will be NAK'd if the peer asks for it.
2559 means that the option will be requested by us.
2561 means that the option will not be requested by us.
2564 may be one of the following:
2567 Default: Enabled and Accepted.
2568 ACFComp stands for Address and Control Field Compression.
2569 Non LCP packets will usually have an address
2570 field of 0xff (the All-Stations address) and a control field of
2571 0x03 (the Unnumbered Information command).
2573 negotiated, these two bytes are simply not sent, thus minimising
2580 Default: Disabled and Accepted.
2581 CHAP stands for Challenge Handshake Authentication Protocol.
2582 Only one of CHAP and PAP (below) may be negotiated.
2583 With CHAP, the authenticator sends a "challenge" message to its peer.
2584 The peer uses a one-way hash function to encrypt the
2585 challenge and sends the result back.
2586 The authenticator does the same, and compares the results.
2587 The advantage of this mechanism is that no
2588 passwords are sent across the connection.
2589 A challenge is made when the connection is first made.
2590 Subsequent challenges may occur.
2591 If you want to have your peer authenticate itself, you must
2594 .Pa /etc/ppp/ppp.conf ,
2595 and have an entry in
2596 .Pa /etc/ppp/ppp.secret
2599 When using CHAP as the client, you need only specify
2604 .Pa /etc/ppp/ppp.conf .
2605 CHAP is accepted by default.
2608 implementations use "MS-CHAP" rather than MD5 when encrypting the
2610 MS-CHAP is a combination of MD4 and DES.
2613 was built on a machine with DES libraries available, it will respond
2614 to MS-CHAP authentication requests, but will never request them.
2616 Default: Enabled and Accepted.
2617 This option decides if deflate
2618 compression will be used by the Compression Control Protocol (CCP).
2619 This is the same algorithm as used by the
2622 Note: There is a problem negotiating
2628 implementation available under many operating systems.
2630 (version 2.3.1) incorrectly attempts to negotiate
2632 compression using type
2634 as the CCP configuration type rather than type
2640 is actually specified as
2641 .Dq PPP Magna-link Variable Resource Compression
2645 is capable of negotiating with
2652 .Ar accept Ns No ed .
2654 Default: Disabled and Denied.
2655 This is a variance of the
2657 option, allowing negotiation with the
2662 section above for details.
2663 It is disabled by default as it violates
2666 Default: Disabled and Denied.
2667 This option allows DNS negotiation.
2672 will request that the peer confirms the entries in
2673 .Pa /etc/resolv.conf .
2674 If the peer NAKs our request (suggesting new IP numbers),
2675 .Pa /etc/resolv.conf
2676 is updated and another request is sent to confirm the new entries.
2679 .Dq accept Ns No ed,
2681 will answer any DNS queries requested by the peer rather than rejecting
2683 The answer is taken from
2684 .Pa /etc/resolv.conf
2687 command is used as an override.
2689 Default: Enabled and Accepted.
2690 This option allows control over whether we
2691 negotiate an endpoint discriminator.
2692 We only send our discriminator if
2697 We reject the peers discriminator if
2701 Default: Disabled and Accepted.
2702 The use of this authentication protocol
2703 is discouraged as it partially violates the authentication protocol by
2704 implementing two different mechanisms (LANMan & NT) under the guise of
2705 a single CHAP type (0x80).
2707 uses a simple DES encryption mechanism and is the least secure of the
2708 CHAP alternatives (although is still more secure than PAP).
2712 description below for more details.
2714 Default: Disabled and Accepted.
2715 This option decides if Link Quality Requests will be sent or accepted.
2716 LQR is a protocol that allows
2718 to determine that the link is down without relying on the modems
2720 When LQR is enabled,
2726 below) as part of the LCP request.
2727 If the peer agrees, both sides will
2728 exchange LQR packets at the agreed frequency, allowing detailed link
2729 quality monitoring by enabling LQM logging.
2730 If the peer doesn't agree,
2732 will send ECHO LQR requests instead.
2733 These packets pass no information of interest, but they
2735 be replied to by the peer.
2737 Whether using LQR or ECHO LQR,
2739 will abruptly drop the connection if 5 unacknowledged packets have been
2740 sent rather than sending a 6th.
2741 A message is logged at the
2743 level, and any appropriate
2745 values are honoured as if the peer were responsible for dropping the
2748 Default: Enabled and Accepted.
2749 This is Microsoft Point to Point Encryption scheme. MPPE key size can be
2750 40-, 56- and 128-bits. Refer to
2754 Default: Disabled and Accepted.
2755 It is very similar to standard CHAP (type 0x05)
2756 except that it issues challenges of a fixed 16 bytes in length and uses a
2757 combination of MD4, SHA-1 and DES to encrypt the challenge rather than using the
2758 standard MD5 mechanism.
2760 Default: Disabled and Accepted.
2761 The use of this authentication protocol
2762 is discouraged as it partially violates the authentication protocol by
2763 implementing two different mechanisms (LANMan & NT) under the guise of
2764 a single CHAP type (0x80).
2765 It is very similar to standard CHAP (type 0x05)
2766 except that it issues challenges of a fixed 8 bytes in length and uses a
2767 combination of MD4 and DES to encrypt the challenge rather than using the
2768 standard MD5 mechanism.
2769 CHAP type 0x80 for LANMan is also supported - see
2777 use CHAP type 0x80, when acting as authenticator with both
2778 .Dq enable Ns No d ,
2780 will rechallenge the peer up to three times if it responds using the wrong
2781 one of the two protocols.
2782 This gives the peer a chance to attempt using both protocols.
2786 acts as the authenticatee with both protocols
2787 .Dq accept Ns No ed ,
2788 the protocols are used alternately in response to challenges.
2790 Note: If only LANMan is enabled,
2792 (version 2.3.5) misbehaves when acting as authenticatee.
2794 the NT and the LANMan answers, but also suggests that only the NT answer
2797 Default: Disabled and Accepted.
2798 PAP stands for Password Authentication Protocol.
2799 Only one of PAP and CHAP (above) may be negotiated.
2800 With PAP, the ID and Password are sent repeatedly to the peer until
2801 authentication is acknowledged or the connection is terminated.
2802 This is a rather poor security mechanism.
2803 It is only performed when the connection is first established.
2804 If you want to have your peer authenticate itself, you must
2807 .Pa /etc/ppp/ppp.conf ,
2808 and have an entry in
2809 .Pa /etc/ppp/ppp.secret
2810 for the peer (although see the
2816 When using PAP as the client, you need only specify
2821 .Pa /etc/ppp/ppp.conf .
2822 PAP is accepted by default.
2824 Default: Enabled and Accepted.
2825 This option decides if Predictor 1
2826 compression will be used by the Compression Control Protocol (CCP).
2828 Default: Enabled and Accepted.
2829 This option is used to negotiate
2830 PFC (Protocol Field Compression), a mechanism where the protocol
2831 field number is reduced to one octet rather than two.
2833 Default: Enabled and Accepted.
2834 This option determines if
2836 will request and accept requests for short
2838 sequence numbers when negotiating multi-link mode.
2839 This is only applicable if our MRRU is set (thus enabling multi-link).
2841 Default: Enabled and Accepted.
2842 This option determines if Van Jacobson header compression will be used.
2845 The following options are not actually negotiated with the peer.
2846 Therefore, accepting or denying them makes no sense.
2848 .It filter-decapsulation
2850 When this option is enabled,
2852 will examine UDP frames to see if they actually contain a
2854 frame as their payload.
2855 If this is the case, all filters will operate on the payload rather
2856 than the actual packet.
2858 This is useful if you want to send PPPoUDP traffic over a
2860 link, but want that link to do smart things with the real data rather than
2863 The UDP frame payload must not be compressed in any way, otherwise
2865 will not be able to interpret it.
2866 It's therefore recommended that you
2867 .Ic disable vj pred1 deflate
2869 .Ic deny vj pred1 deflate
2870 in the configuration for the
2872 invocation with the udp link.
2877 exchanges low-level LCP, CCP and IPCP configuration traffic, the
2879 field of any replies is expected to be the same as that of the request.
2882 drops any reply packets that do not contain the expected identifier
2883 field, reporting the fact at the respective log level.
2888 will ignore the identifier field.
2893 runs as a Multi-link server, a different
2895 instance initially receives each connection.
2896 After determining that
2897 the link belongs to an already existing bundle (controlled by another
2901 will transfer the link to that process.
2903 If the link is a tty device or if this option is enabled,
2905 will not exit, but will change its process name to
2907 and wait for the controlling
2909 to finish with the link and deliver a signal back to the idle process.
2910 This prevents the confusion that results from
2912 parent considering the link resource available again.
2914 For tty devices that have entries in
2916 this is necessary to prevent another
2918 from being started, and for program links such as
2922 from exiting due to the death of its child.
2925 cannot determine its parents requirements (except for the tty case), this
2926 option must be enabled manually depending on the circumstances.
2933 will automatically loop back packets being sent
2934 out with a destination address equal to that of the
2939 will send the packet, probably resulting in an ICMP redirect from
2941 It is convenient to have this option enabled when
2942 the interface is also the default route as it avoids the necessity
2943 of a loopback route.
2946 Enabling this option will tell the PAP authentication
2947 code to use the password database (see
2949 to authenticate the caller if they cannot be found in the
2950 .Pa /etc/ppp/ppp.secret
2952 .Pa /etc/ppp/ppp.secret
2953 is always checked first.
2954 If you wish to use passwords from
2956 but also to specify an IP number or label for a given client, use
2958 as the client password in
2959 .Pa /etc/ppp/ppp.secret .
2962 Enabling this option will tell
2964 to proxy ARP for the peer.
2967 will make an entry in the ARP table using
2971 address of the local network in which
2974 This allows other machines connecteed to the LAN to talk to
2975 the peer as if the peer itself was connected to the LAN.
2976 The proxy entry cannot be made unless
2978 is an address from a LAN.
2981 Enabling this will tell
2983 to add proxy arp entries for every IP address in all class C or
2984 smaller subnets routed via the tun interface.
2986 Proxy arp entries are only made for sticky routes that are added
2990 No proxy arp entries are made for the interface address itself
2998 command is used with the
3002 values, entries are stored in the
3009 change, this list is re-applied to the routing table.
3011 Disabling this option will prevent the re-application of sticky routes,
3014 list will still be maintained.
3021 to adjust outgoing TCP SYN packets so that the maximum receive segment
3022 size is not greater than the amount allowed by the interface MTU.
3027 to gather throughput statistics.
3028 Input and output is sampled over
3029 a rolling 5 second window, and current, best and total figures are retained.
3030 This data is output when the relevant
3032 layer shuts down, and is also available using the
3035 Throughput statistics are available at the
3042 Normally, when a user is authenticated using PAP or CHAP, and when
3046 mode, an entry is made in the utmp and wtmp files for that user.
3047 Disabling this option will tell
3049 not to make any utmp or wtmp entries.
3050 This is usually only necessary if
3051 you require the user to both login and authenticate themselves.
3056 This option simply tells
3058 to add new interface addresses to the interface rather than replacing them.
3059 The option can only be enabled if network address translation is enabled
3060 .Pq Dq nat enable yes .
3062 With this option enabled,
3064 will pass traffic for old interface addresses through the NAT engine
3065 .Pq see Xr libalias 3 ,
3066 resulting in the ability (in
3068 mode) to properly connect the process that caused the PPP link to
3069 come up in the first place.
3079 .Ar dest Ns Op / Ns Ar nn
3084 is the destination IP address.
3085 The netmask is specified either as a number of bits with
3087 or as an IP number using
3092 with no mask refers to the default route.
3093 It is also possible to use the literal name
3098 is the next hop gateway to get to the given
3103 command for further details.
3105 It is possible to use the symbolic names
3109 as the destination, and
3114 is replaced with the interface address and
3116 is replaced with the interface destination (peer) address.
3121 .Pq note the trailing Dq !\& ,
3122 then if the route already exists, it will be updated as with the
3126 for further details).
3128 Routes that contain the
3134 constants are considered
3136 They are stored in a list (use
3138 to see the list), and each time the value of
3144 changes, the appropriate routing table entries are updated.
3145 This facility may be disabled using
3146 .Dq disable sroutes .
3147 .It allow Ar command Op Ar args
3148 This command controls access to
3150 and its configuration files.
3151 It is possible to allow user-level access,
3152 depending on the configuration file label and on the mode that
3155 For example, you may wish to configure
3165 User id 0 is immune to these commands.
3167 .It allow user Ns Xo
3169 .Ar logname Ns No ...
3171 By default, only user id 0 is allowed access to
3173 If this command is used, all of the listed users are allowed access to
3174 the section in which the
3179 section is always checked first (even though it is only ever automatically
3182 commands are cumulative in a given section, but users allowed in any given
3183 section override users allowed in the default section, so it's possible to
3184 allow users access to everything except a given label by specifying default
3187 section, and then specifying a new user list for that label.
3191 is specified, access is allowed to all users.
3192 .It allow mode Ns Xo
3196 By default, access using any
3199 If this command is used, it restricts the access
3201 allowed to load the label under which this command is specified.
3206 command overrides any previous settings, and the
3208 section is always checked first.
3220 When running in multi-link mode, a section can be loaded if it allows
3222 of the currently existing line modes.
3225 .It nat Ar command Op Ar args
3226 This command allows the control of the network address translation (also
3227 known as masquerading or IP aliasing) facilities that are built into
3229 NAT is done on the external interface only, and is unlikely to make sense
3234 For backwards compatibility, the word
3236 may be used in place of
3238 If nat is enabled on your system (it may be omitted at compile time),
3239 the following commands are possible:
3241 .It nat enable yes|no
3242 This command either switches network address translation on or turns it off.
3245 command line flag is synonymous with
3246 .Dq nat enable yes .
3247 .It nat addr Op Ar addr_local addr_alias
3248 This command allows data for
3252 It is useful if you own a small number of real IP numbers that
3253 you wish to map to specific machines behind your gateway.
3254 .It nat deny_incoming yes|no
3255 If set to yes, this command will refuse all incoming packets where an
3256 aliasing link doesn't already exist.
3258 .Sx CONCEPTUAL BACKGROUND
3261 for a description of what an
3265 It should be noted under what circumstances an aliasing link is created by
3267 It may be necessary to further protect your network from outside
3268 connections using the
3274 This command gives a summary of available nat commands.
3276 This option causes various NAT statistics and information to
3277 be logged to the file
3278 .Pa /var/log/alias.log .
3279 .It nat port Ar proto Ar targetIP Ns Xo
3280 .No : Ns Ar targetPort Ns
3282 .No - Ns Ar targetPort
3285 .No - Ns Ar aliasPort
3286 .Oc Oo Ar remoteIP : Ns
3289 .No - Ns Ar remotePort
3293 This command causes incoming
3307 A range of port numbers may be specified as shown above.
3308 The ranges must be of the same size.
3312 is specified, only data coming from that IP number is redirected.
3316 .Pq indicating any source port
3317 or a range of ports the same size as the other ranges.
3319 This option is useful if you wish to run things like Internet phone on
3320 machines behind your gateway, but is limited in that connections to only
3321 one interior machine per source machine and target port are possible.
3322 .It "nat proxy cmd" Ar arg Ns No ...
3325 to proxy certain connections, redirecting them to a given server.
3326 Refer to the description of
3327 .Fn PacketAliasProxyRule
3330 for details of the available commands.
3331 .It nat same_ports yes|no
3332 When enabled, this command will tell the network address translation engine to
3333 attempt to avoid changing the port number on outgoing packets.
3335 if you want to support protocols such as RPC and LPD which require
3336 connections to come from a well known port.
3337 .It nat target Op Ar address
3338 Set the given target address or clear it if no address is given.
3339 The target address is used by libalias to specify how to NAT incoming
3341 If a target address is not set or if
3343 is given, packets are not altered and are allowed to route to the internal
3346 The target address may be set to
3348 in which case libalias will redirect all packets to the interface address.
3349 .It nat use_sockets yes|no
3350 When enabled, this option tells the network address translation engine to
3351 create a socket so that it can guarantee a correct incoming ftp data or
3353 .It nat unregistered_only yes|no
3354 Only alter outgoing packets with an unregistered source address.
3355 According to RFC 1918, unregistered source addresses
3356 are 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16.
3359 These commands are also discussed in the file
3361 which comes with the source distribution.
3368 is executed in the background with the following words replaced:
3369 .Bl -tag -width PEER_ENDDISC
3371 This is replaced with the local
3377 .It Li COMPILATIONDATE
3378 This is replaced with the date on which
3382 These are replaced with the primary and secondary nameserver IP numbers.
3383 If nameservers are negotiated by IPCP, the values of these macros will change.
3385 This is replaced with the local endpoint discriminator value.
3390 This is replaced with the peers IP number.
3392 This is replaced with the name of the interface that's in use.
3394 This is replaced with the last label name used.
3395 A label may be specified on the
3397 command line, via the
3405 This is replaced with the IP number assigned to the local interface.
3407 This is replaced with the value of the peers endpoint discriminator.
3409 This is replaced with the current process id.
3411 This is replaced with the current version number of
3414 This is replaced with the username that has been authenticated with PAP or
3416 Normally, this variable is assigned only in -direct mode.
3417 This value is available irrespective of whether utmp logging is enabled.
3420 These substitutions are also done by the
3424 If you wish to pause
3426 while the command executes, use the
3429 .It clear physical|ipcp Op current|overall|peak...
3430 Clear the specified throughput values at either the
3437 is specified, context must be given (see the
3440 If no second argument is given, all values are cleared.
3441 .It clone Ar name Ns Xo
3442 .Op \&, Ns Ar name Ns
3445 Clone the specified link, creating one or more new links according to the
3448 This command must be used from the
3450 command below unless you've only got a single link (in which case that
3451 link becomes the default).
3452 Links may be removed using the
3456 The default link name is
3458 .It close Op lcp|ccp Ns Op !\&
3459 If no arguments are given, the relevant protocol layers will be brought
3460 down and the link will be closed.
3463 is specified, the LCP layer is brought down, but
3465 will not bring the link offline.
3466 It is subsequently possible to use
3469 to talk to the peer machine if, for example, something like
3474 is specified, only the relevant compression layer is closed.
3477 is used, the compression layer will remain in the closed state, otherwise
3478 it will re-enter the STOPPED state, waiting for the peer to initiate
3479 further CCP negotiation.
3480 In any event, this command does not disconnect the user from
3491 This command deletes the route with the given
3498 all non-direct entries in the routing table for the current interface,
3501 entries are deleted.
3506 the default route is deleted.
3511 .Pq note the trailing Dq !\& ,
3513 will not complain if the route does not already exist.
3514 .It dial|call Op Ar label Ns Xo
3517 This command is the equivalent of
3521 and is provided for backwards compatibility.
3522 .It down Op Ar lcp|ccp
3523 Bring the relevant layer down ungracefully, as if the underlying layer
3524 had become unavailable.
3525 It's not considered polite to use this command on
3526 a Finite State Machine that's in the OPEN state.
3528 supplied, the entire link is closed (or if no context is given, all links
3534 layer is terminated but the device is not brought offline and the link
3538 is specified, only the relevant compression layer(s) are terminated.
3539 .It help|? Op Ar command
3540 Show a list of available commands.
3543 is specified, show the usage string for that command.
3544 .It ident Op Ar text Ns No ...
3545 Identify the link to the peer using
3549 is empty, link identification is disabled.
3550 It is possible to use any of the words described for the
3555 command for details of when
3557 identifies itself to the peer.
3558 .It iface Ar command Op args
3559 This command is used to control the interface used by
3562 may be one of the following:
3566 .Ar addr Ns Op / Ns Ar bits
3577 combination to the interface.
3578 Instead of specifying
3582 .Pq with no space between \&it and Ar addr .
3583 If the given address already exists, the command fails unless the
3585 is used - in which case the previous interface address entry is overwritten
3586 with the new one, allowing a change of netmask or peer address.
3597 .Dq 255.255.255.255 .
3598 This address (the broadcast address) is the only duplicate peer address that
3602 If this command is used while
3604 is in the OPENED state or while in
3606 mode, all addresses except for the IPCP negotiated address are deleted
3610 is not in the OPENED state and is not in
3612 mode, all interface addresses are deleted.
3614 .It iface delete Ns Xo
3619 This command deletes the given
3624 is used, no error is given if the address isn't currently assigned to
3625 the interface (and no deletion takes place).
3627 Shows the current state and current addresses for the interface.
3628 It is much the same as running
3629 .Dq ifconfig INTERFACE .
3630 .It iface help Op Ar sub-command
3631 This command, when invoked without
3633 will show a list of possible
3635 sub-commands and a brief synopsis for each.
3638 only the synopsis for the given sub-command is shown.
3642 .Ar name Ns Op , Ns Ar name Ns
3643 .No ... Ar command Op Ar args
3645 This command may prefix any other command if the user wishes to
3646 specify which link the command should affect.
3647 This is only applicable after multiple links have been created in Multi-link
3653 specifies the name of an existing link.
3656 is a comma separated list,
3658 is executed on each link.
3664 is executed on all links.
3665 .It load Op Ar label Ns Xo
3688 will not attempt to make an immediate connection.
3689 .It open Op lcp|ccp|ipcp
3690 This is the opposite of the
3693 All closed links are immediately brought up apart from second and subsequent
3695 links - these will come up based on the
3697 command that has been used.
3701 argument is used while the LCP layer is already open, LCP will be
3703 This allows various LCP options to be changed, after which
3705 can be used to put them into effect.
3706 After renegotiating LCP,
3707 any agreed authentication will also take place.
3711 argument is used, the relevant compression layer is opened.
3712 Again, if it is already open, it will be renegotiated.
3716 argument is used, the link will be brought up as normal, but if
3717 IPCP is already open, it will be renegotiated and the network
3718 interface will be reconfigured.
3720 It is probably not good practice to re-open the PPP state machines
3721 like this as it's possible that the peer will not behave correctly.
3724 however useful as a way of forcing the CCP or VJ dictionaries to be reset.
3726 Specify the password required for access to the full
3729 This password is required when connecting to the diagnostic port (see the
3740 logging is active, instead, the literal string
3746 is executed from the controlling connection or from a command file,
3747 ppp will exit after closing all connections.
3748 Otherwise, if the user
3749 is connected to a diagnostic socket, the connection is simply dropped.
3755 will exit despite the source of the command after closing all existing
3758 This command removes the given link.
3759 It is only really useful in multi-link mode.
3760 A link must be in the
3762 state before it is removed.
3763 .It rename|mv Ar name
3764 This command renames the given link to
3768 is already used by another link.
3770 The default link name is
3777 may make the log file more readable.
3778 .It resolv Ar command
3779 This command controls
3786 starts up, it loads the contents of this file into memory and retains this
3787 image for future use.
3789 is one of the following:
3790 .Bl -tag -width readonly
3793 .Pa /etc/resolv.conf
3799 will still attempt to negotiate nameservers with the peer, making the results
3805 This is the opposite of the
3810 .Pa /etc/resolv.conf
3812 This may be necessary if for example a DHCP client overwrote
3813 .Pa /etc/resolv.conf .
3816 .Pa /etc/resolv.conf
3817 with the version originally read at startup or with the last
3820 This is sometimes a useful command to put in the
3821 .Pa /etc/ppp/ppp.linkdown
3825 .Pa /etc/resolv.conf
3827 This command will work even if the
3829 command has been used.
3830 It may be useful as a command in the
3831 .Pa /etc/ppp/ppp.linkup
3832 file if you wish to defer updating
3833 .Pa /etc/resolv.conf
3834 until after other commands have finished.
3839 .Pa /etc/resolv.conf
3844 successfully negotiates a DNS.
3845 This is the opposite of the
3850 This option is not (yet) implemented.
3854 to identify itself to the peer.
3855 The link must be in LCP state or higher.
3856 If no identity has been set (via the
3862 When an identity has been set,
3864 will automatically identify itself when it sends or receives a configure
3865 reject, when negotiation fails or when LCP reaches the opened state.
3867 Received identification packets are logged to the LCP log (see
3869 for details) and are never responded to.
3874 This option allows the setting of any of the following variables:
3876 .It set accmap Ar hex-value
3877 ACCMap stands for Asynchronous Control Character Map.
3879 negotiated with the peer, and defaults to a value of 00000000 in hex.
3880 This protocol is required to defeat hardware that depends on passing
3881 certain characters from end to end (such as XON/XOFF etc).
3883 For the XON/XOFF scenario, use
3884 .Dq set accmap 000a0000 .
3885 .It set Op auth Ns Xo
3888 This sets the authentication key (or password) used in client mode
3889 PAP or CHAP negotiation to the given value.
3890 It also specifies the
3891 password to be used in the dial or login scripts in place of the
3893 sequence, preventing the actual password from being logged.
3898 logging is in effect,
3902 for security reasons.
3904 If the first character of
3906 is an exclamation mark
3909 treats the remainder of the string as a program that must be executed
3920 it is treated as a single literal
3922 otherwise, ignoring the
3925 is parsed as a program to execute in the same was as the
3927 command above, substituting special names in the same manner.
3930 will feed the program three lines of input, each terminated by a newline
3934 The host name as sent in the CHAP challenge.
3936 The challenge string as sent in the CHAP challenge.
3942 Two lines of output are expected:
3947 to be sent with the CHAP response.
3951 which is encrypted with the challenge and request id, the answer being sent
3952 in the CHAP response packet.
3957 in this manner, it's expected that the host challenge is a series of ASCII
3958 digits or characters.
3959 An encryption device or Secure ID card is usually
3960 required to calculate the secret appropriate for the given challenge.
3961 .It set authname Ar id
3962 This sets the authentication id used in client mode PAP or CHAP negotiation.
3966 mode with CHAP enabled,
3968 is used in the initial authentication challenge and should normally be set to
3969 the local machine name.
3971 .Ar min-percent max-percent period
3973 These settings apply only in multi-link mode and default to zero, zero and
3977 .Pq also known as Fl auto
3978 mode link is available, only the first link is made active when
3980 first reads data from the tun device.
3983 link will be opened only when the current bundle throughput is at least
3985 percent of the total bundle bandwidth for
3988 When the current bundle throughput decreases to
3990 percent or less of the total bundle bandwidth for
3994 link will be brought down as long as it's not the last active link.
3996 Bundle throughput is measured as the maximum of inbound and outbound
3999 The default values cause
4001 links to simply come up one at a time.
4003 Certain devices cannot determine their physical bandwidth, so it
4004 is sometimes necessary to use the
4006 command (described below) to make
4009 .It set bandwidth Ar value
4010 This command sets the connection bandwidth in bits per second.
4012 must be greater than zero.
4013 It is currently only used by the
4016 .It set callback Ar option Ns No ...
4017 If no arguments are given, callback is disabled, otherwise,
4021 mode, will accept) one of the given
4022 .Ar option Ns No s .
4023 In client mode, if an
4027 will request a different
4029 until no options remain at which point
4031 will terminate negotiations (unless
4033 is one of the specified
4037 will accept any of the given protocols - but the client
4039 request one of them.
4040 If you wish callback to be optional, you must include
4046 are as follows (in this order of preference):
4050 The callee is expected to decide the callback number based on
4054 is the callee, the number should be specified as the fifth field of
4056 .Pa /etc/ppp/ppp.secret .
4058 Microsoft's callback control protocol is used.
4063 If you wish to negotiate
4065 in client mode but also wish to allow the server to request no callback at
4066 CBCP negotiation time, you must specify both
4070 as callback options.
4072 .Ar number Ns Op , Ns Ar number Ns
4075 The caller specifies the
4081 should be either a comma separated list of allowable numbers or a
4083 meaning any number is permitted.
4086 is the caller, only a single number should be specified.
4088 Note, this option is very unsafe when used with a
4090 as a malicious caller can tell
4092 to call any (possibly international) number without first authenticating
4095 If the peer does not wish to do callback at all,
4097 will accept the fact and continue without callback rather than terminating
4099 This is required (in addition to one or more other callback
4100 options) if you wish callback to be optional.
4104 .No *| Ns Ar number Ns Oo
4105 .No , Ns Ar number Ns ...\& Oc
4106 .Op Ar delay Op Ar retry
4108 If no arguments are given, CBCP (Microsoft's CallBack Control Protocol)
4109 is disabled - ie, configuring CBCP in the
4111 command will result in
4113 requesting no callback in the CBCP phase.
4116 attempts to use the given phone
4117 .Ar number Ns No (s).
4122 will insist that the client uses one of these numbers, unless
4124 is used in which case the client is expected to specify the number.
4128 will attempt to use one of the given numbers (whichever it finds to
4129 be agreeable with the peer), or if
4133 will expect the peer to specify the number.
4135 .No off| Ns Ar seconds Ns Op !\&
4139 checks for the existence of carrier depending on the type of device
4140 that has been opened:
4141 .Bl -tag -width XXX -offset XXX
4142 .It Terminal Devices
4143 Carrier is checked one second after the login script is complete.
4146 assumes that this is because the device doesn't support carrier (which
4149 NULL-modem cables), logs the fact and stops checking
4152 As ptys don't support the TIOCMGET ioctl, the tty device will switch all
4153 carrier detection off when it detects that the device is a pty.
4154 .It ISDN (i4b) Devices
4155 Carrier is checked once per second for 6 seconds.
4156 If it's not set after
4157 the sixth second, the connection attempt is considered to have failed and
4158 the device is closed.
4159 Carrier is always required for i4b devices.
4160 .It PPPoE (netgraph) Devices
4161 Carrier is checked once per second for 5 seconds.
4162 If it's not set after
4163 the fifth second, the connection attempt is considered to have failed and
4164 the device is closed.
4165 Carrier is always required for PPPoE devices.
4168 All other device types don't support carrier.
4169 Setting a carrier value will
4170 result in a warning when the device is opened.
4172 Some modems take more than one second after connecting to assert the carrier
4174 If this delay isn't increased, this will result in
4176 inability to detect when the link is dropped, as
4178 assumes that the device isn't asserting carrier.
4182 command overrides the default carrier behaviour.
4184 specifies the maximum number of seconds that
4186 should wait after the dial script has finished before deciding if
4187 carrier is available or not.
4193 will not check for carrier on the device, otherwise
4195 will not proceed to the login script until either carrier is detected
4198 has elapsed, at which point
4200 assumes that the device will not set carrier.
4202 If no arguments are given, carrier settings will go back to their default
4207 is followed immediately by an exclamation mark
4213 If carrier is not detected after
4215 seconds, the link will be disconnected.
4216 .It set choked Op Ar timeout
4217 This sets the number of seconds that
4219 will keep a choked output queue before dropping all pending output packets.
4222 is less than or equal to zero or if
4224 isn't specified, it is set to the default value of
4227 A choked output queue occurs when
4229 has read a certain number of packets from the local network for transmission,
4230 but cannot send the data due to link failure (the peer is busy etc.).
4232 will not read packets indefinitely.
4233 Instead, it reads up to
4239 packets in multi-link mode), then stops reading the network interface
4242 seconds have passed or at least one packet has been sent.
4246 seconds pass, all pending output packets are dropped.
4247 .It set ctsrts|crtscts on|off
4248 This sets hardware flow control.
4249 Hardware flow control is
4252 .It set deflate Ar out-winsize Op Ar in-winsize
4253 This sets the DEFLATE algorithms default outgoing and incoming window
4259 must be values between
4267 will insist that this window size is used and will not accept any other
4268 values from the peer.
4269 .It set dns Op Ar primary Op Ar secondary
4270 This command specifies DNS overrides for the
4275 command description above for details.
4276 This command does not affect the IP numbers requested using
4278 .It set device|line Xo
4281 This sets the device(s) to which
4283 will talk to the given
4286 All ISDN and serial device names are expected to begin with
4288 ISDN devices are usually called
4290 and serial devices are usually called
4297 it must either begin with an exclamation mark
4300 .No PPPoE: Ns Ar iface Ns Xo
4301 .Op \&: Ns Ar provider Ns
4305 .Ar host : port Op /tcp|udp .
4308 If it begins with an exclamation mark, the rest of the device name is
4309 treated as a program name, and that program is executed when the device
4311 Standard input, output and error are fed back to
4313 and are read and written as if they were a regular device.
4316 .No PPPoE: Ns Ar iface Ns Xo
4317 .Op \&: Ns Ar provider Ns
4319 specification is given,
4321 will attempt to create a
4323 over Ethernet connection using the given
4331 will attempt to loaded it using
4333 If this fails, an external program must be used such as the
4335 program available under OpenBSD.
4338 is passed as the service name in the PPPoE Discovery Initiation (PADI)
4340 If no provider is given, an empty value will be used.
4345 for further details.
4348 .Ar host Ns No : Ns Ar port Ns Oo
4351 specification is given,
4353 will attempt to connect to the given
4361 suffix is not provided, the default is
4363 Refer to the section on
4364 .Em PPP OVER TCP and UDP
4365 above for further details.
4371 will attempt to open each one in turn until it succeeds or runs out of
4373 .It set dial Ar chat-script
4374 This specifies the chat script that will be used to dial the other
4381 and to the example configuration files for details of the chat script
4383 It is possible to specify some special
4385 in your chat script as follows:
4386 .Bd -unfilled -offset indent
4388 When used as the last character in a
4390 string, this indicates that a newline should not be appended.
4392 When the chat script encounters this sequence, it delays two seconds.
4394 When the chat script encounters this sequence, it delays for one quarter of
4397 This is replaced with a newline character.
4399 This is replaced with a carriage return character.
4401 This is replaced with a space character.
4403 This is replaced with a tab character.
4405 This is replaced by the current phone number (see
4409 This is replaced by the current
4415 This is replaced by the current
4422 Note that two parsers will examine these escape sequences, so in order to
4425 see the escape character, it is necessary to escape it from the
4426 .Sq command parser .
4427 This means that in practice you should use two escapes, for example:
4428 .Bd -literal -offset indent
4429 set dial "... ATDT\\\\T CONNECT"
4432 It is also possible to execute external commands from the chat script.
4433 To do this, the first character of the expect or send string is an
4436 If a literal exclamation mark is required, double it up to
4438 and it will be treated as a single literal
4440 When the command is executed, standard input and standard output are
4441 directed to the open device (see the
4443 command), and standard error is read by
4445 and substituted as the expect or send string.
4448 is running in interactive mode, file descriptor 3 is attached to
4451 For example (wrapped for readability):
4452 .Bd -literal -offset indent
4453 set login "TIMEOUT 5 \\"\\" \\"\\" login:--login: ppp \e
4454 word: ppp \\"!sh \\\\-c \\\\\\"echo \\\\-n label: >&2\\\\\\"\\" \e
4455 \\"!/bin/echo in\\" HELLO"
4458 would result in the following chat sequence (output using the
4459 .Sq set log local chat
4460 command before dialing):
4461 .Bd -literal -offset indent
4466 Chat: Expecting: login:--login:
4467 Chat: Wait for (5): login:
4469 Chat: Expecting: word:
4470 Chat: Wait for (5): word:
4472 Chat: Expecting: !sh \\-c "echo \\-n label: >&2"
4473 Chat: Exec: sh -c "echo -n label: >&2"
4474 Chat: Wait for (5): !sh \\-c "echo \\-n label: >&2" --> label:
4475 Chat: Exec: /bin/echo in
4477 Chat: Expecting: HELLO
4478 Chat: Wait for (5): HELLO
4482 Note (again) the use of the escape character, allowing many levels of
4484 Here, there are four parsers at work.
4485 The first parses the original line, reading it as three arguments.
4486 The second parses the third argument, reading it as 11 arguments.
4487 At this point, it is
4490 signs are escaped, otherwise this parser will see them as constituting
4491 an expect-send-expect sequence.
4494 character is seen, the execution parser reads the first command as three
4497 itself expands the argument after the
4499 As we wish to send the output back to the modem, in the first example
4500 we redirect our output to file descriptor 2 (stderr) so that
4502 itself sends and logs it, and in the second example, we just output to stdout,
4503 which is attached directly to the modem.
4505 This, of course means that it is possible to execute an entirely external
4507 command rather than using the internal one.
4510 for a good alternative.
4512 The external command that is executed is subjected to the same special
4513 word expansions as the
4516 .It set enddisc Op label|IP|MAC|magic|psn value
4517 This command sets our local endpoint discriminator.
4518 If set prior to LCP negotiation, and if no
4520 command has been used,
4522 will send the information to the peer using the LCP endpoint discriminator
4524 The following discriminators may be set:
4525 .Bd -unfilled -offset indent
4527 The current label is used.
4529 Our local IP number is used.
4530 As LCP is negotiated prior to IPCP, it is
4531 possible that the IPCP layer will subsequently change this value.
4533 it does, the endpoint discriminator stays at the old value unless manually
4536 This is similar to the
4538 option above, except that the MAC address associated with the local IP
4540 If the local IP number is not resident on any Ethernet
4541 interface, the command will fail.
4543 As the local IP number defaults to whatever the machine host name is,
4545 is usually done prior to any
4549 A 20 digit random number is used.
4550 Care should be taken when using magic numbers as restarting
4552 or creating a link using a different
4554 invocation will also use a different magic number and will therefore not
4555 be recognised by the peer as belonging to the same bundle.
4556 This makes it unsuitable for
4564 should be set to an absolute public switched network number with the
4568 If no arguments are given, the endpoint discriminator is reset.
4569 .It set escape Ar value...
4570 This option is similar to the
4573 It allows the user to specify a set of characters that will be
4575 as they travel across the link.
4576 .It set filter dial|alive|in|out Ar rule-no Xo
4577 .No permit|deny|clear| Ns Ar rule-no
4580 .Ar src_addr Ns Op / Ns Ar width
4581 .Op Ar dst_addr Ns Op / Ns Ar width
4582 .Oc [ tcp|udp|ospf|igmp|icmp Op src lt|eq|gt Ar port
4583 .Op dst lt|eq|gt Ar port
4587 .Op timeout Ar secs ]
4590 supports four filter sets.
4593 filter specifies packets that keep the connection alive - resetting the
4597 filter specifies packets that cause
4604 filter specifies packets that are allowed to travel
4605 into the machine and the
4607 filter specifies packets that are allowed out of the machine.
4609 Filtering is done prior to any IP alterations that might be done by the
4610 NAT engine on outgoing packets and after any IP alterations that might
4611 be done by the NAT engine on incoming packets.
4612 By default all empty filter sets allow all packets to pass.
4613 Rules are processed in order according to
4615 (unless skipped by specifying a rule number as the
4617 Up to 40 rules may be given for each set.
4618 If a packet doesn't match
4619 any of the rules in a given set, it is discarded.
4624 filters, this means that the packet is dropped.
4627 filters it means that the packet will not reset the idle timer (even if
4629 .Ar in Ns No / Ns Ar out
4632 value) and in the case of
4634 filters it means that the packet will not trigger a dial.
4635 A packet failing to trigger a dial will be dropped rather than queued.
4638 .Sx PACKET FILTERING
4639 above for further details.
4640 .It set hangup Ar chat-script
4641 This specifies the chat script that will be used to reset the device
4642 before it is closed.
4643 It should not normally be necessary, but can
4644 be used for devices that fail to reset themselves properly on close.
4645 .It set help|? Op Ar command
4646 This command gives a summary of available set commands, or if
4648 is specified, the command usage is shown.
4649 .It set ifaddr Oo Ar myaddr Ns
4651 .Oo Ar hisaddr Ns Op / Ns Ar \&nn
4656 This command specifies the IP addresses that will be used during
4658 Addresses are specified using the format
4664 is the preferred IP, but
4666 specifies how many bits of the address we will insist on.
4669 is omitted, it defaults to
4671 unless the IP address is 0.0.0.0 in which case it defaults to
4674 If you wish to assign a dynamic IP number to the peer,
4676 may also be specified as a range of IP numbers in the format
4677 .Bd -ragged -offset indent
4678 .Ar \&IP Ns Oo \&- Ns Ar \&IP Ns Xo
4679 .Oc Ns Oo , Ns Ar \&IP Ns
4680 .Op \&- Ns Ar \&IP Ns
4687 .Dl set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20
4691 as the local IP number, but may assign any of the given 10 IP
4692 numbers to the peer.
4693 If the peer requests one of these numbers,
4694 and that number is not already in use,
4696 will grant the peers request.
4697 This is useful if the peer wants
4698 to re-establish a link using the same IP number as was previously
4699 allocated (thus maintaining any existing tcp or udp connections).
4701 If the peer requests an IP number that's either outside
4702 of this range or is already in use,
4704 will suggest a random unused IP number from the range.
4708 is specified, it is used in place of
4710 in the initial IPCP negotiation.
4711 However, only an address in the
4713 range will be accepted.
4714 This is useful when negotiating with some
4716 implementations that will not assign an IP number unless their peer
4720 It should be noted that in
4724 will configure the interface immediately upon reading the
4726 line in the config file.
4727 In any other mode, these values are just
4728 used for IPCP negotiations, and the interface isn't configured
4729 until the IPCP layer is up.
4733 argument may be overridden by the third field in the
4735 file once the client has authenticated itself
4736 .Pq if PAP or CHAP are Dq enabled .
4738 .Sx AUTHENTICATING INCOMING CONNECTIONS
4739 section for details.
4741 In all cases, if the interface is already configured,
4743 will try to maintain the interface IP numbers so that any existing
4744 bound sockets will remain valid.
4745 .It set ifqueue Ar packets
4746 Set the maximum number of packets that
4748 will read from the tunnel interface while data cannot be sent to any of
4749 the available links.
4750 This queue limit is necessary to flow control outgoing data as the tunnel
4751 interface is likely to be far faster than the combined links available to
4756 is set to a value less than the number of links,
4758 will read up to that value regardless.
4759 This prevents any possible latency problems.
4761 The default value for
4765 .It set ccpretry|ccpretries Oo Ar timeout
4766 .Op Ar reqtries Op Ar trmtries
4768 .It set chapretry|chapretries Oo Ar timeout
4771 .It set ipcpretry|ipcpretries Oo Ar timeout
4772 .Op Ar reqtries Op Ar trmtries
4774 .It set lcpretry|lcpretries Oo Ar timeout
4775 .Op Ar reqtries Op Ar trmtries
4777 .It set papretry|papretries Oo Ar timeout
4780 These commands set the number of seconds that
4782 will wait before resending Finite State Machine (FSM) Request packets.
4785 for all FSMs is 3 seconds (which should suffice in most cases).
4789 is specified, it tells
4791 how many configuration request attempts it should make while receiving
4792 no reply from the peer before giving up.
4793 The default is 5 attempts for
4794 CCP, LCP and IPCP and 3 attempts for PAP and CHAP.
4798 is specified, it tells
4800 how many terminate requests should be sent before giving up waiting for the
4802 The default is 3 attempts.
4803 Authentication protocols are
4804 not terminated and it is therefore invalid to specify
4808 In order to avoid negotiations with the peer that will never converge,
4810 will only send at most 3 times the configured number of
4812 in any given negotiation session before giving up and closing that layer.
4818 This command allows the adjustment of the current log level.
4819 Refer to the Logging Facility section for further details.
4820 .It set login Ar chat-script
4823 compliments the dial-script.
4824 If both are specified, the login
4825 script will be executed after the dial script.
4826 Escape sequences available in the dial script are also available here.
4827 .It set logout Ar chat-script
4828 This specifies the chat script that will be used to logout
4829 before the hangup script is called.
4830 It should not normally be necessary.
4831 .It set lqrperiod Ar frequency
4832 This command sets the
4839 The default is 30 seconds.
4840 You must also use the
4842 command if you wish to send LQR requests to the peer.
4843 .It set mode Ar interactive|auto|ddial|background
4844 This command allows you to change the
4846 of the specified link.
4847 This is normally only useful in multi-link mode,
4848 but may also be used in uni-link mode.
4850 It is not possible to change a link that is
4855 Note: If you issue the command
4857 and have network address translation enabled, it may be useful to
4858 .Dq enable iface-alias
4862 to do the necessary address translations to enable the process that
4863 triggers the connection to connect once the link is up despite the
4864 peer assigning us a new (dynamic) IP address.
4865 .It set mppe {40|56|128}
4866 This option selects particular key length. Default is 128.
4867 .It set mrru Op Ar value
4868 Setting this option enables Multi-link PPP negotiations, also known as
4869 Multi-link Protocol or MP.
4870 There is no default MRRU (Maximum Reconstructed Receive Unit) value.
4871 If no argument is given, multi-link mode is disabled.
4872 .It set mru Op Ar value
4873 The default MRU (Maximum Receive Unit) is 1500.
4874 If it is increased, the other side *may* increase its MTU.
4875 There is no point in decreasing the MRU to below the default as the
4877 protocol *must* be able to accept packets of at least 1500 octets.
4878 If no argument is given, 1500 is assumed.
4879 .It set mtu Op Ar value
4880 The default MTU is 1500.
4881 At negotiation time,
4883 will accept whatever MRU or MRRU that the peer wants (assuming it's
4884 not less than 296 bytes).
4887 will not accept MRU/MRRU values less than
4889 When negotiations are complete, the MTU is assigned to the interface, even
4890 if the peer requested a higher value MRU/MRRU.
4891 This can be useful for
4892 limiting your packet size (giving better bandwidth sharing at the expense
4893 of more header data).
4897 is given, 1500, or whatever the peer asks for is used.
4898 .It set nbns Op Ar x.x.x.x Op Ar y.y.y.y
4899 This option allows the setting of the Microsoft NetBIOS name server
4900 values to be returned at the peers request.
4901 If no values are given,
4903 will reject any such requests.
4904 .It set openmode active|passive Op Ar delay
4913 will always initiate LCP/IPCP/CCP negotiation one second after the line
4915 If you want to wait for the peer to initiate negotiations, you
4918 If you want to initiate negotiations immediately or after more than one
4919 second, the appropriate
4921 may be specified here in seconds.
4922 .It set parity odd|even|none|mark
4923 This allows the line parity to be set.
4924 The default value is
4926 .It set phone Ar telno Ns Xo
4927 .Oo \&| Ns Ar backupnumber
4928 .Oc Ns ... Ns Oo : Ns Ar nextnumber
4931 This allows the specification of the phone number to be used in
4932 place of the \\\\T string in the dial and login chat scripts.
4933 Multiple phone numbers may be given separated either by a pipe
4938 Numbers after the pipe are only dialed if the dial or login
4939 script for the previous number failed.
4941 Numbers after the colon are tried sequentially, irrespective of
4942 the reason the line was dropped.
4944 If multiple numbers are given,
4946 will dial them according to these rules until a connection is made, retrying
4947 the maximum number of times specified by
4952 mode, each number is attempted at most once.
4953 .It set Op proc Ns Xo
4954 .No title Op Ar value
4956 The current process title as displayed by
4958 is changed according to
4962 is not specified, the original process title is restored.
4964 word replacements done by the shell commands (see the
4966 command above) are done here too.
4968 Note, if USER is required in the process title, the
4970 command must appear in
4972 as it is not known when the commands in
4975 .It set radius Op Ar config-file
4976 This command enables RADIUS support (if it's compiled in).
4978 refers to the radius client configuration file as described in
4981 .Dq enable Ns No d ,
4984 .Em \&N Ns No etwork
4987 and uses the configured RADIUS server to authenticate rather than
4988 authenticating from the
4990 file or from the passwd database.
4992 If neither PAP or CHAP are enabled,
4997 uses the following attributes from the RADIUS reply:
4998 .Bl -tag -width XXX -offset XXX
4999 .It RAD_FRAMED_IP_ADDRESS
5000 The peer IP address is set to the given value.
5001 .It RAD_FRAMED_IP_NETMASK
5002 The tun interface netmask is set to the given value.
5004 If the given MTU is less than the peers MRU as agreed during LCP
5005 negotiation, *and* it is less that any configured MTU (see the
5007 command), the tun interface MTU is set to the given value.
5008 .It RAD_FRAMED_COMPRESSION
5009 If the received compression type is
5012 will request VJ compression during IPCP negotiations despite any
5014 configuration command.
5015 .It RAD_FRAMED_ROUTE
5016 The received string is expected to be in the format
5017 .Ar dest Ns Op / Ns Ar bits
5020 Any specified metrics are ignored.
5024 are understood as valid values for
5031 to sepcify the default route, and
5033 is understood to be the same as
5042 For example, a returned value of
5043 .Dq 1.2.3.4/24 0.0.0.0 1 2 -1 3 400
5044 would result in a routing table entry to the 1.2.3.0/24 network via
5046 and a returned value of
5050 would result in a default route to
5053 All RADIUS routes are applied after any sticky routes are applied, making
5054 RADIUS routes override configured routes.
5055 This also applies for RADIUS routes that don't include the
5062 Values received from the RADIUS server may be viewed using
5064 .It set reconnect Ar timeout ntries
5065 Should the line drop unexpectedly (due to loss of CD or LQR
5066 failure), a connection will be re-established after the given
5068 The line will be re-connected at most
5077 will result in a variable pause, somewhere between 1 and 30 seconds.
5078 .It set recvpipe Op Ar value
5079 This sets the routing table RECVPIPE value.
5080 The optimum value is just over twice the MTU value.
5083 is unspecified or zero, the default kernel controlled value is used.
5084 .It set redial Ar secs Ns Xo
5087 .Oc Ns Op . Ns Ar next
5091 can be instructed to attempt to redial
5094 If more than one phone number is specified (see
5098 is taken before dialing each number.
5101 is taken before starting at the first number again.
5104 may be used here in place of
5108 causing a random delay of between 1 and 30 seconds.
5112 is specified, its value is added onto
5118 will only be incremented at most
5126 delay will be effective, even after
5128 has been exceeded, so an immediate manual dial may appear to have
5130 If an immediate dial is required, a
5132 should immediately follow the
5137 description above for further details.
5138 .It set sendpipe Op Ar value
5139 This sets the routing table SENDPIPE value.
5140 The optimum value is just over twice the MTU value.
5143 is unspecified or zero, the default kernel controlled value is used.
5144 .It "set server|socket" Ar TcpPort Ns No \&| Ns Xo
5145 .Ar LocalName Ns No |none|open|closed
5146 .Op password Op Ar mask
5150 to listen on the given socket or
5152 for incoming command connections.
5158 to close any existing socket and clear the socket configuration.
5163 to attempt to re-open the port.
5168 to close the open port.
5170 If you wish to specify a local domain socket,
5172 must be specified as an absolute file name, otherwise it is assumed
5173 to be the name or number of a TCP port.
5174 You may specify the octal umask to be used with a local domain socket.
5180 for details of how to translate TCP port names.
5182 You must also specify the password that must be entered by the client
5185 variable above) when connecting to this socket.
5187 specified as an empty string, no password is required for connecting clients.
5189 When specifying a local domain socket, the first
5191 sequence found in the socket name will be replaced with the current
5192 interface unit number.
5193 This is useful when you wish to use the same
5194 profile for more than one connection.
5196 In a similar manner TCP sockets may be prefixed with the
5198 character, in which case the current interface unit number is added to
5203 with a server socket, the
5205 command is the preferred mechanism of communications.
5208 can also be used, but link encryption may be implemented in the future, so
5216 interact with the diagnostic socket.
5217 .It set speed Ar value
5218 This sets the speed of the serial device.
5219 If speed is specified as
5222 treats the device as a synchronous device.
5224 Certain device types will know whether they should be specified as
5225 synchronous or asynchronous.
5226 These devices will override incorrect
5227 settings and log a warning to this effect.
5228 .It set stopped Op Ar LCPseconds Op Ar CCPseconds
5229 If this option is set,
5231 will time out after the given FSM (Finite State Machine) has been in
5232 the stopped state for the given number of
5234 This option may be useful if the peer sends a terminate request,
5235 but never actually closes the connection despite our sending a terminate
5237 This is also useful if you wish to
5238 .Dq set openmode passive
5239 and time out if the peer doesn't send a Configure Request within the
5242 .Dq set log +lcp +ccp
5245 log the appropriate state transitions.
5247 The default value is zero, where
5249 doesn't time out in the stopped state.
5251 This value should not be set to less than the openmode delay (see
5254 .It set timeout Ar idleseconds Op Ar mintimeout
5255 This command allows the setting of the idle timer.
5256 Refer to the section titled
5257 .Sx SETTING THE IDLE TIMER
5258 for further details.
5264 will never idle out before the link has been up for at least that number
5272 This command controls the ports that
5274 prioritizes when transmitting data.
5275 The default priority TCP ports
5276 are ports 21 (ftp control), 22 (ssh), 23 (telnet), 513 (login), 514 (shell),
5277 543 (klogin) and 544 (kshell).
5278 There are no priority UDP ports by default.
5293 are given, the priority port lists are cleared (although if
5297 is specified, only that list is cleared).
5300 argument is prefixed with a plus
5304 the current list is adjusted, otherwise the list is reassigned.
5306 prefixed with a plus or not prefixed at all are added to the list and
5308 prefixed with a minus are removed from the list.
5312 is specified, all priority port lists are disabled and even
5314 packets are not prioritised.
5315 .It set vj slotcomp on|off
5318 whether it should attempt to negotiate VJ slot compression.
5319 By default, slot compression is turned
5321 .It set vj slots Ar nslots
5322 This command sets the initial number of slots that
5324 will try to negotiate with the peer when VJ compression is enabled (see the
5327 It defaults to a value of 16.
5336 .It shell|! Op Ar command
5339 is not specified a shell is invoked according to the
5341 environment variable.
5342 Otherwise, the given
5345 Word replacement is done in the same way as for the
5347 command as described above.
5349 Use of the ! character
5350 requires a following space as with any of the other commands.
5351 You should note that this command is executed in the foreground;
5353 will not continue running until this process has exited.
5356 command if you wish processing to happen in the background.
5358 This command allows the user to examine the following:
5361 Show the current bundle settings.
5363 Show the current CCP compression statistics.
5365 Show the current VJ compression statistics.
5367 Show the current escape characters.
5368 .It show filter Op Ar name
5369 List the current rules for the given filter.
5372 is not specified, all filters are shown.
5374 Show the current HDLC statistics.
5376 Give a summary of available show commands.
5378 Show the current interface information
5379 .Pq the same \&as Dq iface show .
5381 Show the current IPCP statistics.
5383 Show the protocol layers currently in use.
5385 Show the current LCP statistics.
5386 .It show Op data Ns Xo
5389 Show high level link information.
5391 Show a list of available logical links.
5393 Show the current log values.
5395 Show current memory statistics.
5397 Show low level link information.
5399 Show Multi-link information.
5401 Show current protocol totals.
5403 Show the current routing tables.
5405 Show the current stopped timeouts.
5407 Show the active alarm timers.
5409 Show the current version number of
5414 Go into terminal mode.
5415 Characters typed at the keyboard are sent to the device.
5416 Characters read from the device are displayed on the screen.
5421 automatically enables Packet Mode and goes back into command mode.
5427 Read the example configuration files.
5428 They are a good source of information.
5437 to get online information about what's available.
5439 The following URLs contain useful information:
5440 .Bl -bullet -compact
5442 http://www.FreeBSD.org/FAQ/userppp.html
5444 http://www.FreeBSD.org/handbook/userppp.html
5451 refers to four files:
5457 These files are placed in the
5461 .It Pa /etc/ppp/ppp.conf
5462 System default configuration file.
5463 .It Pa /etc/ppp/ppp.secret
5464 An authorisation file for each system.
5465 .It Pa /etc/ppp/ppp.linkup
5466 A file to check when
5468 establishes a network level connection.
5469 .It Pa /etc/ppp/ppp.linkdown
5470 A file to check when
5472 closes a network level connection.
5473 .It Pa /var/log/ppp.log
5474 Logging and debugging information file.
5475 Note, this name is specified in
5476 .Pa /etc/syslogd.conf .
5479 for further details.
5480 .It Pa /var/spool/lock/LCK..*
5481 tty port locking file.
5484 for further details.
5485 .It Pa /var/run/tunN.pid
5486 The process id (pid) of the
5488 program connected to the tunN device, where
5490 is the number of the device.
5491 .It Pa /var/run/ttyXX.if
5492 The tun interface used by this port.
5493 Again, this file is only created in
5499 .It Pa /etc/services
5500 Get port number if port number is using service name.
5501 .It Pa /var/run/ppp-authname-class-value
5502 In multi-link mode, local domain sockets are created using the peer
5505 the peer endpoint discriminator class
5507 and the peer endpoint discriminator value
5509 As the endpoint discriminator value may be a binary value, it is turned
5510 to HEX to determine the actual file name.
5512 This socket is used to pass links between different instances of
5553 This program was originally written by
5554 .An Toshiharu OHNO Aq tony-o@iij.ad.jp ,
5555 and was submitted to
5558 .An Atsushi Murai Aq amurai@spec.co.jp .
5560 It was substantially modified during 1997 by
5561 .An Brian Somers Aq brian@Awfulhak.org ,
5564 in November that year
5565 (just after the 2.2 release).
5567 Most of the code was rewritten by
5569 in early 1998 when multi-link ppp support was added.
projects / FreeBSD / FreeBSD.git / blob