{"type":"doc","content":[{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{},"macroMetadata":{"macroId":{"value":"58e95487-1d8a-4b65-b8c1-60078ca1c9fb"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"cc1c6067-6502-41b3-9687-656db306dd07"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"General","type":"text"}]},{"type":"paragraph","content":[{"text":"DPI client plugins have two roles:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Leveraging the attributes captured and reported by the Walleye DPI engine (deep packet inspection of data streams)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"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.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"With this approach, it becomes possible to give multiple client plugins the ability to monitor the same Walleye attribute. For example, ","type":"text"},{"text":"fsm_dpi_dns","type":"text","marks":[{"type":"code"}]},{"text":" 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.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"One client plugin (e.g., plugin ","type":"text"},{"text":"fdm_dpi_XXX","type":"text","marks":[{"type":"code"}]},{"text":" as defined by the shared library, ","type":"text"},{"text":"lib_fsm_dpi_XXX.so","type":"text","marks":[{"type":"code"}]},{"text":") can be called multiple times. For this to happen, each instance must be registered using a different and unique ","type":"text"},{"text":"handler","type":"text","marks":[{"type":"code"}]},{"text":". With this in mind, for example, it becomes possible to configure individual MQTT reporting channels for each instance.","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Configuring an Existing DPI Client Plugin","type":"text"}]},{"type":"paragraph","content":[{"text":"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:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In ","type":"text"},{"text":"Flow_Service_Manager_Config","type":"text","marks":[{"type":"code"}]},{"text":":","type":"text"},{"type":"hardBreak"},{"text":"Define the type, handler (must be kept unique), and the plugin shared object itself (with the full path to the .so file). Within ","type":"text"},{"text":"other_config","type":"text","marks":[{"type":"code"}]},{"text":", there is the plugin-specific configuration. Note the connection with the ","type":"text"},{"text":"policy_table","type":"text","marks":[{"type":"code"}]},{"text":" (to be found in ","type":"text"},{"text":"FSM_Policy","type":"text","marks":[{"type":"code"}]},{"text":" below), and the ","type":"text"},{"text":"flow_attributes","type":"text","marks":[{"type":"code"}]},{"text":" (defined in ","type":"text"},{"text":"Openflow_Tag","type":"text","marks":[{"type":"code"}]},{"text":" below).","type":"text"}]}]}]},{"type":"codeBlock","content":[{"text":"_uuid : ef58~167f\n_version : 1ffb~6ea0\nhandler : dev_dpi_adt\nif_name :\nother_config : [\"map\",[[\"dpi_plugin\",\"walleye_dpi\"],\n [\"dso_init\",\"fsm_dpi_adt_init\"],\n [\"flow_attributes\",\"${dev_dpi_adt}\"],\n [\"mqtt_v\",\"dev-test/ADT/opensync/XXXX600209/XXXXfeeb08a29b62aeade748\"],\n [\"policy_table\",\"dev_dpi_adt\"],\n [\"provider_plugin\",\"gatekeeper\"]]]\npkt_capt_filter :\nplugin : /usr/opensync/lib/libfsm_dpi_adt.so\ntype : dpi_client\n\n","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In ","type":"text"},{"text":"Openflow_Tag","type":"text","marks":[{"type":"code"}]},{"text":":","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"codeBlock","content":[{"text":"_uuid : 61b5~8af2\n_version : 059c~0bac\ncloud_value : [\"set\",[\"dns.qname\",\"http.host\",\"http.user-agent\"]]\ndevice_value : [\"set\",[]]\nname : dev_dpi_adt\n\n","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In ","type":"text"},{"text":"FSM_Policy:","type":"text","marks":[{"type":"code"}]}]}]}]},{"type":"paragraph","content":[{"text":"This table enables executing the policy that defines for which devices this plugin is actually enabled.","type":"text"}]},{"type":"codeBlock","content":[{"text":"_uuid : 0817~4698\n_version : e927~0d8c\naction : gatekeeper\napp_op : [\"set\",[]]\napps : [\"set\",[]]\nfqdn_op : [\"set\",[]]\nfqdncat_op : [\"set\",[]]\nfqdncats : [\"set\",[]]\nfqdns : [\"set\",[]]\nidx : 6\nipaddr_op : [\"set\",[]]\nipaddrs : [\"set\",[]]\nlog : all\nmac_op : out\nmacs : [\"set\",[]]\nname : dev_dpi_adt_rule_0\nnext : [\"map\",[]]\nother_config : [\"map\",[]]\npolicy : dev_dpi_adt\nredirect : [\"set\",[]]\nrisk_level : [\"set\",[]]\nrisk_op : [\"set\",[]]\n\n","type":"text"}]},{"type":"paragraph","content":[{"text":"Examples of scripted configurations can be found within the FUT scripts provided on GitHub.","type":"text"}]},{"type":"paragraph","content":[{"text":"Upon configuration and instantiation of a DPI client plugin, the monitored attributes are logged (","type":"text"},{"text":"TRACE","type":"text","marks":[{"type":"code"}]},{"text":" level). The output looks like this (output from ","type":"text"},{"text":"logread -f | grep fsm_print)","type":"text","marks":[{"type":"code"}]},{"text":":","type":"text"}]},{"type":"codeBlock","content":[{"text":" MISC: fsm_print_dpi_clients: Start\n MISC: fsm_print_one_dpi_client: ---> begin : 1 callback\n MISC: fsm_print_one_dpi_client: --->---> dev_dpi_dns\n MISC: fsm_print_one_dpi_client: ---> dns.a : 1 callback\n MISC: fsm_print_one_dpi_client: --->---> dev_dpi_dns\n MISC: fsm_print_one_dpi_client: ---> dns.aaaa : 1 callback\n MISC: fsm_print_one_dpi_client: --->---> dev_dpi_dns\n MISC: fsm_print_one_dpi_client: ---> dns.qname : 2 callback\n MISC: fsm_print_one_dpi_client: --->---> dev_dpi_dns\n MISC: fsm_print_one_dpi_client: --->---> dev_dpi_adt\n MISC: fsm_print_one_dpi_client: ---> dns.ttl : 1 callback\n MISC: fsm_print_one_dpi_client: --->---> dev_dpi_dns\n MISC: fsm_print_one_dpi_client: ---> dns.type : 1 callback\n MISC: fsm_print_one_dpi_client: --->---> dev_dpi_dns\n MISC: fsm_print_one_dpi_client: ---> end : 1 callback\n MISC: fsm_print_one_dpi_client: --->---> dev_dpi_dns\n MISC: fsm_print_one_dpi_client: ---> http.host : 2 callback\n MISC: fsm_print_one_dpi_client: --->---> dev_dpi_adt\n MISC: fsm_print_one_dpi_client: --->---> dpi_sni\n MISC: fsm_print_one_dpi_client: ---> http.url : 1 callback\n MISC: fsm_print_one_dpi_client: --->---> dpi_sni\n MISC: fsm_print_one_dpi_client: ---> http.user-agent : 1 callback\n MISC: fsm_print_one_dpi_client: --->---> dev_dpi_adt\n MISC: fsm_print_one_dpi_client: ---> tls.sni : 1 callback\n MISC: fsm_print_one_dpi_client: --->---> dpi_sni\n MISC: fsm_print_dpi_clients: End\n\n","type":"text"}]},{"type":"paragraph","content":[{"text":"Each monitored attribute is displayed with the ","type":"text"},{"text":"dpi_client","type":"text","marks":[{"type":"code"}]},{"text":" handler’s name. From the above output, we can see that we have 3 DPI client plugins enabled (","type":"text"},{"text":"dev_dpi_dns","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"dev_dpi_adt","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"dpi_sni","type":"text","marks":[{"type":"code"}]},{"text":"), and that two attributes (","type":"text"},{"text":"dns.qname","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"http.host","type":"text","marks":[{"type":"code"}]},{"text":") are monitored by more than one plugin.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Known Limitations","type":"text"}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"all","type":"text","marks":[{"type":"strong"}]},{"text":" 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 ","type":"text"},{"text":"fsm/src/fsm_dpi_client.c","type":"text","marks":[{"type":"code"}]},{"text":" as part of the ","type":"text"},{"text":"fsm_dpi_call_client()","type":"text","marks":[{"type":"code"}]},{"text":" function.","type":"text"}]},{"type":"paragraph","content":[{"text":"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 ","type":"text"},{"text":"fsm/src/fsm_dpi_client.c","type":"text","marks":[{"type":"code"}]},{"text":"):","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"codeBlock","content":[{"text":"int fsm_dpi_action_weight[] =\n{\n [FSM_DPI_CLEAR] = 0,\n [FSM_DPI_IGNORED] = 10,\n [FSM_DPI_PASSTHRU] = 20,\n [FSM_DPI_INSPECT] = 30,\n [FSM_DPI_DROP] = 40,\n};\n\n","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"It may ","type":"text"},{"text":"not","type":"text","marks":[{"type":"em"}]},{"text":" be possible to have individualized reporting intervals for each of the DPI client plugins.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Northbound API","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"DNS DPI Plugin","type":"text"}]},{"type":"paragraph","content":[{"text":"Please refer to: ","type":"text"},{"text":"https://opensync.atlassian.net/wiki/spaces/~154187874/pages/39884128362","type":"text","marks":[{"type":"link","attrs":{"href":"https://opensync.atlassian.net/wiki/spaces/~154187874/pages/39884128362"}}]},{"text":" ","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"ADT DPI Plugin","type":"text"}]},{"type":"paragraph","content":[{"text":"Please refer to: ","type":"text"},{"text":"https://opensync.atlassian.net/wiki/spaces/~154187874/pages/39884357712","type":"text","marks":[{"type":"link","attrs":{"href":"https://opensync.atlassian.net/wiki/spaces/~154187874/pages/39884357712"}}]},{"text":" ","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"SNI DPI plugin","type":"text"}]},{"type":"paragraph","content":[{"text":"The FSM plugin:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$ ovsh -j s Flow_Service_Manager_Config -w handler==dpi_sni\n[\n {\n \"if_name\": \"\",\n \"_version\": [\n \"uuid\",\n \"XXXXXa56-d5fb-438d-a372-1b8fa80427c8\"\n ],\n \"other_config\": [\n \"map\",\n [\n [\n \"dpi_plugin\",\n \"walleye_dpi\"\n ],\n [\n \"flow_attributes\",\n \"${dpi_sni}\"\n ],\n [\n \"mqtt_v\",\n \"SNI/Requests/opensync/XXXXX002B3/XXXXXf5acbb22513f0ae5e17\"\n ],\n [\n \"policy_table\",\n \"dpi_sni\"\n ],\n [\n \"provider_plugin\",\n \"gatekeeper\"\n ]\n ]\n ],\n \"type\": \"dpi_client\",\n \"plugin\": \"\",\n \"_uuid\": [\n \"uuid\",\n \"XXXXXbd9-083c-4d2e-a8ad-e06fe2a807e5\"\n ],\n \"pkt_capt_filter\": \"\",\n \"handler\": \"dpi_sni\"\n }\n]\n","type":"text"}]},{"type":"paragraph","content":[{"text":"The OpenFlow tag:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$ ovsh -j s Openflow_Tag -w name==dpi_sni\n[\n {\n \"_version\": [\n \"uuid\",\n \"XXXXX175-c57e-495c-91f5-710a319ba4d2\"\n ],\n \"name\": \"dpi_sni\",\n \"device_value\": [\n \"set\",\n []\n ],\n \"_uuid\": [\n \"uuid\",\n \"XXXXX59d-d9af-41ff-ab55-81a583aae18a\"\n ],\n \"cloud_value\": [\n \"set\",\n [\n \"http.host\",\n \"http.url\",\n \"tls.sni\"\n ]\n ]\n }\n]\n","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"APP DPI Plugin","type":"text"}]},{"type":"paragraph","content":[{"text":"OpenFlow tag setting:","type":"text"}]},{"type":"codeBlock","content":[{"text":"$ ovsh -j s Openflow_Tag -w name==dpi_app\n[\n {\n \"_version\": [\n \"uuid\",\n \"XXXXX699-f879-46c6-8428-552045dfcca8\"\n ],\n \"name\": \"dpi_app\",\n \"device_value\": [\n \"set\",\n []\n ],\n \"_uuid\": [\n \"uuid\",\n \"XXXXX297-9995-4695-a079-6fd56eadeb40\"\n ],\n \"cloud_value\": [\n \"set\",\n [\n \"server.name\",\n \"service.application\",\n \"service.feature\",\n \"service.network\",\n \"service.platform\",\n \"service.protocol\",\n \"tag\",\n \"toldata\"\n ]\n ]\n }\n]\n","type":"text"}]},{"type":"paragraph","content":[{"text":" The FSM plugin","type":"text"}]},{"type":"codeBlock","content":[{"text":"$ ovsh -j s Flow_Service_Manager_Config -w handler==dpi_app\n[\n {\n \"if_name\": \"\",\n \"_version\": [\n \"uuid\",\n \"XXXXXb17-cea4-4511-b0d1-617890240dd0\"\n ],\n \"other_config\": [\n \"map\",\n [\n [\n \"dpi_plugin\",\n \"walleye_dpi\"\n ],\n [\n \"dso_init\",\n \"dpi_sni_plugin_init\"\n ],\n [\n \"excluded_devices\",\n \"${app-devices-exclude}\"\n ],\n [\n \"flow_attributes\",\n \"${dpi_app}\"\n ]\n ]\n ],\n \"type\": \"dpi_client\",\n \"plugin\": \"/usr/opensync/lib/libfsm_dpi_sni.so\",\n \"_uuid\": [\n \"uuid\",\n \"XXXXXd2e-67be-4480-9c52-908b63f13ace\"\n ],\n \"pkt_capt_filter\": \"\",\n \"handler\": \"dpi_app\"\n }\n]","type":"text"}]}],"version":1}