FSM: DPI Client Plugins Rework

1 General
2 Configuring an Existing DPI Client Plugin
3 Known Limitations
4 Northbound API
- 4.1 DNS DPI Plugin
- 4.2 ADT DPI Plugin
- 4.3 SNI DPI plugin
- 4.4 APP DPI Plugin

General

DPI client plugins have two roles:

Leveraging the attributes captured and reported by the Walleye DPI engine (deep packet inspection of data streams)
DPI client plugins make the need to re-program the protocol parsers in native C obsolete. The Walleye team creates signatures to extract the information and to present the information back to the plugin as callbacks.

With this approach, it becomes possible to give multiple client plugins the ability to monitor the same Walleye attribute. For example, fsm_dpi_dns is triggered on the DNS-specific attributes, applying some action and reporting through its own channel, while ADTv2 can also be triggered to report the information to a completely separate MQTT channel.

One client plugin (e.g., plugin fdm_dpi_XXX as defined by the shared library, lib_fsm_dpi_XXX.so) can be called multiple times. For this to happen, each instance must be registered using a different and unique handler. With this in mind, for example, it becomes possible to configure individual MQTT reporting channels for each instance.

Configuring an Existing DPI Client Plugin

As previously mentioned, all configuration is done using OVSDB entries. There are three main entries to focus on. All the configurations displayed below match FUT configuration for ADTv2; with some formatting added for readability:

In Flow_Service_Manager_Config:
Define the type, handler (must be kept unique), and the plugin shared object itself (with the full path to the .so file). Within other_config, there is the plugin-specific configuration. Note the connection with the policy_table (to be found in FSM_Policy below), and the flow_attributes (defined in Openflow_Tag below).

_uuid        : ef58~167f
_version     : 1ffb~6ea0
handler      : dev_dpi_adt
if_name      :
other_config : ["map",[["dpi_plugin","walleye_dpi"],
                       ["dso_init","fsm_dpi_adt_init"],
                       ["flow_attributes","${dev_dpi_adt}"],
                       ["mqtt_v","dev-test/ADT/opensync/XXXX600209/XXXXfeeb08a29b62aeade748"],
                       ["policy_table","dev_dpi_adt"],
                       ["provider_plugin","gatekeeper"]]]
pkt_capt_filter :
plugin       : /usr/opensync/lib/libfsm_dpi_adt.so
type         : dpi_client

In Openflow_Tag:

This table defines which Walleye engine attribute(s) the given DPI client plugin should be called back for. The format uses a set of attributes.

_uuid        : 61b5~8af2
_version     : 059c~0bac
cloud_value  : ["set",["dns.qname","http.host","http.user-agent"]]
device_value : ["set",[]]
name         : dev_dpi_adt

In FSM_Policy:

This table enables executing the policy that defines for which devices this plugin is actually enabled.

_uuid        : 0817~4698
_version     : e927~0d8c
action       : gatekeeper
app_op       : ["set",[]]
apps         : ["set",[]]
fqdn_op      : ["set",[]]
fqdncat_op   : ["set",[]]
fqdncats     : ["set",[]]
fqdns        : ["set",[]]
idx          : 6
ipaddr_op    : ["set",[]]
ipaddrs      : ["set",[]]
log          : all
mac_op       : out
macs         : ["set",[]]
name         : dev_dpi_adt_rule_0
next         : ["map",[]]
other_config : ["map",[]]
policy       : dev_dpi_adt
redirect     : ["set",[]]
risk_level   : ["set",[]]
risk_op      : ["set",[]]

Examples of scripted configurations can be found within the FUT scripts provided on GitHub.

Upon configuration and instantiation of a DPI client plugin, the monitored attributes are logged (TRACE level). The output looks like this (output from logread -f | grep fsm_print):

Each monitored attribute is displayed with the dpi_client handler’s name. From the above output, we can see that we have 3 DPI client plugins enabled (dev_dpi_dns, dev_dpi_adt and dpi_sni), and that two attributes (dns.qname and http.host) are monitored by more than one plugin.

Known Limitations

As currently implemented, there is no provision for “plugin precedence”. If one configures more than one client plugin to listen on a given attribute, there is no guarantee on the order in which the plugins are executed and evaluated (but all plugins are evaluated). While this is of no consequence if only one plugin takes an authoritative action (other plugins are only monitoring/reporting), this could lead to more non-deterministic behavior if two client plugins “disagree” on the action to be taken. The behavior is well commented in fsm/src/fsm_dpi_client.c as part of the fsm_dpi_call_client() function.

Each possible action is given a weight. In case of multiple clients, the “heavier” action wins, so that the “heaviest” action is the one that is ultimately reported. Current weights are as follows (in fsm/src/fsm_dpi_client.c):

It may not be possible to have individualized reporting intervals for each of the DPI client plugins.

Northbound API

DNS DPI Plugin

Please refer to: https://opensync.atlassian.net/wiki/spaces/~154187874/pages/39884128362

ADT DPI Plugin

Please refer to: https://opensync.atlassian.net/wiki/spaces/~154187874/pages/39884357712

SNI DPI plugin

The FSM plugin:

The OpenFlow tag:

APP DPI Plugin

OpenFlow tag setting:

The FSM plugin