Mirrors/disko
2
0
Fork 0
mirror of https://github.com/nix-community/disko synced 2024-09-20 05:51:54 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #229 from JillThornhill/master

Browse source
This commit is contained in:
Lassulus 2023-06-05 15:00:51 +02:00 committed by GitHub
commit 29d632d7e8
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
7 changed files with 363 additions and 242 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

267
README.md
View file

@ -1,210 +1,115 @@
# disko - declarative disk partitioning
# disko - Declarative disk partitioning
<!-- Generated with bing image generator (which uses dall-e-2): edge-gpt-image --prompt "Disco ball shooting a laser beam at one hard drive" -->
![Project logo](./docs/logo.jpeg)
Disko takes the NixOS module system and makes it work for disk partitioning
as well.
<img title="" src="./docs/logo.jpeg" alt="Project logo" width="274">
I wanted to write a curses NixOS installer, and that was the first step that I
hit; the disk formatting is a manual process. Once that's done, the NixOS
system itself is declarative, but the actual formatting of disks is manual.
[Documentation Index](./docs/INDEX.md)
## Features
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.
* supports LVM, ZFS, btrfs, GPT, mdadm, ext4, ...
* supports recursive layouts
* outputs a NixOS-compatible module
* CLI
This is especially useful for unattended installations, re-installation after a system crash or for setting up more than one identical server.
## How-to guides
## Overview
### NixOS installation
**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.
For a NixOS installation follow this [quickstart guide](./docs/quickstart.md).
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.
### Using without NixOS
You can keep your configuration and re-use it for other installations, or for a system rebuild.
### Upgrading from older disko versions
**disko** is flexible, in that it supports most of the common formatting and partitioning options, including:
Read our [upgrade guide](/docs/upgrade-guide.md) when updating from older versions.
- Disk layouts: GPT, MBR, and mixed.
- Partition tools: LVM, mdadm, LUKS, and more.
- Filesystems: ext4, btrfs, ZFS, bcachefs, tmpfs, and others.
## Reference
It can work with these in various configurations and orders, and supports recursive layouts.
### Module options
## How to use disko
TODO: link to generated module options
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.
### Examples
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/quickstart.md)
./examples
For more detailed options, such as command line switches, see the [Reference Guide](./docs/reference.md)
### CLI
To access sample configurations for commonly-used disk layouts, refer to the [examples](./examples) provided.
## Sample Configuration and CLI command
A simple disko configuration may look like this:
```
$ nix run github:nix-community/disko --
disko [options] disk-config.nix
or disko [options] --flake github:somebody/somewhere
Options:
* -m, --mode mode
set the mode, either create or mount
* -f, --flake uri
fetch the disko config relative to this flake's root
* --arg name value
pass value to nix-build. can be used to set disk-names for example
* --argstr name value
pass value to nix-build as string
* --root-mountpoint /mnt
where to mount the device tree
* --dry-run
just show the path to the script instead of running it
* --debug
run with set -x
```
## Installing NixOS module
You can use the NixOS module in one of the following ways:
<details>
<summary>Flakes (Current recommendation)</summary>
If you use nix flakes support:
``` nix
{
inputs.disko.url = "github:nix-community/disko";
inputs.disko.inputs.nixpkgs.follows = "nixpkgs";
outputs = { self, nixpkgs, disko }: {
# change `yourhostname` to your actual hostname
nixosConfigurations.yourhostname = nixpkgs.lib.nixosSystem {
# change to your system:
system = "x86_64-linux";
modules = [
./configuration.nix
disko.nixosModules.disko
];
};
};
}
```
</details>
<details>
<summary>niv</summary>
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:
```nix
{
imports = [ "${(import ./nix/sources.nix).disko}/modules/disko.nix" ];
}
```
</details>
<details>
<summary>nix-channel</summary>
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:
```nix
{
imports = [ <disko/modules/disko.nix> ];
}
```
</details>
<details>
<summary>fetchTarball</summary>
Add the following to your configuration.nix:
``` nix
{
imports = [ "${builtins.fetchTarball "https://github.com/nix-community/disko/archive/master.tar.gz"}/module.nix" ];
{ disks ? [ "/dev/vdb" ], ... }: {
disk = {
 vdb = {
  device = builtins.elemAt disks 0;
  type = "disk";
  content = {
   type = "table";
   format = "gpt";
   partitions = [
    {
     type = "partition";
     name = "ESP";
     start = "1MiB";
     end = "100MiB";
     bootable = true;
     content = {
      type = "filesystem";
      format = "vfat";
      mountpoint = "/boot";
     };
    }
    {
     name = "root";
     type = "partition";
     start = "100MiB";
     end = "100%";
     part-type = "primary";
     bootable = true;
     content = {
      type = "filesystem";
      format = "ext4";
      mountpoint = "/";
     };
    }
   ];
  };
 };
};
}
```
or with pinning:
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.
```nix
{
imports = let
# replace this with an actual commit id or tag
commit = "f2783a8ef91624b375a3cf665c3af4ac60b7c278";
in [
"${builtins.fetchTarball {
url = "https://github.com/nix-community/disko/archive/${commit}.tar.gz";
# replace this with an actual hash
sha256 = "0000000000000000000000000000000000000000000000000000";
}}/module.nix"
];
}
```
</details>
## Using the NixOS module
```nix
{
# checkout the example folder for how to configure different disko layouts
disko.devices = {
disk.sda = {
device = "/dev/sda";
type = "disk";
content = {
type = "table";
format = "gpt";
partitions = [
{
name = "ESP";
start = "1MiB";
end = "100MiB";
bootable = true;
content = {
type = "filesystem";
format = "vfat";
mountpoint = "/boot";
};
}
{
name = "root";
start = "100MiB";
end = "100%";
part-type = "primary";
bootable = true;
content = {
type = "filesystem";
format = "ext4";
mountpoint = "/";
};
}
];
};
};
};
}
$ sudo nix run github:nix-community/disko -- --mode zap_create_mount /tmp/disko-config.nix --arg disks '[ "/dev/nvme0n1" ]'
```
this will configure `fileSystems` and other required NixOS options to boot the specified configuration.
## Related Tools
If you are on an installer, you probably want to disable `enableConfig`.
This tool is used by [nixos-anywhere](https://github.com/numtide/nixos-anywhere), which carries out a fully-automated remote install of NixOS.
disko will create the scripts `disko-create` and `disko-mount` which can be used to create/mount the configured disk layout.
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).
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)    
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
- Building their in-house Nix skills, and integrating Nix with their workflows
- 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.

