index.asciidoc in logstash-input-imap-3.2.0

- old
+ new

@@ -24,24 +24,36 @@
 Read mails from IMAP server
 
 Periodically scan an IMAP folder (`INBOX` by default) and move any read messages
 to the trash.
 
+[id="plugins-{type}s-{plugin}-ecs"]
+==== Compatibility with the Elastic Common Schema (ECS)
+
+The plugin includes sensible defaults that change based on <<plugins-{type}s-{plugin}-ecs_compatibility,ECS compatibility mode>>.
+When ECS compatibility is disabled, mail headers and attachments are targeted at the root level.
+When targeting an ECS version, headers and attachments target `@metadata` sub-fields unless configured otherwise in order
+to avoid conflict with ECS fields.
+See <<plugins-{type}s-{plugin}-headers_target>>, and <<plugins-{type}s-{plugin}-attachments_target>>.
+
 [id="plugins-{type}s-{plugin}-options"]
 ==== Imap Input Configuration Options
 
 This plugin supports the following configuration options plus the <<plugins-{type}s-{plugin}-common-options>> described later.
 
 [cols="<,<,<",options="header",]
 |=======================================================================
 |Setting |Input type|Required
+| <<plugins-{type}s-{plugin}-attachments_target>> |<<string,string>>|No
 | <<plugins-{type}s-{plugin}-check_interval>> |<<number,number>>|No
 | <<plugins-{type}s-{plugin}-content_type>> |<<string,string>>|No
 | <<plugins-{type}s-{plugin}-delete>> |<<boolean,boolean>>|No
+| <<plugins-{type}s-{plugin}-ecs_compatibility>> |<<string,string>>|No
 | <<plugins-{type}s-{plugin}-expunge>> |<<boolean,boolean>>|No
 | <<plugins-{type}s-{plugin}-fetch_count>> |<<number,number>>|No
 | <<plugins-{type}s-{plugin}-folder>> |<<string,string>>|No
+| <<plugins-{type}s-{plugin}-headers_target>> |<<string,string>>|No
 | <<plugins-{type}s-{plugin}-host>> |<<string,string>>|Yes
 | <<plugins-{type}s-{plugin}-lowercase_headers>> |<<boolean,boolean>>|No
 | <<plugins-{type}s-{plugin}-password>> |<<password,password>>|Yes
 | <<plugins-{type}s-{plugin}-port>> |<<number,number>>|No
 | <<plugins-{type}s-{plugin}-save_attachments>> |<<boolean,boolean>>|No
@@ -56,10 +68,20 @@
 Also see <<plugins-{type}s-{plugin}-common-options>> for a list of options supported by all
 input plugins.
 
 &nbsp;
 
+[id="plugins-{type}s-{plugin}-attachments_target"]
+===== `attachments_target`
+
+  * Value type is <<string,string>>
+  * Default value depends on whether <<plugins-{type}s-{plugin}-ecs_compatibility>> is enabled:
+    ** ECS Compatibility disabled: `"[attachments]"`
+    ** ECS Compatibility enabled: `"[@metadata][input][imap][attachments]"
+
+The name of the field under which mail attachments information will be added, if <<plugins-{type}s-{plugin}-save_attachments>> is set.
+
 [id="plugins-{type}s-{plugin}-check_interval"]
 ===== `check_interval`
 
   * Value type is <<number,number>>
   * Default value is `300`
@@ -70,21 +92,35 @@
 ===== `content_type`
 
   * Value type is <<string,string>>
   * Default value is `"text/plain"`
 
-For multipart messages, use the first part that has this
-content-type as the event message.
+For multipart messages, use the first part that has this content-type as the event message.
 
 [id="plugins-{type}s-{plugin}-delete"]
 ===== `delete`
 
   * Value type is <<boolean,boolean>>
   * Default value is `false`
 
 
 
+[id="plugins-{type}s-{plugin}-ecs_compatibility"]
+===== `ecs_compatibility`
+
+  * Value type is <<string,string>>
+  * Supported values are:
+    ** `disabled`: does not use ECS-compatible field names (for example, `From` header field is added to the event)
+    ** `v1`, `v8`: avoids field names that might conflict with Elastic Common Schema (for example, the `From` header is added as metadata)
+  * Default value depends on which version of Logstash is running:
+    ** When Logstash provides a `pipeline.ecs_compatibility` setting, its value is used as the default
+    ** Otherwise, the default value is `disabled`.
+
+Controls this plugin's compatibility with the {ecs-ref}[Elastic Common Schema (ECS)].
+The value of this setting affects the _default_ value of <<plugins-{type}s-{plugin}-headers_target>> and
+<<plugins-{type}s-{plugin}-attachments_target>>.
+
 [id="plugins-{type}s-{plugin}-expunge"]
 ===== `expunge`
 
   * Value type is <<boolean,boolean>>
   * Default value is `false`
@@ -104,9 +140,22 @@
 
   * Value type is <<string,string>>
   * Default value is `"INBOX"`
 
 
+
+[id="plugins-{type}s-{plugin}-headers_target"]
+===== `headers_target`
+
+  * Value type is <<string,string>>
+  * Default value depends on whether <<plugins-{type}s-{plugin}-ecs_compatibility>> is enabled:
+    ** ECS Compatibility disabled: no default value (for example, the subject header is stored under the `"subject"` name)
+    ** ECS Compatibility enabled: `"[@metadata][input][imap][headers]"`
+
+The name of the field under which mail headers will be added.
+
+Setting `headers_target => ''` skips headers processing and no header is added to the event.
+Except the date header, if present, which is always used as the event's `@timestamp`.
 
 [id="plugins-{type}s-{plugin}-host"]
 ===== `host`
 
   * This is a required setting.