This documentation is for an older version of the software. If you are using the current version of Cumulus Linux, this content may not be up to date. The current version of the documentation is available here. If you are redirected to the main page of the user guide, then this page may have been renamed; please search for it there.


Cumulus Linux implements TACACS+ client AAA (Accounting, Authentication, and Authorization) in a transparent way with minimal configuration. The client implements the TACACS+ protocol as described in this IETF document. There is no need to create accounts or directories on the switch. Accounting records are sent to all configuredTACACS+ servers by default. Use of per-command authorization requires additional setup on the switch.

Supported Features

  • Authentication via PAM; includes login, ssh, sudo and su

  • Runs over the eth0 management interface

  • Ability to run in the management VRF

  • TACACS+ privilege 15 users can run any command with sudo via the /etc/sudoers.d/tacplus file that is installed by the libtacplus-map1 package

  • Up to 7 TACACS+ servers

Installing the TACACS+ Client Packages

TACACS+ requires the following packages to be installed on Cumulus Linux. They are not part of the base Cumulus Linux image installation. All required packages can be installed easily with these commands:

cumulus@switch:~$ sudo -E apt-get update
cumulus@switch:~$ sudo -E apt-get install tacplus-client

Configuring the TACACS+ Client

Post-installation TACACS+ configuration requires (at minimum) editting only one file, /etc/tacplus_servers. It is necessary add at least one server, and usually one shared secret (key). The server and secret parameters can be given in any order, and must not include any whitespace (spaces or tabs), and can be added anywhere in the file. For example, if your TACACS+ server IP address is, and your shared secret is tacacskey then you would add these parameters to/etc/tacplus_servers:


Up to 7 TACACS+ servers are supported. Connections are made in the order in which they are listed in this file. In most cases, no other parameters need to be changed. All parameters used by any of the packages can be added to this file, and will affect all the TACACS+ client software. It is also possible to configure some of the packages through individual configuration files. For example, the timeout value (see description below) is set to 5 seconds by default for NSS lookups in /etc/tacplus_nss.conf, while other packages use a value of 10 seconds, set in /etc/tacplus_servers.

When TACACS+ servers or secrets are added or removed, auditd must be restarted (with systemctl restart auditd) or a signal must be sent (with killall -HUP audisp-tacplus) before audisp-tacplus will reread the configuration to see the changed server list. Usually this is an issue only at first change to the configuration.

At this point, the Cumulus Linux switch should be able to query the TACACS server.

This is the complete list of the TACACS+ client configuration files, and their use. The full list of TACACS+ parameters is below at TACACS Parameters below.

/etc/tacplus_serversThis is the primary file that requires configuration post-installation, and is used by all packages via
include=/etc/tacplus_servers parameters in the other configuration files, when installed. Since this is usually the file with the shared secrets, it should not be world readable (should be Linux file mode 600).
/etc/nsswitch.confWhen the libnss_tacplus package is installed, this file is configured to enable tacplus lookups via libnss_tacplus. If this file is replaced by automation or other means, you will need to add tacplus as the first lookup method for the passwd database line.
/etc/tacplus_nss.confThis file sets the basic parameters for libnss_tacplus. It includes a debug variable for debugging NSS lookups separately from other client packages.
/usr/share/pam-configs/tacplusConfiguration file for pam-auth-update to generate the files in the next row. These configurations are used at login, by su, and by ssh.
/etc/pam.d/common-*The /etc/pam.d/common-* files are updated for tacplus authentication. The files are updated with pam-auth-update, when libpam-tacplus is installed or removed.
/etc/sudoers.d/tacplusThis file allows TACACS+ privilege level 15 users to run commands with sudo. It also includes an example (commented out) showing how to enable privilege level 15 TACACS users to use sudo without having to enter a password, and an example of how to enable all TACACS users to run specific commands via sudo. It should only be editted with the command: visudo -f /etc/sudoers.d/tacplus
audisp-tacplus.confaudisp plugin configuration file. In general, no modifications are required.
/etc/audisp/audisp-tac_plus.confTACACS+ server configuration file for accounting. In general, no modifications are required. It may be useful to use this configuration file when you only want to debug TACACS+ accounting issues, not all TACACS+ users.
/etc/audit/rules.d/audisp-tacplus.rulesThe auditd rules for TACACS+ accounting. The augenrules command uses all rules files to generate the file rules file (below)
/etc/audit/audit.rulesAudit rules file generated during auditd installation.

