From 8759b5bf0af8c21685e1da7f20c40eeb79eaeec2 Mon Sep 17 00:00:00 2001 From: Janik H Date: Mon, 25 Sep 2023 11:25:40 +0200 Subject: [PATCH] docs: add make-disk-image --- docs/reference.md | 46 ++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 44 insertions(+), 2 deletions(-) diff --git a/docs/reference.md b/docs/reference.md index fe44003..5825cc4 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -2,7 +2,7 @@ ## Module Options -We are currently having issues beeing able to generate proper module option +We are currently having issues being able to generate proper module option documentation for our recursive disko types. However you can read the available options [here](https://github.com/nix-community/disko/tree/master/lib/types). Combined wit the @@ -44,4 +44,46 @@ Options: run with set -x ``` -## +## Generating Disk Images with secrets included + +If you have a system config that uses disko then you can run a script that generates a `.raw` VM image. +This image can be used as a VM image, but you can also dd the `.raw` image on to a physical drive and just boot it. +To execute the script replace the `mySystem` part in the snippet below and run it. +``` +nix build .#nixosConfigurations.mySystem.config.system.build.diskoImagesScript +``` +Now you will have a result file which will output something like this: +``` +./result --help +Usage: $script [options] + +Options: +* --pre-format-files + copies the src to the dst on the VM, before disko is run + This is useful to provide secrets like LUKS keys, or other files you need for formating +* --post-format-files + copies the src to the dst on the finished image + These end up in the images later and is useful if you want to add some extra stateful files + They will have the same permissions but will be owned by root:root +* --build-memory + specify the ammount of memory that gets allocated to the build vm (in mb) + This can be usefull if you want to build images with a more involed NixOS config + By default the vm will get 1024M/1GB +* --write-to-disk + use an actuall disk instead of writing to a file + This only works if your conifg has only one disk specified + There is no check if the specified path is actually a disk so you can also write to another file +``` +If you intend to use it with a virtual drive you have to set `disko.devices.disk..imageSize = "32G"; #set your own size here` in your disko config. +If you just run the result script it will generate a file per drive specified in `disko.devices.disk.` called `.raw` +There is a small problem with this approach because the `.raw` file will have the size that's specified in `imageSize`+padding. +So with a `imageSize` of `64G` you end up with a `69G` image and if you copy/move that file you end up reading and writing a lot of zeros. +At this point it's probably note worth that there is no auto resizing in disko and it's not planed (but open for contributions). +One way to circumvent that is to use the `--write-to-disk` option and just directly write to a drive, +this only works with one drive but can be useful for simple setups like a laptop configuration. + +The way images are generated is basically: +Every file specified in `--pre-format-files` and `--post-format-files` will be copied to a buffer in `/tmp`. +And then copied to the specified locations in the VM before and after the disko partitioning script ran. +After that the NixOS installer will be run which will have access to every file in `--post-format-files` but not `--pre-format-files` because they will already be discarded. +The VM will be shutdown once the installer finishes and then move the `.raw` disk files to the local directory.