Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions src/v2/building-from-source.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand Down
8 changes: 4 additions & 4 deletions src/v2/configuration/command-line-arguments.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ Options:
--directory-listing-download=<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 [<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 [<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 <BASIC_AUTH>
Expand All @@ -89,11 +89,11 @@ Options:
--log-remote-address [<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_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_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 <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 [<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 [<IGNORE_HIDDEN_FILES>]
Expand Down
2 changes: 1 addition & 1 deletion src/v2/configuration/config-file.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 4 additions & 4 deletions src/v2/configuration/environment-variables.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down
4 changes: 4 additions & 0 deletions src/v2/features/basic-authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.<br>
> 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
Expand Down
2 changes: 2 additions & 0 deletions src/v2/features/cache-control-headers.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 4 additions & 0 deletions src/v2/features/compression.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
2 changes: 2 additions & 0 deletions src/v2/features/directory-listing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
4 changes: 4 additions & 0 deletions src/v2/features/http-methods.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 4 additions & 0 deletions src/v2/features/http1.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 3 additions & 1 deletion src/v2/features/http2-tls.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions src/v2/features/ignore-files.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
17 changes: 9 additions & 8 deletions src/v2/features/logging.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:

Expand All @@ -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]
<...>
```

Expand Down
Loading