{{indexmenu_n>11}}  
====== FastBypass monitor ======   
''fastbypass_monitor'' (referred to as "daemon" further in the documentation and script) is a tool for monitoring and managing the state of network interfaces connected to Bypass network cards.  

The daemon reacts to HEARTBEAT signals received from DPI on specific ports defined in the configuration file. If HEARTBEAT signals are not received according to the configuration rules, the daemon performs specific actions such as deleting or creating IP addresses connected to the Bypass cards and enabling or disabling certain network interfaces.  
  
{{ :dpi:dpi_components:fastdpi-bypass.png?900 |}}  

If there is a software failure on DPI, the NPB removes the DPI from the stack and redistributes the load among the remaining DPIs.\\  
If more than two DPI nodes fail, the entire system switches to bypass mode.\\  
If the link on a DPI fails, NPB redistributes the load among the remaining DPIs.\\  
  
===== Hardware Requirements =====  
OS: OpenSwitch 2+ / Debian 9+\\  
Python: 2.7.9  
  
===== Key Features =====  
  * Monitoring HEARTBEAT signals from DPI on specified ports.  
  * Dynamic management of IP addresses and network interfaces.  
  
===== Installation =====  
  - Copy the installation package ''fastbypass_monitor-X.X.XX.deb'' to the host machine.  
  - Run the following command from the directory where the package is located:  
<code bash>sudo dpkg -i fastbypass_monitor-X.X.XX.deb</code>  

After installation, the daemon becomes manageable through the system manager (''systemctl'').  

The configuration file is available at ''/var/fastbypass_monitor/backend/.env''\\  
A sample configuration file can be found at ''/var/fastbypass_monitor/backend/sample.env''\\  
Daemon logs are stored at ''/var/fastbypass_monitor/backend/logs/''  
  
===== Usage =====  
After installation, the daemon runs automatically. Upon reboot, it starts after the ''network'' service has successfully launched.\\  
Manage the daemon using system manager commands.  
  
:!: Aliases (short command equivalents) can only be used with sudo. Use ''sudo su -'' and enter the password to enable this mode.  
  
===Start the daemon:===  
<code bash>sudo systemctl start fastbypass_monitor</code>  
Alias: <code bash>fbypass_ctl start</code>  
  
<note important>The service starts in an unknown state, meaning it does not initially enable or disable bypass mode. After all receivers are initialized and their statuses are determined, the system switches to either normal or bypass mode depending on configuration and receiver status.</note>  

===Restart the daemon:===  
<code bash>sudo systemctl restart fastbypass_monitor</code>  
Alias:  
<code bash>fbypass_ctl restart</code>  
  
===Reload the daemon without stopping:===  
<code bash>sudo systemctl reload fastbypass_monitor</code>  
Alias:  
<code bash>fbypass_ctl reload</code>  

===Stop the daemon:===  
<code bash>sudo systemctl stop fastbypass_monitor</code>  
Alias:  
<code bash>fbypass_ctl stop</code>  

===Check the daemon’s status:===  
<code bash>sudo systemctl status fastbypass_monitor</code>  
Alias:  
<code bash>fbypass_ctl status</code>  

===View the last few lines of the log file in real-time:===  
<code bash>tail -f /var/fastbypass_monitor/backend/logs/fastbypass_monitor.log</code>  
Alias:  
<code bash>fbypass_ctl tailf</code>  

===Output the last 100 lines of the log:===  
<code bash>tail -n 100 /var/fastbypass_monitor/backend/logs/fastbypass_monitor.log</code>  
Alias:  
<code bash>fbypass_ctl tail 100</code>  

===Stop the daemon and remove IPs from Bypass cards, forcing the system into bypass mode:===  
<code bash>fbypass_ctl force_on</code>  

===Stop the daemon and add IPs to Bypass cards, forcing the system into normal mode:===  
<code bash>fbypass_ctl force_off</code>  

===Add the daemon to startup:===  
<code bash>fbypass_ctl enable</code>  

===Remove the daemon from startup:===  
<code bash>fbypass_ctl disable</code>  

To configure and launch the daemon with new settings, edit the configuration file and restart or stop and start the daemon.  

The daemon configuration is located at ''/var/fastbypass_monitor/backend/.env''  

<note>Upon startup and reload, the daemon reads the configuration file. If it can successfully configure the specified IPs and interfaces, it continues operation. Otherwise, it only launches successfully configured components.  

In case of a critical error, the daemon will restart automatically.  

Using ''sudo systemctl reload fastbypass_monitor'' will reload the configuration without stopping the daemon, shutting down removed components, and adding new ones.  

During startup and reload, the daemon does not manage interfaces and IPs until all listeners report their statuses. After a restart, the daemon remains in its previous state until receiving updates from all listeners.</note>  
  
==== Local and Global States: Bypass Mode ====  
The daemon manages interfaces based on either a **global** state (depending on all listeners) or a **local** state (specific to individual listeners).\\  
For instance, if you list interfaces in the global settings, they will be enabled or disabled based on the daemon’s overall state. If the daemon fails to receive enough signals, the interfaces are disabled.  

