Configuration Reference

rustguac reads a TOML configuration file. All settings have sensible defaults and are optional.

rustguac --config /opt/rustguac/config.toml serve

See config.example.toml for a fully commented reference.

Server settings#

Session timeouts#

Browser session settings#

Connection allowlists#

CIDR ranges controlling which hosts sessions can connect to. All default to localhost only.

Important: These are top-level TOML keys and must appear before any [section] header. Keys placed after a section header (e.g., [tls]) are scoped to that section and will be silently ignored.

Trusted proxies#

[tls] section#

Configures TLS for the web server and/or the guacd connection. There is no enabled toggle — the presence of the relevant fields controls behaviour:

• Server HTTPS: Provide both cert_path and key_path to serve HTTPS. Omit them to serve plain HTTP (useful behind a TLS-terminating reverse proxy like Traefik/HAProxy).
• guacd TLS: Provide guacd_cert_path to connect to guacd over TLS. This is independent of server HTTPS.

All fields are optional. The [tls] section can contain any combination.

Examples:

HTTPS + guacd TLS (self-hosted):

[tls]
cert_path = "/opt/rustguac/tls/cert.pem"
key_path = "/opt/rustguac/tls/key.pem"
guacd_cert_path = "/opt/rustguac/tls/cert.pem"

HTTP server + guacd TLS (behind a reverse proxy):

[tls]
guacd_cert_path = "/opt/rustguac/tls/guacd-cert.pem"

HTTPS only (guacd on localhost, no TLS needed):

[tls]
cert_path = "/opt/rustguac/tls/cert.pem"
key_path = "/opt/rustguac/tls/key.pem"

[oidc] section#

Enables OpenID Connect authentication. When configured, the web UI shows a login button. API key auth continues to work alongside OIDC.

Note: issuer_url must match the discovered issuer URI exactly, including default ports and trailing slashes. For example, https://idp.example.com/ and https://idp.example.com may be treated as different issuers. Check your provider's .well-known/openid-configuration for the canonical value.

[vault] section#

Enables the Vault-backed connections. Uses AppRole by default, requiring the VAULT_SECRET_ID environment variable. Configure [vault.jwt_auth] to use a workload JWT instead; JWT mode does not require an AppRole role ID or SecretID.

Workload JWT authentication#

[vault]
addr = "https://vault.example.com:8200"
mount = "secret"
base_path = "rustguac"

[vault.jwt_auth]
mount = "workload-jwt"
role = "rustguac"
path = "/var/run/secrets/vault/token"

Give exactly one of path and token_command. The token is fetched again on every login and reauthentication, so a rotated token is always the one used. JWT mode takes precedence over AppRole and never falls back to it when the token is missing, empty or rejected. The import-guacamole and vault-migrate commands log in the same way. Use this with Vault/OpenBao JWT auth configured to verify the token issuer, audience and exact workload identity. This is separate from users' OIDC login.

The same nested block works as [vault_shared.jwt_auth] and [vault_local.jwt_auth]; only AppRole-mode backends need their SecretID env var. See Integrations for Kubernetes, Nomad, SPIRE and cloud VM setups.

Multiple Vault backends (disaster recovery)#

By default the single [vault] serves both the shared and instance (local) address-book scopes. For DR across a fleet you can give each scope its own Vault so that one being unreachable cannot take the other down with it. Add either or both of the optional blocks below; each takes the same keys as [vault].

A bare [vault] with no overrides behaves exactly as a single-Vault deployment, so nothing changes for existing installs. Each backend connects, retries, and renews its token independently. If a dedicated backend is unreachable, that scope is shown as temporarily unavailable in the Connections tree while the other scopes keep working.

When [vault_local] is used, set its instance_name to the value the data was originally stored under, so the instance/<name>/ paths line up. Splitting an existing single-Vault deployment is a one-time copy with the vault-migrate subcommand (see Splitting to multiple Vaults).

# Primary/local Vault (always reachable on this instance)
[vault]
addr = "https://127.0.0.1:8200"
role_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
instance_name = "dc1"

# Optional central Vault shared across the fleet
[vault_shared]
addr = "https://vault-central.example.com:8200"
role_id = "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"

Related top-level setting:

[drive] section#

Enables file transfer for RDP (drive redirection) and SSH (SFTP).

[theme] section#

Customises the UI appearance — base preset, individual colours, and logo. All fields are optional. A minimal example:

[theme]
preset = "light"
logo_url = "/acme-logo.png"
primary_color = "#003366"
accent_color = "#FF6600"

See themes.md for the full reference: built-in preset list, every overridable field, the per-user picker, and how to author your own themes as .toml files under <static_path>/themes/ (no recompile needed).

Place the logo file in the static_path directory (e.g. /opt/rustguac/static/acme-logo.png). In Docker, mount it as a volume:

-v /path/to/acme-logo.png:/opt/rustguac/static/acme-logo.png:ro

[recording] section#

Controls session recording behaviour and disk management.

[recording]
enabled = true
max_disk_percent = 80
max_recordings = 1000
rotation_interval_secs = 300

SSH typescript recording#

The graphical recording above captures the session as a replayable Guacamole stream. For SSH sessions you can additionally write a typescript: a plain-text log of the full terminal output, compatible with the standard script / scriptreplay tools and trivially greppable. This is aimed at audit and compliance (a human-readable record of what was typed and seen on a switch or server).

Typescript recording is per-connection opt-in and off by default. Two things are required: typescript_path must be set here (the global "where"), and the individual connection entry must have Enable typescript recording for this session ticked in its Recording Settings (Connections page, SSH entries only). A connection with the box unticked, or any session that is not SSH, writes no typescript. Ad-hoc SSH connections (Connect to a host) have no entry; for a non-admin they never record a typescript.

