[lispflowmapping.git] / docs / user-guide.rst

.. _lispflowmapping-user-guide:

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
`OpenOverlayRouter.org <http://www.openoverlayrouter.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 OOR web site <http://www.openoverlayrouter.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.

-  **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.

.. _lfm_config:

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.smr** (default: *true*)
    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. We have included tutorials using two forwarding platforms:

1.  Using `Open Overlay Router (OOR) <https://github.com/OpenOverlayRouter/oor#overview>`__

2.  Using `FD.io <https://wiki.fd.io/view/ONE>`__

Both have different approaches to create the overlay but ultimately do the
same job. Details of both approaches have been explained below.

Creating a LISP overlay with OOR
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This section provides instructions to set up a LISP network of three
nodes (one "client" node and two "server" nodes) using OOR 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
^^^^^^^^^^^^^

-  `The OpenDaylight Karaf Distribution
   <https://www.opendaylight.org/downloads>`_

.. _instructions:

-  **The Postman Chrome App**: the most convenient way to follow along
   this tutorial is to use the `Postman
   App <https://www.getpostman.com/apps>`__
   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/OOR/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/OOR/Beryllium_Tutorial.json.postman_collection;hb=refs/heads/stable/fluorine>`__.
   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 OpenDaylight instance, and ``restconfPort`` to 8181, if you didn’t
   modify the default controller settings.

-  **OOR version 1.0 or later** 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**               | OOR                      | 192.168.16.30            |
+--------------------------+--------------------------+--------------------------+
| **server1**              | OOR                      | 192.168.16.31            |
+--------------------------+--------------------------+--------------------------+
| **server2**              | OOR                      | 192.168.16.32            |
+--------------------------+--------------------------+--------------------------+
| **service-node**         | OOR                      | 192.168.16.33            |
+--------------------------+--------------------------+--------------------------+

Table: Nodes in the tutorial

The figure below gives a sketch of network topology that will be used in the tutorial.

.. figure:: ./images/tutorial_architecture_diagram.png
   :alt: Network architecture of the tutorial

In LISP terminology **client**, **server1** and **server2** are mobile nodes (MN in OOR),
**controller** is a MS/MR and **service-node** is a RTR.

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 the OpenDaylight distribution on the controller VM.
    Please follow the general OpenDaylight 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 OOR on the **client**, **server1**, **server2**, and
    **service-node** VMs following the installation instructions `from
    the OOR README
    file <https://github.com/OpenOverlayRouter/oor#software-prerequisites>`__.

3.  Configure the OOR installations from the previous step. Take a look
    at the ``oor.conf.example`` to get a general idea of the structure
    of the conf file. First, check if the file ``/etc/oor.conf`` exists.
    If the file doesn't exist, create the file ``/etc/oor.conf``. Set the
    EID in ``/etc/oor.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 ``oor.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** remove the Map-Server configuration, 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 ``oor.conf`` file to a
    key/password of your choice (*password* in this tutorial).

    .. note::

        The ``resources/tutorial/OOR`` directory in 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/OOR;hb=refs/heads/stable/fluorine>`_,
        so you can just copy the files to ``/etc/oor.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 PUT \
            http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/authentication-key/ipv4:1.1.1.1%2f32/ \
            --data @add-key.json

    where the content of the *add-key.json* file is the following:

    .. code:: json

        {
            "authentication-key": {
                "eid-uri": "ipv4:1.1.1.1/32",
                "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 GET \
            http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/authentication-key/ipv4:1.1.1.1%2f32/

    The output the above invocation should look like this:

    .. code:: json

        {
            "authentication-key":[
                {
                    "eid-uri":"ipv4:1.1.1.1/32",
                    "eid":{
                        "ipv4-prefix":"1.1.1.1/32",
                        "address-type":"ietf-lisp-address-types:ipv4-prefix-afi"
                    },
                    "mapping-authkey":{
                        "key-string":"password"
                        ,"key-type":1
                    }
                }
            ]
        }

9.  Run the ``oor`` OOR daemon on all VMs:

    ::

        oor -f /etc/oor.conf

    For more information on accessing OOR logs, take a look at
    `OOR README <https://github.com/OpenOverlayRouter/oor#readme>`__
