PPP(8)

NAME
ppp - Point to Point Protocol (aka iijppp)

SYNOPSIS
ppp [-auto | -background | -ddial | -direct | -dedicated] [-alias] [system]

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) and it's thus somewhat hard to debug and/or modify its behavior. However, in this implementation PPP is done as a user process with the help of the tunnel device driver (tun).

Major Features

Provides 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 your modem directly. When your modem is connected to the remote peer and it starts to talk PPP , the PPP software 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 (dedicated or demon dialing) 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 who worry less about line charges and more about being connected full time.

Supports packet aliasing. Packet aliasing, more commonly known as 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 aliased for outgoing packets and de-aliased 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.

Supports server-side PPP connections. Can act as server which accepts incoming PPP connections.

Supports PAP and CHAP authentication.

Supports Proxy Arp. When PPP is set up as server, you can also configure it to do proxy arp for your connection.

Supports packet filtering. User can define four kinds of filters: ifilter for incoming packets, ofilter for outgoing packets, dfilter to define a dialing trigger packet and afilter 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 capability.

Supports IETF draft Predictor-1 compression. ppp supports not only VJ-compression but also Predictor-1 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 compression pre-compresses all data flowing through the link, thus reducing overhead to a minimum.

Supports Microsofts IPCP extentions. Name Server Addresses and NetBIOS Name Server Addresses can be negotiated with clients using the Microsoft PPP stack (ie. Win95, WinNT)

Runs under BSDI-1.1 and FreeBSD.
Patches for NeXTSTEP 3.2 are also available on the net.

GETTING STARTED
When you first run ppp you may need to deal with some initial configuration details. First, your kernel should include a tunnel device (the default in FreeBSD 2.0.5 and later). If it doesn't, you'll need to rebuild your kernel with the following line in your kernel configuration file:
    pseudo-device tun 1
You should set the numeric field to the maximum number of PPP connections you wish to support. Second, check your /dev directory for the tunnel device entry /dev/tun0. If it doesn't exist, you can create it by running "MAKEDEV tun0"

MANUAL DIALING
% ppp User Process PPP written by Toshiharu OHNO. * If you set your hostname and password in /etc/ppp/ppp.secret, you can't do anything except run the quit and help commands * ppp on "your hostname"> help passwd : Password for security quit : Quit the PPP program help : Display this message ppp on tama> pass <password> * "on" will change to "ON" if you specify the correct password. * ppp ON tama> * You can now specify the device name, speed and parity for your modem, and whether CTS/RTS signalling should be used (CTS/RTS is used by default). If your hardware does not provide CTS/RTS lines (as may happen when you are connected directly to certain ppp-capable terminal servers), ppp will never send any output through the port; it waits for a signal which never comes. Thus, if you have a direct line and can't seem to make a connection, try turning ctsrts off: * ppp ON tama> set line /dev/cuaa0 ppp ON tama> set speed 38400 ppp ON tama> set parity even ppp ON tama> set ctsrts on ppp ON tama> show modem * Modem related parameters are shown in here * ppp ON tama> * Use term command to talk with your modem * ppp ON tama> term at OK atdt123456 CONNECT login: ppp Password: * PPP started in remote side. When the peer start to talk PPP, the program will detect it automatically and return to command mode. * ppp ON tama> PPP ON tama> * NOW, you are connected! Note that ‘PPP’ in the prompt has changed to capital letters to indicate this. * PPP ON tama> show lcp * You'll see LCP status * PPP ON tama> show ipcp * You'll see IPCP status. At this point, your machine has a host route to the peer. If you want to add a default route entry, then enter the following command. * PPP ON tama> add 0 0 HISADDR * The string ‘HISADDR’ represents the IP address of connected peer. * PPP ON tama> * Use network applications (i.e. ping, telnet, ftp) in other windows * PPP ON tama> show log * Gives you some logging messages * PPP ON tama> close * The connection is closed and modem will be disconnected. * ppp ON tama> quit %

AUTOMATIC DIALING
To use automatic dialing, you must prepare some Dial and Login chat scripts. See the example definitions in /etc/ppp/ppp.conf.sample (the format of ppp.conf is pretty simple).
•   Each line contains one command, label or comment.
•   A line starting with a ‘#’ character is treated as a comment line.
•   A label name has to start in the first column and should be followed by a colon (:).
•   A command line must contain a space or tab in the first column.
Once ppp.conf is ready, specify the destination label name when you invoke ppp. Commands associated with the destination label are then executed. Note that the commands associated with the “default” label are ALWAYS executed. Once the connection is made, you'll find that the ppp portion of the prompt has changed to PPP. % ppp pm2 ... ppp ON tama> dial dial OK! login OK! PPP ON tama> If the /etc/ppp/ppp.linkup file is available, its contents are executed when the PPP connection is established. See the provided example which adds a default route. The string HISADDR represents the IP address of the remote peer.

