CLI & scripts

Taranac is administered almost entirely from its web UI. The command line exists for the handful of jobs the UI cannot do for itself: bringing the stack up, recovering an admin who is locked out of the UI, 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, 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)

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 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.

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. Both are safe to run at any time; they only read or issue tokens.

./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.

./taranac cluster status                              # cluster/node health and replication
./taranac cluster join-token --name node-2 --address 10.0.0.2   # issue a one-time join token
./taranac cluster register --token <secret>           # redeem a token on a joining node

cluster issues/redeems join tokens and reports cluster status. It does not convert a stack to HA or clone a node — that is out-of-band, driven by the ha-convert.sh and ha-join.sh scripts shipped in the bundle. See High availability for the end-to-end procedure.

./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 --version 1.1.0   # update to a specific version
./taranac update --check       # report only; change nothing
./taranac update --no-restart  # swap files but don't pull/restart yet

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. Database migrations run automatically when the api container starts.

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.1.0.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.

Restoring a full backup onto a fresh host is intentionally two-phase and semi-manual, because the host-side files (.env, the compose file, certificates) are environment-specific and must be reviewed by hand. The deploy/taranac-restore.sh script runs the in-container steps and prints the exact host steps to do between them.

deploy/taranac-restore.sh prod taranac-backup-YYYYMMDDTHHMMSSZ.tar

Phase 1 verifies the original master key and extracts the host secrets and certificates from the archive. You then restore the env-file, the compose file (review the diff first), and the certificates by hand, and recreate the stack so it runs with the original secrets. Phase 2 wipes the current configuration, loads the backup data, and regenerates the daemon configs.

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
• 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