conf.d/node.d/snmp.conf.md

   1 # SNMP Data Collector
   2
   3 Using this collector, netdata can collect data from any SNMP device.
   4
   5 This collector supports:
   6
   7 - any number of SNMP devices
   8 - each SNMP device can be used to collect data for any number of charts
   9 - each chart may have any number of dimensions
  10 - each SNMP device may have a different update frequency
  11 - 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).
  12
  13 The source code of the plugin is [here](https://github.com/firehol/netdata/blob/master/node.d/snmp.node.js).
  14
  15 ## Configuration
  16
  17 You will need to create the file `/etc/netdata/node.d/snmp.conf` with data like the following.
  18
  19 In this example:
  20
  21  - the SNMP device is `10.11.12.8`.
  22  - the SNMP community is `public`.
  23  - we will update the values every 10 seconds (`update_every: 10` under the server `10.11.12.8`).
  24  - we define 2 charts `snmp_switch.bandwidth_port1` and `snmp_switch.bandwidth_port2`, each having 2 dimensions: `in` and `out`.
  25
  26 ```js
  27 {
  28     "enable_autodetect": false,
  29     "update_every": 5,
  30     "max_request_size": 100,
  31     "servers": [
  32         {
  33             "hostname": "10.11.12.8",
  34             "community": "public",
  35             "update_every": 10,
  36             "max_request_size": 50,
  37             "options": { "timeout": 10000 },
  38             "charts": {
  39                 "snmp_switch.bandwidth_port1": {
  40                     "title": "Switch Bandwidth for port 1",
  41                     "units": "kilobits/s",
  42                     "type": "area",
  43                     "priority": 1,
  44                     "family": "ports",
  45                     "dimensions": {
  46                         "in": {
  47                             "oid": "1.3.6.1.2.1.2.2.1.10.1",
  48                             "algorithm": "incremental",
  49                             "multiplier": 8,
  50                             "divisor": 1024,
  51                             "offset": 0
  52                         },
  53                         "out": {
  54                             "oid": "1.3.6.1.2.1.2.2.1.16.1",
  55                             "algorithm": "incremental",
  56                             "multiplier": -8,
  57                             "divisor": 1024,
  58                             "offset": 0
  59                         }
  60                     }
  61                 },
  62                 "snmp_switch.bandwidth_port2": {
  63                     "title": "Switch Bandwidth for port 2",
  64                     "units": "kilobits/s",
  65                     "type": "area",
  66                     "priority": 1,
  67                     "family": "ports",
  68                     "dimensions": {
  69                         "in": {
  70                             "oid": "1.3.6.1.2.1.2.2.1.10.2",
  71                             "algorithm": "incremental",
  72                             "multiplier": 8,
  73                             "divisor": 1024,
  74                             "offset": 0
  75                         },
  76                         "out": {
  77                             "oid": "1.3.6.1.2.1.2.2.1.16.2",
  78                             "algorithm": "incremental",
  79                             "multiplier": -8,
  80                             "divisor": 1024,
  81                             "offset": 0
  82                         }
  83                     }
  84                 }
  85             }
  86         }
  87     ]
  88 }
  89 ```
  90
  91 `update_every` is the update frequency for each server, in seconds.
  92
  93 `max_request_size` limits the maximum number of OIDs that will be requested in a single call. The default is 50. Lower this number of you get `TooBig` errors in netdata error.log.
  94
  95 `family` sets the name of the submenu of the dashboard each chart will appear under.
  96
  97 If you need to define many charts using incremental OIDs, you can use something like this:
  98
  99 This is like the previous, but the option `multiply_range` given, will multiply the current chart from `1` to `24` inclusive, producing 24 charts in total for the 24 ports of the switch `10.11.12.8`.
 100
 101 Each of the 24 new charts will have its id (1-24) appended at:
 102
 103 1. its chart unique id, i.e. `snmp_switch.bandwidth_port1` to `snmp_switch.bandwidth_port24`
 104 2. its `title`, i.e. `Switch Bandwidth for port 1` to `Switch Bandwidth for port 24`
 105 3. 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`
 106 3. its priority (which will be incremented for each chart so that the charts will appear on the dashboard in this order)
 107
 108 ```js
 109 {
 110     "enable_autodetect": false,
 111     "update_every": 10,
 112     "servers": [
 113         {
 114             "hostname": "10.11.12.8",
 115             "community": "public",
 116             "update_every": 10,
 117             "options": { "timeout": 20000 },
 118             "charts": {
 119                 "snmp_switch.bandwidth_port": {
 120                     "title": "Switch Bandwidth for port ",
 121                     "units": "kilobits/s",
 122                     "type": "area",
 123                     "priority": 1,
 124                     "family": "ports",
 125                     "multiply_range": [ 1, 24 ],
 126                     "dimensions": {
 127                         "in": {
 128                             "oid": "1.3.6.1.2.1.2.2.1.10.",
 129                             "algorithm": "incremental",
 130                             "multiplier": 8,
 131                             "divisor": 1024,
 132                             "offset": 0
 133                         },
 134                         "out": {
 135                             "oid": "1.3.6.1.2.1.2.2.1.16.",
 136                             "algorithm": "incremental",
 137                             "multiplier": -8,
 138                             "divisor": 1024,
 139                             "offset": 0
 140                         }
 141                     }
 142                 }
 143             }
 144         }
 145     ]
 146 }
 147 ```
 148
 149 The `options` given for each server, are:
 150
 151  - `timeout`, the time to wait for the SNMP device to respond. The default is 5000 ms.
 152  - `version`, the SNMP version to use. `0` is Version 1, `1` is Version 2c. The default is Version 1 (`0`).
 153  - `transport`, the default is `udp4`.
 154  - `port`, the port of the SNMP device to connect to. The default is `161`.
 155  - `retries`, the number of attempts to make to fetch the data. The default is `1`.
 156
 157 ## Retreiving names from snmp
 158
 159 You can append a value retrieved from SNMP to the title, by adding `titleoid` to the chart.
 160
 161 You can set a dimension name to a value retrieved from SNMP, by adding `oidname` to the dimension.
 162
 163 Both of the above will participate in `multiply_range`.
 164
 165
 166 ## Testing the configuration
 167
 168 To test it, you can run:
 169
 170 ```sh
 171 /usr/libexec/netdata/plugins.d/node.d.plugin 1 snmp
 172 ```
 173
 174 The above will run it on your console and you will be able to see what netdata sees, but also errors. You can get a very detailed output by appending `debug` to the command line.
 175
 176 If it works, restart netdata to activate the snmp collector and refresh the dashboard (if your SNMP device responds with a delay, you may need to refresh the dashboard in a few seconds).
 177
 178 ## Data collection speed
 179
 180 Keep in mind that many SNMP switches are routers are very slow. They may not be able to report values per second. If you run `node.d.plugin` in `debug` mode, it will report the time it took for the SNMP device to respond. My switch, for example, needs 7-8 seconds to respond for the traffic on 24 ports (48 OIDs, in/out).
 181
 182 Also, if you use many SNMP clients on the same SNMP device at the same time, values may be skipped. This is a problem of the SNMP device, not this collector.
 183
 184 ## Finding OIDs
 185
 186 Use `snmpwalk`, like this:
 187
 188 ```sh
 189 snmpwalk -t 20 -v 1 -O fn -c public 10.11.12.8
 190 ```
 191
 192 - `-t 20` is the timeout in seconds
 193 - `-v 1` is the SNMP version
 194 - `-O fn` will display full OIDs in numeric format (you may want to run it also without this option to see human readable output of OIDs)
 195 - `-c public` is the SNMP community
 196 - `10.11.12.8` is the SNMP device
 197
 198 Keep in mind that `snmpwalk` outputs the OIDs with a dot in front them. You should remove this dot when adding OIDs to the configuration file of this collector.
 199
 200 ## Example: Linksys SRW2024P
 201
 202 This is what I use for my Linksys SRW2024P. It creates:
 203
 204 1. A chart for power consumption (it is a PoE switch)
 205 2. Two charts for packets received (total packets received and packets received with errors)
 206 3. One chart for packets output
 207 4. 24 charts, one for each port of the switch. It also appends the port names, as defined at the switch, to the chart titles.
 208
 209 This switch also reports various other metrics, like snmp, packets per port, etc. Unfortunately it does not report CPU utilization or backplane utilization.
 210
 211 This switch has a very slow SNMP processors. To respond, it needs about 8 seconds, so I have set the refresh frequency (`update_every`) to 15 seconds.
 212
 213 ```js
 214 {
 215     "enable_autodetect": false,
 216     "update_every": 5,
 217     "servers": [
 218     {
 219         "hostname": "10.11.12.8",
 220         "community": "public",
 221         "update_every": 15,
 222         "options": { "timeout": 20000, "version": 1 },
 223         "charts": {
 224             "snmp_switch.power": {
 225                 "title": "Switch Power Supply",
 226                 "units": "watts",
 227                 "type": "line",
 228                 "priority": 10,
 229                 "family": "power",
 230                 "dimensions": {
 231                     "supply": {
 232                         "oid": ".1.3.6.1.2.1.105.1.3.1.1.2.1",
 233                         "algorithm": "absolute",
 234                         "multiplier": 1,
 235                         "divisor": 1,
 236                         "offset": 0
 237                     },
 238                     "used": {
 239                         "oid": ".1.3.6.1.2.1.105.1.3.1.1.4.1",
 240                         "algorithm": "absolute",
 241                         "multiplier": 1,
 242                         "divisor": 1,
 243                         "offset": 0
 244                     }
 245                 }
 246             }
 247             , "snmp_switch.input": {
 248                 "title": "Switch Packets Input",
 249                 "units": "packets/s",
 250                 "type": "area",
 251                 "priority": 20,
 252                 "family": "IP",
 253                 "dimensions": {
 254                     "receives": {
 255                         "oid": ".1.3.6.1.2.1.4.3.0",
 256                         "algorithm": "incremental",
 257                         "multiplier": 1,
 258                         "divisor": 1,
 259                         "offset": 0
 260                     }
 261                     , "discards": {
 262                         "oid": ".1.3.6.1.2.1.4.8.0",
 263                         "algorithm": "incremental",
 264                         "multiplier": 1,
 265                         "divisor": 1,
 266                         "offset": 0
 267                     }
 268                 }
 269             }
 270             , "snmp_switch.input_errors": {
 271                 "title": "Switch Received Packets with Errors",
 272                 "units": "packets/s",
 273                 "type": "line",
 274                 "priority": 30,
 275                 "family": "IP",
 276                 "dimensions": {
 277                     "bad_header": {
 278                         "oid": ".1.3.6.1.2.1.4.4.0",
 279                         "algorithm": "incremental",
 280                         "multiplier": 1,
 281                         "divisor": 1,
 282                         "offset": 0
 283                     }
 284                     , "bad_address": {
 285                         "oid": ".1.3.6.1.2.1.4.5.0",
 286                         "algorithm": "incremental",
 287                         "multiplier": 1,
 288                         "divisor": 1,
 289                         "offset": 0
 290                     }
 291                     , "unknown_protocol": {
 292                         "oid": ".1.3.6.1.2.1.4.7.0",
 293                         "algorithm": "incremental",
 294                         "multiplier": 1,
 295                         "divisor": 1,
 296                         "offset": 0
 297                     }
 298                 }
 299             }
 300             , "snmp_switch.output": {
 301                 "title": "Switch Output Packets",
 302                 "units": "packets/s",
 303                 "type": "line",
 304                 "priority": 40,
 305                 "family": "IP",
 306                 "dimensions": {
 307                     "requests": {
 308                         "oid": ".1.3.6.1.2.1.4.10.0",
 309                         "algorithm": "incremental",
 310                         "multiplier": 1,
 311                         "divisor": 1,
 312                         "offset": 0
 313                     }
 314                     , "discards": {
 315                         "oid": ".1.3.6.1.2.1.4.11.0",
 316                         "algorithm": "incremental",
 317                         "multiplier": -1,
 318                         "divisor": 1,
 319                         "offset": 0
 320                     }
 321                     , "no_route": {
 322                         "oid": ".1.3.6.1.2.1.4.12.0",
 323                         "algorithm": "incremental",
 324                         "multiplier": -1,
 325                         "divisor": 1,
 326                         "offset": 0
 327                     }
 328                 }
 329             }
 330             , "snmp_switch.bandwidth_port": {
 331                 "title": "Switch Bandwidth for port ",
 332                 "titleoid": ".1.3.6.1.2.1.31.1.1.1.18.",
 333                 "units": "kilobits/s",
 334                 "type": "area",
 335                 "priority": 100,
 336                 "family": "ports",
 337                 "multiply_range": [ 1, 24 ],
 338                 "dimensions": {
 339                     "in": {
 340                         "oid": ".1.3.6.1.2.1.2.2.1.10.",
 341                         "algorithm": "incremental",
 342                         "multiplier": 8,
 343                         "divisor": 1024,
 344                         "offset": 0
 345                     }
 346                     , "out": {
 347                         "oid": ".1.3.6.1.2.1.2.2.1.16.",
 348                         "algorithm": "incremental",
 349                         "multiplier": -8,
 350                         "divisor": 1024,
 351                         "offset": 0
 352                     }
 353                 }
 354             }
 355         }
 356     }
 357     ]
 358 }
 359 ```