Quick Start
===========

This gives a quick introduction to a few key components of OpenVPN 3 Linux.
This guide expects OpenVPN 3 Linux to be already installed.


Initial setup
-------------

If you are installing OpenPVN 3 from source code, it is recommended to
run this command first as `root`:

      # openvpn3-admin init-config  --write-configs

This command will probe your system to see if it is ready to run
OpenVPN 3 Linux and ensure some of the backend services are configured
to use `systemd` services on your system if they are available.


Using the `openvpn2` front-end
-----------------------------------------

The `openvpn2` front-end is a command line interface which tries to be
similar to the classic OpenVPN 2.x generation.  It supports most of the
options used by clients and will ignore unsupported options which does not
impact the ability to get a connection running.

* Starting a VPN session:

      $ openvpn2 --config my-vpn-config.conf

If the provided configuration contains the `--daemon` option, it will
provide the session path related to this session and return to the command
line again.  From this point of, this session needs to be managed via the
`openvpn3` front-end.

For more information, see the [`openvpn2(1)`](docs/man/openvpn2.1.rst) and
[`openvpn3-session-manage(1)`](docs/man/openvpn3-session-manage.1.rst)
man-pages.


Using the openvpn3 front-end
----------------------------

The `openvpn3` program is the main and preferred command line user interface.

* Starting a VPN session: Single-shot approach

      $ openvpn3 session-start --config my-vpn-config.conf

  This will import the configuration and start a new session directly

* Starting a VPN session: Multi-step approach

  1. Import the configuration file:

         $ openvpn3 config-import --config my-vpn-config.conf

      This will return a configuration path.  This path is a unique reference
      to this specific configuration profile.

  2. (Optional) Display all imported configuration profiles

         $ openvpn3 configs-list

  3. Start a new VPN session

         $ openvpn3 session-start --config my-vpn-config.conf

     or

         $ openvpn3 session-start --config-path /net/openvpn/v3/configuration/d45d4263x42b8x4669xa8b2x583bcac770b2

* Listing established sessions

         $ openvpn3 sessions-list

* To retrieve real-time log events of VPN sessions

         $ openvpn3 log --config my-vpn-config.conf

     or

         $ openvpn3 log --interface tun0

     or

         $ openvpn3 log --session-path /net/openvpn/v3/sessions/b2b3f4afs4576s4d5es97abs17da6fe9b08f

* Getting tunnel statistics
  For already running tunnels, it is possible to extract live statistics
  of each VPN session individually

      $ openvpn3 session-stats --config my-vpn-config.conf

    or

      $ openvpn3 session-stats --interface tun0

    or

      $ openvpn3 session-stats --path /net/openvpn/v3/sessions/46fff369sd155s41e5sb97fsbb9d54738124

* Managing VPN sessions
  For running VPN sessions, you manage them using the
  `openvpn3 session-manage` command, again by providing the session path.  For
  example, to restart a connection:

      $ openvpn3 session-manage --config my-vpn-config.conf --restart

    or

      $ openvpn3 session-manage --interface tun0 --restart

    or

      $ openvpn3 session-manage --path /net/openvpn/v3/sessions/46fff369sd155s41e5sb97fsbb9d54738124 --restart

  Other actions can be `--pause`, `--resume`, and `--disconnect`.

All the `openvpn3` operations are also described via the `--help` option.

       $ openvpn3 --help
       $ openvpn3 session-start --help


For more information, see the [`openvpn3(1)`](docs/man/openvpn3.1.rst),
[`openvpn3-session-start(1)`](docs/man/openvpn3-session-start.1.rst),
[`openvpn3-session-manage(1)`](docs/man/openvpn3-session-manage.1.rst) and
[`openvpn3-config-import(1)`](docs/man/openvpn3-config-import.1.rst) man-pages.


Starting VPN tunnels during boot
--------------------------------

OpenVPN 3 Linux ships with a [`openvpn3-session@.service`](docs/man/openvpn3-systemd.8.rst)
service unit file to manage VPN sessions via systemd.  This approach
requires configuration profiles to be imported as a persistent
configuration first.  See the
[`openvpn3-systemd(8)`](docs/man/openvpn3-systemd.8.rst) man page for
details.

**NOTE**:
      The `openvpn3-session@.service` unit file approach is **not**
      available on Red Hat Enterprise Linux 7 and clones, due to
      no available `python3-systemd` package.

Alternatively the older `openvpn3-autoload` utility can be used to pre-load
configuration profiles and possibly also start tunnels.  This requires a
little bit of preparations.  When starting it via
`systemctl start openvpn3-autoload` it will look for configuration profiles
found inside `/etc/openvpn3/autoload` which has a corresponding `.autoload`
configuration present in addition.  This tells both the Configuration
Manager and Session Manager how to process the VPN configuration profile.
For more details, look at the [`openvpn3-autoload(8)`](docs/man/openvpn3-autoload.8.rst)
man-page.

**NOTE**:
      The `openvpn3-autoload` utility is deprecated.  If you have a
      Linux distribution supporting `openvpn3-session@.service` you should
      use that instead.


Troubleshooting
---------------

If OpenVPN 3 Linux fails to start a VPN session, please test with this
command:

     # openvpn3-admin version --services

This should produce the same version string for all services.  If some
of them fails to start, some Linux installations might not have the
`sssd` or `nscd` service running.  Often the `net.openvpn.v3.netcfg`
service (provided  by `openvpn3-service-netcfg`) fails to start properly.
If your system is configured to use `sssd`, please read the comments in
`/etc/nsswitch.conf` carefully if you want to try to start `nscd`.

It is also recommended to run the
[`openvpn3-admin init-config`](docs/man/openvpn3-admin-init-config.8.rst.in)
utility.  This tool will check that the base installation is reasonably set up.
It will not change any configuration settings by default, so it is safe to run
this more times.