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).showonly 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/
| File | Contents |
|---|---|
rradius.toml | TACACS+ only, no [radius] |
tacacs.lua | Authorization (by role) and accounting (recording commands) |
migrations/1_schema.sql | admins (accounts, roles), tacacs_log |
migrations/2_demo_data.sql | netadmin1 and noc1, with bcrypt passwords |
Who handles what
| Request | Handled 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
| Request | netadmin1 | noc1 |
|---|---|---|
Start a shell (empty cmd=) | Pass, priv-lvl=15 | Pass, priv-lvl=1 |
show interfaces | Pass | Pass |
show running-config | Pass | Fail |
configure terminal | Pass | Fail |
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,protocoland so on. For repeated arguments useget_attrs;get_attrs('cmd-arg'), for example, gives every argument of the command. - Attributes added with
set_attrgo back to the device asname=value(PASS_ADD). - Accounting is keyed on
task_idplus the event (start_timeandstop_timesay whether it is a start or a stop), written withINSERT OR IGNORE, so a retransmission from the device still leaves one row. The command and its arguments are put back together into one line incmd, such asshow 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
denybefore a broaderpermit. When no rule holds, the request is refused. cmd\*is thecmd*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_groupset do not run the authorization part of the script. Authentication and accounting are unchanged, so the accounting records oftacacs.luastill 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
localas 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 frompriv-lvlin the authorization reply, so administrators usually do not need enable. - Set
enable = "login"in[tacacs], and have the device useaaa authentication enable default group RRADIUS enable. Administrators then enable with their own password, so limit it in the script, for example letting only thenetadminrole pass whenauthen_service == 2.
- Keep the device’s local enable password (
- With several rradius servers, list several
server namelines underaaa group server; the device tries them in order.
Before going live
- Port 49: use systemd’s
AmbientCapabilities=CAP_NET_BIND_SERVICE, or give the binarysetcap 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_logkeeps growing, and rradius does not clean it up. For removing old data, see chapter 19.
Common problems
| Symptom | Cause |
|---|---|
| The connection is closed at once | The source is not in [[tacacs.clients]]; the log shows TACACS+ connection from unknown client |
| Authentication answers ERROR, then the connection is closed | The 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 fails | Enable is refused by default; the log shows TACACS+ enable request refused. See “Device configuration” above |
| Login works but every command is refused | The 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 ERROR | The script failed; look for Lua script error. The device retransmits |