daemon.toml

9 min read · Beginner

daemon.toml configures the Edera Protect daemon. It lives at /var/lib/edera/protect/daemon.toml and is generated with defaults the first time the daemon starts.

Restart protect-daemon after editing this file for changes to take effect:

sudo systemctl restart protect-daemon

OCI

The [oci] section controls how the daemon pulls container images.

[oci]
docker-hub-mirror = "index.docker.io"

Options

docker-hub-mirror

Hostname the daemon contacts whenever an image reference would otherwise resolve to Docker Hub. Set this to a pull-through cache or private mirror to avoid hitting Docker Hub directly.

[oci]
docker-hub-mirror = "mirror.example.com"

Zone

The [zone] section sets defaults for zones launched by the daemon.

[zone]
cache-default-kernel = true
cache-default-initrd = true
memory-limit-mb = 1024
destroyed-linger-seconds = 600

Options

cache-default-kernel

When true, the daemon keeps the default zone kernel image on disk after first use so subsequent zone launches skip re-fetching it. Set to false to always pull a fresh copy.

cache-default-initrd

When true, the daemon keeps the default zone initrd image on disk after first use. Set to false to always pull a fresh copy.

memory-limit-mb

Default memory ceiling, in MiB, for any zone that does not specify its own memory limit at launch. All per-zone/per-pod overrides take precedence over this value.

destroyed-linger-seconds

How long a destroyed zone’s record and console log are retained after the zone exits, so post-mortem tooling can still inspect it. Once this window elapses, the daemon drops the record. Set to 0 to discard a zone’s state as soon as it is destroyed.

[zone.kernel-variants]

A map from a short kernel variant name to the zone-kernel OCI reference that provides it. Clients select a kernel by name (protect zone launch --kernel-variant nvidia, or the dev.edera/kernel-variant pod annotation) and the daemon resolves the name to the reference configured here. This lets operators ship, override kernels, or define site-local alternative kernels.

[zone.kernel-variants]
nvidia = "ghcr.io/edera-dev/zone-nvidiagpu-kernel:6.18.38-nvidia-610.43.02"

The installer seeds the nvidia variant with the current NVIDIA zone kernel by default. Add your own entries to expose additional kernels by name; pin each to a specific tag or digest so it resolves deterministically. Run protect image list-kernel-variants to see the variants the daemon can currently resolve.

Variants deprecate the direct --kernel flag and dev.edera/kernel annotation. See Selecting a zone kernel with variants for details.

Power

The [power] section sets the host power-management policy applied when the daemon starts. Knobs are grouped per hypervisor backend under [power.<backend>], and only the group matching the active runtime is applied. Currently only the Xen backend is supported, under [power.xen]. These settings are host-wide and apply in both standalone and Kubernetes contexts.

[power.xen]
x86-turbo = "automatic"
cpu-frequency-governor = "performance"

Options

xen.x86-turbo

Controls x86 turbo mode (Intel Turbo Boost, AMD Core Performance Boost) across all host CPUs through Xen.

• "automatic": leave turbo at the platform default and stay quiet about any failure to apply the policy, since no explicit choice was made. Default.
• "enabled": force turbo mode on.
• "disabled": force turbo mode off.

xen.cpu-frequency-governor

Selects the CPU-frequency governor applied to all host CPUs through Xen.

• "performance": hold CPUs at their highest available frequency. Default.
• "power-save": bias CPUs toward their lowest frequency to save power.

Metrics

The [metrics] section controls the daemon’s Prometheus metrics endpoint and per-zone metrics collection.

[metrics]
enable-metrics-endpoint = true
enable-zone-metrics = true
zone-metrics-heartbeat-interval-seconds = 5
metrics-endpoint-address = "127.0.0.1:3035"

Options

enable-metrics-endpoint

When true, the daemon binds and hosts a Prometheus /metrics endpoint at metrics-endpoint-address. Set to false to disable the endpoint entirely. Note that this only controls the Prometheus scrape endpoint binding, if enable-zone-metrics is true, the metrics will still be collected from each zone at intervals.

enable-zone-metrics

When true, the daemon establishes a metrics listener for each running managed zone and serves the cached results to both the Prometheus metrics endpoint and protect-ctl zone metrics. Set to false to stop collecting per-zone metrics. Note that if this is set to false but enable-metrics-endpoint is set to true, the metrics endpoint will be served with no data.

zone-metrics-heartbeat-interval-seconds

How often, in seconds, the daemon configures each zone to send it an updated metrics snapshot. Lower values give fresher zone metrics at the cost of more frequent collection.

metrics-endpoint-address

Socket address the Prometheus /metrics endpoint binds to when enable-metrics-endpoint is true. Defaults to a loopback address.

[metrics]
metrics-endpoint-address = "127.0.0.1:3035"

Network

The [network] section configures the default zone network for zones launched without Kubernetes (via protect zone launch). In a Kubernetes context, all of these settings are ignored and zone/pod networking is managed by the cluster CNI.

