doc/build-helpers/special/fakenss.section.md

   1 # fakeNss {#sec-fakeNss}
   2
   3 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.
   4 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.
   5
   6 `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.
   7
   8 It also creates an empty directory at `/var/empty` because it uses that as the home directory for the `root` and `nobody` users.
   9 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.
  10
  11 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.
  12 If you need that to be available, see [`dockerTools.binSh`](#sssec-pkgs-dockerTools-helpers-binSh) or provide your own.
  13
  14 ## Inputs {#sec-fakeNss-inputs}
  15
  16 `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.
  17 For more details on how overriding works, see [](#ex-fakeNss-overriding) and [](#sec-pkg-override).
  18
  19 `extraPasswdLines` (List of Strings; _optional_)
  20
  21 : A list of lines that will be added to `/etc/passwd`.
  22   Useful if extra users need to exist in the output of `fakeNss`.
  23   If `extraPasswdLines` is specified, it will **not** override the `root` and `nobody` entries created by `fakeNss`.
  24   Those entries will always exist.
  25
  26   Lines specified here must follow the format in {manpage}`passwd(5)`.
  27
  28   _Default value:_ `[]`.
  29
  30 `extraGroupLines` (List of Strings; _optional_)
  31
  32 : A list of lines that will be added to `/etc/group`.
  33   Useful if extra groups need to exist in the output of `fakeNss`.
  34   If `extraGroupLines` is specified, it will **not** override the `root` and `nobody` entries created by `fakeNss`.
  35   Those entries will always exist.
  36
  37   Lines specified here must follow the format in {manpage}`group(5)`.
  38
  39   _Default value:_ `[]`.
  40
  41 ## Examples {#sec-fakeNss-examples}
  42
  43 :::{.example #ex-fakeNss-dockerTools-buildImage}
  44 # Using `fakeNss` with `dockerTools.buildImage`
  45
  46 This example shows how to use `fakeNss` as-is.
  47 It is useful with functions in `dockerTools` to allow building Docker images that have the `/etc/passwd` and `/etc/group` files.
  48 This example includes the `hello` binary in the image so it can do something besides just have the extra files.
  49
  50 ```nix
  51 { dockerTools, fakeNss, hello }:
  52 dockerTools.buildImage {
  53   name = "image-with-passwd";
  54   tag = "latest";
  55
  56   copyToRoot = [ fakeNss hello ];
  57
  58   config = {
  59     Cmd = [ "/bin/hello" ];
  60   };
  61 }
  62 ```
  63 :::
  64
  65 :::{.example #ex-fakeNss-overriding}
  66 # Using `fakeNss` with an override to add extra lines
  67
  68 The following code uses `override` to add extra lines to `/etc/passwd` and `/etc/group` to create another user and group entry.
  69
  70 ```nix
  71 { fakeNss }:
  72 fakeNss.override {
  73   extraPasswdLines = ["newuser:x:9001:9001:new user:/var/empty:/bin/sh"];
  74   extraGroupLines = ["newuser:x:9001:"];
  75 }
  76 ```
  77 :::