Merge ~gary-wzl77/snappy-hwe-snaps/+git/easy-openvpn:documentation into ~snappy-hwe-team/snappy-hwe-snaps/+git/easy-openvpn:master

Proposed by Gary.Wang on 2017-09-13
Status: Merged
Approved by: Simon Fels on 2017-09-25
Approved revision: 9dc513530e161bd28b7b6f39e8a35e81682cdaef
Merged at revision: 42e9fedde8a65b8e6fda9f838cfb1f62926c0f52
Proposed branch: ~gary-wzl77/snappy-hwe-snaps/+git/easy-openvpn:documentation
Merge into: ~snappy-hwe-team/snappy-hwe-snaps/+git/easy-openvpn:master
Diff against target: 463 lines (+388/-0)
11 files modified
README.md (+2/-0)
docs/faq.md (+26/-0)
docs/index.md (+17/-0)
docs/installation.md (+33/-0)
docs/metadata.yaml (+29/-0)
docs/openvpn-client-setup.md (+24/-0)
docs/openvpn-server-setup.md (+39/-0)
docs/reference/commands.md (+112/-0)
docs/reference/snap-configuration/snap-configuration.md (+64/-0)
docs/release-notes.md (+20/-0)
docs/report-bug.md (+22/-0)
Reviewer Review Type Date Requested Status
Jim Hodapp (community) 2017-09-13 Approve on 2017-09-22
System Enablement Bot continuous-integration Approve on 2017-09-22
Alfonso Sanchez-Beato 2017-09-13 Approve on 2017-09-14
Review via email: mp+330648@code.launchpad.net

Commit message

Follow the guidelines to do the documentation.

*. A general introduction to the easy-openvpn snap
*. A typical guide to the OpenVPN server and client setup
*. A listing of available commands with a brief description of each of the commands

Description of the change

Follow the guidelines to do the documentation.

*. A general introduction to the easy-openvpn snap
*. A typical guide to the OpenVPN server and client setup
*. A listing of available commands with a brief description of each of the commands

To post a comment you must log in.

Some comments, see below.

review: Needs Fixing
Simon Fels (morphis) wrote :

First set of comments.

Gary.Wang (gary-wzl77) :

LGTM

review: Approve

PASSED: Successfully build documentation, rev: a1ade3ae4e4cc014767ade15c39034a7f5119b7c

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/534/

PASSED: Successfully build documentation, rev: a1ade3ae4e4cc014767ade15c39034a7f5119b7c

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/536/

PASSED: Successfully build documentation, rev: a1ade3ae4e4cc014767ade15c39034a7f5119b7c

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/537/

Jim Hodapp (jhodapp) wrote :

Looking good. Some notes:

1. I'd like to see the MR description/commit message say something about what this MR is for and what it covers. The current message doesn't really tell me much.

2. Some things to fix below. Let me know if any of the suggestions aren't clear. I used the standard ed syntax.

Gary.Wang (gary-wzl77) wrote :

Thanks for this! I left a few comments below.
Please take a look.

PASSED: Successfully build documentation, rev: e8fd770d87257cb6fea20d22050851ffda4f3f07

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/568/

Jim Hodapp (jhodapp) wrote :

Some more things to fix up below.

review: Needs Fixing

PASSED: Successfully build documentation, rev: 9dc513530e161bd28b7b6f39e8a35e81682cdaef

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/581/

Jim Hodapp (jhodapp) wrote :

LGTM!

