pyrox.dev
1# pkgs.portableService {#sec-pkgs-portableService}
2
3`pkgs.portableService` is a function to create _portable service images_,
4as read-only, immutable, `squashfs` archives.
5
6systemd supports a concept of [Portable Services](https://systemd.io/PORTABLE_SERVICES/).
7Portable Services are a delivery method for system services that uses two specific features of container management:
8
9* Applications are bundled. I.e. multiple services, their binaries and
10 all their dependencies are packaged in an image, and are run directly from it.
11* Stricter default security policies, i.e. sandboxing of applications.
12
13This allows using Nix to build images which can be run on many recent Linux distributions.
14
15The primary tool for interacting with Portable Services is `portablectl`,
16and they are managed by the `systemd-portabled` system service.
17
18::: {.note}
19Portable services are supported starting with systemd 239 (released on 2018-06-22).
20:::
21
22A very simple example of using `portableService` is described below:
23
24[]{#ex-pkgs-portableService}
25
26```nix
27pkgs.portableService {
28 pname = "demo";
29 version = "1.0";
30 units = [ demo-service demo-socket ];
31}
32```
33
34The above example will build an squashfs archive image in `result/$pname_$version.raw`. The image will contain the
35file system structure as required by the portable service specification, and a subset of the Nix store with all the
36dependencies of the two derivations in the `units` list.
37`units` must be a list of derivations, and their names must be prefixed with the service name (`"demo"` in this case).
38Otherwise `systemd-portabled` will ignore them.
39
40::: {.note}
41The `.raw` file extension of the image is required by the portable services specification.
42:::
43
44Some other options available are:
45- `description`, `homepage`
46
47 Are added to the `/etc/os-release` in the image and are shown by the portable services tooling.
48 Default to empty values, not added to os-release.
49- `symlinks`
50
51 A list of attribute sets {object, symlink}. Symlinks will be created in the root filesystem of the image to
52 objects in the Nix store. Defaults to an empty list.
53- `contents`
54
55 A list of additional derivations to be included in the image Nix store, as-is. Defaults to an empty list.
56- `squashfsTools`
57
58 Defaults to `pkgs.squashfsTools`, allows you to override the package that provides `mksquashfs`.
59- `squash-compression`, `squash-block-size`
60
61 Options to `mksquashfs`. Default to `"xz -Xdict-size 100%"` and `"1M"` respectively.
62
63A typical usage of `symlinks` would be:
64```nix
65 symlinks = [
66 { object = "${pkgs.cacert}/etc/ssl"; symlink = "/etc/ssl"; }
67 { object = "${pkgs.bash}/bin/bash"; symlink = "/bin/sh"; }
68 { object = "${pkgs.php}/bin/php"; symlink = "/usr/bin/php"; }
69 ];
70```
71to create these symlinks for legacy applications that assume them existing globally.
72
73Once 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:
74```console
75portablectl attach demo_1.0.raw
76systemctl enable --now demo.socket
77systemctl enable --now demo.service
78```
79::: {.note}
80See the [man page](https://www.freedesktop.org/software/systemd/man/portablectl.html) of `portablectl` for more info on its usage.
81:::