# Configuration

> Configure HotKV with hotkv.conf or hotkv.toml, command-line flags, and CONFIG GET, SET, REWRITE and RESETSTAT.

URL: https://docs.hotkv.com/operate/configuration/


HotKV reads its settings from one configuration file, from the command
line, and at runtime from the `CONFIG` command. This page explains how
those three fit together. Every individual directive, with its default and
accepted values, is in the [configuration reference](https://docs.hotkv.com/reference/configuration/index.md).

## Two file formats

HotKV takes either of two formats. Use one file, not both:

- **`hotkv.conf`**: the Redis-style format, one `directive value` per line.
  Most `redis.conf` directives keep their Redis names and meaning, so an
  existing Redis configuration is a good starting point.
- **`hotkv.toml`**: the same settings grouped into TOML sections such as
  `[network]`, `[memory]`, `[persistence]`, `[security]`, `[tls]` and
  `[cluster]`, with underscores instead of dashes in key names.

The format is chosen by the file name: a file ending in `.toml` is read as
TOML, anything else as `hotkv.conf` format. The same settings in both:

```
# hotkv.conf
bind 0.0.0.0
port 6379
requirepass "your-password-here"
maxmemory 4gb
maxmemory-policy allkeys-lru
appendonly yes
dir /var/lib/hotkv
```

```toml
# hotkv.toml
[network]
bind = "0.0.0.0"
port = 6379

[security]
requirepass = "your-password-here"

[memory]
maxmemory = "4gb"
maxmemory_policy = "allkeys-lru"

[persistence]
appendonly = true
dir = "/var/lib/hotkv"
```

Sizes take the Redis units in either format: bytes, or a whole number with
`k`, `kb`, `m`, `mb`, `g` or `gb` (`k`, `m` and `g` are powers of 1000,
`kb`, `mb` and `gb` powers of 1024).

A few Redis-named settings have no TOML key and exist only in `hotkv.conf`
and on the command line: `client-output-buffer-limit`,
`client-query-buffer-limit`, `proto-max-bulk-len`, `masterauth`,
`masteruser`, the `repl-*` settings and `ignore-unknown-directives`. If you
use `hotkv.toml`, pass these as command-line flags.

### How mistakes are handled

- In `hotkv.conf`, a line naming a directive HotKV does not know stops the
  start with a `FATAL CONFIG FILE ERROR` that names the line, as Redis
  does, so a typo such as `cluster-enable yes` cannot quietly give you a
  standalone node. Set `ignore-unknown-directives yes` to log and skip such
  lines instead (a HotKV setting; Redis has no equivalent).
- Redis and Valkey directives that HotKV has no use for (for example
  `activedefrag`, `io-threads`, the `lazyfree-*` settings, `syslog-*`,
  `unixsocket`) are accepted with a warning in the log and have no effect.
- Some Redis directives stop the start even though Redis knows them,
  because ignoring them would leave the server in a state you did not ask
  for: `rename-command` (deny the command with an [ACL](https://docs.hotkv.com/operate/acl/index.md) rule
  instead), `user` (declare users in the ACL file named by `aclfile`),
  `loadmodule` (HotKV does not load Redis modules), `sentinel` (HotKV has
  no Sentinel mode). `replicaof`/`slaveof` stop the start only on a cluster
  node; on a standalone node they make it a replica (see
  [Replication](https://docs.hotkv.com/operate/replication/index.md)).
- In the file, a value a directive does not take is logged as a warning
  and the setting keeps the value it had.
- In `hotkv.toml`, keys HotKV does not read and values of the wrong type
  (a string where a boolean is expected, for example) are not reported.
  Check `CONFIG GET` after a change if a setting does not seem to apply.

### Includes

`hotkv.conf` supports `include <file>`, as Redis does: the included file's
lines are read in its place. A pattern (`include /etc/hotkv/conf.d/*.conf`)
reads every matching file in name order, and matching nothing is not an
error. A named file that cannot be read stops the start. Includes can nest
up to 16 levels. A relative path is resolved from the directory the server
was started in (with the packaged systemd unit, `/var/lib/hotkv`), so use
absolute paths. `hotkv.toml` has no include mechanism.

## File locations

The Linux packages install:

| Path | What it is |
| --- | --- |
| `/usr/bin/hotkv`, `/usr/bin/hotkv-cli` | The server and the CLI |
| `/etc/hotkv/hotkv.conf` | The configuration the `hotkv` service loads. Package upgrades keep your changes. |
| `/etc/hotkv/hotkv.toml.example` | A commented TOML example |
| `/var/lib/hotkv` | The service's working directory, where snapshots and the AOF go with the default `dir ./` |
| `/var/log/hotkv` | For log files, when you set `logfile` to a path there (rotated weekly by the packaged logrotate rule) |

The packaged systemd unit runs `hotkv --config /etc/hotkv/hotkv.conf` as
the `hotkv` user. To use TOML instead, point the unit at your file with
`systemctl edit hotkv`; see
[Quick start: On-Premise](https://docs.hotkv.com/quickstart-onpremise/index.md#2-configuration-file-basics).
For containers, see [Docker and Kubernetes](https://docs.hotkv.com/operate/docker-and-kubernetes/index.md).

Started without a configuration file, HotKV runs with the built-in defaults
(listening on `127.0.0.1:6379`).

## Command line

```
hotkv [config-file] [--setting value ...]
hotkv -c config-file [--setting value ...]
hotkv --version | --help | --hwid
```

| Option | Meaning |
| --- | --- |
| `config-file`, `-c FILE`, `--config FILE` | The configuration file to load (`.conf` or `.toml`) |
| `--setting value` | Any `hotkv.conf` directive, which wins over the file |
| `-p PORT` | Same as `--port PORT` |
| `--no-snapshot` | Start without loading the snapshot in `dir`, and with no automatic snapshots. The snapshot file is left as it was; `SAVE` and `BGSAVE` still write one when you ask. See [Persistence](https://docs.hotkv.com/persistence/index.md#start-without-the-snapshot). |
| `-v`, `--version` | Print the version and exit |
| `--hwid` | Print this machine's hardware ID for licensing and exit (see [Quick start: On-Premise](https://docs.hotkv.com/quickstart-onpremise/index.md#3-get-your-hardware-id)) |
| `-h`, `--help` | Print the usage and exit |

Settings on the command line use the `hotkv.conf` names, even when the file
is TOML:

```bash
hotkv /etc/hotkv/hotkv.conf --port 6380 --appendonly yes
hotkv --save "3600 1 300 100" --maxmemory 2gb --dir /var/lib/hotkv
```

A value of several words can also be given as separate arguments
(`--save 3600 1`). A setting given with no value means `yes`
(`--appendonly`, `--cluster-enabled`), except `--save` alone, which turns
automatic snapshots off.

The command line is stricter than the file: an unknown setting or a value
the setting does not take stops the start, so a typo is caught at once.
Enterprise settings, the ones with a dot in their name such as
`replication.enabled`, cannot be given on the command line; put them in the
configuration file.

## Changing settings at runtime

### CONFIG GET

[`CONFIG GET`](https://docs.hotkv.com/commands/config-get/index.md) takes one or more names or glob
patterns, in any case, and returns each matching setting with its current
value:

```
127.0.0.1:6379> CONFIG GET maxmemory*
1) "maxmemory"
2) "0"
3) "maxmemory-policy"
4) "noeviction"
5) "maxmemory-samples"
6) "5"
```

Passwords (`requirepass`, `masterauth`, TLS key passphrases) are shown as
`(hidden)` when set.

### CONFIG SET

[`CONFIG SET`](https://docs.hotkv.com/commands/config-set/index.md) changes one or more settings at once,
and most take effect immediately:

```
127.0.0.1:6379> CONFIG SET maxmemory 4gb maxmemory-policy allkeys-lru
OK
127.0.0.1:6379> CONFIG GET maxmemory
1) "maxmemory"
2) "4294967296"
```

Settings you can change at runtime include `maxmemory` and the eviction
settings, `timeout`, `maxclients`, `requirepass`, `protected-mode`, `save`,
`appendonly` and the AOF settings, `slowlog-*`, `latency-*`,
`notify-keyspace-events`, `bind`, `port`, `tls-port`, the TLS certificate
and key files (setting them reloads TLS for new connections, so a renewed
certificate needs no restart), `hotkey-tracking`, `maxmemory-clients`,
`tracking-table-max-keys`, `repl-backlog-size`, and the cluster settings
listed in [Cluster configuration](https://docs.hotkv.com/clustering/configuration/index.md) other than the
ones below.

These are fixed at startup and are refused with `cannot be changed at
runtime (requires restart)` (or `can't set immutable config` for the
cluster ones):

- `threads`, `databases`, `tcp-backlog`, `daemonize`, `logfile`
- `metrics-port`, `appenddirname`
- `tls-bind`, `tls-replication`
- `enable-protected-configs`, `enable-debug-command`
- `cluster-enabled`, `cluster-config-file`, `cluster-port`, `cluster-databases`

```
127.0.0.1:6379> CONFIG SET threads 8
(error) ERR CONFIG SET failed (possibly related to argument 'threads') - parameter 'threads' cannot be changed at runtime (requires restart)
```

Some settings are not reachable with `CONFIG SET` at all and are read only
at startup: `pidfile`, `aclfile`, `replicaof`, `license-path`, and every enterprise
setting with a dot in its name (`replication.*`, `encryption.*`, ...).

> **Caution**
> `dir`, `dbfilename` and `appendfilename` name files the server writes, so
> `CONFIG SET` refuses them (`can't set protected config`) unless
> `enable-protected-configs` is `yes`, or `local` for clients on the loopback
> interface. This matches Redis 7.

> **Note**
> The log level is fixed at startup: `CONFIG SET loglevel` does not change
> the level of a running server. Change `loglevel` in the configuration file
> and restart to change it.

### CONFIG REWRITE

[`CONFIG REWRITE`](https://docs.hotkv.com/commands/config-rewrite/index.md) writes the settings changed at
runtime back to the file the server was started with, in that file's
format. A setting whose value differs from the file is updated in place, or
appended when the file does not have it. Comments, enterprise settings and
everything else are left as they are. A server started without a file
replies `ERR The server is running without a config file`.

Settings that have no TOML key (see above) cannot be written to a TOML
file.

### CONFIG RESETSTAT

[`CONFIG RESETSTAT`](https://docs.hotkv.com/commands/config-resetstat/index.md) zeroes the counters
reported by `INFO`: connections received and rejected, per-command and
per-error statistics, latency histograms, persistence and script counters,
network byte totals, ACL denial counts and the cluster bus message counts.
See [Monitoring](https://docs.hotkv.com/operate/monitoring/index.md).

## Next steps

- [Configuration reference](https://docs.hotkv.com/reference/configuration/index.md) for every directive
- [Security](https://docs.hotkv.com/security/index.md) for passwords, protected mode and TLS
- [Persistence](https://docs.hotkv.com/persistence/index.md) for snapshots and the AOF
- [Memory and eviction](https://docs.hotkv.com/operate/memory-and-eviction/index.md)