Manpages - nix3-help-stores.1

Stores are specified using a URL-like syntax. For example, the command

# nix path-info --store https://cache.nixos.org/ --json \
  /nix/store/a7gvj343m05j2s32xcnwr35v31ynlypr-coreutils-9.1

fetches information about a store path in the HTTP binary cache located at https://cache.nixos.org/, which is a type of store.

Store URLs can specify store settings using URL query strings, i.e. by appending ?name1=value1&name2=value2&... to the URL. For instance,

--store ssh://machine.example.org?ssh-key=/path/to/my/key

tells Nix to access the store on a remote machine via the SSH protocol, using /path/to/my/key as the SSH private key. The supported settings for each store type are documented below.

The special store URL auto causes Nix to automatically select a store as follows:

• Use the local store /nix/store if /nix/var/nix is writable by the current user.
• Otherwise, if /nix/var/nix/daemon-socket/socket exists, connect to the Nix daemon listening on that socket.
• Otherwise, on Linux only, use the local chroot store ~/.local/share/nix/root, which will be created automatically if it does not exist.
• Otherwise, use the local store /nix/store.

• path-info-cache-size Size of the in-memory store path metadata cache. Default: 65536
• priority Priority of this store when used as a substituter. A lower value means a higher priority. Default: 0
• store Logical location of the Nix store, usually /nix/store. Note that you can only copy store paths between stores if they have the same store setting. Default: /nix/store
• system-features Optional system features available on the system this store uses to build derivations. Example: "kvm" Default: machine-specific
• trusted Whether paths from this store can be used as substitutes even if they are not signed by a key listed in the trusted-public-keys setting. Default: false
• want-mass-query Whether this store can be queried efficiently for path validity when used as a substituter. Default: false

This is a more abstract/conceptual description of the parts of a layered store, an authoritative reference. For more “practical” instructions, see the worked-out example in the next subsection.

The parts of a local overlay store are as follows:

• Lower store:

  Specified with the lower-store setting.

  This is any store implementation that includes a store directory as part of the native operating system filesystem. For example, this could be a [local store], [local daemon store], or even another local overlay store.

  The local overlay store never tries to modify the lower store in any way. Something else could modify the lower store, but there are restrictions on this Nix itself requires that this store only grow, and not change in other ways. For example, new store objects can be added, but deleting or modifying store objects is not allowed in general, because that will confuse and corrupt any local overlay store using those objects. (In addition, the underlying filesystem overlay mechanism may impose additional restrictions, see below.)

  The lower store must not change while it is mounted as part of an overlay store. To ensure it does not, you might want to mount the store directory read-only (which then requires the [read-only] parameter to be set to true).

  • Lower store directory:

  Specified with lower-store.real setting.

  This is the directory used/exposed by the lower store.

  As specified above, Nix requires the local store can only grow not change in other ways. Linux's OverlayFS in addition imposes the further requirement that this directory cannot change at all. That means that, while any local overlay store exists that is using this store as a lower store, this directory must not change.

  • Lower metadata source:

  Not directly specified. A consequence of the lower-store setting, depending on the type of lower store chosen.

  This is abstract, just some way to read the metadata of lower store store objects. For example it could be a SQLite database (for the [local store]), or a socket connection (for the [local daemon store]).

  This need not be writable. As stated above a local overlay store never tries to modify its lower store. The lower store's metadata is considered part of the lower store, just as the store's file system objects that appear in the store directory are.

• Upper almost-store:

  Not directly specified. Instead the constituent parts are independently specified as described below.

  This is almost but not quite just a [local store]. That is because taken in isolation, not as part of a local overlay store, by itself, it would appear corrupted. But combined with everything else as part of an overlay local store, it is valid.

  • Upper layer directory:

  Specified with upper-layer setting.

  This contains additional store objects (or, strictly speaking, their file system objects that the local overlay store will extend the lower store with).

  • Upper store directory:

  Specified with the real setting. This the same as the base local store setting, and can also be indirectly specified with the root setting.

  This contains all the store objects from each of the two directories.

  The lower store directory and upper layer directory are combined via OverlayFS to create this directory. Nix doesn't do this itself, because it typically wouldn't have the permissions to do so, so it is the responsibility of the user to set this up first. Nix can, however, optionally check that that the OverlayFS mount settings appear as expected, matching Nix's own settings.

  • Upper SQLite database:

  Not directly specified. The location of the database instead depends on the state setting. It is is always ${state}/db.

  This contains the metadata of all of the upper layer store objects (everything beyond their file system objects), and also duplicate copies of some lower layer store object's metadta. The duplication is so the metadata for the closure of upper layer store objects can be found entirely within the upper layer. (This allows us to use the same SQL Schema as the [local store]'s SQLite database, as foreign keys in that schema enforce closure metadata to be self-contained in this way.)

