1 .. _lispflowmapping-user-guide:
3 LISP Flow Mapping User Guide
4 ============================
9 Locator/ID Separation Protocol
10 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
12 `Locator/ID Separation Protocol
13 (LISP) <https://tools.ietf.org/html/rfc6830>`__ is a technology that
14 provides a flexible map-and-encap framework that can be used for overlay
15 network applications such as data center network virtualization and
16 Network Function Virtualization (NFV).
18 LISP provides the following name spaces:
20 - `Endpoint Identifiers
21 (EIDs) <https://tools.ietf.org/html/rfc6830#page-6>`__
24 (RLOCs) <https://tools.ietf.org/html/rfc6830#section-3>`__
26 In a virtualization environment EIDs can be viewed as virtual address
27 space and RLOCs can be viewed as physical network address space.
29 The LISP framework decouples network control plane from the forwarding
32 - A data plane that specifies how the virtualized network addresses are
33 encapsulated in addresses from the underlying physical network.
35 - A control plane that stores the mapping of the virtual-to-physical
36 address spaces, the associated forwarding policies and serves this
37 information to the data plane on demand.
39 Network programmability is achieved by programming forwarding policies
40 such as transparent mobility, service chaining, and traffic engineering
41 in the mapping system; where the data plane elements can fetch these
42 policies on demand as new flows arrive. This chapter describes the LISP
43 Flow Mapping project in OpenDaylight and how it can be used to enable
44 advanced SDN and NFV use cases.
46 LISP data plane Tunnel Routers are available at
47 `OpenOverlayRouter.org <https://www.openoverlayrouter.org/>`__ in the open source community on
48 the following platforms:
56 For more details and support for LISP data plane software please visit
57 `the OOR web site <https://www.openoverlayrouter.org/>`__.
59 LISP Flow Mapping Service
60 ~~~~~~~~~~~~~~~~~~~~~~~~~
62 The LISP Flow Mapping service provides LISP Mapping System services.
63 This includes LISP Map-Server and LISP Map-Resolver services to store
64 and serve mapping data to data plane nodes as well as to OpenDaylight
65 applications. Mapping data can include mapping of virtual addresses to
66 physical network address where the virtual nodes are reachable or hosted
67 at. Mapping data can also include a variety of routing policies
68 including traffic engineering and load balancing. To leverage this
69 service, OpenDaylight applications and services can use the northbound
70 REST API to define the mappings and policies in the LISP Mapping
71 Service. Data plane devices capable of LISP control protocol can
72 leverage this service through a southbound LISP plugin. LISP-enabled
73 devices must be configured to use this OpenDaylight service as their Map
74 Server and/or Map Resolver.
76 The southbound LISP plugin supports the LISP control protocol
77 (Map-Register, Map-Request, Map-Reply messages), and can also be used to
78 register mappings in the OpenDaylight mapping service.
80 LISP Flow Mapping Architecture
81 ------------------------------
83 The following figure shows the various LISP Flow Mapping modules.
85 .. figure:: ./images/ODL_lfm_Be_component.jpg
86 :alt: LISP Mapping Service Internal Architecture
88 LISP Mapping Service Internal Architecture
90 A brief description of each module is as follows:
92 - **DAO (Data Access Object):** This layer separates the LISP logic
93 from the database, so that we can separate the map server and map
94 resolver from the specific implementation of the mapping database.
95 Currently we have an implementation of this layer with an in-memory
96 HashMap, but it can be switched to any other key/value store and you
97 only need to implement the ILispDAO interface.
99 - **Map Server:** This module processes the adding or registration of
100 authentication tokens (keys) and mappings. For a detailed
101 specification of LISP Map Server, see
102 `LISP <https://tools.ietf.org/search/rfc6830>`__.
104 - **Map Resolver:** This module receives and processes the mapping
105 lookup queries and provides the mappings to requester. For a detailed
106 specification of LISP Map Server, see
107 `LISP <https://tools.ietf.org/search/rfc6830>`__.
109 - **RPC/RESTCONF:** This is the auto-generated RESTCONF-based
110 northbound API. This module enables defining key-EID associations as
111 well as adding mapping information through the Map Server. Key-EID
112 associations and mappings can also be queried via this API.
114 - **Neutron:** This module implements the OpenDaylight Neutron Service
115 APIs. It provides integration between the LISP service and the
116 OpenDaylight Neutron service, and thus OpenStack.
118 - **Java API:** The API module exposes the Map Server and Map Resolver
119 capabilities via a Java API.
121 - **LISP Proto:** This module includes LISP protocol dependent data
122 types and associated processing.
124 - **In Memory DB:** This module includes the in memory database
125 implementation of the mapping service.
127 - **LISP Southbound Plugin:** This plugin enables data plane devices
128 that support LISP control plane protocol (see
129 `LISP <https://tools.ietf.org/search/rfc6830>`__) to register and
130 query mappings to the LISP Flow Mapping via the LISP control plane
135 Configuring LISP Flow Mapping
136 -----------------------------
138 In order to use the LISP mapping service for registering EID to RLOC
139 mappings from northbound or southbound, keys have to be defined for the
140 EID prefixes first. Once a key is defined for an EID prefix, it can be
141 used to add mappings for that EID prefix multiple times. If the service
142 is going to be used to process Map-Register messages from the southbound
143 LISP plugin, the same key must be used by the data plane device to
144 create the authentication data in the Map-Register messages for the
145 associated EID prefix.
147 The ``etc/custom.properties`` file in the Karaf distribution allows
148 configuration of several OpenDaylight parameters. The LISP service has
149 the following properties that can be adjusted:
151 **lisp.smr** (default: *true*)
152 Enables/disables the `Solicit-Map-Request
153 (SMR) <https://tools.ietf.org/html/rfc6830#section-6.6.2>`__
154 functionality. SMR is a method to notify changes in an EID-to-RLOC
155 mapping to "subscribers". The LISP service considers all
156 Map-Request’s source RLOC as a subscriber to the requested EID
157 prefix, and will send an SMR control message to that RLOC if the
160 **lisp.elpPolicy** (default: *default*)
161 Configures how to build a Map-Reply southbound message from a
162 mapping containing an Explicit Locator Path (ELP) RLOC. It is used
163 for compatibility with dataplane devices that don’t understand the
164 ELP LCAF format. The *default* setting doesn’t alter the mapping,
165 returning all RLOCs unmodified. The *both* setting adds a new RLOC
166 to the mapping, with a lower priority than the ELP, that is the next
167 hop in the service chain. To determine the next hop, it searches the
168 source RLOC of the Map-Request in the ELP, and chooses the next hop,
169 if it exists, otherwise it chooses the first hop. The *replace*
170 setting adds a new RLOC using the same algorithm as the *both*
171 setting, but using the origin priority of the ELP RLOC, which is
172 removed from the mapping.
174 **lisp.lookupPolicy** (default: *northboundFirst*)
175 Configures the mapping lookup algorithm. When set to
176 *northboundFirst* mappings programmed through the northbound API
177 will take precedence. If no northbound programmed mappings exist,
178 then the mapping service will return mappings registered through the
179 southbound plugin, if any exists. When set to
180 *northboundAndSouthbound* the mapping programmed by the northbound
181 is returned, updated by the up/down status of these mappings as
182 reported by the southbound (if existing).
184 **lisp.mappingMerge** (default: *false*)
185 Configures the merge policy on the southbound registrations through
186 the LISP SB Plugin. When set to *false*, only the latest mapping
187 registered through the SB plugin is valid in the southbound mapping
188 database, independent of which device it came from. When set to
189 *true*, mappings for the same EID registered by different devices
190 are merged together and a union of the locators is maintained as the
191 valid mapping for that EID.
193 Textual Conventions for LISP Address Formats
194 --------------------------------------------
196 In addition to the more common IPv4, IPv6 and MAC address data types,
197 the LISP control plane supports arbitrary `Address Family
198 Identifiers <https://www.iana.org/assignments/address-family-numbers>`__
199 assigned by IANA, and in addition to those the `LISP Canoncal Address
200 Format (LCAF) <https://tools.ietf.org/html/draft-ietf-lisp-lcaf>`__.
202 The LISP Flow Mapping project in OpenDaylight implements support for
203 many of these different address formats, the full list being summarized
204 in the following table. While some of the address formats have well
205 defined and widely used textual representation, many don’t. It became
206 necessary to define a convention to use for text rendering of all
207 implemented address types in logs, URLs, input fields, etc. The below
208 table lists the supported formats, along with their AFI number and LCAF
209 type, including the prefix used for disambiguation of potential overlap,
212 +------------------+----------+----------+----------+----------------------------------+
213 | Name | AFI | LCAF | Prefix | Text Rendering |
214 +==================+==========+==========+==========+==================================+
215 | **No Address** | 0 | - | no: | No Address Present |
216 +------------------+----------+----------+----------+----------------------------------+
217 | **IPv4 Prefix** | 1 | - | ipv4: | 192.0.2.0/24 |
218 +------------------+----------+----------+----------+----------------------------------+
219 | **IPv6 Prefix** | 2 | - | ipv6: | 2001:db8::/32 |
220 +------------------+----------+----------+----------+----------------------------------+
221 | **MAC Address** | 16389 | - | mac: | 00:00:5E:00:53:00 |
222 +------------------+----------+----------+----------+----------------------------------+
223 | **Distinguished | 17 | - | dn: | stringAsIs |
225 +------------------+----------+----------+----------+----------------------------------+
226 | **AS Number** | 18 | - | as: | AS64500 |
227 +------------------+----------+----------+----------+----------------------------------+
228 | **AFI List** | 16387 | 1 | list: | {192.0.2.1,192.0.2.2,2001:db8::1 |
230 +------------------+----------+----------+----------+----------------------------------+
231 | **Instance ID** | 16387 | 2 | - | [223] 192.0.2.0/24 |
232 +------------------+----------+----------+----------+----------------------------------+
233 | **Application | 16387 | 4 | appdata: | 192.0.2.1!128!17!80-81!6667-7000 |
235 +------------------+----------+----------+----------+----------------------------------+
236 | **Explicit | 16387 | 10 | elp: | {192.0.2.1→192.0.2.2\|lps→192.0. |
237 | Locator Path** | | | | 2.3} |
238 +------------------+----------+----------+----------+----------------------------------+
239 | **Source/Destina | 16387 | 12 | srcdst: | 192.0.2.1/32\|192.0.2.2/32 |
242 +------------------+----------+----------+----------+----------------------------------+
243 | **Key/Value | 16387 | 15 | kv: | 192.0.2.1⇒192.0.2.2 |
244 | Address Pair** | | | | |
245 +------------------+----------+----------+----------+----------------------------------+
246 | **Service Path** | 16387 | N/A | sp: | 42(3) |
247 +------------------+----------+----------+----------+----------------------------------+
249 Table: LISP Address Formats
251 Please note that the forward slash character ``/`` typically separating
252 IPv4 and IPv6 addresses from the mask length is transformed into ``%2f``
258 In this section we will discuss two types of Karaf commands: built-in,
259 and LISP specific. Some built-in commands are quite useful, and are
260 needed for the tutorial, so they will be discussed here. A reference of
261 all LISP specific commands, added by the LISP Flow Mapping project is
262 also included. They are useful mostly for debugging.
264 Useful built-in commands
265 ~~~~~~~~~~~~~~~~~~~~~~~~
268 Lists all available command, with a short description of each.
270 ``help <command_name>``
271 Show detailed help about a specific command.
273 ``feature:list [-i]``
274 Show all locally available features in the Karaf container. The
275 ``-i`` option lists only features that are currently installed. It
276 is possible to use ``| grep`` to filter the output (for all
277 commands, not just this one).
279 ``feature:install <feature_name>``
280 Install feature ``feature_name``.
282 ``log:set <level> <class>``
283 Set the log level for ``class`` to ``level``. The default log level
284 for all classes is INFO. For debugging, or learning about LISP
285 internals it is useful to run
286 ``log:set TRACE org.opendaylight.lispflowmapping`` right after Karaf
290 Outputs the log file to the console, and returns control to the
294 Continuously shows log output, requires ``Ctrl+C`` to return to the
297 LISP specific commands
298 ~~~~~~~~~~~~~~~~~~~~~~
300 The available lisp commands can always be obtained by
301 ``help mappingservice``. Currently they are:
303 ``mappingservice:addkey``
304 Add the default password ``password`` for the IPv4 EID prefix
305 0.0.0.0/0 (all addresses). This is useful when experimenting with
306 southbound devices, and using the REST interface would be combersome
309 ``mappingservice:mappings``
310 Show the list of all mappings stored in the internal non-persistent
311 data store (the DAO), listing the full data structure. The output is
312 not human friendly, but can be used for debugging.
314 LISP Flow Mapping Karaf Features
315 --------------------------------
317 LISP Flow Mapping has the following Karaf features that can be installed
318 from the Karaf console:
320 ``odl-lispflowmapping-msmr``
321 This includes the core features required to use the LISP Flow
322 Mapping Service such as mapping service and the LISP southbound
325 ``odl-lispflowmapping-ui``
326 This includes the GUI module for the LISP Mapping Service.
328 ``odl-lispflowmapping-neutron``
329 This is the experimental Neutron provider module for LISP mapping
335 This section provides a tutorial demonstrating various features in this
336 service. We have included tutorials using two forwarding platforms:
338 1. Using `Open Overlay Router (OOR) <https://github.com/OpenOverlayRouter/oor/wiki>`__
340 2. Using `FD.io <https://wiki.fd.io/view/ONE>`__
342 Both have different approaches to create the overlay but ultimately do the
343 same job. Details of both approaches have been explained below.
345 Creating a LISP overlay with OOR
346 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
348 This section provides instructions to set up a LISP network of three
349 nodes (one "client" node and two "server" nodes) using OOR as data
350 plane LISP nodes and the LISP Flow Mapping project from OpenDaylight as
351 the LISP programmable mapping system for the LISP network.
356 The steps shown below will demonstrate setting up a LISP network between
357 a client and two servers, then performing a failover between the two
363 - `The OpenDaylight Karaf Distribution
364 <https://www.opendaylight.org/downloads>`_
368 - **The Postman Chrome App**: the most convenient way to follow along
369 this tutorial is to use the `Postman
370 App <https://www.getpostman.com/downloads/>`__
371 to edit and send the requests. The project git repository hosts a
372 collection of the requests that are used in this tutorial in the
373 ``resources/tutorial/OOR/Beryllium_Tutorial.json.postman_collection``
374 file. You can import this file to Postman by clicking *Import* at the
375 top, choosing *Download from link* and then entering the following
377 `<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>`__.
378 Alternatively, you can save the file on your machine, or if you have
379 the repository checked out, you can import from there. You will need
380 to create a new Postman Environment and define some variables within:
381 ``controllerHost`` set to the hostname or IP address of the machine
382 running the OpenDaylight instance, and ``restconfPort`` to 8181, if you didn’t
383 modify the default controller settings.
385 - **OOR version 1.0 or later** The README.md lists the dependencies needed
386 to build it from source.
388 - **A virtualization platform**
393 The three LISP data plane nodes and the LISP mapping system are assumed
394 to be running in Linux virtual machines, which have the ``eth0``
395 interface in NAT mode to allow outside internet access and ``eth1``
396 connected to a host-only network, with the following IP addresses
397 (please adjust configuration files, JSON examples, etc. accordingly if
398 you’re using another addressing scheme):
400 +--------------------------+--------------------------+--------------------------+
401 | Node | Node Type | IP Address |
402 +==========================+==========================+==========================+
403 | **controller** | OpenDaylight | 192.168.16.11 |
404 +--------------------------+--------------------------+--------------------------+
405 | **client** | OOR | 192.168.16.30 |
406 +--------------------------+--------------------------+--------------------------+
407 | **server1** | OOR | 192.168.16.31 |
408 +--------------------------+--------------------------+--------------------------+
409 | **server2** | OOR | 192.168.16.32 |
410 +--------------------------+--------------------------+--------------------------+
411 | **service-node** | OOR | 192.168.16.33 |
412 +--------------------------+--------------------------+--------------------------+
414 Table: Nodes in the tutorial
416 The figure below gives a sketch of network topology that will be used in the tutorial.
418 .. figure:: ./images/tutorial_architecture_diagram.png
419 :alt: Network architecture of the tutorial
421 In LISP terminology **client**, **server1** and **server2** are mobile nodes (MN in OOR),
422 **controller** is a MS/MR and **service-node** is a RTR.
427 The below steps use the command line tool cURL to talk to the LISP Flow
428 Mapping RPC REST API. This is so that you can see the actual request
429 URLs and body content on the page.
431 1. Install and run the OpenDaylight distribution on the controller VM.
432 Please follow the general `OpenDaylight Installation Guide
433 <https://docs.opendaylight.org/en/latest/getting-started-guide/installing_opendaylight.html>`__
434 for this step. Once the OpenDaylight controller is running install
435 the *odl-lispflowmapping-msmr* feature from the Karaf CLI:
439 feature:install odl-lispflowmapping-msmr
441 It takes quite a while to load and initialize all features and their
442 dependencies. It’s worth running the command ``log:tail`` in the
443 Karaf console to see when the log output is winding down, and
444 continue with the tutorial after that.
446 2. Install OOR on the **client**, **server1**, **server2**, and
447 **service-node** VMs following the installation instructions `from
449 <https://github.com/OpenOverlayRouter/oor/blob/master/README.md>`__.
451 3. Configure the OOR installations from the previous step. Take a look
452 at the ``oor.conf.example`` to get a general idea of the structure
453 of the conf file. First, check if the file ``/etc/oor.conf`` exists.
454 If the file doesn't exist, create the file ``/etc/oor.conf``. Set the
455 EID in ``/etc/oor.conf`` file from the IP address space selected
456 for your virtual/LISP network. In this tutorial the EID of the
457 **client** is set to 1.1.1.1/32, and that of **server1** and
458 **server2** to 2.2.2.2/32.
460 4. Set the RLOC interface to ``eth1`` in each ``oor.conf`` file. LISP
461 will determine the RLOC (IP address of the corresponding VM) based
464 5. Set the Map-Resolver address to the IP address of the
465 **controller**, and on the **client** the Map-Server too. On
466 **server1** and **server2** remove the Map-Server configuration, so
467 that it doesn’t interfere with the mappings on the controller, since
468 we’re going to program them manually.
470 6. Modify the "key" parameter in each ``oor.conf`` file to a
471 key/password of your choice (*password* in this tutorial).
475 The ``resources/tutorial/OOR`` directory in the project git repository
476 has the files used in the tutorial `checked in
477 <https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=tree;f=resources/tutorial/OOR;hb=refs/heads/stable/fluorine>`_,
478 so you can just copy the files to ``/etc/oor.conf`` on the respective
479 VMs. You will also find the JSON files referenced below in the same
482 7. Define a key and EID prefix association in OpenDaylight using the
483 RPC REST API for the **client** EID (1.1.1.1/32) to allow
484 registration from the southbound. Since the mappings for the server
485 EID will be configured from the REST API, no such association is
486 necessary. Run the below command on the **controller** (or any
487 machine that can reach **controller**, by replacing *localhost* with
488 the IP address of **controller**).
492 curl -u "admin":"admin" -H "Content-type: application/json" -X PUT \
493 http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/authentication-key/ipv4:1.1.1.1%2f32/ \
496 where the content of the *add-key.json* file is the following:
501 "authentication-key": {
502 "eid-uri": "ipv4:1.1.1.1/32",
504 "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
505 "ipv4-prefix": "1.1.1.1/32"
508 "key-string": "password",
514 8. Verify that the key is added properly by requesting the following
519 curl -u "admin":"admin" -H "Content-type: application/json" -X GET \
520 http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/authentication-key/ipv4:1.1.1.1%2f32/
522 The output the above invocation should look like this:
527 "authentication-key":[
529 "eid-uri":"ipv4:1.1.1.1/32",
531 "ipv4-prefix":"1.1.1.1/32",
532 "address-type":"ietf-lisp-address-types:ipv4-prefix-afi"
535 "key-string":"password"
542 9. Run the ``oor`` OOR daemon on all VMs:
548 For more information on accessing OOR logs, take a look at
549 `OOR README <https://github.com/OpenOverlayRouter/oor#readme>`__
550 10. The **client** OOR node should now register its EID-to-RLOC
551 mapping in OpenDaylight. To verify you can lookup the corresponding
552 EIDs via the REST API
556 curl -u "admin":"admin" -H "Content-type: application/json" -X GET \
557 http://localhost:8181/restconf/operational/odl-mappingservice:mapping-database/virtual-network-identifier/0/mapping/ipv4:1.1.1.1%2f32/southbound/
559 An alternative way for retrieving mappings from OpenDaylight using the
560 southbound interface is using the
561 `lig <https://github.com/davidmeyer/lig>`__ open source tool.
563 11. Register the EID-to-RLOC mapping of the server EID 2.2.2.2/32 to the
564 controller, pointing to **server1** and **server2** with a higher
565 priority for **server1**
569 curl -u "admin":"admin" -H "Content-type: application/json" -X PUT \
570 http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/mapping/ipv4:2.2.2.2%2f32/northbound/ \
573 where the *mapping.json* file looks like this:
579 "eid-uri": "ipv4:2.2.2.2/32",
580 "origin": "northbound",
583 "action": "NoAction",
584 "authoritative": true,
586 "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
587 "ipv4-prefix": "2.2.2.2/32"
591 "locator-id": "server1",
594 "multicastPriority": 255,
595 "multicastWeight": 0,
596 "localLocator": true,
600 "address-type": "ietf-lisp-address-types:ipv4-afi",
601 "ipv4": "192.168.16.31"
605 "locator-id": "server2",
608 "multicastPriority": 255,
609 "multicastWeight": 0,
610 "localLocator": true,
614 "address-type": "ietf-lisp-address-types:ipv4-afi",
615 "ipv4": "192.168.16.32"
623 Here the priority of the second RLOC (192.168.16.32 - **server2**)
624 is 2, a higher numeric value than the priority of 192.168.16.31,
625 which is 1. This policy is saying that **server1** is preferred to
626 **server2** for reaching EID 2.2.2.2/32. Note that lower priority
627 value has higher preference in LISP.
629 12. Verify the correct registration of the 2.2.2.2/32 EID:
633 curl -u "admin":"admin" -H "Content-type: application/json" -X GET \
634 http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/mapping/ipv4:2.2.2.2%2f32/northbound/
636 13. Now the LISP network is up. To verify, log into the **client** VM
637 and ping the server EID:
643 14. Let’s test fail-over now. Suppose you had a service on **server1**
644 which became unavailable, but **server1** itself is still reachable.
645 LISP will not automatically fail over, even if the mapping for
646 2.2.2.2/32 has two locators, since both locators are still reachable
647 and uses the one with the higher priority (lowest priority value).
648 To force a failover, we need to set the priority of **server2** to a
649 lower value. Using the file mapping.json above, swap the priority
650 values between the two locators (lines 14 and 28 in *mapping.json*)
651 and repeat the request from step 11. You can also repeat step 12 to
652 see if the mapping is correctly registered. If you leave the ping
653 on, and monitor the traffic using wireshark, you can see that the
654 ping traffic to 2.2.2.2 will be diverted from the **server1** RLOC
655 to the **server2** RLOC.
657 With the default OpenDaylight configuration the failover should be
658 near instantaneous (we observed 3 lost pings in the worst case),
659 because of the LISP `Solicit-Map-Request (SMR)
660 mechanism <https://tools.ietf.org/html/rfc6830#section-6.6.2>`__ that
661 can ask a LISP data plane element to update its mapping for a
662 certain EID (enabled by default). It is controlled by the
663 ``lisp.smr`` variable in ``etc/custom.porperties``. When enabled,
664 any mapping change from the RPC interface will trigger an SMR packet
665 to all data plane elements that have requested the mapping in the
666 last 24 hours (this value was chosen because it’s the default TTL of
667 Cisco IOS xTR mapping registrations). If disabled, ITRs keep their
668 mappings until the TTL specified in the Map-Reply expires.
670 15. To add a service chain into the path from the client to the server,
671 we can use an Explicit Locator Path, specifying the **service-node**
672 as the first hop and **server1** (or **server2**) as the second hop.
673 The following will achieve that:
677 curl -u "admin":"admin" -H "Content-type: application/json" -X PUT \
678 http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/mapping/ipv4:2.2.2.2%2f32/northbound/ \
681 where the *elp.json* file is as follows:
687 "eid-uri": "ipv4:2.2.2.2/32",
688 "origin": "northbound",
691 "action": "NoAction",
692 "authoritative": true,
694 "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
695 "ipv4-prefix": "2.2.2.2/32"
702 "multicastPriority": 255,
703 "multicastWeight": 0,
704 "localLocator": true,
708 "address-type": "ietf-lisp-address-types:explicit-locator-path-lcaf",
709 "explicit-locator-path": {
712 "hop-id": "service-node",
713 "address": "192.168.16.33",
718 "address": "192.168.16.31",
730 After the mapping for 2.2.2.2/32 is updated with the above, the ICMP
731 traffic from **client** to **server1** will flow through the
732 **service-node**. You can confirm this in the OOR logs, or by
733 sniffing the traffic on either the **service-node** or **server1**.
734 Note that service chains are unidirectional, so unless another ELP
735 mapping is added for the return traffic, packets will go from
736 **server1** to **client** directly.
738 16. Suppose the **service-node** is actually a firewall, and traffic is
739 diverted there to support access control lists (ACLs). In this
740 tutorial that can be emulated by using ``iptables`` firewall rules
741 in the **service-node** VM. To deny traffic on the service chain
742 defined above, the following rule can be added:
746 iptables -A OUTPUT --dst 192.168.16.31 -j DROP
748 The ping from the **client** should now have stopped.
750 In this case the ACL is done on the destination RLOC. There is an
751 effort underway in the OOR community to allow filtering on EIDs,
752 which is the more logical place to apply ACLs.
754 17. To delete the rule and restore connectivity on the service chain,
755 delete the ACL by issuing the following command:
759 iptables -D OUTPUT --dst 192.168.16.31 -j DROP
761 which should restore connectivity.
764 Creating a simple LISP overlay with FD.io
765 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
767 In this section, we use the Overlay Network Engine (ONE) project in FD.io
768 to facilitate fully scripted setup and testing of a LISP/VXLAN-GPE network.
769 Overlay Network Engine (ONE) is a `FD.io <https://fd.io/>`__ project that enables programmable
770 dynamic software defined overlays. Details about this project can be
771 found in `ONE wiki <https://wiki.fd.io/view/ONE>`__.
773 The steps shown below will demonstrate setting up a LISP network between
774 a client and a server using VPP. We demonstrate how to use VPP lite to
775 build a IP4 LISP overlay on an Ubuntu host using namespaces and af_packet
776 interfaces. All configuration files used in the tutorials can be found
777 `here <https://gerrit.fd.io/r/gitweb?p=one.git;a=tree;f=tutorial>`__.
782 - `The OpenDaylight Karaf Distribution
783 <https://www.opendaylight.org/downloads>`_
785 - **The Postman Chrome App**: Please follow the instructions_ and import
786 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>`__.
788 - **Vagrant** (optional): Download it from `Vagrant website <https://www.vagrantup.com/downloads.html>`__
789 and follow the setup instructions.
794 Unlike the case with OOR, we use network namespace functionality of Linux
795 to create the overlay in this case. The following table contains ip addresses
796 of nodes in the overlay topology used in the tutorial. Our objective will be to
797 create this topology and be able to ping from client to server through an
798 intermediary hop, **service node**, which is a ``rtr node`` providing the
799 service of re-encapsulation. So, all the packets from client to server
800 will be through this **service node**.
802 +--------------------------+--------------------------+--------------------------+
803 | Node | Node Type | IP Address |
804 +==========================+==========================+==========================+
805 | **controller** | OpenDaylight | 6.0.3.100 |
806 +--------------------------+--------------------------+--------------------------+
807 | **client** | VPP | 6.0.2.2 |
808 +--------------------------+--------------------------+--------------------------+
809 | **server** | VPP | 6.0.4.4 |
810 +--------------------------+--------------------------+--------------------------+
811 | **service node** | VPP | 6.0.3.3 |
812 +--------------------------+--------------------------+--------------------------+
814 Table: Nodes in the tutorial
816 The figure below gives a sketch of network topology that will be used in the tutorial.
818 .. figure:: ./images/one_ODL_architecture.png
819 :alt: Network architecture of the tutorial for FD.io
824 Follow the instructions below sequentially.
826 1. Pull the VPP code anonymously using:
829 git clone https://gerrit.fd.io/r/vpp
831 2. Then, use the vagrant file from repository to build virtual machine
832 with proper environment.
835 cd vpp/build-root/vagrant/
839 3. In case there is any error from ``vagrant up``, try ``vargant ssh``. if
840 it works, no worries. If it still doesn't work, you can try any Ubuntu virtual
841 machine. Or sometimes there is an issue with the Vagrant properly copying
842 the VPP repo code from the host VM after the first installation. In that
843 case ``/vpp`` doesn't exist. In both cases, follow the instructions
846 1. Clone the code in ``/`` directory. So, the codes will be in ``/vpp``.
848 2. Run the following commands:
854 make V=0 PLATFORM=vpp TAG=vpp install-deb
855 sudo dpkg -i /vpp/build-root/*.deb
857 Alternative and more detailed build instructions can be found in
858 `VPP's wiki <https://wiki.fd.io/view/VPP/Build,_install,_and_test_images>`__
859 4. By now, you should have a Ubuntu VM with VPP repository in ``/vpp``
860 with ``sudo`` access. Now, we need VPP Lite build. The following commands
865 export PLATFORM=vpp_lite
868 Successful build create the binary in ``/vpp/build-root/install-vpp_lite_debug-native/vpp/bin``
870 5. Install bridge-utils and ethtool if needed by using following commands:
873 sudo apt-get install bridge-utils ethtool
875 6. Now, install and run OpenDaylight on the VM. Please follow the general
876 `OpenDaylight Installation Guide
877 <https://docs.opendaylight.org/en/latest/getting-started-guide/installing_opendaylight.html>`__ for this step.
878 Before running OpenDaylight, we need to change the configuration for RTR
879 to work. Update ``etc/custom.properties`` with the ``lisp.elpPolicy`` to
883 lisp.elpPolicy = replace
885 Then, run OpenDaylight. For details regarding configuring LISP
886 Flow Mapping, please take a look at :ref:`lfm_config`.
887 Once the OpenDaylight controller is running install the *odl-lispflowmapping-msmr*
888 feature from the Karaf CLI:
892 feature:install odl-lispflowmapping-msmr
894 It may take quite a while to load and initialize all features and their
895 dependencies. It’s worth running the command ``log:tail`` in the
896 Karaf console to see when the log output is winding down, and
897 continue with the tutorial after that.
899 7. For setting up VPP, get the files from ``resources/tutorial/FD_io``
900 folder of the lispflowmapping repo. The files can also be found `here
901 <https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=tree;f=resources/tutorial/FD_io;hb=refs/heads/stable/fluorine>`__.
902 Copy the ``vpp1.config``, ``vpp2.config`` and ``rtr.config`` files in
905 8. In this example, VPP doesn't make any southbound map registers to OpenDaylight.
906 So, we add the mappings directly from northbound. For that, we need
907 to add the mappings to OpenDaylight via RESTCONF API.
909 Register EID-to-RLOC mapping of the Client EID 6.0.2.0/24.
912 curl -u "admin":"admin" -H "Content-type: application/json" -X PUT \
913 http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/mapping/ipv4:6.0.2.0%2f24/northbound/ \
916 Content of epl1.json:
922 "eid-uri": "ipv4:6.0.2.0/24",
923 "origin": "northbound",
926 "action": "NoAction",
927 "authoritative": true,
929 "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
930 "ipv4-prefix": "6.0.2.0/24"
937 "multicastPriority": 255,
938 "multicastWeight": 0,
939 "localLocator": true,
943 "address-type": "ietf-lisp-address-types:explicit-locator-path-lcaf",
944 "explicit-locator-path": {
948 "address": "6.0.3.3",
949 "lrs-bits": "lookup rloc-probe strict"
953 "address": "6.0.3.1",
954 "lrs-bits": "lookup strict"
966 Similarly add EID-to-RLOC mapping of the Server EID 6.0.4.0/24.
969 curl -u "admin":"admin" -H "Content-type: application/json" -X PUT \
970 http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/mapping/ipv4:6.0.4.0%2f24/northbound/ \
973 Content of elp2.json:
979 "eid-uri": "ipv4:6.0.4.0/24",
980 "origin": "northbound",
983 "action": "NoAction",
984 "authoritative": true,
986 "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
987 "ipv4-prefix": "6.0.4.0/24"
994 "multicastPriority": 255,
995 "multicastWeight": 0,
996 "localLocator": true,
1000 "address-type": "ietf-lisp-address-types:explicit-locator-path-lcaf",
1001 "explicit-locator-path": {
1005 "address": "6.0.3.3",
1006 "lrs-bits": "lookup rloc-probe strict"
1010 "address": "6.0.3.2",
1011 "lrs-bits": "lookup strict"
1022 The JSON files regarding these can be found in `here
1023 <https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=tree;f=resources/tutorial/FD_io;hb=refs/heads/stable/fluorine>`__.
1024 Even though there is no southbound registration for mapping to OpenDaylight, using
1025 northbound policy we can specify mappings, when Client requests for
1026 the Server eid, Client gets a reply from OpenDaylight.
1028 9. Assuming all files have been created and OpenDaylight has been configured as
1029 explained above, execute the host script you've created or the ``topology_setup.sh``
1030 script from `here <https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=tree;f=resources/tutorial/FD_io;hb=refs/heads/stable/fluorine>`__.
1032 10. If all goes well, you can now test connectivity between the namespaces with:
1035 sudo ip netns exec vpp-ns1 ping 6.0.4.4
1037 11. Traffic and control plane message exchanges can be checked with a wireshark
1038 listening on the odl interface.
1039 12. .. important:: Delete the topology by running the ``topology_setup.sh`` with ``clean`` argument.
1042 sudo ./topology_setup.sh clean
1044 Creating a LISP overlay with Cisco IOS-XE
1045 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1047 This section describes how to create a simple LISP overlay using the Cisco
1048 IOS-XE network operating system as the data plane software running on the
1049 `Cisco CSR 1000v Series Cloud Services Router
1050 <https://www.cisco.com/c/en/us/support/routers/cloud-services-router-1000v/model.html>`_.
1055 - `The OpenDaylight Karaf Distribution**
1056 <https://www.opendaylight.org/downloads>`_
1058 - `CSR1Kv image with Cisco IOS-XE version 03.13.00.S or later
1059 <https://www.cisco.com/c/en/us/support/routers/cloud-services-router-1000v/model.html>`_;
1060 the instructions have been tested on version 03.15.00.S.
1062 - **A virtualization platform** supported by CSR1Kv images (VMware ESXi,
1063 Citrix XenServer, KVM, and Microsoft Hyper-V).
1068 The CSR1Kv images are configured with one management interface
1069 (``GigabitEthernet1``), and another interface (``GigabitEthernet2``) connected
1070 to a host-only network on the virtualization platform, while the LISP mapping
1071 system is assumed to be running in a Linux virtual machine, which has the
1072 ``eth0`` interface in NAT mode to allow outside internet access and ``eth1``
1073 connected to the host-only network, with the following IP addresses (please
1074 adjust configuration files, JSON examples, etc. accordingly if you’re using
1075 another addressing scheme):
1077 +--------------------------+--------------------------+--------------------------+
1078 | Node | Node Type | IP Address |
1079 +==========================+==========================+==========================+
1080 | **controller** | OpenDaylight | 192.168.16.11 |
1081 +--------------------------+--------------------------+--------------------------+
1082 | **client** | CSR1Kv | 192.168.16.30 |
1083 +--------------------------+--------------------------+--------------------------+
1084 | **server** | CSR1Kv | 192.168.16.31 |
1085 +--------------------------+--------------------------+--------------------------+
1087 Table: Nodes in the tutorial
1089 The scenario and EID allocation is the same as the OOR scenario, except that
1090 there is no **server2** and **service-node** (for now).
1092 Before this tutorial can be followed, basic connectivity between the Linux VM
1093 and the CSRs should work on the host-only network.
1098 The below steps use the command line tool cURL to talk to the LISP Flow
1099 Mapping RPC REST API. This is so that you can see the actual request
1100 URLs and body content on the page. The easy way is to just use Postman.
1102 1. Install and run the OpenDaylight distribution on the controller VM.
1103 Please follow the general `OpenDaylight Installation Guide
1104 <https://docs.opendaylight.org/en/latest/getting-started-guide/installing_opendaylight.html>`__
1105 for this step. Once the OpenDaylight controller is
1106 running install the *odl-lispflowmapping-msmr* feature from the Karaf CLI:
1110 feature:install odl-lispflowmapping-msmr
1112 It takes quite a while to load and initialize all features and their
1113 dependencies. It’s worth running the command ``log:tail`` in the
1114 Karaf console to see when the log output is winding down, and
1115 continue with the tutorial after that.
1117 2. Create the **client** and **server** VMs following the installation
1118 instructions from the `CSR1Kv Configuration Guide
1119 <https://www.cisco.com/c/en/us/td/docs/routers/csr1000/software/configuration/b_CSR1000v_Configuration_Guide.html>`_.
1121 3. Define a key and EID prefix association in OpenDaylight using the RPC REST
1122 API for the **client** and **server** EIDs (1.1.1.1/32 and 2.2.2.2/32
1123 respectively) to allow registration from the southbound. Run the below
1124 command on the **controller** (or any machine that can reach
1125 **controller**, by replacing *localhost* with the IP address of
1130 curl -u "admin":"admin" -H "Content-type: application/json" -X PUT \
1131 http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/authentication-key/ipv4:1.1.1.1%2f32/ \
1132 --data @add-key.json
1134 where the content of the *add-key.json* file is the following:
1139 "authentication-key": {
1140 "eid-uri": "ipv4:1.1.1.1/32",
1142 "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
1143 "ipv4-prefix": "1.1.1.1/32"
1145 "mapping-authkey": {
1146 "key-string": "password",
1152 The same should be done for 2.2.2.2/32 too.
1154 4. Verify that the key is added properly by requesting the following
1159 curl -u "admin":"admin" -H "Content-type: application/json" -X GET \
1160 http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/authentication-key/ipv4:1.1.1.1%2f32/
1162 The output the above invocation should look like this:
1167 "authentication-key":[
1169 "eid-uri":"ipv4:1.1.1.1/32",
1171 "ipv4-prefix":"1.1.1.1/32",
1172 "address-type":"ietf-lisp-address-types:ipv4-prefix-afi"
1175 "key-string":"password"
1182 5. Configure the CSR installations from the previous step. The EID needs to
1183 be configured on a loopback interface (except when the CSR is used as a
1184 router not a simple client like in this tutorial and the EID is assigned
1185 to a real interface).
1190 ip address 1.1.1.1 255.255.255.255
1192 6. The LISP specific configuration goes to a ``router lisp`` section in the
1193 configuration. A ``locator-set`` defines the list of locators with their
1194 priorities and weights, either statically, or better yet, as an interface
1199 locator-set rloc-network
1200 IPv4-interface GigabitEthernet2 priority 1 weight 1
1203 7. To make sure a Map-Request is using the above defined ``rloc-network``
1204 locator set, the following configuration is used:
1208 map-request itr-rlocs rloc-network
1210 8. Each Instance ID needs its own configuration. For the default Instance ID
1211 of 0, the following configuration is needed for a besic setup:
1215 eid-table default instance-id 0
1216 database-mapping 1.1.1.1/32 locator-set rloc-network
1217 map-cache 0.0.0.0/0 map-request
1218 no ipv4 map-cache-persistent
1219 ipv4 itr map-resolver 192.168.16.11
1221 ipv4 etr map-server 192.168.16.11 key password
1225 ``database-mapping`` defines the EID prefix the router will register in
1226 the mapping system and which locator set it will use (``rloc-network`` in
1227 this case, which was defined in step 6).
1229 The next line creates a static map-cache entry for the whole IPv4 EID
1230 space, causing a Map-Request to be triggered for every destination (that
1231 is not directly connected on some interface).
1233 LISP routers save their map cache to a fie which is used to restore
1234 previous state on reboot. To avoid confusion due to state restored from a
1235 previous run, ``no ipv4 map-cache-persistent`` can be used to disable this
1236 behavior for non-production testing environments.
1238 A ``map-resolver`` is then defined, where Map-Requests will be directed to
1239 for mapping lookups, and then a ``map-server`` association with a shared
1242 9. Here's the full configuration that needs to be pasted into the
1243 configuration of the **client** to follow this tutorial:
1248 ip address 1.1.1.1 255.255.255.255
1251 locator-set rloc-network
1252 IPv4-interface GigabitEthernet2 priority 1 weight 1
1255 map-request itr-rlocs rloc-network
1256 eid-table default instance-id 0
1257 database-mapping 1.1.1.1/32 locator-set rloc-network
1258 map-cache 0.0.0.0/0 map-request
1259 no ipv4 map-cache-persistent
1260 ipv4 itr map-resolver 192.168.16.11
1262 ipv4 etr map-server 192.168.16.11 key password
1268 Configuring the **server** is done by replacing ``1.1.1.1`` with
1269 ``2.2.2.2`` in the above configuration snippet.
1271 10. The CSR nodes should now register their EID-to-RLOC mappings to
1272 OpenDaylight. To verify, the corresponding EIDs can be looked up via the
1277 curl -u "admin":"admin" -H "Content-type: application/json" -X GET \
1278 http://localhost:8181/restconf/operational/odl-mappingservice:mapping-database/virtual-network-identifier/0/mapping/ipv4:1.1.1.1%2f32/southbound/
1280 An alternative way for retrieving mappings from OpenDaylight using the
1281 southbound interface is using the
1282 `lig <https://github.com/davidmeyer/lig>`_ open source tool.
1284 Yet another different way is to use the OpenDaylight mappingservice CLI,
1285 and type the following at the Karaf prompt:
1289 mappingservice:mappings
1291 This needs the *odl-lispflowmapping-mappingservice-shell* feature to be
1292 loaded. The output is intended for debugging purposes and shows the full
1293 Java objects stored in the map-cache.
1296 11. Now the LISP network is up. It can be verified by pinging the **server**
1297 EID from the **client** CSR EID:
1301 ping 2.2.2.2 source 1.1.1.1
1303 LISP Flow Mapping Support
1304 -------------------------
1306 For support the lispflowmapping project can be reached by emailing the
1307 developer mailing list: lispflowmapping-dev@lists.opendaylight.org or on
1308 the #opendaylight-lispflowmapping IRC channel on irc.freenode.net.
1310 Additional information is also available on the `Lisp Flow Mapping
1311 wiki <https://wiki.opendaylight.org/view/OpenDaylight_Lisp_Flow_Mapping:Main>`__
1313 Clustering in LISP Flow Mapping
1314 -------------------------------
1316 Documentation regarding setting up a 3-node OpenDaylight cluster is
1317 described at following `odl wiki
1318 page <https://wiki.opendaylight.org/view/Running_and_testing_an_OpenDaylight_Cluster#Three-node_cluster>`__.
1320 To turn on clustering in LISP Flow Mapping it is necessary:
1322 - run script **deploy.py** script. This script is in
1323 `integration-test <https://git.opendaylight.org/gerrit/gitweb?p=integration/test.git;a=tree>`__
1324 project placed at *tools/clustering/cluster-deployer/deploy.py*. A
1325 whole deploy.py command can looks like:
1329 <div class="informalexample">
1331 | {path\_to\_integration\_test\_project}/tools/clustering/cluster-deployer/**deploy.py**
1332 | --**distribution** {path\_to\_distribution\_in\_zip\_format}
1333 | --**rootdir** {dir\_at\_remote\_host\_where\_copy\_odl\_distribution}
1334 | --**hosts** {ip1},{ip2},{ip3}
1336 | --**template** lispflowmapping
1338 | --**user** {user\_name\_of\_remote\_hosts}
1339 | --**password** {password\_to\_remote\_hosts}
1345 | Running this script will cause that specified **distribution** to be
1346 deployed to remote **hosts** specified through their IP adresses with
1347 using credentials (**user** and **password**). The distribution will
1348 be copied to specified **rootdir**. As part of the deployment, a
1349 **template** which contains a set of controller files which are
1350 different from standard ones. In this case it is specified in
1351 | *{path\_to\_integration\_test\_project}/tools/clustering/cluster-deployer/lispflowmapping*
1353 | Lispflowmapping templates are part of integration-test project. There
1354 are 5 template files:
1356 - akka.conf.template
1358 - jolokia.xml.template
1360 - module-shards.conf.template
1362 - modules.conf.template
1364 - org.apache.karaf.features.cfg.template
1366 After copying the distribution, it is unzipped and started on all of
1367 specified **hosts** in cluster aware manner.
1372 It is necessary to have:
1374 - **unzip** program installed on all of the host
1376 - set all remote hosts /etc/sudoers files to not **requiretty** (should
1377 only matter on debian hosts)