The /etc/pam.d/common-* files can be edited manually. However, if pam-auth-update is run again after the changes are made, the update will fail. Configuration should be done in /usr/share/pam-configs/tacplus instead, followed by running pam-auth-update.

TACACS+ Authentication (login)

The initial authentication configuration is done through the PAM modules, and an updated version of the libpam-tacplus package. When the package is installed, the PAM configuration is updated in /etc/pam.d with the pam-auth-update command. If you have made changes to your PAM configuration, you may need to integrate these changes yourself. If you are also using LDAP with the libpam-ldappackage, you will need to edit the PAM configuration to ensure the LDAP and TACACS ordering that you prefer. The libpam-tacplus are configured to skip over rules, and the values in the success=2 may require adjustments to skip over LDAP rules.

The user’s privilege level is determined by the TACACS+ privilege attribute priv_lvl for the user that is returned by the TACACS+ server during the user authorization exchange. The client accepts the attribute in either the mandatory or optional forms and also accepts priv-lvl as the attribute name. The attribute value must be a numeric string in the range 0 to 15, with 15 the most privileged level.

TACACS+ users at privilege levels other than 15 are not allowed to run sudo commands by default, and are limited to commands that can be run with standard Linux user permissions.

TACACS+ Accounting

TACACS+ accounting is implemented with the audisp module, with an additional plugin for auditd/audisp. The plugin maps the auid in the accounting record to a TACACS login, based on the auid and sessionid. The audisp module requires libnss_tacplus, and uses the library interfaces as part of the modified lipam_tacplus package.

Communication with the TACACS+ servers is done via the libsimple-tacact1 library, through dlopen(). A maximum of 240 bytes of command name and arguments are sent in the accounting record, due to the TACACS+ field length limitation of 255 bytes.

All Linux commands result in an accounting record, including commands run as part of the login process or as a sub-processes of other commands. This can sometimes generate a large number of accounting records.

The IP address and encryption key of the server should be configured in the /etc/tacplus_servers file. Minimal configuration to auditd and audisp is necessary to enable the audit records necessary for accounting. These records are installed as part of the package.

audisp-tacplus installs the audit rules for command accounting. Modifying the configuration files is not usually necessary. However, when a management VRF is configured, the accounting configuration does need special modification, because the auditd service starts prior to networking. It is necessary add the vrf parameter, and to signal the audisp-tacplus process to reread the configuration. The example below shows that the management VRF is named mgmt. The vrf parameter can be placed in either /etc/tacplus_servers or in /etc/audisp/audisp-tac_plus.conf.


After editing the configuration file, notify the accounting process to reread it by sending the HUP signal: killall -HUP audisp-tacplus.

All sudo commands run by TACACS+ users generate accounting records against the original TACACS+ login name.

For more information, refer to the audisp.8 and auditd.8 man pages.

Configuring NCLU for TACACS+ Users

NCLU has its own configuration file to enable TACACS+ privilege level 0 users to run the net command. Edit the /etc/netd.conf file, then:

  • To give a TACACS+ user access to the show commands, add that user to the users_with_show line, then add the tacacs group to the groups_with_show line.

  • To give a TACACS+ user access to the edit commands (for all the NCLU write commands and to restart services with NCLU), add that user to the users_with_edit line.

    cumulus@switch:~$ sudo nano /etc/netd.conf
    # Control which users/groups are allowed to run 'add', 'del',
    # 'clear', 'net abort', 'net commit' and restart services
    # to apply those changes
    users_with_edit = root, cumulus, TACACS_USER
    groups_with_edit = netedit
    # Control which users/groups are allowed to run 'show' commands
    users_with_show = root, cumulus, TACACS_USER
    groups_with_show = netshow, tacacs

TACACS_USER in the above output is actually the username of the account logged in via TACACS.

Do not add the tacacs group to the groups_with_edit line, as this is dangerous and can potentially enable any user to log into the switch as the root user.

TACACS+ Per-command Authorization

