CLI & scripts

Taranac is administered almost entirely from its web UI. The command line exists for the jobs the UI cannot do for itself: bringing the stack up, recovering an admin who is locked out of the UI, building and operating an HA cluster, collecting diagnostics, rotating the master key, updating to a new release, and disaster recovery. All of it runs from the deployment bundle directory on the host (the folder created when you unpacked the release and ran ./install.sh), through one thin wrapper named taranac.

You do not need to know Docker to operate Taranac, but it helps to know that the wrapper is just a shortcut around docker compose: anything you can do with docker compose you can do by typing it after ./taranac.

./taranac has two kinds of commands:

• Convenience subcommands it interprets itself — unlock, reset-password, create-admin, installation-id, cluster, diagnose, restore, rotate-key, reset, version, update.
• Everything else is passed straight through to docker compose, so ./taranac ps, ./taranac logs, ./taranac up -d, ./taranac down, ./taranac restart <service> all behave exactly like the compose commands of the same name.

./taranac ps                 # service status
./taranac logs -f api        # follow one service's logs
./taranac restart edge       # restart the edge (e.g. to apply a new TLS cert)
./taranac up -d              # start the stack (detached)
./taranac down               # stop everything (data in volumes is preserved)

Most of them are a docker compose exec into the api container. Several are not: recovery, key rotation, updates, diagnostics and cluster building have to rewrite host files, capture packets on the host’s interfaces or recreate containers — none of which a container can do for itself — so they live in their own scripts next to the wrapper.

If one of those scripts is missing from the bundle the wrapper says so and tells you to run ./taranac update once — it never falls through to something else.

The same bundle is unpacked on a full Taranac node, on an HA witness and on a standalone NCM collector — that is how those hosts get their own join scripts, and it puts this wrapper on all three. Since 1.2.7 the wrapper resolves which kind of host it is on first and drives that host’s compose file, so ./taranac ps on a witness shows the arbiter’s etcd rather than a product stack that was never meant to run there.

On a witness or a collector, the commands that need the database or the API — cluster …, unlock, reset-password, create-admin, installation-id, reset — are refused with the reason and a list of what can be done on that host. ./taranac diagnose --ha is deliberately allowed on the witness: an HA fault is usually a disagreement between nodes, and support needs the arbiter’s side of it. On a witness, down / stop / kill also print what stopping the arbiter costs you in votes.

These three scripts run once per host, in order, and are the only thing you run before the platform is up. After that, day-to-day work is the wrapper above.

install.sh takes exactly two options: --no-start, which writes the configuration but does not pull or start anything (used to prepare a node that will join an HA cluster, since a joining node must have an empty data volume), and -h / --help. Anything else is refused by name.

install.sh is also the upgrade path for the images: re-running it when .env already exists never regenerates secrets — it just pulls and restarts. For a full release upgrade (images and bundle files) use ./taranac update, described below.

A host that is not a full Taranac node — an HA witness, a standalone NCM collector, a remote captive portal — is brought online by one command that enrolls it against the core. Each of them takes -h / --help.

A witness pins the join channel by a fingerprint the primary prints on its console — not trust-on-first-use — and the normal way to get all three arguments is to let ./taranac cluster add-witness print the command for you. A collector is moved between versions with ./collector-join.sh --update, never with ./taranac update: a collector has to match the version its core runs, which is not the newest release while you upgrade hosts one at a time.

The reason an operator reaches for the CLI most often is being locked out of the web UI. Taranac locks an account after a number of failed logins (MAX_LOGIN_ATTEMPTS, 5 by default) and the lock does not auto-expire — common on an internet-facing host once someone starts guessing passwords. Since the lock blocks the UI, recovery has to happen from the server console.

Each of these runs the corresponding tool inside the api container.

./taranac unlock              # list currently locked accounts
./taranac unlock admin        # unlock one account by username
./taranac unlock --all        # unlock every locked account

Pass either a username or --all, not both.

./taranac reset-password admin                       # reset, print a new random password
./taranac reset-password admin --password 'S3cret!'  # set an exact password
./taranac reset-password admin --no-force-change     # don't force a change at next login

By default the account is required to change the password at the next login.

When no admin login works at all, create-admin is a create-or-repair tool: it creates the admin if missing, or repairs/re-enables and re-passwords an existing one.

./taranac create-admin                                # use INITIAL_ADMIN_* from .env, print password
./taranac create-admin opsadmin --email ops@example.com
./taranac create-admin admin --password 'My$tr0ngPass'

