diff --git a/doc/manual/source/SUMMARY.md.in b/doc/manual/source/SUMMARY.md.in index 8b6b29f6a7f..1a2a2acfbff 100644 --- a/doc/manual/source/SUMMARY.md.in +++ b/doc/manual/source/SUMMARY.md.in @@ -135,6 +135,7 @@ - [Serving Tarball Flakes](protocols/tarball-fetcher.md) - [Store Path Specification](protocols/store-path.md) - [Nix Archive (NAR) Format](protocols/nix-archive/index.md) + - [Nix Cache Info Format](protocols/nix-cache-info.md) - [Derivation "ATerm" file format](protocols/derivation-aterm.md) - [C API](c-api.md) - [Glossary](glossary.md) diff --git a/doc/manual/source/package-management/binary-cache-substituter.md b/doc/manual/source/package-management/binary-cache-substituter.md index 855eaf4705a..e6a772213d6 100644 --- a/doc/manual/source/package-management/binary-cache-substituter.md +++ b/doc/manual/source/package-management/binary-cache-substituter.md @@ -19,17 +19,16 @@ whatever port you like: $ nix-serve -p 8080 ``` -To check whether it works, try the following on the client: +To check whether it works, try fetching the [`nix-cache-info`](@docroot@/protocols/nix-cache-info.md) file on the client: ```console $ curl http://avalon:8080/nix-cache-info +StoreDir: /nix/store +WantMassQuery: 1 +Priority: 30 ``` -which should print something like: - - StoreDir: /nix/store - WantMassQuery: 1 - Priority: 30 +When writing to a binary cache (e.g., with [`nix copy`](@docroot@/command-ref/new-cli/nix3-copy.md)), Nix creates [`nix-cache-info`](@docroot@/protocols/nix-cache-info.md) automatically if it doesn't exist. On the client side, you can tell Nix to use your binary cache using `--substituters`, e.g.: diff --git a/doc/manual/source/protocols/nix-cache-info.md b/doc/manual/source/protocols/nix-cache-info.md new file mode 100644 index 00000000000..e8351e1cebe --- /dev/null +++ b/doc/manual/source/protocols/nix-cache-info.md @@ -0,0 +1,55 @@ +# Nix Cache Info Format + +The `nix-cache-info` file is a metadata file at the root of a [binary cache](@docroot@/package-management/binary-cache-substituter.md) (e.g., `https://cache.example.com/nix-cache-info`). + +MIME type: `text/x-nix-cache-info` + +## Format + +Line-based key-value format: + +``` +Key: value +``` + +Leading and trailing whitespace is trimmed from values. +Lines without a colon are ignored. +Unknown keys are silently ignored. + +## Fields + +### `StoreDir` + +The Nix store directory path that this cache was built for (e.g., `/nix/store`). + +If present, Nix verifies that this matches the client's store directory: + +``` +error: binary cache 'https://example.com' is for Nix stores with prefix '/nix/store', not '/home/user/nix/store' +``` + +### `WantMassQuery` + +`1` or `0`. Sets the default for [`want-mass-query`](@docroot@/store/types/http-binary-cache-store.md#store-http-binary-cache-store-want-mass-query). + +### `Priority` + +Integer. Sets the default for [`priority`](@docroot@/store/types/http-binary-cache-store.md#store-http-binary-cache-store-priority). + +## Example + +``` +StoreDir: /nix/store +WantMassQuery: 1 +Priority: 30 +``` + +## Caching Behavior + +Nix caches `nix-cache-info` in the [cache directory](@docroot@/command-ref/env-common.md#env-NIX_CACHE_HOME) with a 7-day TTL. + +## See Also + +- [HTTP Binary Cache Store](@docroot@/store/types/http-binary-cache-store.md) +- [Serving a Nix store via HTTP](@docroot@/package-management/binary-cache-substituter.md) +- [`substituters`](@docroot@/command-ref/conf-file.md#conf-substituters)