Skip to content

QUICK-START.md

Latest commit

 

History

History
184 lines (118 loc) · 6.01 KB

QUICK-START.md

File metadata and controls

184 lines (118 loc) · 6.01 KB

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 OpenVPN 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) and openvpn3-session-manage(1) 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), openvpn3-session-start(1), openvpn3-session-manage(1) and openvpn3-config-import(1) man-pages.

Starting VPN tunnels during boot

OpenVPN 3 Linux ships with a openvpn3-session@.service 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) 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) 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 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.