Skip to content

Commit 39de9e8

Browse files
Mic92Mic92
committed
move disko-images to its own chapter
1 parent 2ec3549 commit 39de9e8

File tree

3 files changed

+123
-122
lines changed

3 files changed

+123
-122
lines changed

‎docs/INDEX.md

+1
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
- [System Requirements](./requirements.md)
1010
- [How to Guide](./HowTo.md)
1111
- [Disko-Install](./disko-install.md)
12+
- [Disko-Images](./disko-images.md)
1213
- [Support Matrix](./supportmatrix.md)
1314
- [Reference](./reference.md)
1415
- [Upgrade Guide](./upgrade-guide.md)

‎docs/disko-images.md

+122
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# Generating Disk Images with Secrets Included using Disko
2+
3+
Using Disko on NixOS allows you to efficiently create `.raw` VM images from a
4+
system configuration. The generated image can be used as a VM or directly
5+
written to a physical drive to create a bootable disk. Follow the steps below to
6+
generate disk images:
7+
8+
## Generating the `.raw` VM Image
9+
10+
1. **Create a NixOS configuration that includes the disko and the disk
11+
configuration of your choice**
12+
13+
In the this example we create a flake containing a nixos configuration for
14+
`myhost`.
15+
16+
```nix
17+
# save this as flake.nix
18+
{
19+
description = "A disko images example";
20+
21+
inputs = {
22+
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
23+
disko.url = "github:nix-community/disko";
24+
disko.inputs.nixpkgs.follows = "nixpkgs";
25+
};
26+
27+
outputs = { self, disko, nixpkgs }: {
28+
nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
29+
system = "x86_64-linux";
30+
modules = [
31+
# You can get this file from here: https://github.com/nix-community/disko/blob/master/example/simple-efi.nix
32+
./simple-efi.nix
33+
disko.nixosModules.disko
34+
({ config, ... }: {
35+
# shut up state version warning
36+
system.stateVersion = config.system.nixos.version;
37+
# Adjust this to your liking.
38+
# WARNING: if you set a too low value the image might be not big enough to contain the nixos installation
39+
disko.devices.disk.vdb.imageSize = "10G";
40+
})
41+
];
42+
};
43+
};
44+
}
45+
```
46+
47+
2. **Build the disko image script:** Replace `myhost` in the command below with
48+
your specific system configuration name:
49+
50+
```console
51+
nix build .#nixosConfigurations.myhost.config.system.build.diskoImagesScript
52+
```
53+
54+
3. **Execute the disko image script:** Execute the generated disko image script.
55+
Running `./result --help` will output the available options:
56+
57+
```console
58+
./result --help
59+
Usage: $script [options]
60+
61+
Options:
62+
* --pre-format-files <src> <dst>
63+
copies the src to the dst on the VM, before disko is run
64+
This is useful to provide secrets like LUKS keys, or other files you need for formating
65+
* --post-format-files <src> <dst>
66+
copies the src to the dst on the finished image
67+
These end up in the images later and is useful if you want to add some extra stateful files
68+
They will have the same permissions but will be owned by root:root
69+
* --build-memory
70+
specify the ammount of memory that gets allocated to the build vm (in mb)
71+
This can be usefull if you want to build images with a more involed NixOS config
72+
By default the vm will get 1024M/1GB
73+
* --write-to-disk </dev/disk>
74+
use an actuall disk instead of writing to a file
75+
This only works if your conifg has only one disk specified
76+
There is no check if the specified path is actually a disk so you can also write to another file
77+
```
78+
79+
An example run may look like this:
80+
81+
```
82+
sudo ./result --build-memory 2048
83+
```
84+
85+
The script will generate the actual image outside of the nix store in the
86+
current working directory. The create image names depend on the names used in
87+
`disko.devices.disk` attrset in the NixOS configuration. In our code example it will
88+
produce the following image:
89+
90+
```
91+
$ ls -la vdb.raw
92+
.rw-r--r-- root root 10 GB 2 minutes ago vdb.raw
93+
```
94+
95+
## Additional Configuration
96+
97+
- For virtual drive use, define the image size in your Disko configuration:
98+
99+
```console
100+
disko.devices.disk.<drive>.imageSize = "32G"; # Set your preferred size
101+
```
102+
103+
- If the `.raw` image size is not optimal, use `--write-to-disk` to write
104+
directly to a drive. This bypasses the `.raw` file generation, which saves on
105+
read/write operations and is suitable for single disk setups.
106+
107+
## Understanding the Image Generation Process
108+
109+
1. Files specified in `--pre-format-files` and `--post-format-files` are
110+
temporarily copied to `/tmp`.
111+
2. Files are then moved to their respective locations in the VM both before and
112+
after the Disko partitioning script runs.
113+
3. The NixOS installer is executed, having access only to `--post-format-files`.
114+
4. Upon installer completion, the VM is shutdown, and the `.raw` disk files are
115+
moved to the local directory.
116+
117+
> **Note**: The auto-resizing feature is currently not available in Disko.
118+
> Contributions for this feature are welcomed. Adjust the `imageSize`
119+
> configuration to prevent issues related to file size and padding.
120+
121+
By following these instructions and understanding the process, you can smoothly
122+
generate disk images with Disko for your NixOS system configurations.

