# Glossary URL: https://scalws.com/docs/reference/glossary/ Source: `docs/reference/glossary.md` in the ScalWS repository This page defines the terms the ScalWS documentation uses, in alphabetical order, with links to where each one is described in full. ## ACME The protocol by which a certificate authority such as Let's Encrypt issues certificates automatically. With [`server.acme`](https://scalws.com/docs/reference/server-acme/#server.acme.enabled) enabled, ScalWS orders and renews the certificates of applications that set [`acme: true`](https://scalws.com/docs/reference/applications/#tenants-.applications-.acme), or of site files with `tls: auto`. The account and certificates are kept in [`server.acme.state_dir`](https://scalws.com/docs/reference/server-acme/#server.acme.state_dir) (`/var/lib/scalws/acme` in the package); under scalws-controller all instances share it and one of them orders. `scalwsctl certs` shows their state. See [TLS](https://scalws.com/docs/guide/tls/) and [ADR-0018](https://scalws.com/docs/adr/0018-acme/). ## Application A site or service inside a [tenant](#tenant): its domains, an optional document root, a [runtime](#runtime) (or a [profile](#profile) that supplies one), and optional [routes](#route), cache and security settings. Every domain belongs to exactly one application. Applications are named `tenant/app` on the command line, for example `scalwsctl restart shop/web`. See [Applications](https://scalws.com/docs/guide/applications/) and the [applications reference](https://scalws.com/docs/reference/applications/). ## Control plane See [data plane and control plane](#data-plane-and-control-plane). ## Controller `scalws-controller`, the Adaptive Runtime controller. It runs several `scalwsd` [instances](#instance) on separate CPU slices that share the listening sockets, starts, activates, [drains](#drain) and restarts them, rolls them onto new [generations](#generation), and can add or remove instances by [PressureScore](#pressurescore). It never handles client traffic. Its own configuration is `controller.yaml`. See [scalws-controller](https://scalws.com/docs/reference/programs/scalws-controller/) and [Adaptive Runtime](https://scalws.com/docs/adaptive-runtime/). ## Data plane and control plane The data plane is what handles client traffic: `scalwsd` with its listeners, TLS, HTTP, cache, static files, proxy and FastCGI. The control plane is `scalws-controller`, which observes the instances, classifies bottlenecks, decides and manages the instances' lifecycle, but terminates no connections. ScalWS Console sits beside both as a management process; if it fails, client traffic is not affected. See [ADR-0033](https://scalws.com/docs/adr/0033-adaptive-runtime-control-and-data-plane/). ## Drain Ending work without cutting off clients: stop accepting new connections, ask keep-alive connections to close (`Connection: close`, HTTP/2 `GOAWAY`), and let requests in flight finish until a timeout, after which the remaining connections are closed. `scalwsd` drains on `SIGTERM` for up to [`server.limits.shutdown_timeout`](https://scalws.com/docs/reference/server-limits/#server.limits.shutdown_timeout). An instance leaving under the controller drains for up to [`instances.drain_timeout`](https://scalws.com/docs/reference/controller/#instances.drain_timeout) and is killed after a further [`instances.kill_grace`](https://scalws.com/docs/reference/controller/#instances.kill_grace). After a reload, managed runtime processes that the new configuration no longer uses are drained in the background. ## External endpoint An application server that ScalWS does not start but connects to: an existing PHP-FPM pool named by [`php.fastcgi`](https://scalws.com/docs/reference/runtime-php/#tenants-.applications-.runtime.php.fastcgi), or an HTTP server named by a `proxy` runtime's [`upstream`](https://scalws.com/docs/reference/runtime-proxy/#tenants-.applications-.runtime.proxy.upstream). You run and scale it yourself, for example with systemd. Under scalws-controller, applications must be reached as external endpoints (`php` with `fastcgi`, everything else through `proxy`). Compare [managed runtime](#managed-runtime). ## Generation A numbered, validated configuration. `scalwsd` numbers every configuration it activates (start, reload, rollback); `scalwsctl status` shows the active generation and `scalwsctl history` the ones the process keeps in memory. scalws-controller stores each generation on disk as `/generations//scalws.yaml`, never changed afterwards, with the site files expanded into it, so a generation keeps the sites it had even when site files change later. Its instances start against an explicit generation, and a reload creates a new one. See [ADR-0035](https://scalws.com/docs/adr/0035-instance-lifecycle-and-config-generations/). ## Instance One `scalwsd` process started by scalws-controller. Instances have stable ids (`web-0`, `web-1`, ...), their own CPU slice, runtime directory and admin socket (`/run/scalws/web-/admin.sock`), and their own metrics port (`127.0.0.1:9910 + n` by default). They go through the phases Starting, Warming, Ready, Active, Draining and Stopped, or Failed. Only Active instances receive connections. See [Adaptive Runtime](https://scalws.com/docs/adaptive-runtime/). ## Listener An address on which `scalwsd` accepts connections, set in [`server.listeners`](https://scalws.com/docs/reference/server-listeners/): a name, a socket address, and optionally TLS (with certificates or ACME), HTTP/3, the PROXY protocol and [strict SNI](#strict-sni). Changing a standalone server's listener addresses or turning TLS on or off needs a [restart](#reload-and-restart); scalws-controller binds new addresses during a reload. ## Managed runtime A runtime whose processes ScalWS starts and supervises itself, as children of `scalwsd` in the tenant's cgroup: `php` without `fastcgi` (a PHP-FPM pool), `node` and `python` without `upstream`, and `container`. `scalwsd.service` runs them; scalws-controller refuses them, because every instance would start its own copy of the application ([ADR-0036](https://scalws.com/docs/adr/0036-multi-instance-state/)). Compare [external endpoint](#external-endpoint). See [Applications](https://scalws.com/docs/guide/applications/). ## PressureScore A number from 0 to 1 that scalws-controller computes for each instance from its CPU use, event-loop lag, requests in flight and, when a target is set, p99 latency: `max(cpu_lag, inflight, latency)` with `cpu_lag = min(cpu, lag + 0.5)`, so high CPU alone is not pressure but high CPU with rising loop lag is. In autoscaling mode `web-tier`, the controller adds an instance when the web tier stays above [`autoscaling.scale_out_above`](https://scalws.com/docs/reference/controller/#autoscaling.scale_out_above) (0.75) and the bottleneck is the web tier itself, and removes one when it stays below [`autoscaling.scale_in_below`](https://scalws.com/docs/reference/controller/#autoscaling.scale_in_below) (0.30). See [ADR-0034](https://scalws.com/docs/adr/0034-pressure-score-and-bottleneck-classification/). ## Profile An application profile: built-in knowledge about a framework (wordpress, woocommerce, laravel, php, nextjs, node, django, flask, fastapi, python) with detection rules, a runtime template, a health check, and cache-bypass and security rules. `scalwsctl detect` proposes a profile for a directory, `scalwsctl profiles` lists them, and [`profile:`](https://scalws.com/docs/reference/applications/#tenants-.applications-.profile) in an application uses one. See [ADR-0011](https://scalws.com/docs/adr/0011-application-profiles/). ## Reload and restart A reload applies a changed configuration to running processes: it validates and prepares the new configuration (certificates, document roots, runtimes) and swaps it in at once; if anything fails, the active configuration keeps serving. Open connections are kept. On `scalwsd.service` a reload happens in the process (`scalwsctl reload`, `SIGHUP`); under scalws-controller it creates a new [generation](#generation) and replaces the instances one by one (`scalws-controller reload`). A restart stops and starts the process (`systemctl restart scalwsd`). Some changes need one on a standalone server, such as listener addresses, the metrics or admin endpoints and connection limits; a reload refuses them with "requires a restart". Restarting `scalws-controller` restarts only the controller: its instances keep serving and are adopted. `scalwsctl restart tenant/app` is different again: it replaces one application's processes without dropping requests. See [Files and services](https://scalws.com/docs/guide/files-and-services/#how-reload-works). ## Route A path prefix inside an [application](#application) with its own [runtime](#runtime), for example `/api` served by a proxy while the rest of the site is static. The longest matching prefix, compared by whole path segments, wins; requests that match no route use the application's runtime. See the [routes reference](https://scalws.com/docs/reference/routes/). ## Runtime How an application or route answers requests: `static` (files), `php` (FastCGI), `node`, `python`, `container`, `proxy` (an HTTP upstream), `redirect` or `respond` (a fixed response). A runtime is either a [managed runtime](#managed-runtime) or reaches an [external endpoint](#external-endpoint); `static`, `redirect` and `respond` are served by `scalwsd` itself. See [Applications](https://scalws.com/docs/guide/applications/). ## Site file A short YAML file that describes one site, usually `/etc/scalws/sites.d/.yaml`, read through the main configuration's [`include`](https://scalws.com/docs/reference/top-level/#include). It names the domain, aliases, `www` handling, document root, TLS mode and at most one runtime, and becomes a tenant with an application when the configuration is loaded. `scalwsctl site add|list|remove` and `scalwsctl migrate` manage them. See [Sites](https://scalws.com/docs/sites/) and the [site file reference](https://scalws.com/docs/reference/site-file/). ## SNI Server Name Indication: the host name a TLS client sends at the start of the handshake. ScalWS uses it to choose the certificate: an exact [`server_names`](https://scalws.com/docs/reference/server-listeners/#server.listeners-.tls.certificates-.server_names) match, then a one-label wildcard, then the listener's [`default`](https://scalws.com/docs/reference/server-listeners/#server.listeners-.tls.certificates-.default) certificate; otherwise the handshake fails. Which application answers is decided later by the request's `Host`, not by SNI. See [TLS](https://scalws.com/docs/guide/tls/). ## Strict SNI The listener option [`strict_sni`](https://scalws.com/docs/reference/server-listeners/#server.listeners-.strict_sni). With it, a request whose host differs from the SNI name of its TLS connection is answered with `421 Misdirected Request`, and the client opens a new connection for that host. Browsers may otherwise reuse one HTTP/2 connection for several names its certificate covers (connection coalescing); strict SNI keeps one tenant's connection from being used to reach another tenant's site. See [TLS](https://scalws.com/docs/guide/tls/#strict-sni). ## Tenant The unit of isolation and accounting: a named group of [applications](#application) that share resource limits. Its CPU, memory, I/O and process limits are enforced through cgroup v2 for its managed application processes, its request quotas in the server, and it can run as its own Unix user. `scalwsctl limit` and `scalwsctl high` work per tenant. See the [tenants reference](https://scalws.com/docs/reference/tenants/) and [ADR-0010](https://scalws.com/docs/adr/0010-cgroups-and-tenant-limits/).