gardience command reference

gardience is the management command on the Gardience server. The installer puts it in the install directory, /opt/gardience/gardience by default (or ~/gardience/gardience when installed without root).

• Run it as root, or as a user that can run Docker.
• It can be run from any directory. It always works on the install it lives in.
• Relative file paths given to it are taken from the install directory, not your current directory. Use full paths.
• gardience with no subcommand, or with one it does not know, prints a short help list.

For the gdn command line on your own computer, see The gdn command line.

Everyday operation#

status#

gardience status

Lists the services and their state, then prints the result of the console's /gardience/health check.

logs#

gardience logs [service]

Shows the last 100 lines of every service's log (or one service's), then follows new lines. Services are gardience, salt-master (all-in-one only), runner and nginx. Press Ctrl-C to stop. See Support bundle and logs.

start, stop, restart#

gardience start
gardience stop
gardience restart

Starts (and creates if needed), stops, or restarts all services. start also applies changes made to .env.

doctor#

gardience doctor

Checks services, readiness, background components, the warm standby sync, the Salt API, free disk space, the TLS certificate, the license, the audit chain, pre-upgrade backup encryption and recent backups. Prints PASS, WARN or FAIL per check and exits with 1 if anything failed. See Monitoring.

support-bundle#

gardience support-bundle

Writes gardience-support-YYYYMMDD-HHMMSS.tar.gz in the install directory, with logs, versions and configuration, secrets redacted. Sends nothing.

log-level#

gardience log-level debug|info|warning

Sets how much the Gardience service logs and recreates the service. Without a level, prints the usage line and the current setting.

Users and roles#

users#

gardience users

Lists accounts in config/users.yaml with their role and sign-in type (file or ldap).

user add#

gardience user add NAME ROLE [--ldap]

Adds an account, or replaces an existing one with the same name. ROLE is admin, operator, approver, viewer or helpdesk-windows. Without --ldap, a 20-character password is generated and shown once. With --ldap, the person signs in with their directory password. Restarts the Salt master and the service.

user passwd#

gardience user passwd NAME

Sets a new generated password for a local account and shows it once.

user del#

gardience user del NAME

Removes an account. Its API keys stop working at once; open sessions end within the hour. The two service identities cannot be removed.

roles#

gardience roles [--admins A,B] [--approvers C,D]

Shows who administers Gardience and who may approve runs. In attach mode it also sets these lists. Admins are always added to the approvers. Read live by the service, no restart. See Users and roles.

render#

gardience render

Regenerates the Salt master configuration, permissions and node groups from config/users.yaml, then restarts the Salt master and the service. Run it after editing users.yaml by hand, for example to set up LDAP.

License#

license#

gardience license [FILE]

With a file, installs it as config/license.json. Always prints the license status. See Licensing.

Backup, restore and upgrade#

backup#

gardience backup [FILE] [--passphrase-file F | --plaintext]

Takes a consistent backup, including agent keys, after pausing the console for a few seconds. Encrypts it with the passphrase file, or by default with this server's config/backup.key (created on first use: keep a copy), and writes .mac and .sha256 files. --plaintext skips encryption. See Backup and restore.

backups-cron#

gardience backups-cron on|off|status

The once-a-minute check behind scheduled backups (Administration > Backups): a systemd timer (gardience-backups.timer), else /etc/cron.d/gardience-backups, else the installing user's crontab. The installer and upgrades turn it on. status shows which is in place and the last results from backups.log. The check runs gardience backup-scheduled, which does nothing unless the console asked for a backup or a test.

cac#

gardience cac on --dod | --ca FILE  [--crl FILE] [--port N] [--ocsp | --no-ocsp]
gardience cac crl FILE | off | status

Smart card (CAC / PIV) sign-in: opens the smart card port (8445) with the certificate authorities given (--dod downloads DoD's from DISA and checks DISA's checksums) and revocation by OCSP and/or a CRL. crl replaces the revocation list. Then link cards under Administration > Settings > Smart card sign-in. See Government sign-in.

restore#

gardience restore BACKUP.tar.gz[.enc] [--passphrase-file F] [--yes] [--no-checksum] [--legacy] [--keep-pki]

Replaces this install's data, agent keys and configuration with the backup's, then starts. Asks you to type restore unless --yes is given.

upgrade#

