:plugin: snmp
:type: integration
:no_codec:

///////////////////////////////////////////
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 Integration Plugin

include::{include_path}/plugin_header.asciidoc[]

.Announcing the new SNMP integration plugin 
****
The new `logstash-integration-snmp` plugin is available and bundled with {ls} 8.15.0 (and later) by default.
This plugin combines our classic `logstash-input-snmp` and `logstash-input-snmptrap` plugins into a single Ruby gem at v4.0.0 and later.
Earlier versions of the stand-alone plugins that were bundled with {ls} by default will be replaced by the 4.0.0+ version contained in this new integration.

IMPORTANT: Before you upgrade to {ls} 8.15.0 that includes this new integration by default, be aware of {logstash-ref}/plugins-integrations-snmp.html#plugins-integrations-snmp-migration[behavioral and mapping differences] between stand-alone plugins and the new versions included in `integration-snmp`.
If you need to maintain current mappings for the `input-snmptrap` plugin, you have options to {logstash-ref}/plugins-integrations-snmp.html#plugins-integrations-snmp-input-snmptrap-compat[preserve existing behavior].
****

==== Description

The SNMP integration plugin includes:

* link:{logstash-ref}/plugins-inputs-snmp.html[SNMP input plugin]
* link:{logstash-ref}/plugins-inputs-snmptrap.html[Snmptrap input plugin]

The new `logstash-integration-snmp` plugin combines the 
`logstash-input-snmp` and `logstash-input-snmptrap` plugins into one integrated plugin that encompasses
the capabilities of both. 
This integrated plugin package provides better alignment in snmp processing, better resource management, 
easier package maintenance, and a smaller installation footprint. 

In this section, we'll cover:

* <<plugins-{type}s-{plugin}-migration>>
* <<plugins-{type}s-{plugin}-import-mibs>>

[id="plugins-{type}s-{plugin}-migration"]
==== Migrating to `logstash-integration-snmp` from individual plugins

You'll retain and expand the functionality of existing stand-alone plugins, but in a more compact, integrated package. 
In this section, we'll note mapping and behavioral changes, and explain how to preserve current behavior if needed.

[id="plugins-{type}s-{plugin}-migration-input-snmp"]
===== Migration notes: `logstash-input-snmp` 

As a component of the new `logstash-integration-snmp` plugin, the `logstash-input-snmp` plugin offers the same 
capabilities as the stand-alone https://github.com/logstash-plugins/logstash-input-snmp[logstash-input-snmp]. 

You might need to address some behavior changes depending on the use-case and how the ingested data is being handled through the pipeline.


[id="plugins-{type}s-{plugin}-input-snmp-mapping"]
====== Changes to mapping and error logging: `logstash-input-snmp`

* *No such instance errors* are mapped as `error: no such instance currently exists at this OID string` instead of `noSuchInstance`.
* *No such object errors* are mapped as `error: no such object currently exists at this OID string` instead of `noSuchObject`.
* *End of MIB view errors* are mapped as `error: end of MIB view` instead of `endOfMibView`.
* An *unknown variable type* falls back to the `string` representation instead of logging an error as it did in with the stand-alone `logstash-input-snmp`.
This change should not affect existing pipelines, unless they have custom error handlers that rely on specific error messages.

[id="plugins-{type}s-{plugin}-migration-input-snmptrap"]
===== Migration notes: `logstash-input-snmptrap`

As a component of the new `logstash-integration-snmp` plugin, the `logstash-input-snmptrap` plugin offers _almost the same 
capabilities_ as the stand-alone https://github.com/logstash-plugins/logstash-input-snmptrap[logstash-input-snmptrap] plugin. 

You might need to address some behavior changes depending on your use case and how the ingested data is being handled through the pipeline.

[id="plugins-{type}s-{plugin}-input-snmptrap-mapping"]
====== Changes to mapping and error logging: `logstash-input-snmptrap`

* The *PDU variable bindings* are mapped into the {ls} event using the defined data type. 
  By default, the stand-alone `logstash-input-snmptrap` plugin converts all of the data to `string`, ignoring the original type. 
  If this behavior is not what you want, you can use a filter to retain the original type.
