mir/ovs
2
0
Fork 0
mirror of https://github.com/openvswitch/ovs synced 2025-08-31 14:25:26 +00:00
Code Issues Releases Wiki Activity

doc: Convert docs to Markdown language

Browse Source 
Converts the majority of docs over to use the Markdown language for
pretty printing on GitHub. It's a rough first convertion without
exploiting the full potential of Markdown at this point. Section
titles and indentation are fixed as needed. Minimal docs interlinking
is added.

Signed-off-by: Thomas Graf <tgraf@noironetworks.com>
Signed-off-by: Ben Pfaff <blp@nicira.com>
This commit is contained in:
Thomas Graf
2014-10-28 11:19:52 +01:00
committed by Ben Pfaff
parent 3aa40c8301
commit 542cc9bb8b
42 changed files with 1869 additions and 1795 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
CONTRIBUTING → CONTRIBUTING.md
View File

@@ -4,7 +4,7 @@ How to Submit Patches for Open vSwitch
Send changes to Open vSwitch as patches to dev@openvswitch.org.
One patch per email, please. More details are included below.
If you are using Git, then "git format-patch" takes care of most of
If you are using Git, then `git format-patch` takes care of most of
the mechanics described below for you.
Before You Start
@@ -16,7 +16,7 @@ In particular:
- A given patch should not break anything, even if later
patches fix the problems that it causes. The source tree
should still build and work after each patch is applied.
(This enables "git bisect" to work best.)
(This enables `git bisect` to work best.)
- A patch should make one logical change. Don't make
multiple, logically unconnected changes to disparate
@@ -28,7 +28,7 @@ In particular:
Testing is also important:
- A patch that adds or deletes files should be tested with
"make distcheck" before submission.
`make distcheck` before submission.
- A patch that modifies Linux kernel code should be at least
build-tested on various Linux kernel versions before
@@ -44,28 +44,28 @@ Testing is also important:
If you are using GitHub, then you may utilize the travis-ci.org CI build
system by linking your GitHub repository to it. This will run some of
the above tests automatically when you push changes to your repository.
See the "Continuous Integration with Travis-CI" in the INSTALL file for
details on how to set it up.
See the "Continuous Integration with Travis-CI" in the [INSTALL](INSTALL.md)
file for details on how to set it up.
Email Subject
-------------
The subject line of your email should be in the following format:
[PATCH <n>/<m>] <area>: <summary>
`[PATCH <n>/<m>] <area>: <summary>`
- [PATCH <n>/<m>] indicates that this is the nth of a series
- `[PATCH <n>/<m>]` indicates that this is the nth of a series
of m patches. It helps reviewers to read patches in the
correct order. You may omit this prefix if you are sending
only one patch.
- <area>: indicates the area of the Open vSwitch to which the
- `<area>:` indicates the area of the Open vSwitch to which the
change applies (often the name of a source file or a
directory). You may omit it if the change crosses multiple
distinct pieces of code.
- <summary> briefly describes the change.
- `<summary>` briefly describes the change.
The subject, minus the [PATCH <n>/<m>] prefix, becomes the first line
The subject, minus the `[PATCH <n>/<m>]` prefix, becomes the first line
of the commit's change log message.
Description
@@ -100,7 +100,7 @@ datapath names.)'.
If you, the person sending the patch, did not write the patch
yourself, then the very first line of the body should take the form
"From: <author name> <author email>", followed by a blank line. This
`From: <author name> <author email>`, followed by a blank line. This
will automatically cause the named author to be credited with
authorship in the repository.
@@ -254,7 +254,7 @@ Comments
If you want to include any comments in your email that should not be
part of the commit's change log message, put them after the
description, separated by a line that contains just "---". It may be
description, separated by a line that contains just `---`. It may be
helpful to include a diffstat here for changes that touch multiple
files.
@@ -264,9 +264,9 @@ Patch
The patch should be in the body of the email following the description,
separated by a blank line.
Patches should be in "diff -up" format. We recommend that you use Git
to produce your patches, in which case you should use the -M -C
options to "git diff" (or other Git tools) if your patch renames or
Patches should be in `diff -up` format. We recommend that you use Git
to produce your patches, in which case you should use the `-M -C`
options to `git diff` (or other Git tools) if your patch renames or
copies files. Quilt (http://savannah.nongnu.org/projects/quilt) might
be useful if you do not want to use Git.
@@ -278,12 +278,13 @@ If you cannot convince your email client not to mangle patches, then
sending the patch as an attachment is a second choice.
Please follow the style used in the code that you are modifying. The
CodingStyle file describes the coding style used in most of Open
vSwitch. Use Linux kernel coding style for Linux kernel code.
[CodingStyle](CodingStyle.md) file describes the coding style used in
most of Open vSwitch. Use Linux kernel coding style for Linux kernel code.
Example
-------
```
From fa29a1c2c17682879e79a21bb0cdd5bbe67fa7c0 Mon Sep 17 00:00:00 2001
From: Jesse Gross <jesse@nicira.com>
Date: Thu, 8 Dec 2011 13:17:24 -0800
@@ -313,4 +314,5 @@ index fdd952e..f6cb88e 100644
both_modules += brcompat
--
1.7.7.3
```

86
CodingStyle → CodingStyle.md
View File

@@ -1,5 +1,5 @@
Open vSwitch Coding Style
=========================
Open vSwitch Coding Style
=========================
This file describes the coding style used in most C files in the Open
vSwitch distribution. However, Linux kernel code datapath directory
@@ -14,7 +14,7 @@ The following GNU indent options approximate this style:
-di1 -lp -il0 -hnl
BASICS
## BASICS
Limit lines to 79 characters.
@@ -26,35 +26,35 @@ pieces. A form feed should appear as the only character on a line.
Avoid trailing spaces on lines.
NAMING
## NAMING
Use names that explain the purpose of a function or object.
- Use names that explain the purpose of a function or object.
Use underscores to separate words in an identifier: multi_word_name.
- Use underscores to separate words in an identifier: multi_word_name.
Use lowercase for most names. Use uppercase for macros, macro
parameters, and members of enumerations.
- Use lowercase for most names. Use uppercase for macros, macro
parameters, and members of enumerations.
Give arrays names that are plural.
- Give arrays names that are plural.
Pick a unique name prefix (ending with an underscore) for each
module, and apply that prefix to all of that module's externally
visible names. Names of macro parameters, struct and union members,
and parameters in function prototypes are not considered externally
visible for this purpose.
- Pick a unique name prefix (ending with an underscore) for each
module, and apply that prefix to all of that module's externally
visible names. Names of macro parameters, struct and union members,
and parameters in function prototypes are not considered externally
visible for this purpose.
Do not use names that begin with _. If you need a name for
"internal use only", use __ as a suffix instead of a prefix.
- Do not use names that begin with _. If you need a name for
"internal use only", use __ as a suffix instead of a prefix.
Avoid negative names: "found" is a better name than "not_found".
- Avoid negative names: "found" is a better name than "not_found".
In names, a "size" is a count of bytes, a "length" is a count of
characters. A buffer has size, but a string has length. The length
of a string does not include the null terminator, but the size of the
buffer that contains the string does.
- In names, a "size" is a count of bytes, a "length" is a count of
characters. A buffer has size, but a string has length. The length
of a string does not include the null terminator, but the size of the
buffer that contains the string does.
COMMENTS
## COMMENTS
Comments should be written as full sentences that start with a
capital letter and end with a period. Put two spaces between
@@ -97,13 +97,13 @@ e.g.:
Use XXX or FIXME comments to mark code that needs work.
Don't use // comments.
Don't use `//` comments.
Don't comment out or #if 0 out code. Just remove it. The code that
was there will still be in version control history.
FUNCTIONS
## FUNCTIONS
Put the return type, function name, and the braces that surround the
function's code on separate lines, all starting in column 0.
@@ -152,6 +152,7 @@ parameters and their corresponding size parameters should be paired.
Example:
```
/* Stores the features supported by 'netdev' into each of '*current',
* '*advertised', '*supported', and '*peer' that are non-null. Each value
* is a bitmap of "enum ofp_port_features" bits, in host byte order.
@@ -164,6 +165,7 @@ parameters and their corresponding size parameters should be paired.
{
...
}
```
Functions that destroy an instance of a dynamically-allocated type
should accept and ignore a null pointer argument. Code that calls
@@ -177,7 +179,7 @@ compilers warnings about unused functions. (Functions defined in .h
usually should be marked inline.)
FUNCTION PROTOTYPES
## FUNCTION PROTOTYPES
Put the return type and function name on the same line in a function
prototype:
@@ -191,7 +193,7 @@ give useful information, e.g.:
int netdev_get_mtu(const struct netdev *, int *mtup);
STATEMENTS
## STATEMENTS
Indent each level of code with 4 spaces. Use BSD-style brace
placement:
@@ -263,19 +265,19 @@ details. (Some compilers also assume that the "if" branch is the more
common case, so this can be a real form of optimization as well.)
RETURN VALUES
## RETURN VALUES
For functions that return a success or failure indication, prefer
one of the following return value conventions:
* An "int" where 0 indicates success and a positive errno value
* An "int" where 0 indicates success and a positive errno value
indicates a reason for failure.
* A "bool" where true indicates success and false indicates
* A "bool" where true indicates success and false indicates
failure.
MACROS
## MACROS
Don't define an object-like macro if an enum can be used instead.
@@ -312,7 +314,7 @@ the name of each enum. For example:
};
THREAD SAFETY ANNOTATIONS
## THREAD SAFETY ANNOTATIONS
Use the macros in lib/compiler.h to annotate locking requirements.
For example:
@@ -327,7 +329,7 @@ For example:
(Thus we have OVS_REQUIRES(mutex) above, not OVS_REQUIRES(&mutex).)
SOURCE FILES
## SOURCE FILES
Each source file should state its license in a comment at the very
top, followed by a comment explaining the purpose of the code that is
@@ -339,24 +341,24 @@ quickly figure out where a given module fits into the larger system.
#include <config.h>
#include directives should appear in the following order:
`#include` directives should appear in the following order:
1. #include <config.h>
1. `#include <config.h>`
2. The module's own headers, if any. Including this before any
2. The module's own headers, if any. Including this before any
other header (besides <config.h>) ensures that the module's
header file is self-contained (see HEADER FILES) below.
3. Standard C library headers and other system headers, preferably
3. Standard C library headers and other system headers, preferably
in alphabetical order. (Occasionally one encounters a set of
system headers that must be included in a particular order, in
which case that order must take precedence.)
4. Open vSwitch headers, in alphabetical order. Use "", not <>,
4. Open vSwitch headers, in alphabetical order. Use "", not <>,
to specify Open vSwitch header names.
HEADER FILES
## HEADER FILES
Each header file should start with its license, as described under
SOURCE FILES above, followed by a "header guard" to make the header
@@ -384,7 +386,7 @@ the tag yourself. This reduces the number of header file
dependencies.
TYPES
## TYPES
Use typedefs sparingly. Code is clearer if the actual type is
visible at the point of declaration. Do not, in general, declare a
@@ -442,7 +444,7 @@ are convinced there is a size or speed benefit.
Write "int *x", not "int* x" and definitely not "int * x".
EXPRESSIONS
## EXPRESSIONS
Put one space on each side of infix binary and ternary operators:
@@ -519,13 +521,13 @@ or variable argument on the left and a constant argument on the
right, e.g. "x == 0", *not* "0 == x".
BLANK LINES
## BLANK LINES
Put one blank line between top-level definitions of functions and
global variables.
C DIALECT
## C DIALECT
Most C99 features are OK because they are widely implemented:

17
DESIGN → DESIGN.md
View File

@@ -1,5 +1,5 @@
Design Decisions In Open vSwitch
================================
Design Decisions In Open vSwitch
================================
This document describes design decisions that went into implementing
Open vSwitch. While we believe these to be reasonable decisions, it is
@@ -46,6 +46,7 @@ shows how this table is initialized by default when an OpenFlow
connection is made. An entry labeled "yes" means that the message is
sent, an entry labeled "---" means that the message is suppressed.
```
master/
message and reason code other slave
---------------------------------------- ------- -----
@@ -63,6 +64,7 @@ sent, an entry labeled "---" means that the message is suppressed.
OFPPR_ADD yes yes
OFPPR_DELETE yes yes
OFPPR_MODIFY yes yes
```
The NXT_SET_ASYNC_CONFIG message directly sets all of the values in
this table for the current connection. The
@@ -141,6 +143,7 @@ below the table.
OpenFlow 1.0
------------
```
MODIFY DELETE
ADD MODIFY STRICT DELETE STRICT
=== ====== ====== ====== ======
@@ -167,6 +170,7 @@ sends flow_removed message --- --- --- % %
the deleted flow or flows have the OFPFF_SEND_FLOW_REM flag set.
(Each controller can separately control whether it wants to
receive the generated messages.)
```
OpenFlow 1.1
------------
@@ -182,6 +186,7 @@ OpenFlow 1.1 makes these changes:
- When a flow_mod matches on the flow_cookie, "modify" and
"modify-strict" never insert a new flow.
```
MODIFY DELETE
ADD MODIFY STRICT DELETE STRICT
=== ====== ====== ====== ======
@@ -211,6 +216,7 @@ sends flow_removed message --- --- --- % %
(#) "modify" and "modify-strict" only add a new flow if the flow_mod
does not match on any bits of the flow cookie
```
OpenFlow 1.2
------------
@@ -224,6 +230,7 @@ OpenFlow 1.2 makes these changes:
"modify-strict" reset counters, whereas previously they never
reset counters (except when they inserted a new flow).
```
MODIFY DELETE
ADD MODIFY STRICT DELETE STRICT
=== ====== ====== ====== ======
@@ -250,6 +257,7 @@ sends flow_removed message --- --- --- % %
(&) "modify" and "modify-strict" reset counters if the
OFPFF_RESET_COUNTS flag is specified.
```
OpenFlow 1.3
------------
@@ -278,6 +286,7 @@ OFPT_PACKET_IN
The OpenFlow 1.1 specification for OFPT_PACKET_IN is confusing. The
definition in OF1.1 openflow.h is[*]:
```
/* Packet received on port (datapath -> controller). */
struct ofp_packet_in {
struct ofp_header header;
@@ -295,6 +304,7 @@ definition in OF1.1 openflow.h is[*]:
sizeof(struct ofp_packet_in) - 2. */
};
OFP_ASSERT(sizeof(struct ofp_packet_in) == 24);
```
The confusing part is the comment on the data[] member. This comment
is a leftover from OF1.0 openflow.h, in which the comment was correct:
@@ -508,6 +518,7 @@ receiving OFPFC_MODIFY and OFPFC_MODIFY_STRICT messages. A mask of 0
indicates either an explicit mask of zero or an implicit one by not
specifying the NXM_NX_COOKIE(_W) field.
```
Match Update Add on miss Add on miss
cookie cookie mask!=0 mask==0
====== ====== =========== ===========
@@ -517,7 +528,7 @@ OpenFlow 1.2 yes no no no
NXM yes yes* no yes
* Updates the flow's cookie unless the "cookie" field is UINT64_MAX.
```
Multiple Table Support
======================

230
FAQ → FAQ.md
View File

