You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Mar 16, 2024. It is now read-only.
Copy file name to clipboardExpand all lines: README.md
+59-33Lines changed: 59 additions & 33 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,60 +1,76 @@
1
1
# OpenVPN Client for Docker
2
2
## What is this and what does it do?
3
-
[`ghcr.io/wfg/openvpn-client`](https://github.com/users/wfg/packages/container/package/openvpn-client) is a containerized OpenVPN client. It has a kill switch built with `iptables` that kills Internet connectivity to the container if the VPN tunnel goes down for any reason. It also includes an HTTP proxy server ([Tinyproxy](https://tinyproxy.github.io/)) and a SOCKS proxy server ([Dante](https://www.inet.no/dante/index.html)). This allows hosts and non-containerized applications to use the VPN without having to run VPN clients on those hosts.
3
+
[`ghcr.io/wfg/openvpn-client`](https://github.com/users/wfg/packages/container/package/openvpn-client) is a containerized OpenVPN client.
4
+
It has a kill switch built with `iptables` that kills Internet connectivity to the container if the VPN tunnel goes down for any reason.
5
+
It also includes an HTTP proxy server ([Tinyproxy](https://tinyproxy.github.io/)) and a SOCKS proxy server ([Dante](https://www.inet.no/dante/index.html)).
6
+
This allows hosts and non-containerized applications to use the VPN without having to run VPN clients on those hosts.
4
7
5
-
This image requires you to supply the necessary OpenVPN configuration file(s). Because of this, any VPN provider should work (however, if you find something that doesn't, please open an issue for it).
8
+
This image requires you to supply the necessary OpenVPN configuration file(s).
9
+
Because of this, any VPN provider should work.
10
+
11
+
If you find something that doesn't work or have an idea for a new feature, issues and **pull requests are welcome**.
6
12
7
13
## Why?
8
-
Having a containerized VPN client lets you use container networking to easily choose which applications you want using the VPN instead of having to set up split tunnelling. It also keeps you from having to install an OpenVPN client on the underlying host.
14
+
Having a containerized VPN client lets you use container networking to easily choose which applications you want using the VPN instead of having to set up split tunnelling.
15
+
It also keeps you from having to install an OpenVPN client on the underlying host.
9
16
10
-
The idea for this image came from a similar project by [qdm12](https://github.com/qdm12) that has since evolved into something bigger and more complex than I wanted to use. I decided to dissect it and take it in my own direction. I plan to keep everything here well-documented because I want this to be a learning experience for both me and hopefully anyone else that uses it.
17
+
The idea for this image came from a similar project by [qdm12](https://github.com/qdm12) that has since evolved into something bigger and more complex than I wanted to use.
18
+
I decided to dissect it and take it in my own direction.
19
+
I plan to keep everything here well-documented so this is not only a learning experience for me, but also anyone else that uses it.
11
20
12
21
## How do I use it?
13
22
### Getting the image
14
23
You can either pull it from GitHub Container Registry or build it yourself.
15
24
16
-
To pull from GitHub Container Registry, run `docker pull ghcr.io/wfg/openvpn-client`.
The image requires the container be created with the `NET_ADMIN` capability and `/dev/net/tun` accessible. Below are bare-bones examples for `docker run` and Compose; however, you'll probably want to do more than just run the VPN client. See the sections below to learn how to use the [proxies](#http_proxy-and-socks_proxy) and have [other containers use `openvpn-client`'s network stack](#using-with-other-containers).
36
+
The image requires the container be created with the `NET_ADMIN` capability and `/dev/net/tun` accessible.
37
+
Below are bare-bones examples for `docker run` and Compose; however, you'll probably want to do more than just run the VPN client.
38
+
See the sections below to learn how to use the [proxies](#http_proxy-and-socks_proxy) and have [other containers use `openvpn-client`'s network stack](#using-with-other-containers).
27
39
28
40
#### `docker run`
29
41
```bash
30
-
docker run -d \
42
+
docker run --detach \
31
43
--name=openvpn-client \
32
44
--cap-add=NET_ADMIN \
33
45
--device=/dev/net/tun \
34
-
-v <path/to/config>:/data/vpn \
46
+
--env KILL_SWITCH=off \
47
+
--volume <path/to/config/dir>:/data/vpn \
35
48
ghcr.io/wfg/openvpn-client
36
49
```
37
50
38
51
#### `docker-compose`
39
52
```yaml
40
-
version: '2'
53
+
version: "2.4"
41
54
42
55
services:
43
-
openvpn-client:
44
-
image: ghcr.io/wfg/openvpn-client
45
-
container_name: openvpn-client
46
-
cap_add:
47
-
- NET_ADMIN
48
-
devices:
49
-
- /dev/net/tun
50
-
volumes:
51
-
- <path/to/config>:/data/vpn
52
-
restart: unless-stopped
56
+
openvpn-client:
57
+
image: ghcr.io/wfg/openvpn-client
58
+
container_name: openvpn-client
59
+
cap_add:
60
+
- NET_ADMIN
61
+
devices:
62
+
- /dev/net/tun
63
+
environment:
64
+
- KILL_SWITCH=off
65
+
volumes:
66
+
- <path/to/config/dir>:/data/vpn
67
+
restart: unless-stopped
53
68
```
54
69
55
70
#### Environment variables
56
71
| Variable | Default (blank is unset) | Description |
57
72
| --- | --- | --- |
73
+
| `KILL_SWITCH` | `on` | The on/off status of the network kill switch. |
58
74
| `SUBNETS` | | A list of one or more comma-separated subnets (e.g. `192.168.0.0/24,192.168.1.0/24`) to allow outside of the VPN tunnel. See important note about this [below](#subnets). |
| `HTTP_PROXY` | `off` | The on/off status of Tinyproxy, the built-in HTTP proxy server. To enable, set to `on`. Any other value (including unset) will cause the proxy server to not start. It listens on port 8080. |
@@ -64,39 +80,49 @@ services:
64
80
65
81
##### Environment variable considerations
66
82
###### `SUBNETS`
67
-
**Important**: The DNS server used by this container prior to VPN connection must be included in the value specified. For example, if your container is using 192.168.1.1 as a DNS server, then this address or an appropriate CIDR block must be included in `SUBNETS`. This is necessary because the kill switch blocks traffic outside of the VPN tunnel before it's actually established. If the DNS server is not allowed, the server addresses in the VPN configuration will not resolve.
83
+
**Important**:
84
+
If the kill switch is enabled, the DNS server used by this container prior to VPN connection must be included in the value specified.
85
+
For example, if your container is using 192.168.1.1 as a DNS server, then this address or an appropriate CIDR block must be included in `SUBNETS`.
86
+
This is necessary because the kill switch blocks traffic outside of the VPN tunnel before it's actually established.
87
+
If the DNS server is not allowed, the server addresses in the VPN configuration will not resolve.
68
88
69
89
The subnets specified will be allowed through the firewall which allows for connectivity to and from hosts on the subnets.
70
90
71
91
###### `HTTP_PROXY` and `SOCKS_PROXY`
72
-
If enabling the the proxy server(s), you'll want to publish the appropriate port(s) in order to access the server(s). To do that using `docker run`, add `-p <host_port>:8080` and/or `-p <host_port>:1080` where `<host_port>` is whatever port you want to use on the host. If you're using `docker-compose`, add the relevant port specification(s) from the snippet below to the `openvpn-client` service definition in your Compose file.
92
+
If enabling the the proxy server(s), you'll want to publish the appropriate port(s) in order to access the server(s).
93
+
To do that using `docker run`, add `-p <host_port>:8080` and/or `-p <host_port>:1080` where `<host_port>` is whatever port you want to use on the host.
94
+
If you're using `docker-compose`, add the relevant port specification(s) from the snippet below to the `openvpn-client` service definition in your Compose file.
73
95
```yaml
74
96
ports:
75
-
- <host_port>:8080
76
-
- <host_port>:1080
97
+
- <host_port>:8080
98
+
- <host_port>:1080
77
99
```
78
100
79
101
### Using with other containers
80
-
Once you have your `openvpn-client` container up and running, you can tell other containers to use `openvpn-client`'s network stack which gives them the ability to utilize the VPN tunnel. There are a few ways to accomplish this depending how how your container is created.
102
+
Once you have your `openvpn-client` container up and running, you can tell other containers to use `openvpn-client`'s network stack which gives them the ability to utilize the VPN tunnel.
103
+
There are a few ways to accomplish this depending how how your container is created.
81
104
82
105
If your container is being created with
83
106
1. the same Compose YAML file as `openvpn-client`, add `network_mode: service:openvpn-client` to the container's service definition.
84
107
2. a different Compose YAML file than `openvpn-client`, add `network_mode: container:openvpn-client` to the container's service definition.
85
108
3. `docker run`, add `--network=container:openvpn-client` as an option to `docker run`.
86
109
87
-
Once running and provided your container has `wget` or `curl`, you can run `docker exec <container_name> wget -qO - ifconfig.me` or `docker exec <container_name> curl -s ifconfig.me` to get the public IP of the container and make sure everything is working as expected. This IP should match the one of `openvpn-client`.
110
+
Once running and provided your container has `wget` or `curl`, you can run `docker exec <container_name> wget -qO - ifconfig.me` or `docker exec <container_name> curl -s ifconfig.me` to get the public IP of the container and make sure everything is working as expected.
111
+
This IP should match the one of `openvpn-client`.
88
112
89
113
#### Handling ports intended for connected containers
90
-
If you have a connected container and you need to access a port that container, you'll want to publish that port on the `openvpn-client` container instead of the connected container. To do that, add `-p <host_port>:<container_port>` if you're using `docker run`, or add the below snippet to the `openvpn-client` service definition in your Compose file if using `docker-compose`.
114
+
If you have a connected container and you need to access a port that container, you'll want to publish that port on the `openvpn-client` container instead of the connected container.
115
+
To do that, add `-p <host_port>:<container_port>` if you're using `docker run`, or add the below snippet to the `openvpn-client` service definition in your Compose file if using `docker-compose`.
91
116
```yaml
92
117
ports:
93
-
- <host_port>:<container_port>
118
+
- <host_port>:<container_port>
94
119
```
95
120
In both cases, replace `<host_port>` and `<container_port>` with the port used by your connected container.
96
121
97
122
### Verifying functionality
98
-
Once you have container running `ghcr.io/wfg/openvpn-client`, run the following command to spin up a temporary container using `openvpn-client` for networking. The `wget -qO - ifconfig.me` bit will return the public IP of the container (and anything else using `openvpn-client` for networking). You should see an IP address owned by your VPN provider.
123
+
Once you have container running `ghcr.io/wfg/openvpn-client`, run the following command to spin up a temporary container using `openvpn-client` for networking.
124
+
The `wget -qO - ifconfig.me` bit will return the public IP of the container (and anything else using `openvpn-client` for networking).
125
+
You should see an IP address owned by your VPN provider.
99
126
```bash
100
127
docker run --rm -it --network=container:openvpn-client alpine wget -qO - ifconfig.me
0 commit comments