Version: 1.10

Server Configuration

This section defines all required settings that are needed to run the Nauthilus server.

Basic Server Settings

server::address

Default: "127.0.0.1:9080"

This is the IPv4 or IPv6 addresses combined with a TCP port.

server:
  address: "[::]:9443"

server::max_concurrent_requests

Default: 100

This setting defines the maximum number of concurrent requests that can be processed by the server.

server:
  max_concurrent_requests: 200

server::max_password_history_entries

Default: 0

This setting defines the maximum number of password history entries to store for each user.

server:
  max_password_history_entries: 10

server::haproxy_v2

Default: false

If this setting is turned on (true), Nauthilus can make use of the HAproxy version 2 protocol header to identify the original client request.

server:
  haproxy_v2: true

server::http3

Default: false

Enable HTTP/3 support for the server. There does not exist the PROXY protocol for this version!

server::disabled_endpoints

New in version 1.4.9
Default: All endpoints are enabled

It is possible to disable certain HTTP location endpoints that are not needed.

server:
  disabled_endpoints:
    auth_header: false
    auth_json: false
    auth_basic: false
    auth_nginx: false
    auth_saslauthd: false
    auth_jwt: false
    custom_hooks: false
    configuration: false    # Available from version 1.7.11

tip

Disableing unused endpoints may enhance overall security!

Meaning

