manuals/developer-guide/src/main/asciidoc/ttp/ttp-model-dev.adoc

   1 == TTP Model Developer Guide
   2
   3 === Overview
   4 Table Type Patterns are a specification developed by the
   5 https://www.opennetworking.org/[Open Networking Foundation] to enable
   6 the description and negotiation of subsets of the OpenFlow protocol.
   7 This is particularly useful for hardware switches that support OpenFlow
   8 as it enables the to describe what features they do (and thus also what
   9 features they do not) support. More details can be found in the full
  10 specification listed on the
  11 https://www.opennetworking.org/sdn-resources/onf-specifications/openflow[OpenFlow
  12 specifications page].
  13
  14 === TTP Model Architecture
  15 The TTP Model provides a YANG-modeled type for a TTP and allows them
  16 to be associated with a master list of known TTPs, as well as active
  17 and supported TTPs with nodes in the MD-SAL inventory model.
  18
  19 === Key APIs and Interfaces
  20 The key API provided by the TTP Model feature is the ability to store
  21 a set of TTPs in the MD-SAL as well as associate zero or one active
  22 TTPs and zero or more supported TTPs along with a given node in the
  23 MD-SAL inventory model.
  24
  25 === API Reference Documentation
  26
  27 ==== RESTCONF
  28 See the generated RESTCONF API documentation at:
  29 http://localhost:8181/apidoc/explorer/index.html
  30
  31 Look for the onf-ttp module to expand and see the various RESTCONF
  32 APIs.
  33
  34 ==== Java Bindings
  35
  36 TODO: Provide a link to JavaDoc.
  37
  38 As stated above there are 3 locations where a Table Type Pattern can be
  39 placed into the MD-SAL Data Store. They correspond to 3 different REST
  40 API URIs:
  41
  42 . +restconf/config/onf-ttp:opendaylight-ttps/onf-ttp:table-type-patterns/+
  43 . +restconf/config/opendaylight-inventory:nodes/node/{id}/ttp-inventory-node:active_ttp/+
  44 . +restconf/config/opendaylight-inventory:nodes/node/{id}/ttp-inventory-node:supported_ttps/+
  45
  46 [NOTE]
  47 ===============================
  48 Typically, these URIs are running on the machine the controller is on
  49 at port 8181. If you are on the same machine they can thus be accessed
  50 at +http://localhost:8181/<uri>+
  51 ===============================
  52
  53 === Using the TTP Model RESTCONF APIs
  54
  55 ==== Setting REST HTTP Headers
  56
  57 ===== Authentication
  58
  59 The REST API calls require authentication by default. The default
  60 method is to use basic auth with a user name and password of `admin'.
  61
  62 ===== Content-Type and Accept
  63
  64 RESTCONF supports both xml and json. This example focuses on JSON, but
  65 xml can be used just as easily. When doing a PUT or POST be sure to
  66 specify the appropriate +Conetnt-Type+ header: either
  67 +application/json+ or +application/xml+.
  68
  69 When doing a GET be sure to specify the appropriate +Accept+ header:
  70 again, either +application/json+ or +application/xml+.
  71
  72 ==== Content
  73
  74 The contents of a PUT or POST should be a OpenDaylight Table Type
  75 Pattern. An example of one is provided below. The example can also be
  76 found at https://git.opendaylight.org/gerrit/gitweb?p=ttp.git;a=blob;f=parser/sample-TTP-from-tests.ttp;h=45130949b25c6f86b750959d27d04ec2208935fb;hb=HEAD[+parser/sample-TTP-from-tests.ttp+ in the TTP git repository].
  77
  78 .Sample Table Type Pattern (json)
  79 -----------------------------------------------------
  80 {
  81     "table-type-patterns": {
  82         "table-type-pattern": [
  83             {
  84                 "security": {
  85                     "doc": [
  86                         "This TTP is not published for use by ONF. It is an example and for",
  87                         "illustrative purposes only.",
  88                         "If this TTP were published for use it would include",
  89                         "guidance as to any security considerations in this doc member."
  90                     ]
  91                 },
  92                 "NDM_metadata": {
  93                     "authority": "org.opennetworking.fawg",
  94                     "OF_protocol_version": "1.3.3",
  95                     "version": "1.0.0",
  96                     "type": "TTPv1",
  97                     "doc": [
  98                         "Example of a TTP supporting L2 (unicast, multicast, flooding), L3 (unicast only),",
  99                         "and an ACL table."
 100                     ],
 101                     "name": "L2-L3-ACLs"
 102                 },
 103                 "identifiers": [
 104                     {
 105                         "doc": [
 106                             "The VLAN ID of a locally attached L2 subnet on a Router."
 107                         ],
 108                         "var": "<subnet_VID>"
 109                     },
 110                     {
 111                         "doc": [
 112                             "An OpenFlow group identifier (integer) identifying a group table entry",
 113                             "of the type indicated by the variable name"
 114                         ],
 115                         "var": "<<group_entry_types/name>>"
 116                     }
 117                 ],
 118                 "features": [
 119                     {
 120                         "doc": [
 121                             "Flow entry notification Extension – notification of changes in flow entries"
 122                         ],
 123                         "feature": "ext187"
 124                     },
 125                     {
 126                         "doc": [
 127                             "Group notifications Extension – notification of changes in group or meter entries"
 128                         ],
 129                         "feature": "ext235"
 130                     }
 131                 ],
 132                 "meter_table": {
 133                     "meter_types": [
 134                         {
 135                             "name": "ControllerMeterType",
 136                             "bands": [
 137                                 {
 138                                     "type": "DROP",
 139                                     "rate": "1000..10000",
 140                                     "burst": "50..200"
 141                                 }
 142                             ]
 143                         },
 144                         {
 145                             "name": "TrafficMeter",
 146                             "bands": [
 147                                 {
 148                                     "type": "DSCP_REMARK",
 149                                     "rate": "10000..500000",
 150                                     "burst": "50..500"
 151                                 },
 152                                 {
 153                                     "type": "DROP",
 154                                     "rate": "10000..500000",
 155                                     "burst": "50..500"
 156                                 }
 157                             ]
 158                         }
 159                     ],
 160                     "built_in_meters": [
 161                         {
 162                             "name": "ControllerMeter",
 163                             "meter_id": 1,
 164                             "type": "ControllerMeterType",
 165                             "bands": [
 166                                 {
 167                                     "rate": 2000,
 168                                     "burst": 75
 169                                 }
 170                             ]
 171                         },
 172                         {
 173                             "name": "AllArpMeter",
 174                             "meter_id": 2,
 175                             "type": "ControllerMeterType",
 176                             "bands": [
 177                                 {
 178                                     "rate": 1000,
 179                                     "burst": 50
 180                                 }
 181                             ]
 182                         }
 183                     ]
 184                 },
 185                 "table_map": [
 186                     {
 187                         "name": "ControlFrame",
 188                         "number": 0
 189                     },
 190                     {
 191                         "name": "IngressVLAN",
 192                         "number": 10
 193                     },
 194                     {
 195                         "name": "MacLearning",
 196                         "number": 20
 197                     },
 198                     {
 199                         "name": "ACL",
 200                         "number": 30
 201                     },
 202                     {
 203                         "name": "L2",
 204                         "number": 40
 205                     },
 206                     {
 207                         "name": "ProtoFilter",
 208                         "number": 50
 209                     },
 210                     {
 211                         "name": "IPv4",
 212                         "number": 60
 213                     },
 214                     {
 215                         "name": "IPv6",
 216                         "number": 80
 217                     }
 218                 ],
 219                 "parameters": [
 220                     {
 221                         "doc": [
 222                             "documentation"
 223                         ],
 224                         "name": "Showing-curt-how-this-works",
 225                         "type": "type1"
 226                     }
 227                 ],
 228                 "flow_tables": [
 229                     {
 230                         "doc": [
 231                             "Filters L2 control reserved destination addresses and",
 232                             "may forward control packets to the controller.",
 233                             "Directs all other packets to the Ingress VLAN table."
 234                         ],
 235                         "name": "ControlFrame",
 236                         "flow_mod_types": [
 237                             {
 238                                 "doc": [
 239                                     "This match/action pair allows for flow_mods that match on either",
 240                                     "ETH_TYPE or ETH_DST (or both) and send the packet to the",
 241                                     "controller, subject to metering."
 242                                 ],
 243                                 "name": "Frame-To-Controller",
 244                                 "match_set": [
 245                                     {
 246                                         "field": "ETH_TYPE",
 247                                         "match_type": "all_or_exact"
 248                                     },
 249                                     {
 250                                         "field": "ETH_DST",
 251                                         "match_type": "exact"
 252                                     }
 253                                 ],
 254                                 "instruction_set": [
 255                                     {
 256                                         "doc": [
 257                                             "This meter may be used to limit the rate of PACKET_IN frames",
 258                                             "sent to the controller"
 259                                         ],
 260                                         "instruction": "METER",
 261                                         "meter_name": "ControllerMeter"
 262                                     },
 263                                     {
 264                                         "instruction": "APPLY_ACTIONS",
 265                                         "actions": [
 266                                             {
 267                                                 "action": "OUTPUT",
 268                                                 "port": "CONTROLLER"
 269                                             }
 270                                         ]
 271                                     }
 272                                 ]
 273                             }
 274                         ],
 275                         "built_in_flow_mods": [
 276                             {
 277                                 "doc": [
 278                                     "Mandatory filtering of control frames with C-VLAN Bridge reserved DA."
 279                                 ],
 280                                 "name": "Control-Frame-Filter",
 281                                 "priority": "1",
 282                                 "match_set": [
 283                                     {
 284                                         "field": "ETH_DST",
 285                                         "mask": "0xfffffffffff0",
 286                                         "value": "0x0180C2000000"
 287                                     }
 288                                 ]
 289                             },
 290                             {
 291                                 "doc": [
 292                                     "Mandatory miss flow_mod, sends packets to IngressVLAN table."
 293                                 ],
 294                                 "name": "Non-Control-Frame",
 295                                 "priority": "0",
 296                                 "instruction_set": [
 297                                     {
 298                                         "instruction": "GOTO_TABLE",
 299                                         "table": "IngressVLAN"
 300                                     }
 301                                 ]
 302                             }
 303                         ]
 304                     }
 305                 ],
 306                 "group_entry_types": [
 307                     {
 308                         "doc": [
 309                             "Output to a port, removing VLAN tag if needed.",
 310                             "Entry per port, plus entry per untagged VID per port."
 311                         ],
 312                         "name": "EgressPort",
 313                         "group_type": "INDIRECT",
 314                         "bucket_types": [
 315                             {
 316                                 "name": "OutputTagged",
 317                                 "action_set": [
 318                                     {
 319                                         "action": "OUTPUT",
 320                                         "port": "<port_no>"
 321                                     }
 322                                 ]
 323                             },
 324                             {
 325                                 "name": "OutputUntagged",
 326                                 "action_set": [
 327                                     {
 328                                         "action": "POP_VLAN"
 329                                     },
 330                                     {
 331                                         "action": "OUTPUT",
 332                                         "port": "<port_no>"
 333                                     }
 334                                 ]
 335                             },
 336                             {
 337                                 "opt_tag": "VID-X",
 338                                 "name": "OutputVIDTranslate",
 339                                 "action_set": [
 340                                     {
 341                                         "action": "SET_FIELD",
 342                                         "field": "VLAN_VID",
 343                                         "value": "<local_vid>"
 344                                     },
 345                                     {
 346                                         "action": "OUTPUT",
 347                                         "port": "<port_no>"
 348                                     }
 349                                 ]
 350                             }
 351                         ]
 352                     }
 353                 ],
 354                 "flow_paths": [
 355                     {
 356                         "doc": [
 357                             "This object contains just a few examples of flow paths, it is not",
 358                             "a comprehensive list of the flow paths required for this TTP.  It is",
 359                             "intended that the flow paths array could include either a list of",
 360                             "required flow paths or a list of specific flow paths that are not",
 361                             "required (whichever is more concise or more useful."
 362                         ],
 363                         "name": "L2-2",
 364                         "path": [
 365                             "Non-Control-Frame",
 366                             "IV-pass",
 367                             "Known-MAC",
 368                             "ACLskip",
 369                             "L2-Unicast",
 370                             "EgressPort"
 371                         ]
 372                     },
 373                     {
 374                         "name": "L2-3",
 375                         "path": [
 376                             "Non-Control-Frame",
 377                             "IV-pass",
 378                             "Known-MAC",
 379                             "ACLskip",
 380                             "L2-Multicast",
 381                             "L2Mcast",
 382                             "[EgressPort]"
 383                         ]
 384                     },
 385                     {
 386                         "name": "L2-4",
 387                         "path": [
 388                             "Non-Control-Frame",
 389                             "IV-pass",
 390                             "Known-MAC",
 391                             "ACL-skip",
 392                             "VID-flood",
 393                             "VIDflood",
 394                             "[EgressPort]"
 395                         ]
 396                     },
 397                     {
 398                         "name": "L2-5",
 399                         "path": [
 400                             "Non-Control-Frame",
 401                             "IV-pass",
 402                             "Known-MAC",
 403                             "ACLskip",
 404                             "L2-Drop"
 405                         ]
 406                     },
 407                     {
 408                         "name": "v4-1",
 409                         "path": [
 410                             "Non-Control-Frame",
 411                             "IV-pass",
 412                             "Known-MAC",
 413                             "ACLskip",
 414                             "L2-Router-MAC",
 415                             "IPv4",
 416                             "v4-Unicast",
 417                             "NextHop",
 418                             "EgressPort"
 419                         ]
 420                     },
 421                     {
 422                         "name": "v4-2",
 423                         "path": [
 424                             "Non-Control-Frame",
 425                             "IV-pass",
 426                             "Known-MAC",
 427                             "ACLskip",
 428                             "L2-Router-MAC",
 429                             "IPv4",
 430                             "v4-Unicast-ECMP",
 431                             "L3ECMP",
 432                             "NextHop",
 433                             "EgressPort"
 434                         ]
 435                     }
 436                 ]
 437             }
 438         ]
 439     }
 440 }
 441 -----------------------------------------------------
 442
 443 ==== Making a REST Call
 444
 445 In this example we'll do a PUT to install the sample TTP from above
 446 into OpenDaylight and then retrieve it both as json and as xml. We'll
 447 use the https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm[
 448 Postman - REST Client] for Chrome in the examples, but any method of
 449 accessing REST should work.
 450
 451 First, we'll fill in the basic information:
 452
 453 .Filling in URL, content, Content-Type and basic auth
 454 image::ttp-screen1-basic-auth.png[width=500]
 455
 456 . Set the URL to +http://localhost:8181/restconf/config/onf-ttp:opendaylight-ttps/onf-ttp:table-type-patterns/+
 457 . Set the action to +PUT+
 458 . Click Headers and
 459 . Set a header for +Content-Type+ to +application/json+
 460 . Make sure the content is set to raw and
 461 . Copy the sample TTP from above into the content
 462 . Click the Basic Auth tab and
 463 . Set the username and password to admin
 464 . Click Refresh headers
 465
 466 .Refreshing basic auth headers
 467 image::ttp-screen2-applied-basic-auth.png[width=500]
 468
 469 After clicking Refresh headers, we can see that a new header
 470 (+Authorization+) has been created and this will allow us to
 471 authenticate to make the rest call.
 472
 473 .PUTting a TTP
 474 image::ttp-screen3-sent-put.png[width=500]
 475
 476 At this point, clicking send should result in a Status response of +200
 477 OK+ indicating we've successfully PUT the TTP into OpenDaylight.
 478
 479 .Retrieving the TTP as json via a GET
 480 image::ttp-screen4-get-json.png[width=500]
 481
 482 We can now retrieve the TTP by:
 483
 484 . Changing the action to +GET+
 485 . Setting an +Accept+ header to +application/json+ and
 486 . Pressing send
 487
 488 .Retrieving the TTP as xml via a GET
 489 image::ttp-screen5-get-xml.png[width=500]
 490
 491 The same process can retrieve the content as xml by setting the
 492 +Accept+ header to +application/xml+.