Skip to main content

Global Configuration File Support for iOS

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.

Note

Global configuration file support for iOS is compatible with MDM platforms such as Jamf Pro and Microsoft Intune.

Apply a Global Config

Global configuration file requirements

The configuration file must:

Main Sections:

The core 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.

Required field

You need to define the modifiedWhen key. This value should change whenever you push a new config, so OpenVPN Connect recognizes and applies updates.

<key>modifiedWhen</key>
<string>2025-12-30T13:10:49:05</string>

Configure settings

Use the settings object to define OpenVPN Connect settings:

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.

battery-saver

true, false

Prevents the app from reconnecting when the device is locked and the screen isn't active.

connect-via

any, wifi, cellular

Set the network type used for the connection.

captive-portal-detection

true, false

Tries to detect captive portals during network change and application launch.

theme

system, light, dark

Sets the app appearance.

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.

allowUnusedAddrFamilies

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.

use-system-browser

true, false

Set whether to use the system browser for web authentication.

l2-reachability

true, false

Enable a more robust network reachability set when transitioning between Wi-Fi and cellular network.

<key>settings</key>
    <dict>
        <key>vpn-protocol</key>
        <string>adaptive</string>
        <key>timeout</key>
        <string>30</string>
        <key>battery-saver</key>
        <true/>
        <key>connect-via</key>
        <string>cellular</string>
        <key>captive-portal-detection</key>
        <false/>
        <key>confirmation-dialogs</key>
        <string>on-reconnect</string>
        <key>theme</key>
        <string>system</string>
        <key>security-level</key>
        <string>preferred</string>
        <key>allowUnusedAddrFamilies</key>
        <string>no</string>
        <key>google-dns-fallback</key>
        <true/>
        <key>use-system-browser</key>
        <false/>
        <key>l2-reachability</key>
        <false/>
    </dict>

Caution

Settings not supported on iOS will be ignored.

Configure proxies

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

<key>proxies</key>
    <array>
        <dict>
            <key>proxy_name</key>
            <string>Office Proxy</string>
            <key>proxy_host</key>
            <string>proxy.company.ua</string>
            <key>proxy_port</key>
            <integer>8080</integer>
            <key>proxy_username</key>
            <string>user123</string>
            <key>proxy_password</key>
            <string>pass123</string>
            <key>basic_auth</key>
            <false/>
        </dict>
        <dict>
            <key>proxy_name</key>
            <string>Home Proxy</string>
            <key>proxy_host</key>
            <string>192.168.1.100</string>
            <key>proxy_port</key>
            <integer>3128</integer>
        </dict>
    </array>

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.

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

    <key>profiles</key>
    <array>
        <dict>
            <key>profile_name</key>
            <string>Second Profile</string>
            <key>profile_body</key>
            <string>...</string>
        </dict>
    </array>

  2. Method 2: Use profile_path — Specify the direct download link (for network import) within the "profile_path" attribute:

    <key>profiles</key>
    <array>
        <dict>
            <key>profile_name</key>
            <string>My VPN Profile</string>
            <key>profile_path</key>
            <string>https://domain.ua/to/profile.ovpn</string>
        </dict>
    </array>

Important

  • Ensure you replace the special characters in the profile_body with their corresponding XML entries before adding them to the configuration file. Examples:

            '&': '&amp;',
        '<': '&lt;',
        '>': '&gt;',
        '"': '&quot;',
        "'": '&apos;',
        '\n': '&#10;',
        '\r': '&#13;',
        '\t': '&#9;'

  • The profile_path value only supports URLs using the HTTPS protocol for network-based imports.

    <xs:element name="profile_path"> 
<xs:simpleType> 
<xs:restriction base="xs:string">  
 <xs:pattern value="https?://.+"/> 
 </xs:restriction>
</xs:simpleType>
</xs:element>

User restrictions

Use user_restrictions to prevent end users from modifying managed OpenVPN Connect settings or removing imported profiles.

