Skip to main content

Global Configuration File Support for Windows

Abstract

OpenVPN Connect's global configuration allows administrators and users to fully configure a new installation using a single, comprehensive configuration file.

Overview

Global Configuration File Support is a powerful feature that streamlines setup by letting users fully configure a freshly installed OpenVPN Connect app using a single, comprehensive configuration file.

Enhancing MDM Solutions

Global Configuration File Support streamlines Mobile Device Management (MDM) by enabling administrators to deploy pre-configured OpenVPN Connect apps. It simplifies managing app settings, profiles, and proxies, ensuring consistent configurations across all devices while reducing setup time.

Key benefits

  • Streamlined Setup: By utilizing a global configuration file, users can bypass the often lengthy and repetitive setup procedures, ensuring all preferred settings are applied immediately upon installation.

  • Consistency Across Installations: Whether installing the application on multiple devices or sharing configurations within a team using MDM solutions, this feature ensures uniformity and consistency in settings.

  • Simplified Management: Consolidate settings in one file for easier updates and management.

  • Enhanced Customization: Tailor the OpenVPN Connect experience for end users immediately, ensuring a personalized and efficient user experience.

With this feature, we aim to enhance your productivity and ease of use, ensuring that your application environment is set up exactly how you want it, with minimal effort. Let's dive in and explore how to utilize Global Configuration File Support for an optimized and hassle-free experience.

Global configuration structure and format

The configuration file must:

Main Sections:

The configuration file contains three main sections:

  1. Settings: Define application-wide settings.

  2. Proxies: Preconfigure up to ten proxies.

  3. Profiles: Import up to ten connection profiles.

Settings

You can set values for all application settings by using the following format:

"settings": {
  "<setting_name>": "<setting_value>"
}

Available settings and values:

Setting

Values

Description

vpn-protocol

adaptive, tcp, udp

VPN protocol preference.

timeout

10, 30, 60, 120, 0

Sets the connection timeout in seconds. A value of 0 sets the app to retry the connection continuously.

launch-options

start-app, connect-latest, restore-connection, none

Configures app behavior on launch.

seamless-tunnel

true, false

Enables or disables the seamless tunnel feature.

captive-portal-detection

true, false

Enables or disables captive portal detection.

software-update

daily, weekly, monthly, never

Sets the frequency for checking software updates.

theme

system, light, dark

Configures the app's appearance theme.

tray-icon-style

monochrome, colorful

Sets the style of the tray icon.

enable-dco

true,lfalse

Enables the DCO adapter.

confirmation-dialogs

all, none, on-disconnect, on-reconnect

Configures when confirmation dialogs appear.

security-level

preferred, legacy, insecure

Sets the security level for VPN connections.

enforce-tls-1-3

true, false

Enforces the use of TLS 1.3 for connections if supported.

block-ipv6

yes, no

Configures whether IPv6 traffic is blocked.

google-dns-fallback

true, false

Enables or disables fallback to Google DNS when the primary DNS is unavailable.

Proxies

You can predefine up to ten proxies using a config file, but the profile assignment must be done manually.

"proxies": [
    {
      "proxy_name": <string value, mandatory>,
      "proxy_host": <string value, mandatory>,
      "proxy_port": <integer value>,
      "basic_auth": <boolean value>
    },
    ...
  ]

Profiles

You can import up to ten profiles using one of the two methods below:

  1. Method 1: Use profile_body — Place the full profile content within the "profile_body" attribute:

    "profiles": [
        {
          "profile_name": "<string value, mandatory>",
          "profile_body": "<string value, mandatory>"
        },
        ...
    ]
  2. Method 2: Use profile_path — Specify the full file path (for local import) or a direct download link (for network import) within the "profile_path" attribute:

    "profiles": [
        {
          "profile_name": "<string value, mandatory>",
          "profile_path": "<string value, mandatory>"
        },
        ...
    ]

Important

  • Use escape sequences for JSON strings (e.g., \\, \").

  • The file path option supports environment variables and relative paths.

  • The network import option must use HTTPS.

Example config file for Windows

Here is an example of a typical config for Windows:

{
  "profiles": [
    {
      "profile_name": "work_profile",
      "profile_path": "D:\\Profiles\\example.ovpn"
    }
  ],
    "proxies": [
    {
      "proxy_name": "proxy1",
      "proxy_host": "192.168.0.1",
      "proxy_port": 8080,
      "basic_auth": true
    },
    {
      "proxy_name": "proxy2",
      "proxy_host": "192.168.0.2",
      "proxy_port": 3129,
      "basic_auth": false
    }
  ],
  "settings": {
    "vpn-protocol": "adaptive",
    "timeout": "30",
    "launch-options": "connect-latest",
    "seamless-tunnel": true,
    "shortcut-minimize": false,
    "captive-portal-detection": true,
    "software-update": "weekly",
    "theme": "system",
    "tray-icon-style": "colorful",
    "confirmation-dialogs": "on-disconnect",
    "security-level": "preferred",
    "enforce-tls-1-3": true,
    "enable-dco": false,
    "block-ipv6": "no"  }
}

Important

When composing a new config file, validate it against the schema before applying.

Importing global config

There are two ways you can import a global config:

  1. With the help of standard GUI:

    • Double-click the .ocfg file or drag and drop it into OpenVPN Connect.

  2. Using CLI:

    • Execute the following OpenVPN Connect CLI command in a terminal:

       --import-config=<path to ocfg file>

Importing Tips

  • You can't import a config during an active VPN connection.

  • Users will be prompted to replace or discard changes if the config contains existing profile or proxy names.

After importing the file, the user is informed of the result of the operation with a message. For more information on OpenVPN Connect CLI functionality, visit Manage OpenVPN Connect from the Command Line.