‎docs/reference.md

-122
Original file line numberDiff line numberDiff line change
@@ -42,125 +42,3 @@ Options:
4242
run with set -x
4343
```
4444

45-
## Generating Disk Images with Secrets Included using Disko
46-
47-
Using Disko on NixOS allows you to efficiently create `.raw` VM images from a
48-
system configuration. The generated image can be used as a VM or directly
49-
written to a physical drive to create a bootable disk. Follow the steps below to
50-
generate disk images:
51-
52-
### Generating the `.raw` VM Image
53-
54-
1. **Create a NixOS configuration that includes the disko and the disk
55-
configuration of your choice**
56-
57-
In the this example we create a flake containing a nixos configuration for
58-
`myhost`.
59-
60-
```nix
61-
# save this as flake.nix
62-
{
63-
description = "A disko images example";
64-
65-
inputs = {
66-
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
67-
disko.url = "github:nix-community/disko";
68-
disko.inputs.nixpkgs.follows = "nixpkgs";
69-
};
70-
71-
outputs = { self, disko, nixpkgs }: {
72-
nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
73-
system = "x86_64-linux";
74-
modules = [
75-
# You can get this file from here: https://github.com/nix-community/disko/blob/master/example/simple-efi.nix
76-
./simple-efi.nix
77-
disko.nixosModules.disko
78-
({ config, ... }: {
79-
# shut up state version warning
80-
system.stateVersion = config.system.nixos.version;
81-
# Adjust this to your liking.
82-
# WARNING: if you set a too low value the image might be not big enough to contain the nixos installation
83-
disko.devices.disk.vdb.imageSize = "10G";
84-
})
85-
];
86-
};
87-
};
88-
}
89-
```
90-
91-
2. **Build the disko image script:** Replace `myhost` in the command below with
92-
your specific system configuration name:
93-
94-
```console
95-
nix build .#nixosConfigurations.myhost.config.system.build.diskoImagesScript
96-
```
97-
98-
3. **Execute the disko image script:** Execute the generated disko image script.
99-
Running `./result --help` will output the available options:
100-
101-
```console
102-
./result --help
103-
Usage: $script [options]
104-
105-
Options:
106-
* --pre-format-files <src> <dst>
107-
copies the src to the dst on the VM, before disko is run
108-
This is useful to provide secrets like LUKS keys, or other files you need for formating
109-
* --post-format-files <src> <dst>
110-
copies the src to the dst on the finished image
111-
These end up in the images later and is useful if you want to add some extra stateful files
112-
They will have the same permissions but will be owned by root:root
113-
* --build-memory
114-
specify the ammount of memory that gets allocated to the build vm (in mb)
115-
This can be usefull if you want to build images with a more involed NixOS config
116-
By default the vm will get 1024M/1GB
117-
* --write-to-disk </dev/disk>
118-
use an actuall disk instead of writing to a file
119-
This only works if your conifg has only one disk specified
120-
There is no check if the specified path is actually a disk so you can also write to another file
121-
```
122-
123-
An example run may look like this:
124-
125-
```
126-
sudo ./result --build-memory 2048
127-
```
128-
129-
The script will generate the actual image outside of the nix store in the
130-
current working directory. The create image names depend on the names used in
131-
`disko.devices.disk` attrset in the NixOS configuration. In our code example it will
132-
produce the following image:
133-
134-
```
135-
$ ls -la vdb.raw
136-
.rw-r--r-- root root 10 GB 2 minutes ago vdb.raw
137-
```
138-
139-
### Additional Configuration
140-
141-
- For virtual drive use, define the image size in your Disko configuration:
142-
143-
```console
144-
disko.devices.disk.<drive>.imageSize = "32G"; # Set your preferred size
145-
```
146-
147-
- If the `.raw` image size is not optimal, use `--write-to-disk` to write
148-
directly to a drive. This bypasses the `.raw` file generation, which saves on
149-
read/write operations and is suitable for single disk setups.
150-
151-
### Understanding the Image Generation Process
152-
153-
1. Files specified in `--pre-format-files` and `--post-format-files` are
154-
temporarily copied to `/tmp`.
155-
2. Files are then moved to their respective locations in the VM both before and
156-
after the Disko partitioning script runs.
157-
3. The NixOS installer is executed, having access only to `--post-format-files`.
158-
4. Upon installer completion, the VM is shutdown, and the `.raw` disk files are
159-
moved to the local directory.
160-
161-
> **Note**: The auto-resizing feature is currently not available in Disko.
162-
> Contributions for this feature are welcomed. Adjust the `imageSize`
163-
> configuration to prevent issues related to file size and padding.
164-
165-
By following these instructions and understanding the process, you can smoothly
166-
generate disk images with Disko for your NixOS system configurations.

0 commit comments

Comments
 (0)