1 LISP Flow Mapping User Guide
2 ============================
7 Locator/ID Separation Protocol
8 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 `Locator/ID Separation Protocol
11 (LISP) <http://tools.ietf.org/html/rfc6830>`__ is a technology that
12 provides a flexible map-and-encap framework that can be used for overlay
13 network applications such as data center network virtualization and
14 Network Function Virtualization (NFV).
16 LISP provides the following name spaces:
18 - `Endpoint Identifiers
19 (EIDs) <http://tools.ietf.org/html/rfc6830#page-6>`__
22 (RLOCs) <http://tools.ietf.org/html/rfc6830#section-3>`__
24 In a virtualization environment EIDs can be viewed as virtual address
25 space and RLOCs can be viewed as physical network address space.
27 The LISP framework decouples network control plane from the forwarding
30 - A data plane that specifies how the virtualized network addresses are
31 encapsulated in addresses from the underlying physical network.
33 - A control plane that stores the mapping of the virtual-to-physical
34 address spaces, the associated forwarding policies and serves this
35 information to the data plane on demand.
37 Network programmability is achieved by programming forwarding policies
38 such as transparent mobility, service chaining, and traffic engineering
39 in the mapping system; where the data plane elements can fetch these
40 policies on demand as new flows arrive. This chapter describes the LISP
41 Flow Mapping project in OpenDaylight and how it can be used to enable
42 advanced SDN and NFV use cases.
44 LISP data plane Tunnel Routers are available at
45 `OpenOverlayRouter.org <http://www.openoverlayrouter.org/>`__ in the open source community on
46 the following platforms:
54 For more details and support for LISP data plane software please visit
55 `the OOR web site <http://www.openoverlayrouter.org/>`__.
57 LISP Flow Mapping Service
58 ~~~~~~~~~~~~~~~~~~~~~~~~~
60 The LISP Flow Mapping service provides LISP Mapping System services.
61 This includes LISP Map-Server and LISP Map-Resolver services to store
62 and serve mapping data to data plane nodes as well as to OpenDaylight
63 applications. Mapping data can include mapping of virtual addresses to
64 physical network address where the virtual nodes are reachable or hosted
65 at. Mapping data can also include a variety of routing policies
66 including traffic engineering and load balancing. To leverage this
67 service, OpenDaylight applications and services can use the northbound
68 REST API to define the mappings and policies in the LISP Mapping
69 Service. Data plane devices capable of LISP control protocol can
70 leverage this service through a southbound LISP plugin. LISP-enabled
71 devices must be configured to use this OpenDaylight service as their Map
72 Server and/or Map Resolver.
74 The southbound LISP plugin supports the LISP control protocol
75 (Map-Register, Map-Request, Map-Reply messages), and can also be used to
76 register mappings in the OpenDaylight mapping service.
78 LISP Flow Mapping Architecture
79 ------------------------------
81 The following figure shows the various LISP Flow Mapping modules.
83 .. figure:: ./images/ODL_lfm_Be_component.jpg
84 :alt: LISP Mapping Service Internal Architecture
86 LISP Mapping Service Internal Architecture
88 A brief description of each module is as follows:
90 - **DAO (Data Access Object):** This layer separates the LISP logic
91 from the database, so that we can separate the map server and map
92 resolver from the specific implementation of the mapping database.
93 Currently we have an implementation of this layer with an in-memory
94 HashMap, but it can be switched to any other key/value store and you
95 only need to implement the ILispDAO interface.
97 - **Map Server:** This module processes the adding or registration of
98 authentication tokens (keys) and mappings. For a detailed
99 specification of LISP Map Server, see
100 `LISP <http://tools.ietf.org/search/rfc6830>`__.
102 - **Map Resolver:** This module receives and processes the mapping
103 lookup queries and provides the mappings to requester. For a detailed
104 specification of LISP Map Server, see
105 `LISP <http://tools.ietf.org/search/rfc6830>`__.
107 - **RPC/RESTCONF:** This is the auto-generated RESTCONF-based
108 northbound API. This module enables defining key-EID associations as
109 well as adding mapping information through the Map Server. Key-EID
110 associations and mappings can also be queried via this API.
112 - **GUI:** This module enables adding and querying the mapping service
113 through a GUI based on ODL DLUX.
115 - **Neutron:** This module implements the OpenDaylight Neutron Service
116 APIs. It provides integration between the LISP service and the
117 OpenDaylight Neutron service, and thus OpenStack.
119 - **Java API:** The API module exposes the Map Server and Map Resolver
120 capabilities via a Java API.
122 - **LISP Proto:** This module includes LISP protocol dependent data
123 types and associated processing.
125 - **In Memory DB:** This module includes the in memory database
126 implementation of the mapping service.
128 - **LISP Southbound Plugin:** This plugin enables data plane devices
129 that support LISP control plane protocol (see
130 `LISP <http://tools.ietf.org/search/rfc6830>`__) to register and
131 query mappings to the LISP Flow Mapping via the LISP control plane
136 Configuring LISP Flow Mapping
137 -----------------------------
139 In order to use the LISP mapping service for registering EID to RLOC
140 mappings from northbound or southbound, keys have to be defined for the
141 EID prefixes first. Once a key is defined for an EID prefix, it can be
142 used to add mappings for that EID prefix multiple times. If the service
143 is going to be used to process Map-Register messages from the southbound
144 LISP plugin, the same key must be used by the data plane device to
145 create the authentication data in the Map-Register messages for the
146 associated EID prefix.
148 The ``etc/custom.properties`` file in the Karaf distribution allows
149 configuration of several OpenDaylight parameters. The LISP service has
150 the following properties that can be adjusted:
152 **lisp.mappingOverwrite** (default: *true*)
153 Configures handling of mapping updates. When set to *true* (default)
154 a mapping update (either through the southbound plugin via a
155 Map-Register message or through a northbound API PUT REST call) the
156 existing RLOC set associated to an EID prefix is overwritten. When
157 set to *false*, the RLOCs of the update are merged to the existing
160 **lisp.smr** (default: *false*)
161 Enables/disables the `Solicit-Map-Request
162 (SMR) <http://tools.ietf.org/html/rfc6830#section-6.6.2>`__
163 functionality. SMR is a method to notify changes in an EID-to-RLOC
164 mapping to "subscribers". The LISP service considers all
165 Map-Request’s source RLOC as a subscriber to the requested EID
166 prefix, and will send an SMR control message to that RLOC if the
169 **lisp.elpPolicy** (default: *default*)
170 Configures how to build a Map-Reply southbound message from a
171 mapping containing an Explicit Locator Path (ELP) RLOC. It is used
172 for compatibility with dataplane devices that don’t understand the
173 ELP LCAF format. The *default* setting doesn’t alter the mapping,
174 returning all RLOCs unmodified. The *both* setting adds a new RLOC
175 to the mapping, with a lower priority than the ELP, that is the next
176 hop in the service chain. To determine the next hop, it searches the
177 source RLOC of the Map-Request in the ELP, and chooses the next hop,
178 if it exists, otherwise it chooses the first hop. The *replace*
179 setting adds a new RLOC using the same algorithm as the *both*
180 setting, but using the origin priority of the ELP RLOC, which is
181 removed from the mapping.
183 **lisp.lookupPolicy** (default: *northboundFirst*)
184 Configures the mapping lookup algorithm. When set to
185 *northboundFirst* mappings programmed through the northbound API
186 will take precedence. If no northbound programmed mappings exist,
187 then the mapping service will return mappings registered through the
188 southbound plugin, if any exists. When set to
189 *northboundAndSouthbound* the mapping programmed by the northbound
190 is returned, updated by the up/down status of these mappings as
191 reported by the southbound (if existing).
193 **lisp.mappingMerge** (default: *false*)
194 Configures the merge policy on the southbound registrations through
195 the LISP SB Plugin. When set to *false*, only the latest mapping
196 registered through the SB plugin is valid in the southbound mapping
197 database, independent of which device it came from. When set to
198 *true*, mappings for the same EID registered by different devices
199 are merged together and a union of the locators is maintained as the
200 valid mapping for that EID.
202 Textual Conventions for LISP Address Formats
203 --------------------------------------------
205 In addition to the more common IPv4, IPv6 and MAC address data types,
206 the LISP control plane supports arbitrary `Address Family
207 Identifiers <http://www.iana.org/assignments/address-family-numbers>`__
208 assigned by IANA, and in addition to those the `LISP Canoncal Address
209 Format (LCAF) <https://tools.ietf.org/html/draft-ietf-lisp-lcaf>`__.
211 The LISP Flow Mapping project in OpenDaylight implements support for
212 many of these different address formats, the full list being summarized
213 in the following table. While some of the address formats have well
214 defined and widely used textual representation, many don’t. It became
215 necessary to define a convention to use for text rendering of all
216 implemented address types in logs, URLs, input fields, etc. The below
217 table lists the supported formats, along with their AFI number and LCAF
218 type, including the prefix used for disambiguation of potential overlap,
221 +------------------+----------+----------+----------+----------------------------------+
222 | Name | AFI | LCAF | Prefix | Text Rendering |
223 +==================+==========+==========+==========+==================================+
224 | **No Address** | 0 | - | no: | No Address Present |
225 +------------------+----------+----------+----------+----------------------------------+
226 | **IPv4 Prefix** | 1 | - | ipv4: | 192.0.2.0/24 |
227 +------------------+----------+----------+----------+----------------------------------+
228 | **IPv6 Prefix** | 2 | - | ipv6: | 2001:db8::/32 |
229 +------------------+----------+----------+----------+----------------------------------+
230 | **MAC Address** | 16389 | - | mac: | 00:00:5E:00:53:00 |
231 +------------------+----------+----------+----------+----------------------------------+
232 | **Distinguished | 17 | - | dn: | stringAsIs |
234 +------------------+----------+----------+----------+----------------------------------+
235 | **AS Number** | 18 | - | as: | AS64500 |
236 +------------------+----------+----------+----------+----------------------------------+
237 | **AFI List** | 16387 | 1 | list: | {192.0.2.1,192.0.2.2,2001:db8::1 |
239 +------------------+----------+----------+----------+----------------------------------+
240 | **Instance ID** | 16387 | 2 | - | [223] 192.0.2.0/24 |
241 +------------------+----------+----------+----------+----------------------------------+
242 | **Application | 16387 | 4 | appdata: | 192.0.2.1!128!17!80-81!6667-7000 |
244 +------------------+----------+----------+----------+----------------------------------+
245 | **Explicit | 16387 | 10 | elp: | {192.0.2.1→192.0.2.2\|lps→192.0. |
246 | Locator Path** | | | | 2.3} |
247 +------------------+----------+----------+----------+----------------------------------+
248 | **Source/Destina | 16387 | 12 | srcdst: | 192.0.2.1/32\|192.0.2.2/32 |
251 +------------------+----------+----------+----------+----------------------------------+
252 | **Key/Value | 16387 | 15 | kv: | 192.0.2.1⇒192.0.2.2 |
253 | Address Pair** | | | | |
254 +------------------+----------+----------+----------+----------------------------------+
255 | **Service Path** | 16387 | N/A | sp: | 42(3) |
256 +------------------+----------+----------+----------+----------------------------------+
258 Table: LISP Address Formats
260 Please note that the forward slash character ``/`` typically separating
261 IPv4 and IPv6 addresses from the mask length is transformed into ``%2f``
267 In this section we will discuss two types of Karaf commands: built-in,
268 and LISP specific. Some built-in commands are quite useful, and are
269 needed for the tutorial, so they will be discussed here. A reference of
270 all LISP specific commands, added by the LISP Flow Mapping project is
271 also included. They are useful mostly for debugging.
273 Useful built-in commands
274 ~~~~~~~~~~~~~~~~~~~~~~~~
277 Lists all available command, with a short description of each.
279 ``help <command_name>``
280 Show detailed help about a specific command.
282 ``feature:list [-i]``
283 Show all locally available features in the Karaf container. The
284 ``-i`` option lists only features that are currently installed. It
285 is possible to use ``| grep`` to filter the output (for all
286 commands, not just this one).
288 ``feature:install <feature_name>``
289 Install feature ``feature_name``.
291 ``log:set <level> <class>``
292 Set the log level for ``class`` to ``level``. The default log level
293 for all classes is INFO. For debugging, or learning about LISP
294 internals it is useful to run
295 ``log:set TRACE org.opendaylight.lispflowmapping`` right after Karaf
299 Outputs the log file to the console, and returns control to the
303 Continuously shows log output, requires ``Ctrl+C`` to return to the
306 LISP specific commands
307 ~~~~~~~~~~~~~~~~~~~~~~
309 The available lisp commands can always be obtained by
310 ``help mappingservice``. Currently they are:
312 ``mappingservice:addkey``
313 Add the default password ``password`` for the IPv4 EID prefix
314 0.0.0.0/0 (all addresses). This is useful when experimenting with
315 southbound devices, and using the REST interface would be combersome
318 ``mappingservice:mappings``
319 Show the list of all mappings stored in the internal non-persistent
320 data store (the DAO), listing the full data structure. The output is
321 not human friendly, but can be used for debugging.
323 LISP Flow Mapping Karaf Features
324 --------------------------------
326 LISP Flow Mapping has the following Karaf features that can be installed
327 from the Karaf console:
329 ``odl-lispflowmapping-msmr``
330 This includes the core features required to use the LISP Flow
331 Mapping Service such as mapping service and the LISP southbound
334 ``odl-lispflowmapping-ui``
335 This includes the GUI module for the LISP Mapping Service.
337 ``odl-lispflowmapping-neutron``
338 This is the experimental Neutron provider module for LISP mapping
344 This section provides a tutorial demonstrating various features in this
345 service. We have included tutorials using two forwarding platforms:
347 1. Using `Open Overlay Router (OOR) <https://github.com/OpenOverlayRouter/oor#overview>`__
349 2. Using `FD.io <https://wiki.fd.io/view/ONE>`__
351 Both have different approaches to create the overlay but ultimately do the
352 same job. Details of both approaches have been explained below.
354 Creating a LISP overlay with OOR
355 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
357 This section provides instructions to set up a LISP network of three
358 nodes (one "client" node and two "server" nodes) using OOR as data
359 plane LISP nodes and the LISP Flow Mapping project from OpenDaylight as
360 the LISP programmable mapping system for the LISP network.
365 The steps shown below will demonstrate setting up a LISP network between
366 a client and two servers, then performing a failover between the two
372 - **OpenDaylight Boron**
376 - **The Postman Chrome App**: the most convenient way to follow along
377 this tutorial is to use the `Postman
378 App <https://www.getpostman.com/apps>`__
379 to edit and send the requests. The project git repository hosts a
380 collection of the requests that are used in this tutorial in the
381 ``resources/tutorial/OOR/Beryllium_Tutorial.json.postman_collection``
382 file. You can import this file to Postman by clicking *Import* at the
383 top, choosing *Download from link* and then entering the following
385 `<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/boron>`__.
386 Alternatively, you can save the file on your machine, or if you have
387 the repository checked out, you can import from there. You will need
388 to create a new Postman Environment and define some variables within:
389 ``controllerHost`` set to the hostname or IP address of the machine
390 running the OpenDaylight instance, and ``restconfPort`` to 8181, if you didn’t
391 modify the default controller settings.
393 - **OOR version 1.0 or later** The README.md lists the dependencies needed
394 to build it from source.
396 - **A virtualization platform**
401 The three LISP data plane nodes and the LISP mapping system are assumed
402 to be running in Linux virtual machines, which have the ``eth0``
403 interface in NAT mode to allow outside internet access and ``eth1``
404 connected to a host-only network, with the following IP addresses
405 (please adjust configuration files, JSON examples, etc. accordingly if
406 you’re using another addressing scheme):
408 +--------------------------+--------------------------+--------------------------+
409 | Node | Node Type | IP Address |
410 +==========================+==========================+==========================+
411 | **controller** | OpenDaylight | 192.168.16.11 |
412 +--------------------------+--------------------------+--------------------------+
413 | **client** | OOR | 192.168.16.30 |
414 +--------------------------+--------------------------+--------------------------+
415 | **server1** | OOR | 192.168.16.31 |
416 +--------------------------+--------------------------+--------------------------+
417 | **server2** | OOR | 192.168.16.32 |
418 +--------------------------+--------------------------+--------------------------+
419 | **service-node** | OOR | 192.168.16.33 |
420 +--------------------------+--------------------------+--------------------------+
422 Table: Nodes in the tutorial
424 The figure below gives a sketch of network topology that will be used in the tutorial.
426 .. figure:: ./images/tutorial_architecture_diagram.png
427 :alt: Network architecture of the tutorial
429 In LISP terminology **client**, **server1** and **server2** are mobile nodes (MN in OOR),
430 **controller** is a MS/MR and **service-node** is a RTR.
434 While the tutorial uses OOR as the data plane, it could be any
435 LISP-enabled hardware or software router (commercial/open source).
440 The below steps use the command line tool cURL to talk to the LISP Flow
441 Mapping RPC REST API. This is so that you can see the actual request
442 URLs and body content on the page.
444 1. Install and run OpenDaylight Boron release on the controller VM.
445 Please follow the general OpenDaylight Boron Installation Guide
446 for this step. Once the OpenDaylight controller is running install
447 the *odl-lispflowmapping-msmr* feature from the Karaf CLI:
451 feature:install odl-lispflowmapping-msmr
453 It takes quite a while to load and initialize all features and their
454 dependencies. It’s worth running the command ``log:tail`` in the
455 Karaf console to see when the log output is winding down, and
456 continue with the tutorial after that.
458 2. Install OOR on the **client**, **server1**, **server2**, and
459 **service-node** VMs following the installation instructions `from
461 file <https://github.com/OpenOverlayRouter/oor#software-prerequisites>`__.
463 3. Configure the OOR installations from the previous step. Take a look
464 at the ``oor.conf.example`` to get a general idea of the structure
465 of the conf file. First, check if the file ``/etc/oor.conf`` exists.
466 If the file doesn't exist, create the file ``/etc/oor.conf``. Set the
467 EID in ``/etc/oor.conf`` file from the IP address space selected
468 for your virtual/LISP network. In this tutorial the EID of the
469 **client** is set to 1.1.1.1/32, and that of **server1** and
470 **server2** to 2.2.2.2/32.
472 4. Set the RLOC interface to ``eth1`` in each ``oor.conf`` file. LISP
473 will determine the RLOC (IP address of the corresponding VM) based
476 5. Set the Map-Resolver address to the IP address of the
477 **controller**, and on the **client** the Map-Server too. On
478 **server1** and **server2** set the Map-Server to something else, so
479 that it doesn’t interfere with the mappings on the controller, since
480 we’re going to program them manually.
482 6. Modify the "key" parameter in each ``oor.conf`` file to a
483 key/password of your choice (*password* in this tutorial).
487 The ``resources/tutorial/OOR`` directory in the *stable/boron*
488 branch of the project git repository has the files used in the
490 in <https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=tree;f=resources/tutorial/OOR;hb=refs/heads/stable/boron>`__,
491 so you can just copy the files to ``/etc/oor.conf`` on the
492 respective VMs. You will also find the JSON files referenced
493 below in the same directory.
495 7. Define a key and EID prefix association in OpenDaylight using the
496 RPC REST API for the **client** EID (1.1.1.1/32) to allow
497 registration from the southbound. Since the mappings for the server
498 EID will be configured from the REST API, no such association is
499 necessary. Run the below command on the **controller** (or any
500 machine that can reach **controller**, by replacing *localhost* with
501 the IP address of **controller**).
505 curl -u "admin":"admin" -H "Content-type: application/json" -X PUT \
506 http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/authentication-key/ipv4:1.1.1.1%2f32/ \
509 where the content of the *add-key.json* file is the following:
514 "authentication-key": {
515 "eid-uri": "ipv4:1.1.1.1/32",
517 "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
518 "ipv4-prefix": "1.1.1.1/32"
521 "key-string": "password",
527 8. Verify that the key is added properly by requesting the following
532 curl -u "admin":"admin" -H "Content-type: application/json" -X GET \
533 http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/authentication-key/ipv4:1.1.1.1%2f32/
535 The output the above invocation should look like this:
540 "authentication-key":[
542 "eid-uri":"ipv4:1.1.1.1/32",
544 "ipv4-prefix":"1.1.1.1/32",
545 "address-type":"ietf-lisp-address-types:ipv4-prefix-afi"
548 "key-string":"password"
555 9. Run the ``oor`` OOR daemon on all VMs:
561 For more information on accessing OOR logs, take a look at
562 `OOR README <https://github.com/OpenOverlayRouter/oor#readme>`__
563 10. The **client** OOR node should now register its EID-to-RLOC
564 mapping in OpenDaylight. To verify you can lookup the corresponding
565 EIDs via the REST API
569 curl -u "admin":"admin" -H "Content-type: application/json" -X GET \
570 http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/mapping/ipv4:1.1.1.1%2f32/southbound/
572 An alternative way for retrieving mappings from OpenDaylight using the
573 southbound interface is using the
574 ```lig`` <https://github.com/davidmeyer/lig>`__ open source tool.
576 11. Register the EID-to-RLOC mapping of the server EID 2.2.2.2/32 to the
577 controller, pointing to **server1** and **server2** with a higher
578 priority for **server1**
582 curl -u "admin":"admin" -H "Content-type: application/json" -X PUT \
583 http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/mapping/ipv4:2.2.2.2%2f32/northbound/ \
586 where the *mapping.json* file looks like this:
592 "eid-uri": "ipv4:2.2.2.2/32",
593 "origin": "northbound",
596 "action": "NoAction",
597 "authoritative": true,
599 "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
600 "ipv4-prefix": "2.2.2.2/32"
604 "locator-id": "server1",
607 "multicastPriority": 255,
608 "multicastWeight": 0,
609 "localLocator": true,
613 "address-type": "ietf-lisp-address-types:ipv4-afi",
614 "ipv4": "192.168.16.31"
618 "locator-id": "server2",
621 "multicastPriority": 255,
622 "multicastWeight": 0,
623 "localLocator": true,
627 "address-type": "ietf-lisp-address-types:ipv4-afi",
628 "ipv4": "192.168.16.32"
636 Here the priority of the second RLOC (192.168.16.32 - **server2**)
637 is 2, a higher numeric value than the priority of 192.168.16.31,
638 which is 1. This policy is saying that **server1** is preferred to
639 **server2** for reaching EID 2.2.2.2/32. Note that lower priority
640 value has higher preference in LISP.
642 12. Verify the correct registration of the 2.2.2.2/32 EID:
646 curl -u "admin":"admin" -H "Content-type: application/json" -X GET \
647 http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/mapping/ipv4:2.2.2.2%2f32/northbound/
649 13. Now the LISP network is up. To verify, log into the **client** VM
650 and ping the server EID:
656 14. Let’s test fail-over now. Suppose you had a service on **server1**
657 which became unavailable, but **server1** itself is still reachable.
658 LISP will not automatically fail over, even if the mapping for
659 2.2.2.2/32 has two locators, since both locators are still reachable
660 and uses the one with the higher priority (lowest priority value).
661 To force a failover, we need to set the priority of **server2** to a
662 lower value. Using the file mapping.json above, swap the priority
663 values between the two locators (lines 14 and 28 in *mapping.json*)
664 and repeat the request from step 11. You can also repeat step 12 to
665 see if the mapping is correctly registered. If you leave the ping
666 on, and monitor the traffic using wireshark, you can see that the
667 ping traffic to 2.2.2.2 will be diverted from the **server1** RLOC
668 to the **server2** RLOC.
670 With the default OpenDaylight configuration the failover should be
671 near instantaneous (we observed 3 lost pings in the worst case),
672 because of the LISP `Solicit-Map-Request (SMR)
673 mechanism <http://tools.ietf.org/html/rfc6830#section-6.6.2>`__ that
674 can ask a LISP data plane element to update its mapping for a
675 certain EID (enabled by default). It is controlled by the
676 ``lisp.smr`` variable in ``etc/custom.porperties``. When enabled,
677 any mapping change from the RPC interface will trigger an SMR packet
678 to all data plane elements that have requested the mapping in the
679 last 24 hours (this value was chosen because it’s the default TTL of
680 Cisco IOS xTR mapping registrations). If disabled, ITRs keep their
681 mappings until the TTL specified in the Map-Reply expires.
683 15. To add a service chain into the path from the client to the server,
684 we can use an Explicit Locator Path, specifying the **service-node**
685 as the first hop and **server1** (or **server2**) as the second hop.
686 The following will achieve that:
690 curl -u "admin":"admin" -H "Content-type: application/json" -X PUT \
691 http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/mapping/ipv4:2.2.2.2%2f32/northbound/ \
694 where the *elp.json* file is as follows:
700 "eid-uri": "ipv4:2.2.2.2/32",
701 "origin": "northbound",
704 "action": "NoAction",
705 "authoritative": true,
707 "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
708 "ipv4-prefix": "2.2.2.2/32"
715 "multicastPriority": 255,
716 "multicastWeight": 0,
717 "localLocator": true,
721 "address-type": "ietf-lisp-address-types:explicit-locator-path-lcaf",
722 "explicit-locator-path": {
725 "hop-id": "service-node",
726 "address": "192.168.16.33",
731 "address": "192.168.16.31",
743 After the mapping for 2.2.2.2/32 is updated with the above, the ICMP
744 traffic from **client** to **server1** will flow through the
745 **service-node**. You can confirm this in the OOR logs, or by
746 sniffing the traffic on either the **service-node** or **server1**.
747 Note that service chains are unidirectional, so unless another ELP
748 mapping is added for the return traffic, packets will go from
749 **server1** to **client** directly.
751 16. Suppose the **service-node** is actually a firewall, and traffic is
752 diverted there to support access control lists (ACLs). In this
753 tutorial that can be emulated by using ``iptables`` firewall rules
754 in the **service-node** VM. To deny traffic on the service chain
755 defined above, the following rule can be added:
759 iptables -A OUTPUT --dst 192.168.16.31 -j DROP
761 The ping from the **client** should now have stopped.
763 In this case the ACL is done on the destination RLOC. There is an
764 effort underway in the OOR community to allow filtering on EIDs,
765 which is the more logical place to apply ACLs.
767 17. To delete the rule and restore connectivity on the service chain,
768 delete the ACL by issuing the following command:
772 iptables -D OUTPUT --dst 192.168.16.31 -j DROP
774 which should restore connectivity.
777 Creating a simple LISP overlay with FD.io
778 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
780 In this section, we use the Overlay Network Engine (ONE) project in FD.io
781 to facilitate fully scripted setup and testing of a LISP/VXLAN-GPE network.
782 Overlay Network Engine (ONE) is a `FD.io <https://fd.io/>`__ project that enables programmable
783 dynamic software defined overlays. Details about this project can be
784 found in `ONE wiki <https://wiki.fd.io/view/ONE>`__.
786 The steps shown below will demonstrate setting up a LISP network between
787 a client and a server using VPP. We demonstrate how to use VPP lite to
788 build a IP4 LISP overlay on an Ubuntu host using namespaces and af_packet
789 interfaces. All configuration files used in the tutorials can be found
790 `here <https://gerrit.fd.io/r/gitweb?p=one.git;a=tree;f=tutorial;hb=HEAD>`__.
795 - **OpenDaylight Boron**
797 - **The Postman Chrome App**: Please follow the instructions_ and import
798 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>`__.
800 - **Vagrant** (optional): Download it from `Vagrant website <https://www.vagrantup.com/downloads.html>`__
801 and follow the setup instructions.
806 Unlike the case with OOR, we use network namespace functionality of Linux
807 to create the overlay in this case. The following table contains ip addresses
808 of nodes in the overlay topology used in the tutorial. Our objective will be to
809 create this topology and be able to ping from client to server through an
810 intermediary hop, **service node**, which is a ``rtr node`` providing the
811 service of re-encapsulation. So, all the packets from client to server
812 will be through this **service node**.
814 +--------------------------+--------------------------+--------------------------+
815 | Node | Node Type | IP Address |
816 +==========================+==========================+==========================+
817 | **controller** | OpenDaylight | 6.0.3.100 |
818 +--------------------------+--------------------------+--------------------------+
819 | **client** | VPP | 6.0.2.2 |
820 +--------------------------+--------------------------+--------------------------+
821 | **server** | VPP | 6.0.4.4 |
822 +--------------------------+--------------------------+--------------------------+
823 | **service node** | VPP | 6.0.3.3 |
824 +--------------------------+--------------------------+--------------------------+
826 Table: Nodes in the tutorial
828 The figure below gives a sketch of network topology that will be used in the tutorial.
830 .. figure:: ./images/one_ODL_architecture.png
831 :alt: Network architecture of the tutorial for FD.io
836 Follow the instructions below sequentially.
838 1. Pull the VPP code anonymously using:
841 git clone https://gerrit.fd.io/r/vpp
843 2. Then, use the vagrant file from repository to build virtual machine
844 with proper environment.
847 cd vpp/build-root/vagrant/
851 3. In case there is any error from ``vagrant up``, try ``vargant ssh``. if
852 it works, no worries. If it still doesn't work, you can try any Ubuntu virtual
853 machine. Or sometimes there is an issue with the Vagrant properly copying
854 the VPP repo code from the host VM after the first installation. In that
855 case ``/vpp`` doesn't exist. In both cases, follow the instructions
858 1. Clone the code in ``/`` directory. So, the codes will be in ``/vpp``.
860 2. Run the following commands:
866 make V=0 PLATFORM=vpp TAG=vpp install-deb
867 sudo dpkg -i /vpp/build-root/*.deb
869 Alternative and more detailed build instructions can be found in
870 `VPP's wiki <https://wiki.fd.io/view/VPP/Build,_install,_and_test_images>`__
871 4. By now, you should have a Ubuntu VM with VPP repository in ``/vpp``
872 with ``sudo`` access. Now, we need VPP Lite build. The following commands
877 export PLATFORM=vpp_lite
880 Successful build create the binary in ``/vpp/build-root/install-vpp_lite_debug-native/vpp/bin``
882 5. Install bridge-utils and ethtool if needed by using following commands:
885 sudo apt-get install bridge-utils ethtool
887 6. Now, install and run OpenDaylight Boron release on the VM. Please
888 follow the general OpenDaylight Boron Installation Guide for this
889 step from :ref:`install_odl`. Before running OpenDaylight, we need
890 to change the configuration for RTR to work. Update ``etc/custom.properties``
891 with the ``lisp.elpPolicy`` to be replace.
894 lisp.elpPolicy = replace
896 Then, run OpenDaylight. For details regarding configuring LISP
897 Flow Mapping, please take a look at :ref:`lfm_config`.
898 Once the OpenDaylight controller is running install the *odl-lispflowmapping-msmr*
899 feature from the Karaf CLI:
903 feature:install odl-lispflowmapping-msmr
905 It may take quite a while to load and initialize all features and their
906 dependencies. It’s worth running the command ``log:tail`` in the
907 Karaf console to see when the log output is winding down, and
908 continue with the tutorial after that.
910 7. For setting up VPP, get the files from ``resources/tutorial/FD_io``
911 folder of the lispflowmapping repo. The files can also be found `here
912 <https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=tree;f=resources/tutorial/FD_io;hb=refs/heads/stable/boron>`__.
913 Copy the ``vpp1.config``, ``vpp2.config`` and ``rtr.config`` files in
916 8. In this example, VPP doesn't make any southbound map registers to OpenDaylight.
917 So, we add the mappings directly from northbound. For that, we need
918 to add the mappings to OpenDaylight via RESTCONF API.
920 Register EID-to-RLOC mapping of the Client EID 6.0.2.0/24.
923 curl -u "admin":"admin" -H "Content-type: application/json" -X PUT \
924 http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/mapping/ipv4:6.0.2.0%2f24/northbound/ \
927 Content of epl1.json:
933 "eid-uri": "ipv4:6.0.2.0/24",
934 "origin": "northbound",
937 "action": "NoAction",
938 "authoritative": true,
940 "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
941 "ipv4-prefix": "6.0.2.0/24"
948 "multicastPriority": 255,
949 "multicastWeight": 0,
950 "localLocator": true,
954 "address-type": "ietf-lisp-address-types:explicit-locator-path-lcaf",
955 "explicit-locator-path": {
959 "address": "6.0.3.3",
960 "lrs-bits": "lookup rloc-probe strict"
964 "address": "6.0.3.1",
965 "lrs-bits": "lookup strict"
977 Similarly add EID-to-RLOC mapping of the Server EID 6.0.4.0/24.
980 curl -u "admin":"admin" -H "Content-type: application/json" -X PUT \
981 http://localhost:8181/restconf/config/odl-mappingservice:mapping-database/virtual-network-identifier/0/mapping/ipv4:6.0.4.0%2f24/northbound/ \
984 Content of elp2.json:
990 "eid-uri": "ipv4:6.0.4.0/24",
991 "origin": "northbound",
994 "action": "NoAction",
995 "authoritative": true,
997 "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
998 "ipv4-prefix": "6.0.4.0/24"
1002 "locator-id": "ELP",
1005 "multicastPriority": 255,
1006 "multicastWeight": 0,
1007 "localLocator": true,
1008 "rlocProbed": false,
1011 "address-type": "ietf-lisp-address-types:explicit-locator-path-lcaf",
1012 "explicit-locator-path": {
1016 "address": "6.0.3.3",
1017 "lrs-bits": "lookup rloc-probe strict"
1021 "address": "6.0.3.2",
1022 "lrs-bits": "lookup strict"
1033 The JSON files regarding these can be found in `here
1034 <https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=tree;f=resources/tutorial/FD_io;hb=refs/heads/stable/boron>`__.
1035 Even though there is no southbound registration for mapping to OpenDaylight, using
1036 northbound policy we can specify mappings, when Client requests for
1037 the Server eid, Client gets a reply from OpenDaylight.
1039 9. Assuming all files have been created and OpenDaylight has been configured as
1040 explained above, execute the host script you've created or the ``topology_setup.sh``
1041 script from `here <https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=tree;f=resources/tutorial/FD_io;hb=refs/heads/stable/boron>`__.
1043 10. If all goes well, you can now test connectivity between the namespaces with:
1046 sudo ip netns exec vpp-ns1 ping 6.0.4.4
1048 11. Traffic and control plane message exchanges can be checked with a wireshark
1049 listening on the odl interface.
1050 12. .. important:: Delete the topology by running the ``topology_setup.sh`` with ``clean`` argument.
1053 sudo ./topology_setup.sh clean
1055 LISP Flow Mapping Support
1056 -------------------------
1058 For support the lispflowmapping project can be reached by emailing the
1059 developer mailing list: lispflowmapping-dev@lists.opendaylight.org or on
1060 the #opendaylight-lispflowmapping IRC channel on irc.freenode.net.
1062 Additional information is also available on the `Lisp Flow Mapping
1063 wiki <https://wiki.opendaylight.org/view/OpenDaylight_Lisp_Flow_Mapping:Main>`__
1065 Clustering in LISP Flow Mapping
1066 -------------------------------
1068 Documentation regarding setting up a 3-node OpenDaylight cluster is
1069 described at following `odl wiki
1070 page <https://wiki.opendaylight.org/view/Running_and_testing_an_OpenDaylight_Cluster#Three-node_cluster>`__.
1072 To turn on clustering in LISP Flow Mapping it is necessary:
1074 - run script **deploy.py** script. This script is in
1075 `integration-test <https://git.opendaylight.org/gerrit/integration/test>`__
1076 project placed at *tools/clustering/cluster-deployer/deploy.py*. A
1077 whole deploy.py command can looks like:
1081 <div class="informalexample">
1083 | {path\_to\_integration\_test\_project}/tools/clustering/cluster-deployer/**deploy.py**
1084 | --**distribution** {path\_to\_distribution\_in\_zip\_format}
1085 | --**rootdir** {dir\_at\_remote\_host\_where\_copy\_odl\_distribution}
1086 | --**hosts** {ip1},{ip2},{ip3}
1088 | --**template** lispflowmapping
1090 | --**user** {user\_name\_of\_remote\_hosts}
1091 | --**password** {password\_to\_remote\_hosts}
1097 | Running this script will cause that specified **distribution** to be
1098 deployed to remote **hosts** specified through their IP adresses with
1099 using credentials (**user** and **password**). The distribution will
1100 be copied to specified **rootdir**. As part of the deployment, a
1101 **template** which contains a set of controller files which are
1102 different from standard ones. In this case it is specified in
1103 | *{path\_to\_integration\_test\_project}/tools/clustering/cluster-deployer/lispflowmapping*
1105 | Lispflowmapping templates are part of integration-test project. There
1106 are 5 template files:
1108 - akka.conf.template
1110 - jolokia.xml.template
1112 - module-shards.conf.template
1114 - modules.conf.template
1116 - org.apache.karaf.features.cfg.template
1118 After copying the distribution, it is unzipped and started on all of
1119 specified **hosts** in cluster aware manner.
1124 It is necessary to have:
1126 - **unzip** program installed on all of the host
1128 - set all remote hosts /etc/sudoers files to not **requiretty** (should
1129 only matter on debian hosts)