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 documentation to add Migration and Backup S3 pro plugins

Browse source
This commit is contained in:
Théophile Diot 2024-04-18 15:38:59 +02:00
parent f1dc94383d
commit 187d8a50cf
No known key found for this signature in database
GPG key ID: 248FEA4BAE400D06
2 changed files with 323 additions and 38 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

290
docs/security-tuning.md
View file

@ -640,9 +640,11 @@ The Reporting plugin provides a comprehensive solution for regular reporting of
## Backup and restore
### Backup
STREAM support :white_check_mark:
### Automated backup
#### Automated backup
!!! warning "Information for Red Hat Enterprise Linux (RHEL) 8.9 users"
If you are using **RHEL 8.9** and plan on using an **external database**, you will need to install the `mysql-community-client` package to ensure the `mysqldump` command is available. You can install the package by executing the following commands:
@ -696,7 +698,7 @@ Data is invaluable, especially in digital environments where it's susceptible to
| `BACKUP_SCHEDULE` | `daily` | global | no | The frequency of the backup |
| `BACKUP_ROTATION` | `7` | global | no | The number of backups to keep |
### Manual backup
#### Manual backup
To manually initiate a backup, execute the following command:
@ -766,7 +768,7 @@ You can also specify a custom directory for the backup by providing the `BACKUP_
...
```
### Manual restore
#### Manual restore
To manually initiate a restore, execute the following command:
@ -821,3 +823,285 @@ You can also specify a custom backup file for the restore by providing the path
```bash
docker exec -it -e BACKUP_DIRECTORY=/var/tmp/bunkerweb/backups <scheduler_container> bwcli plugin backup restore
```
### Backup S3 <img src='../assets/img/pro-icon.svg' alt='crow pro icon' height='24px' width='24px' style="transform : translateY(3px);"> (PRO)
STREAM support :white_check_mark:
The Backup S3 tool seamlessly automates data protection, similar to the community backup plugin. However, it stands out by securely storing backups directly in an S3 bucket.
By activating this feature, you're proactively safeguarding your **data's integrity**. Storing backups **remotely** shields crucial information from threats like **hardware failures**, **cyberattacks**, or **natural disasters**. This ensures both **security** and **availability**, enabling swift recovery during **unexpected events**, preserving **operational continuity**, and ensuring **peace of mind**.
!!! warning "Information for Red Hat Enterprise Linux (RHEL) 8.9 users"
If you are using **RHEL 8.9** and plan on using an **external database**, you will need to install the `mysql-community-client` package to ensure the `mysqldump` command is available. You can install the package by executing the following commands:
=== "MySQL/MariaDB"
1. **Install the MySQL repository configuration package**
```bash
sudo dnf install https://dev.mysql.com/get/mysql80-community-release-el8-9.noarch.rpm
```
2. **Enable the MySQL repository**
```bash
sudo dnf config-manager --enable mysql80-community
```
3. **Install the MySQL client**
```bash
sudo dnf install mysql-community-client
```
=== "PostgreSQL"
1. **Install the PostgreSQL repository configuration package**
```bash
dnf install "https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-$(uname -m)/pgdg-redhat-repo-latest.noarch.rpm"
```
2. **Install the PostgreSQL client**
```bash
dnf install postgresql<version>
```
**List of features**
- Automatic data backup to an S3 bucket
- Flexible scheduling options: daily, weekly, or monthly
- Rotation management for controlling the number of backups to keep
- Customizable compression level for backup files
**List of settings**
| Setting | Default | Context | Description |
| ----------------------------- | ------- | ------- | ------------------------------------------------ |
| `USE_BACKUP_S3` | `no` | global | Enable or disable the S3 backup feature |
| `BACKUP_S3_SCHEDULE` | `daily` | global | Frequency of the backup (daily, weekly, monthly) |
| `BACKUP_S3_ROTATION` | `7` | global | Number of backups to keep |
| `BACKUP_S3_ENDPOINT` | | global | S3 endpoint |
| `BACKUP_S3_BUCKET` | | global | S3 bucket name |
| `BACKUP_S3_REGION` | | global | S3 region |
| `BACKUP_S3_ACCESS_KEY_ID` | | global | S3 access key ID |
| `BACKUP_S3_ACCESS_KEY_SECRET` | | global | S3 access key secret |
| `BACKUP_S3_COMP_LEVEL` | `6` | global | Compression level of the backup zip file (1-9) |
#### Manual backup
To manually initiate a backup, execute the following command:
=== "Linux"
```bash
bwcli plugin backup_s3 save
```
=== "Docker"
```bash
docker exec -it <scheduler_container> bwcli plugin backup_s3 save
```
This command will create a backup of your database and store it in the S3 bucket specified in the `BACKUP_S3_BUCKET` setting.
You can also specify a custom S3 bucket for the backup by providing the `BACKUP_S3_BUCKET` environment variable when executing the command:
=== "Linux"
```bash
BACKUP_S3_BUCKET=your-bucket-name bwcli plugin backup_s3 save
```
=== "Docker"
```bash
docker exec -it -e BACKUP_S3_BUCKET=your-bucket-name <scheduler_container> bwcli plugin backup_s3 save
```
!!! note "Specifications for MariaDB/MySQL"
In case you are using MariaDB/MySQL, you may encounter the following error when trying to backup your database:
```bash
caching_sha2_password could not be loaded: Error loading shared library /usr/lib/mariadb/plugin/caching_sha2_password.so
```
To resolve this issue, you can execute the following command to change the authentication plugin to `mysql_native_password`:
```sql
ALTER USER 'yourusername'@'localhost' IDENTIFIED WITH mysql_native_password BY 'youpassword';
```
If you're using the Docker integration, you can add the following command to the `docker-compose.yml` file to automatically change the authentication plugin:
=== "MariaDB"
```yaml
bw-db:
image: mariadb:<version>
command: --default-authentication-plugin=mysql_native_password
...
```
=== "MySQL"
```yaml
bw-db:
image: mysql:<version>
command: --default-authentication-plugin=mysql_native_password
...
```
#### Manual restore
To manually initiate a restore, execute the following command:
=== "Linux"
```bash
bwcli plugin backup_s3 restore
```
=== "Docker"
```bash
docker exec -it <scheduler_container> bwcli plugin backup_s3 restore
```
This command will create a temporary backup of your database in the S3 bucket specified in the `BACKUP_S3_BUCKET` setting and restore your database to the latest backup available in the bucket.
You can also specify a custom backup file for the restore by providing the path to it as an argument when executing the command:
=== "Linux"
```bash
bwcli plugin backup_s3 restore s3_backup_file.zip
```
=== "Docker"
```bash
docker exec -it <scheduler_container> bwcli plugin backup restore s3_backup_file.zip
```
!!! example "In case of failure"
Don't worry if the restore fails, you can always restore your database to the previous state by executing the command again as a backup is created before the restore:
=== "Linux"
```bash
bwcli plugin backup_s3 restore
```
=== "Docker"
```bash
docker exec -it <scheduler_container> bwcli plugin backup_s3 restore
```
## Migration of BunkerWeb
### Migration <img src='../assets/img/pro-icon.svg' alt='crow pro icon' height='24px' width='24px' style="transform : translateY(3px);"> (PRO)
STREAM support :white_check_mark:
The Migration tool **revolutionizes** BunkerWeb configuration transfers between instances with its **user-friendly web interface**, simplifying the entire migration journey. Whether you're upgrading systems, scaling infrastructure, or transitioning environments, this tool empowers you to effortlessly transfer **settings, preferences, and data** with unmatched ease and confidence. Say goodbye to cumbersome manual processes and hello to a **seamless, hassle-free migration experience**.
**List of features**
- **Effortless Migration:** Easily transfer BunkerWeb configurations between instances without the complexities of manual procedures.
- **Intuitive Web Interface:** Navigate through the migration process effortlessly with a user-friendly web interface designed for intuitive operation.
- **Cross-Database Compatibility:** Enjoy seamless migration across various database platforms, including SQLite, MySQL, MariaDB, and PostgreSQL, ensuring compatibility with your preferred database environment.
#### Create a migration file
To manually create a migration file, execute the following command:
=== "Linux"
```bash
bwcli plugin migration create /path/to/migration/file
```
=== "Docker"
1. Create a migration file:
```bash
docker exec -it <scheduler_container> bwcli plugin migration create /path/to/migration/file
```
2. Copy the migration file to your local machine:
```bash
docker cp <scheduler_container>:/path/to/migration/file /path/to/migration/file
```
This command will create a backup of your database and store it in the backup directory specified in the command.
!!! note "Specifications for MariaDB/MySQL"
In case you are using MariaDB/MySQL, you may encounter the following error when trying to backup your database:
```bash
caching_sha2_password could not be loaded: Error loading shared library /usr/lib/mariadb/plugin/caching_sha2_password.so
```
To resolve this issue, you can execute the following command to change the authentication plugin to `mysql_native_password`:
```sql
ALTER USER 'yourusername'@'localhost' IDENTIFIED WITH mysql_native_password BY 'youpassword';
```
If you're using the Docker integration, you can add the following command to the `docker-compose.yml` file to automatically change the authentication plugin:
=== "MariaDB"
```yaml
bw-db:
image: mariadb:<version>
command: --default-authentication-plugin=mysql_native_password
...
```
=== "MySQL"
```yaml
bw-db:
image: mysql:<version>
command: --default-authentication-plugin=mysql_native_password
...
```
#### Initialize a migration
To manually initialize a migration, execute the following command:
=== "Linux"
```bash
bwcli plugin migration migrate /path/to/migration/file
```
=== "Docker"
1. Copy the migration file to the container:
```bash
docker cp /path/to/migration/file <scheduler_container>:/path/to/migration/file
```
2. Initialize the migration:
```bash
docker exec -it <scheduler_container> bwcli plugin migration migrate /path/to/migration/file
```
This command seamlessly migrates your BunkerWeb data to precisely match the configuration outlined in the migration file.

71
docs/settings.md
View file

@ -15,41 +15,42 @@ When settings are considered as "multiple", it means that you can have multiple
STREAM support :warning:
| 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. |
|`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. |
|`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. |
| 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. |
|`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. |
|`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)|
## Antibot