# Reference: server

URL: https://scalws.com/docs/reference/server/
Source: `docs/reference/schema` in the ScalWS repository

<h3 id="server.accept_policy"><code>server.accept_policy</code></h3>

| | |
|---|---|
| Syntax | `accept_policy: shared \| fountain` |
| Default | `shared` |
| Context | `server` |
| Reload | read when the process starts |

Which event loop takes a new connection from the shared accept queue (ADR-0044): `shared` (default), whichever loop wakes first; `fountain`, loops fill in order and a loop takes connections only while the loops before it are busy or hold twice their fair share of the open connections.


<h3 id="server.acme"><code>server.acme</code></h3>

| | |
|---|---|
| Syntax | `acme: {...}` |
| Default | `see the fields below` |
| Context | `server` |
| Reload | applies on reload |

Automatic certificates from an ACME CA such as Let's Encrypt (ADR-0018).


<h3 id="server.admin"><code>server.admin</code></h3>

| | |
|---|---|
| Syntax | `admin: {...}` |
| Default | `see the fields below` |
| Context | `server` |
| Reload | applies on reload |

Admin API used by scalwsctl and the console (ADR-0017).


<h3 id="server.ai"><code>server.ai</code></h3>

| | |
|---|---|
| Syntax | `ai: {...}` |
| Default | `see the fields below` |
| Context | `server` |
| Reload | applies on reload |

Optional local AI advisor (ADR-0016); advisory only.


<h3 id="server.cache"><code>server.cache</code></h3>

| | |
|---|---|
| Syntax | `cache: {...}` |
| Default | `see the fields below` |
| Context | `server` |
| Reload | applies on reload |

Memory (and optional disk) shared by applications that enable the response cache.


<h3 id="server.cgroups"><code>server.cgroups</code></h3>

| | |
|---|---|
| Syntax | `cgroups: {...}` |
| Default | `see the fields below` |
| Context | `server` |
| Reload | applies on reload |

cgroup v2 limits for managed applications (ADR-0010).


<h3 id="server.diagnostics"><code>server.diagnostics</code></h3>

| | |
|---|---|
| Syntax | `diagnostics: {...}` |
| Default | `see the fields below` |
| Context | `server` |
| Reload | applies on reload |

Slow-request threshold and the number of recent requests kept for diagnosis.


<h3 id="server.ebpf"><code>server.ebpf</code></h3>

| | |
|---|---|
| Syntax | `ebpf: {...}` |
| Default | `see the fields below` |
| Context | `server` |
| Reload | applies on reload |

Optional eBPF network accounting (ADR-0025, builds with the `ebpf` feature).


<h3 id="server.event_loops"><code>server.event_loops</code></h3>

| | |
|---|---|
| Syntax | `event_loops: <integer>` |
| Default | `one per CPU` |
| Context | `server` |
| Reload | needs a restart |

Per-core event loops (ADR-0029): unset = one per CPU, `0` = one shared work-stealing runtime. Linux only (elsewhere always shared).


<h3 id="server.health"><code>server.health</code></h3>

| | |
|---|---|
| Syntax | `health: {...}` |
| Default | `see the fields below` |
| Context | `server` |
| Reload | applies on reload |

Plain HTTP listener for orchestrator probes: `/healthz`, `/readyz` and optionally `/metrics`; nothing else.


<h3 id="server.http1_server"><code>server.http1_server</code></h3>

| | |
|---|---|
| Syntax | `http1_server: hyper \| experimental` |
| Default | `hyper` |
| Context | `server` |
| Reload | applies on reload |

HTTP/1 server implementation (ADR-0046): `hyper` (default) or `experimental`: scalws's own. Applies to connections accepted after a reload.


<h3 id="server.ktls"><code>server.ktls</code></h3>

| | |
|---|---|
| Syntax | `ktls: true \| false` |
| Default | `false` |
| Context | `server` |
| Reload | read when the process starts |

Kernel TLS for HTTPS/1.1 file bodies (Linux, `modprobe tls`; ADR-0030).


<h3 id="server.limits"><code>server.limits</code></h3>

| | |
|---|---|
| Syntax | `limits: {...}` |
| Default | `see the fields below` |
| Context | `server` |
| Reload | applies on reload |

Connection, header, body and timeout limits for every client connection.


<h3 id="server.listen_socket"><code>server.listen_socket</code></h3>

| | |
|---|---|
| Syntax | `listen_socket: <string>` |
| Default | `none` |
| Context | `server` |
| Reload | read when the process starts |

Unix socket that hands out the listening sockets for `listener_mode: inherited` (set by scalws-controller through `--listen-socket`).


<h3 id="server.listener_mode"><code>server.listener_mode</code></h3>

| | |
|---|---|
| Syntax | `listener_mode: shared \| reuseport \| inherited` |
| Default | `shared` |
| Context | `server` |
| Reload | read when the process starts |

