Configure and Debug a Serial PPP Link with pppd

pppd is the daemon that brings a serial PPP link up, and it happily runs with a typo until authentication fails at 2am. This walks through a repeatable peer configuration, a dry option check that catches mistakes before anything dials, and a short path from a failed negotiation to useful diagnostics. The examples use the installed ppp package version 2.4.9-1+1.1ubuntu4.

Budget 20 minutes for the configuration, plus another 10 if the peer or modem needs debugging. You need root access for files under /etc/ppp, a serial device, a configured remote PPP peer, and the chat utility if the link must dial or log in. Nothing here invents a telephone number, username, password, device name or IP address: swap in whatever your network administrator actually gave you.

1. Check the installed daemon

Start with checks that touch nothing. None of these commands start PPP or need elevated privileges:

$ command -v pppd
/usr/sbin/pppd
$ dpkg-query -W -f='${Package} ${Version}\n' ppp
ppp 2.4.9-1+1.1ubuntu4
$ man pppd

The daemon reads system options before anything you type on the command line. That order matters: /etc/ppp/options, then the user's ~/.ppprc, then a device-specific /etc/ppp/options.ttyname. A peer file loaded with call NAME comes from /etc/ppp/peers/NAME and can itself carry privileged options.

2. Create a peer profile

An administrator-owned peer file means the connection starts with one short, auditable command instead of a pile of flags typed from memory. The example below assumes /dev/ttyUSB0, 115200 baud, hardware flow control, and a chat script that already exists:

# install -o root -g root -m 0644 /dev/null /etc/ppp/peers/field-link
# editor /etc/ppp/peers/field-link

/dev/ttyUSB0
115200
crtscts
connect '/usr/sbin/chat -v -f /etc/ppp/chat-field-link'
defaultroute
usepeerdns
noipdefault

A peer file is just an options file, so each line is an option and its argument where one is needed. crtscts turns on RTS/CTS hardware flow control. defaultroute adds a default route only once IPCP succeeds, and removes it when the link ends. usepeerdns asks for up to two DNS addresses and writes them to /etc/ppp/resolv.conf, also making DNS1 and DNS2 available to ip-up.

noipdefault stops pppd choosing the first local address as its own default. On a simple client link the peer normally hands out addresses anyway. If your provider gives fixed addresses instead, use an explicit local:remote IP option after confirming the values with them.

3. Keep credentials in the secrets file

If this machine must authenticate to the peer, put the identity and secret in the appropriate secrets file rather than using password on the command line. For PAP, the file is /etc/ppp/pap-secrets; CHAP uses /etc/ppp/chap-secrets. The files must be owned by root and must not be readable or writable by other users.

# chmod 600 /etc/ppp/pap-secrets
# chown root:root /etc/ppp/pap-secrets
# editor /etc/ppp/pap-secrets

"PPP_USER" "PEER_NAME" "REPLACE_WITH_SECRET" *

Use the exact format and peer name supplied by the remote administrator. In the peer file, identify the local name with user PPP_USER. If the peer authenticates this machine with CHAP rather than PAP, use the CHAP file and the peer's required name. Avoid putting a real secret in shell history, process listings or article notes.

# stat -c '%U:%G %a %n' /etc/ppp/pap-secrets
root:root 600 /etc/ppp/pap-secrets

4. Validate options before connecting

dump paired with dryrun makes pppd parse the configuration, print its resolved options, and exit without dialling anything. It is the safest useful test on offer, though it still reads the configured device and files, so run it as root when the peer file or device is privileged:

# pppd call field-link dryrun dump

Successful parsing returns to the shell without starting a link. The output is implementation and configuration dependent, so do not compare it with a fixed transcript. If pppd reports an unknown option, a malformed value or a mutually exclusive pair, fix that first. A non-zero status here points to option processing rather than modem negotiation.

Common traps are a peer name beginning with /, a peer name containing .., an unquoted chat command with shell metacharacters, and assuming that call reads a file from the current directory. It does not: the safe peer-file location is /etc/ppp/peers.

5. Start the link and verify its effect

Starting the link is a service-affecting action. Save the current route first, especially if defaultroute is present:

$ ip route show default
default via EXISTING_GATEWAY dev EXISTING_INTERFACE
# pppd call field-link

With a serial device, pppd normally detaches after it starts. Check for the PPP interface and negotiated addresses:

$ ip -brief address show | grep '^ppp'
ppp0             UNKNOWN        LOCAL_IP peer REMOTE_IP
$ ip route show dev ppp0
$ test -f /etc/ppp/resolv.conf && cat /etc/ppp/resolv.conf

The interface name and addresses are host-specific. If no ppp interface appears, inspect the daemon's log before changing options. Do not assume that a process which detached has negotiated IP successfully: exit status 0 can also describe a daemon that detached, and the connection may later be terminated by the peer.

To keep the daemon in the terminal while testing, add nodetach to the command line. This is useful for immediate messages, but it occupies the terminal. Pressing Ctrl-C sends SIGINT, which terminates the link and restores the serial device settings.

6. Diagnose a failed negotiation

Turn on debug only for a controlled test: it logs PPP control packets, including authentication exchanges, to syslog. That detail is exactly what you need for a diagnosis and exactly what you do not want sitting in logs afterwards, so remove the option once the test is done and protect what it wrote.

# pppd call field-link nodetach debug logfile /var/log/pppd-field-link.log
$ tail -f /var/log/pppd-field-link.log

The exit status narrows the next check. Status 2 means an option-processing error; 6 means the serial port could not be locked; 7 means it could not be opened; 8 means the connect script failed; 10 means PPP negotiation did not reach a running network protocol; 11 means the peer refused to authenticate this machine; and 19 means this machine failed to authenticate to the peer.

For status 6, find the competing process and do not delete a lock file while another process may still own the port. For status 7, check the device path and permissions. For status 8, run the chat script against the correct device and inspect its expected prompts. For authentication failures, check the protocol, names and secret file permissions without exposing the secret.

When the link is established but traffic is wrong, check routes before changing MTU or compression. defaultroute may be competing with an existing route; defaultroute-metric can limit which default route is installed. If the peer supplies DNS, check the generated resolver file and the ip-up script that consumes DNS1 and DNS2.

7. Stop, recover and clean up

Find the daemon from the PID file or process list, then send SIGTERM to the right process, not a guessed one. A normal SIGTERM closes the link and restores the serial settings:

$ pgrep -a pppd
# kill -TERM PPPD_PID
$ ip route show default
$ ip -brief address show | grep '^ppp' || true

If you used persist, pppd will try to reopen the connection after termination, so stop it deliberately and remove persist from the profile before retrying. If defaultroute was used, verify that the temporary route disappeared. If a DNS management workflow consumed /etc/ppp/resolv.conf, restore the resolver arrangement expected by this host rather than deleting a file used by another service.

Keep the peer file and secrets file for the next approved connection, but remove temporary debug, nodetach and verbose chat settings. Those options are for diagnosis, not a permanent production profile.