From efdb89994c2ee79763320d70fb4ba881d0e3b1e8 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Thu, 23 Jul 2020 10:56:15 +0200 Subject: [PATCH] Convert nix.conf manpage --- doc/manual/command-ref/conf-file.xml | 43 +- doc/manual/local.mk | 6 +- doc/manual/src/SUMMARY.md | 2 + doc/manual/src/command-ref/conf-file.md | 727 ++++++++++++++++++++++++ doc/manual/src/command-ref/files.md | 4 + 5 files changed, 763 insertions(+), 19 deletions(-) create mode 100644 doc/manual/src/command-ref/conf-file.md create mode 100644 doc/manual/src/command-ref/files.md diff --git a/doc/manual/command-ref/conf-file.xml b/doc/manual/command-ref/conf-file.xml index ff9c7d46c..4c103f505 100644 --- a/doc/manual/command-ref/conf-file.xml +++ b/doc/manual/command-ref/conf-file.xml @@ -21,28 +21,35 @@ By default Nix reads settings from the following places: -The system-wide configuration file -sysconfdir/nix/nix.conf -(i.e. /etc/nix/nix.conf on most systems), or -$NIX_CONF_DIR/nix.conf if -NIX_CONF_DIR is set. Values loaded in this file are not forwarded to the Nix daemon. The -client assumes that the daemon has already loaded them. - + -User-specific configuration files: + + + The system-wide configuration file + sysconfdir/nix/nix.conf + (i.e. /etc/nix/nix.conf on most systems), + or $NIX_CONF_DIR/nix.conf if + NIX_CONF_DIR is set. Values loaded in this + file are not forwarded to the Nix daemon. The client assumes + that the daemon has already loaded them. + + - - If NIX_USER_CONF_FILES is set, then each path separated by - : will be loaded in reverse order. - + + + If NIX_USER_CONF_FILES is set, then each path separated by + : will be loaded in reverse order. + - - Otherwise it will look for nix/nix.conf files in - XDG_CONFIG_DIRS and XDG_CONFIG_HOME. + + Otherwise it will look for nix/nix.conf + files in XDG_CONFIG_DIRS and + XDG_CONFIG_HOME. If these are unset, it will + look in $HOME/.config/nix.conf. + + - The default location is $HOME/.config/nix.conf if - those environment variables are unset. - + The configuration files consist of name = diff --git a/doc/manual/local.mk b/doc/manual/local.mk index 65acd658c..80c517702 100644 --- a/doc/manual/local.mk +++ b/doc/manual/local.mk @@ -12,7 +12,8 @@ dist-files += $(d)/version.txt # Generate man pages. man-pages := $(foreach n, \ - nix-copy-closure.1, \ + nix-copy-closure.1 \ + nix.conf.5, \ $(d)/$(n)) # nix-env.1 nix-build.1 nix-shell.1 nix-store.1 nix-instantiate.1 \ # nix-collect-garbage.1, \ @@ -27,6 +28,9 @@ dist-files += $(man-pages) $(d)/nix-copy-closure.1: $(d)/src/command-ref/nix-copy-closure.md $(trace-gen) lowdown -sT man $^ -o $@ +$(d)/nix.conf.5: $(d)/src/command-ref/conf-file.md + $(trace-gen) lowdown -sT man $^ -o $@ + # Generate the HTML manual. install: $(docdir)/manual/index.html diff --git a/doc/manual/src/SUMMARY.md b/doc/manual/src/SUMMARY.md index f9ef1b060..e8baf489b 100644 --- a/doc/manual/src/SUMMARY.md +++ b/doc/manual/src/SUMMARY.md @@ -49,6 +49,8 @@ - [Common Environment Variables](command-ref/env-common.md) - [Utilities](command-ref/utilities.md) - [nix-copy-closure](command-ref/nix-copy-closure.md) + - [Files](command-ref/files.md) + - [nix.conf](command-ref/conf-file.md) - [Glossary](glossary.md) - [Hacking](hacking.md) - [Release Notes](release-notes/release-notes.md) diff --git a/doc/manual/src/command-ref/conf-file.md b/doc/manual/src/command-ref/conf-file.md new file mode 100644 index 000000000..3f84373e2 --- /dev/null +++ b/doc/manual/src/command-ref/conf-file.md @@ -0,0 +1,727 @@ +nix.conf + +5 + +Nix + +nix.conf + +Nix configuration file + +# Description + +By default Nix reads settings from the following places: + + - The system-wide configuration file `sysconfdir/nix/nix.conf` (i.e. + `/etc/nix/nix.conf` on most systems), or `$NIX_CONF_DIR/nix.conf` if + `NIX_CONF_DIR` is set. Values loaded in this file are not forwarded + to the Nix daemon. The client assumes that the daemon has already + loaded them. + + - If `NIX_USER_CONF_FILES` is set, then each path separated by `:` + will be loaded in reverse order. + + Otherwise it will look for `nix/nix.conf` files in `XDG_CONFIG_DIRS` + and `XDG_CONFIG_HOME`. If these are unset, it will look in + `$HOME/.config/nix.conf`. + +The configuration files consist of `name = +value` pairs, one per line. Other files can be included with a line like +`include +path`, where path is interpreted relative to the current conf file and a +missing file is an error unless `!include` is used instead. Comments +start with a `#` character. Here is an example configuration file: + + keep-outputs = true # Nice for developers + keep-derivations = true # Idem + +You can override settings on the command line using the `--option` flag, +e.g. `--option keep-outputs +false`. + +The following settings are currently available: + + - `allowed-uris` + A list of URI prefixes to which access is allowed in restricted + evaluation mode. For example, when set to + `https://github.com/NixOS`, builtin functions such as `fetchGit` are + allowed to access `https://github.com/NixOS/patchelf.git`. + + - `allow-import-from-derivation` + By default, Nix allows you to `import` 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. + + - `allow-new-privileges` + (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 `sudo` or `ping` + will fail. (Note that in sandbox builds, no such programs are + available unless you bind-mount them into the sandbox via the + `sandbox-paths` 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). + + - `allowed-users` + A list of names of users (separated by whitespace) that are allowed + to connect to the Nix daemon. As with the `trusted-users` option, + you can specify groups by prefixing them with `@`. Also, you can + allow all users by specifying `*`. The default is `*`. + + Note that trusted users are always allowed to connect. + + - `auto-optimise-store` + If set to `true`, 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 `false` (the default), + you can still run `nix-store + --optimise` to get rid of duplicate files. + + - `builders` + A list of machines on which to perform builds. See + [???](#chap-distributed-builds) for details. + + - `builders-use-substitutes` + If set to `true`, 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 `cache.nixos.org`), + 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 + `false`. + + - `build-users-group` + 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. + + 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 `/etc/group`). Those user + accounts should not be used for any other purpose\! + + 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.) + + The build users should have permission to create files in the Nix + store, but not delete them. Therefore, `/nix/store` should be owned + by the Nix account, its group should be the group specified here, + and its mode should be `1775`. + + 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 + `NIX_REMOTE` is empty, the uid under which the Nix daemon runs if + `NIX_REMOTE` is `daemon`). Obviously, this should not be used in + multi-user settings with untrusted users. + + - `compress-build-log` + If set to `true` (the default), build logs written to + `/nix/var/log/nix/drvs` will be compressed on the fly using bzip2. + Otherwise, they will not be compressed. + + - `connect-timeout` + The timeout (in seconds) for establishing connections in the binary + cache substituter. It corresponds to `curl`’s `--connect-timeout` + option. + + - `cores` + Sets the value of the `NIX_BUILD_CORES` 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 + `enableParallelBuilding` is set to `true`, the builder passes the + `-jN` flag to GNU Make. It can be overridden using the `--cores` + command line switch and defaults to `1`. The value `0` means that + the builder should use all available CPU cores in the system. + + See also [???](#chap-tuning-cores-and-jobs). + + - `diff-hook` + Absolute path to an executable capable of diffing build results. The + hook executes if [varlistentry\_title](#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. + + 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. + + The diff hook program receives three parameters: + + 1. A path to the previous build's results + + 2. A path to the current build's results + + 3. The path to the build's derivation + + 4. The path to the build's scratch directory. This directory will + exist only if the build was run with `--keep-failed`. + + 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. + + When using the Nix daemon, `diff-hook` must be set in the `nix.conf` + configuration file, and cannot be passed at the command line. + + - `enforce-determinism` + See [varlistentry\_title](#conf-repeat). + + - `extra-sandbox-paths` + A list of additional paths appended to `sandbox-paths`. Useful if + you want to extend its default value. + + - `extra-platforms` + 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. + + - `extra-substituters` + Additional binary caches appended to those specified in + `substituters`. When used by unprivileged users, untrusted + substituters (i.e. those not listed in `trusted-substituters`) are + silently ignored. + + - `fallback` + If set to `true`, Nix will fall back to building from source if a + binary substitute fails. This is equivalent to the `--fallback` + flag. The default is `false`. + + - `fsync-metadata` + If set to `true`, changes to the Nix store metadata (in + `/nix/var/nix/db`) are synchronously flushed to disk. This improves + robustness in case of system crashes, but reduces performance. The + default is `true`. + + - `hashed-mirrors` + A list of web servers used by `builtins.fetchurl` to obtain files by + hash. The default is `http://tarballs.nixos.org/`. Given a hash type + ht and a base-16 hash h, Nix will try to download the file from + `hashed-mirror/ht/h`. This allows files to be downloaded even if + they have disappeared from their original URI. For example, given + the default mirror `http://tarballs.nixos.org/`, when building the + derivation + + builtins.fetchurl { + url = "https://example.org/foo-1.2.3.tar.xz"; + sha256 = "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"; + } + + Nix will attempt to download this file from + `http://tarballs.nixos.org/sha256/2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae` + first. If it is not available there, if will try the original URI. + + - `http-connections` + 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. + + - `keep-build-log` + If set to `true` (the default), Nix will write the build log of a + derivation (i.e. the standard output and error of its builder) to + the directory `/nix/var/log/nix/drvs`. The build log can be + retrieved using the command `nix-store -l + path`. + + - `keep-derivations` + If `true` (default), the garbage collector will keep the derivations + from which non-garbage store paths were built. If `false`, they will + be deleted unless explicitly registered as a root (or reachable from + other roots). + + 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 `keep-outputs` is also + turned on). + + - `keep-env-derivations` + If `false` (default), derivations are not stored in Nix user + environments. That is, the derivations of any build-time-only + dependencies may be garbage-collected. + + If `true`, 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 (`nix-env --delete-generations`). To prevent + build-time-only dependencies from being collected, you should also + turn on `keep-outputs`. + + The difference between this option and `keep-derivations` is that + this one is “sticky”: it applies to any user environment created + while this option was enabled, while `keep-derivations` only applies + at the moment the garbage collector is run. + + - `keep-outputs` + If `true`, the garbage collector will keep the outputs of + non-garbage derivations. If `false` (default), outputs will be + deleted unless they are GC roots themselves (or reachable from other + roots). + + 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 `true`. + + - `max-build-log-size` + 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 `0` (the default) means that there is no limit. + + - `max-free` + When a garbage collection is triggered by the `min-free` option, it + stops as soon as `max-free` bytes are available. The default is + infinity (i.e. delete all garbage). + + - `max-jobs` + This option defines the maximum number of jobs that Nix will try to + build in parallel. The default is `1`. The special value `auto` + causes Nix to use the number of CPUs in your system. `0` is useful + when using remote builders to prevent any local builds (except for + `preferLocalBuild` derivation attribute which executes locally + regardless). It can be overridden using the `--max-jobs` (`-j`) + command line switch. + + See also [???](#chap-tuning-cores-and-jobs). + + - `max-silent-time` + 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 `--max-silent-time` command line switch. + + The value `0` means that there is no timeout. This is also the + default. + + - `min-free` + When free disk space in `/nix/store` drops below `min-free` during a + build, Nix performs a garbage-collection until `max-free` bytes are + available or there is no more garbage. A value of `0` (the default) + disables this feature. + + - `narinfo-cache-negative-ttl` + 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. + + - `narinfo-cache-positive-ttl` + 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. + + - `netrc-file` + If set to an absolute path to a `netrc` 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 + `$NIX_CONF_DIR/netrc`. + + The `netrc` file consists of a list of accounts in the following + format: + + machine my-machine + login my-username + password my-password + + For the exact syntax, see [the `curl` + documentation.](https://ec.haxx.se/usingcurl-netrc.html) + + > **Note** + > + > This must be an absolute path, and `~` is not resolved. For + > example, `~/.netrc` won't resolve to your home directory's + > `.netrc`. + + - `plugin-files` + 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 `nix` + command, and RegisterSetting to add new nix config settings. See the + constructors for those types for more details. + + 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. + + If an entry in the list is a directory, all files in the directory + are loaded as plugins (non-recursively). + + - `pre-build-hook` + 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. + + 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: + + - `extra-sandbox-paths` + 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 `sandbox-paths`. + + - `post-build-hook` + Optional. The path to a program to execute after each build. + + This option is only settable in the global `nix.conf`, or on the + command line by trusted users. + + When using the nix-daemon, the daemon executes the hook as `root`. + If the nix-daemon is not involved, the hook runs as the user + executing the nix-build. + + - The hook executes after an evaluation-time build. + + - The hook does not execute on substituted paths. + + - The hook's output always goes to the user's terminal. + + - If the hook fails, the build succeeds but no further builds + execute. + + - The hook executes synchronously, and blocks other builds from + progressing while it runs. + + The program executes with no arguments. The program's environment + contains the following environment variables: + + - `DRV_PATH` + The derivation for the built paths. + + Example: + `/nix/store/5nihn1a7pa8b25l9zafqaqibznlvvp3f-bash-4.4-p23.drv` + + - `OUT_PATHS` + Output paths of the built derivation, separated by a space + character. + + Example: + `/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`. + + See [???](#chap-post-build-hook) for an example implementation. + + - `repeat` + 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 + [varlistentry\_title](#conf-enforce-determinism) is true, the build + is rejected and the resulting store paths are not registered as + “valid” in Nix’s database. + + - `require-sigs` + If set to `true` (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 `trusted-public-keys` or `secret-key-files`. Set + to `false` to disable signature checking. + + - `restrict-eval` + If set to `true`, the Nix evaluator will not allow access to any + files outside of the Nix search path (as set via the `NIX_PATH` + environment variable or the `-I` option), or to URIs outside of + `allowed-uri`. The default is `false`. + + - `run-diff-hook` + If true, enable the execution of + [varlistentry\_title](#conf-diff-hook). + + When using the Nix daemon, `run-diff-hook` must be set in the + `nix.conf` configuration file, and cannot be passed at the command + line. + + - `sandbox` + If set to `true`, builds will be performed in a *sandboxed + environment*, 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 `/proc`, `/dev`, + `/dev/shm` and `/dev/pts` (on Linux), and the paths configured with + the [`sandbox-paths` option](#conf-sandbox-paths). This is useful to + prevent undeclared dependencies on files in directories such as + `/usr/bin`. 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). + + 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 + [“build users” feature](#conf-build-users-group) to perform the + actual builds under different users than root). + + If this option is set to `relaxed`, then fixed-output derivations + and derivations that have the `__noChroot` attribute set to `true` + do not run in sandboxes. + + The default is `true` on Linux and `false` on all other platforms. + + - `sandbox-dev-shm-size` + This option determines the maximum size of the `tmpfs` filesystem + mounted on `/dev/shm` in Linux sandboxes. For the format, see the + description of the `size` option of `tmpfs` in mount8. The default + is `50%`. + + - `sandbox-paths` + A list of paths bind-mounted into Nix sandbox environments. You can + use the syntax `target=source` to mount a path in a different + location in the sandbox; for instance, `/bin=/nix-bin` will mount + the path `/nix-bin` as `/bin` inside the sandbox. If source is + followed by `?`, then it is not an error if source does not exist; + for example, `/dev/nvidiactl?` specifies that `/dev/nvidiactl` will + only be mounted in the sandbox if it exists in the host filesystem. + + Depending on how Nix was built, the default value for this option + may be empty or provide `/bin/sh` as a bind-mount of `bash`. + + - `secret-key-files` + A whitespace-separated list of files containing secret (private) + keys. These are used to sign locally-built paths. They can be + generated using `nix-store + --generate-binary-cache-key`. The corresponding public key can be + distributed to other users, who can add it to `trusted-public-keys` + in their `nix.conf`. + + - `show-trace` + Causes Nix to print out a stack trace in case of Nix expression + evaluation errors. + + - `substitute` + If set to `true` (default), Nix will use binary substitutes if + available. This option can be disabled to force building from + source. + + - `stalled-download-timeout` + The timeout (in seconds) for receiving data from servers during + download. Nix cancels idle downloads after this timeout's duration. + + - `substituters` + A list of URLs of substituters, separated by whitespace. The default + is `https://cache.nixos.org`. + + - `system` + This option specifies the canonical Nix system name of the current + installation, such as `i686-linux` or `x86_64-darwin`. Nix can only + build derivations whose `system` 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 `x86_64-linux` and `i686-linux`. + + It defaults to the canonical Nix system name detected by `configure` + at build time. + + - `system-features` + A set of system “features” supported by this machine, e.g. `kvm`. + Derivations can express a dependency on such features through the + derivation attribute `requiredSystemFeatures`. For example, the + attribute + + requiredSystemFeatures = [ "kvm" ]; + + ensures that the derivation can only be built on a machine with the + `kvm` feature. + + This setting by default includes `kvm` if `/dev/kvm` is accessible, + and the pseudo-features `nixos-test`, `benchmark` and `big-parallel` + that are used in Nixpkgs to route builds to specific machines. + + - `tarball-ttl` + Default: `3600` seconds. + + 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. + + Setting the TTL to `0` forces Nix to always check if the tarball is + up to date. + + Nix caches tarballs in `$XDG_CACHE_HOME/nix/tarballs`. + + Files fetched via `NIX_PATH`, `fetchGit`, `fetchMercurial`, + `fetchTarball`, and `fetchurl` respect this TTL. + + - `timeout` + 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 `--timeout` command line switch. + + The value `0` means that there is no timeout. This is also the + default. + + - `trace-function-calls` + Default: `false`. + + If set to `true`, 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. + +
+ + 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 + +
+ + The `undefined position` means the function call is a builtin. + + Use the `contrib/stack-collapse.py` script distributed with the Nix + source code to convert the trace logs in to a format suitable for + `flamegraph.pl`. + + - `trusted-public-keys` + 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: + `cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= + hydra.nixos.org-1:CNHJZBh9K4tP3EKF6FkkgeVYsS3ohTl+oS0Qa8bezVs=`. + + - `trusted-substituters` + 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 `--option + substituters urls` on the command line. Unprivileged users are only + allowed to pass a subset of the URLs listed in `substituters` and + `trusted-substituters`. + + - `trusted-users` + 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 `@`; for + instance, `@wheel` means all users in the `wheel` group. The default + is `root`. + + > **Warning** + > + > Adding a user to `trusted-users` is essentially equivalent to + > giving that user root access to the system. For example, the user + > can set `sandbox-paths` and thereby obtain read access to + > directories that are otherwise inacessible to them. + +## Deprecated Settings + + - `binary-caches` + *Deprecated:* `binary-caches` is now an alias to + [varlistentry\_title](#conf-substituters). + + - `binary-cache-public-keys` + *Deprecated:* `binary-cache-public-keys` is now an alias to + [varlistentry\_title](#conf-trusted-public-keys). + + - `build-compress-log` + *Deprecated:* `build-compress-log` is now an alias to + [varlistentry\_title](#conf-compress-build-log). + + - `build-cores` + *Deprecated:* `build-cores` is now an alias to + [varlistentry\_title](#conf-cores). + + - `build-extra-chroot-dirs` + *Deprecated:* `build-extra-chroot-dirs` is now an alias to + [varlistentry\_title](#conf-extra-sandbox-paths). + + - `build-extra-sandbox-paths` + *Deprecated:* `build-extra-sandbox-paths` is now an alias to + [varlistentry\_title](#conf-extra-sandbox-paths). + + - `build-fallback` + *Deprecated:* `build-fallback` is now an alias to + [varlistentry\_title](#conf-fallback). + + - `build-max-jobs` + *Deprecated:* `build-max-jobs` is now an alias to + [varlistentry\_title](#conf-max-jobs). + + - `build-max-log-size` + *Deprecated:* `build-max-log-size` is now an alias to + [varlistentry\_title](#conf-max-build-log-size). + + - `build-max-silent-time` + *Deprecated:* `build-max-silent-time` is now an alias to + [varlistentry\_title](#conf-max-silent-time). + + - `build-repeat` + *Deprecated:* `build-repeat` is now an alias to + [varlistentry\_title](#conf-repeat). + + - `build-timeout` + *Deprecated:* `build-timeout` is now an alias to + [varlistentry\_title](#conf-timeout). + + - `build-use-chroot` + *Deprecated:* `build-use-chroot` is now an alias to + [varlistentry\_title](#conf-sandbox). + + - `build-use-sandbox` + *Deprecated:* `build-use-sandbox` is now an alias to + [varlistentry\_title](#conf-sandbox). + + - `build-use-substitutes` + *Deprecated:* `build-use-substitutes` is now an alias to + [varlistentry\_title](#conf-substitute). + + - `gc-keep-derivations` + *Deprecated:* `gc-keep-derivations` is now an alias to + [varlistentry\_title](#conf-keep-derivations). + + - `gc-keep-outputs` + *Deprecated:* `gc-keep-outputs` is now an alias to + [varlistentry\_title](#conf-keep-outputs). + + - `env-keep-derivations` + *Deprecated:* `env-keep-derivations` is now an alias to + [varlistentry\_title](#conf-keep-env-derivations). + + - `extra-binary-caches` + *Deprecated:* `extra-binary-caches` is now an alias to + [varlistentry\_title](#conf-extra-substituters). + + - `trusted-binary-caches` + *Deprecated:* `trusted-binary-caches` is now an alias to + [varlistentry\_title](#conf-trusted-substituters). diff --git a/doc/manual/src/command-ref/files.md b/doc/manual/src/command-ref/files.md new file mode 100644 index 000000000..df5646c05 --- /dev/null +++ b/doc/manual/src/command-ref/files.md @@ -0,0 +1,4 @@ +# Files + +This section lists configuration files that you can use when you work +with Nix.