Configuration Reference — SwarmCracker¶

Every configuration key in swarmcracker YAML config files, with defaults, types, and descriptions.

Top-Level Structure¶

executor:   # VM execution settings
network:    # Network infrastructure
logging:    # Log output configuration
images:     # Image preparation and caching
metrics:    # Metrics collection
snapshot:   # Snapshot management
jailer:     # Security jailer (deprecated — use executor.jailer)

executor¶

executor.name¶

Executor backend name. Currently only "firecracker" is supported.

executor.kernel_path¶

Path to the uncompressed Linux kernel ELF binary used to boot all VMs.

executor.initrd_path¶

Optional path to an initrd image. Leave empty to boot directly from the rootfs.

executor.rootfs_dir¶

Directory where OCI images are converted to ext4 root filesystems. Each image gets a subdirectory based on its content hash.

executor.socket_dir¶

Directory for Firecracker Unix domain sockets. One socket per VM, named <task-id>.sock.

executor.default_vcpus¶

Default number of virtual CPUs per VM when not specified in the task spec.

executor.default_memory_mb¶

Default memory in megabytes per VM when not specified in the task spec.

executor.enable_jailer¶

Enable Firecracker jailer for additional process isolation (chroot, UID/GID drop, network namespace, cgroups).

executor.init_system¶

Init system injected into the VM rootfs. tini provides proper signal handling and zombie reaping. Use none for images with their own init (e.g., systemd-based).

executor.init_grace_period¶

Seconds to wait for graceful shutdown via init system before force-killing the VM.

executor.jailer¶

Jailer sub-configuration (only used when executor.enable_jailer is true).

executor:
  enable_jailer: true
  jailer:
    uid: 1000
    gid: 1000
    chroot_base_dir: /srv/jailer
    netns: swarmcracker

network¶

network.bridge_name¶

Name of the Linux bridge interface that VMs attach to. Must be 15 characters or fewer and contain only alphanumeric, hyphen, or underscore characters.

network.subnet¶

Subnet for VM IP allocation. Each VM gets a deterministic IP from this subnet based on its task ID hash.

network.bridge_ip¶

IP address assigned to the bridge interface. Acts as the default gateway for VMs.

network.ip_mode¶

IP allocation mode. static assigns deterministic IPs via SHA-256 hash. dhcp uses dnsmasq for dynamic allocation.

network.nat_enabled¶

Enable NAT masquerading on the bridge for internet access. When false, VMs are isolated to the bridge subnet with no external connectivity.

network.enable_rate_limit¶

Enable per-VM network rate limiting.

network.max_packets_per_sec¶

Maximum packets per second per VM when rate limiting is enabled.

logging¶

logging.level¶

Log level. debug includes token operations and internal state changes. Production should use info or higher.

logging.format¶

Log output format. json for structured logging (recommended for production). console for human-readable output.

logging.output¶

Where logs are written. Use a file path like /var/log/swarmcracker/daemon.log for persistent logging.

images¶

images.cache_dir¶

Directory for OCI image layer caching. Layer caching avoids re-pulling unchanged layers.

images.max_cache_size_mb¶

Maximum total size of cached images. Oldest images are evicted when the limit is reached.

images.enable_layer_cache¶

Enable OCI layer caching. Disable to always pull fresh images.

metrics¶

metrics.enabled¶

Enable metrics collection and exposure.

metrics.address¶

Address to expose Prometheus metrics on. Bind to 127.0.0.1 for security; use 0.0.0.0 if you need remote scraping.

metrics.format¶

Metrics format. Currently only Prometheus text format is supported.

snapshot¶

snapshot.enabled¶

Enable VM snapshot support. Requires the snapshot directory to exist and be writable.

snapshot.snapshot_dir¶

Directory where VM snapshots (memory dumps + state files) are stored.

snapshot.max_snapshots¶

Maximum number of snapshots to retain. Oldest snapshots are deleted when the limit is reached.

snapshot.max_age¶

Maximum age of snapshots before they are eligible for cleanup. Supports d suffix for days.

snapshot.auto_snapshot¶

Automatically create snapshots before service updates. Recommended for production.

snapshot.compress¶

Compress snapshots to reduce disk usage at the cost of slower create/restore.

Complete Example¶

Development (single node)¶

executor:
  name: firecracker
  kernel_path: /usr/share/firecracker/vmlinux
  rootfs_dir: /var/lib/firecracker/rootfs
  socket_dir: /var/run/firecracker
  default_vcpus: 1
  default_memory_mb: 512
  init_system: tini
  init_grace_period: 10

network:
  bridge_name: swarm-br0
  subnet: 192.168.127.0/24
  bridge_ip: 192.168.127.1/24
  ip_mode: static
  nat_enabled: true

logging:
  level: debug
  format: console
  output: stderr

Production (multi-node cluster)¶

executor:
  name: firecracker
  kernel_path: /usr/share/firecracker/vmlinux
  rootfs_dir: /var/lib/firecracker/rootfs
  socket_dir: /var/run/firecracker
  default_vcpus: 2
  default_memory_mb: 512
  init_system: tini
  init_grace_period: 10
  enable_jailer: true
  jailer:
    uid: 1000
    gid: 1000
    chroot_base_dir: /srv/jailer

network:
  bridge_name: swarm-br0
  subnet: 192.168.127.0/24
  bridge_ip: 192.168.127.1/24
  ip_mode: static
  nat_enabled: true

logging:
  level: info
  format: json
  output: /var/log/swarmcracker/daemon.log

images:
  cache_dir: /var/cache/swarmcracker
  max_cache_size_mb: 20480
  enable_layer_cache: true

metrics:
  enabled: true
  address: 127.0.0.1:9100

snapshot:
  enabled: true
  snapshot_dir: /var/lib/swarmcracker/snapshots
  max_snapshots: 20
  max_age: 168h
  auto_snapshot: true
  compress: true

Configuration File Location¶

The config file is loaded from (in order of priority):

1. --config / -c CLI flag
2. SWARMCRACKER_CONFIG environment variable
3. /etc/swarmcracker/config.yaml (default)

Validation¶

# Validate config without starting
swarmcracker config validate

# Validate a specific config file
swarmcracker config validate --config /path/to/config.yaml

# Show effective configuration (defaults applied)
swarmcracker config list

See Also: CLI Reference | Operations Guide | Getting Started