**Example:**  
<code bash>  
LISTEN_CUBRO_IFS=<interface list>  
LISTEN_SHUTDOWN_CUBRO_IFS_WHEN_BYPASS=1  
</code>  

Each listener can also have its own interface list that it manages based on its state.  

**Example:**  
<code bash>  
LISTEN_CUBRO_IFS[0]=<interface list>  
LISTEN_SHUTDOWN_CUBRO_IFS_WHEN_BYPASS[0]=1  
</code>  
  
If the interfaces specified in ''LISTEN_CUBRO_IFS[N]'' are duplicated in multiple listener, they go into bypass mode if one of the corresponding listener stops receiving a signal. The interfaces are only bypassed to normal mode if all the corresponding listener receives signals.

In the case where interfaces are specified in both local and global settings, the interfaces are in bypass mode until the corresponding listener starts receiving signals and the daemon enters normal mode.

===== Configuration =====  
==== Minimal Configuration ====  
The minimum configuration for daemon operation includes specifying at least one interface, IP address, and port to receive HEARTBEAT signals, and one interface and IP address to connect the Bypass card.

**Example:**  
<code bash>  
# Logging level - error and information messages
LOG_LEVEL=INFO
 
# interface for default listener operation
LISTEN_HEARTBEAT_IFS=eth0
# interface for working with Bypass cards by default
BYPASS_CARD_IFS=eth0
 
# number of unsuccessful HEARTBEAT listener for switching to Bypass mode
LISTEN_HEARTBEAT_FAILED=1
# number of attempts to receive the default HEARTBEAT signal for the listener
LISTEN_HEARTBEAT_ATTEMPTS=1
# default HEARTBEAT signal waiting time in milliseconds for listener
LISTEN_HEARTBEAT_TIMEOUT=3000
 
# IP address where the daemon is waiting for HEARTBEAT signals
LISTEN_HB_HOST[0]=192.168.1.202
# port on which the daemon expects HEARTBEAT signals
LISTEN_HB_PORT[0]=3000
 
# IP address where the daemon is waiting for HEARTBEAT signals
LISTEN_HB_HOST[1]=192.168.1.202
# port on which the daemon expects HEARTBEAT signals
LISTEN_HB_PORT[1]=3100
 
# IP address of the Bypass card to which the daemon will be connected
BYPASS_CARD_HOST[0]=192.168.1.211
 
# IP address of the Bypass card to which the daemon will be connected
BYPASS_CARD_HOST[1]=192.168.1.212
</code>  
Above is a sample configuration for receiving HEARTBEAT signals using interface ''eth0'' on IP address ''192.168.1.202'' and ports ''3000'' and ''3100''

Bypass cards are connected on interface ''eth0'' to IP addresses ''192.168.1.211'' and ''192.168.1.212''.

The default values for all listener are set to:

''LISTEN_HEARTBEAT_ATTEMPTS'' — number of attempts to receive the signal: ''1''\\
''LISTEN_HEARTBEAT_TIMEOUT'' — signal waiting time: ''3000'' milliseconds

When the listener does not receive a signal after one attempt within ''3000'' milliseconds, it is considered to have failed.

If the number of failed listeners equals or exceeds the set threshold (''LISTEN_HEARTBEAT_FAILED''), the daemon enters Bypass mode and removes the IP addresses specified for Bypass maps.

When signals are restored, the listener is considered operational.

If the total number of failed listeners becomes less than the threshold, the daemon returns to NORMAL mode and restores the specified IP addresses to the Bypass cards.

==== General Configuration ====

The configuration settings below apply to the overall functioning of the daemon.

The listener settings block serves as default values for those listeners that do not have specific configurations defined. The same applies to interface settings for connecting Bypass network cards.

Additionally, the daemon allows the integration of custom commands to manage interfaces and IP addresses. This makes it possible to tailor the daemon to the specifics of the network and implement custom scripts optimized for specific network environment requirements.

<code bash>
# logging level (optional setting, default is INFO):
# INFO - error and informational messages
# DEBUG - error, informational, and debug messages
LOG_LEVEL=

# network mask for specified IP addresses (optional setting, default is 32)
//NETWORK_MASK=//
</code>

<code bash>
# default interface for listeners that do not specify an interface name for listening to HEARTBEAT (optional)
LISTEN_HEARTBEAT_IFS=

# default IP address for listeners that do not specify an IP address for listening to HEARTBEAT signals (optional)
//LISTEN_HEARTBEAT_HOST=//

# default number of attempts to receive a HEARTBEAT signal for listeners without a specific configuration (optional, default is 3)
//LISTEN_HEARTBEAT_ATTEMPTS=//

# default timeout in milliseconds for HEARTBEAT signal for listeners without a specific configuration (optional, default is 3000)
//LISTEN_HEARTBEAT_TIMEOUT=//

# number of failed HEARTBEAT listeners to trigger Bypass mode (optional, default is 1)
//LISTEN_HEARTBEAT_FAILED=//
</code>

<code bash>
# default interface for working with Bypass cards that do not specify an interface name (optional)
BYPASS_CARD_IFS=
</code>

