doc: explain runtime and indirect roots, merge roots section into GC section

Change-Id: Ib2547c04c938af8fc7346f49616085f514c81749
2025-05-20 12:52:51 +02:00
parent a7634f87aa
commit 498e828efe
3 changed files with 59 additions and 19 deletions
@@ -20,7 +20,6 @@
  - [Basic Package Management](package-management/basic-package-mgmt.md)
  - [Profiles](package-management/profiles.md)
  - [Garbage Collection](package-management/garbage-collection.md)
-    - [Garbage Collector Roots](package-management/garbage-collector-roots.md)
  - [Sharing Packages Between Machines](package-management/sharing-packages.md)
    - [Serving a Nix store via HTTP](package-management/binary-cache-substituter.md)
    - [Copying Closures via SSH](package-management/copy-closure.md)
@@ -71,3 +71,62 @@ $ nix-collect-garbage -d
 ```

 is a quick and easy way to clean up your system.
+
+## Garbage Collector Roots
+
+### Explicit roots
+
+All store paths to which there are symlinks in the directory
+`prefix/nix/var/nix/gcroots` will be used as roots by the garbage
+collector. For instance, the following command makes the path
+`/nix/store/d718ef...-foo` a root of the collector:
+
+```console
+$ ln -s /nix/store/d718ef...-foo /nix/var/nix/gcroots/bar
+```
+
+That is, after this command, the garbage collector will not remove
+`/nix/store/d718ef...-foo` or any of its dependencies.
+
+Subdirectories of `prefix/nix/var/nix/gcroots` are also searched for
+symlinks.
+
+Symlinks may also point to paths outside the nix store. If the
+destination of the symlink is itself a symlink to a store path, it
+is also considered a root. This style of GC root is called an
+"indirect root", and is created by tools like `nix-build` to avoid
+garbage-collecting paths that are being used on-the-fly rather than
+installed in profiles.
+
+
+### In-use roots
+
+Lix will also perform a best-effort detection of paths that are in use
+by running processes when scanning for garbage collection roots, to
+avoid removing paths that are still needed by running processes.
+
+Exact details vary between platforms, but the following will generally
+be taken into account:
+
+- Executables in the store that are currently running;
+- Other files in the store that are mapped into a process's address space (e.g. shared libraries);
+- Files in the store to which processes have open handles;
+- Store paths found in processes' environment variables.
+
+Note that this detection is susceptible to missing paths that may still be in use for multiple reasons:
+
+- Time-of-check-to-time-of-use (TOCTTOU): new processes may appear
+  after Lix has enumerated the currently running processes, and will
+  not be taken into account;
+- Access privileges: if the garbage collection is not running as the
+  root user (this is typically the case for single-user
+  installations), it will not be able to scan processes belonging to
+  other users;
+- Other types of references: store paths may be stored in parts of the
+  filesystem (e.g. databases) or process memory (e.g. environment
+  variables changed since the start of the process) that Lix does not
+  scan.
+
+For this reason, it is recommended to create explicit roots whenever
+using store paths that aren't obtained from some existing explicit GC
+root.
@@ -1,18 +0,0 @@
-# Garbage Collector Roots
-
-The roots of the garbage collector are all store paths to which there
-are symlinks in the directory `prefix/nix/var/nix/gcroots`. For
-instance, the following command makes the path
-`/nix/store/d718ef...-foo` a root of the collector:
-
-```console
-$ ln -s /nix/store/d718ef...-foo /nix/var/nix/gcroots/bar
-```
-
-That is, after this command, the garbage collector will not remove
-`/nix/store/d718ef...-foo` or any of its dependencies.
-
-Subdirectories of `prefix/nix/var/nix/gcroots` are also searched for
-symlinks. Symlinks to non-store paths are followed and searched for
-roots, but symlinks to non-store paths *inside* the paths reached in
-that way are not followed to prevent infinite recursion.