diff options
Diffstat (limited to 'doc/manual/conf-file.xml')
| -rw-r--r-- | doc/manual/conf-file.xml | 460 |
1 files changed, 460 insertions, 0 deletions
diff --git a/doc/manual/conf-file.xml b/doc/manual/conf-file.xml new file mode 100644 index 000000000000..c832108fed06 --- /dev/null +++ b/doc/manual/conf-file.xml @@ -0,0 +1,460 @@ +<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-max-log-size"><term><literal>build-max-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-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> |