Environment variables
Excubius reads its installation settings from the .env file in the install directory, /opt/excubius/.env by default, mode 0600, owned by the service account. The installer writes it from your answers and generates the secrets once. This reference lists the keys you can set, grouped as in the file.
Most settings live in the console, not here: branding and feature switches in Settings › Instance, names and certificates in Settings › Server, sources in Settings › Sources, monitoring credentials in Settings › Credentials. After you change the file, restart the platform as the service account with systemctl --user restart excubius.
Back up the .env file, and with it EXCUBIUS_DATA_KEY. Without that key, the secrets stored in the database cannot be decrypted.
Installation
| Key | Default | Meaning |
|---|---|---|
EXCUBIUS_HOME | /opt/excubius | Install directory. Written by the installer |
SERVER_NAME | — | The primary name: the host of the public URL |
REGISTRY | ghcr.io/custorius-labs/excubius | Registry and repository prefix of the images |
PROXY_MODE | http | http or https. Applies only until the certificate service has taken over; afterwards Settings › Server decides |
COOKIE_SECURE | empty | Empty: session cookies are Secure whenever the request arrived over HTTPS. true or false force it. Leave it empty |
Names and TLS
These keys seed the TLS settings on the first start only, when the platform has none yet. From then on, names and certificates are managed in Settings › Server, without a restart. The installer removes the DNS credentials and the private key from the file once the platform has stored them.
| Key | Default | Meaning |
|---|---|---|
TLS_MODE | empty | letsencrypt_http, letsencrypt_dns, selfsigned, custom, gateway or http. The installer's names letsencrypt, letsencrypt-dns and later are accepted too |
TLS_ALIASES | empty | Other names users may open, separated by spaces |
TLS_CERT_NAMES | empty | Names to put in the certificate, separated by spaces. Empty: every name |
TLS_EMAIL | empty | E-mail of the Let's Encrypt account |
TLS_ACME_SERVER | production | staging to rehearse with test certificates that browsers do not trust |
TLS_DNS_PROVIDER | empty | The acme.sh dnsapi ID of the DNS provider, such as dns_cf or dns_azure |
TLS_DNS_CREDENTIALS | empty | KEY=VALUE pairs separated by new lines or ;, or base64:<…> |
TLS_CERT_FILE, TLS_KEY_FILE | empty | base64:<PEM contents> of your own certificate chain and private key |
TLS_ACME_DNSSLEEP | 0 | Seconds to wait for DNS propagation instead of checking it through public DNS-over-HTTPS resolvers. Use it on networks that cannot reach them |
Product
| Key | Default | Meaning |
|---|---|---|
PRODUCT_NAME | Excubius | Fallback only. The product name comes from the branding in Settings › Instance |
DEFAULT_LOCALE | en | Default language |
BASE_URL | — | The public URL, such as https://monitoring.example.com. Links in messages use it |
EXCUBIUS_DEFAULT_PRESET | enterprise | The preset the instance starts from: enterprise, databases or core |
EXCUBIUS_FEATURES_ENFORCE_API | false | true: switched-off features are also refused by the API. Default: they are hidden in the interface only |
Database and secrets
| Key | Default | Meaning |
|---|---|---|
POSTGRES_USER | excubius | Database user |
POSTGRES_PASSWORD | generated | Letters and digits only, because it is embedded in a connection URL |
POSTGRES_DB | excubius | Database name |
DATABASE_URL | built from the three above | Connection URL. The containers receive it built from the three keys above |
EXCUBIUS_DATA_KEY | generated | Key that encrypts the secrets stored in the database: credentials, source secrets, DNS API keys. 32 random bytes, URL-safe base64. Never change it on a running installation |
EXCUBIUS_COLLECTOR_TOKEN | generated | Shared secret between the collector and the API. Empty: the collector idles and the collector endpoints are disabled |
Sign-in
| Key | Default | Meaning |
|---|---|---|
JWT_SECRET | generated | Signs the session tokens. 64 random characters |
ACCESS_TOKEN_MINUTES | 15 | Lifetime of an access token |
REFRESH_TOKEN_DAYS | 14 | Lifetime of a session |
ENTRA_TENANT_ID, ENTRA_CLIENT_ID, ENTRA_CLIENT_SECRET | empty | Microsoft Entra ID sign-in, single tenant: the directory ID, not common or organizations. Offered once all three are set. Redirect URI: <BASE_URL>/api/v1/auth/entra/callback |
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET | empty | Google sign-in. Redirect URI: <BASE_URL>/api/v1/auth/google/callback |
ALLOWED_SIGNUP_DOMAINS | empty | E-mail domains, separated by commas, whose people get an account as viewer on the root at their first sign-in. Applies only until a registration mode is saved on the root entity. Empty: invitation only |
The client secrets are never stored in the database or logged.
Monitoring core
| Key | Default | Meaning |
|---|---|---|
EXCUBIUS_UNREACHABLE_AFTER | 3 | Consecutive connection, sign-in or timeout failures before a resource gets its Cannot reach alert |
EXCUBIUS_NOTIFY_QUIET_MINUTES | 10 | Minimum minutes between two messages for the same condition. A rising severity always goes out |
EXCUBIUS_COLLECTOR_VIA_PROXY | false | true only for a collector outside the server that reaches the API through the public address |
Collector
The collector container receives only these keys, never the whole file.
| Key | Default | Meaning |
|---|---|---|
EXCUBIUS_COLLECTOR_TOKEN | generated | See Database and secrets |
EXCUBIUS_COLLECTOR_TRANSPORTS | every transport present | Comma-separated subset to offer, such as tsql,http,dns. Values: tsql, http, dns, winrm, ssh, azure_graph, defender, entra, wazuh |
EXCUBIUS_COLLECTOR_CONCURRENCY | 32 | Checks running at once |
EXCUBIUS_TSQL_THREADS | 16 | Threads for SQL Server connections |
EXCUBIUS_SQL_APP_NAME | monitoring-collector | Application name of the collector's SQL Server sessions |
EXCUBIUS_ODBC_DRIVER | ODBC Driver 18 for SQL Server | ODBC driver name |
AZURE_SUBSCRIPTION_IDS | empty | Comma-separated subscriptions for the native Resource Graph checks (cloud security, Azure Update Manager) when the credential sets none. Empty: every subscription the identity can read. The Azure Monitor source has its own list |
AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET | empty | Empty: the server's managed identity. AZURE_CLIENT_ID alone names a user-assigned managed identity. All three: that service principal is used instead |
The collector also has settings for its polling intervals, batch and buffer sizes and host name, but the installed platform does not pass them to its container, so their defaults apply: assignments every 30 seconds, jobs every 10 seconds, a heartbeat every 60 seconds, 200 results per batch, 10,000 results kept while the API is unreachable.
Notifications and tickets
| Key | Default | Meaning |
|---|---|---|
SLACK_BOT_TOKEN | empty | Bot token of the Slack app, with the scope chat:write. Empty: nothing is sent to Slack |
SLACK_DEFAULT_CHANNEL | #alerts | Receives warnings and criticals when no entity on the path has a channel |
JIRA_BASE_URL | empty | https://<site>.atlassian.net |
JIRA_AUTH | token | token (e-mail and API token), oauth (client credentials of an Atlassian service account) or bearer |
JIRA_EMAIL, JIRA_API_TOKEN | empty | Credentials for token |
JIRA_OAUTH_CLIENT_ID, JIRA_OAUTH_CLIENT_SECRET | empty | Credentials for oauth |
JIRA_CLOUD_ID | empty | oauth only: the site's cloud ID |
JIRA_OAUTH_TOKEN_URL | https://auth.atlassian.com/oauth/token | Token URL for oauth |
JIRA_DEFAULT_PROJECT | empty | Project key for new issues |
JIRA_ISSUE_TYPE | Task | Issue type name in that project |
JIRA_SYNC_MINUTES | 10 | How often the status of open issues is read |
WEB_PUSH_VAPID_PUBLIC, WEB_PUSH_VAPID_PRIVATE | empty | Reserved for web push notifications, not available in this release. Leave them empty |
The Jira keys are defaults: each entity may override them in its own Jira settings. See Create Jira issues from alerts.
Updates and security worker
| Key | Default | Meaning |
|---|---|---|
EXCUBIUS_SECURITY_WORKER | true | The API's background worker: vendor feeds, risk acceptance expiry, checks run by the API, security score snapshots, Jira status. Set false only on extra API replicas |
EXCUBIUS_FEEDS_ENABLED | true | false: never fetch the vendor feeds, for air-gapped installations. The copies shipped with the release are used |
EXCUBIUS_FEED_TIMEOUT_SECONDS | 60 | Timeout per feed request |
EXCUBIUS_FEED_SQLSERVER_BUILDS_URLS | the dbatools site, then GitHub | Space-separated URLs of the SQL Server build list, tried in order. Put an internal mirror first |
EXCUBIUS_FEED_ENDOFLIFE_URL | https://endoflife.date/api | Base URL of the end-of-support feed |
EXCUBIUS_FEED_MSRC_URL | https://api.msrc.microsoft.com/cvrf/v3.0 | Base URL of the Microsoft security advisories |
EXCUBIUS_FEED_MSRC_MONTHS | 3 | Monthly releases kept up to date, from 1 to 24 |
HTTPS_PROXY | empty | Proxy for the feed requests |
Keys this release does not read
The shipped .env.example still lists NEWRELIC_API_KEY, NEWRELIC_ACCOUNT_ID, NEWRELIC_WEBHOOK_SECRET, NINJAONE_CLIENT_ID, NINJAONE_CLIENT_SECRET, NINJAONE_REGION, WAZUH_API_URL, WAZUH_API_USER and WAZUH_API_PASSWORD. This release ignores them. Configure New Relic and NinjaOne in Settings › Sources, and Wazuh with a credential and the check's parameters; see Sources and Cloud security.