mnmivm-se/README.md

# 🚀 MNMIVM-SE (Server Edition)

### *A LAN-Native VM Cloud with a Minimal Control Plane*

![MNMIVM Hero](https://mentalnet.xyz/forgejo/markmental/mnmivm-se/raw/branch/master/tuxrockets.jpg)

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

---

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