Host configuration file

The host configuration file holds the settings that belong to this machine rather than to any lab: the subnet pool, the DNS suffix, the pre-shared key for cross-host segments, the viewer command, and the workspace syncer's size guard. Host configuration and WSL 2 explains when to change each one; this chapter lists the fields.

Where it lives

The file is config.wcl in vmlab's XDG config directory, which is ~/.config/vmlab/ unless XDG_CONFIG_HOME moves it. See Files and directories. It is optional: when the file is absent every default applies. When present it must start with import <vmlab-host.wcl>, and a file without the import is rejected with an error naming the missing line. The daemons read it when they start, so a change takes effect on the next vmlab up after the supervisor restarts.

import <vmlab-host.wcl>

host {
  subnet_pool = "10.99.0.0/16"
  dns_suffix  = "lab.local"
  psk         = "shared-secret"
  viewer      = "vncviewer {}"
}

host {}

The one block the file carries. Every field is an override: an absent field leaves the default in place, and a malformed one is reported with its line rather than silently ignored.

host {
  subnet_pool          = "10.213.0.0/16"
  dns_suffix           = "vmlab.internal"
  dns_upstream         = "1.1.1.1:53"
  disk_low_percent     = 10
  psk                  = "…"
  trunk_port           = 13947
  viewer               = "vncviewer {}"
  fastpath             = "auto"
  oci_chunk_size       = 512MiB
  config_weave_bin_dir = "~/.local/share/config-weave/bin"
  workspace_max_file   = 256MiB
  firmware_dir         = "/opt/vmlab-firmware"
}

The parser enforces these rules, and reports every violation in one pass:

• subnet_pool is a well-formed CIDR.
• disk_low_percent is between 0 and 100.
• trunk_port is between 1 and 65535.
• fastpath is one of auto, off, sockmap, afxdp. The VMLAB_FASTPATH environment variable selects the same values.
• oci_chunk_size and workspace_max_file are non-negative sizes.
• A field the schema does not name is rejected with its position.

workspace_max_file is host config rather than a @dev argument because the cap is about this developer's link to the guest, not the lab everyone shares; the refusal message names the field. See Dev machines and the workspace syncer. firmware_dir is authoritative for an architecture it has a directory for: a pair missing from <dir>/<arch>/ is an error, never a fall back to firmware you did not choose. An architecture with no directory there uses the bundled set. See Host configuration and WSL 2.