Here is a worked out example of usage, following the concepts in the previous section.

Say we have the following paths:

• /mnt/example/merged-store/nix/store
• /mnt/example/store-a/nix/store
• /mnt/example/store-b

Then the following store URI can be used to access a local-overlay store at /mnt/example/merged-store:

local-overlay://?root=/mnt/example/merged-store&lower-store=/mnt/example/store-a&upper-layer=/mnt/example/store-b

The lower store directory is located at /mnt/example/store-a/nix/store, while the upper layer is at /mnt/example/store-b.

Before accessing the overlay store you will need to ensure the OverlayFS mount is set up correctly:

mount -t overlay overlay \
  -o lowerdir="/mnt/example/store-a/nix/store" \
  -o upperdir="/mnt/example/store-b" \
  -o workdir="/mnt/example/workdir" \
  "/mnt/example/merged-store/nix/store"

Note that OverlayFS requires /mnt/example/workdir to be on the same volume as the upperdir.

By default, Nix will check that the mountpoint as been set up correctly and fail with an error if it has not. You can override this behaviour by passing check-mount=false if you need to.

• check-mount Check that the overlay filesystem is correctly mounted. Nix does not manage the overlayfs mount point itself, but the correct functioning of the overlay store does depend on this mount point being set up correctly. Rather than just assume this is the case, check that the lowerdir and upperdir options are what we expect them to be. This check is on by default, but can be disabled if needed. Default: true
• log directory where Nix will store log files. Default: /nix/var/log/nix
• lower-store Store URL for the lower store. The default is auto (i.e. use the Nix daemon or /nix/store directly). Must be a store with a store dir on the file system. Must be used as OverlayFS lower layer for this store's store dir. Default: empty
• path-info-cache-size Size of the in-memory store path metadata cache. Default: 65536
• priority Priority of this store when used as a substituter. A lower value means a higher priority. Default: 0

• read-only

  Allow this store to be opened when its database is on a read-only filesystem.

  Normally Nix will attempt to open the store database in read-write mode, even for querying (when write access is not needed), causing it to fail if the database is on a read-only filesystem.

  Enable read-only mode to disable locking and open the SQLite database with the immutable parameter set.

  Warning Do not use this unless the filesystem is read-only.

  Using it when the filesystem is writable can cause incorrect query results or corruption errors if the database is changed by another process. While the filesystem the database resides on might appear to be read-only, consider whether another user or system might have write access to it.

  Default: false

• real Physical path of the Nix store. Default: /nix/store
• remount-hook Script or other executable to run when overlay filesystem needs remounting. This is occasionally necessary when deleting a store path that exists in both upper and lower layers. In such a situation, bypassing OverlayFS and deleting the path in the upper layer directly is the only way to perform the deletion without creating a “whiteout”. However this causes the OverlayFS kernel data structures to get out-of-sync, and can lead to ‘stale file handle' errors; remounting solves the problem. The store directory is passed as an argument to the invoked executable. Default: empty
• require-sigs Whether store paths copied into this store should have a trusted signature. Default: true
• root Directory prefixed to all other paths. Default: ``
• state Directory where Nix will store state. Default: /dummy
• store Logical location of the Nix store, usually /nix/store. Note that you can only copy store paths between stores if they have the same store setting. Default: /nix/store
• system-features Optional system features available on the system this store uses to build derivations. Example: "kvm" Default: machine-specific
• trusted Whether paths from this store can be used as substitutes even if they are not signed by a key listed in the trusted-public-keys setting. Default: false
• upper-layer Directory containing the OverlayFS upper layer for this store's store dir. Default: empty
• want-mass-query Whether this store can be queried efficiently for path validity when used as a substituter. Default: false

