diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 233 |
1 files changed, 175 insertions, 58 deletions
@@ -1,71 +1,188 @@ -disko -===== +# disko - declarative disk partitioning -nix-powered automatic disk partitioning +Disko takes the NixOS module system and makes it work for disk partitioning +as well. -Usage -===== +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. -Master Boot Record ------------------- -This is how your iso configuation may look like +## Features -```nix -{ pkgs, ... }: -let - disko = (builtins.fetchGit { - url = https://cgit.lassul.us/disko/; - rev = "88f56a0b644dd7bfa8438409bea5377adef6aef4"; - }) + "/lib"; - cfg = builtins.fromJSON ./tsp-disk.json; -in { - imports = [ - <nixpkgs/nixos/modules/installer/cd-dvd/installation-cd-minimal.nix> - ]; - environment.systemPackages = with pkgs;[ - (pkgs.writeScriptBin "tsp-create" (disko.mount cfg)) - (pkgs.writeScriptBin "tsp-mount" (disko.mount cfg)) - ]; - # Optional: Automatically creates a service which runs at startup to perform the partitioning - systemd.services.install-to-hd = { - enable = true; - wantedBy = ["multi-user.target"]; - after = ["getty@tty1.service" ]; - serviceConfig = { - Type = "oneshot"; - ExecStart = [ (disko.create cfg) (disk.mount cfg) (]; - StandardInput = "null"; - StandardOutput = "journal+console"; - StandardError = "inherit"; +* supports LVM, ZFS, btrfs, GPT, mdadm, ext4, ... +* supports recursive layouts +* outputs a NixOS-compatible module +* CLI + +## How-to guides + +### NixOS installation + +During the NixOS installation process, replace the [Partitioning and +formatting](https://nixos.org/manual/nixos/stable/index.html#sec-installation-partitioning) +steps with the following: + +1. Find a disk layout in ./examples that you like. +2. Write the config based on the example and your disk layout. +4. Run the CLI (`nix run github:nix-community/disko`) to apply the changes. +5. FIXME: Copy the disko module and disk layout around. +6. Continue the NixOS installation. + +### Using without NixOS + +## Reference + +### Module options + +TODO: link to generated module options + +### Examples + +./examples + +### CLI + +TODO: output of the cli --help + +## 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 + ]; }; }; } ``` -tsp-disk.json (TODO: find the correct disk) -```json +</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 { - "type": "devices", - "content": { - "sda": { - "type": "table", - "format": "msdos", - "partitions": [ - { "type": "partition", - "start": "1M", - "end": "100%", - "bootable": true, - "content": { - "type": "filesystem", - "format": "ext4", - "mountpoint": "/" + 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/main.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 diska layouts + disko.devices = { + disk.sda = { + device = "/dev/sda"; + 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 = "/"; + }; + } + ]; + }; + }; + }; } ``` -GUID Partition Table, LVM and dm-crypt --------------------------------------- -See `examples/` +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. |