Key-name	location	description
auth_header	/api/v1/auth/header	Turn off requests based on HTTP headers
auth_json	/api/v1/auth/json	Turn off HTTP JSON-POST requests
auth_basic	/api/v1/auth/basic	Turn off HTTP Basic Authorization requests (recommended!)
auth_nginx	/api/v1/auth/nginx	Turn off Nginx based requests used by the mail plugin of Nginx
auth_saslauthd	/api/v1/auth/saslauthd	Turn off saslauthd requests used with cyrus-sasl
auth_jwt	/api/v1/jwt/*	Turn off JWT authentication endpoints
custom_hooks	/api/v1/custom/*	Turn off all Lua based custom hooks
configuration	/api/v1/config/*	Turn off all configuration related endpoints

HTTP Client Configuration

server::http_client

Whenever Nauthilus is acting as an HTTP client, a common shared Go-builtin HTTP client is used to handle all requests.

There do exist the following HTTP clients in Nauthilus:

Scope	Usage
core	If the Ory hydra frontend is turned on, all admin-API requests are handled by this client
action	Used for Lua actions, if HTTP requests are used
filter	Used for Lua filters, if HTTP requests are used
feature	Used for Lua featuress, if HTTP requests are used
hook	Used for Lua custom hooks, if HTTP requests are used

Settings are shared with all HTTP clients!

Setting	Meaning (Used from official Go docs)	Default
max_connections_per_host	Limits the total number of connections per host, including connections in the dialing, active, and idle states. On limit violation, dials will block.	0, no limits
max_idle_connections	Controls the maximum number of idle (keep-alive) connections across all hosts.	0, no limits
max_idle_connections_per_host	Controls the maximum idle (keep-alive) connections to keep per-host.	0, no limits
idle_connection_timeout	Is the maximum amount of time an idle (keep-alive) connection will remain idle before closing itself.	0, no limits
proxy	HTTP proxy URL to use for client connections. New in version 1.7.11	"", no proxy
tls	TLS configuration for the HTTP client. New in version 1.7.11	See below

Units for the timeout option should add a time unit like

s - seconds
m - minutes
h - hours

server:
  http_client:
      max_connections_per_host: 10
      max_idle_connections: 5
      max_idle_connections_per_host: 1
      idle_connection_timeout: 60s
      proxy: "http://proxy.example.com:8080"
      tls:
        skip_verify: false

Timeouts

New in version 1.10.0

Global, operation-specific timeouts for selected subsystems. Values use Go's duration format (e.g., 500ms, 2s, 1m30s).

server:
  timeouts:
    redis_read: 1s          # Timeout for Redis read operations (GET, HGET, etc.). Default: 1s
    redis_write: 2s         # Timeout for Redis write operations (SET, HSET, etc.). Default: 2s
    ldap_search: 3s         # Timeout for LDAP search operations. Default: 3s
    ldap_bind: 3s           # Timeout for LDAP bind/auth operations. Default: 3s
    ldap_modify: 5s         # Timeout for LDAP modify operations. Default: 5s
    singleflight_work: 3s   # Budget for the leader's work during in-process deduplication. Default: 3s
    lua_backend: 5s         # Timeout for Lua backend operations. Default: 5s

Notes

These are client-side timeouts applied by Nauthilus when talking to external systems or running local subsystems.
All fields are optional; if omitted or set to a non-positive duration, the defaults shown above are used.
singleflight_work caps the time the leader performs a deduplicated operation before giving up; followers will see a cancellation/timeout if this budget is exceeded.

Keys and defaults

server::timeouts::redis_read — Default: 1s
server::timeouts::redis_write — Default: 2s
server::timeouts::ldap_search — Default: 3s
server::timeouts::ldap_bind — Default: 3s
server::timeouts::ldap_modify — Default: 5s
server::timeouts::singleflight_work — Default: 3s
server::timeouts::lua_backend — Default: 5s

TLS Configuration

server::tls

This object defines TLS related settings.

server::tls::enabled

Default: false

This flag turns on (true) TLS support in the server.

server:
  tls:
    enabled: true

server::tls::cert and server::tls::key

Default: ""

These two settings define a path to an X509 PEM-formatted certificate and key.

server:
  tls:
    cert: /usr/local/etc/nauthilus/localhost.localdomain.pem
    key: /usr/local/etc/nauthilus/localhost.localdomain.key.pem

server::tls::skip_verify

Default: false
New in version 1.7.11

This flag turns on (true) insecure TLS connections by skipping client certificate verification.

server:
  tls:
    skip_verify: true

server::tls::http_client_skip_verify

Default: false
Deprecated: Use server::http_client::tls::skip_verify instead

This flag turns on (true) insecure TLS connections for HTTP(s) requests that are originating from Nauthilus to some remote.

server:
  tls:
    http_client_skip_verify: true

server::tls::min_tls_version

Default: "TLS1.2"
New in version 1.7.11

This setting defines the minimum TLS version that the server will accept. Valid values are "TLS1.2" and "TLS1.3".

server:
  tls:
    min_tls_version: "TLS1.3"

server::tls::ca_file

Default: ""
New in version 1.7.11

This setting defines the path to a CA certificate file in PEM format. This is used to verify client certificates when mutual TLS authentication is enabled.

server:
  tls:
    ca_file: /usr/local/etc/nauthilus/ca.pem

server::tls::cipher_suites

Default: []
New in version 1.7.11

This setting defines a list of cipher suites that the server will use for TLS connections. If not specified, the default Go cipher suites will be used.

server:
  tls:
    cipher_suites:
      - "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384"
      - "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"
      - "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256"

Authentication Configuration

server::basic_auth

This object defines basic authorization settings.

server::basic_auth::enabled

Default: false

This flag turns on (true) Basic Auth support in the server.

server::basic_auth::username and server::basic_auth::password

Default: ""

These settings define a username and its password that is required by HTTP(s) clients to communicate with Nauthilus. The password must be at least 16 characters long and can contain alphanumeric characters and symbols, but no spaces.

server::jwt_auth

This object defines JWT (JSON Web Token) authentication settings. JWT authentication provides a more secure and flexible alternative to HTTP Basic Authentication.

When enabled, Nauthilus provides the following JWT endpoints:

Token Generation: POST /api/v1/jwt/token - Generate a new JWT token with username and password
Token Refresh: POST /api/v1/jwt/refresh - Refresh an existing token using a refresh token

JWT tokens include roles that determine what actions the user can perform:

authenticate: This role is needed to perform authentication requests (renamed from "authenticated" in version 1.7.11)
user_info: Required to access endpoints with mode=no-auth
list_accounts: Required to access endpoints with mode=list-accounts
security: Access to security-related features like metrics and brute force management
admin: Full access to all features
Custom roles: Can be defined for your users and used for custom hooks

For multi-instance environments (e.g., behind a load balancer), enable Redis storage for JWT tokens to ensure that tokens generated by one instance can be validated by another instance.

server::jwt_auth::enabled

Default: false

This flag turns on (true) JWT authentication support in the server.

server:
  jwt_auth:
    enabled: true

server::jwt_auth::secret_key

Default: ""

This setting defines the secret key used for JWT signing. It should be at least 32 characters long and can contain alphanumeric characters and symbols, but no spaces.

server:
  jwt_auth:
    secret_key: "your-secret-key-at-least-32-characters"

server::jwt_auth::token_expiry

Default: 1h

This setting defines the expiration time for JWT tokens.

server:
  jwt_auth:
    token_expiry: 2h

server::jwt_auth::refresh_token

Default: false

This flag enables refresh tokens for JWT authentication.

server:
  jwt_auth:
    refresh_token: true

server::jwt_auth::refresh_token_expiry

Default: 24h

This setting defines the expiration time for JWT refresh tokens.

server:
  jwt_auth:
    refresh_token_expiry: 48h

server::jwt_auth::store_in_redis

Default: false

This flag enables storing JWT tokens in Redis.

server:
  jwt_auth:
    store_in_redis: true

server::jwt_auth::users

This section defines users that can authenticate using JWT.

server:
  jwt_auth:
    users:
      - username: admin
        password: "secure-password"
        roles:
          - admin
          - user
      - username: user
        password: "another-secure-password"
        roles:
          - user

Instance Name

server::instance_name

Default: "nauthilus"

This defines the application name. If not defined, it defaults to nauthilus

Logging Configuration

server::logs

This object defined logging relates settings.

server::log::json

Default: false

This flag turns on (true) logging in JSON format.

server:
  log:
    json: true

server::log::level

Default: "none"

This string defines the log level. It is one of:

Level	Comment
none	Entirely turn of logging
debug	See debug modules below!
info
warn
error

server:
  log:
    level: debug

server::log::add_source

New in version 1.10.0 Default: false

Controls whether the logger attaches source code information (file:line) to each log record. This maps to Go's slog HandlerOptions.AddSource.

Notes:

When enabled, the JSON formatter adds a "source" object (with file and line) to each entry.
The text formatter emits a compact source field near the message.
There is a small performance cost when enabled because caller information must be computed.

Example:

server:
  log:
    add_source: true

server::log::debug_modules

Default: empty list

if debugging is turned on, only very limited debug messages are logged by default. You can increase logging by activating additional log modules. This is the list of all available debug modules:

Module	Application
all	Full debugging
auth	This turns on logging for the main authentication process
hydra	Communication with the Ory hydra server
webauthn	Turn on debugging for WebAuthn (under development)
statistics	Prometheus related debugging
whitelist	Show whitelist related debugging
ldap	Show LDAP command and filter related debugging
ldappool	Show LDAP-pool related debugging such as free/busy/closed connections and housekeeping
cache	Turn on cache backend related debugging
brute_force	Turn on brute-force related debugging
rbl	Turn on RBL (realtime-blackhole-list) related debugging
action	Turn on Lua post-action related debugging
feature	Turn on feature related debugging
lua	Turn on Lua related debugging
filter	Turn on filter related debugging
tolerate	Turn on debugging for operations related to tolerance or error allowances
neural	Turn on debugging for neural network-related operations
jwt	Turn on debugging for JWT-related operations
http	Turn on debugging for HTTP-related operations

server:
  log:
    debug_modules:
      - auth
      - ldap 
      - filter

Backend Configuration

server::backends

Default: none
required

This object defines, which backends are enabled. You must define at least one backend!

Name	Comment
cache	The Redis cache backend is used for positive and failed login requests and should be enabled
ldap	This is the native LDAP backend. See settings below for configuration
lua	This is a Lua backend

For Multi-LDAP and Multi Lua-backends, you can use a special syntax to specify which pool or backend to use:

server:
  backends:
    - cache
    - ldap(pool1)  # Use the LDAP pool named "pool1"
    - lua(backend2)  # Use the Lua backend named "backend2"

This syntax allows you to use multiple LDAP pools or Lua backends with different configurations. The pool or backend name must match a name defined in the optional_ldap_pools or optional_lua_backends sections.

note

The *cache backend not only caches positive and negative requests. It is also a major component for the brute force buckets to detect users with repetitive wrong passwords.

warning

The cache backend should always be the first backend. The order of backends matters!

Features Configuration

server::features

Default: empty list

This object defines runtime features.

Here is a list of features that can be turned on:

Name	Usage
lua	General purpose Lua feature. You can have as many features as you like. They run in sequential order
tls_encryption	Clients must be connected securely to a service to be allowed to authenticate
relay_domains	If the login name equals to an email address, the domain component is compared to a list of known domains
rbl	Check a client IP address against realtime blackhole lists
backend_server_monitoring	This is a special feature that is not used for filtering

These features are primarely used to filter out requests before the main authentication process starts.

note

The features are run one-by-one. The rbl feature does query lists in parallel. The lua feature is always run as first feature and is the only one that can skip further processing of other features!

The backend_server_monitoring feature turns on a background job that does a health check for any kind of backend servers. It holds an in-memory list of alive servers that can be used in Lua scripts to select healthy servers.

server:
  features:
    - tls_encryption
    - lua
    - rbl 

Brute Force Configuration

server::brute_force_protocols

Default: empty list

This object defines a list of protocols for which the brute force protection is turned on.

When a service talks to Nauthilus, it must provide a protocol that is used by a remote client while authenticating.

This list describes protocols for which Nauthilus does brute force checks.

Here is a good working example that can be taken in a production environment:

server:
  brute_force_protocols:
    - imap
    - imaps
    - submission
    - smtp
    - smtps
    - ory-hydra
    - http

note

While most of the protocols are free to chose, ory-hydra has a special meaning for Nauthilus and is assigned to the communication between Nauthilus and the Ory hydra serverr.

Ory Hydra Configuration

server::ory_hydra_admin_url

Default: "http://127.0.0.1:4445"

This setting is the Ory hydra admin URL.

server:
  ory_hydra_admin_url: https://hydra.example.com:4445

DNS Configuration

server::dns

This object defines settings related to the DNS name resolver.

server::dns::resolver

Default: ""

If this setting is given, Nauthilus does not use the Go internal DNS resolver. Instead, it uses the provided resolver for DNS resolution.

server:
  dns:
    resolver: 192.168.0.1

server::dns::timeout

Default: 5

If a custom DNS resolver is set, you can specify a default timeout in seconds, after which DNS queries are aborted without waiting for a result.

server:
  dns:
    timeout: 3

server::dns::resolve_client_ip

Default: false

If a DNS reverse lookup should be done for incoming client requests, you can turn on (true) this feature.

server:
  dns:
    resolve_client_ip: true

warning

Turning on this feature will heavily increase network latency and DNS resolver load. It is suggested to use this feature with care.

Insights Configuration

server::insights

This object defines settings related to go pprof and is mainly useful for developers.

server::insights::enable_pprof

Default: false

Enable (true) pprof in Go for debugging purposes.

server:
  insights:
    enable_pprof: true

server::insights::enable_block_profile

Default: false

If pprof is enabled (required for this flag), you can also activate a block profile, which helps to find blocking code.

server:
  insights:
      enable_block_profile: true

server::insights::monitor_connections

Default: false

This flag turns on (true) connection monitoring.

server:
  insights:
    monitor_connections: true

Redis Configuration

server::redis

This object defines settings related to the Redis server.

server::redis::database_number

Default: 0

If Redis is configured to run standalone, master-slave or as sentinel, you can select the database number that Nauthilus must use.

server:
  redis:
      database_number: 2

server::redis::prefix

Default: ""

You can define a prefix that has to be used for any keys in Redis.

server:
  redis:
    prefix: "nt_"

note

This prefix is for Nauthilus internal keys only. If you chode to use Redis within Lua, you have to manage Redis keys yourself

tip

You may define custom prefixes in Lua with "ntc:" Like "Nauthilus-custom". That way you have a difference between built-in keys and user defined keys.

server::redis::password_nonce

Default: ""
required

This is a random string used to concatenate it with the password. The result will be hashed and truncated and is used in Redis. This helps secure password storage in Redis. The password nonce must be at least 16 characters long and can contain alphanumeric characters and symbols, but no spaces.

server:
  redis:
    password_nonce: "some-random-string-used-for-password-hashing"

server::redis::pool_size

Default: 0
required

This is a Redis pool size. The pool is managed by the underlying redis library go-redis.

server:
  redis:
    pool_size: 10

server::redis::idle_pool_size

Default: 0

This is a Redis idle pool size. The pool is managed by the underlying redis library go-redis.

server:
  redis:
    idle_pool_size: 2

server::redis::tls

New in version 1.7.11

This section configures TLS for Redis connections.

server:
  redis:
    tls:
      skip_verify: false

server::redis::positive_cache_ttl and server::redis::negative_cache_ttl

Default: 3600

Both values set the expiration value for Redis keys in seconds. The positive cache TTL is for authenticated users, while the negative cache TTL is for authentication failures. The latter may be larger as it is also used in the brute-force logic to detect users that try to log in with a repeating wrong password. Such requests are never treated as an attack.

server:
  redis:
    positive_cache_ttl: 3600
    negative_cache_ttl: 7200

Changes in version 1.4.9:

Units should now add a time unit like

s - seconds
m - minutes
h - hours

server::redis::master

If running Redis standalone or in master-slave mode, you have to define the master object.

server::redis::master::address

Default: "127.0.0.1:6379"

This is the socket for a Redis connection to either a standalone server or for a master.

server:
  redis:
    master:
      address: 127.0.0.1:6379

server::redis::master::username and server::redis::master::password

Default: empty

This is an optional username and password for Redis, if the service requires authentication.

Server:
  redis:
    master:
      username: some_user
      password: some_secret

server::redis::replica

This object defines a replica to a master. Currently, there is only support for one master and one replica. If you need more replica server, consider using sentinel instead or use some load balancer in front of Nauthilus that may distribute replica connections to more than one replica instance.

server::redis::replica::address

Deprecated in version 1.4.10
Default: ""

This is the socket for a Redis connection to a replica instance.

server:
  redis:
    replica:
      address: 10.10.10.10:6379

server::redis::replica::addresses

New in version 1.4.10
_Default: []

This is a list of one or more sockets for a Redis connection to a replica instance.

server:
  redis:
    replica:
      addresses:
        - 10.10.10.10:6379

server::redis::sentinels

NAuthilus can connect to Redis sentinels. The following options define such a setup.

server::redis::sentinels::master

Default: ""

This is the name of the sentinel master.

server:
  redis:
    sentinels:
      master: mymaster

server::redis::sentinels::addresses

Default: empty list

This is a list of Redis sentienl sockets.

server:
  redis:
    sentinels:
      addresses:
        - 127.0.0.1:26379
        - 127.0.0.1:26378
        - 127.0.0.1:26377

note

At least one sentinel address is required.

Here is an example for K8s redis-operator sentinel, if you run Nauthilus in Kubernetes on-premise and a NodePort service:

server:
  redis:
    sentinels:
      master: myMaster
      addresses:
        - redis-sentinel-sentinel-0.redis-sentinel-sentinel-headless.ot-operators.svc.cluster.local:26379
        - redis-sentinel-sentinel-1.redis-sentinel-sentinel-headless.ot-operators.svc.cluster.local:26379
        - redis-sentinel-sentinel-2.redis-sentinel-sentinel-headless.ot-operators.svc.cluster.local:26379

server::redis::sentinels::username and server::reids::sentinels::password

Default: ""

Both of these parameters are optional settings, if your Redis sentinels require authentication.

server:
  redis:
    sentinels:
      username: some_user
      password: some_secret

server::redis::cluster

If NAuthilus should be connected to a Redis cluster, the following settings can be set to do so.

server::redis::cluster::addresses

Default: empty list

This is a list of one or more Redis sockets pointing to a Redis cluster.

server:
  redis:
    cluster:
      addresses:
      - 127.0.0.1:6379
      - 127.0.0.1:6378
      - 127.0.0.1:6377

server::redis::cluster::username and server::redis::cluster::password

Default: ""

These parameters are optional settings for authentication with the Redis cluster.

server:
  redis:
    cluster:
      username: some_user
      password: some_secret

server::redis::cluster::route_by_latency

Default: false

When enabled, commands are routed to the Redis node with the lowest latency.

server:
  redis:
    cluster:
      route_by_latency: true

server::redis::cluster::route_randomly

Default: false

When enabled, commands are routed randomly across Redis nodes.

server:
  redis:
    cluster:
      route_randomly: true

server::redis::cluster::route_reads_to_replicas

New in version 1.7.11
Default: false

When enabled, read commands are routed to Redis replica nodes, which can improve performance by distributing the read load across the cluster.

server:
  redis:
    cluster:
      route_reads_to_replicas: true

server::redis::cluster::read_only

Default: false
Deprecated: Use route_reads_to_replicas instead

When enabled, read commands are routed to Redis replica nodes. This parameter has been renamed to route_reads_to_replicas to better reflect its actual functionality.

server:
  redis:
    cluster:
      read_only: true  # Deprecated

server::redis::cluster::max_redirects

Default: 3

This setting defines the maximum number of redirects to follow when executing Redis commands.

server:
  redis:
    cluster:
      max_redirects: 5

server::redis::cluster::read_timeout and server::redis::cluster::write_timeout

Default: 0 (no timeout)

These settings define the timeout duration for read and write operations to the Redis cluster.

Units should add a time unit like:

s - seconds
m - minutes
h - hours

server:
  redis:
    cluster:
      read_timeout: 3s
      write_timeout: 3s

Master User Configuration

server::master_user

This object defines settings related to a so-called master user

server::master_user::enabled

Default: false

If this flag is turned on (true), Nauthilus honors login usernames that are master users. A master user looks something like this:

user@domain.tld*masteruser

As you can see, the master user is separated from the real login name by a "*" character followed by the name of a master user. If NAuthilus detecs such a user, it will do authentication against the master user.

server:
  master_user:
    enabled: true

server::master_user::delimiter

Default: "*"

This is the character that splits the real username from the master user.

server:
  master_user:
    delimiter: "*"

Frontend Configuration

server::frontend

Nauthilus specific settings for the frontend (OIDC)

server::frontend::enabled

Default: false

Turn on the frontend.

server:
  frontend:
    enabled: true

server::frontend::csrf_secret

Default: ""
required

This key is required whenever CSRF (cross-site-request-forgery) attacks must be prevented. This is currently used, if Nauthilus is configured to communicate with Ory Hydra. The login, consent and logout pages are protected with a CSRF token. This value defines the secret used for that token.

This value MUST be 32 bytes long and can contain alphanumeric characters and symbols, but no spaces.

server::frontend::cookie_store_auth_key and server::frontend::cookie_store_encryption_key

Default: ""
required

These keys are used to encrypt and decrypt session cookies.

The cookie_store_auth_key MUST be 32 bytes long and can contain alphanumeric characters and symbols, but no spaces.

The cookie_store_encryption_key MUST be 16, 24, or 32 bytes long and can contain alphanumeric characters and symbols, but no spaces.

Prometheus Timer Configuration

server::prometheus_timer

Turn on several Prometheus labels, which are timers for certain aspects of the application.

server::prometheus\timer::enabled

Turn on the prometheus timers.

server:
  prometheus_timer:
    enabled: true

server::prometheus\timer::labels

The following labels can be turned on:

Label name	Description
account	Mode "list-accounts" timer
action	Timers for Lua actions
backend	Timers for backends
brute_force	Timers for the brute force functions
feature	Timers for all features
filter	Timers for Lua filters
request	Timer for the entire client request without post actions
store_totp	Timer for storing a new TOTP secret to a backend
post_action	Timers for Lua post actions
dns	Timers for DNS queries

Example:

server:
  prometheus_timer:
    enabled: true
    labels:
      - request
      - dns

Compression Configuration

server::compression

This object defines settings related to HTTP response compression.

Note: As of version 1.9.2, MIME types for compression are deprecated and no longer used. Compression decisions are automatically based on negotiation and thresholds (see options below).

server::compression::enabled

Default: false

This flag turns on (true) HTTP response compression.

server:
  compression:
    enabled: true

server::compression::level

Default: 5

Deprecated: As of v1.9.9 use server::compression::level_gzip instead. The old key remains supported for backward compatibility and will be removed in a future release.

# Deprecated — prefer level_gzip
server:
  compression:
    level: 7

server::compression::level_gzip (since v1.9.9)

Default: 5

Defines the gzip compression level (1-9, where 1 is fastest and 9 is best compression). This replaces the old level key to mirror the style of level_zstd.

server:
  compression:
    level_gzip: 7

server::compression::content_types

Default: deprecated since v1.9.2

Deprecated: As of version 1.9.2 MIME/content types are no longer used to decide compression and this option has no effect. The server now determines compression automatically based on request/response negotiation and size thresholds.

If present in your configuration, this key will be ignored from v1.9.2 onwards and can be safely removed.

# Prior to v1.9.2:
# server:
#   compression:
#     content_types:
#       - text/html
#       - application/json

# Since v1.9.2 this option is ignored and should be removed.

server::compression::min_length

Default: 1024

This setting defines the minimum content length required for compression.

server:
  compression:
    min_length: 2048

server::compression::algorithms (since v1.9.8)

Default: ["zstd", "gzip"]

Defines the enabled compression algorithms in order of preference. The router applies only one response compression middleware at a time based on this list. If the client supports Zstandard (zstd) and it is listed first, zstd will be used; otherwise it falls back to gzip when available. Since v1.9.9, Brotli (br) can also be selected and typically offers excellent ratios for text assets.

Valid values include: "br" (Brotli), "zstd" (or aliases "zst", "zstandard") and "gzip".

server:
  compression:
    enabled: true
    algorithms: ["br", "zstd", "gzip"]

Notes:

Only one algorithm is applied for a given response.
If the list is empty or no known algorithm is listed, zstd is used by default.

server::compression::level_zstd (since v1.9.8)

Default: 0 (DefaultCompression)

Configures the Zstandard compression level mapping used by the built-in zstd middleware:

0 = DefaultCompression
1 = BestSpeed
2 = BetterCompression
3 = BestCompression

server:
  compression:
    enabled: true
    algorithms: ["br", "zstd", "gzip"]
    level_zstd: 2 # BetterCompression

server::compression::level_brotli (since v1.9.9)

Default: 0 (DefaultCompression)

Configures the Brotli compression level mapping used by the built-in Brotli middleware:

0 = DefaultCompression
1 = BestSpeed
2 = BetterCompression
3 = BestCompression

server:
  compression:
    enabled: true
    algorithms: ["br", "zstd", "gzip"]
    level_brotli: 2 # BetterCompression

Implementation details:

Zstandard is implemented via klauspost/compress.
Brotli is implemented via andybalholm/brotli.
For gzip, the new level_gzip (1-9) supersedes the deprecated level key (still accepted for backward compatibility).

Request decompression (since v1.9.8; extended in v1.9.9):

Incoming requests with Content-Encoding: gzip are decompressed when compression is enabled.
Incoming requests with Content-Encoding: zstd/zst/zstandard are decompressed when compression is enabled.
Incoming requests with Content-Encoding: br (Brotli) are decompressed when compression is enabled (since v1.9.9).

Keep Alive Configuration

server::keep_alive

This object defines settings related to HTTP connection keep-alive optimization.

server::keep_alive::enabled

Default: false

This flag turns on (true) HTTP keep-alive optimization.

server:
  keep_alive:
    enabled: true

server::keep_alive::timeout

Default: 30s

This setting defines the keep-alive timeout duration.

server:
  keep_alive:
    timeout: 60s

server::keep_alive::max_idle_connections

Default: 100

This setting defines the maximum number of idle connections.

server:
  keep_alive:
    max_idle_connections: 200

server::keep_alive::max_idle_connections_per_host

Default: 10

This setting defines the maximum number of idle connections per host.

server:
  keep_alive:
    max_idle_connections_per_host: 20

Basic Server Settings​

server::address​

server::max_concurrent_requests​

server::max_password_history_entries​

server::haproxy_v2​

server::http3​

server::disabled_endpoints​

Meaning​

HTTP Client Configuration​

server::http_client​

Timeouts​

Keys and defaults​

TLS Configuration​

server::tls​

server::tls::enabled​

server::tls::cert and server::tls::key​

server::tls::skip_verify​

server::tls::http_client_skip_verify​

server::tls::min_tls_version​

server::tls::ca_file​

server::tls::cipher_suites​

Authentication Configuration​

server::basic_auth​

server::basic_auth::enabled​

server::basic_auth::username and server::basic_auth::password​

server::jwt_auth​

server::jwt_auth::enabled​

server::jwt_auth::secret_key​

server::jwt_auth::token_expiry​

server::jwt_auth::refresh_token​

server::jwt_auth::refresh_token_expiry​

server::jwt_auth::store_in_redis​

server::jwt_auth::users​

Instance Name​

server::instance_name​

Logging Configuration​

server::logs​

server::log::json​

server::log::level​

server::log::add_source​

server::log::debug_modules​

Backend Configuration​

server::backends​

Features Configuration​

server::features​

Brute Force Configuration​

server::brute_force_protocols​

Ory Hydra Configuration​

server::ory_hydra_admin_url​

DNS Configuration​

server::dns​

server::dns::resolver​

server::dns::timeout​

server::dns::resolve_client_ip​

Insights Configuration​

server::insights​

server::insights::enable_pprof​

server::insights::enable_block_profile​

server::insights::monitor_connections​

Redis Configuration​

server::redis​

server::redis::database_number​

server::redis::prefix​

server::redis::password_nonce​

server::redis::pool_size​

server::redis::idle_pool_size​

server::redis::tls​

server::redis::positive_cache_ttl and server::redis::negative_cache_ttl​

server::redis::master​

server::redis::master::address​

server::redis::master::username and server::redis::master::password​

server::redis::replica​

server::redis::replica::address​

server::redis::replica::addresses​

server::redis::sentinels​

server::redis::sentinels::master​

server::redis::sentinels::addresses​

server::redis::sentinels::username and server::reids::sentinels::password​

server::redis::cluster​

server::redis::cluster::addresses​

Basic Server Settings

server::address

server::max_concurrent_requests

server::max_password_history_entries

server::haproxy_v2

server::http3

server::disabled_endpoints

Meaning

HTTP Client Configuration

server::http_client

Timeouts

Keys and defaults

TLS Configuration

server::tls

server::tls::enabled

server::tls::cert and server::tls::key

server::tls::skip_verify

server::tls::http_client_skip_verify

server::tls::min_tls_version

server::tls::ca_file

server::tls::cipher_suites

Authentication Configuration

server::basic_auth

server::basic_auth::enabled

server::basic_auth::username and server::basic_auth::password

server::jwt_auth

server::jwt_auth::enabled

server::jwt_auth::secret_key

server::jwt_auth::token_expiry

server::jwt_auth::refresh_token

server::jwt_auth::refresh_token_expiry

server::jwt_auth::store_in_redis

server::jwt_auth::users

Instance Name

server::instance_name

Logging Configuration

server::logs

server::log::json

server::log::level

server::log::add_source

server::log::debug_modules

Backend Configuration

server::backends

Features Configuration

server::features

Brute Force Configuration

server::brute_force_protocols

Ory Hydra Configuration

server::ory_hydra_admin_url

DNS Configuration

server::dns

server::dns::resolver

server::dns::timeout

server::dns::resolve_client_ip

Insights Configuration

server::insights

server::insights::enable_pprof

server::insights::enable_block_profile

server::insights::monitor_connections

Redis Configuration

server::redis

server::redis::database_number

server::redis::prefix

server::redis::password_nonce

server::redis::pool_size

server::redis::idle_pool_size

server::redis::tls

server::redis::positive_cache_ttl and server::redis::negative_cache_ttl

server::redis::master

server::redis::master::address

server::redis::master::username and server::redis::master::password

server::redis::replica

server::redis::replica::address

server::redis::replica::addresses

server::redis::sentinels

server::redis::sentinels::master

server::redis::sentinels::addresses

server::redis::sentinels::username and server::reids::sentinels::password

server::redis::cluster

server::redis::cluster::addresses