<code bash>
# list of interfaces to shut down when entering Bypass mode (optional)
LISTEN_CUBRO_IFS=

# setting for handling interfaces listed in //LISTEN_CUBRO_IFS// (optional, default is 0)
# 1 - shut down specified interfaces when entering Bypass mode
# 0 - take no action with specified interfaces when entering Bypass mode
LISTEN_SHUTDOWN_CUBRO_IFS_WHEN_BYPASS=
</code>

<code bash>
# absolute path to the script for bringing up an interface (optional, default – see Note 2)
CMD_SET_UP_INTFS=

# absolute path to the script for bringing down an interface (optional, default – see Note 2)
CMD_SET_DOWN_INTFS=

# absolute path to the script for adding an IP address (optional, default – see Note 2)
CMD_ADD_IP=

# absolute path to the script for removing an IP address (optional, default – see Note 2)
CMD_DEL_IP=
</code>

<note>__Note 1__

All IP addresses specified in the configuration may be presented in the format ''192.168.1.202'' or with a network mask, e.g., ''192.168.1.202/16''. By default, the network mask is ''32'' (if not set in the global ''NETWORK_MASK'' setting or in a specific listener or Bypass card configuration).

Important: If the IP address matches the management IP address used for SSH connections, then the network mask is not changed and remains as defined in the operating system.

This important condition should be considered when configuring IP addresses to avoid conflicts with the management IP and unintended network mask changes.
</note>

<note>__Note 2__

The daemon configuration allows specifying custom scripts for performing basic operations such as enabling/disabling interfaces and creating/removing IP addresses.

The daemon expects the absolute path to a shell script in the respective configuration, with variables specified at the end of the line in the format ''%(<variable_name>)s''

Used variables:
  * ''intfs'' — interface name
  * ''ip'' — IP address
  * ''netmask'' — network mask

Default configurations:
  * ''CMD_SET_UP_INTFS=/var/fastbypass_monitor/backend/app_bash/cmd_set_up_intfs.sh %(intfs)s''
  * ''CMD_SET_DOWN_INTFS=/var/fastbypass_monitor/backend/app_bash/cmd_set_down_intfs.sh %(intfs)s''
  * ''CMD_ADD_IP=/var/fastbypass_monitor/backend/app_bash/cmd_add_ip.sh %(ip)s %(netmask)s %(intfs)s''
  * ''CMD_DEL_IP=/var/fastbypass_monitor/backend/app_bash/cmd_del_ip.sh %(ip)s %(netmask)s %(intfs)s''
</note>

==== Listener Configuration ====

Each listener enables receiving HEARTBEAT signals from various DPI devices. Each subsequent listener is specified with the next index (e.g., [0], [1], [2]).

A listener has the following parameters for complete configuration:
<code bash>
# listener ID (optional, default is the index)
LISTEN_HB_ID[0]=0

# name of the interface where the listener expects HEARTBEAT signals
LISTEN_HB_IFS[0]=eth0

# IP address/subnet mask for listening to HEARTBEAT signals
LISTEN_HB_HOST[0]=192.168.1.202/32

# port for listening to HEARTBEAT signals
LISTEN_HB_PORT[0]=3000

# number of attempts to receive a HEARTBEAT signal (optional, default: 3)
LISTEN_HB_ATTEMPTS[0]=3

# HEARTBEAT signal timeout in milliseconds (optional, default: 3000)
LISTEN_HB_TIMEOUT[0]=3000

# setting for immediate switch to Bypass mode (optional)
# 1 - if no HEARTBEAT signal received, switch to Bypass immediately
# 0 - if no HEARTBEAT signal received, switch after all attempts (default)
LISTEN_HB_SWITCH_IMMEDIATELY[0]=0

# list of interfaces to shut down when entering Bypass mode (optional)
LISTEN_CUBRO_IFS[0]=e101-001-0,e101-002-0

# setting to shut down interfaces specified in LISTEN_CUBRO_IFS[N] (optional)
# 1 - shut down specified interfaces when entering Bypass mode
# 0 - take no action with specified interfaces when entering Bypass mode (default)
LISTEN_SHUTDOWN_CUBRO_IFS_WHEN_BYPASS[0]=1
</code>

==== Bypass Network Card Interface Configuration ====

The daemon automatically manages (adds/removes) IP addresses on the respective interfaces when switching to BYPASS or NORMAL mode according to the Bypass card settings.\\
Each Bypass card is specified with the next index (e.g., [0], [1], [2]).

Bypass card interfaces have the following parameters for full configuration:
<code bash>
# Bypass card ID (optional, default is the index)
BYPASS_CARD_ID[0]=

# IP address/subnet mask for listening to HEARTBEAT signals
BYPASS_CARD_HOST[0]=

# Bypass card operation mode
# 0 - remove specified IP address when Bypass mode is enabled
# 1 - remove specified IP address when Bypass mode is enabled, add it back when Bypass mode is disabled (default)
BYPASS_CARD_ACTIVE[0]=

# forced Bypass card mode
# 0 - disable forced mode (default)
# 1 - enable forced mode, IP address remains active regardless of daemon state
BYPASS_CARD_FORCE[0]=
</code>