Further expansion and tweaking of Layer 2 OpenVPN doc

diff --git a/docs/Layer_2_OpenVPN.md b/docs/Layer_2_OpenVPN.md
index dbc9b49311337f343723d429c9e0abf17e13586b..a37a11c3e5cfea887e39763cd13828ca4c00ca24 100644 (file)
--- a/docs/Layer_2_OpenVPN.md
+++ b/docs/Layer_2_OpenVPN.md
@@ -14,6 +14,13 @@ they are both on the same Data Link segment (e.g., the same Ethernet
 link). Layer 3 mode is easier to set up, but layer 2 mode is sometimes
 desired to give clients a more direct exposure to services on the LAN.
 
+The scenario we are targeting here is to have:
+
+- An OpenVPN server running on a libreCMC system which can receive
+  traffic from the Internet.
+- An OpenVPN client running on a libreCMC system somewhere else in the
+  Internet. The client can be hidden behind a NAT.
+
 ## Warnings
 
 This information is provided for educational purposes only and is not
@@ -33,12 +40,9 @@ documentation.
 
 In LuCi, select `Network` >> `Interfaces` and then `Add New Interface`.
 
-- Set `Name of the new interface` to `l2server` or anything else you
-  would like.
+- Set `Name of the new interface` to `l2server`.
 - Set `Protocol of the new interface` to unmanaged.
 - Set `Cover the following interface` to `Custom Interface: vpn0`.
-- In my current working system, the `firewall-zone` for the interface
-  is set to `lan`, but I don't think that really matters in this case.
 
 In my working configuration, I added tap0 into the LAN bridge
 interface, and deleted the WAN interface. However, my vpn server is a
@@ -69,8 +73,8 @@ possible to produce more secure certificates using openssl directly.
 build-key l2client
 ```
 
-You can use a different name, but then you have to be consistent in
-adjusting the client config.
+In the server-client configuration we are aiming for here, your client
+key needs to be unencrypted (i.e., not password protected).
 
 ### Server configuration
 
@@ -92,12 +96,12 @@ uci set openvpn.l2server.persist_key='1'
 uci set openvpn.l2server.persist_tun='1'
 uci set openvpn.l2server.user='nobody'
 uci set openvpn.l2server.group='nogroup'
-uci set openvpn.l2server.ca='/etc/easy-rsa/keys/ca.crt'
-uci set openvpn.l2server.cert='/etc/easy-rsa/keys/l2server.crt'
-uci set openvpn.l2server.key='/etc/easy-rsa/keys/l2server.key'
-uci set openvpn.l2server.dh='/etc/easy-rsa/keys/dh2048.pem'
+uci set openvpn.l2server.ca='/etc/openvpn/keys/ca.crt'
+uci set openvpn.l2server.cert='/etc/openvpn/keys/l2server.crt'
+uci set openvpn.l2server.key='/etc/openvpn/keys/l2server.key'
+uci set openvpn.l2server.dh='/etc/openvpn/keys/dh2048.pem'
 uci set openvpn.l2server.tls_server='1'
-uci set openvpn.l2server.tls_auth='/etc/easy-rsa/keys/ta.key 0'
+uci set openvpn.l2server.tls_auth='/etc/openvpn/keys/ta.key 0'
 uci set openvpn.l2server.server_bridge='192.168.1.1 255.255.255.0 192.168.1.201 192.168.1.220'
 uci set openvpn.l2server.client_to_client='1'
 uci set openvpn.l2server.push='persist-key' 'persist-tun' 'redirect-gateway def1'
@@ -107,6 +111,12 @@ uci set openvpn.l2server.verb='3'
 uci commit
 ```
 
+### Firewall
+
+I do not want to describe firewall adjustments in this document, but
+the important point is that your server needs to be able to receive
+UDP packages from the Internet on port 1194.
+
 ## Client Setup and Configuration
 
 This assumes the above configuration for the server.
@@ -118,12 +128,26 @@ This assumes the above configuration for the server.
 
 ### Interface setup
 
-TODO
+In LuCi, select `Network` >> `Interfaces` and then `Add New Interface`.
+
+- Set `Name of the new interface` to `l2server`.
+- Set `Protocol of the new interface` to unmanaged.
+- Set `Cover the following interface` to `Custom Interface: vpn0`.
+
+Adjust the LAN interface so that it bridges over the `vpn0` physical
+interface as well as the default `eth0` and `wlan0` interfaces. This
+is done from the `Network` >> `Interfaces` menu, pressing the `Edit`
+button next to `LAN`, and selecting the `Physical Settings` tab.
 
 ### Certificate and key storage
 
+```
+mkdir -m 700 /etc/openvpn/keys
+```
+
 Client will the need `ca.crt`, `l2client.crt`, `l2client.key', and
-`ta.key` you generated earlier, stored in the /etc/openvpn directory.
+`ta.key` you generated in the server section, stored in the
+`/etc/openvpn/keys` directory.
 
 ### Client configuration
 
@@ -144,11 +168,36 @@ uci set openvpn.l2client.mute_replay_warnings='1'
 uci set openvpn.l2client.key_direction='1'
 uci set openvpn.l2client.redirect_gateway='def1'
 uci set openvpn.l2client.enabled='1'
-uci set openvpn.l2client.ca='/etc/openvpn/ca.crt'
-uci set openvpn.l2client.cert='/etc/openvpn/l2client.crt'
-uci set openvpn.l2client.key='/etc/openvpn/l2client.key'
-uci set openvpn.l2client.tls_auth='/etc/openvpn/ta.key 1'
+uci set openvpn.l2client.ca='/etc/openvpn/keys/ca.crt'
+uci set openvpn.l2client.cert='/etc/openvpn/keys/l2client.crt'
+uci set openvpn.l2client.key='/etc/openvpn/keys/l2client.key'
+uci set openvpn.l2client.tls_auth='/etc/openvpn/keys/ta.key 1'
 uci set openvpn.l2client.mute='15'
 uci set openvpn.l2client.verb='3'
 uci commit
 ```
+
+## Troubleshooting
+
+You are likely to run into one of two issues:
+
+- Either your client or your server is not receiving UDP packets from the other.
+- You have an error in the server or client configurations.
+- There is some problem with the keys or certificates, or they are
+  in the wrong location.
+
+These are some useful tools:
+
+- Without OpenVPN even running, you can use the `nc` program (netcat)
+  to send UDP packets from the client to the server, and then use the
+  `tcpdump` program on the server to see if the UDP packets are
+  arriving at port 1194. The syntax of these programs will not be
+  covered in this document.
+
+- The log output on the server and on the client is very helpful. Run
+  `logread` to view the log or `logread && logread -f` to monitor for
+  log messages. If you find an OpenVPN error, use that in conjunction
+  with the OpenVPN manual page, to figure out what needs to be
+  tweaked.[1]
+
+[1] [https://openvpn.net/index.php/open-source/documentation/manuals.html]
\ No newline at end of file