diff options
Diffstat (limited to 'doc/manual/command-ref/conf-file.xml')
| -rw-r--r-- | doc/manual/command-ref/conf-file.xml | 1236 |
1 files changed, 0 insertions, 1236 deletions
diff --git a/doc/manual/command-ref/conf-file.xml b/doc/manual/command-ref/conf-file.xml deleted file mode 100644 index d0f1b09ca..000000000 --- a/doc/manual/command-ref/conf-file.xml +++ /dev/null @@ -1,1236 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<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" - version="5"> - -<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>By default Nix reads settings from the following places:</para> - -<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. Values loaded in this file are not forwarded to the Nix daemon. The -client assumes that the daemon has already loaded them. -</para> - -<para>User-specific configuration files:</para> - -<para> - If <envar>NIX_USER_CONF_FILES</envar> is set, then each path separated by - <literal>:</literal> will be loaded in reverse order. -</para> - -<para> - Otherwise it will look for <filename>nix/nix.conf</filename> files in - <envar>XDG_CONFIG_DIRS</envar> and <envar>XDG_CONFIG_HOME</envar>. - - The default location is <filename>$HOME/.config/nix.conf</filename> if - those environment variables are unset. -</para> - -<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> - - <para>See also <xref linkend="chap-tuning-cores-and-jobs" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-diff-hook"><term><literal>diff-hook</literal></term> - <listitem> - <para> - Absolute path to an executable capable of diffing build results. - The hook executes if <xref linkend="conf-run-diff-hook" /> is - true, and the output of a build is known to not be the same. - This program is not executed to determine if two results are the - same. - </para> - - <para> - The diff hook is executed by the same user and group who ran the - build. However, the diff hook does not have write access to the - store path just built. - </para> - - <para>The diff hook program receives three parameters:</para> - - <orderedlist> - <listitem> - <para> - A path to the previous build's results - </para> - </listitem> - - <listitem> - <para> - A path to the current build's results - </para> - </listitem> - - <listitem> - <para> - The path to the build's derivation - </para> - </listitem> - - <listitem> - <para> - The path to the build's scratch directory. This directory - will exist only if the build was run with - <option>--keep-failed</option>. - </para> - </listitem> - </orderedlist> - - <para> - The stderr and stdout output from the diff hook will not be - displayed to the user. Instead, it will print to the nix-daemon's - log. - </para> - - <para>When using the Nix daemon, <literal>diff-hook</literal> must - be set in the <filename>nix.conf</filename> configuration file, and - cannot be passed at the command line. - </para> - </listitem> - </varlistentry> - - <varlistentry xml:id="conf-enforce-determinism"> - <term><literal>enforce-determinism</literal></term> - - <listitem><para>See <xref linkend="conf-repeat" />.</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. - 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 hashed mirror - <literal>http://tarballs.example.com/</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.example.com/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 derivations of - 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>When a garbage collection is triggered by the - <literal>min-free</literal> option, it stops as soon as - <literal>max-free</literal> bytes are available. The default is - infinity (i.e. delete all garbage).</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> - - <para>See also <xref linkend="chap-tuning-cores-and-jobs" />.</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 free disk space in <filename>/nix/store</filename> - drops below <literal>min-free</literal> during a build, Nix - performs a garbage-collection until <literal>max-free</literal> - bytes are available or there is no more garbage. A value of - <literal>0</literal> (the default) disables this feature.</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-post-build-hook"> - <term><literal>post-build-hook</literal></term> - <listitem> - <para>Optional. The path to a program to execute after each build.</para> - - <para>This option is only settable in the global - <filename>nix.conf</filename>, or on the command line by trusted - users.</para> - - <para>When using the nix-daemon, the daemon executes the hook as - <literal>root</literal>. If the nix-daemon is not involved, the - hook runs as the user executing the nix-build.</para> - - <itemizedlist> - <listitem><para>The hook executes after an evaluation-time build.</para></listitem> - <listitem><para>The hook does not execute on substituted paths.</para></listitem> - <listitem><para>The hook's output always goes to the user's terminal.</para></listitem> - <listitem><para>If the hook fails, the build succeeds but no further builds execute.</para></listitem> - <listitem><para>The hook executes synchronously, and blocks other builds from progressing while it runs.</para></listitem> - </itemizedlist> - - <para>The program executes with no arguments. The program's environment - contains the following environment variables:</para> - - <variablelist> - <varlistentry> - <term><envar>DRV_PATH</envar></term> - <listitem> - <para>The derivation for the built paths.</para> - <para>Example: - <literal>/nix/store/5nihn1a7pa8b25l9zafqaqibznlvvp3f-bash-4.4-p23.drv</literal> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><envar>OUT_PATHS</envar></term> - <listitem> - <para>Output paths of the built derivation, separated by a space character.</para> - <para>Example: - <literal>/nix/store/zf5lbh336mnzf1nlswdn11g4n2m8zh3g-bash-4.4-p23-dev - /nix/store/rjxwxwv1fpn9wa2x5ssk5phzwlcv4mna-bash-4.4-p23-doc - /nix/store/6bqvbzjkcp9695dq0dpl5y43nvy37pq1-bash-4.4-p23-info - /nix/store/r7fng3kk3vlpdlh2idnrbn37vh4imlj2-bash-4.4-p23-man - /nix/store/xfghy8ixrhz3kyy6p724iv3cxji088dx-bash-4.4-p23</literal>. - </para> - </listitem> - </varlistentry> - </variablelist> - - <para>See <xref linkend="chap-post-build-hook" /> for an example - implementation.</para> - - </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 and <xref linkend="conf-enforce-determinism" /> is - true, 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-run-diff-hook"><term><literal>run-diff-hook</literal></term> - <listitem> - <para> - If true, enable the execution of <xref linkend="conf-diff-hook" />. - </para> - - <para> - When using the Nix daemon, <literal>run-diff-hook</literal> must - be set in the <filename>nix.conf</filename> configuration file, - and cannot be passed at the command line. - </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>true</literal> on Linux and - <literal>false</literal> on all other platforms.</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-stalled-download-timeout"><term><literal>stalled-download-timeout</literal></term> - <listitem> - <para>The timeout (in seconds) for receiving data from servers - during download. Nix cancels idle downloads after this timeout's - duration.</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-tarball-ttl"><term><literal>tarball-ttl</literal></term> - - <listitem> - <para>Default: <literal>3600</literal> seconds.</para> - - <para>The number of seconds a downloaded tarball is considered - fresh. If the cached tarball is stale, Nix will check whether - it is still up to date using the ETag header. Nix will download - a new version if the ETag header is unsupported, or the - cached ETag doesn't match. - </para> - - <para>Setting the TTL to <literal>0</literal> forces Nix to always - check if the tarball is up to date.</para> - - <para>Nix caches tarballs in - <filename>$XDG_CACHE_HOME/nix/tarballs</filename>.</para> - - <para>Files fetched via <envar>NIX_PATH</envar>, - <function>fetchGit</function>, <function>fetchMercurial</function>, - <function>fetchTarball</function>, and <function>fetchurl</function> - respect this TTL. - </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-trace-function-calls"><term><literal>trace-function-calls</literal></term> - - <listitem> - - <para>Default: <literal>false</literal>.</para> - - <para>If set to <literal>true</literal>, the Nix evaluator will - trace every function call. Nix will print a log message at the - "vomit" level for every function entrance and function exit.</para> - - <informalexample><screen> -function-trace entered undefined position at 1565795816999559622 -function-trace exited undefined position at 1565795816999581277 -function-trace entered /nix/store/.../example.nix:226:41 at 1565795253249935150 -function-trace exited /nix/store/.../example.nix:226:41 at 1565795253249941684 -</screen></informalexample> - - <para>The <literal>undefined position</literal> means the function - call is a builtin.</para> - - <para>Use the <literal>contrib/stack-collapse.py</literal> script - distributed with the Nix source code to convert the trace logs - in to a format suitable for <command>flamegraph.pl</command>.</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> |