-== OVSDB MDSAL Southbound Plugin Developer Guide
+== OVSDB MD-SAL Southbound Plugin Developer Guide
=== Overview
-TBD
+The Open vSwitch Database (OVSDB) Model Driven Service Abstraction Layer
+(MD-SAL) Southbound plugin provides an MD-SAL based interface to
+Open vSwitch systems. This is done by augmenting the MD-SAL topology node with
+a YANG model which replicates some (but not all) of the Open vSwitch schema.
-=== OVSDB MDSAL Southbound Plugin Architecture
-TBD
+=== OVSDB MD-SAL Southbound Plugin Architecture and Operation
+The architecture and operation of the OVSDB MD-SAL Southbound plugin is
+illustrated in the following set of diagrams.
-=== Key APIs and Interfaces
-TBD
+==== Connecting to an OVSDB Node
+An OVSDB node is a system which is running the OVS software and is capable of
+being managed by an OVSDB Manager. The OVSDB MD-SAL Southbound plugin in
+OpenDaylight is capable of operating as an OVSDB manager. Depending on the
+configuration of the OVSDB node, the connection of the OVSDB manager can
+be active or passive.
+
+===== Active OVSDB Node Manager Workflow
+An active OVSDB node manager connection is made when OpenDaylight initiates the
+connection to the OVSDB node. In order for this to work, you must configure the
+OVSDB node to listen on a TCP port for the connection (i.e.
+OpenDaylight is active and the OVSDB node is passive). This option can be
+configured on the OVSDB node using the following command:
+
+ ovs-vsctl set-manager ptcp:6640
+
+The following diagram illustrates the sequence of events which occur when
+OpenDaylight initiates an active OVSDB manager connection to an OVSDB node.
+
+.Active OVSDB Manager Connection
+image::ovsdb-sb-active-connection.jpg[width=500]
+
+Step 1::
+Create an OVSDB node by using RESTCONF or an OpenDaylight plugin. The OVSDB node
+is listed under the OVSDB topology node.
+Step 2::
+Add the OVSDB node to the OVSDB MD-SAL southbound configuration datastore. The
+OVSDB southbound provider is registered to listen for data change events on the
+portion of the MD-SAL topology data store which contains the OVSDB southbound
+topology node augmentations. The addition of an OVSDB node causes an event which
+is received by the OVSDB Southbound provider.
+Step 3::
+The OVSDB Southbound provider initiates a connection to the OVSDB node using
+the connection information provided in the configuration OVSDB node (i.e. IP
+address and TCP port number).
+Step 4::
+The OVSDB Southbound provider adds the OVSDB node to the OVSDB MD-SAL
+operational data store. The operational data store contains OVSDB node
+objects which represent active connections to OVSDB nodes.
+Step 5::
+The OVSDB Southbound provider requests the schema and databases which are
+supported by the OVSDB node.
+Step 6::
+The OVSDB Southbound provider uses the database and schema information to
+construct a monitor request which causes the OVSDB node to send the controller
+any updates made to the OVSDB databases on the OVSDB node.
+
+
+===== Passive OVSDB Node Manager Workflow
+A passive OVSDB node connection to OpenDaylight is made when the OVSDB node
+initiates the connection to OpenDaylight. In order for this to work, you must
+configure the OVSDB node to connect to the IP address and OVSDB port on which
+OpenDaylight is listening. This option can be configured on the OVSDB node
+using the following command:
+
+ ovs-vsctl set-manager tcp:<IP address>:6640
+
+The following diagram illustrates the sequence of events which occur when an
+OVSDB node connects to OpenDaylight.
+
+.Passive OVSDB Manager Connection
+image::ovsdb-sb-passive-connection.jpg[width=500]
+
+Step 1::
+The OVSDB node initiates a connection to OpenDaylight.
+Step 2::
+The OVSDB Southbound provider adds the OVSDB node to the OVSDB MD-SAL
+operational data store. The operational data store contains OVSDB node
+objects which represent active connections to OVSDB nodes.
+Step 3::
+The OVSDB Southbound provider requests the schema and databases which are
+supported by the OVSDB node.
+Step 4::
+The OVSDB Southbound provider uses the database and schema information to
+construct a monitor request which causes the OVSDB node to send back
+any updates which have been made to the OVSDB databases on the OVSDB node.
+
+==== OVSDB Node ID in the Southbound Operational MD-SAL
+When OpenDaylight initiates an active connection to an OVSDB node, it
+writes an external-id to the Open_vSwitch table on the OVSDB node. The
+external-id is an OpenDaylight instance identifier which identifies the
+OVSDB topology node which has just been created.
+Here is an example showing the value of the 'opendaylight-iid' entry
+in the external-ids column of the Open_vSwitch table where the
+node-id of the OVSDB node is 'ovsdb:HOST1'.
+
+ $ ovs-vsctl list open_vswitch
+ ...
+ external_ids : {opendaylight-iid="/network-topology:network-topology/network-topology:topology[network-topology:topology-id='ovsdb:1']/network-topology:node[network-topology:node-id='ovsdb:HOST1']"}
+ ...
+
+The 'opendaylight-iid' entry in the external-ids column of the Open_vSwitch
+table causes the OVSDB node to have same node-id in the operational
+MD-SAL datastore as in the configuration MD-SAL datastore. This holds true
+if the OVSDB node manager settings are subsequently changed so that a
+passive OVSDB manager connection is made.
+
+If there is no 'opendaylight-iid' entry in the external-ids column and
+a passive OVSDB manager connection is made, then the node-id of the OVSDB
+node in the operational MD-SAL datastore will be constructed using the UUID
+of the Open_vSwitch table as follows.
+
+ "node-id": "ovsdb://uuid/b8dc0bfb-d22b-4938-a2e8-b0084d7bd8c1"
+
+The 'opendaylight-iid' entry can be removed from the Open_vSwitch table using
+the following command.
+
+ $ sudo ovs-vsctl remove open_vswitch . external-id "opendaylight-iid"
+
+==== OVSDB Changes by using OVSDB Southbound Config MD-SAL
+After the connection has been made to an OVSDB node, you can make changes to the
+OVSDB node by using the OVSDB Southbound Config MD-SAL. You can
+make CRUD operations by using the RESTCONF interface or by a plugin
+using the MD-SAL APIs. The following diagram illustrates the highlevel flow of
+events.
+
+.OVSDB Changes by using the Southbound Config MD-SAL
+image::ovsdb-sb-config-crud.jpg[width=500]
+
+Step 1::
+A change to the OVSDB Southbound Config MD-SAL is made. Changes include adding
+or deleting bridges and ports, or setting attributes of OVSDB nodes, bridges or
+ports.
+Step 2::
+The OVSDB Southbound provider receives notification of the changes made to the
+OVSDB Southbound Config MD-SAL data store.
+Step 3::
+As appropriate, OVSDB transactions are constructed and transmitted to the OVSDB
+node to update the OVSDB database on the OVSDB node.
+Step 4::
+The OVSDB node sends update messages to the OVSDB Southbound provider to
+indicate the changes made to the OVSDB nodes database.
+Step 5::
+The OVSDB Southbound provider maps the changes received from the OVSDB node
+into corresponding changes made to the OVSDB Southbound Operational
+MD-SAL data store.
+
+==== Detecting changes in OVSDB coming from outside OpenDaylight
+Changes to the OVSDB nodes database may also occur independently of OpenDaylight.
+OpenDaylight also receives notifications for these events and updates the
+Southbound operational MD-SAL. The following diagram illustrates the sequence
+of events.
+
+.OVSDB Changes made directly on the OVSDB node
+image::ovsdb-sb-oper-crud.jpg[width=500]
+
+Step 1::
+Changes are made to the OVSDB node outside of OpenDaylight (e.g. ovs-vsctl).
+Step 2::
+The OVSDB node constructs update messages to inform OpenDaylight of the changes
+made to its databases.
+Step 3::
+The OVSDB Southbound provider maps the OVSDB database changes to corresponding
+changes in the OVSDB Southbound operational MD-SAL data store.
+
+// ==== OpenFlow controller
+// Discussion of how the OpenFlow controller node is associated with the OVSDB
+// southbound model
==== OVSDB Model
-TBD
+The OVSDB Southbound MD-SAL operates using a YANG model which is based on the
+abstract topology node model found in the
+https://github.com/opendaylight/yangtools/blob/stable/lithium/model/ietf/ietf-topology/src/main/yang/network-topology%402013-10-21.yang[network topology model].
+
+The augmentations for the OVSDB Southbound MD-SAL are defined in the
+https://github.com/opendaylight/ovsdb/blob/stable/lithium/southbound/southbound-api/src/main/yang/ovsdb.yang[ovsdb.yang] file.
+
+There are three augmentations:
+
+*ovsdb-node-augmentation*::
+This augments the topology node and maps primarily to the Open_vSwitch table of
+the OVSDB schema. It contains the following attributes.
+ * *connection-info* - holds the local and remote IP address and TCP port numbers for the OpenDaylight to OVSDB node connections
+ * *db-version* - version of the OVSDB database
+ * *ovs-version* - version of OVS
+ * *list managed-node-entry* - a list of references to ovsdb-bridge-augmentation nodes, which are the OVS bridges managed by this OVSDB node
+ * *list datapath-type-entry* - a list of the datapath types supported by the OVSDB node (e.g. 'system', 'netdev') - depends on newer OVS versions
+ * *list interface-type-entry* - a list of the interface types supported by the OVSDB node (e.g. 'internal', 'vxlan', 'gre', 'dpdk', etc.) - depends on newer OVS verions
+ * *list openvswitch-external-ids* - a list of the key/value pairs in the Open_vSwitch table external_ids column
+ * *list openvswitch-other-config* - a list of the key/value pairs in the Open_vSwitch table other_config column
+*ovsdb-bridge-augmentation*::
+This augments the topology node and maps to an specific bridge in the OVSDB
+bridge table of the associated OVSDB node. It contains the following attributes.
+ * *bridge-uuid* - UUID of the OVSDB bridge
+ * *bridge-name* - name of the OVSDB bridge
+ * *bridge-openflow-node-ref* - a reference (instance-identifier) of the OpenFlow node associated with this bridge
+ * *list protocol-entry* - the version of OpenFlow protocol to use with the OpenFlow controller
+ * *list controller-entry* - a list of controller-uuid and is-connected status of the OpenFlow controllers associated with this bridge
+ * *datapath-id* - the datapath ID associated with this bridge on the OVSDB node
+ * *datapath-type* - the datapath type of this bridge
+ * *fail-mode* - the OVSDB fail mode setting of this bridge
+ * *flow-node* - a reference to the flow node corresponding to this bridge
+ * *managed-by* - a reference to the ovsdb-node-augmentation (OVSDB node) that is managing this bridge
+ * *list bridge-external-ids* - a list of the key/value pairs in the bridge table external_ids column for this bridge
+ * *list bridge-other-configs* - a list of the key/value pairs in the bridge table other_config column for this bridge
+*ovsdb-termination-point-augmentation*::
+This augments the topology termination point model. The OVSDB Southbound
+MD-SAL uses this model to represent both the OVSDB port and OVSDB interface for
+a given port/interface in the OVSDB schema. It contains the following
+attributes.
+ * *port-uuid* - UUID of an OVSDB port row
+ * *interface-uuid* - UUID of an OVSDB interface row
+ * *name* - name of the port
+ * *interface-type* - the interface type
+ * *list options* - a list of port options
+ * *ofport* - the OpenFlow port number of the interface
+ * *ofport_request* - the requested OpenFlow port number for the interface
+ * *vlan-tag* - the VLAN tag value
+ * *list trunks* - list of VLAN tag values for trunk mode
+ * *vlan-mode* - the VLAN mode (e.g. access, native-tagged, native-untagged, trunk)
+ * *list port-external-ids* - a list of the key/value pairs in the port table external_ids column for this port
+ * *list interface-external-ids* - a list of the key/value pairs in the interface table external_ids interface for this interface
+ * *list port-other-configs* - a list of the key/value pairs in the port table other_config column for this port
+ * *list interface-other-configs* - a list of the key/value pairs in the interface table other_config column for this interface
+
+=== Examples of OVSDB Southbound MD-SAL API
+
+==== Connect to an OVSDB Node
+This example RESTCONF command adds an OVSDB node object to the OVSDB
+Southbound configuration data store and attempts to connect to the OVSDB host
+located at the IP address 10.11.12.1 on TCP port 6640.
+
+ POST http://<host>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/
+ Content-Type: application/json
+ {
+ "node": [
+ {
+ "node-id": "ovsdb:HOST1",
+ "connection-info": {
+ "ovsdb:remote-ip": "10.11.12.1",
+ "ovsdb:remote-port": 6640
+ }
+ }
+ ]
+ }
+
+==== Query the OVSDB Southbound Configuration MD-SAL
+Following on from the previous example, if the OVSDB Southbound configuration
+MD-SAL is queried, the RESTCONF command and the resulting reply is similar
+to the following example.
+
+ GET http://<host>:8080/restconf/config/network-topology:network-topology/topology/ovsdb:1/
+ Application/json data in the reply
+ {
+ "topology": [
+ {
+ "topology-id": "ovsdb:1",
+ "node": [
+ {
+ "node-id": "ovsdb:HOST1",
+ "ovsdb:connection-info": {
+ "remote-port": 6640,
+ "remote-ip": "10.11.12.1"
+ }
+ }
+ ]
+ }
+ ]
+ }
-==== Tunnel Overlay Model
-TBD
+// ==== Query the OVSDB Southbound Operational MD-SAL
+// If the previous example POST command is successful in connecting to the OVSDB
+// node, then eventually the OVSDB Southbound operational MD-SAL is populated
+// with information received in an OVSDB update message from the OVSDB node. The
+// RESTCONF query and resulting reply is similar to the following example.
+//
+// http://<host>:8080/restconf/operational/network-topology:network-topology/topology/ovsdb:1/
+//
+// Application/json data in the reply
+// TBD - things not working well at time of writing
+//
+//
+//
+// ==== Add a bridge
+// TBD
+//
+// ==== Add a port
+// TBD
+//
+// ==== Set attributes
+// TBD
+//
+// ==== Delete examples
+// TBD
-=== API Reference Documentation
-TBD
+=== Reference Documentation
+http://openvswitch.org/ovs-vswitchd.conf.db.5.pdf[Openvswitch schema]
--- /dev/null
+== LISP Flow Mapping User Guide
+
+=== Overview
+
+The lispflowmapping-all feature enables the LISP Mapping Service in OpenDaylight.
+
+==== Locator/ID Separation Protocol
+
+http://tools.ietf.org/html/rfc6830[Locator/ID Separation Protocol (LISP)] is a
+technology that provides a flexible map-and-encap framework that can be used
+for overlay network applications such as data center network virtualization and
+Network Function Virtualization (NFV).
+
+LISP provides the following name spaces:
+
+* http://tools.ietf.org/html/rfc6830#page-6[Endpoint Identifiers (EIDs)]
+* http://tools.ietf.org/html/rfc6830#section-3[Routing Locators (RLOCs)]
+
+In a virtualization environment EIDs can be viewed as virtual address space and
+RLOCs can be viewed as physical network address space.
+
+The LISP framework decouples network control plane from the forwarding plane by
+providing:
+
+* A data plane that specifies how the virtualized network addresses are
+ encapsulated in addresses from the underlying physical network.
+* A control plane that stores the mapping of the virtual-to-physical address
+ spaces and the associated forwarding policies and serves this information to
+ the data plane on demand.
+
+Network programmability is achieved by programming forwarding policies such as
+transparent mobility, service chaining, and traffic engineering in the mapping
+system; where the data plane elements can fetch these policies on demand as new
+flows arrive. This chapter describes the LISP Flow Mapping project in
+OpenDaylight and how it can be used to enable advanced SDN and NFV use cases.
+
+LISP data plane Tunnel Routers are available at
+http://LISPmob.org/[LISPmob.org] in the open source community on the following
+platforms:
+
+* Linux
+* Android
+* OpenWRT
+
+For more details and support for LISP data plane software please visit
+http://LISPmob.org/[the LISPmob web site].
+
+==== LISP Flow Mapping Service
+
+The LISP Flow Mapping service provides LISP Mapping System services. This
+includes LISP Map-Server and LISP Map-Resolver services to store and serve
+mapping data to data plane nodes as well as to OpenDaylight applications.
+Mapping data can include mapping of virtual addresses to physical network
+address where the virtual nodes are reachable or hosted at. Mapping data can
+also include a variety of routing policies including traffic engineering and
+load balancing. To leverage this service, OpenDaylight applications and
+services can use the northbound REST API to define the mappings and policies in
+the LISP Mapping Service. Data plane devices capable of LISP control protocol
+can leverage this service through a southbound LISP plugin. LISP-enabled
+devices must be configured to use this OpenDaylight service as their Map Server
+and/or Map Resolver.
+
+The southbound LISP plugin supports the LISP control protocol (Map-Register,
+Map-Request, Map-Reply messages), and can also be used at register mappings in
+the OpenDaylight mapping service.
+
+=== LISP Flow Mapping Architecture
+
+The following figure shows the various LISP Flow Mapping modules.
+
+.LISP Mapping Service Internal Architecture
+
+image::lispflow-technical-arch-overview-helium.jpg["LISP Mapping Service Internal Architecture", width=460]
+
+A brief description of each module is as follows:
+
+* *DAO:* This layer separates the LISP logic from the database, so that we can
+separate the map server and map resolver from the specific implementation of
+the DHT (Distributed Hash Table). Currently we have an implementation of this
+layer with the controller cluster service as a DHT, but it can be switched to
+any other DHT and you only need to implement the ILISPDAO interface.
+
+* *Map Server:* This module processes the adding or registration of keys and
+ mappings. For a detailed specification of LISP Map Server, see
+ http://tools.ietf.org/search/rfc6830[LISP].
+* *Map Resolver:* This module receives and processes the mapping lookup queries
+ and provides the mappings to requester. For a detailed specification of LISP
+ Map Server, see http://tools.ietf.org/search/rfc6830[LISP].
+* *Northbound API:* This is part of the OpenDaylight northbound API. This
+ module enables defining key-EID associations as well as adding mapping
+ information through the Map Server. Key-EID associations can also be queried
+ via this API. The Northbound API also provides capability of querying the
+ mapping information for an EID prefix.
+* *Neutron:* This module implements the OpenDaylight Neutron Service APIs. It
+ provides integration between the LISP service and the OpenDaylight Neutron
+ service.
+* *NETCONF:* This module enables the LISP service to communicate to
+ NETCONF-enabled devices through OpenDaylight's NETCONF plugin.
+* *Java API:* The API module exposes the Map Server and Map Resolver
+ capabilities via Java API.
+* *LISP Southbound Plugin:* This plugin enables data plane devices that support
+ LISP control plane protocol (see LISP) to register and query mappings to the
+ LISP Flow Mapping via the LISP control plane protocol.
+
+
+=== Configuring LISP Flow Mapping
+
+In order to use the LISP mapping service for registering EID to RLOC mappings
+from NB or SB, keys have to be defined for the EID prefixes first. Once a key
+is defined for an EID prefix, it can be used to add mappings for that EID
+prefix multiple times. If the service is going to be used to process Map
+Register messages from the southbound LISP plugin, the same key must be used by
+the data plane device to create the authentication data in the Map-Register
+messages for the associated EID prefix.
+
+The +etc/custom.properties+ file in the Karaf distribution allows configuration
+of several OpenDaylight parameters. The LISP service has two properties that
+can be adjusted: +lisp.mappingOverwrite+ and +lisp.smr+.
+
+*lisp.mappingOverwrite* (default: 'true')::
+ Configures handling of mapping updates. When set to 'true' (default) a
+ mapping update (either through the southbound plugin via a Map-Register
+ message or through a northbound API PUT REST call) the existing RLOC set
+ associated to an EID prefix is overwritten. When set to 'false', the RLOCs
+ of the update are merged to the existing set.
+
+*lisp.smr* (default: 'false')::
+ Enables/disables the
+ http://tools.ietf.org/html/rfc6830#section-6.6.2[Solicit-Map-Request (SMR)]
+ functionality. SMR is a method to notify changes in an EID-to-RLOC mapping
+ to "subscribers". The LISP service considers all Map-Request's source RLOC
+ as a subscriber to the requested EID prefix, and will send an SMR control
+ message to that RLOC if the mapping changes.
+
+=== Tutorials
+
+This section provides a tutorial demonstrating various features in this service.
+
+==== Creating a LISP overlay
+
+This section provides instructions to set up a LISP network of three nodes (one
+"client" node and two "server" nodes) using LISPmob and Open vSwitch (OVS) as
+data plane LISP nodes and the LISP Flow Mapping project from OpenDaylight as
+the LISP programmable mapping system for the LISP network.
+
+===== Overview
+
+The steps shown below will demonstrate setting up a LISP network between a
+client and two servers. Then performing a failover between the two "server"
+nodes.
+
+===== Prerequisites
+
+NOTE: It is more convenient to use the Postman Chrome browser plugin to edit
+and send the requests. The project git repository hosts a collection of the
+requests that are used in this tutorial in the
++resources/tutorial/ODL_Summit_LISP_Demo.json+ file. You can import this file
+to Postman by following 'Collections->Import a collection->Import from URL' and
+then entering the following link:
++https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=blob_plain;f=resources/tutorial/ODL_Summit_LISP_Demo.json;hb=refs/heads/develop+.
+Alternatively, you can save the file on your machine, or if you have the
+repository checked out, you can import from there. You will need to define some
+variables to point to your OpenDaylight controller instance.
+
+NOTE: It is assumed that commands are executed as the 'root' user.
+
+NOTE: To set up a basic LISP network overlay (no fail-over) without dealing
+ with OVS, you can skip steps 7 and 8 and just use LISPmob as your
+ dataplane. If you do want to test fail-over, but not using OVS, skip
+ steps 7 and 8, but set up LISPmob on *server2* as well, with identical
+ configuration.
+
+===== Target Environment
+
+The three LISP data plane nodes and the LISP mapping system are assumed to be
+running in Linux virtual machines using the following IPv4 addresses on their
+eth0 interfaces (please adjust configuration files, JSON examples, etc.
+accordingly if you're using another addressing scheme):
+
+.Nodes in the tutorial
+[align="right",options="header"]
+|===
+| Node | Node Type | IP Address
+| *controller* | OpenDaylight | 10.33.12.32
+| *client* | LISPmob | 10.33.12.35
+| *server1* | LISPmob | 10.33.12.37
+| *server2* | Open vSwitch | 10.33.12.44
+|===
+
+Note: While the tutorial uses LISPmob and OVS as the data plane, they could be
+any LISP-enabled HW or SW router (commercial/open source).
+
+===== Instructions
+
+The below steps are using the command line tool cURL to talk to the LISP Flow
+Mapping northbound REST API. This is so that you can see the actual request
+URLs and body content on the page.
+
+. Install and run OpenDaylight Helium release on the controller VM. Please
+ follow the general OpenDaylight Helium Installation Guide for this step. Once
+ the OpenDaylight controller is running install the 'odl-openflowplugin-all',
+ 'odl-adsal-compatibility-all', 'odl-ovsdb-all', and 'odl-lispflowmapping-all'
+ features from the CLI:
+
+ feature:install odl-openflowplugin-all odl-adsal-compatibility-all odl-ovsdb-all odl-lispflowmapping-all
++
+NOTE: If you're not planning on using OVS you can skip the first three and
+install 'odl-lispflowmapping-all' only.
++
+It takes quite a while to load and initialize all features and their
+dependencies. It's worth running the command +log:tail+ in the Karaf console to
+see when is the log output winding down, and continue after that.
+
+. Install LISPmob on the *client* and *server1* VMs following the installation
+instructions https://github.com/LISPmob/lispmob#software-prerequisites[from the LISPmob README file].
+
+. Configure the LISPmob installations from the previous step. Starting from the
++lispd.conf.example+ file in the distribution, set the EID in each +lispd.conf+
+file from the IP address space selected for your virtual/LISP network. In this
+tutorial the EID of the *client* is set to 1.1.1.1/32, and that of *server1* to
+2.2.2.2/32. Set the RLOC interface in each +lispd.conf+. LISP will determine
+the RLOC (IP address of the corresponding VM) based on this interface. Set the
+Map-Resolver address to the IP address of the *controller*, and on the *client*
+the Map-Server too. On *server1* set the Map-Server to something else, so that
+it doesn't interfere with the mappings on the controller, since we're going to
+program them manually. Modify the "key" parameter in each +lispd.conf+ file to
+a key/password of your choice, 'asdf' in this tutorial. The
++resources/tutorial+ directory in the 'develop' branch of the project git
+repository has the files used in the tutorial checked in:
+https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=blob_plain;f=resources/tutorial/lispd.conf.client;hb=refs/heads/develop[lispd.conf.client]
+and https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=blob_plain;f=resources/tutorial/lispd.conf.server1;hb=refs/heads/develop[lispd.conf.server1].
+Copy the files to +/root/lispd.conf+ on the respective VMs.
+
+. Define a key and EID prefix association in OpenDaylight using the northbound
+API for both EIDs (1.1.1.1/32 and 2.2.2.2/32). Run the below commands on the
+*controller* (or any machine that can reach *controller*, by replacing
+'localhost' with the IP address of *controller*).
+
+ curl -u "admin":"admin" -H "Content-type: application/json" -X PUT \
+ http://localhost:8080/lispflowmapping/nb/v2/default/key \
+ --data @key1.json
+ curl -u "admin":"admin" -H "Content-type: application/json" -X PUT \
+ http://localhost:8080/lispflowmapping/nb/v2/default/key \
+ --data @key2.json
+
++
+where the content of the 'key1.json' and 'key2.json' files is the following
+(with different "ipAddress"):
++
+[source,json]
+----
+{
+ "key" : "asdf",
+ "maskLength" : 32,
+ "address" :
+ {
+ "ipAddress" : "1.1.1.1",
+ "afi" : 1
+ }
+}
+----
+
+. Verify that the key is added properly by requesting the following URL:
+
+ curl -u "admin":"admin" http://localhost:8080/lispflowmapping/nb/v2/default/key/0/1/1.1.1.1/32
+ curl -u "admin":"admin" http://localhost:8080/lispflowmapping/nb/v2/default/key/0/1/2.2.2.2/32
+
+. Run the lispd LISPmob daemon on the *client* and *server1* VMs:
+
+ lispd -f /root/lispd.conf
+
+. Prepare the OVS environment on *server2*:
+
+ .. Start the ovsdb-server and ovs-vswitchd daemons (or check that your
+ distribution's init scripts already started them)
+ .. Start listening for OVSDB manager connections on the standard 6640 TCP port:
+
+ ovs-vsctl set-manager "ptcp:6640"
+ ovs-vsctl show
+
++
+ .. Create a TAP port for communications with the guest VM. We'll have another
+ VM inside the *server2* VM, that will be set up with the 2.2.2.2/24 EID. It
+ also needs a ficticious gateway, and a static ARP entry for that gateway,
+ with any MAC address.
+
+ tunctl -t tap0
+ ifconfig tap0 up
+
++
+ .. Start the guest VM:
+
+ modprobe kvm
+ kvm -daemonize -vnc :0 -m 128 -net nic,macaddr=00:00:0C:15:C0:A1 \
+ -net tap,ifname=tap0,script=no,downscript=no \
+ -drive file=ubuntu.12-04.x86-64.20120425.static_ip_2.2.2.2.qcow2
+
++
+. Set up the OVS environment on *server2* using the OpenDaylight northbound API
+ .. Connect to the OVSDB management port from OpenDaylight:
+
+ curl -u "admin":"admin" -X PUT \
+ http://localhost:8080/controller/nb/v2/connectionmanager/node/server2/address/10.33.12.44/port/6640
+
++
+You can check if this and the next requests have the desired effect on OVS by
+running the following on *server2*
+
+ ovs-vsctl show
+
++
+It should now show the "Manager" connection as connected
+
+ .. Create the bridge +br0+:
+
+ curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
+ http://localhost:8080/controller/nb/v2/networkconfig/bridgedomain/bridge/OVS/server2/br0 -d "{}"
+
+ .. Add +tap0+ to +br0+:
+
+ curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
+ http://localhost:8080/controller/nb/v2/networkconfig/bridgedomain/port/OVS/server2/br0/tap0 -d "{}"
+
++
+ .. Add the +lisp0+ LISP tunneling virtual port to +br0+:
+
+ curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
+ http://localhost:8080/controller/nb/v2/networkconfig/bridgedomain/port/OVS/server2/br0/lisp0 -d @lisp0.json
++
+where 'lisp0.json' has the following content:
++
+[source,json]
+----
+{
+ "type": "tunnel",
+ "tunnel_type": "lisp",
+ "dest_ip": "10.33.12.35"
+}
+----
+The *dest_ip* parameter sets the tunnel destination to the *client* VM. This
+has to be done manually (from the controller), since OVS doesn't have a LISP
+control plane to fetch mappings.
+
+ .. We will now need to set up flows on +br0+ to to steer traffic received on
+ the LISP virtual port in OVS to the VM connected to +tap0+ and vice-versa.
+ For that we will need the node id of the bridge, which is based on its MAC
+ address, which is generated at creation time. So we look at the list of
+ connections on the controller:
+
+ curl -u "admin":"admin" http://localhost:8080/controller/nb/v2/connectionmanager/nodes
++
+The response should look similar to this:
++
+[literal]
+{"id":"00:00:62:71:36:30:7b:44","type":"OF"}]},{"id":"10.33.12.35","type":"LISP"},{"id":"server2","type":"OVS"}]}
++
+There are three types of nodes connected to OpenDaylight: one "OF" node (the
+OpenFlow connection to +br0+ on *server2*), one "LISP" node (the *client* VM
+sending LISP Map-Register control messages to the controller which is acting as
+a LISP Map-Server), and one "OVS" node (this is the OVSDB connection to
+*server2*). We will need the id of the "OF" node in order to set up flows.
+
+ .. The first flow will decapsulate traffic received from the client VM on
+ *server2* and send it to the guest VM through the +tap0+ port.
+
+ curl -u "admin":"admin" -H "Content-type: application/json" -X PUT \
+ http://localhost:8080/controller/nb/v2/flowprogrammer/default/node/OF/00:00:62:71:36:30:7b:44/staticFlow/Decap -d @flow_decap.json
++
+Make sure that the bridge id after the OF path component of the URL is the id
+from the previous step. It should also be the same on line 6 in
+'flow_decap.json' file (see below), which should have the MAC address of the
+KVM instance started on *server2* on line 11 (+SET_DL_DST+):
++
+[source,json]
+----
+{
+ "installInHw": "true",
+ "name": "Decap",
+ "node": {
+ "type": "OF",
+ "id": "00:00:62:71:36:30:7b:44"
+ },
+ "priority": "10",
+ "dlDst": "02:00:00:00:00:00",
+ "actions": [
+ "SET_DL_DST=00:00:0c:15:c0:a1",
+ "OUTPUT=1"
+ ]
+}
+----
+
+ .. The second flow will encapsulate traffic received from the guest VM on
+ *server2* through the +tap0+ port.
+
+ curl -u "admin":"admin" -H "Content-type: application/json" -X PUT \
+ http://localhost:8080/controller/nb/v2/flowprogrammer/default/node/OF/00:00:62:71:36:30:7b:44/staticFlow/Encap -d @flow_encap.json
++
+The 'flow_encap.json' file should look like this:
++
+[source,json]
+----
+{
+ "installInHw": "true",
+ "name": "Decap",
+ "node": {
+ "type": "OF",
+ "id": "00:00:62:71:36:30:7b:44"
+ },
+ "priority": "5",
+ "ingressPort": "1",
+ "etherType": "0x0800",
+ "vlanId": "0",
+ "nwDst": "1.1.1.1/32",
+ "actions": [
+ "OUTPUT=2"
+ ]
+}
+----
+
+ .. Check if the flows have been created correctly. First, in OpenDaylight
+
+ curl -u "admin":"admin" http://localhost:8080/controller/nb/v2/flowprogrammer/default
++
+And most importantly, on *server2*
+
+ ovs-ofctl dump-flows br0 -O OpenFlow13
+
+. The *client* LISPmob node should now register its EID-to-RLOC mapping in
+ OpenDaylight. To verify you can lookup the corresponding EIDs via the northbound API
+
+ curl -u "admin":"admin" http://localhost:8080/lispflowmapping/nb/v2/default/mapping/0/1/1.1.1.1/32
+
+ . Register the EID-to-RLOC mapping of the server EID 2.2.2.2/32 to the
+ controller, pointing to *server1* and *server2* with a higher priority for
+ *server1*
+
+ curl -u "admin":"admin" -H "Content-type: application/json" -X PUT \
+ http://localhost:8080/lispflowmapping/nb/v2/default/mapping \
+ -d @mapping.json
++
+where the 'mapping.json' file looks like this
++
+[source,json]
+----
+{
+"key" : "asdf",
+"mapregister" :
+ {
+ "proxyMapReply" : true,
+ "eidToLocatorRecords" :
+ [
+ {
+ "authoritative" : true,
+ "prefixGeneric" :
+ {
+ "ipAddress" : "2.2.2.2",
+ "afi" : 1
+ },
+ "mapVersion" : 0,
+ "maskLength" : 32,
+ "action" : "NoAction",
+ "locators" :
+ [
+ {
+ "multicastPriority" : 1,
+ "locatorGeneric" :
+ {
+ "ipAddress" : "10.33.12.37",
+ "afi" : 1
+ },
+ "routed" : true,
+ "multicastWeight" : 0,
+ "rlocProbed" : false,
+ "localLocator" : false,
+ "priority" : 126,
+ "weight" : 1
+ } ,
+ {
+ "multicastPriority" : 1,
+ "locatorGeneric" :
+ {
+ "ipAddress" : "10.33.12.44",
+ "afi" : 1
+ },
+ "routed" : true,
+ "multicastWeight" : 0,
+ "rlocProbed" : false,
+ "localLocator" : false,
+ "priority" : 127,
+ "weight" : 1
+ }
+ ],
+ "recordTtl" : 5
+ }
+ ],
+ "keyId" : 0
+ }
+}
+----
++
+Here the priority of the second RLOC (10.33.12.44 - *server2*) is 127, a higher
+numeric value than the priority of 10.33.12.37, which is 126. This policy is
+saying that *server1* is preferred to *server2* for reaching EID 2.2.2.2/32.
+Note that lower priority has higher preference in LISP.
+
+ . Verify the correct registration of the 2.2.2.2/32 EID:
+
+ curl -u "admin":"admin" http://localhost:8080/lispflowmapping/nb/v2/default/mapping/0/1/2.2.2.2/32
+
+ . Now the LISP network is up. To verify, log into the *client* VM and ping the server EID:
+
+ ping 2.2.2.2
+
+ . Let's test fail-over now. Suppose you had a service on *server1* which
+became unavailable, but *server1* itself is still reachable. LISP will not
+automatically fail over, even if the mapping for 2.2.2.2/32 has two locators,
+since both locators are still reachable and uses the one with the higher
+priority (lowest priority value). To force a failover, we need to set the
+priority of *server2* to a lower value. Using the file mapping.json above, swap
+the priority values between the two locators and repeat the request from step
+10. You can also repeat step 11 to see if the mapping is correctly registered.
+Not that the previous locators are still present, so you should see a list of
+four locators. If you leave the ping on, and monitor the traffic using
+wireshark you can see that the ping traffic will be diverted from *server1* to
+*server2*.
++
+With the default OpenDaylight configuration this may take some time, because
+the mapping stays in the *client* map-cache until the TTL expires. LISP has a
+http://tools.ietf.org/html/rfc6830#section-6.6.2[Solicit-Map-Request (SMR) mechanism]
+that can ask a LISP data plane element to update its mapping for a certain EID.
+This is disabled by default, and is controlled by the +lisp.smr+ variable in
++etc/custom.porperties+. When enabled, any mapping change from the northbound
+will trigger an SMR packet to all data plane elements that have requested the
+mapping in a certain time window.
+
+If you used the Postman collection, you will notice an "ELP" mapping. This is
+for supporting service chaining, but it requires a Re-encapsulating Tunnel
+Router (RTR). Support for RTR functionality in LISPmob is in progress, and we
+will update the tutorial to demonstrate service chaining when it becomes
+available.
+
+=== LISP Flow Mapping Support
+
+For support please contact the lispflowmapping project at:
+
+* Lisp Flow Mapping users mailing list: lispflowmapping-users@lists.opendaylight.org
+
+* Lisp Flow Mapping dev mailing list: lispflowmapping-dev@lists.opendaylight.org
+
+You can also reach us at the following channel on IRC:
+
+* #opendaylight-lispflowmapping on irc.freenode.net
+
+Additional information is also available on the wiki:
+
+* https://wiki.opendaylight.org/view/OpenDaylight_Lisp_Flow_Mapping:Main[Lisp Flow Mapping wiki]
+
+
Code Review / docs.git / commitdiff
