Skip to content

configuration.md

Latest commit

 

History

History
92 lines (72 loc) · 3.39 KB

configuration.md

File metadata and controls

92 lines (72 loc) · 3.39 KB
Raw

Configuration Reference

Configuration is passed as a dict in the hivemind-websocket-plugin block of ~/.config/hivemind-core/server.json. Dict keys always take precedence over environment variables.

Connection

Key Type Default Description
host str 0.0.0.0 Bind address. Falls back to identity.default_master.
port int 5678 Listen port. Falls back to identity.default_port.
ssl bool false Enable TLS (wss://).
cert_dir str $XDG_DATA_HOME/hivemind Directory for TLS cert/key files.
cert_name str hivemind Base filename. It produces <name>.crt and <name>.key.

When ssl=true and the key file does not exist, a self-signed 2048-bit RSA certificate valid for 10 years is generated automatically.

There is no module key in network_protocol. hivemind-core reads every key of that block as a plugin entry-point name and starts each one, so a "module" key is looked up as a plugin named module; that entry fails to load and is logged, and the server still starts as long as another transport loads. agent_protocol, binary_protocol and database do use a module selector; this block does not.

Keepalive

Key Env var Default Description
websocket_ping_interval HIVEMIND_WEBSOCKET_PING_INTERVAL 30.0 Seconds between Tornado WebSocket keepalive pings. 0 disables them.
websocket_ping_timeout HIVEMIND_WEBSOCKET_PING_TIMEOUT 20.0 Seconds to wait for a pong before Tornado closes the connection.

Both accept a number or a numeric string. A negative, non-finite or unparsable value is ignored with a warning and the default is used. These pings are Tornado's WebSocket-level keepalive; they are unrelated to the HiveMind PING message.

Trusted-proxy IP resolution

Key Env var Default Description
trusted_proxy_cidrs HIVEMIND_TRUSTED_PROXY_CIDRS (none, feature disabled) Comma-separated CIDRs of trusted proxy addresses.
trusted_client_ip_headers HIVEMIND_TRUSTED_CLIENT_IP_HEADERS x-forwarded-for,x-real-ip Ordered list of headers to inspect for the real client IP.

Both keys accept a str, list, or tuple. Env vars accept comma-separated strings. The feature is inactive unless at least one CIDR is configured.

When inactive, remote_ip from the Tornado request is used as-is.

Example: nginx on localhost

export HIVEMIND_TRUSTED_PROXY_CIDRS="127.0.0.1/32"
export HIVEMIND_TRUSTED_CLIENT_IP_HEADERS="x-forwarded-for"

Example: private network proxies via config

{
  "network_protocol": {
    "hivemind-websocket-plugin": {
      "trusted_proxy_cidrs": ["10.0.0.0/8", "192.168.0.0/16"],
      "trusted_client_ip_headers": ["x-forwarded-for", "x-real-ip"]
    }
  }
}

See architecture.md for the full algorithm.

Full example

{
  "network_protocol": {
    "hivemind-websocket-plugin": {
      "host": "0.0.0.0",
      "port": 5678,
      "ssl": true,
      "cert_dir": "/etc/hivemind/ssl",
      "cert_name": "hivemind",
      "trusted_proxy_cidrs": ["127.0.0.1/32"],
      "trusted_client_ip_headers": ["x-forwarded-for"],
      "websocket_ping_interval": 30.0,
      "websocket_ping_timeout": 20.0
    }
  }
}

← Architecture · Home · Development →