admin/gluetun
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update readme for new wiki

Browse Source
This commit is contained in:
Quentin McGaw
2020-05-17 17:54:37 -04:00
parent 40a72b6189
commit 886d4ad1a9
5 changed files with 7 additions and 208 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
README.md
View File

@@ -2,7 +2,7 @@
*Lightweight swiss-knife-like VPN client to tunnel to Private Internet Access, Mullvad and Windscribe VPN servers, using Go, OpenVPN, iptables, DNS over TLS, ShadowSocks and Tinyproxy* *Lightweight swiss-knife-like VPN client to tunnel to Private Internet Access, Mullvad and Windscribe VPN servers, using Go, OpenVPN, iptables, DNS over TLS, ShadowSocks and Tinyproxy*
**ANNOUNCEMENT**: *Auto-update of Unbound block lists and cryptographic files, see `DNS_UPDATE_PERIOD`* **ANNOUNCEMENT**: *New wiki available [here](https://github.com/qdm12/private-internet-access-docker/wiki)*
<img height="250" src="https://raw.githubusercontent.com/qdm12/private-internet-access-docker/master/title.svg?sanitize=true"> <img height="250" src="https://raw.githubusercontent.com/qdm12/private-internet-access-docker/master/title.svg?sanitize=true">
@@ -113,10 +113,7 @@
**If you encounter an issue with the tun device not being available, see [the FAQ](https://github.com/qdm12/private-internet-access-docker/blob/master/doc/faq.md#how-to-fix-openvpn-failing-to-start)** **If you encounter an issue with the tun device not being available, see [the FAQ](https://github.com/qdm12/private-internet-access-docker/blob/master/doc/faq.md#how-to-fix-openvpn-failing-to-start)**
1. You can update the image with `docker pull qmcgaw/private-internet-access:latest`. There are also docker tags for older versions available: 1. You can update the image with `docker pull qmcgaw/private-internet-access:latest`. See the [wiki](https://github.com/qdm12/private-internet-access-docker/wiki/Common-issues#use-a-release-tag) for more information on other tags available.
- `qmcgaw/private-internet-access:v2` linked to the [v2 release](https://github.com/qdm12/private-internet-access-docker/releases/tag/v2.0) (Golang based, only PIA)
- `qmcgaw/private-internet-access:v1` linked to the [v1 release](https://github.com/qdm12/private-internet-access-docker/releases/tag/v1.0) (shell scripting based, no support, only PIA)
- `qmcgaw/private-internet-access:old` tag, which is the latest shell scripting version (shell scripting based, no support, only PIA)
## Testing ## Testing
@@ -126,6 +123,8 @@ Check the PIA IP address matches your expectations
docker run --rm --network=container:pia alpine:3.11 wget -qO- https://ipinfo.io docker run --rm --network=container:pia alpine:3.11 wget -qO- https://ipinfo.io
``` ```
Want more testing? ▶ [see the Wiki](https://github.com/qdm12/private-internet-access-docker/wiki/Testing)
## Environment variables ## Environment variables
**Note**: `VPNSP` means VPN service provider **Note**: `VPNSP` means VPN service provider
@@ -281,14 +280,9 @@ A built-in HTTP server listens on port `8000` to modify the state of the contain
- `http://<your-docker-host-ip>:8000/openvpn/actions/restart` restarts the openvpn process - `http://<your-docker-host-ip>:8000/openvpn/actions/restart` restarts the openvpn process
- `http://<your-docker-host-ip>:8000/unbound/actions/restart` re-downloads the DNS files (crypto and block lists) and restarts the unbound process - `http://<your-docker-host-ip>:8000/unbound/actions/restart` re-downloads the DNS files (crypto and block lists) and restarts the unbound process
## FAQ
Please refer to [the FAQ table of content](https://github.com/qdm12/private-internet-access-docker/blob/master/doc/faq.md#Table-of-content)
## Development and contributing ## Development and contributing
- [Setup your environment](https://github.com/qdm12/private-internet-access-docker/blob/master/doc/development.md). - Contribute with code: see [the Wiki](https://github.com/qdm12/private-internet-access-docker/wiki/Contributing).
- [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) - [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 - [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) - [List of issues and feature requests](https://github.com/qdm12/private-internet-access-docker/issues)

43
doc/development.md
View File

@@ -1,43 +0,0 @@
# 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.

120
doc/faq.md
View File

@@ -1,120 +0,0 @@
# 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 after tunneling](#What-files-does-it-download-after-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)
## 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 after tunneling
At start, after tunneling, 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)

32
doc/firewall.md
View File

@@ -1,32 +0,0 @@
# Firewall
If you have a strict firewall setup (host level or router level), you might want to setup the following.
## 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
- If you want access to the built-in HTTP control server, allow inbound TCP 8000 from your LAN

4
internal/constants/splash.go
View File

@@ -2,9 +2,9 @@ package constants
const ( const (
// Announcement is a message announcement // Announcement is a message announcement
Announcement = "Auto update of DNS over TLS block lists and crypto files" Announcement = "New Wiki available at https://github.com/qdm12/private-internet-access-docker/wiki"
// AnnouncementExpiration is the expiration date of the announcement in format yyyy-mm-dd // AnnouncementExpiration is the expiration date of the announcement in format yyyy-mm-dd
AnnouncementExpiration = "2020-05-28" AnnouncementExpiration = "2020-06-10"
) )
const ( const (