SBN Splitter
SBN Splitter
The SBN Splitter can used during conversions from a third party automation system to SBN to capture signals from an alarm receiver. This splitter will simultaneously parse TCP/IP traffic from the receiver to the third party automation and to an SBN Concentrator.
The splitter supports two operating modes:
- Active mode -- the original behavior described in the sections below. The splitter terminates the live TCP connection between the receiver and the existing automation, and forwards bytes to the SBN Concentrator and any other configured destinations.
- SPAN mode -- introduced in v95 (PR #1040). The splitter sits passively on an internal-network SPAN/mirror port and reassembles traffic between the alarm receivers and the existing automation without sitting in the live TCP path. See SPAN Mode (Passive Tap).
Once installed, the SBN Splitter becomes part of the critical alarm signal path and should be treated as a production element. The SBN Splitter process and error log should therefore be monitored in the same way as other receiver infrastructure. The SBN Concentrator will send alerts on an SBN error account if it detects that the Splitter is no longer operational.
Overview
Before go live
The SBN Splitter is placed as a server / client between the Receiver and the existing automation.
Every data packet transmitted from the receiver is
- Forwarded to the automation
- Forwarded to the SBN Concentrator
Every data packet transmitted from the automation is:
- Forwarded only to the receiver
Every data packet transmitted from the SBN Concetrator is ignored.
In this way, the SBN Concentrator can receive the receiver signals without interfering with the processing of the existing Automation.
After go live
The SBN Splitter is placed as a server / client between the Receiver and the SBN Concentrator.
Every data packet transmitted from the receiver is
- Forwarded to the SBN Concentrator
- Forwarded to the previous automation
Every data packet transmitted from the SBN Concentrator is:
- Forwarded only to the receiver
Every data packet transmitted from the existing automation is ignored.
In this way, the previous automation can receive the receiver signals allowing for a record to be maintained in the existing automation.
Installation
The SBN Splitter can be downloaded from the Innovative FTP website [ftps://ftp.innovative247.com/common/Releases/SBN_Conc/94]. The splitter is compatible with Windows, Linux, and MacOS. The relevant version should be copied to a local directory. A sample configuration has been included.
SPAN Mode (Passive Tap)
SPAN mode is an alternative front end for the same sbn-splitter binary. Instead of the splitter terminating the receiver-to-automation TCP connection, the splitter sits on a switch SPAN/mirror port (or an inline network tap), passively reassembles the receiver-to-automation traffic from mirrored packets, and forwards the reassembled byte stream downstream to the SBN Concentrator and any other configured destinations.
The destinations side of the configuration -- the destinations: list under each splitter, and the Concentrator wiring -- is unchanged between active and SPAN mode. Only the front end differs. Removing the span: block from the configuration falls back to active mode.
When to use SPAN mode
Use SPAN mode in environments where:
- The existing automation cannot be reconfigured to point at a new IP/port.
Prerequisites
- Capture tool on PATH -- the daemon checks at startup and refuses to start with a clear install hint if missing:
- Linux/macOS:
tcpdump - Windows:
dumpcap(ships with Wireshark, https://www.wireshark.org/download.html) - Privileges for live capture:
- Linux: run the splitter as root, OR grant
tcpdumpthe right capabilities (sudo setcap cap_net_raw,cap_net_admin+eip /usr/bin/tcpdump), OR run the splitter under sudo. - Windows: launch the splitter daemon as Administrator (or configure Npcap for non-admin capture).
- The
pcapFile:replay form (see below) needs no special privileges. - NIC. The switch SPAN port should mirror the receiver-to-automation traffic on the internal network to a dedicated NIC on the splitter host; configure that NIC name in the
interface:field.
Replay (pcapFile)
Setting span.pcapFile to a previously-captured .pcap file replays it through the same reassembly pipeline. This requires no NIC and no special privileges.
When pcapFile is set, interface: and bpf: are ignored.
Limitations
- TLS-encrypted traffic. SPAN capture is ciphertext-only on the wire; if the receiver-to-automation TCP connection is TLS-encrypted, the splitter cannot reassemble it in clear and cannot forward usable bytes to the SBN Concentrator. Sites using TLS must remain on active mode (or terminate TLS upstream of the splitter) while SPAN mode is in use.
Command line options
The SBN Splitter is a command line application that is run through a command shell such as PowerShell, CMD.EXE, or Bash.
Sample Command | Description |
|---|---|
| Run the splitter with the configuration file sample-config.yaml |
| Run the splitter, enable verbose logging, and output log files to the standard output |
| Start a test echo server on port 8000 |
| Start a test server on port 8001 |
| Start a test client on port 8002 |
| Install the sbn-splitter as a service |
| Start the sbn-splitter service |
| Stop the sbn-splitter service |
| Remove the sbn-splitter as a service |
Configuration
The SBN Splitter is configured via configuration files. The sample configuration file provides an example of the receiver acting as a TCP Client and as a TCP Server.
It is best practice to create a splitter configuration per receiver rather than include multiple splitter configurations in one file. In this way, if a connection fails it will only affect one receiver.
A sample configuration file is provided below.
The splitter will validate the configuration and fail to start if it detects errors.
TCP Splitter options
General splitter options
Option | Description | Default Value |
|---|---|---|
name | Name of the splitter | |
disabled | Whether the splitter is disabled | false |
server | Definition of the server connection | N/A |
client | Definition of the client connection | N/A |
clientKeepAlive | Whether to keep the client connection alive when server disconnects | false |
destinations | A list of additional connections | N/A |
Server connection
Options related to the server connection
Option | Description | Default Value |
|---|---|---|
name | Name of the connection | <none> |
address | Network address to create the server listener | All network interfaces |
port | Port number | |
log | Whether to log traffic coming from and to the server | false |
rejectMultiple | Whether to reject multiple server connections | false |
Destination connection
Options related to the client connection
Option | Description | Default Value |
|---|---|---|
name | Name of the connection | <none> |
address | Network address to connect to when a server connection is created | localhost |
port | Port number | <none> |
log | Whether to log traffic coming from and to the client | false |
Destination
Options related to additional destinations
Option | Description | Default Value |
|---|---|---|
name | Name of the connection | <none> |
disabled | Whether the destination is disabled | false |
address | Network address to connect to if acting as a client | localhost |
port | Port number | <none> |
listen | Whether to act as a server (listening) or as a client | false |
log | Whether to log traffic coming from and to the connection | false |
retry.interval | How often (in milliseconds) to retry establishing a connection when it fails. If zero, the connection will not be retried | <none> |
retry.maxAttempts | How many attempts to try restablishing a connection when it fails. If zero, the connection will be retried continuously | |
tap.server | Whether to tap the server, sending messages from the server to the connection | false |
tap.client | Whether to tap the client, sending messages from the client to the connection | false |
SPAN options
SPAN mode is selected by the presence of an enabled span: block at the same level as splitters:. There is no separate mode field and no enabled flag. Each splitter's existing server.address, server.port, and client.address are reused as the SPAN flow coordinates -- the splitter builds an appropriate BPF filter automatically from those values.
Option | Description | Default |
|---|---|---|
interface | NIC that receives the mirrored traffic from the switch SPAN port. | (required for live capture) |
pcapFile | Path to a pre-captured | |
bpf | Override the auto-derived BPF filter. | auto-derived from each splitter's |
snaplen | Per-packet capture length in bytes. | 262144 |
bufferMb | Capture-tool kernel buffer size in MB ( | 64 |
flushIntervalMs | How often the assembler evicts idle flows. | 250 |
flowIdleTimeoutSec | Silence threshold (seconds) before a flow is considered idle and evicted. | 30 |
Sample configurations
Receiver client to Automation server
Receiver server to Automation client
SPAN mode passive tap
The canonical example ships with the splitter binary at exec/sbn-splitter/receiver-span-migration.yaml. A reduced version: