docs/developer-guide/uni-manager-plug-in-developer-guide.rst

   1 UNI Manager Plug-In Developer Guide
   2 ===================================
   3
   4 The UNI Manager plug in exposes capabilities of OpenDaylight to
   5 configure networked equipment to operate according to Metro Ethernet
   6 Forum (MEF) requirements for User Network Interface (UNI) and to support
   7 the creation of an Ethernet Virtual Connection (EVC) according to MEF
   8 requirements.
   9
  10 UNI Manager adheres to a minimum set of functionality defined by MEF 7.2
  11 and 10.2 specifications.
  12
  13 Functionality
  14 -------------
  15
  16 The UNI manager plugin enables the creation of Ethernet Virtual
  17 Connections (EVC) as defined by the Metro Ethernet Forum (MEF). An EVC
  18 provides a simulated Ethernet connection among LANs existing at
  19 different geographical locations. This version of the plugin is limited
  20 to connecting two LANS.
  21
  22 As defined by MEF, each location to be connected must have a User
  23 Network Interface, (UNI) which is a device that connects the user LAN to
  24 the EVC providers network.
  25
  26 UNI and EVC are implemented via Open vSwitch, leveraging the OVSDB
  27 project: creating a UNI will end up creating an OVSDB node with an
  28 *ovsbr0* bridge, interface and port. While creating a UNI, based on the
  29 MEF requirement, one can specify a desired QoS; this leverages the QoS
  30 and Queue tables from the OVS database. (see documentation bellow for
  31 full details). Same goes with the EVC, to which one can apply a given
  32 QoS to control the speed of the connection. Creating an EVC will add two
  33 additional ports to the *ovsbr0* bridge:
  34
  35 -  *eht0*: the interface connected to a client laptop
  36
  37 -  *gre1*, interface used to for gre tunnelling between two clients
  38    (VXLAN).
  39
  40 Finally, within this release, UniMgr is more a Proof Of Concept than a
  41 framework to be used in production. Previous demonstrations were made
  42 using Raspberry Pis, having a low NIC bandwith, thus the speed as
  43 defined in the API is actually mapped as follow:
  44
  45 -  ``speed-10M`` ⇒ 1 Mb
  46
  47 -  ``speed-100M`` ⇒ 2 Mb
  48
  49 -  ``speed-1G`` ⇒ 3 Mb
  50
  51 -  ``speed-10G`` ⇒ 4 Mb
  52
  53 UNI Manager REST APIs
  54 ---------------------
  55
  56 This API enables the creation and management of both UNI’s and EVCs. In
  57 order to create an EVC using this interface you would first create two
  58 UNI’s via the following REST API (see documentation below for full
  59 details)
  60
  61 ::
  62
  63     PUT http://<host-ip>:8181/restconf/config/network-topology:network-topology/topology/unimgr:uni/node/<uni-id>
  64
  65 You would then create an EVC, indicating that it is a connection between
  66 the two UNI’s that were just created, via the following REST API (see
  67 documentation below for full details)
  68
  69 ::
  70
  71     PUT http://<host-ip>:8181/restconf/config/network-topology:network-topology/topology/unimgr:evc/link/<evc-id>
  72
  73 You can then change attributes of the UNI’s or EVCs, and delete these
  74 entities using this API (see documentation below for full details).
  75
  76 This plugin uses the OpenDaylight OVSDB plugin to provision and the
  77 manage devices which implement the OVSDB REST interface, as needed to
  78 realize the UNI and EVC life-cycles
  79
  80 .. note::
  81
  82     Both the configuration and operational databases can be operated
  83     upon by the unimgr REST API. The only difference between the two is
  84     in the REST Path. The configuration datastore represents the desired
  85     state, the operational datastore represents the actual state.
  86
  87 For operating on the config database
  88
  89 ::
  90
  91     http://<host-ip>:8181/restconf/config/<PATH>
  92
  93 For operating on the operational database
  94
  95 ::
  96
  97     http://<host-ip>:8181/restconf/operational/<PATH>
  98
  99 The documentation below shows examples of both
 100
 101 CREATE UNI
 102 ~~~~~~~~~~
 103
 104 ::
 105
 106     PUT http://<host-ip>:8181/restconf/config/network-topology:network-topology/topology/unimgr:uni/node/<uni-id>
 107
 108 .. note::
 109
 110     uni-id is determined by and supplied by the caller both in the path
 111     and the body of the rest message
 112
 113 Request Body
 114
 115 ::
 116
 117     {
 118       "network-topology:node": [
 119         {
 120           "node-id": "uni-id",
 121           "speed": {
 122             "speed-1G": 1
 123           },
 124           "uni:mac-layer": "IEEE 802.3-2005",
 125           "uni:physical-medium": "100BASE-T",
 126           "uni:mode": "syncEnabled"
 127           "uni:type": "UNITYPE",
 128           "uni:mtu-size": 1600,
 129           "uni:mac-address": "68:5b:35:bb:f8:3e",
 130           "uni:ip-address": "192.168.2.11",
 131         }
 132       ]
 133     }
 134
 135 Response on success: 200
 136
 137 Input Options
 138
 139 ::
 140
 141     "speed"
 142         "speed-10M"
 143         "speed-100M"
 144         "speed-1G"
 145         "speed-10G"
 146     "uni:mac-layer"
 147         "IEEE 802.3-2005"
 148     uni:physical-medium
 149         "10BASE-T"
 150         "100BASE-T"
 151         "1000BASE-T"
 152         "10GBASE-T"
 153     "uni:mode"
 154         "syncEnabled"
 155         "syncDisabled"
 156     "uni:type"
 157         "UNITYPE"
 158         "uni:mtu-size"
 159         1600 reccomended
 160
 161 On OVS, the QoS, the Queue were updated, and a bridge was added:
 162
 163 ::
 164
 165     mininet@mininet-vm:~$ sudo ovs-vsctl list QoS
 166     _uuid               : 341c6e9d-ecb4-44ff-a21c-db644b466f4c
 167     external_ids        : {opendaylight-qos-id="qos://18db2a79-5655-4a94-afac-94015245e3f6"}
 168     other_config        : {dscp="0", max-rate="3000000"}
 169     queues              : {}
 170     type                : linux-htb
 171
 172     mininet@mininet-vm:~$ sudo ovs-vsctl list Queue
 173     _uuid               : 8a0e1fc1-5d5f-4e7a-9c4d-ec412a5ec7de
 174     dscp                : 0
 175     external_ids        : {opendaylight-queue-id="queue://740a3809-5bef-4ad4-98d6-2ba81132bd06"}
 176     other_config        : {dscp="0", max-rate="3000000"}
 177
 178     mininet@mininet-vm:~$ sudo ovs-vsctl show
 179     0b8ed0aa-67ac-4405-af13-70249a7e8a96
 180         Manager "tcp:192.168.1.200:6640"
 181             is_connected: true
 182         Bridge "ovsbr0"
 183             Port "ovsbr0"
 184                 Interface "ovsbr0"
 185                     type: internal
 186         ovs_version: "2.4.0"
 187
 188 RETRIEVE UNI
 189 ~~~~~~~~~~~~
 190
 191 GET
 192 `http://<host-ip>:8181/restconf/operational/network-topology:network-topology/topology/unimgr:uni/node/<uni-id> <http://<host-ip>:8181/restconf/operational/network-topology:network-topology/topology/unimgr:uni/node/<uni-id>>`__
 193
 194 Response : 200
 195
 196 ::
 197
 198     {
 199         "node": [
 200         {
 201             "node-id": "uni-id",
 202             "cl-unimgr-mef:speed": {
 203                 "speed-1G": [null]
 204             },
 205             "cl-unimgr-mef:mac-layer": "IEEE 802.3-2005",
 206             "cl-unimgr-mef:physical-medium": "1000BASE-T",
 207             "cl-unimgr-mef:mode": "syncEnabled",
 208             "cl-unimgr-mef:type": "UNITYPE",
 209             "cl-unimgr-mef:mtu-size": "1600",
 210             "cl-unimgr-mef:mac-address": "00:22:22:22:22:22",
 211             "cl-unimgr-mef:ip-address": "10.36.0.22"
 212         }
 213         ]
 214     }
 215
 216 Output Options
 217
 218 ::
 219
 220     "cl-unimgr-mef:speed"
 221         "speed-10M"
 222         "speed-100M"
 223         "speed-1G"
 224         "speed-10G"
 225     "cl-unimgr-mef::mac-layer"
 226         "IEEE 802.3-2005"
 227     "cl-unimgr-mef:physical-medium"
 228         "10BASE-T"
 229         "100BASE-T"
 230         "1000BASE-T"
 231         "10GBASE-T"
 232     "cl-unimgr-mef::mode"
 233         "syncEnabled"
 234         "syncDisabled"
 235     "cl-unimgr-mef::type"
 236         "UNITYPE"
 237
 238 UPDATE UNI
 239 ~~~~~~~~~~
 240
 241 ::
 242
 243     PUT http://<host-ip>:8181/restconf/config/network-topology:network-topology/topology/unimgr:uni/node/<uni-id>
 244
 245 .. note::
 246
 247     uni-id is determined by and supplied by the caller both in the path
 248     and the body of the rest message
 249
 250 Request Body
 251
 252 ::
 253
 254     {
 255         "network-topology:node": [
 256         {
 257             "node-id": "uni-id",
 258             "speed": {
 259                 "speed-1G": 1
 260             },
 261             "uni:mac-layer": "IEEE 802.3-2005",
 262             "uni:physical-medium": "100BASE-T",
 263             "uni:mode": "syncEnabled"
 264             "uni:type": "UNITYPE",
 265             "uni:mtu-size": 1600,
 266             "uni:mac-address": "68:5b:35:bb:f8:3e",
 267             "uni:ip-address": "192.168.2.11",
 268         }
 269         ]
 270     }
 271
 272 Response on success: 200
 273
 274 Input Options
 275
 276 ::
 277
 278     "speed"
 279         "speed-10M"
 280         "speed-100M"
 281         "speed-1G"
 282         "speed-10G"
 283     "uni:mac-layer"
 284         "IEEE 802.3-2005"
 285     uni:physical-medium
 286         "10BASE-T"
 287         "100BASE-T"
 288         "1000BASE-T"
 289         "10GBASE-T"
 290     "uni:mode"
 291         "syncEnabled"
 292         "syncDisabled"
 293     "uni:type"
 294         "UNITYPE"
 295     "uni:mtu-size"
 296         1600 reccomended
 297
 298 DELETE UNI
 299 ~~~~~~~~~~
 300
 301 ::
 302
 303     DELETE http://<host-ip>:8181/restconf/config/network-topology:network-topology/topology/unimgr:uni/node/<uni-id>
 304
 305 Response on success: 200
 306
 307 CREATE EVC
 308 ~~~~~~~~~~
 309
 310 ::
 311
 312     PUT http://<host-ip>:8181/restconf/config/network-topology:network-topology/topology/unimgr:evc/link/<evc-id>
 313
 314 .. note::
 315
 316     evc-id is determined by and supplied by the caller both in the path
 317     and the body of the rest message
 318
 319 Request Body
 320
 321 ::
 322
 323     {
 324         "link": [
 325         {
 326             "link-id": "evc-1",
 327             "source": {
 328                 "source-node": "/network-topology/topology/node/uni-1"
 329             },
 330             "destination": {
 331                 "dest-node": "/network-topology/topology/node/uni-2"
 332           },
 333           "cl-unimgr-mef:uni-source": [
 334             {
 335                 "order": "0",
 336                 "ip-address": "192.168.2.11"
 337             }
 338             ],
 339             "cl-unimgr-mef:uni-dest": [
 340             {
 341                 "order": "0",
 342                 "ip-address": "192.168.2.10"
 343             }
 344             ],
 345             "cl-unimgr-mef:cos-id": "gold",
 346             "cl-unimgr-mef:ingress-bw": {
 347                 "speed-10G": {}
 348             },
 349             "cl-unimgr-mef:egress-bw": {
 350                 "speed-10G": {}
 351           }
 352         }
 353         ]
 354     }
 355
 356 Response on success: 200
 357
 358 Input Optionss
 359
 360 ::
 361
 362     ["source"]["source-node"]
 363         Id of 1st UNI to assocate EVC with
 364     ["cl-unimgr-mef:uni-source"][0]["ip-address"]
 365         IP address of 1st UNI to associate EVC with
 366     ["destination"]["dest-node"]
 367         Id of 2nd UNI to assocate EVC with
 368     ["cl-unimgr-mef:uni-dest"][0]["ip-address"]
 369         IP address of 2nd UNI to associate EVC with
 370     "cl-unimgr-mef:cos-id"
 371         class of service id to associate with the EVC
 372     "cl-unimgr-mef:ingress-bw"
 373     "cl-unimgr-mef:egress-bw"
 374         "speed-10M"
 375         "speed-100M"
 376         "speed-1G"
 377         "speed-10G"
 378
 379 On OVS, the QoS, the Queue were updated, and two ports were added:
 380
 381 ::
 382
 383     mininet@mininet-vm:~$ sudo ovs-vsctl list QoS
 384     _uuid               : 341c6e9d-ecb4-44ff-a21c-db644b466f4c
 385     external_ids        : {opendaylight-qos-id="qos://18db2a79-5655-4a94-afac-94015245e3f6"}
 386     other_config        : {dscp="0", max-rate="3000000"}
 387     queues              : {}
 388     type                : linux-htb
 389
 390     mininet@mininet-vm:~$ sudo ovs-vsctl list Queue
 391     _uuid               : 8a0e1fc1-5d5f-4e7a-9c4d-ec412a5ec7de
 392     dscp                : 0
 393     external_ids        : {opendaylight-queue-id="queue://740a3809-5bef-4ad4-98d6-2ba81132bd06"}
 394     other_config        : {dscp="0", max-rate="3000000"}
 395
 396     mininet@mininet-vm:~$ sudo ovs-vsctl show
 397     0b8ed0aa-67ac-4405-af13-70249a7e8a96
 398         Manager "tcp:192.168.1.200:6640"
 399             is_connected: true
 400         Bridge "ovsbr0"
 401             Port "ovsbr0"
 402                 Interface "ovsbr0"
 403                     type: internal
 404             Port "eth1"
 405                 Interface "eth1"
 406             Port "gre1"
 407                 Interface "gre1"
 408                     type: gre
 409                     options: {remote_ip="192.168.1.233"}
 410     ovs_version: "2.4.0"
 411
 412 RETRIEVE EVC
 413 ~~~~~~~~~~~~
 414
 415 ::
 416
 417     GET http://<host-ip>:8181/restconf/operational/network-topology:network-topology/topology/unimgr:evc/link/<evc-id>
 418
 419 Response on success: 200
 420
 421 ::
 422
 423     {
 424         "link": [
 425         {
 426             "link-id": "evc-5",
 427             "source": {
 428                 "source-node": "/network-topology/topology/node/uni-9"
 429             },
 430             "destination": {
 431                 "dest-node": "/network-topology/topology/node/uni-10"
 432             },
 433             "cl-unimgr-mef:uni-dest": [
 434             {
 435                 "order": 0,
 436                 "uni": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='unimgr:uni']/network-topology:node[network-topology:node-id='uni-10']",
 437                 "ip-address": "10.0.0.22"
 438             }
 439             ],
 440             "cl-unimgr-mef:ingress-bw": {
 441                 "speed-1G": [null]
 442             },
 443             "cl-unimgr-mef:cos-id": "new1",
 444             "cl-unimgr-mef:uni-source": [
 445             {
 446                 "order": 0,
 447                 "uni": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='unimgr:uni']/network-topology:node[network-topology:node-id='uni-9']",
 448                 "ip-address": "10.0.0.21"
 449             }
 450             ],
 451             "cl-unimgr-mef:egress-bw": {
 452             "speed-1G": [null]
 453           }
 454         }
 455         ]
 456     }
 457
 458 Output Options
 459
 460 ::
 461
 462     ["source"]["source-node"]
 463     ["cl-unimgr-mef:uni-source"][0]["uni"]
 464         Id of 1st UNI assocated with EVC
 465         ["cl-unimgr-mef:uni-source"][0]["ip-address"]
 466         IP address of 1st UNI assocated with EVC
 467     ["destination"]["dest-node"]
 468     ["cl-unimgr-mef:uni-dest"][0]["uni"]
 469         Id of 2nd UNI assocated with EVC
 470     ["cl-unimgr-mef:uni-dest"][0]["ip-address"]
 471         IP address of 2nd UNI assocated with EVC
 472     "cl-unimgr-mef:cos-id"
 473         class of service id associated with the EVC
 474     "cl-unimgr-mef:ingress-bw"
 475     "cl-unimgr-mef:egress-bw"
 476         "speed-10M"
 477         "speed-100M"
 478         "speed-1G"
 479         "speed-10G"
 480
 481 UPDATE EVC
 482 ~~~~~~~~~~
 483
 484 ::
 485
 486     PUT http://<host-ip>:8181/restconf/config/network-topology:network-topology/topology/unimgr:evc/link/<evc-id>
 487
 488 .. note::
 489
 490     evc-id is determined by and supplied by the caller both in the path
 491     and the body of the rest message
 492
 493 Request Body
 494
 495 ::
 496
 497     {
 498         "link": [
 499         {
 500             "link-id": "evc-1",
 501             "source": {
 502                 "source-node": "/network-topology/topology/node/uni-1"
 503             },
 504             "destination": {
 505                 "dest-node": "/network-topology/topology/node/uni-2"
 506             },
 507             "cl-unimgr-mef:uni-source": [
 508             {
 509                 "order": "0",
 510                 "ip-address": "192.168.2.11"
 511             }
 512             ],
 513             "cl-unimgr-mef:uni-dest": [
 514             {
 515                 "order": "0",
 516                 "ip-address": "192.168.2.10"
 517             }
 518             ],
 519             "cl-unimgr-mef:cos-id": "gold",
 520             "cl-unimgr-mef:ingress-bw": {
 521                 "speed-10G": {}
 522             },
 523             "cl-unimgr-mef:egress-bw": {
 524             "speed-10G": {}
 525           }
 526         }
 527         ]
 528     }
 529
 530 Response on success: 200
 531
 532 Input Optionss
 533
 534 ::
 535
 536     ["source"]["source-node"]
 537         Id of 1st UNI to assocate EVC with
 538     ["cl-unimgr-mef:uni-source"][0]["ip-address"]
 539         IP address of 1st UNI to associate EVC with
 540     ["destination"]["dest-node"]
 541         Id of 2nd UNI to assocate EVC with
 542     ["cl-unimgr-mef:uni-dest"][0]["ip-address"]
 543         IP address of 2nd UNI to associate EVC with
 544     "cl-unimgr-mef:cos-id"
 545         class of service id to associate with the EVC
 546     "cl-unimgr-mef:ingress-bw"
 547     "cl-unimgr-mef:egress-bw"
 548         "speed-10M"
 549         "speed-100M"
 550         "speed-1G"
 551         "speed-10G"
 552
 553 DELETE EVC
 554 ~~~~~~~~~~
 555
 556 ::
 557
 558     DELETE http://host-ip:8181/restconf/config/network-topology:network-topology/topology/unimgr:evc/link/evc-id
 559
 560 Response on success: 200
 561