diff options
Diffstat (limited to 'nixpkgs/doc/build-helpers')
3 files changed, 246 insertions, 76 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. ::: |