Skip to content
Reference
Command line
qfence-witness

qfence-witness

Run a witness: a voter of the cluster’s quorum at a third site, holding no controller, no credential and no availability plan.

With an orchestrator at each of two sites, it is the third voter that keeps a majority when one site is lost (§8, §57).

qfence-witness [flags]
qfence-witness <command> ...

Flags

  • -bind string: the “host:port” this witness listens for raft RPCs on AND advertises to peers (required) — must be a specific, reachable address, never a wildcard like 0.0.0.0: raft’s TCP transport refuses to advertise an unspecified address
  • -bootstrap: form a brand-new cluster from -peers on this voter’s first start. Set it on every founding voter, with the same -peers. A voter that already has raft state ignores it, so it may stay set
  • -data-dir string (default ./witness-data): directory for this witness’s durable raft storage
  • -id string: this voter’s raft server ID (required, must be unique in the cluster)
  • -peers string: comma-separated id=host:port list of every voter in the cluster, including this one (required with -bootstrap), e.g. “site-a=10.0.0.1:7000,site-b=10.0.0.2:7000,witness=10.0.0.5:7000”
  • -snapshot-interval duration: how often the snapshot threshold is checked (0: raft’s default, two minutes)
  • -snapshot-threshold uint: take a raft snapshot and compact the log once this many entries were committed since the last one (0: raft’s default, 8192)
  • -status-listen string (default 127.0.0.1:8081): address to serve a minimal JSON health/status endpoint (GET /healthz, GET /status), the B1 status page (GET /), the no-JS join wizard (GET /join, POST /join/1, /join/2, /join/3), and the B3 read-only config page (GET /config) on, for monitoring (§57) and for onboarding a new voter (§8/§57, UI_DESIGN.md App B) — plain HTTP: this endpoint carries no provider config, credentials, or availability plan data, only raft voter health and a bootstrap-token-gated form flow, so it is a lower-stakes surface than the REST API in cmd/orchestrator. Empty disables it
  • -tls-ca string: PEM CA certificate file this voter trusts — must be the same CA that issued every other voter in this cluster’s certificate (see pkg/mtls)
  • -tls-cert string: PEM leaf certificate file for mutual-TLS raft transport (§57 hosted-witness / multi-tenant deployments) — requires -tls-key and -tls-ca together; omit all three for an ordinary plaintext self-hosted witness
  • -tls-crl string: a revocation list (PEM or DER) signed by -tls-ca, e.g. the crl.pem “qfence-orchestrator pki revoke” writes; loaded at start and on SIGHUP. The sites also publish their list through raft, which this witness follows; the file covers a witness that starts before it has synced
  • -tls-key string: PEM private key file matching -tls-cert

qfence-witness help

Print a command’s help, or with -json every command’s flags, as the CLI reference shows them.

qfence-witness help [flags] [command ...]
  • -json: print the description of the command and every command under it, as JSON
qfence-orchestrator