review: Approve

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1diff --git a/README.md b/README.md
2index e5c7630..b37559f 100644
3--- a/README.md
4+++ b/README.md
5@@ -62,6 +62,8 @@ we could reload the snap manually with the following commands:
6 Add a client and enter the same passphrase you set during setup above. Use the
7 .ovpn file to connect to your VPN server.
8
9+ $ sudo easy-openvpn.connect-server <my-config>.ovpn
10+
11 ## Manage
12
13 ### List clients
14diff --git a/docs/faq.md b/docs/faq.md
15new file mode 100644
16index 0000000..85fa927
17--- /dev/null
18+++ b/docs/faq.md
19@@ -0,0 +1,26 @@
20+---
21+title: "FAQ"
22+table_of_contents: True
23+---
24+
25+# FAQ
26+
27+This section covers frequently asked questions related to configuring and using the easy-openvpn snap.
28+
29+## Why do I get the error `Error opening configuration file: foo.ovpn` when running connect-server to connect to the OpenVPN server?
30+
31+The problem is possibly caused by insufficient permissions. When you encounter this problem:
32+1. Please first check if you ran the easy-openvpn.connect-server with sudo.
33+2. As elaborated in [OpenVPN Client Setup](openvpn-client-setup.md), you need to connect the home plug
34+ if you put the ovpn file into your HOME directory. Moreover, you need to change the owner of the ovpn file to
35+ root, otherwise you will probably encounter the following issue: [dac_override denied](https://forum.snapcraft.io/t/docker-load-fails-with-permission-denied/1227/3)
36+
37+## Why no Internet access even after a connection to OpenVPN is established?
38+
39+This means you probably didn't reroute traffic to the right network interface.
40+The default NAT device OpenVPN server relies on to route all traffic through OpenVPN is 'eth0'.
41+When you connected to a wireless network, the active network interface should have been changed to 'wlan0' or others.
42+You need to configure it accordingly before launching the OpenVPN server.
43+Please check here for more details [OpenVPN Server Setup](openvpn-server-setup.md)
44+
45+**NOTE:** Remember to reload the snap to take effect after you changed NAT device.
46diff --git a/docs/index.md b/docs/index.md
47new file mode 100644
48index 0000000..3240531
49--- /dev/null
50+++ b/docs/index.md
51@@ -0,0 +1,17 @@
52+---
53+title: "Overview"
54+table_of_contents: True
55+---
56+
57+# Overview
58+
59+The easy-openvpn snap is designed to be deployed with as little configuration
60+and setup as possible for spot deployment of secure yet disposable OpenVPN instances.
61+It's developed based on the [docker-openvpn](https://github.com/kylemanna/docker-openvpn) project.
62+
63+
64+This snap contains management scripts that simplify [PKI](https://openvpn.net/index.php/open-source/documentation/howto.html#pki) and client management for fast, cheap and disposable VPNs.
65+
66+* A single command to set up the server, create/revoke clients.
67+* A single command to connect to the server.
68+* Easy to configure and manage.
69diff --git a/docs/installation.md b/docs/installation.md
70new file mode 100644
71index 0000000..448e787
72--- /dev/null
73+++ b/docs/installation.md
74@@ -0,0 +1,33 @@
75+---
76+title: "Installation"
77+table_of_contents: True
78+---
79+
80+# Installation
81+
82+To install the latest stable release of easy-openvpn from the Ubuntu store:
83+
84+```
85+ $ snap install easy-openvpn
86+```
87+
88+All necessary plugs and slots will be automatically connected upon
89+installation, except the home plug. You can verify this with:
90+
91+```
92+$ snap interfaces
93+Slot Plug
94+[...]
95+:network easy-openvpn
96+:network-bind easy-openvpn
97+[...]
98+:firewall-control easy-openvpn
99+:network-control easy-openvpn
100+```
101+
102+You probably need to connect the home plug manually if you copy the client
103+ovpn file to your home directory and connect the client to server with it.
104+
105+```
106+$ snap connect easy-openvpn:home :home
107+```
108diff --git a/docs/media/logo.png b/docs/media/logo.png
109new file mode 100644
110index 0000000..caa06d1
111Binary files /dev/null and b/docs/media/logo.png differ
112diff --git a/docs/metadata.yaml b/docs/metadata.yaml
113new file mode 100644
114index 0000000..d8ac8aa
115--- /dev/null
116+++ b/docs/metadata.yaml
117@@ -0,0 +1,29 @@
118+site_title: easy-openvpn documentation
119+site_logo_url: https://assets.ubuntu.com/v1/c5cb0f8e-picto-ubuntu.svg
120+navigation:
121+ - title: Introduction
122+ children:
123+ - title: About easy-openvpn
124+ location: index.md
125+ - title: Install & Setup
126+ children:
127+ - title: Install easy-openvpn
128+ location: installation.md
129+ - title: OpenVPN server Setup
130+ location: openvpn-server-setup.md
131+ - title: OpenVPN client Setup
132+ location: openvpn-client-setup.md
133+ - title: Reference
134+ children:
135+ - title: Commands
136+ location: reference/commands.md
137+ - title: Snap Configuration
138+ location: reference/snap-configuration/snap-configuration.md
139+ - title: Troubleshoot
140+ children:
141+ - title: FAQ
142+ location: faq.md
143+ - title: Release notes
144+ location: release-notes.md
145+ - title: Report a Bug
146+ location: report-bug.md
147diff --git a/docs/openvpn-client-setup.md b/docs/openvpn-client-setup.md
148new file mode 100644
149index 0000000..97edd6a
150--- /dev/null
151+++ b/docs/openvpn-client-setup.md
152@@ -0,0 +1,24 @@
153+---
154+title: "OpenVPN client setup"
155+table_of_contents: True
156+---
157+
158+# Generate client ovpn file
159+
160+Firstly, you need to add a client credential on the server side and copy the generated ovpn file to the clients.
161+
162+ $ sudo easy-openvpn.add-client foo > foo.ovpn
163+
164+Most users simply copy the .ovpn client config file to their home directory and
165+connect to the server directly. Unfortunately, the connection won't be established
166+due to the strict confinement. You need to connect to the home plug as follows:
167+
168+ $ snap connect easy-openvpn:home :home
169+
170+# Launch OpenVPN client
171+
172+On the client side, please connect to your VPN server with the generated .ovpn file.
173+
174+ $ sudo easy-openvpn.connect-server foo.ovpn
175+
176+Once a connection is established, the output should end with the `Initialization Sequence Completed` message.
177diff --git a/docs/openvpn-server-setup.md b/docs/openvpn-server-setup.md
178new file mode 100644
179index 0000000..b633fdf
180--- /dev/null
181+++ b/docs/openvpn-server-setup.md
182@@ -0,0 +1,39 @@
183+---
184+title: "OpenVPN server setup"
185+table_of_contents: True
186+---
187+
188+# Enable IP forwarding
189+
190+First we need to be sure that IP forwarding is enabled.
191+**Note:** On Ubuntu Core, IP forwarding is disabled by default.
192+
193+ $ sudo sysctl -w net.ipv4.ip_forward=1
194+
195+# Set NAT device as needed
196+
197+If the Internet connection is over ethernet, you can skip NAT device setup since the default NAT device value
198+is 'eth0'. While a wireless connection is established, you need to set it to 'wlan0' accordingly.
199+**Note:** This fits the scenario where people usually set up a wireless connection via console-conf
200+on Ubuntu Core during the first boot.
201+
202+ $ sudo snap set easy-openvpn natdevice=wlan0
203+
204+# Launch OpenVPN server
205+
206+Set up an OpenVPN server with a host machine IP address:
207+
208+ $ sudo easy-openvpn.setup -u udp://<public ip>
209+
210+You'll be prompted to set a passphrase for your CA. This passphrase will be used to create clients later.
211+Then start an OpenVPN server with the following command:
212+
213+ $ sudo service snap.easy-openvpn.easy-openvpn start
214+
215+Beginning with snapd 2.26.9, snapd can currently take connections of interfaces dynamically
216+and update the mount namespaces of the snap in-place without any processes
217+restarting or any other change after connecting interfaces above. But to be safe,
218+the snap can be reloaded manually with the following commands:
219+
220+ $ sudo disable easy-openvpn
221+ $ sudo enable easy-openvpn
222diff --git a/docs/reference/commands.md b/docs/reference/commands.md
223new file mode 100644
224index 0000000..3c953c9
225--- /dev/null
226+++ b/docs/reference/commands.md
227@@ -0,0 +1,112 @@
228+---
229+title: Available Commands
230+table_of_contents: true
231+---
232+
233+# Available Commands
234+
235+The easy-openvpn snap is developed based on OpenVPN. OpenVPN itself
236+provides a lot of options to configure servers and clients. In order to make life easier
237+for end users to deploy an OpenVPN server, the easy-openvpn snap offers a few command line tools which cover
238+most commonly used scenarios to manage the OpenVPN service, such as the setup server, create/revoke
239+client ovpns and so on. This section walks you through a brief introduction to each command.
240+
241+## easy-openvpn.setup
242+
243+The *easy-openvpn.setup* command helps to quickly set up an OpenVPN server.
244+It offers a bunch of arguments to set up an OpenVPN server.
245+
246+``` bash
247+Usage: easy-openvpn.setup [-d]
248+ -u SERVER_PUBLIC_URL
249+ [-e EXTRA_SERVER_CONFIG ]
250+ [-E EXTRA_CLIENT_CONFIG ]
251+ [-f FRAGMENT ]
252+ [-n DNS_SERVER ...]
253+ [-s SERVER_SUBNET]
254+
255+optional arguments:
256+ -2 Enable two factor authentication using Google Authenticator.
257+ -a Authenticate packets with HMAC using the given message digest algorithm (auth).
258+ -b Disable 'push block-outside-dns'
259+ -c Enable client-to-client option
260+ -C A list of allowable TLS ciphers delimited by a colon (cipher).
261+ -d Disable default route
262+ -D Do not push dns servers
263+ -k Set keepalive. Default: '10 60'
264+ -m Set client MTU
265+ -N Configure NAT to access external server network
266+ -t Use TAP device (instead of TUN device)
267+ -T Encrypt packets with the given cipher algorithm instead of the default one (tls-cipher).
268+ -z Enable comp-lzo compression.
269+```
270+
271+And the easiest way to set up an OpenVPN server is as follows:
272+
273+```
274+$ easy-openvpn.setup -u udp://server_public_ip_address
275+```
276+
277+## easy-openvpn.add-client
278+
279+The *easy-openvpn.add-client* command helps to add a user to OpenVPN server.
280+The output for this command contains a piece of user configuration file(ovpn) which can be used when
281+connecting to the OpenVPN server with the OpenVPN client.
282+
283+```
284+$ easy-openvpn.add-client foo > foo.ovpn
285+```
286+
287+## easy-openvpn.clients
288+
289+The *easy-openvpn.clients* command helps to view the clients list. The list records a client's name,
290+start and end time of connection establishment, as well as client's status.
291+
292+```
293+$ easy-openvpn.clients
294+```
295+
296+## easy-openvpn.revoke-client
297+
298+The *easy-openvpn.revoke-client* command helps to revoke a client credentials.
299+**NOTE**: even if a client is revoked, the relevant information is still kept in the client list.
300+You are not able to create another client with the same client name.
301+
302+```
303+$ easy-openvpn.revoke-client foo
304+```
305+
306+## easy-openvpn.show-client
307+
308+The *easy-openvpn.show-client* command helps to show a client's credentials (ovpn).
309+
310+```
311+$ easy-openvpn.show-client foo
312+```
313+
314+
315+## easy-openvpn.connect-server
316+
317+The *easy-openvpn.connect-server* command helps to establish an OpenVPN connection.
318+It uses an .ovpn file as client credentials to connect to a remote OpenVPN server.
319+
320+```
321+$ easy-openvpn.connect-server foo.ovpn
322+```
323+
324+## easy-openvpn.status
325+
326+The *easy-openvpn.status* command helps to show the OpenVPN server's current status.
327+The output includes the OpenVPN client list, routing tables and global stats.
328+
329+```
330+$ easy-openvpn.status
331+```
332+
333+## easy-openvpn.help
334+
335+The *easy-openvpn.help* command helps to view all snap-specific configurations.
336+
337+```
338+$ easy-openvpn.help
339+```
340diff --git a/docs/reference/snap-configuration/snap-configuration.md b/docs/reference/snap-configuration/snap-configuration.md
341new file mode 100644
342index 0000000..78d1035
343--- /dev/null
344+++ b/docs/reference/snap-configuration/snap-configuration.md
345@@ -0,0 +1,64 @@
346+---
347+title: "Snap Configuration"
348+table_of_contents: False
349+---
350+
351+# Snap Configuration
352+
353+Besides the configuration offered by upstream, the easy-openvpn snap provides a
354+simple set of snap configuration items that can be changed through the *snap set* system
355+command.
356+
357+The available configuration items are documented in the following sections.
358+
359+## debug
360+
361+The *debug* option allows running easy-openvpn subcommands in verbose logging mode.
362+
363+Possible values are:
364+
365+ * *0 (default):* disable verbose logging mode when runnning easy-openvpn subcommands
366+ * *1:* enable verbose logging mode when runnning easy-openvpn subcommands
367+
368+Example:
369+
370+```
371+$ snap set easy-openvpn debug=1
372+```
373+
374+## nopasswd
375+
376+The *nopasswd* option allows a user to generate a private key without a passphrase during server setup.
377+Normally, a user should always generate private key with a passphrase for security reasons.
378+This value is only used to setup an OpenVPN server in non-interactive mode for running spread test.
379+
380+Possible values are:
381+
382+ * *0 (default):* Disable passphrase-less mode. A passphrase is required to generate private key
383+ * *1:* Enable passphrase-less mode. This will result in configuring server in non-interactive mode
384+
385+Example:
386+
387+```
388+$ snap set easy-openvpn nopasswd=1
389+```
390+
391+## natdevice
392+
393+
394+The *natdevice* option allows to specify the active network interface for traffic rerouting on an OpenVPN server.
395+If the Internet connection is over ethernet, you can skip natdevice setup since the default natdevice value is 'eth0'.
396+While a wireless connection is established, you need to set it to 'wlan0' accordingly.
397+Note: This fits the scenario where users typically set up a wireless connection on Ubuntu Core at the first boot.
398+
399+Possible values are:
400+
401+ * *eth0 (default):* Default active network interface for ethernet connection
402+ * *wlan0:* active network interface for a wireless connection if you connect to wireless network
403+ You need to change it to decent network interface name if you connect to different network
404+
405+Example:
406+
407+```
408+$ snap set easy-openvpn natdevice=wlan0
409+```
410diff --git a/docs/release-notes.md b/docs/release-notes.md
411new file mode 100644
412index 0000000..63e7a98
413--- /dev/null
414+++ b/docs/release-notes.md
415@@ -0,0 +1,20 @@
416+---
417+title: "Release Notes"
418+table_of_contents: True
419+---
420+
421+# Release Notes
422+
423+The version numbers mentioned on this page correspond to those released in the
424+Ubuntu snap store.
425+
426+## 2.3.10-2
427+
428+ * Refactor to follow the upstream to get server setup scripts
429+ * Add spread tests
430+ * Add three commands [revoke-client, connect-server, help]
431+ * Support hooks to set env variables
432+
433+## 2.3.10-1
434+
435+ * Disable user and group setup for OpenVPN server to overcome strict confinement issue.
436diff --git a/docs/report-bug.md b/docs/report-bug.md
437new file mode 100644
438index 0000000..14bf5a1
439--- /dev/null
440+++ b/docs/report-bug.md
441@@ -0,0 +1,22 @@
442+---
443+title: "Report a Bug"
444+table_of_contents: False
445+---
446+
447+# Rebort a Bug
448+
449+Bugs can be reported [here](https://bugs.launchpad.net/snappy-hwe-snaps/+filebug).
450+
451+When submitting a bug report, please attach a copy of the system log of OpenVPN server:
452+
453+```
454+$ journalctl --no-pager -u snap.easy-openvpn.easy-openvpn
455+```
456+
457+And the output of the following three commands:
458+
459+```
460+$ easy-openvpn.connect-server foo.ovpn
461+$ easy-openvpn.status
462+$ easy-openvpn.clients
463+```

Subscribers

People subscribed via source and target branches

to all changes: