Command-Line Arguments
The server can be configured via the following command-line arguments.
Remember
- Command-line arguments are equivalent to their environment variables.
- Command-line arguments take precedence over their equivalent environment variables.
$ static-web-server -h
A cross-platform, high-performance and asynchronous web server for static files-serving.
Usage: static-web-server [OPTIONS] [COMMAND]
Commands:
generate Generate man pages and shell completions
help Print this message or the help of the given subcommand(s)
Options:
-a, --host <HOST>
Host address (E.g 127.0.0.1 or ::1) [env: SERVER_HOST=] [default: ::]
-p, --port <PORT>
Host port [env: SERVER_PORT=] [default: 8787]
-f, --fd <FD>
Instead of binding to a TCP port, accept incoming connections to an already-bound TCP socket listener on the specified file descriptor number (usually zero). Requires that the parent process (e.g. inetd, launchd, or systemd) binds an address and port on behalf of static-web-server, before arranging for the resulting file descriptor to be inherited by static-web-server. Cannot be used in conjunction with the port and host arguments. The included systemd unit file utilises this feature to increase security by allowing the static-web-server to be sandboxed more completely [env: SERVER_LISTEN_FD=]
--unix-socket <UNIX_SOCKET>
Bind the server to a Unix Domain Socket (UDS) at the given filesystem path instead of a TCP host/port. Useful for reverse-proxy setups (e.g. nginx) on the same host where TCP/IP overhead is undesirable and filesystem-based access control is preferred. Cannot be combined with `--host`, `--port`, `--fd`, or TLS-related options. The socket file is removed on a graceful shutdown [env: SERVER_UNIX_SOCKET=]
--unix-socket-mode <UNIX_SOCKET_MODE>
Filesystem permission bits applied to the Unix socket file after binding, expressed in octal (e.g. `660`, `0660`, or `0o660`). When omitted the socket is created with the process umask. Only meaningful together with `--unix-socket` [env: SERVER_UNIX_SOCKET_MODE=]
--unix-socket-force [<UNIX_SOCKET_FORCE>]
When `true`, remove an existing socket file at `--unix-socket` before binding. This is useful when the server was previously killed abruptly and left a stale socket behind. Defaults to `false` to avoid clobbering an unrelated file [env: SERVER_UNIX_SOCKET_FORCE=] [default: false] [possible values: true, false]
-n, --threads-multiplier <THREADS_MULTIPLIER>
Number of worker threads multiplier that'll be multiplied by the number of system CPUs using the formula: `worker threads = number of CPUs * n` where `n` is the value that changes here. When multiplier value is 0 or 1 then one thread per core is used. Number of worker threads result should be a number between 1 and 32,768 though it is advised to keep this value on the smaller side [env: SERVER_THREADS_MULTIPLIER=] [default: 1]
-b, --max-blocking-threads <MAX_BLOCKING_THREADS>
Maximum number of blocking threads [env: SERVER_MAX_BLOCKING_THREADS=] [default: 512]
-d, --root <ROOT>
Root directory path of static files [env: SERVER_ROOT=] [default: ./public]
--page50x <PAGE50X>
HTML file path for 50x errors. If the path is not specified or simply doesn't exist then the server will use a generic HTML error message. If a relative path is used then it will be resolved under the root directory [env: SERVER_ERROR_PAGE_50X=] [default: ./50x.html]
--page404 <PAGE404>
HTML file path for 404 errors. If the path is not specified or simply doesn't exist then the server will use a generic HTML error message. If a relative path is used then it will be resolved under the root directory [env: SERVER_ERROR_PAGE_404=] [default: ./404.html]
--page-fallback <PAGE_FALLBACK>
A HTML file path (not relative to the root) used for GET requests when the requested path doesn't exist. The fallback page is served with a 200 status code, useful when using client routers. If the path doesn't exist then the feature is not activated [env: SERVER_FALLBACK_PAGE=] [default: ""]
-g, --log-level <LOG_LEVEL>
Specify a logging level in lower case. Values: error, warn, info, debug or trace [env: SERVER_LOG_LEVEL=] [default: error]
--log-format <LOG_FORMAT>
Specify the logging output format. Values: json (structured single-line JSON for production) or pretty (human-readable text for development) [env: SERVER_LOG_FORMAT=] [default: json] [possible values: json, pretty]
--log-with-ansi [<LOG_WITH_ANSI>]
Enable or disable ANSI escape codes for colors and other text formatting of the log output. Only effective when `--log-format pretty` is used [env: SERVER_LOG_WITH_ANSI=] [default: false] [possible values: true, false]
--log-file <LOG_FILE>
Optional filesystem path to stream log records to in addition to stderr. When set, logs are written asynchronously through a background worker thread (non-blocking I/O), so the request path is never delayed by disk writes. Missing parent directories are created on startup. ANSI escape codes are always disabled for file output regardless of `--log-with-ansi`. The file uses the format selected by `--log-format` (JSON by default). The file is opened in append mode and is not rotated by SWS, use an external tool (e.g. `logrotate`) for rotation [env: SERVER_LOG_FILE=]
-c, --cors-allow-origins <CORS_ALLOW_ORIGINS>
Specify an optional CORS list of allowed origin hosts separated by commas. Host ports or protocols aren't being checked. Use an asterisk (*) to allow any host [env: SERVER_CORS_ALLOW_ORIGINS=] [default: ""]
-j, --cors-allow-headers <CORS_ALLOW_HEADERS>
Specify an optional CORS list of allowed headers separated by commas. Default "origin, content-type". It requires `--cors-allow-origins` to be used along with [env: SERVER_CORS_ALLOW_HEADERS=] [default: "origin, content-type, authorization"]
--cors-expose-headers <CORS_EXPOSE_HEADERS>
Specify an optional CORS list of exposed headers separated by commas. Default "origin, content-type". It requires `--cors-expose-origins` to be used along with [env: SERVER_CORS_EXPOSE_HEADERS=] [default: "origin, content-type"]
-t, --tls [<TLS>]
Enable TLS/HTTPS support. Requires --tls-cert and --tls-key [env: SERVER_TLS=] [default: false] [possible values: true, false]
--tls-cert <TLS_CERT>
Specify the file path to the TLS certificate [env: SERVER_TLS_CERT=]
--tls-key <TLS_KEY>
Specify the file path to the TLS private key [env: SERVER_TLS_KEY=]
--http2 [<HTTP2>]
Enable HTTP/2 protocol support. Requires TLS to be enabled (--tls) [env: SERVER_HTTP2=] [default: false] [possible values: true, false]
--https-redirect [<HTTPS_REDIRECT>]
Redirect all requests with scheme "http" to "https" for the current server instance. Requires TLS to be enabled (--tls) [env: SERVER_HTTPS_REDIRECT=] [default: false] [possible values: true, false]
--https-redirect-host <HTTPS_REDIRECT_HOST>
Canonical host name or IP of the HTTPS server. It depends on "https_redirect" to be enabled [env: SERVER_HTTPS_REDIRECT_HOST=] [default: localhost]
--https-redirect-from-port <HTTPS_REDIRECT_FROM_PORT>
HTTP host port where the redirect server will listen for requests to redirect them to HTTPS. It depends on "https_redirect" to be enabled [env: SERVER_HTTPS_REDIRECT_FROM_PORT=] [default: 80]
--https-redirect-from-hosts <HTTPS_REDIRECT_FROM_HOSTS>
List of host names or IPs allowed to redirect from. HTTP requests must contain the HTTP 'Host' header and match against this list. It depends on "https_redirect" to be enabled [env: SERVER_HTTPS_REDIRECT_FROM_HOSTS=] [default: localhost]
--index-files <INDEX_FILES>
List of files that will be used as an index for requests ending with the slash character (‘/’). Files are checked in the specified order [env: SERVER_INDEX_FILES=] [default: index.html]
-x, --compression [<COMPRESSION>]
Gzip, Deflate, Brotli or Zstd compression on demand determined by the Accept-Encoding header and applied to text-based web file types only [env: SERVER_COMPRESSION=] [default: true] [possible values: true, false]
--compression-level <COMPRESSION_LEVEL>
Compression level to apply for Gzip, Deflate, Brotli or Zstd compression [env: SERVER_COMPRESSION_LEVEL=] [default: default] [possible values: fastest, best, default]
--compression-static [<COMPRESSION_STATIC>]
Look up the pre-compressed file variant (`.gz`, `.br` or `.zst`) on disk of a requested file and serves it directly if available. The compression type is determined by the `Accept-Encoding` header [env: SERVER_COMPRESSION_STATIC=] [default: true] [possible values: true, false]
-z, --directory-listing [<DIRECTORY_LISTING>]
Enable directory listing for all requests ending with the slash character (‘/’) [env: SERVER_DIRECTORY_LISTING=] [default: false] [possible values: true, false]
--directory-listing-order <DIRECTORY_LISTING_ORDER>
Specify a default code number to order directory listing entries per `Name`, `Last modified` or `Size` attributes (columns). Code numbers supported: 0 (Name asc), 1 (Name desc), 2 (Last modified asc), 3 (Last modified desc), 4 (Size asc), 5 (Size desc). Default 6 (unordered) [env: SERVER_DIRECTORY_LISTING_ORDER=] [default: 6]
--directory-listing-format <DIRECTORY_LISTING_FORMAT>
Specify a content format for directory listing entries. Formats supported: "html" or "json". Default "html" [env: SERVER_DIRECTORY_LISTING_FORMAT=] [default: html] [possible values: html, json]
--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 TLS 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: true] [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]
--etag [<ETAG>]
Enable weak `ETag` headers (`W/"<mtime>-<size>"`) and full conditional request handling (`If-None-Match`, `If-Match`, `If-Range`). Composes with `--cache-control-headers`; emits validators on every static-file response so clients can revalidate hot HTML even when long `max-age` is configured elsewhere [env: SERVER_ETAG=] [default: true] [possible values: true, false]
--basic-auth <BASIC_AUTH>
It provides The "Basic" HTTP Authentication scheme using credentials as "user-id:password" pairs. Password must be encoded using the "BCrypt" password-hashing function [env: SERVER_BASIC_AUTH=] [default: ""]
-q, --grace-period <GRACE_PERIOD>
Defines a grace period in seconds after a `SIGTERM` signal is caught which will delay the server before to shut it down gracefully. The maximum value is 255 seconds [env: SERVER_GRACE_PERIOD=] [default: 0]
-w, --config-file <CONFIG_FILE>
Server TOML configuration file path [env: SERVER_CONFIG_FILE=] [default: ./sws.toml]
--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-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]
--trusted-proxies <TRUSTED_PROXIES>
List of IPs to use X-Forwarded-For from. The default is to trust all [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]
--include-hidden [<INCLUDE_HIDDEN>]
Include hidden files/directories (dotfiles), allowing them to be served and listed in auto HTML index pages (directory listing). Disabled by default; hidden files return `404 Not Found` [env: SERVER_INCLUDE_HIDDEN=] [default: false] [possible values: true, false]
--follow-symlinks [<FOLLOW_SYMLINKS>]
Follow symbolic links when serving files or directories. Disabled by default; requests whose path contains any symlink component return `403 Forbidden` [env: SERVER_FOLLOW_SYMLINKS=] [default: false] [possible values: true, false]
--use-relative-root [<USE_RELATIVE_ROOT>]
Resolve the web root directory at request time rather than at startup, allowing symlinked root directories to be swapped at runtime [env: SERVER_USE_RELATIVE_ROOT=] [default: false] [possible values: true, false]
--accept-markdown [<ACCEPT_MARKDOWN>]
Enable markdown content negotiation. When a client sends Accept: text/markdown, serve .md or .html.md files if available [env: SERVER_ACCEPT_MARKDOWN=] [default: false] [possible values: true, false]
--text-charset [<TEXT_CHARSET>]
Set a default `charset=utf-8` parameter on limited set of `text` responses that don't already have one [env: SERVER_TEXT_CHARSET=] [default: true] [possible values: true, false]
--health [<HEALTH>]
Add a /health endpoint that doesn't generate any log entry and returns a 200 status code. This is especially useful with Kubernetes liveness and readiness probes [env: SERVER_HEALTH=] [default: false] [possible values: true, false]
--metrics [<METRICS>]
Enable the /metrics endpoint that exposes Prometheus metrics for HTTP requests, connections, and latency [env: SERVER_METRICS=] [default: false] [possible values: true, false]
--maintenance-mode [<MAINTENANCE_MODE>]
Enable the server's maintenance mode functionality [env: SERVER_MAINTENANCE_MODE=] [default: false] [possible values: true, false]
--maintenance-mode-status <MAINTENANCE_MODE_STATUS>
Provide a custom HTTP status code when entering into maintenance mode. Default 503 [env: SERVER_MAINTENANCE_MODE_STATUS=] [default: 503]
--maintenance-mode-file <MAINTENANCE_MODE_FILE>
Provide a custom maintenance mode HTML file. If not provided then a generic message will be displayed [env: SERVER_MAINTENANCE_MODE_FILE=] [default: ""]
-V, --version
Print version info and exit
-h, --help
Print help (see more with '--help')Windows
The following options and commands are Windows platform-specific.
-s, --windows-service <windows-service>
Run the web server as a Windows Service [env: SERVER_WINDOWS_SERVICE=] [default: false]
SUBCOMMANDS:
help Prints this message or the help of the given subcommand(s)
install Install a Windows Service for the web server
uninstall Uninstall the current Windows Service