Skip to content

AQtive Guard Configuration Reference🔗

Key Required? Type Description
ASSETS_AUTO_BUILD Internal, do not modify.
CS_ON_PREMISES bool Set to true for on-premise setups. Do not modify.
CS_LICENSE_SERVER Internal, do not modify.
DATABASE_SCHEMA str Set to use a custom database schema.

Default: "public"
DATABASE_URL yes str Set to a Postgres URL. See Database URL Section for a more detailed explanation.
DISABLE_HTTPS_REDIRECT bool Set to true to disable automatic redirection to HTTPS. This is useful if AQtive Guard is located behind a load balancer that handles SSL endpoint termination.

Default: false
LOG_FILE str Define a file to which logs should be written. If unset, logs are written to journalctl.
LOG_FILE_AUDIT str Define a file to which audit logs should be written. If unset, audit logs are written along with the rest of the logs.
LOG_LEVEL str Set logging level of the AQtive Guard instance. Possible values: "debug", "info", "warning", "error".

Default: "info"
LOG_LEVEL_AUDIT str Set logging level of audit logs for this instance. Possible values: "debug", "info", "warning", "error".

Default: "info"
LOG_ROTATE_DAILY bool If set to true and if LOG_FILE is set, then log files will be rotated every 24 hours. Logs continue being written to the file referenced in LOG_FILE. After the 24h period, old logs get moved to [original name].[timestamp]. Requires LOG_FILE to be set.
LOG_ROTATE_DAILY_AUDIT bool If set to true and if LOG_FILE_AUDIT is set, then audit log files will be rotated every 24 hours. Logs continue being written to the file referenced in LOG_FILE_AUDIT. After the 24h period, old logs get moved to [original name].[timestamp]. Requires LOG_FILE_AUDIT to be set.
LOG_ROTATE_MAX int, strictly greater than 0 If set, only LOG_ROTATE_MAX rotating log files will be kept. Old log files will be deleted. Requires LOG_FILE and LOG_ROTATE_DAILY to be set. If unset, log files will never be deleted.
LOG_ROTATE_MAX_AUDIT int, strictly greater than 0 If set, only LOG_ROTATE_MAX_AUDIT rotating audit log files will be kept. Old log files will be deleted. Requires LOG_FILE_AUDIT and LOG_ROTATE_DAILY_AUDIT to be set. If unset, log files will never be deleted.
REDIS_URL yes str URL to a redis instance. See Redis URL Section for a more detailed explanation.
S3_ENDPOINT yes str HTTP Endpoint of the storage solution.
S3_ENDPOINT_USE_EXTERNAL bool Caution: This option needs to be set to false if AQtive Guard uses a storage solution situated on a different machine. If the S3_ENDPOINT is pointing to anything other than localhost , then set this option to false!

Default: true
S3_TRACE_AWS_ACCESS_KEY_ID yes str The Access Key ID for the storage solution account.
S3_TRACE_AWS_SECRET_ACCESS_KEY yes str The Secret Access Key for the storage solution account.
S3_TRACE_BUCKET yes str The name of the bucket in which AQtive Guard should store its files.
S3_REGION str Set this option only if AQtive Guard is using AWS S3.
STORAGE_USE_PUT bool Set this option if AQtive Guard should use the PUT method to upload traces to the storage solution.

Note: StorageGRID only supports PUT upload.
STORAGE_EXTENDED_HEALTH_CHECK bool Set this option to enable storage health checks that do not use the HEAD method, but instead perform write, read and delete operations.
SECRET_KEY yes str Set this value to a random, hex-encoded string of at least 64 characters long. If AQtive Guard is installed in a high-availability setting, it is critical that all instances share the same SECRET_KEY.
SECRET_PROVIDER no str JSON-encoded secret manager parameters. See Secret Managers for a more detailed explanation.
SESSION_DURATION_SECONDS no int Timeout of the login session, in seconds. Default: 86400 (24h)
RATELIMIT_ENABLED bool Toggle the rate-limiter protection. It is recommended to leave this option active.

Default: true
OIDC_DISCOVERY_URL only for OIDC str Discovery URL, meant for autoconfiguration of the OpenID endpoints. It generally look like https://your.id_provider.com/.well-known/openid-configuration.
OIDC_SERVER_CERT no str Path to SSL CA bundle (a file or directory) used to verify OpenID Servers (e.g. "/etc/web/cert.pem").

Default: If unset or the path is invalid, defaults to the SSL certificate used by the underlying OS.
OIDC_CLIENT_NAME only for OIDC str Name you assigned to AQtive Guard when you configured your identity server.
OIDC_SECRET only for OIDC str Secret password associated to AQtive Guard.
OIDC_USE_PING_FEDERATE bool Set this to true the identity provider is PingFederate.

