Configuration

This page describes the ways of configuring the cunīcu daemon (cunicu daemon).

Command Line Flags

Basic options of cunicu daemon can be configured by passing command line arguments. A full overview is available in its manpage.

Configuration File

For more advanced setups, a configuration file can be used for a persistent configuration:

Please have a look at the example configuration file for a full reference of all available settings.

Environment Variables

All the settings from the configuration file can also be passed via environment variables by following the following rules:

• Convert the setting name to uppercase
• Prefixing the setting name with CUNICU_
• Nested settings are separated by underscores

Example: The setting ice.max_binding_requests can be set by the environment variable CUNICU_ICE_MAX_BINDING_REQUESTS

note

Setting lists such as ice.urls or backends can currently not be set via environment variables.

At Runtime

cunīcu's configuration can also be updated at runtime, alleviating daemon restarts and interruption of connectivity.

Please have a look at the cunicu config commands.

Currently, not all settings are runtime tunable.

Changed settings via the cunicu config set command are persisted in a runtime configuration file at /var/lib/cunicu.runtime.yaml. So runtime changes will also be taken into account for subsequent starts of the daemon.

DNS Auto-configuration

cunīcu als supports retrieving parts of the configuration via DNS lookups. This is useful for corporate environments in which a fleet of cunīcu daemon need to be configured centrally.

In this case cunicu daemon is started one or more --domain example.com parameters to look for the following DNS records to obtain its configuration.

STUN and TURN servers used for ICE are retrieved by SVR lookups and other cunīcu settings are retrieved via SRV and TXT lookups:

_stun._udp.example.com.  3600 IN SRV 10 0 3478 stun.example.com.
_stuns._tcp.example.com. 3600 IN SRV 10 0 3478 stun.example.com.
_turn._udp.example.com.  3600 IN SRV 10 0 3478 turn.example.com.
_turn._tcp.example.com.  3600 IN SRV 10 0 3478 turn.example.com.
_turns._tcp.example.com. 3600 IN SRV 10 0 5349 turn.example.com.

example.com.             3600 IN TXT "cunicu-config=https://example.com/cunicu.yaml"
example.com.             3600 IN TXT "cunicu-backend=grpc://signal.example.com:443"
example.com.             3600 IN TXT "cunicu-community=my-community-password"
example.com.             3600 IN TXT "cunicu-ice-username=user1"
example.com.             3600 IN TXT "cunicu-ice-password=pass1"

note

The cunicu-backend and cunicu-config TXT records can be provided multiple times. Others not.

Remote Configuration Files

When cunicu daemon can be started with --config options pointing to HTTPS URIs:

cunicu daemon --config http://example.com/cunicu.yaml

cunīcu will download all configuration files in the order they are specified on the command line and merge them subsequently.

This feature can be combined with the DNS auto-configuration method by providing a TXT record pointing to the configuration file:

example.com. 3600 IN TXT "cunicu-config=https://example.com/cunicu.yaml"

note

Remote configuration files must be fetched via HTTPS if they are not hosted locally and required a trusted server certificate.

Auto-reload

cunīcu can watch local and remote files as well as the DNS configuration for changes and automatically reloads its configuration from them whenever a change has been detected.

Pass the --watch-config or -w command line options to cunicu daemon to enable this feature.

For local files the change is detected by inotify(7). For remote sources, cunīcu periodically checks the Last-Modified and Etag headers in case of HTTP files or the DNS zone's SOA serial number to detect changes without request the full remote source.

note

Configuration file distributed via conicu-config DNS TXT record are not yet monitored for changes.