From cc4f0b26a15fa86aa482af3e254fef2212327bc7 Mon Sep 17 00:00:00 2001 From: AxyFr Date: Fri, 8 Jul 2022 17:31:36 +0200 Subject: [PATCH] Quickstart Ansible and integration --- docs/integrations.md | 48 +++++++++++ docs/quickstart-guide.md | 180 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 228 insertions(+) diff --git a/docs/integrations.md b/docs/integrations.md index dd059de87..e834377ae 100644 --- a/docs/integrations.md +++ b/docs/integrations.md @@ -874,3 +874,51 @@ BunkerWeb is managed using systemctl : - Start it if it's stopped : `systemctl start bunkerweb` - Stop it if it's started : `systemctl stop bunkerweb` - And restart : `systemctl restart bunkerweb` + +## Ansible + +
+ ![Overwiew](assets/img/integration-linux.svg){ align=center } +
Linux integration
+
+ +List of supported Linux distros : + +- Debian 11 "Bullseye" +- Ubuntu 22.04 "Jammy" +- Fedora 36 +- CentOS Stream 8 + +Ansible is an IT automation tool working with python. Ansible work with ssh to connect to remote server, so make sure to have a ssh key. The role will deploy bunkerweb on your remote server. + +First of all download the role from ansible-galaxy: (TODO) + +Next create an inventory by adding the IP adress or FQDN of one or more remote systems, either in `/etc/ansible/hosts` or in your own playbook `inventory.yml` + +``` +[remotehosts] +192.0.2.50 +192.0.2.51 +192.0.2.52 +``` + +The next step we're going to set up the SSH connections so Ansible can connect to the managed nodes. +Firstly: Add your public SSH keys to the `authorized_keys` file on each remote system +Secondly: +Test the SSH connections: +`ssh username@192.0.2.50` + +In order to use the role, we will create the playbook file named `playbook.yml` for example: +```yaml +--- +- hosts: all + become: true + + roles: + - bunkerweb +``` + +Run the playbook: +`ansible-playbook -i inventory.yml playbook.yml` + +The configurations by default for Bunkerweb are minimals, so check out the rest of the documentations to configure Bunkerweb as you desire [quickstart-guide](http://localhost:8000/quickstart-guide/). \ No newline at end of file diff --git a/docs/quickstart-guide.md b/docs/quickstart-guide.md index cbff914fc..22a1add53 100644 --- a/docs/quickstart-guide.md +++ b/docs/quickstart-guide.md @@ -273,6 +273,42 @@ You will find more settings about reverse proxy in the [settings section](/1.4/s systemctl start bunkerweb ``` +=== "Ansible" + + We will assume that you already have a service running and you want to use bunkerweb as a reverse-proxy. + + The following command will run a basic HTTP server on the port 8000 and deliver the files in the current directory : + ```shell + python3 -m http.server -b 127.0.0.1 + ``` + + Configuration of the `variables.env` file : + ```conf + SERVER_NAME=www.example.com + HTTP_PORT=80 + HTTPS_PORT=443 + DNS_RESOLVERS=8.8.8.8 8.8.4.4 + USE_REVERSE_PROXY=yes + REVERSE_PROXY_URL=/ + REVERSE_PROXY_HOST=http://127.0.0.1:8000 + ``` + + In your Ansible inventory, you can use the `variables_env` variable to configure BunkerWeb : + ```yaml + all: + children: + Groups: + hosts: + "Your_IP_Address": + vars: + variables_env: ../variables.env + ``` + + Run the playbook : + ```shell + ansible-playbook -i inventory.yml playbook.yml + ``` + ### Multiple applications !!! tip "Testing" @@ -832,6 +868,57 @@ You will find more settings about reverse proxy in the [settings section](/1.4/s systemctl start bunkerweb ``` +=== "Ansible" + + Let's assume that you have some web applications running on the same machine as BunkerWeb : + + === "App #1" + The following command will run a basic HTTP server on the port 8001 and deliver the files in the current directory : + ```shell + python3 -m http.server -b 127.0.0.1 8001 + ``` + + === "App #2" + The following command will run a basic HTTP server on the port 8002 and deliver the files in the current directory : + ```shell + python3 -m http.server -b 127.0.0.1 8002 + ``` + + === "App #3" + The following command will run a basic HTTP server on the port 8003 and deliver the files in the current directory : + ```shell + python3 -m http.server -b 127.0.0.1 8003 + ``` + + Configuration of the `variables.env` file : + ```conf + SERVER_NAME=app1.example.com app2.example.com app3.example.com + HTTP_PORT=80 + HTTPS_PORT=443 + DNS_RESOLVERS=8.8.8.8 8.8.4.4 + USE_REVERSE_PROXY=yes + REVERSE_PROXY_URL=/ + app1.example.com_REVERSE_PROXY_HOST=http://127.0.0.1:8001 + app2.example.com_REVERSE_PROXY_HOST=http://127.0.0.1:8002 + app3.example.com_REVERSE_PROXY_HOST=http://127.0.0.1:8003 + ``` + + In your Ansible inventory, you can use the `variables_env` variable to configure BunkerWeb : + ```yaml + all: + children: + Groups: + hosts: + "Your_IP_Address": + vars: + variables_env: ../variables.env + ``` + + Run the playbook : + ```shell + ansible-playbook -i inventory.yml playbook.yml + ``` + ## Behind load balancer or reverse proxy When BunkerWeb is itself behind a load balancer or a reverse proxy, you will need to configure it so it can get the real IP address of the clients. If you don't do it, the security features will block the IP address of the load balancer or reverse proxy instead of the client one. @@ -981,6 +1068,33 @@ REAL_IP_HEADER=X-Forwarded-For Don't forget to reload the bunkerweb service once it's done. +=== "Ansible" + + You will need to add the settings to your `variables.env` file : + ```conf + ... + USE_REAL_IP=yes + REAL_IP_FROM=1.2.3.0/24 100.64.0.0/16 + REAL_IP_HEADER=X-Forwarded-For + ... + ``` + + In your Ansible inventory, you can use the `variables_env` variable to configure BunkerWeb : + ```yaml + all: + children: + Groups: + hosts: + "Your_IP_Address": + vars: + variables_env: ../variables.env + ``` + + Run the playbook : + ```shell + ansible-playbook -i inventory.yml playbook.yml + ``` + ### Proxy protocol We will assume the following regarding the load balancers or reverse proxies (you will need to update the settings depending on your configuration) : @@ -1122,6 +1236,34 @@ REAL_IP_HEADER=proxy_protocol Don't forget to reload the bunkerweb service once it's done. +=== "Ansible" + + You will need to add the settings to your `variables.env` file : + ```conf + ... + USE_REAL_IP=yes + USE_PROXY_PROTOCOL=yes + REAL_IP_FROM=1.2.3.0/24 100.64.0.0/16 + REAL_IP_HEADER=proxy_protocol + ... + ``` + + In your Ansible inventory, you can use the `variables_env` variable to configure BunkerWeb : + ```yaml + all: + children: + Groups: + hosts: + "Your_IP_Address": + vars: + variables_env: ../variables.env + ``` + + Run the playbook : + ```shell + ansible-playbook -i inventory.yml playbook.yml + ``` + ## Custom configurations Because BunkerWeb is based on the NGINX web server, you can add custom NGINX configurations in different NGINX contexts. You can also apply custom configurations for the ModSecurity WAF which is a core component of BunkerWeb (more info [here](/1.4/security-tuning/#modsecurity)). Here is the list of custom configurations types : @@ -1350,3 +1492,41 @@ Some integrations offer a more convenient way of applying configurations for exa ``` Don't forget to reload the bunkerweb service once it's done. + +=== "Ansible" + + When the variable `custom_configs` is set to "true" , you could use the + `custom_configs_path[]` variable to write the configs to the /opt/bunkerweb/configs folder. + + Here is an example for server-http/hello-world.conf : + ```conf + location /hello { + default_type 'text/plain'; + content_by_lua_block { + ngx.say('world') + } + } + ``` + + In your Ansible inventory, you can use the `variables_env` variable to configure BunkerWeb : + ```yaml + all: + children: + Groups: + hosts: + "Your_IP_Address": + vars: + custom_configs: true + custom_configs_path: { + server-http: ../hello-world.conf, + #http: ../http.conf, + #default-server-http: ../default-server-http.conf, + #modsec-crs: ../modsec-crs, + #modsec: ../modsec + } + ``` + + Run the playbook : + ```shell + ansible-playbook -i inventory.yml playbook.yml + ``` \ No newline at end of file