Skip to main content

Tutorial: Configure Global Settings with a .ocfg File

Abstract

Configure OpenVPN Connect with a .ocfg file to manage app behavior, security, and settings across Windows and macOS, in one streamlined step.

You can configure global settings in OpenVPN Connect by creating and deploying a .ocfg configuration file. This file allows administrators to control application behavior, set security preferences, connection settings, or update behavior.

This tutorial outlines creating and using a .ocfg file with OpenVPN Connect for Windows or macOS, including what values you can set. We also include examples and reference links for advanced use cases, like managing the app from the command line or combining the .ocfg file with deployment tools.

Tip

For working with iOS global configuration files, refer to Global Configuration File Support for iOS.

Global Configuration File Support

OpenVPN Connect supports global configuration files for macOS and Windows. This allows administrators to streamline application setup with a single configuration file. Refer to these topics for additional details:

Prerequisites

  • OpenVPN Connect installed on a Windows or macOS device.

  • A text editor.

Step 1: Create the .ocfg file

  1. Open your preferred text editor and create a new file.

  2. Add JSON-formatted settings using the supported schema.

    • Minimal, cross-platform example (global.ocfg): This example uses options that work on both Windows and macOS. (Platform-specific settings are ignored on platforms that don't support them.)

      {
  "settings"1: {
    "vpn-protocol": "adaptive",
    "timeout": "30",
    "launch-options": "connect-latest",
    "seamless-tunnel": true,
    "captive-portal-detection": true,
    "software-update": "weekly",
    "theme": "system",
    "confirmation-dialogs": "on-disconnect",
    "security-level": "preferred",
    "enforce-tls-1-3": true,
    "block-ipv6": "no",
    "google-dns-fallback": true
  },
  "proxies"2: [
    {
      "proxy_name": "proxy1",
      "proxy_host": "192.0.2.1",
      "proxy_port": 8080,
      "basic_auth": true
    },
    {
      "proxy_name": "proxy2",
      "proxy_host": "192.0.2.2",
      "proxy_port": 3129,
      "basic_auth": false
    }
  ],
  "profiles"3: [
    {
      "profile_name": "work_profile",
      "profile_path": "~/Porilfes/example.ovpn"
    }
  ]
}

      1

      settings: App-wide configuration (protocol, timeout, security, UI behavior).

      2

      proxies: Preconfigure proxies (profile assignment is done in the app).

      3

      profiles Import VPN profiles (use profile_path for local/HTTPS path, or profile_body to embed the profile content).

      Tip

      You can customize these options. For a full list, refer to the schema for your OS:

      Note on platform-specific options

      Some options (for example, DCO / Data Channel Offload) are Windows-only. If you include a setting that isn’t supported on the current OS, OpenVPN Connect will ignore it at import time. Use the Windows and macOS schema references to see what’s supported per platform.

  3. Save the file as the .ocfg extension.

    • Use a .ocfg extension (e.g., global.ocfg).

    • Follow the JSON format.

    • Adhere to the schema.

    • Ensure your editor doesn't add a .txt extension (e.g., global.ocfg.txt).

Step 2: Deploy the .ocfg file

Refer to your OS for importing the global config file.

Windows: 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.

macOS: 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.

Step 3: Verify the configuration

  1. Launch OpenVPN Connect.

  2. Navigate to the settings to confirm that the configurations from the .ocfg file have been applied.

  3. Check for expected behaviors such as predefined proxy settings and imported profiles.

In this section: