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

Global Configuration File Support is a powerful feature that streamlines setup by letting users fully configure a freshly installed OpenVPN Connect app using a single, comprehensive configuration file.

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.

Global configuration structure and format

The configuration file must:

Main Sections:

The 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 must 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>

Settings

You can set values for all application settings.

Available settings and values:

Setting

Values

Description

vpn-protocol

adaptive, tcp, udp

VPN protocol preference

timeout

10, 30, 60, 120, 0

Sets the connection timeout in seconds. A value of 0 sets the app to retry 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

Configures the app's appearance theme.

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>cellurar</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.

Proxies

You can predefine up to ten proxies using a config file, but the profile assignment must be done manually.

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

Profiles

You can import up to ten profiles using one of the two methods below:

  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>

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>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>
   </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

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.

In this section: