From 498e828efe32ae737f056bdd7cbce51f860090f8 Mon Sep 17 00:00:00 2001 From: Linus Heckemann Date: Tue, 13 May 2025 15:02:19 +0200 Subject: [PATCH] doc: explain runtime and indirect roots, merge roots section into GC section Change-Id: Ib2547c04c938af8fc7346f49616085f514c81749 --- doc/manual/src/SUMMARY.md | 1 - .../package-management/garbage-collection.md | 59 +++++++++++++++++++ .../garbage-collector-roots.md | 18 ------ 3 files changed, 59 insertions(+), 19 deletions(-) delete mode 100644 doc/manual/src/package-management/garbage-collector-roots.md diff --git a/doc/manual/src/SUMMARY.md b/doc/manual/src/SUMMARY.md index 6aa826e65..6a5738f61 100644 --- a/doc/manual/src/SUMMARY.md +++ b/doc/manual/src/SUMMARY.md @@ -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) diff --git a/doc/manual/src/package-management/garbage-collection.md b/doc/manual/src/package-management/garbage-collection.md index 07ca29365..85034037f 100644 --- a/doc/manual/src/package-management/garbage-collection.md +++ b/doc/manual/src/package-management/garbage-collection.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. diff --git a/doc/manual/src/package-management/garbage-collector-roots.md b/doc/manual/src/package-management/garbage-collector-roots.md deleted file mode 100644 index 30c5b7f8d..000000000 --- a/doc/manual/src/package-management/garbage-collector-roots.md +++ /dev/null @@ -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.