Thread Modules¶

Anatomy of a Thread Module (TmModule)¶

A module is a named collection of callbacks related to a task in the packet pipeline. The module definition covers the lifecycle of Suricata -- initialization, operation, and clean up. The steps necessary for declaring a module: adding a unique name to the enum list in tm-modules.h and implement a registration function. Register the module by adding your function call in suricata.c -- the current naming convention is TmModule{YourModuleName}Register(). For example: TmModuleReceivePcapRegister(). Don't forget to add the include statement for your new header file in suricata.c.

During runtime, the module will process packets one at a time. It is guaranteed that no other thread will handle the same packet at the same time. So no locking is necessary when dealing with the packet. When accessing data structures outside of the packet, things change. Almost all packets have a flow (p->flow) that is shared by multiple packets. Before accessing that locking is required. Some global data structures, such as the list of signatures, never change after engine init. These are read only and can thus safely be accessed without any form of locking.

The register function will need to define the fields of a TmModule struct. Some callback fields are optional.

TmModule fields¶

• name: commonly used to locate the module when establishing the packet pipeline plumbing. This way the plumbing declarations indicate incoming queue name, outgoing queue name, and the name of the module to handle processing the packet.

• ThreadInit: init function for associating custom data with the module. For example, logging modules will need to track file handles.

• ThreadDeinit: cleanup function

• ThreadExitPrintStats: optional feature, used to print stats when suricata is shutting down.

• RegisterTests: a function to register module-related unit tests.

• cap_flags: using values from util-privs.h, indicate what sort of capabilities the module will require. This explanation needs further review...

• Func: The meat of the module, the function which is called for each applicable packet.