output-eve.h File Reference

EVE logging subsystem. More...

#include "suricata-common.h"
#include "rust.h"
#include "conf.h"

Include dependency graph for output-eve.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	SCEveFileType_
	Structure used to define an EVE output file type plugin. More...

Typedefs
typedef uint32_t	ThreadId
typedef struct SCEveFileType_	SCEveFileType
	Structure used to define an EVE output file type plugin. More...
typedef void(*	SCEveUserCallbackFn) (ThreadVars *tv, const Packet *p, Flow *f, JsonBuilder *jb, void *user)
	Function type for EVE callbacks. More...

Functions
bool	SCRegisterEveFileType (SCEveFileType *)
	Register an Eve file type. More...
SCEveFileType *	SCEveFindFileType (const char *name)
bool	SCEveRegisterCallback (SCEveUserCallbackFn fn, void *user)
	Register a callback for adding extra information to EVE logs. More...
void	SCEveRunCallbacks (ThreadVars *tv, const Packet *p, Flow *f, JsonBuilder *jb)

Detailed Description

EVE logging subsystem.

This file will attempt to the main module for EVE logging sub-system. Currently most of the API resides in output-json.[ch], but due to some circular dependencies between EVE, and LogFileCtx, it made it hard to add EVE filetype modules there until some include issues are figured out.

Definition in file output-eve.h.

Typedef Documentation

SCEveFileType

typedef struct SCEveFileType_ SCEveFileType

Structure used to define an EVE output file type plugin.

EVE filetypes implement an object with a file-like interface and are used to output EVE log records to files, syslog, or database. They can be built-in such as the syslog (see SyslogInitialize()) and nullsink (see NullLogInitialize()) outputs, registered by a library user or dynamically loaded as a plugin.

The life cycle of an EVE filetype is:

• Init: called once for each EVE instance using this filetype
• ThreadInit: called once for each output thread
• Write: called for each log record
• ThreadInit: called once for each output thread on exit
• Deinit: called once for each EVE instance using this filetype on exit

Examples:

• built-in syslog: src/output-eve-syslog.c
• built-in nullsink: src/output-eve-null.c
• example plugin: examples/plugins/c-json-filetype/filetype.c

Multi-Threaded Note:

The EVE logging system can be configured by the Suricata user to run in threaded or non-threaded modes. In the default non-threaded mode, ThreadInit will only be called once and the filetype does not need to be concerned with threads.

However, in threaded mode, ThreadInit will be called multiple times and the filetype needs to be thread aware and thread-safe. If utilizing a unique resource such as a file for each thread then you may be naturally thread safe. However, if sharing a single file handle across all threads then your filetype will have to take care of locking, etc.

SCEveUserCallbackFn

typedef void(* SCEveUserCallbackFn) (ThreadVars *tv, const Packet *p, Flow *f, JsonBuilder *jb, void *user)

Function type for EVE callbacks.

The function type for callbacks registered with SCEveRegisterCallback. This function will be called with the JsonBuilder just prior to the top-level object being closed. New fields maybe added, however there is no way to alter existing objects already added to the JsonBuilder.

Parameters

tv	The ThreadVars for the thread performing the logging.
p	Packet if available.
f	Flow if available.
user	User data provided during callback registration.

Definition at line 190 of file output-eve.h.

ThreadId

typedef uint32_t ThreadId

Definition at line 37 of file output-eve.h.

Function Documentation

SCEveFindFileType()

SCEveFileType* SCEveFindFileType

(

const char *

name

)

Definition at line 82 of file output-eve.c.

References SCEveFileType_::name, and TAILQ_FOREACH.

SCEveRegisterCallback()

bool SCEveRegisterCallback	(	SCEveUserCallbackFn	fn,
		void *	user
	)

Register a callback for adding extra information to EVE logs.

Allow users to register a callback for each EVE log. The callback is called just before the root object on the JsonBuilder is to be closed.

New objects and fields can be append, but exist entries cannot be modified.

Packet and Flow will be provided if available, but will other be NULL.

Limitations: At this time the callbacks will only be called for EVE loggers that use JsonBuilder, notably this means it won't be called for stats records at this time.

Returns

true if callback is registered, false is not due to memory allocation error.

SCEveRunCallbacks()

void SCEveRunCallbacks	(	ThreadVars *	tv,
		const Packet *	p,
		Flow *	f,
		JsonBuilder *	jb
	)

Definition at line 53 of file output-eve.c.

Referenced by OutputJsonBuilderBuffer().

Here is the caller graph for this function:

SCRegisterEveFileType()

bool SCRegisterEveFileType

(

SCEveFileType *

plugin

)

Register an Eve file type.

Return values

true	if registered successfully, false if the file type name conflicts with a built-in or previously registered file type.

Definition at line 100 of file output-eve.c.