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:
/etc/ghoti$HOME/.ghoti- The current working directory
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 _:
| Key | Environment variable |
|---|---|
addr | GHOTI_ADDR |
protocol | GHOTI_PROTOCOL |
log.level | GHOTI_LOG_LEVEL |
cluster.pass | GHOTI_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#
| Key | Default | Description |
|---|---|---|
addr | localhost:9090 | host:port the server listens on, for every transport. Also settable with ghoti run --addr host:port. |
protocol | standard | standard, telnet or http. Any other value stops the server with protocol not supported. See Transports. |
max_connections | 0 (no cap) | How many client connections may be open at once. A negative value stops the server. See Connection limits. |
log.level | info | debug, info, warn or error. Any other value stops the server. |
log.format | text | text 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#
| Key | Documented in |
|---|---|
slot_000 … slot_999 | Slot reference |
users and per-slot users | Authentication |
metrics | Operations |
cluster | Cluster Experimental |
What is validated at startup#
The server refuses to start, and logs the reason, when:
- No configuration file is found.
protocol,log.levelorlog.formathas an unsupported value, ormax_connectionsis negative.- A user in
usershas a name or password that breaks the login rules. - The
clustersection is missingnode,user,passormanager.type, ornodeis longer than 20 characters. metrics.enabledis true withoutmetrics.addr, or themetricssection still has a key from the removed file-based writer (output_dir,rotation,retain,interval).- The address can't be bound.
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