152
docs/HowTo.md Normal file
View file

@ -0,0 +1,152 @@
# How-to Guide: Disko
## How to use Disko without NixOS
TODO: Still to be documented
## Upgrading From Older disko versions
TODO: Include documentation here.
For now, see the [upgrade guide](https://github.com/JillThornhill/disko/blob/master/docs/upgrade-guide.md)
## Installing NixOS module
You can use the NixOS module in one of the following ways:
<details>
<summary>Flakes (Current recommendation)</summary>
If you use nix flakes support:
``` nix
{
inputs.disko.url = "github:nix-community/disko";
inputs.disko.inputs.nixpkgs.follows = "nixpkgs";
outputs = { self, nixpkgs, disko }: {
# change `yourhostname` to your actual hostname
nixosConfigurations.yourhostname = nixpkgs.lib.nixosSystem {
# change to your system:
system = "x86_64-linux";
modules = [
./configuration.nix
disko.nixosModules.disko
];
};
};
}
```
</details>
<details>
<summary>niv</summary>
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:
```nix
{
imports = [ "${(import ./nix/sources.nix).disko}/modules/disko.nix" ];
}
```
</details>
<details>
<summary>nix-channel</summary>
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:
```nix
{
imports = [ <disko/modules/disko.nix> ];
}
```
</details>
<details>
<summary>fetchTarball</summary>
Add the following to your configuration.nix:
``` nix
{
imports = [ "${builtins.fetchTarball "https://github.com/nix-community/disko/archive/master.tar.gz"}/module.nix" ];
}
```
or with pinning:
```nix
{
imports = let
# replace this with an actual commit id or tag
commit = "f2783a8ef91624b375a3cf665c3af4ac60b7c278";
in [
"${builtins.fetchTarball {
url = "https://github.com/nix-community/disko/archive/${commit}.tar.gz";
# replace this with an actual hash
sha256 = "0000000000000000000000000000000000000000000000000000";
}}/module.nix"
];
}
```
</details>
## Using the NixOS module
```nix
{
# checkout the example folder for how to configure different disko layouts
disko.devices = {
disk.sda = {
device = "/dev/sda";
type = "disk";
content = {
type = "table";
format = "gpt";
partitions = [
{
name = "ESP";
start = "1MiB";
end = "100MiB";
bootable = true;
content = {
type = "filesystem";
format = "vfat";
mountpoint = "/boot";
};
}
{
name = "root";
start = "100MiB";
end = "100%";
part-type = "primary";
bootable = true;
content = {
type = "filesystem";
format = "ext4";
mountpoint = "/";
};
}
];
};
};
};
}
```
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.

13
docs/INDEX.md Normal file
View file

@ -0,0 +1,13 @@
# disko - Declarative disk partitioning
<img title="" src="./logo.jpeg" alt="" width="220">
## Table of Contents
- [README](../README.md)
- [Quickstart](./quickstart.md)
- [System Requirements](./requirements.md)
- [How to Guide](./HowTo.md)
- [Support Matrix](./supportmatrix.md)
- [Reference](./reference.md)
- [Upgrade Guide](./upgrade-guide.md)

123
docs/quickstart.md
View file

@ -1,121 +1,122 @@
# Disko quickstart
# disko - Declarative disk partitioning
This tutorial will guide you through the process of installing NixOS on a single
disk system using Disko.
<img src="./logo.jpeg" title="" alt="Project logo" width="247">
1. Booting the installer
[Documentation Index](./INDEX.md)
Download NixOS ISO images 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.
## Quickstart Guide
2. The disk name
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)
Identify the name of your system disk by using the lsblk command.
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.
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:
```
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.
### Step 3: Retrieve the disk name
Identify the name of your system disk by using the ```lsblk``` command as follows:
```
$ lsblk
```
The output from this command will look something like this:
```
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 as "nvme0n1" disk.
Please note that Disko will reformat the entire disk and overwrite any existing
partitions. Dual booting with other operating systems is not supported.
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
3. Disk layout
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.
Choose a disk layout from the [examples directory](https://github.com/nix-community/disko/tree/master/example)
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:
For those who are unsure of which layout to pick, use the hybrid configuration
found at https://github.com/nix-community/disko/blob/master/example/hybrid.nix
and save it as `/tmp/disko-config.nix`. This layout is compatible with both BIOS
and EFI systems.
```
cd /tmp
$ curl https://raw.githubusercontent.com/nix-community/disko/master/example/hybrid.nix -o disko-config.nix
```
4. Formatting
### Step 5: Run disko to partition, format and mount your disks
The following step will reformat 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.
```
$ sudo nix run github:nix-community/disko -- --mode zap_create_mount /tmp/disko-config.nix --arg disks '[ "/dev/<disk-name>" ]'
$ sudo nix run github:nix-community/disko -- --mode disko /tmp/disko-config.nix --arg disks '[ "/dev/<disk-name>" ]'
```
For example, if the disk name is `nvme0n1`:
For example, if the disk name is `nvme0n1`, the command would be:
```
$ sudo nix run github:nix-community/disko -- --mode zap_create_mount /tmp/disko-config.nix --arg disks '[ "/dev/nvme0n1" ]'
$ sudo nix run github:nix-community/disko -- --mode disko /tmp/disko-config.nix --arg disks '[ "/dev/nvme0n1" ]'
```
After executing the command, the file systems will be 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
```
The output should look like this if your disk name is `nvme0n1`.
```
/dev/nvme0n1p1 on /mnt type ext4 (rw,relatime,stripe=2)
/dev/nvme0n1p2 on /mnt/boot type vfat (rw,relatime,fmask=0022,dmask=0022,codepage=437,iocharset=iso8859-1,shortname=mixed,errors=remount-ro)
```
5. Rest of the NixOS installation:
### Step 6: Complete the NixOS installation.
Generate and modify the NixOS configuration.
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:
You now need to create a file `/mnt/etc/nixos/configuration.nix` that specifies
the intended configuration of the system. This is because NixOS has a
declarative configuration model: you create or edit a description of the desired
configuration of your system, and then NixOS takes care of making it happen. The
syntax of the NixOS configuration file is described in
[Chapter 6, Configuration Syntax](https://nixos.org/manual/nixos/stable/index.html#sec-configuration-syntax),
while a list of available configuration options appears in
[Appendix A, Configuration Options](https://nixos.org/manual/nixos/stable/options.html).
A minimal example is shown in
[Example: NixOS Configuration](https://nixos.org/manual/nixos/stable/index.html#ex-config).
The command nixos-generate-config can generate an initial configuration file for
you.
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
```
We will include `--no-filesystems` the flag here so it won't add any filesystem
mountpoints to the generated `/mnt/etc/nixos/hardware-configuration.nix` since
we will re-use our disko configuration for that.
This will create the file `configuration.nix` in `/mnt/etc/nixos`.
Next move the disko configuration as well to /etc/nixos
b) Move the `disko` configuration to /etc/nixos
```
$ mv /tmp/disko-config.nix /mnt/etc/nixos
```
You should then edit /mnt/etc/nixos/configuration.nix to suit your needs
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).
```
$ nano /mnt/etc/nixos/configuration.nix
```
While being in this file also add the disko nixos module as well as the
disko-config.nix in the imports section of your generated configuration:
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 =
[ # Include the results of the hardware scan.
./hardware-configuration.nix
"${builtins.fetchTarball "https://github.com/nix-community/disko/archive/master.tar.gz"}/module.nix"
(import ./disko-config.nix {
disks = [ "/dev/<disk-name>" ]; # replace this with your disk name i.e. /dev/nvme0n1
})
];
disko.devices = pkgs.callPackage ./disko-config.nix {
disks = [ "/dev/<disk-name>" ]; # replace this with your disk name i.e. /dev/nvme0n1
};
```
If you went for the hybrid-partition scheme, then choose grub as a bootloader.
Otherwise consult the NixOS manual. The following configuration for Grub works
both EFI and BIOS systems. Add it to your configuration.nix while commenting out
the existing lines about `systemd-boot`:
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:
```
# ...
@ -130,7 +131,7 @@ the existing lines about `systemd-boot`:
# ...
```
Then finish the installation and reboot your machine
f) Finish the installation and reboot your machine,
```
$ nixos-install

32
docs/reference.md Normal file
View file

@ -0,0 +1,32 @@
# Reference Manual: disko
## Module Options
TODO: Still to be documented
## # Reference Manual: disko
## Command Line Options
```
$ nix run github:nix-community/disko --
disko [options] disk-config.nix
or disko [options] --flake github:somebody/somewhere
Options:
* -m, --mode mode
set the mode, either create or mount
* -f, --flake uri
fetch the disko config relative to this flake's root
* --arg name value
pass value to nix-build. can be used to set disk-names for example
* --argstr name value
pass value to nix-build as string
* --root-mountpoint /mnt
where to mount the device tree
* --dry-run
just show the path to the script instead of running it
* --debug
run with set -x
```
##

9
docs/requirements.md Normal file
View file

@ -0,0 +1,9 @@
# disko - Declarative disk partitioning
<img title="" src="./logo.jpeg" alt="" width="220">
[Documentation Index](./INDEX.md)
## System Requirements
TODO: Populate this

9
docs/supportmatrix.md Normal file
View file

@ -0,0 +1,9 @@
# disko - Declarative disk partitioning
<img title="" src="./logo.jpeg" alt="" width="220">
[Documentation Index](./INDEX.md)
## Support Matrix
TODO: Populate this