Skip to content
HotKVDocs

Ask the HotKV docs

Answers come only from these docs and can be wrong; check the linked pages before you rely on them.

Configuration

Last updated

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.

Two file formats

Section titled “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
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

Section titled “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 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).
  • 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

Section titled “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

Section titled “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. For containers, see Docker and Kubernetes.

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

Command line

Section titled “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.
-v, --version Print the version and exit
--hwid Print this machine’s hardware ID for licensing and exit (see Quick start: On-Premise)
-h, --help Print the usage and exit

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

Terminal window
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

Section titled “Changing settings at runtime”

CONFIG GET

Section titled “CONFIG GET”

CONFIG GET 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

Section titled “CONFIG SET”

CONFIG SET 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 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.*, …).

CONFIG REWRITE

Section titled “CONFIG REWRITE”

CONFIG REWRITE 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

Section titled “CONFIG RESETSTAT”

CONFIG RESETSTAT 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.

Next steps

Section titled “Next steps”