Expand on the definition of VTEP (it took me a bit of Googling). Signed-off-by: Stephen Finucane <step...@that.guru> --- vtep/README.ovs-vtep.md | 205 ----------------------------------------- vtep/README.ovs-vtep.rst | 231 +++++++++++++++++++++++++++++++++++++++++++++++ vtep/automake.mk | 2 +- 3 files changed, 232 insertions(+), 206 deletions(-) delete mode 100644 vtep/README.ovs-vtep.md create mode 100644 vtep/README.ovs-vtep.rst
diff --git a/vtep/README.ovs-vtep.md b/vtep/README.ovs-vtep.md deleted file mode 100644 index e08c8e6..0000000 --- a/vtep/README.ovs-vtep.md +++ /dev/null @@ -1,205 +0,0 @@ -How to Use the VTEP Emulator -============================ - -This document explains how to use ovs-vtep, a VTEP emulator that uses -Open vSwitch for forwarding. - -Requirements ------------- - -The VTEP emulator is a Python script that invokes calls to tools like -vtep-ctl and ovs-vsctl and is useful only when OVS daemons like ovsdb-server -and ovs-vswitchd are running. So those components should be installed. This -can be done by either of the following methods. - -1. Follow the instructions in the INSTALL.md file of the Open vSwitch repository -(don't start any daemons yet). - -2. Follow the instructions in INSTALL.Debian.rst file and then install the -"openvswitch-vtep" package (if operating on a debian based machine). This -will automatically start the daemons. - -Design -====== - -At the end of this process, you should have the following setup: - - - +---------------------------------------------------+ - | Host Machine | - | | - | | - | +---------+ +---------+ | - | | | | | | - | | VM1 | | VM2 | | - | | | | | | - | +----o----+ +----o----+ | - | | | | - | br0 +------o-----------o--------------------o--+ | - | p0 p1 br0 | - | | - | | - | +------+ +------+ | - +------------------------------| eth0 |---| eth1 |--+ - +------+ +------+ - 10.1.1.1 10.2.2.1 - MANAGEMENT | | - +-----------------o----+ | - | - DATA/TUNNEL | - +-----------------o---+ - -Notes: - -1. We will use Open vSwitch to create our "physical" switch labeled br0 - -2. Our "physical" switch br0 will have one internal port also named br0 - and two "physical" ports, namely p0 and p1. - -3. The host machine may have two external interfaces. We will use eth0 - for management traffic and eth1 for tunnel traffic (One can use - a single interface to achieve both). Please take note of their IP - addresses in the diagram. You do not have to use exactly - the same IP addresses. Just know that the above will be used in the - steps below. - -4. You can optionally connect physical machines instead of virtual - machines to switch br0. In that case: - - 4.1. Make sure you have two extra physical interfaces in your host - machine, eth2 and eth3. - - 4.2. In the rest of this doc, replace p0 with eth2 and p1 with eth3. - -5. In addition to implementing p0 and p1 as physical interfaces, you can - also optionally implement them as standalone TAP devices, or VM - interfaces for simulation. - -6. Creating and attaching the VMs is outside the scope of this document - and is included in the diagram for reference purposes only. - -Startup -------- - -These instructions describe how to run with a single ovsdb-server -instance that handles both the OVS and VTEP schema. You can skip -steps 1-3 if you installed using the debian packages as mentioned in -step 2 of the "Requirements" section. - -1. Create the initial OVS and VTEP schemas: - - ``` -ovsdb-tool create /etc/openvswitch/ovs.db vswitchd/vswitch.ovsschema -ovsdb-tool create /etc/openvswitch/vtep.db vtep/vtep.ovsschema - ``` - -2. Start ovsdb-server and have it handle both databases: - - ``` -ovsdb-server --pidfile --detach --log-file \ ---remote punix:/var/run/openvswitch/db.sock \ ---remote=db:hardware_vtep,Global,managers \ -/etc/openvswitch/ovs.db /etc/openvswitch/vtep.db - ``` - -3. Start OVS as normal: - - ``` -ovs-vswitchd --log-file --detach --pidfile \ -unix:/var/run/openvswitch/db.sock - ``` - -4. Create a "physical" switch and its ports in OVS: - - ``` -ovs-vsctl add-br br0 -ovs-vsctl add-port br0 p0 -ovs-vsctl add-port br0 p1 - ``` - -5. Configure the physical switch in the VTEP database: - - ``` -vtep-ctl add-ps br0 -vtep-ctl set Physical_Switch br0 tunnel_ips=10.2.2.1 - ``` - -6. Start the VTEP emulator. If you installed the components by reading the - INSTALL.md file, run the following from the same directory as this - README.md: - - ``` -./ovs-vtep --log-file=/var/log/openvswitch/ovs-vtep.log \ ---pidfile=/var/run/openvswitch/ovs-vtep.pid \ ---detach br0 - ``` - - If the installation was done by installing the openvswitch-vtep - package, you can find ovs-vtep at /usr/share/openvswitch/scripts. - -7. Configure the VTEP database's manager to point at an NVC: - - ``` -vtep-ctl set-manager tcp:<CONTROLLER IP>:6640 - ``` - - Where CONTROLLER IP is your controller's IP address that is accessible - via the Host Machine's eth0 interface. - -Simulating an NVC ------------------ - -A VTEP implementation expects to be driven by a Network Virtualization -Controller (NVC), such as NSX. If one does not exist, it's possible to -use vtep-ctl to simulate one: - -1. Create a logical switch: - - ``` -vtep-ctl add-ls ls0 - ``` - -2. Bind the logical switch to a port: - - ``` -vtep-ctl bind-ls br0 p0 0 ls0 -vtep-ctl set Logical_Switch ls0 tunnel_key=33 - ``` - -3. Direct unknown destinations out a tunnel. - - For handling L2 broadcast, multicast and unknown unicast traffic, - packets can be sent to all members of a logical switch referenced by - a physical switch. The "unknown-dst" address below is used to - represent these packets. There are different modes to replicate the - packets. The default mode of replication is to send the traffic to a - service node, which can be a hypervisor, server or appliance, and let - the service node handle replication to other transport nodes - (hypervisors or other VTEP physical switches). This mode is called - _service node_ replication. An alternate mode of replication, called - _source node_ replication, involves the source node sending to all - other transport nodes. Hypervisors are always responsible for doing - their own replication for locally attached VMs in both modes. - Service node mode is the default. Service node replication mode is - considered a basic requirement because it only requires sending the - packet to a single transport node. The following configuration is - for service node replication mode as only a single transport node - destination is specified for the unknown-dst address: - - ``` -vtep-ctl add-mcast-remote ls0 unknown-dst 10.2.2.2 - ``` - -4. Optionally, change the replication mode from a default of -"service\_node" to "source\_node", which can be done at the logical -switch level: - - ``` -vtep-ctl set-replication-mode ls0 source_node - ``` - -5. Direct unicast destinations out a different tunnel: - - ``` -vtep-ctl add-ucast-remote ls0 00:11:22:33:44:55 10.2.2.3 - ``` diff --git a/vtep/README.ovs-vtep.rst b/vtep/README.ovs-vtep.rst new file mode 100644 index 0000000..9e9883b --- /dev/null +++ b/vtep/README.ovs-vtep.rst @@ -0,0 +1,231 @@ +.. + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + Convention for heading levels in Open vSwitch documentation: + + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. + +============================ +How to Use the VTEP Emulator +============================ + +This document explains how to use ovs-vtep, a VXLAN Tunnel Endpoint (VTEP) +emulator that uses Open vSwitch for forwarding. VTEPs are the entities that +handle VXLAN frame encapsulation and decapsulation in a network. + +Requirements +------------ + +The VTEP emulator is a Python script that invokes calls to tools like vtep-ctl +and ovs-vsctl. It is only useful when Open vSwitch daemons like ovsdb-server +and ovs-vswitchd are running and installed. To do this, either: + +- Follow the instructions in the `installation guide <..INSTALL.rst>`__ (don't + start any daemons yet). + +- Follow the instructions in `Debian installation guide + <../INSTALL.Debian.rst>`__ and then install the ``openvswitch-vtep`` package + (if operating on a debian based machine). This will automatically start the + daemons. + +Design +------ + +At the end of this process, you should have the following setup: + +:: + + Architecture + + +---------------------------------------------------+ + | Host Machine | + | | + | | + | +---------+ +---------+ | + | | | | | | + | | VM1 | | VM2 | | + | | | | | | + | +----o----+ +----o----+ | + | | | | + | br0 +------o-----------o--------------------o--+ | + | p0 p1 br0 | + | | + | | + | +------+ +------+ | + +------------------------------| eth0 |---| eth1 |--+ + +------+ +------+ + 10.1.1.1 10.2.2.1 + MANAGEMENT | | + +-----------------o----+ | + | + DATA/TUNNEL | + +-----------------o---+ + +Some important points. + +- We will use Open vSwitch to create our "physical" switch labeled ``br0`` + +- Our "physical" switch ``br0`` will have one internal port also named ``br0`` + and two "physical" ports, namely ``p0`` and ``p1``. + +- The host machine may have two external interfaces. We will use ``eth0`` for + management traffic and ``eth1`` for tunnel traffic (One can use a single + interface to achieve both). Please take note of their IP addresses in the + diagram. You do not have to use exactly the same IP addresses. Just know that + the above will be used in the steps below. + +- You can optionally connect physical machines instead of virtual machines to + switch ``br0``. In that case: + + - Make sure you have two extra physical interfaces in your host machine, + ``eth2`` and ``eth3``. + + - In the rest of this doc, replace ``p0`` with ``eth2`` and ``p1`` with + ``eth3``. + +5. In addition to implementing ``p0`` and ``p1`` as physical interfaces, you + can also optionally implement them as standalone TAP devices, or VM + interfaces for simulation. + +6. Creating and attaching the VMs is outside the scope of this document and is + included in the diagram for reference purposes only. + +Startup +------- + +These instructions describe how to run with a single ovsdb-server instance that +handles both the OVS and VTEP schema. You can skip steps 1-3 if you installed +using the debian packages as mentioned in step 2 of the "Requirements" section. + +1. Create the initial OVS and VTEP schemas: + + :: + + $ ovsdb-tool create /etc/openvswitch/ovs.db vswitchd/vswitch.ovsschema + $ ovsdb-tool create /etc/openvswitch/vtep.db vtep/vtep.ovsschema + ``` + +2. Start ovsdb-server and have it handle both databases: + + :: + + $ ovsdb-server --pidfile --detach --log-file \ + --remote punix:/var/run/openvswitch/db.sock \ + --remote=db:hardware_vtep,Global,managers \ + /etc/openvswitch/ovs.db /etc/openvswitch/vtep.db + +3. Start ovs-vswitchd as normal: + + :: + + $ ovs-vswitchd --log-file --detach --pidfile \ + unix:/var/run/openvswitch/db.sock + +4. Create a "physical" switch and its ports in OVS: + + :: + + $ ovs-vsctl add-br br0 + $ ovs-vsctl add-port br0 p0 + $ ovs-vsctl add-port br0 p1 + +5. Configure the physical switch in the VTEP database: + + :: + + $ vtep-ctl add-ps br0 + $ vtep-ctl set Physical_Switch br0 tunnel_ips=10.2.2.1 + +6. Start the VTEP emulator. If you installed the components following the + `installation guide <../INSTALL.rst>`__ file, run the following from the + same directory as this README.md: + + :: + + $ ./ovs-vtep --log-file=/var/log/openvswitch/ovs-vtep.log \ + --pidfile=/var/run/openvswitch/ovs-vtep.pid \ + --detach br0 + + If the installation was done by installing the openvswitch-vtep package, you + can find ovs-vtep at ``/usr/share/openvswitch/scripts``. + +7. Configure the VTEP database's manager to point at an NVC: + + :: + + $ vtep-ctl set-manager tcp:<CONTROLLER IP>:6640 + + Where ``<CONTROLLER IP>`` is your controller's IP address that is accessible + via the Host Machine's eth0 interface. + +Simulating an NVC +----------------- + +A VTEP implementation expects to be driven by a Network Virtualization +Controller (NVC), such as NSX. If one does not exist, it's possible to use +vtep-ctl to simulate one: + +1. Create a logical switch: + + :: + + $ vtep-ctl add-ls ls0 + +2. Bind the logical switch to a port: + + :: + + $ vtep-ctl bind-ls br0 p0 0 ls0 + $ vtep-ctl set Logical_Switch ls0 tunnel_key=33 + +3. Direct unknown destinations out a tunnel. + + For handling L2 broadcast, multicast and unknown unicast traffic, packets + can be sent to all members of a logical switch referenced by a physical + switch. The "unknown-dst" address below is used to represent these packets. + There are different modes to replicate the packets. The default mode of + replication is to send the traffic to a service node, which can be a + hypervisor, server or appliance, and let the service node handle replication + to other transport nodes (hypervisors or other VTEP physical switches). + This mode is called *service node* replication. An alternate mode of + replication, called *source node* replication, involves the source node + sending to all other transport nodes. Hypervisors are always responsible + for doing their own replication for locally attached VMs in both modes. + Service node mode is the default. Service node replication mode is + considered a basic requirement because it only requires sending the packet + to a single transport node. The following configuration is for service node + replication mode as only a single transport node destination is specified + for the unknown-dst address: + + :: + + $ vtep-ctl add-mcast-remote ls0 unknown-dst 10.2.2.2 + +4. Optionally, change the replication mode from a default of ``service_node`` + to ``source_node``, which can be done at the logical switch level: + + :: + + $ vtep-ctl set-replication-mode ls0 source_node + +5. Direct unicast destinations out a different tunnel: + + :: + + $ vtep-ctl add-ucast-remote ls0 00:11:22:33:44:55 10.2.2.3 diff --git a/vtep/automake.mk b/vtep/automake.mk index 2645f30..6a98144 100644 --- a/vtep/automake.mk +++ b/vtep/automake.mk @@ -40,7 +40,7 @@ vtep_vtep_ctl_LDADD = vtep/libvtep.la lib/libopenvswitch.la scripts_SCRIPTS += \ vtep/ovs-vtep -docs += vtep/README.ovs-vtep.md +docs += vtep/README.ovs-vtep.rst EXTRA_DIST += vtep/ovs-vtep FLAKE8_PYFILES += vtep/ovs-vtep -- 2.7.4 _______________________________________________ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev