== 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 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 https://github.com/opendaylight/genius/blob/master/interfacemanager/interfacemanager-api/src/main/yang/odl-interface.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 interfce 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
- }
- ]
- }
-
-==== Binding services on interface ====
-The YANG file https://github.com/opendaylight/genius/blob/stable/boron/interfacemanager/interfacemanager-api/src/main/yang/odl-interface-service-bindings.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 interafce depending upon the a service priority. Service modules can specify openflow-rules to be applied on the packet belonging to the inetrface. 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 https://github.com/opendaylight/genius/blob/stable/boron/interfacemanager/interfacemanager-api/src/main/yang/odl-interface-rpc.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.
-
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/user-guide/genius-user-guide.html
Code Review / docs.git / commitdiff