Keycyte PAM 3.2 · Deployment Guide
Configuration Reference
The PAM server reads its settings from environment variables and, optionally, from a config.yaml file. In a deployment from the installation package, the settings are environment variables that docker-compose.yml passes to the pam container, mostly from the .env file.
How Settings Are Read
- Environment variables. Every setting has an environment variable:
KEYCYTE_followed by the setting path in upper case, with dots replaced by underscores. For example,session.timeoutisKEYCYTE_SESSION_TIMEOUT. config.yaml. The PAM server looks forconfig.yamlin its working directory (/appin the container, which is~/keycyteon the host) and in/etc/keycyte/. The file is optional; if it is not found, the PAM server logs a warning and uses environment variables and defaults.- Precedence. Environment variables take precedence over
config.yaml, andconfig.yamltakes precedence over the built-in defaults.
To change a setting in a deployment from the installation package, edit the value in .env (or in docker-compose.yml if it is set there), and recreate the containers in the package folder:
sudo docker compose --env-file .env -f docker-compose.yml up -dWarning
The .env file contains secrets. Never copy secret values into tickets, documentation or chat, and keep a secure copy of the file.
In the tables below, Default is the built-in default of the PAM server. Package shows the value that the installation package sets, where it differs. Settings marked Required must be set; the PAM server does not start without them.
Server and TLS
| Variable | config.yaml key | Default | Description |
|---|---|---|---|
KEYCYTE_SERVER_PORT | server.port | 8443 | HTTPS port inside the container. Package: 443. |
KEYCYTE_SERVER_TLS_ENABLED | server.tls.enabled | true | Serve HTTPS. |
KEYCYTE_SERVER_TLS_KEYSTORE | server.tls.keystore | empty | Path of the PKCS#12 keystore used when no certificate was applied in the Admin Panel. Package: /app/localhost.p12 (from TLS_KEYSTORE_PATH). |
KEYCYTE_SERVER_TLS_PASSWORD | server.tls.password | empty | Password of the PKCS#12 keystore (from TLS_KEYSTORE_PASSWORD). |
KEYCYTE_SERVER_TLS_SUPPRESS_CLIENT_ERRORS | server.tls.suppress_client_errors | true | Do not log TLS handshake errors caused by clients. |
KEYCYTE_SERVER_CORS_ALLOWED_ORIGINS | server.cors.allowed_origins | empty | Comma-separated list of origins (for example https://portal.example.com) allowed to call the API from another site. Empty disables cross-origin requests. * is not allowed. |
Database
| Variable | config.yaml key | Default | Description |
|---|---|---|---|
KEYCYTE_DATABASE_HOST | database.host | 127.0.0.1 | PostgreSQL host. Package: postgres (the database container), from DB_HOST. |
KEYCYTE_DATABASE_PORT | database.port | 5432 | PostgreSQL port (from DB_PORT). |
KEYCYTE_DATABASE_NAME | database.name | keycytedb | Database name (from DB_NAME). |
KEYCYTE_DATABASE_USERNAME | database.username | empty | Required. Database user (from DB_USER). |
KEYCYTE_DATABASE_PASSWORD | database.password | empty | Required. Database password (from DB_PASSWORD). |
KEYCYTE_DATABASE_SSLMODE | database.sslmode | disable | PostgreSQL SSL mode, for example disable, require, verify-full (from DB_SSLMODE). |
KEYCYTE_DATABASE_MAX_OPEN_CONNS | database.max_open_conns | 25 | Maximum open connections per PAM node. |
KEYCYTE_DATABASE_MAX_IDLE_CONNS | database.max_idle_conns | 10 | Maximum idle connections per PAM node. |
Tip
In a deployment with several nodes, the connection limits apply to each node. Make sure that the total stays below the max_connections setting of PostgreSQL.
Encryption Key
The encryption key protects secrets stored in the database (vault passwords, keys, provider credentials), backup files and session recordings. Required: set exactly one of the following sources. The PAM server does not start without a key.
| Variable | config.yaml key | Default | Description |
|---|---|---|---|
KEYCYTE_KEYSTORE_KEY_HEX | keystore.key_hex | empty | AES key as a hexadecimal string. Package: from KEYSTORE_KEY_HEX. |
KEYCYTE_KEYSTORE_KEY_BASE64 | keystore.key_base64 | empty | AES key as a Base64 string. |
KEYCYTE_KEYSTORE_KEY_FILE | keystore.key_file | empty | Path of a file that contains the raw key (16, 24 or 32 bytes). |
KEYCYTE_KEYSTORE_PATH | keystore.path | empty | Path of a Java PKCS#12 keystore that holds the key (for keys migrated from earlier versions). |
KEYCYTE_KEYSTORE_PASSWORD | keystore.password | empty | Password of the keystore in keystore.path. |
KEYCYTE_KEYSTORE_ALIAS | keystore.alias | keycyte | Alias of the key in the keystore. |
If more than one source is set, the PAM server uses the first one in the order of the table.
Warning
Never change the encryption key of an existing deployment. Data encrypted with the old key, including backups and recordings, can no longer be decrypted. All nodes of a deployment must use the same key.
Session
| Variable | config.yaml key | Default | Description |
|---|---|---|---|
KEYCYTE_SESSION_SECRET_KEY | session.secret_key | built-in value | Required. Secret that signs session cookies. Must be at least 32 bytes long and must not be the built-in value; otherwise the PAM server refuses to start. Create one with openssl rand -base64 48. Package: from SESSION_SECRET_KEY. |
KEYCYTE_SESSION_TIMEOUT | session.timeout | 30m | Idle timeout of a sign-in session. Every request extends it. Package: from SESSION_TIMEOUT. |
KEYCYTE_SESSION_COOKIE_NAME | session.cookie_name | KEYCYTESESSION | Base name of the session cookie. With the host prefix enabled, the cookie is sent as __Host-<name>. Package: from SESSION_COOKIE_NAME. |
KEYCYTE_SESSION_USE_HOST_PREFIX | session.use_host_prefix | true | Add the __Host- prefix to the cookie name. This forces a secure cookie and clears the cookie domain. |
KEYCYTE_SESSION_COOKIE_SECURE | session.cookie_secure | true | Send the cookie only over HTTPS. |
KEYCYTE_SESSION_COOKIE_SAME_SITE | session.cookie_same_site | lax | SameSite attribute: lax, strict or none. none requires a secure cookie. Package: none. |
KEYCYTE_SESSION_COOKIE_DOMAIN | session.cookie_domain | empty | Cookie domain. Ignored while the host prefix is enabled. |
KEYCYTE_SESSION_SINGLE_DEVICE | session.single_device | false | Allow only one active sign-in session per user. A new sign-in signs the user out everywhere else. |
MFA Lockout
| Variable | config.yaml key | Default | Description |
|---|---|---|---|
KEYCYTE_MFA_MAX_FAILED_ATTEMPTS | mfa.max_failed_attempts | 5 | Failed MFA verifications after which the account is locked. |
KEYCYTE_MFA_LOCKOUT_DURATION_MIN | mfa.lockout_duration_min | 15 | Minutes the account stays locked after too many failed MFA verifications. Applies to all user types. |
Files, Recordings and Gateway
| Variable | config.yaml key | Default | Description |
|---|---|---|---|
KEYCYTE_UPLOAD_MAX_FILE_SIZE | upload.max_file_size | 4GB | Maximum size of a file transferred in a browser session. |
KEYCYTE_UPLOAD_STORAGE_PATH | upload.storage_path | /drive | Storage folder for transferred files. Package: /app/uploads. |
KEYCYTE_RECORDING_PATH | recording.path | /recordings | Folder for session recordings. Package: /record (the ~/record host directory). |
KEYCYTE_GATEWAY_ADDRESS | gateway.address | 127.0.0.1 | Address of the gateway (guacd). Package: guacd. |
KEYCYTE_GATEWAY_PORT | gateway.port | 4822 | Port of the gateway. |
LDAP TLS
| Variable | config.yaml key | Default | Description |
|---|---|---|---|
KEYCYTE_LDAP_CA_CERT | ldap.ca_cert | /app/certs/ldap-ca.pem | PEM file with the CA certificates trusted for LDAP over TLS. Certificates trusted from the Admin Panel are also stored here. Package: /app/cacerts.pem (from LDAP_CA_CERT). |
KEYCYTE_LDAP_INSECURE_SKIP_VERIFY | ldap.insecure_skip_verify | false | Skip verification of LDAP server certificates. Do not use in production (from LDAP_INSECURE). |
The Password Manager container receives the same two values as LDAP_CA_CERT and LDAP_INSECURE_SKIP_VERIFY.
Proxies and Access Keys
These variables have no config.yaml key; set them as environment variables. For their meaning and rotation, see Service Access Keys.
| Variable | Default | Description |
|---|---|---|
KEYCYTE_SSH_PROXY_ACCESS_KEY_ID, KEYCYTE_SSH_PROXY_ACCESS_KEY_SECRET | empty | Access key of the SSH proxy. |
KEYCYTE_RADIUS_SERVER_ACCESS_KEY_ID, KEYCYTE_RADIUS_SERVER_ACCESS_KEY_SECRET | empty | Access key of the RADIUS server. |
KEYCYTE_PAM_ACCESS_KEY_ID, KEYCYTE_PAM_ACCESS_KEY_SECRET | empty | Access key the PAM server uses toward the SSH proxy. |
KEYCYTE_SSH_PROXY_WS_URL | ws://ssh-proxy:8443 | Internal WebSocket address of the SSH proxy. |
KEYCYTE_DOCKER_PROJECT | empty | Docker Compose project name. When set, Settings > Services lists only the containers of this project; otherwise it lists all containers on the host. |
DOCKER_HOST | — | Docker socket used by Settings > Services. Package: unix:///var/run/docker.sock. |
Native RDP Launch
These variables have no config.yaml key. Native RDP launch is disabled unless the URL, public address and access key are all set.
| Variable | Default | Description |
|---|---|---|
KEYCYTE_RDP_PROXY_URL | empty | Internal address of the RDP proxy control API. Package: http://rdp-proxy:7171. |
KEYCYTE_RDP_PROXY_PUBLIC_ADDRESS | empty | host:port of the RDP proxy as user workstations reach it, written into the .rdp file, for example pam.example.com:3389. |
KEYCYTE_RDP_PROXY_ACCESS_KEY_ID, KEYCYTE_RDP_PROXY_ACCESS_KEY_SECRET | empty | Access key for the RDP proxy. |
KEYCYTE_RDP_LAUNCH_TOKEN_TTL_SECS | 120 | Lifetime of the single-use connection token, in seconds. |
Logging
| Variable | config.yaml key | Default | Description |
|---|---|---|---|
KEYCYTE_LOG_LEVEL | log.level | info | Log level at startup: debug, info, warn or error. A log level saved on Settings > General (Log Level) overrides it and can be changed without a restart. |
KEYCYTE_LOG_FORMAT | log.format | text | text (readable) or json (for log collectors). |
KEYCYTE_LOG_SOURCE | log.source | false | Add the source file and line to every log line. |
Installation Package Variables
The .env file of the installation package also contains variables that are used by docker-compose.yml and by the other containers, not directly by the PAM server.
| Variable | Set by | Description |
|---|---|---|
PRIMARY_DNS, SECONDARY_DNS | Installer | DNS servers of all containers. |
DOCKER_GID | Installer | Group ID of the host’s docker group. |
KEYCYTE_BASE, KEYCYTE_DRIVE, KEYCYTE_RECORD | Installer | Host directories ~/keycyte, ~/drive, ~/record. |
RUN_UID, RUN_GID | Installer | User and group ID the containers run as. |
TZ | Package | Time zone of all containers. |
SSH_IDLE_TIMEOUT | Package | Idle timeout of SSH proxy sessions. |
DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD, DB_SSLMODE | Package | Database connection of the PAM server and the SSH proxy. |