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 freely using functionality provided by specialized modules divided in the following categories:

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

Core modules can be concatenated to create multiple independent capture chains:

The above diagram could also be represented horizontally:

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

For each chain the logic and functionality is managed using a "capture plans" which defines the behavior of the packet processing pipe. An example follows:

# 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!");
		}
            }
       }
}

As displayed in the example

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 settings:

captagent.xml
captureplans/
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>

Transport Modules

Transport modules are used by captagent to send packets and reports to collectors using different methods and protocols. By default, the HEP method is activated.

HEP

The HEP module is used to define a HEP collector for captured packets, such as HOMER.

The critical parameters are:

• capture-host: defines the IP/hostname of the collector
• capture-port: defines the PORT to deliver HEP packets at the collector
• capture-proto: defines the transport protocol for HEP packets [udp/tcp]
• capture-id: defines a unique delivery HEP-ID to be used for filtering

NOTE: Parameters such as capt-password and payload-compression are currently only used in advanced deployments and can be ignored for standard setups.

<?xml version="1.0"?>
<document type="captagent_module/xml">
    <module name="transport_hep" description="HEP Protocol" serial="2014010402">
        <profile name="hepsocket" description="Transport HEP" enable="true" serial="2014010402">
            <settings>
                <param name="version" value="3"/>
                <param name="capture-host" value="your.homer.ip"/>
                <param name="capture-port" value="9060"/>
                <param name="capture-proto" value="udp"/>
                <param name="capture-id" value="2016"/>
                <param name="capture-password" value="myHep"/>
                <param name="payload-compression" value="false"/>
            </settings>
        </profile>
    </module>
</document>