Configuration

CaptAgent 6: Configuration

This section provides guidance to configure Captagent and its core modules on your system.

Configuration Logic

Understanding of CaptAgent 6 configuration logic and structure is key - read this section carefully!

Sockets, Pipes and Plans

Captagent 6 features a fully modular design enabling users to design and program their packet capture and processing logic, leveraging specialized functionality provided on-demand via loadable dynamic modules.

Core module types include:

type	description
socket	responsible for capturing ingress packets according to settings (ie: PCAP, RAW)
protocol	responsible for processing/dissecting/parsing protocol data (ie: SIP, RTCP)
transport	responsible for providing egress transport for generated data (ie: HEP, JSON)
function	responsible for providing additional functionality (ie: database, etc)

Core modules are loaded via the main captagent.xml configuration file and can be easily concatenated to create multiple, independent capture chains:

In the above example:

SOCKET -> PROFILE -> CAPTURE PLAN <--> MODULES (functions)

---

CAPTURE CHAINS

For each chain, the logic and functionality is managed using a "capture-plan" which defines the behavior of the packet processing pipe. Capture plans are defined within the socket configuration alongside the general capture settings. An example for PCAP socket follows:

            <settings>
		<param name="dev" value="any"/>
		<param name="promisc" value="true"/>
		<param name="reasm" value="false"/>
		<param name="capture-plan" value="sip_capture_plan.cfg"/>
		<param name="filter">
		    <value>portrange 5060-5091</value>
		</param>
	    </settings>

In the above example, packets captured by the socket would be processed by capture-plan in sip_capture_plan.cfg:

# PCAP socket module
capture[pcap] {
        # PROTO SIP module
	# Ie: check source/destination IP/port, message size, etc.
	if(msg_check("size", "100")) {
	    # Parse SIP Protocol
	    if(parse_sip()) {
		# use HEP TRANSPORT module (transport_hep.xml)	
		if(!send_hep("hepsocket")) {
		    clog("ERROR", "Error sending HEP!");
		}
            }
       }
}

The capture-plan can access all functions provided by the loaded modules globally.

---

Basic Configuration

The following are the default file locations (unless otherwise specified during configuration):

• Configuration: /usr/local/etc/captagent
• Capture Plans: /usr/local/etc/captagent/captureplans
• Modules: /usr/local/lib/captagent/modules

Configuration tree

The default directory should contains the following using default profiles and plans:

captagent.xml
captureplans/
    sip_capture_plan.cfg
    rtcp_capture_plan.cfg
    rtcpxr_capture_plan.cfg
protocol_rtcp.xml
protocol_sip.xml
socket_pcap.xml
socket_raw.xml
socket_rtcpxr.xml
transport_hep.xml
transport_json.xml

Main Configuration

To begin, edit and validate the configuration and the module paths in /usr/local/etc/captagent/captagent.xml to match your actual captagent config/lib path:

<configuration name="core.conf" description="CORE Settings" serial="2014024212">
            <settings>
                <param name="debug" value="3"/>
                <param name="version" value="2"/>
                <param name="serial" value="2014056501"/>
                <param name="uuid" value="00781a4a-5b69-11e4-9522-bb79a8fcf0f3"/>
                <param name="daemon" value="false"/>
                <param name="syslog" value="false"/>
                <param name="pid_file" value="/var/run/captagent.pid"/>
                <param name="module_path" value="/usr/local/lib/captagent/modules"/>
                <param name="config_path" value="/usr/local/etc/captagent"/>
                <param name="capture_plans_path" value="/usr/local/etc/captagent/captureplans"/>
                <param name="backup" value="/usr/local/etc/captagent/backup"/>
                <param name="chroot" value="/var/lib/captagent"/>
            </settings>
        </configuration>

Next:

• Configure Socket Modules
• Configure Transport Modules