Skip to main content

Global Configuration File Support for macOS

Abstract

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

Overview

A global configuration file lets you preconfigure a new OpenVPN Connect installation with one file. Instead of asking users to configure settings or import connection details individually, you can provide an .ocfg file that OpenVPN Connect applies on the device.

This is especially useful when you're deploying OpenVPN Connect across multiple devices with a mobile device management (MDM) solution.

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.

global_config_file_key_benefits.png

What you can configure

With a global configuration file, you can:

  • Configure OpenVPN Connect settings.

  • Add up to ten proxies.

  • Import up to ten connection profiles.

  • Prepopulate a server URL or CloudID for Import from URL.

Using the same file across devices helps keep OpenVPN Connect configurations consistent and reduces manual setup for users.

Create your configuration file

You can create the global configuration file manually using the schema described on this page, or use the OpenVPN Global Config Wizard for a guided configuration experience.

Download the OpenVPN Global Config Wizard: macOS

The overall workflow is:

  1. Create the .ocfg file.

  2. Add settings, profiles, proxies, and/or an import URL.

  3. Validate the file against the schema.

  4. Deploy or import the file on the macOS device.

  5. OpenVPN Connect applies the configuration.

Global configuration file requirements

The configuration file must:

The file can contain the following top-level configuration data:

Configure settings

Use the settings object to define OpenVPN Connect settings:

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

The following settings are supported:

Setting

Values

Description

vpn-protocol

adaptive, tcp, udp

Sets the preferred VPN protocol.

timeout

10, 30, 60, 120, 0

Sets the connection timeout in seconds. 0 retries the connection continuously.

launch-at-startup

true, false

Configures whether OpenVPN Connect starts when macOS starts.

connect-on-launch

true, false

Configures whether OpenVPN Connect connects when the app launches.

seamless-tunnel

true, false

Enables or disables Seamless Tunnel.

captive-portal-detection

true, false

Enables or disables captive portal detection.

software-update

daily, weekly, monthly, never

Sets how often OpenVPN Connect checks for software updates.

theme

system, light, dark

Sets the app appearance.

tray-icon-style

monochrome, colorful

Sets the style of the tray icon.

hide-dock-icon

true, false

Hides or shows the dock icon.

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

Requires TLS 1.3 for connections when 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 server is unavailable.

Tip

Enter JSON Boolean values such as true and false without quotation marks. Enter keyword and numeric-string values, such as "adaptive" or "30", with quotation marks.

Configure proxies

You can predefine up to ten proxies in the global configuration file.

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

The global configuration file creates the proxy definitions, but it doesn't assign a proxy to a connection profile. Assign the proxy to the appropriate profile in OpenVPN Connect after import.

Import connection profiles

You can import up to ten connection profiles. Use either profile_body or profile_path for each profile.

Method 1: Include the profile with profile_body

Use profile_body to include the full connection profile directly in the .ocfg file:

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

Method 2: Reference the profile with profile_path

Use profile_path to specify either a local file path or a direct network download URL:

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

When using profile_path:

  • Use the appropriate JSON escape sequences, such as \\ and \".

  • Local file paths can use environment variables or relative paths.

  • Network imports must use HTTPS.

Prepopulate an import URL or CloudID

Use import-url to prepopulate the value shown for Import from URL. This saves users from having to enter the server URL or CloudID themselves.

{
  "import-url": "https://yourcompany.com"
}

Example global configuration file for macOS

Here is an example of a typical config for macOS:

{
  "profiles": [
    {
      "profile_name": "work_profile",
      "profile_path": "~/Downloads/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-at-startup": false,
    "connect-on-launch": true,
    "seamless-tunnel": true,
    "hide-dock-icon": 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,
    "block-ipv6": "no"
  }
}

Important

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

Import the global configuration file

You can import a global configuration file with the OpenVPN Connect app or from the command line:

Import with OpenVPN Connect

Use either of these methods:

  • Double-click the .ocfg file.

  • Drag and drop the .ocfg file into OpenVPN Connect.

Import from the command line

Run OpenVPN Connect with the following option:

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

What happens during import

Keep these behaviors in mind when importing a global configuration file:

  • You can't import a global configuration file while a VPN connection is active.

  • If the file contains a profile or proxy with the same name as an existing one, OpenVPN Connect prompts the user to replace it or keep the existing configuration.

  • After the import finishes, OpenVPN Connect displays the result.

For more information about command-line options, refer to Manage OpenVPN Connect from the Command Line.

See also

In this section: