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.

Important Requirement: The CNL feature requires the VPN to be started at least once to obtain necessary permissions and establish a default VPN profile. Without this initial setup, CNL rules cannot function properly on Android devices.

Overview

Unified SDK provides ability to automatically start/stop VPN session when user changes network.

After VPN connection first start, SDK will download configuration from server. When user is not running active VPN session, SDK will show notification configured by CNL state of NotificationConfigBuilder.

The CNL (Client Network List) feature allows you to configure rules that automatically enable or disable VPN based on the current network connection. When the device connects to a network that matches a CNL rule, the SDK will automatically start or stop the VPN session accordingly.

Setting Up Client Networks

List of network conditions are configured on dashboard. 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");
UnifiedSDK.update(builder.build());

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

• title - CNL

• message - Waiting

Accessing CNL API

The CNL interface is accessed through the UnifiedSdk instance:

UnifiedSdk sdk = UnifiedSdk.getInstance();
Cnl cnl = sdk.cnl; // Get CNL interface

CNL Interface Methods

loadList(callback)

Loads the current CNL configuration list from local storage.

sdk.cnl.loadList(new Callback<List<CnlConfig>>() {
    @Override
    public void success(List<CnlConfig> configs) {
        // Handle loaded configurations
        for (CnlConfig config : configs) {
            Log.d("CNL", "Type: " + config.getType() + ", Action: " + config.getAction());
        }
    }

    @Override
    public void failure(VpnException error) {
        // Handle error
        Log.e("CNL", "Failed to load CNL: " + error.getMessage());
    }
});

updateList(configs, callback)

Updates the CNL configuration list. This replaces the existing list with the provided configurations.

List<CnlConfig> configs = new ArrayList<>();

// Add a rule: Enable VPN on any WiFi network
CnlConfig publicWifiRule = new CnlConfig(
    CnlConfig.Type.WIFI,
    Arrays.asList(""),  // Empty SSID = match any
    Arrays.asList(""),  // Empty BSSID = match any
    CnlConfig.Action.ENABLE,
    CnlConfig.Authorized.UNKNOWN
);
configs.add(publicWifiRule);

sdk.cnl.updateList(configs, new CompletableCallback() {
    @Override
    public void complete() {
        Log.d("CNL", "CNL rules updated successfully");
    }

    @Override
    public void error(VpnException error) {
        Log.e("CNL", "Failed to update CNL: " + error.getMessage());
    }
});

clear(callback)

Clears all CNL configurations.

sdk.cnl.clear(new CompletableCallback() {
    @Override
    public void complete() {
        Log.d("CNL", "All CNL rules cleared");
    }

    @Override
    public void error(VpnException error) {
        Log.e("CNL", "Failed to clear CNL: " + error.getMessage());
    }
});

CnlConfig Data Structure

CnlConfig config = new CnlConfig(
    type,        // Network type: WIFI, MOBILE, or LAN
    ssid,        // List of WiFi SSIDs (empty = match any)
    bssid,       // List of WiFi BSSIDs (empty = match any)
    action,      // Action: ENABLE or DISABLE VPN
    authorized   // Authorization: UNKNOWN, YES, or NO
);

Network Types

• CnlConfig.Type.WIFI - WiFi networks

• CnlConfig.Type.MOBILE - Mobile/cellular networks (WWAN)

• CnlConfig.Type.LAN - Ethernet/LAN networks

Actions

• CnlConfig.Action.ENABLE - Start VPN when matching network is detected

• CnlConfig.Action.DISABLE - Stop VPN when matching network is detected

Authorization Status

• CnlConfig.Authorized.UNKNOWN - Match both open and protected networks

• CnlConfig.Authorized.YES - Only match authorized/protected networks

• CnlConfig.Authorized.NO - Only match open/unprotected networks

Usage Examples

Example 1: Enable VPN on Public WiFi

Automatically enable VPN when connecting to any public WiFi network:

UnifiedSdk sdk = UnifiedSdk.getInstance();

// Load existing rules first
sdk.cnl.loadList(new Callback<List<CnlConfig>>() {
    @Override
    public void success(List<CnlConfig> existingConfigs) {
        // Create new rule
        CnlConfig publicWifiRule = new CnlConfig(
            CnlConfig.Type.WIFI,
            Arrays.asList(""),  // Match any SSID
            Arrays.asList(""),  // Match any BSSID
            CnlConfig.Action.ENABLE,
            CnlConfig.Authorized.UNKNOWN  // Match both open and protected
        );
    
        // Add to existing list
        List<CnlConfig> updatedConfigs = new ArrayList<>(existingConfigs);
        updatedConfigs.add(publicWifiRule);
        
        // Save updated list
        sdk.cnl.updateList(updatedConfigs, new CompletableCallback() {
            @Override
            public void complete() {
                Log.d("CNL", "Public WiFi rule added");
            }

            @Override
            public void error(VpnException error) {
                Log.e("CNL", "Failed to update: " + error.getMessage());
            }
        });
    }

    @Override
    public void failure(VpnException error) {
        Log.e("CNL", "Failed to load existing rules: " + error.getMessage());
    }
});

Example 2: Disable VPN on Trusted Home Network

Automatically disable VPN when connecting to your home WiFi:

UnifiedSdk sdk = UnifiedSdk.getInstance();

