forked from lix-project/lix
1027 lines
40 KiB
XML
1027 lines
40 KiB
XML
<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">
|
||
|
||
<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>Nix reads settings from two configuration files:</para>
|
||
|
||
<itemizedlist>
|
||
|
||
<listitem>
|
||
<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.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>The user configuration file
|
||
<filename>$XDG_CONFIG_HOME/nix/nix.conf</filename>, or
|
||
<filename>~/.config/nix/nix.conf</filename> if
|
||
<envar>XDG_CONFIG_HOME</envar> is not set.</para>
|
||
</listitem>
|
||
|
||
</itemizedlist>
|
||
|
||
<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></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 derivation
|
||
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>This option defines after how many free bytes to stop collecting
|
||
garbage once the <literal>min-free</literal> condition gets triggered.</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></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 the disk reaches <literal>min-free</literal> bytes of free disk space during a build, nix
|
||
will start to garbage-collection until <literal>max-free</literal> bytes are available on the disk.
|
||
A value of <literal>0</literal> (the default) means that this feature is disabled.</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-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, 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-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>false</literal>.</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-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-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-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>
|