# daemon.toml

`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:

```bash
sudo systemctl restart protect-daemon
```

## OCI

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

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

### Options

| Option                | Type    | Default                  | Description                                                                                   |
|----------------------|---------|--------------------------|-----------------------------------------------------------------------------------------------|
| `docker-hub-mirror`  | string  | `"index.docker.io"`    | Registry hostname to use in place of Docker Hub when resolving unqualified image references. |

### `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.

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

## Zone

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

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

### Options

| Option                     | Type      | Default          | Description                                                                                    |
|---------------------------|-----------|------------------|------------------------------------------------------------------------------------------------|
| `cache-default-kernel`    | boolean   | `true`           | Cache the default zone kernel image on disk for reuse across zone launches.                    |
| `cache-default-initrd`    | boolean   | `true`           | Cache the default zone initrd image on disk for reuse across zone launches.                    |
| `memory-limit-mb`         | integer   | `1024`           | Default memory limit, in megabytes, applied to a zone when it is launched without an explicit memory size.  |
| `destroyed-linger-seconds`| integer   | `600`            | How long, in seconds, a destroyed zone’s record and console log are retained for post-mortem inspection. Set to `0` to disable.|

### `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. 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.

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

## 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]`.

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

### Options

| Option                      | Type    | Default         | Description                                                                                 |
|----------------------------|---------|-----------------|---------------------------------------------------------------------------------------------|
| `xen.x86-turbo`            | string  | `"automatic"`  | x86 turbo-mode (Intel Turbo Boost, AMD Core Performance Boost) policy applied to all host CPUs through Xen. One of `"automatic"`, `"enabled"`, or `"disabled"`.  |
| `xen.cpu-frequency-governor`| string  | `"performance"`| CPU-frequency governor applied to all host CPUs through Xen. One of `"performance"` or `"power-save"`. |

### `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.

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

### Options

| Option                        | Type      | Default         | Description                                                                             |
|------------------------------|-----------|-----------------|-----------------------------------------------------------------------------------------|
| `enable-metrics-endpoint`    | boolean   | `true`          | Bind and host a Prometheus `/metrics` endpoint at `metrics-endpoint-address`.          |
| `enable-zone-metrics`        | boolean   | `true`          | Establish a metrics listener for each running managed zone and cache the results for the metrics endpoint and the `ReadZoneMetrics` RPC.  |
| `zone-metrics-heartbeat-interval-seconds`| integer   | `5` | How often, in seconds, each zone is configured to send the daemon an updated metrics snapshot. |
| `metrics-endpoint-address`    | string    | `"127.0.0.1:3035"` | Socket address the Prometheus `/metrics` endpoint binds to when `enable-metrics-endpoint` is `true`. |

### `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.

### `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.

### `zone-metrics-heartbeat-interval-seconds`

How often, in seconds, the daemon configures each zone to send it an updated metrics snapshot.

### `metrics-endpoint-address`

Socket address the Prometheus `/metrics` endpoint binds to when `enable-metrics-endpoint` is `true`.

```toml
[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.

```toml
[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

| Option              | Type              | Default                                            | Description                                                                               |
|--------------------|-------------------|---------------------------------------------------|-------------------------------------------------------------------------------------------|
| `nameservers`      | array of strings   | Cloudflare public resolvers                       | DNS resolvers handed to zones.                                                          |
| `ipv4.subnet`      | string            | `"10.75.0.0/16"`                               | CIDR from which IPv4 addresses are allocated to zones.                                  |
| `ipv6.subnet`      | string            | `"fdd4:1476:6c7e::/48"`                         | CIDR from which IPv6 addresses are allocated to zones.                                  |

### `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`).

```toml
[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.

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

### `ipv6.subnet`

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

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

## PCI

The `[pci]` section declares PCI devices the daemon may pass through to zones.

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

### Device options

| Option                | Type                | Default        | Description                                                                                   |
|-----------------------|---------------------|-----------------|----------------------------------------------------------------------------------------------|
| `locations`           | array of strings     | required        | PCI bus addresses (BDF) that make up this device, for example `"0000:01:00.0"`.          |
| `permissive`          | boolean             | `false`        | Allow the zone to access PCI configuration space normally restricted by the hypervisor.     |
| `msi-translate`       | boolean             | `false`        | Translate MSI interrupts on behalf of the zone.                                               |
| `power-management`     | boolean             | `false`        | Allow the zone to manage device power state.                                                |
| `rdm-reserve-policy`  | string              | `"strict"`    | RMRR (Reserved Memory Region) reservation policy. One of `"strict"` or `"relaxed"`.    |
| `modules`              | array of strings     | `[]`           | Kernel modules to load in the zone for this device.                                         |

### `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.

```toml
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.

```toml
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.

```toml
[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.

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

### Device options

| Option | Type   | Default                       | Description                                                |
|--------|--------|-------------------------------|------------------------------------------------------------|
| `path` | string | required                      | Absolute path to the host block device, for example `/dev/sdb` or `/dev/nvme0n1`. |

### `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.

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

## Features

The `[features]` section toggles experimental feature flags.

```toml
[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

| Option                        | Type      | Default         | Description                                                               |
|------------------------------|-----------|-----------------|---------------------------------------------------------------------------|
| `fork-v0`                    | string    | `"disabled"`   | Enable zone forking (alpha): cheaply snapshot a new zone from an existing suspended Xen PVH zone. |
| `control-api-idm-v0`         | string    | `"disabled"`   | Enable issuing Edera control plane API commands from inside Edera-managed workloads over IDM (alpha). |

### `fork-v0`

Enables zone forking, currently in alpha. A forked zone is cheaply snapshotted from an existing suspended Xen PVH zone.

### `control-api-idm-v0`

Enables issuing Edera control plane API commands from inside Edera-managed workloads, carried over IDM. This is currently in alpha.