Up to Docs
Contents

Trisul Configuration File

All the configuration parameters for the trisul daemon is stored in a single XML main configuration file called trisulConfig.xml. This config file is the first argument to the trisul daemon

The default location of this file is in the /usr/local/etc/trisul directory.

  • Root privileges needed to edit
  • Need to restart trisul for any changes to take effect
You can edit the trisulConfig.xml file using a plain text editor like vi or nano

Sections

trisulConfig.xml is divided into sections

Section What part of trisul does it configure
App The trisul running process
Logging Logging policy – file sizes and rotation
StatsEngine Database cluster tuning
Security For TRP – certificates for remote connections
Redis The Redis server used for real time stabbers
Server For TRP – server parameters
Ring Full content storage and retention policy
Reassembly TCP reassembly and advanced metering
IDS Alerts Unix sockets for accepting Unified and Unified2 alerts
Offline Import For importing large pcap dumps (mostly used for testing
Tuning Tuning packet processing pipeline
Syslog Syslog alert settings

AppTop

Settings for the Trisul daemon process

Parameters you may want to change are

  • Setuid
  • TrisulMode
  • LicenseFile
Parameters Defaults Description
Setuid trisul.trisul Which user/group should trisul run as after dropping root privileges.
IdeallyUseThisSetuid trisul.trisul Unused – Just a hint
TempFolder /tmp
DBRoot /usr/local/var/lib/trisul/CONTEXT0 The base directory under which Trisul stores all its data.
ConfigDB /usr/local/var/lib/trisul/CONTEXT0/ config/TRISULCONFIG.SQDB Location of the configuration database.
TrafficDBRoot /usr/local/var/lib/trisul/CONTEXT0/meters The directory under which Trisul stores traffic and flow statistics.
PluginsLibDirectory /usr/local/lib/trisul/plugins Where trisul looks for dynamic (called so) plugins
PluginsConfDirectory /usr/local/etc/trisul Where trisul looks for additional configuration files and server certificates (for TRP).
PluginsDataDirectory /usr/local/share/trisul/plugins Where trisul looks for plugin configuration data.
ProbeID SE-LINK A mnemonic to identify this instance of Trisul, this string is reported via TRP.
ProbeDesc Trisul Probe monitors the S-E link traffic only A short description of this instance of trisul.
PidFile /usr/local/var/run/trisul.pid File where trisul stores the process id of the current running instance.
LiveStatsDumpFile /tmp/pulse.lst For debugging purposes only.
ThisPath /usr/local/share/trisul Location of the share directory, where certain scripts are installed.
TrisulMode TAP This determines whether you run Trisul in raw packets mode or Netflow mode.TAP Processes all raw packets from the selected network adapters.NETFLOW_TAP Processes Netflow packets
ValidTrisulModes TAP,NETFLOW_TAP Unused – just a quick hint for the previous parameter.
LicenseFile /usr/local/etc/trisul/LicenseKey.txt Location of the license file.
LibpcapMode select Determines how Trisul will use the libpcap API. Only applicable if trisul run mode is ’’online’’ (ie using libpcap). Not applicable when using the default Linux RX Ring runmode
select use the libpcap select/poll API on multiple interfaces to acquire packets
nonblock_dispatch use nonblocking pcap_dispatch in a loop over multiple interfaces to acquire packets.Use nonblock_dispatch if you are using DAG or similar adapters that do not support pcap_get_selectable_fd()

LoggingTop


Controls Trisul logging.
Parameters you may want to change.

  • Loglevel
  • LogRotateSize
  • LogRotateCount

Log files are stored in a ring format so the total space on disk is capped. Typically you’d have logs grow from ns-001.log, ns-002.log, …, ns-005.log and then back to ns-001.log.

Parameters Defaults Description
Logdir /usr/local/var/log/trisul Where the log files are stored.
Logfile ns-???.log Log file pattern. The default is ns-001.log, ns-002.log, etc.
Loglevel DEBUG All messages higher than this level are logged. The available log levels in order of severity (most severe one first is).
EMERG
FATAL
ALERT
CRIT
ERROR
WARN — this level after a few weeks of smooth running
NOTICE
INFO
DEBUG — Recommended default level
LogRotateSize 5000000 Size of each log file is allowed to grow to this size before Trisul moves to the next file.
LogRotateCount 5 The number of files in the log ring.
EnableAccessLog TRUE Access logs are used to keep track of TRP (Trisul Remote Protocol) activity.
AccessLogfile as-???.log The access log file pattern.
AccessLogRotateSize 5000000 Max size of each access log file.
AccessLogRotateCount 5 Number of access log files in ring.

StatsEngineTop

Controls the database storage and retention policy for Trisul.

Parameters Defaults Description
HIWaterPolicy FLEXIBLE Determines how Trisul copes under severe load. This can happen on a very busy network or under a DDoS attack against Trisul itself or elsewhere on the network. Trisul detects this condition when Hi Water marks are crossed for counters or flows.
The available options are :
FLEXIBLE Trisul is not too rigid about the Hi Water mark, it allows usage to grow beyond the high water mark until the next flush interval (see SQLInsertThresholdMSecs)
FIXED When a Hi Water mark is hit, no new counters are flows are accepted. Existing ones are metered as usual. At the next flush interval, the counters or flows are pruned down to the low water mark and things proceed as usual
Usage Hint : Use FLEXIBLE (the default) in most cases, use FIXED if you are memory constrained and can accept a slight inaccuracy under heavy load.
SQLInsertThresholdPackets 100000000 Ensures database is updated atleast every this many packets.
SQLInsertThresholdMSecs 60000 Ensures that the database is updated every this many milliseconds. The default value is 60,000ms or 60 seconds or 1 minute. This means that by merely looking at the database you can have an up to the 1-minute real time view of the network.
SQLBusyTimeoutMsecs 2 SQLITE3 configuration parameter. Timeout for Trisul server inserts and updates.
SQLTRPBusyTimeoutMsecs 8000 SQLITE3 configuration parameter. Timeout for servicing TRP queries.
SQLSynchronousMode 0 SQLITE3 configuration parameter. Options are
Async mode 0 – fastesr. However, power / hardware failures can corrupt data slices.
Partly async 1
Sync 2 – Maximum safety but also slowest (the default)
SQLFlushThreads 2 Number of parallel flusher threads.
Usage note : Set this to 0 when importing pcap files. When set to 0 threads are not used for flushing.
OverlayExistingSlices FALSE If set to TRUE, trisul will accept data with older timestamps and attempt to overlay the stats on existing items in the database. This parameters is only used if you are trying to import IDS alerts from a capture file.
SQLJournalMode default Set this to the underlying SQLITE3 journal mode. Use this only when peak performance is unsatisfactory. One option you can consider is setting this to WAL (Write Ahead Logging).
default The usual sqlite3 journal mode is used (the default)
WAL The newer Write Ahead Logging mode (can give 20-30% better performance
SQLPageSize 0 Allows you to set the page size for the underlying SQLITE3 slices. A value of 0 uses the default.
SQLCacheSize 0 Allows you to set the cache size for the underlying SQLITE3 slices. A value of 0 uses the default.

SlicePolicy

Controls data location and retention policy.

To summarize the Slice concept

  • Divides data into slices
  • Puts slices into three categories depending on their age
  • The three types are Operational (oper), Reference (ref), and Archive (archive)
  • Slices move (slide) across these categories as time goes by
  • Slices slide out from the archive area into (/dev/null) ie. they are deleted

For fastest performance:

  • Operational Slices : On SSD drives
  • Reference Slices : On 15K SAS
  • Archive : Commodity 7200 SATA or NAS
Parameters Defaults Description
SliceWindow DAILY How much data is contained in a single slice. The available choices are :
HOURLY From 00 Min to 59 Min every hour
DAILY From 12:00 AM to 11:59 PM every day
WEEKLY From Sun 12:00 AM to Sat 11:59 PM every week
MONTHLY From 1st of month 12:00 to last of month 11:59 PM every month

Operational

Controls how many slices are kept in the operational area. Allows you to size your operational window to match what time interval most of your users are pulling reports with available hardware resources.

Parameters Defaults Description
SliceCount 32 32 slices are kept in the operational area. Combined with the default SliceWindow of DAILY. This means 32 days worth of data in the oper area. Slices older than 32 days will slide over to the reference area.

Reference

Match your reference area to the time window where users infrequently pull reports or investigate.

Parameters Defaults Description
SliceCount 32 Controls how many slices are kept in the reference area. If you set this to 0, the slices will then move straight from operational to archive.

Archive

For long term storage mostly for compliance purposes. You can still pull reports from the archive area, but such operations are rare and it is okay to take a slight performance hit for this time interval.

Parameters Defaults Description
SliceCount 32 Controls how many slices are kept in the archive area. If you set this to 0, slices move directly to /dev/null (ie are deleted).

SecurityTop

Specifies security parameters for TRP.

Parameters Defaults Description
Protocol TLS Available options :
TLS Use TLS for TRP connections
TCP Use plain TCP, all security related parameters below are ignored.This mode is useful for demos/testing
ClientAuth true Whether client authentication is done. If true, all TRP clients must produce a client certificate issued by the authority administering the Trisul server.
Client Certs are of three types:
Admin Allows TRP clients to perform admin actions, like update keys
Basic All actions except getting at deep packet inspection of monitoring individual user flows
Forensics All actions except admin
ServerCertificate /usr/local/etc/trisul/certs/
trisuls/Demo_TrisulServer.crt		 Server certificate. The default value is a demo cert shipped with Trisul.
ServerKey /usr/local/etc/trisul/certs/
trisuls/Demo_TrisulServer.key		 Server private key. The default value is
a demo key shipped with Trisul.
CACertChain /usr/local/etc/trisul/
certs/Demo_CACerts.pem
ClientCertificateBaseDir /usr/local/etc/trisul/certs/
unsniffs		 Store all issued client certs here. The certs are stored in three subdirectories depending on their permissions

--/admin_certs
--/basic_certs
--/forensics_certs
DiffieHellmanParameters /usr/local/etc/trisul/
certs/TrisulDH1024.pem
CipherPres AES256-SHA Preferred encryption.

RedisTop

Settings for the Redis server used for the real time stabber functionality.

Parameters Defaults Description
Enabled True Set this to ’’False’’ if you are not interested in the real time functionality offered.
UnixSocket /usr/local/var/lib/trisul/
CONTEXT0/run/redis.socket		 The Unix socket for comms between Trisul and Redis.
ConfigFile /usr/local/etc
/trisul/redis.conf		 The redis config file.
ServerImage /usr/local/bin/redis-server The redis-server executable.
If you have a later version, you can point this to your version instead

ServerTop

Controls properties of the TRP server.

Parameters Defaults Description
Port 12001 Port on which to listen for TRP clients.
DebugComms true For internal debugging use.
DebugCommsFile /tmp/pulse_comms.dbg For internal debugging use.
ZipThreshold 100000 For retrieving packets, if PCAP size exceeds this amount in bytes, then the payload is zipped over TRP.
ZipProtocol DEFLATE No options except DEFLATE.
ACL ACLItem Address=“127.0.0.1” Mask=“255.255.255.255”
ACLItem Address=“192.168.2.0” Mask=“255.255.255.0”
ACLItem Address=“192.168.1.0” Mask=“255.255.255.0”
ACLItem Address=“10.1.1.0” Mask=“255.255.255.0” 		Specifies which networks are allowed to connect via TRP.
You have to edit this to match your network. To allow connections from 10.10.17.0/24 network, add a new entry like so

RingTop

Full content storage policy.

The Ring section allows you to control.

  • How big each full content file gets
  • How many such full content files are in a slice
  • How many slices in operational, reference, and archive areas
  • Passphrase file (the content files are AES-128 CTR mode encrypted)
  • Flow rules for content trimming
Parameters Defaults Description
Enabled True Setting this to False will disable all options below, full content will not be saved.
BaseDir /usr/local/var/lib/
trisul/CONTEXT0/caps		 Parent directory under which full content files are saved.
PassphraseFile /usr/local/etc/
trisul/certs/ringpass.txt		 The encryption passphrase for the full content files.
FilePrefix RCF_ Content files are called RCF_001.triscap, RCF_001.triscap, etc.. This options allows you to change the RCF_ part.
FileSizeMB 100 Size of each full content file in megabytes.
Maximum allowed value = 8000 (8GB). If you specify a size greater than this limit, Trisul will ignore it and use 8GB as the value.
ProcSampleSecs 30 Diagnostic use only.
SysStatsUpdateSecs 10 Diagnostic use only.
RunStatsUpdateSecs 30 Diagnostic use only.
LiveStatsFlipSecs 100 Diagnostic use only.
DefaultMode FULL To cut down on full content data, Trisul allows you to apply a variety of policies. The supported modes are
FULL Everything is saved This is the default mode
FLOWCAP10M Only first 10MB of each TCP flow is saved.
FLOWCAP1M Only first 1MB of each TCP flow is saved.
FLOWCAP100K Only first 100KB of each TCP flow is saved.
FLOWCAP10K Only first 10KB of each TCP flow is saved.
HEADERS Only headers are saved, typically upto the TCP/UDP layer
IGNORE Nothing is saved
RuleChain Each packet is evaluated against a rule chain, which is a list of rules.

Operational

SliceCount 32 Number of operational slices , the size of each slices is fixed as specified by FileSizeKB parameter

Reference

SliceCount 32 Setting this to zero will move slices straight to the archive.

Archive

SliceCount 0 Number of reference slices.. If you set this to 0, slices move directly to /dev/null (ie are deleted).

Rule Chain

Number of archive slices. Setting this to zero will delete slices (send to /dev/null)

  • Each rule is an expression in the Trisul filter format
  • Treatment of each packet is one of : Store full packet, Store header, or Ignore
  • The first rule to match determines the treatment given to the packet
  • If no rule matches, the treatment specified in the DefaultMode parameter is applied

Rule mode=“FULL”

If present, packets which match this rule get stored completely.

Rule mode=“FLOWCAP10M”

If present,

  • packets which match this rule and
  • belong to a flow which has transferred less than 10MB bidirectionally get stored fully.

Rule mode=“FLOWCAP1M”

If present,

  • packets which match this rule and
  • belong to a flow which has transferred less than 1MB bidirectionally get stored fully.

Rule mode=“FLOWCAP100K”

If present,

  • packets which match this rule and
  • belong to a flow which has transferred less than 100KB bidirectionally get stored fully.

Rule mode=“FLOWCAP10K”

If present,

  • packets which match this rule and
  • belong to a flow which has transferred less than 10KB bidirectionally get stored fully.

Rule mode=“HEADERS”

If present, packets which match get only their headers stored. The headers include at least the Ethernet/IP/TCP/UDP layers.

Rule mode=“IGNORE”

If present, packets which match get ignored (sent to /dev/null).

SlicePolicy

Specifies how many files you want to keep in each of the three areas. The size of each file is capped by the FileSizeKB parameter.

Example
You want this policy :

  • Each Slice file is 1GB
  • Store 20GB in the operational area (maybe you have limited SSD or RAID5)
  • Store 500GB in the reference area
  • Store 1TB in the archive

Then the SliceCounts will be 20,500,1000 for the operational,ref, archive areas.

Note : The database slices are fixed time but the full content slices are fixed size

ReassemblyTop

Controls how Trisul handles IP fragmentation and TCP reassembly.

IPDefrag

Parameters Defaults Description
Enabled True Reassembles IP fragments.

TCPFlowTrack

Flow tracking keeps track of how much data has been transmitted in either direction in a single TCP flow.

  • Required for flow based full content storage policy (like storing first 1M of each flow)
  • Required for TCP Reassembly
  • Required for all reassembly based applications like XFF Deproxy, URI Log, Content Type meters, etc
Parameters Defaults Description
Enabled False
HiWater 8000 Hi water mark for number of simultaneous flows that can be tracked. If the number of simultaneous active flows exceeds the high water mark, Trisul will prune the oldest active flows until the number of flows goes one below the low water mark.
LoWater 6000 Lo water mark for TCP flow pruning. See explanation for HiWater.

TCPReassembly

Controls TCP Reassembly.

TCP Flow Tracking only tracks the volume of data on each flow, but TCP Reassembly actually puts the payload together and passes the reassembled payload to metering modules.
  • Required for all reassembly based applications like XFF Deproxy, URI Log
  • Required for reassembly based meters like HTTP Content Types, HTTP Hosts, URL Filter, etc
Parameters Defaults Description
Enabled False
MaxBytes 0
KickoffBytes 5000 Some meter within Trisul must express an interest in reassembled data for a given flow before this limit is reached. Otherwise reassembly is stopped at this point for this flow.
Ports 3000,80,443,22,21 Traffic on these ports are reassembled.

Direction

Defaults:INOUT

Available options

IN Only the IN direction; direction of first SYN+ACK is reassembled
OUT Only the OUT direction; direction of initial SYN is reassembled
INOUT Both directions are reassembled

Applications

Some advanced applications.

Since these applications depend on the TCP Reassembly feature, they are resistant to TCP fragmentation evasions.

Parameters Defaults Description
EnableXFFDeproxy True Useful in a corporate environment with web proxies. If set to true, Trisul can deproxy web traffic by looking at the X-Forwarded-For HTTP header. The actual IP is substituted for all metering and flow analysis instead of the proxy’s IP.
EnableURILog True Logs all HTTP URLs requested. These URLS show up as Resources in Trisul where they are correlated and made searchable.
EnableHostMeter True Add traffic metering by HTTP Host header. The net effect of enabling this is that the HTTP Host counter group is made active.
EnableContentTypeMeter True Add traffic metering by HTTP Content-Type header. Activates the HTTP Content Type counter group.

IDSAlertsTop

Controls how security alerts from Snort/Barnyard2 are handled

Parameters Defaults Description
Enabled True Enables this feature. If this is set to FALSE, alerts will not be processed even if trisul is running in fullblown or idsalert modes.
SnortUnixSocket /tmp/snort_alert Trisul opens this unix socket and listens for alerts. Typically this is ’’snort_alert’’ for Unified events from Snort and ’’barnyard2_alert’’ for Unified2 events from Barnyard2.
SnortVersion 2.9+ Trisul uses Unix Sockets to read alerts from Snort. Snort 2.9 and above use a different structure compared to earlier versions. This string helps decide which version we are using.
Example : If you are running Snort 2.8, then set this to ‘’2.8’‘. If you are always using 2.9 or newer then just leave this at the default setting, which is ’’2.9+’’ . Do not set this to 2.10, 3.0, etc.

OfflineImportTop

Controls aspects of PCAP file import.

Parameters Defaults Description
LoopCount 1 Used for testing. Runs the same capture file/directory this many time past Trisul. Each run is appended time-wise to the end of the previous run. This is used internally by us to generate months of data from a few days of capture by repeating them over and over.
AppendMode TRUE Appends the run to the previous runs time-wise. The packet time stamps in the capture file are offset by the last time of the previous run.
InterfileGapSecs 60 When importing multiple files, this option puts a gap of this many seconds between each file. There is no purpose of this option other than to view a gap in the charts representing the capture files.
AutoSortByCaptime TRUE When TRUE, the candidate capture files are sorted by time order (earliest to latest), and then imported into Trisul. When FALSE, the files and subdirectories are processed in alphabetical order.
ResumeStalledImport FALSE Dependency:AutoSortByCaptime must be TRUE
Treats the import as a resumption of a previously stalled or aborted offline import. When TRUE, Trisul will first determine what timestamp was last flushed. Then it will skip all packets earlier than that timestamp and continue importing when newer timestamps are seen.
This feature is used to resume a stopped import without reprocessing everything again.
Use this feature with the following caution :
# Due to the discontinuous nature, some packets may be missed or double counted around the timestamp where the earlier import was aborted
# Flows may be duplicated around the time
AddEthernetFCS FALSE If set to true, will add 12 bytes to every ethernet packet to account for FCS

TuningTop

Fine tune the packet processing pipeline for peak performance.

Parameters Defaults Description
QueueCapacity 200000 A key internal queue, which contains messages pending processing. Increasing this will increase your memory usage and decrease packet loss.
GrainSize 64 Number of packets to process in a batch. You can increase this value if you have a CPU with a large L1/L2 cache. If the entire batch fits in cache memory – it can increase concurrency – and decrease drops.
SpongeCapacity 8 A key internal data structure parameter to help with multicore.
Increase this if you have a very high speed network but with less diversity. In most cases, leave this alone.
SpongeWindow 1 A key internal data structure parameter to help with multicore.
Number of seconds a single core must accumulate before synchronizing. In most cases, leave this alone.
InflightTokens 8 Number of batches (see GrainSize) of work concurrently in flight. A good value would be a little more than the total number of hardware threads available.
RxRingBlockCountExponent 13 Applicable only if capture mechanism is Linux RX Ring. This parameter sets the size of the ring. The number of page-sized blocks in the ring will be 2 ^(_RxRingBlockCountExponent_). The default is 13 – which translates to 2^ 13 = 819 blocks of system page size each = 32MB
Tune this parameter up if you have a huge amount of memory or down if you are constrained.

SyslogTop

Controls which alerts are sent to syslog.

Parameters Defaults Description
Enabled True Do you want this feature to be enabled ?
Program trisul Program name as it appears in syslog

Alerts

Controls the severity level of each type of alert. Leave the severity blank to disable forwarding alerts of that type to syslog.

Default Shown below

 <Alerts>
  <Alert name="ThresholdCrossing" guid="{03AC6B72-FDB7-44c0-9B8C-7A1975C1C5BA}">INFO</Alert>
  <Alert name="FlowTracker"       guid="{18CE5961-38FF-4aea-BAF8-2019F3A09063}">INFO</Alert>
  <Alert name="Badfellas"         guid="{5E97C3A3-41DB-4e34-92C3-87C904FAB83E}">INFO</Alert>
  <Alert name="IDS"               guid="{9AFD8C08-07EB-47E0-BF05-28B4A7AE8DC9}"></Alert>
 </Alerts>

Valid syslog alert types are EMERG, ALERT, CRIT, WARNING, NOTICE, INFO, DEBUG.