base/frameworks/netcontrol/plugin.bro

NetControl

This file defines the plugin interface for NetControl.

Namespace:NetControl
Imports:base/frameworks/netcontrol/types.bro
Source File:/scripts/base/frameworks/netcontrol/plugin.bro

Summary

Types

NetControl::Plugin: record Definition of a plugin.
NetControl::PluginState: record This record keeps the per instance state of a plugin.

Redefinitions

NetControl::PluginState: record Table for a plugin to store instance-specific configuration information.

Detailed Interface

Types

NetControl::Plugin
Type:

record

name: function (state: NetControl::PluginState) : string

Returns a descriptive name of the plugin instance, suitable for use in logging messages. Note that this function is not optional.

can_expire: bool

If true, plugin can expire rules itself. If false, the NetControl framework will manage rule expiration.

init: function (state: NetControl::PluginState) : void &optional

One-time initialization function called when plugin gets registered, and before any other methods are called.

If this function is provided, NetControl assumes that the plugin has to perform, potentially lengthy, initialization before the plugin will become active. In this case, the plugin has to call NetControl::plugin_activated, once initialization finishes.

done: function (state: NetControl::PluginState) : void &optional

One-time finalization function called when a plugin is shutdown; no further functions will be called afterwords.

add_rule: function (state: NetControl::PluginState, r: NetControl::Rule) : bool &optional

Implements the add_rule() operation. If the plugin accepts the rule, it returns true, false otherwise. The rule will already have its id field set, which the plugin may use for identification purposes.

remove_rule: function (state: NetControl::PluginState, r: NetControl::Rule, reason: string) : bool &optional

Implements the remove_rule() operation. This will only be called for rules that the plugin has previously accepted with add_rule(). The id field will match that of the add_rule() call. Generally, a plugin that accepts an add_rule() should also accept the remove_rule().

Definition of a plugin.

Generally a plugin needs to implement only what it can support. By returning failure, it indicates that it can’t support something and the framework will then try another plugin, if available; or inform the that the operation failed. If a function isn’t implemented by a plugin, that’s considered an implicit failure to support the operation.

If plugin accepts a rule operation, it must generate one of the reporting events rule_{added,remove,error} to signal if it indeed worked out; this is separate from accepting the operation because often a plugin will only know later (i.e., asynchronously) if that was an error for something it thought it could handle.

NetControl::PluginState
Type:

record

config: table [string] of string &default = {  } &optional

Table for a plugin to store custom, instance-specific state.

_id: count &optional

Unique plugin identifier – used for backlookup of plugins from Rules. Set internally.

_priority: int &default = 0 &optional

Set internally.

_activated: bool &default = F &optional

Set internally. Signifies if the plugin has returned that it has activated successfully.

plugin: NetControl::Plugin &optional

The plugin that the state belongs to. (Defined separately because of cyclic type dependency.)

of_controller: OpenFlow::Controller &optional

(present if base/frameworks/netcontrol/plugins/openflow.bro is loaded)

OpenFlow controller for NetControl OpenFlow plugin.

of_config: NetControl::OfConfig &optional

(present if base/frameworks/netcontrol/plugins/openflow.bro is loaded)

OpenFlow configuration record that is passed on initialization.

This record keeps the per instance state of a plugin.

Individual plugins commonly extend this record to suit their needs.

Copyright 2016, The Bro Project. Last updated on October 17, 2017. Created using Sphinx 1.5.2.