Configuration Options

Configuration File

Xylok reads configuration data from /etc/xylok/xylok.toml, which uses the TOML format. After any configuration changes, the configuration should be reloaded by running:

sudo systemctl restart xylok

If you are upgrading from a version that used the legacy /etc/xylok.conf format, Xylok will automatically migrate your settings to xylok.toml on first startup, preserving a backup of the original file as /etc/xylok.conf.bak. See Active Directory Login for additional notes on migrating authentication settings.

Common Configuration Options

The most common options are covered below. Other configuration items may appear in your configuration, but should generally only be changed at the direction of Xylok support. Your installed xylok.toml contains the full set of available options and an example configuration is at the bottom of this page, with commments on every configuration item.

Top-level options:

postgres_password: Password to use to connect to the database for the default “postgres” user. This defaults to a generated password when Xylok is first installed and is unique to your installation. If changed, ensure the Postgres database is updated as well.
enable_unready_versions: If true, will allow the use of benchmark versions that Xylok has not finalized testing commands for. Enabling this may result in scripts that do not work properly.
control_set: Defaults to rmfrev4, using the NIST 800-53 rev 4 control set. May be swapped to rmfrev5 to use Rev 5.

Options in the [http] section:

http_only: If true, disables listening on the HTTPS port and allows all calls to happen over HTTP. Useful if running Xylok behind a reverse proxy which is already terminating HTTPS.
http_port: Port to listen for HTTP connections on.
https_port: Port to listen for HTTPS connections on. If changed from the default 443, automatic redirects from HTTP to HTTPS will no longer work correctly.
allowed_domains: A TOML array of domains which this server will respond to and generate HTTPS certificates for, for example allowed_domains = ["example.com", ".*\\.internal"]. All entries are treated as Go regular expressions, using the regexp.Match function. Regardless of this setting, “host less” requests are always allowed to allow internal requests to work. If not given or empty, all domains will be allowed.
fixed_certificate_path and fixed_key_path: Paths to a TLS certificate and private key to serve HTTPS with, instead of an automatically generated certificate.

Options in the [logging] section:

verbosity: Increase to 1 (debug) or 2 (trace) to show extra detail, such as stack traces in error messages, to assist when contacting Xylok Support. Publicly available installs may wish to keep this at 0 for security reasons.
log_requests: If true (the default), each HTTP request is logged as it arrives. Set to false to silence request logging entirely.
log_responses: Controls which HTTP responses are logged: "errors" (the default) logs only responses with a status code of 400 or higher, "all" logs every response, and "none" disables response logging.
log_sql: If true, all SQL statements are logged. Very verbose; use only for debugging.

Options in the [smtp] section control email-based password recovery. Set use = true to enable it, and configure the connection with:

email_from: email address to use for “From” header in emails
email_host: SMTP server to connect to
email_port: Port number on SMTP server to use
email_host_user: Username on SMTP server
email_host_password: Password on SMTP server

Security Options

Xylok offers several configuration options to optionally lock down the containers further. First, CPU and memory limits can be imposed. Memory limits follow the values for the Docker flag --memory, and impose a strict upper limit on the memory that specific container can consume. CPU limits follow the values for the Docker flag --cpu-shares, ranging from 0 to 1024, where 1024 is “100%” of the available CPU and anything less is a proportion of 100%. The exact key names in the xylok.toml file are below, along with any specific recommendations. More details can be found in the Security article.

Options in the [limits] section:

memory: Not recommended to go below 2048Mb
cpu_shares: Limiting CPU will have some of the largest impact on Xylok’s performance, so this should be kept as high as reasonable.

Options in the [http] section:

bind_ip: IP of interface for Xylok to listen on. If not given, Xylok will bind to all interfaces.
banner: If set, Xylok will require the user to read and agree to the banner specified. To include newlines, use \n

Options in the [session] section:

length: Maximum user session length in seconds. If 0, sessions expire at the end of the browser session. Defaults to 2 weeks.
expire_at_browser_close: Terminate session when user closes their browser window.

Xylok optionally supports login via Active Directory and other OIDC providers. Authentication settings are stored in the [authentication] and [oidc] sections of xylok.toml. For more details please see Active Directory Login.

Example Configuration

Below is a complete example xylok.toml with a comment explaining each key. Values shown are the defaults unless noted otherwise.

# Path to write CPU profiling data to, for use when troubleshooting performance with Xylok Support
cpu_profiling_path = ""

# Container engine to use ("docker" or "podman"). If not set, Xylok will autodetect the correct setting, defaulting to docker if both are available
container_engine = ""

# Whether this server is running in development mode. Do not enable in production
dev_mode = false

# Automatically start the Xylok container if it is not already running
auto_start_container = true

# Automatically stop the Xylok container when the server quits
auto_stop_container = true

# Run the Xylok container with a read-only root filesystem
container_read_only = true

