Describe dummy test model. Work on OpenFlow intro.

[openvswitch] / doc / manual.texi

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename openvswitch.info
@settitle Open vSwitch Guide
@c %**end of header

@macro ovs {}
Open@tie{}vSwitch
@end macro

@copying
Copyright @copyright{} 2012, 2013 Nicira, Inc.

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
@url{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.
@end copying

@titlepage
@title Programming the Open vSwitch Platform
@author Open vSwitch Contributors

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top TITLE

This manual is for Open vSwitch, version 1.9.
@end ifnottex

@menu
* Introduction::
@end menu

@node Introduction
@chapter Introduction

Open vSwitch is an Ethernet switch implemented in software.  It is
well suited to environments that call for basic switching features
such as VLANs and bonding.  However, Open vSwitch is built as a
platform to open up network forwarding to programmatic extension, so
it really shines in environments that demand fast, flexible control
over the network.

Open vSwitch is most often deployed today as a purely software switch,
that is, on computers without hardware specialized for packet
switching.  In this class of uses, Open vSwitch most often runs on
virtual server hosts, to forward virtual machine network traffic to
and from a physical network.  Virtualization is not a requirement:
Open vSwitch can also forward traffic among physical interfaces in a
``bare metal'' environment.

Open vSwitch is designed and internally layered to be amenable for use
within special-purpose switch hardware, and a number of network
hardware manufacturers have used it for that purpose.  This allows
Open vSwitch to control high-performance hardware switches as well as
software switches, although hardware is inherently less flexible than
software.

Open vSwitch runs on top of a wide variety of hardware, operating
systems, and hypervisors, and it has been integrated with multiple
cloud management systems.  Please refer to Open vSwitch and vendor
documentation for details.

@menu
* Architecture::                
@end menu

@node Architecture
@section Architecture

This section describes the components of Open vSwitch at a high-level
and how they interact with each other and with components not part of
Open vSwitch.

The most important component of Open vSwitch is the virtual switch
daemon, @command{ovs-vswitchd}.  This daemon implements Open vSwitch
core switching and programmability functions.  In a software switch,
this daemon is a ``soft real-time'' component that handles the first
packet of each new flow that enters the network.  In a hardware
switch, it instead configures the hardware's packet processing
features.

The virtual switch daemon has two important external interfaces.  The
first of these speaks a protocol called OVSDB to the second major Open
vSwitch daemon, the @command{ovsdb-server} database server.  This
daemon's configuration database tracks typically slowly changing
management plane state, such as the set of configured switches and
their ports.  The database server can also talk to controllers on
remote servers over the same OVSDB protocol.

@command{ovs-vswitchd}'s other major external interface is the control
plane interface.  This interface allows controllers on remote servers
to directly control the treatment of packets that arrive on the
switches configured in the database.  Control can be reactive, with
the controller deciding what should be done for each new flow as it
arrives at the switch, or proactive, with the controller specifying in
advance the treatment of every packet that might happen to arrive, or
some combination.  Open vSwitch uses the OpenFlow protocol for this
control plane interface.

Open vSwitch also includes a number of utility programs.
@command{ovs-vsctl} is an interactive command-line interface to
@command{ovsdb-server} for configuring and querying Open vSwitch
configuration.  It is also used heavily in shell scripts that
integrate Open vSwitch with hypervisor and cloud management systems.

@command{ovs-ofctl} is a command-line tool that speaks the OpenFlow
protocol.  Unlike @command{ovs-vsctl}, which is often used in
production, it is most useful for troubleshooting and prototyping.  We
will often use it in examples in this book.

@command{ovs-appctl} is a command-line tool to send commands to
@command{ovs-vswitchd} and @command{ovsdb-server}.  It is occasionally
useful for special purposes, especially in testing and debugging.

@node Testing
@chapter Testing

Testing is essential to writing reliable software, so as network
operation becomes programmable, testing becomes essential to designing
a network.  This chapter discusses different ways that one can test
a network containing Open vSwitch elements.

The goal of testing is to model a network setup that one would use in
production, to allow one to assess important properties of that setup,
such as its correctness, performance, and scalability.  How the model
is constructed determines which properties can be assessed and how
accurately.  The model also determines properties of the testing
itself, such as how easy or difficult the testing is to set up, to
replicate, and to change, how expensive and time-consuming the testing
is, and how easy or difficult the results are to interpret.

@menu
* Physical Test Models::        
* Virtual Test Models::         
@end menu

@node Physical Test Models
@section Physical Test Models

The most obvious way to test Open vSwitch is to use a model that
replicates the production system, or to use the production system for
testing.  This form of modeling allows accurate performance
measurements, but in most other respects, it is inconvenient.  Setting
up a new network topology may require physically replugging network
cables, which is time-consuming and error-prone.  Recovering from
errors in the network programming, which are sure to be encountered
during testing, may require setting up an extra out-of-band network.
Finally, running multiple tests in parallel requires replicating the
entire setup.

Simple setups, such as those that involve only one machine acting as a
switch, can often be tested satisfactorily as physical models.  At
least one Open vSwitch developer tests his changes this way
exclusively.

@node Virtual Test Models
@section Virtual Test Models

Virtualization is one way to ease the inconvenience of testing with a
physical model, that is, to use virtual machines instead of physical
ones, and virtual switches instead of physical switches.  Because
virtual machines and virtual switches are easier to reconfigure than
physical machines and physical switches, this makes running different
tests easier.  Virtual environments also reduce the need for physical
hardware and at the same time, it is easier to replicate virtual
environments, so taken together it becomes cheaper to run multiple
tests in parallel.

A virtual environment doesn't perfectly reproduce the performance of
the physical environment that it models.  A virtual environment
usually performs slightly worse than the corresponding physical setup,
so one may assume that, if the performance of the virtual model is
adequate, then the performance of the corresponding physical setup
would also be acceptable.  (This makes it difficult, of course, to
have confidence in the physical performance if the virtual environment
does not perform acceptably.)

One important way that a virtual environment can perform better than a
physical one is that a virtual network within a single virtual server
host may outperform a typical physical network.  The aggregate
performance of virtual network connections between collocated VMs, for
example, can easily exceed 5 Gb/s, whereas the most common physical
Ethernet connections have a maximum bandwidth of 1 Gb/s.  At the same
time, many implementations of quality-of-service (QoS) features to
limit bandwidth, including the Linux QoS features that Open vSwitch
has built-in support for configuring, are designed for physical
Ethernet connections and do not work well within a virtual server
host.

Using a virtual model can become more difficult if the network setup
that one wishes to test uses virtualization itself.  Sometimes it is
possible to ``factor'' the model so that a simple virtualization setup
still adequately models the physical setup.  For example, one might
decide that how virtual machines are assigned to physical hypervisors
is not an important characteristic of the physical environment, so
that one may represent these virtual machines of the physical
environment as virtual machines in the test model, leaving the
hypervisors of the physical environment out of the model.

In situations where factoring the physical hypervisors out of the test
model is not acceptable, one may resort to @dfn{nested
virtualization}, that is, running hypervisors inside hypervisors.
This decision is not to be made lightly, because nested virtualization
has disadvantages beyond those of ordinary virtualization.  First, not
all hypervisors support nested virtualization.@footnote{In my
experience, nested virtualization works best with VMware ESX as the
outer hypervisor.}  Second, nested virtualization compounds
performance issues.  It is much more common to see poor performance
and timeouts that cannot be reproduced in a corresponding physical
setup in a virtual environment that includes nested hypervisors.

@node Dummy Test Models
@section Dummy Test Models

Open vSwitch has a few special ``dummy'' features for testing
purposes.  A @dfn{dummy switch} is an Open vSwitch switch that it
simulates entirely within itself, without connecting to any physical
or virtual hardware.  Typically a dummy switch's ports will be
populated with dummy network devices, which are, similarly, simulated
entirely within @command{ovs-vswitchd}.

A ``dummy test model,'' that is, a test model based on Open vSwitch
dummy switches, requires no virtual or physical hardware, no
supervisor privilege, and runs comfortably with minimal memory and CPU
resources.  However, dummy test models do not realistically model
actual traffic patterns or performance.  They also rely on Open
vSwitch features that are subject to change from release to release.

A unique advantage of dummy test models is that they can run faster
than real time: the user can manipulate a dummy switch's idea of the
current time can, causing it to stop or to jump forward an arbitrary
amount.  This can be invaluable for some purposes, such as testing
flow expiration or NetFlow traffic.

@node Introduction to OpenFlow
@chapter Introduction to OpenFlow

Programming an Open vSwitch software switch requires a solid grasp of
the fundamentals of OpenFlow.

An OpenFlow switch has two important parts.  The first part is the
switch's set of ports, which are the same as the ports in any other
Ethernet switch.  The second piece is a set of one or more @dfn{flow
tables}.  A flow table amounts to a set of if-then rules that tell the
switch how to handle any packet that might arrive at a port.  Each
rule, called a @dfn{flow}, specifies a condition (the @dfn{match}) and
a list of @dfn{actions} to execute if the condition is met.

To illustrate the idea of a flow table, consider a OpenFlow switch
with three ports, numbered 1, 2, and 3.  The flow table described
informally below would cause such a switch to act as a ``hub'' that
forwards each arriving packet to the other two ports:

@quotation
If the packet arrived on port 1, forward it to ports 2 and 3; @*
If the packet arrived on port 2, forward it to ports 1 and 3; @*
If the packet arrived on port 3, forward it to ports 1 and 2.
@end quotation

In this example, any packet would match exactly one flow.  OpenFlow
provides for packets possibly matching multiple flows on by requiring
the user to associate each flow with a numeric @dfn{priority}.  If a
packet matches more than one flow, the priority is used as a
tie-breaker, with the higher priority wins.  (If two matching flows
have the same priority, the behavior is undefined, so flow tables are
designed to avoid this possibility.)

In some flow tables, some packets match no flows at all.  The user can
configure an OpenFlow switch either to drop these packets or to
forward them to an OpenFlow controller (describe later) for further
processing.

@node Outline
@chapter Outline

@verbatim
* Test setups.
** Physical
** Virtual
*** start-test-vm
**** non-persistent
**** install ethtool, tcpdump, strace, valgrind, hping3, netperf (from non-free)
**** set up serial port in inittab (just uncomment the T0:... line)
**** runme, put this in /etc/rc.local and mark it executable:
**** NFS setup (mount -o ro,udp,timeo=1 10.0.2.2:/home/blp/ovs /mnt)
#!/bin/sh 
mount -t iso9660 /dev/sr0 /cdrom
exec sh -x /cdrom/runme
exit 0

** Nested virtual
** Dummy-based.
** test-vm based
*** not for performance simulation (including QoS)

* Test techniques.
** ofproto/trace
** netdev-dummy/receive
** write some tools for arp, ping, more?

* Introduction to OpenFlow.
* Packet processing pipeline.
** The ``normal'' action's pipeline.
* Examples of proactive programming.
** Hub (flood)
** Virtual switch
** Ingress-only firewall
* Limitations of proactive programming in OF1.0
** Can't do MAC learning (solution: NX or reactive programming)
** Cartesian product is expensive (OF1.1+ or NX or reactive programming)
* Reactive programming.
** Slow
** High latency
** Handles disconnection badly
** Hard to scale
* Hybrid approaches
** Proactive with a few packets to controller
** Proactive with local controller

* Management plane.
** Ports and interfaces.
** Bonding.
*** How to use through OpenFlow, and limitations.
*** Future directions.
*** How to emulate with OpenFlow?
** VLANs.
*** Interaction with OpenFlow.
** MAC learning.
*** Reading and flushing the MAC learning table.
*** Preventing MAC learning.
*** Interaction with bonding.
*** 
** Mirrors.
*** Limitations with OpenFlow.
*** How to emulate with OpenFlow (avoiding duplicates).
** Spanning tree.
*** Limitations for nonstandard setups.
** CFM
*** Tradeoffs.
*** Caveats.
** Policing.
** QoS.

** How to simulate NORMAL with rules that don't use it.

* Control plane programming techniques.
** Resubmit.
** Registers.
*** NAND gate.
** Local controller.

* Proactive control plane programming.
** Resubmit.
*** Firewall with ingress and egress rules.
**** Handling IP fragments.
** Learning.
*** A MAC-learning switch.
**** Reading and flushing the MAC learning table.
**** Monitoring changes to the MAC learning table.
*** Stateful firewall.
** VXLAN control plane.
** Routing.
** Spoof prevention.
*** IPv6.
** PVLAN.

* Reactive control plane programming?
** In-band control as example?

* In-band control.
** How it works.
** Limitations.
** Rolling your own.

* Optimization.
** Separate tables.
*** Tables with a single type of flow (see learning).
** Minimizing types of flows.
** Minimizing lookups.
** Minimizing flow table changes.
*** Avoiding timeouts.
@end verbatim

@node Glossary
@unnumbered Glossary

@macro glentry{term}
@item \term\
@cindex \term\
@anchor{\term\}
@end macro

@table @b
@glentry{action}

@glentry{bridge}
@xref{switch}.

@glentry{flow table}

@glentry{network device}
A real or simulated Ethernet interface.  @samp{lo}, @samp{eth0}, and
@samp{wlan0} are common names for network devices under the Linux
kernel.

@glentry{match}

@glentry{switch}
An Ethernet switch, also called a ``bridge.''
@end table

@node Index
@unnumbered Index

@printindex cp

@bye