<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-conf-file"> <title>Nix configuration file</title> <para>A number of persistent settings of Nix are stored in the file <filename><replaceable>prefix</replaceable>/etc/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. An example configuration file is shown in <xref linkend="ex-nix-conf" />.</para> <example xml:id='ex-nix-conf'><title>Nix configuration file</title> <programlisting> gc-keep-outputs = true # Nice for developers gc-keep-derivations = true # Idem env-keep-derivations = false </programlisting> </example> <para>The following variables 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 a Athlon 64 X2). It can be overriden using the <option linkend='opt-max-jobs'>--max-jobs</option> (<option>-j</option>) command line switch.</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 a 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 overriden 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-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>, or the uid that owns the setuid <command>nix-worker</command> program if <envar>NIX_REMOTE</envar> is <literal>slave</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 (using <command>mount --bind</command> on Linux) some directories from the normal file system hierarchy inside the chroot. These are the Nix store, the temporary build directory (usually <filename>/tmp/nix-<replaceable>pid</replaceable>-<replaceable>number</replaceable></filename>) and the directories listed here. The default is <literal>dev /proc</literal>. Files in <filename>/dev</filename> (such as <filename>/dev/null</filename>) are needed by many builds, and some files in <filename>/proc</filename> may also be needed occasionally.</para> <para>The value used on NixOS is <programlisting> build-use-chroot = /dev /proc /bin</programlisting> to make the <filename>/bin/sh</filename> symlink available (which is still needed by many builders).</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> </variablelist> </para> </section>