docs/user-guide.rst

   1 .. _genius-user-guide:
   2
   3 Genius User Guide
   4 =================
   5
   6 Overview
   7 --------
   8
   9 The Genius project provides generic network interfaces, utilities and
  10 services. Any OpenDaylight application can use these to achieve
  11 interference-free co-existence with other applications using Genius.
  12
  13 Modules and Interfaces
  14 ----------------------
  15
  16 In the first phase delivered in OpenDaylight Boron release, Genius
  17 provides following modules —
  18
  19 -  Modules providing a common view of network interfaces for different
  20    services
  21
  22    -  **Interface (logical port) Manager**
  23
  24       -  *Allows bindings/registration of multiple services to logical
  25          ports/interfaces*
  26
  27       -  *Ability to plug in different types of southbound protocol
  28          renderers*
  29
  30    -  **Overlay Tunnel Manager**
  31
  32       -  *Creates and maintains overlay tunnels between configured
  33          Tunnel Endpoints (TEPs)*
  34
  35 -  Modules providing commonly used functions as shared services to avoid
  36    duplication of code and waste of resources
  37
  38    -  **Liveness Monitor**
  39
  40       -  *Provides tunnel/nexthop liveness monitoring services*
  41
  42    -  **ID Manager**
  43
  44       -  *Generates persistent unique integer IDs*
  45
  46    -  **MD-SAL Utils**
  47
  48       -  *Provides common generic APIs for interaction with MD-SAL*
  49
  50 Interface Manager Operations
  51 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  52
  53 Creating interfaces
  54 ^^^^^^^^^^^^^^^^^^^
  55
  56 The YANG file Data Model
  57 `odl-interface.yang <https://github.com/opendaylight/genius/blob/master/interfacemanager/interfacemanager-api/src/main/yang/odl-interface.yang>`__
  58 contains the interface configuration data-model.
  59
  60 You can create interfaces at the MD-SAL Data Node Path
  61 **/config/if:interfaces/interface**, with the following attributes —
  62
  63 ***Common attributes***
  64
  65 -  **name** — unique interface name, can be any unique string (e.g.,
  66    UUID string)
  67
  68 -  **type** — interface type, currently supported *iana-if-type:l2vlan
  69    and iana-if-type:tunnel*
  70
  71 -  **enabled** — admin status, possible values *true* or *false*
  72
  73 -  **parent-refs** : used to specify references to parent interface/port
  74    feeding to this interface
  75
  76 -  datapath-node-identifier — identifier for a fixed/physical dataplane
  77    node, can be physical switch identifier
  78
  79 -  parent-interface — can be a physical switch port (in conjunction of
  80    above), virtual switch port (e.g., neutron port) or another interface
  81
  82 -  list node-identifier — identifier of the dependant underlying
  83    configuration protocol
  84
  85    -  *topology-id* — can be ovsdb configuration protocol
  86
  87    -  *node-id* — can be hwvtep node-id
  88
  89 ***Type specific attributes***
  90
  91 -  when type = l2vlan
  92
  93    -  **vlan-id** — VLAN id for trunk-member l2vlan interfaces
  94
  95    -  **l2vlan-mode** — currently supported ones are *transparent*,
  96       *trunk* or *trunk-member*
  97
  98 -  when type = stacked\_vlan (Not supported yet)
  99
 100    -  **stacked-vlan-id** — VLAN-Id for additional/second VLAN tag
 101
 102 -  when type = tunnel
 103
 104    -  **tunnel-interface-type** — tunnel type, currently supported ones
 105       are:
 106
 107       -  tunnel-type-vxlan
 108
 109       -  tunnel-type-gre
 110
 111       -  tunnel-type-mpls-over-gre
 112
 113    -  **tunnel-source** — tunnel source IP address
 114
 115    -  **tunnel-destination** — tunnel destination IP address
 116
 117    -  **tunnel-gateway** — gateway IP address
 118
 119    -  **monitor-enabled** — tunnel monitoring enable control
 120
 121    -  **monitor-interval** — tunnel monitoring interval in millisiconds
 122
 123 -  when type = mpls (Not supported yet)
 124
 125    -  **list labelStack** — list of lables
 126
 127    -  **num-labels** — number of lables configured
 128
 129 Supported REST calls are **GET, PUT, DELETE, POST**
 130
 131 Creating L2 port interfaces
 132 '''''''''''''''''''''''''''
 133
 134 Interfaces on normal L2 ports (e.g. Neutron tap ports) are created with
 135 type *l2vlan* and *l2vlan-mode* as *transparent*. This type of interface
 136 classifies packets passing through a particular L2 (OpenFlow) port. In
 137 dataplane, packets belonging to this interface are classified by
 138 matching in-port against the of-port-id assigned to the base port as
 139 specified in parent-interface.
 140
 141 **URL:** /restconf/config/ietf-interfaces:interfaces
 142
 143 **Sample JSON data**
 144
 145 ::
 146
 147     "interfaces": {
 148         "interface": [
 149             {
 150                 "name": "4158408c-942b-487c-9a03-0b603c39d3dd",
 151                 "type": "iana-if-type:l2vlan",                       <--- interface type 'l2vlan' for normal L2 port
 152                 "odl-interface:l2vlan-mode": "transparent",          <--- 'transparent' VLAN port mode allows any (tagged, untagged) ethernet packet
 153                 "odl-interface:parent-interface": "tap4158408c-94",  <--- port-name as it appears on southbound interface
 154                 "enabled": true
 155             }
 156         ]
 157     }
 158
 159 Creating VLAN interfaces
 160 ^^^^^^^^^^^^^^^^^^^^^^^^
 161
 162 A VLAN interface is created as a *l2vlan* interface in *trunk-member*
 163 mode, by configuring a VLAN-Id and a particular L2 (vlan trunk)
 164 interface. Parent VLAN trunk interface is created in the same way as the
 165 *transparent* interface as specified above. A *trunk-member* interface
 166 defines a flow on a particular L2 port and having a particular VLAN tag.
 167 On ingress, after classification the VLAN tag is popped out and
 168 corresponding unique dataplane-id is associated with the packet, before
 169 delivering the packet to service processing. When a service module
 170 delivers the packet to this interface for egress, it pushes
 171 corresponding VLAN tag and sends the packet out of the parent L2 port.
 172
 173 **URL:** /restconf/config/ietf-interfaces:interfaces
 174
 175 **Sample JSON data**
 176
 177 ::
 178
 179     "interfaces": {
 180         "interface": [
 181             {
 182                 "name": "4158408c-942b-487c-9a03-0b603c39d3dd:100",
 183                 "type": "iana-if-type:l2vlan",
 184                 "odl-interface:l2vlan-mode": "trunk-member",        <--- for 'trunk-member', flow is classified with particular vlan-id on an l2 port
 185                 "odl-interface:parent-interface": "4158408c-942b-487c-9a03-0b603c39d3dd",  <--- Parent 'trunk' iterface name
 186                 "odl-interface:vlan-id": "100",
 187                 "enabled": true
 188             }
 189         ]
 190     }
 191
 192 Creating Overlay Tunnel Interfaces
 193 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 194
 195 An overlay tunnel interface is created with type *tunnel* and particular
 196 *tunnel-interface-type*. Tunnel interfaces are created on a particular
 197 data plane node (virtual switches) with a pair of (local, remote) IP
 198 addresses. Currently supported tunnel interface types are VxLAN, GRE and
 199 MPLSoverGRE.
 200
 201 **URL:** /restconf/config/ietf-interfaces:interfaces
 202
 203 **Sample JSON data**
 204
 205 ::
 206
 207     "interfaces": {
 208         "interface": [
 209             {
 210                 "name": "MGRE_TUNNEL:1",
 211                 "type": "iana-if-type:tunnel",
 212                 "odl-interface:tunnel-interface-type": "odl-interface:tunnel-type-mpls-over-gre",
 213                 "odl-interface:datapath-node-identifier": 156613701272907,
 214                 "odl-interface:tunnel-source": "11.0.0.43",
 215                 "odl-interface:tunnel-destination": "11.0.0.66",
 216                 "odl-interface:monitor-enabled": false,
 217                 "odl-interface:monitor-interval": 10000,
 218                 "enabled": true
 219             }
 220         ]
 221     }
 222
 223 .. _genius-user-guide-binding-services:
 224
 225 Binding services on interface
 226 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 227
 228 The YANG file
 229 `odl-interface-service-bindings.yang <https://github.com/opendaylight/genius/blob/stable/boron/interfacemanager/interfacemanager-api/src/main/yang/odl-interface-service-bindings.yang>`__
 230 contains the service binding configuration data model.
 231
 232 An application can bind services to a particular interface by
 233 configuring MD-SAL data node at path /config/interface-service-binding.
 234 Binding services on interface allows particular service to pull traffic
 235 arriving on that interface depending upon the service priority.
 236 Service modules can specify openflow-rules to be applied on the packet
 237 belonging to the interface. Usually these rules include sending the
 238 packet to specific service table/pipeline. Service modules are
 239 responsible for sending the packet back (if not consumed) to service
 240 dispatcher table, for next service to process the packet.
 241
 242 **URL:**/restconf/config/interface-service-bindings:service-bindings/
 243
 244 **Sample JSON data**
 245
 246 ::
 247
 248     "service-bindings": {
 249       "services-info": [
 250         {
 251           "interface-name": "4152de47-29eb-4e95-8727-2939ac03ef84",
 252           "bound-services": [
 253             {
 254               "service-name": "ELAN",
 255               "service-type": "interface-service-bindings:service-type-flow-based"
 256               "service-priority": 3,
 257               "flow-priority": 5,
 258               "flow-cookie": 134479872,
 259               "instruction": [
 260                 {
 261                   "order": 2,
 262                   "go-to-table": {
 263                     "table_id": 50
 264                   }
 265                 },
 266                 {
 267                   "order": 1,
 268                   "write-metadata": {
 269                     "metadata": 83953188864,
 270                     "metadata-mask": 1099494850560
 271                   }
 272                 }
 273               ],
 274             },
 275             {
 276              "service-name": "L3VPN",
 277              "service-type": "interface-service-bindings:service-type-flow-based"
 278              "service-priority": 2,
 279              "flow-priority": 10,
 280              "flow-cookie": 134217729,
 281              "instruction": [
 282                 {
 283                   "order": 2,
 284                   "go-to-table": {
 285                     "table_id": 21
 286                   }
 287                 },
 288                 {
 289                   "order": 1,
 290                   "write-metadata": {
 291                     "metadata": 100,
 292                     "metadata-mask": 4294967295
 293                   }
 294                 }
 295               ],
 296             }
 297           ]
 298         }
 299       ]
 300     }
 301
 302 Interface Manager RPCs
 303 ~~~~~~~~~~~~~~~~~~~~~~
 304
 305 In addition to the above defined configuration interfaces, Interface
 306 Manager also provides several RPCs to access interface operational data
 307 and other helpful information. Interface Manger RPCs are defined in
 308 `odl-interface-rpc.yang <https://github.com/opendaylight/genius/blob/stable/boron/interfacemanager/interfacemanager-api/src/main/yang/odl-interface-rpc.yang>`__
 309
 310 The following RPCs are available —
 311
 312 get-dpid-from-interface
 313 ^^^^^^^^^^^^^^^^^^^^^^^
 314
 315 This RPC is used to retrieve dpid/switch hosting the root port from
 316 given interface name.
 317
 318 ::
 319
 320     rpc get-dpid-from-interface {
 321         description "used to retrieve dpid from interface name";
 322         input {
 323             leaf intf-name {
 324                 type string;
 325             }
 326         }
 327         output {
 328             leaf dpid {
 329                 type uint64;
 330             }
 331         }
 332     }
 333
 334 get-port-from-interface
 335 ^^^^^^^^^^^^^^^^^^^^^^^
 336
 337 This RPC is used to retrieve south bound port attributes from the
 338 interface name.
 339
 340 ::
 341
 342     rpc get-port-from-interface {
 343         description "used to retrieve south bound port attributes from the interface name";
 344         input {
 345             leaf intf-name {
 346                 type string;
 347             }
 348         }
 349         output {
 350             leaf dpid {
 351                 type uint64;
 352             }
 353             leaf portno {
 354                 type uint32;
 355             }
 356             leaf portname {
 357                 type string;
 358             }
 359         }
 360     }
 361
 362 get-egress-actions-for-interface
 363 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 364
 365 This RPC is used to retrieve group actions to use from interface name.
 366
 367 ::
 368
 369     rpc get-egress-actions-for-interface {
 370         description "used to retrieve group actions to use from interface name";
 371         input {
 372             leaf intf-name {
 373                 type string;
 374                 mandatory true;
 375             }
 376             leaf tunnel-key {
 377                 description "It can be VNI for VxLAN tunnel ifaces, Gre Key for GRE tunnels, etc.";
 378                 type uint32;
 379                 mandatory false;
 380             }
 381         }
 382         output {
 383             uses action:action-list;
 384         }
 385     }
 386
 387 get-egress-instructions-for-interface
 388 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 389
 390 This RPC is used to retrieve flow instructions to use from interface
 391 name.
 392
 393 ::
 394
 395     rpc get-egress-instructions-for-interface {
 396         description "used to retrieve flow instructions to use from interface name";
 397         input {
 398             leaf intf-name {
 399                 type string;
 400                 mandatory true;
 401             }
 402             leaf tunnel-key {
 403                 description "It can be VNI for VxLAN tunnel ifaces, Gre Key for GRE tunnels, etc.";
 404                 type uint32;
 405                 mandatory false;
 406             }
 407         }
 408         output {
 409             uses offlow:instruction-list;
 410         }
 411     }
 412
 413 get-endpoint-ip-for-dpn
 414 ^^^^^^^^^^^^^^^^^^^^^^^
 415
 416 This RPC is used to get the local ip of the tunnel/trunk interface on a
 417 particular DPN (Data Plane Node).
 418
 419 ::
 420
 421     rpc get-endpoint-ip-for-dpn {
 422         description "to get the local ip of the tunnel/trunk interface";
 423         input {
 424             leaf dpid {
 425                 type uint64;
 426             }
 427         }
 428         output {
 429             leaf-list local-ips {
 430                 type inet:ip-address;
 431             }
 432         }
 433     }
 434
 435 get-interface-type
 436 ^^^^^^^^^^^^^^^^^^
 437
 438 This RPC is used to get the type of the interface (vlan/vxlan or gre).
 439
 440 ::
 441
 442     rpc get-interface-type {
 443     description "to get the type of the interface (vlan/vxlan or gre)";
 444         input {
 445             leaf intf-name {
 446                 type string;
 447             }
 448         }
 449         output {
 450             leaf interface-type {
 451                 type identityref {
 452                     base if:interface-type;
 453                 }
 454             }
 455         }
 456     }
 457
 458 get-tunnel-type
 459 ^^^^^^^^^^^^^^^
 460
 461 This RPC is used to get the type of the tunnel interface(vxlan or gre).
 462
 463 ::
 464
 465     rpc get-tunnel-type {
 466     description "to get the type of the tunnel interface (vxlan or gre)";
 467         input {
 468             leaf intf-name {
 469                 type string;
 470             }
 471         }
 472         output {
 473             leaf tunnel-type {
 474                 type identityref {
 475                     base odlif:tunnel-type-base;
 476                 }
 477             }
 478         }
 479     }
 480
 481 get-nodeconnector-id-from-interface
 482 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 483
 484 This RPC is used to get node-connector-id associated with an interface.
 485
 486 ::
 487
 488     rpc get-nodeconnector-id-from-interface {
 489     description "to get nodeconnector id associated with an interface";
 490         input {
 491             leaf intf-name {
 492                 type string;
 493             }
 494         }
 495         output {
 496             leaf nodeconnector-id {
 497                 type inv:node-connector-id;
 498             }
 499         }
 500     }
 501
 502 get-interface-from-if-index
 503 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 504
 505 This RPC is used to get interface associated with an if-index (dataplane
 506 interface id).
 507
 508 ::
 509
 510     rpc get-interface-from-if-index {
 511         description "to get interface associated with an if-index";
 512             input {
 513                 leaf if-index {
 514                     type int32;
 515                 }
 516             }
 517             output {
 518                 leaf interface-name {
 519                     type string;
 520                 }
 521             }
 522         }
 523
 524 create-terminating-service-actions
 525 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 526
 527 This RPC is used to create the tunnel termination service table entries.
 528
 529 ::
 530
 531     rpc create-terminating-service-actions {
 532     description "create the ingress terminating service table entries";
 533         input {
 534              leaf dpid {
 535                  type uint64;
 536              }
 537              leaf tunnel-key {
 538                  type uint64;
 539              }
 540              leaf interface-name {
 541                  type string;
 542              }
 543              uses offlow:instruction-list;
 544         }
 545     }
 546
 547 remove-terminating-service-actions
 548 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 549
 550 This RPC is used to remove the tunnel termination service table entries.
 551
 552 ::
 553
 554     rpc remove-terminating-service-actions {
 555     description "remove the ingress terminating service table entries";
 556         input {
 557              leaf dpid {
 558                  type uint64;
 559              }
 560              leaf interface-name {
 561                  type string;
 562              }
 563              leaf tunnel-key {
 564                  type uint64;
 565              }
 566         }
 567     }
 568
 569 ID Manager
 570 ----------
 571
 572 TBD.