Server configuration

The Incus server can be configured through a set of key/value configuration options.

The key/value configuration is namespaced. The following options are available:

See How to configure the Incus server for instructions on how to set the configuration options.

Note

Options marked with a global scope are immediately applied to all cluster members. Options with a local scope must be set on a per-member basis.

Core configuration

The following server options control the core daemon configuration:

core.bgp_address

Address to bind the BGP server to

Key: core.bgp_address
Type:

string
Scope:

local

See How to configure Incus as a BGP server.

core.bgp_asn

BGP Autonomous System Number for the local server

Key: core.bgp_asn
Type:

string
Scope:

global
core.bgp_routerid

A unique identifier for the BGP server

Key: core.bgp_routerid
Type:

string
Scope:

local

The identifier must be formatted as an IPv4 address.

core.debug_address

Address to bind the pprof debug server to (HTTP)

Key: core.debug_address
Type:

string
Scope:

local
core.dns_address

Address to bind the authoritative DNS server to

Key: core.dns_address
Type:

string
Scope:

local

See Enable the built-in DNS server.

core.https_address

Address to bind for the remote API (HTTPS)

Key: core.https_address
Type:

string
Scope:

local

See How to expose Incus to the network.

core.https_allowed_credentials

Whether to set Access-Control-Allow-Credentials

Key: core.https_allowed_credentials
Type:

bool
Default:

false
Scope:

global

If enabled, the Access-Control-Allow-Credentials HTTP header value is set to true.

core.https_allowed_headers

Access-Control-Allow-Headers HTTP header value

Key: core.https_allowed_headers
Type:

string
Scope:

global
core.https_allowed_methods

Access-Control-Allow-Methods HTTP header value

Key: core.https_allowed_methods
Type:

string
Scope:

global
core.https_allowed_origin

Access-Control-Allow-Origin HTTP header value

Key: core.https_allowed_origin
Type:

string
Scope:

global
core.https_trusted_proxy

Trusted servers to provide the client’s address

Key: core.https_trusted_proxy
Type:

string
Scope:

global

Specify a comma-separated list of IP addresses of trusted servers that provide the client’s address through the proxy connection header.

core.metrics_address

Address to bind the metrics server to (HTTPS)

Key: core.metrics_address
Type:

string
Scope:

local

See How to monitor metrics.

core.metrics_authentication

Whether to enforce authentication on the metrics endpoint

Key: core.metrics_authentication
Type:

bool
Default:

true
Scope:

global
core.proxy_http

HTTP proxy to use

Key: core.proxy_http
Type:

string
Scope:

global

If this option is not specified, the daemon falls back to the HTTP_PROXY environment variable (if set).

core.proxy_https

HTTPS proxy to use

Key: core.proxy_https
Type:

string
Scope:

global

If this option is not specified, the daemon falls back to the HTTPS_PROXY environment variable (if set).

core.proxy_ignore_hosts

Hosts that don’t need the proxy

Key: core.proxy_ignore_hosts
Type:

string
Scope:

global

Specify this option in a similar format to NO_PROXY (for example, 1.2.3.4,1.2.3.5)

If this option is not specified, the daemon falls back to the NO_PROXY environment variable (if set).

core.remote_token_expiry

Time after which a remote add token expires

Key: core.remote_token_expiry
Type:

string
Default:

no expiry
Scope:

global
core.shutdown_timeout

How long to wait before shutdown

Key: core.shutdown_timeout
Type:

integer
Default:

5
Scope:

global

Specify the number of minutes to wait for running operations to complete before the daemon shuts down.

core.storage_buckets_address

Address to bind the storage object server to (HTTPS)

Key: core.storage_buckets_address
Type:

string
Scope:

local

See How to manage storage buckets and keys.

core.syslog_socket

Whether to enable the syslog unixgram socket listener

Key: core.syslog_socket
Type:

bool
Default:

false
Scope:

local

Set this option to true to enable the syslog unixgram socket to receive log messages from external processes.

core.trust_ca_certificates

Whether to automatically trust clients signed by the CA

Key: core.trust_ca_certificates
Type:

bool
Default:

false
Scope:

global

ACME configuration

The following server options control the ACME configuration:

acme.agree_tos

Agree to ACME terms of service

Key: acme.agree_tos
Type:

bool
Default:

false
Scope:

global
acme.ca_url

URL to the directory resource of the ACME service

Key: acme.ca_url
Type:

string
Default:

https://acme-v02.api.letsencrypt.org/directory
Scope:

global
acme.domain

Domain for which the certificate is issued

