From 0ea62670eda39ebeaff5335fd8225707ec27e7a3 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Thu, 1 Dec 2022 04:40:02 +0100 Subject: [PATCH 1/2] move documentation on `auto-allocate-uids` to options docs this is where it belongs and can be found together with the other options. --- doc/manual/src/release-notes/rl-next.md | 42 +++++++++++-------------- src/libstore/globals.hh | 36 +++++++++++++++++---- 2 files changed, 48 insertions(+), 30 deletions(-) diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md index 8b314b5f6..bf51aa1f7 100644 --- a/doc/manual/src/release-notes/rl-next.md +++ b/doc/manual/src/release-notes/rl-next.md @@ -12,43 +12,37 @@ ([#7260](https://github.com/NixOS/nix/pull/7260)). * Nix can now automatically pick UIDs for builds, removing the need to - create `nixbld*` user accounts. These UIDs are allocated starting at - 872415232 (0x34000000) on Linux and 56930 on macOS. + create `nixbld*` user accounts. - This is an experimental feature. To enable it, add the following to - `nix.conf`: + See [`auto-allocate-uids`]. - ``` - extra-experimental-features = auto-allocate-uids - auto-allocate-uids = true - ``` + [`auto-allocate-uids`]: (../command-ref/conf-file.md#conf-auto-allocate-uids) * On Linux, Nix can now run builds in a user namespace where the build - runs as root (UID 0) and has 65,536 UIDs available. This is - primarily useful for running containers such as `systemd-nspawn` - inside a Nix build. For an example, see - https://github.com/NixOS/nix/blob/67bcb99700a0da1395fa063d7c6586740b304598/tests/systemd-nspawn.nix. + runs as root (UID 0) and has 65,536 UIDs available. - A build can enable this by requiring the `uid-range` system feature, - i.e. by setting the derivation attribute + + + This is primarily useful for running containers such as `systemd-nspawn` + inside a Nix build. For an example, see [`tests/systemd-nspawn/nix`][nspawn]. + + [nspawn]: https://github.com/NixOS/nix/blob/67bcb99700a0da1395fa063d7c6586740b304598/tests/systemd-nspawn.nix. + + A build can enable this by by setting the derivation attribute: ``` requiredSystemFeatures = [ "uid-range" ]; ``` - The `uid-range` system feature requires the `auto-allocate-uids` - setting to be enabled (see above). + The `uid-range` [system feature] requires the [`auto-allocate-uids`] + setting to be enabled. + + [system feature]: (../command-ref/conf-file.md#conf-system-features), * On Linux, Nix has experimental support for running builds inside a - cgroup. It can be enabled by adding + cgroup. - ``` - extra-experimental-features = cgroups - use-cgroups = true - ``` - - to `nix.conf`. Cgroups are required for derivations that require the - `uid-range` system feature. + See [`use-cgroups`](../command-ref/conf-file.md#conf-use-cgroups). * `nix build --json` now prints some statistics about top-level derivations, such as CPU statistics when cgroups are enabled. diff --git a/src/libstore/globals.hh b/src/libstore/globals.hh index b40dcfa77..b61a34461 100644 --- a/src/libstore/globals.hh +++ b/src/libstore/globals.hh @@ -284,7 +284,21 @@ public: )"}; Setting autoAllocateUids{this, false, "auto-allocate-uids", - "Whether to allocate UIDs for builders automatically."}; + R"( + Whether to allocate UIDs for builders automatically. + + These UIDs are allocated starting at 872415232 (0x34000000) on Linux and 56930 on macOS. + + > **Warning** + > This is an experimental feature. + + To enable it, add the following to [`nix.conf`](#): + + ``` + extra-experimental-features = auto-allocate-uids + auto-allocate-uids = true + ``` + )"}; Setting startId{this, #if __linux__ @@ -308,11 +322,21 @@ public: Setting useCgroups{ this, false, "use-cgroups", R"( - Whether to execute builds inside cgroups. Cgroups are - enabled automatically for derivations that require the - `uid-range` system feature. - )" - }; + Whether to execute builds inside cgroups. + Only on Linux with systemd. + + cgroups are required and enabled automatically for derivations that require the `uid-range` system feature. + + > **Warning** + > This is an experimental feature. + + To enable it, add the following to [`nix.conf`](#): + + ``` + extra-experimental-features = cgroups + use-cgroups = true + ``` + )"}; #endif Setting impersonateLinux26{this, false, "impersonate-linux-26", From 484578d3f9b15c34c0e3a42cc0d1f87f1c15d7f6 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Tue, 6 Dec 2022 10:30:36 +0100 Subject: [PATCH 2/2] Tweak option descriptions --- src/libstore/globals.hh | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/src/libstore/globals.hh b/src/libstore/globals.hh index b61a34461..ca72ad31e 100644 --- a/src/libstore/globals.hh +++ b/src/libstore/globals.hh @@ -285,9 +285,10 @@ public: Setting autoAllocateUids{this, false, "auto-allocate-uids", R"( - Whether to allocate UIDs for builders automatically. + Whether to select UIDs for builds automatically, instead of using the + users in `build-users-group`. - These UIDs are allocated starting at 872415232 (0x34000000) on Linux and 56930 on macOS. + UIDs are allocated starting at 872415232 (0x34000000) on Linux and 56930 on macOS. > **Warning** > This is an experimental feature. @@ -323,9 +324,10 @@ public: this, false, "use-cgroups", R"( Whether to execute builds inside cgroups. - Only on Linux with systemd. + This is only supported on Linux. - cgroups are required and enabled automatically for derivations that require the `uid-range` system feature. + Cgroups are required and enabled automatically for derivations + that require the `uid-range` system feature. > **Warning** > This is an experimental feature.