Reconnection strategy

When building iOS applications that rely on a VPN connection, implementing a robust reconnection strategy is crucial to ensure a seamless user experience. One effective approach is to leverage the On-Demand VPN feature, which allows the system to automatically establish the VPN connection based on predefined rules. In this page, we'll explore how to configure On-Demand VPN using the OnDemandConfiguration struct in Swift and how it ties into a reliable reconnection strategy.

Understanding OnDemandConfiguration

The OnDemandConfiguration struct is a codable struct that represents the configuration for On-Demand VPN. It has two main properties:

Property	Description
isEnabled	A boolean value that determines whether the On-Demand VPN feature is enabled or not. The default value for this setting is false. When set to false, the on-demand rules for automatically reconnecting the VPN are disabled. This means that the VPN will not automatically reconnect based on any rules. In this case, the user must manually manage the VPN connection. When set to true, the VPN will be automatically triggered by the system after the startVPN method is called. To disable On-Demand VPN, you need to call the stop method from your application.
onDemandRules	Defines the rules for triggering the On-Demand VPN connection. These rules specify the conditions under which the VPN should be activated. If no custom rules are provided, OnDemandConfiguration uses the default rules defined in the NEOnDemandRule.defaultRules property from NetworkExtension. You can customize the On-Demand rules based on your specific requirements. For example, you can create rules based on type of network interface (WiFi, cellular, etc), or other criteria supported by the NEOnDemandRule class.

Sample Codes

import NetworkExtension
// ...

// Create custom on-demand rules
let connectRuleWifi = NEOnDemandRuleConnect()
connectRuleWifi.interfaceTypeMatch = .wiFi
let disconnectRuleCellular = NEOnDemandRuleDisconnect()
disconnectRuleCellular.interfaceTypeMatch = .cellular
let onDemandRules = [connectRuleWifi, disconnectRuleCellular]

let hydraConfiguration = HydraConfiguration(
    carrierID: "YOUR_CARRIER_ID",
    extensionBundleID: "com.yourcompany.demo-test.app.hydra-extension",
    groupData: VPNGroupData(
        groupID: "group.GROUP_ID",
        usesSystemExtension: false
    ),
    fireshieldConfig: FireshieldConfig(
        mode: .disabled,
        groupData: VPNGroupData(groupID: "group.com.yourcompany.vpnsdk-demo", usesSystemExtension: false)
    ),
    onDemandConfiguration: OnDemandConfiguration(isEnabled: true, onDemandRules: onDemandRules)
)

In the sample code above:

1. import NetworkExtensions imports the NetworkExtension framework, which provides APIs for configuring and managing VPN connections.

2. Two on-demand rules are created:

• connectRuleWifi: Specifies that the VPN should automatically connect when the device is connected to a Wi-Fi network.

• disconnectRuleCellular: Specifies that the VPN should automatically disconnect when the device switches to a cellular network.

1. The HydraConfiguration object is initialized with various configuration parameters, including the onDemandConfiguration property.

2. The OnDemandConfiguration object is created with isEnabled set to true, enabling the on-demand rules, and the onDemandRules array is passed as the onDemandRules parameter.

SDK Implementation and Limitations

Current Implementation Behavior

Our SDK implementation prioritizes explicit VPN control to ensure predictable behavior. The SDK automatically manages VPN On Demand functionality in conjunction with the start() and stop() methods:

• On start(): The VPN connection is established according to your configuration

• On stop(): The SDK automatically disables VPN On Demand by:

  • Setting isOnDemandEnabled to false

  • Saving this configuration to system preferences

  • Preventing any automatic reconnection based on VPN On Demand rules

This design ensures that when users explicitly stop the VPN, it remains stopped without unexpected reconnections.

On-Demand Only Mode (SDK 7.7.0+)

Starting from version 7.7.0, the SDK introduces a new start policy that enables an on-demand only mode. The SDK continues to disable VPN On Demand when stop() is called, as it did in previous versions.

Start Policies

The start() method now accepts two policies:

• connectNow: The previous start behavior. Establishes the VPN connection immediately according to your configuration.

• configureOnDemand: Enables on-demand only mode. This does not start the tunnel immediately, but prepares the credentials and delegates the tunnel start to the OS. The VPN will be started/stopped depending on the provided on-demand rule list.

Behavior

• On start() with connectNow: The VPN connection is established immediately (unchanged from previous versions)

