: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 the `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 managenment, easier package maintenance, and a smaller installation footprint. In this section, we'll cover: * <> * <> [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-snmp[logstash-input-snmp] 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] ---- ], @timestamp=#, @generic_trap=6, @enterprise=[1.2.3.4.5.6], @source_ip="127.0.0.1", @agent_addr=#, @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. [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!: