From: Eric Leblond <eric@regit.org>
Date: Thu, 26 Oct 2017 08:31:46 +0000 (+0200)
Subject: doc: documentation update on metadata
X-Git-Tag: suricata-4.1.0-beta1~239
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=72c8cd67d5414e919de03693a116f027b82fb66f;p=thirdparty%2Fsuricata.git

doc: documentation update on metadata
---

diff --git a/doc/userguide/output/eve/eve-json-output.rst b/doc/userguide/output/eve/eve-json-output.rst
index 8574d7c44e..936027ee8e 100644
--- a/doc/userguide/output/eve/eve-json-output.rst
+++ b/doc/userguide/output/eve/eve-json-output.rst
@@ -76,6 +76,18 @@ layer metadata to output on a per application layer basis ::
 The `vars` will enable dumping of a set of key/value based on flowbits and other vars
 such as named groups in regular expression.
 
+It is also possible to log key/value pairs defined by the metadata keyword on rule. To
+do so you need to set `enabled` to yes under `rule-metadata` ::
+
+        - alert:
+            metadata: yes              # add L7/applayer fields, flowbit and other vars to the alert
+            rule-metadata:             # dumping of key/value pairs defined by metadata keyword of rule
+              enabled: yes              # set to yes to enable
+              output-array: no         # output value of key as an array
+              array-keys: [tag]        # comma separated array of keys to output as array
+
+This will add a `alert.metadata` object in the alert event.
+
 DNS
 ~~~
 
diff --git a/doc/userguide/partials/eve-log.yaml b/doc/userguide/partials/eve-log.yaml
index ee6436cf97..98e4e8bf8b 100644
--- a/doc/userguide/partials/eve-log.yaml
+++ b/doc/userguide/partials/eve-log.yaml
@@ -54,6 +54,11 @@ outputs:
             # "tag" keyword.
             tagged-packets: yes
 
+            rule-metadata:             # dumping of key/value pairs defined by metadata keyword of rule
+              enabled: no              # set to yes to enable
+              output-array: no         # output value of key as an array
+              array-keys: [tag]        # comma separated array of keys to output as array
+
             # HTTP X-Forwarded-For support by adding an extra field or overwriting
             # the source or destination IP address (depending on flow direction)
             # with the one reported in the X-Forwarded-For HTTP header. This is
diff --git a/doc/userguide/rules/meta.rst b/doc/userguide/rules/meta.rst
index bdcf733ea6..27be92b2db 100644
--- a/doc/userguide/rules/meta.rst
+++ b/doc/userguide/rules/meta.rst
@@ -168,10 +168,14 @@ format of priority is::
 
 metadata
 --------
-Suricata ignores the words behind meta data.  Suricata supports this
-keyword because it is part of the signature language.  The format is::
 
-  metadata:......;
+The meatadata keyword allows additional, non-functional information to
+be added to the signature. While the format is free-form, it is
+recommended to stick to key, value pairs as Suricata can include these
+in eve alerts. The format is::
+
+  metadata: key value;
+  metadata: key value, key value;
 
 target
 ------