Configuration

Consul has two layers of configuration:

1. Agent config — per-process settings (HCL or JSON files, CLI flags, environment) that govern how this agent runs.
2. Cluster config — Raft-replicated state (config entries, ACLs, etc.) that governs what the cluster does. Documented under Features → Config entries.

This page focuses on agent config.

Sources of agent config

Consul layers config from multiple sources, applied in this order:

1. Built-in defaults (agent/config/source_default.go).
2. Files passed via -config-file and directories via -config-dir. HCL or JSON.
3. CLI flags (e.g., -bootstrap, -bind=..., -log-level=...).
4. Auto-config bootstrap response (when used).

Each source produces a partial Config struct; the builder at agent/config/builder.go (107 KB) merges them, validates, and produces a RuntimeConfig (agent/config/runtime.go, 72 KB) used by the rest of the agent.

Files

agent/config/
├── builder.go            # The merge + validate logic (107 KB)
├── runtime.go            # RuntimeConfig: the validated, in-memory shape used by Agent (72 KB)
├── config.go             # User-facing Config struct (HCL/JSON decoded into this)
├── source_default.go     # Built-in defaults
├── source_file.go        # Reads HCL/JSON files
├── source_flag.go        # Translates CLI flags
├── source_test.go        # Unit-test helper
├── deep-copy.sh          # Regenerates DeepCopy helpers
├── ...

Top-level config families

A non-exhaustive map of major config blocks (full schema: https://developer.hashicorp.com/consul/docs/agent/config):

Family	Purpose
node_name, node_id, datacenter, domain, alt_domain	Identity
data_dir	Where Raft, snapshots, and persistent state live
bind_addr, client_addr, advertise_addr, serf_lan, serf_wan	Network bindings
ports	Per-service ports (HTTP, DNS, RPC, Serf, gRPC, ...)
server, bootstrap, bootstrap_expect	Raft cluster sizing
retry_join, retry_join_wan, retry_max	Cluster join behavior
tls.defaults, tls.https, tls.grpc, tls.internal_rpc	TLS material per surface
auto_encrypt, auto_config	Bootstrap protocols
connect, ca_provider, ca_config	Service mesh CA configuration
acl.tokens.*, acl.default_policy, acl.enable_token_persistence	ACL knobs
dns_config.*	DNS service-TTL, max records, EDNS, recursors
gossip_lan, gossip_wan	Serf timing
limits.*	RPC rate limits, max KV value size, etc.
telemetry.*	Prometheus, statsd, statsite, datadog, circonus settings
audit.* (Enterprise)	Audit logging
experiments	Opt-in feature flags (e.g., the v2 resource API)
enable_central_service_config	Treat service-defaults as authoritative
discovery_max_stale, cache.*	Cache and stale-read behavior
ui_config.*	UI metadata for dashboards

Reload

SIGHUP (or consul reload) re-reads the config files. The reloadable subset (defined in agent/agent.go::Reload and agent/config/runtime.go) is applied without restart:

• ACL tokens.
• Most TLS material.
• Telemetry sinks.
• Service definitions.
• Some dns_config knobs.

Non-reloadable settings (data dir, ports, encryption, server-mode, gossip keys) require a restart.

CLI flags

All flags are documented in agent/config/source_flag.go. Most map directly onto a config field; some compose (e.g., -bind plus -advertise together set bind/advertise behavior). Flags always win over file config.

Environment variables

Some settings honor environment variables (e.g., CONSUL_HTTP_TOKEN, CONSUL_HTTP_ADDR on the client side, GOMAXPROCS for concurrency). The agent itself uses a small set documented in agent/config/.

Validation

builder.go runs structural and cross-field validation:

• bootstrap=true requires server=true.
• bootstrap_expect=N requires server=true and N≥1.
• TLS verify flags require certificates to be present.
• Connect requires a configured CA provider.
• Many enterprise-only fields error when the binary is CE.

Validation errors are surfaced at startup with file/line metadata pointing back to the source.

Per-service configuration

Service definitions can be supplied in agent config (legacy) or registered at runtime via the HTTP API. Decoded definitions are merged with cluster-wide service-defaults and proxy-defaults before being persisted in agent/local.State. The merge logic lives in agent/service_manager/.

Entry points for modification

• Add a new field: extend the relevant struct in agent/config/config.go, add the validated form in runtime.go, copy logic in builder.go, and the default in source_default.go. Add a flag in source_flag.go if applicable.
• Make a field reloadable: include it in agent/agent.go::Reload and ensure no consumer caches the old value past reload.
• Document: HashiCorp's docs repo (hashicorp/web-unified-docs) is the public docs source.