When all is set to true, in-app settings can no longer be changed by the end user, and profiles imported through the global configuration can't be removed from the app.

<key>user_restrictions</key>
<dict>
    <key>all</key>
    <true/>
</dict>

Kill switch

Use kill_switch to prevent the VPN connection from being disabled by the end user for a managed profile.

The kill_switch key needs to be defined inside the relevant profile object under the profiles key.

<key>profiles</key>
<array>
    <dict>
        <key>profile_name</key>
        <string>body_auto1</string>
        <key>profile_path</key>
        <string>https://domain.net/path/to/profile.ovpn</string>
        <key>kill_switch</key>
        <true/>
    </dict>
</array>

Important

The kill switch requires that a connection profile be imported via the global configuration file.

Example config file for iOS

Here is an example of a typical config for iOS:

<dict>
    <key>modifiedWhen</key>
    <string>2025-12-30T13:10:49:12</string>

    <key>user_restrictions</key>
    <dict>
        <key>all</key>
        <false/>
    </dict>

    <key>profiles</key>
    <array>
        <dict>
            <key>profile_name</key>
            <string>test_profile</string>
            <key>profile_path</key>
            <string>https://domain.net/path/to/profile.ovpn</string>
            <key>kill_switch</key>
            <false/>
        </dict>
    </array>

    <key>proxies</key>
    <array>
        <dict>
            <key>proxy_name</key>
            <string>test</string>
            <key>proxy_host</key>
            <string>192.168.77.88</string>
            <key>proxy_port</key>
            <integer>808</integer>
        </dict>
    </array>

    <key>settings</key>
    <dict>
        <key>vpn-protocol</key>
        <string>tcp</string>
        <key>timeout</key>
        <string>120</string>
        <key>battery-saver-ios</key>
        <true/>
        <key>seamless-tunnel</key>
        <true/>
        <key>connect-via</key>
        <string>wifi</string>
        <key>captive-portal-detection</key>
        <false/>
        <key>confirmation-dialogs</key>
        <string>on-reconnect</string>
        <key>theme</key>
        <string>light</string>
        <key>security-level</key>
        <string>preferred</string>
        <key>enforce-tls-1-3</key>
        <true/>
        <key>block-ipv6</key>
        <string>yes</string>
        <key>google-dns-fallback</key>
        <false/>
        <key>l2-reachability</key>
        <false/>
        <key>use-system-browser</key>
        <true/>
    </dict>
</dict>

Important

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

Importing global config

Jamf Pro (AppConfig)

Note

OpenVPN Connect for iOS has been tested with Jamf Pro MDM using the AppConfig feature.

  1. Create a new mobile device policy in your MDM.

  2. Assign the App Store version of OpenVPN Connect (net.openvpn.connect.app).

  3. Add your PLIST under the App Configuration tab.

  4. Scope the policy to the intended devices.

Importing Tips

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

  • If the app is running in the background, remove it from Recents and reopen it for the new config to apply.

  • Users are notified if the config import succeeds or fails.

  • Always validate your configuration against the schema before deployment to ensure compatibility.

Microsoft Intune

  1. In the Microsoft Intune admin panel, navigate to Apps > iOS/iPadOS apps and click Create.

  2. Select iOS Store App and search for OpenVPN Connect in the App Store.

  3. Assign it to the relevant user group.

  4. Click Apps > iOS/iPad OS > Configuration Policies and click Create.

  5. During policy creation:

    • Select OpenVPN Connect as the app.

    • Under the Settings tab, choose Enter XML data for the configuration settings format.

    • Paste your PLIST configuration in the XML field.

  6. Assign the configuration policy to the relevant user group.

  7. Review and create the configuration policy.

Importing Tips

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

  • If the app is running in the background, remove it from Recents and reopen it for the new config to apply.

  • Users are notified if the config import succeeds or fails.

  • Always validate your configuration against the schema before deployment to ensure compatibility.

In this section: