static-web-server(1)

NAME
static-web-server - A cross-platform, high-performance and asynchronous web server for static files-serving.

SYNOPSIS
static-web-server [-a|--host] [-p|--port] [-f|--fd] [-n|--threads-multiplier] [-b|--max-blocking-threads] [-d|--root] [--page50x] [--page404] [--page-fallback] [-g|--log-level] [--log-with-ansi] [-c|--cors-allow-origins] [-j|--cors-allow-headers] [--cors-expose-headers] [-t|--http2] [--http2-tls-cert] [--http2-tls-key] [--https-redirect] [--https-redirect-host] [--https-redirect-from-port] [--https-redirect-from-hosts] [--index-files] [-x|--compression] [--compression-level] [--compression-static] [-z|--directory-listing] [--directory-listing-order] [--directory-listing-format] [--directory-listing-download] [--security-headers] [-e|--cache-control-headers] [--basic-auth] [-q|--grace-period] [-w|--config-file] [--log-remote-address] [--log-x-real-ip] [--log-forwarded-for] [--trusted-proxies] [--redirect-trailing-slash] [--ignore-hidden-files] [--disable-symlinks] [--accept-markdown] [--health] [--metrics] [--maintenance-mode] [--maintenance-mode-status] [--maintenance-mode-file] [-V|--version] [-h|--help] [subcommands]

DESCRIPTION
General server configuration available in CLI and config file options.

OPTIONS

-a, --host <HOST> [default: ::]
    Host address (E.g 127.0.0.1 or ::1)
    May also be specified with the SERVER_HOST environment variable.

-p, --port <PORT> [default: 80]
    Host port
    May also be specified with the SERVER_PORT environment variable.

-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
    May also be specified with the SERVER_LISTEN_FD environment variable.

-n, --threads-multiplier <THREADS_MULTIPLIER> [default: 1]
    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
    May also be specified with the SERVER_THREADS_MULTIPLIER environment variable.

-b, --max-blocking-threads <MAX_BLOCKING_THREADS> [default: 512]
    Maximum number of blocking threads
    May also be specified with the SERVER_MAX_BLOCKING_THREADS environment variable.

-d, --root <ROOT> [default: ./public]
    Root directory path of static files
    May also be specified with the SERVER_ROOT environment variable.

--page50x <PAGE50X> [default: ./50x.html]
    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
    May also be specified with the SERVER_ERROR_PAGE_50X environment variable.

--page404 <PAGE404> [default: ./404.html]
    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
    May also be specified with the SERVER_ERROR_PAGE_404 environment variable.

--page-fallback <PAGE_FALLBACK> [default: ]
    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
    May also be specified with the SERVER_FALLBACK_PAGE environment variable.

-g, --log-level <LOG_LEVEL> [default: error]
    Specify a logging level in lower case. Values: error, warn, info, debug or trace
    May also be specified with the SERVER_LOG_LEVEL environment variable.

--log-with-ansi [<LOG_WITH_ANSI>] [default: false]
    Enable or disable ANSI escape codes for colors and other text formatting of the log output
    Possible values:

    •   true

    •   false
    May also be specified with the SERVER_LOG_WITH_ANSI environment variable.

-c, --cors-allow-origins <CORS_ALLOW_ORIGINS> [default: ]
    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
    May also be specified with the SERVER_CORS_ALLOW_ORIGINS environment variable.

-j, --cors-allow-headers <CORS_ALLOW_HEADERS> [default: origin, content-type, authorization]
    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
    May also be specified with the SERVER_CORS_ALLOW_HEADERS environment variable.

--cors-expose-headers <CORS_EXPOSE_HEADERS> [default: origin, content-type]
    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
    May also be specified with the SERVER_CORS_EXPOSE_HEADERS environment variable.

-t, --http2 [<HTTP2>] [default: false]
    Enable HTTP/2 with TLS support
    Possible values:

    •   true

    •   false
    May also be specified with the SERVER_HTTP2_TLS environment variable.

--http2-tls-cert <HTTP2_TLS_CERT>
    Specify the file path to read the certificate
    May also be specified with the SERVER_HTTP2_TLS_CERT environment variable.

