HomeConsole

Client Network List (CNL)

The Unified SDK allows you to automatically enable or disable VPN sessions based on network changes, such as when a user switches between Wi-Fi, mobile data, or other networks.

Setting Up Client Networks

To set up this feature, follow these steps:

  1. Sign in at pango-cloud.com.

  2. Navigate to Settings -> VPN -> Client Networks, click on the Add button.

  3. Edit the client network settings: Type (Wi-Fi, WWAN, LAN) and Action (enable/disable). \

When the SDK enables the VPN for the first time, it downloads the necessary network configuration from the server. If there is no active VPN session, the SDK displays a notification based on the CNL settings.

Practical Use Cases and Configuration Examples

Common CNL Configuration Scenarios

Here are some practical examples of how to configure CNL rules for common use cases:

1. Enable VPN on All Open/Public WiFi Networks

To automatically enable VPN when connecting to any open (unencrypted) WiFi network:

  • Type: WiFi

  • SSID: (leave empty)

  • BSSID: (leave empty)

  • Authorized: False

  • Action: Enable

This configuration will activate the VPN whenever your device connects to an unsecured WiFi network, providing protection on public hotspots.

2. Disable VPN on Cellular/Mobile Data

To conserve mobile data and battery by disabling VPN when on cellular:

  • Type: WWAN

  • Action: Disable

This is useful when you trust your mobile carrier's network and want to avoid the additional data overhead of VPN tunneling.

3. Disable VPN on Trusted Home/Office Networks

To disable VPN on specific trusted networks:

  • Type: WiFi

  • SSID: "MyHomeNetwork"

  • BSSID: "AA:BB:CC:DD:EE:FF" (optional, for extra security)

  • Action: Disable

Adding the BSSID ensures the rule only applies to your specific router, preventing spoofed SSIDs from bypassing VPN protection.

4. Always Enable VPN on Specific Public Networks

For known public networks where you always want protection:

  • Type: WiFi

  • SSID: "Starbucks WiFi"

  • Action: Enable

5. Corporate Network Configuration

For enterprise deployments where VPN should be disabled on corporate LAN:

  • Type: LAN

  • Action: Disable

Best Practices

  1. Security First: When in doubt, default to enabling VPN. It's better to have unnecessary protection than to expose sensitive data.

  2. Use BSSID for Critical Networks: For networks where you absolutely want to disable VPN (like home networks), include the BSSID to prevent SSID spoofing attacks.

  3. Test Your Rules: Always test CNL configurations in different network scenarios to ensure they behave as expected.

  4. Consider Battery and Data: Balance security needs with practical considerations like battery life and data usage, especially for mobile users.

Configuration Priority

When multiple rules might apply, the SDK evaluates them in the following order:

  1. Most specific rules (with both SSID and BSSID) take precedence

  2. Rules with only SSID come next

  3. Generic rules (no SSID/BSSID) are applied last

  4. If no rules match, the VPN state remains unchanged

Custom Notification for CNL State

You can customize the notification message shown to the user when the VPN is waiting for a secure network:

SdkNotificationConfig.Builder builder = SdkNotificationConfig.newBuilder();
builder.inCnl("Waiting for secure network","SDK will enable VPN when a secure network is detected");

If you don't customize the notification, it will display the default title and message:

  • title - CNL

  • message - Waiting

Rules for Network Matching

When a device changes its network connection, the SDK will look through the configured networks in CNL and match the current configuration with server.

For WiFi networks

  • If the SSID and BSSID are empty, it will match any Wifi network.

  • If the authentication is set to Does not matter , it will match both open and protected networks.

Android Permissions

  • For Android 8.1+ (API 27) and Android 10+ (API 29), you need to set up and request runtime permission for location to match networks by SSID and/or BSSID.

  • If the required permission is missing, the SDK will not be able to access the network SSID and BSSID.

VPN Enabled

The SDK provides a VPN Enabled feature that allows for seamless VPN connectivity. When this feature is active, the SDK will automatically handle connecting or reconnecting to a VPN service using either the default or last usedVPN profile or configuration.

Client-side CNL Configuration

The CNL configuration can also be managed on the client side.

Loading the list of saved network configurations

UnifiedSdk sdk = UnifiedSdk.getInstance();
Cnl cnl = sdk.getCnl();

cnl.loadList(new Callback<List<CnlConfig>>() {
    @Override
    public void success(@NonNull List<CnlConfig> configs) {
        // Handle the loaded list of CnlConfig objects
        for (CnlConfig config : configs) {
            System.out.println(config.toString());
            // Perform operations with the CnlConfig objects
        }
    }

    @Override
    public void failure(@NonNull VpnException e) {
        // Handle the failure case
        String errorMessage = e.getMessage();
    }
});

Updating the network configurations

UnifiedSdk sdk = UnifiedSdk.getInstance();
Cnl cnl = sdk.getCnl();

List<CnlConfig> updatedConfigs = new ArrayList<>();
newConfigs.add(new CnlConfig(
    CnlConfig.Type.WIFI,
    Arrays.asList("HomeWiFi", "OfficeWiFi"),
    Arrays.asList("00:11:22:33:44:55", "AA:BB:CC:DD:EE:FF"),
    CnlConfig.Action.ENABLE,
    CnlConfig.Authorized.YES
));
newConfigs.add(new CnlConfig(
    CnlConfig.Type.MOBILE,
    Collections.singletonList(""),
    Collections.singletonList(""),
    CnlConfig.Action.DISABLE,
    CnlConfig.Authorized.NO
));

cnl.updateList(updatedConfigs, new CompletableCallback() {    
    @Override
    public void complete() {
        // Handle the successful completion of the update operation
        System.out.println("CNL configurations updated successfully");
    }

    @Override
    public void error(@NonNull VpnException e) {
        // Handle the failure case
        System.out.println("Failed to update CNL configurations: " + e.getMessage());
    }
});

Resetting the network configurations

UnifiedSdk sdk = UnifiedSdk.getInstance();
Cnl cnl = sdk.getCnl();

cnl.clear(new CompletableCallback() {
    @Override
    public void complete() {
        System.out.println("CNL configurations cleared successfully");
        // Handle the successful completion of the clear operation
    }

    @Override
    public void error(@NonNull VpnException e) {
        // Handle the failure case
        System.out.println("Failed to clear CNL configurations: " + e.getMessage());
    }
});

VPN Disabled

When a user changes the network while a VPN session is active and the new network matches the CNL rules with the Disabled action, the SDK will not reconnect to this network. Instead, it will throw a CnlBlockedException in the VpnStateListener#vpnError callback. Below is an example message:

"VPN disabled. Connected to a network not allowed by CNL rules."
PreviousAuthenticationNextOpenVPN transport

Last updated

Was this helpful?