BACKGROUND DIALING
If you want to establish a connection using ppp non-interactively (such as from a crontab(5) entry or an at(1) script) you should use the -background option. You must also specify the destination label in /etc/ppp/ppp.conf to use. When -background is specified, ppp attempts to establish the connection. If this 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. The file /var/run/ppp.tun0.pid contains the process id number of the ppp program that is using the tunnel device tun0.

DIAL ON DEMAND
To play with demand dialing, you must use the -auto or -ddial option. You must also specify the destination label in /etc/ppp/ppp.conf to use. It should contain the “ifaddr” command to define the remote peer's IP address. (refer to /etc/ppp/ppp.conf.sample) % ppp -auto pm2demand ... % When -auto or -ddial is specified, ppp runs as a daemon but you can still configure or examine its configuration by using the diagnostic port as follows: % telnet localhost 3000 Trying 127.0.0.1... Connected to localhost.spec.co.jp. Escape character is '^]'. User Process PPP. Written by Toshiharu OHNO. Working as auto mode. PPP on tama> show ipcp what ? PPP on tama> pass xxxx PPP ON tama> show ipcp IPCP [OPEND] his side: xxxx ....

Each ppp daemon has an associated port number which is computed as "3000 + tunnel_device_number". If 3000 is not good base number, edit defs.h in the ppp sources ( /usr/src/usr.sbin/ppp) and recompile it. When an outgoing packet is detected, ppp will perform the dialing action (chat script) and try to connect with the peer. If the connect fails, the default behavior is to wait 30 seconds and then attempt to connect when another outgoing packet is detected. This behavior can be changed with

    set redial seconds|random[.nseconds|random] [dial_attempts]

‘Seconds’ is the number of seconds to wait before attempting to connect again. If the argument is ‘random’, the delay period is a random value between 0 and 30 seconds. ‘Nseconds’ is the number of seconds to wait before attempting to dial the next number in a list of numbers (see the “set phone” command). The default is 3 seconds. Again, if the argument is ‘random’, the delay period is a random value between 0 and 30 seconds. ‘dial_attempts’ is the number of times to try to connect for each outgoing packet that is received. The previous value is unchanged if this parameter is omitted. If a value of zero is specified for ‘dial_attempts’, ppp will keep trying until a connection is made.

    set redial 10.3 4

will attempt to connect 4 times for each outgoing packet that is detected 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). Modifying the dial delay is very useful when running ppp in demand dial 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 redial). 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. 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. To terminate the program, type PPP ON tama> close ppp ON tama> quit all

A simple “quit” command will terminate the telnet connection but not the program itself. You must use “quit all” to terminate the program as well.

PACKET ALIASING
The -alias command line option enables 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 are aliased so that they appear to come from the ppp host, and incoming packets are de-aliased so that they are routed to the correct machine on the local area network. Packet aliasing 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 packet aliasing disabled. Then, the -alias option should be switched on, and network applications (web browser, telnet, ftp, ping, traceroute) 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/sysconfig and that other machines have designated the ppp host as the gateway for the LAN.

PACKET FILTERING
This implementation supports packet filtering. There are three kinds of filters: ifilter, ofilter and dfilter. Here are the basics:
•   A filter definition has the following syntax: set filter-name rule-no action [src_addr/src_width] [dst_addr/dst_width] [proto [src [lt|eq|gt] port ]] [dst [lt|eq|gt] port] [estab]

    1.  ‘filter-name’ should be one of ifilter, ofilter, or dfilter.

    2.  There are two actions: ‘permit’ and ‘deny’. If a given packet matches the rule, the associated action is taken immediately.

    3.  ‘src_width’ and ‘dst_width’ work like a netmask to represent an address range.

    4.  ‘proto’ must be one of icmp, udp or tcp.

    5.  ‘port number’ can be specified by number and service name from /etc/services.
•   Each filter can hold up to 20 rules, starting from rule 0. The entire rule set is not effective until rule 0 is defined.
•   If no rule is matched to a packet, that packet will be discarded (blocked).
•   Use “set filter-name -1” to flush all rules.
See /etc/ppp/ppp.conf.filter.example.

RECEIVING INCOMING PPP CONNECTIONS (Method 1)
To handle an incoming PPP connection request, follow these steps:

