6. Network Device Administration (TACACS+)

Scenario: network administrators log in to routers and switches over SSH.

  • Accounts are managed centrally, instead of a set of local accounts on every device.
  • The netadmin role: privilege level 15, every command allowed.
  • The noc role: privilege level 1, look only (show, ping, traceroute). show only takes the items the script lists (interfaces, version, VLANs, routes and the like), not the configuration, because it contains passwords.
  • Every command is recorded: who, from where, on which device, what they ran.

TACACS+ separates authentication, authorization and accounting into three kinds of request, and a device can ask “is this allowed” for every command. That is what makes it better suited than RADIUS for device administration.

Example directory: rradius-server/examples/scenarios/device-admin/

FileContents
rradius.tomlTACACS+ only, no [radius]
tacacs.luaAuthorization (by role) and accounting (recording commands)
migrations/1_schema.sqladmins (accounts, roles), tacacs_log
migrations/2_demo_data.sqlnetadmin1 and noc1, with bcrypt passwords

Who handles what

RequestHandled by
Authentication (user name and password)The sql handler in [auth]: bcrypt hashes in the admins table
Authorization (starting a shell, each command)tacacs.lua, with phase "authorization"
Accounting (login, logout, command records)tacacs.lua, with phase "accounting", written to tacacs_log

This scenario authorizes by the user’s role, so it goes to the top-level script, which does the main work. When authorization depends only on the device, you can skip the script and use “authorization groups” below.

Steps

1. Start

TACACS+ uses port 49, and ordinary accounts cannot bind ports below 1024. For local testing, change [tacacs] port to 4949 first; for production, see “Before going live” below. The example client is 10.50.0.0/24; for local testing, change it to 127.0.0.1.

cd rradius-server
./target/release/rradius-server --config examples/scenarios/device-admin/rradius.toml

2. Test with tacacs_client

tacacs_client is the command that comes with the Python package tacacs_plus (pip install tacacs_plus). Its options may differ slightly between versions; tacacs_client --help is authoritative:

K=tacacs-shared-secret-change-me
tacacs_client -H 127.0.0.1 -p 4949 -k $K -u noc1 authenticate          # type noc1-password
tacacs_client -H 127.0.0.1 -p 4949 -k $K -u noc1 authorize -c service=shell cmd=
tacacs_client -H 127.0.0.1 -p 4949 -k $K -u noc1 authorize -c service=shell cmd=show cmd-arg=running-config
Requestnetadmin1noc1
Start a shell (empty cmd=)Pass, priv-lvl=15Pass, priv-lvl=1
show interfacesPassPass
show running-configPassFail
configure terminalPassFail

The script explained

local cmd = get_attr('cmd')
-- No cmd: starting a shell (EXEC authorization); reply with the privilege level.
if not cmd or cmd == '' then
  set_attr('priv-lvl', role == 'netadmin' and 15 or 1)
  return 'accept'
end
  • The arguments of an authorization request can all be read with get_attr: service, cmd, protocol and so on. For repeated arguments use get_attrs; get_attrs('cmd-arg'), for example, gives every argument of the command.
  • Attributes added with set_attr go back to the device as name=value (PASS_ADD).
  • Accounting is keyed on task_id plus the event (start_time and stop_time say whether it is a start or a stop), written with INSERT OR IGNORE, so a retransmission from the device still leaves one row. The command and its arguments are put back together into one line in cmd, such as show interfaces.
  • Once an account is disabled (enabled = 0), authentication and authorization both reject it, and a session that is already logged in is stopped at its next command.

Without a script: authorization groups

When authorization depends only on the device, not on the user, you can write rules in the configuration file instead of the authorization part of the script. For example, only network administrators can log in to core routers, and always get privilege level 15; access switches are for the on-call staff, who can only look:

[tacacs.authorize_groups]
core = [
  'permit service=shell cmd\* {priv-lvl=15}',
  'permit service=shell cmd=.*',
]
access = [
  'permit service=shell cmd\* {priv-lvl=1}',
  'deny cmd=show cmd-arg=(running-config|startup-config)',
  'permit service=shell cmd=(show|ping|traceroute|exit|terminal)',
]

[[tacacs.clients]]
name = "core-routers"
address = "10.50.0.0/24"
secret_file = "tacacs.secret"
authorize_group = "core"

