Configuration

Every key in ephpm.toml, with type, default, and a short description. The source of truth is crates/ephpm-config/src/lib.rs — if a field has been added there but not here, that’s a doc bug.

All sections and keys are optional. Missing sections use defaults; Config::default_config() produces a fully working configuration.

[server]

[server.request]

[server.timeouts] (all in seconds)

[server.response]

[server.static]

[server.php_etag_cache]

[server.security]

Note: an explicitly set value always wins. When unset, these two resolve to true if either the [server.security] section is present (matching earlier releases) or server.sites_dir is set — so multi-tenant deployments get filesystem isolation and shell-exec hardening by default, even without a [server.security] section. To opt out in multi-tenant mode you must set them to false explicitly (ephpm logs a warning at startup when you do).

[server.logging]

[server.metrics]

[server.limits]

[server.file_cache]

[server.tls]

Two mutually exclusive modes — manual (cert+key) or ACME (domains). If both are set, manual wins.

[php]

Worker mode is not supported with [server] sites_dir (multi-tenant vhosting) in Phase 1 — config load hard-errors. Worker mode boots one framework per worker; per-host worker pools are a later phase.

Resource-aware autotuning

On boot, ephpm serve detects the container’s CPU and memory limits (cgroup-aware) and derives a tuned set of PHP/OPcache ini defaults sized to the box it is actually running on. This is the deploys-are-events, right-size-the-runtime story: you ship the same image to a 320 MiB / 0.25-CPU pod and a 4 GiB / 4-CPU node, and each one sizes OPcache, the per-request memory limit, interned-string and JIT buffers, and the realpath cache to fit — without a per-environment config file.

Detection (Linux):

1. CPU quota — cgroup v2 cpu.max, else v1 cpu.cfs_quota_us/cpu.cfs_period_us. None when unlimited. (Already drives worker_count.)
2. Memory budget — cgroup v2 /sys/fs/cgroup/memory.max, else v1 memory.limit_in_bytes; "max"/the unlimited sentinel means no limit, in which case ePHPm falls back to total system memory (/proc/meminfo MemTotal). No new crate — it reads the same cgroupfs//proc files as the CPU path.

Non-Linux platforms have no cgroup limit and keep PHP defaults for memory-shaped knobs.

Derivation (serve mode):

Dev mode (ephpm dev / bare ephpm) derives none of these: it keeps PHP-friendly defaults (timestamp validation on, assertions on, loose realpath) so the edit-refresh loop stays tight.

Resolution precedence (per directive): explicit [php] value → auto-derived → PHP stock default. Pin any single knob (e.g. opcache_memory_consumption = 256) and the rest keep auto-tuning. ini_overrides still layers last as the ultimate escape hatch.

Transparency: serve startup logs one INFO line summarizing what was detected and derived, marking any explicitly-pinned value with a *. Example for a 320 MiB / 0.25-CPU pod:

autotune (serve): cpu_quota=0.25 mem=320MiB (cgroup v2) -> workers=1[cgroup_quota] opcache.memory_consumption=64MB memory_limit=192M interned=8MB jit_buffer=32MB (buffer-only, jit off) max_files=20000 realpath=16M/ttl=600 validate_timestamps=0 assertions=-1

and for a 4 GiB / 4-CPU node:

autotune (serve): cpu_quota=4.00 mem=4096MiB (cgroup v2) -> workers=4[cgroup_quota] opcache.memory_consumption=512MB memory_limit=880M interned=32MB jit_buffer=64MB (buffer-only, jit off) max_files=20000 realpath=16M/ttl=600 validate_timestamps=0 assertions=-1

[db]

[db.mysql] / [db.postgres] / [db.tds]

All three share the same backend config schema. Adding a [db.mysql] or [db.postgres] section enables that proxy. The TDS proxy is not yet implemented — a [db.tds] section is accepted, but startup logs a warning and skips it.

The proxy listener is unauthenticated — keep it on loopback. The proxy does not validate client credentials. The MySQL proxy reads the client handshake response and discards it; the PostgreSQL proxy answers any startup message with AuthenticationOk. The real credentials in url are used only for the proxy’s own pooled connections to the backend, and are never required of the client.

Binding listen to a non-loopback address therefore gives full read/write access to your database to any host that can reach the port. ePHPm logs a startup warning when listen is a non-loopback IP literal (0.0.0.0:3306, 10.0.0.5:3306, …), but does not refuse to start — binding 0.0.0.0 inside a container that is firewalled by a network policy is a legitimate deployment. Addresses given as hostnames (localhost:3306, db.internal:3306) are not classified, because that would require a DNS lookup at startup; no warning is logged for them either way.

Startup: the upstream does not have to be reachable

The proxy binds listen at startup and reaches url from a background task, retrying forever with exponential backoff (250 ms doubling to a 30 s ceiling). A database that is slower to start than ePHPm — or that restarts later — is picked up when it appears; no ePHPm restart is needed.

Clients that connect during the first 5 seconds of that window queue in the kernel accept backlog rather than getting ECONNREFUSED, so PHP’s first request waits a moment and then succeeds. Past 5 seconds the proxy accepts and immediately closes each client, so callers fail fast: a client whose TCP connect succeeded would otherwise block reading a server greeting that never comes, and mysqlnd’s read timeout is 24 hours by default — that would pin a PHP worker until the HTTP request deadline. PHP reports the close promptly (Lost connection to MySQL server at 'reading initial communication packet').

Two things are fatal at startup, because both are configuration errors: a url that cannot be parsed, and a listen address that cannot be bound.

Readiness and the database proxy

/_ephpm/ready reports 503 until every configured proxy has reached its upstream once. A process whose proxy has never connected cannot serve a single query, so it must stay out of load-balancer rotation, and a rollout containing such a pod should stall rather than replace healthy pods.