Key: acme.domain
Type:

string
Scope:

global
acme.email

Email address used for the account registration

Key: acme.email
Type:

string
Scope:

global

OpenID Connect configuration

The following server options configure external user authentication through OpenID Connect authentication:

oidc.audience

Expected audience value for the application

Key: oidc.audience
Type:

string
Scope:

global

This value is required by some providers.

oidc.claim

OpenID Connect claim to use as the username

Key: oidc.claim
Type:

string
Scope:

global
oidc.client.id

OpenID Connect client ID

Key: oidc.client.id
Type:

string
Scope:

global
oidc.issuer

OpenID Connect Discovery URL for the provider

Key: oidc.issuer
Type:

string
Scope:

global
oidc.scopes

Comma separated list of OpenID Connect scopes

Key: oidc.scopes
Type:

string
Scope:

global

OpenFGA configuration

The following server options configure external user authorization through Open Fine-Grained Authorization (OpenFGA):

openfga.api.token

API token of the OpenFGA server

Key: openfga.api.token
Type:

string
Scope:

global
openfga.api.url

URL of the OpenFGA server

Key: openfga.api.url
Type:

string
Scope:

global
openfga.store.id

ID of the OpenFGA permission store

Key: openfga.store.id
Type:

string
Scope:

global

Cluster configuration

The following server options control Clustering:

cluster.healing_threshold

Threshold when to evacuate an offline cluster member

Key: cluster.healing_threshold
Type:

integer
Default:

0
Scope:

global

Specify the number of seconds after which an offline cluster member is to be evacuated. To disable evacuating offline members, set this option to 0.

cluster.https_address

Address to use for clustering traffic

Key: cluster.https_address
Type:

string
Scope:

local

See Separate REST API and clustering networks.

cluster.images_minimal_replica

Number of cluster members that replicate an image

Key: cluster.images_minimal_replica
Type:

integer
Default:

3
Scope:

global

Specify the minimal number of cluster members that keep a copy of a particular image. Set this option to 1 for no replication, or to -1 to replicate images on all members.

cluster.join_token_expiry

Time after which a cluster join token expires

Key: cluster.join_token_expiry
Type:

string
Default:

3H
Scope:

global
cluster.max_standby

Number of database stand-by members

Key: cluster.max_standby
Type:

integer
Default:

2
Scope:

global

Specify the maximum number of cluster members that are assigned the database stand-by role. This must be a number between 0 and 5.

cluster.max_voters

Number of database voter members

Key: cluster.max_voters
Type:

integer
Default:

3
Scope:

global

Specify the maximum number of cluster members that are assigned the database voter role. This must be an odd number >= 3.

cluster.offline_threshold

Threshold when an unresponsive member is considered offline

Key: cluster.offline_threshold
Type:

integer
Default:

20
Scope:

global

Specify the number of seconds after which an unresponsive member is considered offline.

cluster.rebalance.batch

Maximum number of instances to move during one re-balancing run

Key: cluster.rebalance.batch
Type:

integer
Default:

1
Scope:

global
cluster.rebalance.cooldown

Amount of time during which an instance will not be moved again

Key: cluster.rebalance.cooldown
Type:

string
Default:

6H
Scope:

global
cluster.rebalance.interval

How often (in minutes) to consider re-balancing things. 0 to disable (default)

Key: cluster.rebalance.interval
Type:

integer
Default:

0
Scope:

global
cluster.rebalance.threshold

Percentage load difference between most and least busy server needed to trigger a migration

Key: cluster.rebalance.threshold
Type:

integer
Default:

20
Scope:

global

Images configuration

The following server options configure how to handle Images:

images.auto_update_cached

Whether to automatically update cached images

Key: images.auto_update_cached
Type:

bool
Default:

true
Scope:

global
images.auto_update_interval

Interval at which to look for updates to cached images

Key: images.auto_update_interval
Type:

integer
Default:

6
Scope:

global

Specify the interval in hours. To disable looking for updates to cached images, set this option to 0.

images.compression_algorithm

Compression algorithm to use for new images

Key: images.compression_algorithm
Type:

string
Default:

gzip
Scope:

global

Possible values are bzip2, gzip, lzma, xz, or none.

images.default_architecture

Default architecture to use in a mixed-architecture cluster

Key: images.default_architecture
Type:

string
images.remote_cache_expiry

When an unused cached remote image is flushed

Key: images.remote_cache_expiry
Type:

integer
Default:

10
Scope:

global

Specify the number of days after which the unused cached image expires.

Loki configuration

