Configuration

Pointer-heavy reference to the configuration knobs across services. The truth source for each is the linked Rust file or YAML spec — what's here is meant to surface the names and where to read more.

Pageserver

Schema: pageserver/src/config.rs (~36 KB). Long-form prose: docs/settings.md.

Selected keys in pageserver.toml:

Key	Default	Meaning
listen_pg_addr	127.0.0.1:64000	libpq replication listener (page service).
listen_http_addr	127.0.0.1:9898	HTTP management listener.
broker_endpoint	http://127.0.0.1:50051	Storage broker URL.
pg_distrib_dir	(set per build)	Path containing v14/, v15/, etc. with bin/postgres.
checkpoint_distance	256 MB	Bytes held in the in-memory layer before flushing to L0.
checkpoint_timeout	10 min	Force a flush even if checkpoint_distance not reached.
compaction_target_size	128 MB	Target output L1 size.
compaction_period	20 s	How often the compaction loop wakes up.
compaction_threshold	10	L0 files allowed before triggering L0→L1.
gc_period	1 hour	Garbage collection loop interval.
gc_horizon	64 MB	Bytes of recent WAL preserved beyond PITR.
pitr_interval	7 days	PITR retention window.
image_creation_threshold	3	Delta-chain depth before generating a new image layer.
max_file_descriptors	100	Soft cap on open layer files.
[remote_storage]	unset	TOML table: S3, Azure, GCS, or LocalFs. See docs/settings.md.

Per-tenant overrides for many of these can be set via the storage controller or the pageserver HTTP API.

Safekeeper

Schema: CLI flags in safekeeper/src/bin/safekeeper.rs and the SafeKeeperConf struct.

Selected flags:

Flag	Default	Meaning
--id	(required)	This safekeeper's stable id.
--listen-pg	127.0.0.1:5454	libpq replication listener.
--listen-http	127.0.0.1:7676	HTTP management listener.
--datadir	.neon/safekeepers/skN/	Per-timeline state.
--broker-endpoint	http://127.0.0.1:50051	Storage broker.
--remote-storage	unset	TOML / JSON describing remote storage for WAL backup.
--wal-backup-enabled	true	Whether to upload completed segments.
--peer-recovery	true	Allow pull_timeline from peers.

docs/walservice.md covers more.

Storage broker

Schema: CLI in storage_broker/src/bin/storage_broker.rs.

Flag	Default	Meaning
--listen	127.0.0.1:50051	gRPC listener.
--listen-https	unset	TLS listener (mutually exclusive with HTTP only).
--auth-token-public-key-file	unset	JWT verification key.

Storage controller

Schema: CLI in storage_controller/src/main.rs.

Flag	Default	Meaning
--listen	127.0.0.1:1234	HTTP listener.
--database-url	(required)	Postgres URL for the metadata DB.
--public-key	unset	JWT verification key.
--max-offline	30s	Time after which an unreachable pageserver is considered offline.
--max-secondary-lag-bytes	(large)	Lag tolerated for secondary attachments.

docs/storage_controller.md has more deployment-oriented detail.

Proxy

Schema: proxy/src/config.rs, CLI in proxy/src/bin/proxy.rs. The user guide is proxy/README.md.

Selected flags:

Flag	Meaning
-c, -k	TLS certificate and key paths.
--auth-backend	console / postgres / web / link / local.
--auth-endpoint	URL for the auth backend (a Postgres URL for postgres, console URL for console, etc.).
--proxy	libpq listener address.
--wss	WebSocket TLS listener.
--http	HTTP listener (for SQL/HTTP).
--redis-auth-type	Redis cancellation backend.
--is-auth-broker, --is-rest-broker	Switch into the auth-broker / REST-broker modes.
Rate-limit flags	Many, see proxy/src/rate_limiter/.

compute_ctl

Schema: CLI in compute_tools/src/bin/compute_ctl.rs. Spec consumed at startup is the JSON document fetched from --spec (or read from --spec-path). The spec model is libs/compute_api/src/spec.rs.

Notable env vars:

Var	Effect
PG_BIN	Override path to the Postgres binaries.
RUST_LOG	Log filter.
LOGFMT	json (default) or text.
OTEL_EXPORTER_OTLP_ENDPOINT	Enable OTLP traces.

Postgres-side configuration

The compute receives a list of GUCs from the spec and writes them into postgresql.conf. Notable Neon-specific GUCs (see pgxn/neon/):

GUC	Meaning
neon.pageserver_connstring	libpq connection string to the assigned pageserver(s).
neon.safekeepers	Comma-separated list of safekeeper endpoints.
neon.timeline_id, neon.tenant_id	The IDs this compute is bound to.
neon.max_replication_write_lag	Backpressure: bytes ahead of safekeepers' written LSN.
neon.max_replication_flush_lag	Backpressure: bytes ahead of flush_lsn.
neon.max_replication_apply_lag	Backpressure: bytes ahead of pageserver last_record_lsn.
neon.file_cache_size_limit	Per-compute on-disk page cache size.

Where defaults are encoded

Most defaults sit in:

• pageserver/src/config.rs::PageServerConf::default_*
• safekeeper/src/lib.rs::SafeKeeperConf::default()
• proxy/src/config.rs::ProxyConfig::default()

Reading them is the most reliable way to know what a particular setting starts as.

See also

• Architecture
• How to monitor — observability-related config (OTLP env vars, etc.).
• docs/settings.md for pageserver-specific operator notes.