openvpn3-autoload(8)

📦
version 27.1 · 3 versions
, in nixpkgs unstable, ubuntu stonking

💖 openvpn3-autoload(8) — OpenVPN 3 Linux 💖

okay bestie, gather round, because this is the openvpn3-autoload page from the OpenVPN 3 Linux manual and she is long, so we're doing this in parts. part 1, let's go 🫶

✨ Name ✨

openvpn3-autoload — OpenVPN 3 Linux — the Automated configuration profile loader. yes she loads your profiles for you, no cap 💅

✨ SYNOPSIS ✨

openvpn3-autoload [ OPTIONS ]
openvpn3-autoload -h | --help

✨ DESCRIPTION ✨

🚨 NOTE! This feature is deprecated. It got replaced by the openvpn3-session@.service systemd unit. Please go look at openvpn3-systemd(1) for the whole story, okay? 👑

so like, the openvpn3-autoload utility does one very specific lil job: it automatically loads VPN configuration profiles from a directory of your choosing, and optionally starts them too. ✨

and here's the thing, because the OpenVPN 3 Linux client gives you fine grained control over both config profiles and VPN sessions (those live outside the main config profile, separate vibe entirely), your configuration profiles have to be accompanied by a .autoload definition file that carries all the local, site-specific settings. no .autoload, no autoload, periodt. 🎀

also!! the utility ships with a openvpn3-autoload.service systemd unit file. enable that unit and it will load the configuration profiles chillin' in /etc/openvpn3/autoload. she's giving main character energy in that directory fr fr 🌸

✨ OPTIONS ✨

  • -h, --help — prints the usage info and then dips. that's it, that's the whole job 💅
  • --directory DIR — Required. like, actually required bestie. this is the directory where she goes looking for configuration profiles. 🦋
  • --ignore-autostart — Optional. tells her not to automatically start any VPN sessions that were configured to start during loading. so she'll load everything and just… not start anything. muted mode. 🤫

✨ BACKGROUND ✨

okay so storytime 📖 — back in traditional OpenVPN 2.x land, configuration profiles could contain a LOT of options, and those options were a mix of two very different things: some were site/host independent, and some were site/host specific. iconic?? no, problematic actually. 😭

and that's a whole mess when you're trying to distribute configuration profiles, because a profile that works perfectly on one device in one particular network might just ✨not work✨ on a different device or a different network. it's giving incompatible. 💀

so OpenVPN 3 came through with a solution: it gives you a way to split out the site/host dependent options from the main VPN configuration profile that the VPN provider hands you. 🌈

in the OpenVPN 3 Linux client, those site/host specific settings are managed via openvpn3 config-manage, and that's specifically for configuration profiles you've already imported. and then, the .autoload configuration files swoop in to automate setting up all those various options — with zero direct user interaction required. no clicking, no typing, no nothing. obsessed. 💜

