PPP

DESCRIPTION

This is a user process PPP software package. Normally, PPP is implemented as a part of the kernel (e.g., as managed by pppd(8)) and it is thus somewhat hard to debug and/or modify its behaviour. However, in this implementation PPP is done as a user process with the help of the tunnel device driver (tun).

The -nat flag does the equivalent of a "nat enable yes", enabling ’s network address translation features. This allows ppp to act as a NAT or masquerading engine for all machines on an internal LAN. Refer to libalias(3) for details on the technical side of the NAT engine. Refer to the NETWORK ADDRESS TRANSLATION (PACKET ALIASING) section of this manual page for details on how to configure NAT in ppp.

The -quiet flag tells ppp to be silent at startup rather than displaying the mode and interface to standard output.

The -unit flag tells ppp to only attempt to open /dev/tun N. Normally, ppp will start with a value of 0 for N, and keep trying to open a tunnel device by incrementing the value of N by one each time until it succeeds. If it fails three times in a row because the device file is missing, it gives up.

The following mode s are understood by ppp:

One or more configuration entries or systems (as specified in /etc/ppp/ppp.conf) may also be specified on the command line. ppp will read the "default" system from /etc/ppp/ppp.conf at startup, followed by each of the systems specified on the command line.

Major Features

Provides an interactive user interface. Using its command mode, the user can easily enter commands to establish the connection with the remote end, check the status of connection and close the connection. All functions can also be optionally password protected for security.
Supports both manual and automatic dialing. Interactive mode has a "term" command which enables you to talk to the device directly. When you are connected to the remote peer and it starts to talk PPP, ppp detects it and switches to packet mode automatically. Once you have determined the proper sequence for connecting with the remote host, you can write a chat script to define the necessary dialing and login procedure for later convenience.
Supports on-demand dialup capability. By using -auto mode, ppp will act as a daemon and wait for a packet to be sent over the PPP link. When this happens, the daemon automatically dials and establishes the connection. In almost the same manner -ddial mode (direct-dial mode) also automatically dials and establishes the connection. However, it differs in that it will dial the remote site any time it detects the link is down, even if there are no packets to be sent. This mode is useful for full-time connections where we worry less about line charges and more about being connected full time. A third -dedicated mode is also available. This mode is targeted at a dedicated link between two machines. ppp will never voluntarily quit from dedicated mode - you must send it the "quit all" command via its diagnostic socket. A SIGHUP will force an LCP renegotiation, and a SIGTERM will force it to exit.
Supports client callback. ppp can use either the standard LCP callback protocol or the Microsoft CallBack Control Protocol (ftp://ftp.microsoft.com/developr/rfc/cbcp.txt).
Supports NAT or packet aliasing. Packet aliasing (a.k.a. IP masquerading) allows computers on a private, unregistered network to access the Internet. The PPP host acts as a masquerading gateway. IP addresses as well as TCP and UDP port numbers are NAT’d for outgoing packets and de-NAT’d for returning packets.
Supports background PPP connections. In background mode, if ppp successfully establishes the connection, it will become a daemon. Otherwise, it will exit with an error. This allows the setup of scripts that wish to execute certain commands only if the connection is successfully established.
Supports server-side PPP connections. In direct mode, ppp acts as server which accepts incoming PPP connections on stdin/stdout.
Supports PAP and CHAP (rfc 1994, 2433 and 2759) authentication. With PAP or CHAP, it is possible to skip the Unix style login(1) procedure, and use the PPP protocol for authentication instead. If the peer requests Microsoft CHAP authentication and ppp is compiled with DES support, an appropriate MD4/DES response will be made.
Supports RADIUS (rfc 2138 & 2548) authentication. An extension to PAP and CHAP, R emote A ccess D ial I n U ser S ervice allows authentication information to be stored in a central or distributed database along with various per-user framed connection characteristics. If libradius(3) is available at compile time, ppp will use it to make RADIUS requests when configured to do so.
Supports Proxy Arp. ppp can be configured to make one or more proxy arp entries on behalf of the peer. This allows routing from the peer to the LAN without configuring each machine on that LAN.
Supports packet filtering. User can define four kinds of filters: the in filter for incoming packets, the out filter for outgoing packets, the dial filter to define a dialing trigger packet and the alive filter for keeping a connection alive with the trigger packet.
Tunnel driver supports bpf. The user can use tcpdump(1) to check the packet flow over the PPP link.
Supports PPP over TCP and PPP over UDP. If a device name is specified as host: port [/ tcp|udp], ppp will open a TCP or UDP connection for transporting data rather than using a conventional serial device. UDP connections force ppp into synchronous mode.
Supports PPP over ISDN. If ppp is given a raw B-channel i4b device to open as a link, it is able to talk to the isdnd(8) daemon to establish an ISDN connection.
Supports PPP over Ethernet (rfc 2516). If ppp is given a device specification of the format PPPoE: iface Xo [: provider] and if netgraph(4) is available, ppp will attempt talk PPP over Ethernet to provider using the iface network interface.
On systems that do not support netgraph(4), an external program such as pppoed(8) may be used.
Supports IETF draft Predictor-1 (rfc 1978) and DEFLATE (rfc 1979) compression. ppp supports not only VJ-compression but also Predictor-1 and DEFLATE compression. Normally, a modem has built-in compression (e.g., v42.bis) and the system may receive higher data rates from it as a result of such compression. While this is generally a good thing in most other situations, this higher speed data imposes a penalty on the system by increasing the number of serial interrupts the system has to process in talking to the modem and also increases latency. Unlike VJ-compression, Predictor-1 and DEFLATE compression pre-compresses all network traffic flowing through the link, thus reducing overheads to a minimum.
Supports Microsoft’s IPCP extensions (rfc 1877). Name Server Addresses and NetBIOS Name Server Addresses can be negotiated with clients using the Microsoft PPP stack (i.e., Win95, WinNT)
Supports Multi-link PPP (rfc 1990) It is possible to configure ppp to open more than one physical connection to the peer, combining the bandwidth of all links for better throughput.
Supports MPPE (draft-ietf-pppext-mppe) MPPE is Microsoft Point to Point Encryption scheme. It is possible to configure ppp to participate in Microsoft’s Windows VPN. For now, ppp can only get encryption keys from CHAP 81 authentication. ppp must be compiled with DES for MPPE to operate.
Supports IPV6CP (rfc 2023). An IPv6 connection can be made in addition to or instead of the normal IPv4 connection.

PERMISSIONS

ppp is installed as user root and group network, with permissions 04554. By default, ppp will not run if the invoking user id is not zero. This may be overridden by using the "allow users" command in /etc/ppp/ppp.conf. When running as a normal user, ppp switches to user id 0 in order to alter the system routing table, set up system lock files and read the ppp configuration files. All external commands (executed via the "shell" or "!bg" commands) are executed as the user id that invoked ppp. Refer to the 'ID0' logging facility if you are interested in what exactly is done as user id zero.

GETTING STARTED

When you first run ppp you may need to deal with some initial configuration details.

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 "allow users" 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
*.*<TAB>/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
*.*<TAB>/var/log/ppp0.log
```
in /etc/syslog.conf. Do not forget to send a HUP signal to syslogd(8) after altering /etc/syslog.conf.
Although not strictly relevant to ’s 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 "enable dns" and "resolv" commands below for details.

MANUAL DIALING

In the following examples, we assume that your machine name is awfulhak. when you invoke ppp (see PERMISSIONS above) with no arguments, you are presented with a prompt:

ppp ON awfulhak>

The 'ON' part of your prompt should always be in upper case. If it is in lower case, it means that you must supply a password using the "passwd" command. This only ever happens if you connect to a running version of ppp and have not authenticated yourself using the correct password.

You can start by specifying the device name and speed:

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

Normally, hardware flow control (CTS/RTS) is used. However, under certain circumstances (as may happen when you are connected directly to certain PPP-capable terminal servers), this may result in ppp hanging as soon as it tries to write data to your communications link as it is waiting for the CTS (clear to send) signal - which will never come. Thus, if you have a direct line and cannot seem to make a connection, try turning CTS/RTS off with "set ctsrts off". If you need to do this, check the "set accmap" description below too - you will probably need to "set accmap 000a0000".

Usually, parity is set to "none", and this is ’s default. Parity is a rather archaic error checking mechanism that is no longer used because modern modems do their own error checking, and most link-layer protocols (that is what ppp is) use much more reliable checking mechanisms. Parity has a relatively huge overhead (a 12.5% increase in traffic) and as a result, it is always disabled (set to "none") when PPP is opened. However, some ISPs (Internet Service Providers) may use specific parity settings at connection time (before PPP is opened). Notably, Compuserve insist on even parity when logging in:

ppp ON awfulhak> set parity even

You can now see what your current device settings look like:

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/cuad0
 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>

The term command can now be used to talk directly to the device:

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

When the peer starts to talk in PPP, ppp detects this automatically and returns to command mode.

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

If it does not, it is probable that the peer is waiting for your end to start negotiating. To force ppp to start sending PPP configuration packets to the peer, use the "~p" command to drop out of terminal mode and enter packet mode.

If you never even receive a login prompt, it is quite likely that the peer wants to use PAP or CHAP authentication instead of using Unix-style login/password authentication. To set things up properly, drop back to the prompt and set your authentication name and key, then reconnect:

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

You may need to tell ppp to initiate negotiations with the peer here too:

~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

You are now connected! Note that 'PPP' in the prompt has changed to capital letters to indicate that you have a peer connection. If only some of the three Ps go uppercase, wait until either everything is uppercase or lowercase. If they revert to lowercase, it means that ppp could not successfully negotiate with the peer. A good first step for troubleshooting at this point would be to

ppp ON awfulhak> set log local phase lcp ipcp

and try again. Refer to the "set log" command description below for further details. If things fail at this point, it is quite important that you turn logging on and try again. It is also important that you note any prompt changes and report them to anyone trying to help you.

When the link is established, the show command can be used to see how things are going:

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 *

At this point, your machine has a host route to the peer. This means that you can only make a connection with the host on the other side of the link. If you want to add a default route entry (telling your machine to send all packets without another routing entry to the other side of the PPP link), enter the following command:

PPP ON awfulhak> add default HISADDR

The string 'HISADDR' represents the IP address of the connected peer. If the "add" command fails due to an existing route, you can overwrite the existing route using:

PPP ON awfulhak> add! default HISADDR

This command can also be executed before actually making the connection. If a new IP address is negotiated at connection time, ppp will update your default route accordingly.

You can now use your network applications (ping, telnet, ftp, etc.) in other windows or terminals on your machine. If you wish to reuse the current terminal, you can put ppp into the background using your standard shell suspend and background commands (usually "^Z" followed by "bg").

Refer to the PPP COMMAND LIST section for details on all available commands.

AUTOMATIC DIALING

To use automatic dialing, you must prepare some Dial and Login chat scripts. See the example definitions in /usr/share/examples/ppp/ppp.conf.sample (the format of /etc/ppp/ppp.conf is pretty simple). Each line contains one comment, inclusion, label or command:

A line starting with a ("#") character is treated as a comment line. Leading whitespace are 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 colon (":").
A command line must contain a space or tab in the first column.
A string starting with the "$" character is substituted with the value of the environment variable by the same name. Likewise, a string starting with the "~" 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. If you want to include a literal "$" or "~" character in a command or argument, enclose them in double quotes, e.g.,
```
set password "pa$ss~word"
```

The /etc/ppp/ppp.conf file should consist of at least a "default" section. This section is always executed. It should also contain one or more sections, named according to their purpose, for example, "MyISP" would represent your ISP, and "ppp-in" would represent an incoming ppp configuration. You can now specify the destination label name when you invoke ppp. Commands associated with the "default" label are executed, followed by those associated with the destination label provided. When ppp is started with no arguments, the "default" section is still executed. The load command can be used to manually load a section from the /etc/ppp/ppp.conf file:

ppp ON awfulhak> load MyISP

Note, no action is taken by ppp after a section is loaded, whether it is the result of passing a label on the command line or using the "load" command. Only the commands specified for that label in the configuration file are executed. However, when invoking ppp with the -background , -ddial , or -dedicated switches, the link mode tells ppp to establish a connection. Refer to the "set mode" command below for further details.

Once the connection is made, the 'ppp' portion of the prompt will change to 'PPP':

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

The Ppp prompt indicates that ppp has entered the authentication phase. The PPp prompt indicates that ppp has entered the network phase. The PPP prompt indicates that ppp has successfully negotiated a network layer protocol and is in a usable state.

If the /etc/ppp/ppp.linkup file is available, its contents are executed when the PPP connection is established. See the provided "pmdemand" example in /usr/share/examples/ppp/ppp.conf.sample which runs a script in the background after the connection is established (refer to the "shell" and "bg" commands below for a description of possible substitution strings). Similarly, when a connection is closed, the contents of the /etc/ppp/ppp.linkdown file are executed. Both of these files have the same format as /etc/ppp/ppp.conf.

In previous versions of ppp, it was necessary to re-add routes such as the default route in the ppp.linkup file. ppp supports 'sticky routes', where all routes that contain the HISADDR, MYADDR, HISADDR6 or MYADDR6 literals will automatically be updated when the values of these variables change.

BACKGROUND DIALING

If you want to establish a connection using ppp non-interactively (such as from a crontab(5) entry or an at(1) job) you should use the -background option. When -background is specified, ppp attempts to establish the connection immediately. If multiple phone numbers are specified, each phone number will be tried once. If the attempt fails, ppp exits immediately with a non-zero exit code. If it succeeds, then ppp becomes a daemon, and returns an exit status of zero to its caller. The daemon exits automatically if the connection is dropped by the remote system, or it receives a TERM signal.

DIAL ON DEMAND

Demand dialing is enabled with the -auto or -ddial options. You must also specify the destination label in /etc/ppp/ppp.conf to use. It must contain the "set ifaddr" command to define the remote peers IP address. (refer to /usr/share/examples/ppp/ppp.conf.sample)

# ppp -auto pmdemand

When -auto or -ddial is specified, ppp runs as a daemon but you can still configure or examine its configuration by using the "set server" command in /etc/ppp/ppp.conf, (for example, "set server +3000 mypasswd") and connecting to the diagnostic port as follows:

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

The "show who" command lists users that are currently connected to ppp itself. If the diagnostic socket is closed or changed to a different socket, all connections are immediately dropped.

In -auto mode, when an outgoing packet is detected, ppp will perform the dialing action (chat script) and try to connect with the peer. In -ddial mode, the dialing action is performed any time the line is found to be down. If the connect fails, the default behaviour is to wait 30 seconds and then attempt to connect when another outgoing packet is detected. This behaviour can be changed using the "set redial" command:

set redial secs Xo [+ inc [- max] [.next]] [attempts]

So, for example:

set redial 10.3 4

will attempt to connect 4 times for each outgoing packet that causes a dial attempt with a 3 second delay between each number and a 10 second delay after all numbers have been tried. If multiple phone numbers are specified, the total number of attempts is still 4 (it does not attempt each number 4 times).

Alternatively,

set redial 10+10-5.3 20

tells ppp to attempt to connect 20 times. After the first attempt, ppp pauses for 10 seconds. After the next attempt it pauses for 20 seconds and so on until after the sixth attempt it pauses for 1 minute. The next 14 pauses will also have a duration of one minute. If ppp connects, disconnects and fails to connect again, the timeout starts again at 10 seconds.

Modifying the dial delay is very useful when running ppp in -auto mode on both ends of the link. If each end has the same timeout, both ends wind up calling each other at the same time if the link drops and both ends have packets queued. At some locations, the serial link may not be reliable, and carrier may be lost at inappropriate times. It is possible to have ppp redial should carrier be unexpectedly lost during a session.

set reconnect timeout ntries

This command tells ppp to re-establish the connection ntries times on loss of carrier with a pause of timeout seconds before each try. For example,

set reconnect 3 5

tells ppp that on an unexpected loss of carrier, it should wait 3 seconds before attempting to reconnect. This may happen up to 5 times before ppp gives up. The default value of ntries is zero (no reconnect). Care should be taken with this option. If the local timeout is slightly longer than the remote timeout, the reconnect feature will always be triggered (up to the given number of times) after the remote side times out and hangs up. NOTE: In this context, losing too many LQRs constitutes a loss of carrier and will trigger a reconnect. If the -background flag is specified, all phone numbers are dialed at most once until a connection is made. The next number redial period specified with the "set redial" command is honoured, as is the reconnect tries value. If your redial value is less than the number of phone numbers specified, not all the specified numbers will be tried. To terminate the program, type

PPP ON awfulhak> close
ppp ON awfulhak> quit all

A simple "quit" command will terminate the pppctl(8) or telnet(1) connection but not the ppp program itself. You must use "quit all" to terminate ppp as well.

RECEIVING INCOMING PPP CONNECTIONS (Method 1)

To handle an incoming PPP connection request, follow these steps:

Make sure the modem and (optionally) /etc/rc.serial 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).

Edit /etc/ttys to enable a getty(8) on the port where the modem is attached. For example: ttyd1"/usr/libexec/getty std.38400dialup on secure" Do not 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/cuad1
ppp ON awfulhak> set speed 38400
ppp ON awfulhak> term
deflink: Entering terminal mode on /dev/cuad1
Type ‘~?’ for help
at
OK
at
OK
atz
OK
at
OK
~.
ppp ON awfulhak> quit

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.

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.

Support for IPCP Domain Name Server and NetBIOS Name Server negotiation can be enabled using the "accept dns" and "set nbns" commands. Refer to their descriptions below.

RECEIVING INCOMING PPP CONNECTIONS (Method 2)

This method differs in that we use ppp to authenticate the connection rather than login(1):

Configure your default section in /etc/gettytab with automatic ppp recognition by specifying the "pp" capability:
```
default:\
	:pp=/usr/local/bin/ppplogin:\
	.....
```
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.
Add either "enable chap" or "enable pap" (or both) to /etc/ppp/ppp.conf under the 'incoming' label (or whatever label ppplogin uses).
Create an entry in /etc/ppp/ppp.secret for each incoming user:
```
Pfred<TAB>xxxx
Pgeorge<TAB>yyyy
```

Now, as soon as getty(8) detects a ppp connection (by recognising the HDLC frame headers), it runs "/usr/local/bin/ppplogin".

It is VITAL that either PAP or CHAP are enabled as above. If they are not, you are allowing anybody to establish a ppp session with your machine without a password, opening yourself up to all sorts of potential attacks.

AUTHENTICATING INCOMING CONNECTIONS

Normally, the receiver of a connection requires that the peer authenticates itself. This may be done using login(1), but alternatively, you can use PAP or CHAP. CHAP is the more secure of the two, but some clients may not support it. Once you decide which you wish to use, add the command 'enable chap' or 'enable pap' to the relevant section of ppp.conf.

You must then configure the /etc/ppp/ppp.secret file. This file contains one line per possible client, each line containing up to five fields:

name key[ hisaddr [label [callback-number]] ]

The name and key specify the client username and password. If key is "*" and PAP is being used, ppp will look up the password database (passwd(5)) when authenticating. If the client does not offer a suitable response based on any name / key combination in ppp.secret, authentication fails.

If authentication is successful, hisaddr (if specified) is used when negotiating IP numbers. See the "set ifaddr" command for details.

If authentication is successful and label is specified, the current system label is changed to match the given label. This will change the subsequent parsing of the ppp.linkup and ppp.linkdown files.

If authentication is successful and callback-number is specified and "set callback" has been used in ppp.conf, the client will be called back on the given number. If CBCP is being used, callback-number may also contain a list of numbers or a "*", as if passed to the "set cbcp" command. The value will be used in ’s subsequent CBCP phase.

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

Instead of running ppp over a serial link, it is possible to use a TCP connection instead by specifying the host, port and protocol as the device:

set device ui-gate:6669/tcp

Instead of opening a serial device, ppp will open a TCP connection to the given machine on the given socket. It should be noted however that ppp does not use the telnet protocol and will be unable to negotiate with a telnet server. You should set up a port for receiving this PPP connection on the receiving machine (ui-gate). This is done by first updating /etc/services to name the service:

ppp-in 6669/tcp # Incoming PPP connections over TCP

and updating /etc/inetd.conf to tell inetd(8) how to deal with incoming connections on that port:

ppp-in stream tcp nowait root /usr/sbin/ppp ppp -direct ppp-in

Do not forget to send a HUP signal to inetd(8) after you have updated /etc/inetd.conf. Here, we use a label named "ppp-in". The entry in /etc/ppp/ppp.conf on ui-gate (the receiver) should contain the following:

ppp-in:
 set timeout 0
 set ifaddr 10.0.4.1 10.0.4.2

and the entry in /etc/ppp/ppp.linkup should contain:

ppp-in:
 add 10.0.1.0/24 HISADDR

It is necessary to put the "add" command in ppp.linkup to ensure that the route is only added after ppp has negotiated and assigned addresses to its interface.

You may also want to enable PAP or CHAP for security. To enable PAP, add the following line:

 enable PAP

You will also need to create the following entry in /etc/ppp/ppp.secret:

MyAuthName MyAuthPasswd

If MyAuthPasswd is a "*", the password is looked up in the passwd(5) database.

The entry in /etc/ppp/ppp.conf on awfulhak (the initiator) should contain the following:

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

with the route setup in /etc/ppp/ppp.linkup:

ui-gate:
 add 10.0.2.0/24 HISADDR

Again, if you are enabling PAP, you will also need this in the /etc/ppp/ppp.conf profile:

 set authname MyAuthName
 set authkey MyAuthKey

We are assigning the address of 10.0.4.1 to ui-gate, and the address 10.0.4.2 to awfulhak. To open the connection, just type

awfulhak # ppp -background ui-gate

The result will be an additional "route" on awfulhak to the 10.0.2.0/24 network via the TCP connection, and an additional "route" on ui-gate to the 10.0.1.0/24 network. The networks are effectively bridged - the underlying TCP connection may be across a public network (such as the Internet), and the PPP traffic is conceptually encapsulated (although not packet by packet) inside the TCP stream between the two gateways.

The major disadvantage of this mechanism is that there are two "guaranteed delivery" mechanisms in place - the underlying TCP stream and whatever protocol is used over the PPP link - probably TCP again. If packets are lost, both levels will get in each others way trying to negotiate sending of the missing packet.

To avoid this overhead, it is also possible to do all this using UDP instead of TCP as the transport by simply changing the protocol from "tcp" to "udp". When using UDP as a transport, ppp will operate in synchronous mode. This is another gain as the incoming data does not have to be rearranged into packets.

Care should be taken when adding a default route through a tunneled setup like this. It is quite common for the default route (added in /etc/ppp/ppp.linkup) to end up routing the link’s TCP connection through the tunnel, effectively garrotting the connection. To avoid this, make sure you add a static route for the benefit of the link:

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

where "x.x.x.x" is the IP number that your route to "ui-gate" would normally use.

When routing your connection accross a public network such as the Internet, it is preferable to encrypt the data. This can be done with the help of the MPPE protocol, although currently this means that you will not be able to also compress the traffic as MPPE is implemented as a compression layer (thank Microsoft for this). To enable MPPE encryption, add the following lines to /etc/ppp/ppp.conf on the server:

  enable MSCHAPv2
  disable deflate pred1
  deny deflate pred1

ensuring that you have put the requisite entry in /etc/ppp/ppp.secret (MSCHAPv2 is challenge based, so passwd(5) cannot be used)

MSCHAPv2 and MPPE are accepted by default, so the client end should work without any additional changes (although ensure you have "set authname" and "set authkey" in your profile).

NETWORK ADDRESS TRANSLATION (PACKET ALIASING)

The -nat command line option enables network address translation (a.k.a. packet aliasing). This allows the ppp host to act as a masquerading gateway for other computers over a local area network. Outgoing IP packets are NAT’d so that they appear to come from the ppp host, and incoming packets are de-NAT’d so that they are routed to the correct machine on the local area network. NAT allows computers on private, unregistered subnets to have Internet access, although they are invisible from the outside world. In general, correct ppp operation should first be verified with network address translation disabled. Then, the -nat option should be switched on, and network applications (web browser, telnet(1), ftp(1), ping(8), traceroute(8)) should be checked on the ppp host. Finally, the same or similar applications should be checked on other computers in the LAN. If network applications work correctly on the ppp host, but not on other machines in the LAN, then the masquerading software is working properly, but the host is either not forwarding or possibly receiving IP packets. Check that IP forwarding is enabled in /etc/rc.conf and that other machines have designated the ppp host as the gateway for the LAN.

PACKET FILTERING

This implementation supports packet filtering. There are four kinds of filters: the in filter, the out filter, the dial filter and the alive filter. Here are the basics:

A filter definition has the following syntax: set filter name rule-no action [!] [ [host] src_addr [/ width] [dst_addr [/ width]] ] [ proto [src cmp port] [dst cmp port] [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 [/ width]] and [dst_addr [/ width]] are the source and destination IP number specifications. If [/ width] 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 'lt', 'eq' or 'gt', meaning less-than, equal and greater-than respectively. Port can be specified as a numeric port or by 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 set timeout 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 is 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.

See /usr/share/examples/ppp/ppp.conf.sample.

SETTING THE IDLE TIMER

To check/set the idle timer, use the "show bundle" and "set timeout" commands:

ppp ON awfulhak> set timeout 600

The timeout period is measured in seconds, the default value for which is 180 seconds (or 3 min). To disable the idle timer function, use the command

ppp ON awfulhak> set timeout 0

In -ddial and -dedicated modes, the idle timeout is ignored. In -auto mode, when the idle timeout causes the PPP session to be closed, the ppp program itself remains running. Another trigger packet will cause it to attempt to re-establish the link.

PREDICTOR-1 and DEFLATE COMPRESSION

ppp supports both Predictor type 1 and deflate compression. By default, ppp will attempt to use (or be willing to accept) both compression protocols when the peer agrees (or requests them). The deflate protocol is preferred by ppp. Refer to the "disable" and "deny" commands if you wish to disable this functionality.

It is possible to use a different compression algorithm in each direction by using only one of "disable deflate" and "deny deflate" (assuming that the peer supports both algorithms).

By default, when negotiating DEFLATE, ppp will use a window size of 15. Refer to the "set deflate" command if you wish to change this behaviour.

A special algorithm called DEFLATE24 is also available, and is disabled and denied by default. This is exactly the same as DEFLATE except that it uses CCP ID 24 to negotiate. This allows ppp to successfully negotiate DEFLATE with pppd version 2.3.*.

CONTROLLING IP ADDRESS

For IPv4, ppp uses IPCP to negotiate IP addresses. Each side of the connection specifies the IP address that it is willing to use, and if the requested IP address is acceptable then ppp returns an ACK to the requester. Otherwise, ppp returns NAK to suggest that the peer use a different IP address. When both sides of the connection agree to accept the received request (and send an ACK), IPCP is set to the open state and a network level connection is established. To control this IPCP behaviour, this implementation has the "set ifaddr" command for defining the local and remote IP address:

set ifaddr[src_addr
[/ nn]
[dst_addr [/ nn]
[netmask
[trigger_addr]
]
]
]

where, 'src_addr' is the IP address that the local side is willing to use, 'dst_addr' is the IP address which the remote side should use and 'netmask' is the netmask that should be used. 'Src_addr' defaults to the current hostname(1), 'dst_addr' defaults to 0.0.0.0, and 'netmask' defaults to whatever mask is appropriate for 'src_addr'. It is only possible to make 'netmask' smaller than the default. The usual value is 255.255.255.255, as most kernels ignore the netmask of a POINTOPOINT interface.

Some incorrect PPP implementations require that the peer negotiates a specific IP address instead of 'src_addr'. If this is the case, 'trigger_addr' may be used to specify this IP number. This will not affect the routing table unless the other side agrees with this proposed number.

set ifaddr 192.244.177.38 192.244.177.2 255.255.255.255 0.0.0.0

The above specification means:

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 will not 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.

This is all fine when each side has a pre-determined IP address, however it is often the case that one side is acting as a server which controls all IP addresses and the other side should go along with it. In order to allow more flexible behaviour, the "set ifaddr" command allows the user to specify IP addresses more loosely:

set ifaddr 192.244.177.38/24 192.244.177.2/20

A number followed by a slash ("/") represents the number of bits significant in the IP address. The above example means:

I would like to use 192.244.177.38 as my address if it is possible, but I will also accept any IP address between 192.244.177.0 and 192.244.177.255.
I would like to make him use 192.244.177.2 as his own address, but I will 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 peers selection. When using zero, no routing table entries will be made until a connection is established.
192.244.177.2/0 means that I will accept/permit any IP address but I will suggest that 192.244.177.2 be used first.

When negotiating IPv6 addresses, no control is given to the user. IPV6CP negotiation is fully automatic.

CONNECTING WITH YOUR INTERNET SERVICE PROVIDER

The following steps should be taken when connecting to your ISP:

Describe your providers phone number(s) in the dial script using the "set phone" command. This command allows you to set multiple phone numbers for dialing and redialing separated by either a pipe ("|") or a colon (":"):
```
set phone telno Xo
[| backupnumber
...[:nextnumber]
...]
```
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. If the login script of the 2345678 number 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 "set dial" command (see below).
Set up your redial requirements using "set redial". 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.
Describe your login procedure using the "set dial" and "set login" commands. The "set dial" 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 \"\" \
  ATZ OK-ATZ-OK ATDT\\T TIMEOUT 60 CONNECT"
```
This modem "chat" string means:
- Abort if the string "BUSY" or "NO CARRIER" are received.
- Set the timeout to 4 seconds.
- Expect nothing.
- Send ATZ.
- Expect OK. If that is 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 \
  word: \\P ocol: PPP HELLO"

This login "chat" string means:

Set the timeout to 15 seconds.
Expect "login:". If it is 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".

command

chat

ENABLE CHAT LOGGING

Use "set device" and "set speed" to specify your serial line and speed, for example:
```
set device /dev/cuad0
set speed 115200
```
Cuad0 is the first serial port on If you are running ppp on cua00 is the first. 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.
Use the "set ifaddr" 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').
- In most cases, your ISP will also be your default router. If this is the case, add the line
```
add default HISADDR
```
  to /etc/ppp/ppp.conf (or to /etc/ppp/ppp.linkup for setups that do not use -auto mode). 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.
- 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.
- Ask your ISP to authenticate your nameserver address(es) with the 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

ppp is able to generate the following log info either via syslog(3) or directly to the screen:

The "set log" command allows you to set the logging output level. Multiple levels can be specified on a single command line. The default is equivalent to "set log Phase".

It is also possible to log directly to the screen. The syntax is the same except that the word "local" should immediately follow "set log". The default is "set log local" (i.e., only the un-maskable warning, error and alert output).

If The first argument to "set log [local]" begins with a '+' or a '-' character, the current log levels are not cleared, for example:

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

Log messages of level Warning, Error and Alert are not controllable using "set log [local]".

The Warning level is special in that it will not be logged if it can be displayed locally.

SIGNAL HANDLING

ppp deals with the following signals:

MULTI-LINK PPP

If you wish to use more than one physical link to connect to a PPP peer, that peer must also understand the MULTI-LINK PPP protocol. Refer to RFC 1990 for specification details.

The peer is identified using a combination of his "endpoint discriminator" and his "authentication id". Either or both of these may be specified. It is recommended that at least one is specified, otherwise there is no way of ensuring that all links are actually connected to the same peer program, and some confusing lock-ups may result. Locally, these identification variables are specified using the "set enddisc" and "set authname" commands. The 'authname' (and 'authkey') must be agreed in advance with the peer.

Multi-link capabilities are enabled using the "set mrru" command (set maximum reconstructed receive unit). Once multi-link is enabled, ppp will attempt to negotiate a multi-link connection with the peer.

By default, only one 'link' is available (called 'deflink'). To create more links, the "clone" command is used. This command will clone existing links, where all characteristics are the same except:

The new link has its own name as specified on the "clone" command line.
The new link is an 'interactive' link. Its mode may subsequently be changed using the "set mode" command.
The new link is in a 'closed' state.

A summary of all available links can be seen using the "show links" command.

Once a new link has been created, command usage varies. All link specific commands must be prefixed with the "link name" command, specifying on which link the command is to be applied. When only a single link is available, ppp is smart enough not to require the "link name" prefix.

Some commands can still be used without specifying a link - resulting in an operation at the 'bundle' level. For example, once two or more links are available, the command "show ccp" will show CCP configuration and statistics at the multi-link level, and "link deflink show ccp" will show the same information at the "deflink" link level.

Armed with this information, the following configuration might be used:

mp:
 set timeout 0
 set log phase chat
 set device /dev/cuad0 /dev/cuad1 /dev/cuad2
 set phone "123456789"
 set dial "ABORT BUSY ABORT NO\sCARRIER TIMEOUT 5 \"\" ATZ \
           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’’)

Note how all cloning is done at the end of the configuration. Usually, the link will be configured first, then cloned. If you wish all links to be up all the time, you can add the following line to the end of your configuration.

  link 1,2,3 set mode ddial

If you want the links to dial on demand, this command could be used:

  link * set mode auto

Links may be tied to specific names by removing the "set device" line above, and specifying the following after the "clone" command:

 link 1 set device /dev/cuad0
 link 2 set device /dev/cuad1
 link 3 set device /dev/cuad2

Use the "help" command to see which commands require context (using the "link" command), which have optional context and which should not have any context.

When ppp has negotiated MULTI-LINK mode with the peer, it creates a local domain socket in the /var/run directory. This socket is used to pass link information (including the actual link file descriptor) between different ppp invocations. This facilitates ’s ability to be run from a getty(8) or directly from /etc/gettydefs (using the 'pp=' capability), without needing to have initial control of the serial line. Once ppp negotiates multi-link mode, it will pass its open link to any already running process. If there is no already running process, ppp will act as the master, creating the socket and listening for new connections.

PPP

Point to Point Protocol (a.k.a. user-ppp)

SYNOPSIS