--- /dev/null
+.. _genius-user-guide:
+
+Genius User Guide
+=================
+
+Overview
+--------
+
+The Genius project provides generic network interfaces, utilities and
+services. Any OpenDaylight application can use these to achieve
+interference-free co-existence with other applications using Genius.
+
+Modules and Interfaces
+----------------------
+
+In the first phase delivered in OpenDaylight Boron release, Genius
+provides following modules —
+
+- Modules providing a common view of network interfaces for different
+ services
+
+ - **Interface (logical port) Manager**
+
+ - *Allows bindings/registration of multiple services to logical
+ ports/interfaces*
+
+ - *Ability to plug in different types of southbound protocol
+ renderers*
+
+ - **Overlay Tunnel Manager**
+
+ - *Creates and maintains overlay tunnels between configured
+ Tunnel Endpoints (TEPs)*
+
+- Modules providing commonly used functions as shared services to avoid
+ duplication of code and waste of resources
+
+ - **Liveness Monitor**
+
+ - *Provides tunnel/nexthop liveness monitoring services*
+
+ - **ID Manager**
+
+ - *Generates persistent unique integer IDs*
+
+ - **MD-SAL Utils**
+
+ - *Provides common generic APIs for interaction with MD-SAL*
+
+Interface Manager Operations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Creating interfaces
+^^^^^^^^^^^^^^^^^^^
+
+The YANG file Data Model
+`odl-interface.yang <https://github.com/opendaylight/genius/blob/master/interfacemanager/interfacemanager-api/src/main/yang/odl-interface.yang>`__
+contains the interface configuration data-model.
+
+You can create interfaces at the MD-SAL Data Node Path
+**/config/if:interfaces/interface**, with the following attributes —
+
+***Common attributes***
+
+- **name** — unique interface name, can be any unique string (e.g.,
+ UUID string)
+
+- **type** — interface type, currently supported *iana-if-type:l2vlan
+ and iana-if-type:tunnel*
+
+- **enabled** — admin status, possible values *true* or *false*
+
+- **parent-refs** : used to specify references to parent interface/port
+ feeding to this interface
+
+- datapath-node-identifier — identifier for a fixed/physical dataplane
+ node, can be physical switch identifier
+
+- parent-interface — can be a physical switch port (in conjunction of
+ above), virtual switch port (e.g., neutron port) or another interface
+
+- list node-identifier — identifier of the dependant underlying
+ configuration protocol
+
+ - *topology-id* — can be ovsdb configuration protocol
+
+ - *node-id* — can be hwvtep node-id
+
+***Type specific attributes***
+
+- when type = l2vlan
+
+ - **vlan-id** — VLAN id for trunk-member l2vlan interfaces
+
+ - **l2vlan-mode** — currently supported ones are *transparent*,
+ *trunk* or *trunk-member*
+
+- when type = stacked\_vlan (Not supported yet)
+
+ - **stacked-vlan-id** — VLAN-Id for additional/second VLAN tag
+
+- when type = tunnel
+
+ - **tunnel-interface-type** — tunnel type, currently supported ones
+ are:
+
+ - tunnel-type-vxlan
+
+ - tunnel-type-gre
+
+ - tunnel-type-mpls-over-gre
+
+ - **tunnel-source** — tunnel source IP address
+
+ - **tunnel-destination** — tunnel destination IP address
+
+ - **tunnel-gateway** — gateway IP address
+
+ - **monitor-enabled** — tunnel monitoring enable control
+
+ - **monitor-interval** — tunnel monitoring interval in millisiconds
+
+- when type = mpls (Not supported yet)
+
+ - **list labelStack** — list of lables
+
+ - **num-labels** — number of lables configured
+
+Supported REST calls are **GET, PUT, DELETE, POST**
+
+Creating L2 port interfaces
+'''''''''''''''''''''''''''
+
+Interfaces on normal L2 ports (e.g. Neutron tap ports) are created with
+type *l2vlan* and *l2vlan-mode* as *transparent*. This type of interface
+classifies packets passing through a particular L2 (OpenFlow) port. In
+dataplane, packets belonging to this interface are classified by
+matching in-port against the of-port-id assigned to the base port as
+specified in parent-interface.
+
+**URL:** /restconf/config/ietf-interfaces:interfaces
+
+**Sample JSON data**
+
+::
+
+ "interfaces": {
+ "interface": [
+ {
+ "name": "4158408c-942b-487c-9a03-0b603c39d3dd",
+ "type": "iana-if-type:l2vlan", <--- interface type 'l2vlan' for normal L2 port
+ "odl-interface:l2vlan-mode": "transparent", <--- 'transparent' VLAN port mode allows any (tagged, untagged) ethernet packet
+ "odl-interface:parent-interface": "tap4158408c-94", <--- port-name as it appears on southbound interface
+ "enabled": true
+ }
+ ]
+ }
+
+Creating VLAN interfaces
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+A VLAN interface is created as a *l2vlan* interface in *trunk-member*
+mode, by configuring a VLAN-Id and a particular L2 (vlan trunk)
+interface. Parent VLAN trunk interface is created in the same way as the
+*transparent* interface as specified above. A *trunk-member* interface
+defines a flow on a particular L2 port and having a particular VLAN tag.
+On ingress, after classification the VLAN tag is popped out and
+corresponding unique dataplane-id is associated with the packet, before
+delivering the packet to service processing. When a service module
+delivers the packet to this interface for egress, it pushes
+corresponding VLAN tag and sends the packet out of the parent L2 port.
+
+**URL:** /restconf/config/ietf-interfaces:interfaces
+
+**Sample JSON data**
+
+::
+
+ "interfaces": {
+ "interface": [
+ {
+ "name": "4158408c-942b-487c-9a03-0b603c39d3dd:100",
+ "type": "iana-if-type:l2vlan",
+ "odl-interface:l2vlan-mode": "trunk-member", <--- for 'trunk-member', flow is classified with particular vlan-id on an l2 port
+ "odl-interface:parent-interface": "4158408c-942b-487c-9a03-0b603c39d3dd", <--- Parent 'trunk' iterface name
+ "odl-interface:vlan-id": "100",
+ "enabled": true
+ }
+ ]
+ }
+
+Creating Overlay Tunnel Interfaces
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+An overlay tunnel interface is created with type *tunnel* and particular
+*tunnel-interface-type*. Tunnel interfaces are created on a particular
+data plane node (virtual switches) with a pair of (local, remote) IP
+addresses. Currently supported tunnel interface types are VxLAN, GRE and
+MPLSoverGRE.
+
+**URL:** /restconf/config/ietf-interfaces:interfaces
+
+**Sample JSON data**
+
+::
+
+ "interfaces": {
+ "interface": [
+ {
+ "name": "MGRE_TUNNEL:1",
+ "type": "iana-if-type:tunnel",
+ "odl-interface:tunnel-interface-type": "odl-interface:tunnel-type-mpls-over-gre",
+ "odl-interface:datapath-node-identifier": 156613701272907,
+ "odl-interface:tunnel-source": "11.0.0.43",
+ "odl-interface:tunnel-destination": "11.0.0.66",
+ "odl-interface:monitor-enabled": false,
+ "odl-interface:monitor-interval": 10000,
+ "enabled": true
+ }
+ ]
+ }
+
+.. _genius-user-guide-binding-services:
+
+Binding services on interface
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The YANG file
+`odl-interface-service-bindings.yang <https://github.com/opendaylight/genius/blob/stable/boron/interfacemanager/interfacemanager-api/src/main/yang/odl-interface-service-bindings.yang>`__
+contains the service binding configuration data model.
+
+An application can bind services to a particular interface by
+configuring MD-SAL data node at path /config/interface-service-binding.
+Binding services on interface allows particular service to pull traffic
+arriving on that interface depending upon the service priority.
+Service modules can specify openflow-rules to be applied on the packet
+belonging to the interface. Usually these rules include sending the
+packet to specific service table/pipeline. Service modules are
+responsible for sending the packet back (if not consumed) to service
+dispatcher table, for next service to process the packet.
+
+**URL:**/restconf/config/interface-service-bindings:service-bindings/
+
+**Sample JSON data**
+
+::
+
+ "service-bindings": {
+ "services-info": [
+ {
+ "interface-name": "4152de47-29eb-4e95-8727-2939ac03ef84",
+ "bound-services": [
+ {
+ "service-name": "ELAN",
+ "service-type": "interface-service-bindings:service-type-flow-based"
+ "service-priority": 3,
+ "flow-priority": 5,
+ "flow-cookie": 134479872,
+ "instruction": [
+ {
+ "order": 2,
+ "go-to-table": {
+ "table_id": 50
+ }
+ },
+ {
+ "order": 1,
+ "write-metadata": {
+ "metadata": 83953188864,
+ "metadata-mask": 1099494850560
+ }
+ }
+ ],
+ },
+ {
+ "service-name": "L3VPN",
+ "service-type": "interface-service-bindings:service-type-flow-based"
+ "service-priority": 2,
+ "flow-priority": 10,
+ "flow-cookie": 134217729,
+ "instruction": [
+ {
+ "order": 2,
+ "go-to-table": {
+ "table_id": 21
+ }
+ },
+ {
+ "order": 1,
+ "write-metadata": {
+ "metadata": 100,
+ "metadata-mask": 4294967295
+ }
+ }
+ ],
+ }
+ ]
+ }
+ ]
+ }
+
+Interface Manager RPCs
+~~~~~~~~~~~~~~~~~~~~~~
+
+In addition to the above defined configuration interfaces, Interface
+Manager also provides several RPCs to access interface operational data
+and other helpful information. Interface Manger RPCs are defined in
+`odl-interface-rpc.yang <https://github.com/opendaylight/genius/blob/stable/boron/interfacemanager/interfacemanager-api/src/main/yang/odl-interface-rpc.yang>`__
+
+The following RPCs are available —
+
+get-dpid-from-interface
+^^^^^^^^^^^^^^^^^^^^^^^
+
+This RPC is used to retrieve dpid/switch hosting the root port from
+given interface name.
+
+::
+
+ rpc get-dpid-from-interface {
+ description "used to retrieve dpid from interface name";
+ input {
+ leaf intf-name {
+ type string;
+ }
+ }
+ output {
+ leaf dpid {
+ type uint64;
+ }
+ }
+ }
+
+get-port-from-interface
+^^^^^^^^^^^^^^^^^^^^^^^
+
+This RPC is used to retrieve south bound port attributes from the
+interface name.
+
+::
+
+ rpc get-port-from-interface {
+ description "used to retrieve south bound port attributes from the interface name";
+ input {
+ leaf intf-name {
+ type string;
+ }
+ }
+ output {
+ leaf dpid {
+ type uint64;
+ }
+ leaf portno {
+ type uint32;
+ }
+ leaf portname {
+ type string;
+ }
+ }
+ }
+
+get-egress-actions-for-interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This RPC is used to retrieve group actions to use from interface name.
+
+::
+
+ rpc get-egress-actions-for-interface {
+ description "used to retrieve group actions to use from interface name";
+ input {
+ leaf intf-name {
+ type string;
+ mandatory true;
+ }
+ leaf tunnel-key {
+ description "It can be VNI for VxLAN tunnel ifaces, Gre Key for GRE tunnels, etc.";
+ type uint32;
+ mandatory false;
+ }
+ }
+ output {
+ uses action:action-list;
+ }
+ }
+
+get-egress-instructions-for-interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This RPC is used to retrieve flow instructions to use from interface
+name.
+
+::
+
+ rpc get-egress-instructions-for-interface {
+ description "used to retrieve flow instructions to use from interface name";
+ input {
+ leaf intf-name {
+ type string;
+ mandatory true;
+ }
+ leaf tunnel-key {
+ description "It can be VNI for VxLAN tunnel ifaces, Gre Key for GRE tunnels, etc.";
+ type uint32;
+ mandatory false;
+ }
+ }
+ output {
+ uses offlow:instruction-list;
+ }
+ }
+
+get-endpoint-ip-for-dpn
+^^^^^^^^^^^^^^^^^^^^^^^
+
+This RPC is used to get the local ip of the tunnel/trunk interface on a
+particular DPN (Data Plane Node).
+
+::
+
+ rpc get-endpoint-ip-for-dpn {
+ description "to get the local ip of the tunnel/trunk interface";
+ input {
+ leaf dpid {
+ type uint64;
+ }
+ }
+ output {
+ leaf-list local-ips {
+ type inet:ip-address;
+ }
+ }
+ }
+
+get-interface-type
+^^^^^^^^^^^^^^^^^^
+
+This RPC is used to get the type of the interface (vlan/vxlan or gre).
+
+::
+
+ rpc get-interface-type {
+ description "to get the type of the interface (vlan/vxlan or gre)";
+ input {
+ leaf intf-name {
+ type string;
+ }
+ }
+ output {
+ leaf interface-type {
+ type identityref {
+ base if:interface-type;
+ }
+ }
+ }
+ }
+
+get-tunnel-type
+^^^^^^^^^^^^^^^
+
+This RPC is used to get the type of the tunnel interface(vxlan or gre).
+
+::
+
+ rpc get-tunnel-type {
+ description "to get the type of the tunnel interface (vxlan or gre)";
+ input {
+ leaf intf-name {
+ type string;
+ }
+ }
+ output {
+ leaf tunnel-type {
+ type identityref {
+ base odlif:tunnel-type-base;
+ }
+ }
+ }
+ }
+
+get-nodeconnector-id-from-interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This RPC is used to get node-connector-id associated with an interface.
+
+::
+
+ rpc get-nodeconnector-id-from-interface {
+ description "to get nodeconnector id associated with an interface";
+ input {
+ leaf intf-name {
+ type string;
+ }
+ }
+ output {
+ leaf nodeconnector-id {
+ type inv:node-connector-id;
+ }
+ }
+ }
+
+get-interface-from-if-index
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This RPC is used to get interface associated with an if-index (dataplane
+interface id).
+
+::
+
+ rpc get-interface-from-if-index {
+ description "to get interface associated with an if-index";
+ input {
+ leaf if-index {
+ type int32;
+ }
+ }
+ output {
+ leaf interface-name {
+ type string;
+ }
+ }
+ }
+
+create-terminating-service-actions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This RPC is used to create the tunnel termination service table entries.
+
+::
+
+ rpc create-terminating-service-actions {
+ description "create the ingress terminating service table entries";
+ input {
+ leaf dpid {
+ type uint64;
+ }
+ leaf tunnel-key {
+ type uint64;
+ }
+ leaf interface-name {
+ type string;
+ }
+ uses offlow:instruction-list;
+ }
+ }
+
+remove-terminating-service-actions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This RPC is used to remove the tunnel termination service table entries.
+
+::
+
+ rpc remove-terminating-service-actions {
+ description "remove the ingress terminating service table entries";
+ input {
+ leaf dpid {
+ type uint64;
+ }
+ leaf interface-name {
+ type string;
+ }
+ leaf tunnel-key {
+ type uint64;
+ }
+ }
+ }
+
+ID Manager
+----------
+
+TBD.
Code Review / genius.git / commitdiff