pyrox.dev
+154
-57
doc/build-helpers/images/dockertools.section.md
+154
-57
doc/build-helpers/images/dockertools.section.md
···+When building Docker images with Nix, you might also want to add certain files that are expected to be available globally by the software you're packaging.+Simple examples are the `env` utility in `/usr/bin/env`, or trusted root TLS/SSL certificates.+Such files will most likely not be included if you're building a Docker image from scratch with Nix, and they might also not be included if you're starting from a Docker image that doesn't include them.+The helpers in this section are packages that provide some of these commonly-needed global files.+Most of these helpers are packages, which means you have to add them to the list of contents to be included in the image (this changes depending on the function you're using to build the image).+[](#ex-dockerTools-helpers-buildImage) and [](#ex-dockerTools-helpers-buildLayeredImage) show how to include these packages on `dockerTools` functions that build an image.+This is currently implemented by linking to the `env` binary from the `coreutils` package, but is considered an implementation detail that could change in the future.+Because of this, it supports cases such as running a command interactively in a container (for example by running `docker run -it <image_name>`).+This adds trusted root TLS/SSL certificates from the `cacert` package in multiple locations in an attempt to be compatible with binaries built for multiple Linux distributions.-This constant string is a helper for setting up the base files for managing users and groups, only if such files don't exist already. It is suitable for being used in a [`buildImage` `runAsRoot`](#ex-dockerTools-buildImage-runAsRoot) script for cases like in the example below:+This is a string containing a script that sets up files needed for [`shadow`](https://github.com/shadow-maint/shadow) to work (using the `shadow` package from Nixpkgs), and alters `PATH` to make all its utilities available in the same script.+After the script in `shadowSetup` runs, you'll then be able to add more commands that make use of the utilities in `shadow`, such as adding any extra users and/or groups.+See [](#ex-dockerTools-shadowSetup-buildImage) and [](#ex-dockerTools-shadowSetup-buildLayeredImage) to better understand how to use it.+`shadowSetup` achieves a result similar to [`fakeNss`](#sssec-pkgs-dockerTools-helpers-fakeNss), but only sets up a `root` user with different values for the home directory and the shell to use, in addition to setting up files for [PAM](https://en.wikipedia.org/wiki/Linux_PAM) and a {manpage}`login.defs(5)` file.+Using both `fakeNss` and `shadowSetup` at the same time will either cause your build to break or produce unexpected results.+When used with [`buildLayeredImage`](#ssec-pkgs-dockerTools-buildLayeredImage) or [`streamLayeredImage`](#ssec-pkgs-dockerTools-streamLayeredImage), you will have to set the `enableFakechroot` attribute to `true`, or else the script in `shadowSetup` won't run properly.+This example adds the [`binSh`](#sssec-pkgs-dockerTools-helpers-binSh) helper to a basic Docker image built with [`dockerTools.buildImage`](#ssec-pkgs-dockerTools-buildImage).+After building the image and loading it in Docker, we can create a container based on it and enter a shell inside the container.+This example adds the [`binSh`](#sssec-pkgs-dockerTools-helpers-binSh) helper to a basic Docker image built with [`dockerTools.buildLayeredImage`](#ssec-pkgs-dockerTools-buildLayeredImage).-Creating base files like `/etc/passwd` or `/etc/login.defs` is necessary for shadow-utils to manipulate users and groups.+After building the image and loading it in Docker, we can create a container based on it and enter a shell inside the container.-When using `buildLayeredImage`, you can put this in `fakeRootCommands` if you `enableFakechroot`:+Note that the extra script in `runAsRoot` uses `groupadd` and `useradd`, which are binaries provided by the `shadow` package.+These binaries are added to the `PATH` by the `shadowSetup` script, but only for the duration of `runAsRoot`.+It accomplishes the same thing as [](#ex-dockerTools-shadowSetup-buildImage), but using `buildLayeredImage` instead.+Note that the extra script in `fakeRootCommands` uses `groupadd` and `useradd`, which are binaries provided by the `shadow` package.+These binaries are added to the `PATH` by the `shadowSetup` script, but only for the duration of `fakeRootCommands`.
+1
doc/build-helpers/special.md
+1
doc/build-helpers/special.md
+77
doc/build-helpers/special/fakenss.section.md
+77
doc/build-helpers/special/fakenss.section.md
···+Provides `/etc/passwd` and `/etc/group` files that contain `root` and `nobody`, allowing user/group lookups to work in binaries that insist on doing those.+This might be a better choice than a custom script running `useradd` and related utilities if you only need those files to exist with some entries.+`fakeNss` also provides `/etc/nsswitch.conf`, configuring NSS host resolution to first check `/etc/hosts` before checking DNS, since the default in the absence of a config file (`dns [!UNAVAIL=return] files`) is quite unexpected.+It also creates an empty directory at `/var/empty` because it uses that as the home directory for the `root` and `nobody` users.+The `/var/empty` directory can also be used as a `chroot` target to prevent file access in processes that do not need to access files, if your container runs such processes.+The user entries created by `fakeNss` use the `/bin/sh` shell, which is not provided by `fakeNss` because in most cases it won't be used.+If you need that to be available, see [`dockerTools.binSh`](#sssec-pkgs-dockerTools-helpers-binSh) or provide your own.+`fakeNss` is made available in Nixpkgs as a package rather than a function, but it has two attributes that can be overridden and might be useful in particular cases.+For more details on how overriding works, see [](#ex-fakeNss-overriding) and [](#sec-pkg-override).+If `extraPasswdLines` is specified, it will **not** override the `root` and `nobody` entries created by `fakeNss`.+If `extraGroupLines` is specified, it will **not** override the `root` and `nobody` entries created by `fakeNss`.+It is useful with functions in `dockerTools` to allow building Docker images that have the `/etc/passwd` and `/etc/group` files.+This example includes the `hello` binary in the image so it can do something besides just have the extra files.+The following code uses `override` to add extra lines to `/etc/passwd` and `/etc/group` to create another user and group entry.
+4
-1
doc/manpage-urls.json
+4
-1
doc/manpage-urls.json
···"systemd-veritysetup@.service(8)": "https://www.freedesktop.org/software/systemd/man/systemd-veritysetup@.service.html","systemd-volatile-root(8)": "https://www.freedesktop.org/software/systemd/man/systemd-volatile-root.html","systemd-xdg-autostart-generator(8)": "https://www.freedesktop.org/software/systemd/man/systemd-xdg-autostart-generator.html",
+1
pkgs/build-support/docker/default.nix
+1
pkgs/build-support/docker/default.nix
···+# The use of bashInteractive here is intentional to support cases like `docker run -it <image_name>`, so keep these use cases in mind if making any changes to how this works.