From 3a9fe648bf07f28ddbd4bf7cb400145594e14f17 Mon Sep 17 00:00:00 2001 From: Jose Quintana Date: Mon, 16 Nov 2026 00:32:57 +0100 Subject: [PATCH] docs(v2): update docs for v2.44.1 to v2.44.3 changes --- src/v2/building-from-source.md | 4 ++-- src/v2/configuration/command-line-arguments.md | 8 ++++---- src/v2/configuration/config-file.md | 2 +- src/v2/configuration/environment-variables.md | 8 ++++---- src/v2/features/basic-authentication.md | 4 ++++ src/v2/features/cache-control-headers.md | 2 ++ src/v2/features/compression.md | 4 ++++ src/v2/features/directory-listing.md | 2 ++ src/v2/features/http-methods.md | 4 ++++ src/v2/features/http1.md | 4 ++++ src/v2/features/http2-tls.md | 4 +++- src/v2/features/ignore-files.md | 2 ++ src/v2/features/logging.md | 17 +++++++++-------- src/v2/features/metrics.md | 8 +++++--- src/v2/features/security-headers.md | 10 +++++++--- 15 files changed, 57 insertions(+), 26 deletions(-) diff --git a/src/v2/building-from-source.md b/src/v2/building-from-source.md index 36f90d5..3493435 100644 --- a/src/v2/building-from-source.md +++ b/src/v2/building-from-source.md @@ -33,8 +33,8 @@ However, you can disable just the ones you don't need from the lists below. | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Default** | | | `default` | Activates the default features by omission. | -| `all` | Activates all available features including the `experimental` feature. This is the default feature used when building SWS binaries. | -| `experimental` | Activates all SWS experimental features. Make sure to also provide the required `RUSTFLAGS` if the feature requires so. | +| `all` | Activates the default features and the Tokio runtime metrics, but not the `experimental` feature. This is the feature used when building SWS binaries. | +| `experimental` | Activates all SWS experimental features (in-memory file cache and Tokio runtime metrics), not included in SWS binaries. Provide the required `RUSTFLAGS` if needed. | | [**HTTP2/TLS**](./features/http2-tls.md) | | | `http2` | Activates the HTTP2 and TLS feature. Requires exactly one of `http2-ring` or `http2-fips` to select a TLS crypto provider. | | `http2-ring` | Activates the HTTP2/TLS feature with [`ring`](https://github.com/briansmith/ring) as the TLS crypto provider. Included by default. | diff --git a/src/v2/configuration/command-line-arguments.md b/src/v2/configuration/command-line-arguments.md index 953676e..3a570a1 100644 --- a/src/v2/configuration/command-line-arguments.md +++ b/src/v2/configuration/command-line-arguments.md @@ -77,7 +77,7 @@ Options: --directory-listing-download= Specify list of enabled format(s) for directory download. Format supported: `targz`. Default to empty list (disabled) [env: SERVER_DIRECTORY_LISTING_DOWNLOAD=] [possible values: targz] --security-headers [] - Enable security headers by default when HTTP/2 feature is activated. Headers included: "Strict-Transport-Security: max-age=63072000; includeSubDomains; preload" (2 years max-age), "X-Frame-Options: DENY" and "Content-Security-Policy: frame-ancestors 'self'" [env: SERVER_SECURITY_HEADERS=] [default: false] [possible values: true, false] + Enable security headers. Enabled by default when HTTP/2 (`--http2`) is activated. Headers included: "X-Frame-Options: DENY", "X-Content-Type-Options: nosniff" and "Content-Security-Policy: frame-ancestors 'self'". With `--http2` (TLS), also "Strict-Transport-Security: max-age=63072000; includeSubDomains; preload" (2 years max-age), which is never sent over plain HTTP. Behind a TLS-terminating proxy, add `Strict-Transport-Security` at the proxy or with an `[[advanced.headers]]` rule [env: SERVER_SECURITY_HEADERS=] [default: false] [possible values: true, false] -e, --cache-control-headers [] Enable cache control headers for incoming requests based on a set of file types. The file type list can be found on `src/control_headers.rs` file [env: SERVER_CACHE_CONTROL_HEADERS=] [default: true] [possible values: true, false] --basic-auth @@ -89,11 +89,11 @@ Options: --log-remote-address [] Log incoming requests information along with its remote address if available using the `info` log level [env: SERVER_LOG_REMOTE_ADDRESS=] [default: false] [possible values: true, false] --log-x-real-ip [] - Log the X-Real-IP header for remote IP information [env: SERVER_LOG_X_REAL_IP=] [default: false] [possible values: true, false] + Log the X-Real-IP header of requests from --trusted-proxies [env: SERVER_LOG_X_REAL_IP=] [default: false] [possible values: true, false] --log-forwarded-for [] - Log the X-Forwarded-For header for remote IP information [env: SERVER_LOG_FORWARDED_FOR=] [default: false] [possible values: true, false] + Log the first X-Forwarded-For address of requests from --trusted-proxies [env: SERVER_LOG_FORWARDED_FOR=] [default: false] [possible values: true, false] --trusted-proxies - List of IPs to use X-Forwarded-For from. The default is to trust all [env: SERVER_TRUSTED_PROXIES=] + List of proxy IPs to use the X-Real-IP and X-Forwarded-For headers from. The default trusts no one, so the headers are not logged unless set. IPv4 entries also match their IPv4-mapped IPv6 form (`::ffff:a.b.c.d`) [env: SERVER_TRUSTED_PROXIES=] --redirect-trailing-slash [] Check for a trailing slash in the requested directory URI and redirect permanently (308) to the same path with a trailing slash suffix if it is missing [env: SERVER_REDIRECT_TRAILING_SLASH=] [default: true] [possible values: true, false] --ignore-hidden-files [] diff --git a/src/v2/configuration/config-file.md b/src/v2/configuration/config-file.md index 9cad1eb..dd92323 100644 --- a/src/v2/configuration/config-file.md +++ b/src/v2/configuration/config-file.md @@ -86,7 +86,7 @@ log-remote-address = false #### Log real IP from X-Forwarded-For header if available log-forwarded-for = false -#### IPs to accept the X-Forwarded-For header from. Empty means all +#### Proxy IPs to use the X-Real-IP and X-Forwarded-For headers from. Empty means none trusted-proxies = [] #### Redirect to trailing slash in the requested directory uri diff --git a/src/v2/configuration/environment-variables.md b/src/v2/configuration/environment-variables.md index 04977ae..a972cd2 100644 --- a/src/v2/configuration/environment-variables.md +++ b/src/v2/configuration/environment-variables.md @@ -45,15 +45,15 @@ Log incoming request information along with its Remote Address (IP) if available ## SERVER_LOG_X_REAL_IP -Log the X-Real-IP header if available using the `info` log level. Default `false`. +Log the X-Real-IP header of requests from [trusted proxies](#server_trusted_proxies) using the `info` log level. Default `false`. ## SERVER_LOG_FORWARDED_FOR -Log the X-Forwarded-For header if available using the `info` log level. Default `false`. +Log the first X-Forwarded-For address of requests from [trusted proxies](#server_trusted_proxies) using the `info` log level. Default `false`. ## SERVER_TRUSTED_PROXIES -A comma separated list of IP addresses to accept the X-Forwarded-For header from. An empty string means trust all IPs. Default `""` +A comma separated list of proxy IP addresses to use the X-Real-IP and X-Forwarded-For headers from. An empty string trusts no one, so the headers are not logged. IPv4 entries also match their IPv4-mapped IPv6 form (`::ffff:a.b.c.d`). Default `""` ## SERVER_ERROR_PAGE_404 @@ -147,7 +147,7 @@ Specify list of enabled format(s) for directory download. Format supported: `tar ## SERVER_SECURITY_HEADERS -Enable security headers by default when the HTTP/2 feature is activated. Headers included: `Strict-Transport-Security: max-age=63072000; includeSubDomains; preload` (2 years max-age), `X-Frame-Options: DENY` and `Content-Security-Policy: frame-ancestors 'self'`. Default `false` (disabled). +Enable security headers. Enabled by default when HTTP/2 (`--http2`) is activated. Headers included: `X-Frame-Options: DENY`, `X-Content-Type-Options: nosniff` and `Content-Security-Policy: frame-ancestors 'self'`. With `--http2` (TLS), also `Strict-Transport-Security: max-age=63072000; includeSubDomains; preload` (2 years max-age), which is never sent over plain HTTP. Default `false` (disabled). ## SERVER_CACHE_CONTROL_HEADERS diff --git a/src/v2/features/basic-authentication.md b/src/v2/features/basic-authentication.md index 5d3cb95..96b27b2 100644 --- a/src/v2/features/basic-authentication.md +++ b/src/v2/features/basic-authentication.md @@ -44,6 +44,10 @@ htpasswd -nBC10 "username" > If you are using `SERVER_BASIC_AUTH` env via a `docker-compose.yml` file don't forget to replace the single `$` (dollar sign) with a `$$` (double-dollar sign) if you want those individual `$` dollar signs in your configuration to be treated by Docker as literals.
> More details in [the Docker Compose file: variable substitution](https://docs.docker.com/compose/compose-file/compose-file-v2/#variable-substitution) page. +> [!INFO] OPTIONS requests +> +> `OPTIONS` requests also require credentials, except CORS preflight requests (with `Origin` and `Access-Control-Request-Method` headers) when [CORS](./cors.md) is enabled. + Finally, assign the credentials and run the server. ```sh diff --git a/src/v2/features/cache-control-headers.md b/src/v2/features/cache-control-headers.md index f040d0d..de53a32 100644 --- a/src/v2/features/cache-control-headers.md +++ b/src/v2/features/cache-control-headers.md @@ -16,6 +16,8 @@ This feature is enabled by default and can be controlled by the boolean `-e, --c Control headers are applied only to the following file types with the corresponding `max-age` values. +They are only applied to `2xx` and `304` responses. Other responses (e.g. `404`) get `Cache-Control: no-cache`. + ### One day A `max-age` of _one day_ duration is used by default. diff --git a/src/v2/features/compression.md b/src/v2/features/compression.md index 2e8712b..00628bd 100644 --- a/src/v2/features/compression.md +++ b/src/v2/features/compression.md @@ -48,6 +48,10 @@ Compression is only applied to files with the MIME types listed below, indicatin - `image/x-icon` - `image/vnd.microsoft.icon` +## Responses not compressed + +Partial content (`206`) responses and responses without a body (`1xx`, `204`, `304`) are not compressed. + ## Compression level SWS allows selecting the compression level via `--compression-level` command line option or the equivalent [SERVER_COMPRESSION_LEVEL](../configuration/environment-variables.md#server_compression_level) env. The available values are `fastest`, `best` and `default`. `fastest` will result in the lowest CPU load but also the worst compression factor. `best` will attempt to compress the data as much as possible (not recommended with `Brotli` or `Zstandard` compression, will be very slow). `default` tries to strike a balance, choosing a compression level where compression factor is already fairly good but the CPU load is still low. diff --git a/src/v2/features/directory-listing.md b/src/v2/features/directory-listing.md index 3427803..33dcb5b 100644 --- a/src/v2/features/directory-listing.md +++ b/src/v2/features/directory-listing.md @@ -143,3 +143,5 @@ static-web-server \ ``` When **Directory Download** is enabled, append `?download` to a directory URL to download it. A link will also be added to the top part of **HTML** output format. + +Symlinks resolving outside the root directory are not included in the archive. diff --git a/src/v2/features/http-methods.md b/src/v2/features/http-methods.md index e87a1d7..4e9a942 100644 --- a/src/v2/features/http-methods.md +++ b/src/v2/features/http-methods.md @@ -8,6 +8,10 @@ outline: deep ## OPTIONS Method +> [!INFO] Basic Authentication +> +> When [Basic Authentication](./basic-authentication.md) is enabled, `OPTIONS` requests also require credentials, except [CORS preflight requests](#preflight-requests-in-cors) when [CORS](./cors.md) is enabled. + ### Identifying allowed request methods The HTTP [OPTIONS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/OPTIONS) method can be used to send a request to check for permitted communication options for either a given URL or server. diff --git a/src/v2/features/http1.md b/src/v2/features/http1.md index db12241..bd26cfa 100644 --- a/src/v2/features/http1.md +++ b/src/v2/features/http1.md @@ -7,6 +7,10 @@ The HTTP/1 is the protocol by default and can be used by specifying a host addre > - Either `--host`, `--port` and `--root` have defaults (optional values) so they can be specified or omitted as required. > - The server provides [Termination Signal](https://www.gnu.org/software/libc/manual/html_node/Termination-Signals.html) handling with [Graceful Shutdown](https://cloud.google.com/blog/products/containers-kubernetes/kubernetes-best-practices-terminating-with-grace) ability by default. +The plain HTTP listener only serves HTTP/1. HTTP/2 requires TLS, see [HTTP/2 and TLS](./http2-tls.md). + +HTTP/1 request headers are bounded by a 64 KiB read buffer. Larger requests get a `431 Request Header Fields Too Large` response. + Below is an example of how to run the server using HTTP/1. ```sh diff --git a/src/v2/features/http2-tls.md b/src/v2/features/http2-tls.md index 8a51ae5..6521604 100644 --- a/src/v2/features/http2-tls.md +++ b/src/v2/features/http2-tls.md @@ -4,6 +4,8 @@ This feature is disabled by default and can be activated via the boolean `-t, --http2` option as well as string arguments `--http2-tls-cert` (TLS certificate file path) and `--http2-tls-key` (private key file path). +HTTP/2 is only served over TLS. Its request header list is limited to 16 KiB. + ## Safe TLS defaults SWS comes with safe TLS defaults for underlying cryptography. @@ -84,7 +86,7 @@ Only the following private key file formats are supported: > > - Either `--host`, `--port` and `--root` have defaults (optional values) so they can be specified or omitted as required. > - Don't forget to adjust the proper `--port` value for the HTTP/2 & TLS feature. -> - When this feature is enabled (`--http2=true`) then the [security headers](./security-headers.md) are also enabled automatically. +> - When this feature is enabled (`--http2=true`) then the [security headers](./security-headers.md) are also enabled automatically, unless `--security-headers=false` is set via CLI or env. > - The server provides [Termination Signal](https://www.gnu.org/software/libc/manual/html_node/Termination-Signals.html) handling with [Graceful Shutdown](https://cloud.google.com/blog/products/containers-kubernetes/kubernetes-best-practices-terminating-with-grace) ability by default. ```sh diff --git a/src/v2/features/ignore-files.md b/src/v2/features/ignore-files.md index 677938e..684092f 100644 --- a/src/v2/features/ignore-files.md +++ b/src/v2/features/ignore-files.md @@ -8,6 +8,8 @@ SWS _does ignore_ dotfiles (hidden files) by default for security reasons. As a result, SWS will respond with a `404 Not Found` status as well as hidden files won't be shown in the directory listing if enabled. +On NTFS and FAT volumes, 8.3 short-name aliases of hidden files (e.g. `GIT~1` for `.git`) also get a `404 Not Found`. + This feature is enabled by default and can be controlled by the boolean `--ignore-hidden-files` option or the equivalent [SERVER_IGNORE_HIDDEN_FILES](./../configuration/environment-variables.md#server_ignore_hidden_files) env. Here is an example of how to disable hidden files ignoring if wanted: diff --git a/src/v2/features/logging.md b/src/v2/features/logging.md index 8aaa77a..1ae7f68 100644 --- a/src/v2/features/logging.md +++ b/src/v2/features/logging.md @@ -86,7 +86,7 @@ The relevant log output: ```log INFO static_web_server::logger: logging level: info <...> -INFO static_web_server::info: log requests with remote IP addresses: enabled=true +INFO static_web_server::log_addr: log requests with remote IP addresses: enabled=true <...> INFO static_web_server::handler: incoming request: method=GET uri=/ remote_addr=192.168.1.126:57625 INFO static_web_server::handler: incoming request: method=GET uri=/favicon.ico remote_addr=192.168.1.126:57625 @@ -106,20 +106,20 @@ INFO static_web_server::handler: incoming request: method=GET uri=/ x_real_ip=20 If the value of the `X-Real-IP` header does not parse as an IP address, no value will be logged. -To restrict the logging to only requests that originate from trusted proxy IPs, you can use the `--trusted-proxies` option, or the equivalent [SERVER_TRUSTED_PROXIES](../configuration/environment-variables.md#server_trusted_proxies) env. This should be a list of IPs, separated by commas. An empty list (the default) indicates that all IPs should be trusted. +The header is only logged for requests from trusted proxy IPs, set via the `--trusted-proxies` option or the equivalent [SERVER_TRUSTED_PROXIES](../configuration/environment-variables.md#server_trusted_proxies) env. This should be a list of IPs, separated by commas. An empty list (the default) trusts no one, so the header is not logged and a warning is printed at startup. ## Logging Client IP from X-Forwarded-For header -> Note: This header should only be trusted when you know your upstream is handling X-Forwarded-For securely and when using the `--trusted-proxies` option. +> Note: This header should only be trusted when you know your upstream is handling X-Forwarded-For securely. When used behind a reverse proxy the reported `remote_addr` indicates the proxies IP address and port, not the client's real IP. The Proxy server can be configured to provide the [X-Forwarded-For header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For), containing a comma-separated list of IP addresses, starting with the _real remote client IP_, and all following intermediate proxies (if any). -To enable logging of the real remote IP, enable the `--log-forwarded-for` option or the equivalent [SERVER_LOG_FORWARDED_FOR](../configuration/environment-variables.md#server_log_forwarded_for) env. By default this will log all requests which have a correctly formatted `X-Forwarded-For` header. +To enable logging of the real remote IP, enable the `--log-forwarded-for` option or the equivalent [SERVER_LOG_FORWARDED_FOR](../configuration/environment-variables.md#server_log_forwarded_for) env. The first address of a correctly formatted `X-Forwarded-For` header is logged. Since the content of the `X-Forwarded-For` header can be changed by all proxies in the chain, the remote IP address reported may not be trusted. -To restrict the logging to only requests that originate from trusted proxy IPs, you can use the `--trusted-proxies` option, or the equivalent [SERVER_TRUSTED_PROXIES](../configuration/environment-variables.md#server_trusted_proxies) env. This should be a list of IPs, separated by commas. An empty list (the default) indicates that all IPs should be trusted. +The header is only logged for requests from trusted proxy IPs, set via the `--trusted-proxies` option or the equivalent [SERVER_TRUSTED_PROXIES](../configuration/environment-variables.md#server_trusted_proxies) env. This should be a list of IPs, separated by commas. An empty list (the default) trusts no one, so the header is not logged and a warning is printed at startup. IPv4 entries also match their IPv4-mapped IPv6 form (`::ffff:a.b.c.d`). Command used for the following examples: @@ -132,9 +132,10 @@ Look for these lines in the log output: ```log <...> INFO static_web_server::info: log level: info -INFO static_web_server::info: log requests with remote IP addresses: enabled=false -INFO static_web_server::info: log X-Forwarded-For real remote IP addresses: enabled=true -INFO static_web_server::info: trusted IPs for X-Forwarded-For: [::1] +INFO static_web_server::log_addr: log requests with remote IP addresses: enabled=false +INFO static_web_server::log_addr: log X-Real-IP header: enabled=false +INFO static_web_server::log_addr: log X-Forwarded-For header: enabled=true +INFO static_web_server::log_addr: trusted IPs for X-Real-IP and X-Forwarded-For: [::1] <...> ``` diff --git a/src/v2/features/metrics.md b/src/v2/features/metrics.md index 7edc8bd..3db98b1 100644 --- a/src/v2/features/metrics.md +++ b/src/v2/features/metrics.md @@ -14,7 +14,9 @@ This feature is disabled by default and can be controlled by the boolean `--metr | `sws_http_requests_inflight` | Gauge | — | Requests currently being processed | | `sws_http_connections_active` | Gauge | — | Active HTTP connections | -When built with the `experimental` feature and `RUSTFLAGS="--cfg tokio_unstable"`, Tokio runtime metrics (worker threads, task scheduling, etc.) are also included in the output. +The `host` label is a name listed under [Virtual Hosting](./virtual-hosting.md), otherwise `other`. The `method` label is `GET`, `HEAD` or `OPTIONS`, otherwise `other`. + +When built with the `all` or `experimental` feature and `RUSTFLAGS="--cfg tokio_unstable"`, Tokio runtime metrics (worker threads, task scheduling, etc.) are also included in the output. ## Example @@ -29,10 +31,10 @@ curl http://localhost/metrics ```text # HELP sws_http_requests_total Total HTTP requests by method, status class, and host. # TYPE sws_http_requests_total counter -sws_http_requests_total{host="localhost",method="GET",status="2xx"} 42 +sws_http_requests_total{host="other",method="GET",status="2xx"} 42 # HELP sws_http_request_duration_seconds HTTP request duration in seconds by method, status class, and host. # TYPE sws_http_request_duration_seconds histogram -sws_http_request_duration_seconds_bucket{host="localhost",method="GET",status="2xx",le="0.001"} 38 +sws_http_request_duration_seconds_bucket{host="other",method="GET",status="2xx",le="0.001"} 38 ... # HELP sws_http_connections_active Number of currently active HTTP connections. # TYPE sws_http_connections_active gauge diff --git a/src/v2/features/security-headers.md b/src/v2/features/security-headers.md index c89d986..721af9b 100644 --- a/src/v2/features/security-headers.md +++ b/src/v2/features/security-headers.md @@ -2,7 +2,7 @@ **`SWS`** provides several [security headers](https://web.dev/security-headers/) support. -When the [HTTP/2](../features/http2-tls.md) feature is activated _security headers_ are enabled automatically. +When the [HTTP/2](../features/http2-tls.md) feature is activated _security headers_ are enabled automatically, unless `--security-headers=false` is set via CLI or env. This feature is disabled by default on HTTP/1 and can be controlled by the boolean `--security-headers` option or the equivalent [SERVER_SECURITY_HEADERS](./../configuration/environment-variables.md#server_security_headers) env. @@ -14,7 +14,11 @@ This feature is disabled by default on HTTP/1 and can be controlled by the boole The following headers are included by default. -- `Strict-Transport-Security: max-age=63072000; includeSubDomains; preload" (2 years max-age)` +- `Strict-Transport-Security: max-age=63072000; includeSubDomains; preload` (2 years max-age), only over TLS (`--http2`) - `X-Frame-Options: DENY` - `X-Content-Type-Options: nosniff` -- `Content-Security-Policy: frame-ancestors` +- `Content-Security-Policy: frame-ancestors 'self'` + +> [!INFO] HSTS over plain HTTP +> +> `Strict-Transport-Security` is never sent over plain HTTP. Behind a TLS-terminating proxy, add it at the proxy or via [Custom HTTP Headers](custom-http-headers.md).