1.  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).

2.  Edit /etc/ttys to enable a getty on the port where the modem is attached. For example:
        ttyd1 /usr/libexec/getty std.38400 dialup on secure
    Don't forget to send a HUP signal to the init process to start the getty.
        # kill -HUP 1

3.  Prepare an account for the incoming user.

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

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

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

    (You can specify a label name for further control.)

    Direct mode ( -direct) lets ppp work with stdin and stdout. You can also telnet to port 3000 to get command mode control in the same manner as client-side

5.  Optional support for Microsoft's IPCP Name Server and NetBIOS Name Server negotiation can be enabled use “enable msext” and “set ns pri-addr [sec-addr]” along with “set nbns pri-addr [sec-addr]” in your ppp.conf file

RECEIVING INCOMING PPP CONNECTIONS (Method 2)
This method differs in that it recommends the use of mgetty+sendfax to handle the modem connections. The latest version 0.99 can be compiled with the “AUTO_PPP” option to allow detection of clients speaking PPP to the login prompt. Follow these steps:

1.  Get, configure, and install mgetty+sendfax v0.99 or later (beta) making sure you have used the AUTO_PPP option.

2.  Edit /etc/ttys to enable a mgetty on the port where the modem is attached. For example:
        cuaa1 /usr/local/sbin/mgetty -s 57600 dialup on

3.  Prepare an account for the incoming user.

        Pfred:xxxx:66:66:Fred's PPP:/home/ppp:/etc/ppp/ppp-dialup

4.  Examine the files /etc/ppp/sample.ppp-dialup /etc/ppp/sample.ppp-pap-dialup and /etc/ppp/ppp.conf.sample for ideas. ppp-pap-dialup is supposed to be called from /usr/local/etc/mgetty+sendfax/login.conf from a line like
        /AutoPPP/ - - /etc/ppp/ppp-pap-dialup

SETTING IDLE, LINE QUALITY REQUEST, RETRY TIMER
To check/set idletimer, use the “show timeout” and “set timeout [lqrtimer [retrytimer]]” commands. Ex:
    ppp ON tama> set timeout 600
The timeout period is measured in seconds, the default values for which are timeout = 180 or 3 min, lqrtimer = 30sec and retrytimer = 3sec. To disable the idle timer function, use the command “set timeout 0”. In -auto mode, an idle timeout causes the PPP session to be closed, though the ppp program itself remains running. Another trigger packet will cause it to attempt to reestablish the link.

Predictor-1 compression
This version supports CCP and Predictor type 1 compression based on the current IETF-draft specs. As a default behavior, ppp will attempt to use (or be willing to accept) this capability when the peer agrees (or requests it). To disable CCP/predictor functionality completely, use the “disable pred1” and “deny pred1” commands.

Controlling IP address
ppp uses IPCP to negotiate IP addresses. Each side of the connection specifies the IP address that it's willing to use, and if the requested IP address is acceptable then ppp returns 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 ACK), IPCP is set to the open state and a network level connection is established. To control this IPCP behavior, this implementation has the “set ifaddr” command for defining the local and remote IP address: set ifaddr [src_addr [dst_addr [netmask [trg_addr]]]] Where, ‘src_addr’ is the IP address that the local side is willing to use and ‘dst_addr’ is the IP address which the remote side should use. ‘netmask’ is interface netmask. ‘trg_addr’ is the IP address which used in address negotiation. Ex:
    set ifaddr 192.244.177.38 192.244.177.2 255.255.255.0
