Skip to main content

VPN Commands

Set, start and stop a VPN connection.

Set Binary Path​

Sets the path for OpenVPN, StrongSwan, Shadowsocks and WireGuard binaries.

Required step for macOS

When using the C library on macOS, SET_BINARY_PATH should be called prior starting any VPN connection.

Login required: Yes

CmdProc Code: OVS_CMD_SET_BINARY_PATH

Command number: 31

Input:

{
    "path": "/folder/with/binaries"
}

path - The folder with the binaries. The folder itself should have the following structure:

folder/with/binaries/
    openvpn-x86_64/
        sbin/
                openvpn
    ipsec-x86_64/
            etc/
            lib/
            libexec/
            sbin/
    wireguard-x86_64/
            wg
            wg-quick3
            wg-quick5
            wireguard-go
    openvpn-arm64/
        sbin/
                openvpn
    ipsec-arm64/
            etc/
            lib/
            libexec/
            sbin/
    wireguard-arm64/
            wg
            wg-quick3
            wg-quick5
            wireguard-go
    ss2/
            shadowsocks2-macos-amd64
            shadowsocks2-macos-arm64

Response: OVS_NOTIFY_SET_BINARY_PATH

OVS_NOTIFY_SET_BINARY_PATH Successful response
    OVS_ERR_OK

Code sample:

macOS Code Sample
    void setStrongswanPath(const char *path)
    {
        json_object *j_obj, *j_data_obj;
        char szCmd[1024];
        j_obj = json_object_new_object();
        json_object_object_add(j_obj, "cmd", json_object_new_int(OVS_CMD_SET_BINARY_PATH));
        j_data_obj = json_object_new_object();
        json_object_object_add(j_data_obj, "path", json_object_new_string(path));
        json_object_object_add(j_obj, "data", j_data_obj);
        snprintf(szCmd, sizeof(szCmd), "%s", json_object_get_string(j_obj));
        json_object_put(j_obj);
        CmdProc(szCmd); 
    }

Start VPN Connection​

Establishes a VPN connection with a given server.

Using different protocols

You can select a VPN protocol by using the Set VPN Type command.

When using the C library on macOS, SET_BINARY_PATH should be called prior starting any VPN connection.

Login required: Yes

CmdProc Code: OVS_CMD_CONNECT

Command number: 3

Input:

Values to establish an OpenVPN connection
    {
        "ip_addr": "104.192.3.90",
        "proto": "tcp",
        "port": 1194,
        "ipv6_leak": 1,
        "kill_switch": 1
    }

ip_addr - VPN server's IP address

proto - Use UDP or TCP protocol

port - Use this port to connect. Available ports are returned by server list methods

ipv6_leak - Enable or disable ipv6 leak prevention

kill_switch - Enable or disable existing connections drop

Response:

This method doesn't invoke any callback. While establishing connection, the SDK will notify application with the following notifications when connection status is changed (data property is set to null):

OVS_NOTIFY_VPN_CONNECTING

OVS_NOTIFY_VPN_CONNECTED 

OVS_NOTIFY_VPN_DISCONNECTED

OVS_NOTIFY_VPN_CONNECT_FAILED

OVS_NOTIFY_VPN_ABNOMARLY_DISCONNECTED

Code sample:

Windows Code Sample
    void StartVPNConnection(const char *ip_addr, const char *proto, const char *port, int ipv6_leak, int kill_switch)
    {
            Json::Value val;
            Json::Value data;
            val["cmd"] = OVS_CMD_CONNECT;
            data["ip_addr"] = ip_addr;
            data["proto"] = proto;
            data["port"] = port;
            data["ipv6_leak"] = ipv6_leak;
            data["ip_addr"] = ip_addr;
            data["kill_switch"] = kill_switch;
            val["data"] = data;
            CmdProc(jsonToString(val).c_str());
    }

Stop VPN Connection​

Stops the established VPN connection. Once VPN is successfully disconnected, the SDK sends OVS_NOTIFY_VPN_DISCONNECTED notification.

Login required: Yes

CmdProc Code: OVS_CMD_DISCONNECT

Command number: 4

Input: Not required

Response: OVS_NOTIFY_VPN_DISCONNECTED

OVS_NOTIFY_VPN_DISCONNECTED Successful response
    OVS_ERR_OK

    data is null

Code sample:

macOS Code Sample
    void StopVPNConnection()
    {
        json_object *j_obj;
        char szCmd[1024];
        j_obj = json_object_new_object();
        json_object_object_add(j_obj, "cmd", json_object_new_int(OVS_CMD_DISCONNECT));
        snprintf(szCmd, sizeof(szCmd), "%s", json_object_get_string(j_obj));
        json_object_put(j_obj);
        CmdProc(szCmd); 
    }

Get servers list by geolocation​

Requests available VPN servers and sorts them from nearest to farest based on the estimated location of the end-user's IP address (GeoIP).

Login required: No