• base64-ssh-public-host-key The public host key of the remote machine. Default: empty
• compress Whether to enable SSH compression. Default: false
• log directory where Nix will store log files. Default: /nix/var/log/nix
• max-connection-age Maximum age of a connection before it is closed. Default: 4294967295
• max-connections Maximum number of concurrent connections to the Nix daemon. Default: 1
• path-info-cache-size Size of the in-memory store path metadata cache. Default: 65536
• priority Priority of this store when used as a substituter. A lower value means a higher priority. Default: 0
• real Physical path of the Nix store. Default: /nix/store
• remote-program Path to the nix-daemon executable on the remote machine. Default: nix-daemon
• remote-store Store URL to be used on the remote machine. The default is auto (i.e. use the Nix daemon or /nix/store directly). Default: empty
• root Directory prefixed to all other paths. Default: ``
• ssh-key Path to the SSH private key used to authenticate to the remote machine. Default: empty
• state Directory where Nix will store state. Default: /dummy
• store Logical location of the Nix store, usually /nix/store. Note that you can only copy store paths between stores if they have the same store setting. Default: /nix/store
• system-features Optional system features available on the system this store uses to build derivations. Example: "kvm" Default: machine-specific
• trusted Whether paths from this store can be used as substitutes even if they are not signed by a key listed in the trusted-public-keys setting. Default: false
• want-mass-query Whether this store can be queried efficiently for path validity when used as a substituter. Default: false

• base64-ssh-public-host-key The public host key of the remote machine. Default: empty
• compress Whether to enable SSH compression. Default: false
• max-connection-age Maximum age of a connection before it is closed. Default: 4294967295
• max-connections Maximum number of concurrent connections to the Nix daemon. Default: 1
• path-info-cache-size Size of the in-memory store path metadata cache. Default: 65536
• priority Priority of this store when used as a substituter. A lower value means a higher priority. Default: 0
• remote-program Path to the nix-daemon executable on the remote machine. Default: nix-daemon
• remote-store Store URL to be used on the remote machine. The default is auto (i.e. use the Nix daemon or /nix/store directly). Default: empty
• ssh-key Path to the SSH private key used to authenticate to the remote machine. Default: empty
• store Logical location of the Nix store, usually /nix/store. Note that you can only copy store paths between stores if they have the same store setting. Default: /nix/store
• system-features Optional system features available on the system this store uses to build derivations. Example: "kvm" Default: machine-specific
• trusted Whether paths from this store can be used as substitutes even if they are not signed by a key listed in the trusted-public-keys setting. Default: false
• want-mass-query Whether this store can be queried efficiently for path validity when used as a substituter. Default: false

• compression NAR compression method (xz, bzip2, gzip, zstd, or none). Default: xz
• compression-level The preset level to be used when compressing NARs. The meaning and accepted values depend on the compression method selected. -1 specifies that the default compression level should be used. Default: -1
• index-debug-info Whether to index DWARF debug info files by build ID. This allows dwarffs to fetch debug info on demand Default: false
• local-nar-cache Path to a local cache of NARs fetched from this binary cache, used by commands such as nix store cat. Default: empty
• parallel-compression Enable multi-threaded compression of NARs. This is currently only available for xz and zstd. Default: false
• path-info-cache-size Size of the in-memory store path metadata cache. Default: 65536
• priority Priority of this store when used as a substituter. A lower value means a higher priority. Default: 0
• secret-key Path to the secret key used to sign the binary cache. Default: empty
• store Logical location of the Nix store, usually /nix/store. Note that you can only copy store paths between stores if they have the same store setting. Default: /nix/store
• system-features Optional system features available on the system this store uses to build derivations. Example: "kvm" Default: machine-specific
• trusted Whether paths from this store can be used as substitutes even if they are not signed by a key listed in the trusted-public-keys setting. Default: false
• want-mass-query Whether this store can be queried efficiently for path validity when used as a substituter. Default: false
• write-nar-listing Whether to write a JSON file that lists the files in each NAR. Default: false

• compression NAR compression method (xz, bzip2, gzip, zstd, or none). Default: xz
• compression-level The preset level to be used when compressing NARs. The meaning and accepted values depend on the compression method selected. -1 specifies that the default compression level should be used. Default: -1
• index-debug-info Whether to index DWARF debug info files by build ID. This allows dwarffs to fetch debug info on demand Default: false
• local-nar-cache Path to a local cache of NARs fetched from this binary cache, used by commands such as nix store cat. Default: empty
• parallel-compression Enable multi-threaded compression of NARs. This is currently only available for xz and zstd. Default: false
• path-info-cache-size Size of the in-memory store path metadata cache. Default: 65536
• priority Priority of this store when used as a substituter. A lower value means a higher priority. Default: 0
• secret-key Path to the secret key used to sign the binary cache. Default: empty
• store Logical location of the Nix store, usually /nix/store. Note that you can only copy store paths between stores if they have the same store setting. Default: /nix/store
• system-features Optional system features available on the system this store uses to build derivations. Example: "kvm" Default: machine-specific
• trusted Whether paths from this store can be used as substitutes even if they are not signed by a key listed in the trusted-public-keys setting. Default: false
• want-mass-query Whether this store can be queried efficiently for path validity when used as a substituter. Default: false
• write-nar-listing Whether to write a JSON file that lists the files in each NAR. Default: false

