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
This commit is contained in:
Quentin McGaw
43
doc/development.md
Normal file
43
doc/development.md
Normal file
@@ -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.
|
||||
128
doc/faq.md
Normal file
128
doc/faq.md
Normal file
@@ -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.)
|
||||
39
doc/firewall.md
Normal file
39
doc/firewall.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user