diff options
Diffstat (limited to 'doc/manual/conf-file.xml')
| -rw-r--r-- | doc/manual/conf-file.xml | 474 |
1 files changed, 0 insertions, 474 deletions
diff --git a/doc/manual/conf-file.xml b/doc/manual/conf-file.xml deleted file mode 100644 index 327d22c4a1..0000000000 --- a/doc/manual/conf-file.xml +++ /dev/null @@ -1,474 +0,0 @@ -<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> - - - <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> - - -</variablelist> - -</para> - -</refsection> - -</refentry> |