Merge staging-next into staging

6 files changed, 506 insertions, 136 deletions

diff --git a/doc/build-helpers/images/dockertools.section.md b/doc/build-helpers/images/dockertools.section.md
index 677b429ba3c0..9317146b8f94 100644
--- a/doc/build-helpers/images/dockertools.section.md
+++ b/doc/build-helpers/images/dockertools.section.md
@@ -1088,238 +1088,482 @@ If you don't specify a `name` attribute, you'll encounter an evaluation error an
 
 ## Environment Helpers {#ssec-pkgs-dockerTools-helpers}
 
-Some packages expect certain files to be available globally.
-When building an image from scratch (i.e. without `fromImage`), these files are missing.
-`pkgs.dockerTools` provides some helpers to set up an environment with the necessary files.
-You can include them in `copyToRoot` like this:
+When building Docker images with Nix, you might also want to add certain files that are expected to be available globally by the software you're packaging.
+Simple examples are the `env` utility in `/usr/bin/env`, or trusted root TLS/SSL certificates.
+Such files will most likely not be included if you're building a Docker image from scratch with Nix, and they might also not be included if you're starting from a Docker image that doesn't include them.
+The helpers in this section are packages that provide some of these commonly-needed global files.
 
-```nix
-buildImage {
-  name = "environment-example";
-  copyToRoot = with pkgs.dockerTools; [
-    usrBinEnv
-    binSh
-    caCertificates
-    fakeNss
-  ];
-}
-```
+Most of these helpers are packages, which means you have to add them to the list of contents to be included in the image (this changes depending on the function you're using to build the image).
+[](#ex-dockerTools-helpers-buildImage) and [](#ex-dockerTools-helpers-buildLayeredImage) show how to include these packages on `dockerTools` functions that build an image.
+For more details on how that works, see the documentation for the function you're using.
 
 ### usrBinEnv {#sssec-pkgs-dockerTools-helpers-usrBinEnv}
 
 This provides the `env` utility at `/usr/bin/env`.
+This is currently implemented by linking to the `env` binary from the `coreutils` package, but is considered an implementation detail that could change in the future.
 
 ### binSh {#sssec-pkgs-dockerTools-helpers-binSh}
 
-This provides `bashInteractive` at `/bin/sh`.
+This provides a `/bin/sh` link to the `bash` binary from the `bashInteractive` package.
+Because of this, it supports cases such as running a command interactively in a container (for example by running `docker run -it <image_name>`).
 
 ### caCertificates {#sssec-pkgs-dockerTools-helpers-caCertificates}
 
-This sets up `/etc/ssl/certs/ca-certificates.crt`.
+This adds trusted root TLS/SSL certificates from the `cacert` package in multiple locations in an attempt to be compatible with binaries built for multiple Linux distributions.
+The locations currently used are:
+
+- `/etc/ssl/certs/ca-bundle.crt`
+- `/etc/ssl/certs/ca-certificates.crt`
+- `/etc/pki/tls/certs/ca-bundle.crt`
 
+[]{#ssec-pkgs-dockerTools-fakeNss}
 ### fakeNss {#sssec-pkgs-dockerTools-helpers-fakeNss}
 
-Provides `/etc/passwd` and `/etc/group` that contain root and nobody.
-Useful when packaging binaries that insist on using nss to look up
-username/groups (like nginx).
+This is a re-export of the `fakeNss` package from Nixpkgs.
+See [](#sec-fakeNss).
 
 ### shadowSetup {#ssec-pkgs-dockerTools-shadowSetup}
 
-This constant string is a helper for setting up the base files for managing users and groups, only if such files don't exist already. It is suitable for being used in a [`buildImage` `runAsRoot`](#ex-dockerTools-buildImage-runAsRoot) script for cases like in the example below:
+This is a string containing a script that sets up files needed for [`shadow`](https://github.com/shadow-maint/shadow) to work (using the `shadow` package from Nixpkgs), and alters `PATH` to make all its utilities available in the same script.
+It is intended to be used with other dockerTools functions in attributes that expect scripts.
+After the script in `shadowSetup` runs, you'll then be able to add more commands that make use of the utilities in `shadow`, such as adding any extra users and/or groups.
+See [](#ex-dockerTools-shadowSetup-buildImage) and [](#ex-dockerTools-shadowSetup-buildLayeredImage) to better understand how to use it.
+
+`shadowSetup` achieves a result similar to [`fakeNss`](#sssec-pkgs-dockerTools-helpers-fakeNss), but only sets up a `root` user with different values for the home directory and the shell to use, in addition to setting up files for [PAM](https://en.wikipedia.org/wiki/Linux_PAM) and a {manpage}`login.defs(5)` file.
+
+:::{.caution}
+Using both `fakeNss` and `shadowSetup` at the same time will either cause your build to break or produce unexpected results.
+Use either `fakeNss` or `shadowSetup` depending on your use case, but avoid using both.
+:::
+
+:::{.note}
+When used with [`buildLayeredImage`](#ssec-pkgs-dockerTools-buildLayeredImage) or [`streamLayeredImage`](#ssec-pkgs-dockerTools-streamLayeredImage), you will have to set the `enableFakechroot` attribute to `true`, or else the script in `shadowSetup` won't run properly.
+See [](#ex-dockerTools-shadowSetup-buildLayeredImage).
+:::
+
+### Examples {#ssec-pkgs-dockerTools-helpers-examples}
+
+:::{.example #ex-dockerTools-helpers-buildImage}
+# Using `dockerTools`'s environment helpers with `buildImage`
+
+This example adds the [`binSh`](#sssec-pkgs-dockerTools-helpers-binSh) helper to a basic Docker image built with [`dockerTools.buildImage`](#ssec-pkgs-dockerTools-buildImage).
+This helper makes it possible to enter a shell inside the container.
+This is the `buildImage` equivalent of [](#ex-dockerTools-helpers-buildLayeredImage).
+
+```nix
+{ dockerTools, hello }:
+dockerTools.buildImage {
+  name = "env-helpers";
+  tag = "latest";
+
+  copyToRoot = [
+    hello
+    dockerTools.binSh
+  ];
+```
+
+After building the image and loading it in Docker, we can create a container based on it and enter a shell inside the container.
+This is made possible by `binSh`.
+
+```shell
+$ nix-build
+(some output removed for clarity)
+/nix/store/2p0i3i04cgjlk71hsn7ll4kxaxxiv4qg-docker-image-env-helpers.tar.gz
+$ docker load -i /nix/store/2p0i3i04cgjlk71hsn7ll4kxaxxiv4qg-docker-image-env-helpers.tar.gz
+(output removed for clarity)
+$ docker run --rm -it env-helpers:latest /bin/sh
+sh-5.2# help
+GNU bash, version 5.2.21(1)-release (x86_64-pc-linux-gnu)
+(rest of output removed for clarity)
+```
+:::
+
+:::{.example #ex-dockerTools-helpers-buildLayeredImage}
+# Using `dockerTools`'s environment helpers with `buildLayeredImage`
+
+This example adds the [`binSh`](#sssec-pkgs-dockerTools-helpers-binSh) helper to a basic Docker image built with [`dockerTools.buildLayeredImage`](#ssec-pkgs-dockerTools-buildLayeredImage).
+This helper makes it possible to enter a shell inside the container.
+This is the `buildLayeredImage` equivalent of [](#ex-dockerTools-helpers-buildImage).
 
 ```nix
-buildImage {
+{ dockerTools, hello }:
+dockerTools.buildLayeredImage {
+  name = "env-helpers";
+  tag = "latest";
+
+  contents = [
+    hello
+    dockerTools.binSh
+  ];
+
+  config = {
+    Cmd = [ "/bin/hello" ];
+  };
+}
+```
+
+After building the image and loading it in Docker, we can create a container based on it and enter a shell inside the container.
+This is made possible by `binSh`.
+
+```shell
+$ nix-build
+(some output removed for clarity)
+/nix/store/rpf47f4z5b9qr4db4ach9yr4b85hjhxq-env-helpers.tar.gz
+$ docker load -i /nix/store/rpf47f4z5b9qr4db4ach9yr4b85hjhxq-env-helpers.tar.gz
+(output removed for clarity)
+$ docker run --rm -it env-helpers:latest /bin/sh
+sh-5.2# help
+GNU bash, version 5.2.21(1)-release (x86_64-pc-linux-gnu)
+(rest of output removed for clarity)
+```
+:::
+
+:::{.example #ex-dockerTools-shadowSetup-buildImage}
+# Using `dockerTools.shadowSetup` with `dockerTools.buildImage`
+
+This is an example that shows how to use `shadowSetup` with `dockerTools.buildImage`.
+Note that the extra script in `runAsRoot` uses `groupadd` and `useradd`, which are binaries provided by the `shadow` package.
+These binaries are added to the `PATH` by the `shadowSetup` script, but only for the duration of `runAsRoot`.
+
+```nix
+{ dockerTools, hello }:
+dockerTools.buildImage {
   name = "shadow-basic";
+  tag = "latest";
+
+  copyToRoot = [ hello ];
 
   runAsRoot = ''
-    #!${pkgs.runtimeShell}
-    ${pkgs.dockerTools.shadowSetup}
-    groupadd -r redis
-    useradd -r -g redis redis
+    ${dockerTools.shadowSetup}
+    groupadd -r hello
+    useradd -r -g hello hello
     mkdir /data
-    chown redis:redis /data
+    chown hello:hello /data
   '';
+
+  config = {
+    Cmd = [ "/bin/hello" ];
+    WorkingDir = "/data";
+  };
 }
 ```
+:::
+
+:::{.example #ex-dockerTools-shadowSetup-buildLayeredImage}
+# Using `dockerTools.shadowSetup` with `dockerTools.buildLayeredImage`
+
+It accomplishes the same thing as [](#ex-dockerTools-shadowSetup-buildImage), but using `buildLayeredImage` instead.
 
-Creating base files like `/etc/passwd` or `/etc/login.defs` is necessary for shadow-utils to manipulate users and groups.
+Note that the extra script in `fakeRootCommands` uses `groupadd` and `useradd`, which are binaries provided by the `shadow` package.
+These binaries are added to the `PATH` by the `shadowSetup` script, but only for the duration of `fakeRootCommands`.
 
-When using `buildLayeredImage`, you can put this in `fakeRootCommands` if you `enableFakechroot`:
 ```nix
-buildLayeredImage {
-  name = "shadow-layered";
+{ dockerTools, hello }:
+dockerTools.buildLayeredImage {
+  name = "shadow-basic";
+  tag = "latest";
+
+  contents = [ hello ];
 
   fakeRootCommands = ''
-    ${pkgs.dockerTools.shadowSetup}
+    ${dockerTools.shadowSetup}
+    groupadd -r hello
+    useradd -r -g hello hello
+    mkdir /data
+    chown hello:hello /data
   '';
   enableFakechroot = true;
+
+  config = {
+    Cmd = [ "/bin/hello" ];
+    WorkingDir = "/data";
+  };
 }
 ```
+:::
 
-## fakeNss {#ssec-pkgs-dockerTools-fakeNss}
+[]{#ssec-pkgs-dockerTools-buildNixShellImage-arguments}
+## buildNixShellImage {#ssec-pkgs-dockerTools-buildNixShellImage}
 
-If your primary goal is providing a basic skeleton for user lookups to work,
-and/or a lesser privileged user, adding `pkgs.fakeNss` to
-the container image root might be the better choice than a custom script
-running `useradd` and friends.
+`buildNixShellImage` uses [`streamNixShellImage`](#ssec-pkgs-dockerTools-streamNixShellImage) underneath to build a compressed Docker-compatible repository tarball of an image that sets up an environment similar to that of running `nix-shell` on a derivation.
+Basically, `buildNixShellImage` runs the script created by `streamNixShellImage` to save the compressed image in the Nix store.
 
-It provides a `/etc/passwd` and `/etc/group`, containing `root` and `nobody`
-users and groups.
+`buildNixShellImage` supports the same options as `streamNixShellImage`, see [`streamNixShellImage`](#ssec-pkgs-dockerTools-streamNixShellImage) for details.
 
-It also provides a `/etc/nsswitch.conf`, configuring NSS host resolution to
-first check `/etc/hosts`, before checking DNS, as the default in the absence of
-a config file (`dns [!UNAVAIL=return] files`) is quite unexpected.
+[]{#ssec-pkgs-dockerTools-buildNixShellImage-example}
+### Examples {#ssec-pkgs-dockerTools-buildNixShellImage-examples}
 
-You can pair it with `binSh`, which provides `bin/sh` as a symlink
-to `bashInteractive` (as `/bin/sh` is configured as a shell).
+:::{.example #ex-dockerTools-buildNixShellImage-hello}
+# Building a Docker image with `buildNixShellImage` with the build environment for the `hello` package
 
-```nix
-buildImage {
-  name = "shadow-basic";
+This example shows how to build the `hello` package inside a Docker container built with `buildNixShellImage`.
+The Docker image generated will have a name like `hello-<version>-env` and tag `latest`.
+This example is the `buildNixShellImage` equivalent of [](#ex-dockerTools-streamNixShellImage-hello).
 
-  copyToRoot = pkgs.buildEnv {
-    name = "image-root";
-    paths = [ binSh pkgs.fakeNss ];
-    pathsToLink = [ "/bin" "/etc" "/var" ];
-  };
+```nix
+{ dockerTools, hello }:
+dockerTools.buildNixShellImage {
+  drv = hello;
+  tag = "latest";
 }
 ```
 
-## buildNixShellImage {#ssec-pkgs-dockerTools-buildNixShellImage}
+The result of building this package is a `.tar.gz` file that can be loaded into Docker:
+
+```shell
+$ nix-build
+(some output removed for clarity)
+/nix/store/pkj1sgzaz31wl0pbvbg3yp5b3kxndqms-hello-2.12.1-env.tar.gz
+
+$ docker load -i /nix/store/pkj1sgzaz31wl0pbvbg3yp5b3kxndqms-hello-2.12.1-env.tar.gz
+(some output removed for clarity)
+Loaded image: hello-2.12.1-env:latest
+```
 
-Create a Docker image that sets up an environment similar to that of running `nix-shell` on a derivation.
-When run in Docker, this environment somewhat resembles the Nix sandbox typically used by `nix-build`, with a major difference being that access to the internet is allowed.
-It additionally also behaves like an interactive `nix-shell`, running things like `shellHook` and setting an interactive prompt.
-If the derivation is fully buildable (i.e. `nix-build` can be used on it), running `buildDerivation` inside such a Docker image will build the derivation, with all its outputs being available in the correct `/nix/store` paths, pointed to by the respective environment variables like `$out`, etc.
+After starting an interactive container, the derivation can be built by running `buildDerivation`, and the output can be executed as expected:
 
-::: {.warning}
-The behavior doesn't match `nix-shell` or `nix-build` exactly and this function is known not to work correctly for e.g. fixed-output derivations, content-addressed derivations, impure derivations and other special types of derivations.
+```shell
+$ docker run -it hello-2.12.1-env:latest
+[nix-shell:~]$ buildDerivation
+Running phase: unpackPhase
+unpacking source archive /nix/store/pa10z4ngm0g83kx9mssrqzz30s84vq7k-hello-2.12.1.tar.gz
+source root is hello-2.12.1
+(some output removed for clarity)
+Running phase: fixupPhase
+shrinking RPATHs of ELF executables and libraries in /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1
+shrinking /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1/bin/hello
+checking for references to /build/ in /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1...
+gzipping man pages under /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1/share/man/
+patching script interpreter paths in /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1
+stripping (with command strip and flags -S -p) in  /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1/bin
+
+[nix-shell:~]$ $out/bin/hello
+Hello, world!
+```
 :::
 
-### Arguments {#ssec-pkgs-dockerTools-buildNixShellImage-arguments}
+## streamNixShellImage {#ssec-pkgs-dockerTools-streamNixShellImage}
+
+`streamNixShellImage` builds a **script** which, when run, will stream to stdout a Docker-compatible repository tarball of an image that sets up an environment similar to that of running `nix-shell` on a derivation.
+This means that `streamNixShellImage` does not output an image into the Nix store, but only a script that builds the image, saving on IO and disk/cache space, particularly with large images.
+See [](#ex-dockerTools-streamNixShellImage-hello) to understand how to load in Docker the image generated by this script.
 
-`drv`
+The environment set up by `streamNixShellImage` somewhat resembles the Nix sandbox typically used by `nix-build`, with a major difference being that access to the internet is allowed.
+It also behaves like an interactive `nix-shell`, running things like `shellHook` (see [](#ex-dockerTools-streamNixShellImage-addingShellHook)) and setting an interactive prompt.
+If the derivation is buildable (i.e. `nix-build` can be used on it), running `buildDerivation` in the container will build the derivation, with all its outputs being available in the correct `/nix/store` paths, pointed to by the respective environment variables (e.g. `$out`).
 
-: The derivation on which to base the Docker image.
+::: {.caution}
+The environment in the image doesn't match `nix-shell` or `nix-build` exactly, and this function is known not to work correctly for fixed-output derivations, content-addressed derivations, impure derivations and other special types of derivations.
+:::
 
-    Adding packages to the Docker image is possible by e.g. extending the list of `nativeBuildInputs` of this derivation like
+### Inputs {#ssec-pkgs-dockerTools-streamNixShellImage-inputs}
 
-    ```nix
-    buildNixShellImage {
-      drv = someDrv.overrideAttrs (old: {
-        nativeBuildInputs = old.nativeBuildInputs or [] ++ [
-          somethingExtra
-        ];
-      });
-      # ...
-    }
-    ```
+`streamNixShellImage` expects one argument with the following attributes:
 
-    Similarly, you can extend the image initialization script by extending `shellHook`
+`drv` (Attribute Set)
 
-`name` _optional_
+: The derivation for which the environment in the image will be set up.
+  Adding packages to the Docker image is possible by extending the list of `nativeBuildInputs` of this derivation.
+  See [](#ex-dockerTools-streamNixShellImage-extendingBuildInputs) for how to do that.
+  Similarly, you can extend the image initialization script by extending `shellHook`.
+  [](#ex-dockerTools-streamNixShellImage-addingShellHook) shows how to do that.
 
-: The name of the resulting image.
+`name` (String; _optional_)
 
-    *Default:* `drv.name + "-env"`
+: The name of the generated image.
 
-`tag` _optional_
+  _Default value:_ the value of `drv.name + "-env"`.
+
+`tag` (String or Null; _optional_)
 
 : Tag of the generated image.
+  If `null`, the hash of the nix derivation that builds the Docker image will be used as the tag.
 
-    *Default:* the resulting image derivation output path's hash
+  _Default value:_ `null`.
+
+`uid` (Number; _optional_)
+
+: The user ID to run the container as.
+  This can be seen as a `nixbld` build user.
+
+  _Default value:_ 1000.
 
-`uid`/`gid` _optional_
+`gid` (Number; _optional_)
 
-: The user/group ID to run the container as. This is like a `nixbld` build user.
+: The group ID to run the container as.
+  This can be seen as a `nixbld` build group.
 
-    *Default:* 1000/1000
+  _Default value:_ 1000.
 
-`homeDirectory` _optional_
+`homeDirectory` (String; _optional_)
 
-: The home directory of the user the container is running as
+: The home directory of the user the container is running as.
 
-    *Default:* `/build`
+  _Default value:_ `/build`.
 
-`shell` _optional_
+`shell` (String; _optional_)
 
-: The path to the `bash` binary to use as the shell. This shell is started when running the image.
+: The path to the `bash` binary to use as the shell.
+  This shell is started when running the image.
+  This can be seen as an equivalent of the `NIX_BUILD_SHELL` [environment variable](https://nixos.org/manual/nix/stable/command-ref/nix-shell.html#environment-variables) for {manpage}`nix-shell(1)`.
 
-    *Default:* `pkgs.bashInteractive + "/bin/bash"`
+  _Default value:_ the `bash` binary from the `bashInteractive` package.
 
-`command` _optional_
+`command` (String or Null; _optional_)
 
-: Run this command in the environment of the derivation, in an interactive shell. See the `--command` option in the [`nix-shell` documentation](https://nixos.org/manual/nix/stable/command-ref/nix-shell.html?highlight=nix-shell#options).
+: If specified, this command will be run in the environment of the derivation in an interactive shell.
+  A call to `exit` will be added after the command if it is specified, so the shell will exit after it's finished running.
+  This can be seen as an equivalent of the `--command` option in {manpage}`nix-shell(1)`.
 
-    *Default:* (none)
+  _Default value:_ `null`.
 
-`run` _optional_
+`run` (String or Null; _optional_)
 
-: Same as `command`, but runs the command in a non-interactive shell instead. See the `--run` option in the [`nix-shell` documentation](https://nixos.org/manual/nix/stable/command-ref/nix-shell.html?highlight=nix-shell#options).
+: Similar to the `command` attribute, but runs the command in a non-interactive shell instead.
+  A call to `exit` will be added after the command if it is specified, so the shell will exit after it's finished running.
+  This can be seen as an equivalent of the `--run` option in {manpage}`nix-shell(1)`.
 
-    *Default:* (none)
+  _Default value:_ `null`.
 
-### Example {#ssec-pkgs-dockerTools-buildNixShellImage-example}
+### Examples {#ssec-pkgs-dockerTools-streamNixShellImage-examples}
 
-The following shows how to build the `pkgs.hello` package inside a Docker container built with `buildNixShellImage`.
+:::{.example #ex-dockerTools-streamNixShellImage-hello}
+# Building a Docker image with `streamNixShellImage` with the build environment for the `hello` package
+
+This example shows how to build the `hello` package inside a Docker container built with `streamNixShellImage`.
+The Docker image generated will have a name like `hello-<version>-env` and tag `latest`.
+This example is the `streamNixShellImage` equivalent of [](#ex-dockerTools-buildNixShellImage-hello).
 
 ```nix
-with import <nixpkgs> {};
-dockerTools.buildNixShellImage {
+{ dockerTools, hello }:
+dockerTools.streamNixShellImage {
   drv = hello;
+  tag = "latest";
 }
 ```
 
-Build the derivation:
+The result of building this package is a script.
+Running this script and piping it into `docker load` gives you the same image that was built in [](#ex-dockerTools-buildNixShellImage-hello).
+
+```shell
+$ nix-build
+(some output removed for clarity)
+/nix/store/8vhznpz2frqazxnd8pgdvf38jscdypax-stream-hello-2.12.1-env
+
+$ /nix/store/8vhznpz2frqazxnd8pgdvf38jscdypax-stream-hello-2.12.1-env | docker load
+(some output removed for clarity)
+Loaded image: hello-2.12.1-env:latest
+```
+
+After starting an interactive container, the derivation can be built by running `buildDerivation`, and the output can be executed as expected:
 
-```console
-nix-build hello.nix
+```shell
+$ docker run -it hello-2.12.1-env:latest
+[nix-shell:~]$ buildDerivation
+Running phase: unpackPhase
+unpacking source archive /nix/store/pa10z4ngm0g83kx9mssrqzz30s84vq7k-hello-2.12.1.tar.gz
+source root is hello-2.12.1
+(some output removed for clarity)
+Running phase: fixupPhase
+shrinking RPATHs of ELF executables and libraries in /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1
+shrinking /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1/bin/hello
+checking for references to /build/ in /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1...
+gzipping man pages under /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1/share/man/
+patching script interpreter paths in /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1
+stripping (with command strip and flags -S -p) in  /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1/bin
+
+[nix-shell:~]$ $out/bin/hello
+Hello, world!
 ```
+:::
 
-    these 8 derivations will be built:
-      /nix/store/xmw3a5ln29rdalavcxk1w3m4zb2n7kk6-nix-shell-rc.drv
-    ...
-    Creating layer 56 from paths: ['/nix/store/crpnj8ssz0va2q0p5ibv9i6k6n52gcya-stdenv-linux']
-    Creating layer 57 with customisation...
-    Adding manifests...
-    Done.
-    /nix/store/cpyn1lc897ghx0rhr2xy49jvyn52bazv-hello-2.12-env.tar.gz
+:::{.example #ex-dockerTools-streamNixShellImage-extendingBuildInputs}
+# Adding extra packages to a Docker image built with `streamNixShellImage`
 
-Load the image:
+This example shows how to add extra packages to an image built with `streamNixShellImage`.
+In this case, we'll add the `cowsay` package.
+The Docker image generated will have a name like `hello-<version>-env` and tag `latest`.
+This example uses [](#ex-dockerTools-streamNixShellImage-hello) as a starting point.
 
-```console
-docker load -i result
+```nix
+{ dockerTools, cowsay, hello }:
+dockerTools.streamNixShellImage {
+  tag = "latest";
+  drv = hello.overrideAttrs (old: {
+    nativeBuildInputs = old.nativeBuildInputs or [] ++ [
+      cowsay
+    ];
+  });
+}
 ```
 
-    0d9f4c4cd109: Loading layer [==================================================>]   2.56MB/2.56MB
-    ...
-    ab1d897c0697: Loading layer [==================================================>]  10.24kB/10.24kB
-    Loaded image: hello-2.12-env:pgj9h98nal555415faa43vsydg161bdz
+The result of building this package is a script which can be run and piped into `docker load` to load the generated image.
 
-Run the container:
+```shell
+$ nix-build
+(some output removed for clarity)
+/nix/store/h5abh0vljgzg381lna922gqknx6yc0v7-stream-hello-2.12.1-env
 
-```console
-docker run -it hello-2.12-env:pgj9h98nal555415faa43vsydg161bdz
+$ /nix/store/h5abh0vljgzg381lna922gqknx6yc0v7-stream-hello-2.12.1-env | docker load
+(some output removed for clarity)
+Loaded image: hello-2.12.1-env:latest
+```
+
+After starting an interactive container, we can verify the extra package is available by running `cowsay`:
+
+```shell
+$ docker run -it hello-2.12.1-env:latest
+[nix-shell:~]$ cowsay "Hello, world!"
+ _______________
+< Hello, world! >
+ ---------------
+        \   ^__^
+         \  (oo)\_______
+            (__)\       )\/\
+                ||----w |
+                ||     ||
 ```
+:::
 
-    [nix-shell:/build]$
+:::{.example #ex-dockerTools-streamNixShellImage-addingShellHook}
+# Adding a `shellHook` to a Docker image built with `streamNixShellImage`
 
-In the running container, run the build:
+This example shows how to add a `shellHook` command to an image built with `streamNixShellImage`.
+In this case, we'll simply output the string `Hello, world!`.
+The Docker image generated will have a name like `hello-<version>-env` and tag `latest`.
+This example uses [](#ex-dockerTools-streamNixShellImage-hello) as a starting point.
 
-```console
-buildDerivation
+```nix
+{ dockerTools, hello }:
+dockerTools.streamNixShellImage {
+  tag = "latest";
+  drv = hello.overrideAttrs (old: {
+    shellHook = ''
+      ${old.shellHook or ""}
+      echo "Hello, world!"
+    '';
+  });
+}
 ```
 
-    unpacking sources
-    unpacking source archive /nix/store/8nqv6kshb3vs5q5bs2k600xpj5bkavkc-hello-2.12.tar.gz
-    ...
-    patching script interpreter paths in /nix/store/z5wwy5nagzy15gag42vv61c2agdpz2f2-hello-2.12
-    checking for references to /build/ in /nix/store/z5wwy5nagzy15gag42vv61c2agdpz2f2-hello-2.12...
+The result of building this package is a script which can be run and piped into `docker load` to load the generated image.
 
-Check the build result:
+```shell
+$ nix-build
+(some output removed for clarity)
+/nix/store/iz4dhdvgzazl5vrgyz719iwjzjy6xlx1-stream-hello-2.12.1-env
 
-```console
-$out/bin/hello
+$ /nix/store/iz4dhdvgzazl5vrgyz719iwjzjy6xlx1-stream-hello-2.12.1-env | docker load
+(some output removed for clarity)
+Loaded image: hello-2.12.1-env:latest
 ```
 
-    Hello, world!
+After starting an interactive container, we can see the result of the `shellHook`:
+
+```shell
+$ docker run -it hello-2.12.1-env:latest
+Hello, world!
+
+[nix-shell:~]$
+```
+:::
diff --git a/doc/build-helpers/special.md b/doc/build-helpers/special.md
index 265c2da92bf1..9da278f094dd 100644
--- a/doc/build-helpers/special.md
+++ b/doc/build-helpers/special.md
@@ -3,6 +3,7 @@
 This chapter describes several special build helpers.
 
 ```{=include=} sections
+special/fakenss.section.md
 special/fhs-environments.section.md
 special/makesetuphook.section.md
 special/mkshell.section.md
diff --git a/doc/build-helpers/special/fakenss.section.md b/doc/build-helpers/special/fakenss.section.md
new file mode 100644
index 000000000000..c890752c0653
--- /dev/null
+++ b/doc/build-helpers/special/fakenss.section.md
@@ -0,0 +1,77 @@
+# fakeNss {#sec-fakeNss}
+
+Provides `/etc/passwd` and `/etc/group` files that contain `root` and `nobody`, allowing user/group lookups to work in binaries that insist on doing those.
+This might be a better choice than a custom script running `useradd` and related utilities if you only need those files to exist with some entries.
+
+`fakeNss` also provides `/etc/nsswitch.conf`, configuring NSS host resolution to first check `/etc/hosts` before checking DNS, since the default in the absence of a config file (`dns [!UNAVAIL=return] files`) is quite unexpected.
+
+It also creates an empty directory at `/var/empty` because it uses that as the home directory for the `root` and `nobody` users.
+The `/var/empty` directory can also be used as a `chroot` target to prevent file access in processes that do not need to access files, if your container runs such processes.
+
+The user entries created by `fakeNss` use the `/bin/sh` shell, which is not provided by `fakeNss` because in most cases it won't be used.
+If you need that to be available, see [`dockerTools.binSh`](#sssec-pkgs-dockerTools-helpers-binSh) or provide your own.
+
+## Inputs {#sec-fakeNss-inputs}
+
+`fakeNss` is made available in Nixpkgs as a package rather than a function, but it has two attributes that can be overridden and might be useful in particular cases.
+For more details on how overriding works, see [](#ex-fakeNss-overriding) and [](#sec-pkg-override).
+
+`extraPasswdLines` (List of Strings; _optional_)
+
+: A list of lines that will be added to `/etc/passwd`.
+  Useful if extra users need to exist in the output of `fakeNss`.
+  If `extraPasswdLines` is specified, it will **not** override the `root` and `nobody` entries created by `fakeNss`.
+  Those entries will always exist.
+
+  Lines specified here must follow the format in {manpage}`passwd(5)`.
+
+  _Default value:_ `[]`.
+
+`extraGroupLines` (List of Strings; _optional_)
+
+: A list of lines that will be added to `/etc/group`.
+  Useful if extra groups need to exist in the output of `fakeNss`.
+  If `extraGroupLines` is specified, it will **not** override the `root` and `nobody` entries created by `fakeNss`.
+  Those entries will always exist.
+
+  Lines specified here must follow the format in {manpage}`group(5)`.
+
+  _Default value:_ `[]`.
+
+## Examples {#sec-fakeNss-examples}
+
+:::{.example #ex-fakeNss-dockerTools-buildImage}
+# Using `fakeNss` with `dockerTools.buildImage`
+
+This example shows how to use `fakeNss` as-is.
+It is useful with functions in `dockerTools` to allow building Docker images that have the `/etc/passwd` and `/etc/group` files.
+This example includes the `hello` binary in the image so it can do something besides just have the extra files.
+
+```nix
+{ dockerTools, fakeNss, hello }:
+dockerTools.buildImage {
+  name = "image-with-passwd";
+  tag = "latest";
+
+  copyToRoot = [ fakeNss hello ];
+
+  config = {
+    Cmd = [ "/bin/hello" ];
+  };
+}
+```
+:::
+
+:::{.example #ex-fakeNss-overriding}
+# Using `fakeNss` with an override to add extra lines
+
+The following code uses `override` to add extra lines to `/etc/passwd` and `/etc/group` to create another user and group entry.
+
+```nix
+{ fakeNss }:
+fakeNss.override {
+  extraPasswdLines = ["newuser:x:9001:9001:new user:/var/empty:/bin/sh"];
+  extraGroupLines = ["newuser:x:9001:"];
+}
+```
+:::
diff --git a/doc/hooks/installShellFiles.section.md b/doc/hooks/installShellFiles.section.md
index 84adea2fa30c..2567098116dd 100644
--- a/doc/hooks/installShellFiles.section.md
+++ b/doc/hooks/installShellFiles.section.md
@@ -2,7 +2,7 @@
 
 This hook helps with installing manpages and shell completion files. It exposes 2 shell functions `installManPage` and `installShellCompletion` that can be used from your `postInstall` hook.
 
-The `installManPage` function takes one or more paths to manpages to install. The manpages must have a section suffix, and may optionally be compressed (with `.gz` suffix). This function will place them into the correct directory.
+The `installManPage` function takes one or more paths to manpages to install. The manpages must have a section suffix, and may optionally be compressed (with `.gz` suffix). This function will place them into the correct `share/man/man<section>/` directory, in [`outputMan`](#outputman).
 
 The `installShellCompletion` function takes one or more paths to shell completion files. By default it will autodetect the shell type from the completion file extension, but you may also specify it by passing one of `--bash`, `--fish`, or `--zsh`. These flags apply to all paths listed after them (up until another shell flag is given). Each path may also have a custom installation name provided by providing a flag `--name NAME` before the path. If this flag is not provided, zsh completions will be renamed automatically such that `foobar.zsh` becomes `_foobar`. A root name may be provided for all paths using the flag `--cmd NAME`; this synthesizes the appropriate name depending on the shell (e.g. `--cmd foo` will synthesize the name `foo.bash` for bash and `_foo` for zsh). The path may also be a fifo or named fd (such as produced by `<(cmd)`), in which case the shell and name must be provided.
 
diff --git a/doc/languages-frameworks/dotnet.section.md b/doc/languages-frameworks/dotnet.section.md
index ac659a9c6d28..7987aa41636c 100644
--- a/doc/languages-frameworks/dotnet.section.md
+++ b/doc/languages-frameworks/dotnet.section.md
@@ -93,7 +93,11 @@ The `dotnetCorePackages.sdk` contains both a runtime and the full sdk of a given
 To package Dotnet applications, you can use `buildDotnetModule`. This has similar arguments to `stdenv.mkDerivation`, with the following additions:
 
 * `projectFile` is used for specifying the dotnet project file, relative to the source root. These have `.sln` (entire solution) or `.csproj` (single project) file extensions. This can be a list of multiple projects as well. When omitted, will attempt to find and build the solution (`.sln`). If running into problems, make sure to set it to a file (or a list of files) with the `.csproj` extension - building applications as entire solutions is not fully supported by the .NET CLI.
-* `nugetDeps` takes either a path to a `deps.nix` file, or a derivation. The `deps.nix` file can be generated using the script attached to `passthru.fetch-deps`. This file can also be generated manually using `nuget-to-nix` tool, which is available in nixpkgs. If the argument is a derivation, it will be used directly and assume it has the same output as `mkNugetDeps`.
+* `nugetDeps` takes either a path to a `deps.nix` file, or a derivation. The `deps.nix` file can be generated using the script attached to `passthru.fetch-deps`. If the argument is a derivation, it will be used directly and assume it has the same output as `mkNugetDeps`.
+::: {.note}
+For more detail about managing the `deps.nix` file, see [Generating and updating NuGet dependencies](#generating-and-updating-nuget-dependencies)
+:::
+
 * `packNupkg` is used to pack project as a `nupkg`, and installs it to `$out/share`. If set to `true`, the derivation can be used as a dependency for another dotnet project by adding it to `projectReferences`.
 * `projectReferences` can be used to resolve `ProjectReference` project items. Referenced projects can be packed with `buildDotnetModule` by setting the `packNupkg = true` attribute and passing a list of derivations to `projectReferences`. Since we are sharing referenced projects as NuGets they must be added to csproj/fsproj files as `PackageReference` as well.
  For example, your project has a local dependency:
@@ -156,6 +160,8 @@ in buildDotnetModule rec {
 }
 ```
 
+Keep in mind that you can tag the [`@NixOS/dotnet`](https://github.com/orgs/nixos/teams/dotnet) team for help and code review.
+
 ## Dotnet global tools {#dotnet-global-tools}
 
 [.NET Global tools](https://learn.microsoft.com/en-us/dotnet/core/tools/global-tools) are a mechanism provided by the dotnet CLI to install .NET binaries from Nuget packages.
@@ -212,5 +218,43 @@ buildDotnetGlobalTool {
   };
 }
 ```
+## Generating and updating NuGet dependencies {#generating-and-updating-nuget-dependencies}
+
+First, restore the packages to the `out` directory, ensure you have cloned
+the upstream repository and you are inside it.
+
+```bash
+$ dotnet restore --packages out
+  Determining projects to restore...
+  Restored /home/lychee/Celeste64/Celeste64.csproj (in 1.21 sec).
+```
+
+Next, use `nuget-to-nix` tool provided in nixpkgs to generate a lockfile to `deps.nix` from
+the packages inside the `out` directory.
+
+```bash
+$ nuget-to-nix out > deps.nix
+```
+Which `nuget-to-nix` will generate an output similar to below
+```
+{ fetchNuGet }: [
+  (fetchNuGet { pname = "FosterFramework"; version = "0.1.15-alpha"; sha256 = "0pzsdfbsfx28xfqljcwy100xhbs6wyx0z1d5qxgmv3l60di9xkll"; })
+  (fetchNuGet { pname = "Microsoft.AspNetCore.App.Runtime.linux-x64"; version = "8.0.1"; sha256 = "1gjz379y61ag9whi78qxx09bwkwcznkx2mzypgycibxk61g11da1"; })
+  (fetchNuGet { pname = "Microsoft.NET.ILLink.Tasks"; version = "8.0.1"; sha256 = "1drbgqdcvbpisjn8mqfgba1pwb6yri80qc4mfvyczqwrcsj5k2ja"; })
+  (fetchNuGet { pname = "Microsoft.NETCore.App.Runtime.linux-x64"; version = "8.0.1"; sha256 = "1g5b30f4l8a1zjjr3b8pk9mcqxkxqwa86362f84646xaj4iw3a4d"; })
+  (fetchNuGet { pname = "SharpGLTF.Core"; version = "1.0.0-alpha0031"; sha256 = "0ln78mkhbcxqvwnf944hbgg24vbsva2jpih6q3x82d3h7rl1pkh6"; })
+  (fetchNuGet { pname = "SharpGLTF.Runtime"; version = "1.0.0-alpha0031"; sha256 = "0lvb3asi3v0n718qf9y367km7qpkb9wci38y880nqvifpzllw0jg"; })
+  (fetchNuGet { pname = "Sledge.Formats"; version = "1.2.2"; sha256 = "1y0l66m9rym0p1y4ifjlmg3j9lsmhkvbh38frh40rpvf1axn2dyh"; })
+  (fetchNuGet { pname = "Sledge.Formats.Map"; version = "1.1.5"; sha256 = "1bww60hv9xcyxpvkzz5q3ybafdxxkw6knhv97phvpkw84pd0jil6"; })
+  (fetchNuGet { pname = "System.Numerics.Vectors"; version = "4.5.0"; sha256 = "1kzrj37yzawf1b19jq0253rcs8hsq1l2q8g69d7ipnhzb0h97m59"; })
+]
+```
+
+Finally, you move the `deps.nix` file to the appropriate location to be used by `nugetDeps`, then you're all set!
+
+If you ever need to update the dependencies of a package, you instead do
+
+* `nix-build -A package.fetch-deps` to generate the update script for `package`
+* Run `./result deps.nix` to regenerate the lockfile to `deps.nix`, keep in mind if a location isn't provided, it will write to a temporary path instead
+* Finally, move the file where needed and look at its contents to confirm it has updated the dependencies.
 
-When packaging a new .NET application in nixpkgs, you can tag the [`@NixOS/dotnet`](https://github.com/orgs/nixos/teams/dotnet) team for help and code review.
diff --git a/doc/manpage-urls.json b/doc/manpage-urls.json
index d0fafa379a9f..5739a59d9420 100644
--- a/doc/manpage-urls.json
+++ b/doc/manpage-urls.json
@@ -314,5 +314,9 @@
   "systemd-veritysetup@.service(8)": "https://www.freedesktop.org/software/systemd/man/systemd-veritysetup@.service.html",
   "systemd-volatile-root(8)": "https://www.freedesktop.org/software/systemd/man/systemd-volatile-root.html",
   "systemd-xdg-autostart-generator(8)": "https://www.freedesktop.org/software/systemd/man/systemd-xdg-autostart-generator.html",
-  "udevadm(8)": "https://www.freedesktop.org/software/systemd/man/udevadm.html"
+  "udevadm(8)": "https://www.freedesktop.org/software/systemd/man/udevadm.html",
+  "passwd(5)": "https://man.archlinux.org/man/passwd.5",
+  "group(5)": "https://man.archlinux.org/man/group.5",
+  "login.defs(5)": "https://man.archlinux.org/man/login.defs.5",
+  "nix-shell(1)": "https://nixos.org/manual/nix/stable/command-ref/nix-shell.html"
 }