search

xptsp / pivpn-docker

Run PiVPN in a Container!
MIT License
8 stars 5 forks source link

readme

PiVPN

OpenVPN-based PiVPN in a Docker Container!

Setting up an VPN server is easy, but we can make it even easier and you can do it within 1 min. All the prerequisite is just the docker which has been compatible with the Raspberry Pi for a while. If you don't have the docker installed on your little machine, go and check it out here.

Supported Architectures

Server-side Usage

Using Docker

How to launch PiVPN on the PiVPN server machine using docker:

docker run -ti --rm \
    --privileged \
    --net host \
    --name pivpn \
    -v /home/docker/pivpn/ovpns:/home/pivpn/ovpns \
    -v /home/docker/pivpn/openvpn-data:/etc/openvpn \
    xptsp/pivpn

Wait until you see PiVPN Service Started

Using Docker-Compose

Basic docker-compose.yaml file to use with docker-compose:

version: '2.1'
services:
  pivpn:
    container_name: pivpn
    image: xptsp/pivpn
    privileged: true
    network_mode: "host"
    volumes:
      - /home/docker/pivpn/ovpns:/home/pivpn/ovpns
      - /home/docker/pivpn/openvpn-data:/etc/openvpn

Available Environmental Variables

When linking a PiHole to this container, you should include environment variables pivpnDNS1=10.8.0.1 and pivpnDNS2=none to this container. This should link them correctly, at least from PiVPN's side.

Required Volumes to Mount

Container First Run

On first launch, the server certificates and DH parameters are generated. The default encryption is 2048-bit, which (according to pivpn.net) will take about 40 minutes to generate on a Model B+, and several hours if you choose a larger size.

Managing Client Certificates

Creating a Client Certificate

docker exec -it pivpn pivpn add

You will be prompted to enter a name for your client. Pick anything you like and hit 'enter'. You will be asked to enter a pass phrase for the client key; make sure it's one you'll remember. The script will assemble the client .ovpn file and place it in the volume mounted on the directory /home/pivpn/ovpns within your home directory.

If you need to create a client certificate that is not password protected (IE for use on a router), then you can use the 'pivpn add nopass' option to generate that.

Revoking a Client Certificate

docker exec -it pivpn pivpn revoke

Asks you for the name of the client to revoke. Once you revoke a client, it will no longer allow you to use the given client certificate (ovpn config) to connect. This is useful for many reasons but some ex: You have a profile on a mobile phone and it was lost or stolen. Revoke its cert and generate a new one for your new phone. Or even if you suspect that a cert may have been compromised in any way, just revoke it and generate a new one.

Listing Client Certificates

docker exec -it pivpn pivpn list

If you add more than a few clients, this gives you a nice list of their names and whether their certificate is still valid or has been revoked. Great way to keep track of what you did with 'pivpn add' and 'pivpn revoke'.

Issues

If you have any issues with this docker container, please open an issue over in the GitHub repository and I'll try to address the issue as soon as I am able. Thanks for helping improve this docker container!

Version History

v2 - Unreleased

v1 - August 23rd, 2020

Credits