--http2-tls-key <HTTP2_TLS_KEY>
    Specify the file path to read the private key
    May also be specified with the SERVER_HTTP2_TLS_KEY environment variable.

--https-redirect [<HTTPS_REDIRECT>] [default: false]
    Redirect all requests with scheme "http" to "https" for the current server instance. It depends on "http2" to be enabled
    Possible values:

    •   true

    •   false
    May also be specified with the SERVER_HTTPS_REDIRECT environment variable.

--https-redirect-host <HTTPS_REDIRECT_HOST> [default: localhost]
    Canonical host name or IP of the HTTPS (HTTPS/2) server. It depends on "https_redirect" to be enabled
    May also be specified with the SERVER_HTTPS_REDIRECT_HOST environment variable.

--https-redirect-from-port <HTTPS_REDIRECT_FROM_PORT> [default: 80]
    HTTP host port where the redirect server will listen for requests to redirect them to HTTPS. It depends on "https_redirect" to be enabled
    May also be specified with the SERVER_HTTPS_REDIRECT_FROM_PORT environment variable.

--https-redirect-from-hosts <HTTPS_REDIRECT_FROM_HOSTS> [default: localhost]
    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
    May also be specified with the SERVER_HTTPS_REDIRECT_FROM_HOSTS environment variable.

--index-files <INDEX_FILES> [default: index.html]
    List of files that will be used as an index for requests ending with the slash character (‘/’). Files are checked in the specified order
    May also be specified with the SERVER_INDEX_FILES environment variable.

-x, --compression [<COMPRESSION>] [default: true]
    Gzip, Deflate, Brotli or Zstd compression on demand determined by the Accept-Encoding header and applied to text-based web file types only
    Possible values:

    •   true

    •   false
    May also be specified with the SERVER_COMPRESSION environment variable.

--compression-level <COMPRESSION_LEVEL> [default: default]
    Compression level to apply for Gzip, Deflate, Brotli or Zstd compression
    Possible values:

    •   fastest: Fastest execution at the expense of larger file sizes

    •   best: Smallest file size but potentially slow

    •   default: Algorithm-specific default compression level setting
    May also be specified with the SERVER_COMPRESSION_LEVEL environment variable.

--compression-static [<COMPRESSION_STATIC>] [default: false]
    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
    Possible values:

    •   true

    •   false
    May also be specified with the SERVER_COMPRESSION_STATIC environment variable.

-z, --directory-listing [<DIRECTORY_LISTING>] [default: false]
    Enable directory listing for all requests ending with the slash character (‘/’)
    Possible values:

    •   true

    •   false
    May also be specified with the SERVER_DIRECTORY_LISTING environment variable.

--directory-listing-order <DIRECTORY_LISTING_ORDER> [default: 6]
    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)
    May also be specified with the SERVER_DIRECTORY_LISTING_ORDER environment variable.

--directory-listing-format <DIRECTORY_LISTING_FORMAT> [default: html]
    Specify a content format for directory listing entries. Formats supported: "html" or "json". Default "html"
    Possible values:

    •   html: HTML format to display (default)

    •   json: JSON format to display
    May also be specified with the SERVER_DIRECTORY_LISTING_FORMAT environment variable.

--directory-listing-download=<DIRECTORY_LISTING_DOWNLOAD>
    Specify list of enabled format(s) for directory download. Format supported: `targz`. Default to empty list (disabled)
    Possible values:

    •   targz: Gunzip-compressed tarball (.tar.gz)
    May also be specified with the SERVER_DIRECTORY_LISTING_DOWNLOAD environment variable.

--security-headers [<SECURITY_HEADERS>] [default: false]
    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'"
    Possible values:

    •   true

    •   false
    May also be specified with the SERVER_SECURITY_HEADERS environment variable.

-e, --cache-control-headers [<CACHE_CONTROL_HEADERS>] [default: true]
    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
    Possible values:

    •   true

    •   false
    May also be specified with the SERVER_CACHE_CONTROL_HEADERS environment variable.

