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 Windows and macOS

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

Login required: Yes

CmdProc Code: OVS_CMD_SET_BINARY_PATH

Command number:

Input:

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

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

/folder/with/binaries
/openvpn
/openvpn
/wireguard
/wg
/wg-quick3
/wg-quick5
/wireguard-go
/ss2/
/shadowsocks2
/ipsec
/sbin
/ipsec
/swanctl

Response: OVS_NOTIFY_SET_BINARY_PATH

OVS_NOTIFY_SET_ENCRYPTION Successful response
    OVS_ERR_OK

Code sample:

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

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:

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 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);
}