mirror of
https://github.com/nix-community/disko.git
synced 2024-11-04 05:44:29 +03:00
move disko-images to its own chapter
This commit is contained in:
Jörg Thalheim
Jörg Thalheim
parent
2ec3549b6f
commit
39de9e8cca
@ -9,6 +9,7 @@
|
||||
- [System Requirements](./requirements.md)
|
||||
- [How to Guide](./HowTo.md)
|
||||
- [Disko-Install](./disko-install.md)
|
||||
- [Disko-Images](./disko-images.md)
|
||||
- [Support Matrix](./supportmatrix.md)
|
||||
- [Reference](./reference.md)
|
||||
- [Upgrade Guide](./upgrade-guide.md)
|
||||
|
||||
122
docs/disko-images.md
Normal file
122
docs/disko-images.md
Normal file
@ -0,0 +1,122 @@
|
||||
# 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
|
||||
* --write-to-disk </dev/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
|
||||
```
|
||||
|
||||
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.
|
||||
@ -42,125 +42,3 @@ Options:
|
||||
run with set -x
|
||||
```
|
||||
|
||||
## 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
|
||||
* --write-to-disk </dev/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
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user