```{eval-rst}
.. index:: configuration file
```

# Configuration Reference

When running the zb command-line interface,
zb will gather configuration data from files in the local filesystem.
Command-line flags or environment variables will override any settings in the configuration files.

## Format

zb reads its configuration in [JSON With Commas and Comments][JWCC] format.
This is a strict superset of JSON that permits:

- trailing commas in arrays and objects
- C++ style `/* block comments */` and `// line comments`

[JWCC]: https://nigeltao.github.io/blog/2021/json-with-commas-comments.html

```{eval-rst}
.. index:: configuration file; location
```

## Location

zb will read configuration from the following locations
(in decreasing order of precedence):

1. Files specified by the {option}`--config option <zb --config>`.
2. Files specified by the {envvar}`ZB_CONFIG_FILE` environment variable.
3. Files in operating-system-specific locations (documented below).

### Per-Invocation

Individual invocations of the zb CLI can override configuration
with command-line flags or environment variables:

```{program} zb
```

:::{option} --config <file>

The `--config` option specifies a configuration file that zb will read.
The option may be passed multiple times in increasing order of precedence.

:::

:::{envvar} ZB_CONFIG_FILE

The `ZB_CONFIG_FILE` environment variable can be set to a list of configuration files
that zb will read in decreasing order of precedence.
On Linux and macOS, the files are separated by colons (`:`).
On Windows, the files are separated by semicolons (`;`).

:::

### Linux and macOS

On Linux and macOS systems, zb follows the [XDG Base Directory Specification][]
to find its configuration files.
The files used are (in decreasing order of precedence):

1. `$XDG_CONFIG_HOME/zb/config.jwcc`.
   If `$XDG_CONFIG_HOME` is not set, it defaults to `$HOME/.config`.
2. `$XDG_CONFIG_HOME/zb/config.json`.
   If `$XDG_CONFIG_HOME` is not set, it defaults to `$HOME/.config`.
3. For each directory in `$XDG_CONFIG_DIRS` separated by colons
   (defaulting to `/etc/xdg`):
    a. `zb/config.jwcc` underneath the directory
    b. `zb/config.json` underneath the directory

[XDG Base Directory Specification]: https://specifications.freedesktop.org/basedir/0.8/

### Windows

On Windows systems, zb will find configuration files at (in decreasing order of precedence):

1. `%AppData%\zb\config.jwcc`
2. `%AppData%\zb\config.json`

## Properties

:::{confval} debug
:type: boolean
:default: `false`

Whether to include logging useful for debugging zb itself.
This is generally very verbose and should only be enabled if you are reporting an issue with zb.
Equivalent to the `--debug` command-line flag.

:::

:::{confval} storeDirectory
:type: string
:default: >
: `/opt/zb/store` on Linux and macOS,
: `C:\zb\store` on Windows

Absolute path to the store directory.

Will be overridden by {envvar}`ZB_STORE_DIR`.

:::

:::{confval} storeSocket
:type: string
:default: >
: `/opt/zb/var/zb/server.sock` on Linux and macOS,
: `C:\zb\var\zb\server.sock` on Windows

Absolute path of the store server Unix socket to use or,
in the case of `zb serve`, to create.

Will be overridden by {envvar}`ZB_STORE_SOCKET`.

:::

:::{confval} cacheDB
:type: string
:default: >
: `$XDG_CACHE_HOME/zb/cache.db` on Linux and macOS.
: (`$XDG_CACHE_HOME` defaults to `$HOME/.cache`.)
: `%LocalAppData%\zb\cache.db` on Windows.

Absolute path to a SQLite database that contains cache data for speeding up zb.
This database can be deleted at any time: it exists purely to speed up builds.

Equivalent to the `--cache` command-line flag.

:::

:::

:::{confval} httpCache
:type: string
:default: >
: `$XDG_CACHE_HOME/zb/http-cache.db` on Linux and macOS.
: (`$XDG_CACHE_HOME` defaults to `$HOME/.cache`.)
: `%LocalAppData%\zb\http-cache.db` on Windows.

Absolute path to a SQLite database that stores cached HTTP responses.
This database can be deleted at any time: it exists purely to speed up builds
and reduce network bandwidth usage.

Equivalent to the `--http-cache` command-line flag.

:::

:::{confval} allowEnvironment
:type: boolean or array of string
:default: `false`

The `allowEnvironment` setting configures the behavior of {lua:func}`os.getenv`.

- If `true`, then {lua:func}`os.getenv` can retrieve any environment variable
  in the zb process's environment.
  Equivalent to passing `--allow-all-env` on the command line.
- If `false`, then {lua:func}`os.getenv` will always return `nil`.
- If the setting is an array,
  then it is interpreted as a set of environment variable names
  that {lua:func}`os.getenv` will retrieve from the zb process's environment.
  {lua:func}`os.getenv` will return `nil`
  for any environment variable whose name is not in the array.
  Equivalent to passing `--allow-env` with each name on the command line.

`allowEnvironment` settings are not merged:
the setting from the file with the highest precedence will be used.

:::

:::{confval} trustedPublicKeys
:type: array of objects
:default: `[]`

The `trustedPublicKeys` setting is an array of public keys that zb will trust for existing build results
when building a {term}`derivation`.
`trustedPublicKeys` settings are merged across all configuration files.
Each public key is a JSON object with the following properties:

| Name        | Type   | Description                               |
| :---------- | :----- | :---------------------------------------- |
| `format`    | string | Only `"ed25519"` is defined at the moment |
| `publicKey` | string | Base64-encoded public key data            |

For more details on the content of these properties,
see [realization signature specification](project:#realization-signatures).

If the configuration files do not include any trusted public keys,
then any previous build result can be reused
unless the `--clean` command-line option is passed.

:::

:::{confval} server
:type: object
:default: `{}`

See [Server Configuration](admin/configuration.md).

```{eval-rst}
.. index:: single: configuration value; store locator
```

(store-locator)=
## Store locator

A store locator is a JSON object that specifies how to access a store.
The JSON object's properties are interpreted based on the value of its `type` property,
which can be one of the following strings:

`null`
: Represents an empty store.
  Same as using a JSON `null` instead of the JSON object.
  No additional properties.

`http`
: A store using the [Binary Cache protocol](binary-cache/index.md).

  `http` store locators have the following properties:

  | Name  | Type   | Required | Description                                                                |
  | :---- | :----- | :------- | :------------------------------------------------------------------------- |
  | `url` | string | Yes      | URL to the binary cache's [discovery document](binary-cache/discovery.md). |

  Example:

  ```json
  {
    "server": {
      "download": {
        "type": "http",
        "url": "https://www.example.com/zb/cache.json"
      }
    }
  }
  ```