--basic-auth <BASIC_AUTH> [default: ]
    It provides The "Basic" HTTP Authentication scheme using credentials as "user-id:password" pairs. Password must be encoded using the "BCrypt" password-hashing function
    May also be specified with the SERVER_BASIC_AUTH environment variable.

-q, --grace-period <GRACE_PERIOD> [default: 0]
    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
    May also be specified with the SERVER_GRACE_PERIOD environment variable.

-w, --config-file <CONFIG_FILE> [default: ./sws.toml]
    Server TOML configuration file path
    May also be specified with the SERVER_CONFIG_FILE environment variable.

--log-remote-address [<LOG_REMOTE_ADDRESS>] [default: false]
    Log incoming requests information along with its remote address if available using the `info` log level
    Possible values:

    •   true

    •   false
    May also be specified with the SERVER_LOG_REMOTE_ADDRESS environment variable.

--log-x-real-ip [<LOG_X_REAL_IP>] [default: false]
    Log the X-Real-IP header for remote IP information
    Possible values:

    •   true

    •   false
    May also be specified with the SERVER_LOG_X_REAL_IP environment variable.

--log-forwarded-for [<LOG_FORWARDED_FOR>] [default: false]
    Log the X-Forwarded-For header for remote IP information
    Possible values:

    •   true

    •   false
    May also be specified with the SERVER_LOG_FORWARDED_FOR environment variable.

--trusted-proxies <TRUSTED_PROXIES>
    List of IPs to use X-Forwarded-For from. The default is to trust all
    May also be specified with the SERVER_TRUSTED_PROXIES environment variable.

--redirect-trailing-slash [<REDIRECT_TRAILING_SLASH>] [default: true]
    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
    Possible values:

    •   true

    •   false
    May also be specified with the SERVER_REDIRECT_TRAILING_SLASH environment variable.

--ignore-hidden-files [<IGNORE_HIDDEN_FILES>] [default: true]
    Ignore hidden files/directories (dotfiles), preventing them to be served and being included in auto HTML index pages (directory listing)
    Possible values:

    •   true

    •   false
    May also be specified with the SERVER_IGNORE_HIDDEN_FILES environment variable.

--disable-symlinks [<DISABLE_SYMLINKS>] [default: true]
    Prevent following files or directories if any path name component is a symbolic link
    Possible values:

    •   true

    •   false
    May also be specified with the SERVER_DISABLE_SYMLINKS environment variable.

--accept-markdown [<ACCEPT_MARKDOWN>] [default: false]
    Enable markdown content negotiation. When a client sends Accept: text/markdown, serve .md or .html.md files if available
    Possible values:

    •   true

    •   false
    May also be specified with the SERVER_ACCEPT_MARKDOWN environment variable.

--health [<HEALTH>] [default: false]
    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
    Possible values:

    •   true

    •   false
    May also be specified with the SERVER_HEALTH environment variable.

--metrics [<METRICS>] [default: false]
    Enable the /metrics endpoint that exposes Prometheus metrics for HTTP requests, connections, and latency
    Possible values:

    •   true

    •   false
    May also be specified with the SERVER_METRICS environment variable.

--maintenance-mode [<MAINTENANCE_MODE>] [default: false]
    Enable the server's maintenance mode functionality
    Possible values:

    •   true

    •   false
    May also be specified with the SERVER_MAINTENANCE_MODE environment variable.

--maintenance-mode-status <MAINTENANCE_MODE_STATUS> [default: 503]
    Provide a custom HTTP status code when entering into maintenance mode. Default 503
    May also be specified with the SERVER_MAINTENANCE_MODE_STATUS environment variable.

--maintenance-mode-file <MAINTENANCE_MODE_FILE> [default: ]
    Provide a custom maintenance mode HTML file. If not provided then a generic message will be displayed
    May also be specified with the SERVER_MAINTENANCE_MODE_FILE environment variable.

-V, --version
    Print version info and exit

-h, --help
    Print help (see a summary with '-h')

SUBCOMMANDS

static-web-server-generate(1)
    Generate man pages and shell completions

static-web-server-help(1)
    Print this message or the help of the given subcommand(s)

AUTHORS
Jose Quintana <https://joseluisq.net>