ScalWSScalWS

    Get started
    ScalWSScalWS
    Get started

    Reference

    scalwsd

    scalwsd is the ScalWS web server daemon: it serves client traffic from one configuration file, either on its own as scalwsd.service or as an instance started by scalws-controller.

    scalwsd [OPTIONS]

    scalwsd --help lists the options; scalwsd --version prints the version.

    Options

    OptionDefaultMeaning
    -c, --config <PATH>$SCALWS_CONFIG, else /etc/scalws/scalws.yamlYAML configuration file.
    --checkValidates and prepares the configuration, then exits. Prints configuration OK, or exits with 2.
    --worker-threads <N>number of CPUsTokio worker threads. Also the per-core event-loop count unless server.event_loops is set.
    --wait-for-activationPrepares everything, but accepts client connections only after SIGUSR2. Until then /readyz on the metrics listener reports ready, and active after.
    --instance-id <ID>Instance identity under the controller: the runtime directory, admin socket and disk cache move to per-instance subdirectories, and the remote admin listener is not started. [a-z0-9-], at most 32 characters.
    --metrics-address <ADDR>Metrics listener address (/metrics, /healthz, /readyz) for this instance. Turns the metrics listener on.
    --reuseportSame as server.listener_mode: reuseport. Not allowed with HTTP/3 listeners.
    --listen-socket <PATH>Receives the listening sockets from this Unix socket (listener_mode: inherited, used by scalws-controller).
    --limit-share-file <PATH>A file holding the number of instances that share the configured per-client, route and tenant limits. Each limit is divided by that number, rounded up. Re-read on every reload.
    --tenant-limits-file <PATH>Run-time tenant limits to start with. Kept by scalws-controller.
    --sandbox-floor <MODE>$SCALWS_SANDBOX_FLOOR, else noneLowest sandbox mode (off, audit, on): the stricter of this and server.sandbox applies. scalws-controller passes it from its own record.
    --config-sha256 <HEX>SHA-256 the configuration file must have, given by scalws-controller from its own record. The bytes parsed at start and on every reload are checked against it; a mismatch fails the start (exit 2) or rejects the reload.
    --previous-config-sha256 <HEX>SHA-256 --previous-config must have; a file that differs is not compared with (a document root that cannot be opened then fails the start).
    --sandbox-selftestApplies the configured sandbox (as on) to this process, checks that it refuses what it must and allows what it must, prints the result and exits: 0 passed, 1 failed, 2 not applicable here.
    --featuresPrints the optional Cargo features the binary was built with, one per line (http3, mimalloc, ebpf, perf-instrumentation), and exits. The packages print http3 and mimalloc.
    --service-sandboxService sandbox for systems without systemd (OpenRC): the systemd unit’s write fence and system call settings, inherited by every program started.
    --service-rw <PATH>Extra writable directory of --service-sandbox (repeatable), the twin of ReadWritePaths=.
    --restrict-suid-sgidRefuses set-user/group-ID modes on files and directories this process and every program it starts create, like systemd’s RestrictSUIDSGID=, but leaves openat2 to the static files. The packaged unit passes it instead of that setting; --service-sandbox includes it. SCALWS_RESTRICT_SUID_SGID=false (in a drop-in) turns it off.
    --previous-config <PATH>The configuration of the generation this one replaces (given by scalws-controller on a reload). An application whose document root cannot be opened answers 503 only when its root and runtimes are unchanged from it; a new or changed one fails the start, so the controller rolls the generation back. Without it every such application answers 503.

    The instance options (--wait-for-activation, --instance-id, --listen-socket, --limit-share-file, --tenant-limits-file, --previous-config, --sandbox-floor, --config-sha256) are set by scalws-controller. An instance (--instance-id) with a sandbox floor of audit or on refuses a configuration that would start processes. You normally use only --config, --check and perhaps --worker-threads.

    Socket addresses and the instance id follow the value formats.

    Exit status

    StatusWhen
    0--check passed, or the server stopped normally.
    1Start-up failed (for example a port that cannot be bound).
    2The configuration cannot be loaded, the command-line options do not fit it (for example --reuseport with an HTTP/3 listener, or an invalid --instance-id), or --check failed.

    Signals

    On Unix:

    SignalEffect
    SIGHUPReloads the configuration file, like scalwsctl reload. A rejected reload is logged and the active configuration stays. Once a shutdown has begun, it is logged and ignored.
    SIGTERM, SIGINTKeeps serving for server.limits.shutdown_delay (a second signal ends the delay), drains connections for up to server.limits.shutdown_timeout, closes the remaining ones, and exits with 0. Both are read from the active configuration when the signal arrives. A signal received while the server starts takes effect once it has started.
    SIGUSR2Activation (with --wait-for-activation).

    On other platforms, Ctrl-C drains and exits, and reloading by signal is not available.

    scalwsd --config /etc/scalws/scalws.yaml --check
systemctl reload scalwsd       # sends SIGHUP

    Changes that a reload cannot apply, such as listener addresses, are refused with “requires a restart”; see Files and services.

    See also