3
0
Fork 0
forked from mirrors/nixpkgs

add documentation for the pkgs.portableService tool (#193081)

* add documentation for the pkgs.portableService tool

as introduced in 499aebcf34

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
This commit is contained in:
Дамјан Георгиевски 2022-10-07 10:37:56 +02:00 committed by GitHub
parent d29ad7dd85
commit 4e385bec15
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 82 additions and 0 deletions

View file

@ -9,4 +9,5 @@
<xi:include href="images/dockertools.section.xml" />
<xi:include href="images/ocitools.section.xml" />
<xi:include href="images/snaptools.section.xml" />
<xi:include href="images/portableservice.section.xml" />
</chapter>

View file

@ -0,0 +1,81 @@
# pkgs.portableService {#sec-pkgs-portableService}
`pkgs.portableService` is a function to create _portable service images_,
as read-only, immutable, `squashfs` archives.
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:
* 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.
This allows using Nix to build images which can be run on many recent Linux distributions.
The primary tool for interacting with Portable Services is `portablectl`,
and they are managed by the `systemd-portabled` system service.
:::{.note}
Portable services are supported starting with systemd 239 (released on 2018-06-22).
:::
A very simple example of using `portableService` is described below:
[]{#ex-pkgs-portableService}
```nix
pkgs.portableService {
pname = "demo";
version = "1.0";
units = [ demo-service demo-socket ];
}
```
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.
:::
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`
A list of additional derivations to be included in the image Nix store, as-is. Defaults to an empty list.
- `squashfsTools`
Defaults to `pkgs.squashfsTools`, allows you to override the package that provides `mksquashfs`.
- `squash-compression`, `squash-block-size`
Options to `mksquashfs`. Default to `"xz -Xdict-size 100%"` and `"1M"` respectively.
A typical usage of `symlinks` would be:
```nix
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"; }
];
```
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.
:::