397 lines
6.7 KiB
Markdown
397 lines
6.7 KiB
Markdown
# 🚀 MNMIVM-SE (Server Edition)
|
||
|
||
### *A LAN-Native VM Cloud with a Minimal Control Plane*
|
||
|
||
|
||
|
||
---
|
||
|
||
## Demo Video
|
||
<video controls src="https://mentalnet.xyz/forgejo/markmental/mnmivm-se/raw/branch/master/assets/output.mp4">
|
||
Your browser does not support the video tag. Video is available in /assets/output.mp4
|
||
</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.
|
||
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
sudo apt install -y cpu-checker
|
||
kvm-ok
|
||
```
|
||
|
||
Ensure KVM is available:
|
||
|
||
```bash
|
||
ls -l /dev/kvm
|
||
```
|
||
|
||
---
|
||
|
||
## 🔌 TUN/TAP Kernel Module (Required)
|
||
|
||
MNMIVM-SE requires the **TUN/TAP** kernel module.
|
||
|
||
Verify:
|
||
|
||
```bash
|
||
ls -l /dev/net/tun
|
||
```
|
||
|
||
If missing:
|
||
|
||
```bash
|
||
sudo modprobe tun
|
||
```
|
||
|
||
Persist on boot:
|
||
|
||
### Debian
|
||
|
||
```bash
|
||
echo tun | sudo tee /etc/modules-load.d/tun.conf
|
||
```
|
||
|
||
### Alpine
|
||
|
||
```bash
|
||
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)
|
||
|
||
```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:
|
||
|
||
* 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:
|
||
|
||
```bash
|
||
cat /proc/sys/net/bridge/bridge-nf-call-iptables
|
||
# must be 0
|
||
```
|
||
|
||
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
|
||
```
|
||
|
||
Persist:
|
||
|
||
```ini
|
||
# /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
|
||
|
||
```ini
|
||
# /etc/qemu/bridge.conf
|
||
allow br0
|
||
```
|
||
|
||
Verify helper:
|
||
|
||
```bash
|
||
ls -l /usr/lib/qemu/qemu-bridge-helper
|
||
```
|
||
|
||
---
|
||
|
||
## 🐧 Alpine Linux Host Notes (3.22+)
|
||
|
||
```bash
|
||
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`:
|
||
|
||
```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
|
||
|
||
```bash
|
||
sudo mnmivm-se create vm1 \
|
||
--os debian \
|
||
--pubkey-path ~/.ssh/id_ed25519.pub \
|
||
--ip 192.168.86.53
|
||
```
|
||
|
||
### Start
|
||
|
||
```bash
|
||
sudo mnmivm-se start vm1
|
||
```
|
||
|
||
### SSH
|
||
|
||
```bash
|
||
ssh debian@192.168.86.53
|
||
```
|
||
|
||
### Stop
|
||
|
||
```bash
|
||
sudo mnmivm-se stop vm1
|
||
```
|
||
|
||
### Update cloud-init
|
||
|
||
```bash
|
||
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.
|
||
|