@@ -1,12 +1,12 @@
Open vSwitch <http://openvswitch.org>
Frequently Asked Questions
==========================
Open vSwitch <http://openvswitch.org>
General
-------
Q: What is Open vSwitch?
### Q: What is Open vSwitch?
A: Open vSwitch is a production quality open source software switch
designed to be used as a vswitch in virtualized server
@@ -24,7 +24,7 @@ A: Open vSwitch is a production quality open source software switch
Open vSwitch will be able to take advantage of on-NIC switching
chipsets as their functionality matures.
Q: What virtualization platforms can use Open vSwitch?
### Q: What virtualization platforms can use Open vSwitch?
A: Open vSwitch can currently run on any Linux-based virtualization
platform (kernel 2.6.32 and newer), including: KVM, VirtualBox, Xen,
@@ -34,7 +34,7 @@ A: Open vSwitch can currently run on any Linux-based virtualization
inquires about integrating Open vSwitch with other virtualization
platforms.
Q: How can I try Open vSwitch?
### Q: How can I try Open vSwitch?
A: The Open vSwitch source code can be built on a Linux system. You can
build and experiment with Open vSwitch on any Linux machine.
@@ -47,7 +47,7 @@ A: The Open vSwitch source code can be built on a Linux system. You can
integrated with a particular platform may not be the most recent Open
vSwitch release.
Q: Does Open vSwitch only work on Linux?
### Q: Does Open vSwitch only work on Linux?
A: No, Open vSwitch has been ported to a number of different operating
systems and hardware platforms. Most of the development work occurs
@@ -59,22 +59,20 @@ A: No, Open vSwitch has been ported to a number of different operating
Linux and will provide the highest performance. However, a userspace
datapath is available that should be very portable.
Q: What's involved with porting Open vSwitch to a new platform or
switching ASIC?
### Q: What's involved with porting Open vSwitch to a new platform or switching ASIC?
A: The PORTING document describes how one would go about porting Open
vSwitch to a new operating system or hardware platform.
A: The [PORTING](PORTING.md) document describes how one would go about
porting Open vSwitch to a new operating system or hardware platform.
Q: Why would I use Open vSwitch instead of the Linux bridge?
### Q: Why would I use Open vSwitch instead of the Linux bridge?
A: Open vSwitch is specially designed to make it easier to manage VM
network configuration and monitor state spread across many physical
hosts in dynamic virtualized environments. Please see WHY-OVS for a
more detailed description of how Open vSwitch relates to the Linux
Bridge.
hosts in dynamic virtualized environments. Please see
[WHY-OVS](WHY-OVS.md) for a more detailed description of how Open
vSwitch relates to the Linux Bridge.
Q: How is Open vSwitch related to distributed virtual switches like the
VMware vNetwork distributed switch or the Cisco Nexus 1000V?
### Q: How is Open vSwitch related to distributed virtual switches like the VMware vNetwork distributed switch or the Cisco Nexus 1000V?
A: Distributed vswitch applications (e.g., VMware vNetwork distributed
switch, Cisco Nexus 1000V) provide a centralized way to configure and
@@ -93,7 +91,7 @@ A: Distributed vswitch applications (e.g., VMware vNetwork distributed
extend to provide distributed vswitch capabilities that are closely
integrated with their virtualization management platform.
Q: Why doesn't Open vSwitch support distribution?
### Q: Why doesn't Open vSwitch support distribution?
A: Open vSwitch is intended to be a useful component for building
flexible network infrastructure. There are many different approaches
@@ -103,7 +101,7 @@ A: Open vSwitch is intended to be a useful component for building
support all as a primitive building block rather than choose a
particular point in the distributed design space.
Q: How can I contribute to the Open vSwitch Community?
### Q: How can I contribute to the Open vSwitch Community?
A: You can start by joining the mailing lists and helping to answer
questions. You can also suggest improvements to documentation. If
@@ -116,8 +114,7 @@ A: You can start by joining the mailing lists and helping to answer
Releases
--------
Q: What does it mean for an Open vSwitch release to be LTS (long-term
support)?
### Q: What does it mean for an Open vSwitch release to be LTS (long-term support)?
A: All official releases have been through a comprehensive testing
process and are suitable for production use. Planned releases will
@@ -127,7 +124,7 @@ A: All official releases have been through a comprehensive testing
supplanted by the next major release. The current LTS release is
1.9.x.
Q: What Linux kernel versions does each Open vSwitch release work with?
### Q: What Linux kernel versions does each Open vSwitch release work with?
A: The following table lists the Linux kernel versions against which the
given versions of the Open vSwitch kernel module will successfully
@@ -137,19 +134,19 @@ A: The following table lists the Linux kernel versions against which the
most notably true of Red Hat Enterprise Linux (RHEL) kernels, which
are extensively modified from upstream.
Open vSwitch Linux kernel
------------ -------------
1.4.x 2.6.18 to 3.2
1.5.x 2.6.18 to 3.2
1.6.x 2.6.18 to 3.2
1.7.x 2.6.18 to 3.3
1.8.x 2.6.18 to 3.4
1.9.x 2.6.18 to 3.8
1.10.x 2.6.18 to 3.8
1.11.x 2.6.18 to 3.8
2.0.x 2.6.32 to 3.10
2.1.x 2.6.32 to 3.11
2.3.x 2.6.32 to 3.14
| Open vSwitch | Linux kernel
|:------------:|:-------------:
| 1.4.x | 2.6.18 to 3.2
| 1.5.x | 2.6.18 to 3.2
| 1.6.x | 2.6.18 to 3.2
| 1.7.x | 2.6.18 to 3.3
| 1.8.x | 2.6.18 to 3.4
| 1.9.x | 2.6.18 to 3.8
| 1.10.x | 2.6.18 to 3.8
| 1.11.x | 2.6.18 to 3.8
| 2.0.x | 2.6.32 to 3.10
| 2.1.x | 2.6.32 to 3.11
| 2.3.x | 2.6.32 to 3.14
Open vSwitch userspace should also work with the Linux kernel module
built into Linux 3.3 and later.
@@ -158,7 +155,7 @@ A: The following table lists the Linux kernel versions against which the
It should build against almost any kernel, certainly against 2.6.32
and later.
Q: I get an error like this when I configure Open vSwitch:
### Q: I get an error like this when I configure Open vSwitch:
configure: error: Linux kernel in <dir> is version <x>, but
version newer than <y> is not supported (please refer to the
@@ -175,8 +172,7 @@ A: If there is a newer version of Open vSwitch, consider building that
compatible with all versions of the Open vSwitch kernel module, so
this will also work. See also the following question.
Q: What features are not available in the Open vSwitch kernel datapath
that ships as part of the upstream Linux kernel?
### Q: What features are not available in the Open vSwitch kernel datapath that ships as part of the upstream Linux kernel?
A: The kernel module in upstream Linux does not include support for
LISP. Work is in progress to add support for LISP to the upstream
@@ -190,19 +186,18 @@ A: The kernel module in upstream Linux does not include support for
Linux release or using the kernel module paired with the userspace
distribution.
Q: Why do tunnels not work when using a kernel module other than the
one packaged with Open vSwitch?
### Q: Why do tunnels not work when using a kernel module other than the one packaged with Open vSwitch?
A: Support for tunnels was added to the upstream Linux kernel module
after the rest of Open vSwitch. As a result, some kernels may contain
support for Open vSwitch but not tunnels. The minimum kernel version
that supports each tunnel protocol is:
Protocol Linux Kernel
-------- ------------
GRE 3.11
VXLAN 3.12
LISP <not upstream>
| Protocol | Linux Kernel
|:--------:|:-------------:
| GRE | 3.11
| VXLAN | 3.12
| LISP | <not upstream>
If you are using a version of the kernel that is older than the one
listed above, it is still possible to use that tunnel protocol. However,
@@ -211,19 +206,19 @@ A: Support for tunnels was added to the upstream Linux kernel module
persist after doing this, check to make sure that the module that is
loaded is the one you expect.
Q: What features are not available when using the userspace datapath?
### Q: What features are not available when using the userspace datapath?
A: Tunnel virtual ports are not supported, as described in the
previous answer. It is also not possible to use queue-related
actions. On Linux kernels before 2.6.39, maximum-sized VLAN packets
may not be transmitted.
Q: What Linux kernel versions does IPFIX flow monitoring work with?
### Q: What Linux kernel versions does IPFIX flow monitoring work with?
A: IPFIX flow monitoring requires the Linux kernel module from Open
vSwitch version 1.10.90 or later.
Q: Should userspace or kernel be upgraded first to minimize downtime?
### Q: Should userspace or kernel be upgraded first to minimize downtime?
In general, the Open vSwitch userspace should be used with the
kernel version included in the same release or with the version
@@ -231,7 +226,7 @@ Q: Should userspace or kernel be upgraded first to minimize downtime?
of Open vSwitch it is best to migrate userspace first to reduce
the possibility of incompatibilities.
Q: What happened to the bridge compatibility feature?
### Q: What happened to the bridge compatibility feature?
A: Bridge compatibility was a feature of Open vSwitch 1.9 and earlier.
When it was enabled, Open vSwitch imitated the interface of the
@@ -254,14 +249,13 @@ A: Bridge compatibility was a feature of Open vSwitch 1.9 and earlier.
Terminology
-----------
Q: I thought Open vSwitch was a virtual Ethernet switch, but the
documentation keeps talking about bridges. What's a bridge?
### Q: I thought Open vSwitch was a virtual Ethernet switch, but the documentation keeps talking about bridges. What's a bridge?
A: In networking, the terms "bridge" and "switch" are synonyms. Open
vSwitch implements an Ethernet switch, which means that it is also
an Ethernet bridge.
Q: What's a VLAN?
### Q: What's a VLAN?
A: See the "VLAN" section below.
@@ -269,7 +263,7 @@ A: See the "VLAN" section below.
Basic Configuration
-------------------
Q: How do I configure a port as an access port?
### Q: How do I configure a port as an access port?
A: Add "tag=VLAN" to your "ovs-vsctl add-port" command. For example,
the following commands configure br0 with eth0 as a trunk port (the
@@ -284,8 +278,7 @@ A: Add "tag=VLAN" to your "ovs-vsctl add-port" command. For example,
ovs-vsctl set port tap0 tag=9
Q: How do I configure a port as a SPAN port, that is, enable mirroring
of all traffic to that port?
### Q: How do I configure a port as a SPAN port, that is, enable mirroring of all traffic to that port?
A: The following commands configure br0 with eth0 and tap0 as trunk
ports. All traffic coming in or going out on eth0 or tap0 is also
@@ -303,7 +296,7 @@ A: The following commands configure br0 with eth0 and tap0 as trunk
ovs-vsctl clear bridge br0 mirrors
Q: Does Open vSwitch support configuring a port in promiscuous mode?
### Q: Does Open vSwitch support configuring a port in promiscuous mode?
A: Yes. How you configure it depends on what you mean by "promiscuous
mode":
@@ -337,8 +330,7 @@ A: Yes. How you configure it depends on what you mean by "promiscuous
SPAN, see "How do I configure a port as a SPAN port, that is,
enable mirroring of all traffic to that port?"
Q: How do I configure a VLAN as an RSPAN VLAN, that is, enable
mirroring of all traffic to that VLAN?
### Q: How do I configure a VLAN as an RSPAN VLAN, that is, enable mirroring of all traffic to that VLAN?
A: The following commands configure br0 with eth0 as a trunk port and
tap0 as an access port for VLAN 10. All traffic coming in or going
@@ -364,7 +356,7 @@ A: The following commands configure br0 with eth0 as a trunk port and
GRE tunnel has fewer caveats than mirroring to a VLAN and should
generally be preferred.
Q: Can I mirror more than one input VLAN to an RSPAN VLAN?
### Q: Can I mirror more than one input VLAN to an RSPAN VLAN?
A: Yes, but mirroring to a VLAN strips the original VLAN tag in favor
of the specified output-vlan. This loss of information may make
@@ -388,7 +380,7 @@ A: Yes, but mirroring to a VLAN strips the original VLAN tag in favor
GRE tunnel has fewer caveats than mirroring to a VLAN and should
generally be preferred.
Q: How do I configure mirroring of all traffic to a GRE tunnel?
### Q: How do I configure mirroring of all traffic to a GRE tunnel?
A: The following commands configure br0 with eth0 and tap0 as trunk
ports. All traffic coming in or going out on eth0 or tap0 is also
@@ -409,13 +401,13 @@ A: The following commands configure br0 with eth0 and tap0 as trunk
ovs-vsctl clear bridge br0 mirrors
ovs-vcstl del-port br0 gre0
Q: Does Open vSwitch support ERSPAN?
### Q: Does Open vSwitch support ERSPAN?
A: No. ERSPAN is an undocumented proprietary protocol. As an
alternative, Open vSwitch supports mirroring to a GRE tunnel (see
above).
Q: How do I connect two bridges?
### Q: How do I connect two bridges?
A: First, why do you want to do this? Two connected bridges are not
much different from a single bridge, so you might as well just have
@@ -452,8 +444,7 @@ A: First, why do you want to do this? Two connected bridges are not
ports will not work with the userspace datapath, only with the
kernel module.
Q: How do I configure a bridge without an OpenFlow local port?
(Local port in the sense of OFPP_LOCAL)
### Q: How do I configure a bridge without an OpenFlow local port? (Local port in the sense of OFPP_LOCAL)
A: Open vSwitch does not support such a configuration.
Bridges always have their local ports.
@@ -462,7 +453,7 @@ A: Open vSwitch does not support such a configuration.
Implementation Details
----------------------
Q: I hear OVS has a couple of kinds of flows. Can you tell me about them?
### Q: I hear OVS has a couple of kinds of flows. Can you tell me about them?
A: Open vSwitch uses different kinds of flows for different purposes:
@@ -494,33 +485,33 @@ A: Open vSwitch uses different kinds of flows for different purposes:
table. Open vSwitch manages the datapath flow table itself, so
users should not normally be concerned with it.
Q: Why are there so many different ways to dump flows?
### Q: Why are there so many different ways to dump flows?
A: Open vSwitch has two kinds of flows (see the previous question), so
it has commands with different purposes for dumping each kind of
flow:
- "ovs-ofctl dump-flows <br>" dumps OpenFlow flows, excluding
- `ovs-ofctl dump-flows <br>` dumps OpenFlow flows, excluding
hidden flows. This is the most commonly useful form of flow
dump. (Unlike the other commands, this should work with any
OpenFlow switch, not just Open vSwitch.)
- "ovs-appctl bridge/dump-flows <br>" dumps OpenFlow flows,
- `ovs-appctl bridge/dump-flows <br>` dumps OpenFlow flows,
including hidden flows. This is occasionally useful for
troubleshooting suspected issues with in-band control.
- "ovs-dpctl dump-flows [dp]" dumps the datapath flow table
- `ovs-dpctl dump-flows [dp]` dumps the datapath flow table
entries for a Linux kernel-based datapath. In Open vSwitch
1.10 and later, ovs-vswitchd merges multiple switches into a
single datapath, so it will show all the flows on all your
kernel-based switches. This command can occasionally be
useful for debugging.
- "ovs-appctl dpif/dump-flows <br>", new in Open vSwitch 1.10,
- `ovs-appctl dpif/dump-flows <br>`, new in Open vSwitch 1.10,
dumps datapath flows for only the specified bridge, regardless
of the type.
Q: How does multicast snooping works with VLANs?
### Q: How does multicast snooping works with VLANs?
A: Open vSwitch maintains snooping tables for each VLAN.
@@ -528,7 +519,7 @@ A: Open vSwitch maintains snooping tables for each VLAN.
Performance
-----------
Q: I just upgraded and I see a performance drop. Why?
### Q: I just upgraded and I see a performance drop. Why?
A: The OVS kernel datapath may have been updated to a newer version than
the OVS userspace components. Sometimes new versions of OVS kernel
@@ -549,7 +540,7 @@ A: The OVS kernel datapath may have been updated to a newer version than
Configuration Problems
----------------------
Q: I created a bridge and added my Ethernet port to it, using commands
### Q: I created a bridge and added my Ethernet port to it, using commands
like these:
ovs-vsctl add-br br0
@@ -594,8 +585,8 @@ A: A physical Ethernet device that is part of an Open vSwitch bridge
devices. It applies to all network devices except Open vSwitch
"internal" devices.
Q: I created a bridge and added a couple of Ethernet ports to it,
using commands like these:
### Q: I created a bridge and added a couple of Ethernet ports to it,
### using commands like these:
ovs-vsctl add-br br0
ovs-vsctl add-port br0 eth0
@@ -661,7 +652,7 @@ A: More than likely, you've looped your network. Probably, eth0 and
acting as a beta tester then another option might be your
best shot.
Q: I can't seem to use Open vSwitch in a wireless network.
### Q: I can't seem to use Open vSwitch in a wireless network.
A: Wireless base stations generally only allow packets with the source
MAC address of NIC that completed the initial handshake.
@@ -672,17 +663,17 @@ A: Wireless base stations generally only allow packets with the source
point, so the same problems will show up with the Linux bridge or
any other way to do bridging.
Q: I can't seem to add my PPP interface to an Open vSwitch bridge.
### Q: I can't seem to add my PPP interface to an Open vSwitch bridge.
A: PPP most commonly carries IP packets, but Open vSwitch works only
with Ethernet frames. The correct way to interface PPP to an
Ethernet network is usually to use routing instead of switching.
Q: Is there any documentation on the database tables and fields?
### Q: Is there any documentation on the database tables and fields?
A: Yes. ovs-vswitchd.conf.db(5) is a comprehensive reference.
Q: When I run ovs-dpctl I no longer see the bridges I created. Instead,
### Q: When I run ovs-dpctl I no longer see the bridges I created. Instead,
I only see a datapath called "ovs-system". How can I see datapath
information about a particular bridge?
@@ -690,7 +681,7 @@ A: In version 1.9.0, OVS switched to using a single datapath that is
shared by all bridges of that type. The "ovs-appctl dpif/*"
commands provide similar functionality that is scoped by the bridge.
Q: I created a GRE port using ovs-vsctl so why can't I send traffic or
### Q: I created a GRE port using ovs-vsctl so why can't I send traffic or
see the port in the datapath?
A: On Linux kernels before 3.11, the OVS GRE module and Linux GRE module
@@ -698,10 +689,10 @@ A: On Linux kernels before 3.11, the OVS GRE module and Linux GRE module
Linux GRE module is already loaded and blocking OVS (to confirm, check
dmesg for errors regarding GRE registration). To fix this, unload all
GRE modules that appear in lsmod as well as the OVS kernel module. You
can then reload the OVS module following the directions in INSTALL,
which will ensure that dependencies are satisfied.
can then reload the OVS module following the directions in
[INSTALL](INSTALL.md), which will ensure that dependencies are satisfied.
Q: Open vSwitch does not seem to obey my packet filter rules.
### Q: Open vSwitch does not seem to obey my packet filter rules.
A: It depends on mechanisms and configurations you want to use.
@@ -731,7 +722,7 @@ A: It depends on mechanisms and configurations you want to use.
you want to use ebtables rules.) On NetBSD, you might want to
consider using the bridge(4) with BRIDGE_IPF option.
Q: It seems that Open vSwitch does nothing when I removed a port and
### Q: It seems that Open vSwitch does nothing when I removed a port and
then immediately put it back. For example, consider that p1 is
a port of type=internal:
@@ -762,7 +753,7 @@ A: It's an expected behaviour.
Quality of Service (QoS)
------------------------
Q: How do I configure Quality of Service (QoS)?
### Q: How do I configure Quality of Service (QoS)?
A: Suppose that you want to set up bridge br0 connected to physical
Ethernet port eth0 (a 1 Gbps device) and virtual machine interfaces
@@ -824,7 +815,7 @@ A: Suppose that you want to set up bridge br0 connected to physical
--all option), then you will have to destroy QoS and Queue records
individually.
Q: I configured Quality of Service (QoS) in my OpenFlow network by
### Q: I configured Quality of Service (QoS) in my OpenFlow network by
adding records to the QoS and Queue table, but the results aren't
what I expect.
@@ -835,7 +826,7 @@ A: Did you install OpenFlow flows that use your queues? This is the
Refer to the previous question for an example.
Q: I'd like to take advantage of some QoS feature that Open vSwitch
### Q: I'd like to take advantage of some QoS feature that Open vSwitch
doesn't yet support. How do I do that?
A: Open vSwitch does not implement QoS itself. Instead, it can
@@ -848,7 +839,7 @@ A: Open vSwitch does not implement QoS itself. Instead, it can
Linux QoS doesn't support the feature you want, then first you have
to add that support to Linux.)
Q: I configured QoS, correctly, but my measurements show that it isn't
### Q: I configured QoS, correctly, but my measurements show that it isn't
working as well as I expect.
A: With the Linux kernel, the Open vSwitch implementation of QoS has
@@ -880,7 +871,7 @@ A: With the Linux kernel, the Open vSwitch implementation of QoS has
tc-htb(8), tc-hfsc(8)), web resources (e.g. http://lartc.org/), or
mailing lists (e.g. http://vger.kernel.org/vger-lists.html#netdev).
Q: Does Open vSwitch support OpenFlow meters?
### Q: Does Open vSwitch support OpenFlow meters?
A: Since version 2.0, Open vSwitch has OpenFlow protocol support for
OpenFlow meters. There is no implementation of meters in the Open
@@ -891,7 +882,7 @@ A: Since version 2.0, Open vSwitch has OpenFlow protocol support for
VLANs
-----
Q: What's a VLAN?
### Q: What's a VLAN?
A: At the simplest level, a VLAN (short for "virtual LAN") is a way to
partition a single switch into multiple switches. Suppose, for
@@ -945,7 +936,7 @@ A: At the simplest level, a VLAN (short for "virtual LAN") is a way to
numbers. (That said, VLAN 0 is usually synonymous with a packet
that has no VLAN header, and VLAN 4095 is reserved.)
Q: VLANs don't work.
### Q: VLANs don't work.
A: Many drivers in Linux kernels before version 3.3 had VLAN-related
bugs. If you are having problems with VLANs that you suspect to be
@@ -986,13 +977,13 @@ A: Many drivers in Linux kernels before version 3.3 had VLAN-related
utilities, ovs-test(8) is newer and more thorough, but
ovs-vlan-test(8) may be easier to use.
Q: VLANs still don't work. I've tested the driver so I know that it's OK.
### Q: VLANs still don't work. I've tested the driver so I know that it's OK.
A: Do you have VLANs enabled on the physical switch that OVS is
attached to? Make sure that the port is configured to trunk the
VLAN or VLANs that you are using with OVS.
Q: Outgoing VLAN-tagged traffic goes through OVS to my physical switch
### Q: Outgoing VLAN-tagged traffic goes through OVS to my physical switch
and to its destination host, but OVS seems to drop incoming return
traffic.
@@ -1019,7 +1010,7 @@ A: It's possible that you have the VLAN configured on your physical
equally well. Refer to the documentation for the Port table
in ovs-vswitchd.conf.db(5) for more information.
Q: I added a pair of VMs on different VLANs, like this:
### Q: I added a pair of VMs on different VLANs, like this:
ovs-vsctl add-br br0
ovs-vsctl add-port br0 eth0
@@ -1038,7 +1029,7 @@ A: It is to be expected that the VMs can't access each other. VLANs
the machines you are trying to access are not on VLAN 9 (or 10) and
that the Internet is not available on VLAN 9 (or 10).
Q: I added a pair of VMs on the same VLAN, like this:
### Q: I added a pair of VMs on the same VLAN, like this:
ovs-vsctl add-br br0
ovs-vsctl add-port br0 eth0
@@ -1053,7 +1044,7 @@ A: It seems likely that the machines you are trying to access in the
available on VLAN 9. Also, ensure VLAN 9 is set up as an allowed
trunk VLAN on the upstream switch port to which eth0 is connected.
Q: Can I configure an IP address on a VLAN?
### Q: Can I configure an IP address on a VLAN?
A: Yes. Use an "internal port" configured as an access port. For
example, the following configures IP address 192.168.0.7 on VLAN 9.
@@ -1069,7 +1060,7 @@ A: Yes. Use an "internal port" configured as an access port. For
See also the following question.
Q: I configured one IP address on VLAN 0 and another on VLAN 9, like
### Q: I configured one IP address on VLAN 0 and another on VLAN 9, like
this:
ovs-vsctl add-br br0
@@ -1111,7 +1102,7 @@ A: RFC 1122 section 3.3.4.2 "Multihoming Requirements" describes two
BSD uses the strong ES model.
Q: My OpenFlow controller doesn't see the VLANs that I expect.
### Q: My OpenFlow controller doesn't see the VLANs that I expect.
A: The configuration for VLANs in the Open vSwitch database (e.g. via
ovs-vsctl) only affects traffic that goes through Open vSwitch's
@@ -1137,7 +1128,7 @@ A: The configuration for VLANs in the Open vSwitch database (e.g. via
needs to send it out on an access port, then the flow can
strip the VLAN tag with the "strip_vlan" action.
Q: I configured ports on a bridge as access ports with different VLAN
### Q: I configured ports on a bridge as access ports with different VLAN
tags, like this:
ovs-vsctl add-br br0
@@ -1155,7 +1146,7 @@ A: Do you have a controller configured on br0 (as the commands above
OpenFlow controller doesn't see the VLANs that I expect," and you
can refer to the answer there for more information.
Q: How MAC learning works with VLANs?
### Q: How MAC learning works with VLANs?
A: Open vSwitch implements Independent VLAN Learning (IVL) for
OFPP_NORMAL action. I.e. it logically has separate learning tables
@@ -1165,7 +1156,7 @@ A: Open vSwitch implements Independent VLAN Learning (IVL) for
VXLANs
-----
Q: What's a VXLAN?
### Q: What's a VXLAN?
A: VXLAN stands for Virtual eXtensible Local Area Network, and is a means
to solve the scaling challenges of VLAN networks in a multi-tenant
@@ -1175,7 +1166,7 @@ A: VXLAN stands for Virtual eXtensible Local Area Network, and is a means
http://tools.ietf.org/html/draft-mahalingam-dutt-dcops-vxlan-03
Q: How much of the VXLAN protocol does Open vSwitch currently support?
### Q: How much of the VXLAN protocol does Open vSwitch currently support?
A: Open vSwitch currently supports the framing format for packets on the
wire. There is currently no support for the multicast aspects of VXLAN.
@@ -1183,7 +1174,7 @@ A: Open vSwitch currently supports the framing format for packets on the
pre-provision MAC to IP address mappings either manually or from a
controller.
Q: What destination UDP port does the VXLAN implementation in Open vSwitch
### Q: What destination UDP port does the VXLAN implementation in Open vSwitch
use?
A: By default, Open vSwitch will use the assigned IANA port for VXLAN, which
@@ -1200,13 +1191,13 @@ A: By default, Open vSwitch will use the assigned IANA port for VXLAN, which
Using OpenFlow (Manually or Via Controller)
-------------------------------------------
Q: What versions of OpenFlow does Open vSwitch support?
### Q: What versions of OpenFlow does Open vSwitch support?
A: The following table lists the versions of OpenFlow supported by
each version of Open vSwitch:
Open vSwitch OF1.0 OF1.1 OF1.2 OF1.3 OF1.4 OF1.5
=============== ===== ===== ===== ===== ===== =====
###============ ===== ===== ===== ===== ===== =====
1.9 and earlier yes --- --- --- --- ---
1.10 yes --- [*] [*] --- ---
1.11 yes --- [*] [*] --- ---
@@ -1252,7 +1243,7 @@ A: The following table lists the versions of OpenFlow supported by
by default. Also, the OpenFlow 1.5 specification is still under
development and thus subject to change.
Q: Does Open vSwitch support MPLS?
### Q: Does Open vSwitch support MPLS?
A: Before version 1.11, Open vSwitch did not support MPLS. That is,
these versions can match on MPLS Ethernet types, but they cannot
@@ -1275,7 +1266,7 @@ A: Before version 1.11, Open vSwitch did not support MPLS. That is,
Open vSwitch version 2.4 will have kernel support for MPLS,
yielding improved performance.
Q: I'm getting "error type 45250 code 0". What's that?
### Q: I'm getting "error type 45250 code 0". What's that?
A: This is a Open vSwitch extension to OpenFlow error codes. Open
vSwitch uses this extension when it must report an error to an
@@ -1329,7 +1320,7 @@ A: By default, Open vSwitch assumes that OpenFlow controllers are
ovs-vsctl set controller br0 connection-mode=out-of-band
Q: I configured all my controllers for out-of-band control mode but
### Q: I configured all my controllers for out-of-band control mode but
"ovs-appctl bridge/dump-flows" still shows some hidden flows.
A: You probably have a remote manager configured (e.g. with "ovs-vsctl
@@ -1343,11 +1334,11 @@ A: You probably have a remote manager configured (e.g. with "ovs-vsctl
if all the bridge's controllers were configured for out-of-band
control.
Q: My OpenFlow controller doesn't see the VLANs that I expect.
### Q: My OpenFlow controller doesn't see the VLANs that I expect.
A: See answer under "VLANs", above.
Q: I ran "ovs-ofctl add-flow br0 nw_dst=192.168.0.1,actions=drop"
### Q: I ran "ovs-ofctl add-flow br0 nw_dst=192.168.0.1,actions=drop"
but I got a funny message like this:
ofp_util|INFO|normalization changed ofp_match, details:
@@ -1378,7 +1369,7 @@ A: The term "normalization" in the log message means that a flow
TCP source port 1234, write "tcp,tp_src=1234", or to match UDP
source port 1234, write "udp,tp_src=1234".
Q: How can I figure out the OpenFlow port number for a given port?
### Q: How can I figure out the OpenFlow port number for a given port?
A: The OFPT_FEATURES_REQUEST message requests an OpenFlow switch to
respond with an OFPT_FEATURES_REPLY that, among other information,
@@ -1406,14 +1397,14 @@ A: The OFPT_FEATURES_REQUEST message requests an OpenFlow switch to
normally an intermittent condition (unless ovs-vswitchd is not
running).
Q: I added some flows with my controller or with ovs-ofctl, but when I
### Q: I added some flows with my controller or with ovs-ofctl, but when I
run "ovs-dpctl dump-flows" I don't see them.
A: ovs-dpctl queries a kernel datapath, not an OpenFlow switch. It
won't display the information that you want. You want to use
"ovs-ofctl dump-flows" instead.
Q: It looks like each of the interfaces in my bonded port shows up
### Q: It looks like each of the interfaces in my bonded port shows up
as an individual OpenFlow port. Is that right?
A: Yes, Open vSwitch makes individual bond interfaces visible as
@@ -1431,7 +1422,7 @@ A: Yes, Open vSwitch makes individual bond interfaces visible as
implementation of such a feature, please bring it up on the Open
vSwitch development mailing list at dev@openvswitch.org.
Q: I have a sophisticated network setup involving Open vSwitch, VMs or
### Q: I have a sophisticated network setup involving Open vSwitch, VMs or
multiple hosts, and other components. The behavior isn't what I
expect. Help!
@@ -1513,7 +1504,7 @@ A: To debug network behavior problems, trace the path of a packet,
problem. If not, then follow the ARP reply back to the origin, in
reverse.
Q: How do I make a flow drop packets?
### Q: How do I make a flow drop packets?
A: To drop a packet is to receive it without forwarding it. OpenFlow
explicitly specifies forwarding actions. Thus, a flow with an
@@ -1534,7 +1525,7 @@ A: To drop a packet is to receive it without forwarding it. OpenFlow
"drop" is not an action, either in OpenFlow or Open vSwitch.
Rather, it is only a way to say that there are no actions.
Q: I added a flow to send packets out the ingress port, like this:
### Q: I added a flow to send packets out the ingress port, like this:
ovs-ofctl add-flow br0 in_port=2,actions=2
@@ -1584,7 +1575,7 @@ A: Yes, OpenFlow requires a switch to ignore attempts to send a packet
2,3,4,5,6,\
pop:NXM_OF_IN_PORT[]
Q: My bridge br0 has host 192.168.0.1 on port 1 and host 192.168.0.2
### Q: My bridge br0 has host 192.168.0.1 on port 1 and host 192.168.0.2
on port 2. I set up flows to forward only traffic destined to the
other host and drop other traffic, like this:
@@ -1618,7 +1609,7 @@ A: These flows drop the ARP packets that IP hosts use to establish IP
priority=5,in_port=1,dl_dst=01:00:00:00:00:00/01:00:00:00:00:00,actions=2
priority=5,in_port=2,dl_dst=01:00:00:00:00:00/01:00:00:00:00:00,actions=1
Q: My bridge disconnects from my controller on add-port/del-port.
### Q: My bridge disconnects from my controller on add-port/del-port.
A: Reconfiguring your bridge can change your bridge's datapath-id because
Open vSwitch generates datapath-id from the MAC address of one of its ports.
@@ -1633,13 +1624,14 @@ A: Reconfiguring your bridge can change your bridge's datapath-id because
Development
-----------
Q: How do I implement a new OpenFlow message?
### Q: How do I implement a new OpenFlow message?
A: Add your new message to "enum ofpraw" and "enum ofptype" in
lib/ofp-msgs.h, following the existing pattern. Then recompile and
fix all of the new warnings, implementing new functionality for the
new message as needed. (If you configure with --enable-Werror, as
described in INSTALL, then it is impossible to miss any warnings.)
described in [INSTALL](INSTALL.md), then it is impossible to miss
any warnings.)
If you need to add an OpenFlow vendor extension message for a
vendor that doesn't yet have any extension messages, then you will

252
INSTALL.DPDK
View File

@@ -1,252 +0,0 @@
Using Open vSwitch with DPDK
============================
Open vSwitch can use Intel(R) DPDK lib to operate entirely in
userspace. This file explains how to install and use Open vSwitch in
such a mode.
The DPDK support of Open vSwitch is considered experimental.
It has not been thoroughly tested.
This version of Open vSwitch should be built manually with "configure"
and "make".
OVS needs a system with 1GB hugepages support.
Building and Installing:
------------------------
Required DPDK 1.7
DPDK:
Set dir i.g.: export DPDK_DIR=/usr/src/dpdk-1.7.1
cd $DPDK_DIR
update config/common_linuxapp so that dpdk generate single lib file.
(modification also required for IVSHMEM build)
CONFIG_RTE_BUILD_COMBINE_LIBS=y
For default install without IVSHMEM:
make install T=x86_64-native-linuxapp-gcc
To include IVSHMEM (shared memory):
make install T=x86_64-ivshmem-linuxapp-gcc
For details refer to http://dpdk.org/
Linux kernel:
Refer to intel-dpdk-getting-started-guide.pdf for understanding
DPDK kernel requirement.
OVS:
Non IVSHMEM:
export DPDK_BUILD=$DPDK_DIR/x86_64-native-linuxapp-gcc/
IVSHMEM:
export DPDK_BUILD=$DPDK_DIR/x86_64-ivshmem-linuxapp-gcc/
cd $(OVS_DIR)/openvswitch
./boot.sh
./configure --with-dpdk=$DPDK_BUILD
make
To have better performance one can enable aggressive compiler optimizations and
use the special instructions(popcnt, crc32) that may not be available on all
machines. Instead of typing 'make', type:
make CFLAGS='-O3 -march=native'
Refer to INSTALL.userspace for general requirements of building
userspace OVS.
Using the DPDK with ovs-vswitchd:
---------------------------------
Setup system boot:
kernel bootline, add: default_hugepagesz=1GB hugepagesz=1G hugepages=1
First setup DPDK devices:
- insert uio.ko
e.g. modprobe uio
- insert igb_uio.ko
e.g. insmod $DPDK_BUILD/kmod/igb_uio.ko
- Bind network device to igb_uio.
e.g. $DPDK_DIR/tools/dpdk_nic_bind.py --bind=igb_uio eth1
Prepare system:
- mount hugetlbfs
e.g. mount -t hugetlbfs -o pagesize=1G none /dev/hugepages
Ref to http://www.dpdk.org/doc/quick-start for verifying DPDK setup.
Start ovsdb-server as discussed in INSTALL doc:
Summary e.g.:
First time only db creation (or clearing):
mkdir -p /usr/local/etc/openvswitch
mkdir -p /usr/local/var/run/openvswitch
rm /usr/local/etc/openvswitch/conf.db
cd $OVS_DIR
./ovsdb/ovsdb-tool create /usr/local/etc/openvswitch/conf.db \
./vswitchd/vswitch.ovsschema
start ovsdb-server
cd $OVS_DIR
./ovsdb/ovsdb-server --remote=punix:/usr/local/var/run/openvswitch/db.sock \
--remote=db:Open_vSwitch,Open_vSwitch,manager_options \
--private-key=db:Open_vSwitch,SSL,private_key \
--certificate=Open_vSwitch,SSL,certificate \
--bootstrap-ca-cert=db:Open_vSwitch,SSL,ca_cert --pidfile --detach
First time after db creation, initialize:
cd $OVS_DIR
./utilities/ovs-vsctl --no-wait init
Start vswitchd:
DPDK configuration arguments can be passed to vswitchd via `--dpdk`
argument. This needs to be first argument passed to vswitchd process.
dpdk arg -c is ignored by ovs-dpdk, but it is a required parameter
for dpdk initialization.
e.g.
export DB_SOCK=/usr/local/var/run/openvswitch/db.sock
./vswitchd/ovs-vswitchd --dpdk -c 0x1 -n 4 -- unix:$DB_SOCK --pidfile --detach
If allocated more than one GB hugepage (as for IVSHMEM), set amount and use NUMA
node 0 memory:
./vswitchd/ovs-vswitchd --dpdk -c 0x1 -n 4 --socket-mem 1024,0 \
-- unix:$DB_SOCK --pidfile --detach
To use ovs-vswitchd with DPDK, create a bridge with datapath_type
"netdev" in the configuration database. For example:
ovs-vsctl add-br br0 -- set bridge br0 datapath_type=netdev
Now you can add dpdk devices. OVS expect DPDK device name start with dpdk
and end with portid. vswitchd should print (in the log file) the number of dpdk
devices found.
ovs-vsctl add-port br0 dpdk0 -- set Interface dpdk0 type=dpdk
ovs-vsctl add-port br0 dpdk1 -- set Interface dpdk1 type=dpdk
Once first DPDK port is added to vswitchd, it creates a Polling thread and
polls dpdk device in continuous loop. Therefore CPU utilization
for that thread is always 100%.
Test flow script across NICs (assuming ovs in /usr/src/ovs):
Execute script:
############################# Script:
#! /bin/sh
# Move to command directory
cd /usr/src/ovs/utilities/
# Clear current flows
./ovs-ofctl del-flows br0
# Add flows between port 1 (dpdk0) to port 2 (dpdk1)
./ovs-ofctl add-flow br0 in_port=1,action=output:2
./ovs-ofctl add-flow br0 in_port=2,action=output:1
######################################
With pmd multi-threading support, OVS creates one pmd thread for each
numa node as default. The pmd thread handles the I/O of all DPDK
interfaces on the same numa node. The following two commands can be used
to configure the multi-threading behavior.
ovs-vsctl set Open_vSwitch . other_config:pmd-cpu-mask=<hex string>
The command above asks for a CPU mask for setting the affinity of pmd threads.
A set bit in the mask means a pmd thread is created and pinned to the
corresponding CPU core. For more information, please refer to
`man ovs-vswitchd.conf.db`
ovs-vsctl set Open_vSwitch . other_config:n-dpdk-rxqs=<integer>
The command above sets the number of rx queues of each DPDK interface. The
rx queues are assigned to pmd threads on the same numa node in round-robin
fashion. For more information, please refer to `man ovs-vswitchd.conf.db`
Ideally for maximum throughput, the pmd thread should not be scheduled out
which temporarily halts its execution. The following affinitization methods
can help.
Lets pick core 4,6,8,10 for pmd threads to run on. Also assume a dual 8 core
sandy bridge system with hyperthreading enabled where CPU1 has cores 0,...,7
and 16,...,23 & CPU2 cores 8,...,15 & 24,...,31. (A different cpu
configuration could have different core mask requirements).
To kernel bootline add core isolation list for cores and associated hype cores
(e.g. isolcpus=4,20,6,22,8,24,10,26,). Reboot system for isolation to take
effect, restart everything.
Configure pmd threads on core 4,6,8,10 using 'pmd-cpu-mask':
ovs-vsctl set Open_vSwitch . other_config:pmd-cpu-mask=00000550
You should be able to check that pmd threads are pinned to the correct cores
via:
top -p `pidof ovs-vswitchd` -H -d1
Note, the pmd threads on a numa node are only created if there is at least
one DPDK interface from the numa node that has been added to OVS.
Note, core 0 is always reserved from non-pmd threads and should never be set
in the cpu mask.
DPDK Rings :
------------
Following the steps above to create a bridge, you can now add dpdk rings
as a port to the vswitch. OVS will expect the DPDK ring device name to
start with dpdkr and end with a portid.
ovs-vsctl add-port br0 dpdkr0 -- set Interface dpdkr0 type=dpdkr
DPDK rings client test application
Included in the test directory is a sample DPDK application for testing
the rings. This is from the base dpdk directory and modified to work
with the ring naming used within ovs.
location tests/ovs_client
To run the client :
cd /usr/src/ovs/tests/
ovsclient -c 1 -n 4 --proc-type=secondary -- -n "port id you gave dpdkr"
In the case of the dpdkr example above the "port id you gave dpdkr" is 0.
It is essential to have --proc-type=secondary
The application simply receives an mbuf on the receive queue of the
ethernet ring and then places that same mbuf on the transmit ring of
the ethernet ring. It is a trivial loopback application.
DPDK rings in VM (IVSHMEM shared memory communications)
-------------------------------------------------------
In addition to executing the client in the host, you can execute it within
a guest VM. To do so you will need a patched qemu. You can download the
patch and getting started guide at :
https://01.org/packet-processing/downloads
A general rule of thumb for better performance is that the client
application should not be assigned the same dpdk core mask "-c" as
the vswitchd.
Restrictions:
-------------
- This Support is for Physical NIC. I have tested with Intel NIC only.
- Work with 1500 MTU, needs few changes in DPDK lib to fix this issue.
- Currently DPDK port does not make use any offload functionality.
ivshmem:
- The shared memory is currently restricted to the use of a 1GB
huge pages.
- All huge pages are shared amongst the host, clients, virtual
machines etc.
Bug Reporting:
--------------
Please report problems to bugs@openvswitch.org.

284
INSTALL.DPDK.md Normal file
View File

@@ -0,0 +1,284 @@
Using Open vSwitch with DPDK
============================
Open vSwitch can use Intel(R) DPDK lib to operate entirely in
userspace. This file explains how to install and use Open vSwitch in
such a mode.
The DPDK support of Open vSwitch is considered experimental.
It has not been thoroughly tested.
This version of Open vSwitch should be built manually with `configure`
and `make`.
OVS needs a system with 1GB hugepages support.
Building and Installing:
------------------------
Required DPDK 1.7
1. Configure build & install DPDK:
1. Set `$DPDK_DIR`
```
export DPDK_DIR=/usr/src/dpdk-1.7.1
cd $DPDK_DIR
```
2. Update `config/common_linuxapp` so that DPDK generate single lib file.
(modification also required for IVSHMEM build)
`CONFIG_RTE_BUILD_COMBINE_LIBS=y`
Then run `make install` to build and isntall the library.
For default install without IVSHMEM:
`make install T=x86_64-native-linuxapp-gcc`
To include IVSHMEM (shared memory):
`make install T=x86_64-ivshmem-linuxapp-gcc`
For further details refer to http://dpdk.org/
2. Configure & build the Linux kernel:
Refer to intel-dpdk-getting-started-guide.pdf for understanding
DPDK kernel requirement.
3. Configure & build OVS:
* Non IVSHMEM:
`export DPDK_BUILD=$DPDK_DIR/x86_64-native-linuxapp-gcc/`
* IVSHMEM:
`export DPDK_BUILD=$DPDK_DIR/x86_64-ivshmem-linuxapp-gcc/`
```
cd $(OVS_DIR)/openvswitch
./boot.sh
./configure --with-dpdk=$DPDK_BUILD
make
```
To have better performance one can enable aggressive compiler optimizations and
use the special instructions(popcnt, crc32) that may not be available on all
machines. Instead of typing `make`, type:
`make CFLAGS='-O3 -march=native'`
Refer to [INSTALL.userspace](INSTALL.userspace.md) for general requirements of
building userspace OVS.
Using the DPDK with ovs-vswitchd:
---------------------------------
1. Setup system boot
Add the following options to the kernel bootline:
`default_hugepagesz=1GB hugepagesz=1G hugepages=1`
2. Setup DPDK devices:
1. insert uio.ko: `modprobe uio`
2. insert igb_uio.ko: `insmod $DPDK_BUILD/kmod/igb_uio.ko`
3. Bind network device to igb_uio: `$DPDK_DIR/tools/dpdk_nic_bind.py --bind=igb_uio eth1`
3. Mount the hugetable filsystem
`mount -t hugetlbfs -o pagesize=1G none /dev/hugepages`
Ref to http://www.dpdk.org/doc/quick-start for verifying DPDK setup.
4. Start ovsdb-server as discussed in [INSTALL](INSTALL.md) doc:
1. First time only db creation (or clearing):
```
mkdir -p /usr/local/etc/openvswitch
mkdir -p /usr/local/var/run/openvswitch
rm /usr/local/etc/openvswitch/conf.db
cd $OVS_DIR
./ovsdb/ovsdb-tool create /usr/local/etc/openvswitch/conf.db \
./vswitchd/vswitch.ovsschema
```
2. start ovsdb-server
```
cd $OVS_DIR
./ovsdb/ovsdb-server --remote=punix:/usr/local/var/run/openvswitch/db.sock \
--remote=db:Open_vSwitch,Open_vSwitch,manager_options \
--private-key=db:Open_vSwitch,SSL,private_key \
--certificate=Open_vSwitch,SSL,certificate \
--bootstrap-ca-cert=db:Open_vSwitch,SSL,ca_cert --pidfile --detach
```
3. First time after db creation, initialize:
```
cd $OVS_DIR
./utilities/ovs-vsctl --no-wait init
```
5. Start vswitchd:
DPDK configuration arguments can be passed to vswitchd via `--dpdk`
argument. This needs to be first argument passed to vswitchd process.
dpdk arg -c is ignored by ovs-dpdk, but it is a required parameter
for dpdk initialization.
export DB_SOCK=/usr/local/var/run/openvswitch/db.sock
./vswitchd/ovs-vswitchd --dpdk -c 0x1 -n 4 -- unix:$DB_SOCK --pidfile --detach
If allocated more than one GB hugepage (as for IVSHMEM), set amount and use NUMA
node 0 memory:
./vswitchd/ovs-vswitchd --dpdk -c 0x1 -n 4 --socket-mem 1024,0 \
-- unix:$DB_SOCK --pidfile --detach
6. Add bridge & ports
To use ovs-vswitchd with DPDK, create a bridge with datapath_type
"netdev" in the configuration database. For example:
`ovs-vsctl add-br br0 -- set bridge br0 datapath_type=netdev`
Now you can add dpdk devices. OVS expect DPDK device name start with dpdk
and end with portid. vswitchd should print (in the log file) the number of dpdk
devices found.
ovs-vsctl add-port br0 dpdk0 -- set Interface dpdk0 type=dpdk
ovs-vsctl add-port br0 dpdk1 -- set Interface dpdk1 type=dpdk
Once first DPDK port is added to vswitchd, it creates a Polling thread and
polls dpdk device in continuous loop. Therefore CPU utilization
for that thread is always 100%.
7. Add test flows
Test flow script across NICs (assuming ovs in /usr/src/ovs):
Execute script:
```
#! /bin/sh
# Move to command directory
cd /usr/src/ovs/utilities/
# Clear current flows
./ovs-ofctl del-flows br0
# Add flows between port 1 (dpdk0) to port 2 (dpdk1)
./ovs-ofctl add-flow br0 in_port=1,action=output:2
./ovs-ofctl add-flow br0 in_port=2,action=output:1
```
8. Performance tuning
With pmd multi-threading support, OVS creates one pmd thread for each
numa node as default. The pmd thread handles the I/O of all DPDK
interfaces on the same numa node. The following two commands can be used
to configure the multi-threading behavior.
ovs-vsctl set Open_vSwitch . other_config:pmd-cpu-mask=<hex string>
The command above asks for a CPU mask for setting the affinity of pmd threads.
A set bit in the mask means a pmd thread is created and pinned to the
corresponding CPU core. For more information, please refer to
`man ovs-vswitchd.conf.db`
ovs-vsctl set Open_vSwitch . other_config:n-dpdk-rxqs=<integer>
The command above sets the number of rx queues of each DPDK interface. The
rx queues are assigned to pmd threads on the same numa node in round-robin
fashion. For more information, please refer to `man ovs-vswitchd.conf.db`
Ideally for maximum throughput, the pmd thread should not be scheduled out
which temporarily halts its execution. The following affinitization methods
can help.
Lets pick core 4,6,8,10 for pmd threads to run on. Also assume a dual 8 core
sandy bridge system with hyperthreading enabled where CPU1 has cores 0,...,7
and 16,...,23 & CPU2 cores 8,...,15 & 24,...,31. (A different cpu
configuration could have different core mask requirements).
To kernel bootline add core isolation list for cores and associated hype cores
(e.g. isolcpus=4,20,6,22,8,24,10,26,). Reboot system for isolation to take
effect, restart everything.
Configure pmd threads on core 4,6,8,10 using 'pmd-cpu-mask':
ovs-vsctl set Open_vSwitch . other_config:pmd-cpu-mask=00000550
You should be able to check that pmd threads are pinned to the correct cores
via:
top -p `pidof ovs-vswitchd` -H -d1
Note, the pmd threads on a numa node are only created if there is at least
one DPDK interface from the numa node that has been added to OVS.
Note, core 0 is always reserved from non-pmd threads and should never be set
in the cpu mask.
DPDK Rings :
------------
Following the steps above to create a bridge, you can now add dpdk rings
as a port to the vswitch. OVS will expect the DPDK ring device name to
start with dpdkr and end with a portid.
ovs-vsctl add-port br0 dpdkr0 -- set Interface dpdkr0 type=dpdkr
DPDK rings client test application
Included in the test directory is a sample DPDK application for testing
the rings. This is from the base dpdk directory and modified to work
with the ring naming used within ovs.
location tests/ovs_client
To run the client :
cd /usr/src/ovs/tests/
ovsclient -c 1 -n 4 --proc-type=secondary -- -n "port id you gave dpdkr"
In the case of the dpdkr example above the "port id you gave dpdkr" is 0.
It is essential to have --proc-type=secondary
The application simply receives an mbuf on the receive queue of the
ethernet ring and then places that same mbuf on the transmit ring of
the ethernet ring. It is a trivial loopback application.
DPDK rings in VM (IVSHMEM shared memory communications)
-------------------------------------------------------
In addition to executing the client in the host, you can execute it within
a guest VM. To do so you will need a patched qemu. You can download the
patch and getting started guide at :
https://01.org/packet-processing/downloads
A general rule of thumb for better performance is that the client
application should not be assigned the same dpdk core mask "-c" as
the vswitchd.
Restrictions:
-------------
- This Support is for Physical NIC. I have tested with Intel NIC only.
- Work with 1500 MTU, needs few changes in DPDK lib to fix this issue.
- Currently DPDK port does not make use any offload functionality.
ivshmem:
- The shared memory is currently restricted to the use of a 1GB
huge pages.
- All huge pages are shared amongst the host, clients, virtual
machines etc.
Bug Reporting:
--------------
Please report problems to bugs@openvswitch.org.

24
INSTALL.Debian → INSTALL.Debian.md
View File

@@ -1,9 +1,9 @@
How to Build Debian Packages for Open vSwitch
=============================================
How to Build Debian Packages for Open vSwitch
=============================================
This document describes how to build Debian packages for Open vSwitch.
To install Open vSwitch on Debian without building Debian packages,
see INSTALL instead.
see [INSTALL](INSTALL.md) instead.
These instructions should also work on Ubuntu and other Debian
derivative distributions.
@@ -28,33 +28,33 @@ Open vSwitch Git tree with these instructions.
You do not need to be the superuser to build the Debian packages.
1. Install the "build-essential" and "fakeroot" packages, e.g. with
"apt-get install build-essential fakeroot".
`apt-get install build-essential fakeroot`.
2. Obtain and unpack an Open vSwitch source distribution and "cd" into
2. Obtain and unpack an Open vSwitch source distribution and `cd` into
its top level directory.
3. Install the build dependencies listed under "Build-Depends:" near
the top of debian/control. You can install these any way you like,
e.g. with "apt-get install".
e.g. with `apt-get install`.
Check your work by running "dpkg-checkbuilddeps" in the top level of
Check your work by running `dpkg-checkbuilddeps` in the top level of
your ovs directory. If you've installed all the dependencies
properly, dpkg-checkbuilddeps will exit without printing anything.
If you forgot to install some dependencies, it will tell you which ones.
4. Run:
fakeroot debian/rules binary
`fakeroot debian/rules binary`
This will do a serial build that runs the unit tests. This will take
approximately 8 to 10 minutes. If you prefer, you can run a faster
parallel build, e.g.:
DEB_BUILD_OPTIONS='parallel=8' fakeroot debian/rules binary
`DEB_BUILD_OPTIONS='parallel=8' fakeroot debian/rules binary`
If you are in a big hurry, you can even skip the unit tests:
DEB_BUILD_OPTIONS='parallel=8 nocheck' fakeroot debian/rules binary
`DEB_BUILD_OPTIONS='parallel=8 nocheck' fakeroot debian/rules binary`
5. The generated .deb files will be in the parent directory of the
Open vSwitch source distribution.
@@ -66,9 +66,9 @@ Installing .deb Packages
These instructions apply to installing from Debian packages that you
built yourself, as described in the previous section, or from packages
provided by Debian or a Debian derivative distribution such as Ubuntu.
In the former case, use a command such as "dpkg -i" to install the
In the former case, use a command such as `dpkg -i` to install the
.deb files that you build, and in the latter case use a program such
as "apt-get" or "aptitude" to download and install the provided
as `apt-get` or `aptitude` to download and install the provided
packages.
You must be superuser to install Debian packages.

23
INSTALL.Docker → INSTALL.Docker.md
View File

@@ -1,10 +1,11 @@
How to Use Open vSwitch with Docker
====================================
How to Use Open vSwitch with Docker
====================================
This document describes how to use Open vSwitch with Docker 1.2.0 or
later. This document assumes that you followed INSTALL or installed
Open vSwitch from distribution packaging such as a .deb or .rpm.
Consult www.docker.com for instructions on how to install Docker.
later. This document assumes that you followed [INSTALL](INSTALL.md)
or installed Open vSwitch from distribution packaging such as a .deb
or .rpm. Consult www.docker.com for instructions on how to install
Docker.
Limitations
-----------
@@ -19,8 +20,10 @@ Setup
-----
* Create your container, e.g.:
```
% docker run -d ubuntu:14.04 /bin/sh -c \
"while true; do echo hello world; sleep 1; done"
```
The above command creates a container with one network interface 'eth0'
and attaches it to a Linux bridge called 'docker0'. 'eth0' by default
@@ -31,8 +34,10 @@ connected to the same bridge. If you prefer that no network interface be
created by default, you can start your container with
the option '--net=none', e,g.:
```
% docker run -d --net=none ubuntu:14.04 /bin/sh -c \
"while true; do echo hello world; sleep 1; done"
```
The above commands will return a container id. You will need to pass this
value to the utility 'ovs-docker' to create network interfaces attached to an
@@ -42,7 +47,7 @@ as $CONTAINER_ID in the next steps.
* Add a new network interface to the container and attach it to an Open vSwitch
bridge. e.g.:
% ovs-docker add-port br-int eth1 $CONTAINER_ID
`% ovs-docker add-port br-int eth1 $CONTAINER_ID`
The above command will create a network interface 'eth1' inside the container
and then attaches it to the Open vSwitch bridge 'br-int'. This is done by
@@ -51,16 +56,16 @@ container and the other end attaches to 'br-int'.
The script also lets one to add an IP address to the interface. e.g.:
% ovs-docker add-port br-int eth1 $CONTAINER_ID 192.168.1.1/24
`% ovs-docker add-port br-int eth1 $CONTAINER_ID 192.168.1.1/24`
* A previously added network interface can be deleted. e.g.:
% ovs-docker del-port br-int eth1 $CONTAINER_ID
`% ovs-docker del-port br-int eth1 $CONTAINER_ID`
All the previously added Open vSwitch interfaces inside a container can be
deleted. e.g.:
% ovs-docker del-ports br-int $CONTAINER_ID
`% ovs-docker del-ports br-int $CONTAINER_ID`
It is important that the same $CONTAINER_ID be passed to both add-port
and del-port[s] commands.

20
INSTALL.Fedora → INSTALL.Fedora.md
View File

@@ -1,9 +1,9 @@
How to Install Open vSwitch on Fedora Linux
===========================================
How to Install Open vSwitch on Fedora Linux
===========================================
This document describes how to build and install Open vSwitch on a Fedora
Linux host. If you want to install Open vSwitch on a generic Linux host,
see INSTALL.Linux instead.
see [INSTALL.Linux](INSTALL.Linux.md) instead.
We have tested these instructions with Fedora 16 and Fedora 17.
@@ -35,43 +35,49 @@ $HOME/rpmbuild/SOURCES.
Create a distribution tarball from the root of the Git tree by
running:
```
./boot.sh
./configure
make dist
```
2. Now you have a distribution tarball, named something like
openvswitch-x.y.z.tar.gz. Copy this file into the RPM sources
directory, e.g.:
cp openvswitch-x.y.z.tar.gz $HOME/rpmbuild/SOURCES
`cp openvswitch-x.y.z.tar.gz $HOME/rpmbuild/SOURCES`
3. Make another copy of the distribution tarball in a temporary
directory. Then unpack the tarball and "cd" into its root, e.g.:
```
tar xzf openvswitch-x.y.z.tar.gz
cd openvswitch-x.y.z
```
4. To build Open vSwitch userspace, run:
rpmbuild -bb rhel/openvswitch-fedora.spec
`rpmbuild -bb rhel/openvswitch-fedora.spec`
This produces one RPM: "openvswitch".
The above command automatically runs the Open vSwitch unit tests.
To disable the unit tests, run:
rpmbuild -bb --without check rhel/openvswitch-fedora.spec
`rpmbuild -bb --without check rhel/openvswitch-fedora.spec`
5. On Fedora 17, to build the Open vSwitch kernel module, run:
rpmbuild -bb rhel/openvswitch-kmod-fedora.spec
`rpmbuild -bb rhel/openvswitch-kmod-fedora.spec`
You might have to specify a kernel version and/or variants, e.g.:
```
rpmbuild -bb \
-D "kversion 2.6.32-131.6.1.el6.x86_64" \
-D "kflavors default debug kdump" \
rhel/openvswitch-kmod-rhel6.spec
```
This produces an "kmod-openvswitch" RPM for each kernel variant,
in this example: "kmod-openvswitch", "kmod-openvswitch-debug", and

27
INSTALL.KVM → INSTALL.KVM.md
View File

@@ -1,15 +1,16 @@
How to Use Open vSwitch with KVM
=================================
How to Use Open vSwitch with KVM
=================================
This document describes how to use Open vSwitch with the Kernel-based
Virtual Machine (KVM). This document assumes that you have read and
followed INSTALL to get Open vSwitch setup on your Linux system.
followed [INSTALL](INSTALL.md) to get Open vSwitch setup on your Linux
system.
Setup
-----
First, follow the setup instructions in INSTALL to get a working
Open vSwitch installation.
First, follow the setup instructions in [INSTALL](INSTALL.md) to get a
working Open vSwitch installation.
KVM uses tunctl to handle various bridging modes, which you can
install with the Debian/Ubuntu package uml-utilities.
@@ -26,24 +27,26 @@ Create the following two files and store them in known locations.
For example /etc/ovs-ifup and /etc/ovs-ifdown
/etc/ovs-ifup
--------------------------------------------------------------------
```
#!/bin/sh
switch='br0'
/sbin/ifconfig $1 0.0.0.0 up
ovs-vsctl add-port ${switch} $1
--------------------------------------------------------------------
```
/etc/ovs-ifdown
--------------------------------------------------------------------
```
#!/bin/sh
switch='br0'
/sbin/ifconfig $1 0.0.0.0 down
ovs-vsctl del-port ${switch} $1
--------------------------------------------------------------------
```
At the end of INSTALL, it describes basic usage of creating
At the end of [INSTALL](INSTALL.md), it describes basic usage of creating
bridges and ports. If you haven't already, create a bridge named
br0 with the following command:
@@ -59,8 +62,8 @@ Please refer to ovs-vsctl(8) for more details.
Next, we'll start a guest that will use our ifup and ifdown scripts.
% kvm -m 512 -net nic,macaddr=00:11:22:EE:EE:EE -net \
tap,script=/etc/ovs-ifup,downscript=/etc/ovs-ifdown -drive \
file=/path/to/disk-image,boot=on
tap,script=/etc/ovs-ifup,downscript=/etc/ovs-ifdown -drive \
file=/path/to/disk-image,boot=on
This will start the guest and associate a tap device with it. The
ovs-ifup script will add a port on the br0 bridge so that the

18
INSTALL.Libvirt → INSTALL.Libvirt.md
View File

@@ -1,5 +1,5 @@
How to Use Open vSwitch with Libvirt
====================================
How to Use Open vSwitch with Libvirt
====================================
This document describes how to use Open vSwitch with Libvirt 0.9.11 or
later. This document assumes that you followed INSTALL or installed
@@ -26,31 +26,31 @@ Once that is done, create a VM, if necessary, and edit its Domain XML file:
% virsh edit <vm>
Lookup in the Domain XML file the <interface> section. There should be one
Lookup in the Domain XML file the `<interface>` section. There should be one
such XML section for each interface the VM has.
...
```
<interface type='network'>
<mac address='52:54:00:71:b1:b6'/>
<source network='default'/>
<address type='pci' domain='0x0000' bus='0x00' slot='0x03' function='0x0'/>
</interface>
...
```
And change it to something like this:
...
```
<interface type='bridge'>
<mac address='52:54:00:71:b1:b6'/>
<source bridge='ovsbr'/>
<virtualport type='openvswitch'/>
<address type='pci' domain='0x0000' bus='0x00' slot='0x03' function='0x0'/>
</interface>
...
```
The interface type must be set to "bridge". The <source> XML element
The interface type must be set to "bridge". The `<source>` XML element
specifies to which bridge this interface will be attached to. The
<virtualport> element indicates that the bridge in <source> element is an
`<virtualport>` element indicates that the bridge in `<source>` element is an
Open vSwitch bridge.
Then (re)start the VM and verify if the guest's vnet interface is attached to

26
INSTALL.NetBSD → INSTALL.NetBSD.md
View File

@@ -1,30 +1,32 @@
How to Install Open vSwitch on NetBSD
=====================================
How to Install Open vSwitch on NetBSD
=====================================
On NetBSD, you might want to install requirements from pkgsrc.
In that case, you need at least the following packages.
automake
libtool-base
gmake
python27
py27-xml
pkg_alternatives
* automake
* libtool-base
* gmake
* python27
* py27-xml
* pkg_alternatives
Some components have additional requirements. (See INSTALL)
Some components have additional requirements. (See [INSTALL](INSTALL.md))
Assuming you are running NetBSD/amd64 6.1.2, you can download and
install pre-built binary packages as the following.
(You might get some warnings about minor version mismatch. Don't care.)
```
# PKG_PATH=http://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/amd64/6.1.2/All/
# export PKG_PATH
# pkg_add automake libtool-base gmake python27 py27-xml pkg_alternatives
```
NetBSD's /usr/bin/make is not GNU make. GNU make is installed as
/usr/pkg/bin/gmake by the above mentioned 'gmake' package.
NetBSD's `/usr/bin/make` is not GNU make. GNU make is installed as
`/usr/pkg/bin/gmake` by the above mentioned `gmake` package.
As all executables installed with pkgsrc are placed in /usr/pkg/bin/
As all executables installed with pkgsrc are placed in `/usr/pkg/bin/`
directory, it might be a good idea to add it to your PATH.
Open vSwitch on NetBSD is currently "userspace switch" implementation

38
INSTALL.RHEL → INSTALL.RHEL.md
View File

@@ -1,9 +1,9 @@
How to Install Open vSwitch on Red Hat Enterprise Linux
=======================================================
How to Install Open vSwitch on Red Hat Enterprise Linux
=======================================================
This document describes how to build and install Open vSwitch on a Red
Hat Enterprise Linux (RHEL) host. If you want to install Open vSwitch
on a generic Linux host, see INSTALL instead.
on a generic Linux host, see [INSTALL](INSTALL.md) instead.
We have tested these instructions with RHEL 5.6 and RHEL 6.0.
@@ -34,9 +34,11 @@ $HOME/rpmbuild/SOURCES.
1. Install build prerequisites:
```
yum install gcc make python-devel openssl-devel kernel-devel graphviz \
kernel-debug-devel autoconf automake rpm-build redhat-rpm-config \
libtool
```
2. If you are building from a distribution tarball, skip to step 3.
Otherwise, you must be building from an Open vSwitch Git tree.
@@ -49,9 +51,9 @@ $HOME/rpmbuild/SOURCES.
b. Create a distribution tarball on some other machine, by
running "./boot.sh; ./configure; make dist" in the Git tree.
You must run this on a machine that has the tools listed in
INSTALL as prerequisites for building from a Git tree.
Afterward, proceed with the rest of the instructions using the
distribution tarball.
[INSTALL](INSTALL.md) as prerequisites for building from a Git
tree. Afterward, proceed with the rest of the instructions using
the distribution tarball.
3. Some versions of the RHEL 6 kernel-devel package contain a broken
"build" symlink. If you are using such a version, you must fix
@@ -59,10 +61,12 @@ $HOME/rpmbuild/SOURCES.
To find out whether you are affected, run:
```
cd /lib/modules/<version>
ls -l build/
```
where <version> is the version number of the RHEL 6 kernel. (The
where `<version>` is the version number of the RHEL 6 kernel. (The
trailing slash in the final command is important. Be sure to include
it.) If the "ls" command produces a directory listing, your
kernel-devel package is OK. If it produces a "No such file or
@@ -70,12 +74,14 @@ $HOME/rpmbuild/SOURCES.
If your kernel-devel package is buggy, then you can fix it with:
```
cd /lib/modules/<version>
rm build
ln -s /usr/src/kernels/<target> build
```
where <target> is the name of an existing directory under
/usr/src/kernels, whose name should be similar to <version> but may
where `<target>` is the name of an existing directory under
/usr/src/kernels, whose name should be similar to `<version>` but may
contain some extra parts. Once you have done this, verify the fix with
the same procedure you used above to check for the problem.
@@ -83,32 +89,36 @@ $HOME/rpmbuild/SOURCES.
Otherwise, create a distribution tarball from the root of the Git
tree by running:
```
./boot.sh
./configure
make dist
```
5. Now you have a distribution tarball, named something like
openvswitch-x.y.z.tar.gz. Copy this file into the RPM sources
directory, e.g.:
cp openvswitch-x.y.z.tar.gz $HOME/rpmbuild/SOURCES
`cp openvswitch-x.y.z.tar.gz $HOME/rpmbuild/SOURCES`
6. Make another copy of the distribution tarball in a temporary
directory. Then unpack the tarball and "cd" into its root, e.g.:
```
tar xzf openvswitch-x.y.z.tar.gz
cd openvswitch-x.y.z
```
7. To build Open vSwitch userspace, run:
rpmbuild -bb rhel/openvswitch.spec
`rpmbuild -bb rhel/openvswitch.spec`
This produces two RPMs: "openvswitch" and "openvswitch-debuginfo".
The above command automatically runs the Open vSwitch unit tests.
To disable the unit tests, run:
rpmbuild -bb --without check rhel/openvswitch.spec
`rpmbuild -bb --without check rhel/openvswitch.spec`
If the build fails with "configure: error: source dir
/lib/modules/2.6.32-279.el6.x86_64/build doesn't exist" or similar,
@@ -118,14 +128,16 @@ $HOME/rpmbuild/SOURCES.
8. On RHEL 6, to build the Open vSwitch kernel module, copy
rhel/openvswitch-kmod.files into the RPM sources directory and run:
rpmbuild -bb rhel/openvswitch-kmod-rhel6.spec
`rpmbuild -bb rhel/openvswitch-kmod-rhel6.spec`
You might have to specify a kernel version and/or variants, e.g.:
```
rpmbuild -bb \
-D "kversion 2.6.32-131.6.1.el6.x86_64" \
-D "kflavors default debug kdump" \
rhel/openvswitch-kmod-rhel6.spec
```
This produces an "kmod-openvswitch" RPM for each kernel variant, in
this example: "kmod-openvswitch", "kmod-openvswitch-debug", and

4
INSTALL.SSL → INSTALL.SSL.md
View File

@@ -1,5 +1,5 @@
Configuring Open vSwitch for SSL
================================
Configuring Open vSwitch for SSL
================================
If you plan to configure Open vSwitch to connect across the network to
an OpenFlow controller, then we recommend that you build Open vSwitch

8
INSTALL.Windows → INSTALL.Windows.md
View File

@@ -1,5 +1,5 @@
How to Build the Kernel module & userspace daemons for Windows
==============================================================
How to Build the Kernel module & userspace daemons for Windows
==============================================================
Autoconf, Automake and Visual C++:
---------------------------------
@@ -92,8 +92,8 @@ For example,
% ./configure CC=./build-aux/cccl LD="`which link`" LIBS="-lws2_32" \
--prefix="C:/openvswitch/usr" --localstatedir="C:/openvswitch/var" \
--sysconfdir="C:/openvswitch/etc" --with-pthread="C:/pthread" --enable-ssl \
--with-openssl="C:/OpenSSL-Win32"
--sysconfdir="C:/openvswitch/etc" --with-pthread="C:/pthread" \
--enable-ssl --with-openssl="C:/OpenSSL-Win32"
* Run make for the ported executables.

34
INSTALL.XenServer → INSTALL.XenServer.md
View File

@@ -1,9 +1,9 @@
How to Install Open vSwitch on Citrix XenServer
===============================================
How to Install Open vSwitch on Citrix XenServer
===============================================
This document describes how to build and install Open vSwitch on a
Citrix XenServer host. If you want to install Open vSwitch on a
generic Linux or BSD host, see INSTALL instead.
generic Linux or BSD host, see [INSTALL](INSTALL.md) instead.
These instructions have been tested with XenServer 5.6 FP1.
@@ -15,12 +15,12 @@ Open vSwitch Git tree. The recommended build environment to build
RPMs for Citrix XenServer is the DDK VM available from Citrix.
1. If you are building from an Open vSwitch Git tree, then you will
need to first create a distribution tarball by running "./boot.sh;
./configure; make dist" in the Git tree. You cannot run this in
need to first create a distribution tarball by running `./boot.sh;
./configure; make dist` in the Git tree. You cannot run this in
the DDK VM, because it lacks tools that are necessary to bootstrap
the Open vSwitch distribution. Instead, you must run this on a
machine that has the tools listed in INSTALL as prerequisites for
building from a Git tree.
machine that has the tools listed in [INSTALL](INSTALL.md) as
prerequisites for building from a Git tree.
2. Copy the distribution tarball into /usr/src/redhat/SOURCES inside
the DDK VM.
@@ -30,7 +30,7 @@ RPMs for Citrix XenServer is the DDK VM available from Citrix.
4. To build Open vSwitch userspace, run:
rpmbuild -bb xenserver/openvswitch-xen.spec
`rpmbuild -bb xenserver/openvswitch-xen.spec`
This produces three RPMs in /usr/src/redhat/RPMS/i386:
"openvswitch", "openvswitch-modules-xen", and
@@ -39,7 +39,7 @@ RPMs for Citrix XenServer is the DDK VM available from Citrix.
The above command automatically runs the Open vSwitch unit tests.
To disable the unit tests, run:
rpmbuild -bb --without check xenserver/openvswitch-xen.spec
`rpmbuild -bb --without check xenserver/openvswitch-xen.spec`
Build Parameters
----------------
@@ -50,6 +50,7 @@ itself, but if it does not do it correctly then you can specify them
yourself as parameters to the build. Thus, the final "rpmbuild" step
above can be elaborated as:
```
VERSION=<Open vSwitch version>
KERNEL_NAME=<Xen Kernel name>
KERNEL_VERSION=<Xen Kernel version>
@@ -60,21 +61,22 @@ above can be elaborated as:
-D "kernel_version $KERNEL_VERSION" \
-D "kernel_flavor $KERNEL_FLAVOR" \
-bb xenserver/openvswitch-xen.spec
```
where:
<openvswitch version> is the version number that appears in the
`<openvswitch version>` is the version number that appears in the
name of the Open vSwitch tarball, e.g. 0.90.0.
<Xen Kernel name> is the name of the XenServer kernel package,
`<Xen Kernel name>` is the name of the XenServer kernel package,
e.g. kernel-xen or kernel-NAME-xen, without the "kernel-" prefix.
<Xen Kernel version> is the output of:
`<Xen Kernel version>` is the output of:
rpm -q --queryformat "%{Version}-%{Release}" <kernel-devel-package>,
e.g. 2.6.32.12-0.7.1.xs5.6.100.323.170596, where <kernel-devel-package> is
the name of the -devel package corresponding to <Xen Kernel name>.
<Xen Kernel flavor (suffix) > is either "xen" or "kdump".
`<Xen Kernel flavor (suffix) >` is either "xen" or "kdump".
The "xen" flavor is the main running kernel flavor and the "kdump" flavor is
the crashdump kernel flavor. Commonly, one would specify "xen" here.
@@ -85,6 +87,7 @@ To install Open vSwitch on a XenServer host, or to upgrade to a newer version,
copy the "openvswitch" and "openvswitch-modules-xen" RPMs to that host with
"scp", then install them with "rpm -U", e.g.:
```
scp openvswitch-$VERSION-1.i386.rpm \
openvswitch-modules-xen-$XEN_KERNEL_VERSION-$VERSION-1.i386.rpm \
root@<host>:
@@ -93,12 +96,13 @@ copy the "openvswitch" and "openvswitch-modules-xen" RPMs to that host with
(At this point you will have to enter <host>'s root password again.)
rpm -U openvswitch-$VERSION-1.i386.rpm \
openvswitch-modules-xen-$XEN_KERNEL_VERSION-$VERSION-1.i386.rpm
```
To uninstall Open vSwitch from a XenServer host, remove the packages:
ssh root@<host>
`ssh root@<host>`
(At this point you will have to enter <host>'s root password again.)
rpm -e openvswitch openvswitch-modules-xen-$XEN_KERNEL_VERSION
`rpm -e openvswitch openvswitch-modules-xen-$XEN_KERNEL_VERSION`
After installing or uninstalling Open vSwitch, the XenServer should be
rebooted as soon as possible.

108
INSTALL → INSTALL.md
View File

@@ -1,16 +1,16 @@
How to Install Open vSwitch on Linux, FreeBSD and NetBSD
========================================================
How to Install Open vSwitch on Linux, FreeBSD and NetBSD
========================================================
This document describes how to build and install Open vSwitch on a
generic Linux, FreeBSD, or NetBSD host. For specifics around installation
on a specific platform, please see one of these files:
- INSTALL.Debian
- INSTALL.Fedora
- INSTALL.RHEL
- INSTALL.XenServer
- INSTALL.NetBSD
- INSTALL.DPDK
- [INSTALL.Debian](INSTALL.Debian.md)
- [INSTALL.Fedora](INSTALL.Fedora.md)
- [INSTALL.RHEL](INSTALL.RHEL.md)
- [INSTALL.XenServer](INSTALL.XenServer.md)
- [INSTALL.NetBSD](INSTALL.NetBSD.md)
- [INSTALL.DPDK](INSTALL.DPDK.md)
Build Requirements
------------------
@@ -153,34 +153,34 @@ Prerequisites section, follow the procedure below to build.
1. If you pulled the sources directly from an Open vSwitch Git tree,
run boot.sh in the top source directory:
% ./boot.sh
`% ./boot.sh`
2. Configure the package by running the configure script. You can
usually invoke configure without any arguments. For example:
% ./configure
`% ./configure`
By default all files are installed under /usr/local. If you want
to install into, e.g., /usr and /var instead of /usr/local and
/usr/local/var, add options as shown here:
% ./configure --prefix=/usr --localstatedir=/var
`% ./configure --prefix=/usr --localstatedir=/var`
To use a specific C compiler for compiling Open vSwitch user
programs, also specify it on the configure command line, like so:
% ./configure CC=gcc-4.2
`% ./configure CC=gcc-4.2`
To use 'clang' compiler:
% ./configure CC=clang
`% ./configure CC=clang`
To build the Linux kernel module, so that you can run the
kernel-based switch, pass the location of the kernel build
directory on --with-linux. For example, to build for a running
instance of Linux:
% ./configure --with-linux=/lib/modules/`uname -r`/build
`% ./configure --with-linux=/lib/modules/`uname -r`/build`
If --with-linux requests building for an unsupported version of
Linux, then "configure" will fail with an error message. Please
@@ -192,7 +192,7 @@ Prerequisites section, follow the procedure below to build.
when invoking the configure script. For example, to build for MIPS
with Linux:
% ./configure --with-linux=/path/to/linux KARCH=mips
`% ./configure --with-linux=/path/to/linux KARCH=mips`
If you plan to do much Open vSwitch development, you might want to
add --enable-Werror, which adds the -Werror option to the compiler
@@ -202,7 +202,7 @@ Prerequisites section, follow the procedure below to build.
To build with gcov code coverage support, add --enable-coverage,
e.g.:
% ./configure --enable-coverage
`% ./configure --enable-coverage`
The configure script accepts a number of other options and honors
additional environment variables. For a full list, invoke
@@ -214,22 +214,22 @@ Prerequisites section, follow the procedure below to build.
builds, or to build kernel modules for more than one Linux version.
Here is an example:
% mkdir _gcc && (cd _gcc && ../configure CC=gcc)
% mkdir _clang && (cd _clang && ../configure CC=clang)
`% mkdir _gcc && (cd _gcc && ../configure CC=gcc)`
`% mkdir _clang && (cd _clang && ../configure CC=clang)`
3. Run GNU make in the build directory, e.g.:
% make
`% make`
or if GNU make is installed as "gmake":
% gmake
`% gmake`
If you used a separate build directory, run make or gmake from that
directory, e.g.:
% make -C _gcc
% make -C _clang
`% make -C _gcc`
`% make -C _clang`
For improved warnings if you installed "sparse" (see
"Prerequisites"), add C=1 to the command line.
@@ -244,20 +244,20 @@ Prerequisites section, follow the procedure below to build.
7. If you built kernel modules, you may install and load them, e.g.:
% make modules_install
% /sbin/modprobe openvswitch
`% make modules_install`
`% /sbin/modprobe openvswitch`
To verify that the modules have been loaded, run "/sbin/lsmod" and
check that openvswitch is listed.
If the "modprobe" operation fails, look at the last few kernel log
messages (e.g. with "dmesg | tail"):
If the `modprobe` operation fails, look at the last few kernel log
messages (e.g. with `dmesg | tail`):
- The message "openvswitch: exports duplicate symbol
br_should_route_hook (owned by bridge)" means that the bridge
module is loaded. Run "/sbin/rmmod bridge" to remove it.
module is loaded. Run `/sbin/rmmod bridge` to remove it.
If "/sbin/rmmod bridge" fails with "ERROR: Module bridge does
If `/sbin/rmmod bridge` fails with "ERROR: Module bridge does
not exist in /proc/modules", then the bridge is compiled into
the kernel, rather than as a module. Open vSwitch does not
support this configuration (see "Build Requirements", above).
@@ -265,25 +265,27 @@ Prerequisites section, follow the procedure below to build.
- The message "openvswitch: exports duplicate symbol
dp_ioctl_hook (owned by ofdatapath)" means that the ofdatapath
module from the OpenFlow reference implementation is loaded.
Run "/sbin/rmmod ofdatapath" to remove it. (You might have to
Run `/sbin/rmmod ofdatapath` to remove it. (You might have to
delete any existing datapaths beforehand, using the "dpctl"
program included with the OpenFlow reference implementation.
"ovs-dpctl" will not work.)
- Otherwise, the most likely problem is that Open vSwitch was
built for a kernel different from the one into which you are
trying to load it. Run "modinfo" on openvswitch.ko and on
trying to load it. Run `modinfo` on openvswitch.ko and on
a module built for the running kernel, e.g.:
```
% /sbin/modinfo openvswitch.ko
% /sbin/modinfo /lib/modules/`uname -r`/kernel/net/bridge/bridge.ko
```
Compare the "vermagic" lines output by the two commands. If
they differ, then Open vSwitch was built for the wrong kernel.
- If you decide to report a bug or ask a question related to
module loading, please include the output from the "dmesg" and
"modinfo" commands mentioned above.
module loading, please include the output from the `dmesg` and
`modinfo` commands mentioned above.
There is an optional module parameter to openvswitch.ko called
vlan_tso that enables TCP segmentation offload over VLANs on NICs
@@ -299,8 +301,8 @@ Prerequisites section, follow the procedure below to build.
8. Initialize the configuration database using ovsdb-tool, e.g.:
% mkdir -p /usr/local/etc/openvswitch
% ovsdb-tool create /usr/local/etc/openvswitch/conf.db vswitchd/vswitch.ovsschema
`% mkdir -p /usr/local/etc/openvswitch`
`% ovsdb-tool create /usr/local/etc/openvswitch/conf.db vswitchd/vswitch.ovsschema`
Startup
=======
@@ -352,7 +354,9 @@ also upgrade the database schema:
1. Stop the Open vSwitch daemons, e.g.:
```
% kill `cd /usr/local/var/run/openvswitch && cat ovsdb-server.pid ovs-vswitchd.pid`
```
2. Install the new Open vSwitch release.
@@ -366,7 +370,7 @@ also upgrade the database schema:
- If you want to preserve the contents of your database, back it
up first, then use "ovsdb-tool convert" to upgrade it, e.g.:
% ovsdb-tool convert /usr/local/etc/openvswitch/conf.db vswitchd/vswitch.ovsschema
`% ovsdb-tool convert /usr/local/etc/openvswitch/conf.db vswitchd/vswitch.ovsschema`
4. Start the Open vSwitch daemons as described under "Building and
Installing Open vSwitch for Linux, FreeBSD or NetBSD" above.
@@ -436,25 +440,25 @@ other areas of Open vSwitch.
Refer to "Testsuites" above for prerequisites.
To run all the unit tests in Open vSwitch, one at a time:
make check
`make check`
This takes under 5 minutes on a modern desktop system.
To run all the unit tests in Open vSwitch, up to 8 in parallel:
make check TESTSUITEFLAGS=-j8
`make check TESTSUITEFLAGS=-j8`
This takes under a minute on a modern 4-core desktop system.
To see a list of all the available tests, run:
make check TESTSUITEFLAGS=--list
`make check TESTSUITEFLAGS=--list`
To run only a subset of tests, e.g. test 123 and tests 477 through 484:
make check TESTSUITEFLAGS='123 477-484'
`make check TESTSUITEFLAGS='123 477-484'`
(Tests do not have inter-dependencies, so you may run any subset.)
To run tests matching a keyword, e.g. "ovsdb":
make check TESTSUITEFLAGS='-k ovsdb'
`make check TESTSUITEFLAGS='-k ovsdb'`
To see a complete list of test options:
make check TESTSUITEFLAGS=--help
`make check TESTSUITEFLAGS=--help`
The results of a testing run are reported in tests/testsuite.log.
Please report test failures as bugs and include the testsuite.log in
@@ -463,8 +467,8 @@ your report.
If you have "valgrind" installed, then you can also run the testsuite
under valgrind by using "make check-valgrind" in place of "make
check". All the same options are available via TESTSUITEFLAGS. When
you do this, the "valgrind" results for test <N> are reported in files
named tests/testsuite.dir/<N>/valgrind.*. You may find that the
you do this, the "valgrind" results for test `<N>` are reported in files
named `tests/testsuite.dir/<N>/valgrind.*`. You may find that the
valgrind results are easier to interpret if you put "-q" in
~/.valgrindrc, since that reduces the amount of output.
@@ -498,24 +502,24 @@ program) to your $PATH. This slightly simplifies running OFTest later.
To run OFTest in dummy mode, run the following command from your Open
vSwitch build directory:
make check-oftest OFT=<oft-binary>
where <oft-binary> is the absolute path to the "oft" program in
`make check-oftest OFT=<oft-binary>`
where `<oft-binary>` is the absolute path to the "oft" program in
OFTest.
If you added "oft" to your $PATH, you may omit the OFT variable
assignment:
make check-oftest
`make check-oftest`
By default, "check-oftest" passes "oft" just enough options to enable
dummy mode. You can use OFTFLAGS to pass additional options. For
example, to run just the basic.Echo test instead of all tests (the
default) and enable verbose logging:
make check-oftest OFT=<oft-binary> OFTFLAGS='--verbose -T basic.Echo'
`make check-oftest OFT=<oft-binary> OFTFLAGS='--verbose -T basic.Echo'`
If you use OFTest that does not include commit 4d1f3eb2c792 (oft:
change default port to 6653), merged into the OFTest repository in
October 2013, then you need to add an option to use the IETF-assigned
controller port:
make check-oftest OFT=<oft-binary> OFTFLAGS='--port=6653'
`make check-oftest OFT=<oft-binary> OFTFLAGS='--port=6653'`
Please interpret OFTest results cautiously. Open vSwitch can fail a
given test in OFTest for many reasons, including bugs in Open vSwitch,
@@ -542,11 +546,11 @@ Ryu (some of the tests do not get installed, so it does not help).
To run Ryu tests, run the following command from your Open vSwitch
build directory:
make check-ryu RYUDIR=<ryu-source-dir>
where <ryu-source-dir> is the absolute path to the root of the Ryu
source distribution. The default <ryu-source-dir> is $srcdir/../ryu
`make check-ryu RYUDIR=<ryu-source-dir>`
where `<ryu-source-dir>` is the absolute path to the root of the Ryu
source distribution. The default `<ryu-source-dir>` is `$srcdir/../ryu`
where $srcdir is your Open vSwitch source directory, so if this
default is correct then you make simply run "make check-ryu".
default is correct then you make simply run `make check-ryu`.
Open vSwitch has not been validated against Ryu. Please do report
test failures that you believe to represent bugs in Open vSwitch.

16
INSTALL.userspace → INSTALL.userspace.md
View File

@@ -1,5 +1,5 @@
Using Open vSwitch without kernel support
=========================================
Using Open vSwitch without kernel support
=========================================
Open vSwitch can operate, at a cost in performance, entirely in
userspace, without assistance from a kernel module. This file
@@ -8,8 +8,8 @@ explains how to install Open vSwitch in such a mode.
The userspace-only mode of Open vSwitch is considered experimental.
It has not been thoroughly tested.
This version of Open vSwitch should be built manually with "configure"
and "make". Debian packaging for Open vSwitch is also included, but
This version of Open vSwitch should be built manually with `configure`
and `make`. Debian packaging for Open vSwitch is also included, but
it has not been recently tested, and so Debian packages are not a
recommended way to use this version of Open vSwitch.
@@ -25,11 +25,11 @@ On Linux, the userspace switch additionally requires the kernel
TUN/TAP driver to be available, either built into the kernel or loaded
as a module. If you are not sure, check for a directory named
/sys/class/misc/tun. If it does not exist, then attempt to load the
module with "modprobe tun".
module with `modprobe tun`.
The tun device must also exist as /dev/net/tun. If it does not exist,
then create /dev/net (if necessary) with "mkdir /dev/net", then create
/dev/net/tun with "mknod /dev/net/tun c 10 200".
The tun device must also exist as `/dev/net/tun`. If it does not exist,
then create /dev/net (if necessary) with `mkdir /dev/net`, then create
`/dev/net/tun` with `mknod /dev/net/tun c 10 200`.
On FreeBSD and NetBSD, the userspace switch additionally requires the
kernel tap(4) driver to be available, either built into the kernel or

4
IntegrationGuide → IntegrationGuide.md
View File

@@ -1,5 +1,5 @@
Integration Guide for Centralized Control
=========================================
Integration Guide for Centralized Control
=========================================
This document describes how to integrate Open vSwitch onto a new
platform to expose the state of the switch and attached devices for

50
Makefile.am
View File

@@ -62,35 +62,35 @@ CLEAN_LOCAL =
DISTCLEANFILES =
PYCOV_CLEAN_FILES = build-aux/check-structs,cover
EXTRA_DIST = \
CONTRIBUTING \
CodingStyle \
DESIGN \
FAQ \
INSTALL \
INSTALL.Debian \
INSTALL.Docker \
INSTALL.DPDK \
INSTALL.Fedora \
INSTALL.KVM \
INSTALL.Libvirt \
INSTALL.NetBSD \
INSTALL.RHEL \
INSTALL.SSL \
INSTALL.XenServer \
INSTALL.userspace \
INSTALL.Windows \
IntegrationGuide \
CONTRIBUTING.md \
CodingStyle.md \
DESIGN.md \
FAQ.md \
INSTALL.md \
INSTALL.Debian.md \
INSTALL.Docker.md \
INSTALL.DPDK.md \
INSTALL.Fedora.md \
INSTALL.KVM.md \
INSTALL.Libvirt.md \
INSTALL.NetBSD.md \
INSTALL.RHEL.md \
INSTALL.SSL.md \
INSTALL.XenServer.md \
INSTALL.userspace.md \
INSTALL.Windows.md \
IntegrationGuide.md \
NOTICE \
OPENFLOW-1.1+ \
PORTING \
OPENFLOW-1.1+.md \
PORTING.md \
README.md \
README-lisp \
REPORTING-BUGS \
TODO \
README-lisp.md \
REPORTING-BUGS.md \
TODO.md \
.travis.yml \
.travis/build.sh \
.travis/prepare.sh \
WHY-OVS \
WHY-OVS.md \
boot.sh \
build-aux/cccl \
build-aux/sodepends.pl \
@@ -225,7 +225,7 @@ printf-check:
then \
echo "See above for list of violations of the rule that"; \
echo "'z', 't', 'j', 'hh' printf() type modifiers are"; \
echo "forbidden. See CodingStyle for replacements."; \
echo "forbidden. See CodingStyle.md for replacements."; \
exit 1; \
fi
.PHONY: printf-check

4
NEWS
View File

@@ -32,7 +32,7 @@ Post-v2.3.0
who find it useful for testing basic OpenFlow setups. It is still not
a necessary or desirable part of most Open vSwitch deployments.
- Support for travis-ci.org based continuous integration builds has been
added. Build failures are reported to build@openvswitch.org. See INSTALL
added. Build failures are reported to build@openvswitch.org. See INSTALL.md
file for additional details.
- Experimental support for the Rapid Spanning Tree Protocol
(IEEE 802.1D-2004). More conformance and interoperability testing is
@@ -71,7 +71,7 @@ v2.2.0 - Internal Release
- The "ovsdbmonitor" graphical tool has been removed, because it was
poorly maintained and not widely used.
- New "check-ryu" Makefile target for running Ryu tests for OpenFlow
controllers against Open vSwitch. See INSTALL for details.
controllers against Open vSwitch. See INSTALL.md for details.
- Added IPFIX support for SCTP flows and templates for ICMPv4/v6 flows.
- Upon the receipt of a SIGHUP signal, ovs-vswitchd no longer reopens its
log file (it will terminate instead). Please use 'ovs-appctl vlog/reopen'

231
OPENFLOW-1.1+
View File

@@ -1,231 +0,0 @@
OpenFlow 1.1+ support in Open vSwitch
=====================================
Open vSwitch support for OpenFlow 1.1 and beyond is a work in
progress. This file describes the work still to be done.
The Plan
--------
OpenFlow version support is not a build-time option. A single build
of Open vSwitch must be able to handle all supported versions of
OpenFlow. Ideally, even at runtime it should be able to support all
protocol versions at the same time on different OpenFlow bridges (and
perhaps even on the same bridge).
At the same time, it would be a shame to litter the core of the OVS
code with lots of ugly code concerned with the details of various
OpenFlow protocol versions.
The primary approach to compatibility is to abstract most of the
details of the differences from the core code, by adding a protocol
layer that translates between OF1.x and a slightly higher-level
abstract representation. The core of this approach is the many struct
ofputil_* structures in lib/ofp-util.h.
As a consequence of this approach, OVS cannot use OpenFlow protocol
definitions that closely resemble those in the OpenFlow specification,
because openflow.h in different versions of the OpenFlow specification
defines the same identifier with different values. Instead,
openflow-common.h contains definitions that are common to all the
specifications and separate protocol version-specific headers contain
protocol-specific definitions renamed so as not to conflict,
e.g. OFPAT10_ENQUEUE and OFPAT11_ENQUEUE for the OpenFlow 1.0 and 1.1
values for OFPAT_ENQUEUE. Generally, in cases of conflict, the
protocol layer will define a more abstract OFPUTIL_* or struct
ofputil_*.
Here are the current approaches in a few tricky areas:
* Port numbering. OpenFlow 1.0 has 16-bit port numbers and later
OpenFlow versions have 32-bit port numbers. For now, OVS
support for later protocol versions requires all port numbers to
fall into the 16-bit range, translating the reserved OFPP_* port
numbers.
* Actions. OpenFlow 1.0 and later versions have very different
ideas of actions. OVS reconciles by translating all the
versions' actions (and instructions) to and from a common
internal representation.
OpenFlow 1.1
------------
The list of remaining work items for OpenFlow 1.1 is below. It is
probably incomplete.
* Match and set double-tagged VLANs (QinQ). This requires kernel
work for reasonable performance.
[optional for OF1.1+]
* VLANs tagged with 88a8 Ethertype. This requires kernel work for
reasonable performance.
[required for OF1.1+]
OpenFlow 1.2
------------
OpenFlow 1.2 support requires OpenFlow 1.1 as a prerequisite. All the
additional work specific to Openflow 1.2 are complete. (This is based
on the change log at the end of the OF1.2 spec. I didn't compare the
specs carefully yet.)
OpenFlow 1.3
------------
OpenFlow 1.3 support requires OpenFlow 1.2 as a prerequisite, plus the
following additional work. (This is based on the change log at the
end of the OF1.3 spec, reusing most of the section titles directly. I
didn't compare the specs carefully yet.)
* Add support for multipart requests.
Currently we always report OFPBRC_MULTIPART_BUFFER_OVERFLOW.
[optional for OF1.3+]
* IPv6 extension header handling support. Fully implementing this
requires kernel support. This likely will take some careful and
probably time-consuming design work. The actual coding, once
that is all done, is probably 2 or 3 days work.
[optional for OF1.3+]
* Per-flow meters. OpenFlow protocol support is now implemented.
Support for the special OFPM_SLOWPATH and OFPM_CONTROLLER meters
is missing. Support for the software switch is under review.
[optional for OF1.3+]
* Auxiliary connections. An implementation in generic code might
be a week's worth of work. The value of an implementation in
generic code is questionable, though, since much of the benefit
of axuiliary connections is supposed to be to take advantage of
hardware support. (We could make the kernel module somehow
send packets across the auxiliary connections directly, for
some kind of "hardware" support, if we judged it useful enough.)
[optional for OF1.3+]
* Provider Backbone Bridge tagging. I don't plan to implement
this (but we'd accept an implementation).
[optional for OF1.3+]
* On-demand flow counters. I think this might be a real
optimization in some cases for the software switch.
[optional for OF1.3+]
ONF OpenFlow Exensions for 1.3.X Pack1
--------------------------------------
OpenFlow 1.3 has a bunch of ONF extentions.
Many of them are necessary for OpenFlow 1.4 as well.
* Flow entry notifications
This seems to be modelled after OVS's NXST_FLOW_MONITOR.
(Simon Horman is working on this.)
[EXT-187]
[required for OF1.4+]
* Role Status
[EXT-191]
[required for OF1.4+]
* Flow entry eviction
OVS has flow eviction functionality.
table_mod OFPTC_EVICTION, flow_mod 'importance', and
table_desc ofp_table_mod_prop_eviction need to be implemented.
[EXT-192-e]
[optional for OF1.4+]
* Vacancy events
[EXT-192-v]
[optional for OF1.4+]
* Bundle
Transactional modification. OpenFlow 1.4 requires to support
flow_mods and port_mods in a bundle.
(Not related to OVS's 'ofbundle' stuff.)
[EXT-230]
[required for OF1.4+]
* Table synchronisation
[EXT-232]
[optional for OF1.4+]
* Group notifications
[EXT-235]
[optional for OF1.4+]
* Bad flow entry priority error
Probably not so useful to the software switch.
[EXT-236]
[optional for OF1.4+]
* Set async config error
[EXT-237]
[optional for OF1.4+]
* PBB UCA header field
[EXT-256]
[optional for OF1.4+]
* Multipart timeout error
[EXT-264]
[required for OF1.4+]
OpenFlow 1.4
------------
* More extensible wire protocol
Many on-wire structures got TLVs.
[EXT-262]
[required for OF1.4+]
* More descriptive reasons for packet-in
Distinguish OFPR_APPLY_ACTION, OFPR_ACTION_SET, OFPR_GROUP,
OFPR_PACKET_OUT. NO_MATCH was renamed to OFPR_TABLE_MISS.
[EXT-136]
[required for OF1.4+]
* Optical port properties
[EXT-154]
[optional for OF1.4+]
* Meter notifications
[EXT-235]
[optional for OF1.4+]
General
-----
* ovs-ofctl(8) often lists as Nicira extensions features that
later OpenFlow versions support in standard ways.
How to contribute
-----------------
If you plan to contribute code for a feature, please let everyone know
on ovs-dev before you start work. This will help avoid duplicating
work.
Please consider the following:
* Testing. Please test your code.
* Unit tests. Please consider writing some. The tests directory
has many examples that you can use as a starting point.
* ovs-ofctl. If you add a feature that is useful for some
ovs-ofctl command then you should add support for it there.
* Documentation. If you add a user-visible feature, then you
should document it in the appropriate manpage and mention it in
NEWS as well.
* Coding style (see the CodingStyle file at the top of the source
tree).
* The patch submission guidelines (see CONTRIBUTING). I
recommend using "git send-email", which automatically follows a
lot of those guidelines.
Bug Reporting
-------------
Please report problems to bugs@openvswitch.org.

231
OPENFLOW-1.1+.md Normal file
View File

@@ -0,0 +1,231 @@
OpenFlow 1.1+ support in Open vSwitch
=====================================
Open vSwitch support for OpenFlow 1.1 and beyond is a work in
progress. This file describes the work still to be done.
The Plan
--------
OpenFlow version support is not a build-time option. A single build
of Open vSwitch must be able to handle all supported versions of
OpenFlow. Ideally, even at runtime it should be able to support all
protocol versions at the same time on different OpenFlow bridges (and
perhaps even on the same bridge).
At the same time, it would be a shame to litter the core of the OVS
code with lots of ugly code concerned with the details of various
OpenFlow protocol versions.
The primary approach to compatibility is to abstract most of the
details of the differences from the core code, by adding a protocol
layer that translates between OF1.x and a slightly higher-level
abstract representation. The core of this approach is the many struct
ofputil_* structures in lib/ofp-util.h.
As a consequence of this approach, OVS cannot use OpenFlow protocol
definitions that closely resemble those in the OpenFlow specification,
because openflow.h in different versions of the OpenFlow specification
defines the same identifier with different values. Instead,
openflow-common.h contains definitions that are common to all the
specifications and separate protocol version-specific headers contain
protocol-specific definitions renamed so as not to conflict,
e.g. OFPAT10_ENQUEUE and OFPAT11_ENQUEUE for the OpenFlow 1.0 and 1.1
values for OFPAT_ENQUEUE. Generally, in cases of conflict, the
protocol layer will define a more abstract OFPUTIL_* or struct
ofputil_*.
Here are the current approaches in a few tricky areas:
* Port numbering. OpenFlow 1.0 has 16-bit port numbers and later
OpenFlow versions have 32-bit port numbers. For now, OVS
support for later protocol versions requires all port numbers to
fall into the 16-bit range, translating the reserved OFPP_* port
numbers.
* Actions. OpenFlow 1.0 and later versions have very different
ideas of actions. OVS reconciles by translating all the
versions' actions (and instructions) to and from a common
internal representation.
OpenFlow 1.1
------------
The list of remaining work items for OpenFlow 1.1 is below. It is
probably incomplete.
* Match and set double-tagged VLANs (QinQ). This requires kernel
work for reasonable performance.
[optional for OF1.1+]
* VLANs tagged with 88a8 Ethertype. This requires kernel work for
reasonable performance.
[required for OF1.1+]
OpenFlow 1.2
------------
OpenFlow 1.2 support requires OpenFlow 1.1 as a prerequisite. All the
additional work specific to Openflow 1.2 are complete. (This is based
on the change log at the end of the OF1.2 spec. I didn't compare the
specs carefully yet.)
OpenFlow 1.3
------------
OpenFlow 1.3 support requires OpenFlow 1.2 as a prerequisite, plus the
following additional work. (This is based on the change log at the
end of the OF1.3 spec, reusing most of the section titles directly. I
didn't compare the specs carefully yet.)
* Add support for multipart requests.
Currently we always report OFPBRC_MULTIPART_BUFFER_OVERFLOW.
[optional for OF1.3+]
* IPv6 extension header handling support. Fully implementing this
requires kernel support. This likely will take some careful and
probably time-consuming design work. The actual coding, once
that is all done, is probably 2 or 3 days work.
[optional for OF1.3+]
* Per-flow meters. OpenFlow protocol support is now implemented.
Support for the special OFPM_SLOWPATH and OFPM_CONTROLLER meters
is missing. Support for the software switch is under review.
[optional for OF1.3+]
* Auxiliary connections. An implementation in generic code might
be a week's worth of work. The value of an implementation in
generic code is questionable, though, since much of the benefit
of axuiliary connections is supposed to be to take advantage of
hardware support. (We could make the kernel module somehow
send packets across the auxiliary connections directly, for
some kind of "hardware" support, if we judged it useful enough.)
[optional for OF1.3+]
* Provider Backbone Bridge tagging. I don't plan to implement
this (but we'd accept an implementation).
[optional for OF1.3+]
* On-demand flow counters. I think this might be a real
optimization in some cases for the software switch.
[optional for OF1.3+]
ONF OpenFlow Exensions for 1.3.X Pack1
--------------------------------------
OpenFlow 1.3 has a bunch of ONF extentions.
Many of them are necessary for OpenFlow 1.4 as well.
* Flow entry notifications
This seems to be modelled after OVS's NXST_FLOW_MONITOR.
(Simon Horman is working on this.)
[EXT-187]
[required for OF1.4+]
* Role Status
[EXT-191]
[required for OF1.4+]
* Flow entry eviction
OVS has flow eviction functionality.
table_mod OFPTC_EVICTION, flow_mod 'importance', and
table_desc ofp_table_mod_prop_eviction need to be implemented.
[EXT-192-e]
[optional for OF1.4+]
* Vacancy events
[EXT-192-v]
[optional for OF1.4+]
* Bundle
Transactional modification. OpenFlow 1.4 requires to support
flow_mods and port_mods in a bundle.
(Not related to OVS's 'ofbundle' stuff.)
[EXT-230]
[required for OF1.4+]
* Table synchronisation
[EXT-232]
[optional for OF1.4+]
* Group notifications
[EXT-235]
[optional for OF1.4+]
* Bad flow entry priority error
Probably not so useful to the software switch.
[EXT-236]
[optional for OF1.4+]
* Set async config error
[EXT-237]
[optional for OF1.4+]
* PBB UCA header field
[EXT-256]
[optional for OF1.4+]
* Multipart timeout error
[EXT-264]
[required for OF1.4+]
OpenFlow 1.4
------------
* More extensible wire protocol
Many on-wire structures got TLVs.
[EXT-262]
[required for OF1.4+]
* More descriptive reasons for packet-in
Distinguish OFPR_APPLY_ACTION, OFPR_ACTION_SET, OFPR_GROUP,
OFPR_PACKET_OUT. NO_MATCH was renamed to OFPR_TABLE_MISS.
[EXT-136]
[required for OF1.4+]
* Optical port properties
[EXT-154]
[optional for OF1.4+]
* Meter notifications
[EXT-235]
[optional for OF1.4+]
General
-----
* ovs-ofctl(8) often lists as Nicira extensions features that
later OpenFlow versions support in standard ways.
How to contribute
-----------------
If you plan to contribute code for a feature, please let everyone know
on ovs-dev before you start work. This will help avoid duplicating
work.
Please consider the following:
* Testing. Please test your code.
* Unit tests. Please consider writing some. The tests directory
has many examples that you can use as a starting point.
* ovs-ofctl. If you add a feature that is useful for some
ovs-ofctl command then you should add support for it there.
* Documentation. If you add a user-visible feature, then you
should document it in the appropriate manpage and mention it in
NEWS as well.
* Coding style (see the [CodingStyle](CodingStyle.md) file at the
top of the source tree).
* The patch submission guidelines (see CONTRIBUTING). I
recommend using "git send-email", which automatically follows a
lot of those guidelines.
Bug Reporting
-------------
Please report problems to bugs@openvswitch.org.

8
PORTING → PORTING.md
View File

@@ -1,5 +1,5 @@
How to Port Open vSwitch to New Software or Hardware
====================================================
How to Port Open vSwitch to New Software or Hardware
====================================================
Open vSwitch (OVS) is intended to be easily ported to new software and
hardware platforms. This document describes the types of changes that
@@ -129,8 +129,8 @@ implementation built into Open vSwitch. This ought to work, without
writing any more code, as long as the netdev provider that you
implemented supports receiving packets. It yields poor performance,
however, because every packet passes through the ovs-vswitchd process.
See INSTALL.userspace for instructions on how to configure a userspace
switch.
See [INSTALL.userspace](INSTALL.userspace.md) for instructions on how
to configure a userspace switch.
If the userspace switch is not the right choice for your port, then
you will have to write more code. You may implement either an

0
README-lisp → README-lisp.md
View File

21
README.md
View File

@@ -81,24 +81,27 @@ To install Open vSwitch on a regular Linux or FreeBSD host, please
read INSTALL. For specifics around installation on a specific
platform, please see one of these files:
- INSTALL.Debian
- INSTALL.Fedora
- INSTALL.RHEL
- INSTALL.XenServer
- [INSTALL.Debian](INSTALL.Debian.md)
- [INSTALL.Fedora](INSTALL.Fedora.md)
- [INSTALL.RHEL](INSTALL.RHEL.md)
- [INSTALL.XenServer](INSTALL.XenServer.md)
To use Open vSwitch...
- ...with Docker on Linux, read INSTALL.Docker.
- ...with Docker on Linux, read [INSTALL.Docker](INSTALL.Docker.md)
- ...with KVM on Linux, read INSTALL, read INSTALL.KVM.
- ...with KVM on Linux, read [INSTALL](INSTALL.md), read
[INSTALL.KVM](INSTALL.KVM.md)
- ...with Libvirt, read INSTALL.Libvirt.
- ...with Libvirt, read [INSTALL.Libvirt](INSTALL.Libvirt.md).
- ...without using a kernel module, read INSTALL.userspace.
- ...without using a kernel module, read
[INSTALL.userspace](INSTALL.userspace.md).
For answers to common questions, read FAQ.
To learn how to set up SSL support for Open vSwitch, read INSTALL.SSL.
To learn how to set up SSL support for Open vSwitch, read
[INSTALL.SSL](INSTALL.SSL.md).
To learn about some advanced features of the Open vSwitch software
switch, read the tutorial in tutorial/Tutorial.

56
REPORTING-BUGS
View File

@@ -1,56 +0,0 @@
Reporting Bugs in Open vSwitch
==============================
We are eager to hear from users about problems that they have
encountered with Open vSwitch. This file documents how best to report
bugs so as to ensure that they can be fixed as quickly as possible.
Please report bugs by sending email to bugs@openvswitch.org.
The most important parts of your bug report are the following:
* What you did that make the problem appear.
* What you expected to happen.
* What actually happened.
Please also include the following information:
* The Open vSwitch version number (as output by "ovs-vswitchd
--version").
* The Git commit number (as output by "git rev-parse HEAD"),
if you built from a Git snapshot.
* Any local patches or changes you have applied (if any).
The following are also handy sometimes:
* The kernel version on which Open vSwitch is running (from
/proc/version) and the distribution and version number of
your OS (e.g. "Centos 5.0").
* The contents of the vswitchd configuration database (usually
/etc/openvswitch/conf.db).
* The output of "ovs-dpctl show".
* If you have Open vSwitch configured to connect to an
OpenFlow controller, the output of "ovs-ofctl show <bridge>"
for each <bridge> configured in the vswitchd configuration
database.
* A fix or workaround, if you have one.
* Any other information that you think might be relevant.
bugs@openvswitch.org is a public mailing list, to which anyone can
subscribe, so please do not include confidential information in your
bug report.
Contact
-------
bugs@openvswitch.org
http://openvswitch.org/

56
REPORTING-BUGS.md Normal file
View File

@@ -0,0 +1,56 @@
Reporting Bugs in Open vSwitch
==============================
We are eager to hear from users about problems that they have
encountered with Open vSwitch. This file documents how best to report
bugs so as to ensure that they can be fixed as quickly as possible.
Please report bugs by sending email to bugs@openvswitch.org.
The most important parts of your bug report are the following:
* What you did that make the problem appear.
* What you expected to happen.
* What actually happened.
Please also include the following information:
* The Open vSwitch version number (as output by `ovs-vswitchd
--version`).
* The Git commit number (as output by `git rev-parse HEAD`),
if you built from a Git snapshot.
* Any local patches or changes you have applied (if any).
The following are also handy sometimes:
* The kernel version on which Open vSwitch is running (from
`/proc/version`) and the distribution and version number of
your OS (e.g. "Centos 5.0").
* The contents of the vswitchd configuration database (usually
`/etc/openvswitch/conf.db`).
* The output of `ovs-dpctl show`.
* If you have Open vSwitch configured to connect to an
OpenFlow controller, the output of `ovs-ofctl show <bridge>`
for each `<bridge>` configured in the vswitchd configuration
database.
* A fix or workaround, if you have one.
* Any other information that you think might be relevant.
bugs@openvswitch.org is a public mailing list, to which anyone can
subscribe, so please do not include confidential information in your
bug report.
Contact
-------
bugs@openvswitch.org
http://openvswitch.org/

20
TODO → TODO.md
View File

@@ -1,5 +1,5 @@
Open vSwitch Project Ideas
==========================
Open vSwitch Project Ideas
==========================
This file lists a number of project ideas for Open vSwitch. The ideas
here overlap somewhat with those in the OPENFLOW-1.1+ file.
@@ -11,10 +11,10 @@ Programming Project Ideas
Each of these projects would ideally result in a patch or a short
series of them posted to ovs-dev.
Please read CONTRIBUTING and CodingStyle in the top of the source tree
before you begin work. The OPENFLOW-1.1+ file also has an
introduction to how OpenFlow is implemented in Open vSwitch. It is
also a good idea to look around the source tree for related code, and
Please read [CONTRIBUTING](CONTRIBUTING.md) and [CodingStyle](CodingStyle.md)
in the top of the source tree before you begin work. The OPENFLOW-1.1+
file also has an introduction to how OpenFlow is implemented in Open vSwitch.
It is also a good idea to look around the source tree for related code, and
back through the Git history for commits on related subjects, to allow
you to follow existing patterns and conventions.
@@ -266,11 +266,11 @@ Please consider the following:
should document it in the appropriate manpage and mention it in
NEWS as well.
* Coding style (see the CodingStyle file at the top of the source
tree).
* Coding style (see the [CodingStyle](CodingStyle.md) file at the top
of the source tree).
* The patch submission guidelines (see CONTRIBUTING). I
recommend using "git send-email", which automatically follows a
* The patch submission guidelines (see [CONTRIBUTING](CONTRIBUTING.md)).
I recommend using "git send-email", which automatically follows a
lot of those guidelines.

4
WHY-OVS → WHY-OVS.md
View File

@@ -1,5 +1,5 @@
Why Open vSwitch?
=================
Why Open vSwitch?
=================
Hypervisors need the ability to bridge traffic between VMs and with the
outside world. On Linux-based hypervisors, this used to mean using the

2
datapath/Modules.mk
View File

@@ -34,7 +34,7 @@ openvswitch_headers = \
vport-netdev.h
openvswitch_extras = \
README
README.md
dist_sources = $(foreach module,$(dist_modules),$($(module)_sources))
dist_headers = $(foreach module,$(dist_modules),$($(module)_headers))

0
datapath/README → datapath/README.md
View File

2
lib/dpif.h
View File

@@ -113,7 +113,7 @@
*
* In Open vSwitch userspace, "struct flow" is the typical way to describe
* a flow, but the datapath interface uses a different data format to
* allow ABI forward- and backward-compatibility. datapath/README
* allow ABI forward- and backward-compatibility. datapath/README.md
* describes the rationale and design. Refer to OVS_KEY_ATTR_* and
* "struct ovs_key_*" in include/odp-netlink.h for details.
* lib/odp-util.h defines several functions for working with these flows.

2
rhel/openvswitch-fedora.spec.in
View File

@@ -204,7 +204,7 @@ systemctl start openvswitch.service
%doc /usr/share/man/man8/ovs-test.8.gz
%doc /usr/share/man/man8/ovs-l3ping.8.gz
%doc /usr/share/man/man8/vtep-ctl.8.gz
%doc COPYING DESIGN INSTALL.SSL NOTICE README.md WHY-OVS FAQ NEWS INSTALL.DPDK
%doc COPYING DESIGN.md INSTALL.SSL.md NOTICE README.md WHY-OVS.md FAQ.md NEWS INSTALL.DPDK.md
/var/lib/openvswitch
/var/log/openvswitch
/usr/share/openvswitch/scripts/ovs-ctl

4
rhel/openvswitch.spec.in
View File

@@ -175,7 +175,7 @@ exit 0
/usr/share/openvswitch/scripts/sysconfig.template
/usr/share/openvswitch/vswitch.ovsschema
/usr/share/openvswitch/vtep.ovsschema
%doc COPYING DESIGN INSTALL.SSL NOTICE README.md WHY-OVS FAQ NEWS
%doc INSTALL.DPDK rhel/README.RHEL
%doc COPYING DESIGN.md INSTALL.SSL.md NOTICE README.md WHY-OVS.md FAQ.md NEWS
%doc INSTALL.DPDK.md rhel/README.RHEL
/var/lib/openvswitch
/var/log/openvswitch

0
third-party/README → third-party/README.md vendored
View File

2
third-party/automake.mk vendored
View File

@@ -1,3 +1,3 @@
EXTRA_DIST += \
third-party/README \
third-party/README.md \
third-party/ofp-tcpdump.patch

69
tutorial/Tutorial → tutorial/Tutorial.md
View File

@@ -28,7 +28,7 @@ include/openflow/nicira-ext.h header file.
Getting Started
===============
---------------
This is a hands-on tutorial. To get the most out of it, you will need
Open vSwitch binaries. You do not, on the other hand, need any
@@ -37,19 +37,19 @@ system. Instead, we will use a script called "ovs-sandbox", which
accompanies the tutorial, that constructs a software simulated network
environment based on Open vSwitch.
You can use "ovs-sandbox" three ways:
You can use `ovs-sandbox` three ways:
* If you have already installed Open vSwitch on your system, then
you should be able to just run "ovs-sandbox" from this directory
you should be able to just run `ovs-sandbox` from this directory
without any options.
* If you have not installed Open vSwitch (and you do not want to
install it), then you can build Open vSwitch according to the
instructions in INSTALL, without installing it. Then run
"./ovs-sandbox -b DIRECTORY" from this directory, substituting
`./ovs-sandbox -b DIRECTORY` from this directory, substituting
the Open vSwitch build directory for DIRECTORY.
* As a slight variant on the latter, you can run "make sandbox"
* As a slight variant on the latter, you can run `make sandbox`
from an Open vSwitch build directory.
When you run ovs-sandbox, it does the following:
@@ -67,7 +67,7 @@ When you run ovs-sandbox, it does the following:
installs the Open vSwitch manpages in a subdirectory of
"sandbox" and adjusts the MANPATH environment variable to point
to this directory. This means that you can use, for example,
"man ovs-vsctl" to see a manpage for the ovs-vsctl program that
`man ovs-vsctl` to see a manpage for the ovs-vsctl program that
you built.
5. Creates an empty Open vSwitch configuration database under
@@ -107,7 +107,7 @@ or after you exit.
Motivation
==========
----------
The goal of this tutorial is to demonstrate the power of Open vSwitch
flow tables. The tutorial works through the implementation of a
@@ -147,7 +147,7 @@ features.
Scenario
========
--------
We will construct Open vSwitch flow tables for a VLAN-capable,
MAC-learning switch that has four ports:
@@ -189,7 +189,7 @@ for cutting and pasting and are not supplied separately.
Setup
=====
-----
To get started, start "ovs-sandbox". Inside the interactive shell
that it starts, run this command:
@@ -238,7 +238,7 @@ command like "ovs-vsctl show" or "ovs-ofctl show br0".
Implementing Table 0: Admission control
=======================================
---------------------------------------
Table 0 is where packets enter the switch. We use this stage to
discard packets that for one reason or another are invalid. For
@@ -267,8 +267,7 @@ to pipeline stage 1 in OpenFlow table 1:
(The "resubmit" action is an Open vSwitch extension to OpenFlow.)
Testing Table 0
---------------
### Testing Table 0
If we were using Open vSwitch to set up a physical or a virtual
switch, then we would naturally test it by sending packets through it
@@ -283,7 +282,7 @@ the specification of a flow, "ofproto/trace" shows, step-by-step, how
such a flow would be treated as it goes through the switch.
== EXAMPLE 1 ==
### EXAMPLE 1
Try this command:
@@ -311,7 +310,7 @@ The second block of lines summarizes the results, which are not very
interesting here.
== EXAMPLE 2 ==
### EXAMPLE 2
Try another command:
@@ -343,7 +342,7 @@ identical to our first example.
Implementing Table 1: VLAN Input Processing
===========================================
-------------------------------------------
A packet that enters table 1 has already passed basic validation in
table 0. The purpose of table 1 is validate the packet's VLAN, based
@@ -375,7 +374,7 @@ along to the next stage:
table=1, priority=99, in_port=2, vlan_tci=0, actions=mod_vlan_vid:20, resubmit(,2)
table=1, priority=99, in_port=3, vlan_tci=0, actions=mod_vlan_vid:30, resubmit(,2)
table=1, priority=99, in_port=4, vlan_tci=0, actions=mod_vlan_vid:30, resubmit(,2)
EOF
EOF
We don't write any rules that match packets with 802.1Q that enter
this stage on any of the access ports, so the "default drop" rule we
@@ -387,14 +386,13 @@ want for access ports.
packets, replace "vlan_tci=0" by "vlan_tci=0/0xfff" above.
Testing Table 1
---------------
### Testing Table 1
"ofproto/trace" allows us to test the ingress VLAN rules that we added
above.
== EXAMPLE 1: Packet on Trunk Port ==
### EXAMPLE 1: Packet on Trunk Port
Here's a test of a packet coming in on the trunk port:
@@ -423,7 +421,7 @@ anything there yet):
Datapath actions: drop
== EXAMPLE 2: Valid Packet on Access Port ==
### EXAMPLE 2: Valid Packet on Access Port
Here's a test of a valid packet (a packet without an 802.1Q header)
coming in on access port p2:
@@ -453,7 +451,7 @@ along to table 2:
Datapath actions: drop
== EXAMPLE 3: Invalid Packet on Access Port ==
### EXAMPLE 3: Invalid Packet on Access Port
This tests an invalid packet (one that includes an 802.1Q header)
coming in on access port p2:
@@ -477,7 +475,7 @@ The output shows the packet matching the default drop rule:
Implementing Table 2: MAC+VLAN Learning for Ingress Port
========================================================
--------------------------------------------------------
This table allows the switch we're implementing to learn that the
packet's source MAC is located on the packet's ingress port in the
@@ -539,10 +537,9 @@ Here's how you can interpret each part of the "learn" action above:
This definitely calls for examples.
Testing Table 2
---------------
### Testing Table 2
== EXAMPLE 1 ==
### EXAMPLE 1
Try the following test command:
@@ -573,7 +570,7 @@ hexadecimal) and destination MAC 50:00:00:00:00:01. The flow loads
port number 1, the input port for the flow we tested, into register 0.
== EXAMPLE 2 ==
### EXAMPLE 2
Here's a second test command:
@@ -593,7 +590,7 @@ that the learned port is port 2, as we would expect:
Implementing Table 3: Look Up Destination Port
==============================================
----------------------------------------------
This table figures out what port we should send the packet to based on
the destination MAC and VLAN. That is, if we've learned the location
@@ -630,10 +627,9 @@ multicast and broadcast packets, since those should always be flooded:
have a multicast source address.)
Testing Table 3
---------------
### Testing Table 3
== EXAMPLE ==
### EXAMPLE
Here's a command that should cause OVS to learn that f0:00:00:00:00:01
is on p1 in VLAN 20:
@@ -705,7 +701,7 @@ then we see in the output that the destination has now been learned:
Implementing Table 4: Output Processing
=======================================
---------------------------------------
At entry to stage 4, we know that register 0 contains either the
desired output port or is zero if the packet should be flooded. We
@@ -724,7 +720,7 @@ before outputting the packet:
table=4 reg0=2 actions=strip_vlan,2
table=4 reg0=3 actions=strip_vlan,3
table=4 reg0=4 actions=strip_vlan,4
EOF
EOF
The only slightly tricky part is flooding multicast and broadcast
packets and unicast packets with unlearned destinations. For those,
@@ -737,7 +733,7 @@ ports:
table=4 reg0=0 priority=99 dl_vlan=20 actions=1,strip_vlan,2
table=4 reg0=0 priority=99 dl_vlan=30 actions=1,strip_vlan,3,4
table=4 reg0=0 priority=50 actions=1
EOF
EOF
>>> Our rules rely on the standard OpenFlow behavior that an output
action will not forward a packet back out the port it came in on.
@@ -748,10 +744,9 @@ EOF
destination cases above also rely on this behavior.
Testing Table 4
---------------
### Testing Table 4
== EXAMPLE 1: Broadcast, Multicast, and Unknown Destination ==
### EXAMPLE 1: Broadcast, Multicast, and Unknown Destination
Try tracing a broadcast packet arriving on p1 in VLAN 30:
@@ -795,7 +790,7 @@ packets whose destination has not been learned, e.g.:
ovs-appctl ofproto/trace br0 in_port=1,dl_dst=90:12:34:56:78:90,dl_vlan=30
== EXAMPLE 2: MAC Learning ==
### EXAMPLE 2: MAC Learning
Let's follow the same pattern as we did for table 3. First learn a
MAC on port p1 in VLAN 30:

2
tutorial/automake.mk
View File

@@ -1,5 +1,5 @@
EXTRA_DIST += \
tutorial/Tutorial \
tutorial/Tutorial.md \
tutorial/ovs-sandbox \
tutorial/t-setup \
tutorial/t-stage0 \

2
utilities/ovs-ctl.8
View File

@@ -441,5 +441,5 @@ distribution are good examples of how to use \fBovs\-ctl\fR.
.
.SH "SEE ALSO"
.
\fBREADME.md\fR, \fBINSTALL.Linux\fR, \fBovsdb\-server\fR(8),
\fBREADME.md\fR, \fBINSTALL.Linux.md\fR, \fBovsdb\-server\fR(8),
\fBovs\-vswitchd\fR(8).

17
vtep/README.ovs-vtep → vtep/README.ovs-vtep.md
View File

@@ -1,21 +1,21 @@
How to Use the VTEP Emulator
============================
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 file of the Open vSwitch repository
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 file and then install the
2. Follow the instructions in INSTALL.Debian.md file and then install the
"openvswitch-vtep" package (if operating on a debian based machine). This
will automatically start the daemons.
@@ -79,7 +79,7 @@ Notes:
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
@@ -115,7 +115,8 @@ step 2 of the "Requirements" section.
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 file, run the following from the same directory as this README:
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 \
@@ -132,7 +133,7 @@ step 2 of the "Requirements" section.
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

2
vtep/automake.mk
View File

@@ -19,7 +19,7 @@ scripts_SCRIPTS += \
EXTRA_DIST += \
vtep/ovs-vtep \
vtep/README.ovs-vtep
vtep/README.ovs-vtep.md
# VTEP schema and IDL
EXTRA_DIST += vtep/vtep.ovsschema