reference config

⚠️ Auto-generated from the repository — do not edit here. Source: https://github.com/luisgf/ssh-broker/tree/main/docs

Config reference

Every configuration field, extracted from the Go structs (field · JSON key · type · doc comment). See Operations for worked examples and the *.example.json files.

Signer config (signer.json)

Config in cmd/signer/main.go

JSON key	Type	Description
listen	string	e.g. ":9443"
server_cert	string	mTLS: presents server_cert and requires clients signed by client_ca.
server_key	string
client_ca	string	CA that signs authorised brokers
ca_key	string	CA key custody. ca_key: legacy path to a PEM CA key (backward compatible). ca_keys: per-group CA key overrides. The reserved key "_default" overrides ca_key when present. See CAKeyConfig for supported backends ("pem" for local files, "akv" for Azure Key Vault).
ca_keys	map[string]ca.CAKeyConfig
audit_log	string	Issuance audit log (independent of the broker).
audit_key	string
max_ttl_seconds	int	MaxTTLSeconds: global cap when the host policy does not set one.
auto_reload_seconds	int	AutoReloadSeconds: if > 0, the signer polls signer.json's mtime every N seconds and hot-reloads on change — same validated, atomic path as SIGHUP / POST /v1/reload, so a transiently-invalid in-progress save is rejected and the previous good state is kept. 0 or absent = disabled (default).
max_grant_ttl_seconds	int	MaxGrantTTLSeconds: optional upper bound on a runtime grant's TTL (POST /v1/policy/hosts/{host}/grants). 0 or absent = no cap.
reload_callers	[]string	ReloadCallers: client cert CNs authorised to invoke POST /v1/reload. Empty = HTTP endpoint disabled (403); SIGHUP still works locally.
trusted_forwarders	[]string	TrustedForwarders: client cert CNs authorised to act on behalf of another broker (on_behalf_of field / X-On-Behalf-Of header). This is the control plane CN. Only these CNs may impersonate a broker for RBAC; any other CN sending on_behalf_of is rejected.
hosts	signer.PolicyTable	Hosts: issuance policy + connectivity per host. Single source of truth: the broker fetches addr/user/host_key/jump via GET /v1/hosts.
callers	signer.CallerTable	Callers: group-based RBAC. Maps broker mTLS cert CN → allowed groups. A CN absent from the table has no group restriction (backward compatible). A CN present can only see and sign hosts whose groups field intersects with its allowed_groups.
command_policies	map[string]signer.CommandPolicy	CommandPolicies is a named library of command policies, attachable to groups. GroupCommandPolicies maps a group name to the policy names that apply to its hosts; the reserved group "_default" applies to every host. A host's effective firewall is the composition of its inline command_policy and the policies of all its groups (additive union; deny wins).
group_command_policies	map[string][]string

Control-plane config (control-plane.json)

Config in cmd/control-plane/main.go

JSON key	Type	Description
listen	string	e.g. ":7443"
server_cert	string	mTLS toward the broker: presents server_cert and requires clients signed by client_ca.
server_key	string
client_ca	string
sign_callers	[]string	SignCallers: client cert CNs authorised to use the signing path (/v1/sign, /v1/hosts, /v1/sign/result) — i.e. the brokers. This separates the broker role from the approver role (approval.callers) when both are signed by the same client_ca. If non-empty, only these CNs may request signing. If empty/absent, any authenticated broker may — EXCEPT a CN that is in approval.callers, which is an approver, not a broker, and is denied the sign path (role separation, secure by default).
signer	(object)	Signer: mTLS client toward the signing service.
approval	(object)	Approval: human-approval orchestration.
behavior	control.BehaviorConfig	Behavior: behaviour guardrails (anomaly detection + rate limiting).
trusted_forwarders	[]string	TrustedForwarders: broker client cert CNs whose end_user claim is trusted (brokers that authenticate end users, e.g. via OIDC). Mirrors the signer's trusted_forwarders semantics. Behaviour guardrails key on ":<end_user>" only for these CNs; for any other CN the client-supplied end_user is ignored and the authenticated broker CN alone is used, so a client cannot evade rate limits or anomaly detection by rotating end_user. Empty/absent = end_user never qualifies the subject.
audit_log	string	Audit log for the control plane (independent of broker and signer).
audit_key	string

Host policy (hosts.<name>)

HostPolicy in internal/signer/signer.go

JSON key	Type	Description
addr	string	Connectivity — exposed to the broker via /v1/hosts.
user	string	remote SSH account
host_key	string	authorized_keys line for the host key
jump	string	logical name of the preceding bastion
principal	string	Issuance policy — internal, never exposed to the broker.
source_address	string
max_ttl_seconds	int
allow_as_bastion	bool
allowed_callers	[]string	AllowedCallers restricts which CNs may request this host. Empty = any authenticated caller.
allow_sudo	bool	Elevation (sudo NOPASSWD). AllowSudo enables privilege elevation for this host.
allowed_sudo_users	[]string	AllowedSudoUsers lists the permitted target users (e.g. ["root","deploy"]). Empty = root only. "root" is always implied when AllowSudo=true.
allow_pty	bool	AllowPTY authorises the permit-pty extension in certificates for this host. If false, PTY requests are rejected.
groups	[]string	Groups lists the RBAC groups this host belongs to. A caller restricted by groups can only access hosts that share at least one of its allowed_groups. Empty = host belongs to no group.
command_policy	CommandPolicy	CommandPolicy restricts which commands may run on this host (AI-action firewall). Empty/off = no command restriction. Session commands are preflighted against the current signer policy before each exec, so reloads affect already-open sessions: target and bastion access, end-user groups, sudo, sudo_user and PTY are revalidated; the broker also rejects already-open sessions if the host's physical SSH route changed. mode=exec is allowed, while shell/pty sessions are rejected when rules are present because stateful commands are not independently verifiable.

Command policy (command_policy)

CommandPolicy in internal/signer/cmdpolicy.go

JSON key	Type	Description
mode	string	Mode: "off" (or empty) | "allowlist" | "denylist". Controls allow/deny.
enforcement	string	Enforcement: "enforce" (or empty) blocks/gates matching commands; "audit" lets them run and returns/audits a warning instead. In composed policies, enforce wins over audit.
allow	[]string	Allow: in allowlist mode, the command must match at least one.
deny	[]string	Deny: in denylist mode, the command must not match any.
require_approval	[]string	RequireApproval: commands that match require out-of-band human approval. Evaluated independently of the mode (orchestrated by the control plane).
shell_parse	bool	ShellParse: if true, the command is parsed as POSIX sh before evaluating the policy. Each simple command is evaluated separately; dangerous nodes (subshells, process substitution, file redirects) are rejected unconditionally. Backward compatible: false by default.

Vocabulary (enumerated constants)

Role distinguishes the role of a hop in the chain.: target, bastion

Purpose distinguishes the intended use of the connection.: oneshot, session

SessionMode distinguishes broker-managed session styles.: exec, shell, pty

CommandPolicy modes.: off, allowlist, denylist

CommandPolicy enforcement modes.: enforce, audit