Configuration reference

The configuration tree

With no --root, httpjet uses /usr/local/lsws. The parser (hj-config) applies LiteSpeed value semantics faithfully:

• Variables $SERVER_ROOT, $HOSTNAME, $VH_ROOT, $VH_NAME substitute in $VAR and ${VAR} forms.
• Sizes accept K/M/G/B suffixes; times are bare seconds.
• Bounded integers use OLS semantics: absent, unparsable or out-of-range values fall back to the default (never clamped). The isolation modes setUIDMode/chrootMode are the exception: out-of-range is a hard error (2026-09-16).
• Booleans are 1, 2 or true (case-insensitive); followSymbolLink/allowSymbolLink treat 2 (owner-restricted) as fail-closed never-follow.
• Unknown elements are ignored so real trees load; check --strict reports the ones that would silently do nothing.

/usr/local/lsws/
├── conf/
│   ├── httpd_config.xml          # server, tuning, security, listeners, extProcessors, vhost declarations
│   ├── mime.properties           # mime/type = ext1, ext2   (best-effort)
│   └── vhosts/example.test.xml   # <virtualHostConfig>: docroot, contexts, rewrite, vhssl, cache, logging
└── logs/

flowchart TB
  classDef srv fill:#13203a,stroke:#818cf8,color:#fff
  classDef vh fill:#0e1424,stroke:#22d3ee,color:#e8ecf6
  classDef ctx fill:#141b2e,stroke:#e879f9,color:#e8ecf6
  classDef ht fill:#0f2a24,stroke:#34d399,color:#fff
  S["httpd_config.xml (server root)<br/>tuning · security · listeners · extProcessorList · vhostMapList"]:::srv
  V["vhosts/<name>.xml (virtualHostConfig)<br/>docRoot · vhssl · rewrite · cache · suEXEC · logging"]:::vh
  C["<context> prefix match (longest prefix wins)<br/>type (static|proxy|lsapi|redirect) · maxReqBodySize · responseTimeout · bandwidthLimit · subFilter · cachePolicy"]:::ctx
  H[".htaccess chain (docroot → target dir, depth ≤ 64)<br/>SetEnvIf · Order/Allow/Deny · Require · RewriteCond/Rule · Header · Expires* · CacheLookup"]:::ht
  M["parse-time MemoClass verdict (httpjet check)<br/>eligible + vary-set (Origin, UA bitmap) vs ineligible (Remote_Addr, Cookie, IP ACL)"]:::srv
  S -- "vhost defaults + allowSymbolLink fold" --> V
  V -- "URI prefix routing" --> C
  V -- "allowOverride = 1" --> H
  H -- "static analysis at load" --> M
  click S "configuration.html#server"
  click V "configuration.html#vhosts"
  click C "configuration.html#contexts"
  click H "rewrite.html#loading"
  click M "rewrite.html#memo"

Server and tuning

Security directives

Listeners and TLS

<quic><quicEnable>1</quicEnable></quic>
<listenerList>
  <listener>
    <name>https</name>
    <address>*:443</address>
    <secure>1</secure>
    <keyFile>/etc/letsencrypt/live/example.test/privkey.pem</keyFile>
    <certFile>/etc/letsencrypt/live/example.test/fullchain.pem</certFile>
    <clientVerify>0</clientVerify>
    <vhostMapList><vhostMap><vhost>example.test</vhost><domain>example.test,www.example.test</domain></vhostMap></vhostMapList>
  </listener>
</listenerList>

External processors

An <extProcessor> (server-level <extProcessorList> or per-vhost) is a reverse-proxy upstream (proxy), an LSAPI app (lsapi), or httpjet a FastCGI app (fcgi/fastcgi). <phpConfig> configures the default PHP handler with the same pool knobs. Unknown legacy types (rails, appserver, …) keep proxy behavior; cgi contexts are not executed.

Virtual hosts

Declarations live in httpd_config.xml (name, vhRoot, configFile, allowSymbolLink, enableScript, restrained); behavior lives in the referenced <virtualHostConfig>. allowSymbolLink is a tri-state override (file > declaration > server); restrained confines the vhost to vhRoot and forces symlinks off; enableScript=0 disables script handlers for the vhost.

Contexts

Contexts map URI prefixes to terminals (static, proxy, redirect, php/lsapi via handler) and carry per-context overrides:

<contextList>
  <context>
    <type>proxy</type>
    <uri>/api/</uri>
    <handler>application</handler>
    <maxReqBodySize>2M</maxReqBodySize>
    <responseTimeout>15</responseTimeout>
    <subFilter>http://internal.example => https://example.test</subFilter>
    <subFilterTypes>text/html,application/json</subFilterTypes>
  </context>
</contextList>

Checking a configuration

httpjet --root /abs/root check            # summary: listeners, vhost map, fast-memo verdicts, warnings
httpjet --root /abs/root check --strict   # + topology lint, missing docroots, vhost-map-fingerprint; non-zero on findings

Run the check under the intended service identity as well as as root: readable-by-root is not proof the runtime user can read certificates or write logs and sockets. The same normalization runs for the write API's in-memory bundle (parse_bundle), which additionally refuses DTDs, more than 64 nesting levels, more than 128 vhosts, and 1 MiB of XML. A config file read from disk is capped at 16 MiB per file (ConfigError::TooLarge, 2026-10-06) — a bound on all readers, check included.

Environment variables

The full list, with the flags they pair with, is on the CLI reference. The ones most often set in a unit drop-in: HTTPJET_ACCESS_LOG_FORMAT=json, HTTPJET_ERROR_LOG_FORMAT=json, HTTPJET_SYSLOG_TARGET, CF_SEND_ZSTD=1, HJ_FAST_MEMO=0, HTTPJET_OTEL=1, RUST_LOG.