README-lisp.rst

   1 ..
   2       Licensed under the Apache License, Version 2.0 (the "License"); you may
   3       not use this file except in compliance with the License. You may obtain
   4       a copy of the License at
   5
   6           http://www.apache.org/licenses/LICENSE-2.0
   7
   8       Unless required by applicable law or agreed to in writing, software
   9       distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  10       WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  11       License for the specific language governing permissions and limitations
  12       under the License.
  13
  14       Convention for heading levels in Open vSwitch documentation:
  15
  16       =======  Heading 0 (reserved for the title in a document)
  17       -------  Heading 1
  18       ~~~~~~~  Heading 2
  19       +++++++  Heading 3
  20       '''''''  Heading 4
  21
  22       Avoid deeper levels because they do not render well.
  23
  24 ====================
  25 Using LISP tunneling
  26 ====================
  27
  28 LISP is a layer 3 tunneling mechanism, meaning that encapsulated packets do not
  29 carry Ethernet headers, and ARP requests shouldn't be sent over the tunnel.
  30 Because of this, there are some additional steps required for setting up LISP
  31 tunnels in Open vSwitch, until support for L3 tunnels will improve.
  32
  33 This guide assumes tunneling between two VMs connected to OVS bridges on
  34 different hypervisors reachable over IPv4.  Of course, more than one VM may be
  35 connected to any of the hypervisors, and a hypervisor may communicate with
  36 several different hypervisors over the same lisp tunneling interface.  A LISP
  37 "map-cache" can be implemented using flows, see example at the bottom of this
  38 file.
  39
  40 There are several scenarios:
  41
  42 1) the VMs have IP addresses in the same subnet and the hypervisors are also
  43    in a single subnet (although one different from the VM's);
  44 2) the VMs have IP addresses in the same subnet but the hypervisors are
  45    separated by a router;
  46 3) the VMs are in different subnets.
  47
  48 In cases 1) and 3) ARP resolution can work as normal: ARP traffic is configured
  49 not to go through the LISP tunnel.  For case 1) ARP is able to reach the other
  50 VM, if both OVS instances default to MAC address learning.  Case 3) requires
  51 the hypervisor be configured as the default router for the VMs.
  52
  53 In case 2) the VMs expect ARP replies from each other, but this is not possible
  54 over a layer 3 tunnel.  One solution is to have static MAC address entries
  55 preconfigured on the VMs (e.g., ``arp -f /etc/ethers`` on startup on Unix based
  56 VMs), or have the hypervisor do proxy ARP.  In this scenario, the eth0
  57 interfaces need not be added to the br0 bridge in the examples below.
  58
  59 On the receiving side, the packet arrives without the original MAC header.  The
  60 LISP tunneling code attaches a header with harcoded source and destination MAC
  61 address ``02:00:00:00:00:00``.  This address has all bits set to 0, except the
  62 locally administered bit, in order to avoid potential collisions with existing
  63 allocations.  In order for packets to reach their intended destination, the
  64 destination MAC address needs to be rewritten.  This can be done using the flow
  65 table.
  66
  67 See below for an example setup, and the associated flow rules to enable LISP
  68 tunneling.
  69
  70 ::
  71
  72     Diagram
  73
  74            +---+                               +---+
  75            |VM1|                               |VM2|
  76            +---+                               +---+
  77              |                                   |
  78         +--[tap0]--+                       +--[tap0]---+
  79         |          |                       |           |
  80     [lisp0] OVS1 [eth0]-----------------[eth0] OVS2 [lisp0]
  81         |          |                       |           |
  82         +----------+                       +-----------+
  83
  84 On each hypervisor, interfaces tap0, eth0, and lisp0 are added to a single
  85 bridge instance, and become numbered 1, 2, and 3 respectively:
  86
  87 ::
  88
  89     $ ovs-vsctl add-br br0
  90     $ ovs-vsctl add-port br0 tap0
  91     $ ovs-vsctl add-port br0 eth0
  92     $ ovs-vsctl add-port br0 lisp0 \
  93       -- set Interface lisp0 type=lisp options:remote_ip=flow options:key=flow
  94
  95 The last command sets up flow based tunneling on the lisp0 interface.  From
  96 the LISP point of view, this is like having the Tunnel Router map cache
  97 implemented as flow rules.
  98
  99 Flows on br0 should be configured as follows:
 100
 101 ::
 102
 103     priority=3,dl_dst=02:00:00:00:00:00,action=mod_dl_dst:<VMx_MAC>,output:1
 104     priority=2,in_port=1,dl_type=0x0806,action=NORMAL
 105     priority=1,in_port=1,dl_type=0x0800,vlan_tci=0,nw_src=<EID_prefix>,action=set_field:<OVSx_IP>->tun_dst,output:3
 106     priority=0,action=NORMAL
 107
 108 The third rule is like a map cache entry: the ``<EID_prefix>`` specified by the
 109 ``nw_src`` match field is mapped to the RLOC ``<OVSx_IP>``, which is set as the
 110 tunnel destination for this particular flow.
 111
 112 Optionally, if you want to use Instance ID in a flow, you can add
 113 ``set_tunnel:<IID>`` to the action list.