pkgs.dockerTools: buildImage Function Inputs (Continued)

If specified, the layer created by `buildImage` will be appended to the layers defined in the base image, resulting in an image with at least two layers (one or more layers from the base image and the layer created by `buildImage`). Otherwise, the resulting image will contain the single layer created by `buildImage`. :::{.note} Only **Env** configuration is inherited from the base image. ::: _Default value:_ `null`. `fromImageName` (String or Null; _optional_) : Used to specify the image within the repository tarball in case it contains multiple images. A value of `null` means that `buildImage` will use the first image available in the repository. :::{.note} This must be used with `fromImageTag`. Using only `fromImageName` without `fromImageTag` will make `buildImage` use the first image available in the repository. ::: _Default value:_ `null`. `fromImageTag` (String or Null; _optional_) : Used to specify the image within the repository tarball in case it contains multiple images. A value of `null` means that `buildImage` will use the first image available in the repository. :::{.note} This must be used with `fromImageName`. Using only `fromImageTag` without `fromImageName` will make `buildImage` use the first image available in the repository ::: _Default value:_ `null`. `copyToRoot` (Path, List of Paths, or Null; _optional_) : Files to add to the generated image. Anything that coerces to a path (e.g. a derivation) can also be used. This can be seen as an equivalent of `ADD contents/ /` in a `Dockerfile`. _Default value:_ `null`. `keepContentsDirlinks` (Boolean; _optional_) : When adding files to the generated image (as specified by `copyToRoot`), this attribute controls whether to preserve symlinks to directories. If `false`, the symlinks will be transformed into directories. This behaves the same as `rsync -k` when `keepContentsDirlinks` is `false`, and the same as `rsync -K` when `keepContentsDirlinks` is `true`. _Default value:_ `false`. `runAsRoot` (String or Null; _optional_) : A bash script that will run as root inside a VM that contains the existing layers of the base image and the new generated layer (including the files from `copyToRoot`). The script will be run with a working directory of `/`. This can be seen as an equivalent of `RUN ...` in a `Dockerfile`. A value of `null` means that this step in the image generation process will be skipped. See [](#ex-dockerTools-buildImage-runAsRoot) for how to work with this attribute. :::{.caution} Using this attribute requires the `kvm` device to be available, see [`system-features`](https://nixos.org/manual/nix/stable/command-ref/conf-file.html#conf-system-features). If the `kvm` device isn't available, you should consider using [`buildLayeredImage`](#ssec-pkgs-dockerTools-buildLayeredImage) or [`streamLayeredImage`](#ssec-pkgs-dockerTools-streamLayeredImage) instead. Those functions allow scripts to be run as root without access to the `kvm` device. ::: :::{.note} At the time the script in `runAsRoot` is run, the files specified directly in `copyToRoot` will be present in the VM, but their dependencies might not be there yet. Copying their dependencies into the generated image is a step that happens after `runAsRoot` finishes running. ::: _Default value:_ `null`. `extraCommands` (String; _optional_) : A bash script that will run before the layer created by `buildImage` is finalised. The script will be run on some (opaque) working directory which will become `/` once the layer is created. This is similar to `runAsRoot`, but the script specified in `extraCommands` is **not** run as root, and does not involve creating a VM. It is simply run as part of building the derivation that outputs the layer created by `buildImage`. See [](#ex-dockerTools-buildImage-extraCommands) for how to work with this attribute, and subtle differences compared to `runAsRoot`. _Default value:_ `""`.

This document continues describing the input attributes for the `pkgs.dockerTools.buildImage` function. It explains `fromImageName` and `fromImageTag`, used in conjunction to specify a particular base image from a repository tarball. `copyToRoot` allows adding files or derivations to the image's root, similar to `ADD` in a Dockerfile, with `keepContentsDirlinks` controlling directory symlink handling. The `runAsRoot` attribute defines a bash script to be executed as root within a VM, enabling custom modifications but requiring KVM. Alternatively, `extraCommands` provides a non-root bash script that runs during the build process before the layer is finalized, without a VM.