Set Up pppd RADIUS Authentication with the radius.so Plugin

You will configure a PPP peer so that pppd sends PAP, CHAP, MS-CHAP or MS-CHAPv2 authentication to a RADIUS server through radius.so, instead of checking the local PPP secrets files. This guide targets the Ubuntu package ppp version 2.4.9-1+1.1ubuntu4, which installs the plugin under /usr/lib/pppd/2.4.9/.

Allow about 20 minutes if the RADIUS service and PPP transport already exist. You need root access, a reachable RADIUS server, its shared secret, a working PPP transport, and permission to edit the RADIUS client configuration. The example values are deliberately fictional. Replace every value marked CHANGE_ME before using it.

1. Check the installed plugin and version

Start with read-only checks. The plugin option is privileged, so the final daemon invocation will need an appropriate elevated service context. Do not assume that a plugin built for a different pppd version will load safely.

$ dpkg-query -W -f='${Package} ${Version}\n' ppp
ppp 2.4.9-1+1.1ubuntu4
$ ls -l /usr/lib/pppd/2.4.9/radius.so
-rw-r--r-- 1 root root ... /usr/lib/pppd/2.4.9/radius.so

On this package, plugin radius.so is enough for pppd to search its versioned plugin directory. An absolute plugin path is possible, but the short form keeps the configuration tied to the running pppd version lookup.

2. Check the RADIUS client configuration

The plugin delegates its server and client settings to the radiusclient library. Unless you specify another file, it reads /etc/radiusclient/radiusclient.conf. That directory normally also contains the server definitions and shared secrets used by the library.

$ sudo ls -l /etc/radiusclient/radiusclient.conf /etc/radiusclient/servers
$ sudo sed -n '1,160p' /etc/radiusclient/radiusclient.conf
$ sudo sed -n '1,80p' /etc/radiusclient/servers

Read the installed library's documentation before changing these files, because the exact server-file syntax is not defined by pppd-radius(8). The shared secret is security-sensitive. Keep it owned by root, restrict its mode to the users that must run the PPP service, and never paste it into a support ticket or a shell command.

If your deployment uses a separate client configuration, keep it in a root-owned location and pass its path explicitly. This avoids silently editing the default used by another PPP service:

$ sudo install -o root -g root -m 0640 /path/to/radiusclient.conf /etc/ppp/radiusclient-office.conf

That command changes state. To undo this particular example, remove the copied file after confirming that no service refers to it:

$ sudo rm /etc/ppp/radiusclient-office.conf

3. Build a peer options file

Put the PPP options in a named peer file so that the service can load a repeatable configuration. The file below shows the plugin, an explicit RADIUS configuration path, and the default interface-name mapping for the RADIUS NAS-Port attribute.

$ sudo install -o root -g root -m 0644 /dev/null /etc/ppp/peers/radius-office
$ sudoedit /etc/ppp/peers/radius-office

plugin radius.so
radius-config-file /etc/ppp/radiusclient-office.conf
map-to-ifname

Use map-to-ifname when the RADIUS server expects NAS-Port to be derived from the PPP interface name. The plugin documents this as the default. Use map-to-ttyname instead only when your RADIUS policy expects the value supplied by the libradiusclient library.

Do not add login or local pap-secrets entries as a second authentication scheme and then assume both systems will be consulted. With this plugin, the normal local PPP authentication schemes are skipped. The identity and password still come from the peer's negotiated PPP authentication exchange; the RADIUS server validates them.

4. Select optional request attributes

Use avpair for an Attribute-Value pair that must be included in each RADIUS request. Confirm the attribute name and value with the RADIUS server policy first. A policy-specific example looks like this:

plugin radius.so
radius-config-file /etc/ppp/radiusclient-office.conf
avpair NAS-Identifier=ppp-gateway-01

This is not a universal requirement. An unknown attribute, a value in the wrong format, or a value that disagrees with the server policy can make an otherwise valid login fail. Add one pair at a time and retain a copy of the last known-good peer file.

5. Start one controlled test

Run the peer through the same service or privileged wrapper that normally owns the PPP device. The plugin option itself is privileged, and the plugin option in pppd(8) is also marked privileged. A generic manual invocation therefore needs a real transport option from your environment; do not copy this as a complete dial-up command.

$ sudo pppd call radius-office

Supply the serial, modem, tunnel or other transport settings required by your deployment through the peer file or service. On success, the PPP link comes up and the peer address should be supplied by the RADIUS server's Framed-IP-Address attribute. The plugin's man page identifies that attribute as the expected way for RADIUS to assign the peer address.

Check the daemon and network logs from a separate terminal while testing:

$ sudo journalctl -b --no-pager | rg 'pppd|radius|PPP'
$ ip -brief address show | rg '^ppp'

Do not enable packet debugging casually. PPP debug output can expose authentication details and other network data in system logs. If you must increase logging, limit the test window, protect the logs, and remove the extra setting afterwards.

6. Diagnose the usual failures

• Plugin not found: check that radius.so exists in the directory matching the installed pppd version. A stale absolute path or a plugin from another package version is a common cause.
• Configuration not found: check the spelling and permissions of radius-config-file. If the option is absent, inspect the default /etc/radiusclient/radiusclient.conf instead.
• Authentication rejected: verify the username, negotiated authentication protocol, RADIUS client address, shared secret, and server policy. Do not fall back to local secrets without deciding that the change is acceptable.
• Timeouts: test routing and firewall access to the configured RADIUS server, then check that the server recognises this PPP host as a client. A timeout is not evidence of a bad password.
• Unexpected port policy: compare the server's expected NAS-Port representation with map-to-ifname and map-to-ttyname. Change only the mapping that matches the server's documented policy.

If the test breaks an existing service, stop the new PPP attempt, restore the previous peer file from your backup, and restart only the affected service. Do not delete shared RADIUS configuration while another PPP instance may still use it.