Skip to content

Commit a6ec0ad

Browse files
SloCompTechSloCompTech
committed
Added docs
1 parent 785266d commit a6ec0ad

File tree

3 files changed

+300
-26
lines changed

3 files changed

+300
-26
lines changed

‎README.md‎

Lines changed: 69 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,34 @@
11

2-
# [slocomptech/docker-openvpn]()
2+
# [slocomptech/docker-openvpn](https://github.com/SloCompTech/docker-openvpn)
33

44

55
Features:
66

7-
- OpenVPN is running as non-root user, soo it has limited permission.
8-
- OpenVPN is running in isolated environment (container) so you don't break it with updates, upgrades of your PC.
9-
- Easy managed (has helper scripts).
7+
- OpenVPN running as non-root user (limited permission)
8+
- Containerized (Isolated environment)
9+
- Easy managed (Helper scripts).
1010
- Easy start (Simple first-start guide).
1111
- Easly modified to your needs (see [docs](CONTRIBUTING.md)).
1212
- Easy scripting (python3 installed).
1313

1414
## Usage
1515

16+
Here are some example snippets to help you get started creating a container.
17+
1618
### docker
1719

1820
``` bash
19-
21+
# Normal start command (but you need to setup config first)
22+
docker run \
23+
--name=ovpn \
24+
--cap-add NET_ADMIN \
25+
-e PUID=1000 \
26+
-e GUID=1000 \
27+
-p 1194:1194/udp \
28+
-v </path/o/config>:/config \
29+
--restart=unless-stopped \
30+
--network host \
31+
slocomptech/openvpn:latest
2032
```
2133

2234
### docker-compose
@@ -29,6 +41,9 @@ Features:
2941

3042
|**Parameter**|**Function**|
3143
|:-----------:|:----------:|
44+
|`-e PUID=1000`|for UserID - see below for explanation|
45+
|`-e PGID=1000`|for GroupID - see below for explanation|
46+
|`-v /config`|All the config files including OpenVPNs reside here|
3247

3348
## User / Group Identifiers
3449

@@ -45,29 +60,56 @@ In this instance `PUID=1000` and `PGID=1000`, to find yours use `id user` as bel
4560

4661
## Application setup
4762

48-
``` bash
49-
# Setup config directory
50-
sudo docker run -v <Config on Host>:/config --rm -it slocomptech/docker-openvpn bash
51-
$ ovpn_init
52-
# Here will ask for password for CA (needed for signing new certificates) (add nopass if you dont want to set password)
53-
# Enable basic example as config & edit /config/openvpn/server/server_*.conf & /config/openvpn/client_*.conf
54-
$ ovpn_enconf basic1
55-
# Or put your own server config in /config/openvpn/server & client template (without certs) to /config/openvpn/client
56-
# To add client (generate certificates)
57-
$ ovpn_client add <name> [nopass]
58-
# To build .ovpn file
59-
$ ovpn_client ovpn <name> > <file>
60-
# Or from outside of docker (currently not working yet)
61-
sudo docker exec -it <container name> ovpn_client add <name> nopass && ovpn_client ovpn <name> > <file>
62-
# Exit from temporary container
63-
$ exit
64-
# Run container for real
65-
sudo docker run -v <Config on Host>:/config --cap-add NET_ADMIN -p 1104:1194/udp --restart=unless-stopped slocomptech/docker-openvpn
66-
# Setup routing
63+
### Initial setup
6764

68-
```
65+
If you are new to containers please see rather [Detailed first setup guide](docs/SetupGuide.md), because it includes more detailed description.
66+
67+
1. Init configuration directory with initial config files:
68+
69+
``` bash
70+
docker run -it --rm --cap-add NET_ADMIN -v </path/to/config>:/config slocomptech/openvpn:latest bash
71+
```
72+
73+
2. At this point you will have bash shell which runs in container. Now run following commands to setup your PKI:
74+
75+
``` bash
76+
ovpn_init [nopass] # Inits PKI
77+
```
78+
79+
3. Setup OpenVPN config based on example `basic_nat` with configuration wizard:
80+
81+
``` bash
82+
ovpn_enconf basic_nat
83+
#Protocol udp, tcp, udp6, tcp6 [udp]:
84+
#VPN network [10.0.0.0]:
85+
#Port [1194]:
86+
#Public IP or domain of server: <YOUR PUBLIC IP>
87+
#DNS1 [8.8.8.8]:
88+
#DNS2 [8.8.4.4]:
89+
```
90+
4. Enable **port forwarding** on your router so OpenVPN server will be accessible from the internet.
91+
5. Add clients
92+
93+
``` bash
94+
# Generates client certificates
95+
ovpn_client add <name> [nopass]
96+
97+
# Generates client config file and prints it to screen (redirect to file)
98+
ovpn_client ovpn <name> > <config file>.ovpn
99+
100+
# OR BETTER SOLLUTION: Run outside container
101+
docker exec -it <container name> ovpn_client ovpn <name> > <config file>.ovpn
102+
```
103+
104+
5. Exit container with `exit`, then it will destroy itself.
105+
6. Start container using command specified in *Usage* section.
106+
107+
For more infromation see:
69108

