markmental 6bafe78941 Update README.md

2025-12-22 13:47:22 +00:00

6.7 KiB

Raw Blame History

🚀 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) — 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.

6.7 KiB Raw Blame History Unescape Escape