Add Getting Started

Getting-Started.md

@@ -0,0 +1,358 @@
+# 🚀 MNMIVM-SE — Getting Started
+
+This guide walks through **installing dependencies**, **building MNMIVM-SE**, and **basic CLI usage** on a fresh system.
+
+MNMIVM-SE is intentionally simple: no services, no installers, no background daemons.  
+If the host is ready, the binary just runs.
+
+---
+
+## 🧱 Prerequisites
+
+Before building or running MNMIVM-SE, your host must support **KVM virtualization** and **bridged networking**.
+
+### Hardware requirements
+- x86_64 CPU
+- Hardware virtualization enabled (Intel VT-x / AMD-V)
+- Wired Ethernet (Wi-Fi cannot be bridged)
+
+---
+
+## 📦 Installing Dependencies
+
+### Debian 12+ (Recommended)
+
+```bash
+sudo apt update
+sudo apt install -y \
+  qemu-system-x86 \
+  qemu-utils \
+  qemu-bridge-helper \
+  cloud-image-utils \
+  genisoimage \
+  bridge-utils \
+  iproute2 \
+  iptables \
+  curl \
+  ca-certificates \
+  git \
+  build-essential
+````
+
+Optional (but useful):
+
+```bash
+sudo apt install -y cpu-checker
+kvm-ok
+```
+
+Verify KVM is available:
+
+```bash
+ls -l /dev/kvm
+```
+
+---
+
+### Alpine Linux 3.22+
+
+Alpine does not ship a hypervisor stack by default.
+
+```bash
+apk add \
+  qemu-system-x86_64 \
+  qemu-img \
+  qemu-hw-display-virtio-vga \
+  bridge-utils \
+  cdrkit \
+  go \
+  git
+```
+
+Notes:
+
+* `cdrkit` provides `genisoimage`
+* No libvirt or system services are required
+* OpenRC is sufficient
+
+---
+
+## 🔌 Required Kernel Modules
+
+MNMIVM-SE requires **TUN/TAP** for bridged networking.
+
+Check:
+
+```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
+```
+
+---
+
+## 🌐 Bridge Setup (Required)
+
+MNMIVM-SE expects a Linux bridge named **`br0`**.
+
+### Example (Debian `/etc/network/interfaces`)
+
+```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 lives on `br0`
+* Physical NIC has **no IP**
+* Wi-Fi cannot be bridged
+
+---
+
+## 🔥 Disable Bridge Netfilter (CRITICAL)
+
+If this is enabled, VMs will boot but be unreachable.
+
+```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
+```
+
+---
+
+## 🔐 Allow QEMU to Use the Bridge
+
+Create or edit:
+
+```bash
+sudo nano /etc/qemu/bridge.conf
+```
+
+```ini
+allow br0
+```
+
+Verify helper exists:
+
+```bash
+ls -l /usr/lib/qemu/qemu-bridge-helper
+```
+
+---
+
+## 🛠 Building MNMIVM-SE
+
+Clone the repository:
+
+```bash
+git clone https://mentalnet.xyz/forgejo/markmental/mnmivm-se.git
+cd mnmivm-se
+```
+
+Build the binary:
+
+```bash
+./build.sh
+```
+
+This produces:
+
+```bash
+./mnmivm-se
+```
+
+(Optional) Install system-wide:
+
+```bash
+sudo install -m 755 mnmivm-se /usr/local/bin/mnmivm-se
+```
+
+---
+
+## ⚙️ Configuration (Code-Level)
+
+MNMIVM-SE is configured **in code** for predictability.
+
+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"
+```
+
+Rebuild after changes:
+
+```bash
+./build.sh
+```
+
+---
+
+## 🧰 CLI Usage
+
+### Create a VM
+
+```bash
+sudo mnmivm-se create vm1 \
+  --os debian \
+  --pubkey-path ~/.ssh/id_ed25519.pub \
+  --ip 192.168.86.53
+```
+
+This will:
+
+* Download the cloud image (if missing)
+* Create a QCOW2 disk
+* Generate a cloud-init seed
+* Pin MAC, IP, and SSH key
+
+---
+
+### Start the VM
+
+```bash
+sudo mnmivm-se start vm1
+```
+
+---
+
+### SSH Into the VM
+
+```bash
+ssh debian@192.168.86.53
+```
+
+SSH is **key-only**.
+No passwords are enabled.
+
+---
+
+### Stop the VM
+
+```bash
+sudo mnmivm-se stop vm1
+```
+
+---
+
+### Update Cloud-Init (Key or IP)
+
+```bash
+sudo mnmivm-se update-cloud vm1 \
+  --pubkey-path newkey.pub \
+  --ip 192.168.86.54
+```
+
+Changes apply on next boot.
+
+---
+
+### List VMs
+
+```bash
+sudo mnmivm-se list
+```
+
+---
+
+### Delete a VM
+
+```bash
+sudo mnmivm-se delete vm1
+```
+
+Requires typing `YES` to confirm.
+
+---
+
+## 🔑 Security Notes
+
+* SSH key–only access
+* No password authentication
+* No root login
+* Static IP assignment
+* VNC console for recovery only
+
+Security is **intentional by default**.
+
+---
+
+## 🧠 Final Notes
+
+* MNMIVM-SE does not manage host firewalls
+* IPv4 is used for predictable internal networking
+* IPv6 may be present depending on your router
+* If IPv6 is enabled, it is assumed you understand its exposure model
+
+If something breaks, it’s almost always:
+
+* bridge config
+* kernel sysctls
+* missing `tun` module
+
+That’s not a bug.
+
+That’s infrastructure.
+
+---
+
+Happy launching! 🚀
+