Configure and Debug a Serial PPP Link with pppd

You will finish with a repeatable pppd peer configuration for a serial PPP connection, a dry option check, 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 and the local pppd(8) behaviour.

Allow about 20 minutes for the configuration and a further 10 minutes 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. This guide does not invent a telephone number, username, password, device name or IP address: replace each marked value with one supplied by your network administrator.

1. Check the installed daemon

Start with read-only checks. These commands do not start PPP and do not 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 command-line options. The relevant files are /etc/ppp/options, the user's ~/.ppprc, and a device-specific /etc/ppp/options.ttyname. A peer file loaded with call NAME is read from /etc/ppp/peers/NAME and may contain privileged options.

Checkpoint: record the exact serial device, its speed, the peer's authentication method, and whether this connection should install a default route. Treat an unknown answer as a configuration blocker, not as a value to guess.

2. Create a peer profile

Use an administrator-owned peer file so the connection can be started with a short, auditable command. The following example 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 an options file, so each line is an option and its argument where required. crtscts enables RTS/CTS hardware flow control. defaultroute adds a default route only after 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; it also makes DNS1 and DNS2 available to ip-up.

noipdefault prevents pppd from choosing the first local address as its default local IP address. In simple client links the peer normally supplies addresses. If your provider gives fixed addresses, use an explicit local:remote IP option instead, after confirming the values.

Do not blindly add noauth. It is privileged and disables the requirement for the peer to authenticate itself. Keep the default authentication policy unless the peer is trusted and the link design explicitly requires otherwise.

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.

Checkpoint: verify the permissions without printing the secret:

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

4. Validate options before connecting

Use dump with dryrun to make pppd parse the configuration and print its resolved options, then exit. This is the safest useful test, but 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

Enable debug only during a controlled test. It logs PPP control packets, including authentication exchanges, through syslog. Packet logs can contain sensitive operational detail, so remove the option after the test and protect the logs.

# 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 correct process. A normal SIGTERM closes the link and restores serial settings:

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

Do not kill a guessed PID. 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.