Docs / Reference
Ports and files
Ports
Published on the server
These are the only ports open to the network. Allow them in your firewall.
| Port (default) | Protocol | Used by | Change with |
|---|---|---|---|
| 443 | HTTPS | The console, the REST API and the MCP server | --https-port |
| 80 | HTTP | Redirects to HTTPS only | --http-port |
| 4505 | TCP | Salt publish port: agents receive jobs. All-in-one only. | --salt-ports |
| 4506 | TCP | Salt return port: agents send results. All-in-one only. | --salt-ports |
The Salt ports listen on the address set by --salt-bind (all addresses by default).
Outgoing connections
The Gardience server connects out to these services when you set them up:
| Destination | When |
|---|---|
| Your salt-api | Attach mode (--attach). |
| Your identity provider | Single sign-on is on (OpenID Connect discovery, keys and tokens; SAML metadata URL). |
| Your SIEM | Audit forwarding is on. |
| Your Slack or Teams webhook | Notifications are on. |
| The other server's console | A primary and standby pair (--peer-url), for the signed status. |
| The standby, over SSH | gardience standby-sync on the primary. |
Internal only
These listen on the internal container network and are not published:
| Port | Service |
|---|---|
| 8000 | salt-api (all-in-one) |
| 9400 | The Gardience service |
| 9500 | The playbook runner |
URLs the console serves
| Path | What it is |
|---|---|
/ | Console sign-in and the Salt pages. |
/gardience/dashboard | Patch and compliance dashboard. |
/gardience/health | Liveness check. No sign-in. |
/gardience/ready | Readiness check. No sign-in. |
/gardience/ha-status | This server's signed role and generation, for its partner. Served even while the console is stopped. |
/gardience/api/v1/... | REST API. Needs an API key. |
/gardience/api/v1/docs | Interactive API documentation. |
/gardience/mcp | MCP server. Needs an API key. |
/gardience/cli/gdn | Download of the gdn command line. |
/gardience/sso/... | Single sign-on start, OIDC callback, SAML ACS and SAML metadata. |
Install directory
/opt/gardience by default, or ~/gardience when installed without root (--dir to change).
| Path | Contents |
|---|---|
gardience | The management command. |
.env | Settings and generated secrets. Readable by its owner only. |
compose.yml | The Docker Compose file. Generated; changes are lost at upgrade. |
VERSION | Installed version. |
config/ | Configuration, keys and certificates. Readable by its owner only. See below. |
srv/ | Salt content: states, modules and the reactor. Updated at upgrade. |
srv/pillar/ | Pillar data: system locks and drift rules. Kept at upgrade. |
ha/ | This server's signed status and fencing state, for a primary and standby pair. |
releases/ | Unpacked upgrade bundles. |
gardience-backup-*, pre-upgrade-* | Backups written here when no other path is given, and automatic pre-upgrade backups. |
gardience-support-*.tar.gz | Support bundles. |
ATTACH.md, attach-kit/ | Attach mode only: setup steps and files for your Salt master. |
config/
| File | Contents |
|---|---|
users.yaml | Accounts, roles and LDAP settings. Edit by hand only for LDAP; then run gardience render. |
htpasswd | Password hashes of local accounts. Generated. |
master.d/gardience.conf | Salt master settings, permissions and node groups. Generated by gardience render; do not edit. |
roles.env | Who administers and who approves. Read live by the service. |
salt-auth.txt | Which sign-in types the sign-in page offers. Generated. |
nginx.conf | Web front end settings. Generated. |
tls/gardience.crt, tls/gardience.key | The console's TLS certificate and key. |
license.json | The license. |
autosign/ | Agent enrollment tokens. |
state/audit.key | Key for the audit log's hash chain. Kept outside the data volume on purpose. |
state/audit.checkpoint, state/audit.anchor | Signed record of the audit log's length and newest entry, and where keyed hashing began. |
state/audit.alarm | Present only while an audit log problem is waiting to be acknowledged. |
removed_users.json | Accounts removed with gardience user del, so their API keys stay refused. |
ha/ha.json | This server's role and generation in a primary and standby pair. |
standby-sync.json | Result of the last standby-sync, on a primary. |
The Gardience web service reads config but may write only state/ and autosign/: everything else (users, Salt permissions, TLS, license) is written only by the config-keeper container, which has no network, and by the gardience command. Before 1.2.4 the audit files sat at the top of config; upgrades and restores move them.
Docker volumes
Volume names start with the project name (--name, gardience-server by default).
| Volume | Mounted at | Contents |
|---|---|---|
NAME_gardiencedata | /data in the Gardience service | All Gardience data: see below. |
NAME_saltpki | /etc/salt/pki in the Salt master | The Salt master key and accepted agent keys. All-in-one only. |
NAME_saltcache | /var/cache/salt in the Salt master | Salt's job cache. All-in-one only. Not backed up. |
gardience backup includes the first two volumes. gardience uninstall removes all three.
The data volume
Main files, all owned by the service's user (uid 10001):
| File | Contents |
|---|---|
audit.jsonl, audit-*.jsonl | The audit log: the live segment and sealed 50 MB segments. |
compliance.json, inventory.json, drift.json | Latest scan results, asset inventory and drift. |
runbooks.json, workflows.json, schedules.json, runs.json, runs-archive.jsonl | Automation and run history. |
groups.json, locks.json, windows.json, queue.json, rules.json | Node groups, locks, change windows, held work and event rules. |
settings.json | Console settings, including the SIEM destination and webhook. |
vault.key, vault.json, transport.json | The vault key and the encrypted secrets. |
api_keys.json | API key hashes and their settings. |
sso.json, sso_users.json | Single sign-on settings (client secret encrypted) and recent single sign-on users. |
sessions.json, perms.json, last_signin.json | Open sessions, each person's grants and last sign-in time. |
siem_cursor.json | SIEM forwarding position per destination. |
enrollments.json | Agent enrollment tokens issued. |
ansible-uploads/ | Playbooks uploaded through the API or gdn. |