🚀 MNMIVM-SE (Server Edition)

A LAN-Native VM Cloud with a Minimal Control Plane

---

Demo Video

---

MNMIVM-SE (MentalNet Micro VMs - Server Edition) 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.

Click this link to find out how to install and get started: https://mentalnet.xyz/forgejo/markmental/mnmivm-se/wiki/Getting-Started

---

☁️ 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.