1 .. _lispflowmapping-user-guide:
3 LISP Flow Mapping User Guide
4 ============================
9 Locator/ID Separation Protocol
10 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
12 `Locator/ID Separation Protocol
13 (LISP) <http://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) <http://tools.ietf.org/html/rfc6830#page-6>`__
24 (RLOCs) <http://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 <http://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 <http://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 <http://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 <http://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 - **GUI:** This module enables adding and querying the mapping service
115 through a GUI based on ODL DLUX.
117 - **Neutron:** This module implements the OpenDaylight Neutron Service
118 APIs. It provides integration between the LISP service and the
119 OpenDaylight Neutron service, and thus OpenStack.
121 - **Java API:** The API module exposes the Map Server and Map Resolver
122 capabilities via a Java API.
124 - **LISP Proto:** This module includes LISP protocol dependent data
125 types and associated processing.
127 - **In Memory DB:** This module includes the in memory database
128 implementation of the mapping service.
130 - **LISP Southbound Plugin:** This plugin enables data plane devices
131 that support LISP control plane protocol (see
132 `LISP <http://tools.ietf.org/search/rfc6830>`__) to register and
133 query mappings to the LISP Flow Mapping via the LISP control plane
138 Configuring LISP Flow Mapping
139 -----------------------------
141 In order to use the LISP mapping service for registering EID to RLOC
142 mappings from northbound or southbound, keys have to be defined for the
143 EID prefixes first. Once a key is defined for an EID prefix, it can be
144 used to add mappings for that EID prefix multiple times. If the service
145 is going to be used to process Map-Register messages from the southbound
146 LISP plugin, the same key must be used by the data plane device to
147 create the authentication data in the Map-Register messages for the
148 associated EID prefix.
150 The ``etc/custom.properties`` file in the Karaf distribution allows
151 configuration of several OpenDaylight parameters. The LISP service has
152 the following properties that can be adjusted:
154 **lisp.smr** (default: *false*)
155 Enables/disables the `Solicit-Map-Request
156 (SMR) <http://tools.ietf.org/html/rfc6830#section-6.6.2>`__
157 functionality. SMR is a method to notify changes in an EID-to-RLOC
158 mapping to "subscribers". The LISP service considers all
159 Map-Request’s source RLOC as a subscriber to the requested EID
160 prefix, and will send an SMR control message to that RLOC if the
163 **lisp.elpPolicy** (default: *default*)
164 Configures how to build a Map-Reply southbound message from a
165 mapping containing an Explicit Locator Path (ELP) RLOC. It is used
166 for compatibility with dataplane devices that don’t understand the
167 ELP LCAF format. The *default* setting doesn’t alter the mapping,
168 returning all RLOCs unmodified. The *both* setting adds a new RLOC
169 to the mapping, with a lower priority than the ELP, that is the next
170 hop in the service chain. To determine the next hop, it searches the
171 source RLOC of the Map-Request in the ELP, and chooses the next hop,
172 if it exists, otherwise it chooses the first hop. The *replace*
173 setting adds a new RLOC using the same algorithm as the *both*
174 setting, but using the origin priority of the ELP RLOC, which is
175 removed from the mapping.
177 **lisp.lookupPolicy** (default: *northboundFirst*)
178 Configures the mapping lookup algorithm. When set to
179 *northboundFirst* mappings programmed through the northbound API
180 will take precedence. If no northbound programmed mappings exist,
181 then the mapping service will return mappings registered through the
182 southbound plugin, if any exists. When set to
183 *northboundAndSouthbound* the mapping programmed by the northbound
184 is returned, updated by the up/down status of these mappings as
185 reported by the southbound (if existing).
187 **lisp.mappingMerge** (default: *false*)
188 Configures the merge policy on the southbound registrations through
189 the LISP SB Plugin. When set to *false*, only the latest mapping
190 registered through the SB plugin is valid in the southbound mapping
191 database, independent of which device it came from. When set to
192 *true*, mappings for the same EID registered by different devices
193 are merged together and a union of the locators is maintained as the
194 valid mapping for that EID.
196 Textual Conventions for LISP Address Formats
197 --------------------------------------------
199 In addition to the more common IPv4, IPv6 and MAC address data types,
200 the LISP control plane supports arbitrary `Address Family
201 Identifiers <http://www.iana.org/assignments/address-family-numbers>`__
202 assigned by IANA, and in addition to those the `LISP Canoncal Address
203 Format (LCAF) <https://tools.ietf.org/html/draft-ietf-lisp-lcaf>`__.
205 The LISP Flow Mapping project in OpenDaylight implements support for
206 many of these different address formats, the full list being summarized
207 in the following table. While some of the address formats have well
208 defined and widely used textual representation, many don’t. It became
209 necessary to define a convention to use for text rendering of all
210 implemented address types in logs, URLs, input fields, etc. The below
211 table lists the supported formats, along with their AFI number and LCAF
212 type, including the prefix used for disambiguation of potential overlap,
215 +------------------+----------+----------+----------+----------------------------------+
216 | Name | AFI | LCAF | Prefix | Text Rendering |
217 +==================+==========+==========+==========+==================================+
218 | **No Address** | 0 | - | no: | No Address Present |
219 +------------------+----------+----------+----------+----------------------------------+
220 | **IPv4 Prefix** | 1 | - | ipv4: | 192.0.2.0/24 |
221 +------------------+----------+----------+----------+----------------------------------+
222 | **IPv6 Prefix** | 2 | - | ipv6: | 2001:db8::/32 |
223 +------------------+----------+----------+----------+----------------------------------+
224 | **MAC Address** | 16389 | - | mac: | 00:00:5E:00:53:00 |
225 +------------------+----------+----------+----------+----------------------------------+
226 | **Distinguished | 17 | - | dn: | stringAsIs |
228 +------------------+----------+----------+----------+----------------------------------+
229 | **AS Number** | 18 | - | as: | AS64500 |
230 +------------------+----------+----------+----------+----------------------------------+
231 | **AFI List** | 16387 | 1 | list: | {192.0.2.1,192.0.2.2,2001:db8::1 |
233 +------------------+----------+----------+----------+----------------------------------+
234 | **Instance ID** | 16387 | 2 | - | [223] 192.0.2.0/24 |
235 +------------------+----------+----------+----------+----------------------------------+
236 | **Application | 16387 | 4 | appdata: | 192.0.2.1!128!17!80-81!6667-7000 |
238 +------------------+----------+----------+----------+----------------------------------+
239 | **Explicit | 16387 | 10 | elp: | {192.0.2.1→192.0.2.2\|lps→192.0. |
240 | Locator Path** | | | | 2.3} |
241 +------------------+----------+----------+----------+----------------------------------+
242 | **Source/Destina | 16387 | 12 | srcdst: | 192.0.2.1/32\|192.0.2.2/32 |
245 +------------------+----------+----------+----------+----------------------------------+
246 | **Key/Value | 16387 | 15 | kv: | 192.0.2.1⇒192.0.2.2 |
247 | Address Pair** | | | | |
248 +------------------+----------+----------+----------+----------------------------------+
249 | **Service Path** | 16387 | N/A | sp: | 42(3) |
250 +------------------+----------+----------+----------+----------------------------------+
252 Table: LISP Address Formats
254 Please note that the forward slash character ``/`` typically separating
255 IPv4 and IPv6 addresses from the mask length is transformed into ``%2f``
261 In this section we will discuss two types of Karaf commands: built-in,
262 and LISP specific. Some built-in commands are quite useful, and are
263 needed for the tutorial, so they will be discussed here. A reference of
264 all LISP specific commands, added by the LISP Flow Mapping project is
265 also included. They are useful mostly for debugging.
267 Useful built-in commands
268 ~~~~~~~~~~~~~~~~~~~~~~~~
271 Lists all available command, with a short description of each.
273 ``help <command_name>``
274 Show detailed help about a specific command.
276 ``feature:list [-i]``
277 Show all locally available features in the Karaf container. The
278 ``-i`` option lists only features that are currently installed. It
279 is possible to use ``| grep`` to filter the output (for all
280 commands, not just this one).
282 ``feature:install <feature_name>``
283 Install feature ``feature_name``.
285 ``log:set <level> <class>``
286 Set the log level for ``class`` to ``level``. The default log level
287 for all classes is INFO. For debugging, or learning about LISP
288 internals it is useful to run
289 ``log:set TRACE org.opendaylight.lispflowmapping`` right after Karaf
293 Outputs the log file to the console, and returns control to the
297 Continuously shows log output, requires ``Ctrl+C`` to return to the
300 LISP specific commands
301 ~~~~~~~~~~~~~~~~~~~~~~
303 The available lisp commands can always be obtained by
304 ``help mappingservice``. Currently they are:
306 ``mappingservice:addkey``
307 Add the default password ``password`` for the IPv4 EID prefix
308 0.0.0.0/0 (all addresses). This is useful when experimenting with
309 southbound devices, and using the REST interface would be combersome
312 ``mappingservice:mappings``
313 Show the list of all mappings stored in the internal non-persistent
314 data store (the DAO), listing the full data structure. The output is
315 not human friendly, but can be used for debugging.
317 LISP Flow Mapping Karaf Features
318 --------------------------------
320 LISP Flow Mapping has the following Karaf features that can be installed
321 from the Karaf console:
323 ``odl-lispflowmapping-msmr``
324 This includes the core features required to use the LISP Flow
325 Mapping Service such as mapping service and the LISP southbound
328 ``odl-lispflowmapping-ui``
329 This includes the GUI module for the LISP Mapping Service.
331 ``odl-lispflowmapping-neutron``
332 This is the experimental Neutron provider module for LISP mapping
338 This section provides a tutorial demonstrating various features in this
339 service. We have included tutorials using two forwarding platforms:
341 1. Using `Open Overlay Router (OOR) <https://github.com/OpenOverlayRouter/oor#overview>`__
343 2. Using `FD.io <https://wiki.fd.io/view/ONE>`__
345 Both have different approaches to create the overlay but ultimately do the
346 same job. Details of both approaches have been explained below.
348 Creating a LISP overlay with OOR
349 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
351 This section provides instructions to set up a LISP network of three
352 nodes (one "client" node and two "server" nodes) using OOR as data
353 plane LISP nodes and the LISP Flow Mapping project from OpenDaylight as
354 the LISP programmable mapping system for the LISP network.
359 The steps shown below will demonstrate setting up a LISP network between
360 a client and two servers, then performing a failover between the two
366 - **OpenDaylight Carbon**
370 - **The Postman Chrome App**: the most convenient way to follow along
371 this tutorial is to use the `Postman
372 App <https://www.getpostman.com/apps>`__
373 to edit and send the requests. The project git repository hosts a
374 collection of the requests that are used in this tutorial in the
375 ``resources/tutorial/OOR/Beryllium_Tutorial.json.postman_collection``
376 file. You can import this file to Postman by clicking *Import* at the
377 top, choosing *Download from link* and then entering the following
379 `<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/carbon>`__.
380 Alternatively, you can save the file on your machine, or if you have
381 the repository checked out, you can import from there. You will need
382 to create a new Postman Environment and define some variables within:
383 ``controllerHost`` set to the hostname or IP address of the machine
384 running the OpenDaylight instance, and ``restconfPort`` to 8181, if you didn’t
385 modify the default controller settings.
387 - **OOR version 1.0 or later** The README.md lists the dependencies needed
388 to build it from source.
390 - **A virtualization platform**
395 The three LISP data plane nodes and the LISP mapping system are assumed
396 to be running in Linux virtual machines, which have the ``eth0``
397 interface in NAT mode to allow outside internet access and ``eth1``
398 connected to a host-only network, with the following IP addresses
399 (please adjust configuration files, JSON examples, etc. accordingly if
400 you’re using another addressing scheme):
402 +--------------------------+--------------------------+--------------------------+
403 | Node | Node Type | IP Address |
404 +==========================+==========================+==========================+
405 | **controller** | OpenDaylight | 192.168.16.11 |
406 +--------------------------+--------------------------+--------------------------+
407 | **client** | OOR | 192.168.16.30 |
408 +--------------------------+--------------------------+--------------------------+
409 | **server1** | OOR | 192.168.16.31 |
410 +--------------------------+--------------------------+--------------------------+
411 | **server2** | OOR | 192.168.16.32 |
412 +--------------------------+--------------------------+--------------------------+
413 | **service-node** | OOR | 192.168.16.33 |
414 +--------------------------+--------------------------+--------------------------+
416 Table: Nodes in the tutorial
418 The figure below gives a sketch of network topology that will be used in the tutorial.
420 .. figure:: ./images/tutorial_architecture_diagram.png
421 :alt: Network architecture of the tutorial
423 In LISP terminology **client**, **server1** and **server2** are mobile nodes (MN in OOR),
424 **controller** is a MS/MR and **service-node** is a RTR.
428 While the tutorial uses OOR as the data plane, it could be any
429 LISP-enabled hardware or software router (commercial/open source).
434 The below steps use the command line tool cURL to talk to the LISP Flow
435 Mapping RPC REST API. This is so that you can see the actual request
436 URLs and body content on the page.
438 1. Install and run OpenDaylight Carbon release on the controller VM.
439 Please follow the general OpenDaylight Carbon Installation Guide
440 for this step. Once the OpenDaylight controller is running install
441 the *odl-lispflowmapping-msmr* feature from the Karaf CLI:
445 feature:install odl-lispflowmapping-msmr
447 It takes quite a while to load and initialize all features and their
448 dependencies. It’s worth running the command ``log:tail`` in the
449 Karaf console to see when the log output is winding down, and
450 continue with the tutorial after that.
452 2. Install OOR on the **client**, **server1**, **server2**, and
453 **service-node** VMs following the installation instructions `from
455 file <https://github.com/OpenOverlayRouter/oor#software-prerequisites>`__.
457 3. Configure the OOR installations from the previous step. Take a look
458 at the ``oor.conf.example`` to get a general idea of the structure
459 of the conf file. First, check if the file ``/etc/oor.conf`` exists.
460 If the file doesn't exist, create the file ``/etc/oor.conf``. Set the
461 EID in ``/etc/oor.conf`` file from the IP address space selected
462 for your virtual/LISP network. In this tutorial the EID of the
463 **client** is set to 1.1.1.1/32, and that of **server1** and
464 **server2** to 2.2.2.2/32.
466 4. Set the RLOC interface to ``eth1`` in each ``oor.conf`` file. LISP
467 will determine the RLOC (IP address of the corresponding VM) based
470 5. Set the Map-Resolver address to the IP address of the
471 **controller**, and on the **client** the Map-Server too. On
472 **server1** and **server2** remove the Map-Server configuration, so
473 that it doesn’t interfere with the mappings on the controller, since
474 we’re going to program them manually.
476 6. Modify the "key" parameter in each ``oor.conf`` file to a
477 key/password of your choice (*password* in this tutorial).
481 The ``resources/tutorial/OOR`` directory in the *stable/carbon*
482 branch of the project git repository has the files used in the
484 in <https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=tree;f=resources/tutorial/OOR;hb=refs/heads/stable/carbon>`__,
485 so you can just copy the files to ``/etc/oor.conf`` on the
486 respective VMs. You will also find the JSON files referenced
487 below in the same directory.
489 7. Define a key and EID prefix association in OpenDaylight using the
490 RPC REST API for the **client** EID (1.1.1.1/32) to allow
491 registration from the southbound. Since the mappings for the server
492 EID will be configured from the REST API, no such association is
493 necessary. Run the below command on the **controller** (or any
494 machine that can reach **controller**, by replacing *localhost* with
495 the IP address of **controller**).
499 curl -u "admin":"admin" -H "Content-type: application/json" -X PUT \
500 http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/authentication-key/ipv4:1.1.1.1%2f32/ \
503 where the content of the *add-key.json* file is the following:
508 "authentication-key": {
509 "eid-uri": "ipv4:1.1.1.1/32",
511 "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
512 "ipv4-prefix": "1.1.1.1/32"
515 "key-string": "password",
521 8. Verify that the key is added properly by requesting the following
526 curl -u "admin":"admin" -H "Content-type: application/json" -X GET \
527 http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/authentication-key/ipv4:1.1.1.1%2f32/
529 The output the above invocation should look like this:
534 "authentication-key":[
536 "eid-uri":"ipv4:1.1.1.1/32",
538 "ipv4-prefix":"1.1.1.1/32",
539 "address-type":"ietf-lisp-address-types:ipv4-prefix-afi"
542 "key-string":"password"
549 9. Run the ``oor`` OOR daemon on all VMs:
555 For more information on accessing OOR logs, take a look at
556 `OOR README <https://github.com/OpenOverlayRouter/oor#readme>`__
557 10. The **client** OOR node should now register its EID-to-RLOC
558 mapping in OpenDaylight. To verify you can lookup the corresponding
559 EIDs via the REST API
563 curl -u "admin":"admin" -H "Content-type: application/json" -X GET \
564 http://localhost:8181/restconf/operational/odl-mappingservice:mapping-database/virtual-network-identifier/0/mapping/ipv4:1.1.1.1%2f32/southbound/
566 An alternative way for retrieving mappings from OpenDaylight using the
567 southbound interface is using the
568 ```lig`` <https://github.com/davidmeyer/lig>`__ open source tool.
570 11. Register the EID-to-RLOC mapping of the server EID 2.2.2.2/32 to the
571 controller, pointing to **server1** and **server2** with a higher
572 priority for **server1**
576 curl -u "admin":"admin" -H "Content-type: application/json" -X PUT \
577 http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/mapping/ipv4:2.2.2.2%2f32/northbound/ \
580 where the *mapping.json* file looks like this:
586 "eid-uri": "ipv4:2.2.2.2/32",
587 "origin": "northbound",
590 "action": "NoAction",
591 "authoritative": true,
593 "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
594 "ipv4-prefix": "2.2.2.2/32"
598 "locator-id": "server1",
601 "multicastPriority": 255,
602 "multicastWeight": 0,
603 "localLocator": true,
607 "address-type": "ietf-lisp-address-types:ipv4-afi",
608 "ipv4": "192.168.16.31"
612 "locator-id": "server2",
615 "multicastPriority": 255,
616 "multicastWeight": 0,
617 "localLocator": true,
621 "address-type": "ietf-lisp-address-types:ipv4-afi",
622 "ipv4": "192.168.16.32"
630 Here the priority of the second RLOC (192.168.16.32 - **server2**)
631 is 2, a higher numeric value than the priority of 192.168.16.31,
632 which is 1. This policy is saying that **server1** is preferred to
633 **server2** for reaching EID 2.2.2.2/32. Note that lower priority
634 value has higher preference in LISP.
636 12. Verify the correct registration of the 2.2.2.2/32 EID:
640 curl -u "admin":"admin" -H "Content-type: application/json" -X GET \
641 http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/mapping/ipv4:2.2.2.2%2f32/northbound/
643 13. Now the LISP network is up. To verify, log into the **client** VM
644 and ping the server EID:
650 14. Let’s test fail-over now. Suppose you had a service on **server1**
651 which became unavailable, but **server1** itself is still reachable.
652 LISP will not automatically fail over, even if the mapping for
653 2.2.2.2/32 has two locators, since both locators are still reachable
654 and uses the one with the higher priority (lowest priority value).
655 To force a failover, we need to set the priority of **server2** to a
656 lower value. Using the file mapping.json above, swap the priority
657 values between the two locators (lines 14 and 28 in *mapping.json*)
658 and repeat the request from step 11. You can also repeat step 12 to
659 see if the mapping is correctly registered. If you leave the ping
660 on, and monitor the traffic using wireshark, you can see that the
661 ping traffic to 2.2.2.2 will be diverted from the **server1** RLOC
662 to the **server2** RLOC.
664 With the default OpenDaylight configuration the failover should be
665 near instantaneous (we observed 3 lost pings in the worst case),
666 because of the LISP `Solicit-Map-Request (SMR)
667 mechanism <http://tools.ietf.org/html/rfc6830#section-6.6.2>`__ that
668 can ask a LISP data plane element to update its mapping for a
669 certain EID (enabled by default). It is controlled by the
670 ``lisp.smr`` variable in ``etc/custom.porperties``. When enabled,
671 any mapping change from the RPC interface will trigger an SMR packet
672 to all data plane elements that have requested the mapping in the
673 last 24 hours (this value was chosen because it’s the default TTL of
674 Cisco IOS xTR mapping registrations). If disabled, ITRs keep their
675 mappings until the TTL specified in the Map-Reply expires.
677 15. To add a service chain into the path from the client to the server,
678 we can use an Explicit Locator Path, specifying the **service-node**
679 as the first hop and **server1** (or **server2**) as the second hop.
680 The following will achieve that:
684 curl -u "admin":"admin" -H "Content-type: application/json" -X PUT \
685 http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/mapping/ipv4:2.2.2.2%2f32/northbound/ \
688 where the *elp.json* file is as follows:
694 "eid-uri": "ipv4:2.2.2.2/32",
695 "origin": "northbound",
698 "action": "NoAction",
699 "authoritative": true,
701 "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
702 "ipv4-prefix": "2.2.2.2/32"
709 "multicastPriority": 255,
710 "multicastWeight": 0,
711 "localLocator": true,
715 "address-type": "ietf-lisp-address-types:explicit-locator-path-lcaf",
716 "explicit-locator-path": {
719 "hop-id": "service-node",
720 "address": "192.168.16.33",
725 "address": "192.168.16.31",
737 After the mapping for 2.2.2.2/32 is updated with the above, the ICMP
738 traffic from **client** to **server1** will flow through the
739 **service-node**. You can confirm this in the OOR logs, or by
740 sniffing the traffic on either the **service-node** or **server1**.
741 Note that service chains are unidirectional, so unless another ELP
742 mapping is added for the return traffic, packets will go from
743 **server1** to **client** directly.
745 16. Suppose the **service-node** is actually a firewall, and traffic is
746 diverted there to support access control lists (ACLs). In this
747 tutorial that can be emulated by using ``iptables`` firewall rules
748 in the **service-node** VM. To deny traffic on the service chain
749 defined above, the following rule can be added:
753 iptables -A OUTPUT --dst 192.168.16.31 -j DROP
755 The ping from the **client** should now have stopped.
757 In this case the ACL is done on the destination RLOC. There is an
758 effort underway in the OOR community to allow filtering on EIDs,
759 which is the more logical place to apply ACLs.
761 17. To delete the rule and restore connectivity on the service chain,
762 delete the ACL by issuing the following command:
766 iptables -D OUTPUT --dst 192.168.16.31 -j DROP
768 which should restore connectivity.
771 Creating a simple LISP overlay with FD.io
772 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
774 In this section, we use the Overlay Network Engine (ONE) project in FD.io
775 to facilitate fully scripted setup and testing of a LISP/VXLAN-GPE network.
776 Overlay Network Engine (ONE) is a `FD.io <https://fd.io/>`__ project that enables programmable
777 dynamic software defined overlays. Details about this project can be
778 found in `ONE wiki <https://wiki.fd.io/view/ONE>`__.
780 The steps shown below will demonstrate setting up a LISP network between
781 a client and a server using VPP. We demonstrate how to use VPP lite to
782 build a IP4 LISP overlay on an Ubuntu host using namespaces and af_packet
783 interfaces. All configuration files used in the tutorials can be found
784 `here <https://gerrit.fd.io/r/gitweb?p=one.git;a=tree;f=tutorial;hb=HEAD>`__.
789 - **OpenDaylight Carbon**
791 - **The Postman Chrome App**: Please follow the instructions_ and import
792 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=HEAD>`__.
794 - **Vagrant** (optional): Download it from `Vagrant website <https://www.vagrantup.com/downloads.html>`__
795 and follow the setup instructions.
800 Unlike the case with OOR, we use network namespace functionality of Linux
801 to create the overlay in this case. The following table contains ip addresses
802 of nodes in the overlay topology used in the tutorial. Our objective will be to
803 create this topology and be able to ping from client to server through an
804 intermediary hop, **service node**, which is a ``rtr node`` providing the
805 service of re-encapsulation. So, all the packets from client to server
806 will be through this **service node**.
808 +--------------------------+--------------------------+--------------------------+
809 | Node | Node Type | IP Address |
810 +==========================+==========================+==========================+
811 | **controller** | OpenDaylight | 6.0.3.100 |
812 +--------------------------+--------------------------+--------------------------+
813 | **client** | VPP | 6.0.2.2 |
814 +--------------------------+--------------------------+--------------------------+
815 | **server** | VPP | 6.0.4.4 |
816 +--------------------------+--------------------------+--------------------------+
817 | **service node** | VPP | 6.0.3.3 |
818 +--------------------------+--------------------------+--------------------------+
820 Table: Nodes in the tutorial
822 The figure below gives a sketch of network topology that will be used in the tutorial.
824 .. figure:: ./images/one_ODL_architecture.png
825 :alt: Network architecture of the tutorial for FD.io
830 Follow the instructions below sequentially.
832 1. Pull the VPP code anonymously using:
835 git clone https://gerrit.fd.io/r/vpp
837 2. Then, use the vagrant file from repository to build virtual machine
838 with proper environment.
841 cd vpp/build-root/vagrant/
845 3. In case there is any error from ``vagrant up``, try ``vargant ssh``. if
846 it works, no worries. If it still doesn't work, you can try any Ubuntu virtual
847 machine. Or sometimes there is an issue with the Vagrant properly copying
848 the VPP repo code from the host VM after the first installation. In that
849 case ``/vpp`` doesn't exist. In both cases, follow the instructions
852 1. Clone the code in ``/`` directory. So, the codes will be in ``/vpp``.
854 2. Run the following commands:
860 make V=0 PLATFORM=vpp TAG=vpp install-deb
861 sudo dpkg -i /vpp/build-root/*.deb
863 Alternative and more detailed build instructions can be found in
864 `VPP's wiki <https://wiki.fd.io/view/VPP/Build,_install,_and_test_images>`__
865 4. By now, you should have a Ubuntu VM with VPP repository in ``/vpp``
866 with ``sudo`` access. Now, we need VPP Lite build. The following commands
871 export PLATFORM=vpp_lite
874 Successful build create the binary in ``/vpp/build-root/install-vpp_lite_debug-native/vpp/bin``
876 5. Install bridge-utils and ethtool if needed by using following commands:
879 sudo apt-get install bridge-utils ethtool
881 6. Now, install and run OpenDaylight Carbon release on the VM. Please
882 follow the general OpenDaylight Carbon Installation Guide for this
883 step from :ref:`install_odl`. Before running OpenDaylight, we need
884 to change the configuration for RTR to work. Update ``etc/custom.properties``
885 with the ``lisp.elpPolicy`` to be replace.
888 lisp.elpPolicy = replace
890 Then, run OpenDaylight. For details regarding configuring LISP
891 Flow Mapping, please take a look at :ref:`lfm_config`.
892 Once the OpenDaylight controller is running install the *odl-lispflowmapping-msmr*
893 feature from the Karaf CLI:
897 feature:install odl-lispflowmapping-msmr
899 It may take quite a while to load and initialize all features and their
900 dependencies. It’s worth running the command ``log:tail`` in the
901 Karaf console to see when the log output is winding down, and
902 continue with the tutorial after that.
904 7. For setting up VPP, get the files from ``resources/tutorial/FD_io``
905 folder of the lispflowmapping repo. The files can also be found `here
906 <https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=tree;f=resources/tutorial/FD_io;hb=refs/heads/stable/carbon>`__.
907 Copy the ``vpp1.config``, ``vpp2.config`` and ``rtr.config`` files in
910 8. In this example, VPP doesn't make any southbound map registers to OpenDaylight.
911 So, we add the mappings directly from northbound. For that, we need
912 to add the mappings to OpenDaylight via RESTCONF API.
914 Register EID-to-RLOC mapping of the Client EID 6.0.2.0/24.
917 curl -u "admin":"admin" -H "Content-type: application/json" -X PUT \
918 http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/mapping/ipv4:6.0.2.0%2f24/northbound/ \
921 Content of epl1.json:
927 "eid-uri": "ipv4:6.0.2.0/24",
928 "origin": "northbound",
931 "action": "NoAction",
932 "authoritative": true,
934 "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
935 "ipv4-prefix": "6.0.2.0/24"
942 "multicastPriority": 255,
943 "multicastWeight": 0,
944 "localLocator": true,
948 "address-type": "ietf-lisp-address-types:explicit-locator-path-lcaf",
949 "explicit-locator-path": {
953 "address": "6.0.3.3",
954 "lrs-bits": "lookup rloc-probe strict"
958 "address": "6.0.3.1",
959 "lrs-bits": "lookup strict"
971 Similarly add EID-to-RLOC mapping of the Server EID 6.0.4.0/24.
974 curl -u "admin":"admin" -H "Content-type: application/json" -X PUT \
975 http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/mapping/ipv4:6.0.4.0%2f24/northbound/ \
978 Content of elp2.json:
984 "eid-uri": "ipv4:6.0.4.0/24",
985 "origin": "northbound",
988 "action": "NoAction",
989 "authoritative": true,
991 "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
992 "ipv4-prefix": "6.0.4.0/24"
999 "multicastPriority": 255,
1000 "multicastWeight": 0,
1001 "localLocator": true,
1002 "rlocProbed": false,
1005 "address-type": "ietf-lisp-address-types:explicit-locator-path-lcaf",
1006 "explicit-locator-path": {
1010 "address": "6.0.3.3",
1011 "lrs-bits": "lookup rloc-probe strict"
1015 "address": "6.0.3.2",
1016 "lrs-bits": "lookup strict"
1027 The JSON files regarding these can be found in `here
1028 <https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=tree;f=resources/tutorial/FD_io;hb=refs/heads/stable/carbon>`__.
1029 Even though there is no southbound registration for mapping to OpenDaylight, using
1030 northbound policy we can specify mappings, when Client requests for
1031 the Server eid, Client gets a reply from OpenDaylight.
1033 9. Assuming all files have been created and OpenDaylight has been configured as
1034 explained above, execute the host script you've created or the ``topology_setup.sh``
1035 script from `here <https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=tree;f=resources/tutorial/FD_io;hb=refs/heads/stable/carbon>`__.
1037 10. If all goes well, you can now test connectivity between the namespaces with:
1040 sudo ip netns exec vpp-ns1 ping 6.0.4.4
1042 11. Traffic and control plane message exchanges can be checked with a wireshark
1043 listening on the odl interface.
1044 12. .. important:: Delete the topology by running the ``topology_setup.sh`` with ``clean`` argument.
1047 sudo ./topology_setup.sh clean
1049 LISP Flow Mapping Support
1050 -------------------------
1052 For support the lispflowmapping project can be reached by emailing the
1053 developer mailing list: lispflowmapping-dev@lists.opendaylight.org or on
1054 the #opendaylight-lispflowmapping IRC channel on irc.freenode.net.
1056 Additional information is also available on the `Lisp Flow Mapping
1057 wiki <https://wiki.opendaylight.org/view/OpenDaylight_Lisp_Flow_Mapping:Main>`__
1059 Clustering in LISP Flow Mapping
1060 -------------------------------
1062 Documentation regarding setting up a 3-node OpenDaylight cluster is
1063 described at following `odl wiki
1064 page <https://wiki.opendaylight.org/view/Running_and_testing_an_OpenDaylight_Cluster#Three-node_cluster>`__.
1066 To turn on clustering in LISP Flow Mapping it is necessary:
1068 - run script **deploy.py** script. This script is in
1069 `integration-test <https://git.opendaylight.org/gerrit/integration/test>`__
1070 project placed at *tools/clustering/cluster-deployer/deploy.py*. A
1071 whole deploy.py command can looks like:
1075 <div class="informalexample">
1077 | {path\_to\_integration\_test\_project}/tools/clustering/cluster-deployer/**deploy.py**
1078 | --**distribution** {path\_to\_distribution\_in\_zip\_format}
1079 | --**rootdir** {dir\_at\_remote\_host\_where\_copy\_odl\_distribution}
1080 | --**hosts** {ip1},{ip2},{ip3}
1082 | --**template** lispflowmapping
1084 | --**user** {user\_name\_of\_remote\_hosts}
1085 | --**password** {password\_to\_remote\_hosts}
1091 | Running this script will cause that specified **distribution** to be
1092 deployed to remote **hosts** specified through their IP adresses with
1093 using credentials (**user** and **password**). The distribution will
1094 be copied to specified **rootdir**. As part of the deployment, a
1095 **template** which contains a set of controller files which are
1096 different from standard ones. In this case it is specified in
1097 | *{path\_to\_integration\_test\_project}/tools/clustering/cluster-deployer/lispflowmapping*
1099 | Lispflowmapping templates are part of integration-test project. There
1100 are 5 template files:
1102 - akka.conf.template
1104 - jolokia.xml.template
1106 - module-shards.conf.template
1108 - modules.conf.template
1110 - org.apache.karaf.features.cfg.template
1112 After copying the distribution, it is unzipped and started on all of
1113 specified **hosts** in cluster aware manner.
1118 It is necessary to have:
1120 - **unzip** program installed on all of the host
1122 - set all remote hosts /etc/sudoers files to not **requiretty** (should
1123 only matter on debian hosts)