mnmivm-se/README.md

🚀 MNMIVM-SE (Server Edition)

A LAN-Native VM Cloud with a Minimal Control Plane

Demo Video

MNMIVM-SE is the server-focused edition of MNMIVM
(https://mentalnet.xyz/forgejo/markmental/mnmivm-se) — 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 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, but it is intentionally minimal, local, and explicit.

• Single CLI binary
• File-backed state
• Linux process lifecycle tracking

There is:

• No daemon
• No API server
• No database
• No reconciliation loop

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.

---

🧱 Supported Host Operating Systems

✅ Supported

Host OS	Version
Debian	12+
Alpine Linux	3.22+

🕒 Coming Soon

Host OS	Notes
Ubuntu	Netplan-based host networking planned

Ubuntu is undocumented for now due to netplan differences, but it should not be much different in setting up a bridged network interface.

❌ Not Supported

• Wi-Fi–only hosts
• WSL / nested hypervisors
• Desktop NAT-based setups

---

📦 Debian Host Requirements (12+)

Install required packages:

sudo apt update
sudo apt install -y \
  qemu-system-x86 \
  golang \
  qemu-utils \
  qemu-bridge-helper \
  cloud-image-utils \
  genisoimage \
  bridge-utils \
  iproute2 \
  iptables \
  curl \
  ca-certificates \
  git \
  build-essential

Optional but recommended:

sudo apt install -y cpu-checker
kvm-ok

Ensure KVM is available:

ls -l /dev/kvm

---

🔌 TUN/TAP Kernel Module (Required)

MNMIVM-SE requires the TUN/TAP kernel module.

Verify:

ls -l /dev/net/tun

If missing:

sudo modprobe tun

Persist on boot:

Debian

echo tun | sudo tee /etc/modules-load.d/tun.conf

Alpine

echo tun | sudo tee -a /etc/modules

---

🧱 Architecture Overview

/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 Linux bridge.

Example: /etc/network/interfaces (Debian)

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:

• Host IP must live on br0
• Physical NIC has no IP
• Wi-Fi cannot be bridged
• VMs attach via TAP devices

---

🔥 Kernel Bridge Filtering (THIS WILL BREAK VMs)

Check:

cat /proc/sys/net/bridge/bridge-nf-call-iptables
# must be 0

Fix (runtime):

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

Persist:

# /etc/sysctl.d/99-bridge.conf
net.bridge.bridge-nf-call-iptables = 0
net.bridge.bridge-nf-call-ip6tables = 0
net.bridge.bridge-nf-call-arptables = 0

---

🔐 QEMU Bridge Permissions

# /etc/qemu/bridge.conf
allow br0

Verify helper:

ls -l /usr/lib/qemu/qemu-bridge-helper

---

🐧 Alpine Linux Host Notes (3.22+)

apk add \
  qemu-system-x86_64 \
  qemu-img \
  qemu-hw-display-virtio-vga \
  bridge-utils \
  cdrkit \
  go

Notes:

• cdrkit provides genisoimage
• No libvirt or background services
• OpenRC is sufficient

---

⚙️ Server Edition Configuration (Code-Level)

Edit constants in main.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"

---

🧰 CLI Usage

Create VM

sudo mnmivm-se create vm1 \
  --os debian \
  --pubkey-path ~/.ssh/id_ed25519.pub \
  --ip 192.168.86.53

Start

sudo mnmivm-se start vm1

SSH

ssh debian@192.168.86.53

Stop

sudo mnmivm-se stop vm1

Update cloud-init

sudo mnmivm-se update-cloud vm1 \
  --pubkey-path newkey.pub \
  --ip 192.168.86.54

---

🔑 Security Model

• SSH key–only access
• No passwords
• No root login
• Static IPs
• Pinned MAC addresses
• VNC console for recovery only

Security is intentional by default.

---

⚠️ What MNMIVM-SE Is Not

• A managed cloud
• A multi-tenant platform
• A scheduler
• A UI-driven system
• A NAT-based laptop tool

If you want policy and HA, use Proxmox or OpenStack. If you want direct infrastructure control, use MNMIVM-SE.

---

🐧 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.

---

⚠️ Final Note

If networking breaks, it isn't a bug.

It's Linux doing exactly what you told it to do.

And that's the point.