Updated documentation.
* Related to https://github.com/kylemanna/docker-openvpn/pull/54 * Allow better syntax highlighting. * Added/Fixed hyperlinks. * Spelling.
This commit is contained in:
Robin Schneider
parent
15ac3c89b0
commit
2d16231c3c
20
README.md
20
README.md
@ -18,34 +18,48 @@ a corresponding [Digital Ocean Community Tutorial](http://bit.ly/1AGUZkq).
|
||||
|
||||
* Create the `$OVPN_DATA` volume container, i.e. `OVPN_DATA="ovpn-data"`
|
||||
|
||||
```Shell
|
||||
docker run --name $OVPN_DATA -v /etc/openvpn busybox
|
||||
```
|
||||
|
||||
* Initialize the `$OVPN_DATA` container that will hold the configuration files and certificates
|
||||
|
||||
```Shell
|
||||
docker run --volumes-from $OVPN_DATA --rm kylemanna/openvpn ovpn_genconfig -u udp://VPN.SERVERNAME.COM
|
||||
docker run --volumes-from $OVPN_DATA --rm -it kylemanna/openvpn ovpn_initpki
|
||||
```
|
||||
|
||||
* Start OpenVPN server process
|
||||
|
||||
- On Docker [version 1.2](http://blog.docker.com/2014/08/announcing-docker-1-2-0/) and newer
|
||||
|
||||
```Shell
|
||||
docker run --volumes-from $OVPN_DATA -d -p 1194:1194/udp --cap-add=NET_ADMIN kylemanna/openvpn
|
||||
```
|
||||
|
||||
- On Docker older than version 1.2
|
||||
|
||||
```Shell
|
||||
docker run --volumes-from $OVPN_DATA -d -p 1194:1194/udp --privileged kylemanna/openvpn
|
||||
```
|
||||
|
||||
* Generate a client certificate without a passphrase
|
||||
|
||||
```Shell
|
||||
docker run --volumes-from $OVPN_DATA --rm -it kylemanna/openvpn easyrsa build-client-full CLIENTNAME nopass
|
||||
```
|
||||
|
||||
* Retrieve the client configuration with embedded certificates
|
||||
|
||||
```Shell
|
||||
docker run --volumes-from $OVPN_DATA --rm kylemanna/openvpn ovpn_getclient CLIENTNAME > CLIENTNAME.ovpn
|
||||
```
|
||||
|
||||
* Create an environment variable with the name DEBUG and value of 1 to enable debug output (using "docker -e").
|
||||
|
||||
for example - docker run --volumes-from $OVPN_DATA -d -p 1194:1194/udp --privileged -e DEBUG=1 kylemanna/openvpn
|
||||
```Shell
|
||||
docker run --volumes-from $OVPN_DATA -d -p 1194:1194/udp --privileged -e DEBUG=1 kylemanna/openvpn
|
||||
```
|
||||
|
||||
## How Does It Work?
|
||||
|
||||
@ -109,13 +123,13 @@ packets, etc).
|
||||
simplicity. It's highly recommended to secure the CA key with some
|
||||
passphrase to protect against a filesystem compromise. A more secure system
|
||||
would put the EasyRSA PKI CA on an offline system (can use the same Docker
|
||||
image and the script [`ovpn_copy_server_files`](/docs/clients.md) to accomplish this).
|
||||
image and the script [`ovpn_copy_server_files`](/docs/paranoid.md) to accomplish this).
|
||||
* It would be impossible for an adversary to sign bad or forged certificates
|
||||
without first cracking the key's passphase should the adversary have root
|
||||
access to the filesystem.
|
||||
* The EasyRSA `build-client-full` command will generate and leave keys on the
|
||||
server, again possible to compromise and steal the keys. The keys generated
|
||||
need to signed by the CA which the user hopefully configured with a passphrase
|
||||
need to be signed by the CA which the user hopefully configured with a passphrase
|
||||
as described above.
|
||||
* Assuming the rest of the Docker container's filesystem is secure, TLS + PKI
|
||||
security should prevent any malicious host from using the VPN.
|
||||
|
||||
@ -7,6 +7,7 @@ The [`ovpn_genconfig`](/bin/ovpn_genconfig) script is intended for simple config
|
||||
* Refer to the Quick Start document, and substitute `--volumes-from $OVPN_DATA` with `-v /path/on/host/openvpn0:/etc/openvpn`
|
||||
* Quick example that is likely to be out of date, but here's how to get started:
|
||||
|
||||
```Shell
|
||||
mkdir openvpn0
|
||||
cd openvpn0
|
||||
docker run --rm -v $PWD:/etc/openvpn kylemanna/openvpn ovpn_genconfig -u udp://VPN.SERVERNAME.COM:1194
|
||||
@ -14,7 +15,10 @@ The [`ovpn_genconfig`](/bin/ovpn_genconfig) script is intended for simple config
|
||||
vim openvpn.conf
|
||||
docker run --rm -v $PWD:/etc/openvpn -it kylemanna/openvpn easyrsa build-client-full CLIENTNAME nopass
|
||||
docker run --rm -v $PWD:/etc/openvpn kylemanna/openvpn ovpn_getclient CLIENTNAME > CLIENTNAME.ovpn
|
||||
```
|
||||
|
||||
* Start the server with:
|
||||
|
||||
```Shell
|
||||
docker run -v $PWD:/etc/openvpn -d -p 1194:1194/udp --privileged kylemanna/openvpn
|
||||
```
|
||||
|
||||
@ -2,19 +2,23 @@
|
||||
|
||||
## Security
|
||||
|
||||
The resulting archive from this back-up contains all credential to impersonate the server at a minimum. If the client's private keys are generated using the EasyRSA utility then it also contains the client certificates that could be used to impersonate said clients. Most importantly, if the certificate authority key is in this archive (as it is given the quick start directions), then a adversary could generate certificates at will.
|
||||
The resulting archive from this backup contains all credential to impersonate the server at a minimum. If the client's private keys are generated using the EasyRSA utility then it also contains the client certificates that could be used to impersonate said clients. Most importantly, if the certificate authority key is in this archive (as it is given the quick start directions), then a adversary could generate certificates at will.
|
||||
|
||||
I'd recommend encrypting the archive with something strong (e.g. gpg or openssl + AES). For the paranoid keep backup offline. For the truly paranoid users, never keep any keys (i.e. client and certificate authority) in the docker container to begin with :).
|
||||
I'd recommend encrypting the archive with something strong (e.g. gpg or openssl + AES). For the paranoid keep backup offline. For the [truly paranoid users](/docs/paranoid.md), never keep any keys (i.e. client and certificate authority) in the docker container to begin with :).
|
||||
|
||||
|
||||
**TL;DR Protect the resulting archive file. Ensure there is very limited access to it.**
|
||||
|
||||
## Backup to Archive
|
||||
|
||||
```Shell
|
||||
docker run --volumes-from $OVPN_DATA --rm busybox tar -cvf - -C /etc openvpn | xz > openvpn-backup.tar.xz
|
||||
```
|
||||
|
||||
## Restore to New Container
|
||||
|
||||
Assumes an existing container named `$OVPN_DATA` to extract the data over the top.
|
||||
|
||||
```Shell
|
||||
xzcat openvpn-backup.tar.xz | docker run --name $OVPN_DATA -v /etc/openvpn -i busybox tar -xvf - -C /etc
|
||||
```
|
||||
|
||||
@ -15,12 +15,13 @@ If you have more than a few clients, you will want to generate and update your c
|
||||
|
||||
Execute the following to generate the configuration for all clients:
|
||||
|
||||
docker run --rm -it -v /tmp/openvpn:/etc/openvpn kylemanna/openvpn ovpn_getclient_all
|
||||
```Shell
|
||||
docker run --rm -it --volumes-from $OVPN_DATA --volume /tmp/openvpn_clients:/etc/openvpn/clients kylemanna/openvpn ovpn_getclient_all
|
||||
```
|
||||
|
||||
After doing so, you will find the following files in each of the `$cn` directories:
|
||||
|
||||
ca.crt
|
||||
dh.pem
|
||||
$cn-combined.ovpn # Combined configuration file format. If your client recognices this file then only this file is needed.
|
||||
$cn.ovpn # Separated configuration. This configuration file requires the other files ca.crt dh.pem $cn.crt $cn.key ta.key
|
||||
$cn.crt
|
||||
@ -31,7 +32,9 @@ After doing so, you will find the following files in each of the `$cn` directori
|
||||
|
||||
Revoke `client1`'s certificate and generate the certificate revocation list (CRL):
|
||||
|
||||
```Shell
|
||||
docker run --rm -it --volumes-from $OVPN_DATA kylemanna/openvpn easyrsa revoke client1
|
||||
docker run --rm -it --volumes-from $OVPN_DATA kylemanna/openvpn easyrsa gen-crl
|
||||
```
|
||||
|
||||
The OpenVPN server will read this change every time a client connects (no need to restart server) and deny clients access using revoked certificates.
|
||||
|
||||
@ -7,7 +7,9 @@ Random things I do to debug the containers.
|
||||
* Create a shell in the running docker container (aka namespace) with [nsenter](https://github.com/jpetazzo/nsenter)
|
||||
* If you don't have nsenter/docker-enter, you can mount the data container and modify it with
|
||||
|
||||
```Shell
|
||||
docker run --rm -it --volumes-from $OVPN_DATA kylemanna/openvpn bash -l
|
||||
```
|
||||
|
||||
## Stream OpenVPN Logs
|
||||
|
||||
|
||||
@ -11,7 +11,7 @@ It is recommended to use platforms that support systemd as future versions of th
|
||||
|
||||
### Step 1 — Set Up Docker
|
||||
|
||||
Docker is moving fast and Debian / Ubuntu's long term support (LTS) policy doesn't keep up. To work around this we'll install a PPA that will get us the latest version of Docker.
|
||||
Docker is moving fast and Debian / Ubuntu's long term support (LTS) policy doesn't keep up. To work around this we'll install a PPA that will get us the latest version of Docker. For Debian Jessie users, just install docker.io from jessie-backports.
|
||||
|
||||
Ensure dependencies are installed:
|
||||
|
||||
@ -41,11 +41,15 @@ After **re-logging in** verify the group membership using the id command. The ex
|
||||
|
||||
Run a Debian jessie docker container:
|
||||
|
||||
```Shell
|
||||
docker run --rm -it debian:jessie bash -l
|
||||
```
|
||||
|
||||
Once inside the container you'll see the `root@<container id>:/#` prompt signifying that the current shell is in a Docker container. To confirm that it's different from the host, check the version of Debian running in the container:
|
||||
|
||||
```Shell
|
||||
cat /etc/issue.net
|
||||
```
|
||||
|
||||
Expected result:
|
||||
|
||||
|
||||
@ -2,10 +2,12 @@
|
||||
|
||||
As mentioned in the [backup section](/docs/backup.md), there are good reasons to not generate the CA and/or leave it on the server. This document describes how you can generate the CA and all your certificates on a secure machine and then copy only the needed files (which never includes the CA root key obviously ;) ) to the server(s) and clients.
|
||||
|
||||
Execute the following commands. Note that you might want to change the volume `/tmp/openvpn` to persistent storage or use a data docker container for this.
|
||||
Execute the following commands. Note that you might want to change the volume `$PWD` or use a data docker container for this.
|
||||
|
||||
```Shell
|
||||
docker run --rm -t -i -v $PWD:/etc/openvpn kylemanna/openvpn ovpn_genconfig -u udp://VPN.SERVERNAME.COM
|
||||
docker run --rm -t -i -v $PWD:/etc/openvpn kylemanna/openvpn ovpn_initpki
|
||||
docker run --rm -t -i -v $PWD:/etc/openvpn kylemanna/openvpn ovpn_copy_server_files
|
||||
```
|
||||
|
||||
The [`ovpn_copy_server_files`](/bin/ovpn_copy_server_files) script puts all the needed configuration in a subdirectory which defaults to `$OPENVPN/server`. All you need to do now is to copy this directory to the server and you are good to go.
|
||||
|
||||
@ -1,13 +1,15 @@
|
||||
# Static IP Addresses
|
||||
|
||||
The docker image is setup for static client configuration on the 192.168.254.0/24 subnet. To use it follow the Quick Start section below. Note that the IP addresses octects need to be picked special, see [OpenVPN Documentation](https://openvpn.net/index.php/open-source/documentation/howto.html#policy) for more details.
|
||||
The docker image is setup for static client configuration on the 192.168.254.0/24 subnet. To use it follow the Quick Start section below. Note that the IP addresses octets need to be picked special, see [OpenVPN Documentation](https://openvpn.net/index.php/open-source/documentation/howto.html#policy) for more details.
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. Create a client specific configuration:
|
||||
|
||||
$ echo "ifconfig-push 192.168.254.1 192.168.254.2" | docker run --volumes-from $OVPN_DATA -i --rm kylemanna/openvpn tee /etc/openvpn/ccd/CERT_COMMON_NAME
|
||||
```Shell
|
||||
echo "ifconfig-push 192.168.254.1 192.168.254.2" | docker run --volumes-from $OVPN_DATA -i --rm kylemanna/openvpn tee /etc/openvpn/ccd/CERT_COMMON_NAME
|
||||
ifconfig-push 192.168.254.1 192.168.254.2
|
||||
```
|
||||
|
||||
2. Wait for client to reconnect if necessary
|
||||
|
||||
@ -15,10 +17,14 @@ The docker image is setup for static client configuration on the 192.168.254.0/2
|
||||
|
||||
Login to the data volume with a `bash` container, note only changes in /etc/openvpn will persist:
|
||||
|
||||
```Shell
|
||||
docker run --volumes-from $OVPN_DATA -it --rm kylemanna/openvpn bash -l
|
||||
```
|
||||
|
||||
## Upgrading from Old OpenVPN Configurations
|
||||
|
||||
If you're running an old configuration and need to upgrade it to pull in the ccd directory run the following:
|
||||
|
||||
```Shell
|
||||
docker run --volumes-from $OVPN_DATA --rm kylemanna/openvpn ovpn_genconfig
|
||||
```
|
||||
|
||||
Loading…
Reference in New Issue
Block a user