70-
See more in [docs](docs).
109+
- [Detailed first setup guide](docs/SetupGuide.md)
110+
- [docs](docs) (for detailed command usage)
111+
- **configuration example directory** (for more info about example)
112+
- [Contributing](CONTRIBUTING.md) (for explanation how container works, how to write an example config ...)
71113

72114
## Contribute
73115

@@ -92,3 +134,4 @@ Wanted features (please help implement):
92134

93135
## Versions
94136

137+
See [CHANGELOG](CHANGELOG.md)

‎docs/README.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Documentation
2+
3+
## Table of content
4+
5+
1. Commands
6+
7+
- [Simple setup guide](SetupGuide.md)
8+
9+
## Commands
10+
11+
This section explains commands available for use.
12+
13+
### Command List
14+
15+
|**Command**|**Description**|
16+
|:---------:|:-------------:|
17+
|`ovpn_backup`|Backups your configration|
18+
|`ovpn_client`|Manages clients|
19+
|`ovpn_disconf`|Deletes active OpenVPN config|
20+
|`ovpn_enconf`|Enables OpenVPN config from examples|
21+
|`ovpn_init`|Inits PKI|
22+
23+
#### ovpn_backup
24+
25+
This command backups your configration into *.tar.gz* archive and puts it into `/config/backup` directory.
26+
27+
```
28+
Usage: ovpn_backup COMMAND
29+
30+
Commands:
31+
all # Backup whole config directory"
32+
pki # Backup PKI files"
33+
hooks # Backup hooks"
34+
openvpn # Backup openvpn live config"
35+
```
36+
37+
**Note:** Store your backups in a **SECURE** way, because they are unecrypted.
38+
39+
#### ovpn_client
40+
41+
This commands manages clients of your OpenVPN server.
42+
43+
```
44+
Usage: ovpn_client COMMAND [ARGS]
45+
46+
Commands:
47+
add [NAME [nopass]] # Creates certificates for client
48+
ovpn NAME # Builds .ovpn file
49+
revoke|ban|delete|remove NAME # Removes client
50+
```
51+
52+
**Note:** First you need to use `add` to create client certificates, before you can use `ovpn` command.
53+
54+
#### ovpn_disconf
55+
56+
This command deletes your active configuration. **Container restart** is needed for changes to take affect.
57+
58+
```
59+
Usage: ovpn_disconf
60+
```
61+
62+
**NOTE:** This command does not delete PKI.
63+
64+
#### ovpn_enconf
65+
66+
This command enables OpenVPN config based on config example. If config name isn't specified it prints out config list.
67+
68+
```
69+
Usage: ovpn_enconf CONFIG_NAME [wizard args...]
70+
71+
Configs:
72+
<example config name>
73+
```
74+
75+
**Note:** Please read example documentation to understand how to use it.
76+
**Tip:** If you modifed config in a way that others might need same configuration, consider making new example.
77+
78+
#### ovpn_init
79+
80+
This command inits your PKI in `/config/pki` folder. You need to run this command only once.
81+
82+
```
83+
Usage: ovpn_init [nopass]
84+
```
85+
86+
**Note:** Best practise is to use password for your PKI. Password is only needed for signing new certificates (when adding new clients). If you don't want your PKI certificate protected with password, add `nopass` parameter.
87+
**Note:** In this process you need to enter PKI password serveral times, because a lot of things are generated.
88+

