From: Colin Dixon Date: Thu, 18 Aug 2016 21:27:36 +0000 (-0400) Subject: Migrate LISP Flow Mapping user docs to rst X-Git-Tag: release/boron~229 X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=commitdiff_plain;h=70295c9fb3e8f77bb49a4b205b61065024ae7525;p=docs.git Migrate LISP Flow Mapping user docs to rst Change-Id: Ia8455dc62a4001ba5c599709eb505df6ba04d129 Signed-off-by: Colin Dixon (cherry picked from commit 47981f8eb12360a40593d0764314597065f5327c) --- diff --git a/docs/user-guide/images/ODL_lfm_Be_component.jpg b/docs/user-guide/images/ODL_lfm_Be_component.jpg new file mode 100644 index 000000000..1ee309402 Binary files /dev/null and b/docs/user-guide/images/ODL_lfm_Be_component.jpg differ diff --git a/docs/user-guide/lisp-flow-mapping-user-guide.rst b/docs/user-guide/lisp-flow-mapping-user-guide.rst new file mode 100644 index 000000000..6d85e2ec1 --- /dev/null +++ b/docs/user-guide/lisp-flow-mapping-user-guide.rst @@ -0,0 +1,817 @@ +LISP Flow Mapping User Guide +============================ + +Overview +-------- + +Locator/ID Separation Protocol +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +`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: + +- `Endpoint Identifiers + (EIDs) `__ + +- `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 +`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 `__. + +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 `__. + +- **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 `__. + +- **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 `__) 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) `__ + 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 `__ +assigned by IANA, and in addition to those the `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. + ++------------------+----------+----------+----------+----------------------------------+ +| 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 `` + 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 `` + Install feature ``feature_name``. + +``log:set `` + 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 `__ + 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 `__. + +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 `__, + 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`` `__ 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 `__ 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 `__ + +Clustering in LISP Flow Mapping +------------------------------- + +Documentation regarding setting up a 3-node OpenDaylight cluster is +described at following `odl wiki +page `__. + +To turn on clustering in LISP Flow Mapping it is necessary: + +- run script **deploy.py** script. This script is in + `integration-test `__ + project placed at *tools/clustering/cluster-deployer/deploy.py*. A + whole deploy.py command can looks like: + +.. raw:: html + +
+ +| {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 + +
+ +| 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) + diff --git a/manuals/user-guide/src/main/asciidoc/lfm/lispflowmapping-clustering-user.adoc b/manuals/user-guide/src/main/asciidoc/lfm/lispflowmapping-clustering-user.adoc deleted file mode 100644 index 0b531bdae..000000000 --- a/manuals/user-guide/src/main/asciidoc/lfm/lispflowmapping-clustering-user.adoc +++ /dev/null @@ -1,34 +0,0 @@ -=== Clustering in LISP Flow Mapping -Documentation regarding setting up a 3-node OpenDaylight cluster is described at following https://wiki.opendaylight.org/view/Running_and_testing_an_OpenDaylight_Cluster#Three-node_cluster[odl wiki page]. - -To turn on clustering in LISP Flow Mapping it is necessary: - -* run script *deploy.py* script. This script is in https://git.opendaylight.org/gerrit/integration/test[integration-test] project placed at _tools/clustering/cluster-deployer/deploy.py_. A whole deploy.py command can looks like: -======= -{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} -======= -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) diff --git a/manuals/user-guide/src/main/asciidoc/lfm/lispflowmapping-msmr-user.adoc b/manuals/user-guide/src/main/asciidoc/lfm/lispflowmapping-msmr-user.adoc index 0caa9b02c..e60cd814d 100644 --- a/manuals/user-guide/src/main/asciidoc/lfm/lispflowmapping-msmr-user.adoc +++ b/manuals/user-guide/src/main/asciidoc/lfm/lispflowmapping-msmr-user.adoc @@ -1,639 +1,3 @@ == 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 +:: - 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 +:: - Install feature `feature_name`. - -+log:set +:: - 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