sdk.cnl.loadList(new Callback<List<CnlConfig>>() {
    @Override
    public void success(List<CnlConfig> existingConfigs) {
        // Create rule for home WiFi
        CnlConfig homeWifiRule = new CnlConfig(
            CnlConfig.Type.WIFI,
            Arrays.asList("MyHomeWiFi"),  // Specific SSID
            Arrays.asList(""),            // Any BSSID
            CnlConfig.Action.DISABLE,
            CnlConfig.Authorized.YES  // Only match protected networks
        );
    
        List<CnlConfig> updatedConfigs = new ArrayList<>(existingConfigs);
        updatedConfigs.add(homeWifiRule);
        
        sdk.cnl.updateList(updatedConfigs, new CompletableCallback() {
            @Override
            public void complete() {
                Log.d("CNL", "Home WiFi rule added - VPN will auto-disable");
            }

            @Override
            public void error(VpnException error) {
                Log.e("CNL", "Failed to update: " + error.getMessage());
            }
        });
    }

    @Override
    public void failure(VpnException error) {
        Log.e("CNL", "Failed to load: " + error.getMessage());
    }
});

Example 3: Enable VPN on Mobile Data

Always enable VPN when using mobile/cellular data:

UnifiedSdk sdk = UnifiedSdk.getInstance();

sdk.cnl.loadList(new Callback<List<CnlConfig>>() {
    @Override
    public void success(List<CnlConfig> existingConfigs) {
        CnlConfig mobileRule = new CnlConfig(
            CnlConfig.Type.MOBILE,
            Arrays.asList(),  // Not applicable for mobile
            Arrays.asList(),  // Not applicable for mobile
            CnlConfig.Action.ENABLE,
            CnlConfig.Authorized.UNKNOWN
        );
    
        List<CnlConfig> updatedConfigs = new ArrayList<>(existingConfigs);
        updatedConfigs.add(mobileRule);
        
        sdk.cnl.updateList(updatedConfigs, new CompletableCallback() {
            @Override
            public void complete() {
                Log.d("CNL", "Mobile data rule added");
            }

            @Override
            public void error(VpnException error) {
                Log.e("CNL", "Failed to update: " + error.getMessage());
            }
        });
    }

    @Override
    public void failure(VpnException error) {
        Log.e("CNL", "Failed to load: " + error.getMessage());
    }
});

Example 5: Clear All CNL Rules

UnifiedSdk sdk = UnifiedSdk.getInstance();

sdk.cnl.clear(new CompletableCallback() {
    @Override
    public void complete() {
        Log.d("CNL", "All CNL rules cleared");
    }

    @Override
    public void error(VpnException error) {
        Log.e("CNL", "Failed to clear CNL: " + error.getMessage());
    }
});

Dashboard Configuration

CNL rules can also be configured on the dashboard:

1. Open https://www.pango-cloud.com

2. Under your project, select Settings → Client Networks

3. Configure list of network conditions (SSID, BSSID, authorization, type) and actions (start/stop)

After the first VPN connection, the SDK will download the configuration from the server. Programmatically configured rules (via updateList) take precedence over server-configured rules.

Notifications

When CNL is active and waiting for a matching network, the SDK will show a notification. Configure this notification using SdkNotificationConfig:

SdkNotificationConfig.Builder builder = SdkNotificationConfig.newBuilder();
builder.inCnl("VPN Waiting", "Waiting for configured network");
UnifiedSDK.update(builder.build());

If no notification title/message is configured, it will use default values:

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

WiFi Network Matching

If network type is set to WiFi:

• If SSID and BSSID are empty - it will match any WiFi network

• If authentication is "Does not matter" - it will match open and protected networks

• If authorization is UNKNOWN - it will match both open and protected networks

• If authorization is YES - it will only match protected/authorized networks

• If authorization is NO - it will only match open/unprotected networks

Rule Evaluation

• Rules are evaluated in the order they appear in the list

• The first matching rule determines the action (ENABLE or DISABLE)

• If no rules match, the current VPN state is maintained

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.

Permissions Required

Android 8.1+ (API 27)

If you want to match network by SSID and/or BSSID on Android 8.1+ (API 27), you need to setup and request runtime permission for use location:

• ACCESS_COARSE_LOCATION

• ACCESS_WIFI_STATE - required for accessing WiFi information

Android 10+ (API 29)

If you want to match network by SSID and/or BSSID on Android 10+ (API 29), you need to setup and request runtime permission for use location:

• ACCESS_FINE_LOCATION

• ACCESS_WIFI_STATE - required for accessing WiFi information

Note: In case of missing permission, the SDK will not be able to get network SSID and BSSID, and WiFi-specific rules may not work correctly.

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.cnl;

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.cnl;

List<CnlConfig> updatedConfigs = new ArrayList<>();
updatedConfigs.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
));
updatedConfigs.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.cnl;

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

Best Practices

1. Always load existing rules before updating - Use loadList() first, then modify and call updateList()

2. Test on real devices - SSID/BSSID matching requires actual network connections

3. Consider user experience - Auto-enabling VPN may surprise users; provide clear UI

4. Provide UI for rule management - Allow users to view and manage their CNL rules

5. Clear rules when appropriate - Consider clearing CNL rules on logout or app uninstall