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="<2s,>,>,<,<4l"]
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/stable/beryllium+.
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* The README.md lists the dependencies needed to
275 build it from source.
276 * *A virtualization platform*
278 ===== Target Environment
280 The three LISP data plane nodes and the LISP mapping system are assumed to be
281 running in Linux virtual machines, which have the +eth0+ interface in NAT mode
282 to allow outside internet access and +eth1+ connected to a host-only network,
283 with the following IP addresses (please adjust configuration files, JSON
284 examples, etc. accordingly if you're using another addressing scheme):
286 .Nodes in the tutorial
287 [align="right",options="header"]
289 | Node | Node Type | IP Address
290 | *controller* | OpenDaylight | 192.168.16.11
291 | *client* | LISPmob | 192.168.16.30
292 | *server1* | LISPmob | 192.168.16.31
293 | *server2* | LISPmob | 192.168.16.32
294 | *service-node* | LISPmob | 192.168.16.33
297 NOTE: While the tutorial uses LISPmob as the data plane, it could be any
298 LISP-enabled hardware or software router (commercial/open source).
302 The below steps use the command line tool cURL to talk to the LISP Flow
303 Mapping RPC REST API. This is so that you can see the actual request URLs and
304 body content on the page.
306 . Install and run OpenDaylight Beryllium release on the controller VM. Please
307 follow the general OpenDaylight Beryllium Installation Guide for this step.
308 Once the OpenDaylight controller is running install the
309 'odl-openflowplugin-msmr' feature from the Karaf CLI:
311 feature:install odl-lispflowmapping-msmr
313 It takes quite a while to load and initialize all features and their
314 dependencies. It's worth running the command +log:tail+ in the Karaf console
315 to see when the log output is winding down, and continue with the tutorial
318 . Install LISPmob on the *client*, *server1*, *server2*, and *service-node*
319 VMs following the installation instructions
320 https://github.com/LISPmob/lispmob#software-prerequisites[from the LISPmob
323 . Configure the LISPmob installations from the previous step. Starting from
324 the +lispd.conf.example+ file in the distribution, set the EID in each
325 +lispd.conf+ file from the IP address space selected for your virtual/LISP
326 network. In this tutorial the EID of the *client* is set to 1.1.1.1/32, and
327 that of *server1* and *server2* to 2.2.2.2/32.
329 . Set the RLOC interface to +eth1+ in each +lispd.conf+ file. LISP will
330 determine the RLOC (IP address of the corresponding VM) based on this
333 . Set the Map-Resolver address to the IP address of the *controller*, and on
334 the *client* the Map-Server too. On *server1* and *server2* set the
335 Map-Server to something else, so that it doesn't interfere with the
336 mappings on the controller, since we're going to program them manually.
338 . Modify the "key" parameter in each +lispd.conf+ file to a key/password of
339 your choice ('password' in this tutorial).
341 NOTE: The +resources/tutorial+ directory in the 'stable/beryllium' branch of the
342 project git repository has the files used in the tutorial
343 https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=tree;f=resources/tutorial;hb=refs/heads/stable/beryllium[checked
344 in], so you can just copy the files to +/root/lispd.conf+ on the
345 respective VMs. You will also find the JSON files referenced below in
348 . Define a key and EID prefix association in OpenDaylight using the RPC REST
349 API for the *client* EID (1.1.1.1/32) to allow registration from the
350 southbound. Since the mappings for the server EID will be configured from
351 the REST API, no such association is necessary. Run the below command on
352 the *controller* (or any machine that can reach *controller*, by replacing
353 'localhost' with the IP address of *controller*).
355 curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
356 http://localhost:8181/restconf/operations/odl-mappingservice:add-key \
360 where the content of the 'add-key.json' file is the following:
367 "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
368 "ipv4-prefix": "1.1.1.1/32"
371 "key-string": "password",
378 . Verify that the key is added properly by requesting the following URL:
380 curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
381 http://localhost:8181/restconf/operations/odl-mappingservice:get-key \
385 where the content of the 'get1.json' file can be derived from the
386 'add-key.json' file by removing the 'mapping-authkey' field. The output the
387 above invocation should look like this:
389 {"output":{"mapping-authkey":{"key-type":1,"key-string":"password"}}}
391 . Run the +lispd+ LISPmob daemon on all VMs:
393 lispd -f /root/lispd.conf
395 . The *client* LISPmob node should now register its EID-to-RLOC mapping in
396 OpenDaylight. To verify you can lookup the corresponding EIDs via the REST
399 curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
400 http://localhost:8181/restconf/operations/odl-mappingservice:get-mapping \
404 An alternative way for retrieving mappings from ODL using the southbound
405 interface is using the https://github.com/davidmeyer/lig[+lig+] open source
408 . Register the EID-to-RLOC mapping of the server EID 2.2.2.2/32 to the
409 controller, pointing to *server1* and *server2* with a higher priority for
412 curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
413 http://localhost:8181/restconf/operations/odl-mappingservice:add-mapping \
416 where the 'mapping.json' file looks like this:
424 "action": "NoAction",
425 "authoritative": true,
427 "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
428 "ipv4-prefix": "2.2.2.2/32"
432 "locator-id": "server1",
435 "multicastPriority": 255,
436 "multicastWeight": 0,
437 "localLocator": true,
441 "address-type": "ietf-lisp-address-types:ipv4-afi",
442 "ipv4": "192.168.16.31"
446 "locator-id": "server2",
449 "multicastPriority": 255,
450 "multicastWeight": 0,
451 "localLocator": true,
455 "address-type": "ietf-lisp-address-types:ipv4-afi",
456 "ipv4": "192.168.16.32"
465 Here the priority of the second RLOC (192.168.16.32 - *server2*) is 2, a higher
466 numeric value than the priority of 192.168.16.31, which is 1. This policy is
467 saying that *server1* is preferred to *server2* for reaching EID 2.2.2.2/32.
468 Note that lower priority value has higher preference in LISP.
470 . Verify the correct registration of the 2.2.2.2/32 EID:
472 curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
473 http://localhost:8181/restconf/operations/odl-mappingservice:get-mapping \
477 where 'get2.json' can be derived from 'get1.json' by changing the content of
478 the 'Ipv4Address' field from '1.1.1.1' to '2.2.2.2'.
480 . Now the LISP network is up. To verify, log into the *client* VM and ping the server EID:
484 . Let's test fail-over now. Suppose you had a service on *server1* which
485 became unavailable, but *server1* itself is still reachable. LISP will not
486 automatically fail over, even if the mapping for 2.2.2.2/32 has two
487 locators, since both locators are still reachable and uses the one with the
488 higher priority (lowest priority value). To force a failover, we need to
489 set the priority of *server2* to a lower value. Using the file mapping.json
490 above, swap the priority values between the two locators (lines 14 and 28
491 in 'mapping.json') and repeat the request from step 11. You can also
492 repeat step 12 to see if the mapping is correctly registered. If you leave
493 the ping on, and monitor the traffic using wireshark, you can see that the
494 ping traffic to 2.2.2.2 will be diverted from the *server1* RLOC to the
497 With the default OpenDaylight configuration the failover should be near
498 instantaneous (we observed 3 lost pings in the worst case), because of the
499 LISP http://tools.ietf.org/html/rfc6830#section-6.6.2[Solicit-Map-Request
500 (SMR) mechanism] that can ask a LISP data plane element to update its mapping
501 for a certain EID (enabled by default). It is controlled by the +lisp.smr+
502 variable in +etc/custom.porperties+. When enabled, any mapping change from the
503 RPC interface will trigger an SMR packet to all data plane elements that have
504 requested the mapping in the last 24 hours (this value was chosen because it's
505 the default TTL of Cisco IOS xTR mapping registrations). If disabled, ITRs
506 keep their mappings until the TTL specified in the Map-Reply expires.
508 . To add a service chain into the path from the client to the server, we can
509 use an Explicit Locator Path, specifying the *service-node* as the first
510 hop and *server1* (or *server2*) as the second hop. The following will
513 curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
514 http://localhost:8181/restconf/operations/odl-mappingservice:add-mapping \
517 where the 'elp.json' file is as follows:
525 "action": "NoAction",
526 "authoritative": true,
528 "address-type": "ietf-lisp-address-types:ipv4-prefix-afi",
529 "ipv4-prefix": "2.2.2.2/32"
536 "multicastPriority": 255,
537 "multicastWeight": 0,
538 "localLocator": true,
542 "address-type": "ietf-lisp-address-types:explicit-locator-path-lcaf",
543 "explicit-locator-path": {
546 "hop-id": "service-node",
547 "address": "192.168.16.33",
552 "address": "192.168.16.31",
565 After the mapping for 2.2.2.2/32 is updated with the above, the ICMP traffic
566 from *client* to *server1* will flow through the *service-node*. You can
567 confirm this in the LISPmob logs, or by sniffing the traffic on either the
568 *service-node* or *server1*. Note that service chains are unidirectional, so
569 unless another ELP mapping is added for the return traffic, packets will go
570 from *server1* to *client* directly.
572 . Suppose the *service-node* is actually a firewall, and traffic is diverted
573 there to support access control lists (ACLs). In this tutorial that can be
574 emulated by using +iptables+ firewall rules in the *service-node* VM. To
575 deny traffic on the service chain defined above, the following rule can be
578 iptables -A OUTPUT --dst 192.168.16.31 -j DROP
581 The ping from the *client* should now have stopped.
583 In this case the ACL is done on the destination RLOC. There is an effort underway in the LISPmob
584 community to allow filtering on EIDs, which is the more logical place to apply
587 . To delete the rule and restore connectivity on the service chain, delete
588 the ACL by issuing the following command:
590 iptables -D OUTPUT --dst 192.168.16.31 -j DROP
593 which should restore connectivity.
595 === LISP Flow Mapping Support
597 For support the lispflowmapping project can be reached by emailing the
598 developer mailing list: lispflowmapping-dev@lists.opendaylight.org or on the
599 #opendaylight-lispflowmapping IRC channel on irc.freenode.net.
601 Additional information is also available on the https://wiki.opendaylight.org/view/OpenDaylight_Lisp_Flow_Mapping:Main[Lisp Flow Mapping wiki]