--- /dev/null
+LISP Flow Mapping User Guide
+============================
+
+Overview
+--------
+
+Locator/ID Separation Protocol
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`Locator/ID Separation Protocol
+(LISP) <http://tools.ietf.org/html/rfc6830>`__ 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:
+
+- `Endpoint Identifiers
+ (EIDs) <http://tools.ietf.org/html/rfc6830#page-6>`__
+
+- `Routing Locators
+ (RLOCs) <http://tools.ietf.org/html/rfc6830#section-3>`__
+
+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, 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
+`LISPmob.org <http://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
+`the LISPmob web site <http://LISPmob.org/>`__.
+
+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 to
+register mappings in the OpenDaylight mapping service.
+
+LISP Flow Mapping Architecture
+------------------------------
+
+The following figure shows the various LISP Flow Mapping modules.
+
+.. figure:: ./images/ODL_lfm_Be_component.jpg
+ :alt: LISP Mapping Service Internal Architecture
+
+ LISP Mapping Service Internal Architecture
+
+A brief description of each module is as follows:
+
+- **DAO (Data Access Object):** 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 mapping database.
+ Currently we have an implementation of this layer with an in-memory
+ HashMap, but it can be switched to any other key/value store and you
+ only need to implement the ILispDAO interface.
+
+- **Map Server:** This module processes the adding or registration of
+ authentication tokens (keys) and mappings. For a detailed
+ specification of LISP Map Server, see
+ `LISP <http://tools.ietf.org/search/rfc6830>`__.
+
+- **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
+ `LISP <http://tools.ietf.org/search/rfc6830>`__.
+
+- **RPC/RESTCONF:** This is the auto-generated RESTCONF-based
+ northbound API. This module enables defining key-EID associations as
+ well as adding mapping information through the Map Server. Key-EID
+ associations and mappings can also be queried via this API.
+
+- **GUI:** This module enables adding and querying the mapping service
+ through a GUI based on ODL DLUX.
+
+- **Neutron:** This module implements the OpenDaylight Neutron Service
+ APIs. It provides integration between the LISP service and the
+ OpenDaylight Neutron service, and thus OpenStack.
+
+- **Java API:** The API module exposes the Map Server and Map Resolver
+ capabilities via a Java API.
+
+- **LISP Proto:** This module includes LISP protocol dependent data
+ types and associated processing.
+
+- **In Memory DB:** This module includes the in memory database
+ implementation of the mapping service.
+
+- **LISP Southbound Plugin:** This plugin enables data plane devices
+ that support LISP control plane protocol (see
+ `LISP <http://tools.ietf.org/search/rfc6830>`__) 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 northbound or southbound, 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
+the following properties that can be adjusted:
+
+**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 `Solicit-Map-Request
+ (SMR) <http://tools.ietf.org/html/rfc6830#section-6.6.2>`__
+ 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.
+
+**lisp.elpPolicy** (default: *default*)
+ Configures how to build a Map-Reply southbound message from a
+ mapping containing an Explicit Locator Path (ELP) RLOC. It is used
+ for compatibility with dataplane devices that don’t understand the
+ ELP LCAF format. The *default* setting doesn’t alter the mapping,
+ returning all RLOCs unmodified. The *both* setting adds a new RLOC
+ to the mapping, with a lower priority than the ELP, that is the next
+ hop in the service chain. To determine the next hop, it searches the
+ source RLOC of the Map-Request in the ELP, and chooses the next hop,
+ if it exists, otherwise it chooses the first hop. The *replace*
+ setting adds a new RLOC using the same algorithm as the *both*
+ setting, but using the origin priority of the ELP RLOC, which is
+ removed from the mapping.
+
+**lisp.lookupPolicy** (default: *northboundFirst*)
+ Configures the mapping lookup algorithm. When set to
+ *northboundFirst* mappings programmed through the northbound API
+ will take precedence. If no northbound programmed mappings exist,
+ then the mapping service will return mappings registered through the
+ southbound plugin, if any exists. When set to
+ *northboundAndSouthbound* the mapping programmed by the northbound
+ is returned, updated by the up/down status of these mappings as
+ reported by the southbound (if existing).
+
+**lisp.mappingMerge** (default: *false*)
+ Configures the merge policy on the southbound registrations through
+ the LISP SB Plugin. When set to *false*, only the latest mapping
+ registered through the SB plugin is valid in the southbound mapping
+ database, independent of which device it came from. When set to
+ *true*, mappings for the same EID registered by different devices
+ are merged together and a union of the locators is maintained as the
+ valid mapping for that EID.
+
+Textual Conventions for LISP Address Formats
+--------------------------------------------
+
+In addition to the more common IPv4, IPv6 and MAC address data types,
+the LISP control plane supports arbitrary `Address Family
+Identifiers <http://www.iana.org/assignments/address-family-numbers>`__
+assigned by IANA, and in addition to those the `LISP Canoncal Address
+Format (LCAF) <https://tools.ietf.org/html/draft-ietf-lisp-lcaf>`__.
+
+The LISP Flow Mapping project in OpenDaylight implements support for
+many of these different address formats, the full list being summarized
+in the following table. While some of the address formats have well
+defined and widely used textual representation, many don’t. It became
+necessary to define a convention to use for text rendering of all
+implemented address types in logs, URLs, input fields, etc. The below
+table lists the supported formats, along with their AFI number and LCAF
+type, including the prefix used for disambiguation of potential overlap,
+and examples output.
+
++------------------+----------+----------+----------+----------------------------------+
+| Name | AFI | LCAF | Prefix | Text Rendering |
++==================+==========+==========+==========+==================================+
+| **No Address** | 0 | - | no: | No Address Present |
++------------------+----------+----------+----------+----------------------------------+
+| **IPv4 Prefix** | 1 | - | ipv4: | 192.0.2.0/24 |
++------------------+----------+----------+----------+----------------------------------+
+| **IPv6 Prefix** | 2 | - | ipv6: | 2001:db8::/32 |
++------------------+----------+----------+----------+----------------------------------+
+| **MAC Address** | 16389 | - | mac: | 00:00:5E:00:53:00 |
++------------------+----------+----------+----------+----------------------------------+
+| **Distinguished | 17 | - | dn: | stringAsIs |
+| Name** | | | | |
++------------------+----------+----------+----------+----------------------------------+
+| **AS Number** | 18 | - | as: | AS64500 |
++------------------+----------+----------+----------+----------------------------------+
+| **AFI List** | 16387 | 1 | list: | {192.0.2.1,192.0.2.2,2001:db8::1 |
+| | | | | } |
++------------------+----------+----------+----------+----------------------------------+
+| **Instance ID** | 16387 | 2 | - | [223] 192.0.2.0/24 |
++------------------+----------+----------+----------+----------------------------------+
+| **Application | 16387 | 4 | appdata: | 192.0.2.1!128!17!80-81!6667-7000 |
+| Data** | | | | |
++------------------+----------+----------+----------+----------------------------------+
+| **Explicit | 16387 | 10 | elp: | {192.0.2.1→192.0.2.2\|lps→192.0. |
+| Locator Path** | | | | 2.3} |
++------------------+----------+----------+----------+----------------------------------+
+| **Source/Destina | 16387 | 12 | srcdst: | 192.0.2.1/32\|192.0.2.2/32 |
+| tion | | | | |
+| Key** | | | | |
++------------------+----------+----------+----------+----------------------------------+
+| **Key/Value | 16387 | 15 | kv: | 192.0.2.1⇒192.0.2.2 |
+| Address Pair** | | | | |
++------------------+----------+----------+----------+----------------------------------+
+| **Service Path** | 16387 | N/A | sp: | 42(3) |
++------------------+----------+----------+----------+----------------------------------+
+
+Table: LISP Address Formats
+
+Please note that the forward slash character ``/`` typically separating
+IPv4 and IPv6 addresses from the mask length is transformed into ``%2f``
+when used in a URL.
+
+Karaf commands
+--------------
+
+In this section we will discuss two types of Karaf commands: built-in,
+and LISP specific. Some built-in commands are quite useful, and are
+needed for the tutorial, so they will be discussed here. A reference of
+all LISP specific commands, added by the LISP Flow Mapping project is
+also included. They are useful mostly for debugging.
+
+Useful built-in commands
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+``help``
+ Lists all available command, with a short description of each.
+
+``help <command_name>``
+ Show detailed help about a specific command.
+
+``feature:list [-i]``
+ Show all locally available features in the Karaf container. The
+ ``-i`` option lists only features that are currently installed. It
+ is possible to use ``| grep`` to filter the output (for all
+ commands, not just this one).
+
+``feature:install <feature_name>``
+ Install feature ``feature_name``.
+
+``log:set <level> <class>``
+ Set the log level for ``class`` to ``level``. The default log level
+ for all classes is INFO. For debugging, or learning about LISP
+ internals it is useful to run
+ ``log:set TRACE org.opendaylight.lispflowmapping`` right after Karaf
+ starts up.
+
+``log:display``
+ Outputs the log file to the console, and returns control to the
+ user.
+
+``log:tail``
+ Continuously shows log output, requires ``Ctrl+C`` to return to the
+ console.
+
+LISP specific commands
+~~~~~~~~~~~~~~~~~~~~~~
+
+The available lisp commands can always be obtained by
+``help mappingservice``. Currently they are:
+
+``mappingservice:addkey``
+ Add the default password ``password`` for the IPv4 EID prefix
+ 0.0.0.0/0 (all addresses). This is useful when experimenting with
+ southbound devices, and using the REST interface would be combersome
+ for whatever reason.
+
+``mappingservice:mappings``
+ Show the list of all mappings stored in the internal non-persistent
+ data store (the DAO), listing the full data structure. The output is
+ not human friendly, but can be used for debugging.
+
+LISP Flow Mapping Karaf Features
+--------------------------------
+
+LISP Flow Mapping has the following Karaf features that can be installed
+from the Karaf console:
+
+``odl-lispflowmapping-msmr``
+ This includes the core features required to use the LISP Flow
+ Mapping Service such as mapping service and the LISP southbound
+ plugin.
+
+``odl-lispflowmapping-ui``
+ This includes the GUI module for the LISP Mapping Service.
+
+``odl-lispflowmapping-neutron``
+ This is the experimental Neutron provider module for LISP mapping
+ service.
+
+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 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
+^^^^^^^^^^^^^
+
+- **OpenDaylight Beryllium**
+
+- **The Postman Chrome App**: the most convenient way to follow along
+ this tutorial is to use the `Postman Chrome
+ App <https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en>`__
+ 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/Beryllium_Tutorial.json.postman_collection``
+ file. You can import this file to Postman by clicking *Import* at the
+ top, choosing *Download from link* and then entering the following
+ URL:
+ ``https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=blob_plain;f=resources/tutorial/Beryllium_Tutorial.json.postman_collection;hb=refs/heads/stable/beryllium``.
+ 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 create a new Postman Environment and define some variables within:
+ ``controllerHost`` set to the hostname or IP address of the machine
+ running the ODL instance, and ``restconfPort`` to 8181, if you didn’t
+ modify the default controller settings.
+
+- **LISPmob version 0.5.x** The README.md lists the dependencies needed
+ to build it from source.
+
+- **A virtualization platform**
+
+Target Environment
+^^^^^^^^^^^^^^^^^^
+
+The three LISP data plane nodes and the LISP mapping system are assumed
+to be running in Linux virtual machines, which have the ``eth0``
+interface in NAT mode to allow outside internet access and ``eth1``
+connected to a host-only network, with the following IP addresses
+(please adjust configuration files, JSON examples, etc. accordingly if
+you’re using another addressing scheme):
+
++--------------------------+--------------------------+--------------------------+
+| Node | Node Type | IP Address |
++==========================+==========================+==========================+
+| **controller** | OpenDaylight | 192.168.16.11 |
++--------------------------+--------------------------+--------------------------+
+| **client** | LISPmob | 192.168.16.30 |
++--------------------------+--------------------------+--------------------------+
+| **server1** | LISPmob | 192.168.16.31 |
++--------------------------+--------------------------+--------------------------+
+| **server2** | LISPmob | 192.168.16.32 |
++--------------------------+--------------------------+--------------------------+
+| **service-node** | LISPmob | 192.168.16.33 |
++--------------------------+--------------------------+--------------------------+
+
+Table: Nodes in the tutorial
+
+.. note::
+
+ While the tutorial uses LISPmob as the data plane, it could be any
+ LISP-enabled hardware or software router (commercial/open source).
+
+Instructions
+^^^^^^^^^^^^
+
+The below steps use the command line tool cURL to talk to the LISP Flow
+Mapping RPC REST API. This is so that you can see the actual request
+URLs and body content on the page.
+
+1. Install and run OpenDaylight Beryllium release on the controller VM.
+ Please follow the general OpenDaylight Beryllium Installation Guide
+ for this step. Once the OpenDaylight controller is running install
+ the *odl-lispflowmapping-msmr* feature from the Karaf CLI:
+
+ ::
+
+ feature:install odl-lispflowmapping-msmr
+
+ 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 the log output is winding down, and
+ continue with the tutorial after that.
+
+2. Install LISPmob on the **client**, **server1**, **server2**, and
+ **service-node** VMs following the installation instructions `from
+ the LISPmob README
+ file <https://github.com/LISPmob/lispmob#software-prerequisites>`__.
+
+3. 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** and
+ **server2** to 2.2.2.2/32.
+
+4. Set the RLOC interface to ``eth1`` in each ``lispd.conf`` file. LISP
+ will determine the RLOC (IP address of the corresponding VM) based
+ on this interface.
+
+5. Set the Map-Resolver address to the IP address of the
+ **controller**, and on the **client** the Map-Server too. On
+ **server1** and **server2** 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.
+
+6. Modify the "key" parameter in each ``lispd.conf`` file to a
+ key/password of your choice (*password* in this tutorial).
+
+ .. note::
+
+ The ``resources/tutorial`` directory in the *stable/beryllium*
+ 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=tree;f=resources/tutorial;hb=refs/heads/stable/beryllium>`__,
+ so you can just copy the files to ``/root/lispd.conf`` on the
+ respective VMs. You will also find the JSON files referenced
+ below in the same directory.
+
+7. Define a key and EID prefix association in OpenDaylight using the
+ RPC REST API for the **client** EID (1.1.1.1/32) to allow
+ registration from the southbound. Since the mappings for the server
+ EID will be configured from the REST API, no such association is
+ necessary. Run the below command 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 POST \
+ http://localhost:8181/restconf/operations/odl-mappingservice:add-key \
+ --data @add-key.json
+
+ where the content of the *add-key.json* file is the following:
+
+ .. code:: json
+
+ {
+ "input": {
+ "eid": {
+ "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
+ "ipv4-prefix": "1.1.1.1/32"
+ },
+ "mapping-authkey": {
+ "key-string": "password",
+ "key-type": 1
+ }
+ }
+ }
+
+8. Verify that the key is added properly by requesting the following
+ URL:
+
+ ::
+
+ curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
+ http://localhost:8181/restconf/operations/odl-mappingservice:get-key \
+ --data @get1.json
+
+ where the content of the *get1.json* file can be derived from the
+ *add-key.json* file by removing the *mapping-authkey* field. The
+ output the above invocation should look like this:
+
+ ::
+
+ {"output":{"mapping-authkey":{"key-type":1,"key-string":"password"}}}
+
+9. Run the ``lispd`` LISPmob daemon on all VMs:
+
+ ::
+
+ lispd -f /root/lispd.conf
+
+10. The **client** LISPmob node should now register its EID-to-RLOC
+ mapping in OpenDaylight. To verify you can lookup the corresponding
+ EIDs via the REST API
+
+ ::
+
+ curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
+ http://localhost:8181/restconf/operations/odl-mappingservice:get-mapping \
+ --data @get1.json
+
+ An alternative way for retrieving mappings from ODL using the
+ southbound interface is using the
+ ```lig`` <https://github.com/davidmeyer/lig>`__ open source tool.
+
+11. 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 POST \
+ http://localhost:8181/restconf/operations/odl-mappingservice:add-mapping \
+ --data @mapping.json
+
+ where the *mapping.json* file looks like this:
+
+ .. code:: json
+
+ {
+ "input": {
+ "mapping-record": {
+ "recordTtl": 1440,
+ "action": "NoAction",
+ "authoritative": true,
+ "eid": {
+ "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
+ "ipv4-prefix": "2.2.2.2/32"
+ },
+ "LocatorRecord": [
+ {
+ "locator-id": "server1",
+ "priority": 1,
+ "weight": 1,
+ "multicastPriority": 255,
+ "multicastWeight": 0,
+ "localLocator": true,
+ "rlocProbed": false,
+ "routed": true,
+ "rloc": {
+ "address-type": "ietf-lisp-address-types:ipv4-afi",
+ "ipv4": "192.168.16.31"
+ }
+ },
+ {
+ "locator-id": "server2",
+ "priority": 2,
+ "weight": 1,
+ "multicastPriority": 255,
+ "multicastWeight": 0,
+ "localLocator": true,
+ "rlocProbed": false,
+ "routed": true,
+ "rloc": {
+ "address-type": "ietf-lisp-address-types:ipv4-afi",
+ "ipv4": "192.168.16.32"
+ }
+ }
+ ]
+ }
+ }
+ }
+
+ Here the priority of the second RLOC (192.168.16.32 - **server2**)
+ is 2, a higher numeric value than the priority of 192.168.16.31,
+ which is 1. This policy is saying that **server1** is preferred to
+ **server2** for reaching EID 2.2.2.2/32. Note that lower priority
+ value has higher preference in LISP.
+
+12. Verify the correct registration of the 2.2.2.2/32 EID:
+
+ ::
+
+ curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
+ http://localhost:8181/restconf/operations/odl-mappingservice:get-mapping \
+ --data @get2.json
+
+ where *get2.json* can be derived from *get1.json* by changing the
+ content of the *Ipv4Address* field from *1.1.1.1* to *2.2.2.2*.
+
+13. Now the LISP network is up. To verify, log into the **client** VM
+ and ping the server EID:
+
+ ::
+
+ ping 2.2.2.2
+
+14. 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 (lines 14 and 28 in *mapping.json*)
+ and repeat the request from step 11. You can also repeat step 12 to
+ see if the mapping is correctly registered. If you leave the ping
+ on, and monitor the traffic using wireshark, you can see that the
+ ping traffic to 2.2.2.2 will be diverted from the **server1** RLOC
+ to the **server2** RLOC.
+
+ With the default OpenDaylight configuration the failover should be
+ near instantaneous (we observed 3 lost pings in the worst case),
+ because of the LISP `Solicit-Map-Request (SMR)
+ mechanism <http://tools.ietf.org/html/rfc6830#section-6.6.2>`__ that
+ can ask a LISP data plane element to update its mapping for a
+ certain EID (enabled by default). It is controlled by the
+ ``lisp.smr`` variable in ``etc/custom.porperties``. When enabled,
+ any mapping change from the RPC interface will trigger an SMR packet
+ to all data plane elements that have requested the mapping in the
+ last 24 hours (this value was chosen because it’s the default TTL of
+ Cisco IOS xTR mapping registrations). If disabled, ITRs keep their
+ mappings until the TTL specified in the Map-Reply expires.
+
+15. To add a service chain into the path from the client to the server,
+ we can use an Explicit Locator Path, specifying the **service-node**
+ as the first hop and **server1** (or **server2**) as the second hop.
+ The following will achieve that:
+
+ ::
+
+ curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
+ http://localhost:8181/restconf/operations/odl-mappingservice:add-mapping \
+ --data @elp.json
+
+ where the *elp.json* file is as follows:
+
+ .. code:: json
+
+ {
+ "input": {
+ "mapping-record": {
+ "recordTtl": 1440,
+ "action": "NoAction",
+ "authoritative": true,
+ "eid": {
+ "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
+ "ipv4-prefix": "2.2.2.2/32"
+ },
+ "LocatorRecord": [
+ {
+ "locator-id": "ELP",
+ "priority": 1,
+ "weight": 1,
+ "multicastPriority": 255,
+ "multicastWeight": 0,
+ "localLocator": true,
+ "rlocProbed": false,
+ "routed": true,
+ "rloc": {
+ "address-type": "ietf-lisp-address-types:explicit-locator-path-lcaf",
+ "explicit-locator-path": {
+ "hop": [
+ {
+ "hop-id": "service-node",
+ "address": "192.168.16.33",
+ "lrs-bits": "strict"
+ },
+ {
+ "hop-id": "server1",
+ "address": "192.168.16.31",
+ "lrs-bits": "strict"
+ }
+ ]
+ }
+ }
+ }
+ ]
+ }
+ }
+ }
+
+ After the mapping for 2.2.2.2/32 is updated with the above, the ICMP
+ traffic from **client** to **server1** will flow through the
+ **service-node**. You can confirm this in the LISPmob logs, or by
+ sniffing the traffic on either the **service-node** or **server1**.
+ Note that service chains are unidirectional, so unless another ELP
+ mapping is added for the return traffic, packets will go from
+ **server1** to **client** directly.
+
+16. Suppose the **service-node** is actually a firewall, and traffic is
+ diverted there to support access control lists (ACLs). In this
+ tutorial that can be emulated by using ``iptables`` firewall rules
+ in the **service-node** VM. To deny traffic on the service chain
+ defined above, the following rule can be added:
+
+ ::
+
+ iptables -A OUTPUT --dst 192.168.16.31 -j DROP
+
+ The ping from the **client** should now have stopped.
+
+ In this case the ACL is done on the destination RLOC. There is an
+ effort underway in the LISPmob community to allow filtering on EIDs,
+ which is the more logical place to apply ACLs.
+
+17. To delete the rule and restore connectivity on the service chain,
+ delete the ACL by issuing the following command:
+
+ ::
+
+ iptables -D OUTPUT --dst 192.168.16.31 -j DROP
+
+ which should restore connectivity.
+
+LISP Flow Mapping Support
+-------------------------
+
+For support the lispflowmapping project can be reached by emailing the
+developer mailing list: lispflowmapping-dev@lists.opendaylight.org or on
+the #opendaylight-lispflowmapping IRC channel on irc.freenode.net.
+
+Additional information is also available on the `Lisp Flow Mapping
+wiki <https://wiki.opendaylight.org/view/OpenDaylight_Lisp_Flow_Mapping:Main>`__
+
+Clustering in LISP Flow Mapping
+-------------------------------
+
+Documentation regarding setting up a 3-node OpenDaylight cluster is
+described at following `odl wiki
+page <https://wiki.opendaylight.org/view/Running_and_testing_an_OpenDaylight_Cluster#Three-node_cluster>`__.
+
+To turn on clustering in LISP Flow Mapping it is necessary:
+
+- run script **deploy.py** script. This script is in
+ `integration-test <https://git.opendaylight.org/gerrit/integration/test>`__
+ project placed at *tools/clustering/cluster-deployer/deploy.py*. A
+ whole deploy.py command can looks like:
+
+.. raw:: html
+
+ <div class="informalexample">
+
+| {path\_to\_integration\_test\_project}/tools/clustering/cluster-deployer/**deploy.py**
+| --**distribution** {path\_to\_distribution\_in\_zip\_format}
+| --**rootdir** {dir\_at\_remote\_host\_where\_copy\_odl\_distribution}
+| --**hosts** {ip1},{ip2},{ip3}
+| --**clean**
+| --**template** lispflowmapping
+| --**rf** 3
+| --**user** {user\_name\_of\_remote\_hosts}
+| --**password** {password\_to\_remote\_hosts}
+
+.. raw:: html
+
+ </div>
+
+| Running this script will cause that specified **distribution** to be
+ deployed to remote **hosts** specified through their IP adresses with
+ using credentials (**user** and **password**). The distribution will
+ be copied to specified **rootdir**. As part of the deployment, a
+ **template** which contains a set of controller files which are
+ different from standard ones. In this case it is specified in
+| *{path\_to\_integration\_test\_project}/tools/clustering/cluster-deployer/lispflowmapping*
+ directory.
+| Lispflowmapping templates are part of integration-test project. There
+ are 5 template files:
+
+- akka.conf.template
+
+- jolokia.xml.template
+
+- module-shards.conf.template
+
+- modules.conf.template
+
+- org.apache.karaf.features.cfg.template
+
+After copying the distribution, it is unzipped and started on all of
+specified **hosts** in cluster aware manner.
+
+Remarks
+~~~~~~~
+
+It is necessary to have:
+
+- **unzip** program installed on all of the host
+
+- set all remote hosts /etc/sudoers files to not **requiretty** (should
+ only matter on debian hosts)
+
== LISP Flow Mapping User Guide
-=== Overview
-
-==== 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, 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 to 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::ODL_lfm_Be_component.jpg["LISP Mapping Service Internal Architecture", width=460]
-
-A brief description of each module is as follows:
-
-* *DAO (Data Access Object):* 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 mapping database. Currently we have an
- implementation of this layer with an in-memory HashMap, but it can be switched
- to any other key/value store and you only need to implement the ILispDAO
- interface.
-
-* *Map Server:* This module processes the adding or registration of
- authentication tokens (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].
-* *RPC/RESTCONF:* This is the auto-generated RESTCONF-based northbound API. This
- module enables defining key-EID associations as well as adding mapping
- information through the Map Server. Key-EID associations and mappings can also
- be queried via this API.
-* *GUI:* This module enables adding and querying the mapping service through a
- GUI based on ODL DLUX.
-* *Neutron:* This module implements the OpenDaylight Neutron Service APIs. It
- provides integration between the LISP service and the OpenDaylight Neutron
- service, and thus OpenStack.
-* *Java API:* The API module exposes the Map Server and Map Resolver
- capabilities via a Java API.
-* *LISP Proto:* This module includes LISP protocol dependent data types and
- associated processing.
-* *In Memory DB:* This module includes the in memory database implementation of
- the mapping service.
-* *LISP Southbound Plugin:* This plugin enables data plane devices that support
- LISP control plane protocol (see http://tools.ietf.org/search/rfc6830[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 northbound or southbound, 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 the following properties
-that can be adjusted:
-
-*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.
-
-*lisp.elpPolicy* (default: 'default')::
- Configures how to build a Map-Reply southbound message from a mapping
- containing an Explicit Locator Path (ELP) RLOC. It is used for
- compatibility with dataplane devices that don't understand the ELP LCAF
- format. The 'default' setting doesn't alter the mapping, returning all
- RLOCs unmodified. The 'both' setting adds a new RLOC to the mapping, with
- a lower priority than the ELP, that is the next hop in the service chain.
- To determine the next hop, it searches the source RLOC of the Map-Request
- in the ELP, and chooses the next hop, if it exists, otherwise it chooses
- the first hop. The 'replace' setting adds a new RLOC using the same
- algorithm as the 'both' setting, but using the origin priority of the ELP
- RLOC, which is removed from the mapping.
-*lisp.lookupPolicy* (default: 'northboundFirst')::
- Configures the mapping lookup algorithm. When set to 'northboundFirst'
- mappings programmed through the northbound API will take precedence. If
- no northbound programmed mappings exist, then the mapping service will
- return mappings registered through the southbound plugin, if any exists.
- When set to 'northboundAndSouthbound' the mapping programmed by the
- northbound is returned, updated by the up/down status of these mappings
- as reported by the southbound (if existing).
-*lisp.mappingMerge* (default: 'false')::
- Configures the merge policy on the southbound registrations through the
- LISP SB Plugin. When set to 'false', only the latest mapping registered
- through the SB plugin is valid in the southbound mapping database,
- independent of which device it came from. When set to 'true', mappings
- for the same EID registered by different devices are merged together and
- a union of the locators is maintained as the valid mapping for that EID.
-
-=== Textual Conventions for LISP Address Formats
-
-In addition to the more common IPv4, IPv6 and MAC address data types, the LISP
-control plane supports arbitrary
-http://www.iana.org/assignments/address-family-numbers[Address Family
-Identifiers] assigned by IANA, and in addition to those the
-https://tools.ietf.org/html/draft-ietf-lisp-lcaf[LISP Canoncal Address Format
-(LCAF)].
-
-The LISP Flow Mapping project in OpenDaylight implements support for many of
-these different address formats, the full list being summarized in the
-following table. While some of the address formats have well defined and
-widely used textual representation, many don't. It became necessary to define
-a convention to use for text rendering of all implemented address types in
-logs, URLs, input fields, etc. The below table lists the supported formats,
-along with their AFI number and LCAF type, including the prefix used for
-disambiguation of potential overlap, and examples output.
-
-.LISP Address Formats
-[align="right",options="header",cols="<2s,>,>,<,<4l"]
-|=====
-| Name | AFI | LCAF | Prefix | Text Rendering
-| No Address | 0 | - | no: | No Address Present
-| IPv4 Prefix | 1 | - | ipv4: | 192.0.2.0/24
-| IPv6 Prefix | 2 | - | ipv6: | 2001:db8::/32
-| MAC Address | 16389 | - | mac: | 00:00:5E:00:53:00
-| Distinguished Name | 17 | - | dn: | stringAsIs
-| AS Number | 18 | - | as: | AS64500
-| AFI List | 16387 | 1 | list: | {192.0.2.1,192.0.2.2,2001:db8::1}
-| Instance ID | 16387 | 2 | - | [223] 192.0.2.0/24
-| Application Data | 16387 | 4 | appdata: | 192.0.2.1!128!17!80-81!6667-7000
-| Explicit Locator Path | 16387 | 10 | elp: | {192.0.2.1->192.0.2.2\|lps->192.0.2.3}
-| Source/Destination Key | 16387 | 12 | srcdst: | 192.0.2.1/32\|192.0.2.2/32
-| Key/Value Address Pair | 16387 | 15 | kv: | 192.0.2.1=>192.0.2.2
-| Service Path | 16387 | N/A | sp: | 42(3)
-|=====
-
-Please note that the forward slash character `/` typically separating IPv4 and
-IPv6 addresses from the mask length is transformed into `%2f` when used in a
-URL.
-
-=== Karaf commands
-
-In this section we will discuss two types of Karaf commands: built-in, and
-LISP specific. Some built-in commands are quite useful, and are needed for the
-tutorial, so they will be discussed here. A reference of all LISP specific
-commands, added by the LISP Flow Mapping project is also included. They are
-useful mostly for debugging.
-
-==== Useful built-in commands
-
-+help+::
- Lists all available command, with a short description of each.
-
-+help <command_name>+::
- Show detailed help about a specific command.
-
-+feature:list [-i]+::
- Show all locally available features in the Karaf container. The `-i`
- option lists only features that are currently installed. It is possible to
- use `| grep` to filter the output (for all commands, not just this one).
-
-+feature:install <feature_name>+::
- Install feature `feature_name`.
-
-+log:set <level> <class>+::
- Set the log level for `class` to `level`. The default log level for all
- classes is INFO. For debugging, or learning about LISP internals it is
- useful to run `log:set TRACE org.opendaylight.lispflowmapping` right after
- Karaf starts up.
-
-+log:display+::
- Outputs the log file to the console, and returns control to the user.
-
-+log:tail+::
- Continuously shows log output, requires `Ctrl+C` to return to the console.
-
-==== LISP specific commands
-
-The available lisp commands can always be obtained by `help mappingservice`.
-Currently they are:
-
-+mappingservice:addkey+::
- Add the default password `password` for the IPv4 EID prefix 0.0.0.0/0 (all
- addresses). This is useful when experimenting with southbound devices,
- and using the REST interface would be combersome for whatever reason.
-
-+mappingservice:mappings+::
- Show the list of all mappings stored in the internal non-persistent data
- store (the DAO), listing the full data structure. The output is not human
- friendly, but can be used for debugging.
-
-
-=== LISP Flow Mapping Karaf Features
-
-LISP Flow Mapping has the following Karaf features that can be installed from
-the Karaf console:
-
-+odl-lispflowmapping-msmr+::
- This includes the core features required to use the LISP Flow Mapping Service
- such as mapping service and the LISP southbound plugin.
-
-+odl-lispflowmapping-ui+::
- This includes the GUI module for the LISP Mapping Service.
-
-+odl-lispflowmapping-neutron+::
- This is the experimental Neutron provider module for LISP mapping service.
-
-
-=== 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 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
-
-* *OpenDaylight Beryllium*
-* *The Postman Chrome App*: the most convenient way to follow along this
- tutorial is to use the
- https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en[Postman
- Chrome App] 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/Beryllium_Tutorial.json.postman_collection+ file. You can
- import this file to Postman by clicking 'Import' at the top, choosing
- 'Download from link' and then entering the following URL:
- +https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=blob_plain;f=resources/tutorial/Beryllium_Tutorial.json.postman_collection;hb=refs/heads/stable/beryllium+.
- 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 create a
- new Postman Environment and define some variables within: +controllerHost+
- set to the hostname or IP address of the machine running the ODL instance,
- and +restconfPort+ to 8181, if you didn't modify the default controller
- settings.
-* *LISPmob version 0.5.x* The README.md lists the dependencies needed to
- build it from source.
-* *A virtualization platform*
-
-===== Target Environment
-
-The three LISP data plane nodes and the LISP mapping system are assumed to be
-running in Linux virtual machines, which have the +eth0+ interface in NAT mode
-to allow outside internet access and +eth1+ connected to a host-only network,
-with the following IP addresses (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 | 192.168.16.11
-| *client* | LISPmob | 192.168.16.30
-| *server1* | LISPmob | 192.168.16.31
-| *server2* | LISPmob | 192.168.16.32
-| *service-node* | LISPmob | 192.168.16.33
-|===
-
-NOTE: While the tutorial uses LISPmob as the data plane, it could be any
- LISP-enabled hardware or software router (commercial/open source).
-
-===== Instructions
-
-The below steps use the command line tool cURL to talk to the LISP Flow
-Mapping RPC REST API. This is so that you can see the actual request URLs and
-body content on the page.
-
- . Install and run OpenDaylight Beryllium release on the controller VM. Please
- follow the general OpenDaylight Beryllium Installation Guide for this step.
- Once the OpenDaylight controller is running install the
- 'odl-lispflowmapping-msmr' feature from the Karaf CLI:
-
- feature:install odl-lispflowmapping-msmr
-+
-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 the log output is winding down, and continue with the tutorial
-after that.
-
- . Install LISPmob on the *client*, *server1*, *server2*, and *service-node*
- 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* and *server2* to 2.2.2.2/32.
-
- . Set the RLOC interface to +eth1+ in each +lispd.conf+ file. 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* and *server2* 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 ('password' in this tutorial).
-+
-NOTE: The +resources/tutorial+ directory in the 'stable/beryllium' branch of the
- project git repository has the files used in the tutorial
- https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=tree;f=resources/tutorial;hb=refs/heads/stable/beryllium[checked
- in], so you can just copy the files to +/root/lispd.conf+ on the
- respective VMs. You will also find the JSON files referenced below in
- the same directory.
-+
- . Define a key and EID prefix association in OpenDaylight using the RPC REST
- API for the *client* EID (1.1.1.1/32) to allow registration from the
- southbound. Since the mappings for the server EID will be configured from
- the REST API, no such association is necessary. Run the below command 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 POST \
- http://localhost:8181/restconf/operations/odl-mappingservice:add-key \
- --data @add-key.json
-
-+
-where the content of the 'add-key.json' file is the following:
-+
-[source,json]
-----
-{
- "input": {
- "eid": {
- "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
- "ipv4-prefix": "1.1.1.1/32"
- },
- "mapping-authkey": {
- "key-string": "password",
- "key-type": 1
- }
- }
-}
-----
-
- . Verify that the key is added properly by requesting the following URL:
-
- curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
- http://localhost:8181/restconf/operations/odl-mappingservice:get-key \
- --data @get1.json
-
-+
-where the content of the 'get1.json' file can be derived from the
-'add-key.json' file by removing the 'mapping-authkey' field. The output the
-above invocation should look like this:
-
- {"output":{"mapping-authkey":{"key-type":1,"key-string":"password"}}}
-
- . Run the +lispd+ LISPmob daemon on all VMs:
-
- lispd -f /root/lispd.conf
-
- . The *client* LISPmob node should now register its EID-to-RLOC mapping in
- OpenDaylight. To verify you can lookup the corresponding EIDs via the REST
- API
-
- curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
- http://localhost:8181/restconf/operations/odl-mappingservice:get-mapping \
- --data @get1.json
-
-+
-An alternative way for retrieving mappings from ODL using the southbound
-interface is using the https://github.com/davidmeyer/lig[+lig+] open source
-tool.
-
- . 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 POST \
- http://localhost:8181/restconf/operations/odl-mappingservice:add-mapping \
- --data @mapping.json
-+
-where the 'mapping.json' file looks like this:
-+
-[source,json]
-----
-{
- "input": {
- "mapping-record": {
- "recordTtl": 1440,
- "action": "NoAction",
- "authoritative": true,
- "eid": {
- "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
- "ipv4-prefix": "2.2.2.2/32"
- },
- "LocatorRecord": [
- {
- "locator-id": "server1",
- "priority": 1,
- "weight": 1,
- "multicastPriority": 255,
- "multicastWeight": 0,
- "localLocator": true,
- "rlocProbed": false,
- "routed": true,
- "rloc": {
- "address-type": "ietf-lisp-address-types:ipv4-afi",
- "ipv4": "192.168.16.31"
- }
- },
- {
- "locator-id": "server2",
- "priority": 2,
- "weight": 1,
- "multicastPriority": 255,
- "multicastWeight": 0,
- "localLocator": true,
- "rlocProbed": false,
- "routed": true,
- "rloc": {
- "address-type": "ietf-lisp-address-types:ipv4-afi",
- "ipv4": "192.168.16.32"
- }
- }
- ]
- }
- }
-}
-----
-+
-Here the priority of the second RLOC (192.168.16.32 - *server2*) is 2, a higher
-numeric value than the priority of 192.168.16.31, which is 1. This policy is
-saying that *server1* is preferred to *server2* for reaching EID 2.2.2.2/32.
-Note that lower priority value has higher preference in LISP.
-
- . Verify the correct registration of the 2.2.2.2/32 EID:
-
- curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
- http://localhost:8181/restconf/operations/odl-mappingservice:get-mapping \
- --data @get2.json
-
-+
-where 'get2.json' can be derived from 'get1.json' by changing the content of
-the 'Ipv4Address' field from '1.1.1.1' to '2.2.2.2'.
-
- . 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 (lines 14 and 28
- in 'mapping.json') and repeat the request from step 11. You can also
- repeat step 12 to see if the mapping is correctly registered. If you leave
- the ping on, and monitor the traffic using wireshark, you can see that the
- ping traffic to 2.2.2.2 will be diverted from the *server1* RLOC to the
- *server2* RLOC.
-+
-With the default OpenDaylight configuration the failover should be near
-instantaneous (we observed 3 lost pings in the worst case), because of the
-LISP 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 (enabled by default). It is controlled by the +lisp.smr+
-variable in +etc/custom.porperties+. When enabled, any mapping change from the
-RPC interface will trigger an SMR packet to all data plane elements that have
-requested the mapping in the last 24 hours (this value was chosen because it's
-the default TTL of Cisco IOS xTR mapping registrations). If disabled, ITRs
-keep their mappings until the TTL specified in the Map-Reply expires.
-
- . To add a service chain into the path from the client to the server, we can
- use an Explicit Locator Path, specifying the *service-node* as the first
- hop and *server1* (or *server2*) as the second hop. The following will
- achieve that:
-
- curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
- http://localhost:8181/restconf/operations/odl-mappingservice:add-mapping \
- --data @elp.json
-+
-where the 'elp.json' file is as follows:
-+
-[source,json]
-----
-{
- "input": {
- "mapping-record": {
- "recordTtl": 1440,
- "action": "NoAction",
- "authoritative": true,
- "eid": {
- "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
- "ipv4-prefix": "2.2.2.2/32"
- },
- "LocatorRecord": [
- {
- "locator-id": "ELP",
- "priority": 1,
- "weight": 1,
- "multicastPriority": 255,
- "multicastWeight": 0,
- "localLocator": true,
- "rlocProbed": false,
- "routed": true,
- "rloc": {
- "address-type": "ietf-lisp-address-types:explicit-locator-path-lcaf",
- "explicit-locator-path": {
- "hop": [
- {
- "hop-id": "service-node",
- "address": "192.168.16.33",
- "lrs-bits": "strict"
- },
- {
- "hop-id": "server1",
- "address": "192.168.16.31",
- "lrs-bits": "strict"
- }
- ]
- }
- }
- }
- ]
- }
- }
-}
-----
-+
-After the mapping for 2.2.2.2/32 is updated with the above, the ICMP traffic
-from *client* to *server1* will flow through the *service-node*. You can
-confirm this in the LISPmob logs, or by sniffing the traffic on either the
-*service-node* or *server1*. Note that service chains are unidirectional, so
-unless another ELP mapping is added for the return traffic, packets will go
-from *server1* to *client* directly.
-
- . Suppose the *service-node* is actually a firewall, and traffic is diverted
- there to support access control lists (ACLs). In this tutorial that can be
- emulated by using +iptables+ firewall rules in the *service-node* VM. To
- deny traffic on the service chain defined above, the following rule can be
- added:
-
- iptables -A OUTPUT --dst 192.168.16.31 -j DROP
-
-+
-The ping from the *client* should now have stopped.
-+
-In this case the ACL is done on the destination RLOC. There is an effort underway in the LISPmob
-community to allow filtering on EIDs, which is the more logical place to apply
-ACLs.
-
- . To delete the rule and restore connectivity on the service chain, delete
- the ACL by issuing the following command:
-
- iptables -D OUTPUT --dst 192.168.16.31 -j DROP
-
-+
-which should restore connectivity.
-
-=== LISP Flow Mapping Support
-
-For support the lispflowmapping project can be reached by emailing the
-developer mailing list: lispflowmapping-dev@lists.opendaylight.org or on the
-#opendaylight-lispflowmapping IRC channel on irc.freenode.net.
-
-Additional information is also available on the https://wiki.opendaylight.org/view/OpenDaylight_Lisp_Flow_Mapping:Main[Lisp Flow Mapping wiki]
-
-include::lispflowmapping-clustering-user.adoc[Clustering in lispflowmapping]
+This content has been migrated to: http://docs.opendaylight.org/en/stable-boron/user-guide/lisp-flow-mapping-user-guide.html
Code Review / docs.git / commitdiff
