doc/devguide: document eve file types

Ticket: #4708

diff --git a/doc/userguide/devguide/extending/index.rst b/doc/userguide/devguide/extending/index.rst
index bcdabeffd7a30a6737caac6e46b8340fb8c281d7..0505f1625b055f6d5c49954e9065593ef41356a8 100644 (file)
--- a/doc/userguide/devguide/extending/index.rst
+++ b/doc/userguide/devguide/extending/index.rst
@@ -9,3 +9,4 @@ Extending Suricata
    app-layer/index.rst
    detect/index.rst
    output/index.rst
+   output/eve-filetypes.rst

diff --git a/doc/userguide/devguide/extending/output/eve-filetypes.rst b/doc/userguide/devguide/extending/output/eve-filetypes.rst
new file mode 100644 (file)
index 0000000..f6c8996
--- /dev/null
+++ b/doc/userguide/devguide/extending/output/eve-filetypes.rst
@@ -0,0 +1,99 @@
+EVE Filetypes
+#############
+
+Introduction
+************
+
+The Suricata EVE/JSON output supports filetypes to extend how
+EVE records are processed and delivered. Custom filetypes
+provide alternatives to standard file output by implementing a
+file-like interface that Suricata can write to. These filetypes can
+send events to databases, sockets, or other destinations, and can even
+perform custom processing on the output before storing it.
+
+EVE Filetype Life Cycle
+***********************
+
+The life-cycle of an EVE filetype along with the callbacks are
+discussed in ``output-eve.h``:
+
+.. literalinclude:: ../../../../../src/output-eve.h
+   :language: c
+   :start-at: /** \brief Structure used to define an EVE output
+   :end-at: } SCEveFileType;
+
+Threading Considerations
+************************
+
+It is the user's Suricata EVE output configuration that enables
+multi-threaded logging, not the filetype. So all filetypes should be
+designed to be thread safe.
+
+If your filetype can absolutely not be made thread safe, it would be
+best to error out on initialization. This can be done during the
+filetype initialization:
+
+.. code-block:: c
+
+   static int MyFiletypeInit(const SCConfNode *node, const bool threaded, void **data)
+   {
+       if (threaded) {
+           FatalError("EVE filetype does not support threaded logging.");
+       }
+
+       /* Continue with initialization. */
+   }
+
+Write Considerations
+********************
+
+The ``Write`` callback is called in a packet processing thread so any
+blocking (other than writing to a file) should be avoided. If writing
+to a blocking resource it is recommended to copy the buffer into
+another thread for further processing to avoid packet loss.
+
+Registration
+************
+
+Registering an EVE filetype requires registering the filetype
+early in the Suricata start-up or lifecycle, or if a plugin, in the
+plugin initialization function.
+
+.. code-block:: c
+
+   SCEveFileType *filetype = SCCalloc(1, sizeof(SCEveFileType));
+
+   filetype->name = "my-custom-filetype";
+   filetype->Init = FiletypeInit;
+   filetype->Deinit = FiletypeDeinit;
+   filetype->ThreadInit = FiletypeThreadInit;
+   filetype->ThreadDeinit = FiletypeThreadDeinit;
+   filetype->Write = FiletypeWrite;
+
+   if (!SCRegisterEveFileType(filetype)) {
+       FatalError("Failed to register EVE filetype");
+   }                                                                                   
+
+Then to use this filetype, set the ``filetype`` in your
+``suricata.yaml`` ``eve-log`` configuration to the name of the
+filetype:
+
+.. code-block:: yaml
+
+   outputs:
+     - eve-log:
+         enabled: true
+         filetype: my-custom-filetype
+
+Examples
+********
+
+Suricata built-ins:
+
+* ``null``: see ``output-eve-null.c`` in the Suricata source code
+* ``syslog``: see ``output-eve-syslog.c`` in the Suricata source code
+
+Plugin:
+
+* The Suricata source code contains an example as a plugin, see:
+  ``examples/plugins/c-json-filetype``.

diff --git a/src/output-eve.h b/src/output-eve.h
index ecc06adaaa1f1038e0b931dc96f316e251eec85a..120105dc4f09d7cdb6a10246cadbd794fe8648e7 100644 (file)
--- a/src/output-eve.h
+++ b/src/output-eve.h
@@ -36,8 +36,7 @@
 
 typedef uint32_t ThreadId;
 
-/**
- * \brief Structure used to define an EVE output file type plugin.
+/** \brief Structure used to define an EVE output file type.
  *
  * EVE filetypes implement an object with a file-like interface and
  * are used to output EVE log records to files, syslog, or