(part 1 done, part 2 is coming, don't go anywhere bestie 🫶)

✨ FILE FORMAT ✨

Okay bestie, so the file format? It's built on JSON 💖 but instead of rocking .ovpn or .conf, it carries the .autoload extension. That's the vibe.

Three rules, no cap:

  • The .autoload file has to live in the same directory as the main configuration file 📁
  • The base part of the filename must be identical to the .ovpn/.conf file
  • That's it, that's the whole thing

Example, because examples eat every time: if your configuration profile is named vpn-client.conf, then the .autoload file must be named vpn-client.autoload. Iconic. 👑

🌸 Main section 🌸

Here's the basic layout of an .autoload file, and yes I'm putting it in a code block because it deserves the moment:

{
   "autostart": BOOLEAN,
    "name": "string value",
    "acl": {
        ...
    },
    "crypto": {
        ...
    },
    "remote": {
        ...
    },
    "tunnel": {
        ...
    },
    "user-auth": {
        ...
    }
}

🦋 Attribute: autostart 🦋

The autostart boolean is the lil switch that declares whether the configuration profile should get started the moment it's been imported into the OpenVPN 3 Configuration Manager. (Default: false)

🎀 Attribute: name 🎀

By default, every automatically imported configuration profile just uses the complete profile filename, .conf or .ovpn extension and all. Kinda long, kinda basic.

But if you set this attribute? That string becomes the profile name instead of the filesystem filename. Slay. 💅

⚠️ Beware bestie: the configuration manager will accept duplicate profile names. It is not going to stop you. That's a you problem now. 😭

🌈 Section: acl 🌈

The acl section declares a bunch of Access Control Level parameters for the imported configuration profile. Here's what's valid:

"acl": {
    "public": BOOLEAN,
    "locked-down": BOOLEAN,
    "set-owner": UID
}

🔐 Attribute acl:public 🔐

The public element declares whether this configuration profile is available for all users on the system or not. (Default: false)

🔒 Attribute: acl:locked-down 🔒

Setting locked-down to true means users who've been granted access can only start new tunnels with this profile — they can't peek at the information stored in the configuration profile. No snooping. 🙈 (Default: false)

👑 Attribute: acl:set-owner 👑

By default, all processed configuration profiles are owned by whoever runs openvpn3-autoload. Makes sense, that's the person doing the work.

But the root user on the system can re-assign ownership of the configuration profiles it imports — like when you're running this utility during system boot. 🌅

So you hand over the set-owner element with the UID of the user who should own this configuration profile, and boom, ownership gets transferred. This is a root-only feature, no exceptions. ✨

🧚 Section: crypto 🧚

The crypto section lets you fine-tune some of the configuration parameters around the crypto layers of a VPN session. Very main character of it.

"crypto": {
    "tls-params": {
        ...
    }
}

💜 Sub-Section: crypto:tls-params 💜

The tls-params sub-section goes even deeper and controls the TLS protocol parameters.

"tls-params": {
    "cert-profile": [ "legacy" | "preferred" | "suiteb" ],
    "min-version": [ "disabled" | "default" | "tls_1_0" | "tls_1_1" | "tls_1_2" | "tls_1_3" ]
}

⭐ Attribute: crypto:tls-params:cert-profile ⭐

The cert-profile declares the security level of the TLS channel. Valid values, and I'm listing every single one:

  • legacy — Allows minimum 1024 bits RSA keys with certificates signed with SHA1.
  • preferred — Allows minimum 2048 bits RSA keys with certificates signed with SHA256 or higher.
  • suiteb — This follows the NSA Suite-B specification.

🦋 Attribute: crypto:tls-params:min-version 🦋

The min-version defines the minimum TLS version being accepted by the client. Here's the full roster:

  • disabled — No minimum version is defined nor required
  • default — Uses the default minimum version the SSL library defines
  • tls_1_0 — Requires at least TLSv1.0
  • tls_1_1 — Requires at least TLSv1.1
  • tls_1_2 — Requires at least TLSv1.2
  • tls_1_3 — Requires at least TLSv1.3

🌐 Section: remote 🌐

Settings in this section are all about the connection to the remote server. Important detail though: it does not support different settings per remote server — this is shared across all the remote servers enlisted in the main configuration file. Group settings energy. 🫶

"remote": {
        "proto-override": [ "udp" | "tcp" ],
        "port-override": PORT_NUM,
        "timeout": SECONDS,
        "compression": [ "no" | "yes" | "asym" ],
        "proxy": {
            ...
        }
}

💫 Attribute: remote:protocol-override 💫

This forces the VPN client to connect using the given protocol. Valid values are tcp or udp. Pick one bestie, it's not a choose-your-own-adventure. ✨

🔌 Attribute remote:port-override 🔌

Port number to use instead of the port number defined in the VPN configuration profile.

⚠️ It must be an integer between 0 and 65535. Stay in range. 🙏

⏳ Attribute: remote:timeout ⏳

An unsigned integer defining how long to wait before trying the next remote entry enlisted in the VPN configuration profile. Patience is a virtue but apparently it's configurable. 😌

🗜️ Attribute: remote:compression 🗜️

Controls how compression settings work for the data channel. Valid values:

  • no — Compression is disabled
  • yes — Compression is enabled in both directions
  • asym — Compression is only enabled for traffic sent from the remote side to the local side

🎀 Sub-section: remote:proxy 🎀

This sub-section configures the client to start the connection via an HTTP proxy server. Goin' through the side door, love that for us. 💅

"proxy": {
        "host": "proxy-server-name",
        "port": "proxy-port",
        "username": "proxy-username",
        "password": "proxy-password",
        "allow-plain-text": BOOLEAN
}

🏠 Attribute: remote:proxy:host 🏠

String containing the hostname of the HTTP proxy.

🔢 Attribute: remote:proxy:port 🔢

Unsigned integer defining the port to use when connecting to the proxy server.

🫥 Attribute: remote:proxy:username 🫥

If the proxy server requires user authentication, this needs to contain a string with the proxy username to use.

🤫 Attribute: remote:proxy:password 🤫

If the proxy server requires user authentication, this needs to contain a string with the password to use.

😱 Attribute: remote:proxy:allow-plain-text 😱

Boolean flag enabling or disabling the OpenVPN 3 client to transport the proxy username/password unencrypted. Default: false

🚨 Bestie. Read that again. Unencrypted. Keep it false unless you really know what you're doing. 💀

🕳️ Section: tunnel 🕳️

The tunnel section defines settings related to the tunnel interface. Lowkey platform-dependent: on some platforms this interacts directly with a tun/tap interface, while other platforms may pass these settings via VPN API provided by the platform. Either way it works, just differently. 🌈

"tunnel": {
        "ipv6": [ "yes" | "no" | "default" ],
        "persist": BOOLEAN,
        "dns-fallback": [ "google" ],
        "dns-setup-disabled": BOOLEAN
    }

🛰️ Attribute: tunnel:ipv6 🛰️

Enable or disable the IPv6 capability on the tunnel interface. It can be a string which must contain one of these values:

  • yes — IPv6 capability is enabled and will be configured if the server sends IPv6 configuration details
  • no — IPv6 capability is disabled and will not be configured, regardless of what the server provides of IPv6 configuration details
  • default — Make use of IPv6 if the platform supports it

🔁 Attribute: tunnel:persist 🔁

Boolean flag which enables the persistent tunnel interface behaviour. This is about whether the tunnel interface will be torn down and re-established during re-connections or restarts of the VPN tunnel. If set to true, the tunnel interface is preserved during such events. Keeping the friendship alive through the rough patches. 🫶

🧭 Attribute: tunnel:dns-fallback 🧭

This makes the VPN client configure an additional fallback DNS server on the system. Valid strings are:

  • google — Configures the system to use 8.8.8.8 and 8.8.4.4 as fallback DNS servers

🔍 Attribute: dns-scope 🔍

Defines the DNS query scope. Heads up: this is currently only supported when enabling the systemd-resolved(8) resolver support in openvpn3-service-netcfg(8). Supported values:

  • global: (default) — The VPN service provided DNS server(s) will be used for all types of DNS queries.
  • tunnel: — The VPN service provided DNS server(s) will only be used for queries for DNS domains pushed by the VPN service.
📌 NOTE: The DNS domains pushed by the VPN service may be queried by DNS servers with systemd-resolved(8) service if their respective interfaces are configured to do global DNS queries. But other non-listed DNS domains will not be sent to this VPN service provider's DNS server.

🚫 Attribute: dns-setup-disabled 🚫

Controls whether DNS configurations in the VPN configuration profile, or DNS settings sent from the server, will be applied on the system or not. (Default: false)

🔑 Section: user-auth 🔑

This section only matters if the server uses user authentication methods other than certificate based authentication — and it's only used if the autostart attribute is set to true. It's here to automate the client connection as much as possible, because who has time to type things. ⚡

"user-auth": {
    "autologin": BOOLEAN,
    "username": "string value",
    "password": "string value",
    "pk_passphrase": "string value",
    "dynamic_challenge": "string value"
}

🎟️ Attribute: user-auth:autologin 🎟️

If set to true, the client will not ask for username/password, since it's expected that the VPN configuration profile carries the needed settings providing the identity towards the server. (Default: false)

🙋 Attribute: user-auth:username 🙋

String containing the username to authenticate as.

🤐 Attribute: user-auth:password 🤐

String containing the password used for the authentication.

🗝️ Attribute: user-auth:pk_passphrase 🗝️

String containing the private key passphrase, which is needed if the private key in the VPN configuration profile is encrypted.

🎲 Attribute: user-auth:dynamic_challenge 🎲

The server might ask the client for a dynamic challenge. If the expected response is static, the static response can be put here.

⚠️ But if the server expects an OTP token code or similarly dynamic changing input, the VPN configuration profile is not suitable for autostart. Sorry bestie, some things just gotta be typed live. 😭

👀 SEE ALSO 👀

And that's the whole page, bestie!! 💖✨ You just read openvpn3-autoload(8) — shoutout to whoever wrote it, the copyright holders, and whatever license it ships under, all of which live up in the real page header, mwah. This one was rendered from the source/version and date tucked into the page's own footer — go check 'em if you need the receipts. 🎀 Now go configure something. Periodt. 👑

📦 where this page comes from