From cd8011195b449aec53b059f653ca0c093109a70a Mon Sep 17 00:00:00 2001 From: Adam Langbert Date: Sun, 27 Feb 2022 09:39:39 -0500 Subject: [PATCH 1/3] Improve docker documentation --- README.md | 34 ++++++++++++++++------------- docker-compose.yml | 8 ------- docs/deployment/1-docker.md | 24 +++++++++----------- docs/deployment/2-docker-compose.md | 23 +++++++++++++++++++ 4 files changed, 52 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 244ca3cf..fa90c785 100644 --- a/README.md +++ b/README.md @@ -64,27 +64,16 @@ docker run \ ghcr.io/freifunkmuc/wg-access-server:latest ``` +**Note:** This command includes the `SYS_MODULE` capability which essentially gives the container root privileges over the host system and an attacker could easily break out of the container. See the [Docker instructions](https://www.freie-netze.org/wg-access-server/deployment/1-docker/) for the recommended way to run the container. + If the wg-access-server is accessible via LAN or a network you are in, you can directly connect your phone to the VPN. You have to call the webfrontent of the project for this. Normally, this is done via the IP address of the device or server on which the wg-access-server is running followed by the standard port 8000, via which the web interface can be reached. For most deployments something like this should work: http://192.168.0.XX:8000 If the project is running locally on the computer, you can easily connect to the web interface by connecting to http://localhost:8000 in the browser. -## Running on Kubernetes via Helm - -wg-access-server ships a Helm chart to make it easy to get started on -Kubernetes. - -Here's a quick start, but you can read more at the [Helm Chart Deployment Docs](https://freifunkMUC.github.io/wg-access-server/deployment/3-kubernetes/) - -```bash -# deploy -helm install my-release --repo https://freifunkMUC.github.io/wg-access-server wg-access-server - -# cleanup -helm delete my-release -``` - ## Running with Docker-Compose +Please also read the [Docker instructions](https://www.freie-netze.org/wg-access-server/deployment/1-docker/) for general information regarding Docker deployments. + Download the the docker-compose.yml file from the repo and run the following command. ```bash @@ -100,6 +89,21 @@ You can connect to the web server on the local machine browser at http://localho If you open your browser to your machine's LAN IP address you'll be able to connect your phone using the UI and QR code! +## Running on Kubernetes via Helm + +wg-access-server ships a Helm chart to make it easy to get started on +Kubernetes. + +Here's a quick start, but you can read more at the [Helm Chart Deployment Docs](https://freifunkMUC.github.io/wg-access-server/deployment/3-kubernetes/) + +```bash +# deploy +helm install my-release --repo https://freifunkMUC.github.io/wg-access-server wg-access-server + +# cleanup +helm delete my-release +``` + ## Screenshots ![Devices](https://github.com/freifunkMUC/wg-access-server/raw/master/screenshots/devices.png) diff --git a/docker-compose.yml b/docker-compose.yml index 400abecb..4c617162 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -9,16 +9,13 @@ services: container_name: wg-access-server cap_add: - NET_ADMIN - - SYS_MODULE sysctls: net.ipv6.conf.all.disable_ipv6: 0 net.ipv6.conf.all.forwarding: 1 volumes: - - "/lib/modules:/lib/modules:ro" - "wg-access-server-data:/data" # - "./config.yaml:/config.yaml" # if you have a custom config file environment: - - "WG_ADMIN_USERNAME=admin" - "WG_ADMIN_PASSWORD=${WG_ADMIN_PASSWORD:?\n\nplease set the WG_ADMIN_PASSWORD environment variable:\n export WG_ADMIN_PASSWORD=example\n}" - "WG_WIREGUARD_PRIVATE_KEY=${WG_WIREGUARD_PRIVATE_KEY:?\n\nplease set the WG_WIREGUARD_PRIVATE_KEY environment variable:\n export WG_WIREGUARD_PRIVATE_KEY=$(wg genkey)\n}" # - "WG_VPN_CIDRV6=0" # to disable IPv6 @@ -27,8 +24,3 @@ services: - "51820:51820/udp" devices: - "/dev/net/tun:/dev/net/tun" - -# shared volumes with the host -volumes: - wg-access-server-data: - driver: local diff --git a/docs/deployment/1-docker.md b/docs/deployment/1-docker.md index eb1dc95f..2240677a 100644 --- a/docs/deployment/1-docker.md +++ b/docs/deployment/1-docker.md @@ -1,20 +1,23 @@ # Docker -## TL;DR; +Load the `ip_tables` and `ip6_tables` kernel modules on the host. -Here's a one-liner to run wg-access-server: +```bash +modprobe ip_tables && modprobe ip6_tables +# Load modules on boot +echo ip_tables >> /etc/modules +echo ip6_tables >> /etc/modules +``` ```bash docker run \ -it \ --rm \ --cap-add NET_ADMIN \ - --cap-add SYS_MODULE \ --device /dev/net/tun:/dev/net/tun \ --sysctl net.ipv6.conf.all.disable_ipv6=0 \ --sysctl net.ipv6.conf.all.forwarding=1 \ -v wg-access-server-data:/data \ - -v /lib/modules:/lib/modules:ro \ -e "WG_ADMIN_PASSWORD=$WG_ADMIN_PASSWORD" \ -e "WG_WIREGUARD_PRIVATE_KEY=$WG_WIREGUARD_PRIVATE_KEY" \ -p 8000:8000/tcp \ @@ -24,16 +27,9 @@ docker run \ ## Modules -If you load the kernel modules `ip_tables` and `ip6_tables` on the host, -you can drop the `SYS_MODULE` capability and remove the `/lib/modules` mount: -```bash -modprobe ip_tables && modprobe ip6_tables -# Load modules on boot -echo ip_tables >> /etc/modules -echo ip6_tables >> /etc/modules -``` -This is highly recommended, as a container with CAP_SYS_MODULE essentially has root privileges -over the host system and attacker could easily break out of the container. +If you are unable to load the kernel modules, you can add the `SYS_MODULE` capability instead: `--cap-add SYS_MODULE`. You must also add the following mount: `-v /lib/modules:/lib/modules:ro`. + +This is not recommended as it essentially gives the container root privileges over the host system and an attacker could easily break out of the container. ## IPv4-only (without IPv6) diff --git a/docs/deployment/2-docker-compose.md b/docs/deployment/2-docker-compose.md index 9aa9b706..7763e69d 100644 --- a/docs/deployment/2-docker-compose.md +++ b/docs/deployment/2-docker-compose.md @@ -9,3 +9,26 @@ Please also read the [Docker instructions](../1-docker.md) for general informati ```yaml {!../docker-compose.yml!} ``` + +## IPv4-only (without IPv6) + +```yaml +version: "3.0" +services: + wg-access-server: + image: ghcr.io/freifunkmuc/wg-access-server:latest + container_name: wg-access-server + cap_add: + - NET_ADMIN + volumes: + - "wg-access-server-data:/data" + environment: + - "WG_ADMIN_PASSWORD=${WG_ADMIN_PASSWORD:?\n\nplease set the WG_ADMIN_PASSWORD environment variable:\n export WG_ADMIN_PASSWORD=example\n}" + - "WG_WIREGUARD_PRIVATE_KEY=${WG_WIREGUARD_PRIVATE_KEY:?\n\nplease set the WG_WIREGUARD_PRIVATE_KEY environment variable:\n export WG_WIREGUARD_PRIVATE_KEY=$(wg genkey)\n}" + - "WG_VPN_CIDRV6=0" # to disable IPv6 + ports: + - "8000:8000/tcp" + - "51820:51820/udp" + devices: + - "/dev/net/tun:/dev/net/tun" +``` From 81634a45449874d50e4a91f3b106dcf393f1be00 Mon Sep 17 00:00:00 2001 From: Adam Langbert Date: Mon, 28 Feb 2022 16:13:31 -0500 Subject: [PATCH 2/3] add back named volume --- docker-compose.yml | 5 +++++ docs/deployment/2-docker-compose.md | 4 ++++ 2 files changed, 9 insertions(+) diff --git a/docker-compose.yml b/docker-compose.yml index 4c617162..dc772297 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -24,3 +24,8 @@ services: - "51820:51820/udp" devices: - "/dev/net/tun:/dev/net/tun" + +# shared volumes with the host +volumes: + wg-access-server-data: + driver: local diff --git a/docs/deployment/2-docker-compose.md b/docs/deployment/2-docker-compose.md index 7763e69d..fd5f382b 100644 --- a/docs/deployment/2-docker-compose.md +++ b/docs/deployment/2-docker-compose.md @@ -31,4 +31,8 @@ services: - "51820:51820/udp" devices: - "/dev/net/tun:/dev/net/tun" + +volumes: + wg-access-server-data: + driver: local ``` From ff4a05dcab410e347e21a234604ff3d3ab25e9fa Mon Sep 17 00:00:00 2001 From: DasSkelett Date: Mon, 28 Feb 2022 22:31:56 +0100 Subject: [PATCH 3/3] Fix Docker instructions link in 2-docker-compose.md --- docs/deployment/2-docker-compose.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/deployment/2-docker-compose.md b/docs/deployment/2-docker-compose.md index fd5f382b..272bb13e 100644 --- a/docs/deployment/2-docker-compose.md +++ b/docs/deployment/2-docker-compose.md @@ -4,7 +4,7 @@ You can run wg-access-server using the following example Docker Compose file. Checkout the [configuration docs](../2-configuration.md) to learn how wg-access-server can be configured. -Please also read the [Docker instructions](../1-docker.md) for general information regarding Docker deployments. +Please also read the [Docker instructions](1-docker.md) for general information regarding Docker deployments. ```yaml {!../docker-compose.yml!}