From 8c8f07fb1676b23ffc7e9acbdcb3a49527764168 Mon Sep 17 00:00:00 2001 From: markmental Date: Mon, 22 Dec 2025 00:19:31 +0000 Subject: [PATCH] Add Getting Started --- Getting-Started.md | 358 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 358 insertions(+) create mode 100644 Getting-Started.md diff --git a/Getting-Started.md b/Getting-Started.md new file mode 100644 index 0000000..89decc9 --- /dev/null +++ b/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! ๐Ÿš€ +