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:

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().

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:

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.

record

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