vanja/gluetun
1
0
Fork 0
mirror of https://github.com/qdm12/gluetun.git synced 2026-05-06 20:10:11 +02:00
Code Issues Packages Projects Releases Wiki Activity

Rework Wiki documents

Quentin McGaw
2020-12-30 22:33:13 -05:00
parent bd4d9864b6
commit 6054194858
23 changed files with 144 additions and 131 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Contributing/Developement setup.md
+4 -10
@@ -1,21 +1,13 @@
# Setup
This document describes how to setup your development environment to contribute to this program.
## 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:
The repository .devcontainer [readme document](https://github.com/qdm12/gluetun/tree/master/.devcontainer#development-container) explains its setup.
## Local installation
1. Install [Docker](https://www.docker.com/products/docker-desktop)
1. Install [Go](https://golang.org/dl/)
1. Install [Git](https://git-scm.com/downloads)
1. Download the dependencies
@@ -25,7 +17,9 @@ That should be easier and better than a local setup, although it might use more
```
1. Install [golangci-lint](https://github.com/golangci/golangci-lint#install)
1. You might want to use an IDE such as VSCode with the [Go extension](https://marketplace.visualstudio.com/items?itemName=golang.go)
1. You might want to install [Docker](https://www.docker.com/products/docker-desktop) to build and run the image.
## Next steps
Go to the [commands document](Developement-commands)
Go to the [development commands document](Developement-commands)
Contributing/Development commands.md
+3 -5
@@ -1,11 +1,9 @@
# Commands
Once your [development setup](setup.md) is complete, you have the following commands available.
Once your [development setup](Development-setup) is complete, you have the following commands available.
- Test the code: `go test ./...`
- Lint the code `golangci-lint run`
- Build the Docker image (tests and lint included): `docker build -t qmcgaw/private-internet-access .`
- Run the Docker container: `docker run -it --rm --cap-add=NET_ADMIN -e USER=test -e PASSWORD=test qmcgaw/private-internet-access`
- Build the Docker image (tests and lint included): `docker build -t qmcgaw/gluetun .`
- Run the Docker container: `docker run -it --rm --cap-add=NET_ADMIN -e OPENVPN_USER=test -e OPENVPN_PASSWORD=test qmcgaw/gluetun`
Other useful commands:
Contributing/Development guidelines.md
+2 -4
@@ -1,7 +1,5 @@
# Guidelines
The Go code is in the Go file [cmd/main.go](https://github.com/qdm12/gluetun/blob/master/cmd/main.go) and the [internal directory](https://github.com/qdm12/gluetun/tree/master/internal), you might want to start reading the main.go file.
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.
See the [Contributing document](https://github.com/qdm12/private-internet-access-docker/blob/master/.github/CONTRIBUTING.md) for more information on how to contribute to this repository.
See the [Contributing document](https://github.com/qdm12/gluetun/blob/master/.github/CONTRIBUTING.md) for more information on how to contribute to this repository.
As always, feel free to reach out to me if you have any question.
FAQ/Docker image tags.md
+22 -19
@@ -1,28 +1,31 @@
# Docker image
![Visitors count](https://visitor-badge.laobi.icu/badge?page_id=gluetun.faq.dockerimage)
If you use the default `qmcgaw/private-internet-access` image, you are technically using the Docker image with the `:latest` tag.
If you use the default `qmcgaw/gluetun` image, you are technically using the Docker image with the `:latest` tag.
If it happens to be **broken**, this page is for you.
## Release tag
## Release tags
[Multiple releases](https://github.com/qdm12/private-internet-access-docker/releases) are made through time when the image is considered stable.
ℹ️ [Live list of image tags **after v3.9.0**](https://hub.docker.com/r/qmcgaw/gluetun/tags?page=1&ordering=last_updated)
ℹ️ [List of image tags](https://hub.docker.com/r/qmcgaw/private-internet-access/tags?page=1&ordering=last_updated)
| Image | Github release | CPU architectures |
| --- | --- | --- |
| `qmcgaw/gluetun:v3.10.0` | [v3.10.0](releases/tag/v3.10.0) | 386, amd64, armv6, armv7, arm64 |
| `qmcgaw/private-internet-access:v3.9.0` | [v3.9.0](https://github.com/qdm12/gluetun/releases/tag/v3.9.0) | 386, amd64, armv6, armv7, arm64 |
| `qmcgaw/private-internet-access:v3.8.1` | [v3.9.0](https://github.com/qdm12/gluetun/releases/tag/v3.8.1) | 386, amd64, armv6, armv7, arm64 |
| `qmcgaw/private-internet-access:v3.7.0` | [v3.7.0](https://github.com/qdm12/gluetun/releases/tag/v3.7.0) | 386, amd64, armv6, armv7, arm64 |
| `qmcgaw/private-internet-access:v3.6.0` | [v3.6.0](https://github.com/qdm12/gluetun/releases/tag/v3.6.0) | 386, amd64, armv6, armv7, arm64 |
| `qmcgaw/private-internet-access:v3.5.1` | [v3.5.1](https://github.com/qdm12/gluetun/releases/tag/v3.5.1) | 386, amd64, armv6, armv7, arm64 |
| `qmcgaw/private-internet-access:v3.4.0` | [v3.4.0](https://github.com/qdm12/gluetun/releases/tag/v3.4.0) | 386, amd64, armv6, armv7, arm64 |
| `qmcgaw/private-internet-access:v3.3.0` | [v3.3.0](https://github.com/qdm12/gluetun/releases/tag/v3.3.0) | 386, amd64, armv6, armv7, arm64 |
| `qmcgaw/private-internet-access:v3.2.0` | [v3.2.0](https://github.com/qdm12/gluetun/releases/tag/v3.2.0) | 386, amd64, armv6, armv7, arm64 |
| `qmcgaw/private-internet-access:v3.1.0` | [v3.1.0](https://github.com/qdm12/gluetun/releases/tag/v3.1.0) | 386, amd64, armv6, armv7, arm64 |
| `qmcgaw/private-internet-access:v3.0.1` | [v3.0.1](https://github.com/qdm12/gluetun/releases/tag/v3.0.1) | 386, amd64, armv6, armv7, arm64 |
| `qmcgaw/private-internet-access:v2` | [v2.0.0](https://github.com/qdm12/gluetun/releases/tag/v2.0.0) | 386, amd64, armv6, armv7, arm64, ppc64le, s390x |
| `qmcgaw/private-internet-access:v1` | [v1](https://github.com/qdm12/gluetun/releases/tag/v1.0) | 386, amd64, armv6, armv7, arm64, ppc64le, s390x |
| `qmcgaw/private-internet-access:old` | *Too old to know* | amd64 |
Each time a Github release is made, an associated Docker image tag is made, for example a `v3.1.0` release produces the image `qmcgaw/private-internet-access:v3.1.0`.
[Multiple releases](https://github.com/qdm12/gluetun/releases) are made through time when the image is considered stable.
You can thus use one of these image tags if `:latest` doesn't work for you. Also, don't forget to create an issue for it 😉
Each time a Github release is made, an associated Docker image tag is made, for example a `v3.1.0` release produces the image `qmcgaw/gluetun:v3.1.0`.
## Build the image from a Git commit
1. Install [Git](https://git-scm.com/), test it's here with `git version`
1. Find a [commit](https://github.com/qdm12/private-internet-access-docker/commits/master) you want to build for, in example `095623925a9cc0e5cf89d5b9b510714792267d9b`
1. Build the image
```sh
docker build -t qmcgaw/private-internet-access https://github.com/qdm12/private-internet-access-docker.git#095623925a9cc0e5cf89d5b9b510714792267d9b
```
1. You can now use `qmcgaw/private-internet-access` which is the image you just built.
You can thus use one of these image tags if `:latest` doesn't work for you. Also, don't forget to [create an issue](https://github.com/qdm12/gluetun/issues/new/choose) for it 😉
FAQ/Mullvad IPv6.md → FAQ/Mullvad.md
+2 -2
@@ -1,7 +1,7 @@
# Mullvad
![Visitors count](https://visitor-badge.laobi.icu/badge?page_id=gluetun.faq.mullvad)
## IPv6
If you want to tunnel IPv6 with Mullvad, follow the following.
1. Ensure your Kernel has IPv6
FAQ/Openvpn killed.md
-15
@@ -1,15 +0,0 @@
# OpenVPN killed
It may happen, quite rarely though, that Openvpn gets killed in a loop by the host system.
If you get regularly in your logs
```s
openvpn: Sun May 10 19:23:37 2020 Initialization Sequence Completed
openvpn: Sun May 10 19:23:45 2020 event_wait : Interrupted system call (code=4)
openvpn: Sun May 10 19:23:45 2020 ERROR: Linux route delete command failed: external program exited with error status: 2
openvpn: signal: killed
```
It might be another app you have interfering with the `/dev/net/tun` device and thus killing openvpn.
For QNAP users, it may be the **QCenter**. More information on [this issue](https://github.com/qdm12/private-internet-access-docker/issues/157) and many thanks for @AlexAlbright for finding the root cause through trial and error 🎈
FAQ/Openvpn ping timeout.md
-26
@@ -1,26 +0,0 @@
# Ping timeout
If your Openvpn drops the connection because of a ping timeout, then this page is for you.
It happens, especially on some Private Internet Access servers, that the server side configuration changes 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`.
FAQ/Openvpn warnings.md
-17
@@ -1,17 +0,0 @@
# OpenVPN warnings
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.
FAQ/Openvpn.md
+60
@@ -0,0 +1,60 @@
## Inconsistence warnings
You might see some warnings for Private Internet Access and others, similar to:
```s
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'
```
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.
## Exiting on ping timeout
If your Openvpn drops the connection because of a ping timeout, the container will exit
and connected containers will lose their connection to it, even if it restarts.
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 allow openvpn to restart itself, run openvpn with root by setting the environment variable `OPENVPN_ROOT=yes`.
## Interrupted system call
It may happen, quite rarely though, that Openvpn is killed in a loop by the host system.
Even if it runs in a container, because it shares the tunnel device with the host, the host can make it fail.
If you get regularly in your logs
```s
openvpn: Sun May 10 19:23:37 2020 Initialization Sequence Completed
openvpn: Sun May 10 19:23:45 2020 event_wait : Interrupted system call (code=4)
openvpn: Sun May 10 19:23:45 2020 ERROR: Linux route delete command failed: external program exited with error status: 2
openvpn: signal: killed
```
It might be another app you have interfering with the `/dev/net/tun` device and thus killing openvpn.
For QNAP users, it may be the **QCenter**. More information on [this issue](https://github.com/qdm12/gluetun/issues/157) and many thanks for @AlexAlbright for finding the root cause through trial and error 🎈
FAQ/Portainer iptables error.md → FAQ/Portainer.md
+2 -2
@@ -1,4 +1,4 @@
# Portainer
## Iptables permission
If you use Portainer to run the container and get the error:
@@ -7,4 +7,4 @@ If you use Portainer to run the container and get the error:
Perhaps iptables or your kernel needs to be upgraded.: exit status 3```
```
This might be because portainer does not set the `--cap_add=NET_ADMIN` successfully. You might need to run the container without Portainer in this case. More information on [this issue](https://github.com/qdm12/private-internet-access-docker/issues/139).
This might be because portainer does not set the `--cap_add=NET_ADMIN` successfully. You might need to run the container without Portainer in this case. More information on [this issue](https://github.com/qdm12/gluetun/issues/139).
HTTP Control server/Control DNS over TLS.md
-2
@@ -1,5 +1,3 @@
# DNS over TLS
The HTTP control server allows to modify the state of Unbound, which is the subprocess responsible for DNS over TLS.
## Restart
HTTP Control server/Control Openvpn.md
-2
@@ -1,5 +1,3 @@
# OpenVPN
The HTTP control server allows to modify the state of OpenVPN, which is the subprocess responsible for your VPN connection.
## Restart
HTTP Control server/HTTP Control server.md
-2
@@ -1,5 +1,3 @@
# HTTP Control server
The HTTP control server allows to obtain and modify the state of the container without restarting it.
- [Setup](Setup-the-HTTP-control-server)
HTTP Control server/Setup the HTTP control server.md
+1 -3
@@ -1,5 +1,3 @@
# Setup
A built-in HTTP server listens on port `8000` to modify the state of the container.
To access it, simply map the ports for the container `-p 8000:8000/tcp` and set up `EXTRA_SUBNETS` accordingly.
To access it, simply publish this port for the container, for example: `-p 8000:8000/tcp`.
Home.md
+5 -3
@@ -1,7 +1,9 @@
# Wiki
👋👋👋
Welcome to the Gluetun Wiki!
🎊 Welcome to the Gluetun Wiki! 🎊
You can navigate pages on the right side bar.
👋👋👋
You can navigate pages on the right side bar 👉
There are pages about the container setup, advanced configuration, servers updating, FAQ and contributing documentation.
More-information.md
+38
@@ -0,0 +1,38 @@
## Table of content
1. [What is all this Go code](#What-is-all-this-Go-code)
1. [What files does it download after tunneling](#What-files-does-it-download-after-tunneling)
1. [Healthcheck](#Healthcheck)
## What is all this Go code
The Go code was essentially a big rewrite of the previous shell entrypoint.
It now acts a supervisor program, and has a built-in HTTP control server.
It allows for:
- better testing
- better maintainability
- ease of implementing new features
- faster start time
- asynchronous/parallel operations
- Restarting openvpn/unbound when needed without quitting the container
It is mostly made of the [internal directory](../internal) and the entry Go file [cmd/main.go](../cmd/main.go).
## What files does it download after tunneling
If `DOT=off`, Unbound won't run and therefore no file will be downloaded by the program at all.
If `DOT=on`, after tunneling, it downloads at start (and periodically if `DNS_UPDATE_PERIOD` is not `0`):
- [DNS named root](https://github.com/qdm12/files/blob/master/named.root.updated) and the [DNS 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
## Healthcheck
For Docker, docker-compose and Docker Swarm, there is a built-in [Docker healthcheck](https://docs.docker.com/engine/reference/builder/#healthcheck) running periodically which verifies DNS resolution of github.com is working, to ensure DNS over TLS **and** the Openvpn connection are both working.
If this is bothering you, you [can disable it](Advanced-setup#Disable-the-healthcheck).
Servers/Surfshark Servers.md
-2
@@ -1,5 +1,3 @@
# Surfshark
## Regions available
- Albania
Servers/Updating Servers.md
+2 -4
@@ -1,5 +1,3 @@
# Updating
## Pre-requisites
- Use Docker images `latest` or superior to release tag `v3.2.0`
@@ -22,13 +20,13 @@ The best way is to set the environment variable `UPDATE_PERIOD=24h` for example,
You can run the docker container in CLI operation, check the possible options with:
```sh
docker run -it --rm qmcgaw/private-internet-access update -help
docker run -it --rm qmcgaw/gluetun update -help
```
To update your servers.json file with, for example `mullvad`, use:
```sh
docker run -it --rm -v /yourpath:/gluetun qmcgaw/private-internet-access update -file -mullvad
docker run -it --rm -v /yourpath:/gluetun qmcgaw/gluetun update -file -mullvad
```
Note that this operation is very quick 🚀 for some providers (`pia`, `mullvad`, `nordvpn`, ...) and very slow 🐢 for other providers (`cyberghost`, `windscribe`, ...).
Setup/Advanced setup.md
-2
@@ -1,5 +1,3 @@
# Advanced setup
## Custom iptables rules
If you need to specify additional iptables rules to be run after the built-in iptables rules, you can use the file at `/iptables/post-rules.txt` with one iptables command per line and these will automatically be run on container start.
Setup/External firewall.md
-2
@@ -1,5 +1,3 @@
# External firewall
If you have a strict firewall setup (host level or router level), you will need to let some ports through for this container to work.
## VPN connections
Setup/Synology setup.md
-2
@@ -1,5 +1,3 @@
# Synology
On some Synology devices, it is required to re-install the `tun` kernel module on your host **at every boot**.
To do so, open a terminal and enter:
Setup/Testing the setup.md
-2
@@ -1,5 +1,3 @@
# Testing
Once your container is up and running, you may want to test your connection is correct and secured.
## Check your IP address
_Sidebar.md
+3 -5
@@ -8,11 +8,9 @@
- [External firewall](External-firewall)
- FAQ
- [Docker image tags](Docker-image-tags)
- [Openvpn warnings](Openvpn-warnings)
- [Openvpn ping timeout](Openvpn-ping-timeout)
- [Openvpn killed](Openvpn-killed)
- [Portainer iptables error](Portainer-iptables-error)
- [Mullvad IPv6](Mullvad-IPv6)
- [Openvpn](Openvpn)
- [Portainer](Portainer)
- [Mullvad](Mullvad)
- [HTTP Control server](HTTP-Control-server)
- [Control Openvpn](Control-Openvpn)
- [Control DNS over TLS](Control-DNS-over-TLS)