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::ODL_lfm_Be_component.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 * *RPC/RESTCONF:* This is the auto-generated RESTCONF-based northbound API. This
89 module enables defining key-EID associations as well as adding mapping
90 information through the Map Server. Key-EID associations and mappings can also
91 be queried via this API.
92 * *GUI:* This module enables adding and querying the mapping service through a
93 GUI based on ODL DLUX.
94 * *Neutron:* This module implements the OpenDaylight Neutron Service APIs. It
95 provides integration between the LISP service and the OpenDaylight Neutron
96 service, and thus OpenStack.
97 * *Java API:* The API module exposes the Map Server and Map Resolver
98 capabilities via a Java API.
99 * *LISP Proto:* This module includes LISP protocol dependent data types and
100 associated processing.
101 * *In Memory DB:* This module includes the in memory database implementation of
103 * *LISP Southbound Plugin:* This plugin enables data plane devices that support
104 LISP control plane protocol (see http://tools.ietf.org/search/rfc6830[LISP])
105 to register and query mappings to the
106 LISP Flow Mapping via the LISP control plane protocol.
109 === Configuring LISP Flow Mapping
111 In order to use the LISP mapping service for registering EID to RLOC mappings
112 from northbound or southbound, keys have to be defined for the EID prefixes first. Once a key
113 is defined for an EID prefix, it can be used to add mappings for that EID
114 prefix multiple times. If the service is going to be used to process Map-Register
115 messages from the southbound LISP plugin, the same key must be used by
116 the data plane device to create the authentication data in the Map-Register
117 messages for the associated EID prefix.
119 The +etc/custom.properties+ file in the Karaf distribution allows configuration
120 of several OpenDaylight parameters. The LISP service has the following properties
121 that can be adjusted:
123 *lisp.mappingOverwrite* (default: 'true')::
124 Configures handling of mapping updates. When set to 'true' (default) a
125 mapping update (either through the southbound plugin via a Map-Register
126 message or through a northbound API PUT REST call) the existing RLOC set
127 associated to an EID prefix is overwritten. When set to 'false', the RLOCs
128 of the update are merged to the existing set.
130 *lisp.smr* (default: 'false')::
132 http://tools.ietf.org/html/rfc6830#section-6.6.2[Solicit-Map-Request (SMR)]
133 functionality. SMR is a method to notify changes in an EID-to-RLOC mapping
134 to "subscribers". The LISP service considers all Map-Request's source RLOC
135 as a subscriber to the requested EID prefix, and will send an SMR control
136 message to that RLOC if the mapping changes.
138 *lisp.elpPolicy* (default: 'default')::
139 Configures how to build a Map-Reply southbound message from a mapping
140 containing an Explicit Locator Path (ELP) RLOC. It is used for
141 compatibility with dataplane devices that don't understand the ELP LCAF
142 format. The 'default' setting doesn't alter the mapping, returning all
143 RLOCs unmodified. The 'both' setting adds a new RLOC to the mapping, with
144 a lower priority than the ELP, that is the next hop in the service chain.
145 To determine the next hop, it searches the source RLOC of the Map-Request
146 in the ELP, and chooses the next hop, if it exists, otherwise it chooses
147 the first hop. The 'replace' setting adds a new RLOC using the same
148 algorithm as the 'both' setting, but using the origin priority of the ELP
149 RLOC, which is removed from the mapping.
150 *lisp.lookupPolicy* (default: 'northboundFirst')::
151 Configures the mapping lookup algorithm. When set to 'northboundFirst'
152 mappings programmed through the northbound API will take precedence. If
153 no northbound programmed mappings exist, then the mapping service will
154 return mappings registered through the southbound plugin, if any exists.
155 When set to 'northboundAndSouthbound' the mapping programmed by the
156 northbound is returned, updated by the up/down status of these mappings
157 as reported by the southbound (if existing).
158 *lisp.mappingMerge* (default: 'false')::
159 Configures the merge policy on the southbound registrations through the
160 LISP SB Plugin. When set to 'false', only the latest mapping registered
161 through the SB plugin is valid in the southbound mapping database,
162 independent of which device it came from. When set to 'true', mappings
163 for the same EID registered by different devices are merged together and
164 a union of the locators is maintained as the valid mapping for that EID.
166 === Textual Conventions for LISP Address Formats
168 In addition to the more common IPv4, IPv6 and MAC address data types, the LISP
169 control plane supports arbitrary
170 http://www.iana.org/assignments/address-family-numbers[Address Family
171 Identifiers] assigned by IANA, and in addition to those the
172 https://tools.ietf.org/html/draft-ietf-lisp-lcaf[LISP Canoncal Address Format
175 The LISP Flow Mapping project in OpenDaylight implements support for many of
176 these different address formats, the full list being summarized in the
177 following table. While some of the address formats have well defined and
178 widely used textual representation, many don't. It became necessary to define
179 a convention to use for text rendering of all implemented address types in
180 logs, URLs, input fields, etc. The below table lists the supported formats,
181 along with their AFI number and LCAF type, including the prefix used for
182 disambiguation of potential overlap, and examples output.
184 .LISP Address Formats
185 [align="right",options="header",cols="<2s,>,>,<,<4l"]
187 | Name | AFI | LCAF | Prefix | Text Rendering
188 | No Address | 0 | - | no: | No Address Present
189 | IPv4 Prefix | 1 | - | ipv4: | 192.0.2.0/24
190 | IPv6 Prefix | 2 | - | ipv6: | 2001:db8::/32
191 | MAC Address | 16389 | - | mac: | 00:00:5E:00:53:00
192 | Distinguished Name | 17 | - | dn: | stringAsIs
193 | AS Number | 18 | - | as: | AS64500
194 | AFI List | 16387 | 1 | list: | {192.0.2.1,192.0.2.2,2001:db8::1}
195 | Instance ID | 16387 | 2 | - | [223] 192.0.2.0/24
196 | Application Data | 16387 | 4 | appdata: | 192.0.2.1!128!17!80-81!6667-7000
197 | Explicit Locator Path | 16387 | 10 | elp: | {192.0.2.1->192.0.2.2\|lps->192.0.2.3}
198 | Source/Destination Key | 16387 | 12 | srcdst: | 192.0.2.1/32\|192.0.2.2/32
199 | Key/Value Address Pair | 16387 | 15 | kv: | 192.0.2.1=>192.0.2.2
200 | Service Path | 16387 | N/A | sp: | 42(3)
203 Please note that the forward slash character `/` typically separating IPv4 and
204 IPv6 addresses from the mask length is transformed into `%2f` when used in a
209 In this section we will discuss two types of Karaf commands: built-in, and
210 LISP specific. Some built-in commands are quite useful, and are needed for the
211 tutorial, so they will be discussed here. A reference of all LISP specific
212 commands, added by the LISP Flow Mapping project is also included. They are
213 useful mostly for debugging.
215 ==== Useful built-in commands
218 Lists all available command, with a short description of each.
220 +help <command_name>+::
221 Show detailed help about a specific command.
223 +feature:list [-i]+::
224 Show all locally available features in the Karaf container. The `-i`
225 option lists only features that are currently installed. It is possible to
226 use `| grep` to filter the output (for all commands, not just this one).
228 +feature:install <feature_name>+::
229 Install feature `feature_name`.
231 +log:set <level> <class>+::
232 Set the log level for `class` to `level`. The default log level for all
233 classes is INFO. For debugging, or learning about LISP internals it is
234 useful to run `log:set TRACE org.opendaylight.lispflowmapping` right after
238 Outputs the log file to the console, and returns control to the user.
241 Continuously shows log output, requires `Ctrl+C` to return to the console.
243 ==== LISP specific commands
245 The available lisp commands can always be obtained by `help mappingservice`.
248 +mappingservice:addkey+::
249 Add the default password `password` for the IPv4 EID prefix 0.0.0.0/0 (all
250 addresses). This is useful when experimenting with southbound devices,
251 and using the REST interface would be combersome for whatever reason.
253 +mappingservice:mappings+::
254 Show the list of all mappings stored in the internal non-persistent data
255 store (the DAO), listing the full data structure. The output is not human
256 friendly, but can be used for debugging.
259 === LISP Flow Mapping Karaf Features
261 LISP Flow Mapping has the following Karaf features that can be installed from
264 +odl-lispflowmapping-msmr+::
265 This includes the core features required to use the LISP Flow Mapping Service
266 such as mapping service and the LISP southbound plugin.
268 +odl-lispflowmapping-ui+::
269 This includes the GUI module for the LISP Mapping Service.
271 +odl-lispflowmapping-neutron+::
272 This is the experimental Neutron provider module for LISP mapping service.
277 This section provides a tutorial demonstrating various features in this service.
279 ==== Creating a LISP overlay
281 This section provides instructions to set up a LISP network of three nodes (one
282 "client" node and two "server" nodes) using LISPmob as data plane LISP nodes
283 and the LISP Flow Mapping project from OpenDaylight as the LISP programmable
284 mapping system for the LISP network.
288 The steps shown below will demonstrate setting up a LISP network between a
289 client and two servers, then performing a failover between the two "server"
294 * *OpenDaylight Beryllium*
295 * *The Postman Chrome App*: the most convenient way to follow along this
296 tutorial is to use the
297 https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en[Postman
298 Chrome App] to edit and send the requests. The project git repository hosts
299 a collection of the requests that are used in this tutorial in the
300 +resources/tutorial/Beryllium_Tutorial.json.postman_collection+ file. You can
301 import this file to Postman by clicking 'Import' at the top, choosing
302 'Download from link' and then entering the following URL:
303 +https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=blob_plain;f=resources/tutorial/Beryllium_Tutorial.json.postman_collection;hb=refs/heads/stable/beryllium+.
304 Alternatively, you can save the file on your machine, or if you have the
305 repository checked out, you can import from there. You will need to create a
306 new Postman Environment and define some variables within: +controllerHost+
307 set to the hostname or IP address of the machine running the ODL instance,
308 and +restconfPort+ to 8181, if you didn't modify the default controller
310 * *LISPmob version 0.5.x* The README.md lists the dependencies needed to
311 build it from source.
312 * *A virtualization platform*
314 ===== Target Environment
316 The three LISP data plane nodes and the LISP mapping system are assumed to be
317 running in Linux virtual machines, which have the +eth0+ interface in NAT mode
318 to allow outside internet access and +eth1+ connected to a host-only network,
319 with the following IP addresses (please adjust configuration files, JSON
320 examples, etc. accordingly if you're using another addressing scheme):
322 .Nodes in the tutorial
323 [align="right",options="header"]
325 | Node | Node Type | IP Address
326 | *controller* | OpenDaylight | 192.168.16.11
327 | *client* | LISPmob | 192.168.16.30
328 | *server1* | LISPmob | 192.168.16.31
329 | *server2* | LISPmob | 192.168.16.32
330 | *service-node* | LISPmob | 192.168.16.33
333 NOTE: While the tutorial uses LISPmob as the data plane, it could be any
334 LISP-enabled hardware or software router (commercial/open source).
338 The below steps use the command line tool cURL to talk to the LISP Flow
339 Mapping RPC REST API. This is so that you can see the actual request URLs and
340 body content on the page.
342 . Install and run OpenDaylight Beryllium release on the controller VM. Please
343 follow the general OpenDaylight Beryllium Installation Guide for this step.
344 Once the OpenDaylight controller is running install the
345 'odl-lispflowmapping-msmr' feature from the Karaf CLI:
347 feature:install odl-lispflowmapping-msmr
349 It takes quite a while to load and initialize all features and their
350 dependencies. It's worth running the command +log:tail+ in the Karaf console
351 to see when the log output is winding down, and continue with the tutorial
354 . Install LISPmob on the *client*, *server1*, *server2*, and *service-node*
355 VMs following the installation instructions
356 https://github.com/LISPmob/lispmob#software-prerequisites[from the LISPmob
359 . Configure the LISPmob installations from the previous step. Starting from
360 the +lispd.conf.example+ file in the distribution, set the EID in each
361 +lispd.conf+ file from the IP address space selected for your virtual/LISP
362 network. In this tutorial the EID of the *client* is set to 1.1.1.1/32, and
363 that of *server1* and *server2* to 2.2.2.2/32.
365 . Set the RLOC interface to +eth1+ in each +lispd.conf+ file. LISP will
366 determine the RLOC (IP address of the corresponding VM) based on this
369 . Set the Map-Resolver address to the IP address of the *controller*, and on
370 the *client* the Map-Server too. On *server1* and *server2* set the
371 Map-Server to something else, so that it doesn't interfere with the
372 mappings on the controller, since we're going to program them manually.
374 . Modify the "key" parameter in each +lispd.conf+ file to a key/password of
375 your choice ('password' in this tutorial).
377 NOTE: The +resources/tutorial+ directory in the 'stable/beryllium' branch of the
378 project git repository has the files used in the tutorial
379 https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=tree;f=resources/tutorial;hb=refs/heads/stable/beryllium[checked
380 in], so you can just copy the files to +/root/lispd.conf+ on the
381 respective VMs. You will also find the JSON files referenced below in
384 . Define a key and EID prefix association in OpenDaylight using the RPC REST
385 API for the *client* EID (1.1.1.1/32) to allow registration from the
386 southbound. Since the mappings for the server EID will be configured from
387 the REST API, no such association is necessary. Run the below command on
388 the *controller* (or any machine that can reach *controller*, by replacing
389 'localhost' with the IP address of *controller*).
391 curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
392 http://localhost:8181/restconf/operations/odl-mappingservice:add-key \
396 where the content of the 'add-key.json' file is the following:
403 "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
404 "ipv4-prefix": "1.1.1.1/32"
407 "key-string": "password",
414 . Verify that the key is added properly by requesting the following URL:
416 curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
417 http://localhost:8181/restconf/operations/odl-mappingservice:get-key \
421 where the content of the 'get1.json' file can be derived from the
422 'add-key.json' file by removing the 'mapping-authkey' field. The output the
423 above invocation should look like this:
425 {"output":{"mapping-authkey":{"key-type":1,"key-string":"password"}}}
427 . Run the +lispd+ LISPmob daemon on all VMs:
429 lispd -f /root/lispd.conf
431 . The *client* LISPmob node should now register its EID-to-RLOC mapping in
432 OpenDaylight. To verify you can lookup the corresponding EIDs via the REST
435 curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
436 http://localhost:8181/restconf/operations/odl-mappingservice:get-mapping \
440 An alternative way for retrieving mappings from ODL using the southbound
441 interface is using the https://github.com/davidmeyer/lig[+lig+] open source
444 . Register the EID-to-RLOC mapping of the server EID 2.2.2.2/32 to the
445 controller, pointing to *server1* and *server2* with a higher priority for
448 curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
449 http://localhost:8181/restconf/operations/odl-mappingservice:add-mapping \
452 where the 'mapping.json' file looks like this:
460 "action": "NoAction",
461 "authoritative": true,
463 "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
464 "ipv4-prefix": "2.2.2.2/32"
468 "locator-id": "server1",
471 "multicastPriority": 255,
472 "multicastWeight": 0,
473 "localLocator": true,
477 "address-type": "ietf-lisp-address-types:ipv4-afi",
478 "ipv4": "192.168.16.31"
482 "locator-id": "server2",
485 "multicastPriority": 255,
486 "multicastWeight": 0,
487 "localLocator": true,
491 "address-type": "ietf-lisp-address-types:ipv4-afi",
492 "ipv4": "192.168.16.32"
501 Here the priority of the second RLOC (192.168.16.32 - *server2*) is 2, a higher
502 numeric value than the priority of 192.168.16.31, which is 1. This policy is
503 saying that *server1* is preferred to *server2* for reaching EID 2.2.2.2/32.
504 Note that lower priority value has higher preference in LISP.
506 . Verify the correct registration of the 2.2.2.2/32 EID:
508 curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
509 http://localhost:8181/restconf/operations/odl-mappingservice:get-mapping \
513 where 'get2.json' can be derived from 'get1.json' by changing the content of
514 the 'Ipv4Address' field from '1.1.1.1' to '2.2.2.2'.
516 . Now the LISP network is up. To verify, log into the *client* VM and ping the server EID:
520 . Let's test fail-over now. Suppose you had a service on *server1* which
521 became unavailable, but *server1* itself is still reachable. LISP will not
522 automatically fail over, even if the mapping for 2.2.2.2/32 has two
523 locators, since both locators are still reachable and uses the one with the
524 higher priority (lowest priority value). To force a failover, we need to
525 set the priority of *server2* to a lower value. Using the file mapping.json
526 above, swap the priority values between the two locators (lines 14 and 28
527 in 'mapping.json') and repeat the request from step 11. You can also
528 repeat step 12 to see if the mapping is correctly registered. If you leave
529 the ping on, and monitor the traffic using wireshark, you can see that the
530 ping traffic to 2.2.2.2 will be diverted from the *server1* RLOC to the
533 With the default OpenDaylight configuration the failover should be near
534 instantaneous (we observed 3 lost pings in the worst case), because of the
535 LISP http://tools.ietf.org/html/rfc6830#section-6.6.2[Solicit-Map-Request
536 (SMR) mechanism] that can ask a LISP data plane element to update its mapping
537 for a certain EID (enabled by default). It is controlled by the +lisp.smr+
538 variable in +etc/custom.porperties+. When enabled, any mapping change from the
539 RPC interface will trigger an SMR packet to all data plane elements that have
540 requested the mapping in the last 24 hours (this value was chosen because it's
541 the default TTL of Cisco IOS xTR mapping registrations). If disabled, ITRs
542 keep their mappings until the TTL specified in the Map-Reply expires.
544 . To add a service chain into the path from the client to the server, we can
545 use an Explicit Locator Path, specifying the *service-node* as the first
546 hop and *server1* (or *server2*) as the second hop. The following will
549 curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
550 http://localhost:8181/restconf/operations/odl-mappingservice:add-mapping \
553 where the 'elp.json' file is as follows:
561 "action": "NoAction",
562 "authoritative": true,
564 "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
565 "ipv4-prefix": "2.2.2.2/32"
572 "multicastPriority": 255,
573 "multicastWeight": 0,
574 "localLocator": true,
578 "address-type": "ietf-lisp-address-types:explicit-locator-path-lcaf",
579 "explicit-locator-path": {
582 "hop-id": "service-node",
583 "address": "192.168.16.33",
588 "address": "192.168.16.31",
601 After the mapping for 2.2.2.2/32 is updated with the above, the ICMP traffic
602 from *client* to *server1* will flow through the *service-node*. You can
603 confirm this in the LISPmob logs, or by sniffing the traffic on either the
604 *service-node* or *server1*. Note that service chains are unidirectional, so
605 unless another ELP mapping is added for the return traffic, packets will go
606 from *server1* to *client* directly.
608 . Suppose the *service-node* is actually a firewall, and traffic is diverted
609 there to support access control lists (ACLs). In this tutorial that can be
610 emulated by using +iptables+ firewall rules in the *service-node* VM. To
611 deny traffic on the service chain defined above, the following rule can be
614 iptables -A OUTPUT --dst 192.168.16.31 -j DROP
617 The ping from the *client* should now have stopped.
619 In this case the ACL is done on the destination RLOC. There is an effort underway in the LISPmob
620 community to allow filtering on EIDs, which is the more logical place to apply
623 . To delete the rule and restore connectivity on the service chain, delete
624 the ACL by issuing the following command:
626 iptables -D OUTPUT --dst 192.168.16.31 -j DROP
629 which should restore connectivity.
631 === LISP Flow Mapping Support
633 For support the lispflowmapping project can be reached by emailing the
634 developer mailing list: lispflowmapping-dev@lists.opendaylight.org or on the
635 #opendaylight-lispflowmapping IRC channel on irc.freenode.net.
637 Additional information is also available on the https://wiki.opendaylight.org/view/OpenDaylight_Lisp_Flow_Mapping:Main[Lisp Flow Mapping wiki]
639 include::lispflowmapping-clustering-user.adoc[Clustering in lispflowmapping]