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