Configuration Architecture & Layout

PiVirt utilizes a layered, declarative configuration model with YAML definitions, runtime environment variable overrides, and external secret integration across all services.

Configuration Hierarchy

Configuration settings are evaluated in strict order of precedence (highest to lowest):

1. Command-line flags (--config, --grpc-addr, etc.) — Highest priority
2. Environment variables (PIVIRT_*, PIVIRTD_*)
3. Configuration files (/etc/pivirt-*/config.yaml or /var/lib/pivirt/pivirtd.yaml)
4. Built-in default values — Lowest priority

---

Configuration Files Layout

The file tree below outlines all configuration files across PiVirt components, indicating which files you need to edit during installation and maintenance:

• Directoryetc/

  • Directorypivirtd/

    • config.yaml Primary hypervisor daemon config (edit listen address, hypervisor, storage pools)
    • Directorytls/

      • server.crt Node TLS server certificate
      • server.key Node TLS private key
      • ca.crt Cluster CA certificate bundle
  • Directorypivirt-agent/

    • config.yaml Agent RPC & service mesh config (edit ConnectRPC endpoint, PiTrust TLS & etcd)
    • Directoryetcd/

      • ca.crt etcd client CA
      • client.crt etcd mTLS certificate
      • client.key etcd mTLS private key
  • Directoryiscsiman/

    • config.yaml iSCSI target/initiator storage cluster manager config
  • Directorydeployer/

    • config.yaml Bare-metal bootstrap & Talos node deployer config
• Directoryhome/

  • Directory<user>/

    • Directory.config/

      • Directorypvcli/

        • config.yaml CLI client configuration (edit current cluster context & credentials)
• Directoryvar/

  • Directorylib/

    • Directorypivirt/

      • pivirtd.yaml Alternative base directory config file
      • Directorydaemon/

        • pivirtd.sock Local control Unix domain socket
      • Directoryimages/ Default base storage pool directory for VM images

        • …
  • Directorylog/

    • Directorypivirtd/ Daemon runtime logs (when not using journald)

      • …

---

Component Configuration Matrix

Component	Default File Location	Systemd Service	Purpose
pivirtd	/etc/pivirtd/config.yaml	pivirtd.service	Hypervisor engine, QEMU/KVM lifecycle & local storage
agent	/etc/pivirt-agent/config.yaml	pivirt-agent.service	ConnectRPC edge proxy, PiTrust mTLS & service mesh
pvcli	~/.config/pvcli/config.yaml	User CLI	Operator CLI client targeting agent or pivirtd
iscsiman	/etc/iscsiman/config.yaml	iscsiman.service	Dynamic LUN allocation & iSCSI SAN manager
deployer	/etc/deployer/config.yaml	pivirt-deployer.service	Bare-metal Talos & OS node auto-provisioner

---

Environment Variables

All configuration values can be overridden with environment variables using the standard hierarchical format:

PIVIRT_<COMPONENT>_<SECTION>_<KEY>

For direct pivirtd daemon parameters:

PIVIRTD_<KEY>

Common Overrides

# Hypervisor daemon overrides
PIVIRTD_LISTEN_TCP="0.0.0.0:8443"
PIVIRTD_LOG_LEVEL="debug"
PIVIRTD_STORAGE_DIR="/mnt/fast-nvme/images"

# Agent cluster overrides
PIVIRT_AGENT_SERVER_CONNECTRPC_ADDR="0.0.0.0:443"
PIVIRT_AGENT_TLS_ENABLED="true"
PIVIRT_ISCSIMAN_CLUSTER_NAME="budapest-dc-prod"

---

Secret Management

Secrets and private keys should never be hardcoded into configuration files. PiVirt supports external secret references via URI schemes:

# HashiCorp Vault lookup
password_ref: "vault:secret/data/pivirt/db#password"

# Filesystem path
cert_ref: "file:/etc/pivirtd/tls/server.crt"

# Environment variable lookup
token_ref: "env:PIVIRT_API_TOKEN"

---

Configuration Validation & Hot Reload

Before restarting production services, validate your configuration syntax:

# Validate pivirtd configuration syntax and binary dependencies
pivirtd --config /etc/pivirtd/config.yaml --validate

# Validate agent configuration syntax and etcd connectivity
pivirt-agent --config /etc/pivirt-agent/config.yaml --validate

Certain parameters (such as log levels, certificate renewals, and pool refreshes) support dynamic reload without dropping active VM connections:

# Hot-reload pivirtd configuration
pivirtd reload
# Or via systemd SIGHUP
sudo systemctl reload pivirtd

# Hot-reload agent configuration
pivirt-agent reload

---

Next Steps

• pivirtd Configuration — Detailed daemon flags and Viper keys
• Agent Configuration — ConnectRPC, PiTrust identity, and etcd mesh
• Storage Configuration — Defining dir, LVM, iSCSI, and OCFS2 storage pools
• Networking Configuration — Linux bridge, VLAN, and VXLAN parameters