Settings
Settings generator tool
To help you tune BunkerWeb, we have made an easy-to-use settings generator tool available at config.bunkerweb.io.
This section contains the full list of settings supported by BunkerWeb. If you are not yet familiar with BunkerWeb, you should first read the concepts section of the documentation. Please follow the instructions for your own integration on how to apply the settings.
As a general rule when multisite mode is enabled, if you want to apply settings with multisite context to a specific server, you will need to add the primary (first) server name as a prefix like www.example.com_USE_ANTIBOT=captcha
or myapp.example.com_USE_GZIP=yes
for example.
When settings are considered as "multiple", it means that you can have multiple groups of settings for the same feature by adding numbers as suffix like REVERSE_PROXY_URL_1=/subdir
, REVERSE_PROXY_HOST_1=http://myhost1
, REVERSE_PROXY_URL_2=/anotherdir
, REVERSE_PROXY_HOST_2=http://myhost2
, ... for example.
Global settings
STREAM support
Setting | Default | Context | Multiple | Description |
---|---|---|---|---|
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. |
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. |
WORKER_RLIMIT_NOFILE |
2048 |
global | no | Maximum number of open files for worker processes. |
WORKER_CONNECTIONS |
1024 |
global | no | Maximum number of connections per worker. |
LOG_FORMAT |
$host $remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" |
global | no | The format to use for access logs. |
LOG_LEVEL |
notice |
global | no | The level to use for error logs. |
DNS_RESOLVERS |
127.0.0.11 |
global | no | DNS addresses of resolvers to use. |
WORKERLOCK_MEMORY_SIZE |
48k |
global | no | Size of lua_shared_dict for initialization workers |
DATASTORE_MEMORY_SIZE |
64m |
global | no | Size of the internal datastore. |
CACHESTORE_MEMORY_SIZE |
64m |
global | no | Size of the internal cachestore. |
CACHESTORE_IPC_MEMORY_SIZE |
16m |
global | no | Size of the internal cachestore (ipc). |
CACHESTORE_MISS_MEMORY_SIZE |
16m |
global | no | Size of the internal cachestore (miss). |
CACHESTORE_LOCKS_MEMORY_SIZE |
16m |
global | no | Size of the internal cachestore (locks). |
USE_API |
yes |
global | no | Activate the API to control BunkerWeb. |
API_HTTP_PORT |
5000 |
global | no | Listen port number for the API. |
API_LISTEN_IP |
0.0.0.0 |
global | no | Listen IP address for the API. |
API_SERVER_NAME |
bwapi |
global | no | Server name (virtual host) for the API. |
API_WHITELIST_IP |
127.0.0.0/8 |
global | no | List of IP/network allowed to contact the API. |
AUTOCONF_MODE |
no |
global | no | Enable Autoconf Docker integration. |
SWARM_MODE |
no |
global | no | Enable Docker Swarm integration. |
KUBERNETES_MODE |
no |
global | no | Enable Kubernetes integration. |
|API_TIMEOUT
|10
|global |no |Manually set the timeout for BunkerWeb API requests. | |
|API_READ_TIMEOUT
|30
|global |no |Manually set the read timeout for BunkerWeb API requests. |
|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). |
|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. |
|OVERRIDE_INSTANCES
| |global |no |List of BunkerWeb instances separated with spaces (format : fqdn-or-ip:5000 fqdn-or-ip:5000)|
|DISABLE_CONFIGURATION_TESTING
|no
|global |no |Disable sanity checks for all other environment variables. |
Antibot
STREAM support
Bot detection by using a challenge.
Setting | Default | Context | Multiple | Description |
---|---|---|---|---|
USE_ANTIBOT |
no |
multisite | no | Activate antibot feature. |
ANTIBOT_URI |
/challenge |
multisite | no | Unused URI that clients will be redirected to to solve the challenge. |
ANTIBOT_TIME_RESOLVE |
60 |
multisite | no | Maximum time (in seconds) clients have to resolve the challenge. Once this time has passed, a new challenge will be generated. |
ANTIBOT_TIME_VALID |
86400 |
multisite | no | Maximum validity time of solved challenges. Once this time has passed, clients will need to resolve a new one. |
ANTIBOT_RECAPTCHA_SCORE |
0.7 |
multisite | no | Minimum score required for reCAPTCHA challenge (Only compatible with reCAPTCHA v3). |
ANTIBOT_RECAPTCHA_SITEKEY |
multisite | no | Sitekey for reCAPTCHA challenge. | |
ANTIBOT_RECAPTCHA_SECRET |
multisite | no | Secret for reCAPTCHA challenge. | |
ANTIBOT_HCAPTCHA_SITEKEY |
multisite | no | Sitekey for hCaptcha challenge. | |
ANTIBOT_HCAPTCHA_SECRET |
multisite | no | Secret for hCaptcha challenge. | |
ANTIBOT_TURNSTILE_SITEKEY |
multisite | no | Sitekey for Turnstile challenge. | |
ANTIBOT_TURNSTILE_SECRET |
multisite | no | Secret for Turnstile challenge. |
Auth basic
STREAM support
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 |
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_TEXT |
Restricted area |
multisite | no | Text to display |
Backup
STREAM support
Backup your data to a custom location. Ensure the safety and availability of your important files by creating regular backups.
Setting | Default | Context | Multiple | Description |
---|---|---|---|---|
USE_BACKUP |
yes |
global | no | Enable or disable the backup feature |
BACKUP_SCHEDULE |
daily |
global | no | The frequency of the backup (daily, weekly or monthly) |
BACKUP_ROTATION |
7 |
global | no | The number of backups to keep |
BACKUP_DIRECTORY |
/var/lib/bunkerweb/backups |
global | no | The directory where the backup will be stored |
Backup S3 (PRO)
STREAM support
Automatically backup your data to an S3 bucket
Setting | Default | Context | Multiple | Description |
---|---|---|---|---|
USE_BACKUP_S3 |
no |
global | no | Enable or disable the S3 backup feature |
BACKUP_S3_SCHEDULE |
daily |
global | no | The frequency of the backup |
BACKUP_S3_ROTATION |
7 |
global | no | The number of backups to keep |
BACKUP_S3_ENDPOINT |
global | no | The S3 endpoint | |
BACKUP_S3_BUCKET |
global | no | The S3 bucket | |
BACKUP_S3_DIR |
global | no | The S3 directory | |
BACKUP_S3_REGION |
global | no | The S3 region | |
BACKUP_S3_ACCESS_KEY_ID |
global | no | The S3 access key ID | |
BACKUP_S3_ACCESS_KEY_SECRET |
global | no | The S3 access key secret | |
BACKUP_S3_COMP_LEVEL |
6 |
global | no | The compression level of the backup zip file |
Bad behavior
STREAM support
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. |
BAD_BEHAVIOR_STATUS_CODES |
400 401 403 404 405 429 444 |
multisite | no | List of HTTP status codes considered as 'bad'. |
BAD_BEHAVIOR_THRESHOLD |
10 |
multisite | no | Maximum number of 'bad' HTTP status codes within the period of time before IP is banned. |
BAD_BEHAVIOR_COUNT_TIME |
60 |
multisite | no | Period of time (in seconds) during which we count 'bad' HTTP status codes. |
BAD_BEHAVIOR_BAN_TIME |
86400 |
multisite | no | The duration time (in seconds) of a ban when the corresponding IP has reached the threshold. |
Blacklist
STREAM support
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. |
BLACKLIST_IP |
multisite | no | List of IP/network, separated with spaces, to block. | |
BLACKLIST_RDNS |
.shodan.io .censys.io |
multisite | no | List of reverse DNS suffixes, separated with spaces, to block. |
BLACKLIST_RDNS_GLOBAL |
yes |
multisite | no | Only perform RDNS blacklist checks on global IP addresses. |
BLACKLIST_ASN |
multisite | no | List of ASN numbers, separated with spaces, to block. | |
BLACKLIST_USER_AGENT |
multisite | no | List of User-Agent (PCRE regex), separated with spaces, to block. | |
BLACKLIST_URI |
multisite | no | List of URI (PCRE regex), separated with spaces, to block. | |
BLACKLIST_IGNORE_IP |
multisite | no | List of IP/network, separated with spaces, to ignore in the blacklist. | |
BLACKLIST_IGNORE_RDNS |
multisite | no | List of reverse DNS suffixes, separated with spaces, to ignore in the blacklist. | |
BLACKLIST_IGNORE_ASN |
multisite | no | List of ASN numbers, separated with spaces, to ignore in the blacklist. | |
BLACKLIST_IGNORE_USER_AGENT |
multisite | no | List of User-Agent (PCRE regex), separated with spaces, to ignore in the blacklist. | |
BLACKLIST_IGNORE_URI |
multisite | no | List of URI (PCRE regex), separated with spaces, to ignore in the blacklist. | |
BLACKLIST_IP_URLS |
https://www.dan.me.uk/torlist/?exit |
global | no | List of URLs, separated with spaces, containing bad IP/network to block. Also supports file:// URLs and and auth basic using http://user:pass@url scheme. |
BLACKLIST_RDNS_URLS |
global | no | List of URLs, separated with spaces, containing reverse DNS suffixes to block. Also supports file:// URLs and and auth basic using http://user:pass@url scheme. | |
BLACKLIST_ASN_URLS |
global | no | List of URLs, separated with spaces, containing ASN to block. Also supports file:// URLs and and auth basic using http://user:pass@url scheme. | |
BLACKLIST_USER_AGENT_URLS |
https://raw.githubusercontent.com/mitchellkrogza/nginx-ultimate-bad-bot-blocker/master/_generator_lists/bad-user-agents.list |
global | no | List of URLs, separated with spaces, containing bad User-Agent to block. Also supports file:// URLs and and auth basic using http://user:pass@url scheme. |
BLACKLIST_URI_URLS |
global | no | List of URLs, separated with spaces, containing bad URI to block. Also supports file:// URLs and and auth basic using http://user:pass@url scheme. | |
BLACKLIST_IGNORE_IP_URLS |
global | no | List of URLs, separated with spaces, containing IP/network to ignore in the blacklist. Also supports file:// URLs and and auth basic using http://user:pass@url scheme. | |
BLACKLIST_IGNORE_RDNS_URLS |
global | no | List of URLs, separated with spaces, containing reverse DNS suffixes to ignore in the blacklist. Also supports file:// URLs and and auth basic using http://user:pass@url scheme. | |
BLACKLIST_IGNORE_ASN_URLS |
global | no | List of URLs, separated with spaces, containing ASN to ignore in the blacklist. Also supports file:// URLs and and auth basic using http://user:pass@url scheme. | |
BLACKLIST_IGNORE_USER_AGENT_URLS |
global | no | List of URLs, separated with spaces, containing User-Agent to ignore in the blacklist. Also supports file:// URLs and and auth basic using http://user:pass@url scheme. | |
BLACKLIST_IGNORE_URI_URLS |
global | no | List of URLs, separated with spaces, containing URI to ignore in the blacklist. Also supports file:// URLs and and auth basic using http://user:pass@url scheme. |
Brotli
STREAM support
Compress HTTP requests with the brotli algorithm.
Setting | Default | Context | Multiple | Description |
---|---|---|---|---|
USE_BROTLI |
no |
multisite | no | Use brotli |
BROTLI_TYPES |
application/atom+xml application/javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-opentype application/x-font-truetype application/x-font-ttf application/x-javascript application/xhtml+xml application/xml font/eot font/opentype font/otf font/truetype image/svg+xml image/vnd.microsoft.icon image/x-icon image/x-win-bitmap text/css text/javascript text/plain text/xml |
multisite | no | List of MIME types that will be compressed with brotli. |
BROTLI_MIN_LENGTH |
1000 |
multisite | no | Minimum length for brotli compression. |
BROTLI_COMP_LEVEL |
6 |
multisite | no | The compression level of the brotli algorithm. |
BunkerNet
STREAM support
Share threat data with other BunkerWeb instances via BunkerNet.
Setting | Default | Context | Multiple | Description |
---|---|---|---|---|
USE_BUNKERNET |
yes |
multisite | no | Activate BunkerNet feature. |
BUNKERNET_SERVER |
https://api.bunkerweb.io |
global | no | Address of the BunkerNet API. |
CORS
STREAM support
Cross-Origin Resource Sharing.
Setting | Default | Context | Multiple | Description |
---|---|---|---|---|
USE_CORS |
no |
multisite | no | Use CORS |
CORS_ALLOW_ORIGIN |
* |
multisite | no | Allowed origins to make CORS requests : PCRE regex or *. |
CORS_ALLOW_METHODS |
GET, POST, OPTIONS |
multisite | no | Value of the Access-Control-Allow-Methods header. |
CORS_ALLOW_HEADERS |
DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range |
multisite | no | Value of the Access-Control-Allow-Headers header. |
CORS_ALLOW_CREDENTIALS |
no |
multisite | no | Send the Access-Control-Allow-Credentials header. |
CORS_EXPOSE_HEADERS |
Content-Length,Content-Range |
multisite | no | Value of the Access-Control-Expose-Headers header. |
CROSS_ORIGIN_OPENER_POLICY |
multisite | no | Value for the Cross-Origin-Opener-Policy header. | |
CROSS_ORIGIN_EMBEDDER_POLICY |
multisite | no | Value for the Cross-Origin-Embedder-Policy header. | |
CROSS_ORIGIN_RESOURCE_POLICY |
multisite | no | Value for the Cross-Origin-Resource-Policy header. | |
CORS_MAX_AGE |
86400 |
multisite | no | Value of the Access-Control-Max-Age header. |
CORS_DENY_REQUEST |
yes |
multisite | no | Deny request and don't send it to backend if Origin is not allowed. |
Client cache
STREAM support
Manage caching for clients.
Setting | Default | Context | Multiple | Description |
---|---|---|---|---|
USE_CLIENT_CACHE |
no |
multisite | no | Tell client to store locally static files. |
CLIENT_CACHE_EXTENSIONS |
jpg|jpeg|png|bmp|ico|svg|tif|css|js|otf|ttf|eot|woff|woff2 |
global | no | List of file extensions, separated with pipes that should be cached. |
CLIENT_CACHE_ETAG |
yes |
multisite | no | Send the HTTP ETag header for static resources. |
CLIENT_CACHE_CONTROL |
public, max-age=15552000 |
multisite | no | Value of the Cache-Control HTTP header. |
Country
STREAM support
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 (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
STREAM support
Choose custom certificate for HTTPS.
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. |
DB
STREAM support
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. |
DATABASE_URI_READONLY |
global | no | The database URI for read-only operations, it can also serve as a fallback if the main database is down. Following the sqlalchemy format. | |
DATABASE_LOG_LEVEL |
warning |
global | no | The level to use for database logs. |
DNSBL
STREAM support
Deny access based on external DNSBL servers.
Setting | Default | Context | Multiple | Description |
---|---|---|---|---|
USE_DNSBL |
yes |
multisite | no | Activate DNSBL feature. |
DNSBL_LIST |
bl.blocklist.de problems.dnsbl.sorbs.net sbl.spamhaus.org xbl.spamhaus.org |
global | no | List of DNSBL servers. |
Errors
STREAM support
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 ...). | |
INTERCEPTED_ERROR_CODES |
400 401 403 404 405 413 429 500 501 502 503 504 |
multisite | no | List of HTTP error code intercepted by BunkerWeb |
Greylist
STREAM support
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. |
GREYLIST_IP |
multisite | no | List of IP/network, separated with spaces, to put into the greylist. | |
GREYLIST_RDNS |
multisite | no | List of reverse DNS suffixes, separated with spaces, to put into the greylist. | |
GREYLIST_RDNS_GLOBAL |
yes |
multisite | no | Only perform RDNS greylist checks on global IP addresses. |
GREYLIST_ASN |
multisite | no | List of ASN numbers, separated with spaces, to put into the greylist. | |
GREYLIST_USER_AGENT |
multisite | no | List of User-Agent (PCRE regex), separated with spaces, to put into the greylist. | |
GREYLIST_URI |
multisite | no | List of URI (PCRE regex), separated with spaces, to put into the greylist. | |
GREYLIST_IP_URLS |
global | no | List of URLs, separated with spaces, containing good IP/network to put into the greylist. Also supports file:// URLs and and auth basic using http://user:pass@url scheme. | |
GREYLIST_RDNS_URLS |
global | no | List of URLs, separated with spaces, containing reverse DNS suffixes to put into the greylist. Also supports file:// URLs and and auth basic using http://user:pass@url scheme. | |
GREYLIST_ASN_URLS |
global | no | List of URLs, separated with spaces, containing ASN to put into the greylist. Also supports file:// URLs and and auth basic using http://user:pass@url scheme. | |
GREYLIST_USER_AGENT_URLS |
global | no | List of URLs, separated with spaces, containing good User-Agent to put into the greylist. Also supports file:// URLs and and auth basic using http://user:pass@url scheme. | |
GREYLIST_URI_URLS |
global | no | List of URLs, separated with spaces, containing bad URI to put into the greylist. Also supports file:// URLs and and auth basic using http://user:pass@url scheme. |
Gzip
STREAM support
Compress HTTP requests with the gzip algorithm.
Setting | Default | Context | Multiple | Description |
---|---|---|---|---|
USE_GZIP |
no |
multisite | no | Use gzip |
GZIP_TYPES |
application/atom+xml application/javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-opentype application/x-font-truetype application/x-font-ttf application/x-javascript application/xhtml+xml application/xml font/eot font/opentype font/otf font/truetype image/svg+xml image/vnd.microsoft.icon image/x-icon image/x-win-bitmap text/css text/javascript text/plain text/xml |
multisite | no | List of MIME types that will be compressed with gzip. |
GZIP_MIN_LENGTH |
1000 |
multisite | no | Minimum length for gzip compression. |
GZIP_COMP_LEVEL |
5 |
multisite | no | The compression level of the gzip algorithm. |
GZIP_PROXIED |
no-cache no-store private expired auth |
multisite | no | Which kind of proxied requests we should compress. |
HTML injection
STREAM support
Inject custom HTML code before the