github.com/netdata/go.d.plugin@v0.58.1/modules/snmp/metadata.yaml (about) 1 plugin_name: go.d.plugin 2 modules: 3 - meta: 4 id: collector-go.d.plugin-snmp 5 plugin_name: go.d.plugin 6 module_name: snmp 7 monitored_instance: 8 name: SNMP devices 9 link: "" 10 icon_filename: snmp.png 11 categories: 12 - data-collection.generic-data-collection 13 keywords: 14 - snmp 15 related_resources: 16 integrations: 17 list: [] 18 info_provided_to_referring_integrations: 19 description: "" 20 most_popular: true 21 overview: 22 data_collection: 23 metrics_description: | 24 This collector monitors any SNMP devices and uses the [gosnmp](https://github.com/gosnmp/gosnmp) package. 25 26 It supports: 27 28 - all SNMP versions: SNMPv1, SNMPv2c and SNMPv3. 29 - any number of SNMP devices. 30 - each SNMP device can be used to collect data for any number of charts. 31 - each chart may have any number of dimensions. 32 - each SNMP device may have a different update frequency. 33 - 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). 34 35 Keep in mind that many SNMP switches and routers are very slow. They may not be able to report values per second. 36 `go.d.plugin` reports the time it took for the SNMP device to respond when executed in the debug mode. 37 38 Also, if many SNMP clients are used on the same SNMP device at the same time, values may be skipped. 39 This is a problem of the SNMP device, not this collector. In this case, consider reducing the frequency of data collection (increasing `update_every`). 40 method_description: "" 41 supported_platforms: 42 include: [] 43 exclude: [] 44 multi_instance: true 45 additional_permissions: 46 description: "" 47 default_behavior: 48 auto_detection: 49 description: "" 50 limits: 51 description: "" 52 performance_impact: 53 description: "" 54 setup: 55 prerequisites: 56 list: 57 - title: Find OIDs 58 description: | 59 Use `snmpwalk`, like this: 60 61 ```sh 62 snmpwalk -t 20 -O fn -v 2c -c public 192.0.2.1 63 ``` 64 65 - `-t 20` is the timeout in seconds. 66 - `-O fn` will display full OIDs in numeric format. 67 - `-v 2c` is the SNMP version. 68 - `-c public` is the SNMP community. 69 - `192.0.2.1` is the SNMP device. 70 configuration: 71 file: 72 name: go.d/snmp.conf 73 options: 74 description: | 75 The following options can be defined globally: update_every, autodetection_retry. 76 folding: 77 title: Config options 78 enabled: true 79 list: 80 - name: update_every 81 description: Data collection frequency. 82 default_value: 1 83 required: false 84 - name: autodetection_retry 85 description: Recheck interval in seconds. Zero means no recheck will be scheduled. 86 default_value: 0 87 required: false 88 - name: hostname 89 description: Target ipv4 address. 90 default_value: 127.0.0.1 91 required: true 92 - name: community 93 description: SNMPv1/2 community string. 94 default_value: public 95 required: false 96 - name: options.version 97 description: "SNMP version. Available versions: 1, 2, 3." 98 default_value: 2 99 required: false 100 - name: options.port 101 description: Target port. 102 default_value: 161 103 required: false 104 - name: options.retries 105 description: Retries to attempt. 106 default_value: 1 107 required: false 108 - name: options.timeout 109 description: SNMP request/response timeout. 110 default_value: 10 111 required: false 112 - name: options.max_request_size 113 description: Maximum number of OIDs allowed in one one SNMP request. 114 default_value: 60 115 required: false 116 - name: user.name 117 description: SNMPv3 user name. 118 default_value: "" 119 required: false 120 - name: user.name 121 description: Security level of SNMPv3 messages. 122 default_value: "" 123 required: false 124 - name: user.auth_proto 125 description: Security level of SNMPv3 messages. 126 default_value: "" 127 required: false 128 detailed_description: | 129 The security of an SNMPv3 message as per RFC 3414 (`user.level`): 130 131 | String value | Int value | Description | 132 |:------------:|:---------:|------------------------------------------| 133 | none | 1 | no message authentication or encryption | 134 | authNoPriv | 2 | message authentication and no encryption | 135 | authPriv | 3 | message authentication and encryption | 136 - name: user.name 137 description: Authentication protocol for SNMPv3 messages. 138 default_value: "" 139 required: false 140 detailed_description: | 141 The digest algorithm for SNMPv3 messages that require authentication (`user.auth_proto`): 142 143 | String value | Int value | Description | 144 |:------------:|:---------:|-------------------------------------------| 145 | none | 1 | no message authentication | 146 | md5 | 2 | MD5 message authentication (HMAC-MD5-96) | 147 | sha | 3 | SHA message authentication (HMAC-SHA-96) | 148 | sha224 | 4 | SHA message authentication (HMAC-SHA-224) | 149 | sha256 | 5 | SHA message authentication (HMAC-SHA-256) | 150 | sha384 | 6 | SHA message authentication (HMAC-SHA-384) | 151 | sha512 | 7 | SHA message authentication (HMAC-SHA-512) | 152 - name: user.auth_key 153 description: Authentication protocol pass phrase. 154 default_value: "" 155 required: false 156 - name: user.priv_proto 157 description: Privacy protocol for SNMPv3 messages. 158 default_value: "" 159 required: false 160 detailed_description: | 161 The encryption algorithm for SNMPv3 messages that require privacy (`user.priv_proto`): 162 163 | String value | Int value | Description | 164 |:------------:|:---------:|-------------------------------------------------------------------------| 165 | none | 1 | no message encryption | 166 | des | 2 | ES encryption (CBC-DES) | 167 | aes | 3 | 128-bit AES encryption (CFB-AES-128) | 168 | aes192 | 4 | 192-bit AES encryption (CFB-AES-192) with "Blumenthal" key localization | 169 | aes256 | 5 | 256-bit AES encryption (CFB-AES-256) with "Blumenthal" key localization | 170 | aes192c | 6 | 192-bit AES encryption (CFB-AES-192) with "Reeder" key localization | 171 | aes256c | 7 | 256-bit AES encryption (CFB-AES-256) with "Reeder" key localization | 172 - name: user.priv_key 173 description: Privacy protocol pass phrase. 174 default_value: "" 175 required: false 176 - name: charts 177 description: List of charts. 178 default_value: "[]" 179 required: true 180 - name: charts.id 181 description: Chart ID. Used to uniquely identify the chart. 182 default_value: "" 183 required: true 184 - name: charts.title 185 description: Chart title. 186 default_value: "Untitled chart" 187 required: false 188 - name: charts.units 189 description: Chart units. 190 default_value: num 191 required: false 192 - name: charts.family 193 description: Chart family. 194 default_value: charts.id 195 required: false 196 - name: charts.type 197 description: Chart type (line, area, stacked). 198 default_value: line 199 required: false 200 - name: charts.priority 201 description: Chart priority. 202 default_value: 70000 203 required: false 204 - name: charts.multiply_range 205 description: Used when you need to define many charts using incremental OIDs. 206 default_value: "[]" 207 required: false 208 - name: charts.dimensions 209 description: List of chart dimensions. 210 default_value: "[]" 211 required: true 212 - name: charts.dimensions.oid 213 description: Collected metric OID. 214 default_value: "" 215 required: true 216 - name: charts.dimensions.name 217 description: Dimension name. 218 default_value: "" 219 required: true 220 - name: charts.dimensions.algorithm 221 description: Dimension algorithm (absolute, incremental). 222 default_value: absolute 223 required: false 224 - name: charts.dimensions.multiplier 225 description: Collected value multiplier, applied to convert it properly to units. 226 default_value: 1 227 required: false 228 - name: charts.dimensions.divisor 229 description: Collected value divisor, applied to convert it properly to units. 230 default_value: 1 231 required: false 232 examples: 233 folding: 234 title: Config 235 enabled: true 236 list: 237 - name: SNMPv1/2 238 description: | 239 In this example: 240 241 - the SNMP device is `192.0.2.1`. 242 - the SNMP version is `2`. 243 - the SNMP community is `public`. 244 - we will update the values every 10 seconds. 245 - we define 2 charts `bandwidth_port1` and `bandwidth_port2`, each having 2 dimensions: `in` and `out`. 246 247 > **SNMPv1**: just set `options.version` to 1. 248 > **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. 249 config: | 250 jobs: 251 - name: switch 252 update_every: 10 253 hostname: 192.0.2.1 254 community: public 255 options: 256 version: 2 257 charts: 258 - id: "bandwidth_port1" 259 title: "Switch Bandwidth for port 1" 260 units: "kilobits/s" 261 type: "area" 262 family: "ports" 263 dimensions: 264 - name: "in" 265 oid: "1.3.6.1.2.1.2.2.1.10.1" 266 algorithm: "incremental" 267 multiplier: 8 268 divisor: 1000 269 - name: "out" 270 oid: "1.3.6.1.2.1.2.2.1.16.1" 271 multiplier: -8 272 divisor: 1000 273 - id: "bandwidth_port2" 274 title: "Switch Bandwidth for port 2" 275 units: "kilobits/s" 276 type: "area" 277 family: "ports" 278 dimensions: 279 - name: "in" 280 oid: "1.3.6.1.2.1.2.2.1.10.2" 281 algorithm: "incremental" 282 multiplier: 8 283 divisor: 1000 284 - name: "out" 285 oid: "1.3.6.1.2.1.2.2.1.16.2" 286 multiplier: -8 287 divisor: 1000 288 - name: SNMPv3 289 description: | 290 To use SNMPv3: 291 292 - use `user` instead of `community`. 293 - set `options.version` to 3. 294 295 The rest of the configuration is the same as in the SNMPv1/2 example. 296 config: | 297 jobs: 298 - name: switch 299 update_every: 10 300 hostname: 192.0.2.1 301 options: 302 version: 3 303 user: 304 name: username 305 level: authPriv 306 auth_proto: sha256 307 auth_key: auth_protocol_passphrase 308 priv_proto: aes256 309 priv_key: priv_protocol_passphrase 310 - name: Multiply range 311 description: | 312 If you need to define many charts using incremental OIDs, you can use the `charts.multiply_range` option. 313 314 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`. 315 316 Each of the 24 new charts will have its id (1-24) appended at: 317 318 - its chart unique `id`, i.e. `bandwidth_port_1` to `bandwidth_port_24`. 319 - its title, i.e. `Switch Bandwidth for port 1` to `Switch Bandwidth for port 24`. 320 - 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`. 321 - its `priority` will be incremented for each chart so that the charts will appear on the dashboard in this order. 322 config: | 323 jobs: 324 - name: switch 325 update_every: 10 326 hostname: "192.0.2.1" 327 community: public 328 options: 329 version: 2 330 charts: 331 - id: "bandwidth_port" 332 title: "Switch Bandwidth for port" 333 units: "kilobits/s" 334 type: "area" 335 family: "ports" 336 multiply_range: [1, 24] 337 dimensions: 338 - name: "in" 339 oid: "1.3.6.1.2.1.2.2.1.10" 340 algorithm: "incremental" 341 multiplier: 8 342 divisor: 1000 343 - name: "out" 344 oid: "1.3.6.1.2.1.2.2.1.16" 345 multiplier: -8 346 divisor: 1000 347 - name: Multiple devices with a common configuration 348 description: | 349 YAML supports [anchors](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases). 350 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. 351 352 The following example: 353 354 - adds an `anchor` to the first job. 355 - injects (copies) the first job configuration to the second and updates `name` and `hostname` parameters. 356 - injects (copies) the first job configuration to the third and updates `name` and `hostname` parameters. 357 config: | 358 jobs: 359 - &anchor 360 name: switch 361 update_every: 10 362 hostname: "192.0.2.1" 363 community: public 364 options: 365 version: 2 366 charts: 367 - id: "bandwidth_port1" 368 title: "Switch Bandwidth for port 1" 369 units: "kilobits/s" 370 type: "area" 371 family: "ports" 372 dimensions: 373 - name: "in" 374 oid: "1.3.6.1.2.1.2.2.1.10.1" 375 algorithm: "incremental" 376 multiplier: 8 377 divisor: 1000 378 - name: "out" 379 oid: "1.3.6.1.2.1.2.2.1.16.1" 380 multiplier: -8 381 divisor: 1000 382 - <<: *anchor 383 name: switch2 384 hostname: "192.0.2.2" 385 - <<: *anchor 386 name: switch3 387 hostname: "192.0.2.3" 388 troubleshooting: 389 problems: 390 list: [] 391 alerts: [] 392 metrics: 393 folding: 394 title: Metrics 395 enabled: false 396 description: The metrics that will be collected are defined in the configuration file. 397 availability: [] 398 scopes: []