# πŸš€ MNMIVM-SE (Server Edition) ### *A LAN-Native VM Cloud with a Minimal Control Plane* ![MNMIVM Hero](./assets/tuxrockets.jpg) ## Demo Video **MNMIVM-SE** is the **server-focused edition** of MNMIVM β€” a minimal, single-binary VM launcher built on **QEMU + KVM + cloud-init** that turns your **LAN into a local VM cloud**. Unlike traditional platforms, MNMIVM-SE exposes the raw infrastructure primitives directly: bridges, TAP devices, MAC addresses, static IPs, and Linux processes. > Your LAN is the fabric. > The kernel is the scheduler. > The CLI is the control plane. --- ## ☁️ What MNMIVM-SE Is * A **local VM cloud** built directly on your LAN * A **process-native control plane** * A **CLI-first infrastructure tool** * A Proxmox-style networking model **without Proxmox** Each VM: - Has a persistent MAC address - Has a static IP on your LAN - Appears as a first-class network device - Can host real infrastructure services (DNS, CI, storage, routing, etc.) Routers, firewalls, and switches see MNMIVM-SE VMs as **real machines**, not NAT artifacts. --- ## 🧠 Control Plane Model MNMIVM-SE **does have a control plane** β€” it’s just intentionally **minimal, local, and explicit**. The control plane is implemented as: - A single CLI binary - A file-backed state store - Linux process lifecycle tracking There is: - No always-on daemon - No API server - No database - No reconciliation loop - No scheduler service Instead: - VM lifecycle = Linux process lifecycle - State = files under `/var/lib/microvm` - Configuration changes = cloud-init regeneration - Access = SSH + VNC > The filesystem is the state store. > `/proc` is the source of truth. > Each CLI command is a deliberate control action. This makes MNMIVM-SE closer to **early private IaaS** and **bare-metal virtualization** than modern hyperscaler platforms. --- ## 🧱 Supported Host Operating Systems MNMIVM-SE is conservative about host support and only documents what is tested. ### βœ… Supported | Host OS | Version | |------|---------| | **Debian** | 12+ | | **Alpine Linux** | 3.22+ | ### πŸ•’ Coming Soon | Host OS | Notes | |------|------| | Ubuntu | Netplan-based host networking support planned | > Ubuntu is not currently documented due to netplan-specific bridge handling. > Support will be added, but is not a top priority. ### ❌ Not Supported - Wi-Fi–only hosts - WSL / nested hypervisors - Desktop laptop setups expecting NAT --- ## 🧱 Architecture Overview * **QEMU + KVM** * **Linux bridge (`br0`)** * **TAP devices** * **Cloud-init seed ISO** * **Static IP networking** * **VNC console for recovery** ``` /var/lib/microvm/ β”œβ”€β”€ images/ └── vms/ └── vm1/ β”œβ”€β”€ disk.qcow2 β”œβ”€β”€ seed.iso β”œβ”€β”€ pubkey.pub β”œβ”€β”€ os.name β”œβ”€β”€ vm.ip β”œβ”€β”€ vm.mac β”œβ”€β”€ vnc.port └── vm.pid ```` No libvirt. No XML. No daemon. --- ## 🌐 Host Networking Requirements (CRITICAL) MNMIVM-SE requires a **proper Linux bridge**. ### Example: `/etc/network/interfaces` (Debian) ```ini auto lo iface lo inet loopback auto ens18 iface ens18 inet manual auto br0 iface br0 inet static address 192.168.86.10 netmask 255.255.255.0 gateway 192.168.86.1 dns-nameservers 1.1.1.1 8.8.8.8 bridge_ports ens18 bridge_stp off bridge_fd 0 ```` **Rules that must be followed:** * The host IP must live on `br0` * The physical NIC must have no IP * Wi-Fi cannot be bridged * VMs attach via TAP devices --- ## πŸ”₯ Kernel Bridge Filtering (THIS WILL BREAK VMs) Linux defaults can silently block bridged traffic. This **must** be disabled: ```bash cat /proc/sys/net/bridge/bridge-nf-call-iptables # must be 0 ``` If set to `1`, VMs will: * Boot successfully * Have valid IPs * Be completely unreachable ### Fix (runtime) ```bash sudo sysctl -w net.bridge.bridge-nf-call-iptables=0 sudo sysctl -w net.bridge.bridge-nf-call-ip6tables=0 sudo sysctl -w net.bridge.bridge-nf-call-arptables=0 ``` ### Persistent fix `/etc/sysctl.d/99-bridge.conf`: ```ini net.bridge.bridge-nf-call-iptables = 0 net.bridge.bridge-nf-call-ip6tables = 0 net.bridge.bridge-nf-call-arptables = 0 ``` --- ## πŸ” QEMU Bridge Permissions QEMU must be allowed to attach TAP devices. ### `/etc/qemu/bridge.conf` ```ini allow br0 ``` Verify helper: ```bash ls -l /usr/lib/qemu/qemu-bridge-helper ``` --- ## 🐧 Alpine Linux Host Notes (3.22+) Alpine does not ship a hypervisor stack by default. Install required packages: ```bash apk add \ qemu-system-x86_64 \ qemu-img \ qemu-hw-display-virtio-vga \ bridge-utils \ cdrkit \ go ``` Notes: * `cdrkit` provides `genisoimage` * `bridge-utils` provides `brctl` * `qemu-hw-display-virtio-vga` is required for VNC * No libvirt or services are used * OpenRC is sufficient Alpine works well as a **minimal KVM host** once assembled. --- ## βš™οΈ Server Edition Configuration (Code-Level) Networking and sizing are configured **in code**, not via runtime flags. Edit these constants in `main.go` (around lines 25–30): ```go // Networking bridgeName = "br0" lanCIDR = "192.168.86.0/24" lanGW = "192.168.86.1" lanDNS1 = "192.168.86.1" lanDNS2 = "8.8.8.8" // VM sizing baseDiskSize = "12G" memMB = "1024" cpus = "1" ``` This keeps runtime behavior explicit and predictable. --- ## 🧰 CLI Usage ### Create a VM ```bash sudo mnmivm-se create vm1 \ --os debian \ --pubkey-path ~/.ssh/id_ed25519.pub \ --ip 192.168.86.53 ``` ### Start a VM ```bash sudo mnmivm-se start vm1 ``` ### SSH in ```bash ssh debian@192.168.86.53 ``` ### Stop a VM ```bash sudo mnmivm-se stop vm1 ``` ### Update cloud-init (SSH key / IP) ```bash sudo mnmivm-se update-cloud vm1 \ --pubkey-path newkey.pub \ --ip 192.168.86.54 ``` --- ## πŸ”‘ Security Model * SSH key–only access * No password authentication * No root login * Static IPs (no DHCP ambiguity) * MAC addresses pinned via cloud-init * VNC console for recovery only This follows **server-grade discipline**, not container ergonomics. --- ## ⚠️ What MNMIVM-SE Is Not * ❌ A managed cloud service * ❌ A multi-tenant platform * ❌ A scheduler or orchestrator * ❌ A UI-driven system * ❌ A laptop-friendly NAT tool If you want **policy, HA, quotas, tenants**, use Proxmox or OpenStack. If you want **direct control over real infrastructure**, MNMIVM-SE is the tool. --- ## 🐧 Why MNMIVM-SE Exists Because sometimes you don’t want: * libvirt * XML * dashboards * APIs * orchestration layers You want: > β€œPut a VM on my LAN, give it an IP, and let me build infrastructure.” MNMIVM-SE does exactly that β€” and nothing more. --- ### ⚠️ Final Note If you break networking with MNMIVM-SE, it isn’t a bug. It’s Linux doing exactly what you told it to do. And that’s the point.