Docs / Configure

Configuration

Ghoti reads one YAML file, config.yaml. Any key in it can be overridden with an environment variable, and the listen address with a command-line flag.

File locations#

ghoti run looks for a file named config.yaml in these directories, in this order, and uses the first one it finds:

  1. /etc/ghoti
  2. $HOME/.ghoti
  3. The current working directory
A configuration file is required

If no config.yaml is found, the server logs Config File "config" Not Found and exits with status 1. It does not start with defaults.

Environment variables#

Any key can be set through an environment variable named GHOTI_ plus the key in upper case, with . (and -) replaced by _:

KeyEnvironment variable
addrGHOTI_ADDR
protocolGHOTI_PROTOCOL
log.levelGHOTI_LOG_LEVEL
cluster.passGHOTI_CLUSTER_PASS

An environment variable overrides the file, and the --addr flag overrides both. Use environment variables to inject secrets such as cluster.pass at runtime instead of committing them to a file. The file is still required, even if every key you need comes from the environment.

One exception: the users block is read as a map, and its entries can't be injected from the environment. Per-user passwords have to come from the file.

Server settings#

KeyDefaultDescription
addrlocalhost:9090host:port the server listens on, for every transport. Also settable with ghoti run --addr host:port.
protocolstandardstandard, telnet or http. Any other value stops the server with protocol not supported. See Transports.
max_connections0 (no cap)How many client connections may be open at once. A negative value stops the server. See Connection limits.
log.levelinfodebug, info, warn or error. Any other value stops the server.
log.formattexttext or json. Logs go to standard output.

The default address binds to loopback, so a fresh server is not reachable from other hosts. Before binding to a routable address, read the TLS notes: Ghoti doesn't encrypt any traffic.

Other sections#

KeyDocumented in
slot_000 … slot_999Slot reference
users and per-slot usersAuthentication
metricsOperations
clusterCluster Experimental

What is validated at startup#

The server refuses to start, and logs the reason, when:

Slot definitions are not validated at startup

An invalid slot (an unknown kind, a missing required option or an out-of-range value) is ignored silently. The server starts without a warning, and that slot answers e<slot>005 (MISSING_SLOT) as if it was never defined. Read every slot once after a configuration change.

Annotated example#

This is the example config.yaml from the repository:

# Example config file for Ghoti

log:
  level: debug
  format: text

# Metrics are disabled by default. Uncomment and configure to enable.
#metrics:
#  enabled: true
#  addr: "127.0.0.1:9100"       # host:port where GET /metrics is served for Prometheus

# Cluster mode is disabled by default. Uncomment and configure to enable.
#cluster:
#  node: node1                  # unique node ID, decides election priority
#  user: cluster_user           # inter-node credentials (min 4 characters)
#  pass: cluster_pass
#  manager:
#    type: join_server
#    addr: "0.0.0.0:2222"       # where this node's cluster server listens
#    join: "10.0.0.2:2222"      # existing member to join; omit to bootstrap
#  leader:
#    enabled: true              # serve GET /leader for load balancer health
#                               # checks: 200 on the leader, 503 on followers

slot_000:
  kind: broadcast

slot_001:
  kind: simple_memory

slot_002:
  kind: simple_memory

slot_003:
  kind: timeout_memory
  timeout: 60

Found something out of date? Open an issue or edit this page.