Changes between Initial Version and Version 1 of OpenVPN3Linux

Timestamp:

06/03/19 10:03:47 (5 years ago)

Author:

David Sommerseth

Comment:

--

OpenVPN3Linux

@@ +1 @@
+= OpenVPN 3 Linux =
+
+The [https://github.com/OpenVPN/openvpn3-linux/ OpenVPN 3 Linux project] is a new client built on top of the [https://github.com/OpenVPN/openvpn3/ OpenVPN 3 Core Library], which is also used in the various OpenVPN Connect clients and OpenVPN for Android (need to be enabled via the settings page in the app).
+
+This client is built around a completely different architecture in regards to usage.  It builds heavily on D-Bus and allows unprivileged users to start and manage their own VPN tunnels out-of-the box.  System administrators wanting more control can also control and restrict this access both by hardening the default OpenVPN 3 D-Bus policy or facilitating features in OpenVPN 3 Linux.
+
+Even though the project name carries "Linux", it doesn't mean it is restricted to Linux only.  Any platform which has D-Bus available should be capable of running this client in theory.  But since D-Bus is most commonly used in Linux environments, this will naturally be the primary focus for the project.
+
+== Pre-built packages ==
+
+=== Debian, Ubuntu ===
+
+First ensure that your apt supports the https transport:
+{{{
+   # apt install apt-transport-https
+}}}
+Install the OpenVPN repository key used by the OpenVPN 3 Linux packages
+{{{
+   # wget https://swupdate.openvpn.net/repos/openvpn-repo-pkg-key.pub
+   # apt-key add openvpn-repo-pkg-key.pub
+}}}
+Then you need to install the proper repository.  Replace $DISTRO with
+stretch, xenial or bionic, depending on your Debian/Ubuntu distribution.
+{{{
+   # wget -O /etc/apt/sources.list.d/openvpn3.list https://swupdate.openvpn.net/community/openvpn3/repos/openvpn3-$DISTRO.list
+   # apt update
+}}}
+And finally the openvpn3 package can be installed
+{{{
+   # apt install openvpn3
+}}}
+
+=== Fedora, Red Hat Enterprise Linux, CentOS, Scientific Linux ===
+
+Packages for these distributions are provided via a Fedora Copr repository.
+
+If you are running Red Hat Enterprise Linux or its clones, you need to install the yum copr module first.  Fedora releases usually have the dnf copr module preinstalled.
+
+{{{
+   # yum install yum-plugin-copr
+}}}
+
+With the Copr module available, it is time to enable the appropriate OpenVPN 3 Copr repository.  Red Hat Enterprise Linux and clones typically use `yum` while Fedora uses `dnf`.
+{{{
+   # {yum,dnf} copr enable dsommers/openvpn3
+}}}
+
+And then the OpenVPN 3 Linux client can be installed
+{{{
+   # {yum,dnf} install openvpn3-client
+}}}
+
+
+== Quick start - how to use OpenVPN 3 Linux ==
+
+With the openvpn3 packages installed, everything should be ready to be used.  By default any user account on the system should be able to start VPN tunnels.
+
+=== Using `openvpn2`
+
+For users familiar with the classic OpenVPN 2.x command line, the `openvpn2` front-end aims to be fairly close to old behaviour.
+
+{{{
+   $ openvpn2 --config ${MY_CONFIGURATION_FILE} --verb 6
+}}}
+
+Replace ${MY_CONFIGURATION_FILE} with the OpenVPN configuration file you want to use.  If this configuration includes the `--daemon` option, the VPN session will be started in the background and the user is given the command line back again.  To further manage this VPN session, the `openvpn3 session-manage` command line interface must be used.  Without `--daemon` the console will be filled with log data from the VPN session and the session can be disconnected via a simple CTRL-C in the terminal.
+
+For more information, see `openvpn2 --help`, `openvpn3 session-manage --help` as well as the [https://github.com/OpenVPN/openvpn3-linux/blob/master/docs/man/openvpn2.1.rst openvpn2] and [https://github.com/OpenVPN/openvpn3-linux/blob/master/docs/man/openvpn3-session-manage.1.rst openvpn3-session-manage] man pages.
+
+=== Using `openvpn3`
+
+For more advanced usage, the `openvpn3` command line offers a lot more features.  Configuration profiles in OpenVPN 3 Linux are managed by a [https://github.com/OpenVPN/openvpn3-linux/blob/master/docs/man/openvpn3-service-configmgr.8.rst Configuration Manager] before the VPN session is started via the [https://github.com/OpenVPN/openvpn3-linux/blob/master/docs/man/openvpn3-service-sessionmgr.8.rst Session Manager].  The `openvpn3` utility gives access to the features these manager services provides.
+
+==== Starting a one-shot configuration profile
+
+A "one-shot configuration profile" means that the configuration file is parsed, loaded and deleted from the the configuration manage as soon as the VPN session has been attempted started.  No configuration file is available for re-use after this approach.  This is achieved by giving the configuration file to the `openvpn3 session-start` command directly.
+
+{{{
+   $ openvpn3 session-start --config ${MY_CONFIGURATION_FILE}
+}}}
+
+
+==== Importing a configuration file for re-use and starting a VPN session
+
+Using this approach, an imported configuration file can be used several times and access to the configuration file itself is not needed to start VPN tunnels.  By default, configuration profiles imported are only available to the user who imported the configuration file.  But OpenVPN 3 Linux also provides an Access Control List feature via [https://github.com/OpenVPN/openvpn3-linux/blob/master/docs/man/openvpn3-config-acl.1.rst openvpn3 config-acl] to grant access to specific or all users on the system.
+
+{{{
+   $ openvpn3 config-import --config ${MY_CONFIGURATION_FILE}
+}}}
+
+This loads the configuration profile and stores it in memory-only.  That means, if the system is rebooted, the configuration profile is not preserved.  If the `--persistent` argument is added to the command line above, the configuration profile will be saved to disk in a directory only accessible by the `openvpn` user.  Whenever the [https://github.com/OpenVPN/openvpn3-linux/blob/master/docs/man/openvpn3-service-configmgr.8.rst Configuration Manager] is started, configuration files imported with `--persistent` will be automatically loaded as well.
+
+To list all available configuration profiles, run this command:
+
+{{{
+   $ openvpn3 configs-list
+}}}
+
+A configuration file typically contains generic options to be able to connect to a specific server, regardless of the device itself.  OpenVPN 3 Linux also supports setting more host-specific settings on a configuration profile as well.  This is handled via the [https://github.com/OpenVPN/openvpn3-linux/blob/master/docs/man/openvpn3-config-manage.1.rst `openvpn3 config-manage`] interface.  Any settings here will also be preserved across boots if the configuration profile was imported with the `--persistent` argument.
+
+==== Starting a new VPN session from an imported configuration profile
+
+When a configuration profile is available via `openvpn3 configs-list`, it can easily be started via `openvpn3 session-start` using the configuration profile name (typically the filename used during the import)
+
+{{{
+   $ openvpn3 session-start --config ${CONFIGURATION_PROFILE_NAME}
+}}}
+
+or it is possible to use the D-Bus path to the configuration profile:
+
+{{{
+   $ openvpn3 session-start --config-path /net/openvpn/v3/configuration/.........
+}}}
+
+In either of these cases is it necessarily to have access to the configuration profile on disk.  As long as configuration profiles are available via `openvpn3 configs-list`, all needed to start a VPN session should be present.
+
+
+==== Managing a running VPN session
+
+Once a VPN session has started, it should be seen in [https://github.com/OpenVPN/openvpn3-linux/blob/master/docs/man/openvpn3-sessions-list.1.rst `openvpn3 sessions-list`]:
+
+{{{
+   $ openvpn3 sessions-list
+}}}
+
+Using the `openvpn3 session-manage` there are a few things which can be done, but most typically it is the `--disconnect` or `--restart` alternatives which is most commonly used.
+
+{{{
+   $ openvpn3 session-manage --config ${CONFIGURATION_PROFILE_NAME} --restart
+}}}
+
+This disconnects and re-connects to the server again, re-establishing the connection.  The `${CONFIGURATION_PROFILE_NAME}` is the configuration name as displayed in `openvpn3 sessions-list`.  It is also possible to use the D-Bus path to the session as well:
+
+{{{
+   $ openvpn3 session-manage --session-path /net/openvpn/v3/sessions/..... --disconnect
+}}}
+
+This command above will disconnect a running session.  Once this operation has completed, it will be removed from the `openvpn3 sessions-list` overview.
+
+It is also possible to retrieve real-time tunnel statistics from running sessions:
+
+{{{
+   $ openvpn3 session-stats --config ${CONFIGURATION_PROFILE_NAME}
+   $ openvpn3 session-stats --session-path /net/openvpn/v3/sessions/.....
+}}}
+
+And to retrieve real-time log events as they occur, run the [https://github.com/OpenVPN/openvpn3-linux/blob/master/docs/man/openvpn3-log.1.rst `openvpn3 log`] command line below:
+{{{
+   $ openvpn3 log --config ${CONFIGURATION_PROFILE_NAME}
+}}}
+
+This might be quite silent, as it does not provide any log events from the past.  Issue an `openvpn3 session-manage --restart` from a different terminal, and log events will occur.  You may want to boost the log-level with `--log-level 6`.  Valid log levels are from 0 to 6, where 6 is the most verbose.
+
+VPN sessions are also owned by the user which started it.  But the [https://github.com/OpenVPN/openvpn3-linux/blob/master/docs/man/openvpn3-service-sessionmgr.8.rst Session Manager] also provides its own Access Control List feature via [https://github.com/OpenVPN/openvpn3-linux/blob/master/docs/man/openvpn3-session-acl.1.rst `openvpn3 session-acl`].
+
+== Further information
+
+* man pages:
+  - [https://github.com/OpenVPN/openvpn3-linux/blob/master/docs/man/openvpn3-linux.7.rst openvpn3-linux.7] - Main overview
+  - [https://github.com/OpenVPN/openvpn3-linux/blob/master/docs/man/openvpn3.1.rst openvpn3.1] - `openvpn3` command line interface
+  - [https://github.com/OpenVPN/openvpn3-linux/blob/master/docs/man/openvpn2.1.rst openvpn2.1] - `openvpn2` command line interface which is similar to the classic OpenVPN 2.x interface
+  - [https://github.com/OpenVPN/openvpn3-linux/blob/master/docs/man/openvpn3-autoload.8.rst openvpn3-autoload.8] - Automatic load and start of VPN tunnels
+  - [https://github.com/OpenVPN/openvpn3-linux/tree/master/docs/man More man pages]
+
+* Developers / D-Bus API documentation
+  - [https://github.com/OpenVPN/openvpn3-linux/blob/master/docs/dbus/dbus-primer.md D-Bus Primer] - Understanding D-Bus
+  - [https://github.com/OpenVPN/openvpn3-linux/blob/master/docs/dbus/dbus-overview.md OpenVPN 3 D-Bus overview] - Overview of all D-Bus services which are provided and used
+  - [https://github.com/OpenVPN/openvpn3-linux/blob/master/docs/debugging.md Debugging] - How to debug OpenVPN 3 Linux
+  - [https://github.com/OpenVPN/openvpn3-linux/tree/master/docs/dbus More D-Bus documentation]
+