gardience upgrade gardience-X.Y.Z.tar.gz [--check] [--trust-key release-public-key.pem] [--allow-downgrade]

Upgrades to a release bundle. The bundle's .sha256 and .sha256.sig files must be next to it.

1. Checks the signature against the release key this install trusts, and the checksum against the bundle.
2. Refuses a version that is not newer than the installed one, unless --allow-downgrade is given.
3. Takes a backup (pre-upgrade-...). If that fails, nothing changes.
4. Updates the configuration, builds or loads the images, regenerates permissions and starts.
5. Waits for the console to be ready. If it is not, rolls back images, configuration and data on its own.

A standby stays a standby after an upgrade. The newest two pre-upgrade backups are kept. See Upgrade.

upgrade-apply#

gardience upgrade-apply NEW_RELEASE_DIR

Used internally by gardience upgrade: the new release's copy of the command runs this step against the install. Do not run it by hand.

Warm standby#

See High availability for how these fit together.

standby-mode#

gardience standby-mode

On the standby: stops the console, and keeps the Salt master side holding the pair's keys without accepting agents.

standby-sync#

gardience standby-sync USER@HOST[:DIR] --passphrase-file F [--keys-only]

On the primary, from cron: sends an encrypted backup to the standby over SSH, keeps the newest 5 there, and loads the primary's keys into the standby. --keys-only sends only the Salt keys. DIR defaults to /var/lib/gardience-standby. Refuses to run on a standby or a fenced server, and refuses to send to a server that is not a standby of the same or an older generation.

standby-refresh#

gardience standby-refresh BACKUP.tar.gz.enc --passphrase-file F

On the standby: loads only the Salt keys from a backup or key file. standby-sync runs it for you. Refuses on a primary, and never loads keys older than the ones already loaded.

keys-export#

gardience keys-export FILE --passphrase-file F

Writes the Salt master and agent keys, encrypted, to FILE.enc with .sha256 and .mac files, and prints the path. standby-sync --keys-only runs it for you.

promote#

gardience promote [BACKUP] --passphrase-file F [--force]

On the standby: restores the newest backup (/var/lib/gardience-standby/latest.tar.gz.enc by default) and becomes the primary of a new generation. Refuses while the old primary still answers as a primary, when there is no --peer-url, or when the backup is older than the newest one received. --force skips those checks.

autofailover#

gardience autofailover on MINUTES [--passphrase-file F] | off | status

Automatic failover for a primary/standby pair with a witness: run it on both servers. The standby then checks once a minute and promotes itself when the primary's signed heartbeat at the witness has been silent for MINUTES (3 or more) and the primary does not answer it either; a primary cut off from both the witness and its standby stops serving a minute earlier. On the standby it needs the backup passphrase file and root (it installs /etc/cron.d/gardience-autofailover). See High availability.

Site proxy (install/proxy.sh)#

./install/proxy.sh --master SERVER --site NAME [--master-ports P,R] [--listen-ports P,R] [--listen ADDR] [--dir DIR]
/opt/gardience-proxy/proxy status | restart | logs | uninstall

Runs on a machine at a remote site, not on the server. See Site proxies.

ha-role#

gardience ha-role

Prints this server's role and generation, for example primary 3. standby-sync uses it to check its partner.

Removing Gardience#

uninstall#

gardience uninstall

Asks you to type remove, then removes the containers and the data volumes, including the audit log, the vault and the agent keys. The install directory, with its configuration, is left for you to delete. Take a backup first if you might need the data.

Related#

• Installer options
• Ports and files
• Backup and restore
• Troubleshooting

automation#

gardience automation status | commands on|off | allow FUNCTION | disallow FUNCTION

What Gardience's automation identity may run on agents. commands off removes arbitrary command execution (Run a command, Ansible controller mode, PowerShell); allow adds a function a custom runbook needs. Restarts the Salt master to apply.

machine#

gardience machine removed | restore NAME | limit N

Machines removed through the API (DELETE /machines/{node}, for example by terraform destroy) are checked and limited by the config keeper and carried out by the Salt master, which moves the machine's key into a holding folder instead of deleting it. removed lists the held keys, restore NAME puts the newest one back so the machine can talk to the master again (within 30 days; after that the keeper deletes them), and limit N sets how many machines may be removed through the API in any hour (default 50). Not used in attach mode, where your own Salt master owns the keys.