Architecture

Taranac is not a single daemon — it is a small set of containers that each own one job (the API, the protocol engines, the database, the edge) and share a single source of truth in PostgreSQL. You manage everything from one admin UI; the protocol containers read their working configuration from a shared volume and the database, never from hand-edited files. This page explains what the moving parts are, how they relate, and what actually happens when a switch, router, or laptop asks Taranac to authenticate.

The whole stack runs under Docker Compose. In the default single-host deployment there is no separate “controller” and “node” tier — the same compose file brings up the API, the AAA engines, NAC, the captive portal, the database, and the public edge proxy together. Under the optional high-availability topology this changes: the database becomes a Patroni-managed primary/replica cluster across two or more hosts, layered on by an HA overlay compose file — see the HA section below.

The dashboard surfaces live activity from every container — AAA and NAC authentications, sessions, and certificate expiry — in one place.

Each box below is a separate container. They communicate over an internal Docker network; only the edge proxy and the protocol listeners are exposed to the outside.

Both protocols cover “who can manage the network gear”, but they do policy differently, and this shapes what you can configure:

You do not need to know this to use the UI, but it explains why Command Sets and enable settings appear only under TACACS+, and why a RADIUS policy is purely “match conditions → assign a profile.”

Two mechanisms tie the containers into one product.

1. PostgreSQL is the single source of truth. Users, groups, devices, policies, profiles, certificates, logs, and live session state all live in one database. The protocol engines do not own any of this — they read it. Each engine keeps small in-memory caches (users, devices, policy rules, profiles) that refresh from the database roughly every 30 seconds, so a change you make in the UI takes effect within seconds without a restart.

2. Generated config on a shared volume. Some settings — chiefly the list of network devices and their shared secrets — can’t be served from a cache at request time; the protocol daemons need them in their own config files. When you save a device or change a setting, the API renders the engine configuration and writes it to a Docker volume that the relevant container mounts. A watcher inside the container then validates and reloads:

Admin UI → API renders config → writes to shared volume → watcher validates → reload signal → tac_plus-ng / FreeRADIUS picks it up

The reload is deliberately careful. For FreeRADIUS, if only modules or virtual servers changed, the engine is sent a hot HUP with no downtime; if the device list (clients.conf) changed, the container does a full restart, because FreeRADIUS 3.x cannot add or remove clients from its in-memory table on a HUP. You never edit these files by hand — the UI owns them.

Server-to-server traffic (API ↔ engines ↔ MFA) runs over HTTPS using a self-signed internal CA that Taranac generates automatically on first start. The CA and per-service certificates are distributed through a shared taranac_certs volume. This is entirely separate from the public certificate the operator supplies for the edge proxy — the internal CA is never exposed to browsers.

The request path depends on which engine the network device talks to.

Network device → tacacs (tac_plus-ng) → MAVIS handler:
  1. Look up the user (local or LDAP) and verify the password
  2. Apply MFA if the policy requires it
  3. Match WHO / WHEN policy conditions → return matching rule profiles
→ tac_plus-ng applies first-match-wins, WHERE/SOURCE conditions, and per-command rules
→ device gets shell, privilege level, and allowed commands

Network device → radius (FreeRADIUS, VS aaa) → Python handler:
  1. Identify the device by NAS IP; look up the user
  2. Evaluate policy (WHO + WHERE + SOURCE + WHEN), first-match-wins
  3. Reject, authenticate-only, or render an authorization profile
  4. Apply MFA challenge if required
→ Access-Accept with the profile's reply attributes

Endpoint → switch port → nac (FreeRADIUS, VS nac) → NAC handler:
  • 802.1X (PEAP / EAP-TLS / EAP-TTLS): negotiate EAP, verify the user or
    certificate, enrich the endpoint
  • MAB (no supplicant): use the MAC as identity, look up the endpoint,
    auto-discover and classify if unknown
  → evaluate NAC policy (HOW / WHO / WHAT / WHERE / WHEN), first-match-wins
  → render the authorization profile into vendor-correct RADIUS attributes
→ Access-Accept with VLAN / dACL / redirect, or Access-Reject
→ accounting tracks the live session; CoA can re-authorize it later

The same authorization profile — say “Printers, VLAN 300, restricted ACL” — works across every switch vendor. The NAC engine consults a vendor dictionary to translate that intent into the exact RADIUS attributes a Cisco, Arista, or Aruba switch expects.

NAC policy rules evaluate first-match-wins; each rule’s conditions map to an authorization profile or a reject.

Almost every object an engine evaluates is a shared record you manage once:

Because the identity store and the device list are shared, the same user or the same switch is defined exactly once and is consistent across TACACS+, RADIUS, and NAC.

Network devices are defined once and reused by every protocol engine, with shared-secret inheritance from device groups.

A single-host Compose deployment is the default topology. For deployments where authentication must survive a host failure, Taranac ships a turnkey high-availability mode as a licensed Pro feature. Because all durable state lives in PostgreSQL, HA is built around replicating the database: the stack runs across two or more hosts with a Patroni-managed primary/replica PostgreSQL cluster (etcd as the coordination store, plus a lightweight witness for two-node setups), and the API/engine tier follows the elected leader for writes while reads can be served from replicas. An HA overlay compose file adds these pieces on top of the standard stack; converting a running single-host deployment is a two-phase ha-convert.sh --prepare / --continue flow. This qualifies the single-host “no controller/node tier” statement above — under HA there is a leader (primary) and one or more followers (replicas).

HA is license-gated: the cluster refuses to issue join tokens beyond the licensed node count unless a valid Pro license is active. See Licensing for how the offline license enables it, and High availability for the full architecture, prerequisites, enablement, and day-2 operations.

• Quick start — bring the stack up
• AAA policy — how TACACS+ and RADIUS authorization is decided
• NAC overview — endpoints, 802.1X, and port access control
• Network devices — defining the NAS devices every engine relies on
• Deployment bundle & docs: github.com/TaranacLabs/taranac