logstash-integration-snmp 4.0.0-java

data/docs/input-snmptrap.asciidoc

@@ -0,0 +1,392 @@
+:integration: snmp
+:plugin: snmptrap
+:type: input
+:default_codec: plain
+
+///////////////////////////////////////////
+START - GENERATED VARIABLES, DO NOT EDIT!
+///////////////////////////////////////////
+:version: %VERSION%
+:release_date: %RELEASE_DATE%
+:changelog_url: %CHANGELOG_URL%
+:include_path: ../../../../logstash/docs/include
+///////////////////////////////////////////
+END - GENERATED VARIABLES, DO NOT EDIT!
+///////////////////////////////////////////
+
+[id="plugins-{type}s-{plugin}"]
+
+=== SNMP trap input plugin
+
+//Uncomment after generated the initial versions of the target file
+//include::{include_path}/plugin_header-integration.asciidoc[]
+
+==== Description
+
+The `logstash-input-snmptrap` plugin reads SNMP trap messages as events.
+
+Resulting `message` field resembles:
+[source,json]
+{"agent_addr":"192.168.1.40", "generic_trap":6, "specific_trap":15511, "enterprise":"1.3.6.1.2.1.1.1", "variable_bindings":{"1.3.6.1.2.1.1.2.0":"test one", "1.3.6.1.2.1.1.1.0":"test two"}, "type":"V1TRAP", "community":"public", "version":1, "timestamp":1500}
+
+.Migrating to `logstash-integration-snmp` from stand-alone `input-snmptrap`
+**** 
+The `logstash-input-snmptrap` plugin is now a component of the `logstash-integration-snmp` plugin. 
+This integrated plugin package provides better alignment in snmp processing, better resource management, 
+easier package maintenance, and a smaller installation footprint. 
+
+For migration information and guidelines, check out the migration guide.
+**** 
+
+// TODO: Add link to migration topic in the integration index. 
+
+[id="plugins-{type}s-{plugin}-ecs"]
+==== Event Metadata and the Elastic Common Schema (ECS)
+
+Because SNMP data has specific field names based on OIDs, we recommend setting a <<plugins-{type}s-{plugin}-target>>.
+The source host field changes based on <<plugins-{type}s-{plugin}-ecs_compatibility>>.
+
+[cols="<l,<l,e,<e"]
+|=======================================================================
+|ECS disabled |ECS v1, v8    |Availability|Description
+|[host]|[host][ip]|Always|IP address of the host e.g. "192.168.1.11"
+|=======================================================================
+
+This plugin also adds the trap PDU metadata to each event.
+The value is stored in the `@metadata` where it can be used by other plugins in the pipeline.
+
+[cols="<l,e,<e"]
+|=======================================================================
+|ECS disabled, v1, v8 |Availability|Description
+|[@metadata][input][snmptrap][pdu][agent_addr]|`SNMPv1`|Network address of the object generating the trap
+|[@metadata][input][snmptrap][pdu][community]|`SNMPv1` `SNMPv2c`|SNMP community
+|[@metadata][input][snmptrap][pdu][enterprise]|`SNMPv1`|Type of object generating the trap
+|[@metadata][input][snmptrap][pdu][error_index]|`SNMPv2c` `SNMPv3`|Provides additional information by identifying
+which variable binding in the list caused the error
+|[@metadata][input][snmptrap][pdu][error_status]|`SNMPv2c` `SNMPv3`|Error status code
+|[@metadata][input][snmptrap][pdu][error_status_text]|`SNMPv2c` `SNMPv3`|Error status code description
+|[@metadata][input][snmptrap][pdu][generic_trap]|`SNMPv1`|Generic trap type
+|[@metadata][input][snmptrap][pdu][request_id]|`SNMPv2c` `SNMPv3`|Request ID
+|[@metadata][input][snmptrap][pdu][specific_trap]|`SNMPv1`|Specific code, presented even if the generic_trap is not enterprise specific
+|[@metadata][input][snmptrap][pdu][timestamp]|`SNMPv1`|Time elapsed between the last (re)initialization of the network entity and the generation of the trap
+|[@metadata][input][snmptrap][pdu][type]|Always|PDU type
+|[@metadata][input][snmptrap][pdu][variable_bindings]|Always|SNMP variable bindings values
+|[@metadata][input][snmptrap][pdu][version]|Always|SNMP version
+|=======================================================================
+
+[id="plugins-{type}s-{plugin}-import-mibs"]
+==== Importing MIBs
+
+This plugin already includes the IETF MIBs (management information bases), and you do not need to import them.
+If you need additional MIBs, you need to important them.  
+Check out "Importing MIBs" for instructions.
+
+// ToDo: Add link to MIBs content after generated file exists.
+
+
+[id="plugins-{type}s-{plugin}-options"]
+==== SNMP Trap 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}-community>> |<<array,array>>|No
+| <<plugins-{type}s-{plugin}-ecs_compatibility>> |<<string,string>>|No
+| <<plugins-{type}s-{plugin}-host>> |<<string,string>>|No
+| <<plugins-{type}s-{plugin}-mib_paths>> |<<path,path>>|No
+| <<plugins-{type}s-{plugin}-oid_mapping_format>> |<<string,string>>, one of `["default", "ruby_snmp", "dotted_string"]`|No
+| <<plugins-{type}s-{plugin}-oid_map_field_values>> |<<boolean,boolean>>|Yes
+| <<plugins-{type}s-{plugin}-oid_path_length>> |<<number,number>>|No
+| <<plugins-{type}s-{plugin}-oid_root_skip>> |<<number,number>>|No
+| <<plugins-{type}s-{plugin}-port>> |<<number,number>>|No
+| <<plugins-{type}s-{plugin}-supported_transports>> |<<string,string>>|No
+| <<plugins-{type}s-{plugin}-supported_versions>> |<<string,string>>|No
+| <<plugins-{type}s-{plugin}-target>> |<<string,string>>|No
+| <<plugins-{type}s-{plugin}-threads>> |<<number,number>>|No
+| <<plugins-{type}s-{plugin}-use_provided_mibs>> |<<boolean,boolean>>|No
+| <<plugins-{type}s-{plugin}-yamlmibdir>> |<<string,string>>|__Deprecated__
+|=======================================================================
+
+==== SNMPv3 Authentication Options
+
+This plugin supports the following SNMPv3 authentication options.
+
+[cols="<,<,<",options="header",]
+|=======================================================================
+|Setting |Input type|Required
+| <<plugins-{type}s-{plugin}-auth_pass>> |<<password,password>>|No
+| <<plugins-{type}s-{plugin}-auth_protocol>> |<<string,string>>, one of `["md5", "sha", "sha2", "hmac128sha224", "hmac192sha256", "hmac256sha384", "hmac384sha512"]`|No
+| <<plugins-{type}s-{plugin}-priv_pass>> |<<password,password>>|No
+| <<plugins-{type}s-{plugin}-priv_protocol>> |<<string,string>>, one of `["des", "3des", "aes", "aes128", "aes192", "aes256"]`|No
+| <<plugins-{type}s-{plugin}-security_level>> |<<string,string>>, one of `["noAuthNoPriv", "authNoPriv", "authPriv"]`|No
+| <<plugins-{type}s-{plugin}-security_name>> |<<string,string>>|No
+|=======================================================================
+
+==== SNMP Trap Input Configuration Options
+
+Also see <<plugins-{type}s-{plugin}-common-options>> for a list of options supported by all
+input plugins.
+
+[id="plugins-{type}s-{plugin}-community"]
+===== `community` 
+
+  * Value type is <<array,array>>
+  * Default value is `["public"]`
+
+The SNMPv1 and SNMPv2c communities to listen for.
+To allow any community, set this config value to empty `community => []`.
+
+Examples
+
+*Listen for `public` and `guest` communities*
+[source,ruby]
+-----
+input {
+  snmptrap {
+    community => ["public", "guest"]
+  }
+}
+-----
+
+*Listen for all communities*
+[source,ruby]
+-----
+input {
+  snmptrap {
+    community => []
+  }
+}
+-----
+
+[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 (fields might be set at the root of the event)
+    ** `v1`, `v8`: avoids field names that might conflict with Elastic Common Schema (for example, the `host` field)
+  * 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)].
+
+[id="plugins-{type}s-{plugin}-host"]
+===== `host` 
+
+  * Value type is <<string,string>>
+  * Default value is `"0.0.0.0"`
+
+The address to listen on.
+
+[id="plugins-{type}s-{plugin}-mib_paths"]
+===== `mib_paths`
+
+  * Value type is <<path,path>>
+  * There is no default value for this setting
+
+The `mib_paths` option specifies the location of one or more imported MIB files.
+The value can be either a dir path containing the imported MIB (`.dic`, `.yaml`) files or a
+file path to a single MIB file.
+
+[id="plugins-{type}s-{plugin}-oid_mapping_format"]
+===== `oid_mapping_format`
+
+  * Value can be any of: `default`, `ruby_snmp`, `dotted_string`
+  * Default value is `"default"`
+
+Defines the mapping textual representation of an OID in the Logstash event:
+* `default` translates every identifier, using the MIBs resolved names, separated by dots. Example:
+`1.3.6.1.2.1.1.2.0` is mapped as `iso.org.dod.internet.mgmt.mib-2.system.sysObjectID.0`
+* `ruby_snmp` produces field names prefixed by the MIBs module name, followed by the latest resolved identifier name and unknowns values. Example:
+`1.3.6.1.2.1.1.2.0` is mapped as `SNMPv2-MIB::sysObjectID.0`.
+* `dotted_string` maps fields using the standard dotted string representation, Example:
+`1.3.6.1.2.1.1.2.0` is mapped as  `1.3.6.1.2.1.1.2.0`
+
+[id="plugins-{type}s-{plugin}-oid_map_field_values"]
+===== `oid_map_field_values`
+
+  * Value type is <<boolean,boolean>>
+  * Default value is `false`
+
+Defines if the Logstash event fields values, which types are `OID`, are mapped using the configured OID textual representation
+set on the <<plugins-{type}s-{plugin}-oid_mapping_format>> option.
+
+[id="plugins-{type}s-{plugin}-oid_root_skip"]
+===== `oid_root_skip`
+
+  * Value type is <<number,number>>
+  * Default value is `0`
+
+The `oid_root_skip` option specifies the number of OID root digits to ignore in the event field name.
+For example, in a numeric OID like "1.3.6.1.2.1.1.1.0" the first 5 digits could be ignored by setting `oid_root_skip => 5`
+which would result in a field name "1.1.1.0". Similarly when a MIB is used an OID such
+"1.3.6.1.2.mib-2.system.sysDescr.0" would become "mib-2.system.sysDescr.0"
+
+[NOTE]
+* You can use this setting or <<plugins-{type}s-{plugin}-oid_path_length>>, but not both at the same time.
+* Use this setting only if <<plugins-{type}s-{plugin}-oid_mapping_format>> is set to `default`.
+
+[id="plugins-{type}s-{plugin}-oid_path_length"]
+===== `oid_path_length`
+
+  * Value type is <<number,number>>
+  * Default value is `0`
+
+The `oid_path_length` option specifies the number of OID root digits to retain in the event field name.
+For example, in a numeric OID like "1.3.6.1.2.1.1.1.0" the last 2 digits could be retained by setting `oid_path_length => 2`
+which would result in a field name "1.0". Similarly when a MIB is used an OID such
+"1.3.6.1.2.mib-2.system.sysDescr.0" would become "sysDescr.0"
+
+[NOTE]
+* You can use this setting or <<plugins-{type}s-{plugin}-oid_root_skip>>, but not both at the same time.
+* Use this setting only if <<plugins-{type}s-{plugin}-oid_mapping_format>> is set to `default`.
+
+[id="plugins-{type}s-{plugin}-port"]
+===== `port` 
+
+  * Value type is <<number,number>>
+  * Default value is `1062`
+
+The port to listen on. Remember that ports less than 1024 (privileged
+ports) may require root to use. hence the default of 1062.
+
+[id="plugins-{type}s-{plugin}-supported_transports"]
+===== `supported_transports`
+  * Value type is <<string,string>>
+  * Allowed values are: `tcp`, `udp`
+  * Default value is `["udp"]`
+
+The supported transport protocols to listen on.
+
+SNMP was originally designed for use with UDP as transport protocol and is the official recommendation.
+TCP is an optional transport mapping and can be enabled if needed. For more details
+on SNMP over TCP, please refer to the https://datatracker.ietf.org/doc/html/rfc3430[RFC-3430].
+
+[id="plugins-{type}s-{plugin}-supported_versions"]
+===== `supported_versions`
+  * Value type is <<string,string>>
+  * Allowed values are: `1`, `2c`, `3`
+  * Default value is `["1", "2c"]`
+
+The supported SNMP protocol versions to listen on.
+SNMP messages for versions that are either unsupported and/or disabled are automatically discarded.
+
+[id="plugins-{type}s-{plugin}-target"]
+===== `target`
+
+  * Value type is <<string,string>>
+  * There is no default value for this setting
+
+The name of the field under which SNMP payloads are assigned.
+If not specified data will be stored in the root of the event.
+
+Setting a target is recommended when <<plugins-{type}s-{plugin}-ecs_compatibility>> is enabled.
+
+[id="plugins-{type}s-{plugin}-threads"]
+===== `threads`
+
+  * Value type is <<number,number>>
+  * Default value is 75% of the number of CPU cores
+
+The number of threads to use for processing the received SNMP trap messages.
+
+[id="plugins-{type}s-{plugin}-use_provided_mibs"]
+===== `use_provided_mibs`
+
+  * Value type is <<boolean,boolean>>
+  * Default value is `true`
+
+This plugin provides all IETF MIBs (management information bases), publicly available in the https://www.ibr.cs.tu-bs.de/projects/libsmi[libsmi] version `0.5.0`.
+When enabled, it automatically loads the bundled MIBs and provides mapping of the numeric OIDs to MIB field names in the resulting event.
+
+[id="plugins-{type}s-{plugin}-yamlmibdir"]
+===== `yamlmibdir` 
+deprecated[4.0.0, Replaced by <<plugins-{type}s-{plugin}-mib_paths>>]
+
+  * Value type is <<string,string>>
+  * There is no default value for this setting.
+
+directory of YAML MIB maps  (same format ruby-snmp uses)
+
+==== SNMPv3 Authentication Options
+
+A **single user** can be configured. Multiple snmptrap input declarations will be needed if multiple SNMPv3 users are required.
+These options are required only if you are using SNMPv3.
+
+[id="plugins-{type}s-{plugin}-auth_pass"]
+===== `auth_pass`
+
+  * Value type is <<password,password>>
+  * There is no default value for this setting
+
+The `auth_pass` option specifies the SNMPv3 authentication passphrase or password.
+
+[id="plugins-{type}s-{plugin}-auth_protocol"]
+===== `auth_protocol`
+
+The `auth_protocol` option specifies the SNMPv3 authentication protocol or type
+
+* Value can be any of: `md5`, `sha`, `sha2`, `hmac128sha224`, `hmac192sha256`, `hmac256sha384`, `hmac384sha512`
+* Note that `sha2` and `hmac192sha256` are equivalent
+* There is no default value for this setting
+
+[id="plugins-{type}s-{plugin}-priv_pass"]
+===== `priv_pass`
+
+  * Value type is <<password,password>>
+  * There is no default value for this setting
+
+The `priv_pass` option specifies the SNMPv3 encryption password.
+
+[id="plugins-{type}s-{plugin}-priv_protocol"]
+===== `priv_protocol`
+
+  * Value can be any of: `des`, `3des`, `aes`, `aes128`, `aes192`, `aes256`
+  * Note that `aes` and `aes128` are equivalent
+  * There is no default value for this setting
+
+The `priv_protocol` option specifies the SNMPv3 privacy/encryption protocol.
+
+[id="plugins-{type}s-{plugin}-security_level"]
+===== `security_level`
+
+  * Value can be any of: `noAuthNoPriv`, `authNoPriv`, `authPriv`
+  * There is no default value for this setting
+
+The `security_level` option specifies the SNMPv3 security level between
+Authentication, No Privacy; Authentication, Privacy; or no Authentication, no Privacy.
+
+[id="plugins-{type}s-{plugin}-security_name"]
+===== `security_name`
+
+  * Value type is <<string,string>>
+  * There is no default value for this setting
+
+The `security_name` option specifies the SNMPv3 security name or user name.
+
+==== Configuration examples
+
+*Specifying SNMPv3 traps settings*
+
+[source,ruby]
+-----
+input {
+  snmptrap {
+    supported_versions => ['3']
+    security_name => "mySecurityName"
+    auth_protocol => "sha"
+    auth_pass => "ShaPassword"
+    priv_protocol => "aes"
+    priv_pass => "AesPasword"
+    security_level => "authPriv"
+  }
+}
+-----
+
+[id="plugins-{type}s-{plugin}-common-options"]
+include::{include_path}/{type}.asciidoc[]
+
+:default_codec!: