NAME

SYNOPSIS

DESCRIPTION

-auto

ppp opens the tun interface, configures it, then goes into the background. The link isn't brought up until outgoing data is detected on the tun interface at which point ppp attempts to bring up the link. Packets received (including the first one) while ppp is trying to bring the link up will remain queued for a default of 2 minutes. See the setchoked command below.

In -auto mode, at least one system must be given on the command line (see below) and a setifaddr must be done in the system profile that specifies a peer IP address to use when configuring the interface. Something like “10.0.0.1/0” is usually appropriate. See the “pmdemand” system in /etc/ppp/ppp.conf.sample for an example.

-background

Here, ppp attempts to establish a connection with the peer immediately. If it succeeds, ppp goes into the background and the parent process returns an exit code of 0. If it fails, ppp exits with a non-zero result.

-foreground

In foreground mode, ppp attempts to establish a connection with the peer immediately, but never becomes a daemon. The link is created in background mode. This is useful if you wish to control ppp invocation from another process.

-direct

This is used for communicating over an already established connection, usually when receiving incoming connections accepted by getty(8). ppp ignores the setdevice line and uses descriptor 0 as the link. ppp will also ignore any configured chat scripts unless the “force-scripts” option has been enabled.

If callback is configured, ppp will use the setdevice information when dialing back.

-dedicated

This option is designed for machines connected with a dedicated wire. ppp will always keep the device open and will ignore any configured chat scripts unless the “force-scripts” option has been enabled.

-ddial

This mode is equivalent to -auto mode except that ppp will bring the link back up any time it's dropped for any reason.

-interactive

This is a no-op, and gives the same behaviour as if none of the above modes have been specified. ppp loads any sections specified on the command line, then provides an interactive prompt.

Major Features

PERMISSIONS

GETTING STARTED

• Your kernel must include a tunnel device (the GENERIC kernel includes one by default). If it doesn't, you'll need to rebuild your kernel with the following line in your kernel configuration file:
       pseudo-device tun
  Tun interfaces can be created at runtime using the -ifconfigtunN create command or by opening the character special device /dev/tunN. See ifconfig(8) and tun(4) for more information.
• Check your /dev directory for the tunnel device entries /dev/tunN, where ‘N’ represents the number of the tun device, starting at zero. If they don't exist, you can create them by running "sh ./MAKEDEV tunN". This will create tun devices 0 through N.
• Make sure that your system has a group named “network” in the /etc/group file and that the group contains the names of all users expected to use ppp. Refer to the group(5) manual page for details. Each of these users must also be given access using the allowusers command in /etc/ppp/ppp.conf.
• Create a log file. ppp uses syslog(3) to log information. A common log file name is /var/log/ppp.log. To make output go to this file, put the following lines in the /etc/syslog.conf file:

  !ppp
  *.*/var/log/ppp.log
  

  It is possible to have more than one PPP log file by creating a link to the ppp executable:
       # cd /usr/sbin      # ln ppp ppp0
  and using

  !ppp0
  *.*/var/log/ppp0.log
  

  in /etc/syslog.conf. Don't forget to send a HUP signal to syslogd(8) after altering /etc/syslog.conf.
• Although not strictly relevant to ppp operation, you should configure your resolver so that it works correctly. This can be done by configuring a local DNS (using named(8)) or by adding the correct “nameserver” lines to the file /etc/resolv.conf. Refer to the resolv.conf(5) manual page for details.
  Alternatively, if the peer supports it, ppp can be configured to ask the peer for the nameserver address(es) and to update /etc/resolv.conf automatically. Refer to the enabledns and resolv commands below for details.

MANUAL DIALING

ppp ON awfulhak>

ppp ON awfulhak> set device /dev/cua00
ppp ON awfulhak> set speed 38400

ppp ON awfulhak> set parity even

ppp ON awfulhak> show physical
Name: deflink
 State:           closed
 Device:          N/A
 Link Type:       interactive
 Connect Count:   0
 Queued Packets:  0
 Phone Number:    N/A

Defaults:
 Device List:     /dev/cua00
 Characteristics: 38400bps, cs8, even parity, CTS/RTS on

Connect time: 0 secs
0 octets in, 0 octets out
Overall 0 bytes/sec
ppp ON awfulhak>

ppp ON awfulhak> term
at
OK
atdt123456
CONNECT
login: myispusername
Password: myisppassword
Protocol: ppp

ppp ON awfulhak>               # No link has been established
Ppp ON awfulhak>               # We've connected & finished LCP
PPp ON awfulhak>               # We've authenticated
PPP ON awfulhak>               # We've agreed IP numbers

~.
ppp ON awfulhak> set authname myispusername
ppp ON awfulhak> set authkey myisppassword
ppp ON awfulhak> term
at
OK
atdt123456
CONNECT

~p
ppp ON awfulhak>               # No link has been established
Ppp ON awfulhak>               # We've connected & finished LCP
PPp ON awfulhak>               # We've authenticated
PPP ON awfulhak>               # We've agreed IP numbers

ppp ON awfulhak> set log local phase lcp ipcp

PPP ON awfulhak> show physical
* Modem related information is shown here *
PPP ON awfulhak> show ccp
* CCP (compression) related information is shown here *
PPP ON awfulhak> show lcp
* LCP (line control) related information is shown here *
PPP ON awfulhak> show ipcp
* IPCP (IP) related information is shown here *
PPP ON awfulhak> show ipv6cp
* IPV6CP (IPv6) related information is shown here *
PPP ON awfulhak> show link
* Link (high level) related information is shown here *
PPP ON awfulhak> show bundle
* Logical (high level) connection related information is shown here *

PPP ON awfulhak> add default HISADDR

PPP ON awfulhak> add! default HISADDR

AUTOMATIC DIALING

• A line starting with a ‘#’ character is treated as a comment line. Leading whitespace is ignored when identifying comment lines.
• An inclusion is a line beginning with the word “!include”. It must have one argument \- the file to include. You may wish to “!include ~/.ppp.conf” for compatibility with older versions of ppp.
• A label name starts in the first column and is followed by a ‘\&:’ character.
• A command line must contain a space or tab in the first column.
• A string starting with a ‘$’ character is substituted with the value of the environment variable by the same name. Likewise, a string starting with a ‘~’ character is substituted with the full path to the home directory of the user account by the same name, and the ‘~’ character by itself is substituted with the full path to the home directory of the current user. Any characters following a ‘#’ character are ignored. To include a literal ‘$’, ‘~’, or ‘#’ character in a command or argument, escape it with a ‘\e’ character or quote the command/argument using the ‘\&"’ character. For example:
       set password pa\e$ss\e~word      set password \&"user#1234@example.net\&"

ppp ON awfulhak> load MyISP

# ppp MyISP
\&...
ppp ON awfulhak> dial
Ppp ON awfulhak>
PPp ON awfulhak>
PPP ON awfulhak>

BACKGROUND DIALING

DIAL ON DEMAND

# ppp -auto pmdemand

# pppctl 3000	(assuming tun0)
Password:
PPP ON awfulhak> show who
tcp (127.0.0.1:1028) *

secs

The number of seconds to wait before attempting to connect again. If the argument is the literal string ‘random’, the delay period is a random value between 1 and 30 seconds inclusive.

inc

The number of seconds that secs should be incremented each time a new dial attempt is made. The timeout reverts to secs only after a successful connection is established. The default value for inc is zero.

max

The maximum number of times ppp should increment secs. The default value for max is 10.

next

The number of seconds to wait before attempting to dial the next number in a list of numbers (see the setphone command). The default is 3 seconds. Again, if the argument is the literal string ‘random’, the delay period is a random value between 1 and 30 seconds.

attempts

The maximum number of times to try to connect for each outgoing packet that triggers a dial. The previous value is unchanged if this parameter is omitted. If a value of zero is specified for attempts, ppp will keep trying until a connection is made.

set redial 10.3 4

set redial 10+10-5.3 20

set reconnect timeout ntries

set reconnect 3 5

PPP ON awfulhak> close
ppp ON awfulhak> quit all

RECEIVING INCOMING PPP CONNECTIONS (Method 1)

1. Make sure the modem is configured correctly:
   • Use Hardware Handshake (CTS/RTS) for flow control.
   • Modem should be set to NO echo back (ATE0) and NO results string (ATQ1).

