Skip to content

Commit 92bb2a8

Browse files
GHOSCHTGHOSCHT
committed
Customize readme
1 parent 62fcb8c commit 92bb2a8

File tree

1 file changed

+61
-88
lines changed

1 file changed

+61
-88
lines changed

‎README.md

Lines changed: 61 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,47 @@
11
# OpenVPN for Docker
22

3-
[![Build Status](https://travis-ci.org/kylemanna/docker-openvpn.svg)](https://travis-ci.org/kylemanna/docker-openvpn)
4-
[![Docker Stars](https://img.shields.io/docker/stars/kylemanna/openvpn.svg)](https://hub.docker.com/r/kylemanna/openvpn/)
5-
[![Docker Pulls](https://img.shields.io/docker/pulls/kylemanna/openvpn.svg)](https://hub.docker.com/r/kylemanna/openvpn/)
6-
[![ImageLayers](https://images.microbadger.com/badges/image/kylemanna/openvpn.svg)](https://microbadger.com/#/images/kylemanna/openvpn)
7-
[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fkylemanna%2Fdocker-openvpn.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Fkylemanna%2Fdocker-openvpn?ref=badge_shield)
8-
9-
103
OpenVPN server in a Docker container complete with an EasyRSA PKI CA.
114

12-
Extensively tested on [Digital Ocean $5/mo node](http://bit.ly/1C7cKr3) and has
13-
a corresponding [Digital Ocean Community Tutorial](http://bit.ly/1AGUZkq).
14-
155
#### Upstream Links
166

17-
* Docker Registry @ [kylemanna/openvpn](https://hub.docker.com/r/kylemanna/openvpn/)
18-
* GitHub @ [kylemanna/docker-openvpn](https://github.com/kylemanna/docker-openvpn)
7+
- Docker Registry @ [ghoscht/openvpn](https://hub.docker.com/r/ghoscht/openvpn)
8+
- Original GitHub Repo @ [kylemanna/docker-openvpn](https://github.com/kylemanna/docker-openvpn)
199

2010
## Quick Start
2111

22-
* Pick a name for the `$OVPN_DATA` data volume container. It's recommended to
23-
use the `ovpn-data-` prefix to operate seamlessly with the reference systemd
24-
service. Users are encourage to replace `example` with a descriptive name of
25-
their choosing.
12+
- Pick a name for the `$OVPN_DATA` data volume container. It's recommended to
13+
use the `ovpn-data-` prefix to operate seamlessly with the reference systemd
14+
service. Users are encourage to replace `example` with a descriptive name of
15+
their choosing.
2616

27-
OVPN_DATA="ovpn-data-example"
17+
OVPN_DATA="ovpn-data-example"
2818

29-
* Initialize the `$OVPN_DATA` container that will hold the configuration files
30-
and certificates. The container will prompt for a passphrase to protect the
31-
private key used by the newly generated certificate authority.
19+
- Initialize the `$OVPN_DATA` container that will hold the configuration files
20+
and certificates. The container will prompt for a passphrase to protect the
21+
private key used by the newly generated certificate authority.
3222

33-
docker volume create --name $OVPN_DATA
34-
docker run -v $OVPN_DATA:/etc/openvpn --rm kylemanna/openvpn ovpn_genconfig -u udp://VPN.SERVERNAME.COM
35-
docker run -v $OVPN_DATA:/etc/openvpn --rm -it kylemanna/openvpn ovpn_initpki
23+
docker volume create --name $OVPN_DATA
24+
docker run -v $OVPN_DATA:/etc/openvpn --rm ghoscht/openvpn ovpn_genconfig -u tcp://VPN.SERVERNAME.COM
25+
docker run -v $OVPN_DATA:/etc/openvpn --rm -it ghoscht/openvpn ovpn_initpki
3626

37-
* Start OpenVPN server process
27+
- Start OpenVPN server process
3828

39-
docker run -v $OVPN_DATA:/etc/openvpn -d -p 1194:1194/udp --cap-add=NET_ADMIN kylemanna/openvpn
29+
docker run -v $OVPN_DATA:/etc/openvpn -d -p 1194:1194/tcp --cap-add=NET_ADMIN ghoscht/openvpn
4030

41-
* Generate a client certificate without a passphrase
31+
Remember to add following environment variables:
32+
AUTHTOKEN = Ngrok auth token
33+
SENDERMAIL = Gmail address the ngrok url information is sent from
34+
SENDERPASSWORD = Gmail password for sendermail
35+
-> IT'S NECESSARY TO ALLOW LESS SECURE APP ACCESS IN YOUR GOOGLE ACCOUNT DASHBOARD UNDER SECURITY FOR IT TO WORK
36+
RECIPIENTMAIL = Email address you want to send notifications to
4237

43-
docker run -v $OVPN_DATA:/etc/openvpn --rm -it kylemanna/openvpn easyrsa build-client-full CLIENTNAME nopass
38+
- Generate a client certificate without a passphrase
4439

45-
* Retrieve the client configuration with embedded certificates
40+
docker run -v $OVPN_DATA:/etc/openvpn --rm -it ghoscht/openvpn easyrsa build-client-full CLIENTNAME nopass
4641

47-
docker run -v $OVPN_DATA:/etc/openvpn --rm kylemanna/openvpn ovpn_getclient CLIENTNAME > CLIENTNAME.ovpn
42+
- Retrieve the client configuration with embedded certificates
43+
44+
docker run -v $OVPN_DATA:/etc/openvpn --rm ghoscht/openvpn ovpn_getclient CLIENTNAME > CLIENTNAME.ovpn
4845

4946
## Next Steps
5047

@@ -67,34 +64,34 @@ If you prefer to use `docker-compose` please refer to the [documentation](docs/d
6764

6865
## Debugging Tips
6966

70-
* Create an environment variable with the name DEBUG and value of 1 to enable debug output (using "docker -e").
67+
- Create an environment variable with the name DEBUG and value of 1 to enable debug output (using "docker -e").
7168

72-
docker run -v $OVPN_DATA:/etc/openvpn -p 1194:1194/udp --cap-add=NET_ADMIN -e DEBUG=1 kylemanna/openvpn
69+
docker run -v $OVPN_DATA:/etc/openvpn -p 1194:1194/tcp --cap-add=NET_ADMIN -e DEBUG=1 ghoscht/openvpn
7370

74-
* Test using a client that has openvpn installed correctly
71+
- Test using a client that has openvpn installed correctly
7572

76-
$ openvpn --config CLIENTNAME.ovpn
73+
$ openvpn --config CLIENTNAME.ovpn
7774

78-
* Run through a barrage of debugging checks on the client if things don't just work
75+
- Run through a barrage of debugging checks on the client if things don't just work
7976

80-
$ ping 8.8.8.8 # checks connectivity without touching name resolution
81-
$ dig google.com # won't use the search directives in resolv.conf
82-
$ nslookup google.com # will use search
77+
$ ping 8.8.8.8 # checks connectivity without touching name resolution
78+
$ dig google.com # won't use the search directives in resolv.conf
79+
$ nslookup google.com # will use search
8380

84-
* Consider setting up a [systemd service](/docs/systemd.md) for automatic
85-
start-up at boot time and restart in the event the OpenVPN daemon or Docker
86-
crashes.
81+
- Consider setting up a [systemd service](/docs/systemd.md) for automatic
82+
start-up at boot time and restart in the event the OpenVPN daemon or Docker
83+
crashes.
8784

8885
## How Does It Work?
8986

90-
Initialize the volume container using the `kylemanna/openvpn` image with the
87+
Initialize the volume container using the `ghoscht/openvpn` image with the
9188
included scripts to automatically generate:
9289

93-
- Diffie-Hellman parameters
94-
- a private key
95-
- a self-certificate matching the private key for the OpenVPN server
96-
- an EasyRSA CA key and certificate
97-
- a TLS auth key from HMAC security
90+
- Diffie-Hellman parameters
91+
- a private key
92+
- a self-certificate matching the private key for the OpenVPN server
93+
- an EasyRSA CA key and certificate
94+
- a TLS auth key from HMAC security
9895

9996
The OpenVPN server is started with the default run cmd of `ovpn_run`
10097

@@ -103,11 +100,11 @@ declares that directory as a volume. It means that you can start another
103100
container with the `-v` argument, and access the configuration.
104101
The volume also holds the PKI keys and certs so that it could be backed up.
105102

106-
To generate a client certificate, `kylemanna/openvpn` uses EasyRSA via the
103+
To generate a client certificate, `ghoscht/openvpn` uses EasyRSA via the
107104
`easyrsa` command in the container's path. The `EASYRSA_*` environmental
108105
variables place the PKI CA under `/etc/openvpn/pki`.
109106

110-
Conveniently, `kylemanna/openvpn` comes with a script called `ovpn_getclient`,
107+
Conveniently, `ghoscht/openvpn` comes with a script called `ovpn_getclient`,
111108
which dumps an inline OpenVPN client configuration file. This single file can
112109
then be given to a client for access to the VPN.
113110

@@ -122,7 +119,7 @@ is rooted.
122119
The topology used is `net30`, because it works on the widest range of OS.
123120
`p2p`, for instance, does not work on Windows.
124121

125-
The UDP server uses`192.168.255.0/24` for dynamic clients by default.
122+
The tcp server uses`192.168.255.0/24` for dynamic clients by default.
126123

127124
The client profile specifies `redirect-gateway def1`, meaning that after
128125
establishing the VPN connection, all traffic will go through the VPN.
@@ -132,7 +129,6 @@ and they might not answer to you. If that happens, use public DNS
132129
resolvers like those of Google (8.8.4.4 and 8.8.8.8) or OpenDNS
133130
(208.67.222.222 and 208.67.220.220).
134131

135-
136132
## Security Discussion
137133

138134
The Docker container runs its own EasyRSA PKI Certificate Authority. This was
@@ -144,21 +140,20 @@ adversary had access to these files, the adversary could manipulate the
144140
function of the OpenVPN server itself (sniff packets, create a new PKI CA, MITM
145141
packets, etc).
146142

147-
* The certificate authority key is kept in the container by default for
148-
simplicity. It's highly recommended to secure the CA key with some
149-
passphrase to protect against a filesystem compromise. A more secure system
150-
would put the EasyRSA PKI CA on an offline system (can use the same Docker
151-
image and the script [`ovpn_copy_server_files`](/docs/paranoid.md) to accomplish this).
152-
* It would be impossible for an adversary to sign bad or forged certificates
153-
without first cracking the key's passphase should the adversary have root
154-
access to the filesystem.
155-
* The EasyRSA `build-client-full` command will generate and leave keys on the
156-
server, again possible to compromise and steal the keys. The keys generated
157-
need to be signed by the CA which the user hopefully configured with a passphrase
158-
as described above.
159-
* Assuming the rest of the Docker container's filesystem is secure, TLS + PKI
160-
security should prevent any malicious host from using the VPN.
161-
143+
- The certificate authority key is kept in the container by default for
144+
simplicity. It's highly recommended to secure the CA key with some
145+
passphrase to protect against a filesystem compromise. A more secure system
146+
would put the EasyRSA PKI CA on an offline system (can use the same Docker
147+
image and the script [`ovpn_copy_server_files`](/docs/paranoid.md) to accomplish this).
148+
- It would be impossible for an adversary to sign bad or forged certificates
149+
without first cracking the key's passphase should the adversary have root
150+
access to the filesystem.
151+
- The EasyRSA `build-client-full` command will generate and leave keys on the
152+
server, again possible to compromise and steal the keys. The keys generated
153+
need to be signed by the CA which the user hopefully configured with a passphrase
154+
as described above.
155+
- Assuming the rest of the Docker container's filesystem is secure, TLS + PKI
156+
security should prevent any malicious host from using the VPN.
162157

163158
## Benefits of Running Inside a Docker Container
164159

@@ -173,7 +168,7 @@ OpenVPN with latest OpenSSL on Ubuntu 12.04 LTS).
173168
### It Doesn't Stomp All Over the Server's Filesystem
174169

175170
Everything for the Docker container is contained in two images: the ephemeral
176-
run time image (kylemanna/openvpn) and the `$OVPN_DATA` data volume. To remove
171+
run time image (ghoscht/openvpn) and the `$OVPN_DATA` data volume. To remove
177172
it, remove the corresponding containers, `$OVPN_DATA` data volume and Docker
178173
image and it's completely removed. This also makes it easier to run multiple
179174
servers since each lives in the bubble of the container (of course multiple IPs
@@ -186,25 +181,3 @@ compromise of the server. There are many arguments surrounding this, but the
186181
take away is that it certainly makes it more difficult to break out of the
187182
container. People are actively working on Linux containers to make this more
188183
of a guarantee in the future.
189-
190-
## Differences from jpetazzo/dockvpn
191-
192-
* No longer uses serveconfig to distribute the configuration via https
193-
* Proper PKI support integrated into image
194-
* OpenVPN config files, PKI keys and certs are stored on a storage
195-
volume for re-use across containers
196-
* Addition of tls-auth for HMAC security
197-
198-
## Originally Tested On
199-
200-
* Docker hosts:
201-
* server a [Digital Ocean](https://www.digitalocean.com/?refcode=d19f7fe88c94) Droplet with 512 MB RAM running Ubuntu 14.04
202-
* Clients
203-
* Android App OpenVPN Connect 1.1.14 (built 56)
204-
* OpenVPN core 3.0 android armv7a thumb2 32-bit
205-
* OS X Mavericks with Tunnelblick 3.4beta26 (build 3828) using openvpn-2.3.4
206-
* ArchLinux OpenVPN pkg 2.3.4-1
207-
208-
209-
## License
210-
[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fkylemanna%2Fdocker-openvpn.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fkylemanna%2Fdocker-openvpn?ref=badge_large)

0 commit comments

Comments
 (0)