• On start() with configureOnDemand: The SDK configures on-demand rules and lets the OS manage when to start/stop the tunnel based on those rules

• On stop(): The VPN is completely stopped and on-demand is disabled, as it was in previous versions

Switching Policies

If you want to switch between policies (e.g., from connectNow to configureOnDemand or vice versa), you must call stop() first and then call start() again with the desired policy.

OnDemandConfiguration in start()

OnDemandConfiguration is now a parameter in the start() method, so you don't need to reconfigure the SDK each time you want to start with a new rule list. The OnDemandConfiguration property in the SDK configuration is deprecated and will be removed in future versions.

Migration Notes

If you are upgrading from a version prior to 7.7.0:

1. Review your start calls: Consider whether the new configureOnDemand policy fits your use case

2. Update OnDemandConfiguration usage: Move OnDemandConfiguration from SDK configuration to the start() method parameter

3. Remove workarounds: If you previously implemented the workaround described below to maintain VPN On Demand after stop(), you can now use the configureOnDemand policy instead

Workaround for Persistent VPN On Demand (Pre-7.7.0)

If your application requires VPN On Demand to remain active even after calling stop(), you can implement a workaround using direct access to Apple's NetworkExtension API. This approach bypasses the SDK's automatic VPN On Demand management.

Implementation Steps

1. Configure and start the VPN profile using the SDK as normal

2. After SDK configuration, access the NETunnelProviderManager directly

3. Manually enable both VPN On Demand and the VPN profile

4. Save the configuration to system preferences

Important Considerations

• Manual Management Required: When using this workaround, you become responsible for managing VPN On Demand state

• SDK stop() Behavior: The SDK's stop() method will still attempt to disable VPN On Demand, so you may need to re-enable it after stopping

• System Behavior: iOS/macOS will continue attempting to connect based on your VPN On Demand rules, even if the VPN encounters errors

• User Experience: Consider implementing UI controls to allow users to fully disable VPN On Demand when needed

Handling NEOnDemandRuleConnect Behavior

When NEOnDemandRuleConnect is enabled and matches, the VPN connection will automatically restart even if the user tries to turn it off from system settings. The OS prevents manual disconnection in this mode.

If your goal is to maintain the VPN connection until the user explicitly disables it, keep VPN On Demand enabled. However, you'll need to guide users to disconnect through your app instead of system settings.

Recommended Approach

1. Add an "Always On" toggle in your app

   • This setting controls whether VPN On Demand is enabled

   • Makes it clear to users how to control the behavior

2. Notify users when automatic restart occurs

   • Use the User Notifications framework to alert users when they try to disable the VPN from system settings and it restarts automatically

   • Explain that they need to disable it from within the app

Detecting Automatic Restart

To detect when the VPN is restarting due to VPN On Demand (rather than a crash or error):

1. vpnWillStop() is called with error = nil

2. Extension then restarts with StartupOptions.isOnDemand = true in vpnWillStart()

This approach successfully distinguishes between:

• Manual user stop → automatic restart: Detected via error == nil in vpnWillStop() followed by isOnDemand == true in vpnWillStart()

• Non-user stops (like network changes): Where error != nil

Since this involves two separate processes, you need to:

• Persist a flag when vpnWillStop() is called with nil error

• Check this flag when the extension restarts with isOnDemand = true

• Reset the flag when the app starts (StartupOptions.isAppStart == true)

When this sequence is detected, show a notification explaining: "VPN must be stopped from the app while 'Always On' is enabled."

Why Not Disable VPN On Demand From the Extension?

While the extension can detect the manual stop + VPN On Demand restart sequence, it cannot modify VPN configuration settings. This is an architectural limitation of iOS/macOS Network Extensions:

• Extension capabilities: The Network Extension runs as a separate process and only receives lifecycle callbacks (vpnWillStart(), vpnDidStart(), vpnWillStop(), etc.). It can observe and react to events but cannot modify VPN configuration.

• Configuration control: The SDK's stop() method and VPN On Demand configuration changes can only be called from the main app, not from within the extension. When stop() is called from the main app, the SDK automatically disables VPN On Demand by setting isOnDemandEnabled to false and saving this configuration to system preferences.

Therefore, when the extension detects a manual stop with VPN On Demand restart:

1. It can send a notification to inform the user

2. The user must open the main app

3. The user must toggle the "Always On" setting in the app to properly disable VPN On Demand and stop the VPN