nixpkgs/nixos/doc/manual/configuration/file-systems.chapter.md
pennae 1229e735ac nixos-render-docs: add structural includes, use for manual
this adds support for structural includes to nixos-render-docs.
structural includes provide a way to denote the (sub)structure of the
nixos manual in the markdown source files, very similar to how we used
literal docbook blocks before, and are processed by nixos-render-docs
without involvement of xml tooling. this will ultimately allow us to
emit the nixos manual in other formats as well, e.g. html, without going
through docbook at all.

alternatives to this source layout were also considered:

a parallel structure using e.g. toml files that describe the document
tree and links to each part is possible, but much more complicated to
implement than the solution chosen here and makes it harder to follow
which files have what substructure. it also makes it much harder to
include a substructure in the middle of a file.

much the same goes for command-line arguments to the converter, only
that command-lined arguments are even harder to specify correctly and
cannot be reasonably pulled together from many places without involving
another layer of tooling. cli arguments would also mean that the manual
structure would be fixed in default.nix, which is also not ideal.
2023-02-12 13:02:42 +01:00

42 lines
1.7 KiB
Markdown

# File Systems {#ch-file-systems}
You can define file systems using the `fileSystems` configuration
option. For instance, the following definition causes NixOS to mount the
Ext4 file system on device `/dev/disk/by-label/data` onto the mount
point `/data`:
```nix
fileSystems."/data" =
{ device = "/dev/disk/by-label/data";
fsType = "ext4";
};
```
This will create an entry in `/etc/fstab`, which will generate a
corresponding [systemd.mount](https://www.freedesktop.org/software/systemd/man/systemd.mount.html)
unit via [systemd-fstab-generator](https://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html).
The filesystem will be mounted automatically unless `"noauto"` is
present in [options](#opt-fileSystems._name_.options). `"noauto"`
filesystems can be mounted explicitly using `systemctl` e.g.
`systemctl start data.mount`. Mount points are created automatically if they don't
already exist. For `device`, it's best to use the topology-independent
device aliases in `/dev/disk/by-label` and `/dev/disk/by-uuid`, as these
don't change if the topology changes (e.g. if a disk is moved to another
IDE controller).
You can usually omit the file system type (`fsType`), since `mount` can
usually detect the type and load the necessary kernel module
automatically. However, if the file system is needed at early boot (in
the initial ramdisk) and is not `ext2`, `ext3` or `ext4`, then it's best
to specify `fsType` to ensure that the kernel module is available.
::: {.note}
System startup will fail if any of the filesystems fails to mount,
dropping you to the emergency shell. You can make a mount asynchronous
and non-critical by adding `options = [ "nofail" ];`.
:::
```{=include=} sections
luks-file-systems.section.md
sshfs-file-systems.section.md
```