---
title: Global Configuration File Support for macOS
canonical: https://openvpn.net/connect-docs/macos-global-configuration-file-support/
product: OpenVPN Connect Docs
description: OpenVPN Connect's global configuration allows administrators and users to fully configure a new installation using a single, comprehensive configuration file.
---

# Global Configuration File Support for macOS

## 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.

> **Tip**
>
> **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.

### 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 use the schema detailed here to manually create the global configuration file, or use the **OpenVPN Global Config Wizard** for a guided configuration experience.

### Download the OpenVPN Global Config Wizard

Download the Wizard for your system:

- **macOS:** [OpenVPN-Global-Config-Wizard\_1.1\_universal\_signed.dmg](https://packages.openvpn.net/connect/v3/OpenVPN-Global-Config-Wizard_1.1_universal_signed.dmg)
- **Windows:** [OpenVPN-Global-Config-Wizard\_1.1\_x64\_en-US.msi](https://packages.openvpn.net/connect/v3/OpenVPN-Global-Config-Wizard_1.1_x64_en-US.msi)

### Configuration workflow:

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:

- Use a `.ocfg` file extension.
- Use valid JSON.
- Conform to [ovpn\_mac\_config\_schema.json](https://packages.openvpn.net/connect/v3/ovpn_mac_config_schema.json).

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

| **Key** | **Purpose** |
| --- | --- |
| `settings` | Configures OpenVPN Connect settings |
| `proxies` | Defines up to ten proxies. |
| `profiles` | Imports up to ten connection profiles. |
| `import-url` | Prepopulates a server URL or CloudID for **Import from URL**. |

### 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](https://openvpn.net/connect-docs/tutorials/tutorial--turn-on-seamless-tunnel-to-ensure-secure-internet-browsing.md). |
| ``` 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:

```json
{
  "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](https://openvpn.net/connect-docs/command-line-functionality-macos.md).

## See also

- [Global Configuration File Support for Windows](https://openvpn.net/connect-docs/windows-global-configuration-file-support.md)
- [Global Configuration File Support for iOS](https://openvpn.net/connect-docs/ios-global-configuration-file-support.md)

---

Prev: [Command-Line Functionality](https://openvpn.net/connect-docs/command-line-functionality-macos.md)
Next: [FAQs](https://openvpn.net/connect-docs/macos-faq.md)
Index: https://openvpn.net/connect-docs/llms.txt