Scenario: the TACACS+ of chapter 6 obfuscates packet contents with the shared secret, which uses only MD5 and cannot stop someone who can capture traffic on the management network: administrators’ passwords and every command they ran can be decoded. Newer devices support TACACS+ over TLS (RFC 9887): the whole connection goes inside TLS 1.3, and devices and the server verify each other by certificate.
Devices are not all replaced in a day, so there is a period where both run side by side:
- Core routers already support it: they move to the TLS port, each with its own certificate.
- Access switches still have old firmware: they keep using the shared secret port.
- Once everything has moved, the port without TLS is closed.
This chapter reuses the accounts, roles and command records of chapter 6, and covers only TLS and the migration.
Example directory: rradius-server/examples/scenarios/device-admin-tls/
| File | Contents |
|---|---|
rradius.toml | [tacacs] plus [tacacs.tls], two kinds of client, one authorization group |
make-certs.sh | Creates a demo device CA, a server certificate and three device certificates |
core.secret, access.secret | Shared secrets for the two groups of devices |
The script and tables are chapter 6’s ../device-admin/tacacs.lua and ../device-admin/migrations/, so the two directories must be kept together.
Two ports
| Port without TLS | TLS port | |
|---|---|---|
| Setting | [tacacs] port, 49 by default | [tacacs.tls] port, 300 by default |
| Protection | Obfuscation with the shared secret (MD5) | TLS 1.3, and devices must present a certificate |
| How devices are recognised | Source address | Source address, plus certificate |
| Shared secret | Must match the device | Not used (still required in the configuration) |
Once connected, authentication, authorization and accounting are handled exactly the same way: the same chains, scripts and authorization groups.
Steps
1. Create the certificates
cd rradius-server/examples/scenarios/device-admin-tls
./make-certs.sh
certs/ then holds ca.pem, the server’s server.pem/server.key (name tacacs.mgmt.example.net), and three device certificates: core-rtr-1, core-rtr-2 and spare. For testing only.
2. Start
49 and 300 are both below 1024, which ordinary accounts cannot bind. For local testing, change them to 4949 and 4300 first; for production, see “Before going live” in chapter 6. For local testing, change the address of core-rtr-1 to 127.0.0.1.
cd ../../..
./target/release/rradius-server --config examples/scenarios/device-admin-tls/rradius.toml
The log has two lines, TACACS+ Server listening on ... and TACACS+ over TLS listening on ....
3. Check the handshake
cd examples/scenarios/device-admin-tls
openssl s_client -connect 127.0.0.1:4300 -tls1_3 -servername tacacs.mgmt.example.net \
-CAfile certs/ca.pem -cert certs/core-rtr-1.pem -key certs/core-rtr-1.key
Verify return code: 0 (ok) means the certificate part works. openssl can only check the handshake; logins and authorization have to come from a device that supports RFC 9887. The automated test plays the device in code and checks the following:
| Situation | Result |
|---|---|
core-rtr-1’s certificate, from its address: netadmin1 logs in | PASS |
| Same connection: wrong password | FAIL |
| Same connection: netadmin1 starts a shell | PASS, priv-lvl=15 (decided by the script from the role) |
Same connection: noc1 runs configure terminal | FAIL |
| A packet not marked “unobfuscated” | ERROR, connection closed |
core-rtr-2’s certificate, from core-rtr-1’s address | Closed after the handshake: the certificate is not valid for this device’s tls_name |
A certificate belonging to no device (spare) | Closed after the handshake |
| A client that only speaks TLS 1.2 | Handshake fails |
core-rtr-1 connecting to the port without TLS instead | Connection closed: a device with tls_name set can only use TLS |
| Access switch with the shared secret: starts a shell | PASS, priv-lvl=1 (the authorization group’s rule) |
Access switch: show running-config | FAIL |
The configuration explained
[tacacs]
port = 49
enable = "deny"
[tacacs.tls]
port = 300
cert_file = "certs/server.pem"
key_file = "certs/server.key"
client_ca_file = "certs/ca.pem"
tls_only = false
client_ca_fileis the CA that issues device certificates. Only it is trusted, not the system’s root certificates. Use a CA dedicated to network devices: if this CA also signs certificates for other purposes, those could be used to impersonate devices (seetls_namebelow).- TLS 1.3 only, and devices must have a certificate. A device with no certificate, the wrong certificate, or only TLS 1.2 fails the handshake.
- The address comes from
[tacacs] bind; both ports bind the same address. The connection limit and idle timeout are shared too.
Binding certificates to devices with tls_name
[[tacacs.clients]]
name = "core-rtr-1"
address = "10.50.0.1"
tls_name = "core-rtr-1.mgmt.example.net"
secret_file = "core.secret"
[[tacacs.clients]]
name = "access-switches"
address = "10.60.0.0/22"
secret_file = "access.secret"
authorize_group = "readonly"
A device is always first matched to its [[tacacs.clients]] entry by source address, and connections from sources not on the list are closed before the handshake. Then tls_name is looked at:
| Client setting | TLS port | Port without TLS |
|---|---|---|
Single address, no tls_name | Yes. Any certificate from the CA can connect from this address | Yes |
Single address, with tls_name | Yes; the certificate must be valid for this name | No |
Range, no tls_name | No; closed after the handshake, logging needs tls_name | Yes |
Range, with tls_name | Yes; the certificate must be valid for this name (a wildcard certificate can be used) | No |
tls_nameis matched against the DNS names in the certificate’s SAN.- Setting
tls_namedeclares “this device has moved”: it can no longer use the port without TLS. Even someone who has the old shared secret and spoofs its address cannot get in. secretis still required; the TLS port does not use it.
Authorization is unchanged
The example’s core routers do not set authorize_group, so authorization goes to chapter 6’s script and is decided by the user’s role. The access switches set authorize_group = "readonly", so rules decide, regardless of user: even netadmin1 gets only priv-lvl=1 on the access switches. For the difference between the two, see chapter 6.
The order of the migration
Prepare the CA and certificates. One per device, named with its management host name. The server certificate’s name must be the name filled in on the devices.
Add
[tacacs.tls]and restart. Adding this section needs a restart; SIGHUP alone is not enough. At this point every device still uses port 49, with no effect at all.Move devices one at a time:
- Install the certificate and the CA on the device, and configure it to reach rradius over TLS.
- Confirm it connects (see “Which port each device uses” below).
- Add
tls_nameto its[[tacacs.clients]]and send SIGHUP. From then on it can only use TLS.
Step 3 comes after step 2. Adding
tls_namefirst means the device is refused on port 49 before its TLS is set up; that is when the device’s local emergency account earns its keep.Devices that were covered by one range (
access-switchesin the example): as they move, give each moved device its own single-address entry (longest prefix wins, overriding the range), withtls_name.Once everything has moved, set
tls_only = trueand send SIGHUP. The port without TLS stops serving at once: new connections, and open connections at their next packet, are closed, loggingtls_only takes TACACS+ over TLS only. After the next restart, that port is not opened at all. Changing back fromtruetofalseneeds a restart.
RFC 9887 recommends keeping the period where both run side by side as short as possible.
Which port each device uses
- The authentication log has one line per login, with the device’s name as
client. Setting[log] leveltodebugshows every TACACS+ connection. - Try tightening: add
tls_nameto a device that has moved. If it is in fact still using port 49, its next request fails, the device falls back to its local accounts, and you notice at once. rradius_tacacs_connections_totaldoes not distinguish ports; connections on both are counted together.
Revoking and renewing certificates
- Revocation lists: set
crl_file, with one for every CA in the chain. Send SIGHUP after updating. - OCSP: set
ocsp = "soft"or"hard", the same way as in chapter 15. - Open connections are checked again: once more than 60 seconds have passed since the last check, the certificate is checked again (CA, revocation list, expiry,
tls_name) before the next packet is handled. A connection that fails is closed. An idle connection is checked only when it sends its next packet. - Replace the server certificate before it expires and send SIGHUP: new connections use the new one, and open ones are unaffected.
- When a device’s certificate expires, that device cannot log in, and only its local accounts work. Monitor certificate expiry dates.
Before going live
- Devices must keep a local emergency account, as in chapter 6. An expired certificate, a changed CA or a wrong clock all stop TLS from connecting.
- Device clocks must be right. Certificates have start and expiry times, and a clock that is far off fails the handshake. This is especially likely when logging in after a device reboot, before it has synchronised its clock.
- Firewall: open port 300 to the devices’ management range. Close 49 when the migration is over.
- No session resumption. Every connection does a full handshake and certificate check; devices that keep a long-lived connection (single-connection) need fewer handshakes.
- Not yet tested on real devices, only with a program (a rustls client). RFC 9887 was published in December 2025; check with vendors first which devices and versions support it. Device configuration commands differ by vendor, and this chapter does not include them.
- The other items of chapter 6’s “Before going live” (permissions for port 49, keeping records) still apply.
Common problems
| Symptom | Cause |
|---|---|
Startup fails, mentioning the certificates of tacacs.tls | make-certs.sh has not been run, or the private key does not match the certificate |
Startup fails, mentioning tls_name | tls_name is set but there is no [tacacs.tls], or that client has no address |
| A device connecting to port 300 fails the handshake | The device presented no certificate, the certificate is not signed by client_ca_file, it is revoked or expired, or the device only speaks TLS 1.2 |
The handshake succeeds but the connection drops at once, with needs tls_name in the log | This device’s client is a range without tls_name. Give it its own entry with tls_name |
| The handshake succeeds but the connection drops at once | The certificate is not valid for this client’s tls_name: the wrong certificate is installed, or the name is not among the DNS names in the SAN |
After adding tls_name, that device cannot log in | It is still using port 49. Move the device to TLS first |
| Every request gets ERROR and the connection drops | The device still sends obfuscated packets over TLS (not marked unobfuscated). The device’s TLS mode is not set correctly |
After setting tls_only = true, no old device can log in | Some devices have not moved yet. Change it back to false and restart |