From 3368852e7f4a906e6def25895319a3419f56c4d4 Mon Sep 17 00:00:00 2001
From: Tom Fitzhenry <tom@tom-fitzhenry.me.uk>
Date: Sun, 12 Apr 2026 03:06:11 +0000
Subject: [PATCH] doc: add NFS file systems documentation

Add a new section to the NixOS manual documenting how to mount NFS.

fixes https://github.com/NixOS/nixpkgs/issues/76671
---
 .../configuration/file-systems.chapter.md     |  1 +
 .../configuration/nfs-file-systems.section.md | 52 +++++++++++++++++++
 nixos/doc/manual/redirects.json               |  9 ++++
 3 files changed, 62 insertions(+)
 create mode 100644 nixos/doc/manual/configuration/nfs-file-systems.section.md

diff --git a/nixos/doc/manual/configuration/file-systems.chapter.md b/nixos/doc/manual/configuration/file-systems.chapter.md
index 8a63a2b849cd..8b6a06c5720a 100644
--- a/nixos/doc/manual/configuration/file-systems.chapter.md
+++ b/nixos/doc/manual/configuration/file-systems.chapter.md
@@ -41,5 +41,6 @@ and non-critical by adding `options = [ "nofail" ];`.
 ```{=include=} sections
 luks-file-systems.section.md
 sshfs-file-systems.section.md
+nfs-file-systems.section.md
 overlayfs.section.md
 ```
diff --git a/nixos/doc/manual/configuration/nfs-file-systems.section.md b/nixos/doc/manual/configuration/nfs-file-systems.section.md
new file mode 100644
index 000000000000..3ac6792e0167
--- /dev/null
+++ b/nixos/doc/manual/configuration/nfs-file-systems.section.md
@@ -0,0 +1,52 @@
+# NFS File Systems {#sec-nfs-file-systems}
+
+[NFS][nfs] (Network File System) allows you to mount directories from remote machines over the network.
+
+[nfs]: https://en.wikipedia.org/wiki/Network_File_System
+[nfs-man]: https://man7.org/linux/man-pages/man5/nfs.5.html
+
+To mount NFS filesystems persistently, use the `fileSystems` option:
+
+```nix
+{
+  fileSystems."/mnt/data" = {
+    device = "server.example.com:/export/data";
+    fsType = "nfs";
+  };
+}
+```
+
+## Automounting {#sec-nfs-automount}
+
+To have NFS filesystems mounted on-demand instead of at boot, add the `noauto` and `x-systemd.automount` options:
+
+```nix
+{
+  fileSystems."/mnt/data" = {
+    device = "server.example.com:/export/data";
+    fsType = "nfs";
+    options = [
+      "noauto"
+      "x-systemd.automount"
+    ];
+  };
+}
+```
+
+## Ad-hoc Mounting {#sec-nfs-adhoc}
+
+To mount NFS filesystems ad-hoc using the `mount` command, enable NFS and required RPC services:
+
+```nix
+{
+  boot.supportedFilesystems = [ "nfs" ];
+}
+```
+
+Then you can mount filesystems manually:
+
+```shell
+$ sudo mount -t nfs server.example.com:/export/data /mnt/data
+```
+
+For more information on NFS mount options, see the [nfs(5) man page][nfs-man].
diff --git a/nixos/doc/manual/redirects.json b/nixos/doc/manual/redirects.json
index f767735f9e37..12cfdd1d9063 100644
--- a/nixos/doc/manual/redirects.json
+++ b/nixos/doc/manual/redirects.json
@@ -619,6 +619,15 @@
   "sec-luks-file-systems-fido2-systemd": [
     "index.html#sec-luks-file-systems-fido2-systemd"
   ],
+  "sec-nfs-file-systems": [
+    "index.html#sec-nfs-file-systems"
+  ],
+  "sec-nfs-automount": [
+    "index.html#sec-nfs-automount"
+  ],
+  "sec-nfs-adhoc": [
+    "index.html#sec-nfs-adhoc"
+  ],
   "sec-sshfs-file-systems": [
     "index.html#sec-sshfs-file-systems"
   ],