tacacs-plus

Define a named list of TACACS+ client devices.

clients {
    tacacs-plus "NETWORK_DEVICES" {
        client "core-switch-1" {
            source {
                ip 10.10.1.10;
            }
            secret "SuperSecretKey!";
            timeout 60s;
            @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.

TACACS+ clients must declare exactly one secret setting. Use secret none; only for legacy devices that cannot send obfuscated TACACS+ bodies. When a shared secret is configured, unencrypted requests are rejected. When secret none; is configured, encrypted requests are rejected.

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

• 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.
• TLS protects the transport, but TACACS+ packet handling still follows the configured secret or secret none; mode for body obfuscation and compatibility checks.
• Use TACACS+ only on a trusted network path, or configure servers.tls for TACACS+ over TLS.
• secret none; is an explicit compatibility opt-out for older TACACS+ clients and should only be used when the network path is otherwise trusted.

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 10000 milliseconds (10s). 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.

@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 limits on TLS listeners