Configuration and option reference

RedisServerWrapper has three configuration layers:

RedisServerWrapper.Config is a typed Redis configuration builder.
Server, Cluster, and Sentinel accept curated operational options and own lifecycle/topology directives.
:extra is a token-safe escape hatch for Redis directives that do not have typed fields.

The wrapper does not claim that every Redis directive is a typed option. Use the tables below to determine what is emitted, what controls redis-cli, and what a topology owns.

Typed Config options

RedisServerWrapper.Config.new/1 validates these keys and RedisServerWrapper.Config.to_config_string/1 renders the Redis directives. Unless noted, the same key can be passed to RedisServerWrapper.Server.start/1 or RedisServerWrapper.Server.start_link/1.

Endpoint, auth, and logging

Option	Default	Meaning
`port`	`6379`	Plain TCP listener, `0..65_535`; `0` disables plaintext TCP.
`bind`	`"127.0.0.1"`	One address, a whitespace-separated string, or a list of addresses.
`control_host`	`nil`	Concrete host used by `redis-cli` and lifecycle probes. Derived from the first bind address; required when that address is a wildcard. Not emitted to Redis.
`username`	`nil`	Named ACL user. Requires a string `password`; disables the default user unless the name is `"default"`.
`password`	`nil`	`requirepass` when no username is set, otherwise the named ACL user's password.
`loglevel`	`:notice`	One of `:debug`, `:verbose`, `:notice`, or `:warning`.
`logfile`	`nil`	Redis log path. Server supplies a generated private node-directory path when omitted.
`daemonize`	`false`	Direct Config value. Server overrides it from `managed`: foreground for `true`/`:forcola`, daemonized for `false`.
`pidfile`	`nil`	Direct Config value. Server always supplies a generated node-directory path.
`dir`	`nil`	Redis working directory. Server always supplies its generated node directory.

At least one of port > 0, tls_port, or unixsocket must be enabled.

Persistence, memory, and TCP

Option	Default	Meaning
`save`	`:default`	`:default` leaves Redis defaults untouched; `:disabled` emits an empty `save`; a list of `{positive_seconds, positive_changes}` emits explicit policies.
`appendonly`	`false`	Enables AOF persistence.
`appendfsync`	`:everysec`	One of `:always`, `:everysec`, or `:no`.
`maxmemory`	`nil`	Redis memory limit string, for example `"256mb"`.
`maxmemory_policy`	`nil`	Redis eviction policy string, for example `"allkeys-lru"`.
`tcp_backlog`	`nil`	Non-negative Redis TCP listen backlog.
`timeout`	`nil`	Redis idle-client timeout when using `Config` directly. On `Server`, the `timeout` keyword is instead the wrapper startup timeout; use of the Redis directive through Server is intentionally unavailable because `:extra` cannot override wrapper-owned `timeout`.
`tcp_keepalive`	`nil`	Non-negative Redis TCP keepalive interval.
`unixsocket`	`nil`	Standalone Unix socket path, at most 103 bytes for portable macOS/Linux support.
`unixsocketperm`	`nil`	Redis socket mode string, for example `"700"`.

TLS

Option	Default	Meaning
`tls_port`	`nil`	TLS listener, `1..65_535`. Enables TLS configuration and makes TLS the lifecycle connection.
`tls_cert_file`	`nil`	Required TLS server certificate when `tls_port` is set.
`tls_key_file`	`nil`	Required TLS server private key when `tls_port` is set.
`tls_ca_cert_file`	`nil`	Trusted CA file used by Redis and `redis-cli`; mutually exclusive with `tls_ca_cert_dir`.
`tls_ca_cert_dir`	`nil`	Trusted CA directory; mutually exclusive with `tls_ca_cert_file`. Exactly one CA source is required.
`tls_auth_clients`	`nil`	`nil`, `"yes"`, `"no"`, or `"optional"`. Redis's default is client-certificate authentication.
`tls_client_cert_file`	`nil`	`redis-cli` client certificate. Required with its key when client auth is `nil`/`"yes"`. Not emitted to Redis.
`tls_client_key_file`	`nil`	`redis-cli` client private key. Not emitted to Redis.
`tls_server_name`	`nil`	`redis-cli` SNI/hostname-verification name. Not emitted to Redis.
`tls_insecure`	`false`	Disables `redis-cli` certificate verification. Not emitted to Redis.
`tls_replication`	`false`	Emits `tls-replication yes`; Sentinel sets this for TLS data nodes.
`tls_cluster`	`false`	Emits `tls-cluster yes`; Cluster sets this for TLS nodes.

