446 lines
18 KiB
XML
446 lines
18 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>A number of persistent settings of Nix are stored in the file
|
||
<filename><replaceable>sysconfdir</replaceable>/nix/nix.conf</filename>.
|
||
This file is a list of <literal><replaceable>name</replaceable> =
|
||
<replaceable>value</replaceable></literal> pairs, one per line.
|
||
Comments start with a <literal>#</literal> character. Here is an example
|
||
configuration file:</para>
|
||
|
||
<programlisting>
|
||
gc-keep-outputs = true # Nice for developers
|
||
gc-keep-derivations = true # Idem
|
||
env-keep-derivations = false
|
||
</programlisting>
|
||
|
||
<para>You can override settings using the <option>--option</option>
|
||
flag, e.g. <literal>--option gc-keep-outputs false</literal>.</para>
|
||
|
||
<para>The following settings are currently available:
|
||
|
||
<variablelist>
|
||
|
||
|
||
<varlistentry xml:id="conf-gc-keep-outputs"><term><literal>gc-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-gc-keep-derivations"><term><literal>gc-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 safe a bit of disk space (or a lot if
|
||
<literal>gc-keep-outputs</literal> is also turned on).</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
|
||
<varlistentry><term><literal>env-keep-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>gc-keep-outputs</literal>.</para>
|
||
|
||
<para>The difference between this option and
|
||
<literal>gc-keep-derivations</literal> is that this one is
|
||
“sticky”: it applies to any user environment created while this
|
||
option was enabled, while <literal>gc-keep-derivations</literal>
|
||
only applies at the moment the garbage collector is
|
||
run.</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
|
||
<varlistentry xml:id="conf-build-max-jobs"><term><literal>build-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>. You should generally set it to the number
|
||
of CPUs in your system (e.g., <literal>2</literal> on an Athlon 64
|
||
X2). 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-build-cores"><term><literal>build-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-build-max-silent-time"><term><literal>build-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-build-timeout"><term><literal>build-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-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><term><literal>build-use-chroot</literal></term>
|
||
|
||
<listitem><para>If set to <literal>true</literal>, builds will be
|
||
performed in a <emphasis>chroot environment</emphasis>, i.e., the
|
||
build will be isolated from the normal file system hierarchy and
|
||
will only see the Nix store, the temporary build directory, and
|
||
the directories configured with the <link
|
||
linkend='conf-build-chroot-dirs'><literal>build-chroot-dirs</literal>
|
||
option</link> (such as <filename>/proc</filename> and
|
||
<filename>/dev</filename>). This is useful to prevent undeclared
|
||
dependencies on files in directories such as
|
||
<filename>/usr/bin</filename>.</para>
|
||
|
||
<para>The use of a chroot requires that Nix is run as root (but
|
||
you can still use the <link
|
||
linkend='conf-build-users-group'>“build users” feature</link> to
|
||
perform builds under different users than root). Currently,
|
||
chroot builds only work on Linux because Nix uses “bind mounts” to
|
||
make the Nix store and other directories available inside the
|
||
chroot.</para>
|
||
|
||
</listitem>
|
||
|
||
</varlistentry>
|
||
|
||
|
||
<varlistentry xml:id="conf-build-chroot-dirs"><term><literal>build-chroot-dirs</literal></term>
|
||
|
||
<listitem><para>When builds are performed in a chroot environment,
|
||
Nix will mount some directories from the normal file system
|
||
hierarchy inside the chroot. These are the Nix store, the
|
||
temporary build directory (usually
|
||
<filename>/tmp/nix-build-<replaceable>drvname</replaceable>-<replaceable>number</replaceable></filename>),
|
||
the <literal>/proc</literal> filesystem, and the directories
|
||
listed here. The default is <literal>/dev /dev/pts</literal>,
|
||
since these contain files needed by many builds (such as
|
||
<filename>/dev/null</filename>). You can use the syntax
|
||
<literal><replaceable>target</replaceable>=<replaceable>source</replaceable></literal>
|
||
to mount a path in a different location in the chroot; for
|
||
instance, <literal>/bin=/nix-bin</literal> will mount the
|
||
directory <literal>/nix-bin</literal> as <literal>/bin</literal>
|
||
inside the chroot.</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
|
||
<varlistentry><term><literal>build-use-substitutes</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><term><literal>build-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><term><literal>build-cache-failures</literal></term>
|
||
|
||
<listitem><para>If set to <literal>true</literal>, Nix will
|
||
“cache” build failures, meaning that it will remember (in its
|
||
database) that a derivation previously failed. If you then try to
|
||
build the derivation again, Nix will immediately fail rather than
|
||
perform the build again. Failures in fixed-output derivations
|
||
(such as <function>fetchurl</function> calls) are never cached.
|
||
The “failed” status of a derivation can be cleared using
|
||
<command>nix-store --clear-failed-paths</command>. By default,
|
||
failure caching is disabled.</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
|
||
<varlistentry><term><literal>build-keep-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><term><literal>build-compress-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><term><literal>use-binary-caches</literal></term>
|
||
|
||
<listitem><para>If set to <literal>true</literal> (the default),
|
||
Nix will check the binary caches specified by
|
||
<option>binary-caches</option> and related options to obtain
|
||
binary substitutes.</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
|
||
<varlistentry><term><literal>binary-caches</literal></term>
|
||
|
||
<listitem><para>A list of URLs of binary caches, separated by
|
||
whitespace. The default is
|
||
<literal>http://cache.nixos.org</literal>.</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
|
||
<varlistentry><term><literal>binary-caches-files</literal></term>
|
||
|
||
<listitem><para>A list of names of files that will be read to
|
||
obtain additional binary cache URLs. The default is
|
||
<literal>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/channels/binary-caches/*</literal>.
|
||
Note that when you’re using the Nix daemon,
|
||
<replaceable>username</replaceable> is always equal to
|
||
<literal>root</literal>, so Nix will only use the binary caches
|
||
provided by the channels installed by root. Do not set this
|
||
option to read files created by untrusted users!</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
|
||
<varlistentry><term><literal>trusted-binary-caches</literal></term>
|
||
|
||
<listitem><para>A list of URLs of binary caches, separated by
|
||
whitespace. These are not used by default, but can be enabled by
|
||
users of the Nix daemon by specifying <literal>--option
|
||
binary-caches <replaceable>urls</replaceable></literal> on the
|
||
command line. Unprivileged users are only allowed to pass a
|
||
subset of the URLs listed in <literal>binary-caches</literal> and
|
||
<literal>trusted-binary-caches</literal>.</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
|
||
<varlistentry><term><literal>extra-binary-caches</literal></term>
|
||
|
||
<listitem><para>Additional binary caches appended to those
|
||
specified in <option>binary-caches</option> and
|
||
<option>binary-caches-files</option>. When used by unprivileged
|
||
users, untrusted binary caches (i.e. those not listed in
|
||
<option>trusted-binary-caches</option>) are silently
|
||
ignored.</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
|
||
<varlistentry><term><literal>binary-caches-parallel-connections</literal></term>
|
||
|
||
<listitem><para>The maximum number of parallel HTTP connections
|
||
used by the binary cache substituter to get NAR info files. This
|
||
number should be high to minimise latency. It defaults to
|
||
150.</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
|
||
<varlistentry><term><literal>force-manifest</literal></term>
|
||
|
||
<listitem><para>If this option is set to <literal>false</literal>
|
||
(default) and a Nix channel provides both a manifest and a binary
|
||
cache, only the binary cache will be used. If set to
|
||
<literal>true</literal>, the manifest will be fetched as well.
|
||
This is useful if you want to use binary patches (which are
|
||
currently not supported by binary caches).</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
|
||
<varlistentry><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>powerpc-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>powerpc-darwin</literal> and
|
||
<literal>i686-darwin</literal>.</para>
|
||
|
||
<para>It defaults to the canonical Nix system name detected by
|
||
<filename>configure</filename> at build time.</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
|
||
<varlistentry><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><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>
|
||
|
||
|
||
</variablelist>
|
||
|
||
</para>
|
||
|
||
</refsection>
|
||
|
||
</refentry>
|