tacacs-plus

Define a named list of TACACS+ client devices.

The example below shows a static TACACS+ client configuration. For IP-based client resolution populated from a jsonfile or external database, see ipmap.

clients {
    tacacs-plus "NETWORK_DEVICES" {
        client "core-switch-1" {
            source {
                ip 10.10.1.10;
            }
            secret "SuperSecretKey!";
            timeout 60s;
            connection-mode client-selected;
            validation-mode compatible;
            @pre-policy {
                # Optional: logging, attribute normalization
            }
            @post-policy {
                # Optional: audit logging
            }
        }

        client "access-switches" {
            source {
                ip 10.20.0.0/16;
            }
            secret none;
        }
    }
}

Elements

Note: The @ prefix is required for pipeline blocks. The legacy syntax without @ (for example pre-policy {} and post-policy {}) is deprecated and emits warnings.

Source Block

Use one or more ip statements to match incoming client devices. TACACS+ client selection is based on source IP prefixes, so a client with no ip entries will not match incoming connections. Add protocol tcp; or protocol tls; when the same address space needs separate client policy for TCP and TLS listeners.

More specific prefixes take precedence over broader ones.

source {
    ip 10.10.1.10;
    ip 10.10.2.0/24;
    ip 2001:db8:1234::/48;
    protocol tls;
}

Use separate client entries when the same device range is allowed over both plain TCP and TLS, but you want distinct matching or timeout policy:

clients {
    tacacs-plus "NETWORK_DEVICES" {
        client "switches-tcp" {
            source {
                ip 10.20.0.0/16;
                protocol tcp;
            }
            secret "SharedTacacsSecret";
        }

        client "switches-tls" {
            source {
                ip 10.20.0.0/16;
                protocol tls;
            }
            secret "SharedTacacsSecret";
            timeout 1m;
        }
    }
}

Secrets and Obfuscation

The client secret setting and the TACACS+ server obfuscation setting together decide whether TACACS+ packet bodies are obfuscated on the wire:

• secret "STRING"; - shared secret; the client must send obfuscated packets.
• secret none; - no shared secret; the client must send unobfuscated packets.
• secret omitted - the client has no shared secret. The matched TACACS+ server must set obfuscation disabled;; otherwise the client entry cannot be used.

If the matched TACACS+ server sets obfuscation disabled;, the client secret is ignored and the server always expects unobfuscated packets.

Operational guidance:

• Configure the same secret on both the device and the server.
• Use long, random strings and rotate them periodically.
• Avoid reusing the same secret across separate trust zones.
• TACACS+ shared secrets provide only MD5-based body obfuscation. They do not provide modern integrity or replay protection for the transport.
• Use TACACS+ only on a trusted network path, or configure servers.tls for TACACS+ over TLS.
• If you use secret none; without TLS, keep the network path trusted.
• For TACACS+ over TLS deployment details, see TACACS+ Authentication, Authorization, and Accounting.

Timeouts

timeout accepts a duration value. Use explicit unit suffixes such as ms, s, m, or h. Bare numbers are interpreted as milliseconds for backward compatibility, so timeout 60; means 60 milliseconds, not 60 seconds.

If omitted, the listener's timeout value is used. If neither the client nor the listener has a timeout configured, the default is 20000 milliseconds (20s). The timeout is applied as the TACACS+ TCP/TLS connection idle timeout for that client. It does not limit individual request processing time.

Set timeout 0; to disable the idle timeout.

Listener keepalive settings complement this timeout on TCP and TLS listeners: keepalive probes help close stale connections even when the idle timeout is set to a large value.

Examples:

timeout 500ms;
timeout 5s;
timeout 1m30s;
timeout 0;

See Duration Units for the supported suffixes.

Validation Mode

Use validation-mode to control RFC 8907 interoperability for an individual TACACS+ client:

Compatible mode currently permits ENABLE requests with protocol minor version

1. RFC 8907 specifies an ASCII-like version 0 exchange for ENABLE because its authen_type is not used, but older clients may derive version 1 from PAP, CHAP, or MSCHAP configuration. Other request validation remains enforced in both modes.

Use strict mode for clients known to follow RFC 8907 exactly:

client "rfc8907-switch" {
    source {
        ip 10.20.30.50;
    }
    secret "SharedTacacsSecret";
    validation-mode strict;
}

Connection Mode

Use connection-mode to control RFC 8907 Single Connection Mode for an individual TACACS+ client:

Use connection-per-session for devices with broken connection reuse or session multiplexing. This setting affects both TCP and TLS connections.

A client may ignore prefer-single-connection when it did not request the mode. The setting advertises server support but cannot require the client to reuse the connection.

client "legacy-switch" {
    source {
        ip 10.20.30.40;
    }
    secret "SharedTacacsSecret";
    connection-mode connection-per-session;
}

See Client-Selected Connection Mode for protocol behavior and timeout guidance.

@pre-policy / @post-policy

These optional pipelines let you insert early or late logic specific to that client:

Keep these pipelines fast. Long blocking operations in @pre-policy increase the latency seen by the TACACS+ device.

Example With Two Device Groups

clients {
    tacacs-plus "NETWORK_DEVICES" {
        client "core" {
            source { ip 10.1.0.10; ip 10.1.0.11; }
            secret "CoreSecret2024!";
            @pre-policy {
                # debug "Core device TACACS+ request";
            }
        }

        client "edge" {
            source { ip 10.2.0.0/16; }
            secret "EdgeDeviceSecret!";
            timeout 45s;
        }
    }
}

Authentication Types and Multistage Flows

Only the TACACS+ ASCII authen_type supports multistage continue rounds and therefore challenge, hotp, and totp follow-ups. PAP, CHAP, MSCHAP, and MSCHAPv2 must complete in a single exchange.

Inside an ASCII flow you can still validate captured passwords with pap and OTPs with totp or hotp. See TACACS+ Authentication, Authorization, and Accounting for a worked end-to-end example.

See Also

• TACACS+ Authentication, Authorization, and Accounting - Concept overview and multistage ASCII example
• servers.tls - TACACS+ over TLS listener configuration
• servers.listen.proxy-protocol - PROXY protocol support on TCP and TLS listeners