HomeGuidesAPI Reference
GuidesAPI ReferenceGitHubAirheads Developer CommunityLog In
Guides

AppRF Streaming Event

AppRF stream is the flow of all the client sessions, that is intra-internet bound happening in the network. Deep packet inspection on each client session is carried out and the sessions are classified into well-known application, application category, web category and web reputation. In addition, client's association details such as device type, client MAC on which the session happened, SSID and user role to which the client is associated with are available in the Apprf event messages.

In order for the AppRF Streaming Topic to have detailed messages, Deep Packet Inspection (DPI) configuration needs to be enabled for the devices. An AppRF message contains a list of all the client sessions for a given device (Instant AP).

AppRF Streaming Topic Protocol Buffer File

package Apprf;

message mac_address
{ 
    optional bytes addr = 1;
}

message ip_address
{
    enum addr_family
    {
        ADDR_FAMILY_UNSPEC = 0;
        ADDR_FAMILY_INET = 1;
        ADDR_FAMILY_INET6 = 2;
    }
    optional addr_family af = 1;
    optional bytes addr = 2;
}

message apprf_session 
    {
    optional string customer_id = 1;
    optional uint64 timestamp = 2;
    optional string serial_number = 3;
    repeated client_firewall_session client_firewall_session = 4;
    repeated url_detail_record url_detail_record = 5;
    optional string ap_name = 6;
    optional uint32 session_duration = 7;
    }