• log directory where Nix will store log files. Default: /nix/var/log/nix
• max-connection-age Maximum age of a connection before it is closed. Default: 4294967295
• max-connections Maximum number of concurrent connections to the Nix daemon. Default: 1
• path-info-cache-size Size of the in-memory store path metadata cache. Default: 65536
• priority Priority of this store when used as a substituter. A lower value means a higher priority. Default: 0
• real Physical path of the Nix store. Default: /nix/store
• root Directory prefixed to all other paths. Default: ``
• state Directory where Nix will store state. Default: /dummy
• store Logical location of the Nix store, usually /nix/store. Note that you can only copy store paths between stores if they have the same store setting. Default: /nix/store
• system-features Optional system features available on the system this store uses to build derivations. Example: "kvm" Default: machine-specific
• trusted Whether paths from this store can be used as substitutes even if they are not signed by a key listed in the trusted-public-keys setting. Default: false
• want-mass-query Whether this store can be queried efficiently for path validity when used as a substituter. Default: false

• log directory where Nix will store log files. Default: /nix/var/log/nix
• path-info-cache-size Size of the in-memory store path metadata cache. Default: 65536
• priority Priority of this store when used as a substituter. A lower value means a higher priority. Default: 0

• read-only

  Allow this store to be opened when its database is on a read-only filesystem.

  Normally Nix will attempt to open the store database in read-write mode, even for querying (when write access is not needed), causing it to fail if the database is on a read-only filesystem.

  Enable read-only mode to disable locking and open the SQLite database with the immutable parameter set.

  Warning Do not use this unless the filesystem is read-only.

  Using it when the filesystem is writable can cause incorrect query results or corruption errors if the database is changed by another process. While the filesystem the database resides on might appear to be read-only, consider whether another user or system might have write access to it.

  Default: false

• real Physical path of the Nix store. Default: /nix/store
• require-sigs Whether store paths copied into this store should have a trusted signature. Default: true
• root Directory prefixed to all other paths. Default: ``
• state Directory where Nix will store state. Default: /dummy
• store Logical location of the Nix store, usually /nix/store. Note that you can only copy store paths between stores if they have the same store setting. Default: /nix/store
• system-features Optional system features available on the system this store uses to build derivations. Example: "kvm" Default: machine-specific
• trusted Whether paths from this store can be used as substitutes even if they are not signed by a key listed in the trusted-public-keys setting. Default: false
• want-mass-query Whether this store can be queried efficiently for path validity when used as a substituter. Default: false

If your binary cache is publicly accessible and does not require authentication, it is simplest to use the [HTTP Binary Cache Store] rather than S3 Binary Cache Store with https://example-nix-cache.s3.amazonaws.com instead of s3://example-nix-cache.

Your bucket will need a bucket policy like the following to be accessible:

{
    "Id": "DirectReads",
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowDirectReads",
            "Action": [
                "s3:GetObject",
                "s3:GetBucketLocation"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:s3:::example-nix-cache",
                "arn:aws:s3:::example-nix-cache/*"
            ],
            "Principal": "*"
        }
    ]
}

Nix will use the default credential provider chain for authenticating requests to Amazon S3.

Note that this means Nix will read environment variables and files with different idioms than with Nix's own settings, as implemented by the AWS SDK. Consult the documentation linked above for further details.

Your bucket will need a bucket policy allowing the desired users to perform the s3:GetObject and s3:GetBucketLocation action on all objects in the bucket. The anonymous policy given above can be updated to have a restricted Principal to support this.

Your account will need an IAM policy to support uploading to the bucket:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "UploadToCache",
      "Effect": "Allow",
      "Action": [
        "s3:AbortMultipartUpload",
        "s3:GetBucketLocation",
        "s3:GetObject",
        "s3:ListBucket",
        "s3:ListBucketMultipartUploads",
        "s3:ListMultipartUploadParts",
        "s3:PutObject"
      ],
      "Resource": [
        "arn:aws:s3:::example-nix-cache",
        "arn:aws:s3:::example-nix-cache/*"
      ]
    }
  ]
}

With bucket policies and authentication set up as described above, uploading works via nix copy (experimental).