[network]
nameservers = [
    "1.1.1.1",
    "1.0.0.1",
    "2606:4700:4700::1111",
    "2606:4700:4700::1001",
]

[network.ipv4]
subnet = "10.75.0.0/16"

[network.ipv6]
subnet = "fdd4:1476:6c7e::/48"

Options

nameservers

DNS resolvers given to every zone. Accepts both IPv4 and IPv6 addresses. Defaults to Cloudflare’s public resolvers (1.1.1.1, 1.0.0.1, 2606:4700:4700::1111, 2606:4700:4700::1001).

[network]
nameservers = ["10.0.0.53", "10.0.0.54"]

ipv4.subnet

CIDR the daemon allocates IPv4 addresses from when assigning an interface to a zone. Choose a subnet that does not collide with networks the host already routes to.

[network.ipv4]
subnet = "10.200.0.0/16"

ipv6.subnet

CIDR the daemon allocates IPv6 addresses from when assigning an interface to a zone.

[network.ipv6]
subnet = "fd12:3456:789a::/48"

PCI

The [pci] section declares PCI devices the daemon may pass through to zones. Each device is a named entry under [pci.devices.<name>]; the name is what you reference with protect zone launch --device <name>.

[pci.devices.gpu0]
locations = ["0000:01:00.0"]
permissive = false
msi-translate = false
power-management = false
rdm-reserve-policy = "strict"
modules = []

[pci.devices.gpu0.module-parameters]

Device options

locations

List of PCI BDF addresses (domain:bus:device.function) that belong to this logical device. Most devices have one address; multi-function devices that must be passed through together list all of their functions here.

locations = ["0000:01:00.0", "0000:01:00.1"]

permissive

Set to true to let the zone touch PCI configuration registers the hypervisor would otherwise hide. Required for some passthrough scenarios; reduces isolation when enabled.

msi-translate

Set to true to have the hypervisor translate Message Signaled Interrupts for this device. Needed for devices that require MSI but cannot program it directly under passthrough.

power-management

Set to true to let the zone control the device’s power state (suspend, resume). Off by default to keep the host in charge of device power.

rdm-reserve-policy

How strictly to enforce IOMMU Reserved Memory Regions for this device.

• "strict": fail to attach the device if its reserved regions cannot be honored. Default; safer.
• "relaxed": attach the device even if reserved regions cannot be fully honored. May be required for some legacy devices.

modules

Kernel modules to load inside the zone before the device is brought up. Useful when the zone’s default kernel does not auto-load the driver for this device.

modules = ["nvme", "nvme-core"]

module-parameters

Per-module parameters to apply when loading the modules listed in modules. Keys are module names; values are arrays of parameter strings.

[pci.devices.nic0.module-parameters]
ixgbe = ["allow_unsupported_sfp=1", "max_vfs=8"]

Block

The [block] section declares host block devices the daemon may attach to zones. Each device is a named entry under [block.devices.<name>]; the name is what you reference at zone launch time (for example protect zone launch --attach-scratch-disk <name>). In a Kubernetes context, all of these settings are ignored and zone/pod block device mounts are instead managed directly by native Kubernetes block device APIs.

[block.devices.mydevice]
path = "/dev/sdb"

Device options

path

Absolute path to the host block device that should be exposed to zones under this name. The daemon does not create or partition the device; it must already exist on the host.

[block.devices.scratch0]
path = "/dev/nvme0n1"

Features

The [features] section toggles experimental feature flags. Each entry maps a feature-flag name to a state. Flags not listed in the file take their built-in default, which for every flag below is disabled. Enabling an alpha feature may log a warning at daemon startup.

[features]
fork-v0 = "enabled"
control-api-idm-v0 = "enabled"

A flag’s state is one of:

• "enabled": turn the feature on.
• "disabled": turn the feature off.
• "default": use the flag’s built-in default. All flags below default to disabled.

Options

fork-v0

Enables zone forking, currently in alpha. A forked zone is cheaply snapshotted from an existing suspended Xen PVH zone, sharing pages with the parent through a copy-on-write mechanism for tight bin-packing and efficient memory use. This flag must be enabled for protect-ctl zone fork to function.

Enabling fork-v0 disables GPU hotplug by default, because fork support and GPU hotplug are currently mutually exclusive.

control-api-idm-v0

Enables issuing Edera control plane API commands from inside Edera-managed workloads, carried over IDM. This is currently in alpha. Grant it only to workloads that need control plane access: the privilege-escalation vectors it opens are not yet fully validated.

See also

• Claiming devices with Edera: end-to-end walkthrough for adding [pci.devices] and [block.devices] entries and attaching them to a zone.
• NVIDIA GPU passthrough: example [pci.devices] configuration for GPUs.
• Using storage in Kubernetes - end-to-end walkthrough for using block devices in Kubernetes.
• Kubernetes networking with Edera - networking in Kubernetes.