The above specification means:
•   I strongly want to use 192.244.177.38 as my IP address, and I'll disagree if the peer suggests that I use another address.
•   I strongly insist that peer use 192.244.177.2 as own side address and don't permit it to use any IP address but 192.244.177.2. When peer request another IP address, I always suggest that it use 192.244.177.2.
•   My interface netmask will be 255.255.255.0.
•   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 obey the direction from it.
In order to allow more flexible behavior, `ifaddr' variable allows the user to specify IP address more loosely:
    set ifaddr 192.244.177.38/24 192.244.177.2/20
A number followed by a slash (/) represent the number of bits significant in the IP address. The above example signifies that:
•   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.
•   192.244.177.2/0 means that I'll accept/permit any IP address but I'll try to insist that 192.244.177.2 be used first.

Connecting with your service provider
The following steps should be taken when connecting to your ISP:

1.  Describe your provider's 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 a colon (:). For example:

        set phone "1234567:2345678"

    Here, the first number is attempted. If the connection fails, the second number is attempted after the next number redial period. If the second number also fails, the first is tried again after the redial period has expired. The selected phone number is substituted for the \T string in the “set dial” command (see below).

2.  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.

3.  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.

    •   Expect nothing.

    •   Send ATZ.

    •   Expect OK. If that's not received, 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:

        set login "TIMEOUT 15 login:-\\r-login: awfulhak word: xxx 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 "xxx".

    •   Expect "ocol:" (the tail end of a "Protocol:" prompt).

    •   Send "PPP".

    •   Expect "HELLO".

    Login scripts vary greatly between ISPs.

4.  Use “set line” and “set sp” to specify your serial line and speed, for example:

        set line /dev/cuaa0
        set sp 115200

    Cuaa0 is the first serial port on FreeBSD. Cuaa1 is the second etc. 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 “set ifaddr” command to define the IP address.

    •   If you know what IP address your provider uses, then use it as the remote address, 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.

    •   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.0/24.

    An example for a connection where you don't know your IP number or your ISPs IP number would be:

        set ifaddr 10.0.0.1/0 10.0.0.2/0

6.  In most cases, your ISP will also be your default router. If this is the case, add the lines

        delete ALL
        add 0 0 HISADDR

    to ppp.conf.

    This tells ppp to delete all routing entries already made by ppp, then to add a default route to HISADDR. HISADDR is a macro meaning the "other side"s IP number.

    If you're using dynamic IP numbers, you must also put these two lines in the ppp.linkup file. Then, once the link has been established and ppp knows the actual IP numbers in use, all previous (and probably incorrect) entries are deleted and a default to the correct IP number is added. Use the same label as the one used in ppp.conf.

    If commands are being typed interactively, the only requirement is to type

        add 0 0 HISADDR

    after a successful dial.

7.  If your provider requests that you use PAP/CHAP authentication methods, add the next lines to your ppp.conf file:

        enable pap (or enable chap)
        disable chap (or disable pap)
        set authname MyName
        set authkey MyPassword

8.  It is also worth adding the following line:

        set openmode active

    This tells ppp to initiate LCP. Without this line, there's a possibility of both sides of the connection just sitting there and looking at eachother rather than communicating.
Please refer to /etc/ppp/ppp.conf.sample and /etc/ppp/ppp.linkup.sample for some real examples. The pmdemand label should be appropriate for most ISPs.

Logging facility
ppp is able to generate the following log info into /var/log/ppp.tun0.log:
Phase Phase transition log output
Chat Generate Chat script trace log
Connect Generate complete Chat log
Carrier Log Chat lines with 'CARRIER'
LQM Generate LQR report
LCP Generate LCP/IPCP packet trace
Link Log address assignments and link up/down events
TCP/IP Dump TCP/IP packet
HDLC Dump HDLC packet in hex
Async Dump async level packet in hex
The “set debug” command allows you to set logging output level, of which multiple levels can be specified. The default is equivalent to “set debug carrier link phase”. If a HUP signal is received, the log file is closed and re-opened to facilitate log file rotation.

MORE DETAILS
•   Please read the Japanese doc for complete explanation. It may not be useful for non-japanese readers, but examples in the document may help you to guess.
•   Please read example configuration files.
•   Use “help”, “show”?, “set”? and “set? <var>” commands.
•   NetBSD and BSDI-1.0 were supported in previous releases but are no longer supported in this release. Please contact the author if you need old driver code.

FILES
ppp refers to three files: ppp.conf, ppp.linkup and ppp.secret. These files are placed in /etc/ppp, but the user can create his own files under his $HOME directory as .ppp.conf, .ppp.linkup and .ppp.secret. ppp will always try to consult the user's personal setup first.
$HOME/ppp/.ppp.[conf|linkup|secret] User dependent configuration files. /etc/ppp/ppp.conf System default configuration file. /etc/ppp/ppp.secret An authorization file for each system. /etc/ppp/ppp.linkup A file to check when ppp establishes a network level connection. /var/log/ppp.tun0.log Logging and debugging information file. /var/spool/lock/Lck..* tty port locking file. /var/run/PPP.system Holds the pid for ppp -auto system. /var/run/tun0.pid The process id (pid) of the ppp program connected to the tun0 device. /var/run/ttyXX.pid The tun interface used by this port. /etc/services Get port number if port number is using service name.

SEE ALSO
chat(8), pppd(8), uucplock(3)

HISTORY
This program was submitted in FreeBSD-2.0.5 Atsushi Murai (amurai@spec.co.jp).

AUTHORS
Toshiharu OHNO (tony-o@iij.ad.jp)