* *SNMP `TimeTicks` variables* are mapped as `Long` timestamps instead of formatted date string (`%d days, %02d:%02d:%02d.%02d`).
* *`null` variables values* are mapped using the string `null` instead of `Null` (upper-case N).
* *No such instance errors* are mapped as `error: no such instance currently exists at this OID string` instead of `noSuchInstance`.
* *No such object errors* are mapped as `error: no such object currently exists at this OID string` instead of `noSuchObject`.
* *End of MIB view errors* are mapped as `error: end of MIB view` instead of `endOfMibView`.
* The previous generation (stand-alone) input-snmptrap plugin formatted the *`message` field* as
a ruby-snmp `SNMP::SNMPv1_Trap` object representation.  
+
[source,sh]
----
<SNMP::SNMPv1_Trap:0x6f1a7a4 @varbind_list=[#<SNMP::VarBind:0x2d7bcd8f @value="teststring", @name=[1.11.12.13.14.15]>], @timestamp=#<SNMP::TimeTicks:0x1af47e9d @value=55>, @generic_trap=6,  @enterprise=[1.2.3.4.5.6], @source_ip="127.0.0.1", @agent_addr=#<SNMP::IpAddress:0x29a4833e @value="test">, @specific_trap=99>
----
+
The new integrated `input-snmptrap` plugin uses JSON to format *`message` field*.
+
[source,json]
----
{"error_index":0, "variable_bindings":{"1.3.6.1.6.3.1.1.4.1.0":"SNMPv2-MIB::coldStart", "1.3.6.1.2.1.1.3.0":0}, "error_status":0, "type":"TRAP", "error_status_text":"Success", "community":"public", "version":"2c", "request_id":1436216872}
----

// ToDo: Add more details wrt PDU variable binding.  Which filter? Add sample config? 

[id="plugins-{type}s-{plugin}-input-snmptrap-compat"]
====== Maintain maximum compatibility with previous implementation

If needed, you can configure the new `logstash-integration-snmp` plugin to maintain maximum compatibility with the previous (stand-alone) 
version of the https://github.com/logstash-plugins/logstash-input-snmp[input-snmp] plugin.

[source,ruby]
----
input {
   snmptrap {
    use_provided_mibs => false
    oid_mapping_format => 'ruby_snmp'
    oid_map_field_values => true
   }
}
----

// ToDo: Any considerations that we should point out? 

[id="plugins-{type}s-{plugin}-import-mibs"]
==== Importing MIBs

The SNMP plugins already include the IETF MIBs (management information bases) and these do not need to be imported.
To disable the bundled MIBs set the `use_provided_mibs` option to `false`.

Any other MIB will need to be manually imported to provide mapping of the numeric OIDs to MIB field names in the resulting event.

To import a MIB, the OSS https://www.ibr.cs.tu-bs.de/projects/libsmi/[libsmi library] is required.
libsmi is available and installable on most operating systems.

To import a MIB, you need to first convert the ASN.1 MIB file into a `.dic` file using the libsmi `smidump` command line utility.

*Example (using `RFC1213-MIB` file)*

[source,sh]
-----
$ smidump --level=1 -k -f python RFC1213-MIB > RFC1213-MIB.dic
-----

Note that the resulting file as output by `smidump` must have the `.dic` extension.

When `mib_paths` is configured, note that the complete set of all MIBs required must be included here. Any conflicting MIBs with defaults will
prefer the default, not the MIB configured on the `mib_paths`. The tightest control and maximal compatability can be acheived by ensuring that
`use_provided_mibs` is set to `false` and the complete set of MIBs are included in files listed in `mib_paths`. The defaults from the old implementation
can be found in the https://github.com/ruby-snmp/ruby-snmp/tree/master/data/ruby/snmp/mibs[ruby-snmp github repository].

[id="plugins-{type}s-{plugin}-locate-mibs"]
===== Preventing a `failed to locate MIB module` error

The `smidump` function looks for MIB dependencies in its pre-configured paths list.
To avoid the `failed to locate MIB module` error, you may need to provide the MIBs locations in your particular environment.

The recommended ways to provide the additional path configuration are:

* an environment variable, or
* a config file to provide the additional path configuration.

See the "MODULE LOCATIONS" section of the https://www.ibr.cs.tu-bs.de/projects/libsmi/smi_config.html#MODULE%20LOCATIONS[smi_config documentation] for more information.

[id="plugins-{type}s-{plugin}-env-var"]
===== Option 1: Use an environment variable

Set the `SMIPATH` env var with the path to your MIBs.
Be sure to include a prepended colon (`:`) for the path.

[source,sh]
-----
$ SMIPATH=":/path/to/mibs/" smidump -k -f python CISCO-PROCESS-MIB.mib > CISCO-PROCESS-MIB_my.dic <1>
-----
<1> Notice the colon that precedes the path definition.

[id="plugins-{type}s-{plugin}-mib-config"]
===== Option 2: Provide a configuration file

The other approach is to create a configuration file with the `path` option. For example, you could create a file called `smi.conf`:

[source,sh]
-----
path :/path/to/mibs/
-----

And use the config with smidump:

[source,sh]
-----
$ smidump -c smi.conf -k -f python CISCO-PROCESS-MIB.mib > CISCO-PROCESS-MIB_my.dic
-----

:no_codec!:
