:tocdepth: 3

base/frameworks/control/main.bro
================================
.. bro:namespace:: Control

The control framework provides the foundation for providing "commands"
that can be taken remotely at runtime to modify a running Bro instance
or collect information from the running instance.

:Namespace: Control
:Source File: :download:`/scripts/base/frameworks/control/main.bro`

Summary
~~~~~~~
Options
#######
============================================================================ ================================================================
:bro:id:`Control::arg`: :bro:type:`string` :bro:attr:`&redef`                This can be used by commands that take an argument.
:bro:id:`Control::cmd`: :bro:type:`string` :bro:attr:`&redef`                The command that is being done.
:bro:id:`Control::commands`: :bro:type:`set` :bro:attr:`&redef`              The commands that can currently be given on the command line for
                                                                             remote control.
:bro:id:`Control::controllee_events`: :bro:type:`pattern` :bro:attr:`&redef` Events that need to be handled by controllees.
:bro:id:`Control::controller_events`: :bro:type:`pattern` :bro:attr:`&redef` Events that need to be handled by controllers.
:bro:id:`Control::host`: :bro:type:`addr` :bro:attr:`&redef`                 The address of the host that will be controlled.
:bro:id:`Control::host_port`: :bro:type:`port` :bro:attr:`&redef`            The port of the host that will be controlled.
:bro:id:`Control::zone_id`: :bro:type:`string` :bro:attr:`&redef`            If :bro:id:`Control::host` is a non-global IPv6 address and
                                                                             requires a specific :rfc:`4007` ``zone_id``, it can be set here.
============================================================================ ================================================================

Constants
#########
============================================== ==========================================================
:bro:id:`Control::ignore_ids`: :bro:type:`set` Variable IDs that are to be ignored by the update process.
============================================== ==========================================================

Events
######
=================================================================== ====================================================================
:bro:id:`Control::configuration_update`: :bro:type:`event`          This event is a wrapper and alias for the
                                                                    :bro:id:`Control::configuration_update_request` event.
:bro:id:`Control::configuration_update_request`: :bro:type:`event`  Inform the remote Bro instance that it's configuration may have been
                                                                    updated.
:bro:id:`Control::configuration_update_response`: :bro:type:`event` Message in response to a configuration update request.
:bro:id:`Control::id_value_request`: :bro:type:`event`              Event for requesting the value of an ID (a variable).
:bro:id:`Control::id_value_response`: :bro:type:`event`             Event for returning the value of an ID after an
                                                                    :bro:id:`Control::id_value_request` event.
:bro:id:`Control::net_stats_request`: :bro:type:`event`             Requests the current net_stats.
:bro:id:`Control::net_stats_response`: :bro:type:`event`            Returns the current net_stats.
:bro:id:`Control::peer_status_request`: :bro:type:`event`           Requests the current communication status.
:bro:id:`Control::peer_status_response`: :bro:type:`event`          Returns the current communication status.
:bro:id:`Control::shutdown_request`: :bro:type:`event`              Requests that the Bro instance begins shutting down.
:bro:id:`Control::shutdown_response`: :bro:type:`event`             Message in response to a shutdown request.
=================================================================== ====================================================================


Detailed Interface
~~~~~~~~~~~~~~~~~~
Options
#######
.. bro:id:: Control::arg

   :Type: :bro:type:`string`
   :Attributes: :bro:attr:`&redef`
   :Default: ``""``

   This can be used by commands that take an argument.

.. bro:id:: Control::cmd

   :Type: :bro:type:`string`
   :Attributes: :bro:attr:`&redef`
   :Default: ``""``

   The command that is being done.  It's typically set on the
   command line.

.. bro:id:: Control::commands

   :Type: :bro:type:`set` [:bro:type:`string`]
   :Attributes: :bro:attr:`&redef`
   :Default:

   ::

      {
         "id_value",
         "net_stats",
         "configuration_update",
         "peer_status",
         "shutdown"
      }

   The commands that can currently be given on the command line for
   remote control.

.. bro:id:: Control::controllee_events

   :Type: :bro:type:`pattern`
   :Attributes: :bro:attr:`&redef`
   :Default:

   ::

      /^?(Control::.*_response)$?/

   Events that need to be handled by controllees.

.. bro:id:: Control::controller_events

   :Type: :bro:type:`pattern`
   :Attributes: :bro:attr:`&redef`
   :Default:

   ::

      /^?(Control::.*_request)$?/

   Events that need to be handled by controllers.

.. bro:id:: Control::host

   :Type: :bro:type:`addr`
   :Attributes: :bro:attr:`&redef`
   :Default: ``0.0.0.0``

   The address of the host that will be controlled.

.. bro:id:: Control::host_port

   :Type: :bro:type:`port`
   :Attributes: :bro:attr:`&redef`
   :Default: ``0/tcp``

   The port of the host that will be controlled.

.. bro:id:: Control::zone_id

   :Type: :bro:type:`string`
   :Attributes: :bro:attr:`&redef`
   :Default: ``""``

   If :bro:id:`Control::host` is a non-global IPv6 address and
   requires a specific :rfc:`4007` ``zone_id``, it can be set here.

Constants
#########
.. bro:id:: Control::ignore_ids

   :Type: :bro:type:`set` [:bro:type:`string`]
   :Default: ``{}``

   Variable IDs that are to be ignored by the update process.

Events
######
.. bro:id:: Control::configuration_update

   :Type: :bro:type:`event` ()

   This event is a wrapper and alias for the
   :bro:id:`Control::configuration_update_request` event.
   This event is also a primary hooking point for the control framework.

.. bro:id:: Control::configuration_update_request

   :Type: :bro:type:`event` ()

   Inform the remote Bro instance that it's configuration may have been
   updated.

.. bro:id:: Control::configuration_update_response

   :Type: :bro:type:`event` ()

   Message in response to a configuration update request.

.. bro:id:: Control::id_value_request

   :Type: :bro:type:`event` (id: :bro:type:`string`)

   Event for requesting the value of an ID (a variable).

.. bro:id:: Control::id_value_response

   :Type: :bro:type:`event` (id: :bro:type:`string`, val: :bro:type:`string`)

   Event for returning the value of an ID after an
   :bro:id:`Control::id_value_request` event.

.. bro:id:: Control::net_stats_request

   :Type: :bro:type:`event` ()

   Requests the current net_stats.

.. bro:id:: Control::net_stats_response

   :Type: :bro:type:`event` (s: :bro:type:`string`)

   Returns the current net_stats.

.. bro:id:: Control::peer_status_request

   :Type: :bro:type:`event` ()

   Requests the current communication status.

.. bro:id:: Control::peer_status_response

   :Type: :bro:type:`event` (s: :bro:type:`string`)

   Returns the current communication status.

.. bro:id:: Control::shutdown_request

   :Type: :bro:type:`event` ()

   Requests that the Bro instance begins shutting down.

.. bro:id:: Control::shutdown_response

   :Type: :bro:type:`event` ()

   Message in response to a shutdown request.


