···11# pkgs.ociTools {#sec-pkgs-ociTools}
2233-`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.
33+`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).
44+It makes no assumptions about the container runner you choose to use to run the created container.
55+66+The set of functions in `pkgs.ociTools` currently does not handle the [OCI image specification](https://github.com/opencontainers/image-spec).
77+88+At a high-level an OCI implementation would download an OCI Image then unpack that image into an OCI Runtime filesystem bundle.
99+At this point the OCI Runtime Bundle would be run by an OCI Runtime.
1010+`pkgs.ociTools` provides utilities to create OCI Runtime bundles.
411512## buildContainer {#ssec-pkgs-ociTools-buildContainer}
61377-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.
1414+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.
1515+The nix store of the container will contain all referenced dependencies of the given command.
1616+1717+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.
1818+Because of this, a container built with `buildContainer` will not work on Windows or other non-POSIX platforms without modifications to the container configuration.
1919+These modifications aren't supported by `buildContainer`.
2020+2121+For `linux` platforms, `buildContainer` also configures the following namespaces (see {manpage}`unshare(1)`) to isolate the OCI container from the global namespace:
2222+PID, network, mount, IPC, and UTS.
2323+2424+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.
2525+2626+### Inputs {#ssec-pkgs-ociTools-buildContainer-inputs}
2727+2828+`buildContainer` expects an argument with the following attributes:
2929+3030+`args` (List of String)
3131+3232+: Specifies a set of arguments to run inside the container.
3333+ Any packages referenced by `args` will be made available inside the container.
3434+3535+`mounts` (Attribute Set; _optional_)
3636+3737+: Would specify additional mounts that the runtime must make available to the container.
3838+3939+ :::{.warning}
4040+ As explained in [issue #290879](https://github.com/NixOS/nixpkgs/issues/290879), this attribute is currently ignored.
4141+ :::
4242+4343+ :::{.note}
4444+ `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.
4545+ :::
4646+4747+ _Default value:_ `{}`.
4848+4949+`readonly` (Boolean; _optional_)
5050+5151+: If `true`, sets the container's root filesystem as read-only.
5252+5353+ _Default value:_ `false`.
5454+5555+`os` **DEPRECATED**
5656+5757+: Specifies the operating system on which the container filesystem is based on.
5858+ If specified, its value should follow the [OCI Image Configuration Specification](https://github.com/opencontainers/image-spec/blob/main/config.md#properties).
5959+ 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`.
6060+6161+ _Default value:_ `"linux"`.
6262+6363+`arch` **DEPRECATED**
6464+6565+: Used to specify the architecture for which the binaries in the container filesystem have been compiled.
6666+ If specified, its value should follow the [OCI Image Configuration Specification](https://github.com/opencontainers/image-spec/blob/main/config.md#properties).
6767+ 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`.
6868+6969+ _Default value:_ `x86_64`.
7070+7171+### Examples {#ssec-pkgs-ociTools-buildContainer-examples}
7272+7373+::: {.example #ex-ociTools-buildContainer-bash}
7474+# Creating an OCI runtime container that runs `bash`
87599-The parameters of `buildContainer` with an example value are described below:
7676+This example uses `ociTools.buildContainer` to create a simple container that runs `bash`.
10771178```nix
1212-buildContainer {
7979+{ ociTools, lib, bash }:
8080+ociTools.buildContainer {
1381 args = [
1414- (with pkgs;
1515- writeScript "run.sh" ''
1616- #!${bash}/bin/bash
1717- exec ${bash}/bin/bash
1818- '').outPath
8282+ (lib.getExe bash)
1983 ];
20842121- mounts = {
2222- "/data" = {
2323- type = "none";
2424- source = "/var/lib/mydata";
2525- options = [ "bind" ];
2626- };
2727- };
2828-2985 readonly = false;
3086}
3187```
32883333-- `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.
8989+As an example of how to run the container generated by this package, we'll use `runc` to start the container.
9090+Any other tool that supports OCI containers could be used instead.
34913535-- `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)
9292+```shell
9393+$ nix-build
9494+(some output removed for clarity)
9595+/nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join
36963737-- `readonly` makes the container's rootfs read-only if it is set to true. The default value is false `false`.
9797+$ cd /nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join
9898+$ nix-shell -p runc
9999+[nix-shell:/nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join]$ sudo runc run ocitools-example
100100+help
101101+GNU bash, version 5.2.26(1)-release (x86_64-pc-linux-gnu)
102102+(some output removed for clarity)
103103+```
104104+:::
···11# pkgs.portableService {#sec-pkgs-portableService}
2233-`pkgs.portableService` is a function to create _portable service images_,
44-as read-only, immutable, `squashfs` archives.
33+`pkgs.portableService` is a function to create [Portable Services](https://systemd.io/PORTABLE_SERVICES/) in a read-only, immutable, `squashfs` raw disk image.
44+This lets you use Nix to build images which can be run on many recent Linux distributions.
5566-systemd supports a concept of [Portable Services](https://systemd.io/PORTABLE_SERVICES/).
77-Portable Services are a delivery method for system services that uses two specific features of container management:
66+::: {.note}
77+Portable services are supported starting with systemd 239 (released on 2018-06-22).
88+:::
8999-* Applications are bundled. I.e. multiple services, their binaries and
1010- all their dependencies are packaged in an image, and are run directly from it.
1111-* Stricter default security policies, i.e. sandboxing of applications.
1010+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.
1111+When generated, the image will exist in the Nix store with the `.raw` file extension, as required by the specification.
1212+See [](#ex-portableService-hello) to understand how to use the output of `portableService`.
12131313-This allows using Nix to build images which can be run on many recent Linux distributions.
1414+## Inputs {#ssec-pkgs-portableService-inputs}
14151515-The primary tool for interacting with Portable Services is `portablectl`,
1616-and they are managed by the `systemd-portabled` system service.
1616+`portableService` expects one argument with the following attributes:
17171818-::: {.note}
1919-Portable services are supported starting with systemd 239 (released on 2018-06-22).
2020-:::
1818+`pname` (String)
21192222-A very simple example of using `portableService` is described below:
2020+: The name of the portable service.
2121+ The generated image will be named according to the template `$pname_$version.raw`, which is supported by the Portable Services specification.
2222+2323+`version` (String)
2424+2525+: The version of the portable service.
2626+ The generated image will be named according to the template `$pname_$version.raw`, which is supported by the Portable Services specification.
2727+2828+`units` (List of Attribute Set)
2929+3030+: A list of derivations for systemd unit files.
3131+ 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).
3232+ See [](#ex-portableService-hello) to better understand this naming constraint.
3333+3434+`description` (String or Null; _optional_)
3535+3636+: If specified, the value is added as `PORTABLE_PRETTY_NAME` to the `/etc/os-release` file in the generated image.
3737+ This could be used to provide more information to anyone inspecting the image.
3838+3939+ _Default value:_ `null`.
4040+4141+`homepage` (String or Null; _optional_)
4242+4343+: If specified, the value is added as `HOME_URL` to the `/etc/os-release` file in the generated image.
4444+ This could be used to provide more information to anyone inspecting the image.
4545+4646+ _Default value:_ `null`.
4747+4848+`symlinks` (List of Attribute Set; _optional_)
4949+5050+: A list of attribute sets in the format `{object, symlink}`.
5151+ 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`.
5252+5353+ All packages that `object` depends on and their dependencies are automatically copied into the image.
5454+5555+ This can be used to create symlinks for applications that assume some files to exist globally (`/etc/ssl` or `/bin/bash`, for example).
5656+ See [](#ex-portableService-symlinks) to understand how to do that.
5757+5858+ _Default value:_ `[]`.
5959+6060+`contents` (List of Attribute Set; _optional_)
6161+6262+: A list of additional derivations to be included as-is in the image.
6363+ These derivations will be included directly in a `/nix/store` directory inside the image.
6464+6565+ _Default value:_ `[]`.
6666+6767+`squashfsTools` (Attribute Set; _optional_)
6868+6969+: Allows you to override the package that provides {manpage}`mksquashfs(1)`, which is used internally by `portableService`.
7070+7171+ _Default value:_ `pkgs.squashfsTools`.
7272+7373+`squash-compression` (String; _optional_)
7474+7575+: Passed as the compression option to {manpage}`mksquashfs(1)`, which is used internally by `portableService`.
7676+7777+ _Default value:_ `"xz -Xdict-size 100%"`.
7878+7979+`squash-block-size` (String; _optional_)
8080+8181+: Passed as the block size option to {manpage}`mksquashfs(1)`, which is used internally by `portableService`.
8282+8383+ _Default value:_ `"1M"`.
8484+8585+## Examples {#ssec-pkgs-portableService-examples}
23862487[]{#ex-pkgs-portableService}
8888+:::{.example #ex-portableService-hello}
8989+# Building a Portable Service image
9090+9191+The following example builds a Portable Service image with the `hello` package, along with a service unit that runs it.
25922693```nix
2727-pkgs.portableService {
2828- pname = "demo";
2929- version = "1.0";
3030- units = [ demo-service demo-socket ];
9494+{ lib, writeText, portableService, hello }:
9595+let
9696+ hello-service = writeText "hello.service" ''
9797+ [Unit]
9898+ Description=Hello world service
9999+100100+ [Service]
101101+ Type=oneshot
102102+ ExecStart=${lib.getExe hello}
103103+ '';
104104+in
105105+portableService {
106106+ pname = "hello";
107107+ inherit (hello) version;
108108+ units = [ hello-service ];
31109}
32110```
331113434-The above example will build an squashfs archive image in `result/$pname_$version.raw`. The image will contain the
3535-file system structure as required by the portable service specification, and a subset of the Nix store with all the
3636-dependencies of the two derivations in the `units` list.
3737-`units` must be a list of derivations, and their names must be prefixed with the service name (`"demo"` in this case).
3838-Otherwise `systemd-portabled` will ignore them.
112112+After building the package, the generated image can be loaded into a system through {manpage}`portablectl(1)`:
391134040-::: {.note}
4141-The `.raw` file extension of the image is required by the portable services specification.
4242-:::
114114+```shell
115115+$ nix-build
116116+(some output removed for clarity)
117117+/nix/store/8c20z1vh7z8w8dwagl8w87b45dn5k6iq-hello-img-2.12.1
431184444-Some other options available are:
4545-- `description`, `homepage`
119119+$ portablectl attach /nix/store/8c20z1vh7z8w8dwagl8w87b45dn5k6iq-hello-img-2.12.1/hello_2.12.1.raw
120120+Created directory /etc/systemd/system.attached.
121121+Created directory /etc/systemd/system.attached/hello.service.d.
122122+Written /etc/systemd/system.attached/hello.service.d/20-portable.conf.
123123+Created symlink /etc/systemd/system.attached/hello.service.d/10-profile.conf → /usr/lib/systemd/portable/profile/default/service.conf.
124124+Copied /etc/systemd/system.attached/hello.service.
125125+Created symlink /etc/portables/hello_2.12.1.raw → /nix/store/8c20z1vh7z8w8dwagl8w87b45dn5k6iq-hello-img-2.12.1/hello_2.12.1.raw.
461264747- Are added to the `/etc/os-release` in the image and are shown by the portable services tooling.
4848- Default to empty values, not added to os-release.
4949-- `symlinks`
127127+$ systemctl start hello
128128+$ journalctl -u hello
129129+Feb 28 22:39:16 hostname systemd[1]: Starting Hello world service...
130130+Feb 28 22:39:16 hostname hello[102887]: Hello, world!
131131+Feb 28 22:39:16 hostname systemd[1]: hello.service: Deactivated successfully.
132132+Feb 28 22:39:16 hostname systemd[1]: Finished Hello world service.
501335151- A list of attribute sets {object, symlink}. Symlinks will be created in the root filesystem of the image to
5252- objects in the Nix store. Defaults to an empty list.
5353-- `contents`
134134+$ portablectl detach hello_2.12.1
135135+Removed /etc/systemd/system.attached/hello.service.
136136+Removed /etc/systemd/system.attached/hello.service.d/10-profile.conf.
137137+Removed /etc/systemd/system.attached/hello.service.d/20-portable.conf.
138138+Removed /etc/systemd/system.attached/hello.service.d.
139139+Removed /etc/portables/hello_2.12.1.raw.
140140+Removed /etc/systemd/system.attached.
141141+```
142142+:::
541435555- A list of additional derivations to be included in the image Nix store, as-is. Defaults to an empty list.
5656-- `squashfsTools`
144144+:::{.example #ex-portableService-symlinks}
145145+# Specifying symlinks when building a Portable Service image
571465858- Defaults to `pkgs.squashfsTools`, allows you to override the package that provides `mksquashfs`.
5959-- `squash-compression`, `squash-block-size`
147147+Some services may expect files or directories to be available globally.
148148+An example is a service which expects all trusted SSL certificates to exist in a specific location by default.
601496161- Options to `mksquashfs`. Default to `"xz -Xdict-size 100%"` and `"1M"` respectively.
150150+To make things available globally, you must specify the `symlinks` attribute when using `portableService`.
151151+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`).
621526363-A typical usage of `symlinks` would be:
64153```nix
154154+{ lib, writeText, portableService, hello, cacert }:
155155+let
156156+ hello-service = writeText "hello.service" ''
157157+ [Unit]
158158+ Description=Hello world service
159159+160160+ [Service]
161161+ Type=oneshot
162162+ ExecStart=${lib.getExe hello}
163163+ '';
164164+in
165165+portableService {
166166+ pname = "hello";
167167+ inherit (hello) version;
168168+ units = [ hello-service ];
65169 symlinks = [
6666- { object = "${pkgs.cacert}/etc/ssl"; symlink = "/etc/ssl"; }
6767- { object = "${pkgs.bash}/bin/bash"; symlink = "/bin/sh"; }
6868- { object = "${pkgs.php}/bin/php"; symlink = "/usr/bin/php"; }
170170+ { object = "${cacert}/etc/ssl"; symlink = "/etc/ssl"; }
69171 ];
7070-```
7171-to create these symlinks for legacy applications that assume them existing globally.
7272-7373-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:
7474-```console
7575-portablectl attach demo_1.0.raw
7676-systemctl enable --now demo.socket
7777-systemctl enable --now demo.service
172172+}
78173```
7979-::: {.note}
8080-See the [man page](https://www.freedesktop.org/software/systemd/man/portablectl.html) of `portablectl` for more info on its usage.
81174:::
···145145 in fix g
146146 ```
147147148148+ :::{.note}
149149+ The argument to the given fixed-point function after applying an overlay will *not* refer to its own return value, but rather to the value after evaluating the overlay function.
150150+151151+ The given fixed-point function is called with a separate argument than if it was evaluated with `lib.fix`.
152152+ :::
153153+148154 :::{.example}
149155150156 # Extend a fixed-point function with an overlay
···230236231237 fix (extends (final: prev: { c = final.a + final.b; }) f)
232238 => { a = 1; b = 3; c = 4; }
233233-234234- :::{.note}
235235- The argument to the given fixed-point function after applying an overlay will *not* refer to its own return value, but rather to the value after evaluating the overlay function.
236236-237237- The given fixed-point function is called with a separate argument than if it was evaluated with `lib.fix`.
238238- The new argument
239239- :::
240239 */
241240 extends =
242241 # The overlay to apply to the fixed-point function
···77, luajit
88, makeWrapper
99, symlinkJoin
1010-, disable-warnings-if-gcc13
1110}:
12111312# revisions are taken from https://github.com/GrimKriegor/TES3MP-deploy
14131514let
1615 # raknet could also be split into dev and lib outputs
1717- raknet = disable-warnings-if-gcc13 (stdenv.mkDerivation {
1616+ raknet = stdenv.mkDerivation {
1817 pname = "raknet";
1918 version = "unstable-2020-01-19";
2019···4645 installPhase = ''
4746 install -Dm555 lib/libRakNetLibStatic.a $out/lib/libRakNetLibStatic.a
4847 '';
4949- });
4848+ };
50495150 coreScripts = stdenv.mkDerivation {
5251 pname = "corescripts";
+3-1
pkgs/os-specific/linux/reptyr/default.nix
···17171818 nativeCheckInputs = [ python ];
19192020- doCheck = true;
2020+ # reptyr needs to do ptrace of a non-child process
2121+ # It can be neither used nor tested if the kernel is not told to allow this
2222+ doCheck = false;
21232224 checkFlags = [
2325 "PYTHON_CMD=${python.interpreter}"