10. The **client** OOR 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 GET \
            http://localhost:8181/restconf/operational/odl-mappingservice:mapping-database/virtual-network-identifier/0/mapping/ipv4:1.1.1.1%2f32/southbound/

    An alternative way for retrieving mappings from OpenDaylight 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 PUT \
            http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/mapping/ipv4:2.2.2.2%2f32/northbound/ \
            --data @mapping.json

    where the *mapping.json* file looks like this:

    .. code:: json

        {
            "mapping": {
                "eid-uri": "ipv4:2.2.2.2/32",
                "origin": "northbound",
                "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 GET \
            http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/mapping/ipv4:2.2.2.2%2f32/northbound/

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 PUT \
            http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/mapping/ipv4:2.2.2.2%2f32/northbound/ \
            --data @elp.json

    where the *elp.json* file is as follows:

    .. code:: json

        {
            "mapping": {
                "eid-uri": "ipv4:2.2.2.2/32",
                "origin": "northbound",
                "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 OOR 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 OOR 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.


Creating a simple LISP overlay with FD.io
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In this section, we use the Overlay Network Engine (ONE) project in FD.io
to facilitate fully scripted setup and testing of a LISP/VXLAN-GPE network.
Overlay Network Engine (ONE) is a `FD.io <https://fd.io/>`__ project that enables programmable
dynamic software defined overlays. Details about this project can be
found in `ONE wiki <https://wiki.fd.io/view/ONE>`__.

The steps shown below will demonstrate setting up a LISP network between
a client and a server using VPP. We demonstrate how to use VPP lite to
build a IP4 LISP overlay on an Ubuntu host using namespaces and af_packet
interfaces. All configuration files used in the tutorials can be found
`here <https://gerrit.fd.io/r/gitweb?p=one.git;a=tree;f=tutorial>`__.

Prerequisites
^^^^^^^^^^^^^

-  `The OpenDaylight Karaf Distribution
   <https://www.opendaylight.org/downloads>`_

-  **The Postman Chrome App**: Please follow the instructions_ and import
   postman collection from the following URL: `<https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=blob;f=resources/tutorial/FD_io/lfm_vpp.postman_collection.json;hb=refs/heads/stable/fluorine>`__.

-  **Vagrant** (optional): Download it from `Vagrant website <https://www.vagrantup.com/downloads.html>`__
   and follow the setup instructions.

Target Environment
^^^^^^^^^^^^^^^^^^

Unlike the case with OOR, we use network namespace functionality of Linux
to create the overlay in this case. The following table contains ip addresses
of nodes in the overlay topology used in the tutorial. Our objective will be to
create this topology and be able to ping from client to server through an
intermediary hop, **service node**, which is a ``rtr node`` providing the
service of re-encapsulation. So, all the packets from client to server
will be through this **service node**.

+--------------------------+--------------------------+--------------------------+
| Node                     | Node Type                | IP Address               |
+==========================+==========================+==========================+
| **controller**           | OpenDaylight             | 6.0.3.100                |
+--------------------------+--------------------------+--------------------------+
| **client**               | VPP                      | 6.0.2.2                  |
+--------------------------+--------------------------+--------------------------+
| **server**               | VPP                      | 6.0.4.4                  |
+--------------------------+--------------------------+--------------------------+
| **service node**         | VPP                      | 6.0.3.3                  |
+--------------------------+--------------------------+--------------------------+

Table: Nodes in the tutorial

The figure below gives a sketch of network topology that will be used in the tutorial.

.. figure:: ./images/one_ODL_architecture.png
   :alt: Network architecture of the tutorial for FD.io

Instructions
^^^^^^^^^^^^

Follow the instructions below sequentially.

1.  Pull the VPP code anonymously using:
    ::

        git clone https://gerrit.fd.io/r/vpp

2.  Then, use the vagrant file from repository to build virtual machine
    with proper environment.
    ::

        cd vpp/build-root/vagrant/
        vagrant up
        vagrant ssh

3.  In case there is any error from ``vagrant up``, try ``vargant ssh``. if
    it works, no worries. If it still doesn't work, you can try any Ubuntu virtual
    machine. Or sometimes there is an issue with the Vagrant properly copying
    the VPP repo code from the host VM after the first installation. In that
    case ``/vpp`` doesn't exist. In both cases, follow the instructions
    from below.

    1. Clone the code in ``/`` directory. So, the codes will be in ``/vpp``.

    2. Run the following commands:
        ::

            cd /vpp/build-root
            make distclean
            ./bootstrap.sh
            make V=0 PLATFORM=vpp TAG=vpp install-deb
            sudo dpkg -i /vpp/build-root/*.deb

    Alternative and more detailed build instructions can be found in
    `VPP's wiki <https://wiki.fd.io/view/VPP/Build,_install,_and_test_images>`__
4.  By now, you should have a Ubuntu VM with VPP repository in ``/vpp``
    with ``sudo`` access. Now, we need VPP Lite build. The following commands
    builds VPP Lite.
    ::

        cd /vpp
        export PLATFORM=vpp_lite
        make build

    Successful build create the binary in ``/vpp/build-root/install-vpp_lite_debug-native/vpp/bin``

5.  Install bridge-utils and ethtool if needed by using following commands:
    ::

       sudo apt-get install bridge-utils ethtool

6.  Now, install and run OpenDaylight on the VM. Please follow the general
    OpenDaylight Installation Guide for this step from :ref:`install_odl`.
    Before running OpenDaylight, we need to change the configuration for RTR
    to work. Update ``etc/custom.properties`` with the ``lisp.elpPolicy`` to
    be replace.
    ::

        lisp.elpPolicy = replace

    Then, run OpenDaylight. For details regarding configuring LISP
    Flow Mapping, please take a look at :ref:`lfm_config`.
    Once the OpenDaylight controller is running install the *odl-lispflowmapping-msmr*
    feature from the Karaf CLI:

    ::

        feature:install odl-lispflowmapping-msmr

    It may take 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.

7.  For setting up VPP, get the files from ``resources/tutorial/FD_io``
    folder of the lispflowmapping repo. The files can also be found `here
    <https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=tree;f=resources/tutorial/FD_io;hb=refs/heads/stable/fluorine>`__.
    Copy the ``vpp1.config``, ``vpp2.config`` and ``rtr.config`` files in
    ``/etc/vpp/lite/``.

8.  In this example, VPP doesn't make any southbound map registers to OpenDaylight.
    So, we add the mappings directly from northbound. For that, we need
    to add the mappings to OpenDaylight via RESTCONF API.

    Register EID-to-RLOC mapping of the Client EID 6.0.2.0/24.
    ::

        curl -u "admin":"admin" -H "Content-type: application/json" -X PUT \
            http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/mapping/ipv4:6.0.2.0%2f24/northbound/ \
            --data @epl1.json

    Content of epl1.json:

    .. code:: json

        {
            "mapping": {
                "eid-uri": "ipv4:6.0.2.0/24",
                "origin": "northbound",
                "mapping-record": {
                    "recordTtl": 1440,
                    "action": "NoAction",
                    "authoritative": true,
                    "eid": {
                            "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
                            "ipv4-prefix": "6.0.2.0/24"
                    },
                    "LocatorRecord": [
                        {
                            "locator-id": "ELP",
                            "priority": 1,
                            "weight": 1,
                            "multicastPriority": 255,
                            "multicastWeight": 0,
                            "localLocator": true,
                            "rlocProbed": false,
                            "routed": false,
                            "rloc": {
                                "address-type": "ietf-lisp-address-types:explicit-locator-path-lcaf",
                                "explicit-locator-path": {
                                    "hop": [
                                        {
                                            "hop-id": "Hop 1",
                                            "address": "6.0.3.3",
                                            "lrs-bits": "lookup rloc-probe strict"
                                        },
                                        {
                                            "hop-id": "Hop 2",
                                            "address": "6.0.3.1",
                                            "lrs-bits": "lookup strict"
                                        }
                                    ]
                                }
                            }
                        }
                    ]
                }
            }
        }


    Similarly add EID-to-RLOC mapping of the Server EID 6.0.4.0/24.
    ::

        curl -u "admin":"admin" -H "Content-type: application/json" -X PUT \
            http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/mapping/ipv4:6.0.4.0%2f24/northbound/ \
            --data @epl2.json

    Content of elp2.json:

    .. code:: json

        {
            "mapping": {
                "eid-uri": "ipv4:6.0.4.0/24",
                "origin": "northbound",
                "mapping-record": {
                    "recordTtl": 1440,
                    "action": "NoAction",
                    "authoritative": true,
                    "eid": {
                            "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
                            "ipv4-prefix": "6.0.4.0/24"
                    },
                    "LocatorRecord": [
                        {
                            "locator-id": "ELP",
                            "priority": 1,
                            "weight": 1,
                            "multicastPriority": 255,
                            "multicastWeight": 0,
                            "localLocator": true,
                            "rlocProbed": false,
                            "routed": false,
                            "rloc": {
                                "address-type": "ietf-lisp-address-types:explicit-locator-path-lcaf",
                                "explicit-locator-path": {
                                    "hop": [
                                        {
                                            "hop-id": "Hop 1",
                                            "address": "6.0.3.3",
                                            "lrs-bits": "lookup rloc-probe strict"
                                        },
                                        {
                                            "hop-id": "Hop 2",
                                            "address": "6.0.3.2",
                                            "lrs-bits": "lookup strict"
                                        }
                                    ]
                                }
                            }
                        }
                    ]
                }
            }
        }

    The JSON files regarding these can be found in `here
    <https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=tree;f=resources/tutorial/FD_io;hb=refs/heads/stable/fluorine>`__.
    Even though there is no southbound registration for mapping to OpenDaylight, using
    northbound policy we can specify mappings, when Client requests for
    the Server eid, Client gets a reply from OpenDaylight.

9.  Assuming all files have been created and OpenDaylight has been configured as
    explained above, execute the host script you've created or the ``topology_setup.sh``
    script from `here <https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=tree;f=resources/tutorial/FD_io;hb=refs/heads/stable/fluorine>`__.

10. If all goes well, you can now test connectivity between the namespaces with:
    ::

        sudo ip netns exec vpp-ns1 ping 6.0.4.4

11. Traffic and control plane message exchanges can be checked with a wireshark
    listening on the odl interface.
12. .. important:: Delete the topology by running the ``topology_setup.sh`` with ``clean`` argument.
        ::

            sudo ./topology_setup.sh clean

Creating a LISP overlay with Cisco IOS-XE
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This section describes how to create a simple LISP overlay using the Cisco
IOS-XE network operating system as the data plane software running on the
`Cisco CSR 1000v Series Cloud Services Router
<http://www.cisco.com/c/en/us/support/routers/cloud-services-router-1000v/model.html>`_.

Prerequisites
^^^^^^^^^^^^^

-  `The OpenDaylight Karaf Distribution**
   <https://www.opendaylight.org/downloads>`_

-  `CSR1Kv image with Cisco IOS-XE version 03.13.00.S or later
   <http://www.cisco.com/c/en/us/support/routers/cloud-services-router-1000v/model.html#~tab-downloads>`_;
   the instructions have been tested on version 03.15.00.S.

-  **A virtualization platform** supported by CSR1Kv images (VMware ESXi,
   Citrix XenServer, KVM, and Microsoft Hyper-V).

Target Environment
^^^^^^^^^^^^^^^^^^

The CSR1Kv images are configured with one management interface
(``GigabitEthernet1``), and another interface (``GigabitEthernet2``) connected
to a host-only network on the virtualization platform, while the LISP mapping
system is assumed to be running in a Linux virtual machine, which has the
``eth0`` interface in NAT mode to allow outside internet access and ``eth1``
connected to the 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**               | CSR1Kv                   | 192.168.16.30            |
+--------------------------+--------------------------+--------------------------+
| **server**               | CSR1Kv                   | 192.168.16.31            |
+--------------------------+--------------------------+--------------------------+

Table: Nodes in the tutorial

The scenario and EID allocation is the same as the OOR scenario, except that
there is no **server2** and **service-node** (for now).

Before this tutorial can be followed, basic connectivity between the Linux VM
and the CSRs should work on the host-only network.

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. The easy way is to just use Postman.

1.  Install and run the OpenDaylight distribution on the controller VM.
    Please follow the general OpenDaylight Installation Guide from
    :ref:`install_odl` 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.  Create the **client** and **server** VMs following the installation
    instructions from the `CSR1Kv Configuration Guide
    <http://www.cisco.com/c/en/us/td/docs/routers/csr1000/software/configuration/b_CSR1000v_Configuration_Guide.html>`_.

3.  Define a key and EID prefix association in OpenDaylight using the RPC REST
    API for the **client** and **server** EIDs (1.1.1.1/32 and 2.2.2.2/32
    respectively) to allow registration from the southbound.  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 PUT \
            http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/authentication-key/ipv4:1.1.1.1%2f32/ \
            --data @add-key.json

    where the content of the *add-key.json* file is the following:

    .. code:: json

        {
            "authentication-key": {
                "eid-uri": "ipv4:1.1.1.1/32",
                "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
                }
            }
        }

    The same should be done for 2.2.2.2/32 too.

4.  Verify that the key is added properly by requesting the following
    URL:

    ::

        curl -u "admin":"admin" -H "Content-type: application/json" -X GET \
            http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/authentication-key/ipv4:1.1.1.1%2f32/

    The output the above invocation should look like this:

    .. code:: json

        {
            "authentication-key":[
                {
                    "eid-uri":"ipv4:1.1.1.1/32",
                    "eid":{
                        "ipv4-prefix":"1.1.1.1/32",
                        "address-type":"ietf-lisp-address-types:ipv4-prefix-afi"
                    },
                    "mapping-authkey":{
                        "key-string":"password"
                        ,"key-type":1
                    }
                }
            ]
        }

5.  Configure the CSR installations from the previous step. The EID needs to
    be configured on a loopback interface (except when the CSR is used as a
    router not a simple client like in this tutorial and the EID is assigned
    to a real interface).

    ::

        interface Loopback0
         ip address 1.1.1.1 255.255.255.255

6.  The LISP specific configuration goes to a ``router lisp`` section in the
    configuration. A ``locator-set`` defines the list of locators with their
    priorities and weights, either statically, or better yet, as an interface
    name:

    ::

        locator-set rloc-network
         IPv4-interface GigabitEthernet2 priority 1 weight 1
         exit

7.  To make sure a Map-Request is using the above defined ``rloc-network``
    locator set, the following configuration is used:

    ::

        map-request itr-rlocs rloc-network

8.  Each Instance ID needs its own configuration. For the default Instance ID
    of 0, the following configuration is needed for a besic setup:

    ::

        eid-table default instance-id 0
         database-mapping 1.1.1.1/32 locator-set rloc-network
         map-cache 0.0.0.0/0 map-request
         no ipv4 map-cache-persistent
         ipv4 itr map-resolver 192.168.16.11
         ipv4 itr
         ipv4 etr map-server 192.168.16.11 key password
         ipv4 etr
         exit

    ``database-mapping`` defines the EID prefix the router will register in
    the mapping system and which locator set it will use (``rloc-network`` in
    this case, which was defined in step 6).

    The next line creates a static map-cache entry for the whole IPv4 EID
    space, causing a Map-Request to be triggered for every destination (that
    is not directly connected on some interface).

    LISP routers save their map cache to a fie which is used to restore
    previous state on reboot. To avoid confusion due to state restored from a
    previous run, ``no ipv4 map-cache-persistent`` can be used to disable this
    behavior for non-production testing environments.

    A ``map-resolver`` is then defined, where Map-Requests will be directed to
    for mapping lookups, and then a ``map-server`` association with a shared
    secret key.

9.  Here's the full configuration that needs to be pasted into the
    configuration of the **client** to follow this tutorial:

    ::

        interface Loopback0
         ip address 1.1.1.1 255.255.255.255
        !
        router lisp
         locator-set rloc-network
          IPv4-interface GigabitEthernet2 priority 1 weight 1
          exit
         !
         map-request itr-rlocs rloc-network
         eid-table default instance-id 0
          database-mapping 1.1.1.1/32 locator-set rloc-network
          map-cache 0.0.0.0/0 map-request
          no ipv4 map-cache-persistent
          ipv4 itr map-resolver 192.168.16.11
          ipv4 itr
          ipv4 etr map-server 192.168.16.11 key password
          ipv4 etr
          exit
         !
         exit

    Configuring the **server** is done by replacing ``1.1.1.1`` with
    ``2.2.2.2`` in the above configuration snippet.

10. The CSR nodes should now register their EID-to-RLOC mappings to
    OpenDaylight. To verify, the corresponding EIDs can be looked up via the
    REST API:

    ::

        curl -u "admin":"admin" -H "Content-type: application/json" -X GET \
            http://localhost:8181/restconf/operational/odl-mappingservice:mapping-database/virtual-network-identifier/0/mapping/ipv4:1.1.1.1%2f32/southbound/

    An alternative way for retrieving mappings from OpenDaylight using the
    southbound interface is using the
    `lig <https://github.com/davidmeyer/lig>`_ open source tool.

    Yet another different way is to use the OpenDaylight mappingservice CLI,
    and type the following at the Karaf prompt:

    ::

        mappingservice:mappings

    This needs the *odl-lispflowmapping-mappingservice-shell* feature to be
    loaded. The output is intended for debugging purposes and shows the full
    Java objects stored in the map-cache.


11. Now the LISP network is up. It can be verified by pinging the **server**
    EID from the **client** CSR EID:

    ::

        ping 2.2.2.2 source 1.1.1.1

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)