After that first success, readiness never flaps on upstream state again. This is deliberate: gating readiness on live database reachability would fail every replica’s probe at the same instant during a shared-database outage, empty the Service, and turn a degraded database into a total outage — including for the static assets and non-DB routes those pods could still serve. Liveness (/_ephpm/health) stays green throughout; restarting the process does not bring a remote database back.

A post-startup outage is reported instead of routed around: ephpm_db_proxy_upstream_up drops to 0, ephpm_db_proxy_connect_failures_total climbs, and the proxy logs at ERROR (throttled to one line per minute). See Metrics → Database (proxy upstream health).

[db.sqlite]

[db.sqlite.proxy]

These listeners are unauthenticated too. litewire’s MySQL, Hrana, PostgreSQL, and TDS frontends accept any client — the PostgreSQL frontend is explicitly wired to a no-op startup handler, and the others never ask for credentials. The design assumes only PHP inside this process reaches them. As with [db.mysql], each of these four keys is checked at startup and a non-loopback IP literal logs a warning naming the risk; startup is not blocked. Bind loopback unless the port is firewalled from untrusted networks.

[db.sqlite.sqld] (clustered mode only)

[db.sqlite.replication] (clustered mode only)

[db.read_write_split]

[db.analysis]

What query stats cover

One collector serves every database path, so proxied and embedded queries land on the same metric names with no extra label to distinguish them. What each path can see differs, because the proxy only observes statements at the points where it already parses the wire protocol:

No reset_strategy value turns recording off on either engine — every proxy path frames the wire protocol.

Notable gaps, all deliberate:

• Proxy durations include the network. The embedded-SQLite numbers are in-process execution time; the proxy numbers are a round trip to your database server. Comparing them directly is comparing two different things.
• COM_STMT_PREPARE is never recorded. Preparing is a metadata round trip, not an execution — recording it under the statement’s digest would publish parse latency as query latency.
• COM_STMT_EXECUTE is invisible on the default MySQL path. Attributing an execute to its SQL requires having parsed the prepare response, which only the R/W-split routing loop does. Applications that turn off PDO’s emulated prepares (PDO::ATTR_EMULATE_PREPARES = false) will therefore see little or no proxy query-stat traffic unless R/W splitting is on.
• PostgreSQL extended-protocol executions are invisible. Messages stay framed, but attributing an Execute to the SQL a Parse carried means tracking named statements and portals across the session; recording the Parse alone would publish planning time as query time, exactly as for COM_STMT_PREPARE. Same for COPY. A simple Query issued later on such a session is recorded.
• MySQL durations on the single-backend path are an upper bound. That path does not frame the backend→client direction, so completion is inferred from the arrival of the next client command. PostgreSQL has an explicit ReadyForQuery marker on every path and is exact everywhere.
• Rows the proxy cannot count are reported as 0, never estimated.

[kv]

[kv.redis_compat]

[cluster]

[cluster.channel]

Experimental-adjacent. The cluster channel is a single, authenticated, yamux-multiplexed TCP listener that opt-in cluster features share (Turso CDC replication and its snapshot bootstrap today). It is only bound when at least one feature asks for it: a config that ships no channel feature is byte-identical to a config without this section — no socket, no task, no startup log noise above debug!. Adding [cluster.channel] to a config is not itself an opt-in; a feature elsewhere (today just [db.sqlite.replication] cdc_experimental = true in clustered mode) has to ask. See the cluster channel roadmap for the design.

Security posture. Connections complete a mutual challenge/response handshake in which both peers prove possession of the shared secret and both contribute fresh randomness, so a recorded handshake cannot be replayed. Both ends then derive a per-connection key from the secret salted with the handshake transcript, and every subsequent byte — yamux framing included — is sealed with ChaCha20-Poly1305. Inbound connections must additionally come from an IP that gossip currently knows as a cluster member. There is no TLS and no certificate-based peer identity: authentication is “holds the shared cluster secret”, and the membership check is per-host and trusts the TCP source address.

[cluster.kv]

[[middleware]]

Native middleware mounts — repeatable array-of-tables. Each mount resolves against the builtin registry first: the four in-tree modules (jwt, cors, ratelimit, security-headers) are compiled into every binary and run in-process — no shared library on disk, no dlopen. Any other name loads a shared library (.so/.dylib/.dll) at startup. Loading is fail-fast: a builtin rejecting its config, an unresolvable library, a missing ABI symbol, or a failing module init aborts server startup. The chain is evaluated on every PHP-bound request, before the request body is read. Mounts apply globally, not per vhost — a module can discriminate by vhost via the request’s server name. See the Native Middleware guide.

Built-ins work in every binary. Shared-library mounts (custom out-of-tree modules) work out of the box with the stock release binaries on all platforms — the Linux release is glibc-dynamic (<arch>-unknown-linux-gnu), so dlopen is available. Only a self-built fully static musl binary lacks dlopen (Dynamic loading not supported at startup) — see the guide’s dynamic-lane section.

[opcache]

Governs the cluster-wide OPcache invalidation watcher (Phase 1 of the OPcache clustering roadmap). When enabled, every PHP request checks opcache:version:<vhost> in the in-process KV store and, when the value has advanced since this node last saw it, runs opcache_invalidate() for every cached script under the vhost’s docroot before executing the request. The lookup is one atomic load plus one DashMap::get — sub-microsecond in the fast path.

The companion CLI is ephpm deploy / ephpm cache reset — both write the version key via the RESP listener, so [kv.redis_compat] enabled = true is required for the CLI to reach the running server. See the roadmap page for the wire semantics.

See also

• Environment variables — how to override any of these via EPHPM_*
• crates/ephpm-config/src/lib.rs — definitive source