Connectors are a set of modules that are used to exchange message-oriented
data among Snort threads and the external world.  A typical use-case is
HA (High Availability) message exchange.  Connectors serve to decouple the
message transport from the message creation/consumption.  Connectors expose
a common API for several forms of message transport.

Connectors are a Snort plugin type.

===== Connector (parent plugin class)

Connectors may either be a simplex channel and perform unidirectional
communications.  Or may be duplex and perform bidirectional communications.
The TcpConnector is duplex while the FileConnector is simplex.

All subtypes of Connector have a 'direction' configuration element and a
'connector' element.  The 'connector' string is the key used to identify the
element for client module configuration.  The 'direction' element may have a
default value, for instance TcpConnector is 'duplex'.


Currently there are the following implementations of the Connector:

* TcpConnector - Exchange messages over a tcp channel.

* FileConnector - Write messages to files and read messages from files.

* StdConnector - Exchange messages over a standard input/output.


===== TcpConnector

TcpConnector is a subclass of Connector and implements a DUPLEX type Connector,
able to send and receive messages over a tcp session.

TcpConnector adds a few session setup configuration elements:

* setup = 'call' or 'answer' - 'call' is used to have TcpConnector initiate
        the connection.  'answer' is used to have TcpConnector accept incoming
        connections.

* address = '<addr>' - used for 'call' setup to specify the partner

* ports = "port port ..." - used to pick a port number for 'call' and
        'answer' modes.  If the 'ports' list contains more than one port,
        the "per-thread" destination mode will be assumed. In this mode, each thread
        will connect to a corresponding destination port by selecting a port number
        from the list based on the instance_id.

An example segment of TcpConnector configuration:

    tcp_connector =
    {
        {
            connector = 'tcp_1',
            address = '127.0.0.1',
            setup = 'call',
            ports = "11000 11001 11002 11003",
        },
    }


===== FileConnector

FileConnector implements a Connector that can either read from files or write
to files.  FileConnector's are simplex and must be configured to be
CONN_TRANSMIT or CONN_RECEIVE.

FileConnector configuration adds two additional element:

* name = string - used as part of the message file name

* text_format = bool - FileConnector works in binary mode by default, the option switches it to text mode

The configured 'name' string is used to construct the actual names as in:

* file_connector_NAME_transmit and file_connector_NAME_receive

All messages for one Snort invocation are read and written to one file.

In the case of a receive FileConnector, all messages are read from the file
prior to the start of packet processing.  This allows the messages to
establish state information for all processed packets.

An example segment of FileConnector configuration:

    file_connector =
    {
        {
            connector = 'file_tx_1',
            direction = 'transmit',
            text_format = true,
            name = 'HA'
        },
        {
            connector = 'file_rx_1',
            direction = 'receive',
            text_format = true,
            name = 'HA'
        },
    }


===== StdConnector

StdConnector is an implementation of a Connector that has the capability to
read from the standard input and write to the standard output. Its principal
purpose is testing.

All messages transmitted through the stdout are automatically appended with a new
line. Therefore, it is expected that each message read from the stdin will also be
separated by a newline.

The std_connector module automatically sets-up three default connectors on startup:

* `stdout`: the default transmit connector
* `stdin`: the default receive connector
* `stdio`: the default duplex connector.

An example segment of a duplex StdConnector configuration:

std_connector =
{
    {
        connector = 'std_in_out',
        direction = 'duplex'
    }
}

