summaryrefslogtreecommitdiffstats
path: root/source/configuration/modules/imbatchreport.rst
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--source/configuration/modules/imbatchreport.rst222
1 files changed, 222 insertions, 0 deletions
diff --git a/source/configuration/modules/imbatchreport.rst b/source/configuration/modules/imbatchreport.rst
new file mode 100644
index 0000000..439eae4
--- /dev/null
+++ b/source/configuration/modules/imbatchreport.rst
@@ -0,0 +1,222 @@
+****************************************
+imbatchreport: Batch report input module
+****************************************
+
+================ ==============================================================
+**Module Name:** **imbatchreport**
+**Authors:** Jean-Philippe Hilaire <jean-philippe.hilaire@pmu.fr> & Philippe Duveau <philippe.duveau@free.fr>
+================ ==============================================================
+
+
+Purpose
+=======
+
+This module allows rsyslog to manage batch reports.
+
+Batch are programs launched successively to process a large amount of
+information. These programs are organized in stages with passing conditions.
+The batch ends with a global execution summary. Each Batch produces a single
+result file usually named with the name of the batch and its date of execution.
+
+Those files have sense only when they are complete in one log. When the file is
+collected it becomes useless and, as a statefile, should be deleted or renamed.
+
+This module handle those characteristics :
+
+- reads the complete file,
+
+- extracts the structured data from the file (see managing structured data),
+
+- transmit the message to output module(s),
+
+- action is applied to the file to flag it as treated. Two different actions can be applied: delete or rename the file.
+
+If the file is too large to be handled in the message size defined by rsyslog,
+the file is renamed as a "rejected file". See \$maxMessageSize
+
+**Managing structured data**
+
+As part of the batch summary, the structure data can be provided in the batch
+report file as the last part of the file.
+
+The last non-space char has to be a closing brace ']' then all chars between
+this char up to the closest opening brace '[' are computed as structured data.
+
+All the structured data has to be contained in the last 150 chars of the file.
+
+In general, structured data should contain the batch name (program) and the
+start timestamp. Those two values can be extract to fill rsyslog message
+attributes.
+
+Compile
+=======
+
+To successfully compile imbatchreport module.
+
+ ./configure --enable-imbatchreport ...
+
+Configuration Parameters
+========================
+
+Action Parameters
+-----------------
+
+Reports
+^^^^^^^
+
+.. csv-table::
+ :header: "type", "mandatory", "format", "default"
+ :widths: auto
+ :class: parameter-table
+
+ "string", "yes", "glob definition",
+
+Glob definition used to identify reports to manage.
+
+Tag
+^^^
+
+.. csv-table::
+ :header: "type", "mandatory", "format", "default"
+ :widths: auto
+ :class: parameter-table
+
+ "string", "yes", ,"none"
+
+The tag to be assigned to messages read from this file. If you would like to
+see the colon after the tag, you need to include it when you assign a tag
+value, like so: ``tag="myTagValue:"``.
+
+Facility
+^^^^^^^^
+
+.. csv-table::
+ :header: "type", "mandatory", "format", "default"
+ :widths: auto
+ :class: parameter-table
+
+ "string", "no", "facility\|number", "local0"
+
+The syslog facility to be assigned to messages read from this file. Can be
+specified in textual form (e.g. ``local0``, ``local1``, ...) or as numbers (e.g.
+16 for ``local0``). Textual form is suggested.
+
+Severity
+^^^^^^^^
+
+.. csv-table::
+ :header: "type", "mandatory", "format", "default"
+ :widths: auto
+ :class: parameter-table
+
+ "string", "no", "severity\|number", "notice"
+
+The syslog severity to be assigned to lines read. Can be specified
+in textual form (e.g. ``info``, ``warning``, ...) or as numbers (e.g. 6
+for ``info``). Textual form is suggested.
+
+DeduplicateSpaces
+^^^^^^^^^^^^^^^^^
+
+.. csv-table::
+ :header: "type", "mandatory", "format", "default"
+ :widths: auto
+ :class: parameter-table
+
+ "binary", "no", "", "on"
+
+The parameter modify the way consecutive spaces like chars are managed.
+When it is setted to "on", consecutive spaces like chars are reduced to a single one
+and trailing space like chars are suppressed.
+
+Delete
+^^^^^^
+
+.. csv-table::
+ :header: "type", "mandatory", "format", "default"
+ :widths: auto
+ :class: parameter-table
+
+ "string", "no", "<regex> <reject>",
+
+This parameter informs the module to delete the report to flag it as treated.
+If the file is too large (or failed to be removed) it is renamed using the
+<regex> to identify part of the file name that has to be replaced it by
+<reject>. See Examples
+
+Rename
+^^^^^^
+
+.. csv-table::
+ :header: "type", "mandatory", "format", "default"
+ :widths: auto
+ :class: parameter-table
+
+ "string", "no", "<regex> <sent> <reject>",
+
+This parameter informs the module to rename the report to flag it as treated.
+The file is renamed using the <regex> to identify part of the file name that
+has to be replaced it:
+
+- by <rename> if the file was successfully treated,
+
+- by <reject> if the file is too large to be sent.
+
+See #Examples
+
+Programkey
+^^^^^^^^^^
+
+.. csv-table::
+ :header: "type", "mandatory", "format", "default"
+ :widths: auto
+ :class: parameter-table
+
+ "string", "no", ,
+
+The attribute in structured data which contains the rsyslog APPNAME.
+This attribute has to be a String between double quotes (").
+
+Timestampkey
+^^^^^^^^^^^^
+
+.. csv-table::
+ :header: "type", "mandatory", "format", "default"
+ :widths: auto
+ :class: parameter-table
+
+ "string", "no", ,
+
+The attribute in structured data which contains the rsyslog TIMESTAMP.
+This attribute has to be a Number (Unix TimeStamp).
+
+Examples
+========
+
+The example show the delete action. All files corresponding to
+"/test/\*.ok" will be treated as batch reports and will be deleted
+on success or renamed from <file>.ok to <file>.rejected in other
+cases.
+
+.. code-block:: none
+
+ module(load="imbatchreport")
+ input(type="imbatchreport" reports="/test/\*.ok"
+ ruleset="myruleset" tag="batch"
+ delete=".ok$ .rejected"
+ programkey="SHELL" timestampkey="START"
+ )
+
+The example show the rename action. All files corresponding to
+"/test/\*.ok" will be treated as batch reports and will be renamed
+from <file>.ok to <file>.sent on success or
+renamed from <file>.ok to <file>.rejected in other cases.
+
+.. code-block:: none
+
+ module(load="imbatchreport")
+ input(type="imbatchreport" reports="/test/\*.ok"
+ ruleset="myruleset" tag="batch"
+ rename=".ok$ .sent .rejected"
+ programkey="SHELL" timestampkey="START"
+ )