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

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