Server configuration

The LXD 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 LXD 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 LXD 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 LXD 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, LXD 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, LXD 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, LXD 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 LXD server 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.client.id

OpenID Connect client ID

Key: oidc.client.id
Type:

string

Scope:

global

oidc.groups.claim

Expected audience value for the application

Key: oidc.groups.claim
Type:

string

Scope:

global

Specify a custom claim to be requested when performing OIDC flows. Configure a corresponding custom claim in your identity provider and add organization level groups to it. These can be mapped to LXD groups for automatic access control.

oidc.issuer

OpenID Connect Discovery URL for the provider

Key: oidc.issuer
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.

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. LXD 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 ovn.

Miscellaneous options

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

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.migration.stateful

Whether to set migration.stateful to true for the instances

Key: instances.migration.stateful
Type:

bool

Scope:

global

You can override this setting for relevant instances, either in the instance-specific configuration or through a profile.

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 lxd<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.

maas.api.key

API key to manage MAAS

Key: maas.api.key
Type:

string

Scope:

global

maas.api.url

URL of the MAAS server

Key: maas.api.url
Type:

string

Scope:

global

maas.machine

Name of this LXD host in MAAS

Key: maas.machine
Type:

string

Default:

host name

Scope:

local

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:/var/run/ovn/ovnnb_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.