[[tacacs.clients]]
name = "access-switches"
address = "10.60.0.0/22"
secret_file = "tacacs.secret"
authorize_group = "access"
  • Rules are matched in order, and the first that holds decides; put deny before a broader permit. When no rule holds, the request is refused.
  • cmd\* is the cmd* a device sends when asking to start a shell, and {priv-lvl=15} goes back to the device as the privilege level.
  • Always use single quotes; double-quoted strings do not accept \*.
  • Devices with authorize_group set do not run the authorization part of the script. Authentication and accounting are unchanged, so the accounting records of tacacs.lua still work.
  • Rules do not distinguish users: in the example above, everyone who can log in to the access switches can only look. To distinguish by role as earlier in this chapter, keep using the script.
  • The full description of the format and its checks is in usage section 2.3.

Device configuration

Using Cisco IOS as an example (not yet tested on real devices; commands may differ between versions, so confirm on a lab device before going live):

aaa new-model
tacacs server rradius-1
 address ipv4 10.50.0.100
 key tacacs-shared-secret-change-me
aaa group server tacacs+ RRADIUS
 server name rradius-1
!
aaa authentication login default group RRADIUS local
aaa authorization exec default group RRADIUS local
aaa authorization commands 1 default group RRADIUS local
aaa authorization commands 15 default group RRADIUS local
aaa accounting exec default start-stop group RRADIUS
aaa accounting commands 1 default stop-only group RRADIUS
aaa accounting commands 15 default stop-only group RRADIUS
  • Always keep local as a fallback, and before configuring, make sure the local emergency account can log in. When rradius is down or unreachable, the device uses its local accounts; without a fallback you lock yourself out.
  • Turn on authentication first, and turn on command authorization only once that works. A mistake can refuse even exit.
  • Do not hand enable to rradius unless you set enable = "login". By default rradius refuses enable requests (it answers FAIL), and a device that gets FAIL does not fall back to its local enable password. Two ways to handle this:
    • Keep the device’s local enable password (aaa authentication enable default enable). The configuration above does not hand enable to rradius; the privilege level comes from priv-lvl in the authorization reply, so administrators usually do not need enable.
    • Set enable = "login" in [tacacs], and have the device use aaa authentication enable default group RRADIUS enable. Administrators then enable with their own password, so limit it in the script, for example letting only the netadmin role pass when authen_service == 2.
  • With several rradius servers, list several server name lines under aaa group server; the device tries them in order.

Before going live

  • Port 49: use systemd’s AmbientCapabilities=CAP_NET_BIND_SERVICE, or give the binary setcap cap_net_bind_service=+ep. Do not run it as root.
  • TACACS+ encryption is weak: the obfuscation of RFC 8907 uses only MD5 and the shared secret, and is no substitute for real encryption. Keep traffic between devices and rradius on the management network, with long shared secrets (fewer than 16 characters gives a warning at startup) that differ per device (several [[tacacs.clients]] can be used). When devices support TACACS+ over TLS (RFC 9887), use TLS instead; see chapter 16.
  • ASCII login (the device asks for the user name, then the password) and PAP are both supported. Enable is refused by default, and password changes always get FAIL; see usage section 4.6.
  • CHAP and MS-CHAPv2 (used only by devices that dial in over PPP) are checked by the authentication chain, so the account’s password must be in a form the server can read: plain text for CHAP, plain text or {nthash} for MS-CHAPv2. The example accounts are stored as bcrypt, so these two kinds of login are rejected; ordinary SSH logins (PAP, ASCII) are unaffected. Devices without a chain get RESTART and can switch to PAP.
  • Messages for the user: text set by the script with set_attr('server_msg', '...') goes into the reply, and devices usually show it to the person logging in, for example to explain why a command was refused. Authorization group rules cannot carry a message.
  • Idle connections are closed after 300 seconds without a complete packet (idle_timeout_ms), and each connection allows at most 8 unfinished logins.
  • Keeping records: tacacs_log keeps growing, and rradius does not clean it up. For removing old data, see chapter 19.

Common problems

SymptomCause
The connection is closed at onceThe source is not in [[tacacs.clients]]; the log shows TACACS+ connection from unknown client
Authentication answers ERROR, then the connection is closedThe shared secret differs, so the decoded contents are garbage. The log shows a body did not decode, so the shared secret may be wrong, and rradius_tacacs_malformed_total increases
The enable command always failsEnable is refused by default; the log shows TACACS+ enable request refused. See “Device configuration” above
Login works but every command is refusedThe authorization script refuses: the account has no role, service is not shell, or cmd is not on the allowed list. With authorization groups, no rule held
Accounting answers ERRORThe script failed; look for Lua script error. The device retransmits
Built with Hugo
Theme Stack designed by Jimmy