The following server options configure the external log aggregation system:

loki.api.ca_cert

CA certificate for the Loki server

Key: loki.api.ca_cert
Type:

string
Scope:

global
loki.api.url

URL to the Loki server

Key: loki.api.url
Type:

string
Scope:

global

Specify the protocol, name or IP and port. For example https://loki.example.com:3100. Incus will automatically add the /loki/api/v1/push suffix so there’s no need to add it here.

loki.auth.password

Password used for Loki authentication

Key: loki.auth.password
Type:

string
Scope:

global
loki.auth.username

User name used for Loki authentication

Key: loki.auth.username
Type:

string
Scope:

global
loki.instance

Name to use as the instance field in Loki events.

Key: loki.instance
Type:

string
Default:

Local server host name or cluster member name
Scope:

global

This allows replacing the default instance value (server host name) by a more relevant value like a cluster identifier.

loki.labels

Labels for a Loki log entry

Key: loki.labels
Type:

string
Scope:

global

Specify a comma-separated list of values that should be used as labels for a Loki log entry.

loki.loglevel

Minimum log level to send to the Loki server

Key: loki.loglevel
Type:

string
Default:

info
Scope:

global
loki.types

Events to send to the Loki server

Key: loki.types
Type:

string
Default:

lifecycle,logging
Scope:

global

Specify a comma-separated list of events to send to the Loki server. The events can be any combination of lifecycle, logging, and network-acl.

Miscellaneous options

The following server options configure server-specific settings for Instances, OVN integration, Backups and Storage:

authorization.scriptlet

Authorization scriptlet

Key: authorization.scriptlet
Type:

string
Scope:

global

When using scriptlet-based authorization, this option stores the scriptlet.

backups.compression_algorithm

Compression algorithm to use for backups

Key: backups.compression_algorithm
Type:

string
Default:

gzip
Scope:

global

Possible values are bzip2, gzip, lzma, xz, or none.

instances.lxcfs.per_instance

Whether to run LXCFS on a per-instance basis

Key: instances.lxcfs.per_instance
Type:

bool
Default:

false
Scope:

global

LXCFS is used to provide overlays for common /proc and /sys files which reflect the resource limits applied to the container.

It normally operates through a single file system mount on the host which is then shared by all containers. This is very efficient but comes with the downside that a crash of LXCFS will break all containers.

With this option, it’s now possible to run a LXCFS instance per container instead, using more system resources but reducing the impact of a crash.

instances.nic.host_name

How to set the host name for a NIC

Key: instances.nic.host_name
Type:

string
Default:

random
Scope:

global

Possible values are random and mac.

If set to random, use the random host interface name as the host name. If set to mac, generate a host name in the form inc<mac_address> (MAC without leading two digits).

instances.placement.scriptlet

Instance placement scriptlet for automatic instance placement

Key: instances.placement.scriptlet
Type:

string
Scope:

global

When using custom automatic instance placement logic, this option stores the scriptlet. See Instance placement scriptlet for more information.

network.ovn.ca_cert

OVN SSL certificate authority

Key: network.ovn.ca_cert
Type:

string
Default:

Content of /etc/ovn/ovn-central.crt if present
Scope:

global
network.ovn.client_cert

OVN SSL client certificate

Key: network.ovn.client_cert
Type:

string
Default:

Content of /etc/ovn/cert_host if present
Scope:

global
network.ovn.client_key

OVN SSL client key

Key: network.ovn.client_key
Type:

string
Default:

Content of /etc/ovn/key_host if present
Scope:

global
network.ovn.integration_bridge

OVS integration bridge to use for OVN networks

Key: network.ovn.integration_bridge
Type:

string
Default:

br-int
Scope:

global
network.ovn.northbound_connection

OVN northbound database connection string

Key: network.ovn.northbound_connection
Type:

string
Default:

unix:/run/ovn/ovnnb_db.sock
Scope:

global
network.ovs.connection

OVS socket path

Key: network.ovs.connection
Type:

string
Default:

unix:/run/openvswitch/db.sock
Scope:

global
storage.backups_volume

Volume to use to store backup tarballs

Key: storage.backups_volume
Type:

string
Scope:

local

Specify the volume using the syntax POOL/VOLUME.

storage.images_volume

Volume to use to store the image tarballs

Key: storage.images_volume
Type:

string
Scope:

local

Specify the volume using the syntax POOL/VOLUME.

User options

Additional user defined configuration keys are available within the user. namespace. Note that keys starting with user.ui. are used for web UI configuration options and are visible even to unauthenticated users.