diff options
Diffstat (limited to '')
| -rw-r--r-- | src/go/collectors/go.d.plugin/modules/snmp/metadata.yaml | 398 |
1 files changed, 398 insertions, 0 deletions
diff --git a/src/go/collectors/go.d.plugin/modules/snmp/metadata.yaml b/src/go/collectors/go.d.plugin/modules/snmp/metadata.yaml new file mode 100644 index 000000000..a35b3190d --- /dev/null +++ b/src/go/collectors/go.d.plugin/modules/snmp/metadata.yaml @@ -0,0 +1,398 @@ +plugin_name: go.d.plugin +modules: + - meta: + id: collector-go.d.plugin-snmp + plugin_name: go.d.plugin + module_name: snmp + monitored_instance: + name: SNMP devices + link: "" + icon_filename: snmp.png + categories: + - data-collection.generic-data-collection + keywords: + - snmp + related_resources: + integrations: + list: [] + info_provided_to_referring_integrations: + description: "" + most_popular: true + overview: + data_collection: + metrics_description: | + This collector monitors any SNMP devices and uses the [gosnmp](https://github.com/gosnmp/gosnmp) package. + + It supports: + + - all SNMP versions: SNMPv1, SNMPv2c and SNMPv3. + - any number of SNMP devices. + - each SNMP device can be used to collect data for any number of charts. + - each chart may have any number of dimensions. + - each SNMP device may have a different update frequency. + - each SNMP device will accept one or more batches to report values (you can set `max_request_size` per SNMP server, to control the size of batches). + + Keep in mind that many SNMP switches and routers are very slow. They may not be able to report values per second. + `go.d.plugin` reports the time it took for the SNMP device to respond when executed in the debug mode. + + Also, if many SNMP clients are used on the same SNMP device at the same time, values may be skipped. + This is a problem of the SNMP device, not this collector. In this case, consider reducing the frequency of data collection (increasing `update_every`). + method_description: "" + supported_platforms: + include: [] + exclude: [] + multi_instance: true + additional_permissions: + description: "" + default_behavior: + auto_detection: + description: "" + limits: + description: "" + performance_impact: + description: "" + setup: + prerequisites: + list: + - title: Find OIDs + description: | + Use `snmpwalk`, like this: + + ```sh + snmpwalk -t 20 -O fn -v 2c -c public 192.0.2.1 + ``` + + - `-t 20` is the timeout in seconds. + - `-O fn` will display full OIDs in numeric format. + - `-v 2c` is the SNMP version. + - `-c public` is the SNMP community. + - `192.0.2.1` is the SNMP device. + configuration: + file: + name: go.d/snmp.conf + options: + description: | + The following options can be defined globally: update_every, autodetection_retry. + folding: + title: Config options + enabled: true + list: + - name: update_every + description: Data collection frequency. + default_value: 1 + required: false + - name: autodetection_retry + description: Recheck interval in seconds. Zero means no recheck will be scheduled. + default_value: 0 + required: false + - name: hostname + description: Target ipv4 address. + default_value: 127.0.0.1 + required: true + - name: community + description: SNMPv1/2 community string. + default_value: public + required: false + - name: options.version + description: "SNMP version. Available versions: 1, 2, 3." + default_value: 2 + required: false + - name: options.port + description: Target port. + default_value: 161 + required: false + - name: options.retries + description: Retries to attempt. + default_value: 1 + required: false + - name: options.timeout + description: SNMP request/response timeout. + default_value: 10 + required: false + - name: options.max_request_size + description: Maximum number of OIDs allowed in one one SNMP request. + default_value: 60 + required: false + - name: user.name + description: SNMPv3 user name. + default_value: "" + required: false + - name: user.name + description: Security level of SNMPv3 messages. + default_value: "" + required: false + - name: user.auth_proto + description: Security level of SNMPv3 messages. + default_value: "" + required: false + detailed_description: | + The security of an SNMPv3 message as per RFC 3414 (`user.level`): + + | String value | Int value | Description | + |:------------:|:---------:|------------------------------------------| + | none | 1 | no message authentication or encryption | + | authNoPriv | 2 | message authentication and no encryption | + | authPriv | 3 | message authentication and encryption | + - name: user.name + description: Authentication protocol for SNMPv3 messages. + default_value: "" + required: false + detailed_description: | + The digest algorithm for SNMPv3 messages that require authentication (`user.auth_proto`): + + | String value | Int value | Description | + |:------------:|:---------:|-------------------------------------------| + | none | 1 | no message authentication | + | md5 | 2 | MD5 message authentication (HMAC-MD5-96) | + | sha | 3 | SHA message authentication (HMAC-SHA-96) | + | sha224 | 4 | SHA message authentication (HMAC-SHA-224) | + | sha256 | 5 | SHA message authentication (HMAC-SHA-256) | + | sha384 | 6 | SHA message authentication (HMAC-SHA-384) | + | sha512 | 7 | SHA message authentication (HMAC-SHA-512) | + - name: user.auth_key + description: Authentication protocol pass phrase. + default_value: "" + required: false + - name: user.priv_proto + description: Privacy protocol for SNMPv3 messages. + default_value: "" + required: false + detailed_description: | + The encryption algorithm for SNMPv3 messages that require privacy (`user.priv_proto`): + + | String value | Int value | Description | + |:------------:|:---------:|-------------------------------------------------------------------------| + | none | 1 | no message encryption | + | des | 2 | ES encryption (CBC-DES) | + | aes | 3 | 128-bit AES encryption (CFB-AES-128) | + | aes192 | 4 | 192-bit AES encryption (CFB-AES-192) with "Blumenthal" key localization | + | aes256 | 5 | 256-bit AES encryption (CFB-AES-256) with "Blumenthal" key localization | + | aes192c | 6 | 192-bit AES encryption (CFB-AES-192) with "Reeder" key localization | + | aes256c | 7 | 256-bit AES encryption (CFB-AES-256) with "Reeder" key localization | + - name: user.priv_key + description: Privacy protocol pass phrase. + default_value: "" + required: false + - name: charts + description: List of charts. + default_value: "[]" + required: true + - name: charts.id + description: Chart ID. Used to uniquely identify the chart. + default_value: "" + required: true + - name: charts.title + description: Chart title. + default_value: "Untitled chart" + required: false + - name: charts.units + description: Chart units. + default_value: num + required: false + - name: charts.family + description: Chart family. + default_value: charts.id + required: false + - name: charts.type + description: Chart type (line, area, stacked). + default_value: line + required: false + - name: charts.priority + description: Chart priority. + default_value: 70000 + required: false + - name: charts.multiply_range + description: Used when you need to define many charts using incremental OIDs. + default_value: "[]" + required: false + - name: charts.dimensions + description: List of chart dimensions. + default_value: "[]" + required: true + - name: charts.dimensions.oid + description: Collected metric OID. + default_value: "" + required: true + - name: charts.dimensions.name + description: Dimension name. + default_value: "" + required: true + - name: charts.dimensions.algorithm + description: Dimension algorithm (absolute, incremental). + default_value: absolute + required: false + - name: charts.dimensions.multiplier + description: Collected value multiplier, applied to convert it properly to units. + default_value: 1 + required: false + - name: charts.dimensions.divisor + description: Collected value divisor, applied to convert it properly to units. + default_value: 1 + required: false + examples: + folding: + title: Config + enabled: true + list: + - name: SNMPv1/2 + description: | + In this example: + + - the SNMP device is `192.0.2.1`. + - the SNMP version is `2`. + - the SNMP community is `public`. + - we will update the values every 10 seconds. + - we define 2 charts `bandwidth_port1` and `bandwidth_port2`, each having 2 dimensions: `in` and `out`. + + > **SNMPv1**: just set `options.version` to 1. + > **Note**: the algorithm chosen is `incremental`, because the collected values show the total number of bytes transferred, which we need to transform into kbps. To chart gauges (e.g. temperature), use `absolute` instead. + config: | + jobs: + - name: switch + update_every: 10 + hostname: 192.0.2.1 + community: public + options: + version: 2 + charts: + - id: "bandwidth_port1" + title: "Switch Bandwidth for port 1" + units: "kilobits/s" + type: "area" + family: "ports" + dimensions: + - name: "in" + oid: "1.3.6.1.2.1.2.2.1.10.1" + algorithm: "incremental" + multiplier: 8 + divisor: 1000 + - name: "out" + oid: "1.3.6.1.2.1.2.2.1.16.1" + multiplier: -8 + divisor: 1000 + - id: "bandwidth_port2" + title: "Switch Bandwidth for port 2" + units: "kilobits/s" + type: "area" + family: "ports" + dimensions: + - name: "in" + oid: "1.3.6.1.2.1.2.2.1.10.2" + algorithm: "incremental" + multiplier: 8 + divisor: 1000 + - name: "out" + oid: "1.3.6.1.2.1.2.2.1.16.2" + multiplier: -8 + divisor: 1000 + - name: SNMPv3 + description: | + To use SNMPv3: + + - use `user` instead of `community`. + - set `options.version` to 3. + + The rest of the configuration is the same as in the SNMPv1/2 example. + config: | + jobs: + - name: switch + update_every: 10 + hostname: 192.0.2.1 + options: + version: 3 + user: + name: username + level: authPriv + auth_proto: sha256 + auth_key: auth_protocol_passphrase + priv_proto: aes256 + priv_key: priv_protocol_passphrase + - name: Multiply range + description: | + If you need to define many charts using incremental OIDs, you can use the `charts.multiply_range` option. + + This is like the SNMPv1/2 example, but the option will multiply the current chart from 1 to 24 inclusive, producing 24 charts in total for the 24 ports of the switch `192.0.2.1`. + + Each of the 24 new charts will have its id (1-24) appended at: + + - its chart unique `id`, i.e. `bandwidth_port_1` to `bandwidth_port_24`. + - its title, i.e. `Switch Bandwidth for port 1` to `Switch Bandwidth for port 24`. + - its `oid` (for all dimensions), i.e. dimension in will be `1.3.6.1.2.1.2.2.1.10.1` to `1.3.6.1.2.1.2.2.1.10.24`. + - its `priority` will be incremented for each chart so that the charts will appear on the dashboard in this order. + config: | + jobs: + - name: switch + update_every: 10 + hostname: "192.0.2.1" + community: public + options: + version: 2 + charts: + - id: "bandwidth_port" + title: "Switch Bandwidth for port" + units: "kilobits/s" + type: "area" + family: "ports" + multiply_range: [1, 24] + dimensions: + - name: "in" + oid: "1.3.6.1.2.1.2.2.1.10" + algorithm: "incremental" + multiplier: 8 + divisor: 1000 + - name: "out" + oid: "1.3.6.1.2.1.2.2.1.16" + multiplier: -8 + divisor: 1000 + - name: Multiple devices with a common configuration + description: | + YAML supports [anchors](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases). + The `&` defines and names an anchor, and the `*` uses it. `<<: *anchor` means, inject the anchor, then extend. We can use anchors to share the common configuration for multiple devices. + + The following example: + + - adds an `anchor` to the first job. + - injects (copies) the first job configuration to the second and updates `name` and `hostname` parameters. + - injects (copies) the first job configuration to the third and updates `name` and `hostname` parameters. + config: | + jobs: + - &anchor + name: switch + update_every: 10 + hostname: "192.0.2.1" + community: public + options: + version: 2 + charts: + - id: "bandwidth_port1" + title: "Switch Bandwidth for port 1" + units: "kilobits/s" + type: "area" + family: "ports" + dimensions: + - name: "in" + oid: "1.3.6.1.2.1.2.2.1.10.1" + algorithm: "incremental" + multiplier: 8 + divisor: 1000 + - name: "out" + oid: "1.3.6.1.2.1.2.2.1.16.1" + multiplier: -8 + divisor: 1000 + - <<: *anchor + name: switch2 + hostname: "192.0.2.2" + - <<: *anchor + name: switch3 + hostname: "192.0.2.3" + troubleshooting: + problems: + list: [] + alerts: [] + metrics: + folding: + title: Metrics + enabled: false + description: The metrics that will be collected are defined in the configuration file. + availability: [] + scopes: [] |