pivirtd Architecture

pivirtd is the core hypervisor daemon responsible for direct QEMU/KVM virtual machine orchestration, sparse disk management, network TAP allocation, and QMP telemetry.

Component Architecture

flowchart TB
    subgraph pivirtd[pivirtd]
        subgraph grpc["gRPC Server (Port 9001)"]
            vms[VMService]
            disk[DiskService]
            net[NetService]
            cluster[ClusterService]
        end
        subgraph core[Core Engine]
            vm[VM Manager]
            dmanager[Disk Manager]
            nmanager[Net Manager]
            snapshot[Snapshot Manager]
        end
        subgraph qemu[QEMU/KVM Interface]
            qmp[QMP Monitor]
            block[Block Drivers]
            migration["Migration (NBD/TCP)"]
        end
    end

Data Flow

VM Creation Flow

sequenceDiagram
    participant Client
    participant gRPC
    participant VMManager
    participant DiskManager
    participant NetManager
    participant QEMU

    Client->>gRPC: CreateVM(spec)
    gRPC->>VMManager: Validate spec
    VMManager->>DiskManager: Create disks
    DiskManager-->>VMManager: Disk paths
    VMManager->>NetManager: Create NICs
    NetManager-->>VMManager: NIC configs
    VMManager->>QEMU: Define VM
    QEMU-->>VMManager: VM UUID
    VMManager-->>gRPC: VM object
    gRPC-->>Client: Success

VM Start Flow

sequenceDiagram
    participant Client
    participant gRPC
    participant VMManager
    participant QMP
    participant QEMU

    Client->>gRPC: StartVM(id)
    gRPC->>VMManager: Load VM config
    VMManager->>QMP: Connect to QEMU
    QMP->>QEMU: cont (continue)
    QEMU-->>QMP: Running
    QMP-->>VMManager: Status
    VMManager-->>gRPC: Operation
    gRPC-->>Client: Success

Storage Architecture

flowchart TB
    subgraph storage[Storage Layer]
        subgraph diskmgr[Disk Manager]
            local["Local (dir)"]
            lvm["LVM (thin)"]
            iscsi["iSCSI (block)"]
            nfs["NFS (file)"]
        end
        subgraph blocklayer[Block Layer]
            raw["Raw (direct)"]
            qcow2["QCOW2 (CoW)"]
            vmdk["VMDK (compat)"]
            vdi["VDI (VirtualBox)"]
        end
    end

On-Disk Storage Directory Structure

The storage layer isolates daemon runtime files, golden templates, copy-on-write overlays, and VM runtime state as follows:

• Directoryvar/

  • Directorylib/

    • Directorypivirt/

      • Directorydaemon/

        • pivirtd.sock QMP / gRPC Unix domain control socket
        • pivirtd.pid Daemon lockfile
      • Directoryimages/ Base image templates (read-only golden images)

        • debian-12-genericcloud.qcow2
        • ubuntu-24.04-server.qcow2
      • Directoryvms/ Instance directories (isolated per VM UUID)

        • Directory<vm-uuid>/

          • vm.json Persisted VM runtime configuration
          • disk-0.qcow2 Delta / CoW disk overlay referencing backing template
          • nvram.fd Persistent UEFI variables store
          • qmp.sock Dedicated QEMU monitor socket
          • qga.sock Dedicated QEMU guest-agent socket
          • console.log Serial ringbuffer output capture
      • Directorypools/ Mounted remote cluster pools (OCFS2, NFS)

        • Directorycluster-san/

          • …
  • Directorycache/

    • Directorypivirtd/

      • Directoryimages/ Downloaded remote template image cache

        • …

---

Network Architecture

flowchart TB
    subgraph network[Network Layer]
        subgraph netmgr[Network Manager]
            bridge["Bridge (L2)"]
            vlan["VLAN (802.1q)"]
            vxlan["VXLAN (Overlay)"]
            sriov["SR-IOV (Passthru)"]
        end
        subgraph vnic[Virtual NIC Layer]
            virtio["virtio (native)"]
            e1000["e1000 (compat)"]
            vmxnet3["vmxnet3 (VMware)"]
            rtl8139["rtl8139 (legacy)"]
        end
    end

---

Migration Architecture

Live Migration (Shared Storage)

sequenceDiagram
    participant Source as Source Node
    participant Target as Target Node
    participant Storage as Shared Storage

    Source->>Target: Migrate memory state
    Source->>Storage: Access disk images (shared)
    Target->>Storage: Access disk images (shared)
    Note over Source,Target: VM continues running on target

Live Migration (Shared-Nothing / Block Migration)

sequenceDiagram
    participant Source as Source Node
    participant Target as Target Node

    Source->>Target: Pre-copy memory + NBD block mirror
    Source->>Target: Final dirty block sync
    Source->>Target: Pause VM on source, hand over CPU state
    Target->>Target: Resume VM on target