mirror of
https://github.com/nix-community/disko.git
synced 2024-11-04 05:44:29 +03:00
Update README.md
Editing Readme
This commit is contained in:
JillThornhill
lassulus
parent
ce406dfd46
commit
15020a6395
261
README.md
261
README.md
@ -1,210 +1,111 @@
|
|||||||
# 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" -->
|
<!-- Generated with bing image generator (which uses dall-e-2): edge-gpt-image --prompt "Disco ball shooting a laser beam at one hard drive" -->
|
||||||
|
|
||||||
|
|
||||||
Disko takes the NixOS module system and makes it work for disk partitioning
|
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.
|
||||||
as well.
|
|
||||||
|
|
||||||
I wanted to write a curses NixOS installer, and that was the first step that I
|
This is especially useful for unattended installations, re-installation after a system crash or for setting up more than one identical server.
|
||||||
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.
|
|
||||||
|
|
||||||
## Features
|
## Overview
|
||||||
|
|
||||||
* supports LVM, ZFS, btrfs, GPT, mdadm, ext4, ...
|
**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.
|
||||||
* supports recursive layouts
|
|
||||||
* outputs a NixOS-compatible module
|
|
||||||
* CLI
|
|
||||||
|
|
||||||
## How-to guides
|
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.
|
||||||
|
|
||||||
### NixOS installation
|
You can keep your configuration and re-use it for other installations, or for a system rebuild.
|
||||||
|
|
||||||
For a NixOS installation follow this [quickstart guide](./docs/quickstart.md).
|
**disko** is flexible, in that it supports most of the common formatting and partitioning options, including:
|
||||||
|
|
||||||
### Using without NixOS
|
- Disk layouts: GPT, MBR, and mixed.
|
||||||
|
- Partition tools: LVM, mdadm, LUKS, and more.
|
||||||
|
- Filesystems: ext4, btrfs, ZFS, bcachefs, tmpfs, and others.
|
||||||
|
|
||||||
### Upgrading from older disko versions
|
It can work with these in various configurations and orders, and supports recursive layouts.
|
||||||
|
|
||||||
Read our [upgrade guide](/docs/upgrade-guide.md) when updating from older versions.
|
|
||||||
|
|
||||||
## Reference
|
## How to use disko
|
||||||
|
|
||||||
### 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.
|
||||||
|
|
||||||
TODO: link to generated module options
|
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)
|
||||||
|
|
||||||
./examples
|
To access sample configurations for commonly-used disk layouts, refer to the [examples](./examples) provided.
|
||||||
|
|
||||||
### CLI
|
## Sample Configuration and CLI command
|
||||||
|
|
||||||
|
A simple disko configuration may look like this:
|
||||||
|
|
||||||
```
|
```
|
||||||
$ nix run github:nix-community/disko --
|
{ disks ? [ "/dev/vdb" ], ... }: {
|
||||||
|
disk = {
|
||||||
disko [options] disk-config.nix
|
vdb = {
|
||||||
or disko [options] --flake github:somebody/somewhere
|
device = builtins.elemAt disks 0;
|
||||||
|
type = "disk";
|
||||||
Options:
|
content = {
|
||||||
|
type = "table";
|
||||||
* -m, --mode mode
|
format = "gpt";
|
||||||
set the mode, either create or mount
|
partitions = [
|
||||||
* -f, --flake uri
|
{
|
||||||
fetch the disko config relative to this flake's root
|
type = "partition";
|
||||||
* --arg name value
|
name = "ESP";
|
||||||
pass value to nix-build. can be used to set disk-names for example
|
start = "1MiB";
|
||||||
* --argstr name value
|
end = "100MiB";
|
||||||
pass value to nix-build as string
|
bootable = true;
|
||||||
* --root-mountpoint /mnt
|
content = {
|
||||||
where to mount the device tree
|
type = "filesystem";
|
||||||
* --dry-run
|
format = "vfat";
|
||||||
just show the path to the script instead of running it
|
mountpoint = "/boot";
|
||||||
* --debug
|
};
|
||||||
run with set -x
|
}
|
||||||
|
{
|
||||||
```
|
name = "root";
|
||||||
|
type = "partition";
|
||||||
|
start = "100MiB";
|
||||||
|
end = "100%";
|
||||||
## Installing NixOS module
|
part-type = "primary";
|
||||||
|
bootable = true;
|
||||||
You can use the NixOS module in one of the following ways:
|
content = {
|
||||||
|
type = "filesystem";
|
||||||
<details>
|
format = "ext4";
|
||||||
<summary>Flakes (Current recommendation)</summary>
|
mountpoint = "/";
|
||||||
|
};
|
||||||
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:
|
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
|
$ sudo nix run github:nix-community/disko -- --mode zap_create_mount /tmp/disko-config.nix --arg disks '[ "/dev/nvme0n1" ]'
|
||||||
{
|
|
||||||
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
|
## Related Tools
|
||||||
|
|
||||||
```nix
|
This tool is used by [nixos-anywhere](https://github.com/numtide/nixos-anywhere), which carries out a fully-automated remote install of NixOS.
|
||||||
{
|
|
||||||
# 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.
|
We also acknowledge https://github.com/NixOS/nixpart, the conceptual ancestor of this project.
|
||||||
|
|
||||||
If you are on an installer, you probably want to disable `enableConfig`.
|
## Licensing and Contribution details
|
||||||
|
|
||||||
disko will create the scripts `disko-create` and `disko-mount` which can be used to create/mount the configured disk layout.
|
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/). 
|
||||||
|
|
||||||
|
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.
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user