Global Configuration File Support for macOS
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 in OpenVPN Connect 3.6.0 and newer for macOS and Windows allows administrators to streamline application setup with a single configuration file. This feature enhances productivity by automating the customization of OpenVPN Connect for specific user needs.
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.
Here are the simple steps to apply Global Config:
Create the .ocfg file formatted according to the schema.
Apply it on the user device using one of the preferred methods.
Global configuration structure and format
The configuration file must:
Use a .ocfg extension.
Follow the JSON format.
Adhere to the schema: ovpn_mac_config_schema.json.
Main Sections:
Settings: Define application-wide settings.
Proxies: Preconfigure up to ten proxies.
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 |
| VPN protocol preference. |
timeout |
| Sets the connection timeout in seconds. A value of |
launch-options |
| Configures app behavior on launch. |
seamless-tunnel |
| Enables or disables the seamless tunnel feature. |
captive-portal-detection |
| Enables or disables captive portal detection. |
software-update |
| Sets the frequency for checking software updates. |
theme |
| Configures the app's appearance theme. |
tray-icon-style |
| Sets the style of the tray icon. |
hide-dock-icon |
| Hides or shows the dock icon. |
confirmation-dialogs |
| Configures when confirmation dialogs appear. |
security-level |
| Sets the security level for VPN connections. |
enforce-tls-1-3 |
| Enforces the use of TLS 1.3 for connections if supported. |
block-ipv6 |
| Configures whether IPv6 traffic is blocked. |
google-dns-fallback |
| 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 following methods:
Place the full profile content within the
"profile_body"attribute:"profiles": [ { "profile_name": "<string value, mandatory>", "profile_body": "<string value, mandatory>" }, ... ]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 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-options": "connect-latest",
"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.
Importing global config
There are two ways you can import a global config:
With the help of standard GUI:
Double-click the .ocfg file or drag and drop it into OpenVPN Connect.
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 Command-Line Functionality.