docs/user-guide/genius-user-guide.rst

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