add stories

documentation/stories.md

@@ -0,0 +1,68 @@
+# About this document
+
+This document is meant to explain what should happen when an user is doing XYZ.
+
+# Adding a new template
+
+- USER edits the file to add a new template
+- USER runs the `openkubsd apply`
+- create a new qcow2 file
+- install the OS
+- deploy ssh key
+- create a new user
+- configure doas to permit all
+- configure sndiod
+- install programs from the configuration file
+
+# Adding a new VM (not disposable)
+
+- USER edits the file to add the new VM
+- USER runs the `openkubsd apply`
+- run the command that generates a fresh derived disk from the template
+- create a new qcow2 file for /home
+- generate the PF rules
+  - allow host NFS
+  - prevent IP spoofing
+  - block everything except the gateway
+  - allow sndio to the host if allowed in the configuration file
+- generate the NFS directory for that VM
+- generate the NFS /etc/exports line for that share (restricted to that VM)
+
+# Adding a new VM (disposable)
+
+- USER edits the file to add the new disposable VM (based on a template)
+- nothing is done at this step
+
+# Starting a VM
+
+- USER runs something like `openkubsd start foobar`
+- create a qcow2 derived from the template
+- if disposable
+  - generate the PF rules
+  - generate the NFS directory
+  - generate the NFS /etc/exports
+- starts the VM
+- run a start script if in the configuration
+
+# Starting a program in a VM
+
+- USER runs something like `openkubsd start foobar firefox`
+- try to start the VM / wait for the VM to be started (should support concurrency)
+- run `ssh -Y $vm "firefox"`
+
+# Stopping a VM
+
+- USER runs `openkubsd stop $vm`
+- stop the VM
+- deleting the qcow2 derived file of the template
+- if it's disposable
+  - delete the PF rules
+  - delete the NFS directory
+  - delete the NFS configuration
+
+# Removing a VM
+
+- USER removes VM foobar from the configuration file
+- USER runs `openkubsd apply`
+- extra VMs are removed
+- their disks are removed (USER may be asked)