CmdProc Code: OVS_CMD_GET_SERVLIST_BYGEO

Command number: 24

Input: 

{
    "premium": true | false
}

premium - optional flag to select between premium and non-premium server list (true by default).

Response: OVS_NOTIFY_GET_SERVLIST_BYGEO

OVS_NOTIFY_GET_SERVLIST_BYGEO Successful response
    OVS_ERR_OK

    data contains the available server list.

Server data response includes the following array of objects respresenting each server's parameters:

ip - Server's ip address
hostname - Server host name
protocols - Supported protocols (L2TP, OpenVPN, IKEv2, WireGuard)
name - Human readable server name
country - Country code
cipher - Array of available ciphers
cipher_tcp_ports - Available TCP ports
cipher_upd_ports - Available UDP ports
lz4 - LZ4 support
lz4_port - Port where LZ4 is supported
xor - XOR support
xor_ports - Port where XOR is supported
smart_dns_id - Smart DNS ID (for Smart DNS API)
flag - URL for server's country flag
lat - Server latitude
lon - Server longitude
distance - Physical distance from the end-user's estimated location to the server location
ipv6_enabled - Server supports Wireguard IPv6
ipv6_prefix - IPv6 address prefix for Wireguard IPv6
wg_port - Port where Wireguard service is listening
wg_public - Wireguard public key

Code sample:

macOS Code Sample
    void GetServerListbyGeo(bool premium)
    {
        json_object *j_obj, *j_data_obj;
        char szCmd[1024];
        j_obj = json_object_new_object();
        json_object_object_add(j_obj, "cmd", json_object_new_int(OVS_CMD_GET_SERVLIST_BYGEO));
        j_data_obj = json_object_new_object();
        json_object_object_add(j_data_obj, "premium", json_object_new_boolean(premium));
        json_object_object_add(j_obj, "data", j_data_obj);
        snprintf(szCmd, sizeof(szCmd), "%s", json_object_get_string(j_obj));
        json_object_put(j_obj);
        CmdProc(szCmd);
    }

Get servers list by country​

Requests available VPN servers and sorts them from nearest to farest based on the specified country.

Login required: No

CmdProc Code: OVS_CMD_GET_SERVLIST_BYCOUNTRY

Command number: 25

Input: 

{
    country": "",
    "premium": true | false
}

country - two characters ISO country code (for example - US, CA, FR).

premium - optional flag to select between premium and non-premium server list (true by default).

Response: OVS_NOTIFY_GET_SERVLIST_BYCOUNTRY

OVS_NOTIFY_GET_SERVLIST_BYCOUNTRY Successful response
    OVS_ERR_OK

    data contains the available server list.

Server data response includes the following array of objects respresenting each server's parameters:

ip - Server's ip address
hostname - Server host name
protocols - Supported protocols (L2TP, OpenVPN, IKEv2, WireGuard)
name - Human readable server name
country - Country code
cipher - Array of available ciphers
cipher_tcp_ports - Available TCP ports
cipher_upd_ports - Available UDP ports
lz4 - LZ4 support
lz4_port - Port where LZ4 is supported
xor - XOR support
xor_ports - Port where XOR is supported
smart_dns_id - Smart DNS ID (for Smart DNS API)
flag - URL for server's country flag
lat - Server latitude
lon - Server longitude
distance - Physical distance from the end-user's estimated location to the server location

Code sample:

macOS Code Sample
    void GetServerListbyCountry(const char *country, bool premium)
    {
        json_object *j_obj, *j_data_obj;
        char szCmd[1024];
        j_obj = json_object_new_object();
        json_object_object_add(j_obj, "cmd", json_object_new_int(OVS_CMD_GET_SERVLIST_BYCOUNTRY));
        j_data_obj = json_object_new_object();
        json_object_object_add(j_data_obj, "country", json_object_new_string(country));
        json_object_object_add(j_data_obj, "premium", json_object_new_boolean(premium));
        json_object_object_add(j_obj, "data", j_data_obj);
        snprintf(szCmd, sizeof(szCmd), "%s", json_object_get_string(j_obj));
        json_object_put(j_obj);
        CmdProc(szCmd);
    }

Switch VPN Server​

Switch to the specified VPN server.

Login required: Yes

CmdProc Code: OVS_CMD_SWITCH_VPN_SERVER

Command number: 41

Input: { "ip_addr": "45.79.163.199", "server_name": "us-new-jersey.keenvpn.me" }

ip_addr - The designated VPN server's IP address

server_name - The designated VPN server's hostname

Response: OVS_NOTIFY_SWITCH_VPN_SERVER

OVS_NOTIFY_SWITCH_VPN_SERVER Successful response
    OVS_ERR_OK

    data is null

Code sample:

Windows Code Sample
    void switchVpnServer(const char *ip_addr, const char *server_name)
    {
        json_object *j_obj, *j_data_obj;
        char szCmd[1024];
        j_obj = json_object_new_object();
        json_object_object_add(j_obj, "cmd", json_object_new_int(OVS_CMD_SWITCH_VPN_SERVER));
        j_data_obj = json_object_new_object();
        json_object_object_add(j_data_obj, "ip_addr", json_object_new_string(ip_addr));
        json_object_object_add(j_data_obj, "server_name", json_object_new_string(server_name));
        json_object_object_add(j_obj, "data", j_data_obj);
        snprintf(szCmd, sizeof(szCmd), "%s", json_object_get_string(j_obj));
        json_object_put(j_obj);
        CmdProc(szCmd); 
    }

Set VPN Type​

Change VPN Protocol

Login required: Yes

CmdProc Code: OVS_CMD_SET_VPN_TYPE

Command number: 51

Input:

{
    "vpn_type": 0
}

vpn_type can be any of the following:

0: OpenVPN

1: IKEv2-IPSec

2: WireGuard

3: ShadowSocks

Response: OVS_NOTIFY_SET_VPN_TYPE

OVS_NOTIFY_SET_VPN_TYPE Successful response
    OVS_ERR_OK

Code sample:

Windows Code Sample
    void setVPNType(int type)
    {
        json_object *j_obj, *j_data_obj;
        char szCmd[1024];
        j_obj = json_object_new_object();
        json_object_object_add(j_obj, "cmd", json_object_new_int(OVS_CMD_SET_VPN_TYPE));
        j_data_obj = json_object_new_object();
        json_object_object_add(j_data_obj, "vpn_tye", json_object_new_int(type));
        json_object_object_add(j_obj, "data", j_data_obj);
        snprintf(szCmd, sizeof(szCmd), "%s", json_object_get_string(j_obj));
        json_object_put(j_obj);
        CmdProc(szCmd); 
    }

Set Adblock​

Enabled or disables Adblock functionality

Login required: Yes

CmdProc Code: OVS_CMD_SET_ADBLOCK

Comand number: 81

Input:

{
    "adblock": "0"|"1"
}

adblock - 0: Adblock disabled for current user, 1: Adblock enabled for current user

Response: OVS_NOTIFY_SET_ADBLOCK

OVS_NOTIFY_SET_ADBLOCK Successful response
        OVS_ERR_OK

Code Sample

macOS Code Sample
        void SetAdblock(const char *adblock)
        {
                json_object *j_obj, *j_data_obj;
                char szCmd[1024];
                j_obj = json_object_new_object();
                json_object_object_add(j_obj, "cmd", json_object_new_int(OVS_CMD_SET_ADBLOCK));
                j_data_obj = json_object_new_object();
                json_object_object_add(j_data_obj, "adblock", json_object_new_string(adblock));
                json_object_object_add(j_obj, "data", j_data_obj);
                snprintf(szCmd, sizeof(szCmd), "%s", json_object_get_string(j_obj));
                json_object_put(j_obj);
                CmdProc(szCmd);
        }

Get Adblock​

Get current Adblock functionality status

Login required: Yes

CmdProc Code: OVS_CMD_GET_ADBLOCK

Comand number: 82

Input: Not required

Response: OVS_NOTIFY_GET_ADBLOCK

OVS_NOTIFY_GET_ADBLOCK Successful response
        OVS_ERR_OK

    {
        "adblock": "0"|"1"
    }

Code Sample

macOS Code Sample
        void GetAdblock()
        {
                json_object *j_obj, *j_data_obj;
                char szCmd[1024];
                j_obj = json_object_new_object();
                json_object_object_add(j_obj, "cmd", json_object_new_int(OVS_CMD_GET_ADBLOCK));
                snprintf(szCmd, sizeof(szCmd), "%s", json_object_get_string(j_obj));
                json_object_put(j_obj);
                CmdProc(szCmd);
        }

Set OpenVPN cipher​

Sets a cipher for OpenVPN connection

Login required: Yes

CmdProc Code: OVS_CMD_SET_ENCRYPTION

Command number: 14

Input:

{
     "cipher": "AES-256-CBC"
}

cipher - Cipher name. Supported ciphers could be retrived by one of the server list functions listed above.

Response: OVS_NOTIFY_SET_ENCRYPTION

OVS_NOTIFY_SET_ENCRYPTION Successful response
    OVS_ERR_OK

Code sample:

macOS Code Sample
    void SetEncryption(const char *cipher)
    {
        json_object *j_obj, *j_data_obj;
        char szCmd[1024];
        j_obj = json_object_new_object();
        json_object_object_add(j_obj, "cmd", json_object_new_int(OVS_CMD_SET_ENCRYPTION));
        j_data_obj = json_object_new_object();
        json_object_object_add(j_data_obj, "cipher", json_object_new_string(cipher));
        json_object_object_add(j_obj, "data", j_data_obj);
        snprintf(szCmd, sizeof(szCmd), "%s", json_object_get_string(j_obj));
        json_object_put(j_obj);
        CmdProc(szCmd); 
    }