Merge branch 'nixos-unstable-small' of https://github.com/NixOS/nixpkgs

5 files changed, 260 insertions, 78 deletions

diff --git a/nixpkgs/doc/build-helpers/images/dockertools.section.md b/nixpkgs/doc/build-helpers/images/dockertools.section.md
index a1d1f2cb2012..001d5695290e 100644
--- a/nixpkgs/doc/build-helpers/images/dockertools.section.md
+++ b/nixpkgs/doc/build-helpers/images/dockertools.section.md
@@ -507,6 +507,16 @@ This allows the function to produce reproducible images.
 
   _Default value:_ `"1970-01-01T00:00:01Z"`.
 
+`uid` (Number; _optional_) []{#dockerTools-buildLayeredImage-arg-uid}
+`gid` (Number; _optional_) []{#dockerTools-buildLayeredImage-arg-gid}
+`uname` (String; _optional_) []{#dockerTools-buildLayeredImage-arg-uname}
+`gname` (String; _optional_) []{#dockerTools-buildLayeredImage-arg-gname}
+
+: Credentials for Nix store ownership.
+  Can be overridden to e.g. `1000` / `1000` / `"user"` / `"user"` to enable building a container where Nix can be used as an unprivileged user in single-user mode.
+
+  _Default value:_ `0` / `0` / `"root"` / `"root"`
+
 `maxLayers` (Number; _optional_) []{#dockerTools-buildLayeredImage-arg-maxLayers}
 
 : The maximum number of layers that will be used by the generated image.
diff --git a/nixpkgs/doc/build-helpers/images/ocitools.section.md b/nixpkgs/doc/build-helpers/images/ocitools.section.md
index c35f65bce007..96627615ffb5 100644
--- a/nixpkgs/doc/build-helpers/images/ocitools.section.md
+++ b/nixpkgs/doc/build-helpers/images/ocitools.section.md
@@ -1,37 +1,104 @@
 # pkgs.ociTools {#sec-pkgs-ociTools}
 
-`pkgs.ociTools` is a set of functions for creating containers according to the [OCI container specification v1.0.0](https://github.com/opencontainers/runtime-spec). Beyond that, it makes no assumptions about the container runner you choose to use to run the created container.
+`pkgs.ociTools` is a set of functions for creating runtime container bundles according to the [OCI runtime specification v1.0.0](https://github.com/opencontainers/runtime-spec/blob/v1.0.0/spec.md).
+It makes no assumptions about the container runner you choose to use to run the created container.
+
+The set of functions in `pkgs.ociTools` currently does not handle the [OCI image specification](https://github.com/opencontainers/image-spec).
+
+At a high-level an OCI implementation would download an OCI Image then unpack that image into an OCI Runtime filesystem bundle.
+At this point the OCI Runtime Bundle would be run by an OCI Runtime.
+`pkgs.ociTools` provides utilities to create OCI Runtime bundles.
 
 ## buildContainer {#ssec-pkgs-ociTools-buildContainer}
 
-This function creates a simple OCI container that runs a single command inside of it. An OCI container consists of a `config.json` and a rootfs directory. The nix store of the container will contain all referenced dependencies of the given command.
+This function creates an OCI runtime container (consisting of a `config.json` and a root filesystem directory) that runs a single command inside of it.
+The nix store of the container will contain all referenced dependencies of the given command.
+
+This function has an assumption that the container will run on POSIX platforms, and sets configurations (such as the user running the process or certain mounts) according to this assumption.
+Because of this, a container built with `buildContainer` will not work on Windows or other non-POSIX platforms without modifications to the container configuration.
+These modifications aren't supported by `buildContainer`.
+
+For `linux` platforms, `buildContainer` also configures the following namespaces (see {manpage}`unshare(1)`) to isolate the OCI container from the global namespace:
+PID, network, mount, IPC, and UTS.
+
+Note that no user namespace is created, which means that you won't be able to run the container unless you are the `root` user.
+
+### Inputs {#ssec-pkgs-ociTools-buildContainer-inputs}
+
+`buildContainer` expects an argument with the following attributes:
+
+`args` (List of String)
+
+: Specifies a set of arguments to run inside the container.
+  Any packages referenced by `args` will be made available inside the container.
+
+`mounts` (Attribute Set; _optional_)
+
+: Would specify additional mounts that the runtime must make available to the container.
+
+  :::{.warning}
+  As explained in [issue #290879](https://github.com/NixOS/nixpkgs/issues/290879), this attribute is currently ignored.
+  :::
+
+  :::{.note}
+  `buildContainer` includes a minimal set of necessary filesystems to be mounted into the container, and this set can't be changed with the `mounts` attribute.
+  :::
+
+  _Default value:_ `{}`.
 
-The parameters of `buildContainer` with an example value are described below:
+`readonly` (Boolean; _optional_)
+
+: If `true`, sets the container's root filesystem as read-only.
+
+  _Default value:_ `false`.
+
+`os` **DEPRECATED**
+
+: Specifies the operating system on which the container filesystem is based on.
+  If specified, its value should follow the [OCI Image Configuration Specification](https://github.com/opencontainers/image-spec/blob/main/config.md#properties).
+  According to the linked specification, all possible values for `$GOOS` in [the Go docs](https://go.dev/doc/install/source#environment) should be valid, but will commonly be one of `darwin` or `linux`.
+
+  _Default value:_ `"linux"`.
+
+`arch` **DEPRECATED**
+
+: Used to specify the architecture for which the binaries in the container filesystem have been compiled.
+  If specified, its value should follow the [OCI Image Configuration Specification](https://github.com/opencontainers/image-spec/blob/main/config.md#properties).
+  According to the linked specification, all possible values for `$GOARCH` in [the Go docs](https://go.dev/doc/install/source#environment) should be valid, but will commonly be one of `386`, `amd64`, `arm`, or `arm64`.
+
+  _Default value:_ `x86_64`.
+
+### Examples {#ssec-pkgs-ociTools-buildContainer-examples}
+
+::: {.example #ex-ociTools-buildContainer-bash}
+# Creating an OCI runtime container that runs `bash`
+
+This example uses `ociTools.buildContainer` to create a simple container that runs `bash`.
 
 ```nix
-buildContainer {
+{ ociTools, lib, bash }:
+ociTools.buildContainer {
   args = [
-    (with pkgs;
-      writeScript "run.sh" ''
-        #!${bash}/bin/bash
-        exec ${bash}/bin/bash
-      '').outPath
+    (lib.getExe bash)
   ];
 
-  mounts = {
-    "/data" = {
-      type = "none";
-      source = "/var/lib/mydata";
-      options = [ "bind" ];
-    };
-  };
-
   readonly = false;
 }
 ```
 
-- `args` specifies a set of arguments to run inside the container. This is the only required argument for `buildContainer`. All referenced packages inside the derivation will be made available inside the container.
+As an example of how to run the container generated by this package, we'll use `runc` to start the container.
+Any other tool that supports OCI containers could be used instead.
 
-- `mounts` specifies additional mount points chosen by the user. By default only a minimal set of necessary filesystems are mounted into the container (e.g procfs, cgroupfs)
+```shell
+$ nix-build
+(some output removed for clarity)
+/nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join
 
-- `readonly` makes the container's rootfs read-only if it is set to true. The default value is false `false`.
+$ cd /nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join
+$ nix-shell -p runc
+[nix-shell:/nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join]$ sudo runc run ocitools-example
+help
+GNU bash, version 5.2.26(1)-release (x86_64-pc-linux-gnu)
+(some output removed for clarity)
+```
+:::
diff --git a/nixpkgs/doc/build-helpers/images/portableservice.section.md b/nixpkgs/doc/build-helpers/images/portableservice.section.md
index 5400928b158f..c271bc775dba 100644
--- a/nixpkgs/doc/build-helpers/images/portableservice.section.md
+++ b/nixpkgs/doc/build-helpers/images/portableservice.section.md
@@ -1,81 +1,174 @@
 # pkgs.portableService {#sec-pkgs-portableService}
 
-`pkgs.portableService` is a function to create _portable service images_,
-as read-only, immutable, `squashfs` archives.
+`pkgs.portableService` is a function to create [Portable Services](https://systemd.io/PORTABLE_SERVICES/) in a read-only, immutable, `squashfs` raw disk image.
+This lets you use Nix to build images which can be run on many recent Linux distributions.
 
-systemd supports a concept of [Portable Services](https://systemd.io/PORTABLE_SERVICES/).
-Portable Services are a delivery method for system services that uses two specific features of container management:
+::: {.note}
+Portable services are supported starting with systemd 239 (released on 2018-06-22).
+:::
 
-* Applications are bundled. I.e. multiple services, their binaries and
-  all their dependencies are packaged in an image, and are run directly from it.
-* Stricter default security policies, i.e. sandboxing of applications.
+The generated image will contain the file system structure as required by the Portable Services specification, along with the packages given to `portableService` and all of their dependencies.
+When generated, the image will exist in the Nix store with the `.raw` file extension, as required by the specification.
+See [](#ex-portableService-hello) to understand how to use the output of `portableService`.
 
-This allows using Nix to build images which can be run on many recent Linux distributions.
+## Inputs {#ssec-pkgs-portableService-inputs}
 
-The primary tool for interacting with Portable Services is `portablectl`,
-and they are managed by the `systemd-portabled` system service.
+`portableService` expects one argument with the following attributes:
 
-::: {.note}
-Portable services are supported starting with systemd 239 (released on 2018-06-22).
-:::
+`pname` (String)
+
+: The name of the portable service.
+  The generated image will be named according to the template `$pname_$version.raw`, which is supported by the Portable Services specification.
+
+`version` (String)
+
+: The version of the portable service.
+  The generated image will be named according to the template `$pname_$version.raw`, which is supported by the Portable Services specification.
+
+`units` (List of Attribute Set)
+
+: A list of derivations for systemd unit files.
+  Each derivation must produce a single file, and must have a name that starts with the value of `pname` and ends with the suffix of the unit type (e.g. ".service", ".socket", ".timer", and so on).
+  See [](#ex-portableService-hello) to better understand this naming constraint.
+
+`description` (String or Null; _optional_)
+
+: If specified, the value is added as `PORTABLE_PRETTY_NAME` to the `/etc/os-release` file in the generated image.
+  This could be used to provide more information to anyone inspecting the image.
+
+  _Default value:_ `null`.
+
+`homepage` (String or Null; _optional_)
+
+: If specified, the value is added as `HOME_URL` to the `/etc/os-release` file in the generated image.
+  This could be used to provide more information to anyone inspecting the image.
+
+  _Default value:_ `null`.
+
+`symlinks` (List of Attribute Set; _optional_)
+
+: A list of attribute sets in the format `{object, symlink}`.
+  For each item in the list, `portableService` will create a symlink in the path specified by `symlink` (relative to the root of the image) that points to `object`.
+
+  All packages that `object` depends on and their dependencies are automatically copied into the image.
+
+  This can be used to create symlinks for applications that assume some files to exist globally (`/etc/ssl` or `/bin/bash`, for example).
+  See [](#ex-portableService-symlinks) to understand how to do that.
+
+  _Default value:_ `[]`.
+
+`contents` (List of Attribute Set; _optional_)
 
-A very simple example of using `portableService` is described below:
+: A list of additional derivations to be included as-is in the image.
+  These derivations will be included directly in a `/nix/store` directory inside the image.
+
+  _Default value:_ `[]`.
+
+`squashfsTools` (Attribute Set; _optional_)
+
+: Allows you to override the package that provides {manpage}`mksquashfs(1)`, which is used internally by `portableService`.
+
+  _Default value:_ `pkgs.squashfsTools`.
+
+`squash-compression` (String; _optional_)
+
+: Passed as the compression option to {manpage}`mksquashfs(1)`, which is used internally by `portableService`.
+
+  _Default value:_ `"xz -Xdict-size 100%"`.
+
+`squash-block-size` (String; _optional_)
+
+: Passed as the block size option to {manpage}`mksquashfs(1)`, which is used internally by `portableService`.
+
+  _Default value:_ `"1M"`.
+
+## Examples {#ssec-pkgs-portableService-examples}
 
 []{#ex-pkgs-portableService}
+:::{.example #ex-portableService-hello}
+# Building a Portable Service image
+
+The following example builds a Portable Service image with the `hello` package, along with a service unit that runs it.
 
 ```nix
-pkgs.portableService {
-  pname = "demo";
-  version = "1.0";
-  units = [ demo-service demo-socket ];
+{ lib, writeText, portableService, hello }:
+let
+  hello-service = writeText "hello.service" ''
+    [Unit]
+    Description=Hello world service
+
+    [Service]
+    Type=oneshot
+    ExecStart=${lib.getExe hello}
+  '';
+in
+portableService {
+  pname = "hello";
+  inherit (hello) version;
+  units = [ hello-service ];
 }
 ```
 
-The above example will build an squashfs archive image in `result/$pname_$version.raw`. The image will contain the
-file system structure as required by the portable service specification, and a subset of the Nix store with all the
-dependencies of the two derivations in the `units` list.
-`units` must be a list of derivations, and their names must be prefixed with the service name (`"demo"` in this case).
-Otherwise `systemd-portabled` will ignore them.
-
-::: {.note}
-The `.raw` file extension of the image is required by the portable services specification.
+After building the package, the generated image can be loaded into a system through {manpage}`portablectl(1)`:
+
+```shell
+$ nix-build
+(some output removed for clarity)
+/nix/store/8c20z1vh7z8w8dwagl8w87b45dn5k6iq-hello-img-2.12.1
+
+$ portablectl attach /nix/store/8c20z1vh7z8w8dwagl8w87b45dn5k6iq-hello-img-2.12.1/hello_2.12.1.raw
+Created directory /etc/systemd/system.attached.
+Created directory /etc/systemd/system.attached/hello.service.d.
+Written /etc/systemd/system.attached/hello.service.d/20-portable.conf.
+Created symlink /etc/systemd/system.attached/hello.service.d/10-profile.conf → /usr/lib/systemd/portable/profile/default/service.conf.
+Copied /etc/systemd/system.attached/hello.service.
+Created symlink /etc/portables/hello_2.12.1.raw → /nix/store/8c20z1vh7z8w8dwagl8w87b45dn5k6iq-hello-img-2.12.1/hello_2.12.1.raw.
+
+$ systemctl start hello
+$ journalctl -u hello
+Feb 28 22:39:16 hostname systemd[1]: Starting Hello world service...
+Feb 28 22:39:16 hostname hello[102887]: Hello, world!
+Feb 28 22:39:16 hostname systemd[1]: hello.service: Deactivated successfully.
+Feb 28 22:39:16 hostname systemd[1]: Finished Hello world service.
+
+$ portablectl detach hello_2.12.1
+Removed /etc/systemd/system.attached/hello.service.
+Removed /etc/systemd/system.attached/hello.service.d/10-profile.conf.
+Removed /etc/systemd/system.attached/hello.service.d/20-portable.conf.
+Removed /etc/systemd/system.attached/hello.service.d.
+Removed /etc/portables/hello_2.12.1.raw.
+Removed /etc/systemd/system.attached.
+```
 :::
 
-Some other options available are:
-- `description`, `homepage`
-
-  Are added to the `/etc/os-release` in the image and are shown by the portable services tooling.
-  Default to empty values, not added to os-release.
-- `symlinks`
-
-  A list of attribute sets {object, symlink}. Symlinks will be created  in the root filesystem of the image to
-  objects in the Nix store. Defaults to an empty list.
-- `contents`
+:::{.example #ex-portableService-symlinks}
+# Specifying symlinks when building a Portable Service image
 
-  A list of additional derivations to be included in the image Nix store, as-is. Defaults to an empty list.
-- `squashfsTools`
+Some services may expect files or directories to be available globally.
+An example is a service which expects all trusted SSL certificates to exist in a specific location by default.
 
-  Defaults to `pkgs.squashfsTools`, allows you to override the package that provides `mksquashfs`.
-- `squash-compression`, `squash-block-size`
+To make things available globally, you must specify the `symlinks` attribute when using `portableService`.
+The following package builds on the package from [](#ex-portableService-hello) to make `/etc/ssl` available globally (this is only for illustrative purposes, because `hello` doesn't use `/etc/ssl`).
 
-  Options to `mksquashfs`. Default to `"xz -Xdict-size 100%"` and `"1M"` respectively.
-
-A typical usage of `symlinks` would be:
 ```nix
+{ lib, writeText, portableService, hello, cacert }:
+let
+  hello-service = writeText "hello.service" ''
+    [Unit]
+    Description=Hello world service
+
+    [Service]
+    Type=oneshot
+    ExecStart=${lib.getExe hello}
+  '';
+in
+portableService {
+  pname = "hello";
+  inherit (hello) version;
+  units = [ hello-service ];
   symlinks = [
-    { object = "${pkgs.cacert}/etc/ssl"; symlink = "/etc/ssl"; }
-    { object = "${pkgs.bash}/bin/bash"; symlink = "/bin/sh"; }
-    { object = "${pkgs.php}/bin/php"; symlink = "/usr/bin/php"; }
+    { object = "${cacert}/etc/ssl"; symlink = "/etc/ssl"; }
   ];
+}
 ```
-to create these symlinks for legacy applications that assume them existing globally.
-
-Once the image is created, and deployed on a host in `/var/lib/portables/`, you can attach the image and run the service. As root run:
-```console
-portablectl attach demo_1.0.raw
-systemctl enable --now demo.socket
-systemctl enable --now demo.service
-```
-::: {.note}
-See the [man page](https://www.freedesktop.org/software/systemd/man/portablectl.html) of `portablectl` for more info on its usage.
 :::
diff --git a/nixpkgs/doc/manpage-urls.json b/nixpkgs/doc/manpage-urls.json
index 5739a59d9420..2cc03af4360f 100644
--- a/nixpkgs/doc/manpage-urls.json
+++ b/nixpkgs/doc/manpage-urls.json
@@ -318,5 +318,7 @@
   "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"
+  "unshare(1)": "https://man.archlinux.org/man/unshare.1.en",
+  "nix-shell(1)": "https://nixos.org/manual/nix/stable/command-ref/nix-shell.html",
+  "mksquashfs(1)": "https://man.archlinux.org/man/extra/squashfs-tools/mksquashfs.1.en"
 }
diff --git a/nixpkgs/doc/packages/darwin-builder.section.md b/nixpkgs/doc/packages/darwin-builder.section.md
index bf6ef906ca5a..3a547de53705 100644
--- a/nixpkgs/doc/packages/darwin-builder.section.md
+++ b/nixpkgs/doc/packages/darwin-builder.section.md
@@ -1,5 +1,12 @@
 # darwin.linux-builder {#sec-darwin-builder}
 
+:::{.warning}
+By default, `darwin.linux-builder` uses a publicly-known private SSH **host key** (this is different from the SSH key used by the user that connects to the builder).
+
+Given the intended use case for it (a Linux builder that runs **on the same machine**), this shouldn't be an issue.
+However, if you plan to deviate from this use case in any way (e.g. by exposing this builder to remote machines), you should understand the security implications of doing so and take any appropriate measures.
+:::
+
 `darwin.linux-builder` provides a way to bootstrap a Linux remote builder on a macOS machine.
 
 This requires macOS version 12.4 or later.
@@ -97,6 +104,7 @@ $ sudo launchctl kickstart -k system/org.nixos.nix-daemon
         { virtualisation = {
             host.pkgs = pkgs;
             darwin-builder.workingDirectory = "/var/lib/darwin-builder";
+            darwin-builder.hostPort = 22;
           };
         }
       ];
@@ -110,7 +118,9 @@ $ sudo launchctl kickstart -k system/org.nixos.nix-daemon
           {
             nix.distributedBuilds = true;
             nix.buildMachines = [{
-              hostName = "ssh://builder@localhost";
+              hostName = "localhost";
+              sshUser = "builder";
+              sshKey = "/etc/nix/builder_ed25519";
               system = linuxSystem;
               maxJobs = 4;
               supportedFeatures = [ "kvm" "benchmark" "big-parallel" ];