From 187d8a50cf349b730aed672d9d2f4b548a306e57 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Th=C3=A9ophile=20Diot?= Date: Thu, 18 Apr 2024 15:38:59 +0200 Subject: [PATCH] Update documentation to add Migration and Backup S3 pro plugins --- docs/security-tuning.md | 290 +++++++++++++++++++++++++++++++++++++++- docs/settings.md | 71 +++++----- 2 files changed, 323 insertions(+), 38 deletions(-) diff --git a/docs/security-tuning.md b/docs/security-tuning.md index ea6438813..16f6f8244 100644 --- a/docs/security-tuning.md +++ b/docs/security-tuning.md @@ -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 bwcli plugin backup restore ``` + +### Backup S3 crow pro icon (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 + ``` + +**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 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 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: + command: --default-authentication-plugin=mysql_native_password + ... + ``` + + === "MySQL" + + ```yaml + bw-db: + image: mysql: + 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 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 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 bwcli plugin backup_s3 restore + ``` + +## Migration of BunkerWeb + +### Migration crow pro icon (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 bwcli plugin migration create /path/to/migration/file + ``` + + 2. Copy the migration file to your local machine: + + ```bash + docker cp :/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: + command: --default-authentication-plugin=mysql_native_password + ... + ``` + + === "MySQL" + + ```yaml + bw-db: + image: mysql: + 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 :/path/to/migration/file + ``` + + 2. Initialize the migration: + + ```bash + docker exec -it 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. diff --git a/docs/settings.md b/docs/settings.md index 02784093e..8e13116b9 100644 --- a/docs/settings.md +++ b/docs/settings.md @@ -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