openvpn3-service-netcfg(8)

📦
version 27.1 · 6 versions
, in ubuntu stonking

✨ openvpn3-service-netcfg — bestie edition ✨

okay so you're here for openvpn3-service-netcfg(8), the OpenVPN 3 Linux Network Configuration Service, and honestly? she's the backbone of the whole VPN networking situation. let's get into it 💅

🌸 NAME 🌸

openvpn3-service-netcfg — the OpenVPN 3 Linux Network Configuration Service. that's her. that's the whole name. 💖

🎀 SYNOPSIS 🎀

openvpn3-service-netcfg [OPTIONS]
openvpn3-service-netcfg -h | --help

🦋 DESCRIPTION 🦋

so openvpn3-service-netcfg is a backend service for OpenVPN 3 Linux, and her whole job is creating and managing virtual network interfaces, plus all the routing and DNS configuration that your VPN connections hand over. she's not out here doing small talk — she's doing infrastructure.

she gets started automatically when openvpn3-service-client starts and begins configuring a virtual network interface for its session. like, you don't have to text her first, she already knows. 💫

🚨 important: only one network configuration service can run on the system. just one. no duplicates, no clones, no "but I want two". the vibes must remain singular.

normally she's launched automatically when needed, through the net.openvpn.v3.netcfg.service auto-start configuration handled by dbus-daemon(1) — but you can also start her manually from the command line. she's flexible like that.

this service must start as root. literally must. but the second she's requested the privileges she needs for her operations, she drops the rest of those privileges and switches over to the _openvpn user. very "I got what I came for, I'm leaving" energy. 👑

⚠️ also beware: if you change this to another user account, you also have to update the D-Bus policy too. you can't just swap it and walk away, bestie. that's not how this works.

🔥 OPTIONS 🔥

  • -h, --help — prints usage and help details straight to your terminal. your little "what do I do" lifeline. 🫶
  • --version — prints the version of the program and then exits. short, sweet, gone.
  • --log-level LEVEL — sets the default log verbosity for log events this service generates. default is 4. valid values go from 0 to 6. higher log levels = more verbose logs, and log level 6 contains all the debug log events, every last one, no crumbs left behind. 💀
  • --log-file LOG_DESTINATION — by default, logging goes through the openvpn3-service-log service. but if you pass this argument, logging will also be sent to LOG_DESTINATION, which can be either a filename or stdout: — and that second one sends the log data to the console. double logging, double the receipts.
  • --colour — adds colours to log events when you're logging to a file or the terminal. events get coloured based on the log level of the event. cute and functional, we love to see it 🌈
  • --idle-exit MINUTES — the openvpn3-service-netcfg service will exit automatically if she's been idle for MINUTES minutes. and by "idle" we mean: no active virtual network interfaces are being managed by this service. she's not just sitting there scrolling, she's genuinely got nothing to do.
  • --redirect-method METHOD — this defines how route configurations get handled when they involve changing the default gateway. primarily it controls how network traffic routing happens from the VPN client process to the remote server. valid METHOD arguments:
    • host-route (default) — adds an explicit direct host route for the VPN server's IP address to go via the default gateway on the system. this is a lot like how OpenVPN 2.x behaves. classic behavior, classic girl. 🎀
    • bind-device — binds the device using the SO_BINDDEV socket option on the UDP/TCP socket used to connect to the remote side.
    • none — disables any specific routing arrangement for the remote host access. and look, if the default gateway gets modified, this will most certainly make the VPN connection useless. so this is not recommended for production. not even a little. 🙈
  • --set-somark MARK — adds an SO_MARK based reference to the packets sent to the remote server. netfilters can use this, like the --mark feature in iptables. works on its own or in combination with any --redirect-method settings — unless openvpn3-service-client is started with --disable-protect-socket. read that again, it's a real condition. ✨
  • --state-dir DIRECTORY — defines a directory where openvpn3-service-netcfg will read configuration data from. this config file is JSON based and will override the options from the command line. yes, it really does override. the file said what it said.

🧚 DNS Resolver Configuration 🧚

the openvpn3-service-netcfg service can configure the DNS resolver based on whatever the running VPN sessions got pushed from the OpenVPN servers. she supports multiple approaches — but only one of them can be enabled. pick your fighter, not both. 💜

  • --resolv-conf RESOLV-CONF-FILE — this method modifies the provided RESOLV-CONF-FILE directly. the file typically points at /etc/resolv.conf. but beware, bestie: this approach may not be fail-safe in all scenarios, and other network services may overwrite the changes OpenVPN applied, or OpenVPN may overwrite changes outside of its control. it's giving chaos, lowkey.

OpenVPN keeps a backup file when it has modified it, and will automatically restore the content when no running OpenVPN sessions have received any DNS configurations. so she does clean up after herself. 🫶

  • --systemd-resolved — enables integration with the systemd-resolved(8) service. the system must be pre-configured to use this service for OpenVPN's changes to fully take effect. this is the preferred way, because the DNS resolver settings are fully managed by systemd-resolved(8). and this approach will currently enable split-DNS by default. icon behavior, honestly. 👑

📁 Configuration file 📁

the default location for the configuration file is under /var/lib/openvpn3. it's a plain JSON configuration file and it 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 the settings you actually use need to be present. and if something isn't set there, the command line options are able to set those options instead. teamwork! 🤝

⭐ Attribute: log_level ⭐

this is the equivalent of the --log-level command line argument. valid LEVEL values are 0 to 6. same rules, different address.

⭐ Attribute: log_file ⭐

this is the equivalent of the --log-file command line argument. it must be a filename where to write log files. it also supports stdout: to write log data to the console/tty. and heads up: logging will also be sent to the openvpn3-service-log(8) service regardless of this setting. no escaping the log service, she's always invited. ✨

⭐ 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 — how many minutes it'll be allowed to run idle, not managing any OpenVPN network devices, before it shuts down automatically. clock's ticking 💅

⭐ Attribute: resolv_conf_file ⭐

this is used to enable the resolv.conf DNS resolver configuration integration. see --resolv-conf for the details.

⭐ Attribute: systemd_resolved ⭐

this is used to enable the systemd-resolved(8) DNS resolver configuration integration. see --systemd-resolved for the details.

⭐ Attribute: redirect_method ⭐

this is the equivalent of the --redirect-method option. see that option for the details. no need to make me repeat myself, bestie, I already spilled. 🍓

⭐ Attribute: set_somark ⭐

this is the equivalent of --set-somark. see that option for the details.

🌈 SEE ALSO 🌈

and that's the whole page, bestie. this whole thing comes to you from OpenVPN 3 Linux — openvpn3-service-netcfg(8), periodt. go configure something responsibly 💖✨🦋

📦 where this page comes from