From 14b648f286671f67047cb0f6b5f68d5e5a9223cf Mon Sep 17 00:00:00 2001 From: Jason Ish Date: Fri, 30 Aug 2024 12:54:28 -0600 Subject: [PATCH] output-streaming: rename and document registration Prefix the registration function and types with "SC", and add function documentation. Ticket: #7227 --- .../devguide/extending/output/index.rst | 15 +++++++++ src/log-tcp-data.c | 2 +- src/output-streaming.c | 10 +++--- src/output-streaming.h | 33 +++++++++++++++---- src/output.c | 4 +-- src/output.h | 8 ++--- src/runmodes.c | 2 +- 7 files changed, 54 insertions(+), 20 deletions(-) diff --git a/doc/userguide/devguide/extending/output/index.rst b/doc/userguide/devguide/extending/output/index.rst index c401b3c4e7..e5b22192ef 100644 --- a/doc/userguide/devguide/extending/output/index.rst +++ b/doc/userguide/devguide/extending/output/index.rst @@ -62,3 +62,18 @@ Transaction logger can be registered with the :language: c :start-at: /** \brief Register a transaction logger :end-at: ); + +Stream Logging +~~~~~~~~~~~~~~ + +Stream logging allows for the logging of streaming data such as TCP +reassembled data and HTTP body data. The provided log function will be +called each time a new chunk of data is available. + +Stream loggers can be registered with the +``SCOutputRegisterStreamingLogger`` function: + +.. literalinclude:: ../../../../../src/output-streaming.h + :language: c + :start-at: /** \brief Register a streaming logger + :end-at: ); diff --git a/src/log-tcp-data.c b/src/log-tcp-data.c index a801c89978..b4e8b18a86 100644 --- a/src/log-tcp-data.c +++ b/src/log-tcp-data.c @@ -54,7 +54,7 @@ void LogTcpDataLogRegister (void) { typedef struct LogTcpDataFileCtx_ { LogFileCtx *file_ctx; - enum OutputStreamingType type; + enum SCOutputStreamingType type; const char *log_dir; int file; int dir; diff --git a/src/output-streaming.c b/src/output-streaming.c index a2e3067b08..c81fbbc9ee 100644 --- a/src/output-streaming.c +++ b/src/output-streaming.c @@ -48,20 +48,20 @@ typedef struct OutputStreamingLoggerThreadData_ { * it's perfectly valid that have multiple instances of the same * log module (e.g. http.log) with different output ctx'. */ typedef struct OutputStreamingLogger_ { - StreamingLogger LogFunc; + SCStreamingLogger LogFunc; void *initdata; struct OutputStreamingLogger_ *next; const char *name; LoggerId logger_id; - enum OutputStreamingType type; + enum SCOutputStreamingType type; ThreadInitFunc ThreadInit; ThreadDeinitFunc ThreadDeinit; } OutputStreamingLogger; static OutputStreamingLogger *list = NULL; -int OutputRegisterStreamingLogger(LoggerId id, const char *name, StreamingLogger LogFunc, - void *initdata, enum OutputStreamingType type, ThreadInitFunc ThreadInit, +int SCOutputRegisterStreamingLogger(LoggerId id, const char *name, SCStreamingLogger LogFunc, + void *initdata, enum SCOutputStreamingType type, ThreadInitFunc ThreadInit, ThreadDeinitFunc ThreadDeinit) { OutputStreamingLogger *op = SCCalloc(1, sizeof(*op)); @@ -98,7 +98,7 @@ typedef struct StreamerCallbackData_ { OutputLoggerThreadStore *store; ThreadVars *tv; Packet *p; - enum OutputStreamingType type; + enum SCOutputStreamingType type; } StreamerCallbackData; static int Streamer(void *cbdata, Flow *f, const uint8_t *data, uint32_t data_len, uint64_t tx_id, uint8_t flags) diff --git a/src/output-streaming.h b/src/output-streaming.h index 1af4058fe4..c09f544371 100644 --- a/src/output-streaming.h +++ b/src/output-streaming.h @@ -1,4 +1,4 @@ -/* Copyright (C) 2007-2022 Open Information Security Foundation +/* Copyright (C) 2007-2024 Open Information Security Foundation * * You can copy, redistribute or modify this Program under the terms of * the GNU General Public License version 2 as published by the Free @@ -32,22 +32,41 @@ #define OUTPUT_STREAMING_FLAG_TOCLIENT 0x08 #define OUTPUT_STREAMING_FLAG_TRANSACTION 0x10 -enum OutputStreamingType { +enum SCOutputStreamingType { STREAMING_TCP_DATA, STREAMING_HTTP_BODIES, }; /** streaming logger function pointer type */ -typedef int (*StreamingLogger)(ThreadVars *, void *thread_data, - const Flow *f, const uint8_t *data, uint32_t data_len, - uint64_t tx_id, uint8_t flags); +typedef int (*SCStreamingLogger)(ThreadVars *, void *thread_data, const Flow *f, + const uint8_t *data, uint32_t data_len, uint64_t tx_id, uint8_t flags); -int OutputRegisterStreamingLogger(LoggerId id, const char *name, StreamingLogger LogFunc, - void *initdata, enum OutputStreamingType, ThreadInitFunc ThreadInit, +/** \brief Register a streaming logger. + * + * \param logger_id An ID to uniquely identify this logger. + * + * \param name An informational name for this logger. + * + * \param LogFunc Pointer to logging function. + * + * \param initdata Initialization data that will be passed the + * ThreadInit. + * + * \param stream_type Type of stream to log, see + * SCOutputStreamingType. + * + * \param ThreadInit Pointer to thread initialization function. + * + * \param ThreadDeinit Pointer to thread de-initialization function. + */ +int SCOutputRegisterStreamingLogger(LoggerId logger_id, const char *name, SCStreamingLogger LogFunc, + void *initdata, enum SCOutputStreamingType stream_type, ThreadInitFunc ThreadInit, ThreadDeinitFunc ThreadDeinit); +/** Internal function: private API. */ void OutputStreamingLoggerRegister (void); +/** Internal function: private API. */ void OutputStreamingShutdown(void); #endif /* SURICATA_OUTPUT_STREAMING_H */ diff --git a/src/output.c b/src/output.c index db399e25a6..46e7f808a8 100644 --- a/src/output.c +++ b/src/output.c @@ -501,8 +501,8 @@ error: * \retval Returns 0 on success, -1 on failure. */ void OutputRegisterStreamingModule(LoggerId id, const char *name, const char *conf_name, - OutputInitFunc InitFunc, StreamingLogger StreamingLogFunc, - enum OutputStreamingType stream_type, ThreadInitFunc ThreadInit, + OutputInitFunc InitFunc, SCStreamingLogger StreamingLogFunc, + enum SCOutputStreamingType stream_type, ThreadInitFunc ThreadInit, ThreadDeinitFunc ThreadDeinit) { if (unlikely(StreamingLogFunc == NULL)) { diff --git a/src/output.h b/src/output.h index a7652f8d9d..abbd907a1e 100644 --- a/src/output.h +++ b/src/output.h @@ -71,10 +71,10 @@ typedef struct OutputModule_ { FileLogger FileLogFunc; FiledataLogger FiledataLogFunc; FlowLogger FlowLogFunc; - StreamingLogger StreamingLogFunc; + SCStreamingLogger StreamingLogFunc; StatsLogger StatsLogFunc; AppProto alproto; - enum OutputStreamingType stream_type; + enum SCOutputStreamingType stream_type; int tc_log_progress; int ts_log_progress; @@ -128,8 +128,8 @@ void OutputRegisterFlowSubModule(LoggerId id, const char *parent_name, const cha ThreadInitFunc ThreadInit, ThreadDeinitFunc ThreadDeinit); void OutputRegisterStreamingModule(LoggerId id, const char *name, const char *conf_name, - OutputInitFunc InitFunc, StreamingLogger StreamingLogFunc, - enum OutputStreamingType stream_type, ThreadInitFunc ThreadInit, + OutputInitFunc InitFunc, SCStreamingLogger StreamingLogFunc, + enum SCOutputStreamingType stream_type, ThreadInitFunc ThreadInit, ThreadDeinitFunc ThreadDeinit); void OutputRegisterStatsModule(LoggerId id, const char *name, const char *conf_name, diff --git a/src/runmodes.c b/src/runmodes.c index 9a2f20d5e8..eb4cfa879e 100644 --- a/src/runmodes.c +++ b/src/runmodes.c @@ -640,7 +640,7 @@ static void SetupOutput( file_logger_count++; } else if (module->StreamingLogFunc) { SCLogDebug("%s is a streaming logger", module->name); - OutputRegisterStreamingLogger(module->logger_id, module->name, module->StreamingLogFunc, + SCOutputRegisterStreamingLogger(module->logger_id, module->name, module->StreamingLogFunc, output_ctx, module->stream_type, module->ThreadInit, module->ThreadDeinit); } else { SCLogError("Unknown logger type: name=%s", module->name);