# Secret used for generating session IDs. Generated randomly on first install; keep private
secret_key = "change-me"

# Password for the default "postgres" database user. Generated randomly on first install
postgres_password = "change-me"

# Base directory of the Xylok installation
install_dir = "/opt/xylok"

# Directory used for passing data in and out of the container
passthrough_dir = "/opt/xylok/_passthrough"

# Base directory for Xylok data
data_dir = "/var/lib/xylok"

# Base directory for Xylok logs
log_dir = "/var/log/xylok"

# Directory containing check-level post-processing script overrides
pp_overrides_dir = "/etc/xylok/pp-overrides"

# Operating system user the server should run as
user_name = "xylok"

# Control set to use: "rmfrev4" (NIST 800-53 rev 4) or "rmfrev5"
control_set = "rmfrev4"

# Features enabled by your license. Normally managed automatically; do not edit by hand
features = []

# Allow use of benchmark versions that Xylok has not finalized testing commands for
enable_unready_versions = false

# SMTP settings, used for password recovery via email
[smtp]
# Enable SMTP for password recovery
use = false
# Email address to use for the "From" header in emails
email_from = ""
# SMTP server to connect to
email_host = ""
# Port number on the SMTP server
email_port = ""
# Username on the SMTP server
email_host_user = ""
# Password on the SMTP server
email_host_password = ""

# User session settings
[session]
# Maximum session length in seconds. 0 expires sessions at the end of the browser session regardless of the length of that session. Defaults to 2 weeks (1209600)
length = 1209600
# Terminate the session when the user closes their browser window
expire_at_browser_close = false

# Authentication settings
[authentication]
# Primary domain that the identity provider will use for sending back credentials
login_host = ""

# OIDC login settings. See the Active Directory Login article for details
[oidc]
# Enable login via OIDC
use = false
# OIDC issuer URL (e.g. a Keycloak realm URL)
issuer = ""
# OIDC client ID
client_id = ""
# OIDC client secret
client_secret = ""
# Claim to use as the username (e.g. preferred_username, email, upn)
username_claim = "preferred_username"
# Claim to use for group membership (e.g. groups, roles)
groups_claim = "groups"
# Groups that grant superuser access
group_mapping_is_super = []
# Groups that grant staff access
group_mapping_is_staff = []
# Use TLS when connecting to the OIDC provider
enable_tls = true
# Skip verification of the OIDC provider's certificate. Not recommended in production
skip_cert_verification = false
# Custom CA certificate (PEM encoded) for the OIDC provider
ca_certificate = ""
# Original filename of the uploaded custom CA certificate
ca_certificate_name = ""
# Upload date of the custom CA certificate
ca_certificate_upload_date = ""

# Resource limits for the Xylok container. Note that this limits only the container, not the /opt/xylok/xylok binary
# being run by systemd
[limits]
# Maximum memory the container may consume (Docker --memory). Not recommended below 2048Mb
memory = ""
# CPU shares for the container (Docker --cpu-shares), 0-1024 where 1024 is 100% of available CPU
cpu_shares = 0

# Logging settings
[logging]
# Log verbosity: 0 = info, 1 = debug, 2 = trace
verbosity = 0
# Log format: 1 = human-readable text, 0 = JSON. Configurations migrated from the legacy xylok.conf use JSON under systemd
format = 1
# Log all SQL statements. Very verbose; use only for debugging
log_sql = false
# Include the source file and line that produced each log message
caller = false
# Log each HTTP request as it arrives
log_requests = true
# Which HTTP responses to log: "none", "errors" (only 4xx/5xx responses), or "all"
log_responses = "errors"
# URLs to exclude from request logging (Go regular expressions)
exclude_urls = []

# HTTP/HTTPS server settings
[http]
# Allow search engines to index this server
allow_search_indexing = false
# IP of the interface to listen on. "0.0.0.0" binds to all interfaces
bind_ip = "0.0.0.0"
# Disable HTTPS and serve all traffic over HTTP. Useful behind a reverse proxy that terminates HTTPS
http_only = false
# Port to listen for HTTP connections on
http_port = 80
# Port to listen for HTTPS connections on. Changing from 443 breaks automatic HTTP-to-HTTPS redirects
https_port = 443
# Domains this server will respond to and generate certificates for (Go regular expressions). Empty allows all domains
allowed_domains = []
# Path to a fixed TLS certificate, instead of an automatically managed certificate
fixed_certificate_path = ""
# Path to the private key for the fixed TLS certificate
fixed_key_path = ""
# Login banner the user must agree to before using the server. Use \n for newlines or TOML multiline strings (triple single quotes, typically)
banner = ""

# Automatic certificate management (ACME/Let's Encrypt) settings
[http.acme]
# ACME server to use for certificate requests
server = ""
# Email address to register with the ACME server
email = ""