agent Daemon Reference

The PiVirt Agent (pivirt-agent) runs as a system daemon on each hypervisor node, orchestrating node-level ConnectRPC services, discovery, and storage/network subsystems.

Service Management

Use systemd to manage the agent service.

# start the agent
sudo systemctl start pivirt-agent

# stop the agent
sudo systemctl stop pivirt-agent

# restart the agent
sudo systemctl restart pivirt-agent

# check status
sudo systemctl status pivirt-agent

# enable on boot
sudo systemctl enable pivirt-agent

Health Endpoints

gRPC Health Check

# check agent health
grpcurl -plaintext localhost:8443 grpc.health.v1.Health/Check

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

HTTP Health Check

# check agent health
curl http://localhost:8444/health

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

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

Management Endpoints

Reload Configuration

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

Debug Endpoints

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

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

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

Metrics

Prometheus Metrics

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

# get specific metrics
curl http://localhost:8444/metrics | grep pivirt_api_requests_total

Service Discovery

List Registered Services

# list all services
grpcurl -plaintext localhost:8443 \
  pivirt.discovery.v1.DiscoveryService/ListServices

# get specific service
grpcurl -plaintext -d '{"name": "pivirtd"}' \
  localhost:8443 \
  pivirt.discovery.v1.DiscoveryService/GetService

Configuration Validation

# validate configuration
pivirt-agent --config /etc/pivirt-agent/config.yaml --validate

# show effective configuration
pivirt-agent --config /etc/pivirt-agent/config.yaml --show-config

Troubleshooting

Check PiTrust Certificates

# verify certificate chain
openssl verify -CAfile /etc/pivirt/certs/ca-chain.pem /etc/pivirt/certs/agent-server.crt

# verify certificate details
openssl x509 -in /etc/pivirt/certs/agent-server.crt -text -noout | grep -A1 "Subject Alternative Name"

Check Service Mesh

# list backend connections
curl http://localhost:8444/debug/backends

# check backend health
curl http://localhost:8444/debug/backends/health

Debug Logging

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

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