If --password is omitted a strong password is generated and printed; if the username is omitted it falls back to INITIAL_ADMIN_USERNAME (or admin).

Two subcommands support the Pro edition. installation-id only reads. cluster spans everything from a status read to building a cluster and evicting a node from it, so each destructive verb carries its own guard — the safe ones (status, verify without --rehearse, connectivity, manifest-fetch, manifest-info) can be run at any time. Both are refused on a witness or a collector host.

./taranac installation-id     # print this install's immutable installation ID

The installation ID is the value a Pro license binds to. Send it to TaranacLabs out-of-band to have a signed .lic issued, then upload that file under Settings → Licensing. The same ID is shown on the Licensing page in the UI. See Licensing & editions for the full flow.

Since 1.2.3 cluster is the whole HA interface: it builds the cluster as well as operating it. You never hand-edit .env on each machine, copy TLS material over scp or carry the master key by hand — and you never drive ha-convert.sh / ha-join.sh yourself, though they are still in the bundle because the wizard calls them.

./taranac cluster with no arguments prints one help text covering both families, and every subcommand takes its own --help. This page is the syntax; the procedure, the ordering rules and what each command proves are on High availability.

./taranac cluster init --witness 10.0.0.3=wit-01 --node 10.0.0.2=node-02
./taranac cluster add-witness --address 10.0.0.3
./taranac cluster add-node    --address 10.0.0.2
./taranac cluster status

Building the cluster — run on the host holding the primary role. These rewrite this host’s .env and recreate containers, so they run on the host, not in a container.

A node’s name is chosen at init or not at all: it is written into the etcd ring, the certificates and every node’s .env, so there is no rename. Omit =NAME and one is derived (<cluster>-node-N).

Operating the cluster — these run inside the api container, where the database session, RBAC and the audit log are.

The manifest subcommands are normally driven by the wizard. They are first-class commands because they are the two cures the wizard prints when a node’s copy of config/cluster.yml and the cluster’s copy disagree — it names both and never picks one for you:

./taranac cluster manifest-publish < config/cluster.yml   # this node's copy is right
./taranac cluster sync                                    # the cluster's copy is right

./taranac diagnose --protocol tacacs --device 10.0.0.5      # one device's traffic, decoded
./taranac diagnose --protocol ncm --config "SW1 - show runn" # why a config collection fails
./taranac diagnose --ha                                      # this node's view of the cluster

One command, three collectors: a packet capture around one device with the daemon log, Taranac’s own records and the generated config; a session recorder for one tracked configuration; and a cluster-state snapshot to run on every node, the witness included. None of them writes a secret into what it produces — only 12-hex key fingerprints. The packet-capturing collectors need root: run them as root, or from an account that can sudo without a password, which the script uses on its own. See Diagnostic bundles.

--ha accepts its own two options instead: --out DIR (same default) and --log-lines N (default 400).

./taranac update is a true release upgrade: it refreshes both the container images and the bundle files (the wrapper itself, docker-compose.yml, install.sh, docs, .env.example). A plain docker compose pull only updates images and silently leaves the bundle scripts stale — update closes that gap.

./taranac version              # show installed version + check for a newer one
./taranac update               # update to the latest published version
./taranac update --check       # report only; change nothing

What update does, in order: backs up the current bundle files, swaps in the new ones, leaves your .env and config/ untouched (it only lists any new settings worth adding), bumps the pinned version, pulls images and restarts, then removes the superseded images — keeping the installed version and the one before it, and only ever under this install’s own IMAGE_PREFIX. Database migrations run automatically when the api container starts.

Two things worth knowing before you run it:

• It never updates one half. If the bundle tarball cannot be fetched, the update aborts with nothing changed rather than pulling images over a stale framework — a release may need the new docker-compose.yml as much as the new images. A failed checksum aborts the same way.
• A witness is not a Taranac node. Since 1.2.7, ./taranac update on an HA witness refreshes the bundle’s files (witness-join.sh, the witness compose file, diagnose.sh, the HA runbook) and stops: it neither reads nor edits the witness .env, and it starts nothing. A collector host behaves the same way — move a collector with ./collector-join.sh --update, which asks its core what version to be.

Air-gapped hosts. A failed online check is a notice, not an error — normal operation never touches the network. To update offline, copy the bundle tarball onto the host and point update at it:

./taranac update --from taranac-bundle-1.2.8.tar.gz

If a bundle is so old it has no update command yet, copy taranac and taranac-update.sh from a newer bundle once; from then on it is self-maintaining.

