From 93d67a0d32b2c7da7220563e77f219e0429594a3 Mon Sep 17 00:00:00 2001
From: Fulvio Galeazzi <fulvio.galeazzi@garr.it>
Date: Fri, 27 Mar 2020 18:37:56 +0100
Subject: [PATCH] 2020-03-27: Update README.md
---
README.md | 127 +++++++++++++++++++++++++++++++++++++++---------------
1 file changed, 93 insertions(+), 34 deletions(-)
diff --git a/README.md b/README.md
index 303b88c..e30d425 100644
--- a/README.md
+++ b/README.md
@@ -2,28 +2,29 @@ SetupOpenVPN
============
This package sets up:
- * an OpenVPN server, called `openvpn` in the following
- * a machine acting as CA authority, based on EasyRSA, called `authca` in the following
+ * an OpenVPN server, called *openvpn* in the following,
+ * a machine acting as CA authority, based on EasyRSA, called *authca* in the following
-Pre-requisite
--------------
+All configuration takes place from *localhost* which is assumed to *openvpn*:
+this is where `ansible` commands are run.
-Ensure `ansible` is installed on both `openvpn` and `authca`, by executing:
- ```
- apt install ansible
- ```
+These instructions assume that *openvpn* and *authca* are both Ubuntu 18.04 servers
+and were installed with no direct `root` access but rather with a generic user
+(`ubuntu`, in this tutorial) with `sudoer` capability: login to these servers is
+only allowed by using a SSH key (same one, on both servers).
-These instructions assume that `openvpn` and `authca` were both installed with no
-direct `root` access but rather with a generic user (`ubuntu`, in this tutorial) with
-`sudoer` capability: login to these servers is only allowed by using a SSH key (same
-one, on both servers).
We also assume that:
- * `openvpn` has a public IP address (`1.2.3.4`) as well as a private address
+ * *openvpn* has a public IP address (`1.2.3.4`) as well as a private address
`10.9.8.8`
- * `authca` has only a private address `10.9.8.7`
+ * *authca* has only a private address `10.9.8.7`
+
+
+Step 0: repeat each time
+------------------------
+
+To avoid copying the installation SSH key around, we use `ssh-agent` to
+enable safer login to (*openvpn* and) *authca*.
-To avoid storing the installation SSH key to `openvpn`, we will use `ssh-agent` to
-enable safer login to `authca`.
From your client machine, execute the following:
```
eval "$(ssh-agent)"
@@ -32,33 +33,44 @@ From your client machine, execute the following:
ssh -A ubuntu@openvpn # you should not be prompted for password/passphrase
```
-Now, on `openvpn`, verify your agent has the required identity loaded:
+Now, on *openvpn*, verify your agent has the required identity loaded:
```
ssh-add -L
```
-You should now be able to log into `authca` with:
+You should now be able to log into *authca* with:
```
ssh ubuntu@authca
```
-Bootstrap Ansible configuration
--------------------------------
-This step will:
+Step 1: pre-requisite (execute once)
+------------------------------------
+
+Ensure `ansible` is installed on both *openvpn* and *authca*, by logging in on
+each one and executing:
+ ```
+ sudo apt update ; sudo apt install ansible
+ ```
+
+Step 2: Bootstrap Ansible configuration (execute once)
+------------------------------------------------------
+
+This step needs to be executed just once:
* create a generic `ansible` user
- * for such user, create `~/.ssh/authorized_keys` from keys stored by SSH-Agent on localhost (`ssh-add -L`)
+ * for such user, create `~/.ssh/authorized_keys` appending keys stored by SSH-Agent on localhost (`ssh-add -L`)
* grant "sudo" privileges
-
Execute the command (note that we override `ansible_user` with the `-e` switch,
so it matches the generic user created during server installation):
```
ansible-playbook -e "ansible_user=ubuntu" -v -i inventory.yml playbooks/bootstrapconfig.yml
```
-Installation and Configuration
-------------------------------
+Step 3: Installation and Configuration (execute once)
+-----------------------------------------------------
+
+This step, too, will normally be ran just once: unless the configuration changes.
Inspect file `group_vars/authca` and change relevant information, to match
your organization (country, province, city, organization name, email, organization unit).
@@ -71,20 +83,67 @@ Execute the `setup.yml` playbook:
```
which will take care of:
- * installing some useful packages (see list in file `roles/setup/vars/Debian.yml`), as well as `openvpn` and `easyRSA`
- (this latter, by cloning the Git repository).
- * on *authca*: create EasyRSA vars file, out of dictionary in `group_vars/authca`
- * execute `./easyrsa init`
- * on *authca*: execute `./easyrsa build-ca nopass`
+ * installing some useful packages (see list in file `roles/setup/vars/Debian.yml`),
+ as well as *openvpn* and *easyRSA* (this latter, by cloning the Git repository);
+ * on *authca*: create EasyRSA vars file, and initializa the CA, create ca.crt file
+ * on *openvpn*: prepare request
+ * sign *openvpn* request and return certificate and other relevant files
+ * on *openvpn*: create other important files (dh.pem, ta.key)
+ * on *openvpn*: configure sysctl and ufw firewall
+
+At this point, both servers are ready to process client certificates.
+
+
+Step 4: Client Configuration
+----------------------------
+
+Repeat this step each time you need to issue a new client configuration file
+for OpenVPN (.ovpn file). The .ovpn file is self-contained, namely it includes
+all required files (ca.crt, dh.pem, ta.key).
+
+
+### Step 4a: Update Ansible configuration
+
+Open `group_vars/openvpn` and add a stanza to `clientconfig.clients`.
+In the following example we are adding a stanza for a configuration for `misterX`:
+ ```
+ ...
+ clientconfig:
+ ...
+ clients:
+ ...
+ - misterX:
+ nameshort: misterXcfg
+ CommonName: '"Certificate for Mister X"'
+ ```
+
+Note that:
+* `nameshort` should not contain blanks
+* `CommonName` is enclosed in single and double quotes
+
+
+### Step 4b: Generate client certificate
+
+Execute the `setup.yml` playbook:
+ ```
+ ansible-playbook -v -i inventory.yml playbooks/clientsetup.yml
+ ```
+
+which will take care of:
+ * creating the request and transferring to *authca*
+ * signing the request and copying the `.crt` file back to localhost
+ * assemble the `.ovpn` file
-At this point, you have created the CA.crt and CA.key files on `authca`.
+Step 5: Time to enjoy your VPN
+------------------------------
-...
+Configuration files for OpenVPN were created on your machine, under
+`<clientconfig.cfghome>/files`
+(please ignore the `.part` files).
-to be continued
+Distribute the `.ovpn` files to your colleagues and enjoy!
-...
License
--
GitLab