disko/README.md

116 lines
4.9 KiB
Markdown
Raw Normal View History

2023-05-09 12:38:07 +03:00
# disko - Declarative disk partitioning
2018-09-11 21:42:55 +03:00
2023-04-16 18:04:15 +03:00
<!-- Generated with bing image generator (which uses dall-e-2): edge-gpt-image --prompt "Disco ball shooting a laser beam at one hard drive" -->
<img title="" src="./docs/logo.jpeg" alt="Project logo" width="274">
[Documentation Index](./docs/INDEX.md)
2023-04-16 18:04:15 +03:00
2023-05-09 12:38:07 +03:00
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.
2023-05-09 12:38:07 +03:00
This is especially useful for unattended installations, re-installation after a system crash or for setting up more than one identical server.
2023-05-09 12:38:07 +03:00
## Overview
2023-05-09 12:38:07 +03:00
**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.
2023-05-09 12:38:07 +03:00
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.
2023-05-09 12:38:07 +03:00
You can keep your configuration and re-use it for other installations, or for a system rebuild.
2023-05-09 12:38:07 +03:00
**disko** is flexible, in that it supports most of the common formatting and partitioning options, including:
2023-05-09 12:38:07 +03:00
- Disk layouts: GPT, MBR, and mixed.
- Partition tools: LVM, mdadm, LUKS, and more.
- Filesystems: ext4, btrfs, ZFS, bcachefs, tmpfs, and others.
2023-05-09 12:38:07 +03:00
It can work with these in various configurations and orders, and supports recursive layouts.
2023-04-15 17:04:05 +03:00
2023-05-09 12:38:07 +03:00
## How to use disko
2023-05-09 12:38:07 +03:00
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.
2023-05-09 12:38:07 +03:00
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)
2023-05-09 12:38:07 +03:00
For more detailed options, such as command line switches, see the [Reference Guide](./docs/reference.md)
2023-05-09 12:38:07 +03:00
To access sample configurations for commonly-used disk layouts, refer to the [examples](./examples) provided.
2023-05-09 12:38:07 +03:00
## Sample Configuration and CLI command
2023-05-09 12:38:07 +03:00
A simple disko configuration may look like this:
2023-02-01 16:52:46 +03:00
```
2023-05-09 12:38:07 +03:00
{ 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 = "/";
     };
    }
   ];
  };
 };
};
2022-10-23 13:29:30 +03:00
}
```
2023-06-05 11:23:08 +03:00
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.
2018-09-11 21:42:55 +03:00
2023-06-05 11:23:08 +03:00
```
$ sudo nix run github:nix-community/disko -- --mode disko /tmp/disko-config.nix --arg disks '[ "/dev/nvme0n1" ]'
2023-06-05 11:23:08 +03:00
```
2022-10-23 13:29:30 +03:00
2023-05-09 12:38:07 +03:00
## Related Tools
2022-10-23 13:29:30 +03:00
2023-05-09 12:38:07 +03:00
This tool is used by [nixos-anywhere](https://github.com/numtide/nixos-anywhere), which carries out a fully-automated remote install of NixOS.
2022-10-23 13:29:30 +03:00
2023-05-09 12:38:07 +03:00
We also acknowledge https://github.com/NixOS/nixpart, the conceptual ancestor of this project.
2022-10-23 13:29:30 +03:00
2023-05-09 12:38:07 +03:00
## Licensing and Contribution details
2022-10-23 13:29:30 +03:00
2023-05-09 12:38:07 +03:00
This software is provided free under the [MIT Licence](https://opensource.org/licenses/MIT).
2022-10-23 13:29:30 +03:00
2023-05-09 12:38:07 +03:00
If you would like to become a contributor, please see our [contribution guidelines.](https://github.com/numtide/docs/contribution-guidelines.md)
2022-10-23 13:29:30 +03:00
2023-05-09 12:38:07 +03:00
---
This project is supported by [Numtide](https://numtide.com/).  ![Untitledpng](https://codahosted.io/docs/6FCIMTRM0p/blobs/bl-sgSunaXYWX/077f3f9d7d76d6a228a937afa0658292584dedb5b852a8ca370b6c61dabb7872b7f617e603f1793928dc5410c74b3e77af21a89e435fa71a681a868d21fd1f599dd10a647dd855e14043979f1df7956f67c3260c0442e24b34662307204b83ea34de929d)    
2018-09-11 21:42:55 +03:00
2023-05-09 12:38:07 +03:00
We are a team of independent freelancers that love open source.  We help our customers make their project lifecycles more efficient by:
2023-05-09 12:38:07 +03:00
- 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.
2023-05-09 12:38:07 +03:00
[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.