Skip to content

configuration.md

Latest commit

 

History

History
289 lines (207 loc) · 8.88 KB

configuration.md

File metadata and controls

289 lines (207 loc) · 8.88 KB

urunc supports configuration through a TOML configuration file that allows you to customize various runtime behaviors including logging, timestamping, and monitor defaults. This document explains how to configure urunc using the configuration file.

Configuration File Location

urunc looks for its configuration file at /etc/urunc/config.toml. If the file doesn't exist or contains invalid configuration, urunc will use sensible defaults and continue to operate normally.

Configuration File Format

The configuration file uses the TOML format and is organized into several sections:

[log]
level = "info"
syslog = false

[timestamps]
enabled = false
destination = "/var/log/urunc/timestamps.log"

[monitors.qemu]
default_memory_mb = 512
default_vcpus = 2
path = "/usr/bin/qemu-system-x86_64"

[monitors.firecracker]
default_memory_mb = 256
default_vcpus = 1
path = "/usr/local/bin/firecracker"

[monitors.hvt]
default_memory_mb = 256
default_vcpus = 1

[monitors.spt]
default_memory_mb = 256
default_vcpus = 1

[extra_binaries.virtiofsd]
path = "/usr/libexec/virtiofsd"
options = "--sandbox none"

[rootfs_view]
enabled = false

Configuration Sections

Log Configuration

The [log] section controls logging behavior for urunc:

Option Type Default Description
level string "info" Log level. Valid values: "trace", "debug", "info", "warn", "error", "fatal", "panic"
syslog boolean false Enable syslog output in addition to stderr

Example:

[log]
level = "debug"
syslog = true

Note: The effective log level is determined by both the configuration file and the command-line --debug flag.

  • If --debug is not specified, the log level from the configuration file is used.
  • If --debug is specified, the effective log level is the more verbose of:
    • the configuration file’s log level, and
    • "debug" (the level implied by the flag).

For example:

  • Config: "warn", CLI: --debug → effective level = "debug"
  • Config: "trace", CLI: --debug → effective level = "trace"
  • Config: "error", no --debug → effective level = "error"

Timestamps Configuration

The [timestamps] section controls timestamp logging for performance monitoring:

Option Type Default Description
enabled boolean false Enable timestamp logging for performance metrics
destination string "/var/log/urunc/timestamps.log" File path where timestamps will be written

Example:

[timestamps]
enabled = true
destination = "/tmp/urunc-timestamps.log"

When enabled, urunc will log performance timestamps to help with debugging and optimization.

Rootfs View Configuration

The [rootfs_view] section controls whether the urunc shim prepares a per-container containerd rootfs view at task Create (for devmapper / blockfile snapshotters).

Option Type Default Description
enabled boolean false Prepare rootfs views for container block rootfs after shim task Create

When enabled = true, the shim first lets the wrapped task service create the task so the bundle rootfs is mounted. It then runs ChooseRootfs and prepares a view only if all of the following hold:

  1. The container snapshotter is block-based (devmapper or blockfile).
  2. Shim ChooseRootfs selected container block rootfs (type=block with a non-empty MountedPath).

This matches the block-rootfs boot-artifact path: kernel/initrd are read from a read-only view instead of being copied out of the container rootfs before attach.

Example:

[rootfs_view]
enabled = true

Monitor Configuration

The [monitors] section allows you to configure default settings for different VM/Sandbox monitors. Each monitor is configured as a subsection with its own default values.

Supported monitors and their respective subsection names

Monitor Options

Each monitor subsection supports the following options:

Option Type Default Description
default_memory_mb integer 256 Default memory allocation in megabytes
default_vcpus integer 1 Default number of virtual CPUs
path string (empty) Optional custom path to the monitor binary. If not specified, urunc will search for the binary in PATH
data_path string (empty) Optional custom path for the monitor's data file directory

Since Qemu is the only currently supported monitor which requires extra data to boot a VM, urunc will first check /usr/local/share and then /usr/share for Qemu's data files.

Example:

[monitors.qemu]
default_memory_mb = 1024
default_vcpus = 4
path = "/usr/local/bin/qemu-system-x86_64"
data_path = "/usr/local/share/"

[monitors.firecracker]
default_memory_mb = 512
default_vcpus = 2
path = "/opt/firecracker/firecracker"

Extra binaries Configuration

The [extra_binaries] section allows users to configure default settings for different extra binaries to be included in the monitor's container. Each extra binary is configured as a subsection with its own default values.

Supported extra binaries

  • virtiofsd - vhost-user virtio-fs device backend written in Rust

Extra binaries Options

Each extra binary subsection supports the following options:

Option Type Default Description
path string (empty) Optional custom path to the extra binary. If not specified, urunc will search for the binary in PATH
options string (empty) Optional custom cli options for the extra binary

Specifically for virtiofsd the default values are the following:

  • path: /usr/libexec/virtiofsd
  • options: --cache always --sandbox none

Example:

[extra_binaries.virtiofsd]
path = "/usr/local/bin/virtiofsd"
options = "--sandbox none --cache always"

Creating the Configuration File

To create a configuration file, you can:

  1. Create the directory structure:

    sudo mkdir -p /etc/urunc

  2. Create the configuration file:

    sudo tee /etc/urunc/config.toml > /dev/null <<EOF
[log]
level = "info"
syslog = false

[timestamps]
enabled = false
destination = "/var/log/urunc/timestamps.log"

[monitors.qemu]
default_memory_mb = 512
default_vcpus = 2

[monitors.firecracker]
default_memory_mb = 256
default_vcpus = 1

[monitors.hvt]
default_memory_mb = 256
default_vcpus = 1

[monitors.spt]
default_memory_mb = 256
default_vcpus = 1

[rootfs_view]
enabled = false
EOF

Configuration Validation

urunc will validate the configuration file when it starts. If the configuration file:

  • Does not exist: urunc uses default values and logs a warning
  • Contains syntax errors: urunc uses default values and logs a warning about the parsing error
  • Contains invalid values: urunc will either use default values for invalid fields or fail to start if critical errors are found

Default Values

If no configuration file is provided, urunc uses these default values:

[log]
level = "info"
syslog = false

[timestamps]
enabled = false
destination = "/var/log/urunc/timestamps.log"

[monitors.qemu]
default_memory_mb = 256
default_vcpus = 1
# path is not set by default - urunc will search in PATH

[monitors.firecracker]
default_memory_mb = 256
default_vcpus = 1
# path is not set by default - urunc will search in PATH

[monitors.hvt]
default_memory_mb = 256
default_vcpus = 1
# path is not set by default - urunc will search in PATH

[monitors.spt]
default_memory_mb = 256
default_vcpus = 1
# path is not set by default - urunc will search in PATH

[rootfs_view]
enabled = false

Notes

  • The configuration file is only fully loaded during urunc create. The configuration options' values are then stored as Annotations in the state.json file inside the respective container's bundle. For subsequent urunc commands (such as start, kill, etc.), configuration options are loaded from the state.json annotations. In that way, all urunc configuration values except logging configuration and timestamping (see below) remain the same throughout the specific container lifecycle.
  • The configuration file is partially loaded every time urunc is invoked to parse the logging configuration and timestamping options. This way, the user has fine-grained control over the logging level and whether to redirect urunc logs to syslog. Similarly, the user can enable and disable timestamping.