---
paths:
  - "notes/networking-guide.md"
  - "notes/shared-storage-guide.md"
  - "notes/migration-guide.md"
  - "notes/utm-support.md"
---

# Networking, Storage, and Migration

## OVN networking

- **Bridge networks are node-local**: same subnet but separate L2 domains.
- **OVN**: cross-node L2 overlay via Geneve tunnels. Sub-ms latency.
- **IncusOS OVN services disabled by default**: enable via `/os/1.0/services/ovn` on EVERY node.
- OVN service enable:
  ```bash
  incus query <remote>:/os/1.0/services/ovn --request PUT --data '{
    "config": {
      "database": "tcp:<SB_HOST>:6642",
      "enabled": true,
      "tunnel_address": "<THIS_NODE_LAN_IP>",
      "tunnel_protocol": "geneve"
    }, "state": {}
  }'
  ```
  `database` is **southbound** (6642), NOT northbound (6641).
- **Setup sequence**: deploy OVN container -> enable services -> set northbound
  connection -> add ovn-chassis roles -> create uplink -> create OVN network.
- **Uplink**: `parent=mgmt` (NOT `ens18`). `ipv4.ovn.ranges` + `ipv4.gateway`.
- **LB/forward backends need IP addresses**, not instance names.
- See `notes/networking-guide.md` for full tutorial.

## Shared storage (iSCSI + lvmcluster)

- IncusOS-native: iSCSI initiator, lvmlockd, sanlock built in.
- **iSCSI API**: `/os/1.0/services/iscsi`. Field is `"target"` (NOT `"iqn"`).
- **LVM API**: `/os/1.0/services/lvm`. `system_id` must be 1-2000 (not 0).
- **lvmcluster**: thick provisioning. Two-step cluster pattern for pool creation.
- **Migration perf** (1GbE): container 0.15s, VM non-live 1.8s, VM live ~6s.
- **Proxy devices don't work for iSCSI** (portal mismatch). Use direct paths.
- **First live migration after stop/start may fail** (transient sanlock). Retry works.
- **Hybrid recommended**: local ZFS + shared lvmcluster for HA VMs.
- See `notes/shared-storage-guide.md` for full walkthrough.

## Migration into Incus

- `incus-migrate`: official import tool. `qemu-img convert` for format conversion.
- Workflow: convert disk -> `incus storage volume import` -> `incus init --empty --vm`
  -> attach -> start.
- Docker: `docker export` -> `incus import`.
- See `notes/migration-guide.md` for per-hypervisor procedures.

## UTM support (future)

- Design doc at `notes/utm-support.md`.
- `utmctl` for start/stop but not VM creation (AppleScript or `.utm` bundle).
- No `blockstat` equivalent -- timeout + port polling for install detection.