message client_firewall_session 
    { 
    optional ip_address client_ip = 1;
    optional mac_address client_mac = 2;
    optional ip_address dest_ip = 3;
    optional ingress_type_t ingress_type = 4;
    enum ingress_type_t 
    {
        INGRESS_WLAN  = 0;
        INGRESS_WIRED = 1;
        INGRESS_VPN  = 2;
    }
    optional uint32 ip_proto = 5; 
    optional string vlan = 6;  
    optional uint32 uplink_id = 7;  
    optional string uplink_name = 8;
    optional uint32 app_id = 9;
    optional string app_name = 10;
    optional uint32 app_cat_id = 11;
    optional string app_cat = 12;
    optional uint32 web_cat_id = 13;
    optional string web_cat = 14;
    optional uint32 web_rep_score = 15;
    optional string web_rep = 16;
    optional string dest_url_prefix = 17;  
    optional string domain = 18; 
    enum app_enforcement_status
    {
        ENF_PERMIT = 0;
        ENF_DENY = 1;
    }
    optional app_enforcement_status session_flags = 19;
    optional uint64 tx_bytes = 20;
    optional uint64 rx_bytes = 21;
    optional uint64 rtt = 22;   
    optional uint64 c2s_rtt = 23; 
    optional uint64 s2c_rtt = 24;
    optional uint64 packet_loss = 25;  
    optional uint64 c2s_packet_loss = 26;
    optional uint64 s2c_packet_loss = 27;
    optional string ssid = 28;
    optional string user_name = 29;
    optional string user_role = 30;
    optional string device_type = 31;
    optional uint64 timestamp = 32;
    optional bool preauth_flag = 33;
    optional unit32 dest_port = 34;

message url_detail_record 
   {
    enum url_http_method
    {
        NON_HTTP = 1;
        HTTP_GET = 2;
        HTTP_PUT = 3;
        HTTP_POST = 4;
        HTTP_HEAD = 5;
    }
    required ip_address client_ip = 1;
    required ip_address dest_ip = 2;
    required mac_address client_mac = 3;
    optional bytes dest_url_prefix = 4;
    optional uint32 hit_count = 5;
    optional url_http_method http_method = 6;
    optional uint64 last_hit_timestamp = 7;
}

Parameters Descriptions

The following table lists the field, type, rule, and descriptions of the above mentioned protobuf definition

Field

Type

Rule

Description

addr

bytes

Optional

Indicates the address field in bytes.

addr_family

enum

Indicates the enum address family. Contains one of the following:

  • ADDR_FAMILY_UNSPEC— Indicates that the IP Version is unspecified.
  • ADDR_FAMILY_INET— Indicates that the IP Version is IPv4.
  • ADDR_FAMILY_INET6— Indicates that the IP Version is IPv6.

af

addr_family

Optional

Indicates the IP version.

customer ID

string

Optional

Indicates the customer ID.

timestamp

uint64

Optional

Indicates the time of the session.

serial_number

string

Optional

Indicates the serial number of the client.

client_firewall_session

message

Repeated

Indicates the client sessions data.

url_detail_record

message

Repeated

Indicates the visited url information.

ap_name

string

Optional

Indicates the name of the access point.

session_duration

uint32

Optional

Indicates the time duration since the last statistics were streamed out for the device.

client_ip

ip_address

Optional

Indicates the IP information of the user who has triggered the event. This is determined by the client IP address.

client_mac

mac_address

Optional

Indicates the MAC address of the client.

dest_ip

ip_address

Optional

Indicates the destination IP address of the client.

ingress_type_t

enum

Indicates the client connection type, Wireless (WLAN) or Wired (WIRED). It contains any one of the following:

  • INGRESS_WLAN is wireless connection.
  • INGRESS_WIRED is wired connection.
  • INGRESS_VPN are the sessions coming from VIA VPN clients in the network.

ip_proto

uint32

Optional

Indicates the network protocol.

vlan

uint32

Optional

Indicates the customer configured user role.

uplink_id

uint32

Optional

Indicates the device uplink ID of the session.

uplink_name

string

Optional

Indicates the device uplink name of the session.

app_id

uint32

Optional

Indicates the app unique ID. AppRF supports 500+ apps and each each one has an unique ID.

app_name

string

Optional

Indicates the app name. AppRF supports 500+ apps.

app_cat_id

uint32

Optional

Indicates app category ID. AppRF supports 500+ apps and each one is assigned an app category ID.

app_cat

string

Optional

Indicates the App category. AppRF supports 500+ apps and each app is assigned a category.

web_cat_id

uint32

Optional

Indicates the web ID for the destination visited.

web_cat

string

Optional

Indicates the web category.

web_rep_score

uint32

Optional

Indicates the web reputation score for the destination visited.

web_rep

string

Optional

Indicates the web reputation for the destination visited, which is mapped using the web_rep_score.

dest_url_prefix

string

Optional

Indicates the URL link in the session, where the client made access.

app_enforcement_status

enum

Indicates the app enforcement status. It contains the following:

  • ENF_PERMIT— Client session that connected successfully.
  • ENF_DENY— Client session that is blocked by device.

session_flags

app_enforcement_status

Optional

Indicates the app enforcement status. It contains the enum app_enforcement_status.

tx_bytes

uint64

Optional

Indicates the number of bytes transmitted.

rx_bytes

uint64

Optional

Indicates the number of bytes of received.

rtt

uint64

Optional

Indicates the round trip time of the associated session.

c2s_rt

uint64

Optional

Indicates the client to server round trip time. This field is only supported in BGW messages.

s2c_rtt

uint64

Optional

Indicates the server to client round trip time. This field is only supported in BGW messages.

packet_loss

uint64

Optional

Indicates packet loss during communication. This field is only supported in BGW messages.

c2s_packet_loss

uint64

Optional

Indicates the client to server packet loss in the network.

s2c_packet_loss

uint64

Optional

Indicates the server to client packet loss in the network.

ssid

string

Optional

Indicates the client SSID.

username

string

Optional

Indicates the client name in the network.

user_role

string

Optional

Indicates the customer configured user role.

device_type

string

Optional

Indicates the client device type.

preauth_flag

bool

Optional

Indicates customer to filter out any blocked session that has preauth_flag = true.

dest_port

unit32

Optional

Indicates the destination port of the streamed AppRF sessions. The session in the streaming API is an aggregate of all the sessions of the client for the same application for 14 minutes.
For some applications, multiple destination ports are used for a set of actual sessions that were combined to a single aggregate session. In such a case the destination port is set to a value in one of the sessions.

url_http_method

enum

Indicates the enum fields that classify the HTTP Requests, which can be one of the following:

  • NON_HTTP
  • HTTP_GET
  • HTTP_PUT
  • HTTP_POST
  • HTTP_HEAD
dest_url_prefixbytesOptionalIndicates the URL that the client visited.
hit_countuint32OptionalIndicates the number of visits (hits) that the client URL has.
http_methodurl_http_methodOptionalIndicates the HTTP properties of the client URL.
last_hit_timestampuint64OptionalIndicates the last visited timestamp of the URL in the session.

Examples for the AppRF Message

The .proto file shown above consists of many messages. But, the message "apprf_session" contains all other messages nested in it. Therefore, the message apprf_session should be used to deserialize the AppRF events.

Following are the sample events received for the AppRF Streaming Topic:

  • IAP Message
customer_id: "6e81148a580444c0a3aa1e24171151d9"
timestamp: 1613616317
serial_number: "CNDRJSSCFT"

client_firewall_session {
client_ip {
af: ADDR_FAMILY_INET
addr: "\300\250\024\025"
}
dest_ip {
af: ADDR_FAMILY_INET
addr: "\254\331\244n"
}
ingress_type: INGRESS_WLAN
ip_proto: 0
app_id: 240
app_cat_id: 1
web_cat_id: 25
web_rep_score: 5
dest_url_prefix: "youtube.com"
session_flags: ENF_PERMIT
tx_bytes: 6918
rx_bytes: 111964
rtt: 0
packet_loss: 0
ssid: "NA"
user_role: "UD"
device_type: "Others"
timestamp: 1607041697
}
  • BWG Event
customer_id: "111952018"
timestamp: 1615322941
serial_number: "MCD1360044"

client_firewall_session {
client_ip {
af: ADDR_FAMILY_INET
addr: "\300\250\n\001"
}
dest_ip {
af: ADDR_FAMILY_INET
addr: "\n,\021\361"
}
ingress_type: INGRESS_WIRED
ip_proto: 17
vlan: Engineer
app_id: 10000
app_cat_id: 6
web_cat_id: 100
web_rep_score: 0
session_flags: ENF_PERMIT
tx_bytes: 588115
rx_bytes: 809977
rtt: 1
c2s_rtt: 3
s2c_rtt: 0
packet_loss: 2423
c2s_packet_loss: 4847
s2c_packet_loss: 0
ssid: "NA"
user_role: "UD"
device_type: "Others"
timestamp: 1607040992
}