Skip to content

armgit / xerj

Public Imported from GitHub
0

AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.

fix(server): reject a non-IP bind_address before the exposure checks run

xerj-org4cc6bcb41ce0
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 85463e0b8..504acdc2f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -43,6 +43,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
also prints the bind address on every listener line, so a loopback node and a
world-facing one no longer look identical.
+ A `bind_address` that is not an IP literal is rejected first, ahead of both
+ exposure checks, with the fault it actually has. Host names have never been
+ resolved — the pre-#228 code parsed `"{bind}:{port}"` as a socket address and
+ failed on them too — but the exposure predicates fail closed on anything they
+ cannot parse, so without that ordering `bind_address = "localhost"` was
+ refused with a message asserting that localhost "is not loopback" and would
+ "serve plain HTTP on a network-reachable interface", and pointed at an opt-out
+ that fixed nothing: setting it let the boot run on to the bind and fail there
+ instead, after the data directory, the `.xerj_*` system indices, the master
+ key and a printed first-run `admin.key` already existed.
+
### Fixed
- **`autoindex` no longer leaves immortal catalog entries for skipped files**
diff --git a/docs/SECURITY_MODEL.md b/docs/SECURITY_MODEL.md
index bde1c6f78..7fa08dcdd 100644
--- a/docs/SECURITY_MODEL.md
+++ b/docs/SECURITY_MODEL.md
@@ -407,6 +407,22 @@ Scope of the refusal, all pinned by tests:
- **The opt-out relaxes only this check.** With TLS on it is not consulted at
all; the residual gRPC h2c exposure stays governed by
`tls.allow_insecure_grpc_h2c` (#229).
+- **The bind address must be an IP literal.** Host names are not resolved, and
+ a node given one is refused at `main.rs` step 3a — *before* either exposure
+ check runs, so neither can describe an address it could not parse. Without
+ that ordering, `bind_address = "localhost"` was refused by 3c with a message
+ claiming localhost "is not loopback", and the opt-out that message names
+ merely deferred the same failure past the data directory and a printed
+ first-run admin key. Resolution is deliberately not attempted: a name maps to
+ different addresses on different hosts and at different times, so "which
+ interfaces did this node just publish itself on?" would stop having a fixed
+ answer.
+
+```
+Error: server.bind_address = "localhost" is not an IP address — it must be an
+IPv4 or IPv6 literal such as "127.0.0.1" (the default), "0.0.0.0" or "::1".
+Host names are not resolved.
+```
The escape hatch does not make anything safe. It records that you know, and it
is what you set when a reverse proxy, sidecar, mesh or ingress terminates TLS in
diff --git a/engine/crates/xerj-common/src/config.rs b/engine/crates/xerj-common/src/config.rs
index 4f08bb444..4a529f4cc 100644
--- a/engine/crates/xerj-common/src/config.rs
+++ b/engine/crates/xerj-common/src/config.rs
@@ -303,8 +303,17 @@ impl Config {
/// Only a loopback literal counts. `0.0.0.0` and `::` are *unspecified*,
/// not loopback — they bind every interface the host has, which is the
/// exposure this predicate exists to detect. An address that does not
- /// parse is reported as not confined: it fails closed here, and the bind
- /// itself rejects it a moment later anyway.
+ /// parse is reported as not confined — it fails closed here, because a
+ /// predicate that guards an exposure must never answer "safe" about a
+ /// value it does not understand.
+ ///
+ /// That fail-closed answer is correct and is *not* a message: on its own
+ /// it would have the startup refusals tell an operator who wrote
+ /// `bind_address = "localhost"` that localhost "is not loopback", which is
+ /// false, and prescribe an opt-out that only defers the failure. So
+ /// `xerj-server/src/main.rs` rejects a non-IP `bind_address` at step 3a
+ /// with [`Config::bind_ip`], before either exposure check runs; by the
+ /// time this predicate is consulted there, the address is known to parse.
pub fn bind_address_is_loopback(&self) -> bool {
self.bind_ip()
.map(crate::net::canonical_ip)
diff --git a/engine/crates/xerj-server/src/main.rs b/engine/crates/xerj-server/src/main.rs
index 4a960b026..ccec1be4a 100644
--- a/engine/crates/xerj-server/src/main.rs
+++ b/engine/crates/xerj-server/src/main.rs
@@ -1710,6 +1710,46 @@ async fn async_main() -> Result<()> {
info!("xerj v{} starting", env!("CARGO_PKG_VERSION"));
+ // 3a. `server.bind_address` must be an IP literal — and must be rejected
+ // *here*, ahead of the two exposure checks that follow.
+ //
+ // Both of those keep on `Config::bind_address_is_loopback`, which
+ // fails closed on a value it cannot parse. That is the right answer
+ // for a security predicate and the wrong one for a message: without
+ // this guard, `bind_address = "localhost"` is refused by 3c with
+ // «"localhost" is not loopback … would serve plain HTTP on a
+ // network-reachable interface», two statements that are simply untrue
+ // of localhost — and the remedy that refusal prescribes,
+ // `allow_insecure_network_bind = true`, does not fix anything. It only
+ // silences 3c, so the boot then runs to step 11 and dies on the bind
+ // *after* the data directory, the `.xerj_*` system indices, the master
+ // key and a first-run `admin.key` exist and the console setup link has
+ // been printed. That is the exact late-and-worse failure shape the
+ // cluster-transport commit on this branch was written to remove; this
+ // closes the same hole on the data-listener path.
+ //
+ // Rejecting first means the loopback predicate only ever runs on a
+ // value that is known to be an IP, so 3b and 3c can only ever say
+ // something true — and the one honest error arrives with the other
+ // startup refusals, before anything is written to disk.
+ //
+ // Host names are deliberately not resolved. Nothing regresses: the
+ // pre-#228 code composed listeners with
+ // `format!("{bind}:{port}").parse::<SocketAddr>()`, which never
+ // resolved names either — it just failed at step 11 instead of here.
+ // Keeping it that way also keeps the exposure predicates
+ // deterministic: a name resolves to different addresses on different
+ // hosts and at different times, so "is this node about to publish
+ // itself off-loopback?" would stop having a fixed answer. meilisearch
+ // took the other branch — `DEFAULT_HTTP_ADDR = "localhost:7700"`
+ // (`crates/meilisearch/src/option.rs:97`, MIT) is a name, resolved by
+ // actix's `bind()` — and pays for it with a bind that happens at
+ // `crates/meilisearch/src/main.rs:199-201`, after the index scheduler
+ // and database are already open. Approach compared, no code taken.
+ if cfg.bind_ip().is_none() {
+ anyhow::bail!(bad_bind_address(&cfg));
+ }
+
// 3b. gRPC h2c exposure — fail closed (issue #229). `grpc.rs` builds
// tonic without its `tls` feature, so `server.grpc_port` speaks
// cleartext h2c no matter what `[tls]` says. Enabling TLS and binding
@@ -1719,11 +1759,12 @@ async fn async_main() -> Result<()> {
// banner they read once. Refuse instead, and name the one setting
// that says the exposure is deliberate.
//
- // First thing after tracing, on purpose: a boot that is going to be
- // rejected must not create the data directory, mint and print a
- // first-run admin key, or generate a certificate. It is also after
- // `load_config`, so `--insecure` (which clears `tls.enabled`) has
- // already been applied and cannot be overruled from a config file.
+ // Immediately after tracing and the 3a bind parse, on purpose: a boot
+ // that is going to be rejected must not create the data directory,
+ // mint and print a first-run admin key, or generate a certificate —
+ // and 3a creates nothing either. It is also after `load_config`, so
+ // `--insecure` (which clears `tls.enabled`) has already been applied
+ // and cannot be overruled from a config file.
if cfg.grpc_h2c_exposed_off_loopback() {
anyhow::bail!(
"tls.enabled = true but the gRPC listener on {}:{} speaks cleartext h2c — \
@@ -1992,6 +2033,12 @@ async fn async_main() -> Result<()> {
// `"{bind}:{port}"` — that string is unparseable for every IPv6
// literal (`"::1:9200"`), which made `bind_address = "::1"` a node
// that could not start at all.
+ //
+ // `socket_addr` cannot be `None` here: step 3a rejected an
+ // unparseable `bind_address` before the data directory existed, which
+ // is where that failure belongs. The context is kept as a backstop so
+ // that if a future edit reorders or drops 3a, this still names the
+ // setting rather than surfacing a bare `Option` unwrap.
let rest_addr: SocketAddr = cfg
.socket_addr(cfg.server.rest_port)
.with_context(|| bad_bind_address(&cfg))?;
diff --git a/engine/crates/xerj-server/tests/cleartext_bind_fail_closed.rs b/engine/crates/xerj-server/tests/cleartext_bind_fail_closed.rs
index 02d7aef14..75c3926bb 100644
--- a/engine/crates/xerj-server/tests/cleartext_bind_fail_closed.rs
+++ b/engine/crates/xerj-server/tests/cleartext_bind_fail_closed.rs
@@ -51,9 +51,9 @@ fn toml_path(p: &std::path::Path) -> String {
/// Run the real binary against `config_body` (plus `extra_args`) and return
/// `(success, stderr)`.
///
-/// The fixed binary rejects at step 3c of startup — before the data directory,
-/// the first-run admin key, or any listener — so well under a second even on a
-/// 2-core CI runner; 60 s is pure headroom.
+/// The fixed binary rejects at step 3a or 3c of startup — before the data
+/// directory, the first-run admin key, or any listener — so well under a
+/// second even on a 2-core CI runner; 60 s is pure headroom.
fn run_until_exit(config_body: &str, dir: &std::path::Path, extra_args: &[&str]) -> (bool, String) {
let config_path = dir.join("xerj.toml");
std::fs::write(&config_path, config_body).unwrap();
@@ -75,9 +75,10 @@ fn run_until_exit(config_body: &str, dir: &std::path::Path, extra_args: &[&str])
child.kill().ok();
child.wait().ok();
panic!(
- "xerj kept running with a non-loopback bind_address and tls.enabled \
- = false — it is serving plain HTTP on a network-reachable interface, \
- so every API key it accepts crosses the wire in cleartext"
+ "xerj kept running on a bind_address the startup checks must \
+ refuse — with tls.enabled = false that means plain HTTP on a \
+ network-reachable interface, so every API key it accepts \
+ crosses the wire in cleartext"
);
}
None => std::thread::sleep(Duration::from_millis(100)),
@@ -502,3 +503,145 @@ auth_secret = "0123456789abcdef0123456789abcdef"
with {exited:?}. stderr:\n{stderr}"
);
}
+
+/// A `bind_address` that is not an IP literal must be told the truth about
+/// itself, and must be told it before anything is created.
+///
+/// `Config::bind_address_is_loopback` fails closed on a value it cannot parse
+/// — correct for a predicate guarding an exposure, and the reason `localhost`
+/// used to be refused by step 3c with a message asserting that localhost "is
+/// not loopback" and "would serve plain HTTP on a network-reachable
+/// interface". Both false. Worse, the remedy that refusal named
+/// (`allow_insecure_network_bind = true`) fixed nothing: it silenced 3c and
+/// let the boot run to the bind at step 11, so the operator following the
+/// instructions got a data directory, `.xerj_*` system indices, a master key,
+/// a printed first-run `admin.key` — and then the same failure anyway.
+///
+/// Both halves are asserted here: the message is the true one, and the
+/// declared-exposure path (the one the old message pointed at) refuses in the
+/// same place rather than deferring.
+#[test]
+fn non_ip_bind_address_is_refused_early_and_truthfully() {
+ for opt_out in [false, true] {
+ let dir = tempfile::tempdir().unwrap();
+ let data_dir = dir.path().join("data");
+ let (rest, grpc, es) = three_free_ports();
+ let opt_out_line = if opt_out {
+ "allow_insecure_network_bind = true\n"
+ } else {
+ ""
+ };
+ let body = format!(
+ r#"
+[server]
+bind_address = "localhost"
+{opt_out_line}rest_port = {rest}
+grpc_port = {grpc}
+es_compat_port = {es}
+data_dir = "{data}"
+"#,
+ data = toml_path(&data_dir),
+ );
+
+ let (ok, stderr) = run_until_exit(&body, dir.path(), &[]);
+
+ assert!(
+ !ok,
+ "a bind_address that is not an IP literal must exit non-zero \
+ (allow_insecure_network_bind = {opt_out}); stderr:\n{stderr}"
+ );
+ assert!(
+ stderr.contains("is not an IP address") && stderr.contains("localhost"),
+ "the exit reason must name the real fault and quote the value \
+ (allow_insecure_network_bind = {opt_out}); stderr:\n{stderr}"
+ );
+ assert!(
+ !stderr.contains("is not loopback"),
+ "localhost IS loopback — the refusal must not assert otherwise; \
+ stderr:\n{stderr}"
+ );
+ assert!(
+ !stderr.contains("allow_insecure_network_bind"),
+ "the refusal must not prescribe an opt-out that does not fix the \
+ fault and only defers the failure past the data directory; \
+ stderr:\n{stderr}"
+ );
+ // The point of moving this to step 3a: with the opt-out set, the old
+ // code reached step 11 and died there, leaving the data dir, the
+ // system indices and a first-run admin key behind.
+ assert!(
+ !data_dir.exists(),
+ "a rejected boot must create nothing (allow_insecure_network_bind \
+ = {opt_out}); found {}. stderr:\n{stderr}",
+ data_dir.display()
+ );
+ }
+}
+
+/// The same guard, reached through `--bind`. The flag is applied after the
+/// config file is validated, so a check that lived in `Config::validate`
+/// would never see it — this pins that the rejection is on the boot path both
+/// sources funnel through.
+#[test]
+fn non_ip_bind_flag_is_refused_before_the_data_dir() {
+ let dir = tempfile::tempdir().unwrap();
+ let data_dir = dir.path().join("data");
+ let (rest, grpc, es) = three_free_ports();
+ let config_path = dir.path().join("xerj.toml");
+ std::fs::write(
+ &config_path,
+ format!(
+ r#"
+[server]
+rest_port = {rest}
+grpc_port = {grpc}
+es_compat_port = {es}
+data_dir = "{data}"
+"#,
+ data = toml_path(&data_dir),
+ ),
+ )
+ .unwrap();
+
+ let mut child = Command::new(env!("CARGO_BIN_EXE_xerj"))
+ .arg("--config")
+ .arg(&config_path)
+ .arg("--bind")
+ .arg("db.internal.example")
+ .stdout(Stdio::null())
+ .stderr(Stdio::piped())
+ .spawn()
+ .expect("spawn xerj");
+
+ let deadline = Instant::now() + Duration::from_secs(60);
+ let status = loop {
+ match child.try_wait().expect("poll child") {
+ Some(status) => break status,
+ None if Instant::now() > deadline => {
+ child.kill().ok();
+ child.wait().ok();
+ panic!("--bind db.internal.example must be refused, not served");
+ }
+ None => std::thread::sleep(Duration::from_millis(100)),
+ }
+ };
+ let mut stderr = String::new();
+ child
+ .stderr
+ .take()
+ .expect("stderr piped")
+ .read_to_string(&mut stderr)
+ .expect("read child stderr");
+
+ assert!(!status.success(), "must exit non-zero; stderr:\n{stderr}");
+ assert!(
+ stderr.contains("is not an IP address") && stderr.contains("db.internal.example"),
+ "host names are not resolved, and the refusal must say so while \
+ quoting the value; stderr:\n{stderr}"
+ );
+ assert!(
+ !data_dir.exists(),
+ "a rejected boot must create nothing; found {}. stderr:\n{stderr}",
+ data_dir.display()
+ );
+}
diff --git a/engine/xerj.default.toml b/engine/xerj.default.toml
index 2ad60e7c8..bc640720b 100644
--- a/engine/xerj.default.toml
+++ b/engine/xerj.default.toml
@@ -31,7 +31,10 @@ es_compat_port = 9200
# Ensure this path has sufficient disk space and fast I/O.
data_dir = "./data"
-# IP address to bind all listeners to.
+# IP address to bind all listeners to. An IPv4 or IPv6 literal — "127.0.0.1",
+# "0.0.0.0", "::1". Host names are NOT resolved; a name is refused at startup
+# before anything is created, rather than resolving to a different interface on
+# every host.
#
# Defaults to loopback: a fresh node is reachable from the machine it runs on
# and nowhere else. TLS is off by default, so a node that bound every interface
diff --git a/landing/docs/cli.html b/landing/docs/cli.html
index 5b5b41178..b194fb758 100644
--- a/landing/docs/cli.html
+++ b/landing/docs/cli.html
@@ -141,7 +141,7 @@ OPTIONS:
<p>Convenience override for <code class="inline">[server] data_dir</code>. Useful for ephemeral dev runs and for pointing XERJ at a tmpfs when you just want to burn something down after.</p>
<h2 id="bind-flag">--bind / -b</h2>
- <p>Interface to bind every listener to; overrides <code class="inline">[server] bind_address</code>. Env: <code class="inline">XERJ_BIND_ADDRESS</code>. The default is <code class="inline">127.0.0.1</code> — loopback only. Pass <code class="inline">0.0.0.0</code> (or a specific address) to expose the node; with TLS off that also needs <code class="inline">server.allow_insecure_network_bind = true</code> (env <code class="inline">XERJ_ALLOW_INSECURE_NETWORK_BIND</code>), because every request, API key included, would cross the network in cleartext.</p>
+ <p>Interface to bind every listener to; overrides <code class="inline">[server] bind_address</code>. Env: <code class="inline">XERJ_BIND_ADDRESS</code>. The default is <code class="inline">127.0.0.1</code> — loopback only. Pass <code class="inline">0.0.0.0</code> (or a specific address) to expose the node; with TLS off that also needs <code class="inline">server.allow_insecure_network_bind = true</code> (env <code class="inline">XERJ_ALLOW_INSECURE_NETWORK_BIND</code>), because every request, API key included, would cross the network in cleartext. The value must be an IPv4 or IPv6 literal; host names are not resolved, and one is refused at startup before the data directory is created.</p>
<h2 id="insecure-flag">--insecure / -k</h2>
<p>Disables TLS and API-key auth. <strong>Dev only.</strong> It does not unlock a network bind: clearing <code class="inline">tls.enabled</code> is exactly what makes a non-loopback <code class="inline">bind_address</code> refuse to start, so <code class="inline">--insecure</code> on <code class="inline">0.0.0.0</code> exits non-zero unless the exposure is declared.</p>
diff --git a/landing/docs/config.html b/landing/docs/config.html
index e829e57fa..e72c36821 100644
--- a/landing/docs/config.html
+++ b/landing/docs/config.html
@@ -124,7 +124,7 @@
<p>Paths for the config are, in precedence order: <code class="inline">--config /path/to/xerj.toml</code> on the command line, then <code class="inline">/etc/xerj/xerj.toml</code>, then <code class="inline">./xerj.toml</code> in the working directory. If none exist, the full default is used.</p>
<h2>Full key table</h2>
- <div class="cfg"><div class="head">KEY</div><div class="head">TYPE</div><div class="head">DEFAULT</div><div class="head">DESCRIPTION</div><div class="group" id="server">[server]</div><div class="cell k">rest_port</div><div class="cell t">u16</div><div class="cell d">8080</div><div class="cell dsc">Native REST API listener port. All native endpoints (/v1/*) live here.</div><div class="cell k">grpc_port</div><div class="cell t">u16</div><div class="cell d">8081</div><div class="cell dsc">Reserved for a future gRPC API. Not wired in v0.1 — leave at default.</div><div class="cell k">es_compat_port</div><div class="cell t">u16</div><div class="cell d">9200</div><div class="cell dsc">Elasticsearch-compatible wire port. Point Kibana, Logstash, or the ES client here. Set to 0 to disable.</div><div class="cell k">bind_address</div><div class="cell t">string</div><div class="cell d">"127.0.0.1"</div><div class="cell dsc">Interface to bind every listener to. Loopback by default, so an unconfigured node is unreachable from the network. Set "0.0.0.0" or a private address to expose it (also --bind / XERJ_BIND_ADDRESS).</div><div class="cell k">allow_insecure_network_bind</div><div class="cell t">bool</div><div class="cell d">false</div><div class="cell dsc">Permit a non-loopback bind_address while tls.enabled = false. Startup refuses that combination otherwise: every listener would serve plain HTTP, so the API key in every Authorization header crosses the network in cleartext. Set true only when a proxy, sidecar, mesh or container boundary terminates TLS in front of the node. Env: XERJ_ALLOW_INSECURE_NETWORK_BIND.</div><div class="cell k">data_dir</div><div class="cell t">path</div><div class="cell d">"./data"</div><div class="cell dsc">Root for indices, WAL files, and segments. Needs fast I/O and enough free space.</div><div class="group" id="auth">[auth]</div><div class="cell k">enabled</div><div class="cell t">bool</div><div class="cell d">true</div><div class="cell dsc">Require an API key on every request. Set to false only on a trusted network.</div><div class="cell k">admin_api_key</div><div class="cell t">string</div><div class="cell d">""</div><div class="cell dsc">Static admin key. Left empty, a 256-bit key is generated on first run and written to <data_dir>/admin.key.</div><div class="group" id="tls">[tls]</div><div class="cell k">enabled</div><div class="cell t">bool</div><div class="cell d">false</div><div class="cell dsc">Terminate TLS at the server. Requires cert_path + key_path. If you terminate at a proxy, leave false.</div><div class="cell k">cert_path</div><div class="cell t">path</div><div class="cell d">""</div><div class="cell dsc">PEM X.509 certificate. Use a CA-signed cert in production.</div><div class="cell k">key_path</div><div class="cell t">path</div><div class="cell d">""</div><div class="cell dsc">PEM private key. Permissions should be 0600.</div><div class="group" id="storage">[storage]</div><div class="cell k">wal_sync</div><div class="cell t">enum</div><div class="cell d">"batched"</div><div class="cell dsc">"sync" · "batched" · "async". Durability vs throughput. Batched is the recommended default.</div><div class="cell k">wal_batch_ms</div><div class="cell t">u32</div><div class="cell d">100</div><div class="cell dsc">Fsync cadence when wal_sync="batched" (ms). Range 1–10000. Lower = smaller loss window.</div><div class="cell k">wal_max_size_mb</div><div class="cell t">u32</div><div class="cell d">512</div><div class="cell dsc">WAL rollover threshold (MiB). Larger means fewer rollovers, longer crash recovery.</div><div class="cell k">flush_size_mb</div><div class="cell t">u32</div><div class="cell d">256</div><div class="cell dsc">Memtable buffer size that triggers a segment flush (MiB).</div><div class="cell k">flush_interval_secs</div><div class="cell t">u32</div><div class="cell d">30</div><div class="cell dsc">Maximum wall-clock interval between flushes even if the buffer is not full.</div><div class="group" id="merge">[merge]</div><div class="cell k">strategy</div><div class="cell t">enum</div><div class="cell d">"size_tiered"</div><div class="cell dsc">"size_tiered" or "log_structured". Size-tiered for write-heavy, log-structured for mixed workloads.</div><div class="cell k">min_segments</div><div class="cell t">u32</div><div class="cell d">10</div><div class="cell dsc">Minimum live segments before a merge pass is scheduled. Must be ≥ 2.</div><div class="cell k">max_segment_mb</div><div class="cell t">u32</div><div class="cell d">5120</div><div class="cell dsc">Upper bound on a mergeable segment (MiB). Segments larger than this are never merged.</div><div class="cell k">io_rate_mb_per_sec</div><div class="cell t">u32</div><div class="cell d">100</div><div class="cell dsc">Merge I/O throttle (MiB/s). Set 0 to disable — not recommended in production.</div><div class="cell k">max_concurrent</div><div class="cell t">u8</div><div class="cell d">1</div><div class="cell dsc">Concurrent merge workers per index. Bump to 2–4 on fast NVMe.</div><div class="group" id="compression">[compression]</div><div class="cell k">enabled</div><div class="cell t">bool</div><div class="cell d">true</div><div class="cell dsc">Block-level compression. Disabling increases disk usage and lowers read CPU.</div><div class="cell k">level</div><div class="cell t">enum</div><div class="cell d">"balanced"</div><div class="cell dsc">"fast" (LZ4), "balanced" (Zstd L3, default), "best" (Zstd L19, cold storage).</div><div class="cell k">block_size_docs</div><div class="cell t">u32</div><div class="cell d">128</div><div class="cell dsc">Docs per compressed block. Range 16–4096. Larger = better ratio, higher fetch cost.</div><div class="group" id="fts">[fts]</div><div class="cell k">default_analyzer</div><div class="cell t">enum</div><div class="cell d">"standard"</div><div class="cell dsc">"standard" · "whitespace" · "simple" · "english". Override per-field in the mapping.</div><div class="group" id="vector">[vector]</div><div class="cell k">default_metric</div><div class="cell t">enum</div><div class="cell d">"cosine"</div><div class="cell dsc">"cosine" · "dot_product" · "euclidean". Cosine for text embeddings is the usual choice.</div><div class="cell k">hnsw_m</div><div class="cell t">u32</div><div class="cell d">16</div><div class="cell dsc">Accepted and validated; the built-in HNSW graph currently builds with fixed M=16 — this key is not yet wired to the build.</div><div class="cell k">hnsw_ef_construction</div><div class="cell t">u32</div><div class="cell d">200</div><div class="cell dsc">Accepted; must be ≥ hnsw_m. The graph currently builds with fixed ef_construction=200 — this key is not yet wired to the build.</div><div class="cell k">hnsw_ef_search</div><div class="cell t">u32</div><div class="cell d">100</div><div class="cell dsc">Accepted but not read by the serving path — the ANN beam width comes from the request's num_candidates (floored at 800).</div><div class="cell k">default_quantization</div><div class="cell t">enum</div><div class="cell d">"scalar8"</div><div class="cell dsc">"none" · "scalar8" · "scalar4" · "binary". scalar8 = 4× RAM saving, 1–2% recall loss.</div><div class="cell k">max_dimensions</div><div class="cell t">u32</div><div class="cell d">16384</div><div class="cell dsc">Upper bound on vector dimensionality. 4× the Elasticsearch limit of 4096.</div><div class="group" id="logs">[logs]</div><div class="cell k">retention_days</div><div class="cell t">u32</div><div class="cell d">90</div><div class="cell dsc">Auto-delete log docs older than N days. 0 disables.</div><div class="cell k">time_partition</div><div class="cell t">enum</div><div class="cell d">"1h"</div><div class="cell dsc">"1m" · "5m" · "15m" · "1h" · "6h" · "1d". Time-slice granularity for retention pruning.</div><div class="group" id="embedding">[embedding]</div><div class="cell k">default_endpoint</div><div class="cell t">string</div><div class="cell d">""</div><div class="cell dsc">OpenAI-compatible embeddings URL. Empty disables auto-embedding on ingest. Example: "https://api.openai.com/v1/embeddings".</div><div class="cell k">default_model</div><div class="cell t">string</div><div class="cell d">""</div><div class="cell dsc">Model name passed to the endpoint. Example: "text-embedding-3-small" or "nomic-embed-text".</div><div class="cell k">batch_size</div><div class="cell t">u32</div><div class="cell d">64</div><div class="cell dsc">Docs per embedding API call. Range 1–2048. Bigger batches amortise round-trip cost.</div><div class="cell k">timeout_ms</div><div class="cell t">u32</div><div class="cell d">5000</div><div class="cell dsc">HTTP timeout for embedding calls (ms). Ingest fails with a timeout error if exceeded.</div><div class="group" id="limits">[limits]</div><div class="cell k">max_query_memory_mb</div><div class="cell t">u32</div><div class="cell d">512</div><div class="cell dsc">Per-query memory cap (MiB). Queries that exceed it are cancelled.</div><div class="cell k">max_concurrent_searches</div><div class="cell t">u32</div><div class="cell d">64</div><div class="cell dsc">Global in-flight search ceiling. Extras are queued.</div><div class="cell k">max_fields_per_index</div><div class="cell t">u32</div><div class="cell d">500</div><div class="cell dsc">Field-explosion protection. ES default is 1000; 500 is intentionally stricter.</div><div class="group" id="indexing">[indexing]</div><div class="cell k">turbo_batch_size</div><div class="cell t">u32</div><div class="cell d">1000</div><div class="cell dsc">Docs per batch in turbo mode. Range 500–5000. Larger = higher throughput, slightly higher latency.</div><div class="cell k">turbo_parallel</div><div class="cell t">bool</div><div class="cell d">true</div><div class="cell dsc">Parallel tokenisation on Rayon threads. Disable only for debugging.</div><div class="cell k">turbo_fast_analyzer</div><div class="cell t">bool</div><div class="cell d">false</div><div class="cell dsc">Skip stemming and stop-word removal in turbo mode. Trades recall for speed.</div><div class="group" id="cluster">[cluster]</div><div class="cell k">enabled</div><div class="cell t">bool</div><div class="cell d">false</div><div class="cell dsc">Enable multi-node cluster mode. When true, the Raft state machine and cluster transport are started on port.</div><div class="cell k">port</div><div class="cell t">u16</div><div class="cell d">9300</div><div class="cell dsc">TCP port for intra-cluster Raft and search messages. Must be reachable from every peer.</div><div class="cell k">peers</div><div class="cell t">array</div><div class="cell d">[]</div><div class="cell dsc">Peer list in "node_id=host:port" format. The local node identifies itself from the entry matching bind_address:port. Example: ["a=10.0.0.1:9300","b=10.0.0.2:9300","c=10.0.0.3:9300"].</div><div class="cell k">tick_ms</div><div class="cell t">u64</div><div class="cell d">50</div><div class="cell dsc">Raft tick interval (ms). Lower = faster leader election at the cost of CPU.</div><div class="cell k">auth_secret</div><div class="cell t">string</div><div class="cell d">""</div><div class="cell dsc">Cluster-wide shared secret authenticating every control frame on port (HMAC-SHA256 over a per-connection challenge). Mandatory when enabled = true — with cluster mode on and no secret here or in XERJ_CLUSTER_AUTH_SECRET the node refuses to start. Same value on every node; minimum 16 chars; generate with `openssl rand -hex 32`. Authenticates, does not encrypt.</div></div>
+ <div class="cfg"><div class="head">KEY</div><div class="head">TYPE</div><div class="head">DEFAULT</div><div class="head">DESCRIPTION</div><div class="group" id="server">[server]</div><div class="cell k">rest_port</div><div class="cell t">u16</div><div class="cell d">8080</div><div class="cell dsc">Native REST API listener port. All native endpoints (/v1/*) live here.</div><div class="cell k">grpc_port</div><div class="cell t">u16</div><div class="cell d">8081</div><div class="cell dsc">Reserved for a future gRPC API. Not wired in v0.1 — leave at default.</div><div class="cell k">es_compat_port</div><div class="cell t">u16</div><div class="cell d">9200</div><div class="cell dsc">Elasticsearch-compatible wire port. Point Kibana, Logstash, or the ES client here. Set to 0 to disable.</div><div class="cell k">bind_address</div><div class="cell t">string</div><div class="cell d">"127.0.0.1"</div><div class="cell dsc">Interface to bind every listener to. Loopback by default, so an unconfigured node is unreachable from the network. Set "0.0.0.0" or a private address to expose it (also --bind / XERJ_BIND_ADDRESS). Must be an IPv4 or IPv6 literal — host names are not resolved, and a node given one refuses to start.</div><div class="cell k">allow_insecure_network_bind</div><div class="cell t">bool</div><div class="cell d">false</div><div class="cell dsc">Permit a non-loopback bind_address while tls.enabled = false. Startup refuses that combination otherwise: every listener would serve plain HTTP, so the API key in every Authorization header crosses the network in cleartext. Set true only when a proxy, sidecar, mesh or container boundary terminates TLS in front of the node. Env: XERJ_ALLOW_INSECURE_NETWORK_BIND.</div><div class="cell k">data_dir</div><div class="cell t">path</div><div class="cell d">"./data"</div><div class="cell dsc">Root for indices, WAL files, and segments. Needs fast I/O and enough free space.</div><div class="group" id="auth">[auth]</div><div class="cell k">enabled</div><div class="cell t">bool</div><div class="cell d">true</div><div class="cell dsc">Require an API key on every request. Set to false only on a trusted network.</div><div class="cell k">admin_api_key</div><div class="cell t">string</div><div class="cell d">""</div><div class="cell dsc">Static admin key. Left empty, a 256-bit key is generated on first run and written to <data_dir>/admin.key.</div><div class="group" id="tls">[tls]</div><div class="cell k">enabled</div><div class="cell t">bool</div><div class="cell d">false</div><div class="cell dsc">Terminate TLS at the server. Requires cert_path + key_path. If you terminate at a proxy, leave false.</div><div class="cell k">cert_path</div><div class="cell t">path</div><div class="cell d">""</div><div class="cell dsc">PEM X.509 certificate. Use a CA-signed cert in production.</div><div class="cell k">key_path</div><div class="cell t">path</div><div class="cell d">""</div><div class="cell dsc">PEM private key. Permissions should be 0600.</div><div class="group" id="storage">[storage]</div><div class="cell k">wal_sync</div><div class="cell t">enum</div><div class="cell d">"batched"</div><div class="cell dsc">"sync" · "batched" · "async". Durability vs throughput. Batched is the recommended default.</div><div class="cell k">wal_batch_ms</div><div class="cell t">u32</div><div class="cell d">100</div><div class="cell dsc">Fsync cadence when wal_sync="batched" (ms). Range 1–10000. Lower = smaller loss window.</div><div class="cell k">wal_max_size_mb</div><div class="cell t">u32</div><div class="cell d">512</div><div class="cell dsc">WAL rollover threshold (MiB). Larger means fewer rollovers, longer crash recovery.</div><div class="cell k">flush_size_mb</div><div class="cell t">u32</div><div class="cell d">256</div><div class="cell dsc">Memtable buffer size that triggers a segment flush (MiB).</div><div class="cell k">flush_interval_secs</div><div class="cell t">u32</div><div class="cell d">30</div><div class="cell dsc">Maximum wall-clock interval between flushes even if the buffer is not full.</div><div class="group" id="merge">[merge]</div><div class="cell k">strategy</div><div class="cell t">enum</div><div class="cell d">"size_tiered"</div><div class="cell dsc">"size_tiered" or "log_structured". Size-tiered for write-heavy, log-structured for mixed workloads.</div><div class="cell k">min_segments</div><div class="cell t">u32</div><div class="cell d">10</div><div class="cell dsc">Minimum live segments before a merge pass is scheduled. Must be ≥ 2.</div><div class="cell k">max_segment_mb</div><div class="cell t">u32</div><div class="cell d">5120</div><div class="cell dsc">Upper bound on a mergeable segment (MiB). Segments larger than this are never merged.</div><div class="cell k">io_rate_mb_per_sec</div><div class="cell t">u32</div><div class="cell d">100</div><div class="cell dsc">Merge I/O throttle (MiB/s). Set 0 to disable — not recommended in production.</div><div class="cell k">max_concurrent</div><div class="cell t">u8</div><div class="cell d">1</div><div class="cell dsc">Concurrent merge workers per index. Bump to 2–4 on fast NVMe.</div><div class="group" id="compression">[compression]</div><div class="cell k">enabled</div><div class="cell t">bool</div><div class="cell d">true</div><div class="cell dsc">Block-level compression. Disabling increases disk usage and lowers read CPU.</div><div class="cell k">level</div><div class="cell t">enum</div><div class="cell d">"balanced"</div><div class="cell dsc">"fast" (LZ4), "balanced" (Zstd L3, default), "best" (Zstd L19, cold storage).</div><div class="cell k">block_size_docs</div><div class="cell t">u32</div><div class="cell d">128</div><div class="cell dsc">Docs per compressed block. Range 16–4096. Larger = better ratio, higher fetch cost.</div><div class="group" id="fts">[fts]</div><div class="cell k">default_analyzer</div><div class="cell t">enum</div><div class="cell d">"standard"</div><div class="cell dsc">"standard" · "whitespace" · "simple" · "english". Override per-field in the mapping.</div><div class="group" id="vector">[vector]</div><div class="cell k">default_metric</div><div class="cell t">enum</div><div class="cell d">"cosine"</div><div class="cell dsc">"cosine" · "dot_product" · "euclidean". Cosine for text embeddings is the usual choice.</div><div class="cell k">hnsw_m</div><div class="cell t">u32</div><div class="cell d">16</div><div class="cell dsc">Accepted and validated; the built-in HNSW graph currently builds with fixed M=16 — this key is not yet wired to the build.</div><div class="cell k">hnsw_ef_construction</div><div class="cell t">u32</div><div class="cell d">200</div><div class="cell dsc">Accepted; must be ≥ hnsw_m. The graph currently builds with fixed ef_construction=200 — this key is not yet wired to the build.</div><div class="cell k">hnsw_ef_search</div><div class="cell t">u32</div><div class="cell d">100</div><div class="cell dsc">Accepted but not read by the serving path — the ANN beam width comes from the request's num_candidates (floored at 800).</div><div class="cell k">default_quantization</div><div class="cell t">enum</div><div class="cell d">"scalar8"</div><div class="cell dsc">"none" · "scalar8" · "scalar4" · "binary". scalar8 = 4× RAM saving, 1–2% recall loss.</div><div class="cell k">max_dimensions</div><div class="cell t">u32</div><div class="cell d">16384</div><div class="cell dsc">Upper bound on vector dimensionality. 4× the Elasticsearch limit of 4096.</div><div class="group" id="logs">[logs]</div><div class="cell k">retention_days</div><div class="cell t">u32</div><div class="cell d">90</div><div class="cell dsc">Auto-delete log docs older than N days. 0 disables.</div><div class="cell k">time_partition</div><div class="cell t">enum</div><div class="cell d">"1h"</div><div class="cell dsc">"1m" · "5m" · "15m" · "1h" · "6h" · "1d". Time-slice granularity for retention pruning.</div><div class="group" id="embedding">[embedding]</div><div class="cell k">default_endpoint</div><div class="cell t">string</div><div class="cell d">""</div><div class="cell dsc">OpenAI-compatible embeddings URL. Empty disables auto-embedding on ingest. Example: "https://api.openai.com/v1/embeddings".</div><div class="cell k">default_model</div><div class="cell t">string</div><div class="cell d">""</div><div class="cell dsc">Model name passed to the endpoint. Example: "text-embedding-3-small" or "nomic-embed-text".</div><div class="cell k">batch_size</div><div class="cell t">u32</div><div class="cell d">64</div><div class="cell dsc">Docs per embedding API call. Range 1–2048. Bigger batches amortise round-trip cost.</div><div class="cell k">timeout_ms</div><div class="cell t">u32</div><div class="cell d">5000</div><div class="cell dsc">HTTP timeout for embedding calls (ms). Ingest fails with a timeout error if exceeded.</div><div class="group" id="limits">[limits]</div><div class="cell k">max_query_memory_mb</div><div class="cell t">u32</div><div class="cell d">512</div><div class="cell dsc">Per-query memory cap (MiB). Queries that exceed it are cancelled.</div><div class="cell k">max_concurrent_searches</div><div class="cell t">u32</div><div class="cell d">64</div><div class="cell dsc">Global in-flight search ceiling. Extras are queued.</div><div class="cell k">max_fields_per_index</div><div class="cell t">u32</div><div class="cell d">500</div><div class="cell dsc">Field-explosion protection. ES default is 1000; 500 is intentionally stricter.</div><div class="group" id="indexing">[indexing]</div><div class="cell k">turbo_batch_size</div><div class="cell t">u32</div><div class="cell d">1000</div><div class="cell dsc">Docs per batch in turbo mode. Range 500–5000. Larger = higher throughput, slightly higher latency.</div><div class="cell k">turbo_parallel</div><div class="cell t">bool</div><div class="cell d">true</div><div class="cell dsc">Parallel tokenisation on Rayon threads. Disable only for debugging.</div><div class="cell k">turbo_fast_analyzer</div><div class="cell t">bool</div><div class="cell d">false</div><div class="cell dsc">Skip stemming and stop-word removal in turbo mode. Trades recall for speed.</div><div class="group" id="cluster">[cluster]</div><div class="cell k">enabled</div><div class="cell t">bool</div><div class="cell d">false</div><div class="cell dsc">Enable multi-node cluster mode. When true, the Raft state machine and cluster transport are started on port.</div><div class="cell k">port</div><div class="cell t">u16</div><div class="cell d">9300</div><div class="cell dsc">TCP port for intra-cluster Raft and search messages. Must be reachable from every peer.</div><div class="cell k">peers</div><div class="cell t">array</div><div class="cell d">[]</div><div class="cell dsc">Peer list in "node_id=host:port" format. The local node identifies itself from the entry matching bind_address:port. Example: ["a=10.0.0.1:9300","b=10.0.0.2:9300","c=10.0.0.3:9300"].</div><div class="cell k">tick_ms</div><div class="cell t">u64</div><div class="cell d">50</div><div class="cell dsc">Raft tick interval (ms). Lower = faster leader election at the cost of CPU.</div><div class="cell k">auth_secret</div><div class="cell t">string</div><div class="cell d">""</div><div class="cell dsc">Cluster-wide shared secret authenticating every control frame on port (HMAC-SHA256 over a per-connection challenge). Mandatory when enabled = true — with cluster mode on and no secret here or in XERJ_CLUSTER_AUTH_SECRET the node refuses to start. Same value on every node; minimum 16 chars; generate with `openssl rand -hex 32`. Authenticates, does not encrypt.</div></div>
<h2 id="server-section">[server]</h2>