The typescript is produced by guacd, so typescript_path must be writable by the guacd process. On a standard install guacd runs as the same rustguac user as the main service, so a path it owns just works; create_typescript_path = true lets guacd create the directory. guacd writes two files per session, NAME and NAME.timing.

When typescripts exist, the Recordings page shows a SSH Typescripts section (poweruser+) listing each one with its name, size, and time. This is list-only by design: the text content is never downloadable through the web UI (a typescript can contain passwords typed at prompts or secrets printed to screen), so a poweruser can confirm a session was recorded while retrieving the actual log still requires direct access to the rustguac host or storage.

[recording]
typescript_path = "/opt/rustguac/data/typescripts"
typescript_name = "{connection}-{user}-{date}-{time}"
create_typescript_path = true

Filename tokens. guacd does not template typescript names itself (it uses the name verbatim and only appends a numeric suffix to avoid overwriting an existing file). rustguac therefore expands its own tokens in typescript_name before handing it over, so each file is identifiable:

Substituted values are sanitised to [A-Za-z0-9_-] (everything else becomes -), so usernames like alice@example.com and free-text entry names are always reduced to a safe basename with no path separators. Unknown {tokens} are left untouched.

Keystroke logging in the graphical recording (guacd's recording-include-keys, parseable by guaclog) is a separate mechanism that depends on guacd-driven graphical recording, which rustguac does not use (it records the proxied stream itself). It is therefore not wired up; the typescript is the supported text-audit path.

MP4 downloads#

A .guac recording only plays in rustguac's own player. The Recordings page can also give you an MP4 that plays anywhere (VLC, a browser, a video editor): click mp4 next to a recording. rustguac converts it in the background with guacenc, which comes with guacamole-server, and the file downloads when it is ready. Converting a long session takes a while, so the button shows converting... until then.

• The same people can get the MP4 as can download the recording (poweruser and admin).
• A recording whose session is still running is not converted, since the file is not finished.
• Converted files are kept in mp4_cache_path for mp4_cache_hours, so a second download is instant, and removed when their recording is. When rotation needs disk space it removes them all before touching any recording.
• The video is the recording's own size, scaled down to fit mp4_max_width x mp4_max_height.
• The button only appears when guacenc is installed. It is part of the .deb, the Docker image and install.sh from 1.11.1; on a build without it the button is not shown.

To convert recordings yourself, for example a batch for an audit, run guacenc on the rustguac host. It writes <recording>.m4v (an MP4 file) next to the input, so copy recordings somewhere writable first:

cp /opt/rustguac/recordings/<id>.guac /tmp/
/opt/rustguac/bin/guacenc -s 1920x1080 -r 2000000 /tmp/<id>.guac
# -> /tmp/<id>.guac.m4v

guacenc reports failures in its output but exits 0 either way, so check that the .m4v file exists.

Encryption at rest (LUKS)#

Typescripts are written in plain text. For encryption at rest with no extra infrastructure, point typescript_path at a subdirectory of the LUKS-encrypted drive volume rustguac already manages (see the [drive] section). rustguac opens and mounts that volume at startup (key fetched from Vault) and unmounts it at shutdown, so the directory is available whenever rustguac is running, and the files are encrypted on the block device at rest (powered off, disk theft, block-device backups).

[drive]
drive_path = "/mnt/rustguac-drives"
luks_device = "/dev/disk/by-uuid/..."   # your LUKS volume
luks_key_path = "secret/rustguac/luks"  # Vault KV path holding the key

[recording]
typescript_path = "/mnt/rustguac-drives/typescripts"
create_typescript_path = true

This is the recommended way to protect typescripts at rest today. Note its limits: while rustguac is running the volume is mounted, so the files are plain text to anyone with host access (the same threat model as the drive feature), and it is one key for the whole volume rather than per-connection. Per-file, per-connection-key encryption is tracked as a separate feature request, pending demand.

[vdi] section#

Enables VDI (Virtual Desktop Infrastructure) sessions using Docker containers. Each user gets an ephemeral Linux desktop in a Docker container, accessed via xrdp through guacd.

Prerequisites: Docker must be installed on the host and the rustguac user must be in the docker group. See VDI Desktop Containers for full setup.

[vdi]
enabled = true
idle_timeout_mins = 60
# port_range_start = 39000
# port_range_end = 39999
# container_hook_script = "/opt/rustguac/vdi-container-hook.sh"
# container_hook_timeout_secs = 10
home_base = "/vdi-homes"
# allowed_images = ["myregistry/desktop:latest"]

Environment variables#

Setting environment variables for systemd#

The shipped systemd unit (rustguac.service) does not include an EnvironmentFile directive by default. To provide secrets like VAULT_SECRET_ID and OIDC_CLIENT_SECRET, create a systemd drop-in override:

1. Create the env file with your secrets:

cat > /opt/rustguac/env <<'EOF'
VAULT_SECRET_ID=your-vault-secret-id
OIDC_CLIENT_SECRET=your-oidc-client-secret
EOF
chmod 600 /opt/rustguac/env
chown rustguac:rustguac /opt/rustguac/env

2. Create a systemd override to load the env file:

sudo systemctl edit rustguac

This opens an editor. Add the following:

[Service]
EnvironmentFile=/opt/rustguac/env

Save and close. This creates a drop-in file at /etc/systemd/system/rustguac.service.d/override.conf.

3. Reload and restart:

sudo systemctl daemon-reload
sudo systemctl restart rustguac

The override persists across package upgrades — dpkg will not overwrite files in the .d/ directory.

Verifying the environment#

To confirm the env file is loaded:

sudo systemctl show rustguac | grep EnvironmentFile

You should see:

EnvironmentFile=/opt/rustguac/env