./taranac reset truncates every table, re-applies the default seeds (settings, RBAC roles, AAA templates and profiles, the default policy), regenerates the daemon configs, and recreates the admin from the INITIAL_ADMIN_* values in .env. It is meant for demo and lab stands, and it is guarded so you cannot fire it by accident.

./taranac reset                  # dry run — print the plan, change nothing
./taranac reset --confirm RESET  # actually perform the reset

Two guards must both pass:

1. Environment — only APP_ENV=demo or development may reset. On anything else (production) it refuses unless you add --force-prod. To reset a production-flagged stand deliberately, set APP_ENV=demo in .env, run ./taranac up -d to recreate the api container, then reset.
2. Typed confirmation — nothing happens without --confirm RESET.

By default a backup is taken before the wipe and the reset aborts if that backup fails, so you are never left without a safety net. --no-backup removes both.

./taranac rotate-key replaces the key that encrypts every stored secret — device and group shared secrets, enable passwords, the internal CA’s private keys, NCM credentials, TOTP secrets, the LDAP bind password, the license. It runs on a stopped system, in one database transaction, so “half the data on the old key” cannot happen, and it keeps the previous key under config/retired-keys/ so archives taken before the rotation stay restorable.

./taranac rotate-key --confirm LOCAL-ACCESS-VERIFIED
./taranac rotate-key --confirm LOCAL-ACCESS-VERIFIED --new-key-file /path/to/key

You are asked for the current key even when it is already in .env. That is not a formality: it proves you still hold the key that opens every archive taken so far.

Restore is not in the UI — it erases the current configuration — so it runs from the CLI, off the API, and verifies your master key before it touches anything. One command drives both phases:

./taranac restore taranac-backup-YYYYMMDDTHHMMSSZ.tar
./taranac restore <archive>.tar --master-key <KEY>   # this install runs a different key
./taranac restore <archive>.tar --yes                # skip the phase-2 confirmation

Phase 1 verifies the original master key and extracts the archive’s host files and certificates. The script then overlays the five values that must survive a rebuild — MASTER_KEY, SECRET_KEY, TARANAC_MFA_API_KEY, INTERNAL_API_KEY, REPORTS_RENDERER_API_KEY — onto this host’s .env, keeping the previous file as .env.pre-restore; clears the daemons’ master_key volume so their entrypoints adopt the restored key; restores the certificates and ./config; recreates the services that read those secrets; and only then runs phase 2, which replaces the configuration with the archive’s. Everything finishes with a full restart so each service re-reads what was restored.

./backups/restore holds decrypted secrets — delete it when you are done. Two things the archive never carries: MFA enrollments (taranac-mfa has its own database and its own crypto) and the Active Directory machine account (Samba rotates its password weekly, so a restored one would be a broken trust — re-join the domain from System → Authentication if MS-CHAPv2 is used).

The two phases are also reachable individually inside the api container, which is what the script calls: python -m app.scripts.restore host <archive> [--master-key KEY] [--out DIR] (default /restore) and python -m app.scripts.restore db <archive> [--yes] [--force], where --force overrides a version or schema mismatch.

For a non-standard layout, point the script at the right pair explicitly rather than passing a positional: it reads TARANAC_ENV_FILE and TARANAC_COMPOSE_FILE, defaulting to .env and docker-compose.yml.

Under HA the script detects the cluster and merges the Patroni overlay by itself; recovery runs on the leader, and the other nodes rejoin afterwards. See Backup & upgrades for the full runbook.

You will not run these yourself, but it helps to know they exist when reading logs. The TACACS+, RADIUS and NAC containers each run small watcher scripts that keep the running daemon in sync with the configuration the web UI produces. The admin UI generates a config file, drops a signal file next to it, and a watcher picks up the change:

The effect for an operator: when you save an AAA, NAC or device change in the UI, the relevant daemon reloads on its own within seconds — there is no command to run and no restart. If a reload ever doesn’t take, ./taranac restart <service> (for example radius or nac) forces a clean restart.

• Installation & first run — full deploy runbook
• Backup & upgrades — taking backups before upgrades and resets, the full restore and key-rotation runbooks
• Diagnostic bundles — what each diagnose collector gathers and how to read it
• Settings reference — the .env settings these commands read
• Licensing & editions — what installation-id is for and how to activate Pro
• High availability — the cluster the cluster subcommand operates on
• Deployment bundle & releases: github.com/TaranacLabs/taranac