docs/developer-guide/snmp4sdn-developer-guide.rst

   1 .. _snmp4sdn-dev-guide:
   2
   3 SNMP4SDN Developer Guide
   4 ========================
   5
   6 Overview
   7 --------
   8
   9 We propose a southbound plugin that can control the off-the-shelf
  10 commodity Ethernet switches for the purpose of building SDN using
  11 Ethernet switches. For Ethernet switches, forwarding table, VLAN table,
  12 and ACL are where one can install flow configuration on, and this is
  13 done via SNMP and CLI in the proposed plugin. In addition, some settings
  14 required for Ethernet switches in SDN, e.g., disabling STP and flooding,
  15 are proposed.
  16
  17 .. figure:: ./images/snmp4sdn_in_odl_architecture.jpg
  18    :alt: SNMP4SDN as an OpenDaylight southbound plugin
  19
  20    SNMP4SDN as an OpenDaylight southbound plugin
  21
  22 Architecture
  23 ------------
  24
  25 The modules in the plugin are depicted as the following figure.
  26
  27 .. figure:: ./images/snmp4sdn_modules.jpg
  28    :alt: Modules in the SNMP4SDN Plugin
  29
  30    Modules in the SNMP4SDN Plugin
  31
  32 -  AclService: add/remove ACL profile and rule on the switches.
  33
  34 -  FdbService: add/modify/remove FDB table entry on the switches.
  35
  36 -  VlanService: add/modify/remove VLAN table entry on the switches.
  37
  38 -  TopologyService: query and acquire the subnet topology.
  39
  40 -  InventoryService: acquire the switches and their ports.
  41
  42 -  DiscoveryService: probe and resolve the underlying switches as well
  43    as the port pairs connecting the switches. The probing is realized by
  44    SNMP queries. The updates from discovery will also be reflected to
  45    the TopologyService.
  46
  47 -  MiscConfigService: do kinds of settings on switches
  48
  49    -  Supported STP and ARP settings such as enable/disable STP, get
  50       port’s STP state, get ARP table, set ARP entry, and others
  51
  52 -  VendorSpecificHandler: to assist the flow configuration services to
  53    call the switch-talking modules with correct parameters value and
  54    order.
  55
  56 -  Switch-talking modules
  57
  58    -  For the services above, when they need to read or configure the
  59       underlying switches via SNMP or CLI, these queries are dealt with
  60       the modules SNMPHandler and CLIHandler which directly talk with
  61       the switches. The SNMPListener is to listen to snmp trap such as
  62       link up/down event or switch on/off event.
  63
  64 Design
  65 ------
  66
  67 In terms of the architecture of the SNMP4SDN Plugin’s features, the
  68 features include flow configuration, topology discovery, and
  69 multi-vendor support. Their architectures please refer to Wiki
  70 (`Developer Guide -
  71 Design <https://wiki.opendaylight.org/view/SNMP4SDN:Developer_Guide#Design>`__).
  72
  73 Installation and Configuration Guide
  74 ------------------------------------
  75
  76 -  Please refer to the *Getting Started Guide* in
  77    https://www.opendaylight.org/downloads, find the SNMP4SDN section.
  78
  79 -  For the latest full guide, please refer to Wiki (`Installation
  80    Guide <https://wiki.opendaylight.org/view/SNMP4SDN:Installation_Guide>`__,
  81    `User Guide -
  82    Configuration <https://wiki.opendaylight.org/view/SNMP4SDN:User_Guide#Configuration>`__).
  83
  84 Tutorial
  85 --------
  86
  87 -  For the latest full guide, please refer to Wiki (`User Guide -
  88    Tutorial <https://wiki.opendaylight.org/view/SNMP4SDN:User_Guide#Tutorial_.2F_How-To>`__).
  89
  90 Programmatic Interface(s)
  91 -------------------------
  92
  93 SNMP4SDN Plugin exposes APIs via MD-SAL with YANG model. The methods
  94 (RPC call) and data structures for them are listed below.
  95
  96 TopologyService
  97 ~~~~~~~~~~~~~~~
  98
  99 -  RPC call
 100
 101    -  get-edge-list
 102
 103    -  get-node-list
 104
 105    -  get-node-connector-list
 106
 107    -  set-discovery-interval (given interval time in seconds)
 108
 109    -  rediscover
 110
 111 -  Data structure
 112
 113    -  node: composed of node-id, node-type
 114
 115    -  node-connector: composed of node-connector-id,
 116       node-connector-type, node
 117
 118    -  topo-edge: composed of head-node-connector-id,
 119       head-node-connector-type, head-node-id, head-node-type,
 120       tail-node-connector-id, tail-node-connector-type, tail-node-id,
 121       tail-node-type
 122
 123 VlanService
 124 ~~~~~~~~~~~
 125
 126 -  RPC call
 127
 128    -  add-vlan (given node ID, VLAN ID, VLAN name)
 129
 130    -  add-vlan-and-set-ports (given node ID, VLAN ID, VLAN name, tagged
 131       ports, untagged ports)
 132
 133    -  set-vlan-ports (given node ID, VLAN ID, tagged ports, untagged
 134       ports)
 135
 136    -  delete-vlan (given node ID, VLAN ID)
 137
 138    -  get-vlan-table (given node ID)
 139
 140 AclService
 141 ~~~~~~~~~~
 142
 143 -  RPC call
 144
 145    -  create-acl-profile (given node ID, acl-profile-index, acl-profile)
 146
 147    -  del-acl-profile (given node ID, acl-profile-index)
 148
 149    -  set-acl-rule (given node ID, acl-index, acl-rule)
 150
 151    -  del-acl-rule (given node ID, acl-index)
 152
 153    -  clear-acl-table (given node ID)
 154
 155 -  Data structure
 156
 157    -  acl-profile-index: composed of profile-id, profile name
 158
 159    -  acl-profile: composed of acl-layer, vlan-mask, src-ip-mask,
 160       dst-ip-mask
 161
 162    -  acl-layer: IP or ETHERNET
 163
 164    -  acl-index: composed of acl-profile-index, acl-rule-index
 165
 166    -  acl-rule-index: composed of rule-id, rule-name
 167
 168    -  acl-rule: composed of port-list, acl-layer, acl-field, acl-action
 169
 170    -  acl-field: composed of vlan-id, src-ip, dst-ip
 171
 172    -  acl-action: PERMIT or DENY
 173
 174 FdbService
 175 ~~~~~~~~~~
 176
 177 -  RPC call
 178
 179    -  set-fdb-entry (given fdb-entry)
 180
 181    -  del-fdb-entry (given node-id, vlan-id, dest-mac-adddr)
 182
 183    -  get-fdb-entry (given node-id, vlan-id, dest-mac-adddr)
 184
 185    -  get-fdb-table (given node-id)
 186
 187 -  Data structure
 188
 189    -  fdb-entry: composed of node-id, vlan-id, dest-mac-addr, port,
 190       fdb-entry-type
 191
 192    -  fdb-entry-type: OTHER/INVALID/LEARNED/SELF/MGMT
 193
 194 MiscConfigService
 195 ~~~~~~~~~~~~~~~~~
 196
 197 -  RPC call
 198
 199    -  set-stp-port-state (given node-id, port, is\_nable)
 200
 201    -  get-stp-port-state (given node-id, port)
 202
 203    -  get-stp-port-root (given node-id, port)
 204
 205    -  enable-stp (given node-id)
 206
 207    -  disable-stp (given node-id)
 208
 209    -  delete-arp-entry (given node-id, ip-address)
 210
 211    -  set-arp-entry (given node-id, arp-entry)
 212
 213    -  get-arp-entry (given node-id, ip-address)
 214
 215    -  get-arp-table (given node-id)
 216
 217 -  Data structure
 218
 219    -  stp-port-state:
 220       DISABLE/BLOCKING/LISTENING/LEARNING/FORWARDING/BROKEN
 221
 222    -  arp-entry: composed of ip-address and mac-address
 223
 224 SwitchDbService
 225 ~~~~~~~~~~~~~~~
 226
 227 -  RPC call
 228
 229    -  reload-db (The following 4 RPC implemention is TBD)
 230
 231    -  add-switch-entry
 232
 233    -  delete-switch-entry
 234
 235    -  clear-db
 236
 237    -  update-db
 238
 239 -  Data structure
 240
 241    -  switch-info: compose of node-ip, node-mac, community,
 242       cli-user-name, cli-password, model
 243
 244 Help
 245 ----
 246
 247 -  `SNMP4SDN Wiki <https://wiki.opendaylight.org/view/SNMP4SDN:Main>`__
 248
 249 -  SNMP4SDN Mailing List
 250    (`user <https://lists.opendaylight.org/mailman/listinfo/snmp4sdn-users>`__,
 251    `developer <https://lists.opendaylight.org/mailman/listinfo/snmp4sdn-dev>`__)
 252
 253 -  `Latest troubleshooting in
 254    Wiki <https://wiki.opendaylight.org/view/SNMP4SDN:User_Guide#Troubleshooting>`__