Per-command authorization is handled with the tacplus-auth command. To make this an enforced authorization, the TACACS+ login must be changed to use a restricted shell, with a very limited executable search path. Otherwise, the user can bypass the authorization. The tacplus-restrict utility simplifies the setup of the restricted environment. The example below initializes the environment for the tacacs0 user account. This is the account used for TACACS+ users at privilege level 0.

tacuser0@switch:~$ sudo tacplus-restrict -i -u tacacs0 -a command1 command2 ... commandN

If the user/command combination is not authorized by the TACACS+ server, a message similar to the following gets displayed:

tacuser0@switch:~$ net show version
net not authorized by TACACS+ with given arguments, not executing

Command Options




Initializes the environment. It only needs to be issued once per username.


The utility can be invoked with the -a option as many times as desired. For each command in the -a list, a symbolic link is created from tacplus-auth to the relative portion of the command name in the local bin subdirectory. These commands also need to be enabled on the TACACS+ server. See the server documentation for how to do that. It is common to have the server allow some options to a command, but not others.


Re-initializes the environment. If you need to start over, issue the -f option with the -i to force the re-initialization; otherwise, repeated use of -i is ignored. As part of the initialization:

  • The user's shell is changed to /bin/rbash.

  • Any existing dot files are saved.

  • A limited environment is set up that does not allow general command execution, but instead allows only commands from the user's local bin subdirectory.

As a full example, if you want to allow the user to be able to run the net and ip commands (potentially, if the TACACS+ server authorizes), use the command:

cumulus@switch:~$ sudo tacplus-restrict -i -u tacacs0 -a ip net

After running this command, examining the tacacs0 directory should show something similar to the following:

cumulus@switch:~$ sudo ls -lR ~tacacs0
total 12
lrwxrwxrwx 1 root root 22 Nov 21 22:07 ip -> /usr/sbin/tacplus-auth
lrwxrwxrwx 1 root root 22 Nov 21 22:07 net -> /usr/sbin/tacplus-auth

Other than shell built-ins, the only two commands the privilege level 0 TACACS users can run are the ip and net commands.

If you mistakenly add potential commands with the -a option, you can remove the commands that you don’t want (the example below shows the net command):

cumulus@switch:~$ sudo rm ~tacacs0/bin/net

Or you can remove all the commands with:

cumulus@switch:~$ sudo rm ~tacacs0/bin/*

Use the man command on the switch for more information on tacplus-auth and tacplus-restrict.

cumulus@switch:~$ man tacplus-auth tacplus-restrict

NSS Plugin

When used with pam_tacplus, TACACS+ authenticated users are able to log in without a local account on the system via the NSS plugin that comes with the tacplus_nss package. The plugin uses the mapped tacplus information if the user is not found in the local password file, provides the getpwnam() and getpwuid()entry point,s and uses the TACACS+ authentication functions.

The plugin asks the TACACS+ server if the user is known, and then for relevant attributes to determine the user’s privilege level. When the libnss_tacplus package is installed, nsswitch.conf is be modified to set tacplus as the first lookup method for passwd. If the order is changed, lookups will return the local accounts such as tacacs0

If the user is not found, a mapped lookup is performed using the exported functions. The privilege level is appended to “tacacs “, and the lookup searches for the name in the local password file. For example, privilege level 15 will search for the tacacs15 user. If the user is found, the password structure is filled in with the user’s information.

If it is not found, the privilege level is decremented and checked again, until privilege level 0 (user tacacs0) is reached. This allows use of only the two local users tacacs0 and tacacs15, if minimal configuration is desired.

TACACS Configuration Parameters

The recognized configuration options are the same as the libpam_tacplus command line arguments; not all pam_tacplus options are supported, however. These configuration parameters are documented in the tacplus_servers.5 man page, which is part of the libpam-tacplus package.

The table below describes the configuration options available:

Configuration Option



Output debugging information via syslog(3).

Debugging is heavy, including passwords. Do not leave debugging enabled on a production switch once you have completed troubleshooting.


Secret key used to encrypt/decrypt packets sent to/received from the server. Can be specified more than once, and can be in any order with respect to the server= parameter. When fewer secret= parameters are specified, the last secret given is used for the remaining servers. This parameter should only be put into files such as /etc/tacplus_servers that are not world readable.



Adds a TACACS+ server to the servers list. Servers will be queried in turn until a match is found, or no servers remain in the list. Can be specified up to 7 times. When the IP_ADDR form is used, it can be optionally followed by a port number, preceded by a ":". The default port is 49.

When sending accounting records, the record is sent to all servers in the list if acct_all=1, which is the default.


TACACS+ server(s) communication timeout. The default value is 5 seconds.


TACACS+ authentication service (pap, chap, or login). The default value is pap.


This is not enabled by default. When enabled, a separate home directory for each TACACS+ user is created when the TACACS+ user first logs in. By default, the home directory in the mapping accounts in /etc/passwd (/home/tacacs0 ... /home/tacacs15) is used. If the home directory does not exist, it is created with the mkhomedir_helper program, in the same manner as pam_mkhomedir.

This option is not honored for accounts with restricted shells when per-command authorization is enabled.


Configuration option for audisp_tacplus and pam_tacplus sending accounting records to all supplied servers (1), or the first server to respond (0). The default value is 1.


Sets the timeout in seconds for connections to each TACACS+ server. The default is 10 seconds for all lookups except that NSS lookups use a 5 second timeout.


If the management network is in a VRF, set this variable to the VRF name. This would usually be "mgmt". When this variable is set, the connection to the TACACS+ accounting servers is made through the named VRF.


TACACS+ accounting and authorization service. Examples include shell, pap, raccess, ppp, and slip.

The default value is shell.


TACACS+ protocol field. This option is use dependent.

PAM uses the SSH protocol.

Removing the TACACS+ Client Packages

To remove all of the TACACS+ client packages, use the following commands:

cumulus@switch:~$ sudo -E apt-get remove tacplus-client
cumulus@switch:~$ sudo -E apt-get autoremove

To remove the TACACS+ client configuration files as well as the packages (recommended), use this command:

cumulus@switch:~$ sudo -E apt-get autoremove --purge

Troubleshooting TACACS+

Debugging Basic Server Connectivity or NSS Issues

The getent command can be used to determine whether TACACS+ is configured correctly, and the local password is stored in the configuration files. In the example commands below, the cumulus user represents the local user, while cumulusTAC represents the TACACS user.

To look up the username within all NSS methods:

cumulus@switch:~$ sudo getent passwd cumulusTAC
cumulusTAC:x:1016:1001:TACACS+ mapped user at privilege level 15,,,:/home/tacacs15:/bin/bash

To look up the user within the local database only:

cumulus@switch:~$ sudo getent -s compat passwd cumulus

To look up the user within the TACACS+ database only:

cumulus@switch:~$ sudo getent -s tacplus passwd cumulusTAC
cumulusTAC:x:1016:1001:TACACS+ mapped user at privilege level 15,,,:/home/tacacs15:/bin/bash

If TACACS does not appear to be working correctly, the following configuration files should be debugged by adding the debug=1 parameter to one or more of these files:

  • /etc/tacplus_servers
  • /etc/tacplus_nss.conf

debug=1 can also be added to individual pam_tacplus lines in /etc/pam.d/common*.

All log messages are stored in /var/log/syslog.

Incorrect Shared Key

The TACACS client on the switch and the TACACS server should have the same shared secret key. If this key is incorrect, the following messages is printed to syslog:

2017-09-05T19:57:00.356520+00:00 leaf01 sshd[3176]: nss_tacplus: TACACS+ server read failed with protocol error (incorrect shared secret?) user cumulus 

Debugging Issues with Per-command Authorization

To debug TACACS user command authorization, have the TACACS+ user enter the following command at a shell prompt, and then try the command again:

tacuser0@switch:~$ export TACACSAUTHDEBUG=1 

When this debugging is enabled, additional information is shown for the command authorization conversation with the TACACS+ server:

tacuser0@switch:~$ net pending
tacplus-auth: found matching command (/usr/bin/net) request authorization
tacplus-auth: error connecting to to request authorization for net: Transport endpoint is not connected
tacplus-auth: cmd not authorized (16)
tacplus-auth: net not authorized from
net not authorized by TACACS+ with given arguments, not executing
tacuser0@switch:~$ net show version
tacplus-auth: found matching command (/usr/bin/net) request authorization
tacplus-auth: error connecting to to request authorization for net: Transport endpoint is not connected
tacplus-auth: authorized command net
tacplus-auth: net authorized, executing
DISTRIB_ID="Cumulus Linux"
DISTRIB_DESCRIPTION="Cumulus Linux 3.4.0"

To disable debugging:

tacuser0@switch:~$ export -n TACACSAUTHDEBUG

Debug Issues with Accounting Records

If TACACS+ servers have been added or deleted from the configuration files, make sure you notify the audisp plugin with this command:

cumulus@switch:~$ sudo killall -HUP audisp-tacplus

If accounting records still are not being sent, add debug=1 to the file /etc/audisp/audisp-tac_plus.conf, and then issue the command above to notify the plugin. Then have the TACACS+ user run a command, and examine the end of /var/log/syslog for messages from the plugin. You can also check the auditing log file /var/log/audit/audit.log to be sure the auditing records are being written. If they are not, restart the audit daemon with:

cumulus@switch:~$ sudo systemctl restart auditd.service

TACACS Component Software Descriptions

These different pieces of software are involved with delivering TACACS. Provided below is a brief description of their functionalities.

Package NameDescription
audisp-tacplus_1.0.0-1-cl3u3This package uses auditing data from auditd to send accounting records to the TACACS+ server and is started as part of auditd.
libtac2_1.4.0-cl3u2Basic TACACS+ server utility and communications routines.
libnss-tacplus_1.0.1-cl3u3Provides an interface between libc username lookups, the mapping functions, and the TACACS+ server.
tacplus-auth-1.0.0-cl3u1This package provides the ability to do per-command TACACS+ authorization, and a setup utility tacplus-restrict to enable that. Per-command authorization is not done by default.
libpam-tacplus_1.4.0-1-cl3u2A modified version of the standard Debian package.
libtacplus-map1_1.0.0-cl3u2The mapping functionality between local and TACACS+ users on the server. Sets the immutable sessionid and auditing UID to ensure the original user can be tracked through multiple processes and privilege changes. Sets the auditing loginuid as immutable if supported. Creates and maintains a status database in /run/tacacs_client_map to manage and lookup mappings.
libsimple-tacacct1_1.0.0-cl3u2Provides an interface for programs to send accounting records to the TACACS+ server. Used by audisp-tacplus.
libtac2-bin_1.4.0-cl3u2Provides the “tacc " testing program and TACACS+ man page.


TACACS+ Client Is only Supported through the Management Interface

The TACACS+ client is only supported through the switch’s management interface, which could be eth0 or eth1, or even the VRF management interface. The TACACS+ client is not supported through bonds, switch virtual interfaces (SVIs) or switch port interfaces (swp).

Multiple TACACS+ Users

If two or more TACACS+ users are logged in simultaneously, with the same privilege level, while the accounting records are maintained correctly, a lookup on either name will match both users, while a UID lookup will only return the user that logged in first.

This means that any processes run by either user will be attributed to both, and all files created by either user will be attributed to the first name matched. This is similar to adding two local users to the password file with the same UID and GID, and is an inherent limitation of using the UID for the base user from the password file.

The current algorithm returns the first name matching the UID from the mapping file; this could be the first or second user that logged in.

To work around this issue, the switch’s audit log or the TACACS server accounting logs can be used to determine which processes and files were created by each user.

  • For commands that do not execute other commands (for example, changes to configurations in an editor, or actions with tools like clagctl and vtysh), no additional accounting is done.
  • Per-command authorization is not implemented in this release except at the most basic level (commands are permitted or denied based on the standard Linux user permissions for the local TACACS users, and only privilege level 15 users can run sudo commands by default).

The Linux auditd system does not always generate audit events for processes when terminated with a signal (via the kill system call or internal errors such as SIGSEGV). As a result, processes that exit on a signal that isn’t caught and handled may not generate a STOP accounting record.

Issues with deluser Command

TACACS+ and other non-local users that run the deluser command with the --remove-home option will see an error about not finding the user in /etc/passwd:

tacuser0@switch: deluser --remove-home USERNAME
userdel: cannot remove entry 'USERNAME' from /etc/passwd
/usr/sbin/deluser: `/usr/sbin/userdel USERNAME' returned error code 1. Exiting

However, the command does remove the home directory. The user can still log in on that account, but will not have a valid home directory. This is a known upstream issue with the deluser command for all non-local users.

The --remove-home option should only be used when the user_homedir=1 configuration command is in use.