Elgato_dark/bunkerweb
1
0
Fork 0
mirror of https://github.com/bunkerity/bunkerweb synced 2026-05-24 09:28:37 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update settings documentation

Browse source
This commit is contained in:
Théophile Diot 2025-01-13 12:17:53 +01:00
parent d61c10e8e0
commit 426f1a0349
No known key found for this signature in database
GPG key ID: FA995104A0BA376A
1 changed files with 62 additions and 50 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

112
docs/settings.md
View file

@ -19,8 +19,8 @@ STREAM support :warning:
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | --------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `IS_LOADING` | `no` | global | no | Internal use : set to yes when BW is loading. |
| `NGINX_PREFIX` | `/etc/nginx/` | global | no | Where nginx will search for configurations. |
| `HTTP_PORT` | `8080` | global | no | HTTP port number which bunkerweb binds to. |
| `HTTPS_PORT` | `8443` | global | no | HTTPS port number which bunkerweb binds to. |
| `HTTP_PORT` | `8080` | global | yes | HTTP port number which bunkerweb binds to. |
| `HTTPS_PORT` | `8443` | global | yes | HTTPS port number which bunkerweb binds to. |
| `MULTISITE` | `no` | global | no | Multi site activation. |
| `SERVER_NAME` | `www.example.com` | multisite | no | List of the virtual hosts served by bunkerweb. |
| `WORKER_PROCESSES` | `auto` | global | no | Number of worker processes. |
@ -45,9 +45,10 @@ STREAM support :warning:
| `KUBERNETES_MODE` | `no` | global | no | Enable Kubernetes integration. |
| `SERVER_TYPE` | `http` | multisite | no | Server type : http or stream. |
| `LISTEN_STREAM` | `yes` | multisite | no | Enable listening for non-ssl (passthrough). |
| `LISTEN_STREAM_PORT` | `1337` | multisite | no | Listening port for non-ssl (passthrough). |
| `LISTEN_STREAM_PORT_SSL` | `4242` | multisite | no | Listening port for ssl (passthrough). |
| `USE_UDP` | `no` | multisite | no | UDP listen instead of TCP (stream). |
| `LISTEN_STREAM_PORT` | `1337` | multisite | yes | Listening port for non-ssl (passthrough). |
| `LISTEN_STREAM_PORT_SSL` | `4242` | multisite | yes | Listening port for ssl (passthrough). |
| `USE_TCP` | `yes` | multisite | no | TCP listen (stream). |
| `USE_UDP` | `no` | multisite | no | UDP listen (stream). |
| `USE_IPV6` | `no` | global | no | Enable IPv6 connectivity. |
| `IS_DRAFT` | `no` | multisite | no | Internal use : set to yes when the service is in draft mode. |
| `TIMERS_LOG_LEVEL` | `debug` | global | no | Log level for timers. |
@ -86,8 +87,8 @@ Enforce login before accessing a resource or the whole site using HTTP basic aut
| --------------------- | ----------------- | --------- | -------- | ------------------------------------------------ |
| `USE_AUTH_BASIC` | `no` | multisite | no | Use HTTP basic auth |
| `AUTH_BASIC_LOCATION` | `sitewide` | multisite | no | URL of the protected resource or sitewide value. |
| `AUTH_BASIC_USER` | `changeme` | multisite | no | Username |
| `AUTH_BASIC_PASSWORD` | `changeme` | multisite | no | Password |
| `AUTH_BASIC_USER` | `changeme` | multisite | yes | Username |
| `AUTH_BASIC_PASSWORD` | `changeme` | multisite | yes | Password |
| `AUTH_BASIC_TEXT` | `Restricted area` | multisite | no | Text to display |
## Backup
@ -236,19 +237,20 @@ Deny access based on the country of the client IP.
| `BLACKLIST_COUNTRY` | | multisite | no | Deny access if the country of the client is in the list (ISO 3166-1 alpha-2 format separated with spaces). |
| `WHITELIST_COUNTRY` | | multisite | no | Deny access if the country of the client is not in the list (ISO 3166-1 alpha-2 format separated with spaces). |
## Custom HTTPS certificate
## Custom SSL certificate
STREAM support :white_check_mark:
Choose custom certificate for HTTPS.
Choose custom certificate for SSL.
| Setting | Default | Context | Multiple | Description |
| ---------------------- | ------- | --------- | -------- | -------------------------------------------------------------------------------- |
| `USE_CUSTOM_SSL` | `no` | multisite | no | Use custom HTTPS certificate. |
| `CUSTOM_SSL_CERT` | | multisite | no | Full path of the certificate or bundle file (must be readable by the scheduler). |
| `CUSTOM_SSL_KEY` | | multisite | no | Full path of the key file (must be readable by the scheduler). |
| `CUSTOM_SSL_CERT_DATA` | | multisite | no | Certificate data encoded in base64. |
| `CUSTOM_SSL_KEY_DATA` | | multisite | no | Key data encoded in base64. |
| Setting | Default | Context | Multiple | Description |
| -------------------------- | ------- | --------- | -------- | -------------------------------------------------------------------------------------- |
| `USE_CUSTOM_SSL` | `no` | multisite | no | Use custom SSL certificate. |
| `CUSTOM_SSL_CERT_PRIORITY` | `file` | multisite | no | Choose whether to prioritize the certificate from file path or from base64 data. (file | data) |
| `CUSTOM_SSL_CERT` | | multisite | no | Full path of the certificate or bundle file (must be readable by the scheduler). |
| `CUSTOM_SSL_KEY` | | multisite | no | Full path of the key file (must be readable by the scheduler). |
| `CUSTOM_SSL_CERT_DATA` | | multisite | no | Certificate data encoded in base64. |
| `CUSTOM_SSL_KEY_DATA` | | multisite | no | Key data encoded in base64. |
## DB
@ -337,22 +339,21 @@ STREAM support :x:
Manage HTTP headers sent to clients.
| Setting | Default | Context | Multiple | Description |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | -------- | ---------------------------------------------------------------------------------------------- |
| `CUSTOM_HEADER` | | multisite | yes | Custom header to add (HeaderName: HeaderValue). |
| `REMOVE_HEADERS` | `Server Expect-CT X-Powered-By X-AspNet-Version X-AspNetMvc-Version Public-Key-Pins` | multisite | no | Headers to remove (Header1 Header2 Header3 ...) |
| `KEEP_UPSTREAM_HEADERS` | `Content-Security-Policy Permissions-Policy X-Frame-Options` | multisite | no | Headers to keep from upstream (Header1 Header2 Header3 ... or * for all). |
| `STRICT_TRANSPORT_SECURITY` | `max-age=31536000; includeSubDomains; preload` | multisite | no | Value for the Strict-Transport-Security header. |
| `COOKIE_FLAGS` | `* HttpOnly SameSite=Lax` | multisite | yes | Cookie flags automatically added to all cookies (value accepted for nginx_cookie_flag_module). |
| `COOKIE_AUTO_SECURE_FLAG` | `yes` | multisite | no | Automatically add the Secure flag to all cookies. |
| `CONTENT_SECURITY_POLICY` | `object-src 'none'; form-action 'self'; frame-ancestors 'self';` | multisite | no | Value for the Content-Security-Policy header. |
| `CONTENT_SECURITY_POLICY_REPORT_ONLY` | `no` | multisite | no | Send reports for violations of the Content-Security-Policy header instead of blocking them. |
| `REFERRER_POLICY` | `strict-origin-when-cross-origin` | multisite | no | Value for the Referrer-Policy header. |
| `PERMISSIONS_POLICY` | `accelerometer=(), ambient-light-sensor=(), attribution-reporting=(), autoplay=(), battery=(), bluetooth=(), browsing-topics=(), camera=(), compute-pressure=(), display-capture=(), document-domain=(), encrypted-media=(), execution-while-not-rendered=(), execution-while-out-of-viewport=(), fullscreen=(), gamepad=(), geolocation=(), gyroscope=(), hid=(), identity-credentials-get=(), idle-detection=(), local-fonts=(), magnetometer=(), microphone=(), midi=(), otp-credentials=(), payment=(), picture-in-picture=(), publickey-credentials-create=(), publickey-credentials-get=(), screen-wake-lock=(), serial=(), speaker-selection=(), storage-access=(), usb=(), web-share=(), window-management=(), xr-spatial-tracking=(), interest-cohort=()` | multisite | no | Value for the Permissions-Policy header. |
| `X_FRAME_OPTIONS` | `SAMEORIGIN` | multisite | no | Value for the X-Frame-Options header. |
| `X_CONTENT_TYPE_OPTIONS` | `nosniff` | multisite | no | Value for the X-Content-Type-Options header. |
| `X_XSS_PROTECTION` | `1; mode=block` | multisite | no | Value for the X-XSS-Protection header. |
| `X_DNS_PREFETCH_CONTROL` | `off` | multisite | no | Value for the X-DNS-Prefetch-Control header. |
| Setting | Default | Context | Multiple | Description |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------- | ---------------------------------------------------------------------------------------------- |
| `CUSTOM_HEADER` | | multisite | yes | Custom header to add (HeaderName: HeaderValue). |
| `REMOVE_HEADERS` | `Server Expect-CT X-Powered-By X-AspNet-Version X-AspNetMvc-Version Public-Key-Pins` | multisite | no | Headers to remove (Header1 Header2 Header3 ...) |
| `KEEP_UPSTREAM_HEADERS` | `Content-Security-Policy Permissions-Policy X-Frame-Options` | multisite | no | Headers to keep from upstream (Header1 Header2 Header3 ... or * for all). |
| `STRICT_TRANSPORT_SECURITY` | `max-age=31536000; includeSubDomains; preload` | multisite | no | Value for the Strict-Transport-Security header. |
| `COOKIE_FLAGS` | `* HttpOnly SameSite=Lax` | multisite | yes | Cookie flags automatically added to all cookies (value accepted for nginx_cookie_flag_module). |
| `COOKIE_AUTO_SECURE_FLAG` | `yes` | multisite | no | Automatically add the Secure flag to all cookies. |
| `CONTENT_SECURITY_POLICY` | `object-src 'none'; form-action 'self'; frame-ancestors 'self';` | multisite | no | Value for the Content-Security-Policy header. |
| `CONTENT_SECURITY_POLICY_REPORT_ONLY` | `no` | multisite | no | Send reports for violations of the Content-Security-Policy header instead of blocking them. |
| `REFERRER_POLICY` | `strict-origin-when-cross-origin` | multisite | no | Value for the Referrer-Policy header. |
| `PERMISSIONS_POLICY` | `accelerometer=(), ambient-light-sensor=(), attribution-reporting=(), autoplay=(), battery=(), bluetooth=(), browsing-topics=(), camera=(), compute-pressure=(), display-capture=(), encrypted-media=(), execution-while-not-rendered=(), execution-while-out-of-viewport=(), fullscreen=(), gamepad=(), geolocation=(), gyroscope=(), hid=(), identity-credentials-get=(), idle-detection=(), local-fonts=(), magnetometer=(), microphone=(), midi=(), otp-credentials=(), payment=(), picture-in-picture=(), publickey-credentials-create=(), publickey-credentials-get=(), screen-wake-lock=(), serial=(), speaker-selection=(), storage-access=(), usb=(), web-share=(), window-management=(), xr-spatial-tracking=(), interest-cohort=()` | multisite | no | Value for the Permissions-Policy header. |
| `X_FRAME_OPTIONS` | `SAMEORIGIN` | multisite | no | Value for the X-Frame-Options header. |
| `X_CONTENT_TYPE_OPTIONS` | `nosniff` | multisite | no | Value for the X-Content-Type-Options header. |
| `X_DNS_PREFETCH_CONTROL` | `off` | multisite | no | Value for the X-DNS-Prefetch-Control header. |
## Let's Encrypt
@ -395,11 +396,12 @@ STREAM support :warning:
Metrics collection and retrieve.
| Setting | Default | Context | Multiple | Description |
| ------------------------------ | ------- | --------- | -------- | --------------------------------------------------------- |
| `USE_METRICS` | `yes` | multisite | no | Enable collection and retrieval of internal metrics. |
| `METRICS_MEMORY_SIZE` | `16m` | global | no | Size of the internal storage for metrics. |
| `METRICS_MAX_BLOCKED_REQUESTS` | `100` | global | no | Maximum number of blocked requests to store (per worker). |
| Setting | Default | Context | Multiple | Description |
| ------------------------------------ | -------- | --------- | -------- | --------------------------------------------------------- |
| `USE_METRICS` | `yes` | multisite | no | Enable collection and retrieval of internal metrics. |
| `METRICS_MEMORY_SIZE` | `16m` | global | no | Size of the internal storage for metrics. |
| `METRICS_MAX_BLOCKED_REQUESTS` | `1000` | global | no | Maximum number of blocked requests to store (per worker). |
| `METRICS_MAX_BLOCKED_REQUESTS_REDIS` | `100000` | global | no | Maximum number of blocked requests to store in Redis. |
## Migration <img src='../assets/img/pro-icon.svg' alt='crow pro icon' height='24px' width='24px' style='transform : translateY(3px);'> (PRO)
@ -418,13 +420,10 @@ Miscellaneous settings.
| ----------------------------------- | ----------------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `DISABLE_DEFAULT_SERVER` | `no` | global | no | Deny HTTP request if the request vhost is unknown. |
| `DISABLE_DEFAULT_SERVER_STRICT_SNI` | `no` | global | no | Close SSL/TLS connection if the SNI is unknown. |
| `REDIRECT_HTTP_TO_HTTPS` | `no` | multisite | no | Redirect all HTTP request to HTTPS. |
| `AUTO_REDIRECT_HTTP_TO_HTTPS` | `yes` | multisite | no | Try to detect if HTTPS is used and activate HTTP to HTTPS redirection if that's the case. |
| `ALLOWED_METHODS` | `GET | POST | HEAD` | multisite | no | Allowed HTTP and WebDAV methods, separated with pipes to be sent by clients. |
| `MAX_CLIENT_SIZE` | `10m` | multisite | no | Maximum body size (0 for infinite). |
| `SERVE_FILES` | `yes` | multisite | no | Serve files from the local folder. |
| `ROOT_FOLDER` | | multisite | no | Root folder containing files to serve (/var/www/html/{server_name} if unset). |
| `SSL_PROTOCOLS` | `TLSv1.2 TLSv1.3` | multisite | no | The supported version of TLS. We recommend the default value TLSv1.2 TLSv1.3 for compatibility reasons. |
| `HTTP2` | `yes` | multisite | no | Support HTTP2 protocol when HTTPS is enabled. |
| `HTTP3` | `yes` | multisite | no | Support HTTP3 protocol when HTTPS is enabled. |
| `HTTP3_ALT_SVC_PORT` | `443` | multisite | no | HTTP3 alternate service port. This value will be used as part of the Alt-Svc header. |
@ -444,16 +443,17 @@ STREAM support :x:
Management of the ModSecurity WAF.
| Setting | Default | Context | Multiple | Description |
| --------------------------------- | -------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `USE_MODSECURITY` | `yes` | multisite | no | Enable ModSecurity WAF. |
| `USE_MODSECURITY_CRS` | `yes` | multisite | no | Enable OWASP Core Rule Set. |
| `USE_MODSECURITY_CRS_PLUGINS` | `yes` | multisite | no | Enable OWASP Core Rule Set plugins. |
| `MODSECURITY_CRS_VERSION` | `4` | multisite | no | Version of the OWASP Core Rule Set to use with ModSecurity (3, 4 or nightly). |
| `MODSECURITY_CRS_PLUGIN_URLS` | | multisite | no | List of OWASP CRS plugins URLs (direct download to .zip or .tar file) to download and install (URLs are separated with space). (Not compatible with CRS version 3) |
| `MODSECURITY_SEC_AUDIT_ENGINE` | `RelevantOnly` | multisite | no | SecAuditEngine directive of ModSecurity. |
| `MODSECURITY_SEC_RULE_ENGINE` | `On` | multisite | no | SecRuleEngine directive of ModSecurity. |
| `MODSECURITY_SEC_AUDIT_LOG_PARTS` | `ABCFHZ` | multisite | no | SecAuditLogParts directive of ModSecurity. |
| Setting | Default | Context | Multiple | Description |
| ------------------------------------- | -------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `USE_MODSECURITY` | `yes` | multisite | no | Enable ModSecurity WAF. |
| `USE_MODSECURITY_CRS` | `yes` | multisite | no | Enable OWASP Core Rule Set. |
| `USE_MODSECURITY_CRS_PLUGINS` | `yes` | multisite | no | Enable OWASP Core Rule Set plugins. |
| `MODSECURITY_CRS_VERSION` | `4` | multisite | no | Version of the OWASP Core Rule Set to use with ModSecurity (3, 4 or nightly). |
| `MODSECURITY_CRS_PLUGIN_URLS` | | multisite | no | List of OWASP CRS plugins URLs (direct download to .zip or .tar file) to download and install (URLs are separated with space). (Not compatible with CRS version 3) |
| `MODSECURITY_SEC_AUDIT_ENGINE` | `RelevantOnly` | multisite | no | SecAuditEngine directive of ModSecurity. |
| `MODSECURITY_SEC_RULE_ENGINE` | `On` | multisite | no | SecRuleEngine directive of ModSecurity. |
| `MODSECURITY_SEC_AUDIT_LOG_PARTS` | `ABCFHZ` | multisite | no | SecAuditLogParts directive of ModSecurity. |
| `MODSECURITY_REQ_BODY_NO_FILES_LIMIT` | `131072` | multisite | no | SecRequestBodyNoFilesLimit directive of ModSecurity. |
## Monitoring <img src='../assets/img/pro-icon.svg' alt='crow pro icon' height='24px' width='24px' style='transform : translateY(3px);'> (PRO)
@ -631,6 +631,18 @@ Scan clients ports to detect proxies or servers.
| `REVERSE_SCAN_PORTS` | `22 80 443 3128 8000 8080` | multisite | no | List of port to scan when using reverse scan feature. |
| `REVERSE_SCAN_TIMEOUT` | `500` | multisite | no | Specify the maximum timeout (in ms) when scanning a port. |
## SSL
STREAM support :white_check_mark:
Handle SSL/TLS related settings.
| Setting | Default | Context | Multiple | Description |
| ----------------------------- | ----------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `REDIRECT_HTTP_TO_HTTPS` | `no` | multisite | no | Redirect all HTTP request to HTTPS. |
| `AUTO_REDIRECT_HTTP_TO_HTTPS` | `yes` | multisite | no | Try to detect if HTTPS is used and activate HTTP to HTTPS redirection if that's the case. |
| `SSL_PROTOCOLS` | `TLSv1.2 TLSv1.3` | multisite | no | The supported version of TLS. We recommend the default value TLSv1.2 TLSv1.3 for compatibility reasons. |
## Security.txt
STREAM support :white_check_mark: