mirror of
https://github.com/nix-community/disko
synced 2024-11-14 16:17:06 +00:00
118 lines
4.2 KiB
Markdown
118 lines
4.2 KiB
Markdown
# Generating Disk Images with Secrets Included using Disko
|
|
|
|
Using Disko on NixOS allows you to efficiently create `.raw` VM images from a
|
|
system configuration. The generated image can be used as a VM or directly
|
|
written to a physical drive to create a bootable disk. Follow the steps below to
|
|
generate disk images:
|
|
|
|
## Generating the `.raw` VM Image
|
|
|
|
1. **Create a NixOS configuration that includes the disko and the disk
|
|
configuration of your choice**
|
|
|
|
In the this example we create a flake containing a nixos configuration for
|
|
`myhost`.
|
|
|
|
```nix
|
|
# save this as flake.nix
|
|
{
|
|
description = "A disko images example";
|
|
|
|
inputs = {
|
|
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
|
|
disko.url = "github:nix-community/disko";
|
|
disko.inputs.nixpkgs.follows = "nixpkgs";
|
|
};
|
|
|
|
outputs = { self, disko, nixpkgs }: {
|
|
nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
|
|
system = "x86_64-linux";
|
|
modules = [
|
|
# You can get this file from here: https://github.com/nix-community/disko/blob/master/example/simple-efi.nix
|
|
./simple-efi.nix
|
|
disko.nixosModules.disko
|
|
({ config, ... }: {
|
|
# shut up state version warning
|
|
system.stateVersion = config.system.nixos.version;
|
|
# Adjust this to your liking.
|
|
# WARNING: if you set a too low value the image might be not big enough to contain the nixos installation
|
|
disko.devices.disk.vdb.imageSize = "10G";
|
|
})
|
|
];
|
|
};
|
|
};
|
|
}
|
|
```
|
|
|
|
2. **Build the disko image script:** Replace `myhost` in the command below with
|
|
your specific system configuration name:
|
|
|
|
```console
|
|
nix build .#nixosConfigurations.myhost.config.system.build.diskoImagesScript
|
|
```
|
|
|
|
3. **Execute the disko image script:** Execute the generated disko image script.
|
|
Running `./result --help` will output the available options:
|
|
|
|
```console
|
|
./result --help
|
|
Usage: $script [options]
|
|
|
|
Options:
|
|
* --pre-format-files <src> <dst>
|
|
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 <src> <dst>
|
|
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
|
|
```
|
|
|
|
An example run may look like this:
|
|
|
|
```
|
|
sudo ./result --build-memory 2048
|
|
```
|
|
|
|
The script will generate the actual image outside of the nix store in the
|
|
current working directory. The create image names depend on the names used in
|
|
`disko.devices.disk` attrset in the NixOS configuration. In our code example
|
|
it will produce the following image:
|
|
|
|
```
|
|
$ ls -la vdb.raw
|
|
.rw-r--r-- root root 10 GB 2 minutes ago vdb.raw
|
|
```
|
|
|
|
## Additional Configuration
|
|
|
|
- For virtual drive use, define the image size in your Disko configuration:
|
|
|
|
```console
|
|
disko.devices.disk.<drive>.imageSize = "32G"; # Set your preferred size
|
|
```
|
|
|
|
- If the `.raw` image size is not optimal, use `--write-to-disk` to write
|
|
directly to a drive. This bypasses the `.raw` file generation, which saves on
|
|
read/write operations and is suitable for single disk setups.
|
|
|
|
## Understanding the Image Generation Process
|
|
|
|
1. Files specified in `--pre-format-files` and `--post-format-files` are
|
|
temporarily copied to `/tmp`.
|
|
2. Files are then moved to their respective locations in the VM both before and
|
|
after the Disko partitioning script runs.
|
|
3. The NixOS installer is executed, having access only to `--post-format-files`.
|
|
4. Upon installer completion, the VM is shutdown, and the `.raw` disk files are
|
|
moved to the local directory.
|
|
|
|
> **Note**: The auto-resizing feature is currently not available in Disko.
|
|
> Contributions for this feature are welcomed. Adjust the `imageSize`
|
|
> configuration to prevent issues related to file size and padding.
|
|
|
|
By following these instructions and understanding the process, you can smoothly
|
|
generate disk images with Disko for your NixOS system configurations.
|