vtep/README.ovs-vtep.md

   1 How to Use the VTEP Emulator
   2 ============================
   3
   4 This document explains how to use ovs-vtep, a VTEP emulator that uses
   5 Open vSwitch for forwarding.
   6
   7 Requirements
   8 ------------
   9
  10 The VTEP emulator is a Python script that invokes calls to tools like
  11 vtep-ctl and ovs-vsctl and is useful only when OVS daemons like ovsdb-server
  12 and ovs-vswitchd are running. So those components should be installed. This
  13 can be done by either of the following methods.
  14
  15 1. Follow the instructions in the INSTALL.md file of the Open vSwitch repository
  16 (don't start any daemons yet).
  17
  18 2. Follow the instructions in INSTALL.Debian.md file and then install the
  19 "openvswitch-vtep" package (if operating on a debian based machine). This
  20 will automatically start the daemons.
  21
  22 Design
  23 ======
  24
  25 At the end of this process, you should have the following setup:
  26
  27
  28       +---------------------------------------------------+
  29       | Host Machine                                      |
  30       |                                                   |
  31       |                                                   |
  32       |       +---------+ +---------+                     |
  33       |       |         | |         |                     |
  34       |       |   VM1   | |   VM2   |                     |
  35       |       |         | |         |                     |
  36       |       +----o----+ +----o----+                     |
  37       |            |           |                          |
  38       | br0 +------o-----------o--------------------o--+  |
  39       |            p0          p1                  br0    |
  40       |                                                   |
  41       |                                                   |
  42       |                              +------+   +------+  |
  43       +------------------------------| eth0 |---| eth1 |--+
  44                                      +------+   +------+
  45                                      10.1.1.1   10.2.2.1
  46                         MANAGEMENT      |          |
  47                       +-----------------o----+     |
  48                                                    |
  49                                    DATA/TUNNEL     |
  50                                  +-----------------o---+
  51
  52 Notes:
  53
  54 1. We will use Open vSwitch to create our "physical" switch labeled br0
  55
  56 2. Our "physical" switch br0 will have one internal port also named br0
  57    and two "physical" ports, namely p0 and p1.
  58
  59 3. The host machine may have two external interfaces. We will use eth0
  60    for management traffic and eth1 for tunnel traffic (One can use
  61    a single interface to achieve both). Please take note of their IP
  62    addresses in the diagram. You do not have to use exactly
  63    the same IP addresses. Just know that the above will be used in the
  64    steps below.
  65
  66 4. You can optionally connect physical machines instead of virtual
  67    machines to switch br0. In that case:
  68
  69    4.1. Make sure you have two extra physical interfaces in your host
  70         machine, eth2 and eth3.
  71
  72    4.2. In the rest of this doc, replace p0 with eth2 and p1 with eth3.
  73
  74 5. In addition to implementing p0 and p1 as physical interfaces, you can
  75    also optionally implement them as standalone TAP devices, or VM
  76    interfaces for simulation.
  77
  78 6. Creating and attaching the VMs is outside the scope of this document
  79    and is included in the diagram for reference purposes only.
  80
  81 Startup
  82 -------
  83
  84 These instructions describe how to run with a single ovsdb-server
  85 instance that handles both the OVS and VTEP schema. You can skip
  86 steps 1-3 if you installed using the debian packages as mentioned in
  87 step 2 of the "Requirements" section.
  88
  89 1. Create the initial OVS and VTEP schemas:
  90
  91     ovsdb-tool create /etc/openvswitch/ovs.db vswitchd/vswitch.ovsschema
  92     ovsdb-tool create /etc/openvswitch/vtep.db vtep/vtep.ovsschema
  93
  94 2. Start ovsdb-server and have it handle both databases:
  95
  96     ovsdb-server --pidfile --detach --log-file \
  97       --remote punix:/var/run/openvswitch/db.sock \
  98       --remote=db:hardware_vtep,Global,managers \
  99       /etc/openvswitch/ovs.db /etc/openvswitch/vtep.db
 100
 101 3. Start OVS as normal:
 102
 103     ovs-vswitchd --log-file --detach --pidfile \
 104       unix:/var/run/openvswitch/db.sock
 105
 106 4. Create a "physical" switch and its ports in OVS:
 107
 108     ovs-vsctl add-br br0
 109     ovs-vsctl add-port br0 p0
 110     ovs-vsctl add-port br0 p1
 111
 112 5. Configure the physical switch in the VTEP database:
 113
 114     vtep-ctl add-ps br0
 115     vtep-ctl set Physical_Switch br0 tunnel_ips=10.2.2.1
 116
 117 6. Start the VTEP emulator. If you installed the components by reading the
 118    INSTALL.md file, run the following from the same directory as this
 119    README.md:
 120
 121     ./ovs-vtep --log-file=/var/log/openvswitch/ovs-vtep.log \
 122       --pidfile=/var/run/openvswitch/ovs-vtep.pid \
 123       --detach br0
 124
 125     If the installation was done by installing the openvswitch-vtep
 126     package, you can find ovs-vtep at /usr/share/openvswitch/scripts.
 127
 128 7. Configure the VTEP database's manager to point at an NVC:
 129
 130     vtep-ctl set-manager tcp:<CONTROLLER IP>:6632
 131
 132    Where CONTROLLER IP is your controller's IP address that is accessible
 133    via the Host Machine's eth0 interface.
 134
 135 Simulating an NVC
 136 -----------------
 137
 138 A VTEP implementation expects to be driven by a Network Virtualization
 139 Controller (NVC), such as NSX.  If one does not exist, it's possible to
 140 use vtep-ctl to simulate one:
 141
 142 1. Create a logical switch:
 143
 144     vtep-ctl add-ls ls0
 145
 146 2. Bind the logical switch to a port:
 147
 148     vtep-ctl bind-ls br0 p0 0 ls0
 149     vtep-ctl set Logical_Switch ls0 tunnel_key=33
 150
 151 3. Direct unknown destinations out a tunnel:
 152
 153     vtep-ctl add-mcast-remote ls0 unknown-dst 10.2.2.2
 154
 155 4. Direct unicast destinations out a different tunnel:
 156
 157     vtep-ctl add-ucast-remote ls0 11:22:33:44:55:66 10.2.2.3