=======================
openvpn3-service-netcfg
=======================

---------------------------------------------
OpenVPN 3 Linux Network Configuration Service
---------------------------------------------

:Manual section: 8
:Manual group: OpenVPN 3 Linux

SYNOPSIS
========
| ``openvpn3-service-netcfg`` ``[OPTIONS]``
| ``openvpn3-service-netcfg`` ``-h`` | ``--help``


DESCRIPTION
===========
The ``openvpn3-service-netcfg`` process is a backend service for OpenVPN 3
Linux, responsible for creating and managing virtual network interfaces, routing
and DNS configuration provided by VPN connections.  This service will be started
automatically when the ``openvpn3-service-client`` starts and begins to
configure a virtual network interface for its session.

Only one network configuration service can run on the system.

This service is normally started automatically when needed, via the
*net.openvpn.v3.netcfg.service* auto-start configuration by the
``dbus-daemon``\(1), but can also be started manually on the command line.  This
service must start as *root*, but as soon as it has requested the needed
privileges for its operations, it will drop the rest of the privileges and
switch to the *@OPENVPN_USERNAME@* user.  Beware that changing this to another
user account also requires updating the D-Bus policy as well.


OPTIONS
=======

-h, --help      Print  usage and help details to the terminal

--version       Prints the version of the program and exists

--log-level LEVEL
                Sets the default log verbosity for log events generated by
                this service.  The default is :code:`4`.  Valid values are
                :code:`0` to :code:`6`.  Higher log levels results in more
                verbose logs and log level :code:`6` will contain all debug
                log events.

--log-file LOG_DESTINATION
                By default, logging will go via the ``openvpn3-service-log``
                service.  By providing this argument, logging will also be sent
                to *LOG_DESTINATION*, which can be either a filename or
                :code:`stdout:` where the latter one sends log data to the
                console.

--colour
                This will add colours to log events when logging to file
                or terminal.  Log events will be coloured based on the log
                level of the event.

--idle-exit MINUTES
                The ``openvpn3-service-netcfg`` service will exit
                automatically if it is being idle for *MINUTES* minutes.  By
                being idle, it means no active virtual network interfaces is
                being managed by this service.

--redirect-method METHOD
                This defines how to handle route configurations which involves
                changing the default gateway.  This primarily controls how
                the network traffic routing is done from the VPN client process
                to the remote server.  Valid *METHOD* arguments:

                :code:`host-route` (default)
                    This will add an explicit direct host route for the VPN
                    server's IP address to go via the default gateway on the
                    system.  This is quite similar to how OpenVPN 2.x behaves.

                :code:`bind-device`
                    This will bind the device using the *SO_BINDDEV* socket option
                    for the UDP/TCP socket used to connect to the remote side.

                :code:`none`
                    This will disable any specific routing arrangement for the
                    remote host access.  If the default gateway is modified, this
                    will most certainly make the VPN connection useless; thus
                    this is not recommended for production.

--set-somark MARK
                This will add a *SO_MARK* based reference to the packets sent
                to the remote server.  This can be used by *netfilters* like
                the ``--mark`` feature in ``iptables``.  This can be used
                by itself or in combination with any ``--redirect-method``
                settings, unless ``openvpn3-service-client`` is started with
                ``--disable-protect-socket``.

--state-dir DIRECTORY
                This option will define a directory where
                ``openvpn3-service-netcfg`` will read configuration data from.
                This configuration file is JSON based and will override the
                options from the command line.

DNS Resolver Configuration
--------------------------
The ``openvpn3-service-netcfg`` service is capable of configuring the DNS
resolver based on what the running VPN sessions have been pushed from the
OpenVPN servers.  The OpenVPN 3 Network Configuration service supports
multiple approaches, but only one of them can be enabled.

--resolv-conf RESOLV-CONF-FILE
         This method will modify the provided *RESOLV-CONF-FILE* directly.
         The file will typically point at :code:`/etc/resolv.conf`.  But
         beware that this approach may not be fail-safe in all scenarios
         and other network service may overwrite changes OpenVPN has
         applied or OpenVPN may overwrite changes outside of its control.

         OpenVPN will keep a backup file when it has modified it and will
         automatically restore the content when no running OpenVPN sessions
         has received any DNS configurations.

--systemd-resolved
         This will enable integration with the `systemd-resolved`\(8)
         service.  The system must be preconfigured to use this service
         for OpenVPN's changes to fully take effect.  This is the
         preferred way, as the DNS resolver settings are fully managed
         by `systemd-resolved`\(8).  This approach will currently
         enable split-DNS by default.


Configuration file
------------------
The default location for the configuration file is under
:code:`@OPENVPN_STATEDIR@`.  This is a plain JSON configuration file which
only considers a few fields:
::

        {
                "log_level": LEVEL,
                "log_file": FILENAME,
                "idle_exit": MINUTES,
                "resolv_conf_file": FILENAME,
                "systemd_resolved": "",
                "redirect_method": ["host-route" | "bind-device" | "none" ],
                "set_somark": MARK
         }

Only used settings need to be present.  If not set, the command line options
will be able to set these options.

Attribute: log_level
""""""""""""""""""""
This is the equivalent of the ``--log-level`` command line argument.  Valid
``LEVEL`` values are :code:`0` to :code:`6`.

Attribute: log_file
"""""""""""""""""""
This is the equivalent of the ``--log-file`` command line argument.  Must
be a filename where to write log files.  It also supports :code:`stdout:` to
write log data to the console/tty.  Logging will also be sent to the
``openvpn3-service-log``\(8) service regardless of this setting.

Attribute: idle_exit
""""""""""""""""""""
This is the equivalent of the ``--idle-exit`` command line argument.  This
overrides the default automatic exit logic.  The argument it takes is a
positive integer of how many minutes it will be allowed to run idle, not
managing any OpenVPN network devices before it shuts down automatically.

Attribute: resolv_conf_file
"""""""""""""""""""""""""""
This is used to enable the :code:`resolv.conf` DNS resolver configuration
integration.  See ``--resolv-conf``  for details.

Attribute: systemd_resolved
"""""""""""""""""""""""""""
This is used to enable the ``systemd-resolved``\(8) DNS resolver configuration
integratoin.  See ``--systemd-resolved`` for details.

Attribute: redirect_method
""""""""""""""""""""""""""
This is the equivalent of the ``--redirect-method`` option.  See that option
for details.

Attribute: set_somark
"""""""""""""""""""""
This is the equivalent of ``--set-somark``.  See that option for details.


SEE ALSO
========

``dbus-daemon``\(1)
``openvpn3``\(1)
``openvpn3-service-client``\(8)
``openvpn3-service-log``\(8)
