reformat tree

This commit is contained in:
Jörg Thalheim 2023-09-15 07:56:40 +02:00 committed by mergify[bot]
parent 1be23d771f
commit 9ab96378f8
9 changed files with 173 additions and 73 deletions

View file

@ -6,35 +6,52 @@
[Documentation Index](./docs/INDEX.md)
NixOS is a Linux distribution where everything is described as code, with one exception: during installation, the disk partitioning and formatting are manual steps. **disko** aims to correct this sad 🤡 omission.
NixOS is a Linux distribution where everything is described as code, with one
exception: during installation, the disk partitioning and formatting are manual
steps. **disko** aims to correct this sad 🤡 omission.
This is especially useful for unattended installations, re-installation after a system crash or for setting up more than one identical server.
This is especially useful for unattended installations, re-installation after a
system crash or for setting up more than one identical server.
## Overview
**disko** can either be used after booting from a NixOS installer, or in conjunction with [nixos-anywhere](https://github.com/numtide/nixos-anywhere) if you're installing remotely.
**disko** can either be used after booting from a NixOS installer, or in
conjunction with [nixos-anywhere](https://github.com/numtide/nixos-anywhere) if
you're installing remotely.
Before using **disko**, the specifications of the disks, partitions, type of formatting and the mount points must be defined in a Nix configuration. You can find [examples](./example) of typical configurations in the Nix community repository, and use one of these as the basis of your own configuration.
Before using **disko**, the specifications of the disks, partitions, type of
formatting and the mount points must be defined in a Nix configuration. You can
find [examples](./example) of typical configurations in the Nix community
repository, and use one of these as the basis of your own configuration.
You can keep your configuration and re-use it for other installations, or for a system rebuild.
You can keep your configuration and re-use it for other installations, or for a
system rebuild.
**disko** is flexible, in that it supports most of the common formatting and partitioning options, including:
**disko** is flexible, in that it supports most of the common formatting and
partitioning options, including:
- Disk layouts: GPT, MBR, and mixed.
- Partition tools: LVM, mdadm, LUKS, and more.
- Filesystems: ext4, btrfs, ZFS, bcachefs, tmpfs, and others.
It can work with these in various configurations and orders, and supports recursive layouts.
It can work with these in various configurations and orders, and supports
recursive layouts.
## How to use disko
Disko doesn't require installation: it can be run directly from nix-community repository. The [Quickstart Guide](./docs/quickstart.md) documents how to run Disko in its simplest form when installing NixOS.
Disko doesn't require installation: it can be run directly from nix-community
repository. The [Quickstart Guide](./docs/quickstart.md) documents how to run
Disko in its simplest form when installing NixOS.
For information on other use cases, including upgrading from an older version of **disko**, using **disko** without NixOS and downloading the module, see the [How To Guide](./docs/HowTo.md)
For information on other use cases, including upgrading from an older version of
**disko**, using **disko** without NixOS and downloading the module, see the
[How To Guide](./docs/HowTo.md)
For more detailed options, such as command line switches, see the [Reference Guide](./docs/reference.md)
For more detailed options, such as command line switches, see the
[Reference Guide](./docs/reference.md)
To access sample configurations for commonly-used disk layouts, refer to the [examples](./example) provided.
To access sample configurations for commonly-used disk layouts, refer to the
[examples](./example) provided.
## Sample Configuration and CLI command
@ -72,7 +89,9 @@ A simple disko configuration may look like this:
}
```
If you'd saved this configuration in /tmp/disko-config.nix, and wanted to create a disk named /dev/nvme0n1, you would run the following command to partition, format and mount the disk.
If you'd saved this configuration in /tmp/disko-config.nix, and wanted to create
a disk named /dev/nvme0n1, you would run the following command to partition,
format and mount the disk.
```
$ sudo nix run github:nix-community/disko -- --mode disko /tmp/disko-config.nix --arg disks '[ "/dev/nvme0n1" ]'
@ -80,21 +99,28 @@ $ sudo nix run github:nix-community/disko -- --mode disko /tmp/disko-config.nix
## Related Tools
This tool is used by [nixos-anywhere](https://github.com/numtide/nixos-anywhere), which carries out a fully-automated remote install of NixOS.
This tool is used by
[nixos-anywhere](https://github.com/numtide/nixos-anywhere), which carries out a
fully-automated remote install of NixOS.
We also acknowledge https://github.com/NixOS/nixpart, the conceptual ancestor of this project.
We also acknowledge https://github.com/NixOS/nixpart, the conceptual ancestor of
this project.
## Licensing and Contribution details
This software is provided free under the [MIT Licence](https://opensource.org/licenses/MIT).
This software is provided free under the
[MIT Licence](https://opensource.org/licenses/MIT).
If you would like to become a contributor, please see our [contribution guidelines.](https://github.com/numtide/docs/contribution-guidelines.md)
If you would like to become a contributor, please see our
[contribution guidelines.](https://github.com/numtide/docs/contribution-guidelines.md)
---
This project is supported by [Numtide](https://numtide.com/).  ![Untitledpng](https://codahosted.io/docs/6FCIMTRM0p/blobs/bl-sgSunaXYWX/077f3f9d7d76d6a228a937afa0658292584dedb5b852a8ca370b6c61dabb7872b7f617e603f1793928dc5410c74b3e77af21a89e435fa71a681a868d21fd1f599dd10a647dd855e14043979f1df7956f67c3260c0442e24b34662307204b83ea34de929d)    
This project is supported by [Numtide](https://numtide.com/).
![Untitledpng](https://codahosted.io/docs/6FCIMTRM0p/blobs/bl-sgSunaXYWX/077f3f9d7d76d6a228a937afa0658292584dedb5b852a8ca370b6c61dabb7872b7f617e603f1793928dc5410c74b3e77af21a89e435fa71a681a868d21fd1f599dd10a647dd855e14043979f1df7956f67c3260c0442e24b34662307204b83ea34de929d)
We are a team of independent freelancers that love open source.  We help our customers make their project lifecycles more efficient by:
We are a team of independent freelancers that love open source.  We help our
customers make their project lifecycles more efficient by:
- Providing and supporting useful tools such as this one
- Building and deploying infrastructure, and offering dedicated DevOps support
@ -102,4 +128,6 @@ We are a team of independent freelancers that love open source.  We help our cu
- Developing additional features and tools
- Carrying out custom research and development.
[Contact us](https://numtide.com/contact) if you have a project in mind, or if you need help with any of our supported tools, including this one. We'd love to hear from you.
[Contact us](https://numtide.com/contact) if you have a project in mind, or if
you need help with any of our supported tools, including this one. We'd love to
hear from you.

View file

@ -8,7 +8,8 @@ TODO: Still to be documented
TODO: Include documentation here.
For now, see the [upgrade guide](https://github.com/JillThornhill/disko/blob/master/docs/upgrade-guide.md)
For now, see the
[upgrade guide](https://github.com/JillThornhill/disko/blob/master/docs/upgrade-guide.md)
## Installing NixOS module
@ -19,7 +20,7 @@ You can use the NixOS module in one of the following ways:
If you use nix flakes support:
``` nix
```nix
{
inputs.disko.url = "github:nix-community/disko";
inputs.disko.inputs.nixpkgs.follows = "nixpkgs";
@ -37,54 +38,57 @@ If you use nix flakes support:
};
}
```
</details>
<details>
<summary>niv</summary>
First add it to [niv](https://github.com/nmattia/niv):
First add it to [niv](https://github.com/nmattia/niv):
```console
$ niv add nix-community/disko
```
Then add the following to your configuration.nix in the `imports` list:
Then add the following to your configuration.nix in the `imports` list:
```nix
{
imports = [ "${(import ./nix/sources.nix).disko}/modules/disko.nix" ];
}
```
</details>
<details>
<summary>nix-channel</summary>
As root run:
As root run:
```console
$ nix-channel --add https://github.com/nix-community/disko/archive/master.tar.gz disko
$ nix-channel --update
```
Then add the following to your configuration.nix in the `imports` list:
Then add the following to your configuration.nix in the `imports` list:
```nix
{
imports = [ <disko/modules/disko.nix> ];
}
```
</details>
<details>
<summary>fetchTarball</summary>
Add the following to your configuration.nix:
Add the following to your configuration.nix:
``` nix
```nix
{
imports = [ "${builtins.fetchTarball "https://github.com/nix-community/disko/archive/master.tar.gz"}/module.nix" ];
}
```
or with pinning:
or with pinning:
```nix
{
@ -100,6 +104,7 @@ $ nix-channel --update
];
}
```
</details>
## Using the NixOS module
@ -145,8 +150,10 @@ $ nix-channel --update
}
```
this will configure `fileSystems` and other required NixOS options to boot the specified configuration.
this will configure `fileSystems` and other required NixOS options to boot the
specified configuration.
If you are on an installer, you probably want to disable `enableConfig`.
disko will create the scripts `disko-create` and `disko-mount` which can be used to create/mount the configured disk layout.
disko will create the scripts `disko-create` and `disko-mount` which can be used
to create/mount the configured disk layout.

View file

@ -6,17 +6,30 @@
## Quickstart Guide
This tutorial describes how to install NixOS on a single disk system using `disko`. You will also need to refer to the NixOS manual, which is available [here.](https://nixos.org/manual/nixos/stable/index.html#ex-config)
This tutorial describes how to install NixOS on a single disk system using
`disko`. You will also need to refer to the NixOS manual, which is available
[here.](https://nixos.org/manual/nixos/stable/index.html#ex-config)
Please note that `disko` will reformat the entire disk and overwrite any existing partitions. Dual booting with other operating systems is not supported.
Please note that `disko` will reformat the entire disk and overwrite any
existing partitions. Dual booting with other operating systems is not supported.
### Step 1: Choose a Disk Configuration
Configurations for the most common disk layouts are provided in the [examples directory](https://github.com/nix-community/disko/tree/master/example) of the `disko` repository. Decide which of these layouts best suits your requirements. If you're not sure which layout to pick, use the [hybrid](https://github.com/nix-community/disko/blob/master/example/hybrid.nix) configuration. This layout is compatible with both BIOS and EFI systems.
Configurations for the most common disk layouts are provided in the
[examples directory](https://github.com/nix-community/disko/tree/master/example)
of the `disko` repository. Decide which of these layouts best suits your
requirements. If you're not sure which layout to pick, use the
[hybrid](https://github.com/nix-community/disko/blob/master/example/hybrid.nix)
configuration. This layout is compatible with both BIOS and EFI systems.
Refer to the [reference manual](./reference) for more information about the sample layouts and how to build your own configuration.
Refer to the [reference manual](./reference) for more information about the
sample layouts and how to build your own configuration.
Once you've chosen your layout, you'll need to make a note of the URL to the raw file. To do this, open the file in Github. Immediately below the list of contributors, you will see a button labelled 'RAW' near the right hand side. Click this. The URL of the raw file will appear in the search bar of your browser. It will look something like this:
Once you've chosen your layout, you'll need to make a note of the URL to the raw
file. To do this, open the file in Github. Immediately below the list of
contributors, you will see a button labelled 'RAW' near the right hand side.
Click this. The URL of the raw file will appear in the search bar of your
browser. It will look something like this:
```
https://raw.githubusercontent.com/nix-community/disko/master/example/hybrid.nix
@ -24,11 +37,15 @@ https://raw.githubusercontent.com/nix-community/disko/master/example/hybrid.nix
### Step 2: Boot the installer
Download the NixOS ISO image from the NixOS [download page](https://nixos.org/download.html#nixos-iso), and create a bootable USB drive following the instructions in [Section 2.4.1 "Booting from a USB flash drive"](https://nixos.org/manual/nixos/stable/index.html#sec-booting-from-usb) of the NixOS manual. Boot the machine from this USB drive.
Download the NixOS ISO image from the NixOS
[download page](https://nixos.org/download.html#nixos-iso), and create a
bootable USB drive following the instructions
in [Section 2.4.1 "Booting from a USB flash drive"](https://nixos.org/manual/nixos/stable/index.html#sec-booting-from-usb) of
the NixOS manual. Boot the machine from this USB drive.
### Step 3: Retrieve the disk name
Identify the name of your system disk by using the ```lsblk``` command as follows:
Identify the name of your system disk by using the `lsblk` command as follows:
```
$ lsblk
@ -41,13 +58,20 @@ NAME        MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
nvme0n1     259:0    0   1,8T  0 disk
```
In this example, an empty NVME SSD with 2TB space is shown with the disk name "nvme0n1". Make a note of the disk name as you will need it later.
In this example, an empty NVME SSD with 2TB space is shown with the disk name
"nvme0n1". Make a note of the disk name as you will need it later.
### Step 4: Copy the disk configuration to your machine
In Step 1, you chose a disk layout configuration from the  [examples directory](https://github.com/nix-community/disko/tree/master/example), and made a note of its URL.
In Step 1, you chose a disk layout configuration from the
[examples directory](https://github.com/nix-community/disko/tree/master/example),
and made a note of its URL.
Your configuration needs to be saved on the new machine as /tmp/disko-config.nix. You can do this using the ```curl``` command to download from the url you noted above, using the `-o` option to save the file as disko-config.nix. Your commands would look like this if you had chosen the hybrid layout:
Your configuration needs to be saved on the new machine
as /tmp/disko-config.nix. You can do this using the `curl` command to download
from the url you noted above, using the `-o` option to save the file as
disko-config.nix. Your commands would look like this if you had chosen the
hybrid layout:
```
cd /tmp
@ -56,7 +80,8 @@ $ curl https://raw.githubusercontent.com/nix-community/disko/master/example/hybr
### Step 5: Run disko to partition, format and mount your disks
The following step will partition and format your disk, and mount it to `/mnt`. Replace `<disk-name>` with the name of your disk obtained in Step 1.
The following step will partition and format your disk, and mount it to `/mnt`.
Replace `<disk-name>` with the name of your disk obtained in Step 1.
Please note: This will erase any existing data on your disk.
@ -70,7 +95,8 @@ For example, if the disk name is `nvme0n1`, the command would be:
$ sudo nix run github:nix-community/disko -- --mode disko /tmp/disko-config.nix --arg disks '[ "/dev/nvme0n1" ]'
```
After the command has run, your file system should have been formatted and mounted. You can verify this by running the following command:
After the command has run, your file system should have been formatted and
mounted. You can verify this by running the following command:
```
$ mount | grep /mnt
@ -83,11 +109,21 @@ The output should look like this if your disk name is `nvme0n1`.
/dev/nvme0n1p2 on /mnt/boot type vfat (rw,relatime,fmask=0022,dmask=0022,codepage=437,iocharset=iso8859-1,shortname=mixed,errors=remount-ro)
```
### Step 6: Complete the NixOS installation.
### Step 6: Complete the NixOS installation.
Your disks have now been formatted and mounted, and you are ready to complete the NixOS installation as described in the [NixOS manual](https://nixos.org/manual/nixos/stable/index.html#sec-installation) - see the section headed "**Installing**", Steps 3 onwards. However, you will need to include the partitioning and formatting configurations that you copied into `/tmp/disko-config.nix` in your configuration, rather than allowing NixOS to generate information about your file systems. When you are configuring the system as per Step 4 of the manual, you should:
Your disks have now been formatted and mounted, and you are ready to complete
the NixOS installation as described in the
[NixOS manual](https://nixos.org/manual/nixos/stable/index.html#sec-installation) -
see the section headed "**Installing**", Steps 3 onwards. However, you will need
to include the partitioning and formatting configurations that you copied into
`/tmp/disko-config.nix` in your configuration, rather than allowing NixOS to
generate information about your file systems. When you are configuring the
system as per Step 4 of the manual, you should:
a) Include the `no-filesystems` switch when using the `nixos-generate-config` command to generate an initial `configuration.nix`. You will be supplying the file system configuration details from `disko-config.nix`. Your CLI command to generate the configuration will be:
a) Include the `no-filesystems` switch when using the `nixos-generate-config`
command to generate an initial `configuration.nix`. You will be supplying the
file system configuration details from `disko-config.nix`. Your CLI command to
generate the configuration will be:
```
$ nixos-generate-config --no-filesystems --root /mnt
@ -101,9 +137,20 @@ b) Move the `disko` configuration to /etc/nixos
$ mv /tmp/disko-config.nix /mnt/etc/nixos
```
c) You can now edit `configuration.nix` as per your requirements. This is described in Step 4 of the manual. For more information about configuring your system, refer to the NixOS manual. [Chapter 6, Configuration Syntax](https://nixos.org/manual/nixos/stable/index.html#sec-configuration-syntax) describes the NixOS configuration syntax, and [Appendix A, Configuration Options](https://nixos.org/manual/nixos/stable/options.html) gives a list of available options. You can find also find a minimal example of a NixOS configuration in the manual: [Example: NixOS Configuration](https://nixos.org/manual/nixos/stable/index.html#ex-config).
c) You can now edit `configuration.nix` as per your requirements. This is
described in Step 4 of the manual. For more information about configuring your
system, refer to the NixOS manual.
[Chapter 6, Configuration Syntax](https://nixos.org/manual/nixos/stable/index.html#sec-configuration-syntax)
describes the NixOS configuration syntax, and
[Appendix A, Configuration Options](https://nixos.org/manual/nixos/stable/options.html)
gives a list of available options. You can find also find a minimal example of a
NixOS configuration in the manual:
[Example: NixOS Configuration](https://nixos.org/manual/nixos/stable/index.html#ex-config).
d) When editing `configuration.nix`, you will need to add the `disko` NixOS module and `disko-config.nix` to the imports section. This section will already include the file `./hardware-configuration.nix`, and you can add the new entries just below this. This section will now include:
d) When editing `configuration.nix`, you will need to add the `disko` NixOS
module and `disko-config.nix` to the imports section. This section will already
include the file `./hardware-configuration.nix`, and you can add the new entries
just below this. This section will now include:
```
imports =
@ -116,7 +163,11 @@ imports =
};
```
e) If you chose the hybrid-partition scheme, then choose `grub` as a bootloader, otherwise follow the recommendations in Step 4 of the **Installation** section of the NixOS manual. The following configuration for `grub` works for both EFI and BIOS systems. Add this to your configuration.nix, commenting out the existing lines that configure `systemd-boot`. The entries will look like this:
e) If you chose the hybrid-partition scheme, then choose `grub` as a bootloader,
otherwise follow the recommendations in Step 4 of the **Installation** section
of the NixOS manual. The following configuration for `grub` works for both EFI
and BIOS systems. Add this to your configuration.nix, commenting out the
existing lines that configure `systemd-boot`. The entries will look like this:
```
# ...

View file

@ -2,10 +2,12 @@
## Module Options
We are currently having issues beeing 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 [examples](https://github.com/nix-community/disko/tree/master/example) this hopefully gives you an overview.
We are currently having issues beeing 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
[examples](https://github.com/nix-community/disko/tree/master/example) this
hopefully gives you an overview.
## # Reference Manual: disko
@ -42,4 +44,4 @@ Options:
run with set -x
```
##
##

View file

@ -1,13 +1,18 @@
# 2023-07-09 121df48
Changes:
- BTRFS subvolumes are mounted if and only their `mountpoint` is set.
Especially, if you have specific mount options for a subvolume (through `mountOptions`), make sure to set `mountpoint` otherwise the subvolume will not be mounted.
- BTRFS subvolumes are mounted if and only their `mountpoint` is set.
This change allows more flexibility when using BTRFS, giving access to its volume management functionality.
Especially, if you have specific mount options for a subvolume (through
`mountOptions`), make sure to set `mountpoint` otherwise the subvolume will not
be mounted.
This change allows more flexibility when using BTRFS, giving access to its
volume management functionality.
It allows layouts as the following:
```nix
content = {
type = "btrfs";
@ -38,7 +43,9 @@ content = {
};
};
```
corresponding to the following BTRFS layout:
```
BTRFS partition # not mounted
|
@ -87,15 +94,17 @@ datasets = {
}
```
Note: The `zfs_type` attribute has been replaced with a type attribute for each dataset, and the `size` attribute is only available for `zfs_volume`.
These changes have been reflected in the `example/zfs.nix` file.
Note: The `zfs_type` attribute has been replaced with a type attribute for each
dataset, and the `size` attribute is only available for `zfs_volume`. These
changes have been reflected in the `example/zfs.nix` file.
# 2023-04-07 654ecb3
The `lvm_lv` type is always part of an `lvm_vg` and it is no longer necessary to specify the type.
The `lvm_lv` type is always part of an `lvm_vg` and it is no longer necessary to
specify the type.
This means that if you were using the `lvm_lv` type in your code, you should remove it.
For example, if you were defining an `lvm_lv` type like this:
This means that if you were using the `lvm_lv` type in your code, you should
remove it. For example, if you were defining an `lvm_lv` type like this:
```nix
{
@ -107,7 +116,6 @@ For example, if you were defining an `lvm_lv` type like this:
You should now define it like this:
```nix
{
size = "10G";
@ -115,11 +123,14 @@ You should now define it like this:
}
```
Note that the `type` field is no longer necessary and should be removed from your code.
Note that the `type` field is no longer necessary and should be removed from
your code.
# 2023-04-07 d6f062e
Partition types are now always part of a table and cannot be specified individually anymore. This change makes the library more consistent and easier to use.
Partition types are now always part of a table and cannot be specified
individually anymore. This change makes the library more consistent and easier
to use.
Example of how to change code:
@ -146,7 +157,8 @@ After:
}
```
Note that the `type` field is no longer necessary and should be removed from your code.
Note that the `type` field is no longer necessary and should be removed from
your code.
# 2023-03-22 2624af6

View file

@ -24,7 +24,7 @@ let
description = "one of ${concatStringsSep "," (attrNames types)}";
check = x: if x ? type then types.${x.type}.check x else throw "No type option set in:\n${generators.toPretty {} x}";
merge = loc: foldl'
(res: def: types.${def.value.type}.merge loc [
(_res: def: types.${def.value.type}.merge loc [
# we add a dummy root parent node to render documentation
(lib.recursiveUpdate { value._module.args = extraArgs; } def)
])
@ -183,7 +183,7 @@ let
/* Takes a Submodules config and options argument and returns a serializable
subset of config variables as a shell script snippet.
*/
defineHookVariables = { config, options }:
defineHookVariables = { options }:
let
sanitizeName = lib.replaceStrings [ "-" ] [ "_" ];
isAttrsOfSubmodule = o: o.type.name == "attrsOf" && o.type.nestedTypes.elemType.name == "submodule";
@ -229,7 +229,7 @@ let
type = lib.types.str;
default = ''
( # ${config.type} ${concatMapStringsSep " " (n: toString (config.${n} or "")) ["name" "device" "format" "mountpoint"]} #
${diskoLib.indent (diskoLib.defineHookVariables { inherit config options; })}
${diskoLib.indent (diskoLib.defineHookVariables { inherit options; })}
${config.preCreateHook}
${diskoLib.indent attrs.default}
${config.postCreateHook}
@ -238,7 +238,7 @@ let
description = "Creation script";
};
mkMountOption = { config, options, default }@attrs:
mkMountOption = { default, ... }@attrs:
lib.mkOption {
internal = true;
readOnly = true;

View file

@ -86,7 +86,7 @@ let
tsp-config = tsp-generator.config testConfigBooted;
num-disks = builtins.length (lib.attrNames testConfigBooted.disko.devices.disk);
installed-system = { modulesPath, ... }: {
installed-system = { ... }: {
imports = [
(lib.optionalAttrs (testMode == "direct") tsp-config)
(lib.optionalAttrs (testMode == "module") {
@ -149,7 +149,7 @@ let
makeTest' {
name = "disko-${name}";
nodes.machine = { pkgs, modulesPath, ... }: {
nodes.machine = { pkgs, ... }: {
imports = [
(lib.optionalAttrs (testMode == "module") {
imports = [

View file

@ -68,7 +68,7 @@
internal = true;
readOnly = true;
type = lib.types.functionTo diskoLib.jsonType;
default = dev: { };
default = _dev: { };
description = "Metadata";
};
_create = diskoLib.mkCreateOption {

View file

@ -60,7 +60,7 @@ in
Extra NixOS config for your test. Can be used to specify a different luks key for tests.
A dummy key is in /tmp/secret.key
'';
default = {};
default = { };
};
};
};