---
name: "openvpn3-service-netcfg"
section: "8"
platform: "linux"
package: "openvpn3-client"
version: "24.1+dfsg-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/openvpn3-service-netcfg"
---

# openvpn3-service-netcfg(8)

OpenVPN 3 Linux Network Configuration Service

## NAME

openvpn3-service-netcfg - OpenVPN 3 Linux Network Configuration Service

## 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)](/dbus-daemon/1.md), 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* 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 **4**.  Valid values are **0** to **6**.  Higher log levels results in more verbose logs and log level **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 **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.

- **--signal-broadcast**

  Normally, the **openvpn3-service-netcfg** will attach a log stream to the **openvpn3-service-log** service.  By providing this option, it will instead broadcast all log events to all listeners on the system.  This is more useful for debugging when the standard logging does not provide any clues. This is not recommended for production.

- **--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:

  - **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.

  - **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.

  - **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 **/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)](/systemd-resolved/8.md) 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)](/systemd-resolved/8.md).  This approach will currently enable split-DNS by default.

### Configuration file

The default location for the configuration file is under **/var/lib/openvpn3**.  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 **0** to **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 **stdout:** to write log data to the console/tty.  Logging will also be sent to the [**openvpn3-service-log**(8)](/openvpn3-service-log/8.md) 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 **resolv.conf** DNS resolver configuration integration.  See **--resolv-conf**  for details.

### Attribute: systemd\_resolved

This is used to enable the [**systemd-resolved**(8)](/systemd-resolved/8.md) 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)](/dbus-daemon/1.md) [**openvpn3**(1)](/openvpn3/1.md) [**openvpn3-service-client**(8)](/openvpn3-service-client/8.md) [**openvpn3-service-log**(8)](/openvpn3-service-log/8.md)