2. Edit /etc/ttys to enable a getty(8) on the port where the modem is attached. For example:
        ttyd1 Qo /usr/libexec/getty std.38400 Qc dialup on secure
   Don't forget to send a HUP signal to the init(8) process to start the getty(8):
        # kill -HUP 1
   It is usually also necessary to train your modem to the same DTR speed as the getty:

   # ppp
   ppp ON awfulhak> set device /dev/cua01
   ppp ON awfulhak> set speed 38400
   ppp ON awfulhak> term
   deflink: Entering terminal mode on /dev/cua01
   Type `~?' for help
   at
   OK
   at
   OK
   atz
   OK
   at
   OK
   ~.
   ppp ON awfulhak> quit
   

3. Create a /usr/local/bin/ppplogin file with the following contents:

   #! /bin/sh
   exec /usr/sbin/ppp -direct incoming
   

   Direct mode (-direct) lets ppp work with stdin and stdout. You can also use pppctl(8) to connect to a configured diagnostic port, in the same manner as with client-side ppp.
   Here, the incoming section must be set up in /etc/ppp/ppp.conf.
   Make sure that the incoming section contains the “allow users” command as appropriate.
4. Prepare an account for the incoming user.

   ppp:xxxx:66:66:PPP Login User:/home/ppp:/usr/local/bin/ppplogin
   

   Refer to the manual entries for adduser(8) and vipw(8) for details.
5. Support for IPCP Domain Name Server and NetBIOS Name Server negotiation can be enabled using the acceptdns and setnbns commands. Refer to their descriptions below.

RECEIVING INCOMING PPP CONNECTIONS (Method 2)

1. Configure your default section in /etc/gettytab with automatic ppp recognition by specifying the ‘pp’ capability:

   default:\\
   	:pp=/usr/local/bin/ppplogin:\\
   	.....
   

2. Configure your serial device(s), enable a getty(8), and create /usr/local/bin/ppplogin as in the first three steps for method 1 above.
3. Add either “enable chap” or “enable pap” (or both) to /etc/ppp/ppp.conf under the “incoming” label (or whatever label ppplogin uses).
4. Create an entry in /etc/ppp/ppp.secret for each incoming user:

   Pfredxxxx
   Pgeorgeyyyy
   

AUTHENTICATING INCOMING CONNECTIONS

PPP OVER TCP and UDP (a.k.a. Tunnelling)

ppp-in:
 set timeout 0
 set ifaddr 10.0.4.1 10.0.4.2

ppp-in:
 add 10.0.1.0/24 HISADDR

 enable PAP

MyAuthName MyAuthPasswd

ui-gate:
 set escape 0xff
 set device ui-gate:ppp-in/tcp
 set dial
 set timeout 30
 set log Phase Chat Connect hdlc LCP IPCP IPV6CP CCP tun
 set ifaddr 10.0.4.2 10.0.4.1

ui-gate:
 add 10.0.2.0/24 HISADDR

 set authname MyAuthName
 set authkey MyAuthKey

ui-gate:
 set escape 0xff
 set device ui-gate:ppp-in/tcp
 add ui-gate x.x.x.x
 .....

  enable MSCHAPv2
  disable deflate pred1
  deny deflate pred1

NETWORK ADDRESS TRANSLATION (PACKET ALIASING)

PACKET FILTERING

• A filter definition has the following syntax:
  setfilter name rule-no action [!\&] .Oo [host] src_addr [dst_addr] .Oc [proto [src cmpport] [dst cmpport] [estab] [syn] [finrst] [timeout secs]]
  1. Name should be one of “in”, “out”, “dial”, or “alive”.
  2. Rule-no is a numeric value between 0 and 39 specifying the rule number. Rules are specified in numeric order according to rule-no, but only if rule 0 is defined.
  3. Action may be specified as “permit” or “deny”, in which case if a given packet matches the rule, the associated action is taken immediately. Action can also be specified as “clear” to clear the action associated with that particular rule, or as a new rule number greater than the current rule. In this case, if a given packet matches the current rule, the packet will next be matched against the new rule number (rather than the next rule number).
     The action may optionally be followed with an exclamation mark (‘!\&’), telling ppp to reverse the sense of the following match.
  4. [src_addr] and [dst_addr] are the source and destination IP number specifications. If [/ ] is specified, it gives the number of relevant netmask bits, allowing the specification of an address range.
     Either src_addr or dst_addr may be given the values MYADDR, HISADDR, MYADDR6, or HISADDR6 (refer to the description of the bg command for a description of these values). When these values are used, the filters will be updated any time the values change. This is similar to the behaviour of the add command below.
  5. Proto may be any protocol from protocols(5).
  6. Cmp is one of ‘\<’, ‘\&eq’, or ‘\>’, meaning less-than, equal, and greater-than, respectively. Port can be specified as a numeric port or by a service name from /etc/services.
  7. The ‘estab’, ‘syn’, and ‘finrst’ flags are only allowed when proto is set to ‘tcp’, and represent the TH_ACK, TH_SYN, and TH_FIN or TH_RST TCP flags, respectively.
  8. The timeout value adjusts the current idle timeout to at least secs seconds. If a timeout is given in the alive filter as well as in the in/out filter, the in/out value is used. If no timeout is given, the default timeout (set using settimeout and defaulting to 180 seconds) is used.

• Each filter can hold up to 40 rules, starting from rule 0. The entire rule set is not effective until rule 0 is defined, i.e., the default is to allow everything through.
• If no rule in a defined set of rules matches a packet, that packet will be discarded (blocked). If there are no rules in a given filter, the packet will be permitted.
• It's possible to filter based on the payload of UDP frames where those frames contain a PROTO_IP PPP frame header. See the filter-decapsulation option below for further details.
• Use “set filter name \-1” to flush all rules.

SETTING THE IDLE TIMER

ppp ON awfulhak> set timeout 600

ppp ON awfulhak> set timeout 0

PREDICTOR-1 and DEFLATE COMPRESSION

CONTROLLING IP ADDRESS

set ifaddr 192.244.177.38 192.244.177.2 255.255.255.255 0.0.0.0

• I will first suggest that my IP address should be 0.0.0.0, but I will only accept an address of 192.244.177.38.
• I strongly insist that the peer uses 192.244.177.2 as his own address and won't permit the use of any IP address but 192.244.177.2. When the peer requests another IP address, I will always suggest that it uses 192.244.177.2.
• The routing table entry will have a netmask of 0xffffffff.

• I'd like to use 192.244.177.38 as my address if it is possible, but I'll also accept any IP address between 192.244.177.0 and 192.244.177.255.
• I'd like to make him use 192.244.177.2 as his own address, but I'll also permit him to use any IP address between 192.244.176.0 and 192.244.191.255.
• As you may have already noticed, 192.244.177.2 is equivalent to saying 192.244.177.2/32.
• As an exception, 0 is equivalent to 0.0.0.0/0, meaning that I have no preferred IP address and will obey the remote peer's selection. When using zero, no routing table entries will be made until a connection is established.
• 192.244.177.2/0 means that I'll accept/permit any IP address but I'll suggest that 192.244.177.2 be used first.

CONNECTING WITH YOUR INTERNET SERVICE PROVIDER

1. Describe your providers phone number(s) in the dial script using the setphone command. This command allows you to set multiple phone numbers for dialing and redialing separated by either a pipe (‘\&|’) or a colon (‘\&:’): setphone telno .Oo \&| Ns Ar backupnumber .Oc Ns ... Ns Oo : Ns Ar nextnumber .Oc Ns ...
   Numbers after the first in a pipe-separated list are only used if the previous number was used in a failed dial or login script. Numbers separated by a colon are used sequentially, irrespective of what happened as a result of using the previous number. For example:

   set phone "1234567|2345678:3456789|4567890"
   

   Here, the 1234567 number is attempted. If the dial or login script fails, the 2345678 number is used next time, but *only* if the dial or login script fails. On the dial after this, the 3456789 number is used. The 4567890 number is only used if the dial or login script using the 3456789 fails. Irrespective of whether the login script of the 2345678 number succeeds or fails, the next number is still the 3456789 number.
   As many pipes and colons can be used as are necessary (although a given site would usually prefer to use either the pipe or the colon, but not both). The next number redial timeout is used between all numbers. When the end of the list is reached, the normal redial period is used before starting at the beginning again. The selected phone number is substituted for the \\\\T string in the setdial command (see below).
2. Set up your redial requirements using setredial. For example, if you have a bad telephone line or your provider is usually engaged (not so common these days), you may want to specify the following:

   set redial 10 4
   

   This says that up to 4 phone calls should be attempted with a pause of 10 seconds before dialing the first number again.
3. Describe your login procedure using the setdial and setlogin commands. The setdial command is used to talk to your modem and establish a link with your ISP, for example:

   set dial "ABORT BUSY ABORT NO\\\\sCARRIER TIMEOUT 4 \\"\\" \e
     ATZ OK-ATZ-OK ATDT\\\\T TIMEOUT 60 CONNECT"
   

   This modem "chat" string means:
   • Abort if the string "BUSY" or "NO CARRIER" is received.
   • Set the timeout to 4 seconds.
   • Expect nothing.
   • Send ATZ.
   • Expect OK. If that's not received within the 4 second timeout, send ATZ and expect OK.
   • Send ATDTxxxxxxx where xxxxxxx is the next number in the phone list from above.
   • Set the timeout to 60.
   • Wait for the CONNECT string.
   Once the connection is established, the login script is executed. This script is written in the same style as the dial script, but care should be taken to avoid having your password logged:

   set authkey MySecret
   set login "TIMEOUT 15 login:-\\\\r-login: awfulhak \e
     word: \\\\P ocol: PPP HELLO"
   

   This login "chat" string means:
   • Set the timeout to 15 seconds.
   • Expect "login:". If it's not received, send a carriage return and expect "login:" again.
   • Send "awfulhak".
   • Expect "word:" (the tail end of a "Password:" prompt).
   • Send whatever our current authkey value is set to.
   • Expect "ocol:" (the tail end of a "Protocol:" prompt).
   • Send "PPP".
   • Expect "HELLO".
   The setauthkey command is logged specially. When command or chat logging is enabled, the actual password is not logged; ‘********’ is logged instead.
   Login scripts vary greatly between ISPs. If you're setting one up for the first time, ENABLE CHAT LOGGING so that you can see if your script is behaving as you expect.
4. Use setdevice and setspeed to specify your serial line and speed, for example:

   set device /dev/cua00
   set speed 115200
   

   The first serial port is cua00. The modem will attach at either com(4) or ucom(4). So, for example, if the modem attaches at “com3”, device should be set to /dev/cua03.
   A speed of 115200 should be specified if you have a modem capable of bit rates of 28800 or more. In general, the serial speed should be about four times the modem speed.
5. Use the setifaddr command to define the IP address.
   • If you know what IP address your provider uses, then use it as the remote address (dst_addr), otherwise choose something like 10.0.0.2/0 (see below).
   • If your provider has assigned a particular IP address to you, then use it as your address (src_addr).
   • If your provider assigns your address dynamically, choose a suitably unobtrusive and unspecific IP number as your address. 10.0.0.1/0 would be appropriate. The bit after the / specifies how many bits of the address you consider to be important, so if you wanted to insist on something in the class C network 1.2.3.0, you could specify 1.2.3.1/24.
   • If you find that your ISP accepts the first IP number that you suggest, specify third and forth arguments of “0.0.0.0”. This will force your ISP to assign a number (the third argument will be ignored as it is less restrictive than the default mask for your ‘src_addr)’.
   An example for a connection where you don't know your IP number or your ISP's IP number would be:

   set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0
   

6. In most cases, your ISP will also be your default router. If this is the case, add the following line to /etc/ppp/ppp.conf (or to /etc/ppp/ppp.linkup for setups that don't use -auto mode):

   add default HISADDR
   

   This tells ppp to add a default route to whatever the peer address is (10.0.0.2 in this example). This route is “sticky”, meaning that should the value of HISADDR change, the route will be updated accordingly.
7. If your provider requests that you use PAP/CHAP authentication methods, add the next lines to your /etc/ppp/ppp.conf file:

   set authname MyName
   set authkey MyPassword
   

   Both are accepted by default, so ppp will provide whatever your ISP requires.
   It should be noted that a login script is rarely (if ever) required when PAP or CHAP are in use.
8. Ask your ISP to authenticate your nameserver address(es) with the following line:

   enable dns
   

   Do NOT do this if you are running a local DNS unless you also either use “resolv readonly” or have “resolv restore” in /etc/ppp/ppp.linkdown, as ppp will simply circumvent its use by entering some nameserver lines in /etc/resolv.conf.

LOGGING FACILITY

All

Enable all logging facilities. This generates a lot of log. The most common use of “all” is as a basis, where you remove some facilities after enabling “all” .Pf ( Dq debug and “timer” are usually best disabled).

Async

Dump async level packet in hex.

CBCP

Generate CBCP (CallBack Control Protocol) logs.

CCP

Generate a CCP packet trace.

Chat

Generate “dial”, “login”, “logout”, and “hangup” chat script trace logs.

Command

Log commands executed either from the command line or any of the configuration files.

Connect

Log Chat lines containing the string "CONNECT".

Debug

Log debug information.

DNS

Log DNS QUERY packets.

Filter

Log packets permitted by the dial filter and denied by any filter.

HDLC

Dump HDLC packet in hex.

ID0

Log all function calls specifically made as user ID 0.

IPCP

Generate an IPCP packet trace.

LCP

Generate an LCP packet trace.

LQM

Generate LQR reports.

Phase

Phase transition log output.

Physical

Dump physical level packet in hex.

Radius

Dump RADIUS information. RADIUS information resulting from the link coming up or down is logged at “Phase” level unless “Radius” logging is enabled. This log level is most useful for monitoring RADIUS alive information.

Sync

Dump sync level packet in hex.

TCP/IP

Dump all TCP/IP packets.

Timer

Log timer manipulation.

TUN

Include the tun(4) device on each log line.

Warning

Output to the terminal device. If there is currently no terminal, output is sent to the log file using syslog's LOG_WARNING.

Error

Output to both the terminal device and the log file using syslog's LOG_ERROR.

Alert

Output to the log file using LOG_ALERT.

PPP ON awfulhak> set log phase
PPP ON awfulhak> show log
Log:   Phase Warning Error Alert
Local: Warning Error Alert
PPP ON awfulhak> set log +tcp/ip -warning
PPP ON awfulhak> set log local +command
PPP ON awfulhak> show log
Log:   Phase TCP/IP Warning Error Alert
Local: Command Warning Error Alert

SIGNAL HANDLING

INT

Receipt of this signal causes the termination of the current connection (if any). This will cause ppp to exit unless it is in -auto or -ddial mode.

HUP, TERM, & QUIT

These signals tell ppp to exit.

USR1

This signal tells ppp to re-open any existing server socket, dropping all existing diagnostic connections. Sockets that couldn't previously be opened will be retried.

USR2

This signal tells ppp to close any existing server socket, dropping all existing diagnostic connections. SIGUSR1 can still be used to re-open the socket.

MULTI-LINK PPP

1. The new link has its own name as specified on the clone command line.
2. The new link is an “interactive” link. Its mode may subsequently be changed using the setmode command.
3. The new link is in a “closed” state.

mp:
 set timeout 0
 set log phase chat
 set device /dev/cua00 /dev/cua01 /dev/cua02
 set phone "123456789"
 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \\"\\" ATZ \e
           OK-AT-OK \\\\dATDT\\\\T TIMEOUT 45 CONNECT"
 set login
 set ifaddr 10.0.0.1/0 10.0.0.2/0 0.0.0.0 0.0.0.0
 set authname ppp
 set authkey ppppassword

 set mrru 1500
 clone 1,2,3	     # Create 3 new links - duplicates of the default
 link deflink remove # Delete the default link (called ``deflink'')

link 1,2,3 set mode ddial

link * set mode auto

link 1 set device /dev/cua00
link 2 set device /dev/cua01
link 3 set device /dev/cua02

PPP COMMAND LIST

accept\&| deny\&| enable\&| disable option.... These directives tell ppp how to negotiate the initial connection with the peer. Each option has a default of either accept or deny and enable or disable. “Accept” means that the option will be ACK'd if the peer asks for it. “Deny” means that the option will be NAK'd if the peer asks for it. “Enable” means that the option will be requested by us. “Disable” means that the option will not be requested by us.

option may be one of the following:

acfcomp

Default: Enabled and Accepted. ACFComp stands for Address and Control Field Compression. Non LCP packets will usually have an address field of 0xff (the All-Stations address) and a control field of 0x03 (the Unnumbered Information command). If this option is negotiated, these two bytes are simply not sent, thus minimising traffic.

See RFC 1662 for details.

chap

Default: Disabled and Accepted. CHAP stands for Challenge Handshake Authentication Protocol. Only one of CHAP and PAP (below) may be negotiated. With CHAP, the authenticator sends a "challenge" message to its peer. The peer uses a one-way hash function to encrypt the challenge and sends the result back. The authenticator does the same, and compares the results. The advantage of this mechanism is that no passwords are sent across the connection. A challenge is made when the connection is first made. Subsequent challenges may occur. If you want to have your peer authenticate itself, you must “enable chap” in /etc/ppp/ppp.conf, and have an entry in /etc/ppp/ppp.secret for the peer.

When using CHAP as the client, you need only specify “AuthName” and “AuthKey” in /etc/ppp/ppp.conf. CHAP is accepted by default. Some PPP implementations use "MS-CHAP" rather than MD5 when encrypting the challenge. MS-CHAP is a combination of MD4 and DES. If ppp was built on a machine with DES libraries available, it will respond to MS-CHAP authentication requests, but will never request them.

deflate

Default: Enabled and Accepted. This option decides if deflate compression will be used by the Compression Control Protocol (CCP). This is the same algorithm as used by the gzip(1) program. Note: There is a problem negotiating deflate capabilities with pppd(8) \- a PPP implementation available under many operating systems. pppd (version 2.3.1) incorrectly attempts to negotiate deflate compression using type 24 as the CCP configuration type rather than type 26 as specified in RFC 1979. Type 24 is actually specified as “PPP Magna-link Variable Resource Compression” in RFC 1975! ppp is capable of negotiating with pppd, but only if “deflate24” is enabled and accepted.

deflate24

Default: Disabled and Denied. This is a variance of the deflate option, allowing negotiation with the pppd(8) program. Refer to the deflate section above for details. It is disabled by default as it violates RFC 1975.

dns

Default: Disabled and Denied. This option allows DNS negotiation.

If enabled, ppp will request that the peer confirms the entries in /etc/resolv.conf. If the peer NAKs our request (suggesting new IP numbers), /etc/resolv.conf is updated and another request is sent to confirm the new entries.

If accepted, ppp will answer any DNS queries requested by the peer rather than rejecting them. The answer is taken from /etc/resolv.conf unless the setdns command is used as an override.

enddisc

Default: Enabled and Accepted. This option allows control over whether we negotiate an endpoint discriminator. We only send our discriminator if setenddisc is used and enddisc is enabled. We reject the peer's discriminator if enddisc is denied.

LANMan|chap80lm

Default: Disabled and Accepted. The use of this authentication protocol is discouraged as it partially violates the authentication protocol by implementing two different mechanisms (LANMan & NT) under the guise of a single CHAP type (0x80). “LANMan” uses a simple DES encryption mechanism and is the least secure of the CHAP alternatives (although still more secure than PAP).

Refer to the “MSChap” description below for more details.

lqr

Default: Disabled and Accepted. This option decides if Link Quality Requests will be sent or accepted. LQR is a protocol that allows ppp to determine that the link is down without relying on the modem's carrier detect. When LQR is enabled, ppp sends the QUALPROTO option (see “set lqrperiod” below) as part of the LCP request. If the peer agrees, both sides will exchange LQR packets at the agreed frequency, allowing detailed link quality monitoring by enabling LQM logging. If the peer doesn't agree, and if the “echo” option is enabled, ppp will send LCP ECHO requests instead. These packets pass no information of interest, but they MUST be replied to by the peer.

Whether using LQR or LCP ECHO, ppp will abruptly drop the connection if 5 unacknowledged packets have been sent rather than sending a 6th. A message is logged at the PHASE level, and any appropriate “reconnect” values are honoured as if the peer were responsible for dropping the connection.

Refer to the “enable echo” command description for differences in behaviour prior to ppp version 3.4.2.

mppe

Default: Enabled and Accepted. This is Microsoft Point to Point Encryption scheme. MPPE key size can be 40-, 56-, and 128-bits. Refer to the setmppe command.

MSChapV2|chap81

Default: Disabled and Accepted. It is very similar to standard CHAP (type 0x05) except that it issues challenges of a fixed 16 bytes in length and uses a combination of MD4, SHA-1, and DES to encrypt the challenge rather than using the standard MD5 mechanism.

MSChap|chap80nt

Default: Disabled and Accepted. The use of this authentication protocol is discouraged as it partially violates the authentication protocol by implementing two different mechanisms (LANMan & NT) under the guise of a single CHAP type (0x80). It is very similar to standard CHAP (type 0x05) except that it issues challenges of a fixed 8 bytes in length and uses a combination of MD4 and DES to encrypt the challenge rather than using the standard MD5 mechanism. CHAP type 0x80 for LANMan is also supported \- see “enable LANMan” for details.

Because both “LANMan” and ‘NT’ use CHAP type 0x80, when acting as authenticator with both enabled, ppp will rechallenge the peer up to three times if it responds using the wrong one of the two protocols. This gives the peer a chance to attempt using both protocols.

Conversely, when ppp acts as the authenticatee with both protocols accepted, the protocols are used alternately in response to challenges.

Note: If only LANMan is enabled, pppd(8) (version 2.3.5) misbehaves when acting as authenticatee. It provides both the NT and the LANMan answers, but also suggests that only the NT answer should be used.

pap

Default: Disabled and Accepted. PAP stands for Password Authentication Protocol. Only one of PAP and CHAP (above) may be negotiated. With PAP, the ID and Password are sent repeatedly to the peer until authentication is acknowledged or the connection is terminated. This is a rather poor security mechanism. It is only performed when the connection is first established. If you want to have your peer authenticate itself, you must “enable pap” in /etc/ppp/ppp.conf, and have an entry in /etc/ppp/ppp.secret for the peer (although see the passwdauth and setradius options below).

When using PAP as the client, you need only specify “AuthName” and “AuthKey” in /etc/ppp/ppp.conf. PAP is accepted by default.

pred1

Default: Enabled and Accepted. This option decides if Predictor 1 compression will be used by the Compression Control Protocol (CCP).

protocomp

Default: Enabled and Accepted. This option is used to negotiate PFC (Protocol Field Compression), a mechanism where the protocol field number is reduced to one octet rather than two.

shortseq

Default: Enabled and Accepted. This option determines if ppp will request and accept requests for short (12-bit) sequence numbers when negotiating multi-link mode. This is only applicable if our MRRU is set (thus enabling multi-link).

vjcomp

Default: Enabled and Accepted. This option determines if Van Jacobson header compression will be used.

The following options are not actually negotiated with the peer. Therefore, accepting or denying them makes no sense.

echo

Default: Disabled. When this option is enabled, ppp will send LCP ECHO requests to the peer at the frequency defined by “echoperiod”. Note: LQR requests will supersede LCP ECHO requests if enabled and negotiated. See “set lqrperiod” below for details.

Prior to ppp version 3.4.2, “echo” was considered enabled if lqr was enabled and negotiated, otherwise it was considered disabled. For the same behaviour, it is now necessary to “enable lqr echo” rather than just “enable lqr”.

filter-decapsulation

Default: Disabled. When this option is enabled, ppp will examine UDP frames to see if they actually contain a PPP frame as their payload. If this is the case, all filters will operate on the payload rather than the actual packet.

This is useful if you want to send PPPoUDP traffic over a PPP link, but want that link to do smart things with the real data rather than the UDP wrapper.

The UDP frame payload must not be compressed in any way, otherwise ppp will not be able to interpret it. It's therefore recommended that you disablevj pred1 deflate and denyvj pred1 deflate in the configuration for the ppp invocation with the udp link.

force-scripts

Default: Disabled. Forces execution of the configured chat scripts in direct and dedicated modes.

idcheck

Default: Enabled. When ppp exchanges low-level LCP, CCP, and IPCP configuration traffic, the Identifier field of any replies is expected to be the same as that of the request. By default, ppp drops any reply packets that do not contain the expected identifier field, reporting the fact at the respective log level. If idcheck is disabled, ppp will ignore the identifier field.

iface-alias

Default: Enabled if -nat is specified. This option simply tells ppp to add new interface addresses to the interface rather than replacing them. The option can only be enabled if network address translation is enabled (“nat enable yes”).

With this option enabled, ppp will pass traffic for old interface addresses through the NAT engine, resulting in the ability (in -auto mode) to properly connect the process that caused the PPP link to come up in the first place.

Disabling NAT with “nat enable no” will also disable “iface-alias”.

ipcp

Default: Enabled. This option allows ppp to attempt to negotiate IP control protocol capabilities and if successful to exchange IP datagrams with the peer.

ipv6cp

Default: Enabled. This option allows ppp to attempt to negotiate IPv6 control protocol capabilities and if successful to exchange IPv6 datagrams with the peer.

keep-session

Default: Disabled. When ppp runs as a Multi-link server, a different ppp instance initially receives each connection. After determining that the link belongs to an already existing bundle (controlled by another ppp invocation), ppp will transfer the link to that process.

If the link is a tty device or if this option is enabled, ppp will not exit, but will change its process name to “session owner” and wait for the controlling ppp to finish with the link and deliver a signal back to the idle process. This prevents the confusion that results from ppp parent considering the link resource available again.

For tty devices that have entries in /etc/ttys, this is necessary to prevent another getty(8) from being started, and for program links such as sshd(8), it prevents sshd(8) from exiting due to the death of its child. As ppp cannot determine its parents requirements (except for the tty case), this option must be enabled manually depending on the circumstances.

loopback

Default: Enabled. When loopback is enabled, ppp will automatically loop back packets being sent out with a destination address equal to that of the PPP interface. If disabled, ppp will send the packet, probably resulting in an ICMP redirect from the other end. It is convenient to have this option enabled when the interface is also the default route as it avoids the necessity of a loopback route.

NAS-IP-Address

Default: Enabled. This option controls whether ppp sends the “NAS-IP-Address” attribute to the RADIUS server when RADIUS is in use (see “set radius”).

Note: at least one of “NAS-IP-Address” and “NAS-Identifier” must be enabled.

Versions of ppp prior to version 3.4.1 did not send the “NAS-IP-Address” attribute as it was reported to break the Radiator RADIUS server. As the latest RFC (2865) no longer hints that only one of “NAS-IP-Address” and “NAS-Identifier” should be sent (as RFC 2138 did), ppp now sends both and leaves it up to the administrator that chooses to use bad RADIUS implementations to “disable NAS-IP-Address”.

NAS-Identifier

Default: Enabled. This option controls whether ppp sends the “NAS-Identifier” attribute to the RADIUS server when RADIUS is in use (see “set radius”).

Note: at least one of “NAS-IP-Address” and “NAS-Identifier” must be enabled.

passwdauth

Default: Disabled. Enabling this option will tell the PAP authentication code to use the password database (see passwd(5)) to authenticate the caller if they cannot be found in the /etc/ppp/ppp.secret file. /etc/ppp/ppp.secret is always checked first. If you wish to use passwords from passwd(5), but also to specify an IP number or label for a given client, use ‘\&*’ as the client password in /etc/ppp/ppp.secret.

proxy

Default: Disabled. Enabling this option will tell ppp to proxy ARP for the peer. This means that ppp will make an entry in the ARP table using HISADDR and the MAC address of the local network in which HISADDR appears. This allows other machines connected to the LAN to talk to the peer as if the peer itself was connected to the LAN. The proxy entry cannot be made unless HISADDR is an address from a LAN.

proxyall

Default: Disabled. Enabling this will tell ppp to add proxy arp entries for every IP address in all class C or smaller subnets routed via the tun interface.

Proxy arp entries are only made for sticky routes that are added using the add command. No proxy arp entries are made for the interface address itself (as created by the setifaddr command).

sroutes

Default: Enabled. When the add command is used with the HISADDR, MYADDR, HISADDR6, or MYADDR6 values, entries are stored in the “sticky route” list. Each time these variables change, this list is re-applied to the routing table.

Disabling this option will prevent the re-application of sticky routes, although the “sticky route” list will still be maintained.

[tcp ]

mssfixup Default: Enabled. This option tells ppp to adjust TCP SYN packets so that the maximum receive segment size is not greater than the amount allowed by the interface MTU.

throughput

Default: Enabled. This option tells ppp to gather throughput statistics. Input and output is sampled over a rolling 5 second window, and current, best, and total figures are retained. This data is output when the relevant PPP layer shuts down, and is also available using the show command. Throughput statistics are available at the “IPCP” and “physical” levels.

utmp

Default: Enabled. Normally, when a user is authenticated using PAP or CHAP, and when ppp is running in -direct mode, an entry is made in the utmp and wtmp files for that user. Disabling this option will tell ppp not to make any utmp or wtmp entries. This is usually only necessary if you require the user to both login and authenticate themselves.

add

[!\&] dest [mask] [gateway] Dest is the destination IP address. The netmask is specified either as a number of bits with / or as an IP number using mask. 00 or simply 0 with no mask refers to the default route. It is also possible to use the literal name “default” instead of 0. Gateway is the next hop gateway to get to the given dest machine/network. Refer to the route(8) command for further details.

It is possible to use the symbolic names “MYADDR”, “HISADDR”, “MYADDR6”, or “HISADDR6” as the destination, and “HISADDR” or “HISADDR6” as the gateway. “MYADDR” is replaced with the interface IP address, “HISADDR” is replaced with the interface IP destination (peer) address, “MYADDR6” is replaced with the interface IPv6 address, and “HISADDR6” is replaced with the interface IPv6 destination address.

If the add command is used (note the trailing ‘!\&)’, then if the route already exists, it will be updated as with the routechange command (see route(8) for further details).

Routes that contain the “HISADDR”, “MYADDR”, “HISADDR6”, “MYADDR6”, “DNS0”, or “DNS1” constants are considered “sticky”. They are stored in a list (use showncp to see the list), and each time the value of one of these variables changes, the appropriate routing table entries are updated. This facility may be disabled using disablesroutes.

allowcommand[args]

This command controls access to ppp and its configuration files. It is possible to allow user-level access, depending on the configuration file label and on the mode that ppp is being run in. For example, you may wish to configure ppp so that only user “fred” may access label “fredlabel” in -background mode.

User ID 0 is immune to these commands.

allowuser

[s] logname... By default, only user ID 0 is allowed access to ppp. If this command is used, all of the listed users are allowed access to the section in which the allowusers command is found. The “default” section is always checked first (even though it is only ever automatically loaded at startup). allowusers commands are cumulative in a given section, but users allowed in any given section override users allowed in the default section, so it's possible to allow users access to everything except a given label by specifying default users in the “default” section, and then specifying a new user list for that label.

If user ‘*’ is specified, access is allowed to all users. If logname is omitted, the user access list is emptied (i.e. only root will have access). There is no difference between the forms allowuser and allowusers.

allowmode

[s] mode... By default, access using any ppp mode is possible. If this command is used, it restricts the access modes allowed to load the label under which this command is specified. Again, as with the allowusers command, each allowmodes command overrides any previous settings, and the “default” section is always checked first.

Possible modes are: “interactive”, “auto”, “direct”, “dedicated”, “ddial”, “background”, and ‘*’. There is no difference between the forms allowmode and allowmodes.

When running in multi-link mode, a section can be loaded if it allows any of the currently existing line modes.

[!\& ]

bgcommand The given command is executed in the background with the following words replaced:

AUTHNAME

This is replaced with the local authname value. See the setauthname command below.

DNS0 & DNS1

These are replaced with the primary and secondary nameserver IP numbers. If nameservers are negotiated by IPCP, the values of these macros will change.

ENDDISC

This is replaced with the local endpoint discriminator value. See the setenddisc command below.

HISADDR

This is replaced with the peer's IP number.

HISADDR6

This is replaced with the peer's IPv6 number.

INTERFACE

This is replaced with the name of the interface that's in use.

IPOCTETSIN

This is replaced with the number of IP bytes received since the connection was established.

IPOCTETSOUT

This is replaced with the number of IP bytes sent since the connection was established.

IPPACKETSIN

This is replaced with the number of IP packets received since the connection was established.

IPPACKETSOUT

This is replaced with the number of IP packets sent since the connection was established.

IPV6OCTETSIN

This is replaced with the number of IPv6 bytes received since the connection was established.

IPV6OCTETSOUT

This is replaced with the number of IPv6 bytes sent since the connection was established.

IPV6PACKETSIN

This is replaced with the number of IPv6 packets received since the connection was established.

IPV6PACKETSOUT

This is replaced with the number of IPv6 packets sent since the connection was established.

LABEL

This is replaced with the last label name used. A label may be specified on the ppp command line, via the load or dial commands and in the ppp.secret file.

MYADDR

This is replaced with the IP number assigned to the local interface.

MYADDR6

This is replaced with the IPv6 number assigned to the local interface.

OCTETSIN

This is replaced with the number of bytes received since the connection was established.

OCTETSOUT

This is replaced with the number of bytes sent since the connection was established.

PACKETSIN

This is replaced with the number of packets received since the connection was established.

PACKETSOUT

This is replaced with the number of packets sent since the connection was established.

PEER_ENDDISC

This is replaced with the value of the peer's endpoint discriminator.

PROCESSID

This is replaced with the current process ID.

SOCKNAME

This is replaced with the name of the diagnostic socket.

UPTIME

This is replaced with the bundle uptime in HH:MM:SS format.

USER

This is replaced with the username that has been authenticated with PAP or CHAP. Normally, this variable is assigned only in -direct mode. This value is available irrespective of whether utmp logging is enabled.

VERSION

This is replaced with the current version number of ppp.

These substitutions are also done by the setproctitle, ident, and log commands.

If you wish to pause ppp while the command executes, use the shell command instead.

clear physical\&| ipcp\&| ipv6 .Oo Ic current No \&| overall\&| peak... Oc Clear the specified throughput values at either the “physical”, “ipcp”, or “ipv6cp” level. If “physical” is specified, context must be given (see the link command below). If no second argument is given, all values are cleared.

clonename

[\&, ] ... Clone the specified link, creating one or more new links according to the name argument(s). This command must be used from the “link” command below unless you've only got a single link (in which case that link becomes the default). Links may be removed using the remove command (see below).

The default link name is “deflink”.

close .Oo Ic lcp Ns Oo !\& Oc |\& ccp If no arguments are given, the relevant protocol layers will be brought down and the link will be closed. If “lcp” is specified, the LCP layer is brought down, but ppp will not bring the link offline. It is subsequently possible to use “term” (see below) to talk to the peer machine if, for example, something like “slirp” is being used. If “ccp” is specified, only the relevant compression layer is closed. If the ‘!\&’ is used, the compression layer will remain in the closed state, otherwise it will re-enter the STOPPED state, waiting for the peer to initiate further CCP negotiation. In any event, this command does not disconnect the user from ppp or exit ppp. See the quit command below.

delete

[!\&] dest This command deletes the route with the given dest IP address. If dest is specified as “ALL”, all non-direct entries in the routing table for the current interface, and all “sticky route” entries are deleted. If dest is specified as “default”, the default route is deleted.

If the delete command is used (note the trailing ‘!\&)’, ppp will not complain if the route does not already exist.

dial\&| call [label]... This command is the equivalent of “load label” followed by “open”, and is provided for backwards compatibility.

down[lcp| ccp]

Bring the relevant layer down ungracefully, as if the underlying layer had become unavailable. It's not considered polite to use this command on a Finite State Machine that's in the OPEN state. If no arguments are supplied, the entire link is closed (or if no context is given, all links are terminated). If “lcp” is specified, the LCP layer is terminated but the device is not brought offline and the link is not closed. If “ccp” is specified, only the relevant compression layer(s) are terminated.

help\&| ?\& [command] Show a list of available commands. If command is specified, show the usage string for that command.

ident[text]...

Identify the link to the peer using text. If text is empty, link identification is disabled. It is possible to use any of the words described for the bg command above. Refer to the sendident command for details of when ppp identifies itself to the peer.

ifacecommand[args]

This command is used to control the interface used by ppp. Command may be one of the following:

ifaceadd

[!\&] addr [peer]

ifaceadd

[!\&] addr mask peer Add the given addrmask peer combination to the interface. Instead of specifying mask, / can be used (with no space between it and addr)). If the given address already exists, the command fails unless the ‘!\&’ is used \- in which case the previous interface address entry is overwritten with the new one, allowing a change of netmask or peer address.

If only addr is specified, bits defaults to 32 and peer defaults to 255.255.255.255. This address (the broadcast address) is the only duplicate peer address that ppp allows.

ifaceclear [INET\&| INET6] If this command is used while ppp is in the OPENED state or while in -auto mode, all addresses except for the NCP negotiated address are deleted from the interface. If ppp is not in the OPENED state and is not in -auto mode, all interface addresses are deleted.

If the INET or INET6 arguments are used, only addresses for that address family are cleared.

iface delete rm addr This command deletes the given addr from the interface. If the ‘!\&’ is used, no error is given if the address isn't currently assigned to the interface (and no deletion takes place).

ifaceshow

Shows the current state and current addresses for the interface. It is much the same as running “ifconfig INTERFACE”.

ifacehelp [sub-command]

This command, when invoked without sub-command, will show a list of possible “iface” sub-commands and a brief synopsis for each. When invoked with sub-command, only the synopsis for the given sub-command is shown.

[data]

link name ... command[args] This command may prefix any other command if the user wishes to specify which link the command should affect. This is only applicable after multiple links have been created in Multi-link mode using the clone command.

Name specifies the name of an existing link. If name is a comma separated list, command is executed on each link. If name is ‘*’, command is executed on all links.

load[label]

... Load the given label from the ppp.conf file. If label is not given, the default label is used.

Unless the label section uses the setmode, open, or dial commands, ppp will not attempt to make an immediate connection.

logword...

Send the given word(s) to the log file with the prefix “LOG:”. Word substitutions are done as explained under the !\& command above.

natcommand[args]

This command allows the control of the network address translation (also known as masquerading or IP aliasing) facilities that are built into ppp. NAT is done on the external interface only, and is unlikely to make sense if used with the -direct flag.

If nat is enabled on your system (it may be omitted at compile time), the following commands are possible:

natenable yes| no

This command either switches network address translation on or turns it off. The -nat command line flag is synonymous with “nat enable yes”.

nataddr [addr_localaddr_alias]

This command allows data for addr_alias to be redirected to addr_local. It is useful if you own a small number of real IP numbers that you wish to map to specific machines behind your gateway.

natdeny_incoming yes| no

If set to yes, this command will refuse all incoming packets where an aliasing link doesn't already exist.

It should be noted under what circumstances an aliasing link is created. It may be necessary to further protect your network from outside connections using the setfilter or nattarget commands.

nathelp \&| ?\&

This command gives a summary of available nat commands.

natlog yes| no

This option causes various NAT statistics and information to be logged to the file /var/log/alias.log.

natport prototargetIP

: .Oo - .Oc Ar aliasPort Ns .Oo - .Oc Oo Ar remoteIP : Ns remotePort .Oo - .Oc Ns .Oc This command causes incoming proto connections to aliasPort to be redirected to targetPort on targetIP. proto is either “tcp” or “udp”.

A range of port numbers may be specified as shown above. The ranges must be of the same size.

If remoteIP is specified, only data coming from that IP number is redirected. remotePort must either be 0 (indicating any source port) or a range of ports the same size as the other ranges.

This option is useful if you wish to run things like an Internet phone on machines behind your gateway, but it is limited in that connections to only one interior machine per source machine and target port are possible.

natproto protolocalIP Oo

publicIP[remoteIP] .Oc This command tells ppp to redirect packets of protocol type proto (see protocols(5)) to the internal address localIP.

If publicIP is specified, only packets destined for that address are matched, otherwise the default alias address is used.

If remoteIP is specified, only packets matching that source address are matched.

This command is useful for redirecting tunnel endpoints to an internal machine, for example:

     nat proto ipencap 10.0.0.1

natproxy cmd arg...

This command tells ppp to proxy certain connections, redirecting them to a given server.

natpunch_fw [basecount]

This command tells ppp to punch holes in the firewall for FTP or IRC DCC connections. This is done dynamically by installing temporary firewall rules which allow a particular connection (and only that connection) to go through the firewall. The rules are removed once the corresponding connection terminates.

A maximum of count rules starting from rule number base will be used for punching firewall holes. The range will be cleared when the natpunch_fw command is run.

If no arguments are given, firewall punching is disabled.

natskinny_port [port]

This command tells ppp which TCP port is used by the Skinny Station protocol. Skinny is used by Cisco IP phones to communicate with Cisco Call Managers to set up voice over IP calls. The typical port used by Skinny is 2000.

If no argument is given, skinny aliasing is disabled.

natsame_ports yes| no

When enabled, this command tells the network address translation engine to attempt to avoid changing the port number on outgoing packets. This is useful if you want to support protocols such as RPC and LPD which require connections to come from a well known port.

nattarget [address]

Set the given target address or clear it if no address is given. The target address is used to specify how to NAT incoming packets by default. If a target address is not set or if “default” is given, packets are not altered and are allowed to route to the internal network.

The target address may be set to “MYADDR”, in which case all packets will be redirected to the interface address.

natuse_sockets yes| no

When enabled, this option tells the network address translation engine to create a socket so that it can guarantee a correct incoming FTP data or IRC connection.

natunregistered_only yes| no

Only alter outgoing packets with an unregistered source address. According to RFC 1918, unregistered source addresses are 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16.

These commands are also discussed in the file README.nat which comes with the source distribution.

open .Oo Ic lcp No \&| ccp\&| ipcpOc This is the opposite of the close command. All closed links are immediately brought up apart from second and subsequent demand-dial links \- these will come up based on the setautoload command that has been used.

If the “lcp” argument is used while the LCP layer is already open, LCP will be renegotiated. This allows various LCP options to be changed, after which “open lcp” can be used to put them into effect. After renegotiating LCP, any agreed authentication will also take place.

If the “ccp” argument is used, the relevant compression layer is opened. Again, if it is already open, it will be renegotiated.

If the “ipcp” argument is used, the link will be brought up as normal, but if IPCP is already open, it will be renegotiated and the network interface will be reconfigured.

It is probably not good practice to re-open the PPP state machines like this as it's possible that the peer will not behave correctly. It is however useful as a way of forcing the CCP or VJ dictionaries to be reset.

passwdpass

Specify the password required for access to the full ppp command set. This password is required when connecting to the diagnostic port (see the setserver command). Pass is specified on the setserver command line. The value of pass is not logged when command logging is active, instead, the literal string “********” is logged.

quit\&| bye [all] If quit is executed from the controlling connection or from a command file, ppp will exit after closing all connections. Otherwise, if the user is connected to a diagnostic socket, the connection is simply dropped.

If the all keyword is given, ppp will exit despite the source of the command after closing all existing connections.

remove\&| rm

This command removes the given link. It is only really useful in multi-link mode. A link must be in the CLOSED state before it is removed.

rename\&| mvname

This command renames the given link to name. It will fail if name is already used by another link.

The default link name is “deflink”. Renaming it to “modem”, “cua00”, or “USR” may make the log file more readable.

resolvcommand

This command controls ppp manipulation of the resolv.conf(5) file. When ppp starts up, it loads the contents of this file into memory and retains this image for future use. command is one of the following:

readonly

Treat /etc/resolv.conf as read only. If “dns” is enabled, ppp will still attempt to negotiate nameservers with the peer, making the results available via the DNS0 and DNS1 macros. This is the opposite of the resolvwritable command.

reload

Reload /etc/resolv.conf into memory. This may be necessary if, for example, a DHCP client overwrote /etc/resolv.conf.

restore

Replace /etc/resolv.conf with the version originally read at startup or with the last resolvreload command. This is sometimes a useful command to put in the /etc/ppp/ppp.linkdown file.

rewrite

Rewrite the /etc/resolv.conf file. This command will work even if the resolvreadonly command has been used. It may be useful as a command in the /etc/ppp/ppp.linkup file if you wish to defer updating /etc/resolv.conf until after other commands have finished.

writable

Allow ppp to update /etc/resolv.conf if “dns” is enabled and ppp successfully negotiates a DNS. This is the opposite of the resolvreadonly command.

sendident

This command tells ppp to identify itself to the peer. The link must be in LCP state or higher. If no identity has been set (via the ident command), sendident will fail.

When an identity has been set, ppp will automatically identify itself when it sends or receives a configure reject, when negotiation fails, or when LCP reaches the opened state.

Received identification packets are logged to the LCP log (see setlog for details) and are never responded to.

set

[up] varvalue This option allows the setting of any of the following variables:

setaccmap hex-value

ACCMap stands for Asynchronous Control Character Map. This is always negotiated with the peer, and defaults to a value of 00000000 in hex. This protocol is required to defeat hardware that depends on passing certain characters from end to end (such as XON/XOFF etc).

For the XON/XOFF scenario, use “set accmap 000a0000”.

set[auth]

keyvalue This sets the authentication key (or password) used in client mode PAP or CHAP negotiation to the given value. It also specifies the password to be used in the dial or login scripts in place of the ‘\eP’ sequence, preventing the actual password from being logged. If command or chat logging is in effect, value is logged as “********” for security reasons.

If the first character of value is an exclamation mark (‘!\&’), ppp treats the remainder of the string as a program that must be executed to determine the “authname” and “authkey” values.

If the ‘!\&’ is doubled up (to ‘!!)’, it is treated as a single literal ‘!\&’, otherwise, ignoring the ‘!\&’, value is parsed as a program to execute in the same was as the !\& command above, substituting special names in the same manner. Once executed, ppp will feed the program three lines of input, each terminated by a newline character:

• The host name as sent in the CHAP challenge.
• The challenge string as sent in the CHAP challenge.
• The locally defined “authname”.

Two lines of output are expected:

• The “authname” to be sent with the CHAP response.
• The “authkey”, which is encrypted with the challenge and request ID, the answer being sent in the CHAP response packet.

When configuring ppp in this manner, it's expected that the host challenge is a series of ASCII digits or characters. An encryption device or Secure ID card is usually required to calculate the secret appropriate for the given challenge.

setauthname ID

This sets the authentication ID used in client mode PAP or CHAP negotiation.

If used in -direct mode with CHAP enabled, ID is used in the initial authentication challenge and should normally be set to the local machine name.

setautoload

min-percentmax-percent period These settings apply only in multi-link mode and default to zero, zero, and five, respectively. When more than one demand-dial (also known as -auto) mode link is available, only the first link is made active when ppp first reads data from the tun device. The next demand-dial link will be opened only when the current bundle throughput is at least max-percent percent of the total bundle bandwidth for period seconds. When the current bundle throughput decreases to min-percent percent or less of the total bundle bandwidth for period seconds, a demand-dial link will be brought down as long as it's not the last active link.

Bundle throughput is measured as the maximum of inbound and outbound traffic.

The default values cause demand-dial links to simply come up one at a time.

Certain devices cannot determine their physical bandwidth, so it is sometimes necessary to use the setbandwidth command (described below) to make setautoload work correctly.

setbandwidth value

This command sets the connection bandwidth in bits per second. value must be greater than zero. It is currently only used by the setautoload command above.

setcallback option...

If no arguments are given, callback is disabled, otherwise, ppp will request (or in -direct mode, will accept) one of the given options. In client mode, if an option is NAK'd ppp will request a different option, until no options remain; at which point ppp will terminate negotiations (unless “none” is one of the specified options). In server mode, ppp will accept any of the given protocols \- but the client must request one of them. If you wish callback to be optional, you must include none as an option.

The options are as follows (in this order of preference):

auth

The callee is expected to decide the callback number based on authentication. If ppp is the callee, the number should be specified as the fifth field of the peer's entry in /etc/ppp/ppp.secret.

cbcp

Microsoft's callback control protocol is used. See setcbcp below.

If you wish to negotiate cbcp in client mode but also wish to allow the server to request no callback at CBCP negotiation time, you must specify both cbcp and none as callback options.

E.164 *|

number ... The caller specifies the number. If ppp is the callee, number should be either a comma separated list of allowable numbers or a ‘\&*’, meaning any number is permitted. If ppp is the caller, only a single number should be specified.

Note: this option is very unsafe when used with a ‘\&*’ as a malicious caller can tell ppp to call any (possibly international) number without first authenticating themselves.

none

If the peer does not wish to do callback at all, ppp will accept the fact and continue without callback rather than terminating the connection. This is required (in addition to one or more other callback options) if you wish callback to be optional.

setcbcp Oo

*| , [delay[retry]] .Oc If no arguments are given, CBCP (Microsoft's CallBack Control Protocol) is disabled \- i.e., configuring CBCP in the “set callback” command will result in ppp requesting no callback in the CBCP phase. Otherwise, ppp attempts to use the given phone number(s).

In server mode (-direct), ppp will insist that the client uses one of these numbers, unless ‘\&*’ is used in which case the client is expected to specify the number.

In client mode, ppp will attempt to use one of the given numbers (whichever it finds to be agreeable with the peer), or if ‘\&*’ is specified, ppp will expect the peer to specify the number.

setcd Oo

off| .Oc Normally, ppp checks for the existence of carrier depending on the type of device that has been opened:

Terminal Devices

Carrier is checked one second after the login script is complete. If it's not set, ppp assumes that this is because the device doesn't support carrier (which is true for most “laplink” NULL-modem cables), logs the fact, and stops checking for carrier.

As ptys don't support the TIOCMGET ioctl, the tty device will switch all carrier detection off when it detects that the device is a pty.

ISDN (i4b) Devices

Carrier is checked once per second for 6 seconds. If it's not set after the sixth second, the connection attempt is considered to have failed and the device is closed. Carrier is always required for i4b devices.

PPPoE (netgraph) Devices

Carrier is checked once per second for 5 seconds. If it's not set after the fifth second, the connection attempt is considered to have failed and the device is closed. Carrier is always required for PPPoE devices.

All other device types don't support carrier. Setting a carrier value will result in a warning when the device is opened.

Some modems take more than one second after connecting to assert the carrier signal. If this delay isn't increased, this will result in ppp inability to detect when the link is dropped, as ppp assumes that the device isn't asserting carrier.

The setcd command overrides the default carrier behaviour. seconds specifies the maximum number of seconds that ppp should wait after the dial script has finished before deciding if carrier is available or not.

If “off” is specified, ppp will not check for carrier on the device, otherwise ppp will not proceed to the login script until either carrier is detected or until seconds has elapsed, at which point ppp assumes that the device will not set carrier.

If no arguments are given, carrier settings will go back to their default values.

If seconds is followed immediately by an exclamation mark (‘!\&’), ppp will require carrier. If carrier is not detected after seconds seconds, the link will be disconnected.

setchoked [timeout]

This sets the number of seconds that ppp will keep a choked output queue before dropping all pending output packets. If timeout is less than or equal to zero or if timeout isn't specified, it is set to the default value of 120 seconds.

A choked output queue occurs when ppp has read a certain number of packets from the local network for transmission, but cannot send the data due to link failure (the peer is busy etc.). ppp will not read packets indefinitely. Instead, it reads up to 30 packets (or 30 + nlinks * 2 packets in multi-link mode), then stops reading the network interface until either timeout seconds have passed or at least one packet has been sent.

If timeout seconds pass, all pending output packets are dropped.

setctsrts on This sets hardware flow control. Hardware flow control is on by default.

setdeflate out-winsize[in-winsize]

This sets the DEFLATE algorithm's default outgoing and incoming window sizes. Both out-winsize and in-winsize must be values between 8 and 15. If in-winsize is specified, ppp will insist that this window size is used and will not accept any other values from the peer.

setdevice \&| line

value... This sets the device(s) to which ppp will talk to the given value.

All serial device names are expected to begin with /dev/. Serial devices are usually called cuaXX.

If value does not begin with /dev/, it must either begin with an exclamation mark (‘!\&’) or be of the format .Sm off host: port [/tcp|udp]. .Sm on

If it begins with an exclamation mark, the rest of the device name is treated as a program name, and that program is executed when the device is opened. Standard input, output, and error are fed back to ppp and are read and written as if they were a regular device.

If a host: /tcp|udp .Oc specification is given, ppp will attempt to connect to the given host on the given port. If a “/tcp” or “/udp” suffix is not provided, the default is “/tcp”. Refer to the section on PPP OVER TCP and UDP above for further details.

If multiple values are specified, ppp will attempt to open each one in turn until it succeeds or runs out of devices.

setdial chat-script

This specifies the chat script that will be used to dial the other side. See also the setlogin command below. Refer to chat(8) and to the example configuration files for details of the chat script format. It is possible to specify some special “values” in your chat script as follows:

\ec

When used as the last character in a “send” string, this indicates that a newline should not be appended.

\ed

When the chat script encounters this sequence, it delays two seconds.

\en

This is replaced with a newline character.

\ep

When the chat script encounters this sequence, it delays for one quarter of a second.

\er

This is replaced with a carriage return character.

\es

This is replaced with a space character.

\et

This is replaced with a tab character.

\eT

This is replaced by the current phone number (see setphone below).

\eP

This is replaced by the current authkey value (see setauthkey above).

\eU

This is replaced by the current authname value (see setauthname above).

Note that two parsers will examine these escape sequences, so in order to have the “chat parser” see the escape character, it is necessary to escape it from the “command parser”. This means that in practice you should use two escapes, for example:

set dial "... ATDT\\\\T CONNECT"

It is also possible to execute external commands from the chat script. To do this, the first character of the expect or send string is an exclamation mark (‘!\&’). If a literal exclamation mark is required, double it up to ‘!!\&’ and it will be treated as a single literal ‘!\&’. When the command is executed, standard input and standard output are directed to the open device (see the setdevice command), and standard error is read by ppp and substituted as the expect or send string. If ppp is running in interactive mode, file descriptor 3 is attached to /dev/tty.

For example (wrapped for readability):

set login "TIMEOUT 5 \\"\\" \\"\\" login:--login: ppp \e
word: ppp \\"!sh \\\\-c \\\\\\"echo \\\\-n label: >&2\\\\\\"\\" \e
\\"!/bin/echo in\\" HELLO"

would result in the following chat sequence (output using the “set log local chat” command before dialing):

Dial attempt 1 of 1
dial OK!
Chat: Expecting:
Chat: Sending:
Chat: Expecting: login:--login:
Chat: Wait for (5): login:
Chat: Sending: ppp
Chat: Expecting: word:
Chat: Wait for (5): word:
Chat: Sending: ppp
Chat: Expecting: !sh \\-c "echo \\-n label: >&2"
Chat: Exec: sh -c "echo -n label: >&2"
Chat: Wait for (5): !sh \\-c "echo \\-n label: >&2" --> label:
Chat: Exec: /bin/echo in
Chat: Sending:
Chat: Expecting: HELLO
Chat: Wait for (5): HELLO
login OK!

Note (again) the use of the escape character, allowing many levels of nesting. Here there are four parsers at work. The first parses the original line, reading it as three arguments. The second parses the third argument, reading it as 11 arguments. At this point, it is important that the ‘\&-’ signs are escaped, otherwise this parser will see them as constituting an expect-send-expect sequence. When the ‘!\&’ character is seen, the execution parser reads the first command as three arguments, and then sh(1) itself expands the argument after the -c. As we wish to send the output back to the modem, in the first example we redirect our output to file descriptor 2 (stderr) so that ppp itself sends and logs it, and in the second example we just output to stdout, which is attached directly to the modem.

This, of course means that it is possible to execute an entirely external “chat” command rather than using the internal one. See chat(8) for a good alternative.

The external command that is executed is subjected to the same special word expansions as the !\& command.

setdns [primary[secondary]] This command specifies DNS overrides for the acceptdns command. Refer to the accept command description above for details. This command does not affect the IP numbers requested using enabledns.

setenddisc [label|IP|MAC|magic|psn value]

This command sets our local endpoint discriminator. If set prior to LCP negotiation, and if no disableenddisc command has been used, ppp will send the information to the peer using the LCP endpoint discriminator option. The following discriminators may be set:

label

The current label is used.

IP

Our local IP number is used. As LCP is negotiated prior to IPCP, it is possible that the IPCP layer will subsequently change this value. If it does, the endpoint discriminator stays at the old value unless manually reset.

MAC

This is similar to the IP option above, except that the MAC address associated with the local IP number is used. If the local IP number is not resident on any Ethernet interface, the command will fail.

As the local IP number defaults to whatever the machine host name is, “set enddisc mac” is usually done prior to any “set ifaddr” commands.

magic

A 20-digit random number is used. Care should be taken when using magic numbers as restarting ppp or creating a link using a different ppp invocation will also use a different magic number and will therefore not be recognised by the peer as belonging to the same bundle. This makes it unsuitable for -direct connections.

psn value

The given value is used. Value should be set to an absolute public switched network number with the country code first.

If no arguments are given, the endpoint discriminator is reset.

setescape value...

This option is similar to the setaccmap option above. It allows the user to specify a set of characters that will be “escaped” as they travel across the link.

setfilter dial|alive|in|out rule-no

permit|deny|clear| [!\&] .Oo Op host src_addr [dst_addr] .Oc [ Ns Ar proto [src lt|eq|gt port] [dst lt|eq|gt port] [estab] [syn] [finrst] [timeout secs]] ppp supports four filter sets. The alive filter specifies packets that keep the connection alive \- resetting the idle timer. The dial filter specifies packets that cause ppp to dial when in -auto mode. The in filter specifies packets that are allowed to travel into the machine and the out filter specifies packets that are allowed out of the machine.

Filtering is done prior to any IP alterations that might be done by the NAT engine on outgoing packets and after any IP alterations that might be done by the NAT engine on incoming packets. By default all empty filter sets allow all packets to pass. Rules are processed in order according to rule-no (unless skipped by specifying a rule number as the action)). Up to 40 rules may be given for each set. If a packet doesn't match any of the rules in a given set, it is discarded. In the case of in and out filters, this means that the packet is dropped. In the case of alive filters it means that the packet will not reset the idle timer (even if the in filter has a “timeout” value) and in the case of dial filters it means that the packet will not trigger a dial. A packet failing to trigger a dial will be dropped rather than queued. Refer to the section on above for further details.

sethangup chat-script

This specifies the chat script that will be used to reset the device before it is closed. It should not normally be necessary, but can be used for devices that fail to reset themselves properly on close.

sethelp \&| ?\& [command] This command gives a summary of available set commands, or if command is specified, the command usage is shown.

setifaddr Oo myaddr

[/ ] .Oo Ar hisaddr Ns Op / Ns Ar \&nn .Oo Ar netmask [triggeraddr] .Oc Oc .Oc This command specifies the IP addresses that will be used during IPCP negotiation. Addresses are specified using the following format:

     a.b.c.d/nn

\&...where “a.b.c.d” is the preferred IP, but nn specifies how many bits of the address we will insist on. If / is omitted, it defaults to ‘/32’ unless the IP address is 0.0.0.0 in which case it defaults to ‘/0’.

If you wish to assign a dynamic IP number to the peer, hisaddr may also be specified as a range of IP numbers in the following format: \&IP .Oc Ns Oo , Ns Ar \&IP Ns [\&- ] .Oc Ns ...

For example:

     set ifaddr 10.0.0.1 10.0.1.2-10.0.1.10,10.0.1.20

\&...will only negotiate “10.0.0.1” as the local IP number, but may assign any of the given 10 IP numbers to the peer. If the peer requests one of these numbers, and that number is not already in use, ppp will grant the peer's request. This is useful if the peer wants to re-establish a link using the same IP number as was previously allocated (thus maintaining any existing TCP or UDP connections).

If the peer requests an IP number that's either outside of this range or is already in use, ppp will suggest a random unused IP number from the range.

If triggeraddr is specified, it is used in place of myaddr in the initial IPCP negotiation. However, only an address in the myaddr range will be accepted. This is useful when negotiating with some PPP implementations that will not assign an IP number unless their peer requests “0.0.0.0”.

It should be noted that in -auto mode, ppp will configure the interface immediately upon reading the “set ifaddr” line in the config file. In any other mode, these values are just used for IPCP negotiations, and the interface isn't configured until the IPCP layer is up.

Note that the HISADDR argument may be overridden by the third field in the ppp.secret file once the client has authenticated itself (if PAP or CHAP are “enabled)”. Refer to the section for details.

In all cases, if the interface is already configured, ppp will try to maintain the interface IP numbers so that any existing bound sockets will remain valid.

setifqueue packets

Set the maximum number of packets that ppp will read from the tunnel interface while data cannot be sent to any of the available links. This queue limit is necessary to flow control outgoing data as the tunnel interface is likely to be far faster than the combined links available to ppp.

If packets is set to a value less than the number of links, ppp will read up to that value regardless. This prevents any possible latency problems.

The default value for packets is 30.

setccpretry \&| ccpretriesOo timeout [reqtries[trmtriesOc]]

setchapretry \&| chapretriesOo timeout [reqtriesOc]

setipcpretry \&| ipcpretriesOo timeout [reqtries[trmtriesOc]]

setipv6cpretry \&| ipv6cpretriesOo timeout [reqtries[trmtriesOc]]

setlcpretry \&| lcpretriesOo timeout [reqtries[trmtriesOc]]

setpapretry \&| papretriesOo timeout [reqtriesOc] These commands set the number of seconds that ppp will wait before resending Finite State Machine (FSM) Request packets. The default timeout for all FSMs is 3 seconds (which should suffice in most cases).

If reqtries is specified, it tells ppp how many configuration request attempts it should make while receiving no reply from the peer before giving up. The default is 5 attempts for CCP, LCP, and IPCP, and 3 attempts for PAP and CHAP.

If trmtries is specified, it tells ppp how many terminate requests should be sent before giving up waiting for the peer's response. The default is 3 attempts. Authentication protocols are not terminated and it is therefore invalid to specify trmtries for PAP or CHAP.

In order to avoid negotiations with the peer that will never converge, ppp will only send at most 3 times the configured number of reqtries in any given negotiation session before giving up and closing that layer.

setlog

[local] [+|- ] value... This command allows the adjustment of the current log level. Refer to the section above for further details.

setlogin chat-script

This chat-script compliments the dial-script. If both are specified, the login script will be executed after the dial script. Escape sequences available in the dial script are also available here.

setlogout chat-script

This specifies the chat script that will be used to log out before the hangup script is called. It should not normally be necessary.

setlqrperiod|echoperiod frequency

This command sets the frequency in seconds at which LQR or LCP ECHO packets are sent. The default is 30 seconds. You must also use the enablelqr and/or “enable echo” commands if you wish to send LQR or LCP ECHO requests to the peer.

setmode interactive| auto | ddial | background This command allows you to change the “mode” of the specified link. This is normally only useful in multi-link mode, but may also be used in uni-link mode.

It is not possible to change a link that is “direct” or “dedicated”.

Note: If you issue the command “set mode auto”, and have network address translation enabled, it may be useful to “enable iface-alias” afterwards. This will allow ppp to do the necessary address translations to enable the process that triggers the connection to connect once the link is up despite the peer assigning us a new (dynamic) IP address.

setmppe [40|56|128|* [stateless|stateful|*]]

This option selects the encryption parameters used when negotiating MPPE. MPPE can be disabled entirely with the disablemppe command. If no arguments are given, ppp will attempt to negotiate a stateful link with a 128-bit key, but will agree to whatever the peer requests (including no encryption at all).

If any arguments are given, ppp will insist on using MPPE and will close the link if it's rejected by the peer. (Note: this behaviour can be overridden by a configured RADIUS server.)

The first argument specifies the number of bits that ppp should insist on during negotiations and the second specifies whether ppp should insist on stateful or stateless mode. In stateless mode, the encryption dictionary is re-initialised with every packet according to an encryption key that is changed with every packet. In stateful mode, the encryption dictionary is re-initialised every 256 packets or after the loss of any data and the key is changed every 256 packets. Stateless mode is less efficient but is better for unreliable transport layers.

setmrru [value]

Setting this option enables Multi-link PPP negotiations, also known as Multi-link Protocol or MP. There is no default MRRU (Maximum Reconstructed Receive Unit) value. If no argument is given, multi-link mode is disabled.

setmru

[max] [value] The default MRU (Maximum Receive Unit) is 1500. If it is increased, the other side *may* increase its MTU. In theory there is no point in decreasing the MRU to below the default as the PPP protocol says implementations *must* be able to accept packets of at least 1500 octets.

If the maximum keyword is used, ppp will refuse to negotiate a higher value. The maximum MRU can be set to 2048 at most. Setting a maximum of less than 1500 violates the PPP RFC, but may sometimes be necessary. For example, PPPoE imposes a maximum of 1492 due to hardware limitations.

If no argument is given, 1500 is assumed. A value must be given when maximum is specified.

setmtu

[max] [value] The default MTU is 1500. At negotiation time, ppp will accept whatever MRU the peer requests (assuming it's not less than 296 bytes or greater than the assigned maximum). If the MTU is set, ppp will not accept MRU values less than value. When negotiations are complete, the MTU is used when writing to the interface, even if the peer requested a higher value MRU. This can be useful for limiting your packet size (giving better bandwidth sharing at the expense of more header data).

If the maximum keyword is used, ppp will refuse to negotiate a higher value. The maximum MTU can be set to 2048 at most.

If no value is given, 1500, or whatever the peer asks for, is used. A value must be given when maximum is specified.

setnbns [x.x.x.x[y.y.y.y]] This option allows the setting of the Microsoft NetBIOS name server values to be returned at the peer's request. If no values are given, ppp will reject any such requests.

setopenmode active|passive [delay] By default, openmode is always active with a one second delay. That is, ppp will always initiate LCP/IPCP/CCP negotiation one second after the line comes up. If you want to wait for the peer to initiate negotiations, you can use the value passive. If you want to initiate negotiations immediately or after more than one second, the appropriate delay may be specified here in seconds.

setparity odd|even|none|mark

This allows the line parity to be set. The default value is none.

setphone telno

.Oo \&| Ns Ar backupnumber .Oc Ns ... Ns Oo : Ns Ar nextnumber .Oc Ns ... This allows the specification of the phone number to be used in place of the \\\\T string in the dial and login chat scripts. Multiple phone numbers may be given separated either by a pipe (‘\&|’) or a colon (‘\&:’).

Numbers after the pipe are only dialed if the dial or login script for the previous number failed.

Numbers after the colon are tried sequentially, irrespective of the reason the line was dropped.

If multiple numbers are given, ppp will dial them according to these rules until a connection is made, retrying the maximum number of times specified by setredial below. In -background mode, each number is attempted at most once.

set[proc]

title[value] The current process title as displayed by ps(1) is changed according to value. If value is not specified, the original process title is restored. All the word replacements done by the shell commands (see the bg command above) are done here too.

Note: if USER is required in the process title, the setproctitle command must appear in ppp.linkup, as it is not known when the commands in ppp.conf are executed.

setradius [config-file]

This command enables RADIUS support (if it's compiled in). config-file refers to the radius client configuration file. If PAP, CHAP, MSCHAP, or MSCHAPv2 are enabled, ppp behaves as a \&N \&A \&S and uses the configured RADIUS server to authenticate rather than authenticating from the ppp.secret file or from the passwd database.

If none of PAP, CHAP, MSCHAP, or MSCHAPv2 are enabled, setradius will do nothing.

ppp uses the following attributes from the RADIUS reply:

RAD_FRAMED_IP_ADDRESS

The peer IP address is set to the given value.

RAD_FRAMED_IP_NETMASK

The tun interface netmask is set to the given value.

RAD_FRAMED_MTU

If the given MTU is less than the peer's MRU as agreed during LCP negotiation, and it is less that any configured MTU (see the setmru command), the tun interface MTU is set to the given value.

RAD_FRAMED_COMPRESSION

If the received compression type is ֫’, ppp will request VJ compression during IPCP negotiations despite any “disable vj” configuration command.

RAD_FILTER_ID

If this attribute is supplied, ppp will attempt to use it as an additional label to load from the ppp.linkup and ppp.linkdown files. The load will be attempted before (and in addition to) the normal label search. If the label doesn't exist, no action is taken and ppp proceeds to the normal load using the current label.

RAD_FRAMED_ROUTE

The received string is expected to be in the format dest gw [metrics]. Any specified metrics are ignored. MYADDR and HISADDR are understood as valid values for dest and gw, “default” can be used for dest to sepcify the default route, and “0.0.0.0” is understood to be the same as “default” for dest and HISADDR for gw.

For example, a returned value of “1.2.3.4/24 0.0.0.0 1 2 -1 3 400” would result in a routing table entry to the 1.2.3.0/24 network via HISADDR and a returned value of “0.0.0.0 0.0.0.0” or “default HISADDR” would result in a default route to HISADDR.

All RADIUS routes are applied after any sticky routes are applied, making RADIUS routes override configured routes. This also applies for RADIUS routes that don't include the MYADDR or HISADDR keywords.

RAD_FRAMED_IPV6_PREFIX

If this attribute is supplied, the value is substituted for IPV6PREFIX in a command. You may pass it to an upper layer protocol, such as DHCPv6, for delegating an IPv6 prefix to a peer.

RAD_FRAMED_IPV6_ROUTE

The received string is expected to be in the format dest gw [metrics]. Any specified metrics are ignored. MYADDR6 and HISADDR6 are understood as valid values for dest and gw; “default” can be used for dest to specify the default route; and “”:: is understood to be the same as “default” for dest and HISADDR6 for gw.

For example, a returned value of “2001:db8:abcd::/48”:: would result in a routing table entry to the 2001:db8:abcd::/48 network via HISADDR6 and a returned value of “::::”:: or “default HISADDR6” would result in a default route to HISADDR6.

All RADIUS IPv6 routes are applied after any sticky routes are applied, making RADIUS IPv6 routes override configured routes. This also applies for RADIUS IPv6 routes that don't include the MYADDR6 or HISADDR6 keywords.

RAD_SESSION_TIMEOUT

If supplied, the client connection is closed after the given number of seconds.

RAD_REPLY_MESSAGE

If supplied, this message is passed back to the peer as the authentication SUCCESS text.

RAD_MICROSOFT_MS_CHAP_ERROR

If this RAD_VENDOR_MICROSOFT vendor specific attribute is supplied, it is passed back to the peer as the authentication FAILURE text.

RAD_MICROSOFT_MS_CHAP2_SUCCESS

If this RAD_VENDOR_MICROSOFT vendor specific attribute is supplied and if MS-CHAPv2 authentication is being used, it is passed back to the peer as the authentication SUCCESS text.

RAD_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY

If this RAD_VENDOR_MICROSOFT vendor specific attribute is supplied and has a value of 2 (Required), ppp will insist that MPPE encryption is used (even if no “set mppe” configuration command has been given with arguments). If it is supplied with a value of 1 (Allowed), encryption is made optional (despite any setmppe configuration commands with arguments).

RAD_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES

If this RAD_VENDOR_MICROSOFT vendor specific attribute is supplied, bits 1 and 2 are examined. If either or both are set, 40-bit and/or 128-bit (respectively) encryption options are set, overriding any given first argument to the setmppe command. Note: it is not currently possible for the RADIUS server to specify 56-bit encryption.

RAD_MICROSOFT_MS_MPPE_RECV_KEY

If this RAD_VENDOR_MICROSOFT vendor specific attribute is supplied, its value is used as the master key for decryption of incoming data. When clients are authenticated using MSCHAPv2, the RADIUS server MUST provide this attribute if inbound MPPE is to function.

RAD_MICROSOFT_MS_MPPE_SEND_KEY

If this RAD_VENDOR_MICROSOFT vendor specific attribute is supplied, its value is used as the master key for encryption of outgoing data. When clients are authenticated using MSCHAPv2, the RADIUS server MUST provide this attribute if outbound MPPE is to function.

Values received from the RADIUS server may be viewed using showbundle.

setrad_alive timeout

When RADIUS is configured, setting “rad_alive” to a non-zero timeout value will tell ppp to sent RADIUS accounting information to the RADIUS server every timeout seconds.

setreconnect timeoutntries

Should the line drop unexpectedly (due to loss of CD or LQR failure), a connection will be re-established after the given timeout. The line will be re-connected at most ntries times. Ntries defaults to zero. A value of random for timeout will result in a variable pause, somewhere between 1 and 30 seconds.

setrecvpipe [value]

This sets the routing table RECVPIPE value. The optimum value is just over twice the MTU value. If value is unspecified or zero, the default kernel controlled value is used.

setredial secs

.Oo + Ns Ar inc Ns [- ] .Oc Ns Op . Ns Ar next [attempts] ppp can be instructed to attempt to redial attempts times. If more than one phone number is specified (see setphone above), a pause of next is taken before dialing each number. A pause of secs is taken before starting at the first number again. A literal value of “random” may be used here in place of secs and next, causing a random delay of between 1 and 30 seconds.

If inc is specified, its value is added onto secs each time ppp tries a new number. secs will only be incremented at most max times. max defaults to 10.

Note: the secs delay will be effective, even after attempts has been exceeded, so an immediate manual dial may appear to have done nothing. If an immediate dial is required, a ‘!\&’ should immediately follow the open keyword. See the open description above for further details.

setsendpipe [value]

This sets the routing table SENDPIPE value. The optimum value is just over twice the MTU value. If value is unspecified or zero, the default kernel controlled value is used.

setserver TcpPort [password [mask]] This command tells ppp to listen on the given socket or ‘diagnostic port’ for incoming command connections.

The word “none” instructs ppp to close any existing socket and clear the socket configuration. The word “open” instructs ppp to attempt to re-open the port. The word “closed” instructs ppp to close the open port.

If you wish to specify a local domain socket, LocalName must be specified as an absolute file name, otherwise it is assumed to be the name or number of a TCP port. You may specify the octal umask to be used with a local domain socket. Refer to umask(2) for umask details. Refer to services(5) for details of how to translate TCP port names.

You must also specify the password that must be entered by the client (using the “passwd” variable above) when connecting to this socket. If the password is specified as an empty string, no password is required for connecting clients.

When specifying a local domain socket, the first ‘%d’ sequence found in the socket name will be replaced with the current interface unit number. This is useful when you wish to use the same profile for more than one connection.

In a similar manner TCP sockets may be prefixed with the ‘+’ character, in which case the current interface unit number is added to the port number.

When using ppp with a server socket, the pppctl(8) command is the preferred mechanism of communication. Currently, telnet(1) can also be used, but link encryption may be implemented in the future, so telnet(1) should be avoided.

Note: SIGUSR1 and SIGUSR2 interact with the diagnostic socket.

setspeed value

This sets the speed of the serial device. If speed is specified as “sync”, ppp treats the device as a synchronous device.

Certain device types will know whether they should be specified as synchronous or asynchronous. These devices will override incorrect settings and log a warning to this effect.

setstopped [LCPseconds[CCPseconds]] If this option is set, ppp will time out after the given FSM (Finite State Machine) has been in the stopped state for the given number of “seconds”. This option may be useful if the peer sends a terminate request, but never actually closes the connection despite our sending a terminate acknowledgement. This is also useful if you wish to “set openmode passive” and time out if the peer doesn't send a Configure Request within the given time. Use “set log +lcp +ccp” to make ppp log the appropriate state transitions.

The default value is zero, where ppp doesn't time out in the stopped state.

This value should not be set to less than the openmode delay (see setopenmode above).

settimeout idleseconds[mintimeout]

This command allows the setting of the idle timer. Refer to the section titled for further details.

If mintimeout is specified, ppp will never idle out before the link has been up for at least that number of seconds.

seturgent

[tcp|udp|none] .Oo Op +|- Ns port .Oc No ... This command controls the ports that ppp prioritizes when transmitting data. The default priority TCP ports are ports 21 (ftp control), 22 (ssh), 23 (telnet), 513 (login), 514 (shell), 543 (klogin) and 544 (kshell). There are no priority UDP ports by default. See services(5) for details.

If neither “tcp” or “udp” are specified, “tcp” is assumed.

If no ports are given, the priority port lists are cleared (although if “tcp” or “udp” is specified, only that list is cleared). If the first port argument is prefixed with a plus (‘\&+’) or a minus (‘\&-’), the current list is adjusted, otherwise the list is reassigned. ports prefixed with a plus or not prefixed at all are added to the list and ports prefixed with a minus are removed from the list.

If “none” is specified, all priority port lists are disabled and even IPTOS_LOWDELAY packets are not prioritised.

setvj slotcomp on|off

This command tells ppp whether it should attempt to negotiate VJ slot compression. By default, slot compression is turned on.

setvj slots nslots

This command sets the initial number of slots that ppp will try to negotiate with the peer when VJ compression is enabled (see the enable command above). It defaults to a value of 16. Nslots must be between 4 and 16 inclusive.

shell\&| !\& [command] If command is not specified, a shell is invoked according to the SHELL environment variable. Otherwise, the given command is executed. Word replacement is done in the same way as for the !\& command as described above.

Use of the ‘!\&’ character requires a following space as with any of the other commands. You should note that this command is executed in the foreground; ppp will not continue running until this process has exited. Use the bg command if you wish processing to happen in the background.

showvar

This command allows the user to examine the following:

showbundle

Show the current bundle settings.

showccp

Show the current CCP compression statistics.

showcompress

Show the current VJ compression statistics.

showescape

Show the current escape characters.

showfilter [name]

List the current rules for the given filter. If name is not specified, all filters are shown.

showhdlc

Show the current HDLC statistics.

showhelp \&| ?\&

Give a summary of available show commands.

showiface

Show the current interface information (the same as ifaceshow).

showipcp

Show the current IPCP statistics.

showlayers

Show the protocol layers currently in use.

showlcp

Show the current LCP statistics.

show[data]

link Show high level link information.

showlinks

Show a list of available logical links.

showlog

Show the current log values.

showmem

Show current memory statistics.

showncp

Show the current NCP statistics.

showphysical

Show low level link information.

showmp

Show Multi-link information.

showproto

Show current protocol totals.

showroute

Show the current routing tables.

showstopped

Show the current stopped timeouts.

showtimer

Show the active alarm timers.

showversion

Show the current version number of ppp.

term

Go into terminal mode. Characters typed at the keyboard are sent to the device. Characters read from the device are displayed on the screen. When a remote PPP peer is detected, ppp automatically enables Packet Mode and goes back into command mode.

MORE DETAILS

• Read the example configuration files. They are a good source of information.
• Use help, nat\&?, enable\&?, set?\&, and show?\& to get online information about what's available.
• The following URLs contain useful information:
  • http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/faq/ppp.html
  • http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/userppp.html

FILES

/etc/ppp/ppp.conf

System default configuration file.

/etc/ppp/ppp.secret

An authorisation file for each system.

/etc/ppp/ppp.linkup

A file to check when ppp establishes a network level connection.

/etc/ppp/ppp.linkdown

A file to check when ppp closes a network level connection.

/var/log/ppp.log

Logging and debugging information file. Note: this name is specified in /etc/syslog.conf. See syslog.conf(5) for further details.

/var/spool/lock/LCK..*

tty port locking file. Refer to uucplock(3) for further details.

/var/run/tunN.pid

The process ID (PID) of the ppp program connected to the tunN device, where ‘N’ is the number of the device.

/var/run/cuaXX.if

The tun interface used by this port. Again, this file is only created in -background, -auto, and -ddial modes.

/etc/services

Get port number if port number is using service name.

/var/run/ppp-authname-class-value

In multi-link mode, local domain sockets are created using the peer authentication name (‘authname’), the peer endpoint discriminator class (‘class’), and the peer endpoint discriminator value (‘value’). As the endpoint discriminator value may be a binary value, it is turned to HEX to determine the actual file name.

This socket is used to pass links between different instances of ppp.

SEE ALSO

HISTORY