‎docs/SetupGuide.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# Setup guide
2+
3+
This is simple setup guide to help you get started. It uses the simplest configuration which works nearly out of the box.
4+
5+
## Steps
6+
7+
1. Init configuration directory with initial config files:
8+
9+
``` bash
10+
# Starts temporary container, soo you will be able to generate intial config files and opens bash shell in container
11+
docker run -it --rm --cap-add NET_ADMIN -v </path/to/config>:/config slocomptech/openvpn:latest bash
12+
```
13+
14+
2. At this point you will have bash shell which runs in container. Now run following commands to **setup your PKI**:
15+
16+
``` bash
17+
ovpn_init [nopass] # Inits PKI
18+
#CA settings are located in /config/ssl/vars
19+
#Did you modified the file or are you planing to enter values interactively ?
20+
#[y/N]: y
21+
#
22+
#init-pki complete; you may now create a CA or requests.
23+
#Generating DH parameters, 2048 bit long safe prime, generator 2
24+
#This is going to take a long time
25+
#.................................
26+
#DH parameters of size 2048 created at /config/pki/dh.pem
27+
#
28+
#Now it will build CA files for issuing new certifiactes
29+
#Please protect ca.key with secure password (used for signing new certs)
30+
#ca.key is needed only for signing new certificates, not for OpenVPN to work
31+
32+
#Using SSL: openssl OpenSSL 1.1.1a 20 Nov 2018
33+
#Enter New CA Key Passphrase: <ENTER SECRET PKI PASSWORD>
34+
#Re-Enter New CA Key Passphrase: <ENTER SECRET PKI PASSWORD>
35+
#Generating RSA private key, 2048 bit long modulus (2 primes)
36+
#...............................+++++
37+
#You are about to be asked to enter information that will be incorporated
38+
#into your certificate request.
39+
#What you are about to enter is what is called a Distinguished Name or a DN.
40+
#There are quite a few fields but you can leave some blank
41+
#For some fields there will be a default value,
42+
#If you enter '.', the field will be left blank.
43+
#-----
44+
#Common Name (eg: your user, host, or server name) [Easy-RSA CA]: <COMMON NAME OF YOUR CA>
45+
#
46+
#CA creation complete and you may now import and sign cert requests.
47+
#
48+
#Generating a RSA private key
49+
#..............+++++
50+
#writing new private key to '/config/pki/private/server.key.osYA8Mim31'
51+
#-----
52+
#Enter pass phrase for /config/pki/private/ca.key: <ENTER SECRET PKI PASSWORD>
53+
#Check that the request matches the signature
54+
#Signature ok
55+
#The Subject's Distinguished Name is as follows
56+
#commonName :ASN.1 12:'server'
57+
#Certificate is to be certified until Mar 4 21:36:34 2022 GMT (1080 days)
58+
#
59+
#Write out database with 1 new entries
60+
#Data Base Updated
61+
#
62+
#You are about to sign the following certificate.
63+
#Please check over the details shown below for accuracy. Note that this request
64+
#has not been cryptographically verified. Please be sure it came from a trusted
65+
#source or that you have verified the request checksum with the sender.
66+
#
67+
#Request subject, to be signed as a server certificate for 1080 days:
68+
#
69+
#subject=
70+
# commonName = server
71+
#
72+
#Type the word 'yes' to continue, or any other input to abort.
73+
# Confirm request details: <YES>
74+
#Enter pass phrase for /config/pki/private/ca.key: <ENTER SECRET PKI PASSWORD>
75+
#Check that the request matches the signature
76+
#Signature ok
77+
#The Subject's Distinguished Name is as follows
78+
#commonName :ASN.1 12:'server'
79+
#The matching entry has the following details
80+
#Type :Valid
81+
#Expires on :220304213634Z
82+
#Serial Number :DA40AFDB4E9D5C1D596BA698A2EBC1BE
83+
#File name :unknown
84+
#Subject Name :/CN=server
85+
#
86+
#Enter pass phrase for /config/pki/private/ca.key: <ENTER SECRET PKI PASSWORD>
87+
#
88+
#An updated CRL has been created.
89+
#CRL file: /config/pki/crl.pem
90+
```
91+
92+
**Note:** You can generate PKI without password, just use `nopass` option.
93+
94+
3. Setup OpenVPN config based on example `basic_nat` with configuration wizard:
95+
96+
``` bash
97+
ovpn_enconf basic_nat
98+
#Protocol udp, tcp, udp6, tcp6 [udp]:
99+
#VPN network [10.0.0.0]:
100+
#Port [1194]:
101+
#Public IP or domain of server: <PUBLIC IP>
102+
#DNS1 [8.8.8.8]:
103+
#DNS2 [8.8.4.4]:
104+
```
105+
106+
**Note:** If you are using this container for production use your Public IP (if you don't know it, check with `whatsmyip` website and make sure it is **static**, for testing purposes at home, you can use local IP).
107+
108+
4. Enable **port forwarding** on your router so OpenVPN server will be accessible from the internet.
109+
5. Add clients to your server
110+
111+
``` bash
112+
# Generates client certificates
113+
ovpn_client add <name> [nopass]
114+
115+
# Generates client config file and prints it to screen (redirect to file)
116+
ovpn_client ovpn <name> > <config file>.ovpn
117+
118+
# OR BETTER SOLLUTION: Run outside container
119+
docker exec -it <container name> ovpn_client ovpn <name> > <config file>.ovpn
120+
```
121+
122+
**Note:** Client config files MUST be transported to your devices via **SECURE** methon such as USB (email is considered **INSECURE**).
123+
124+
5. Exit container with `exit`, then it will destroy itself.
125+
6. Now you can create config file outside container, mentioned above.
126+
7. If you need to access bash shell again (to add another client after server was started) just use `docker exec -it <container name> bash`.
127+
8. Start container using normal command:
128+
129+
``` bash
130+
docker run \
131+
--name=ovpn \
132+
--cap-add NET_ADMIN \
133+
-e PUID=1000 \
134+
-e GUID=1000 \
135+
-p 1194:1194/udp \
136+
-v </path/o/config>:/config \
137+
--restart=unless-stopped \
138+
--network host \
139+
slocomptech/openvpn:latest
140+
```
141+
142+
**Note:** PUID, GUID parameters are optional.
143+
**Note:** Container in this example will connect to host network, so there is less network overhead (recommended), this also works if container is in default docker network.

0 commit comments

Comments
 (0)