mirror of
https://github.com/zeek/zeek.git
synced 2025-10-02 14:48:21 +00:00
ded98cd373
This is based on commit 2731def9159247e6da8a3191783c89683363689c from the zeek-docs repo.
179 lines
7.1 KiB
ReStructuredText
179 lines
7.1 KiB
ReStructuredText
:tocdepth: 3
|
|
|
|
base/frameworks/netcontrol/plugin.zeek
|
|
======================================
|
|
.. zeek:namespace:: NetControl
|
|
|
|
This file defines the plugin interface for NetControl.
|
|
|
|
:Namespace: NetControl
|
|
:Imports: :doc:`base/frameworks/netcontrol/types.zeek </scripts/base/frameworks/netcontrol/types.zeek>`
|
|
|
|
Summary
|
|
~~~~~~~
|
|
Types
|
|
#####
|
|
========================================================= =====================================================
|
|
:zeek:type:`NetControl::Plugin`: :zeek:type:`record` Definition of a plugin.
|
|
:zeek:type:`NetControl::PluginState`: :zeek:type:`record` This record keeps the per instance state of a plugin.
|
|
========================================================= =====================================================
|
|
|
|
Redefinitions
|
|
#############
|
|
========================================================= ========================================================================
|
|
:zeek:type:`NetControl::PluginState`: :zeek:type:`record` Table for a plugin to store instance-specific configuration information.
|
|
|
|
:New Fields: :zeek:type:`NetControl::PluginState`
|
|
|
|
plugin: :zeek:type:`NetControl::Plugin` :zeek:attr:`&optional`
|
|
The plugin that the state belongs to.
|
|
========================================================= ========================================================================
|
|
|
|
|
|
Detailed Interface
|
|
~~~~~~~~~~~~~~~~~~
|
|
Types
|
|
#####
|
|
.. zeek:type:: NetControl::Plugin
|
|
:source-code: base/frameworks/netcontrol/plugin.zeek 38 72
|
|
|
|
:Type: :zeek:type:`record`
|
|
|
|
|
|
.. zeek:field:: name :zeek:type:`function` (state: :zeek:type:`NetControl::PluginState`) : :zeek:type:`string`
|
|
|
|
Returns a descriptive name of the plugin instance, suitable for use in logging
|
|
messages. Note that this function is not optional.
|
|
|
|
|
|
.. zeek:field:: can_expire :zeek:type:`bool`
|
|
|
|
If true, plugin can expire rules itself. If false, the NetControl
|
|
framework will manage rule expiration.
|
|
|
|
|
|
.. zeek:field:: init :zeek:type:`function` (state: :zeek:type:`NetControl::PluginState`) : :zeek:type:`void` :zeek:attr:`&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.
|
|
|
|
|
|
.. zeek:field:: done :zeek:type:`function` (state: :zeek:type:`NetControl::PluginState`) : :zeek:type:`void` :zeek:attr:`&optional`
|
|
|
|
One-time finalization function called when a plugin is shutdown; no further
|
|
functions will be called afterwards.
|
|
|
|
|
|
.. zeek:field:: add_rule :zeek:type:`function` (state: :zeek:type:`NetControl::PluginState`, r: :zeek:type:`NetControl::Rule`) : :zeek:type:`bool` :zeek:attr:`&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.
|
|
|
|
|
|
.. zeek:field:: remove_rule :zeek:type:`function` (state: :zeek:type:`NetControl::PluginState`, r: :zeek:type:`NetControl::Rule`, reason: :zeek:type:`string`) : :zeek:type:`bool` :zeek:attr:`&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.
|
|
|
|
.. zeek:type:: NetControl::PluginState
|
|
:source-code: base/frameworks/netcontrol/plugin.zeek 11 23
|
|
|
|
:Type: :zeek:type:`record`
|
|
|
|
|
|
.. zeek:field:: config :zeek:type:`table` [:zeek:type:`string`] of :zeek:type:`string` :zeek:attr:`&default` = ``{ }`` :zeek:attr:`&optional`
|
|
|
|
Table for a plugin to store custom, instance-specific state.
|
|
|
|
|
|
.. zeek:field:: _id :zeek:type:`count` :zeek:attr:`&optional`
|
|
|
|
Unique plugin identifier -- used for backlookup of plugins from Rules. Set internally.
|
|
|
|
|
|
.. zeek:field:: _priority :zeek:type:`int` :zeek:attr:`&default` = ``0`` :zeek:attr:`&optional`
|
|
|
|
Set internally.
|
|
|
|
|
|
.. zeek:field:: _activated :zeek:type:`bool` :zeek:attr:`&default` = ``F`` :zeek:attr:`&optional`
|
|
|
|
Set internally. Signifies if the plugin has returned that it has activated successfully.
|
|
|
|
|
|
.. zeek:field:: plugin :zeek:type:`NetControl::Plugin` :zeek:attr:`&optional`
|
|
|
|
The plugin that the state belongs to. (Defined separately
|
|
because of cyclic type dependency.)
|
|
|
|
|
|
.. zeek:field:: of_controller :zeek:type:`OpenFlow::Controller` :zeek:attr:`&optional`
|
|
|
|
(present if :doc:`/scripts/base/frameworks/netcontrol/plugins/openflow.zeek` is loaded)
|
|
|
|
OpenFlow controller for NetControl OpenFlow plugin.
|
|
|
|
|
|
.. zeek:field:: of_config :zeek:type:`NetControl::OfConfig` :zeek:attr:`&optional`
|
|
|
|
(present if :doc:`/scripts/base/frameworks/netcontrol/plugins/openflow.zeek` is loaded)
|
|
|
|
OpenFlow configuration record that is passed on initialization.
|
|
|
|
|
|
.. zeek:field:: broker_config :zeek:type:`NetControl::BrokerConfig` :zeek:attr:`&optional`
|
|
|
|
(present if :doc:`/scripts/base/frameworks/netcontrol/plugins/broker.zeek` is loaded)
|
|
|
|
OpenFlow controller for NetControl Broker plugin.
|
|
|
|
|
|
.. zeek:field:: broker_id :zeek:type:`count` :zeek:attr:`&optional`
|
|
|
|
(present if :doc:`/scripts/base/frameworks/netcontrol/plugins/broker.zeek` is loaded)
|
|
|
|
The ID of this broker instance - for the mapping to PluginStates.
|
|
|
|
|
|
.. zeek:field:: acld_config :zeek:type:`NetControl::AcldConfig` :zeek:attr:`&optional`
|
|
|
|
(present if :doc:`/scripts/base/frameworks/netcontrol/plugins/acld.zeek` is loaded)
|
|
|
|
|
|
.. zeek:field:: acld_id :zeek:type:`count` :zeek:attr:`&optional`
|
|
|
|
(present if :doc:`/scripts/base/frameworks/netcontrol/plugins/acld.zeek` is loaded)
|
|
|
|
The ID of this acld instance - for the mapping to PluginStates.
|
|
|
|
|
|
This record keeps the per instance state of a plugin.
|
|
|
|
Individual plugins commonly extend this record to suit their needs.
|
|
|
|
|