How listening sockets are opened (ADR-0033): `shared` (default), one socket per address shared by this process's event loops; `reuseport`: one `SO_REUSEPORT` socket per event loop, so several scalwsd instances can serve the same address; `inherited`: the sockets are received from `listen_socket` (opened by scalws-controller; every instance accepts from the same queue). Linux only.


<h3 id="server.listeners"><code>server.listeners</code></h3>

| | |
|---|---|
| Syntax | `listeners: [{...}, ...]` |
| Default | `required` |
| Context | `server` |
| Reload | adding or removing it needs a restart; its values apply on reload |

Addresses the server accepts connections on, plain or TLS.


<h3 id="server.logging"><code>server.logging</code></h3>

| | |
|---|---|
| Syntax | `logging: {...}` |
| Default | `see the fields below` |
| Context | `server` |
| Reload | applies on reload |

Log format, level and access logging.


<h3 id="server.loop_lag_probe"><code>server.loop_lag_probe</code></h3>

| | |
|---|---|
| Syntax | `loop_lag_probe: true \| false` |
| Default | `false` |
| Context | `server` |
| Reload | applies on reload |

Measure event-loop lag (a 100 ms timer per loop) and export `scalws_event_loop_lag_seconds` (Adaptive Runtime pressure signal, ADR-0034). Off by default; on for instances started by the controller.


<h3 id="server.metrics"><code>server.metrics</code></h3>

| | |
|---|---|
| Syntax | `metrics: {...}` |
| Default | `see the fields below` |
| Context | `server` |
| Reload | applies on reload |

Loopback listener for `/metrics`, `/healthz`, `/readyz` and the dashboard.


<h3 id="server.open_file_cache"><code>server.open_file_cache</code></h3>

| | |
|---|---|
| Syntax | `open_file_cache: {...}` |
| Default | `see the fields below` |
| Context | `server` |
| Reload | applies on reload |

Open file cache for static files (ADR-0028).


<h3 id="server.optimizer"><code>server.optimizer</code></h3>

| | |
|---|---|
| Syntax | `optimizer: {...}` |
| Default | `see the fields below` |
| Context | `server` |
| Reload | applies on reload |

Deterministic optimizer that evaluates every application periodically (ADR-0014).


<h3 id="server.reload"><code>server.reload</code></h3>

| | |
|---|---|
| Syntax | `reload: {...}` |
| Default | `see the fields below` |
| Context | `server` |
| Reload | applies on reload |

Watch the configuration, its site files and listener certificates, and reload when one of them changes (for Kubernetes ConfigMap and Secret volumes).


<h3 id="server.runtime_dir"><code>server.runtime_dir</code></h3>

| | |
|---|---|
| Syntax | `runtime_dir: <string>` |
| Default | `/run/scalws` |
| Context | `server` |
| Reload | needs a restart |

Directory for managed runtimes' sockets and generated configuration (ADR-0008).


<h3 id="server.sandbox"><code>server.sandbox</code></h3>

| | |
|---|---|
| Syntax | `sandbox: {...}` |
| Default | `none` |
| Context | `server` |
| Reload | read when the process starts |

In-process sandbox of scalwsd (Landlock and seccomp, Linux): `off` (default), `audit` or `on`, or a map with `mode`, `read_paths` and `write_paths` (docs/guide/sandbox.md).


<h3 id="server.security"><code>server.security</code></h3>

| | |
|---|---|
| Syntax | `security: {...}` |
| Default | `see the fields below` |
| Context | `server` |
| Reload | applies on reload |

Per-client connection and request limits.


<h3 id="server.sendfile"><code>server.sendfile</code></h3>

| | |
|---|---|
| Syntax | `sendfile: true \| false` |
| Default | `true` |
| Context | `server` |
| Reload | applies on reload |

Large static files on plain-TCP HTTP/1 connections are sent with `sendfile(2)` (Linux, ADR-0027).


<h3 id="server.trusted_proxies"><code>server.trusted_proxies</code></h3>

| | |
|---|---|
| Syntax | `trusted_proxies: [<string>, ...]` |
| Default | `[]` |
| Context | `server` |
| Reload | applies on reload |

Peers (CIDRs) allowed to report the client address via `X-Forwarded-For` or the PROXY protocol (ADR-0022), e.g. your load balancers.


<h3 id="server.upstream_client"><code>server.upstream_client</code></h3>

| | |
|---|---|
| Syntax | `upstream_client: hyper \| experimental` |
| Default | `hyper` |
| Context | `server` |
| Reload | read when the process starts |

HTTP/1 client of every proxy and managed application (ADR-0045): `hyper` (default) or `experimental`. A proxy route's `client` overrides it. Read at start-up (a reload keeps the running value; route-level `client` changes apply on reload).