docs/user-guide/snmp-plugin-user-guide.rst

   1 .. _snmp-user-guide:
   2
   3 SNMP Plugin User Guide
   4 ======================
   5
   6 Installing Feature
   7 ------------------
   8
   9 The SNMP Plugin can be installed using a single karaf feature:
  10 **odl-snmp-plugin**
  11
  12 After starting Karaf:
  13
  14 -  Install the feature: **feature:install odl-snmp-plugin**
  15
  16 -  Expose the northbound API: **feature:install odl-restconf**
  17
  18 Northbound APIs
  19 ---------------
  20
  21 There are two exposed northbound APIs: snmp-get & snmp-set
  22
  23 SNMP GET
  24 ~~~~~~~~
  25
  26 Default URL: http://localhost:8181/restconf/operations/snmp:snmp-get
  27
  28 POST Input
  29 ^^^^^^^^^^
  30
  31 +----------------+----------------+----------------+----------------+----------------+
  32 | Field Name     | Type           | Description    | Example        | Required?      |
  33 +================+================+================+================+================+
  34 | ip-address     | Ipv4 Address   | The IPv4       | 10.86.3.13     | Yes            |
  35 |                |                | Address of the |                |                |
  36 |                |                | desired        |                |                |
  37 |                |                | network node   |                |                |
  38 +----------------+----------------+----------------+----------------+----------------+
  39 | oid            | String         | The Object     | 1.3.6.1.2.1.1. | Yes            |
  40 |                |                | Identifier of  | 1              |                |
  41 |                |                | the desired    |                |                |
  42 |                |                | MIB            |                |                |
  43 |                |                | table/object   |                |                |
  44 +----------------+----------------+----------------+----------------+----------------+
  45 | get-type       | ENUM (GET,     | The type of    | GET-BULK       | Yes            |
  46 |                | GET-NEXT,      | get request to |                |                |
  47 |                | GET-BULK,      | send           |                |                |
  48 |                | GET-WALK)      |                |                |                |
  49 +----------------+----------------+----------------+----------------+----------------+
  50 | community      | String         | The community  | private        | No. (Default:  |
  51 |                |                | string to use  |                | public)        |
  52 |                |                | for the SNMP   |                |                |
  53 |                |                | request        |                |                |
  54 +----------------+----------------+----------------+----------------+----------------+
  55
  56 **Example.**
  57
  58 ::
  59
  60      {
  61          "input": {
  62              "ip-address": "10.86.3.13",
  63              "oid" : "1.3.6.1.2.1.1.1",
  64              "get-type" : "GET-BULK",
  65              "community" : "private"
  66          }
  67      }
  68
  69 POST Output
  70 ^^^^^^^^^^^
  71
  72 +--------------------------+--------------------------+--------------------------+
  73 | Field Name               | Type                     | Description              |
  74 +==========================+==========================+==========================+
  75 | results                  | List of { "value" :      | The results of the SNMP  |
  76 |                          | String } pairs           | query                    |
  77 +--------------------------+--------------------------+--------------------------+
  78
  79 **Example.**
  80
  81 ::
  82
  83      {
  84          "snmp:results": [
  85              {
  86                  "value": "Ethernet0/0/0",
  87                  "oid": "1.3.6.1.2.1.2.2.1.2.1"
  88              },
  89              {
  90                  "value": "FastEthernet0/0/0",
  91                  "oid": "1.3.6.1.2.1.2.2.1.2.2"
  92              },
  93              {
  94                  "value": "GigabitEthernet0/0/0",
  95                  "oid": "1.3.6.1.2.1.2.2.1.2.3"
  96              }
  97          ]
  98      }
  99
 100 SNMP SET
 101 ~~~~~~~~
 102
 103 Default URL: http://localhost:8181/restconf/operations/snmp:snmp-set
 104
 105 POST Input
 106 ^^^^^^^^^^
 107
 108 +----------------+----------------+----------------+----------------+----------------+
 109 | Field Name     | Type           | Description    | Example        | Required?      |
 110 +================+================+================+================+================+
 111 | ip-address     | Ipv4 Address   | The Ipv4       | 10.86.3.13     | Yes            |
 112 |                |                | address of the |                |                |
 113 |                |                | desired        |                |                |
 114 |                |                | network node   |                |                |
 115 +----------------+----------------+----------------+----------------+----------------+
 116 | oid            | String         | The Object     | 1.3.6.2.1.1.1  | Yes            |
 117 |                |                | Identifier of  |                |                |
 118 |                |                | the desired    |                |                |
 119 |                |                | MIB object     |                |                |
 120 +----------------+----------------+----------------+----------------+----------------+
 121 | value          | String         | The value to   | "Hello World"  | Yes            |
 122 |                |                | set on the     |                |                |
 123 |                |                | network device |                |                |
 124 +----------------+----------------+----------------+----------------+----------------+
 125 | community      | String         | The community  | private        | No. (Default:  |
 126 |                |                | string to use  |                | public)        |
 127 |                |                | for the SNMP   |                |                |
 128 |                |                | request        |                |                |
 129 +----------------+----------------+----------------+----------------+----------------+
 130
 131 **Example.**
 132
 133 ::
 134
 135      {
 136          "input": {
 137              "ip-address": "10.86.3.13",
 138              "oid" : "1.3.6.1.2.1.1.1.0",
 139              "value" : "Sample description",
 140              "community" : "private"
 141          }
 142      }
 143
 144 POST Output
 145 ^^^^^^^^^^^
 146
 147 On a successful SNMP-SET, no output is presented, just a HTTP status of
 148 200.
 149
 150 Errors
 151 ^^^^^^
 152
 153 If any errors happen in the set request, you will be presented with an
 154 error message in the output.
 155
 156 For example, on a failed set request you may see an error like:
 157
 158 ::
 159
 160      {
 161          "errors": {
 162              "error": [
 163                  {
 164                      "error-type": "application",
 165                      "error-tag": "operation-failed",
 166                      "error-message": "SnmpSET failed with error status: 17, error index: 1. StatusText: Not writable"
 167                  }
 168              ]
 169          }
 170      }
 171
 172 which corresponds to Error status 17 in the SNMPv2 RFC:
 173 https://tools.ietf.org/html/rfc1905.
 174