From 68203c221d652b3cc8b50d22df624cfd30323957 Mon Sep 17 00:00:00 2001 From: Quentin McGaw Date: Sun, 12 Apr 2020 13:42:41 +0000 Subject: [PATCH] Refactored documentation for Docker hub workflow - Readme size lowered to 18KB - Documents created in doc/ directory - faq.md, firewall.md, development.md - Title svg as absolute path for Docker hub - Re-enabled Docker hub description workflow --- .github/CONTRIBUTING.md | 12 + .github/workflows/dockerhub-description.yml | 11 +- README.md | 247 +------------------- doc/development.md | 43 ++++ doc/faq.md | 128 ++++++++++ doc/firewall.md | 39 ++++ 6 files changed, 234 insertions(+), 246 deletions(-) create mode 100644 doc/development.md create mode 100644 doc/faq.md create mode 100644 doc/firewall.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index d16bd038..96ad5a7b 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -15,3 +15,15 @@ Contributions are [released](https://help.github.com/articles/github-terms-of-se - [Using Pull Requests](https://help.github.com/articles/about-pull-requests/) - [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/) + +## Contributors + +Thanks for all the contributions, whether small or not so small! + +- [@JeordyR](https://github.com/JeordyR) for testing the Mullvad version and opening a [PR with a few fixes](https://github.com/qdm12/private-internet-access-docker/pull/84/files) 👍 +- [@rorph](https://github.com/rorph) for a [PR to pick a random region for PIA](https://github.com/qdm12/private-internet-access-docker/pull/70) and a [PR to make the container work with kubernetes](https://github.com/qdm12/private-internet-access-docker/pull/69) +- [@JesterEE](https://github.com/JesterEE) for a [PR to fix silly line endings in block lists back then](https://github.com/qdm12/private-internet-access-docker/pull/55) 📎 +- [@elmerfdz](https://github.com/elmerfdz) for a [PR to add timezone information to have correct log timestampts](https://github.com/qdm12/private-internet-access-docker/pull/51) 🕙 +- [@Juggels](https://github.com/Juggels) for a [PR to write the PIA forwarded port to a file](https://github.com/qdm12/private-internet-access-docker/pull/43) +- [@gdlx](https://github.com/gdlx) for a [PR to fix and improve PIA port forwarding script](https://github.com/qdm12/private-internet-access-docker/pull/32) +- [@janaz](https://github.com/janaz) for keeping an eye on [updating things in the Dockerfile](https://github.com/qdm12/private-internet-access-docker/pull/8) diff --git a/.github/workflows/dockerhub-description.yml b/.github/workflows/dockerhub-description.yml index eaa414fb..98282e7f 100644 --- a/.github/workflows/dockerhub-description.yml +++ b/.github/workflows/dockerhub-description.yml @@ -1,16 +1,7 @@ name: Docker Hub description on: push: - branches-ignore: - - '**' - #branches: [master] - paths: - - README.md - - .github/workflows/dockerhub-description.yml - pull_request: - branches-ignore: - - '**' - #branches: [master] + branches: [master] paths: - README.md - .github/workflows/dockerhub-description.yml diff --git a/README.md b/README.md index ef92267c..bc8725ac 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ **ANNOUNCEMENT**: *Support for [Windscribe](https://windscribe.com/)* - + [![Build status](https://github.com/qdm12/private-internet-access-docker/workflows/Buildx%20latest/badge.svg)](https://github.com/qdm12/private-internet-access-docker/actions?query=workflow%3A%22Buildx+latest%22) [![Docker Pulls](https://img.shields.io/docker/pulls/qmcgaw/private-internet-access.svg)](https://hub.docker.com/r/qmcgaw/private-internet-access) @@ -71,26 +71,7 @@ 1. Requirements - Docker 1.13, in order to have Docker API 1.25 which supports `init` (and, if you use docker-compose, docker-compose version 1.22.0) - A Private Internet Access **username** and **password** ([sign up](https://www.privateinternetaccess.com/pages/buy-vpn/)) or Mullvad user ID ([sign up](https://mullvad.net/en/account/)) - -
External firewall requirements, if you have one

- - - At start only - - Allow outbound TCP 443 to github.com - - If `DOT=on`, allow outbound TCP 853 to allow Unbound to resolve github.com and the PIA subdomain name if you use PIA. - - If `DOT=off` and `VPNSP=pia`, allow outbound UDP 53 to your DNS provider to resolve the PIA subdomain name. - - If `VPNSP=pia`, `PIA_ENCRYPTION=strong` and `PROTOCOL=udp`: allow outbound UDP 1197 to the corresponding VPN server IPs - - If `VPNSP=pia`, `PIA_ENCRYPTION=normal` and `PROTOCOL=udp`: allow outbound UDP 1198 to the corresponding VPN server IPs - - If `VPNSP=pia`, `PIA_ENCRYPTION=strong` and `PROTOCOL=tcp`: allow outbound TCP 501 to the corresponding VPN server IPs - - If `VPNSP=pia`, `PIA_ENCRYPTION=normal` and `PROTOCOL=tcp`: allow outbound TCP 502 to the corresponding VPN server IPs - - If `VPNSP=mullvad` and `PORT=`, please refer to the mapping of Mullvad servers in [these source code lines](https://github.com/qdm12/private-internet-access-docker/blob/master/internal/constants/mullvad.go#L64-L667) to find the corresponding UDP port number and IP address(es) of your choice - - If `VPNSP=mullvad` and `PORT=53`, allow outbound UDP 53 to the corresponding VPN server IPs, which you can fine in [the mapping of Mullvad servers](https://github.com/qdm12/private-internet-access-docker/blob/master/internal/constants/mullvad.go#L64-L667) - - If `VPNSP=mullvad` and `PORT=80`, allow outbound TCP 80 to the corresponding VPN server IPs, which you can fine in [the mapping of Mullvad servers](https://github.com/qdm12/private-internet-access-docker/blob/master/internal/constants/mullvad.go#L64-L667) - - If `VPNSP=mullvad` and `PORT=443`, allow outbound TCP 443 to the corresponding VPN server IPs, which you can fine in [the mapping of Mullvad servers](https://github.com/qdm12/private-internet-access-docker/blob/master/internal/constants/mullvad.go#L64-L667) - - If `VPNSP=windscribe` and `PROTOCOL=udp`: allow outbound UDP 443 to the corresponding VPN server IPs - - If `VPNSP=windscribe` and `PROTOCOL=tcp`: allow outbound TCP 1194 to the corresponding VPN server IPs - - If `SHADOWSOCKS=on`, allow inbound TCP 8388 and UDP 8388 from your LAN - - If `TINYPROXY=on`, allow inbound TCP 8888 from your LAN - -

+ - If you have a host or router firewall, please refer [to the firewall documentation](https://github.com/qdm12/private-internet-access-docker/blob/master/doc/firewall.md) 1. Launch the container with: @@ -109,8 +90,8 @@ Note that you can: - Change the many [environment variables](#environment-variables) available - - Use `-p 8888:8888/tcp` to access the HTTP web proxy (and put your LAN in `EXTRA_SUBNETS` environment variable) - - Use `-p 8388:8388/tcp -p 8388:8388/udp` to access the SOCKS5 proxy (and put your LAN in `EXTRA_SUBNETS` environment variable) + - Use `-p 8888:8888/tcp` to access the HTTP web proxy (and put your LAN in `EXTRA_SUBNETS` environment variable, in example `192.168.1.0/24`) + - Use `-p 8388:8388/tcp -p 8388:8388/udp` to access the SOCKS5 proxy (and put your LAN in `EXTRA_SUBNETS` environment variable, in example `192.168.1.0/24`) - Pass additional arguments to *openvpn* using Docker's command function (commands after the image name) 1. You can update the image with `docker pull qmcgaw/private-internet-access:latest`. There are also docker tags for older versions available: @@ -275,221 +256,15 @@ It can be useful to mount this file as a volume to read it from other containers ## FAQ -
Openvpn disconnects because of a ping timeout

+Please refer to [the FAQ table of content](https://github.com/qdm12/private-internet-access-docker/blob/master/doc/faq.md#Table-of-content) -It happens especially on some PIA servers where they change their configuration or the server goes offline. +## Development and contributing -You will obtain an error similar to: - -```s -openvpn: Wed Mar 18 22:13:00 2020 [3a51ae90324bcb0719cb399b650c64d4] Inactivity timeout (--ping-restart), restarting, -openvpn: Wed Mar 18 22:13:00 2020 SIGUSR1[soft,ping-restart] received, process restarting, -... -openvpn: Wed Mar 18 22:13:17 2020 Preserving previous TUN/TAP instance: tun0, -openvpn: Wed Mar 18 22:13:17 2020 NOTE: Pulled options changed on restart, will need to close and reopen TUN/TAP device., -openvpn: Wed Mar 18 22:13:17 2020 ERROR: Linux route delete command failed: external program exited with error status: 2, -openvpn: Wed Mar 18 22:13:17 2020 ERROR: Linux route delete command failed: external program exited with error status: 2, -openvpn: Wed Mar 18 22:13:17 2020 ERROR: Linux route delete command failed: external program exited with error status: 2, -openvpn: Wed Mar 18 22:13:17 2020 ERROR: Linux route delete command failed: external program exited with error status: 2, -openvpn: Wed Mar 18 22:13:17 2020 /sbin/ip addr del dev tun0 local 10.6.11.6 peer 10.6.11.5, -openvpn: Wed Mar 18 22:13:17 2020 Linux ip addr del failed: external program exited with error status: 2, -openvpn: Wed Mar 18 22:13:18 2020 ERROR: Cannot ioctl TUNSETIFF tun: Operation not permitted (errno=1), -openvpn: Wed Mar 18 22:13:18 2020 Exiting due to fatal error, -exit status 1 -``` - -To fix it, you would have to run openvpn with root, by setting the environment variable `OPENVPN_ROOT=yes`. - -

- -
Private Internet Access: Why do I see openvpn warnings at start?

- -You might see some warnings similar to: - -```s -openvpn: Sat Feb 22 15:55:02 2020 WARNING: this configuration may cache passwords in memory -- use the auth-nocache option to prevent this -openvpn: Sat Feb 22 15:55:02 2020 WARNING: 'link-mtu' is used inconsistently, local='link-mtu 1569', remote='link-mtu 1542' -openvpn: Sat Feb 22 15:55:02 2020 WARNING: 'cipher' is used inconsistently, local='cipher AES-256-CBC', remote='cipher BF-CBC' -openvpn: Sat Feb 22 15:55:02 2020 WARNING: 'auth' is used inconsistently, local='auth SHA256', remote='auth SHA1' -openvpn: Sat Feb 22 15:55:02 2020 WARNING: 'keysize' is used inconsistently, local='keysize 256', remote='keysize 128' -openvpn: Sat Feb 22 15:55:02 2020 WARNING: 'comp-lzo' is present in remote config but missing in local config, remote='comp-lzo' -openvpn: Sat Feb 22 15:55:02 2020 [a121ce520d670b71bfd3aa475485539b] Peer Connection Initiated with [AF_INET]xx.xx.xx.xx:1197 -``` - -It is mainly because the option [disable-occ](https://openvpn.net/community-resources/reference-manual-for-openvpn-2-4/) was removed for transparency with you. - -Private Internet Access explains [here why](https://www.privateinternetaccess.com/helpdesk/kb/articles/why-do-i-get-cipher-auth-warnings-when-i-connect) the warnings show up. - -

- -
What files does it download at start before tunneling?

- -At start, the Go entrypoint only downloads, depending on your settings: - -- If `DOT=on`: [DNS over TLS named root](https://github.com/qdm12/files/blob/master/named.root.updated) for Unbound -- If `DOT=on`: [DNS over TLS root key](https://github.com/qdm12/files/blob/master/root.key.updated) for Unbound -- If `BLOCK_MALICIOUS=on`: [Malicious hostnames and IP addresses block lists](https://github.com/qdm12/files) for Unbound -- If `BLOCK_SURVEILLANCE=on`: [Surveillance hostnames and IP addresses block lists](https://github.com/qdm12/files) for Unbound -- If `BLOCK_ADS=on`: [Ads hostnames and IP addresses block lists](https://github.com/qdm12/files) for Unbound - -

- -
How to build Docker images of older or alternate versions

- -First, install [Git](https://git-scm.com/). - -The following will build the Docker image locally and replace the previous one you built or pulled. - -- Build the latest image - - ```sh - docker build -t qmcgaw/private-internet-access https://github.com/qdm12/private-internet-access-docker.git - ``` - -- Find a [commit](https://github.com/qdm12/private-internet-access-docker/commits/master) you want to build for, in example `095623925a9cc0e5cf89d5b9b510714792267d9b`, then: - - ```sh - docker build -t qmcgaw/private-internet-access https://github.com/qdm12/private-internet-access-docker.git#095623925a9cc0e5cf89d5b9b510714792267d9b - ``` - -- Find a [branch](https://github.com/qdm12/private-internet-access-docker/branches) you want to build for, in example `mullvad`, then: - - ```sh - docker build -t qmcgaw/private-internet-access https://github.com/qdm12/private-internet-access-docker.git#mullvad - ``` - -

- -
Mullvad does not work with IPv6?

- -By default, the Mullvad server tunnels both ipv4 and ipv6, hence openvpn will try to create an -ipv6 route. To allow the container to create such route, you have to specify `net.ipv6.conf.all.disable_ipv6=0` -at runtime, using either: - -- For a Docker run command, the flag: `--sysctl net.ipv6.conf.all.disable_ipv6=0` -- In a docker-compose file: - - ```yml - sysctls: - - net.ipv6.conf.all.disable_ipv6=0 - ``` - -

- -
What's all this Go code?

- -The Go code is a big rewrite of the previous shell entrypoint, it allows for: - -- better testing -- better maintainability -- ease of implementing new features -- faster boot -- asynchronous/parallel operations - -It is mostly made of the [internal directory](https://github.com/qdm12/private-internet-access-docker/tree/master/internal) and the entry Go file [cmd/main.go](https://github.com/qdm12/private-internet-access-docker/blob/master/cmd/main.go). - -

- -
How to test DNS over TLS?

- -- You can test DNSSEC using [internet.nl/connection](https://www.internet.nl/connection/) -- Check DNS leak tests with [https://www.dnsleaktest.com](https://www.dnsleaktest.com) -- Some other DNS leaks tests might not work because of [this](https://github.com/qdm12/cloudflare-dns-server#verify-dns-connection) (*TLDR*: Unbound DNS server is a local caching intermediary) - -

- -
How to fix OpenVPN failing to start?

- -You can try: - -- Installing the tun kernel module on your host with `insmod /lib/modules/tun.ko` or `modprobe tun` -- Adding `--device=/dev/net/tun` to your docker run command (equivalent for docker-compose, kubernetes, etc.) - -

- -## Development - -1. Setup your environment - -
Using VSCode and Docker

- - 1. Install [Docker](https://docs.docker.com/install/) - - On Windows, share a drive with Docker Desktop and have the project on that partition - - On OSX, share your project directory with Docker Desktop - 1. With [Visual Studio Code](https://code.visualstudio.com/download), install the [remote containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) - 1. In Visual Studio Code, press on `F1` and select `Remote-Containers: Open Folder in Container...` - 1. Your dev environment is ready to go!... and it's running in a container :+1: - -

- -
Locally

- - Install [Go](https://golang.org/dl/), [Docker](https://www.docker.com/products/docker-desktop) and [Git](https://git-scm.com/downloads); then: - - ```sh - go mod download - go get github.com/golang/mock/gomock - go get github.com/golang/mock/mockgen - ``` - - And finally install [golangci-lint](https://github.com/golangci/golangci-lint#install) - -

- -1. Commands available: - - ```sh - # Build the entrypoint binary - go build cmd/main.go - # Test the entrypoint code - go test ./... - # Lint the code - golangci-lint run - # Build the Docker image - docker build -t qmcgaw/private-internet-access . - ``` - -1. The Go code is in the Go file [cmd/main.go](https://github.com/qdm12/private-internet-access-docker/blob/master/cmd/main.go) and the [internal directory](https://github.com/qdm12/private-internet-access-docker/tree/master/internal), you might want to start reading the main.go file. -1. See [Contributing](.github/CONTRIBUTING.md) for more information on how to contribute to this repository. - -### Contributors - -Thanks for all the contributions, whether small or not so small! - -- [@JeordyR](https://github.com/JeordyR) for testing the Mullvad version and opening a [PR with a few fixes](https://github.com/qdm12/private-internet-access-docker/pull/84/files) 👍 -- [@rorph](https://github.com/rorph) for a [PR to pick a random region for PIA](https://github.com/qdm12/private-internet-access-docker/pull/70) and a [PR to make the container work with kubernetes](https://github.com/qdm12/private-internet-access-docker/pull/69) -- [@JesterEE](https://github.com/JesterEE) for a [PR to fix silly line endings in block lists back then](https://github.com/qdm12/private-internet-access-docker/pull/55) 📎 -- [@elmerfdz](https://github.com/elmerfdz) for a [PR to add timezone information to have correct log timestampts](https://github.com/qdm12/private-internet-access-docker/pull/51) 🕙 -- [@Juggels](https://github.com/Juggels) for a [PR to write the PIA forwarded port to a file](https://github.com/qdm12/private-internet-access-docker/pull/43) -- [@gdlx](https://github.com/gdlx) for a [PR to fix and improve PIA port forwarding script](https://github.com/qdm12/private-internet-access-docker/pull/32) -- [@janaz](https://github.com/janaz) for keeping an eye on [updating things in the Dockerfile](https://github.com/qdm12/private-internet-access-docker/pull/8) - -## TODOs - -
Expand me

- -- Gotify support for notificactions -- Periodic update of malicious block lists with Unbound restart -- Improve healthcheck - - Check IP address belongs to selected region - - Check for DNS provider somehow if this is even possible -- Support for other VPN protocols - - Wireguard (wireguard-go) -- Show new versions/commits available at start -- Colors & emojis - - Setup - - Logging streams -- More unit tests -- Write in Go - - DNS over TLS to replace Unbound - - HTTP proxy to replace tinyproxy - - use [go-Shadowsocks2](https://github.com/shadowsocks/go-shadowsocks2) - - DNS over HTTPS, maybe use [github.com/likexian/doh-go](https://github.com/likexian/doh-go) - - use [iptables-go](https://github.com/coreos/go-iptables) to replace iptables - - wireguard-go - - Openvpn to replace openvpn - -

+- [Setup your environment](https://github.com/qdm12/private-internet-access-docker/blob/master/doc/development.md). +- [Contributing guidelines](https://github.com/qdm12/private-internet-access-docker/blob/master/.github/CONTRIBUTING.md) +- [The list of existing contributors 👍](https://github.com/qdm12/private-internet-access-docker/blob/master/.github/CONTRIBUTING.md#Contributors) +- [Github workflows](https://github.com/qdm12/private-internet-access-docker/actions) to know what's building +- [List of issues and feature requests](https://github.com/qdm12/private-internet-access-docker/issues) ## License diff --git a/doc/development.md b/doc/development.md new file mode 100644 index 00000000..7e6951e2 --- /dev/null +++ b/doc/development.md @@ -0,0 +1,43 @@ +# Development + +## Setup + +### Using VSCode and Docker + +That should be easier and better than a local setup, although it might use more memory if you're not on Linux. + +1. Install [Docker](https://docs.docker.com/install/) + - On Windows, share a drive with Docker Desktop and have the project on that partition + - On OSX, share your project directory with Docker Desktop +1. With [Visual Studio Code](https://code.visualstudio.com/download), install the [remote containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) +1. In Visual Studio Code, press on `F1` and select `Remote-Containers: Open Folder in Container...` +1. Your dev environment is ready to go!... and it's running in a container :+1: + +### Locally + +Install [Go](https://golang.org/dl/), [Docker](https://www.docker.com/products/docker-desktop) and [Git](https://git-scm.com/downloads); then: + +```sh +go mod download +``` + +And finally install [golangci-lint](https://github.com/golangci/golangci-lint#install) + +## Commands available + +```sh +# Build the entrypoint binary +go build cmd/main.go +# Test the entrypoint code +go test ./... +# Lint the code +golangci-lint run +# Build the Docker image +docker build -t qmcgaw/private-internet-access . +``` + +## Guidelines + +The Go code is in the Go file [cmd/main.go](../cmd/main.go) and the [internal directory](../internal), you might want to start reading the main.go file. + +See the [Contributing document](.github/CONTRIBUTING.md) for more information on how to contribute to this repository. diff --git a/doc/faq.md b/doc/faq.md new file mode 100644 index 00000000..f2cbf58c --- /dev/null +++ b/doc/faq.md @@ -0,0 +1,128 @@ +# FAQ + +## Table of content + +- [Openvpn disconnects because of a ping timeout](#Openvpn-disconnects-because-of-a-ping-timeout) +- [Private Internet Access: Why do I see openvpn warnings at start](#Private-Internet-Access:-Why-do-I-see-openvpn-warnings-at-start) +- [What files does it download at start before tunneling](What-files-does-it-download-at-start-before-tunneling) +- [How to build Docker images of older or alternate versions](How-to-build-Docker-images-of-older-or-alternate-versions) +- [Mullvad does not work with IPv6](#Mullvad-does-not-work-with-IPv6) +- [What's all this Go code](#What-is-all-this-Go-code) +- [How to test DNS over TLS](#How-to-test-DNS-over-TLS) +- [How to fix OpenVPN failing to start](#How-to-fix-OpenVPN-failing-to-start) + +## Openvpn disconnects because of a ping timeout + +It happens especially on some PIA servers where they change their configuration or the server goes offline. + +You will obtain an error similar to: + +```s +openvpn: Wed Mar 18 22:13:00 2020 [3a51ae90324bcb0719cb399b650c64d4] Inactivity timeout (--ping-restart), restarting, +openvpn: Wed Mar 18 22:13:00 2020 SIGUSR1[soft,ping-restart] received, process restarting, +... +openvpn: Wed Mar 18 22:13:17 2020 Preserving previous TUN/TAP instance: tun0, +openvpn: Wed Mar 18 22:13:17 2020 NOTE: Pulled options changed on restart, will need to close and reopen TUN/TAP device., +openvpn: Wed Mar 18 22:13:17 2020 ERROR: Linux route delete command failed: external program exited with error status: 2, +openvpn: Wed Mar 18 22:13:17 2020 ERROR: Linux route delete command failed: external program exited with error status: 2, +openvpn: Wed Mar 18 22:13:17 2020 ERROR: Linux route delete command failed: external program exited with error status: 2, +openvpn: Wed Mar 18 22:13:17 2020 ERROR: Linux route delete command failed: external program exited with error status: 2, +openvpn: Wed Mar 18 22:13:17 2020 /sbin/ip addr del dev tun0 local 10.6.11.6 peer 10.6.11.5, +openvpn: Wed Mar 18 22:13:17 2020 Linux ip addr del failed: external program exited with error status: 2, +openvpn: Wed Mar 18 22:13:18 2020 ERROR: Cannot ioctl TUNSETIFF tun: Operation not permitted (errno=1), +openvpn: Wed Mar 18 22:13:18 2020 Exiting due to fatal error, +exit status 1 +``` + +To fix it, you would have to run openvpn with root, by setting the environment variable `OPENVPN_ROOT=yes`. + +## Private Internet Access: Why do I see openvpn warnings at start + +You might see some warnings similar to: + +```s +openvpn: Sat Feb 22 15:55:02 2020 WARNING: this configuration may cache passwords in memory -- use the auth-nocache option to prevent this +openvpn: Sat Feb 22 15:55:02 2020 WARNING: 'link-mtu' is used inconsistently, local='link-mtu 1569', remote='link-mtu 1542' +openvpn: Sat Feb 22 15:55:02 2020 WARNING: 'cipher' is used inconsistently, local='cipher AES-256-CBC', remote='cipher BF-CBC' +openvpn: Sat Feb 22 15:55:02 2020 WARNING: 'auth' is used inconsistently, local='auth SHA256', remote='auth SHA1' +openvpn: Sat Feb 22 15:55:02 2020 WARNING: 'keysize' is used inconsistently, local='keysize 256', remote='keysize 128' +openvpn: Sat Feb 22 15:55:02 2020 WARNING: 'comp-lzo' is present in remote config but missing in local config, remote='comp-lzo' +openvpn: Sat Feb 22 15:55:02 2020 [a121ce520d670b71bfd3aa475485539b] Peer Connection Initiated with [AF_INET]xx.xx.xx.xx:1197 +``` + +It is mainly because the option [disable-occ](https://openvpn.net/community-resources/reference-manual-for-openvpn-2-4/) was removed for transparency with you. + +Private Internet Access explains [here why](https://www.privateinternetaccess.com/helpdesk/kb/articles/why-do-i-get-cipher-auth-warnings-when-i-connect) the warnings show up. + +## What files does it download at start before tunneling + +At start, the Go entrypoint only downloads, depending on your settings: + +- If `DOT=on`: [DNS over TLS named root](https://github.com/qdm12/files/blob/master/named.root.updated) for Unbound +- If `DOT=on`: [DNS over TLS root key](https://github.com/qdm12/files/blob/master/root.key.updated) for Unbound +- If `BLOCK_MALICIOUS=on`: [Malicious hostnames and IP addresses block lists](https://github.com/qdm12/files) for Unbound +- If `BLOCK_SURVEILLANCE=on`: [Surveillance hostnames and IP addresses block lists](https://github.com/qdm12/files) for Unbound +- If `BLOCK_ADS=on`: [Ads hostnames and IP addresses block lists](https://github.com/qdm12/files) for Unbound + +## How to build Docker images of older or alternate versions + +First, install [Git](https://git-scm.com/). + +The following will build the Docker image locally and replace the previous one you built or pulled. + +- Build the latest image + + ```sh + docker build -t qmcgaw/private-internet-access https://github.com/qdm12/private-internet-access-docker.git + ``` + +- Or, find a [commit](https://github.com/qdm12/private-internet-access-docker/commits/master) you want to build for, in example `095623925a9cc0e5cf89d5b9b510714792267d9b`, then: + + ```sh + docker build -t qmcgaw/private-internet-access https://github.com/qdm12/private-internet-access-docker.git#095623925a9cc0e5cf89d5b9b510714792267d9b + ``` + +- Or, find a [branch](https://github.com/qdm12/private-internet-access-docker/branches) you want to build for, in example `mullvad`, then: + + ```sh + docker build -t qmcgaw/private-internet-access https://github.com/qdm12/private-internet-access-docker.git#mullvad + ``` + +## Mullvad does not work with IPv6 + +By default, the Mullvad server tunnels both ipv4 and ipv6, hence openvpn will try to create an +ipv6 route. To allow the container to create such route, you have to specify `net.ipv6.conf.all.disable_ipv6=0` +at runtime, using either: + +- For a Docker run command, the flag: `--sysctl net.ipv6.conf.all.disable_ipv6=0` +- In a docker-compose file: + + ```yml + sysctls: + - net.ipv6.conf.all.disable_ipv6=0 + ``` + +## What is all this Go code + +The Go code is a big rewrite of the previous shell entrypoint, it allows for: + +- better testing +- better maintainability +- ease of implementing new features +- faster boot +- asynchronous/parallel operations + +It is mostly made of the [internal directory](../internal) and the entry Go file [cmd/main.go](../cmd/main.go). + +## How to test DNS over TLS + +- You can test DNSSEC using [internet.nl/connection](https://www.internet.nl/connection/) +- Check DNS leak tests with [https://www.dnsleaktest.com](https://www.dnsleaktest.com) +- Some other DNS leaks tests might not work because of [this](https://github.com/qdm12/cloudflare-dns-server#verify-dns-connection) (*TLDR*: Unbound DNS server is a local caching intermediary) + +## How to fix OpenVPN failing to start + +You can try: + +- Installing the tun kernel module on your host with `insmod /lib/modules/tun.ko` or `modprobe tun` +- Adding `--device=/dev/net/tun` to your docker run command (equivalent for docker-compose, kubernetes, etc.) diff --git a/doc/firewall.md b/doc/firewall.md new file mode 100644 index 00000000..d1f387d2 --- /dev/null +++ b/doc/firewall.md @@ -0,0 +1,39 @@ +# Firewall + +If you have a strict firewall setup (host level or router level), you might want to setup the following. + +## Start only + +The following is required when the container starts only: + +- Allow outbound TCP 443 to github.com +- If `DOT=on`, allow outbound TCP 853 to allow Unbound to resolve github.com and the PIA subdomain name if you use PIA. +- If `DOT=off` and `VPNSP=pia`, allow outbound UDP 53 to your DNS provider to resolve the PIA subdomain name. + +## VPN connections + +You need the following to allow communicating with the VPN servers + +### Private Internet Access + +- If `PIA_ENCRYPTION=strong` and `PROTOCOL=udp`: allow outbound UDP 1197 to the corresponding VPN server IPs +- If `PIA_ENCRYPTION=normal` and `PROTOCOL=udp`: allow outbound UDP 1198 to the corresponding VPN server IPs +- If `PIA_ENCRYPTION=strong` and `PROTOCOL=tcp`: allow outbound TCP 501 to the corresponding VPN server IPs +- If `PIA_ENCRYPTION=normal` and `PROTOCOL=tcp`: allow outbound TCP 502 to the corresponding VPN server IPs + +### Mullvad + +- If `PORT=`, please refer to the mapping of Mullvad servers in [these source code lines](../internal/constants/mullvad.go#L64-L667) to find the corresponding UDP port number and IP address(es) of your choice +- If `PORT=53`, allow outbound UDP 53 to the corresponding VPN server IPs, which you can fine in [the mapping of Mullvad servers](../internal/constants/mullvad.go#L64-L667) +- If `PORT=80`, allow outbound TCP 80 to the corresponding VPN server IPs, which you can fine in [the mapping of Mullvad servers](../internal/constants/mullvad.go#L64-L667) +- If `PORT=443`, allow outbound TCP 443 to the corresponding VPN server IPs, which you can fine in [the mapping of Mullvad servers](../internal/constants/mullvad.go#L64-L667) + +### Windscribe + +- If `PROTOCOL=udp`: allow outbound UDP 443 to the corresponding VPN server IPs +- If `PROTOCOL=tcp`: allow outbound TCP 1194 to the corresponding VPN server IPs + +## Inbound connections + +- If `SHADOWSOCKS=on`, allow inbound TCP 8388 and UDP 8388 from your LAN +- If `TINYPROXY=on`, allow inbound TCP 8888 from your LAN