Storage Configuration

PiVirt provides a multi-backend storage engine supporting local directories, LVM thin provisioning, remote iSCSI SANs, NFS exports, and OCFS2 cluster shared filesystems.

---

Storage Filesystem & Configuration Layout

The file tree below shows where storage pools are mapped on the hypervisor host and where storage settings must be edited:

• Directoryetc/

  • Directorypivirtd/

    • config.yaml Edit storage.pools and storage.defaults sections here
• Directoryvar/

  • Directorylib/

    • Directorypivirt/

      • Directoryimages/ Default local directory pool for base images & VM disks

        • debian-12-genericcloud.qcow2
        • ubuntu-24.04-server.qcow2
      • Directorypools/ Mount points for external storage backends

        • Directorynfs-shared/ NFS volume pool mount

          • …
        • Directoryocfs2-cluster/ OCFS2 cluster filesystem mount

          • …
  • Directorycache/

    • Directorypivirtd/

      • Directoryimages/ Local cache directory for downloaded OS templates

        • …
• Directorymnt/

  • Directorystorage-san/ Target mountpoint for multipath / iSCSI block storage

    • …
• Directorydev/

  • Directorypivirtd-vg/ LVM Volume Group (when using lvm backend)

    • pivirtd-thin LVM thin pool metadata & data LV

---

Storage Pool Definitions

Storage pools are declared under the storage.pools list in /etc/pivirtd/config.yaml:

1. Local Directory Pool (dir)

Recommended for standalone nodes, dev environments, and fast local NVMe storage:

/etc/pivirtd/config.yaml

storage:
  default_pool: "default"
  pools:
    - name: "default"
      type: "dir"
      path: "/var/lib/pivirt/images"
      # Optional permissions & ownership
      permissions: "0755"
      owner: "pivirtd"
      group: "kvm"

2. LVM Thin Pool (lvm)

Provides sub-millisecond volume snapshots and thin provisioning:

storage:
  pools:
    - name: "lvm-pool"
      type: "lvm"
      volume_group: "pivirtd-vg"
      thin_pool: "pivirtd-thin"
      thin_provisioning: true
      discard: true

3. iSCSI SAN Pool (iscsi)

Connects to high-availability SAN storage over dedicated storage networks:

storage:
  pools:
    - name: "iscsi-pool"
      type: "iscsi"
      target_iqn: "iqn.2024-01.hu.pilab:storage"
      portal: "10.0.1.10:3260"
      lun: 0
      auth:
        username: "iscsi-user"
        password_ref: "vault:secret/data/iscsi#password"

4. NFS Shared Pool (nfs)

For cross-node image sharing and backup targets:

storage:
  pools:
    - name: "nfs-pool"
      type: "nfs"
      server: "nas.pilab.hu"
      export: "/exports/pivirt"
      version: "4.2"
      mount_options: "rw,noatime,hard,intr"

---

Volume Defaults

Set global defaults for new virtual disk allocations:

storage:
  defaults:
    format: "qcow2"       # qcow2 | raw
    bus: "virtio"         # virtio | scsi | sata
    cache: "none"         # none | writeback | writethrough
    io: "native"          # native | threads | io_uring
    discard: "unmap"      # unmap | ignore

---

Image Cache Configuration

The image cache stores downloaded cloud-init base images so repeated VM launches do not require network re-downloads:

storage:
  image_cache:
    enabled: true
    path: "/var/cache/pivirtd/images"
    max_size_gb: 100
    ttl_hours: 168

---

Environment Variable Overrides

# Override default storage pool
PIVIRTD_STORAGE_DIR="/mnt/fast-nvme/images"
PIVIRT_PIVIRTD_STORAGE_DEFAULT_POOL="default"
PIVIRT_PIVIRTD_STORAGE_IMAGE_CACHE_ENABLED="true"

---

Related Documentation

• Storage Concepts — Architectural comparison of backends
• iscsiman Overview — Clustered iSCSI management
• Storage Guides — Step-by-step guides for OCFS2, iSCSI, and Multipath