From dbdf817d79e975bfcec396930b0046cefee88c5a Mon Sep 17 00:00:00 2001
From: kalipso <kalipso@c3d2.de>
Date: Tue, 19 Nov 2024 15:43:23 +0100
Subject: [PATCH] [doc] add basic microvm documentation

---
 doc/src/SUMMARY.md           |  3 ++-
 doc/src/anleitung/microvm.md | 39 ++++++++++++++++++++++++++++++++++++
 2 files changed, 41 insertions(+), 1 deletion(-)
 create mode 100644 doc/src/anleitung/microvm.md

diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md
index e9dc6e03..a3076d21 100644
--- a/doc/src/SUMMARY.md
+++ b/doc/src/SUMMARY.md
@@ -14,4 +14,5 @@
     - [How-to]()
         - [Sops](./anleitung/sops.md)            
         - [Updates](./anleitung/updates.md)
-        - [Rollbacks](./anleitung/rollback.md)
\ No newline at end of file
+        - [Rollbacks](./anleitung/rollback.md)
+        - [MicroVM](./anleitung/microvm.md)
diff --git a/doc/src/anleitung/microvm.md b/doc/src/anleitung/microvm.md
new file mode 100644
index 00000000..f8c9005c
--- /dev/null
+++ b/doc/src/anleitung/microvm.md
@@ -0,0 +1,39 @@
+### Declaring a MicroVM
+
+The hosts nixosSystems modules should be declared using the ```makeMicroVM``` helper function.
+Use durruti as orientation:
+``` nix
+    modules = makeMicroVM "durruti" "10.0.0.5" [
+      ./durruti/configuration.nix
+    ];
+```
+
+"durruti" is the hostname.  
+"10.0.0.5" is the IP assigned to its tap interface.  
+
+### Testing MicroVMs locally
+MicroVMs can be built and run easily on your local host.
+For durruti this is done by:
+``` bash
+sudo nix run .\#nixosConfigurations.durruti.config.microvm.declaredRunner
+```
+
+It seems to be necessary to run this as root so that the according tap interface can be created.
+To be able to ping the VM or give Internet Access to the VM your host needs to be setup as described below.
+
+### Host Setup
+To provide network access to the VMs a bridge interface needs to be created on your host.
+For that:
+- Add the infrastructure flake as input to your hosts flake  
+- Add ```inputs.malobeo.nixosModules.malobeo``` to your hosts imports
+- enable the host bridge: ```services.malobeo.microvm.enableHostBridge = true;```
+
+If you want to provide Internet access to the VM it is necessary to create a nat.
+This could be done like this:
+``` nix
+networking.nat = {
+  enable = true;
+  internalInterfaces = [ "microvm" ];
+  externalInterface = "eth0"; #change to your interface name
+};
+```