To run TLS-only, set port: 0. To use both plaintext and TLS listeners, leave a positive port; lifecycle commands still use TLS whenever tls_port is set.

Replication and Cluster directives

Option	Default	Meaning
`replicaof`	`nil`	`{host, port}` for a standalone replica. Sentinel owns this for its replicas.
`masteruser`	`nil`	ACL username used for replication; requires `replicaof` and `masterauth`.
`masterauth`	`nil`	Replication password; requires `replicaof`.
`cluster_enabled`	`false`	Emits `cluster-enabled yes`. Cluster owns this for its nodes.
`cluster_config_file`	`nil`	Redis Cluster state filename. Cluster generates a per-node filename.
`cluster_node_timeout`	`nil`	Non-negative Cluster node timeout in milliseconds.
`cluster_announce_hostname`	`nil`	Explicit Cluster announcement hostname.
`cluster_announce_port`	`nil`	Explicit Cluster data port, `1..65_535`.
`cluster_announce_bus_port`	`nil`	Explicit Cluster bus port, `1..65_535`.

Modules and raw directives

Option	Default	Meaning
`loadmodule`	`[]`	Module paths or `{path, [string_args]}` tuples. Every token is quoted/escaped when needed.
`extra`	`[]`	`{directive, string_or_nonempty_string_vector}` tuples for untyped Redis directives.

Use an argument vector for multi-token directives:

extra: [
  {"notify-keyspace-events", "KEA"},
  {"client-output-buffer-limit", ["pubsub", "32mb", "8mb", "60"]}
]

Directive names are case-insensitive and must contain letters, numbers, and hyphens. :extra cannot replace wrapper-owned fields, including endpoint, auth, TLS, persistence, replication, Cluster, module, PID, directory, and process-lifecycle directives. Unknown Redis directives are accepted by the builder and may still be rejected by the selected Redis version.

Server options

Server.start/1 and Server.start_link/1 accept the Config keys above plus:

Option	Default	Meaning
`name`	`nil`	GenServer registration name. Removed before Config construction.
`redis_server_bin`	distribution default	Executable name or path.
`redis_cli_bin`	`"redis-cli"`	Executable name or path used for readiness, commands, and shutdown.
`distribution`	`:core`	`:core`, `:full`, or `:legacy_stack`; see the support policy.
`timeout`	`10_000`	Wrapper startup/readiness timeout in milliseconds. This shadows the Config field with the same name.
`managed`	`true`	`true` for a foreground Port, `:forcola` for guaranteed owner-death cleanup, or `false` for a detached Redis daemon.

Server owns daemonize, pidfile, and dir even if values are supplied. It honors an explicit logfile, otherwise it generates one beside redis.conf. Only managed: false can be detached with Server.detach/1.

Cluster options

Cluster accepts exactly this topology surface; it does not forward every Config field.

Option	Default	Meaning
`name`	`nil`	Cluster GenServer registration name.
`masters`	`3`	Positive master count.
`replicas_per_master`	`0`	Non-negative replica count for each master.
`base_port`	`7100`	First data/TLS port. Nodes use consecutive ports.
`bind`	`"127.0.0.1"`	Node listen address(es).
`control_host`	first bind	Concrete host for commands and Cluster announcements.
`username` / `password`	`nil`	Password-only or named ACL authentication on every node.
`tls`	`false`	Creates TLS-only Cluster nodes when true.
TLS certificate/client options	`nil` / `false`	`tls_cert_file`, `tls_key_file`, one CA source, `tls_auth_clients`, client certificate/key, `tls_server_name`, and `tls_insecure`.
`redis_server_bin`	distribution default	Redis executable name/path.
`redis_cli_bin`	`"redis-cli"`	CLI executable name/path.
`distribution`	`:core`	`:core`, `:full`, or `:legacy_stack`.
`timeout`	`10_000`	Per-node process-readiness timeout.
`convergence_timeout`	value of `timeout`	Bounded wait for every node to report a healthy agreed topology.
`cluster_node_timeout`	`5_000`	Positive Cluster node timeout in milliseconds.
`loadmodule`	`[]`	Modules loaded into every node.
`extra`	`[]`	Raw non-reserved Redis directives loaded into every node.
`managed`	`true`	Lifecycle backend forwarded to every node. Only `false` supports `Cluster.detach/1`.

For N = masters * (1 + replicas_per_master), Cluster uses data ports base_port..base_port+N-1 and bus ports exactly 10,000 higher. Both ranges are validated for overlap and overflow. Unix sockets are rejected.

