1 == LISP Flow Mapping User Guide
5 ==== Locator/ID Separation Protocol
7 http://tools.ietf.org/html/rfc6830[Locator/ID Separation Protocol (LISP)] is a
8 technology that provides a flexible map-and-encap framework that can be used
9 for overlay network applications such as data center network virtualization and
10 Network Function Virtualization (NFV).
12 LISP provides the following name spaces:
14 * http://tools.ietf.org/html/rfc6830#page-6[Endpoint Identifiers (EIDs)]
15 * http://tools.ietf.org/html/rfc6830#section-3[Routing Locators (RLOCs)]
17 In a virtualization environment EIDs can be viewed as virtual address space and
18 RLOCs can be viewed as physical network address space.
20 The LISP framework decouples network control plane from the forwarding plane by
23 * A data plane that specifies how the virtualized network addresses are
24 encapsulated in addresses from the underlying physical network.
25 * A control plane that stores the mapping of the virtual-to-physical address
26 spaces, the associated forwarding policies and serves this information to
27 the data plane on demand.
29 Network programmability is achieved by programming forwarding policies such as
30 transparent mobility, service chaining, and traffic engineering in the mapping
31 system; where the data plane elements can fetch these policies on demand as new
32 flows arrive. This chapter describes the LISP Flow Mapping project in
33 OpenDaylight and how it can be used to enable advanced SDN and NFV use cases.
35 LISP data plane Tunnel Routers are available at
36 http://LISPmob.org/[LISPmob.org] in the open source community on the following
43 For more details and support for LISP data plane software please visit
44 http://LISPmob.org/[the LISPmob web site].
46 ==== LISP Flow Mapping Service
48 The LISP Flow Mapping service provides LISP Mapping System services. This
49 includes LISP Map-Server and LISP Map-Resolver services to store and serve
50 mapping data to data plane nodes as well as to OpenDaylight applications.
51 Mapping data can include mapping of virtual addresses to physical network
52 address where the virtual nodes are reachable or hosted at. Mapping data can
53 also include a variety of routing policies including traffic engineering and
54 load balancing. To leverage this service, OpenDaylight applications and
55 services can use the northbound REST API to define the mappings and policies in
56 the LISP Mapping Service. Data plane devices capable of LISP control protocol
57 can leverage this service through a southbound LISP plugin. LISP-enabled
58 devices must be configured to use this OpenDaylight service as their Map Server
61 The southbound LISP plugin supports the LISP control protocol (Map-Register,
62 Map-Request, Map-Reply messages), and can also be used to register mappings in
63 the OpenDaylight mapping service.
65 === LISP Flow Mapping Architecture
67 The following figure shows the various LISP Flow Mapping modules.
69 .LISP Mapping Service Internal Architecture
71 image::lispflow-technical-arch-overview-helium.jpg["LISP Mapping Service Internal Architecture", width=460]
73 A brief description of each module is as follows:
75 * *DAO (Data Access Object):* This layer separates the LISP logic from the
76 database, so that we can separate the map server and map resolver from the
77 specific implementation of the mapping database. Currently we have an
78 implementation of this layer with an in-memory HashMap, but it can be switched
79 to any other key/value store and you only need to implement the ILispDAO
82 * *Map Server:* This module processes the adding or registration of
83 authentication tokens (keys) and mappings. For a detailed specification of
84 LISP Map Server, see http://tools.ietf.org/search/rfc6830[LISP].
85 * *Map Resolver:* This module receives and processes the mapping lookup queries
86 and provides the mappings to requester. For a detailed specification of LISP
87 Map Server, see http://tools.ietf.org/search/rfc6830[LISP].
88 * *Northbound API:* This is part of the OpenDaylight northbound API. This
89 module enables defining key-EID associations as well as adding mapping
90 information through the Map Server. Key-EID associations can also be queried
91 via this API. The northbound API also provides capability of querying the
92 mapping information for an EID prefix.
93 * *Neutron:* This module implements the OpenDaylight Neutron Service APIs. It
94 provides integration between the LISP service and the OpenDaylight Neutron
95 service, and thus OpenStack.
96 * *NETCONF:* This module enables the LISP service to communicate to
97 NETCONF-enabled devices through OpenDaylight's NETCONF plugin.
98 * *Java API:* The API module exposes the Map Server and Map Resolver
99 capabilities via a Java API.
100 * *LISP Southbound Plugin:* This plugin enables data plane devices that support
101 LISP control plane protocol (see see http://tools.ietf.org/search/rfc6830[LISP])
102 to register and query mappings to the
103 LISP Flow Mapping via the LISP control plane protocol.
106 === Configuring LISP Flow Mapping
108 In order to use the LISP mapping service for registering EID to RLOC mappings
109 from northbound or southbound, keys have to be defined for the EID prefixes first. Once a key
110 is defined for an EID prefix, it can be used to add mappings for that EID
111 prefix multiple times. If the service is going to be used to process Map-Register
112 messages from the southbound LISP plugin, the same key must be used by
113 the data plane device to create the authentication data in the Map-Register
114 messages for the associated EID prefix.
116 The +etc/custom.properties+ file in the Karaf distribution allows configuration
117 of several OpenDaylight parameters. The LISP service has two properties that
118 can be adjusted: +lisp.mappingOverwrite+ and +lisp.smr+.
120 *lisp.mappingOverwrite* (default: 'true')::
121 Configures handling of mapping updates. When set to 'true' (default) a
122 mapping update (either through the southbound plugin via a Map-Register
123 message or through a northbound API PUT REST call) the existing RLOC set
124 associated to an EID prefix is overwritten. When set to 'false', the RLOCs
125 of the update are merged to the existing set.
127 *lisp.smr* (default: 'false')::
129 http://tools.ietf.org/html/rfc6830#section-6.6.2[Solicit-Map-Request (SMR)]
130 functionality. SMR is a method to notify changes in an EID-to-RLOC mapping
131 to "subscribers". The LISP service considers all Map-Request's source RLOC
132 as a subscriber to the requested EID prefix, and will send an SMR control
133 message to that RLOC if the mapping changes.
135 *lisp.elpPolicy* (default: 'default')::
136 Configures how to build a Map-Reply southbound message from a mapping
137 containing an Explicit Locator Path (ELP) RLOC. It is used for
138 compatibility with dataplane devices that don't understand the ELP LCAF
139 format. The 'default' setting doesn't alter the mapping, returning all
140 RLOCs unmodified. The 'both' setting adds a new RLOC to the mapping, with
141 a lower priority than the ELP, that is the next hop in the service chain.
142 To determine the next hop, it searches the source RLOC of the Map-Request
143 in the ELP, and chooses the next hop, if it exists, otherwise it chooses
144 the first hop. The 'replace' setting adds a new RLOC using the same
145 algorithm as the 'both' setting, but using the origin priority of the ELP
146 RLOC, which is removed from the mapping.
148 === Textual Conventions for LISP Address Formats
150 In addition to the more common IPv4, IPv6 and MAC address data types, the LISP
151 control plane supports arbitrary
152 http://www.iana.org/assignments/address-family-numbers[Address Family
153 Identifiers] assigned by IANA, and in addition to those the
154 https://tools.ietf.org/html/draft-ietf-lisp-lcaf[LISP Canoncal Address Format
157 The LISP Flow Mapping project in OpenDaylight implements support for many of
158 these different address formats, the full list being summarized in the
159 following table. While some of the address formats have well defined and
160 widely used textual representation, many don't. It became necessary to define
161 a convention to use for text rendering of all implemented address types in
162 logs, URLs, input fields, etc. The below table lists the supported formats,
163 along with their AFI number and LCAF type, including the prefix used for
164 disambiguation of potential overlap, and examples output.
166 .LISP Address Formats
167 [align="right",options="header",cols="<s,>,>,<,<l"]
169 | Name | AFI | LCAF | Prefix | Text Rendering
170 | No Address | 0 | - | no: | No Address Present
171 | IPv4 Prefix | 1 | - | ipv4: | 192.0.2.0/24
172 | IPv6 Prefix | 2 | - | ipv6: | 2001:db8::/32
173 | MAC Address | 16389 | - | mac: | 00:00:5E:00:53:00
174 | Distinguished Name | 17 | - | dn: | stringAsIs
175 | AS Number | 18 | - | as: | AS64500
176 | AFI List | 16387 | 1 | list: | {192.0.2.1,192.0.2.2,2001:db8::1}
177 | Instance ID | 16387 | 2 | - | [223] 192.0.2.0/24
178 | Application Data | 16387 | 4 | appdata: | 192.0.2.1!128!17!80-81!6667-7000
179 | Explicit Locator Path | 16387 | 10 | elp: | {192.0.2.1->192.0.2.2\|lps->192.0.2.3}
180 | Source/Destination Key | 16387 | 12 | srcdst: | 192.0.2.1/32\|192.0.2.2/32
181 | Key/Value Address Pair | 16387 | 15 | kv: | 192.0.2.1=>192.0.2.2
184 Please note that the forward slash character `/` typically separating IPv4 and
185 IPv6 addresses from the mask length is transformed into `%2f` when used in a
190 In this section we will discuss two types of Karaf commands: built-in, and
191 LISP specific. Some built-in commands are quite useful, and are needed for the
192 tutorial, so they will be discussed here. A reference of all LISP specific
193 commands, added by the LISP Flow Mapping project is also included. They are
194 useful mostly for debugging.
196 ==== Useful built-in commands
199 Lists all available command, with a short description of each.
201 +help <command_name>+::
202 Show detailed help about a specific command.
204 +feature:list [-i]+::
205 Show all locally available features in the Karaf container. The `-i`
206 option lists only features that are currently installed. It is possible to
207 use `| grep` to filter the output (for all commands, not just this one).
209 +feature:install <feature_name>+::
210 Install feature `feature_name`.
212 +log:set <level> <class>+::
213 Set the log level for `class` to `level`. The default log level for all
214 classes is INFO. For debugging, or learning about LISP internals it is
215 useful to run `log:set TRACE org.opendaylight.lispflowmapping` right after
219 Outputs the log file to the console, and returns control to the user.
222 Continuously shows log output, requires `Ctrl+C` to return to the console.
224 ==== LISP specific commands
226 The available lisp commands can always be obtained by `help mappingservice`.
229 +mappingservice:addkey+::
230 Add the default password `password` for the IPv4 EID prefix 0.0.0.0/0 (all
231 addresses). This is useful when experimenting with southbound devices,
232 and using the REST interface would be combersome for whatever reason.
234 +mappingservice:mappings+::
235 Show the list of all mappings stored in the internal non-persistent data
236 store (the DAO), listing the full data structure. The output is not human
237 friendly, but can be used for debugging.
241 This section provides a tutorial demonstrating various features in this service.
243 ==== Creating a LISP overlay
245 This section provides instructions to set up a LISP network of three nodes (one
246 "client" node and two "server" nodes) using LISPmob as data plane LISP nodes
247 and the LISP Flow Mapping project from OpenDaylight as the LISP programmable
248 mapping system for the LISP network.
252 The steps shown below will demonstrate setting up a LISP network between a
253 client and two servers, then performing a failover between the two "server"
258 * *OpenDaylight Beryllium*
259 * *The Postman Chrome App*: the most convenient way to follow along this
260 tutorial is to use the
261 https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en[Postman
262 Chrome App] to edit and send the requests. The project git repository hosts
263 a collection of the requests that are used in this tutorial in the
264 +resources/tutorial/Beryllium_Tutorial.json.postman_collection+ file. You can
265 import this file to Postman by clicking 'Import' at the top, choosing
266 'Download from link' and then entering the following URL:
267 +https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=blob_plain;f=resources/tutorial/Beryllium_Tutorial.json.postman_collection;hb=refs/heads/master+.
268 Alternatively, you can save the file on your machine, or if you have the
269 repository checked out, you can import from there. You will need to create a
270 new Postman Environment and define some variables within: +controllerHost+
271 set to the hostname or IP address of the machine running the ODL instance,
272 and +restconfPort+ to 8181, if you didn't modify the default controller
274 * *LISPmob version 0.5.x* At the time of this writing this version has not
275 been reelased yet, but it is available in the 'experimental' branch in the
276 project's https://github.com/LISPmob/lispmob/tree/experimental[Git
277 repository]. The README.md lists the dependencies needed to build it from
279 * *A virtualization platform*
281 ===== Target Environment
283 The three LISP data plane nodes and the LISP mapping system are assumed to be
284 running in Linux virtual machines, which have the +eth0+ interface in NAT mode
285 to allow outside internet access and +eth1+ connected to a host-only network,
286 with the following IP addresses (please adjust configuration files, JSON
287 examples, etc. accordingly if you're using another addressing scheme):
289 .Nodes in the tutorial
290 [align="right",options="header"]
292 | Node | Node Type | IP Address
293 | *controller* | OpenDaylight | 192.168.16.11
294 | *client* | LISPmob | 192.168.16.30
295 | *server1* | LISPmob | 192.168.16.31
296 | *server2* | LISPmob | 192.168.16.32
297 | *service-node* | LISPmob | 192.168.16.33
300 NOTE: While the tutorial uses LISPmob as the data plane, it could be any
301 LISP-enabled hardware or software router (commercial/open source).
305 The below steps use the command line tool cURL to talk to the LISP Flow
306 Mapping RPC REST API. This is so that you can see the actual request URLs and
307 body content on the page.
309 . Install and run OpenDaylight Beryllium release on the controller VM. Please
310 follow the general OpenDaylight Beryllium Installation Guide for this step.
311 Once the OpenDaylight controller is running install the
312 'odl-openflowplugin-msmr' feature from the Karaf CLI:
314 feature:install odl-lispflowmapping-msmr
316 It takes quite a while to load and initialize all features and their
317 dependencies. It's worth running the command +log:tail+ in the Karaf console
318 to see when the log output is winding down, and continue with the tutorial
321 . Install LISPmob on the *client*, *server1*, *server2*, and *service-node*
322 VMs following the installation instructions
323 https://github.com/LISPmob/lispmob#software-prerequisites[from the LISPmob
326 . Configure the LISPmob installations from the previous step. Starting from
327 the +lispd.conf.example+ file in the distribution, set the EID in each
328 +lispd.conf+ file from the IP address space selected for your virtual/LISP
329 network. In this tutorial the EID of the *client* is set to 1.1.1.1/32, and
330 that of *server1* and *server2* to 2.2.2.2/32.
332 . Set the RLOC interface to +eth1+ in each +lispd.conf+ file. LISP will
333 determine the RLOC (IP address of the corresponding VM) based on this
336 . Set the Map-Resolver address to the IP address of the *controller*, and on
337 the *client* the Map-Server too. On *server1* and *server2* set the
338 Map-Server to something else, so that it doesn't interfere with the
339 mappings on the controller, since we're going to program them manually.
341 . Modify the "key" parameter in each +lispd.conf+ file to a key/password of
342 your choice ('password' in this tutorial).
344 NOTE: The +resources/tutorial+ directory in the 'stable/beryllium' branch of the
345 project git repository has the files used in the tutorial
346 https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=tree;f=resources/tutorial;hb=refs/heads/stable/beryllium[checked
347 in], so you can just copy the files to +/root/lispd.conf+ on the
348 respective VMs. You will also find the JSON files referenced below in
351 . Define a key and EID prefix association in OpenDaylight using the RPC REST
352 API for the *client* EID (1.1.1.1/32) to allow registration from the
353 southbound. Since the mappings for the server EID will be configured from
354 the REST API, no such association is necessary. Run the below command on
355 the *controller* (or any machine that can reach *controller*, by replacing
356 'localhost' with the IP address of *controller*).
358 curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
359 http://localhost:8181/restconf/operations/mappingservice:add-key \
363 where the content of the 'add-key.json' file is the following:
369 "LispAddressContainer": {
372 "Ipv4Address": "1.1.1.1"
377 "authkey": "password"
382 . Verify that the key is added properly by requesting the following URL:
384 curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
385 http://localhost:8181/restconf/operations/mappingservice:get-key \
389 where the content of the 'get1.json' file can be derived from the
390 'add-key.json' file by removing the 'key-type' and 'authkey' fields. The
391 output the above invocation should look like this:
393 {"output":{"authkey":"password"}}
395 . Run the +lispd+ LISPmob daemon on all VMs:
397 lispd -f /root/lispd.conf
399 . The *client* LISPmob node should now register its EID-to-RLOC mapping in
400 OpenDaylight. To verify you can lookup the corresponding EIDs via the REST
403 curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
404 http://localhost:8181/restconf/operations/mappingservice:get-mapping \
408 An alternative way for retrieving mappings from ODL using the southbound
409 interface is using the https://github.com/davidmeyer/lig[+lig+] open source
412 . Register the EID-to-RLOC mapping of the server EID 2.2.2.2/32 to the
413 controller, pointing to *server1* and *server2* with a higher priority for
416 curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
417 http://localhost:8181/restconf/operations/mappingservice:add-mapping \
420 where the 'mapping.json' file looks like this:
428 "authoritative": true,
429 "LispAddressContainer": {
432 "Ipv4Address": "2.2.2.2"
440 "multicastPriority": 255,
441 "multicastWeight": 0,
442 "localLocator": true,
445 "LispAddressContainer": {
448 "Ipv4Address": "192.168.16.31"
456 "multicastPriority": 255,
457 "multicastWeight": 0,
458 "localLocator": true,
461 "LispAddressContainer": {
464 "Ipv4Address": "192.168.16.32"
473 Here the priority of the second RLOC (192.168.16.32 - *server2*) is 2, a higher
474 numeric value than the priority of 192.168.16.31, which is 1. This policy is
475 saying that *server1* is preferred to *server2* for reaching EID 2.2.2.2/32.
476 Note that lower priority value has higher preference in LISP.
478 . Verify the correct registration of the 2.2.2.2/32 EID:
480 curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
481 http://localhost:8181/restconf/operations/mappingservice:get-mapping \
485 where 'get2.json' can be derived from 'get1.json' by changing the content of
486 the 'Ipv4Address' field from '1.1.1.1' to '2.2.2.2'.
488 . Now the LISP network is up. To verify, log into the *client* VM and ping the server EID:
492 . Let's test fail-over now. Suppose you had a service on *server1* which
493 became unavailable, but *server1* itself is still reachable. LISP will not
494 automatically fail over, even if the mapping for 2.2.2.2/32 has two
495 locators, since both locators are still reachable and uses the one with the
496 higher priority (lowest priority value). To force a failover, we need to
497 set the priority of *server2* to a lower value. Using the file mapping.json
498 above, swap the priority values between the two locators (lines 15 and 31
499 in 'mapping.json') and repeat the request from step 11. You can also
500 repeat step 12 to see if the mapping is correctly registered. If you leave
501 the ping on, and monitor the traffic using wireshark, you can see that the
502 ping traffic to 2.2.2.2 will be diverted from the *server1* RLOC to the
505 With the default OpenDaylight configuration the failover should be near
506 instantaneous (we observed 3 lost pings in the worst case), because of the
507 LISP http://tools.ietf.org/html/rfc6830#section-6.6.2[Solicit-Map-Request
508 (SMR) mechanism] that can ask a LISP data plane element to update its mapping
509 for a certain EID (enabled by default). It is controlled by the +lisp.smr+
510 variable in +etc/custom.porperties+. When enabled, any mapping change from the
511 RPC interface will trigger an SMR packet to all data plane elements that have
512 requested the mapping in the last 15 minutes. If disabled, ITRs keep their
513 mappings until the TTL specified in the Map-Reply expires.
515 . To add a service chain into the path from the client to the server, we can
516 use an Explicit Locator Path, specifying the *service-node* as the first
517 hop and *server1* (or *server2*) as the second hop. The following will
520 curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
521 http://localhost:8181/restconf/operations/mappingservice:add-mapping \
524 where the 'elp.json' file is as follows:
532 "authoritative": true,
533 "LispAddressContainer": {
536 "Ipv4Address": "2.2.2.2"
544 "multicastPriority": 255,
545 "multicastWeight": 0,
546 "localLocator": true,
549 "LispAddressContainer": {
550 "LcafTrafficEngineeringAddr": {
555 "name": "service-node",
562 "Ipv4Address": "192.168.16.33"
574 "Ipv4Address": "192.168.16.31"
587 After the mapping for 2.2.2.2/32 is updated with the above, the ICMP traffic
588 from *client* to *server1* will flow through the *service-node*. You can
589 confirm this in the LISPmob logs, or by sniffing the traffic on either the
590 *service-node* or *server1*. Note that service chains are unidirectional, so
591 unless another ELP mapping is added for the return traffic, packets will go
592 from *server1* to *client* directly.
594 . Suppose the *service-node* is actually a firewall, and traffic is diverted
595 there to support access control lists (ACLs). In this tutorial that can be
596 emulated by using +iptables+ firewall rules in the *service-node* VM. To
597 deny traffic on the service chain defined above, the following rule can be
600 iptables -A OUTPUT --dst 192.168.16.31 -j DROP
603 The ping from the *client* should now have stopped.
605 In this case the ACL is done on the destination RLOC. There is an effort underway in the LISPmob
606 community to allow filtering on EIDs, which is the more logical place to apply
609 . To delete the rule and restore connectivity on the service chain, delete
610 the ACL by issuing the following command:
612 iptables -D OUTPUT --dst 192.168.16.31 -j DROP
615 which should restore connectivity.
617 === LISP Flow Mapping Support
619 For support the lispflowmapping project can be reached by emailing the
620 developer mailing list: lispflowmapping-dev@lists.opendaylight.org or on the
621 #opendaylight-lispflowmapping IRC channel on irc.freenode.net.
623 Additional information is also available on the https://wiki.opendaylight.org/view/OpenDaylight_Lisp_Flow_Mapping:Main[Lisp Flow Mapping wiki]