• To upload with a specific credential profile for Amazon S3:

$ nix copy nixpkgs.hello \
--to 's3://example-nix-cache?profile=cache-upload&region=eu-west-2'

• To upload to an S3-compatible binary cache:

$ nix copy nixpkgs.hello --to \
's3://example-nix-cache?profile=cache-upload&scheme=https&endpoint=minio.example.com'

• buffer-size Size (in bytes) of each part in multi-part uploads. Default: 5242880
• compression NAR compression method (xz, bzip2, gzip, zstd, or none). Default: xz
• compression-level The preset level to be used when compressing NARs. The meaning and accepted values depend on the compression method selected. -1 specifies that the default compression level should be used. Default: -1

• endpoint

  The URL of the endpoint of an S3-compatible service such as MinIO. Do not specify this setting if you're using Amazon S3.

  Note

  This endpoint must support HTTPS and will use path-based addressing instead of virtual host based addressing.

  Default: empty

• index-debug-info Whether to index DWARF debug info files by build ID. This allows dwarffs to fetch debug info on demand Default: false
• local-nar-cache Path to a local cache of NARs fetched from this binary cache, used by commands such as nix store cat. Default: empty
• log-compression Compression method for log/* files. It is recommended to use a compression method supported by most web browsers (e.g. brotli). Default: empty
• ls-compression Compression method for .ls files. Default: empty
• multipart-upload Whether to use multi-part uploads. Default: false
• narinfo-compression Compression method for .narinfo files. Default: empty
• parallel-compression Enable multi-threaded compression of NARs. This is currently only available for xz and zstd. Default: false
• path-info-cache-size Size of the in-memory store path metadata cache. Default: 65536
• priority Priority of this store when used as a substituter. A lower value means a higher priority. Default: 0
• profile The name of the AWS configuration profile to use. By default Nix will use the default profile. Default: empty
• region The region of the S3 bucket. If your bucket is not in us–east-1, you should always explicitly specify the region parameter. Default: us-east-1

• scheme

  The scheme used for S3 requests, https (default) or http. This option allows you to disable HTTPS for binary caches which don't support it.

  Note

  HTTPS should be used if the cache might contain sensitive information.

  Default: empty

• secret-key Path to the secret key used to sign the binary cache. Default: empty
• store Logical location of the Nix store, usually /nix/store. Note that you can only copy store paths between stores if they have the same store setting. Default: /nix/store
• system-features Optional system features available on the system this store uses to build derivations. Example: "kvm" Default: machine-specific
• trusted Whether paths from this store can be used as substitutes even if they are not signed by a key listed in the trusted-public-keys setting. Default: false
• want-mass-query Whether this store can be queried efficiently for path validity when used as a substituter. Default: false
• write-nar-listing Whether to write a JSON file that lists the files in each NAR. Default: false

• base64-ssh-public-host-key The public host key of the remote machine. Default: empty
• compress Whether to enable SSH compression. Default: false
• max-connections Maximum number of concurrent SSH connections. Default: 1
• path-info-cache-size Size of the in-memory store path metadata cache. Default: 65536
• priority Priority of this store when used as a substituter. A lower value means a higher priority. Default: 0
• remote-program Path to the nix-store executable on the remote machine. Default: nix-store
• remote-store Store URL to be used on the remote machine. The default is auto (i.e. use the Nix daemon or /nix/store directly). Default: empty
• ssh-key Path to the SSH private key used to authenticate to the remote machine. Default: empty
• store Logical location of the Nix store, usually /nix/store. Note that you can only copy store paths between stores if they have the same store setting. Default: /nix/store
• system-features Optional system features available on the system this store uses to build derivations. Example: "kvm" Default: machine-specific
• trusted Whether paths from this store can be used as substitutes even if they are not signed by a key listed in the trusted-public-keys setting. Default: false
• want-mass-query Whether this store can be queried efficiently for path validity when used as a substituter. Default: false

• --debug Set the logging verbosity level to ‘debug'.
• --log-format format Set the format of log output; one of raw, internal-json, bar or bar-with-logs.
• --print-build-logs / -L Print full build logs on standard error.
• --quiet Decrease the logging verbosity level.
• --verbose / -v Increase the logging verbosity level.

• --help Show usage information.
• --offline Disable substituters and consider all previously downloaded files up-to-date.
• --option name value Set the Nix configuration setting name to value (overriding nix.conf).
• --refresh Consider all previously downloaded files out-of-date.
• --version Show version information. Note See man nix.conf for overriding configuration settings with command line flags.