From 58fe856c7f03c1cdc50d4faec2cd3d657b324aa2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= Date: Fri, 15 Sep 2023 07:56:40 +0200 Subject: [PATCH] reformat tree --- README.md | 66 ++++++++++++++++++++++---------- docs/HowTo.md | 29 +++++++++------ docs/quickstart.md | 87 ++++++++++++++++++++++++++++++++++--------- docs/reference.md | 12 +++--- docs/upgrade-guide.md | 36 ++++++++++++------ module.nix | 2 +- 6 files changed, 166 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index 0d4c949..0d0e9d8 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/HowTo.md b/docs/HowTo.md index aa755a5..c4a111f 100644 --- a/docs/HowTo.md +++ b/docs/HowTo.md @@ -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: }; } ``` +
niv - 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" ]; } ``` +
nix-channel - 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 = [ ]; } ``` +
fetchTarball - 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 ]; } ``` +
## 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. diff --git a/docs/quickstart.md b/docs/quickstart.md index 2ce0e40..4db82df 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -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 `` 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 `` 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: ``` # ... diff --git a/docs/reference.md b/docs/reference.md index d5be846..fe44003 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -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 ``` -## +## diff --git a/docs/upgrade-guide.md b/docs/upgrade-guide.md index c967863..e6aa835 100644 --- a/docs/upgrade-guide.md +++ b/docs/upgrade-guide.md @@ -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 diff --git a/module.nix b/module.nix index 9f8c42d..a178d36 100644 --- a/module.nix +++ b/module.nix @@ -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 = { }; }; }; };