mirror of
https://github.com/qdm12/gluetun.git
synced 2026-08-14 08:13:02 +02:00
Update OpenVPN file document
Quentin McGaw (desktop)
+56
-43
@@ -4,70 +4,83 @@ You can use an Openvpn configuration file instead of using the built in provider
|
||||
|
||||
## Warnings
|
||||
|
||||
- The [setup](#Setup) is a bit more complicated
|
||||
- There is some [implicit behavior](#Implicit-behavior) that you should be aware of.
|
||||
- If you encounter any issue, please first [open a discussion](https://github.com/qdm12/gluetun/discussions/new) and then, if it's a valid issue, [open an issue](https://github.com/qdm12/gluetun/issues/new/choose).
|
||||
- My support will be limited from my part as I can't help everyone with VPN providers or private VPN servers I am not familiar with.
|
||||
- If you want a smooth experience, [create an issue to support a new provider](https://github.com/qdm12/gluetun/issues/new?assignees=&labels=%3Abulb%3A+New+provider&template=provider.md&title=VPN+provider+support%3A+NAME+OF+THE+PROVIDER), it usually takes 1 to 2 weeks to implement it.
|
||||
- If you want a smooth experience, [create an issue to support a new provider](https://github.com/qdm12/gluetun/issues/new?assignees=&labels=%3Abulb%3A+New+provider&template=provider.md&title=VPN+provider+support%3A+NAME+OF+THE+PROVIDER), it usually takes 2 to 4 weeks to implement it.
|
||||
|
||||
## Setup
|
||||
|
||||
In the following we assume your custom openvpn configuration file is named `custom.conf`.
|
||||
|
||||
1. You need to inline other files into `custom.conf`. For example if you have a `ca.crt` file, you have to inline it as:
|
||||
|
||||
```conf
|
||||
<ca>
|
||||
-----BEGIN CERTIFICATE-----
|
||||
MIIGIzCCBAu...
|
||||
...
|
||||
...mJ7nXe5
|
||||
-----END CERTIFICATE-----
|
||||
</ca>
|
||||
```
|
||||
|
||||
💡 You can ignore `update-resolv-conf` files as these are ignored in the program.
|
||||
|
||||
Feel free to [open a discussion if you need help doing so](https://github.com/qdm12/gluetun/discussions/new).
|
||||
|
||||
1. Replace the VPN server hostname by one of its IP addresses. In `custom.conf`, find the line starting with `remote`. The second field is the VPN server hostname. If it is not an IP address, you need to DNS resolve it, for example with `nslookup domain.com` and replace the hostname field with one of its corresponding IP addresses. This is the case as gluetun's firewall is designed not to leak anything including an initial DNS resolution when starting.
|
||||
1. Bind mount your `custom.conf` file to (for example) `/gluetun/custom.conf`
|
||||
1. Set the environment variable `OPENVPN_CUSTOM_CONFIG=/gluetun/custom.conf`
|
||||
1. Bind mount your `custom.conf` file to `/gluetun/custom.conf`. If you have other files such as `ca.crt` or `up.sh`, bind mount them to `/gluetun/` as well.
|
||||
1. If you have other files referenced in your `custom.conf` such as `ca ca.crt` or `up up.sh`, change the paths to be absolute such as `ca /gluetun/ca.crt` and `up /gluetun/up.sh`. This is because your configuration file `custom.conf` is read, parsed, modified and written somewhere else at runtime.
|
||||
1. Set the environment variables:
|
||||
- `VPNSP=custom`
|
||||
- `OPENVPN_CUSTOM_CONFIG=/gluetun/custom.conf`
|
||||
1. The environment variables `OPENVPN_USER` and `OPENVPN_PASSWORD` are not enforced but should be set if you use authentication.
|
||||
1. Relative file paths specified in your openvpn configuration file **will not work** as the file is copied and transformed at runtime.
|
||||
1. Run the container
|
||||
1. Run the container for example with:
|
||||
|
||||
```sh
|
||||
docker run -it --rm --cap-add=NET_ADMIN -e VPNSP=custom -e OPENVPN_CUSTOM_CONFIG=/gluetun/custom.conf -v /yourpath/custom.conf:/gluetun.custom.conf:ro -e OPENVPN_USER="youruser" -e OPENVPN_PASSWORD="yourpassword" qmcgaw/gluetun
|
||||
```
|
||||
|
||||
## Implicit behavior
|
||||
|
||||
Although you bind mount an Openvpn configuration file, it is read and its final modified version is written to /tmp/target.ovpn. The following are modified
|
||||
### Relative file paths
|
||||
|
||||
- DNS related instructions such as `up update-resolv-conf` and `down update-resolv-conf` are removed as the container uses DNS over TLS with Unbound
|
||||
- If you have multiple `remote` instructions, only the first one is taken into account.
|
||||
- The following values are added:
|
||||
Files referenced in your OpenVPN configuration file as relative file paths will not work.
|
||||
This is because your configuration file is read, parsed, modified and rewritten to `/etc/openvpn/target.ovpn` (subject to change). You could however adapt these file paths to match that directory, or use absolute paths.
|
||||
|
||||
```conf
|
||||
mute-replay-warnings
|
||||
auth-nocache
|
||||
pull-filter ignore "auth-token"
|
||||
pull-filter ignore "ping-restart"
|
||||
auth-retry nointeract
|
||||
suppress-timestamps
|
||||
```
|
||||
### Multiple remote options
|
||||
|
||||
- The following instructions are overriden by settings read from environment variables, if set:
|
||||
If you have multiple `remote` instructions, only the first one is taken into account.
|
||||
|
||||
```conf
|
||||
verb
|
||||
cipher
|
||||
auth
|
||||
mssfix
|
||||
```
|
||||
### Added options
|
||||
|
||||
- If `OPENVPN_IPV6` is `off`, the following instructions are added:
|
||||
Gluetun adds or overrides the following options:
|
||||
|
||||
```conf
|
||||
mute-replay-warnings
|
||||
suppress-timestamps
|
||||
auth-nocache
|
||||
auth-retry nointeract
|
||||
auth-user-pass /etc/openvpn/auth.conf
|
||||
pull-filter ignore "auth-token"
|
||||
```
|
||||
|
||||
### Environment variables
|
||||
|
||||
#### Options overridden
|
||||
|
||||
- `OPENVPN_VERBOSITY` defaults to `1` and adds or overrides the `verb` option.
|
||||
- `OPENVPN_INTERFACE` defaults to `tun0` and adds or overrides the `dev` option.
|
||||
- If `OPENVPN_ROOT=yes` (default), the `user` options is removed so OpenVPN runs as root.
|
||||
- If `OPENVPN_ROOT=no`, `user nonrootuser` option is added or overridden.
|
||||
- If `OPENVPN_IPV6=off` (default), the following options are added:
|
||||
|
||||
```conf
|
||||
pull-filter ignore "route-ipv6"
|
||||
pull-filter ignore "ifconfig-ipv6"
|
||||
```
|
||||
|
||||
And the instruction `tun-ipv6` is removed, if any.
|
||||
And the `tun-ipv6` option is removed.
|
||||
|
||||
#### Options overridden if variables are set
|
||||
|
||||
- `OPENVPN_CIPHER`, if set, adds or overrides:
|
||||
- `cipher` for OpenVPN 2.4
|
||||
- `data-ciphers` and `data-ciphers-fallback` for OpenVPN 2.5
|
||||
- `OPENVPN_AUTH`, if set, adds or overrides `auth`.
|
||||
- `OPENVPN_MSSFIX`, if set, adds or overrides `mssfix`.
|
||||
- `PORT`, if set, overrides the port of the remote connection found in the file.
|
||||
|
||||
#### Ignored variables
|
||||
|
||||
The following OpenVPN environment variables have no effect:
|
||||
|
||||
- `PROTOCOL` - the protocol is determined from your configuration file only.
|
||||
- `OPENVPN_CLIENTKEY_SECRETFILE`
|
||||
- `OPENVPN_CLIENTCRT_SECRETFILE`
|
||||
- `OPENVPN_TARGET_IP`
|
||||
|
||||
Reference in New Issue
Block a user