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

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