Skip to main content

Admin basics

Operate FluxVM on a host: service, ports, auth, logs, and production gates.

Service​

sudo systemctl enable --now fluxvm # if unit installed by deploy
# or foreground:
sudo fluxctl --config /etc/fluxvm.toml serve

TTL reaper and warm-pool backfill run only while serve is up.

Host dependencies​

./scripts/bootstrap-host.sh
# Windows offline customize needs libhivex + nbd:
sudo modprobe nbd max_part=16

Remote: ./scripts/deploy-remote.sh USER@HOST.

Ports​

PortRole
7788FluxVM REST (fluxctl serve)
9108Optional MicroVM Prometheus (MICROVM_METRICS_ADDR)

Fabric (separate product) typically listens on 9095 and proxies FluxVM.

Health​

curl -sf http://127.0.0.1:7788/healthz
curl -sf http://127.0.0.1:7788/readyz | jq .

Both are auth-exempt. Use /readyz when dataplane must be ready before work.

Auth (opt-in)​

Default: open API (every request is admin). Before exposing beyond localhost:

[auth]
require = true

[[auth.tokens]]
token = "replace-me"
role = "admin"
name = "ops"
# tenant = "team-a" # optional scope
curl -sf -H "Authorization: Bearer replace-me" http://127.0.0.1:7788/v1/vms

List/filter: GET /v1/vms?tenant=team-a. See PRODUCTION.md and SECURITY.md.

State and logs​

PathRole
<state_dir>/vms.jsonVM inventory (flock via vms.lock)
<state_dir>/instances/<uuid>/console.logPer-VM console
<state_dir>/instances/<uuid>/serial.sockQEMU serial socket (fluxctl serial)
<state_dir>/instances/<uuid>/disks/QEMU data disks (fluxctl disk)
<state_dir>/events.jsonlLifecycle/audit events (fluxctl events)
<state_dir>/vm-templates.jsonVM templates (fluxctl vm-template)
<state_dir>/backups/VM backups (fluxctl backup)
journalctl -u fluxvm -fDaemon journal

AppArmor and Kairon​

On Ubuntu the AppArmor profile (deploy/apparmor/fluxvm) runs in enforce mode. After upgrading, reload it:

sudo install -m 0644 deploy/apparmor/fluxvm /etc/apparmor.d/fluxvm
sudo apparmor_parser -r /etc/apparmor.d/fluxvm

If a Kairon Machine goes to Error with opening base image /var/lib/kairon-node/image-cache/...: Permission denied, the loaded profile is older than the rule that lets FluxVM read Kairon's image cache. Confirm with journalctl -k | grep 'apparmor="DENIED"', then reload as above. If you edited /etc/apparmor.d/fluxvm by hand (for example an extra QEMU path), merge the new rule instead of overwriting the file. A storage=shared disk outside /var/lib/fluxvm also needs the profile's file-lock permission for QEMU's image lock.

Live migration across hosts​

A migration receiver boots the same concrete machine type as the source (for example pc-q35-noble), and creating one fails up front when the receiving host's QEMU does not list that type: migrate to the same or a newer QEMU release. A receiver that is still receiving past its time limit is kept until the transfer ends. Details: operations.

Production checklist​

./scripts/release-checklist.sh