Operations

Commands

Any other argument is an error: unknown argument "x", see xtq-web --help.

xtq-web check

xtq-web check /etc/xtq-web/xtq-web.conf

Loads the file exactly as a start or a reload would, without opening any ports, and reports what it found:

/etc/xtq-web/xtq-web.conf: OK
  listeners: 0.0.0.0:80,0.0.0.0:443(tls)
  sites:     example.com, api.example.com, *
  proxies:   3 routes, 5 backends
  php:       0

proxies counts proxy handlers and the backends they list. php counts php handlers.

Without a file argument it checks the file in XTQW_CONFIG. With neither, it fails with usage: xtq-web check <config file>, or set XTQW_CONFIG.

On a mistake it prints the error, with the file and line, and exits with a non-zero status:

Error: /etc/xtq-web/xtq-web.conf:9: proxy takes lb, health, health_interval, health_timeout, fail_duration, timeout, host, header_up, limit and max_body, not "retries"

The check also verifies things outside the file that a load needs, such as php docroots existing. Such errors name the line and then the cause:

Error: /etc/xtq-web/xtq-web.conf:5

Caused by:
    0: docroot /var/www/blog
    1: No such file or directory (os error 2)

IP list files that can't be read produce a warning, not a failure, just as at runtime. It does not need root, but it reads the files with your permissions, which may differ from the service user's.

Starting

At startup xTQ Web prints one line that sums up what it is doing:

xtq-web: config=/etc/xtq-web/xtq-web.conf listeners=0.0.0.0:80,0.0.0.0:443(tls) sites=example.com,* backends=2 cache=true max_conns=16384 max_handshakes=8 nofile=1048576

config=environment means XTQW_CONFIG was not set and xTQ Web is running in environment-only mode.

If a listen address is taken, xTQ Web does not fail. It retries every 100 ms and logs once:

xtq-web: can't listen on 0.0.0.0:80 yet (Address already in use (os error 98)), retrying every 100 ms
xtq-web: now listening on 0.0.0.0:80

That lets you start xTQ Web while the server it replaces is still running. Stop the old one and xTQ Web picks the port up within 100 ms. Other listeners work in the meantime.

Signals and reloads

Reload

sudo systemctl reload xtq-web

Under the packaged service, reload runs xtq-web check first and sends SIGHUP only if the config passes. If the check fails, systemctl reload reports the failure and the running server is not touched.

Outside systemd, send the signal yourself:

sudo kill -HUP "$(pidof xtq-web)"
docker kill -s HUP xtq-web

On SIGHUP xTQ Web reads the config file again, and the files it names. If the new config loads, it logs:

xtq-web: reloaded /etc/xtq-web/xtq-web.conf: listeners=0.0.0.0:80,0.0.0.0:443(tls) sites=example.com,*

and from then on:

• New requests use the new sites and routes. Requests already in flight finish on the old ones.
• New listen addresses are opened. Listeners that are gone stop accepting (stopped listening on ...). Listeners that stay are not touched, so nobody is disconnected.
• Proxy pools start fresh: health checks run again at once, and passive failure marks, idle backend connections and in-flight counts start from zero.
• Certificate management restarts, so missing certificates are tried again at once.
• The page and file cache, issued certificates and open connections are kept.
• Without XTQW_SECRET, browser check passes stop being valid.

If the new config has a mistake, it is refused and the running config keeps serving:

xtq-web: reload refused, still serving the previous config: /etc/xtq-web/xtq-web.conf:14: unknown directive "proxi"

Environment variables are not read again on reload. After changing one, restart.

Windows has no SIGHUP. There, restart to apply a change.

Stop

SIGTERM (what systemctl stop and docker stop send) and SIGINT stop the process gracefully:

• xTQ Web stops accepting new connections at once.
• Each open connection finishes the request it is working on. Keep-alive connections are closed after that request instead of waiting for another.
• It waits until every connection is done, or XTQW_DRAIN_SECS seconds have passed (default 10), and exits.

While connections are open, it logs:

xtq-web: stopping, letting 12 open connection(s) finish (up to 10s)

With no open connections it exits at once. XTQW_DRAIN_SECS=0 exits at once in any case. WebSockets that were already handed off to their backend are not waited for, and are closed when the process exits. A long download that takes more than the drain time is cut.

The packaged unit gives the process 20 seconds to stop (TimeoutStopSec=20), and the Docker installer passes --stop-timeout 20, so the default drain fits. If you raise XTQW_DRAIN_SECS past that, raise those too, or systemd and Docker kill the process before it is done.

A restart therefore lets requests in flight finish, but new connections are refused from the moment the old process stops listening until the new one listens. For config changes, reload is still better: nothing is refused at all.

Logs

xTQ Web writes to standard error. Under systemd that ends up in the journal, in Docker in the container log:

journalctl -u xtq-web -f
docker logs -f xtq-web

xTQ Web does not write an access log. It logs events:

Dashboard, stats and metrics

Three paths show what xTQ Web is doing:

They are off until you set XTQW_ADMIN_TOKEN to a secret of at least 16 characters. A shorter token leaves them off. Use letters and digits only, for example:

openssl rand -hex 32

Put it in /etc/xtq-web/env and restart:

XTQW_ADMIN_TOKEN=3f9c...

Pass the token as a token query parameter or in an X-Xtq-Token header:

https://example.com/.xtq/dashboard?token=3f9c...

curl -H "X-Xtq-Token: $TOKEN" https://example.com/.xtq/stats.json
curl "https://example.com/.xtq/metrics?token=$TOKEN"

Without the token, or with a wrong one, these paths answer 404 like any unknown path. They work on every listener and every hostname, before any site is chosen, so you can also reach them on 127.0.0.1. Use HTTPS when you open them from outside, since the token travels in the URL or a header.

The dashboard shows requests per second, cache hit rate, browser checks, busy answers, connections, TLS handshakes, backend errors, proxied requests and open WebSockets. Below that come tables of PHP sites, proxy backends with their state and requests in flight, and issued certificates with the days they have left.

stats.json

Counters count since the process started. A reload does not reset them.

Prometheus

A scrape job with the token as a parameter:

scrape_configs:
  - job_name: xtq-web
    metrics_path: /.xtq/metrics
    params:
      token: ["3f9c..."]
    static_configs:
      - targets: ["127.0.0.1:80"]

Server and X-Powered-By

Every response gets Server: xtq-web and X-Powered-By: xTQ, replacing whatever the app sent. That also hides version banners like Next.js or PHP/8.3. A header line in a route can't change these two, because they are set last.

Any other value is sent as the header. With off, header lines can set or remove these headers like any other.

The X-Xtq-Cache header

Some responses say where they came from:

Reserved paths