Merge pull request #624 in SNORT/snort3 from stream-ha-dev_notes to master

Squashed commit of the following:

commit 0684abf3822d39fa63b64d2a3fc82ee5806d9653
Author: Ed Borgoyn <eborgoyn@cisco.com>
Date:   Fri Sep 16 08:57:56 2016 -0400

    Add HA details to the stream/* dev_notes.

diff --git a/src/stream/icmp/dev_notes.txt b/src/stream/icmp/dev_notes.txt
index fb6857069810e72d510da1bbb97334bfce423674..f5a0a0123c27878ad40825dce1142dccf54fa81f 100644 (file)
--- a/src/stream/icmp/dev_notes.txt
+++ b/src/stream/icmp/dev_notes.txt
@@ -11,3 +11,17 @@ packets directly to the ICMP session packet processing method.
 Currently only the ICMP Unreachable message is handled by the ICMP session
 module.
 
+The module icmp_ha.cc (and icmp_ha.h) implements the per-protocol hooks into
+the stream logic for HA.  IcmpHAManager is a static class that interfaces
+to a per-packet thread instance of the class IcmpHA.  IcmpHA is sub-class
+of ProtocolHA, declared in the stream/base area.  Thus each protocol
+within 'stream' can have specific HA logic and interfaces.
+
+IcmpHAManager::process_deletion() is called when an ICMP stream is being 
+destroyed and indicates to the stream & flow HA logic that a flow
+deletion HA message needs to be emitted for the flow in question.
+Icmp streams are closed due to timeout or puning actions which lead
+to the invocation of process_deletion().
+
+IcmpHA::create_session() is called from the stream & flow HA logic and
+handles the creation of new flow upon receiving an HA update message.

diff --git a/src/stream/ip/dev_notes.txt b/src/stream/ip/dev_notes.txt
index b909f1aaf56bb160c46c9a26c27e45be1647d9d1..54047342fa1c495b224349245077a6541a90e93b 100644 (file)
--- a/src/stream/ip/dev_notes.txt
+++ b/src/stream/ip/dev_notes.txt
@@ -8,3 +8,17 @@ functions for loading stream IP configuration and packet evaluation.  The
 packet eval method is not used as the base Stream Inspector delegates
 packets directly to the IP session packet processing method.
 
+The module ip_ha.cc (and ip_ha.h) implements the per-protocol hooks into
+the stream logic for HA.  IpHAManager is a static class that interfaces
+to a per-packet thread instance of the class IpHA.  IpHA is sub-class
+of ProtocolHA, declared in the stream/base area.  Thus each protocol
+within 'stream' can have specific HA logic and interfaces.
+
+IpHAManager::process_deletion() is called when an IP stream is being 
+destroyed and indicates to the stream & flow HA logic that a flow
+deletion HA message needs to be emitted for the flow in question.
+Ip streams are closed due to timeout or puning actions which lead
+to the invocation of process_deletion().
+
+IpHA::create_session() is called from the stream & flow HA logic and
+handles the creation of new flow upon receiving an HA update message.

diff --git a/src/stream/libtcp/dev_notes.txt b/src/stream/libtcp/dev_notes.txt
index 12a79d004520d936a1c71274594ef381e54fc9f7..0a6ebc9509834c39be330366abc95f7f20af3654 100644 (file)
--- a/src/stream/libtcp/dev_notes.txt
+++ b/src/stream/libtcp/dev_notes.txt
@@ -16,3 +16,12 @@ This TCP library module provides the following functions:
 * TCP State Machine - this class is the engine that dispatches processing to the correct
   event handling method of the handler for the current TCP state of the flow.
 
+Most of the TCP HA processing is contained in the ../tcp area and one needed to refer
+to ../tcp/dev_notes.txt for a description.
+
+One HA state transition is implemented within this TCP library.  In
+TcpStreamSession::clear(), TcpHAManager::process_deletion() is invoked to
+cause HA to generate a Deletion message for the target flow.  This handles
+the case where a TCP session is being removed from from the flow cache due
+to a timeout or pruning function.  Other normal TCP stream closure actions
+are handled in the ../tcp/tcp_session.cc module.

diff --git a/src/stream/tcp/dev_notes.txt b/src/stream/tcp/dev_notes.txt
index d3cc981cb16921430e519bdec41a405fec059b3a..b4bc8bcadce18547683cb511981835d41327bad4 100644 (file)
--- a/src/stream/tcp/dev_notes.txt
+++ b/src/stream/tcp/dev_notes.txt
@@ -42,4 +42,23 @@ State information includes:
 An instance of this data structure is allocated and managed for each end of
 the connection.
 
-
+The module tcp_ha.cc (and tcp_ha.h) implements the per-protocol hooks into
+the stream logic for HA.  TcpHAManager is a static class that interfaces
+to a per-packet thread instance of the class TcpHA.  TcpHA is sub-class
+of ProtocolHA, declared in the stream/base area.  Thus each protocol
+within 'stream' can have specific HA logic and interfaces.
+
+TcpHAManager::process_deletion() is called when an TCP stream is being 
+destroyed and indicates to the stream & flow HA logic that a flow
+deletion HA message needs to be emitted for the flow in question.
+Tcp streams are both closed internally (e.g. FIN) and externally due
+to cache timeout or pruning.  The calls to TcpHAManager::process_deletion()
+in tcp/tcp_session.cc indicate a normal closure of a stream/flow.  
+
+TcpHA::create_session() is called from the stream & flow HA logic and
+handles the creation of new flow upon receiving an HA update message.
+
+TcpHA::deactivate_session() is called from the stream & flow HA logic to 
+place a session into standby mode.  Upon receiving an HA Update message, 
+the flow is first created if necessary, and is then placed into Standby
+state.  deactivate_session() sets the TCP specific state for Standy mode.

diff --git a/src/stream/udp/dev_notes.txt b/src/stream/udp/dev_notes.txt
index 7ac0a9fc03c0b8eb0ab99c642768c1a7a7360706..12d5719ef045c180f5a94b1db2ac3793344dea25 100644 (file)
--- a/src/stream/udp/dev_notes.txt
+++ b/src/stream/udp/dev_notes.txt
@@ -8,3 +8,17 @@ functions for loading stream UDP configuration and packet evaluation.  The
 packet eval method is not used as the base Stream Inspector delegates
 packets directly to the UDP session packet processing method.
 
+The module udp_ha.cc (and udp_ha.h) implements the per-protocol hooks into
+the stream logic for HA.  UdpHAManager is a static class that interfaces
+to a per-packet thread instance of the class UdpHA.  UdpHA is sub-class
+of ProtocolHA, declared in the stream/base area.  Thus each protocol
+within 'stream' can have specific HA logic and interfaces.
+
+UdpHAManager::process_deletion() is called when an UDP stream is being 
+destroyed and indicates to the stream & flow HA logic that a flow
+deletion HA message needs to be emitted for the flow in question.
+Udp streams are closed due to timeout or puning actions which lead
+to the invocation of process_deletion().
+
+UdpHA::create_session() is called from the stream & flow HA logic and
+handles the creation of new flow upon receiving an HA update message.