Merge pull request #5212 from mkenigs/auto-uid-allocation

Merge master into #3600

1 files changed, 0 insertions, 1237 deletions

diff --git a/doc/manual/command-ref/conf-file.xml b/doc/manual/command-ref/conf-file.xml
deleted file mode 100644
index 1fa74a143..000000000
--- a/doc/manual/command-ref/conf-file.xml
+++ /dev/null
@@ -1,1237 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude"
-          xml:id="sec-conf-file"
-          version="5">
-
-<refmeta>
-  <refentrytitle>nix.conf</refentrytitle>
-  <manvolnum>5</manvolnum>
-  <refmiscinfo class="source">Nix</refmiscinfo>
-  <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo>
-</refmeta>
-
-<refnamediv>
-  <refname>nix.conf</refname>
-  <refpurpose>Nix configuration file</refpurpose>
-</refnamediv>
-
-<refsection><title>Description</title>
-
-<para>By default Nix reads settings from the following places:</para>
-
-<para>The system-wide configuration file
-<filename><replaceable>sysconfdir</replaceable>/nix/nix.conf</filename>
-(i.e. <filename>/etc/nix/nix.conf</filename> on most systems), or
-<filename>$NIX_CONF_DIR/nix.conf</filename> if
-<envar>NIX_CONF_DIR</envar> is set. Values loaded in this file are not forwarded to the Nix daemon. The
-client assumes that the daemon has already loaded them.
-</para>
-
-<para>User-specific configuration files:</para>
-
-<para>
-  If <envar>NIX_USER_CONF_FILES</envar> is set, then each path separated by
-  <literal>:</literal> will be loaded in reverse order.
-</para>
-
-<para>
-  Otherwise it will look for <filename>nix/nix.conf</filename> files in
-  <envar>XDG_CONFIG_DIRS</envar> and <envar>XDG_CONFIG_HOME</envar>.
-
-  The default location is <filename>$HOME/.config/nix.conf</filename> if
-  those environment variables are unset.
-</para>
-
-<para>The configuration files consist of
-<literal><replaceable>name</replaceable> =
-<replaceable>value</replaceable></literal> pairs, one per line. Other
-files can be included with a line like <literal>include
-<replaceable>path</replaceable></literal>, where
-<replaceable>path</replaceable> is interpreted relative to the current
-conf file and a missing file is an error unless
-<literal>!include</literal> is used instead.
-Comments start with a <literal>#</literal> character.  Here is an
-example configuration file:</para>
-
-<programlisting>
-keep-outputs = true       # Nice for developers
-keep-derivations = true   # Idem
-</programlisting>
-
-<para>You can override settings on the command line using the
-<option>--option</option> flag, e.g. <literal>--option keep-outputs
-false</literal>.</para>
-
-<para>The following settings are currently available:
-
-<variablelist>
-
-
-  <varlistentry xml:id="conf-allowed-uris"><term><literal>allowed-uris</literal></term>
-
-    <listitem>
-
-      <para>A list of URI prefixes to which access is allowed in
-      restricted evaluation mode. For example, when set to
-      <literal>https://github.com/NixOS</literal>, builtin functions
-      such as <function>fetchGit</function> are allowed to access
-      <literal>https://github.com/NixOS/patchelf.git</literal>.</para>
-
-    </listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id="conf-allow-import-from-derivation"><term><literal>allow-import-from-derivation</literal></term>
-
-    <listitem><para>By default, Nix allows you to <function>import</function> from a derivation,
-    allowing building at evaluation time. With this option set to false, Nix will throw an error
-    when evaluating an expression that uses this feature, allowing users to ensure their evaluation
-    will not require any builds to take place.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id="conf-allow-new-privileges"><term><literal>allow-new-privileges</literal></term>
-
-    <listitem><para>(Linux-specific.) By default, builders on Linux
-    cannot acquire new privileges by calling setuid/setgid programs or
-    programs that have file capabilities. For example, programs such
-    as <command>sudo</command> or <command>ping</command> will
-    fail. (Note that in sandbox builds, no such programs are available
-    unless you bind-mount them into the sandbox via the
-    <option>sandbox-paths</option> option.) You can allow the
-    use of such programs by enabling this option. This is impure and
-    usually undesirable, but may be useful in certain scenarios
-    (e.g. to spin up containers or set up userspace network interfaces
-    in tests).</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id="conf-allowed-users"><term><literal>allowed-users</literal></term>
-
-    <listitem>
-
-      <para>A list of names of users (separated by whitespace) that
-      are allowed to connect to the Nix daemon. As with the
-      <option>trusted-users</option> option, you can specify groups by
-      prefixing them with <literal>@</literal>. Also, you can allow
-      all users by specifying <literal>*</literal>. The default is
-      <literal>*</literal>.</para>
-
-      <para>Note that trusted users are always allowed to connect.</para>
-
-    </listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id="conf-auto-optimise-store"><term><literal>auto-optimise-store</literal></term>
-
-    <listitem><para>If set to <literal>true</literal>, Nix
-    automatically detects files in the store that have identical
-    contents, and replaces them with hard links to a single copy.
-    This saves disk space.  If set to <literal>false</literal> (the
-    default), you can still run <command>nix-store
-    --optimise</command> to get rid of duplicate
-    files.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id="conf-builders">
-    <term><literal>builders</literal></term>
-    <listitem>
-      <para>A list of machines on which to perform builds. <phrase
-      condition="manual">See <xref linkend="chap-distributed-builds"
-      /> for details.</phrase></para>
-    </listitem>
-  </varlistentry>
-
-
-  <varlistentry xml:id="conf-builders-use-substitutes"><term><literal>builders-use-substitutes</literal></term>
-
-    <listitem><para>If set to <literal>true</literal>, Nix will instruct
-    remote build machines to use their own binary substitutes if available. In
-    practical terms, this means that remote hosts will fetch as many build
-    dependencies as possible from their own substitutes (e.g, from
-    <literal>cache.nixos.org</literal>), instead of waiting for this host to
-    upload them all. This can drastically reduce build times if the network
-    connection between this computer and the remote build host is slow. Defaults
-    to <literal>false</literal>.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id="conf-build-users-group"><term><literal>build-users-group</literal></term>
-
-    <listitem><para>This options specifies the Unix group containing
-    the Nix build user accounts.  In multi-user Nix installations,
-    builds should not be performed by the Nix account since that would
-    allow users to arbitrarily modify the Nix store and database by
-    supplying specially crafted builders; and they cannot be performed
-    by the calling user since that would allow him/her to influence
-    the build result.</para>
-
-    <para>Therefore, if this option is non-empty and specifies a valid
-    group, builds will be performed under the user accounts that are a
-    member of the group specified here (as listed in
-    <filename>/etc/group</filename>).  Those user accounts should not
-    be used for any other purpose!</para>
-
-    <para>Nix will never run two builds under the same user account at
-    the same time.  This is to prevent an obvious security hole: a
-    malicious user writing a Nix expression that modifies the build
-    result of a legitimate Nix expression being built by another user.
-    Therefore it is good to have as many Nix build user accounts as
-    you can spare.  (Remember: uids are cheap.)</para>
-
-    <para>The build users should have permission to create files in
-    the Nix store, but not delete them.  Therefore,
-    <filename>/nix/store</filename> should be owned by the Nix
-    account, its group should be the group specified here, and its
-    mode should be <literal>1775</literal>.</para>
-
-    <para>If the build users group is empty, builds will be performed
-    under the uid of the Nix process (that is, the uid of the caller
-    if <envar>NIX_REMOTE</envar> is empty, the uid under which the Nix
-    daemon runs if <envar>NIX_REMOTE</envar> is
-    <literal>daemon</literal>).  Obviously, this should not be used in
-    multi-user settings with untrusted users.</para>
-
-    </listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id="conf-compress-build-log"><term><literal>compress-build-log</literal></term>
-
-    <listitem><para>If set to <literal>true</literal> (the default),
-    build logs written to <filename>/nix/var/log/nix/drvs</filename>
-    will be compressed on the fly using bzip2.  Otherwise, they will
-    not be compressed.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id="conf-connect-timeout"><term><literal>connect-timeout</literal></term>
-
-    <listitem>
-
-      <para>The timeout (in seconds) for establishing connections in
-      the binary cache substituter.  It corresponds to
-      <command>curl</command>’s <option>--connect-timeout</option>
-      option.</para>
-
-    </listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id="conf-cores"><term><literal>cores</literal></term>
-
-    <listitem><para>Sets the value of the
-    <envar>NIX_BUILD_CORES</envar> environment variable in the
-    invocation of builders.  Builders can use this variable at their
-    discretion to control the maximum amount of parallelism.  For
-    instance, in Nixpkgs, if the derivation attribute
-    <varname>enableParallelBuilding</varname> is set to
-    <literal>true</literal>, the builder passes the
-    <option>-j<replaceable>N</replaceable></option> flag to GNU Make.
-    It can be overridden using the <option
-    linkend='opt-cores'>--cores</option> command line switch and
-    defaults to <literal>1</literal>.  The value <literal>0</literal>
-    means that the builder should use all available CPU cores in the
-    system.</para>
-
-    <para>See also <xref linkend="chap-tuning-cores-and-jobs" />.</para></listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-diff-hook"><term><literal>diff-hook</literal></term>
-  <listitem>
-    <para>
-      Absolute path to an executable capable of diffing build results.
-      The hook executes if <xref linkend="conf-run-diff-hook" /> is
-      true, and the output of a build is known to not be the same.
-      This program is not executed to determine if two results are the
-      same.
-    </para>
-
-    <para>
-      The diff hook is executed by the same user and group who ran the
-      build. However, the diff hook does not have write access to the
-      store path just built.
-    </para>
-
-    <para>The diff hook program receives three parameters:</para>
-
-    <orderedlist>
-      <listitem>
-        <para>
-          A path to the previous build's results
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          A path to the current build's results
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          The path to the build's derivation
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          The path to the build's scratch directory. This directory
-          will exist only if the build was run with
-          <option>--keep-failed</option>.
-        </para>
-      </listitem>
-    </orderedlist>
-
-    <para>
-      The stderr and stdout output from the diff hook will not be
-      displayed to the user. Instead, it will print to the nix-daemon's
-      log.
-    </para>
-
-    <para>When using the Nix daemon, <literal>diff-hook</literal> must
-    be set in the <filename>nix.conf</filename> configuration file, and
-    cannot be passed at the command line.
-    </para>
-  </listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-enforce-determinism">
-    <term><literal>enforce-determinism</literal></term>
-
-    <listitem><para>See <xref linkend="conf-repeat" />.</para></listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-extra-sandbox-paths">
-    <term><literal>extra-sandbox-paths</literal></term>
-
-    <listitem><para>A list of additional paths appended to
-    <option>sandbox-paths</option>. Useful if you want to extend
-    its default value.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id="conf-extra-platforms"><term><literal>extra-platforms</literal></term>
-
-    <listitem><para>Platforms other than the native one which
-    this machine is capable of building for. This can be useful for
-    supporting additional architectures on compatible machines:
-    i686-linux can be built on x86_64-linux machines (and the default
-    for this setting reflects this); armv7 is backwards-compatible with
-    armv6 and armv5tel; some aarch64 machines can also natively run
-    32-bit ARM code; and qemu-user may be used to support non-native
-    platforms (though this may be slow and buggy). Most values for this
-    are not enabled by default because build systems will often
-    misdetect the target platform and generate incompatible code, so you
-    may wish to cross-check the results of using this option against
-    proper natively-built versions of your
-    derivations.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id="conf-extra-substituters"><term><literal>extra-substituters</literal></term>
-
-    <listitem><para>Additional binary caches appended to those
-    specified in <option>substituters</option>.  When used by
-    unprivileged users, untrusted substituters (i.e. those not listed
-    in <option>trusted-substituters</option>) are silently
-    ignored.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id="conf-fallback"><term><literal>fallback</literal></term>
-
-    <listitem><para>If set to <literal>true</literal>, Nix will fall
-    back to building from source if a binary substitute fails.  This
-    is equivalent to the <option>--fallback</option> flag.  The
-    default is <literal>false</literal>.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id="conf-fsync-metadata"><term><literal>fsync-metadata</literal></term>
-
-    <listitem><para>If set to <literal>true</literal>, changes to the
-    Nix store metadata (in <filename>/nix/var/nix/db</filename>) are
-    synchronously flushed to disk.  This improves robustness in case
-    of system crashes, but reduces performance.  The default is
-    <literal>true</literal>.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id="conf-hashed-mirrors"><term><literal>hashed-mirrors</literal></term>
-
-    <listitem><para>A list of web servers used by
-    <function>builtins.fetchurl</function> to obtain files by
-    hash. The default is
-    <literal>http://tarballs.nixos.org/</literal>. Given a hash type
-    <replaceable>ht</replaceable> and a base-16 hash
-    <replaceable>h</replaceable>, Nix will try to download the file
-    from
-    <literal>hashed-mirror/<replaceable>ht</replaceable>/<replaceable>h</replaceable></literal>.
-    This allows files to be downloaded even if they have disappeared
-    from their original URI. For example, given the default mirror
-    <literal>http://tarballs.nixos.org/</literal>, when building the derivation
-
-<programlisting>
-builtins.fetchurl {
-  url = "https://example.org/foo-1.2.3.tar.xz";
-  sha256 = "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae";
-}
-</programlisting>
-
-    Nix will attempt to download this file from
-    <literal>http://tarballs.nixos.org/sha256/2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae</literal>
-    first. If it is not available there, if will try the original URI.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id="conf-http-connections"><term><literal>http-connections</literal></term>
-
-    <listitem><para>The maximum number of parallel TCP connections
-    used to fetch files from binary caches and by other downloads. It
-    defaults to 25. 0 means no limit.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id="conf-keep-build-log"><term><literal>keep-build-log</literal></term>
-
-    <listitem><para>If set to <literal>true</literal> (the default),
-    Nix will write the build log of a derivation (i.e. the standard
-    output and error of its builder) to the directory
-    <filename>/nix/var/log/nix/drvs</filename>.  The build log can be
-    retrieved using the command <command>nix-store -l
-    <replaceable>path</replaceable></command>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id="conf-keep-derivations"><term><literal>keep-derivations</literal></term>
-
-    <listitem><para>If <literal>true</literal> (default), the garbage
-    collector will keep the derivations from which non-garbage store
-    paths were built.  If <literal>false</literal>, they will be
-    deleted unless explicitly registered as a root (or reachable from
-    other roots).</para>
-
-    <para>Keeping derivation around is useful for querying and
-    traceability (e.g., it allows you to ask with what dependencies or
-    options a store path was built), so by default this option is on.
-    Turn it off to save a bit of disk space (or a lot if
-    <literal>keep-outputs</literal> is also turned on).</para></listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-keep-env-derivations"><term><literal>keep-env-derivations</literal></term>
-
-    <listitem><para>If <literal>false</literal> (default), derivations
-    are not stored in Nix user environments.  That is, the derivations of
-    any build-time-only dependencies may be garbage-collected.</para>
-
-    <para>If <literal>true</literal>, when you add a Nix derivation to
-    a user environment, the path of the derivation is stored in the
-    user environment.  Thus, the derivation will not be
-    garbage-collected until the user environment generation is deleted
-    (<command>nix-env --delete-generations</command>).  To prevent
-    build-time-only dependencies from being collected, you should also
-    turn on <literal>keep-outputs</literal>.</para>
-
-    <para>The difference between this option and
-    <literal>keep-derivations</literal> is that this one is
-    “sticky”: it applies to any user environment created while this
-    option was enabled, while <literal>keep-derivations</literal>
-    only applies at the moment the garbage collector is
-    run.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id="conf-keep-outputs"><term><literal>keep-outputs</literal></term>
-
-    <listitem><para>If <literal>true</literal>, the garbage collector
-    will keep the outputs of non-garbage derivations.  If
-    <literal>false</literal> (default), outputs will be deleted unless
-    they are GC roots themselves (or reachable from other roots).</para>
-
-    <para>In general, outputs must be registered as roots separately.
-    However, even if the output of a derivation is registered as a
-    root, the collector will still delete store paths that are used
-    only at build time (e.g., the C compiler, or source tarballs
-    downloaded from the network).  To prevent it from doing so, set
-    this option to <literal>true</literal>.</para></listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-max-build-log-size"><term><literal>max-build-log-size</literal></term>
-
-    <listitem>
-
-      <para>This option defines the maximum number of bytes that a
-      builder can write to its stdout/stderr.  If the builder exceeds
-      this limit, it’s killed.  A value of <literal>0</literal> (the
-      default) means that there is no limit.</para>
-
-    </listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id="conf-max-free"><term><literal>max-free</literal></term>
-
-    <listitem><para>When a garbage collection is triggered by the
-    <literal>min-free</literal> option, it stops as soon as
-    <literal>max-free</literal> bytes are available. The default is
-    infinity (i.e. delete all garbage).</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id="conf-max-jobs"><term><literal>max-jobs</literal></term>
-
-    <listitem><para>This option defines the maximum number of jobs
-    that Nix will try to build in parallel.  The default is
-    <literal>1</literal>. The special value <literal>auto</literal>
-    causes Nix to use the number of CPUs in your system.  <literal>0</literal>
-    is useful when using remote builders to prevent any local builds (except for
-    <literal>preferLocalBuild</literal> derivation attribute which executes locally
-    regardless).  It can be
-    overridden using the <option
-    linkend='opt-max-jobs'>--max-jobs</option> (<option>-j</option>)
-    command line switch.</para>
-
-    <para>See also <xref linkend="chap-tuning-cores-and-jobs" />.</para>
-    </listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-max-silent-time"><term><literal>max-silent-time</literal></term>
-
-    <listitem>
-
-      <para>This option defines the maximum number of seconds that a
-      builder can go without producing any data on standard output or
-      standard error.  This is useful (for instance in an automated
-      build system) to catch builds that are stuck in an infinite
-      loop, or to catch remote builds that are hanging due to network
-      problems.  It can be overridden using the <option
-      linkend="opt-max-silent-time">--max-silent-time</option> command
-      line switch.</para>
-
-      <para>The value <literal>0</literal> means that there is no
-      timeout.  This is also the default.</para>
-
-    </listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id="conf-min-free"><term><literal>min-free</literal></term>
-
-    <listitem>
-      <para>When free disk space in <filename>/nix/store</filename>
-      drops below <literal>min-free</literal> during a build, Nix
-      performs a garbage-collection until <literal>max-free</literal>
-      bytes are available or there is no more garbage.  A value of
-      <literal>0</literal> (the default) disables this feature.</para>
-    </listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id="conf-narinfo-cache-negative-ttl"><term><literal>narinfo-cache-negative-ttl</literal></term>
-
-    <listitem>
-
-      <para>The TTL in seconds for negative lookups. If a store path is
-      queried from a substituter but was not found, there will be a
-      negative lookup cached in the local disk cache database for the
-      specified duration.</para>
-
-    </listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id="conf-narinfo-cache-positive-ttl"><term><literal>narinfo-cache-positive-ttl</literal></term>
-
-    <listitem>
-
-      <para>The TTL in seconds for positive lookups. If a store path is
-      queried from a substituter, the result of the query will be cached
-      in the local disk cache database including some of the NAR
-      metadata. The default TTL is a month, setting a shorter TTL for
-      positive lookups can be useful for binary caches that have
-      frequent garbage collection, in which case having a more frequent
-      cache invalidation would prevent trying to pull the path again and
-      failing with a hash mismatch if the build isn't reproducible.
-      </para>
-
-    </listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id="conf-netrc-file"><term><literal>netrc-file</literal></term>
-
-    <listitem><para>If set to an absolute path to a <filename>netrc</filename>
-    file, Nix will use the HTTP authentication credentials in this file when
-    trying to download from a remote host through HTTP or HTTPS. Defaults to
-    <filename>$NIX_CONF_DIR/netrc</filename>.</para>
-
-    <para>The <filename>netrc</filename> file consists of a list of
-    accounts in the following format:
-
-<screen>
-machine <replaceable>my-machine</replaceable>
-login <replaceable>my-username</replaceable>
-password <replaceable>my-password</replaceable>
-</screen>
-
-    For the exact syntax, see <link
-    xlink:href="https://ec.haxx.se/usingcurl-netrc.html">the
-    <literal>curl</literal> documentation.</link></para>
-
-    <note><para>This must be an absolute path, and <literal>~</literal>
-    is not resolved. For example, <filename>~/.netrc</filename> won't
-    resolve to your home directory's <filename>.netrc</filename>.</para></note>
-    </listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id="conf-plugin-files">
-    <term><literal>plugin-files</literal></term>
-    <listitem>
-      <para>
-        A list of plugin files to be loaded by Nix. Each of these
-        files will be dlopened by Nix, allowing them to affect
-        execution through static initialization. In particular, these
-        plugins may construct static instances of RegisterPrimOp to
-        add new primops or constants to the expression language,
-        RegisterStoreImplementation to add new store implementations,
-        RegisterCommand to add new subcommands to the
-        <literal>nix</literal> command, and RegisterSetting to add new
-        nix config settings. See the constructors for those types for
-        more details.
-      </para>
-      <para>
-        Since these files are loaded into the same address space as
-        Nix itself, they must be DSOs compatible with the instance of
-        Nix running at the time (i.e. compiled against the same
-        headers, not linked to any incompatible libraries). They
-        should not be linked to any Nix libs directly, as those will
-        be available already at load time.
-      </para>
-      <para>
-        If an entry in the list is a directory, all files in the
-        directory are loaded as plugins (non-recursively).
-      </para>
-    </listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id="conf-pre-build-hook"><term><literal>pre-build-hook</literal></term>
-
-    <listitem>
-
-
-      <para>If set, the path to a program that can set extra
-      derivation-specific settings for this system. This is used for settings
-      that can't be captured by the derivation model itself and are too variable
-      between different versions of the same system to be hard-coded into nix.
-      </para>
-
-      <para>The hook is passed the derivation path and, if sandboxes are enabled,
-      the sandbox directory. It can then modify the sandbox and send a series of
-      commands to modify various settings to stdout. The currently recognized
-      commands are:</para>
-
-      <variablelist>
-        <varlistentry xml:id="extra-sandbox-paths">
-          <term><literal>extra-sandbox-paths</literal></term>
-
-          <listitem>
-
-            <para>Pass a list of files and directories to be included in the
-            sandbox for this build. One entry per line, terminated by an empty
-            line. Entries have the same format as
-            <literal>sandbox-paths</literal>.</para>
-
-          </listitem>
-
-        </varlistentry>
-      </variablelist>
-    </listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id="conf-post-build-hook">
-    <term><literal>post-build-hook</literal></term>
-    <listitem>
-      <para>Optional. The path to a program to execute after each build.</para>
-
-      <para>This option is only settable in the global
-      <filename>nix.conf</filename>, or on the command line by trusted
-      users.</para>
-
-      <para>When using the nix-daemon, the daemon executes the hook as
-      <literal>root</literal>. If the nix-daemon is not involved, the
-      hook runs as the user executing the nix-build.</para>
-
-      <itemizedlist>
-        <listitem><para>The hook executes after an evaluation-time build.</para></listitem>
-        <listitem><para>The hook does not execute on substituted paths.</para></listitem>
-        <listitem><para>The hook's output always goes to the user's terminal.</para></listitem>
-        <listitem><para>If the hook fails, the build succeeds but no further builds execute.</para></listitem>
-        <listitem><para>The hook executes synchronously, and blocks other builds from progressing while it runs.</para></listitem>
-      </itemizedlist>
-
-      <para>The program executes with no arguments. The program's environment
-      contains the following environment variables:</para>
-
-      <variablelist>
-        <varlistentry>
-          <term><envar>DRV_PATH</envar></term>
-          <listitem>
-            <para>The derivation for the built paths.</para>
-            <para>Example:
-            <literal>/nix/store/5nihn1a7pa8b25l9zafqaqibznlvvp3f-bash-4.4-p23.drv</literal>
-            </para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
-          <term><envar>OUT_PATHS</envar></term>
-          <listitem>
-            <para>Output paths of the built derivation, separated by a space character.</para>
-            <para>Example:
-            <literal>/nix/store/zf5lbh336mnzf1nlswdn11g4n2m8zh3g-bash-4.4-p23-dev
-            /nix/store/rjxwxwv1fpn9wa2x5ssk5phzwlcv4mna-bash-4.4-p23-doc
-            /nix/store/6bqvbzjkcp9695dq0dpl5y43nvy37pq1-bash-4.4-p23-info
-            /nix/store/r7fng3kk3vlpdlh2idnrbn37vh4imlj2-bash-4.4-p23-man
-            /nix/store/xfghy8ixrhz3kyy6p724iv3cxji088dx-bash-4.4-p23</literal>.
-            </para>
-          </listitem>
-        </varlistentry>
-      </variablelist>
-
-      <para>See <xref linkend="chap-post-build-hook" /> for an example
-      implementation.</para>
-
-    </listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-repeat"><term><literal>repeat</literal></term>
-
-    <listitem><para>How many times to repeat builds to check whether
-    they are deterministic. The default value is 0. If the value is
-    non-zero, every build is repeated the specified number of
-    times. If the contents of any of the runs differs from the
-    previous ones and <xref linkend="conf-enforce-determinism" /> is
-    true, the build is rejected and the resulting store paths are not
-    registered as “valid” in Nix’s database.</para></listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-require-sigs"><term><literal>require-sigs</literal></term>
-
-    <listitem><para>If set to <literal>true</literal> (the default),
-    any non-content-addressed path added or copied to the Nix store
-    (e.g. when substituting from a binary cache) must have a valid
-    signature, that is, be signed using one of the keys listed in
-    <option>trusted-public-keys</option> or
-    <option>secret-key-files</option>. Set to <literal>false</literal>
-    to disable signature checking.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id="conf-restrict-eval"><term><literal>restrict-eval</literal></term>
-
-    <listitem>
-
-      <para>If set to <literal>true</literal>, the Nix evaluator will
-      not allow access to any files outside of the Nix search path (as
-      set via the <envar>NIX_PATH</envar> environment variable or the
-      <option>-I</option> option), or to URIs outside of
-      <option>allowed-uri</option>. The default is
-      <literal>false</literal>.</para>
-
-    </listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id="conf-run-diff-hook"><term><literal>run-diff-hook</literal></term>
-  <listitem>
-    <para>
-      If true, enable the execution of <xref linkend="conf-diff-hook" />.
-    </para>
-
-    <para>
-      When using the Nix daemon, <literal>run-diff-hook</literal> must
-      be set in the <filename>nix.conf</filename> configuration file,
-      and cannot be passed at the command line.
-    </para>
-  </listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-sandbox"><term><literal>sandbox</literal></term>
-
-    <listitem><para>If set to <literal>true</literal>, builds will be
-    performed in a <emphasis>sandboxed environment</emphasis>, i.e.,
-    they’re isolated from the normal file system hierarchy and will
-    only see their dependencies in the Nix store, the temporary build
-    directory, private versions of <filename>/proc</filename>,
-    <filename>/dev</filename>, <filename>/dev/shm</filename> and
-    <filename>/dev/pts</filename> (on Linux), and the paths configured with the
-    <link linkend='conf-sandbox-paths'><literal>sandbox-paths</literal>
-    option</link>. This is useful to prevent undeclared dependencies
-    on files in directories such as <filename>/usr/bin</filename>. In
-    addition, on Linux, builds run in private PID, mount, network, IPC
-    and UTS namespaces to isolate them from other processes in the
-    system (except that fixed-output derivations do not run in private
-    network namespace to ensure they can access the network).</para>
-
-    <para>Currently, sandboxing only work on Linux and macOS. The use
-    of a sandbox requires that Nix is run as root (so you should use
-    the <link linkend='conf-build-users-group'>“build users”
-    feature</link> to perform the actual builds under different users
-    than root).</para>
-
-    <para>If this option is set to <literal>relaxed</literal>, then
-    fixed-output derivations and derivations that have the
-    <varname>__noChroot</varname> attribute set to
-    <literal>true</literal> do not run in sandboxes.</para>
-
-    <para>The default is <literal>true</literal> on Linux and
-    <literal>false</literal> on all other platforms.</para>
-
-    </listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id="conf-sandbox-dev-shm-size"><term><literal>sandbox-dev-shm-size</literal></term>
-
-    <listitem><para>This option determines the maximum size of the
-    <literal>tmpfs</literal> filesystem mounted on
-    <filename>/dev/shm</filename> in Linux sandboxes. For the format,
-    see the description of the <option>size</option> option of
-    <literal>tmpfs</literal> in
-    <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>. The
-    default is <literal>50%</literal>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id="conf-sandbox-paths">
-    <term><literal>sandbox-paths</literal></term>
-
-    <listitem><para>A list of paths bind-mounted into Nix sandbox
-    environments. You can use the syntax
-    <literal><replaceable>target</replaceable>=<replaceable>source</replaceable></literal>
-    to mount a path in a different location in the sandbox; for
-    instance, <literal>/bin=/nix-bin</literal> will mount the path
-    <literal>/nix-bin</literal> as <literal>/bin</literal> inside the
-    sandbox. If <replaceable>source</replaceable> is followed by
-    <literal>?</literal>, then it is not an error if
-    <replaceable>source</replaceable> does not exist; for example,
-    <literal>/dev/nvidiactl?</literal> specifies that
-    <filename>/dev/nvidiactl</filename> will only be mounted in the
-    sandbox if it exists in the host filesystem.</para>
-
-    <para>Depending on how Nix was built, the default value for this option
-    may be empty or provide <filename>/bin/sh</filename> as a
-    bind-mount of <command>bash</command>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id="conf-secret-key-files"><term><literal>secret-key-files</literal></term>
-
-    <listitem><para>A whitespace-separated list of files containing
-    secret (private) keys. These are used to sign locally-built
-    paths. They can be generated using <command>nix-store
-    --generate-binary-cache-key</command>. The corresponding public
-    key can be distributed to other users, who can add it to
-    <option>trusted-public-keys</option> in their
-    <filename>nix.conf</filename>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id="conf-show-trace"><term><literal>show-trace</literal></term>
-
-    <listitem><para>Causes Nix to print out a stack trace in case of Nix
-    expression evaluation errors.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id="conf-substitute"><term><literal>substitute</literal></term>
-
-    <listitem><para>If set to <literal>true</literal> (default), Nix
-    will use binary substitutes if available.  This option can be
-    disabled to force building from source.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id="conf-stalled-download-timeout"><term><literal>stalled-download-timeout</literal></term>
-    <listitem>
-      <para>The timeout (in seconds) for receiving data from servers
-      during download. Nix cancels idle downloads after this timeout's
-      duration.</para>
-    </listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-substituters"><term><literal>substituters</literal></term>
-
-    <listitem><para>A list of URLs of substituters, separated by
-    whitespace.  The default is
-    <literal>https://cache.nixos.org</literal>.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id="conf-system"><term><literal>system</literal></term>
-
-    <listitem><para>This option specifies the canonical Nix system
-    name of the current installation, such as
-    <literal>i686-linux</literal> or
-    <literal>x86_64-darwin</literal>.  Nix can only build derivations
-    whose <literal>system</literal> attribute equals the value
-    specified here.  In general, it never makes sense to modify this
-    value from its default, since you can use it to ‘lie’ about the
-    platform you are building on (e.g., perform a Mac OS build on a
-    Linux machine; the result would obviously be wrong).  It only
-    makes sense if the Nix binaries can run on multiple platforms,
-    e.g., ‘universal binaries’ that run on <literal>x86_64-linux</literal> and
-    <literal>i686-linux</literal>.</para>
-
-    <para>It defaults to the canonical Nix system name detected by
-    <filename>configure</filename> at build time.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id="conf-system-features"><term><literal>system-features</literal></term>
-
-    <listitem><para>A set of system “features” supported by this
-    machine, e.g. <literal>kvm</literal>. Derivations can express a
-    dependency on such features through the derivation attribute
-    <varname>requiredSystemFeatures</varname>. For example, the
-    attribute
-
-<programlisting>
-requiredSystemFeatures = [ "kvm" ];
-</programlisting>
-
-    ensures that the derivation can only be built on a machine with
-    the <literal>kvm</literal> feature.</para>
-
-    <para>This setting by default includes <literal>kvm</literal> if
-    <filename>/dev/kvm</filename> is accessible, and the
-    pseudo-features <literal>nixos-test</literal>,
-    <literal>benchmark</literal> and <literal>big-parallel</literal>
-    that are used in Nixpkgs to route builds to specific
-    machines.</para>
-
-    </listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id="conf-tarball-ttl"><term><literal>tarball-ttl</literal></term>
-
-    <listitem>
-      <para>Default: <literal>3600</literal> seconds.</para>
-
-      <para>The number of seconds a downloaded tarball is considered
-      fresh. If the cached tarball is stale, Nix will check whether
-      it is still up to date using the ETag header. Nix will download
-      a new version if the ETag header is unsupported, or the
-      cached ETag doesn't match.
-      </para>
-
-      <para>Setting the TTL to <literal>0</literal> forces Nix to always
-      check if the tarball is up to date.</para>
-
-      <para>Nix caches tarballs in
-      <filename>$XDG_CACHE_HOME/nix/tarballs</filename>.</para>
-
-      <para>Files fetched via <envar>NIX_PATH</envar>,
-      <function>fetchGit</function>, <function>fetchMercurial</function>,
-      <function>fetchTarball</function>, and <function>fetchurl</function>
-      respect this TTL.
-      </para>
-    </listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-timeout"><term><literal>timeout</literal></term>
-
-    <listitem>
-
-      <para>This option defines the maximum number of seconds that a
-      builder can run.  This is useful (for instance in an automated
-      build system) to catch builds that are stuck in an infinite loop
-      but keep writing to their standard output or standard error.  It
-      can be overridden using the <option
-      linkend="opt-timeout">--timeout</option> command line
-      switch.</para>
-
-      <para>The value <literal>0</literal> means that there is no
-      timeout.  This is also the default.</para>
-
-    </listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id="conf-trace-function-calls"><term><literal>trace-function-calls</literal></term>
-
-    <listitem>
-
-      <para>Default: <literal>false</literal>.</para>
-
-      <para>If set to <literal>true</literal>, the Nix evaluator will
-      trace every function call. Nix will print a log message at the
-      "vomit" level for every function entrance and function exit.</para>
-
-      <informalexample><screen>
-function-trace entered undefined position at 1565795816999559622
-function-trace exited undefined position at 1565795816999581277
-function-trace entered /nix/store/.../example.nix:226:41 at 1565795253249935150
-function-trace exited /nix/store/.../example.nix:226:41 at 1565795253249941684
-</screen></informalexample>
-
-      <para>The <literal>undefined position</literal> means the function
-      call is a builtin.</para>
-
-      <para>Use the <literal>contrib/stack-collapse.py</literal> script
-      distributed with the Nix source code to convert the trace logs
-      in to a format suitable for <command>flamegraph.pl</command>.</para>
-
-    </listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id="conf-trusted-public-keys"><term><literal>trusted-public-keys</literal></term>
-
-    <listitem><para>A whitespace-separated list of public keys. When
-    paths are copied from another Nix store (such as a binary cache),
-    they must be signed with one of these keys. For example:
-    <literal>cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=
-    hydra.nixos.org-1:CNHJZBh9K4tP3EKF6FkkgeVYsS3ohTl+oS0Qa8bezVs=</literal>.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id="conf-trusted-substituters"><term><literal>trusted-substituters</literal></term>
-
-    <listitem><para>A list of URLs of substituters, separated by
-    whitespace.  These are not used by default, but can be enabled by
-    users of the Nix daemon by specifying <literal>--option
-    substituters <replaceable>urls</replaceable></literal> on the
-    command line.  Unprivileged users are only allowed to pass a
-    subset of the URLs listed in <literal>substituters</literal> and
-    <literal>trusted-substituters</literal>.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry xml:id="conf-trusted-users"><term><literal>trusted-users</literal></term>
-
-    <listitem>
-
-      <para>A list of names of users (separated by whitespace) that
-      have additional rights when connecting to the Nix daemon, such
-      as the ability to specify additional binary caches, or to import
-      unsigned NARs. You can also specify groups by prefixing them
-      with <literal>@</literal>; for instance,
-      <literal>@wheel</literal> means all users in the
-      <literal>wheel</literal> group. The default is
-      <literal>root</literal>.</para>
-
-      <warning><para>Adding a user to <option>trusted-users</option>
-      is essentially equivalent to giving that user root access to the
-      system. For example, the user can set
-      <option>sandbox-paths</option> and thereby obtain read access to
-      directories that are otherwise inacessible to
-      them.</para></warning>
-
-    </listitem>
-
-  </varlistentry>
-
-</variablelist>
-</para>
-
-<refsection>
-  <title>Deprecated Settings</title>
-
-<para>
-
-<variablelist>
-
-  <varlistentry xml:id="conf-binary-caches">
-    <term><literal>binary-caches</literal></term>
-
-    <listitem><para><emphasis>Deprecated:</emphasis>
-    <literal>binary-caches</literal> is now an alias to
-    <xref linkend="conf-substituters" />.</para></listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-binary-cache-public-keys">
-    <term><literal>binary-cache-public-keys</literal></term>
-
-    <listitem><para><emphasis>Deprecated:</emphasis>
-    <literal>binary-cache-public-keys</literal> is now an alias to
-    <xref linkend="conf-trusted-public-keys" />.</para></listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-build-compress-log">
-    <term><literal>build-compress-log</literal></term>
-
-    <listitem><para><emphasis>Deprecated:</emphasis>
-    <literal>build-compress-log</literal> is now an alias to
-    <xref linkend="conf-compress-build-log" />.</para></listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-build-cores">
-    <term><literal>build-cores</literal></term>
-
-    <listitem><para><emphasis>Deprecated:</emphasis>
-    <literal>build-cores</literal> is now an alias to
-    <xref linkend="conf-cores" />.</para></listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-build-extra-chroot-dirs">
-    <term><literal>build-extra-chroot-dirs</literal></term>
-
-    <listitem><para><emphasis>Deprecated:</emphasis>
-    <literal>build-extra-chroot-dirs</literal> is now an alias to
-    <xref linkend="conf-extra-sandbox-paths" />.</para></listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-build-extra-sandbox-paths">
-    <term><literal>build-extra-sandbox-paths</literal></term>
-
-    <listitem><para><emphasis>Deprecated:</emphasis>
-    <literal>build-extra-sandbox-paths</literal> is now an alias to
-    <xref linkend="conf-extra-sandbox-paths" />.</para></listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-build-fallback">
-    <term><literal>build-fallback</literal></term>
-
-    <listitem><para><emphasis>Deprecated:</emphasis>
-    <literal>build-fallback</literal> is now an alias to
-    <xref linkend="conf-fallback" />.</para></listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-build-max-jobs">
-    <term><literal>build-max-jobs</literal></term>
-
-    <listitem><para><emphasis>Deprecated:</emphasis>
-    <literal>build-max-jobs</literal> is now an alias to
-    <xref linkend="conf-max-jobs" />.</para></listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-build-max-log-size">
-    <term><literal>build-max-log-size</literal></term>
-
-    <listitem><para><emphasis>Deprecated:</emphasis>
-    <literal>build-max-log-size</literal> is now an alias to
-    <xref linkend="conf-max-build-log-size" />.</para></listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-build-max-silent-time">
-    <term><literal>build-max-silent-time</literal></term>
-
-    <listitem><para><emphasis>Deprecated:</emphasis>
-    <literal>build-max-silent-time</literal> is now an alias to
-    <xref linkend="conf-max-silent-time" />.</para></listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-build-repeat">
-    <term><literal>build-repeat</literal></term>
-
-    <listitem><para><emphasis>Deprecated:</emphasis>
-    <literal>build-repeat</literal> is now an alias to
-    <xref linkend="conf-repeat" />.</para></listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-build-timeout">
-    <term><literal>build-timeout</literal></term>
-
-    <listitem><para><emphasis>Deprecated:</emphasis>
-    <literal>build-timeout</literal> is now an alias to
-    <xref linkend="conf-timeout" />.</para></listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-build-use-chroot">
-    <term><literal>build-use-chroot</literal></term>
-
-    <listitem><para><emphasis>Deprecated:</emphasis>
-    <literal>build-use-chroot</literal> is now an alias to
-    <xref linkend="conf-sandbox" />.</para></listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-build-use-sandbox">
-    <term><literal>build-use-sandbox</literal></term>
-
-    <listitem><para><emphasis>Deprecated:</emphasis>
-    <literal>build-use-sandbox</literal> is now an alias to
-    <xref linkend="conf-sandbox" />.</para></listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-build-use-substitutes">
-    <term><literal>build-use-substitutes</literal></term>
-
-    <listitem><para><emphasis>Deprecated:</emphasis>
-    <literal>build-use-substitutes</literal> is now an alias to
-    <xref linkend="conf-substitute" />.</para></listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-gc-keep-derivations">
-    <term><literal>gc-keep-derivations</literal></term>
-
-    <listitem><para><emphasis>Deprecated:</emphasis>
-    <literal>gc-keep-derivations</literal> is now an alias to
-    <xref linkend="conf-keep-derivations" />.</para></listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-gc-keep-outputs">
-    <term><literal>gc-keep-outputs</literal></term>
-
-    <listitem><para><emphasis>Deprecated:</emphasis>
-    <literal>gc-keep-outputs</literal> is now an alias to
-    <xref linkend="conf-keep-outputs" />.</para></listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-env-keep-derivations">
-    <term><literal>env-keep-derivations</literal></term>
-
-    <listitem><para><emphasis>Deprecated:</emphasis>
-    <literal>env-keep-derivations</literal> is now an alias to
-    <xref linkend="conf-keep-env-derivations" />.</para></listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-extra-binary-caches">
-    <term><literal>extra-binary-caches</literal></term>
-
-    <listitem><para><emphasis>Deprecated:</emphasis>
-    <literal>extra-binary-caches</literal> is now an alias to
-    <xref linkend="conf-extra-substituters" />.</para></listitem>
-  </varlistentry>
-
-  <varlistentry xml:id="conf-trusted-binary-caches">
-    <term><literal>trusted-binary-caches</literal></term>
-
-    <listitem><para><emphasis>Deprecated:</emphasis>
-    <literal>trusted-binary-caches</literal> is now an alias to
-    <xref linkend="conf-trusted-substituters" />.</para></listitem>
-  </varlistentry>
-</variablelist>
-</para>
-</refsection>
-
-</refsection>
-
-</refentry>