Sentinel options

Sentinel accepts exactly this topology surface:

Option	Default	Meaning
`name`	`nil`	Sentinel topology GenServer registration name.
`master_name`	`"mymaster"`	Name monitored by Sentinel.
`master_port`	`6390`	Master data/TLS port.
`replicas`	`2`	Non-negative replica count.
`replica_base_port`	`master_port + 1`	First consecutive replica port.
`sentinels`	`3`	Positive Sentinel control-process count.
`sentinel_base_port`	`26_389`	First consecutive Sentinel control port.
`quorum`	`2`	Positive quorum, no greater than `sentinels`.
`down_after_ms`	`5_000`	Sentinel down-after-milliseconds value.
`failover_timeout_ms`	`10_000`	Sentinel failover-timeout value.
`bind`	`"127.0.0.1"`	Listen address(es) for data and control processes.
`control_host`	first bind	Concrete host used for replication, monitoring, and commands.
`username` / `password`	`nil`	Password-only or named ACL auth for data/control nodes and monitoring.
`tls`	`false`	Creates TLS-only Redis and Sentinel listeners when true.
TLS certificate/client options	`nil` / `false`	Same TLS fields accepted by Cluster.
`redis_server_bin`	distribution default	Used to start both Redis and `--sentinel` processes.
`redis_cli_bin`	`"redis-cli"`	CLI executable name/path.
`distribution`	`:core`	`:core`, `:full`, or `:legacy_stack`.
`timeout`	`10_000`	Per-process readiness timeout.
`convergence_timeout`	value of `timeout`	Bounded replication and Sentinel-discovery wait.
`loadmodule`	`[]`	Modules loaded into master and replicas, never Sentinel control processes.
`managed`	`true`	Lifecycle backend used by data and control processes. Only `false` supports `Sentinel.detach/1`.

All master, replica, and Sentinel port ranges must be valid, free, and non-overlapping. Unix sockets and arbitrary :extra data-node directives are not part of the Sentinel surface.

Manager options

Manager always launches detached (managed: false) processes and records their credentials/endpoints in its state file. It intentionally exposes a narrower surface than Server, Cluster, and Sentinel.

`Manager.start_basic/1`

Option	Default	Meaning
`name`	generated	Persistent instance name.
`port`	`6379`	Plain listener; use `0` with TLS or a Unix socket.
`password`	generated	Omit to generate; pass `nil` explicitly for no auth.
`username`	`nil`	Named ACL user paired with password.
`bind` / `control_host`	loopback / derived	Server listen and control addresses.
`persist`	`false`	Enables default RDB policy and AOF.
`maxmemory`	`nil`	Redis memory limit.
`loadmodule`	`[]`	Modules loaded into the server.
`distribution`	`:core`	Redis distribution selection.
`extra`	`[]`	Raw non-reserved Redis directives.
Unix/TLS options	unset	`unixsocket`, `unixsocketperm`, `tls_port`, certificate/CA/client fields, `tls_server_name`, and `tls_insecure`.

The tls boolean is ignored for basic instances; setting tls_port selects TLS. Manager does not forward custom binary paths, startup timeouts, or other typed Config fields.

`Manager.start_cluster/1`

Accepted keys are name, masters, replicas_per_master, base_port, password, username, bind, control_host, loadmodule, distribution, tls, and the TLS certificate/client fields. Defaults match Cluster. Manager does not forward Cluster extra, timeout, node-timeout, binary, or managed options.

`Manager.start_sentinel/1`

Accepted keys are name, master_port, replicas, sentinels, quorum, sentinel_base_port, password, username, bind, control_host, loadmodule, distribution, tls, and the TLS certificate/client fields. Defaults match Sentinel except Manager derives quorum as min(2, sentinels). Manager does not forward replica_base_port, timing, binary, raw Config, or managed options.

Manager state and operations

The application environment key :redis_server_wrapper, :manager_state_file changes the default ~/.config/redis-server-wrapper/instances.json path.

The public operations are:

list/1 (optionally :basic, :cluster, or :sentinel);
info/1 for stored data plus live status;
credentials/1 for intentionally retrieving unredacted auth/URL data;
stop/1 and stop_all/0 for ownership-checked destructive shutdown;
cleanup/0 for removing stopped entries without signaling live processes.

See security and data safety before using persistent Manager instances outside an isolated developer machine.

← Previous Page Support policy

Next Page → Security and data safety