Default: false
OIDC_BUTTON_LABEL str Text that will be displayed on the SSO login button.

Default: "Log in with OpenID"
OIDC_DEFAULT_ORG_ID only for OIDC int The ID of the default organization a user identified by the SSO will belong to.
OIDC_RESOURCE str Optional parameter that hints the role claim(s) to be included in the Access Token upon successful user authentication. Set this if required by the identity provider.
GUNICORN_NUM_WORKERS int Number of gunicorn workers.

Default: 2.
GUNICORN_NUM_THREADS int Number of gunicorn gthreads instantiated within a gunicorn worker.

Default: 4.
GUNICORN_SSL_CERT_FILE str (Not recommended) Full path to SSL certificate file in PEM file format. Setting this option will start application web server with TLS enabled, which is not required in normal operation.

This parameter is mutually exclusive with `GUNICORN_SSL_KEYSTORE_FILE`, and can be set in the configuration file or passed as the environment variable.
GUNICORN_SSL_KEYSTORE_FILE str (Not recommended) Full path to KeyStore in PKCS12 file format. This will start application web server with TLS enabled, not required in normal operation.

This option is mutually exclusive with `GUNICORN_SSL_KEY_FILE`, and can be set in the configuration file or passed in the environment variable.
GUNICORN_SSL_KEY_FILE str (Not recommended) Full path to SSL private key file, if not included in the `GUNICORN_SSL_CERT_FILE` or `GUNICORN_SSL_KEYSTORE_FILE` files. Not required in normal operation.

This parameter can be set in the configuration file or environment variable.
GUNICORN_SSL_KEY_PASSWORD str Optional password for decrypting SSL private key. This parameter is used for decrypting private key supplied in `GUNICORN_SSL_CERT_FILE`, `GUNICORN_SSL_KEYSTORE_FILE` or `GUNICORN_SSL_KEY_FILE`.

This parameter can be set in the configuration file or environment variable.
GUNICORN_SSL_CA_CERTS_FILE str (Not recommended) Full path to SSL CA certificate file for client certificate validation. It is only used when the application web server is running with TLS enabled. Not required in normal operation.

This parameter can be set in the configuration file or environment variable.
ENABLE_GQL_OPERATION_LOGGING bool Whether to log the failed operation when a GraphQL operation fails. To avoid leaking any privileged information, the operation will have all constant values removed.

Default: true.
ENABLE_EXCEPTION_TRACE_LOGGING bool Whether to log the stack trace of any exception associated with a log message.

Default: true.

Database URL🔗

The database URL follows URL formatting. A basic form without authentication might be "postgresql://<host>/<database>".

To set a username and password, use basic auth:

"postgresql://<user>:<password>@<host>/<database>"

The username and password must be URL-encoded.

A custom port can be passed in the <host> value:

