pivirtd Daemon Reference

The PiVirt Daemon (pivirtd) is the hypervisor management service responsible for direct QEMU/KVM process supervision, TAP network interfaces, and disk image operations.

Service Management

Use systemd to manage the pivirtd service.

# start the daemon
sudo systemctl start pivirtd

# stop the daemon
sudo systemctl stop pivirtd

# restart the daemon
sudo systemctl restart pivirtd

# check status
sudo systemctl status pivirtd

# enable on boot
sudo systemctl enable pivirtd

Health Endpoints

gRPC Health Check

# check pivirtd health
grpcurl -plaintext localhost:9001 grpc.health.v1.Health/Check

# check specific service
grpcurl -plaintext -d '{"service": "pivirt.vm.v1.VMService"}' \
  localhost:9001 grpc.health.v1.Health/Check

HTTP Health Check

# check pivirtd health
curl http://localhost:9002/health

# check readiness
curl http://localhost:9002/ready

# check liveness
curl http://localhost:9002/live

Management Endpoints

Reload Configuration

curl -X POST http://localhost:9002/reload

Debug Endpoints

# get debug info
curl http://localhost:9002/debug/vars

# get goroutine stack traces
curl http://localhost:9002/debug/pprof/goroutine?debug=1

# get heap profile
curl http://localhost:9002/debug/pprof/heap > heap.prof

Metrics

Prometheus Metrics

# get all metrics
curl http://localhost:9002/metrics

# get specific metrics
curl http://localhost:9002/metrics | grep pivirtd_vm_count

VM Management

List VMs

# list all VMs
grpcurl -plaintext localhost:9001 \
  pivirt.vm.v1.VMService/ListVMs

# list VMs in namespace
grpcurl -plaintext -d '{"namespace": "production"}' \
  localhost:9001 \
  pivirt.vm.v1.VMService/ListVMs

Get VM Details

# get VM by ID
grpcurl -plaintext -d '{"id": "vm-abc123"}' \
  localhost:9001 \
  pivirt.vm.v1.VMService/GetVM

Start/Stop VM

# start VM
grpcurl -plaintext -d '{"id": "vm-abc123"}' \
  localhost:9001 \
  pivirt.vm.v1.VMService/StartVM

# stop VM
grpcurl -plaintext -d '{"id": "vm-abc123"}' \
  localhost:9001 \
  pivirt.vm.v1.VMService/StopVM

Configuration Validation

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

# show effective configuration
pivirtd --config /etc/pivirtd/config.yaml --show-config

Troubleshooting

Check KVM Access

# check KVM availability
kvm-ok

# check /dev/kvm
ls -la /dev/kvm

# check kernel modules
lsmod | grep kvm

Check QEMU/KVM

# check running QEMU processes
ps aux | grep qemu-system

# list VMs through pivirtd
pvcli vm list

Debug Logging

# enable debug logging
pivirtd --config /etc/pivirtd/config.yaml --log-level debug

# view debug logs
sudo journalctl -u pivirtd -f | grep DEBUG