pivirtd Configuration

The pivirtd hypervisor daemon is configured via YAML at /etc/pivirtd/config.yaml or /var/lib/pivirt/pivirtd.yaml. It manages VM state directories, storage pool mappings, and local gRPC Unix sockets.

Configuration Locations & File Tree

pivirtd uses Viper to manage configuration settings. Configuration values can be loaded from YAML/TOML config files or overridden using PIVIRTD_* environment variables.

The file tree below highlights the key files you need to edit on each hypervisor node:

Directoryetc/
- Directorypivirtd/
  - config.yaml Main daemon configuration file (edit listen ports, hypervisor, storage pools)
  - Directorytls/
    server.crt TLS server certificate for TCP listener
    server.key TLS private key
    ca.crt Trusted root CA bundle
Directoryvar/
- Directorylib/
  - Directorypivirt/
    pivirtd.yaml Alternative base directory config file
    Directorydaemon/
    pivirtd.sock Unix domain control socket for local gRPC / pvcli operations
    Directoryimages/ Default storage directory for VM base images and qcow2 disks
    …
    Directoryvms/ Instance working directories with per-VM sockets, NVRAM, and logs
    …
- Directorylog/
  - Directorypivirtd/
    pivirtd.log Daemon runtime log (when file logging is selected)

Configuration Example

Below is a complete /etc/pivirtd/config.yaml file showing the core parameters:

# /etc/pivirtd/config.yaml (or /var/lib/pivirt/pivirtd.yaml)
base_path: "/var/lib/pivirt"
socket_path: "/var/lib/pivirt/daemon/pivirtd.sock"
qemu_bin_path: "/usr/bin/qemu-system-x86_64"
qemu_img_bin_path: "/usr/bin/qemu-img"
machine: "q35"
log_level: "info"
storage_dir: "/var/lib/pivirt/images"
ovmf_path: "/usr/share/OVMF/OVMF_CODE.fd"
nvram_path: "/usr/share/OVMF/OVMF_VARS.fd"
listen_tcp: "0.0.0.0:8443"
tls_cert_file: "/etc/pivirtd/tls/server.crt"
tls_key_file: "/etc/pivirtd/tls/server.key"

Configuration Reference Table

Field Key	Environment Variable	Default Value	Description
`base_path`	`PIVIRTD_BASE_PATH`	`/var/lib/pivirt`	Base directory for daemon files and VM subdirectories
`socket_path`	`PIVIRTD_SOCKET`	`/var/lib/pivirt/daemon/pivirtd.sock`	Path to Unix domain socket for gRPC / CLI operations
`qemu_bin_path`	`PIVIRTD_QEMU_BIN_PATH`	`/usr/bin/qemu-system-x86_64`	Path to QEMU system binary
`qemu_img_bin_path`	`PIVIRTD_QEMU_IMG_BIN_PATH`	`/usr/bin/qemu-img`	Path to `qemu-img` disk utility binary
`machine`	`PIVIRTD_MACHINE`	`q35` (x86_64) / `virt` (ARM64)	QEMU machine type architecture
`log_level`	`PIVIRTD_LOG_LEVEL`	`info`	Logging verbosity (`debug`, `info`, `warn`, `error`)
`storage_dir`	`PIVIRTD_STORAGE_DIR`	`/var/lib/pivirt/images`	Default image and storage volume directory
`ovmf_path`	`PIVIRTD_OVMF_PATH`	`/usr/share/OVMF/OVMF_CODE.fd`	Auto-detected path to UEFI firmware code file
`nvram_path`	`PIVIRTD_NVRAM_PATH`	`/usr/share/OVMF/OVMF_VARS.fd`	Auto-detected path to NVRAM variables template file
`listen_tcp`	`PIVIRTD_LISTEN_TCP`	`""`	Optional TCP listen address for network access
`tls_cert_file`	`PIVIRTD_TLS_CERT_FILE`	`""`	TLS certificate path for TCP listener
`tls_key_file`	`PIVIRTD_TLS_KEY_FILE`	`""`	TLS private key path for TCP listener

Service Management

After editing /etc/pivirtd/config.yaml, restart or reload the daemon:

# Verify configuration
pivirtd --config /etc/pivirtd/config.yaml --validate

# Restart service via systemd
sudo systemctl restart pivirtd

# Check operational status
sudo systemctl status pivirtd