"postgresql://<hostname>:5431/<database>"`

To enforce SSL verification, use the sslmode=required option, following the URL arguments syntax:

"postgresql://<host>/<database>?sslmode=require"

Available options are:

  • disable: Disable SSL
  • allow: Allow SSL, but favor cleartext connections.
  • prefer: Favor SSL, but allow cleartext connections.
  • require: Require SSL, but do not verify certificates .
  • verify-ca: Require SSL, validate certificates against the local trust OS store.
  • verify-full: Require SSL, validate certificate against the provided root CA.

For more extensive option documentation, refer to the official JDBC postgres documentation.

Redis URL🔗

The Redis URL follows URL formatting. A basic URL without authentication might be "redis://<host>".

A username and password can be provided using the basic auth syntax:

"redis://<username>:<password>@<host>"

The username and password must be URL-encoded. Even if the username is empty, the colon in front of the password must be kept.

A custom port can be passed in the <host> value:

"redis://<hostname>:1234/"

SSL can be enabled by using the rediss protocol:

"rediss://<host>/"

AQtive Guard does not allow for custom certificates for the Redis connection; the OS trust store will be used for CA verification.

Configuration in a high-availability setting🔗

It is strongly recommended to use the identical configuration file for all AQtive Guard machines in a high-availability setting.

Secret Manager configuration🔗

AQtive Guard can fetch secret values from a secret manager instead of storing them in the configuration file.

To enable a secret manager, set the SECRET_PROVIDER configuration key to a JSON-encoded object, with 3 keys:

  • provider: the name of the provider (such as "aws").
  • config: an object containing all the specific keys required by the secret provider.
  • labels: an object with all the configuration keys that should contain a secret value. Each key is mapped to either:

    • a label (string) of the secret stored inside the secret provider, OR
    • an object {label: str, encoding: str} where label is the secret stored inside the secret provider, and encoding specifies the secret encoding type (“RAW”, “URL”, “JSON”, or “UNICODE”).

      • If no encoding is provided, RAW is used and no transformations are done to the secret.
      • If encoding is set to URL or UNICODE, the string will be decoded in the corresponding format after being fetched from the secret provider.

        • JSON encoding is designed to support Amazon RDS credentials managed by AWS Secrets Manager but may work for other use cases. It assumes the secret will be a JSON string with two top-level keys, “username” and “password”.
        • If JSON is specified and the JSON string cannot be decoded, or if these top-level keys are missing from the decoded JSON object, a ConfigError error is raised.
        • If an invalid encoding is specified, an UnsupportedConfigValue error is raised.

          Caution

          Rotating a managed database secret while AQtive Guard is running may result in brief service interruptions to the user. AQtive Guard will detect password authentication failures to the database, and attempt to retrieve a new secret from the configured secret manager for subsequent database connections.

AWS Secrets Manager: a real-life example🔗

Use the following to configure AQtive Guard to use AWS Secrets Manager to fetch the database password (unicode-encoded), redis password (raw string), and SECRET_KEY (raw string, default):

JSON
{
    "provider": "aws",
    "labels": {
        "DATABASE_URL": {"label": "sandboxaq/database", "encoding": "unicode"},
        "REDIS_URL": {"label": "sandboxaq/redis", "encoding": "raw"},
        "SECRET_KEY": "sandboxaq/secret-key",
    },
    "config": {
        "region_name": "us-east-1",
    }
}

Note

Both "KEY": {"label": "some-label", "encoding": "raw"} and "KEY": "some-label" are equivalent and treat the secretId as a raw string.

The following keys can be specified in labels:

  • DATABASE_URL
  • REDIS_URL
  • SECRET_KEY
  • S3_TRACE_AWS_SECRET_ACCESS_KEY

Refer to AWS Secrets Manager integration for more information.

Secrets in URLs🔗

For passwords used in URLs, the secret is fetched from the secret provider and then merged into the URL specified in the configuration file. It is expected that the URL does not contain a password. Otherwise, the application will not start.

This covers:

  • DATABASE_URL
  • REDIS_URL

The following keys configure a redis instance at redis-host.com with the username user and the password p@sswordstored at label redis-password in the AWS Secrets Manager:

REDIS_URL=redis://user:@redis-host.com/
SECRET_PROVIDER={"provider":"aws","labels":{"REDIS_URL":"redis-password"}}

If the password is url-encoded, use the following label instead:

REDIS_URL=redis://user:@redis-host.com/
SECRET_PROVIDER={"provider":"aws","labels":{"label": "REDIS_URL":"redis-password", "encoding": "url"}}

Secret values🔗

For secret values, the secret is simply fetched for the secret provider. It is expected that no value is set for the configuration key in the configuration file. Otherwise, the application will not start.

This covers:

  • SECRET_KEY
  • S3_TRACE_AWS_SECRET_ACCESS_KEY

E.g. if the SECRET_KEY is stored in the AWS Secrets Manager at the label cap-secret-key, use the following configuration key:

SECRET_KEY=
SECRET_PROVIDER={"provider":"aws","labels":{"SECRET_KEY":"cap-secret-key"}}

AWS Secrets Manager integration🔗

To integrate the AWS Secrets Manager, use the "aws" provider. Secrets can be plaintext passwords or RDS credentials. The AWS Secrets Manager client will use IAM authentication when fetching secrets.

The following specific configuration keys are required:

  • "region_name": the region name of the AWS Secrets Manager instance, such as "us-east-1".

Refer to Secret Manager configuration for configuration details.

Example🔗

The following configures a user username and password Passw0rd on host database.company.com:

SECRET_KEY=
DATABASE_URL="postgresql://username:@database.company.com/sandboxaq"
SECRET_PROVIDER='{"provider":"aws", "config":{"region_name": "us-east-1"}, "labels":{"DATABASE_URL": "sandboxaq/database", "SECRET_KEY": "sandboxaq/secretkey"}}'

Inside the AWS Secrets Manager, add plaintext secrets:

label: "sandboxaq/database"
value: "Passw0rd"

label: "sandboxaq/secretkey"
value: "Th1sIsASecret"

When configuring DATABASE_URL to use Amazon RDS credentials, it is necessary to specify JSON encoding in SECRET_PROVIDER (see Secret Manager configuration). In this case, it is also unnecessary to specify the username in DATABASE_URL since it is included in the RDS credentials managed by AWS:

DATABASE_URL="postgresql://:@database.company.com/sandboxaq"
SECRET_PROVIDER='{"provider":"aws", "config":{"region_name": "us-east-1"}, "labels":{"DATABASE_URL": "sandboxaq/database", "encoding": "JSON", label": "rds!db-ffffffff-ffff-ffff-ffff-ffffffffffff"}}'