docs - add stream support info and plugin description to settings page

This commit is contained in:
florian 2023-04-27 20:27:07 +02:00
parent 289b58567b
commit ddd83a8089
No known key found for this signature in database
GPG Key ID: 3D80806F12602A7C
35 changed files with 185 additions and 12 deletions

View File

@ -22,6 +22,15 @@ def print_md_table(settings) -> MarkdownTableWriter:
)
return writer
def stream_support(support) -> str:
md = "STREAM support "
if support == "no":
md += ":x:"
elif support == "yes":
md += ":white_check_mark:"
else:
md += ":warning:"
return md
doc = StringIO()
@ -45,6 +54,7 @@ print(
# Print global settings
print("## Global settings\n", file=doc)
print(f"\n{stream_support('partial')}\n", file=doc)
with open("src/common/settings.json", "r") as f:
print(print_md_table(loads(f.read())), file=doc)
print(file=doc)
@ -56,11 +66,13 @@ for core in glob("src/common/core/*/plugin.json"):
with open(core, "r") as f:
core_plugin = loads(f.read())
if len(core_plugin["settings"]) > 0:
core_settings[core_plugin["name"]] = core_plugin["settings"]
core_settings[core_plugin["name"]] = core_plugin
for name, settings in dict(sorted(core_settings.items())).items():
print(f"### {name}\n", file=doc)
print(print_md_table(settings), file=doc)
for name, data in dict(sorted(core_settings.items())).items():
print(f"### {data['name']}\n", file=doc)
print(f"{stream_support(data['stream'])}\n", file=doc)
print(f"{data['description']}\n", file=doc)
print(print_md_table(data['settings']), file=doc)
doc.seek(0)
content = doc.read()

View File

@ -455,6 +455,7 @@ You can quickly protect sensitive resources like the admin area for example, by
| `AUTH_BASIC_TEXT` | `Restricted area` | Text to display in the auth prompt. |
### Auth request
You can deploy complex authentication (e.g. SSO), by using the auth request settings (see [here](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-subrequest-authentication/) for more information on the feature). Please note that you will find [Authelia](https://www.authelia.com/) and [Authentik](https://goauthentik.io/) examples in the [repository](https://github.com/bunkerity/bunkerweb/tree/master/examples).
**Auth request settings are related to reverse proxy rules.**

View File

@ -12,6 +12,9 @@ When settings are considered as "multiple", it means that you can have multiple
## Global settings
STREAM support :warning:
| Setting | Default | Context |Multiple| Description |
|------------------------------|------------------------------------------------------------------------------------------------------------------------|---------|--------|--------------------------------------------------|
|`IS_LOADING` |`no` |global |no |Internal use : set to yes when BW is loading. |
@ -50,6 +53,10 @@ When settings are considered as "multiple", it means that you can have multiple
### Antibot
STREAM support :x:
Bot detection by using a challenge.
| Setting | Default | Context |Multiple| Description |
|---------------------------|------------|---------|--------|---------------------------------------------------------------------|
|`USE_ANTIBOT` |`no` |multisite|no |Activate antibot feature. |
@ -62,6 +69,10 @@ When settings are considered as "multiple", it means that you can have multiple
### Auth basic
STREAM support :x:
Enforce login before accessing a resource or the whole site using HTTP basic auth method.
| Setting | Default | Context |Multiple| Description |
|---------------------|-----------------|---------|--------|------------------------------------------------|
|`USE_AUTH_BASIC` |`no` |multisite|no |Use HTTP basic auth |
@ -72,6 +83,10 @@ When settings are considered as "multiple", it means that you can have multiple
### Bad behavior
STREAM support :white_check_mark:
Ban IP generating too much 'bad' HTTP status code in a period of time.
| Setting | Default | Context |Multiple| Description |
|---------------------------|-----------------------------|---------|--------|--------------------------------------------------------------------------------------------|
|`USE_BAD_BEHAVIOR` |`yes` |multisite|no |Activate Bad behavior feature. |
@ -82,6 +97,10 @@ When settings are considered as "multiple", it means that you can have multiple
### Blacklist
STREAM support :warning:
Deny access based on internal and external IP/network/rDNS/ASN blacklists.
| Setting | Default | Context |Multiple| Description |
|----------------------------------|------------------------------------------------------------------------------------------------------------------------------|---------|--------|------------------------------------------------------------------------------------------------|
|`USE_BLACKLIST` |`yes` |multisite|no |Activate blacklist feature. |
@ -109,6 +128,10 @@ When settings are considered as "multiple", it means that you can have multiple
### Brotli
STREAM support :x:
Compress HTTP requests with the brotli algorithm.
| Setting | Default | Context |Multiple| Description |
|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|--------|-------------------------------------------------------|
|`USE_BROTLI` |`no` |multisite|no |Use brotli |
@ -118,6 +141,10 @@ When settings are considered as "multiple", it means that you can have multiple
### BunkerNet
STREAM support :white_check_mark:
Share threat data with other BunkerWeb instances via BunkerNet.
| Setting | Default | Context |Multiple| Description |
|------------------|--------------------------|---------|--------|-----------------------------|
|`USE_BUNKERNET` |`yes` |multisite|no |Activate BunkerNet feature. |
@ -125,6 +152,10 @@ When settings are considered as "multiple", it means that you can have multiple
### CORS
STREAM support :x:
Cross-Origin Resource Sharing.
| Setting | Default | Context |Multiple| Description |
|------------------------|------------------------------------------------------------------------------------|---------|--------|--------------------------------------------------|
|`USE_CORS` |`no` |multisite|no |Use CORS |
@ -137,6 +168,10 @@ When settings are considered as "multiple", it means that you can have multiple
### Client cache
STREAM support :x:
Manage caching for clients.
| Setting | Default | Context |Multiple| Description |
|-------------------------|------------------------------------------------------------|---------|--------|--------------------------------------------------------------------|
|`USE_CLIENT_CACHE` |`no` |multisite|no |Tell client to store locally static files. |
@ -146,6 +181,10 @@ When settings are considered as "multiple", it means that you can have multiple
### Country
STREAM support :white_check_mark:
Deny access based on the country of the client IP.
| Setting |Default| Context |Multiple| Description |
|-------------------|-------|---------|--------|-----------------------------------------------------------------------------|
|`BLACKLIST_COUNTRY`| |multisite|no |Deny access if the country of the client is in the list (2 letters code). |
@ -153,6 +192,10 @@ When settings are considered as "multiple", it means that you can have multiple
### Custom HTTPS certificate
STREAM support :white_check_mark:
Choose custom certificate for HTTPS.
| Setting |Default| Context |Multiple| Description |
|-----------------|-------|---------|--------|--------------------------------------------|
|`USE_CUSTOM_SSL` |`no` |multisite|no |Use custom HTTPS certificate. |
@ -161,12 +204,20 @@ When settings are considered as "multiple", it means that you can have multiple
### DB
STREAM support :white_check_mark:
Integrate easily the Database.
| Setting | Default |Context|Multiple| Description |
|--------------|-----------------------------------------|-------|--------|--------------------------------------------------|
|`DATABASE_URI`|`sqlite:////var/lib/bunkerweb/db.sqlite3`|global |no |The database URI, following the sqlalchemy format.|
### DNSBL
STREAM support :white_check_mark:
Deny access based on external DNSBL servers.
| Setting | Default | Context |Multiple| Description |
|------------|----------------------------------------------------------------------------|---------|--------|-----------------------|
|`USE_DNSBL` |`yes` |multisite|no |Activate DNSBL feature.|
@ -174,6 +225,10 @@ When settings are considered as "multiple", it means that you can have multiple
### Errors
STREAM support :x:
Manage default error pages
| Setting | Default | Context |Multiple| Description |
|-------------------------|-------------------------------------------------|---------|--------|------------------------------------------------------------------------------------------------------------------------|
|`ERRORS` | |multisite|no |List of HTTP error code and corresponding error pages, separated with spaces (404=/my404.html 403=/errors/403.html ...).|
@ -181,6 +236,10 @@ When settings are considered as "multiple", it means that you can have multiple
### Greylist
STREAM support :warning:
Allow access while keeping security features based on internal and external IP/network/rDNS/ASN greylists.
| Setting |Default| Context |Multiple| Description |
|--------------------------|-------|---------|--------|----------------------------------------------------------------------------------------------|
|`USE_GREYLIST` |`no` |multisite|no |Activate greylist feature. |
@ -198,6 +257,10 @@ When settings are considered as "multiple", it means that you can have multiple
### Gzip
STREAM support :x:
Compress HTTP requests with the gzip algorithm.
| Setting | Default | Context |Multiple| Description |
|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|--------|-----------------------------------------------------|
|`USE_GZIP` |`no` |multisite|no |Use gzip |
@ -207,12 +270,20 @@ When settings are considered as "multiple", it means that you can have multiple
### HTML injection
STREAM support :x:
Inject custom HTML code before the </body> tag.
| Setting |Default| Context |Multiple| Description |
|-------------|-------|---------|--------|------------------------|
|`INJECT_BODY`| |multisite|no |The HTML code to inject.|
### Headers
STREAM support :x:
Manage HTTP headers sent to clients.
| Setting | Default | Context |Multiple| Description |
|---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|--------|----------------------------------------------------------------------------------------------|
|`CUSTOM_HEADER` | |multisite|yes |Custom header to add (HeaderName: HeaderValue). |
@ -230,6 +301,10 @@ When settings are considered as "multiple", it means that you can have multiple
### Let's Encrypt
STREAM support :white_check_mark:
Automatic creation, renewal and configuration of Let's Encrypt certificates.
| Setting |Default| Context |Multiple| Description |
|--------------------------|-------|---------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|`AUTO_LETS_ENCRYPT` |`no` |multisite|no |Activate automatic Let's Encrypt mode. |
@ -238,17 +313,26 @@ When settings are considered as "multiple", it means that you can have multiple
### Limit
| Setting |Default| Context |Multiple| Description |
|----------------------|-------|---------|--------|--------------------------------------------------------------------------------|
|`USE_LIMIT_REQ` |`yes` |multisite|no |Activate limit requests feature. |
|`LIMIT_REQ_URL` |`/` |multisite|yes |URL where the limit request will be applied. |
|`LIMIT_REQ_RATE` |`2r/s` |multisite|yes |Rate to apply to the URL (s for second, m for minute, h for hour and d for day).|
|`USE_LIMIT_CONN` |`yes` |multisite|no |Activate limit connections feature. |
|`LIMIT_CONN_MAX_HTTP1`|`10` |multisite|no |Maximum number of connections per IP when using HTTP/1.X protocol. |
|`LIMIT_CONN_MAX_HTTP2`|`100` |multisite|no |Maximum number of streams per IP when using HTTP/2 protocol. |
STREAM support :warning:
Limit maximum number of requests and connections.
| Setting |Default| Context |Multiple| Description |
|-----------------------|-------|---------|--------|--------------------------------------------------------------------------------|
|`USE_LIMIT_REQ` |`yes` |multisite|no |Activate limit requests feature. |
|`LIMIT_REQ_URL` |`/` |multisite|yes |URL where the limit request will be applied. |
|`LIMIT_REQ_RATE` |`2r/s` |multisite|yes |Rate to apply to the URL (s for second, m for minute, h for hour and d for day).|
|`USE_LIMIT_CONN` |`yes` |multisite|no |Activate limit connections feature. |
|`LIMIT_CONN_MAX_HTTP1` |`10` |multisite|no |Maximum number of connections per IP when using HTTP/1.X protocol. |
|`LIMIT_CONN_MAX_HTTP2` |`100` |multisite|no |Maximum number of streams per IP when using HTTP/2 protocol. |
|`LIMIT_CONN_MAX_STREAM`|`10` |multisite|no |Maximum number of connections per IP when using stream. |
### Miscellaneous
STREAM support :warning:
Miscellaneous settings.
| Setting | Default | Context |Multiple| Description |
|-----------------------------|-----------------------|---------|--------|----------------------------------------------------------------------------------------------------------------------|
|`DISABLE_DEFAULT_SERVER` |`no` |global |no |Close connection if the request vhost is unknown. |
@ -271,6 +355,10 @@ When settings are considered as "multiple", it means that you can have multiple
### ModSecurity
STREAM support :x:
Management of the ModSecurity WAF.
| Setting | Default | Context |Multiple| Description |
|---------------------------------|--------------|---------|--------|------------------------------------------|
|`USE_MODSECURITY` |`yes` |multisite|no |Enable ModSecurity WAF. |
@ -281,6 +369,10 @@ When settings are considered as "multiple", it means that you can have multiple
### PHP
STREAM support :x:
Manage local or remote PHP-FPM.
| Setting |Default| Context |Multiple| Description |
|-----------------|-------|---------|--------|------------------------------------------------------------|
|`REMOTE_PHP` | |multisite|no |Hostname of the remote PHP-FPM instance. |
@ -290,6 +382,10 @@ When settings are considered as "multiple", it means that you can have multiple
### Real IP
STREAM support :warning:
Get real IP of clients when BunkerWeb is behind a reverse proxy / load balancer.
| Setting | Default | Context |Multiple| Description |
|--------------------|-----------------------------------------|---------|--------|--------------------------------------------------------------------------------------------------------|
|`USE_REAL_IP` |`no` |multisite|no |Retrieve the real IP of client. |
@ -301,6 +397,10 @@ When settings are considered as "multiple", it means that you can have multiple
### Redirect
STREAM support :x:
Manage HTTP redirects.
| Setting |Default| Context |Multiple| Description |
|-------------------------|-------|---------|--------|-------------------------------------------------|
|`REDIRECT_TO` | |multisite|no |Redirect a whole site to another one. |
@ -308,6 +408,10 @@ When settings are considered as "multiple", it means that you can have multiple
### Redis
STREAM support :white_check_mark:
Redis server configuration when using BunkerWeb in cluster mode.
| Setting |Default|Context|Multiple| Description |
|----------------------|-------|-------|--------|------------------------------------------------------------------|
|`USE_REDIS` |`no` |global |no |Activate Redis. |
@ -321,6 +425,10 @@ When settings are considered as "multiple", it means that you can have multiple
### Reverse proxy
STREAM support :warning:
Manage reverse proxy configurations.
| Setting | Default | Context |Multiple| Description |
|---------------------------------------|----------------------------------|---------|--------|-----------------------------------------------------------------------------------------------------------------------------|
|`USE_REVERSE_PROXY` |`no` |multisite|no |Activate reverse proxy mode. |
@ -351,6 +459,10 @@ When settings are considered as "multiple", it means that you can have multiple
### Reverse scan
STREAM support :white_check_mark:
Scan clients ports to detect proxies or servers.
| Setting | Default | Context |Multiple| Description |
|----------------------|--------------------------|---------|--------|------------------------------------------------------------------|
|`USE_REVERSE_SCAN` |`no` |multisite|no |Enable scanning of clients ports and deny access if one is opened.|
@ -359,6 +471,10 @@ When settings are considered as "multiple", it means that you can have multiple
### Self-signed certificate
STREAM support :white_check_mark:
Generate self-signed certificate.
| Setting | Default | Context |Multiple| Description |
|--------------------------|----------------------|---------|--------|-----------------------------------------|
|`GENERATE_SELF_SIGNED_SSL`|`no` |multisite|no |Generate and use self-signed certificate.|
@ -367,6 +483,10 @@ When settings are considered as "multiple", it means that you can have multiple
### Sessions
STREAM support :white_check_mark:
Management of session used by other plugins.
| Setting |Default |Context|Multiple| Description |
|---------------------------|--------|-------|--------|---------------------------------------------------------------------------------|
|`SESSIONS_SECRET` |`random`|global |no |Secret used to encrypt sessions variables for storing data related to challenges.|
@ -377,12 +497,20 @@ When settings are considered as "multiple", it means that you can have multiple
### UI
STREAM support :x:
Integrate easily the BunkerWeb UI.
|Setting |Default| Context |Multiple|Description|
|--------|-------|---------|--------|-----------|
|`USE_UI`|`no` |multisite|no |Use UI |
### Whitelist
STREAM support :warning:
Allow access based on internal and external IP/network/rDNS/ASN whitelists.
| Setting | Default | Context |Multiple| Description |
|---------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|--------|----------------------------------------------------------------------------------|
|`USE_WHITELIST` |`yes` |multisite|no |Activate whitelist feature. |

View File

@ -4,6 +4,7 @@
"name": "Antibot",
"description": "Bot detection by using a challenge.",
"version": "0.1",
"stream": "no",
"settings": {
"USE_ANTIBOT": {
"context": "multisite",

View File

@ -4,6 +4,7 @@
"name": "Auth basic",
"description": "Enforce login before accessing a resource or the whole site using HTTP basic auth method.",
"version": "0.1",
"stream": "no",
"settings": {
"USE_AUTH_BASIC": {
"context": "multisite",

View File

@ -4,6 +4,7 @@
"name": "Bad behavior",
"description": "Ban IP generating too much 'bad' HTTP status code in a period of time.",
"version": "0.1",
"stream": "yes",
"settings": {
"USE_BAD_BEHAVIOR": {
"context": "multisite",

View File

@ -4,6 +4,7 @@
"name": "Blacklist",
"description": "Deny access based on internal and external IP/network/rDNS/ASN blacklists.",
"version": "0.1",
"stream": "partial",
"settings": {
"USE_BLACKLIST": {
"context": "multisite",

View File

@ -4,6 +4,7 @@
"name": "Brotli",
"description": "Compress HTTP requests with the brotli algorithm.",
"version": "0.1",
"stream": "no",
"settings": {
"USE_BROTLI": {
"context": "multisite",

View File

@ -4,6 +4,7 @@
"name": "BunkerNet",
"description": "Share threat data with other BunkerWeb instances via BunkerNet.",
"version": "0.1",
"stream": "yes",
"settings": {
"USE_BUNKERNET": {
"context": "multisite",

View File

@ -4,6 +4,7 @@
"name": "Client cache",
"description": "Manage caching for clients.",
"version": "0.1",
"stream": "no",
"settings": {
"USE_CLIENT_CACHE": {
"context": "multisite",

View File

@ -4,6 +4,7 @@
"name": "CORS",
"description": "Cross-Origin Resource Sharing.",
"version": "0.1",
"stream": "no",
"settings": {
"USE_CORS": {
"context": "multisite",

View File

@ -4,6 +4,7 @@
"name": "Country",
"description": "Deny access based on the country of the client IP.",
"version": "0.1",
"stream": "yes",
"settings": {
"BLACKLIST_COUNTRY": {
"context": "multisite",

View File

@ -4,6 +4,7 @@
"name": "Custom HTTPS certificate",
"description": "Choose custom certificate for HTTPS.",
"version": "0.1",
"stream": "yes",
"settings": {
"USE_CUSTOM_SSL": {
"context": "multisite",

View File

@ -4,6 +4,7 @@
"name": "DB",
"description": "Integrate easily the Database.",
"version": "0.1",
"stream": "yes",
"settings": {
"DATABASE_URI": {
"context": "global",

View File

@ -4,6 +4,7 @@
"name": "DNSBL",
"description": "Deny access based on external DNSBL servers.",
"version": "0.1",
"stream": "yes",
"settings": {
"USE_DNSBL": {
"context": "multisite",

View File

@ -4,6 +4,7 @@
"name": "Errors",
"description": "Manage default error pages",
"version": "0.1",
"stream": "no",
"settings": {
"ERRORS": {
"context": "multisite",

View File

@ -4,6 +4,7 @@
"name": "Greylist",
"description": "Allow access while keeping security features based on internal and external IP/network/rDNS/ASN greylists.",
"version": "0.1",
"stream": "partial",
"settings": {
"USE_GREYLIST": {
"context": "multisite",

View File

@ -4,6 +4,7 @@
"name": "Gzip",
"description": "Compress HTTP requests with the gzip algorithm.",
"version": "0.1",
"stream": "no",
"settings": {
"USE_GZIP": {
"context": "multisite",

View File

@ -4,6 +4,7 @@
"name": "Headers",
"description": "Manage HTTP headers sent to clients.",
"version": "0.1",
"stream": "no",
"settings": {
"CUSTOM_HEADER": {
"context": "multisite",

View File

@ -4,6 +4,7 @@
"name": "HTML injection",
"description": "Inject custom HTML code before the </body> tag.",
"version": "0.1",
"stream": "no",
"settings": {
"INJECT_BODY": {
"context": "multisite",

View File

@ -4,6 +4,7 @@
"name": "Jobs",
"description": "Fake core plugin for internal jobs.",
"version": "0.1",
"stream": "yes",
"settings": {},
"jobs": [
{

View File

@ -4,6 +4,7 @@
"name": "Let's Encrypt",
"description": "Automatic creation, renewal and configuration of Let's Encrypt certificates.",
"version": "0.1",
"stream": "yes",
"settings": {
"AUTO_LETS_ENCRYPT": {
"context": "multisite",

View File

@ -4,6 +4,7 @@
"name": "Limit",
"description": "Limit maximum number of requests and connections.",
"version": "0.1",
"stream": "partial",
"settings": {
"USE_LIMIT_REQ": {
"context": "multisite",

View File

@ -4,6 +4,7 @@
"name": "Miscellaneous",
"description": "Miscellaneous settings.",
"version": "0.1",
"stream": "partial",
"settings": {
"DISABLE_DEFAULT_SERVER": {
"context": "global",

View File

@ -4,6 +4,7 @@
"name": "ModSecurity",
"description": "Management of the ModSecurity WAF.",
"version": "0.1",
"stream": "no",
"settings": {
"USE_MODSECURITY": {
"context": "multisite",

View File

@ -4,6 +4,7 @@
"name": "PHP",
"description": "Manage local or remote PHP-FPM.",
"version": "0.1",
"stream": "no",
"settings": {
"REMOTE_PHP": {
"context": "multisite",

View File

@ -4,6 +4,7 @@
"name": "Real IP",
"description": "Get real IP of clients when BunkerWeb is behind a reverse proxy / load balancer.",
"version": "0.1",
"stream": "partial",
"settings": {
"USE_REAL_IP": {
"context": "multisite",

View File

@ -4,6 +4,7 @@
"name": "Redirect",
"description": "Manage HTTP redirects.",
"version": "0.1",
"stream": "no",
"settings": {
"REDIRECT_TO": {
"context": "multisite",

View File

@ -4,6 +4,7 @@
"name": "Redis",
"description": "Redis server configuration when using BunkerWeb in cluster mode.",
"version": "0.1",
"stream": "yes",
"settings": {
"USE_REDIS": {
"context": "global",

View File

@ -4,6 +4,7 @@
"name": "Reverse proxy",
"description": "Manage reverse proxy configurations.",
"version": "0.1",
"stream": "partial",
"settings": {
"USE_REVERSE_PROXY": {
"context": "multisite",

View File

@ -4,6 +4,7 @@
"name": "Reverse scan",
"description": "Scan clients ports to detect proxies or servers.",
"version": "0.1",
"stream": "yes",
"settings": {
"USE_REVERSE_SCAN": {
"context": "multisite",

View File

@ -4,6 +4,7 @@
"name": "Self-signed certificate",
"description": "Generate self-signed certificate.",
"version": "0.1",
"stream": "yes",
"settings": {
"GENERATE_SELF_SIGNED_SSL": {
"context": "multisite",

View File

@ -4,6 +4,7 @@
"name": "Sessions",
"description": "Management of session used by other plugins.",
"version": "0.1",
"stream": "yes",
"settings": {
"SESSIONS_SECRET": {
"context": "global",

View File

@ -4,6 +4,7 @@
"name": "UI",
"description": "Integrate easily the BunkerWeb UI.",
"version": "0.1",
"stream": "no",
"settings": {
"USE_UI": {
"context": "multisite",

View File

@ -4,6 +4,7 @@
"name": "Whitelist",
"description": "Allow access based on internal and external IP/network/rDNS/ASN whitelists.",
"version": "0.1",
"stream": "partial",
"settings": {
"USE_WHITELIST": {
"context": "multisite",