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

94
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
@@ -13,59 +13,59 @@ Before You Start
Before you send patches at all, make sure that each patch makes sense.
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.)
- 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.)
- A patch should make one logical change. Don't make
multiple, logically unconnected changes to disparate
subsystems in a single patch.
- A patch should make one logical change. Don't make
multiple, logically unconnected changes to disparate
subsystems in a single patch.
- A patch that adds or removes user-visible features should
also update the appropriate user documentation or manpages.
- A patch that adds or removes user-visible features should
also update the appropriate user documentation or manpages.
Testing is also important:
- A patch that adds or deletes files should be tested with
"make distcheck" before submission.
- A patch that adds or deletes files should be tested with
`make distcheck` before submission.
- A patch that modifies Linux kernel code should be at least
build-tested on various Linux kernel versions before
submission. I suggest versions 2.6.32 and whatever
the current latest release version is at the time.
- A patch that modifies Linux kernel code should be at least
build-tested on various Linux kernel versions before
submission. I suggest versions 2.6.32 and whatever
the current latest release version is at the time.
- A patch that modifies the ofproto or vswitchd code should be
tested in at least simple cases before submission.
- A patch that modifies the ofproto or vswitchd code should be
tested in at least simple cases before submission.
- A patch that modifies xenserver code should be tested on
XenServer before submission.
- A patch that modifies xenserver code should be tested on
XenServer before submission.
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
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.
- `[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
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.
- `<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
@@ -80,15 +80,15 @@ Please limit lines in the description to 79 characters in width.
The description should include:
- The rationale for the change.
- The rationale for the change.
- Design description and rationale (but this might be better
added as code comments).
- Design description and rationale (but this might be better
added as code comments).
- Testing that you performed (or testing that should be done
but you could not for whatever reason).
- Testing that you performed (or testing that should be done
but you could not for whatever reason).
- Tags (see below).
- Tags (see below).
There is no need to describe what the patch actually changed, if the
reader can see it for himself.
@@ -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
```

164
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.
@@ -143,15 +143,16 @@ appropriate.
parameter order is preferred. One notable exception is that data
parameters and their corresponding size parameters should be paired.
1. The primary object being manipulated, if any (equivalent to the
"this" pointer in C++).
2. Input-only parameters.
3. Input/output parameters.
4. Output-only parameters.
5. Status parameter.
1. The primary object being manipulated, if any (equivalent to the
"this" pointer in C++).
2. Input-only parameters.
3. Input/output parameters.
4. Output-only parameters.
5. Status parameter.
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
indicates a reason for failure.
* 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
failure.
* 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
other header (besides <config.h>) ensures that the module's
header file is self-contained (see HEADER FILES) below.
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
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.)
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 <>,
to specify Open vSwitch header names.
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
@@ -410,11 +412,11 @@ integer types. Use the PRId<N>, PRIu<N>, and PRIx<N> macros from
For compatibility with antique printf() implementations:
- Instead of "%zu", use "%"PRIuSIZE.
- Instead of "%zu", use "%"PRIuSIZE.
- Instead of "%td", use "%"PRIdPTR.
- Instead of "%td", use "%"PRIdPTR.
- Instead of "%ju", use "%"PRIuMAX.
- Instead of "%ju", use "%"PRIuMAX.
Other variants exist for different radixes. For example, use
"%"PRIxSIZE instead of "%zx" or "%x" instead of "%hhx".
@@ -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,46 +521,46 @@ 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:
* Flexible array members (e.g. struct { int foo[]; }).
* Flexible array members (e.g. struct { int foo[]; }).
* "static inline" functions (but no other forms of "inline", for
which GCC and C99 have differing interpretations).
* "static inline" functions (but no other forms of "inline", for
which GCC and C99 have differing interpretations).
* "long long"
* "long long"
* <stdint.h> and <inttypes.h>.
* <stdint.h> and <inttypes.h>.
* bool and <stdbool.h>, but don't assume that bool or _Bool can
only take on the values 0 or 1, because this behavior can't be
simulated on C89 compilers.
Also, don't assume that a conversion to bool or _Bool follows
C99 semantics. I.e. use "(bool)(some_value != 0)" rather than
"(bool)some_value". The latter might produce unexpected results
on non-C99 environments. For example, if bool is implemented as
a typedef of char and some_value = 0x10000000.
* bool and <stdbool.h>, but don't assume that bool or _Bool can
only take on the values 0 or 1, because this behavior can't be
simulated on C89 compilers.
Also, don't assume that a conversion to bool or _Bool follows
C99 semantics. I.e. use "(bool)(some_value != 0)" rather than
"(bool)some_value". The latter might produce unexpected results
on non-C99 environments. For example, if bool is implemented as
a typedef of char and some_value = 0x10000000.
* Designated initializers (e.g. "struct foo foo = {.a = 1};" and
"int a[] = {[2] = 5};").
* Designated initializers (e.g. "struct foo foo = {.a = 1};" and
"int a[] = {[2] = 5};").
* Mixing of declarations and code within a block. Please use this
judiciously; keep declarations nicely grouped together in the
beginning of a block if possible.
* Mixing of declarations and code within a block. Please use this
judiciously; keep declarations nicely grouped together in the
beginning of a block if possible.
* Use of declarations in iteration statements (e.g.
"for (int i = 0; i < 10; i++)").
* Use of declarations in iteration statements (e.g.
"for (int i = 0; i < 10; i++)").
* Use of a trailing comma in an enum declaration (e.g.
"enum { x = 1, };").
* Use of a trailing comma in an enum declaration (e.g.
"enum { x = 1, };").
As a matter of style, avoid // comments.

539
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
@@ -20,11 +20,11 @@ First, a service controller never receives any asynchronous messages
unless it changes its miss_send_len from the service controller
default of zero in one of the following ways:
- Sending an OFPT_SET_CONFIG message with nonzero miss_send_len.
- Sending an OFPT_SET_CONFIG message with nonzero miss_send_len.
- Sending any NXT_SET_ASYNC_CONFIG message: as a side effect, this
message changes the miss_send_len to
OFP_DEFAULT_MISS_SEND_LEN (128) for service controllers.
- Sending any NXT_SET_ASYNC_CONFIG message: as a side effect, this
message changes the miss_send_len to
OFP_DEFAULT_MISS_SEND_LEN (128) for service controllers.
Second, OFPT_FLOW_REMOVED and NXT_FLOW_REMOVED messages are generated
only if the flow that was removed had the OFPFF_SEND_FLOW_REM flag
@@ -34,11 +34,11 @@ Third, OFPT_PACKET_IN and NXT_PACKET_IN messages are sent only to
OpenFlow controller connections that have the correct connection ID
(see "struct nx_controller_id" and "struct nx_action_controller"):
- For packet-in messages generated by a NXAST_CONTROLLER action,
the controller ID specified in the action.
- For packet-in messages generated by a NXAST_CONTROLLER action,
the controller ID specified in the action.
- For other packet-in messages, controller ID zero. (This is the
default ID when an OpenFlow controller does not configure one.)
- For other packet-in messages, controller ID zero. (This is the
default ID when an OpenFlow controller does not configure one.)
Finally, Open vSwitch consults a per-connection table indexed by the
message type, reason code, and current role. The following table
@@ -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
@@ -88,50 +90,50 @@ The OpenFlow specification for the behavior of OFPT_FLOW_MOD is
confusing. The following tables summarize the Open vSwitch
implementation of its behavior in the following categories:
- "match on priority": Whether the flow_mod acts only on flows
whose priority matches that included in the flow_mod message.
- "match on priority": Whether the flow_mod acts only on flows
whose priority matches that included in the flow_mod message.
- "match on out_port": Whether the flow_mod acts only on flows
that output to the out_port included in the flow_mod message (if
out_port is not OFPP_NONE). OpenFlow 1.1 and later have a
similar feature (not listed separately here) for out_group.
- "match on out_port": Whether the flow_mod acts only on flows
that output to the out_port included in the flow_mod message (if
out_port is not OFPP_NONE). OpenFlow 1.1 and later have a
similar feature (not listed separately here) for out_group.
- "match on flow_cookie": Whether the flow_mod acts only on flows
whose flow_cookie matches an optional controller-specified value
and mask.
- "match on flow_cookie": Whether the flow_mod acts only on flows
whose flow_cookie matches an optional controller-specified value
and mask.
- "updates flow_cookie": Whether the flow_mod changes the
flow_cookie of the flow or flows that it matches to the
flow_cookie included in the flow_mod message.
- "updates flow_cookie": Whether the flow_mod changes the
flow_cookie of the flow or flows that it matches to the
flow_cookie included in the flow_mod message.
- "updates OFPFF_ flags": Whether the flow_mod changes the
OFPFF_SEND_FLOW_REM flag of the flow or flows that it matches to
the setting included in the flags of the flow_mod message.
- "updates OFPFF_ flags": Whether the flow_mod changes the
OFPFF_SEND_FLOW_REM flag of the flow or flows that it matches to
the setting included in the flags of the flow_mod message.
- "honors OFPFF_CHECK_OVERLAP": Whether the OFPFF_CHECK_OVERLAP
flag in the flow_mod is significant.
- "honors OFPFF_CHECK_OVERLAP": Whether the OFPFF_CHECK_OVERLAP
flag in the flow_mod is significant.
- "updates idle_timeout" and "updates hard_timeout": Whether the
idle_timeout and hard_timeout in the flow_mod, respectively,
have an effect on the flow or flows matched by the flow_mod.
- "updates idle_timeout" and "updates hard_timeout": Whether the
idle_timeout and hard_timeout in the flow_mod, respectively,
have an effect on the flow or flows matched by the flow_mod.
- "updates idle timer": Whether the flow_mod resets the per-flow
timer that measures how long a flow has been idle.
- "updates idle timer": Whether the flow_mod resets the per-flow
timer that measures how long a flow has been idle.
- "updates hard timer": Whether the flow_mod resets the per-flow
timer that measures how long it has been since a flow was
modified.
- "updates hard timer": Whether the flow_mod resets the per-flow
timer that measures how long it has been since a flow was
modified.
- "zeros counters": Whether the flow_mod resets per-flow packet
and byte counters to zero.
- "zeros counters": Whether the flow_mod resets per-flow packet
and byte counters to zero.
- "may add a new flow": Whether the flow_mod may add a new flow to
the flow table. (Obviously this is always true for "add"
commands but in some OpenFlow versions "modify" and
"modify-strict" can also add new flows.)
- "may add a new flow": Whether the flow_mod may add a new flow to
the flow table. (Obviously this is always true for "add"
commands but in some OpenFlow versions "modify" and
"modify-strict" can also add new flows.)
- "sends flow_removed message": Whether the flow_mod generates a
flow_removed message for the flow or flows that it affects.
- "sends flow_removed message": Whether the flow_mod generates a
flow_removed message for the flow or flows that it affects.
An entry labeled "yes" means that the flow mod type does have the
indicated behavior, "---" means that it does not, an empty cell means
@@ -141,6 +143,7 @@ below the table.
OpenFlow 1.0
------------
```
MODIFY DELETE
ADD MODIFY STRICT DELETE STRICT
=== ====== ====== ====== ======
@@ -167,21 +170,23 @@ 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
------------
OpenFlow 1.1 makes these changes:
- The controller now must specify the table_id of the flow match
searched and into which a flow may be inserted. Behavior for a
table_id of 255 is undefined.
- The controller now must specify the table_id of the flow match
searched and into which a flow may be inserted. Behavior for a
table_id of 255 is undefined.
- A flow_mod, except an "add", can now match on the flow_cookie.
- A flow_mod, except an "add", can now match on the flow_cookie.
- When a flow_mod matches on the flow_cookie, "modify" and
"modify-strict" never insert a new flow.
- 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,19 +216,21 @@ 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
------------
OpenFlow 1.2 makes these changes:
- Only "add" commands ever add flows, "modify" and "modify-strict"
never do.
- Only "add" commands ever add flows, "modify" and "modify-strict"
never do.
- A new flag OFPFF_RESET_COUNTS now controls whether "modify" and
"modify-strict" reset counters, whereas previously they never
reset counters (except when they inserted a new flow).
- A new flag OFPFF_RESET_COUNTS now controls whether "modify" and
"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,18 +257,19 @@ sends flow_removed message --- --- --- % %
(&) "modify" and "modify-strict" reset counters if the
OFPFF_RESET_COUNTS flag is specified.
```
OpenFlow 1.3
------------
OpenFlow 1.3 makes these changes:
- Behavior for a table_id of 255 is now defined, for "delete" and
"delete-strict" commands, as meaning to delete from all tables.
A table_id of 255 is now explicitly invalid for other commands.
- Behavior for a table_id of 255 is now defined, for "delete" and
"delete-strict" commands, as meaning to delete from all tables.
A table_id of 255 is now explicitly invalid for other commands.
- New flags OFPFF_NO_PKT_COUNTS and OFPFF_NO_BYT_COUNTS for "add"
operations.
- New flags OFPFF_NO_PKT_COUNTS and OFPFF_NO_BYT_COUNTS for "add"
operations.
The table for 1.3 is the same as the one shown above for 1.2.
@@ -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:
@@ -343,25 +353,25 @@ version works.
Each column is interpreted as follows.
- Match: See the list below.
- Match: See the list below.
- NXM: xxxx/yyyy means NXM_OF_VLAN_TCI_W with value xxxx and mask
yyyy. A mask of 0000 is equivalent to omitting
NXM_OF_VLAN_TCI(_W), a mask of ffff is equivalent to
NXM_OF_VLAN_TCI.
- NXM: xxxx/yyyy means NXM_OF_VLAN_TCI_W with value xxxx and mask
yyyy. A mask of 0000 is equivalent to omitting
NXM_OF_VLAN_TCI(_W), a mask of ffff is equivalent to
NXM_OF_VLAN_TCI.
- OF1.0 and OF1.1: wwww/x,yy/z means dl_vlan wwww, OFPFW_DL_VLAN
x, dl_vlan_pcp yy, and OFPFW_DL_VLAN_PCP z. ? means that the
given nibble is ignored (and conventionally 0 for wwww or yy,
conventionally 1 for x or z). <none> means that the given match
is not supported.
- OF1.0 and OF1.1: wwww/x,yy/z means dl_vlan wwww, OFPFW_DL_VLAN
x, dl_vlan_pcp yy, and OFPFW_DL_VLAN_PCP z. ? means that the
given nibble is ignored (and conventionally 0 for wwww or yy,
conventionally 1 for x or z). <none> means that the given match
is not supported.
- OF1.2: xxxx/yyyy,zz means OXM_OF_VLAN_VID_W with value xxxx and
mask yyyy, and OXM_OF_VLAN_PCP (which is not maskable) with
value zz. A mask of 0000 is equivalent to omitting
OXM_OF_VLAN_VID(_W), a mask of ffff is equivalent to
OXM_OF_VLAN_VID. -- means that OXM_OF_VLAN_PCP is omitted.
<none> means that the given match is not supported.
- OF1.2: xxxx/yyyy,zz means OXM_OF_VLAN_VID_W with value xxxx and
mask yyyy, and OXM_OF_VLAN_PCP (which is not maskable) with
value zz. A mask of 0000 is equivalent to omitting
OXM_OF_VLAN_VID(_W), a mask of ffff is equivalent to
OXM_OF_VLAN_VID. -- means that OXM_OF_VLAN_PCP is omitted.
<none> means that the given match is not supported.
The matches are:
@@ -426,12 +436,12 @@ The matches are:
Additional notes:
- OF1.2: The top three bits of OXM_OF_VLAN_VID are fixed to zero,
so bits 13, 14, and 15 in the masks listed in the table may be
set to arbitrary values, as long as the corresponding value bits
are also zero. The suggested ffff mask for [2], [3], and [5]
allows a shorter OXM representation (the mask is omitted) than
the minimal 1fff mask.
- OF1.2: The top three bits of OXM_OF_VLAN_VID are fixed to zero,
so bits 13, 14, and 15 in the masks listed in the table may be
set to arbitrary values, as long as the corresponding value bits
are also zero. The suggested ffff mask for [2], [3], and [5]
allows a shorter OXM representation (the mask is omitted) than
the minimal 1fff mask.
Flow Cookies
@@ -444,70 +454,71 @@ however.
In OpenFlow 1.0:
- OFPFC_ADD set the cookie in the flow that it added.
- OFPFC_ADD set the cookie in the flow that it added.
- OFPFC_MODIFY and OFPFC_MODIFY_STRICT updated the cookie for
the flow or flows that it modified.
- OFPFC_MODIFY and OFPFC_MODIFY_STRICT updated the cookie for
the flow or flows that it modified.
- OFPST_FLOW messages included the flow cookie.
- OFPST_FLOW messages included the flow cookie.
- OFPT_FLOW_REMOVED messages reported the cookie of the flow
that was removed.
- OFPT_FLOW_REMOVED messages reported the cookie of the flow
that was removed.
OpenFlow 1.1 made the following changes:
- Flow mod operations OFPFC_MODIFY, OFPFC_MODIFY_STRICT,
OFPFC_DELETE, and OFPFC_DELETE_STRICT, plus flow stats
requests and aggregate stats requests, gained the ability to
match on flow cookies with an arbitrary mask.
- Flow mod operations OFPFC_MODIFY, OFPFC_MODIFY_STRICT,
OFPFC_DELETE, and OFPFC_DELETE_STRICT, plus flow stats
requests and aggregate stats requests, gained the ability to
match on flow cookies with an arbitrary mask.
- OFPFC_MODIFY and OFPFC_MODIFY_STRICT were changed to add a
new flow, in the case of no match, only if the flow table
modification operation did not match on the cookie field.
(In OpenFlow 1.0, modify operations always added a new flow
when there was no match.)
- OFPFC_MODIFY and OFPFC_MODIFY_STRICT were changed to add a
new flow, in the case of no match, only if the flow table
modification operation did not match on the cookie field.
(In OpenFlow 1.0, modify operations always added a new flow
when there was no match.)
- OFPFC_MODIFY and OFPFC_MODIFY_STRICT no longer updated flow
cookies.
- OFPFC_MODIFY and OFPFC_MODIFY_STRICT no longer updated flow
cookies.
OpenFlow 1.2 made the following changes:
- OFPC_MODIFY and OFPFC_MODIFY_STRICT were changed to never
add a new flow, regardless of whether the flow cookie was
used for matching.
- OFPC_MODIFY and OFPFC_MODIFY_STRICT were changed to never
add a new flow, regardless of whether the flow cookie was
used for matching.
Open vSwitch support for OpenFlow 1.0 implements the OpenFlow 1.0
behavior with the following extensions:
- An NXM extension field NXM_NX_COOKIE(_W) allows the NXM
versions of OFPFC_MODIFY, OFPFC_MODIFY_STRICT, OFPFC_DELETE,
and OFPFC_DELETE_STRICT flow_mods, plus flow stats requests
and aggregate stats requests, to match on flow cookies with
arbitrary masks. This is much like the equivalent OpenFlow
1.1 feature.
- An NXM extension field NXM_NX_COOKIE(_W) allows the NXM
versions of OFPFC_MODIFY, OFPFC_MODIFY_STRICT, OFPFC_DELETE,
and OFPFC_DELETE_STRICT flow_mods, plus flow stats requests
and aggregate stats requests, to match on flow cookies with
arbitrary masks. This is much like the equivalent OpenFlow
1.1 feature.
- Like OpenFlow 1.1, OFPC_MODIFY and OFPFC_MODIFY_STRICT add a
new flow if there is no match and the mask is zero (or not
given).
- Like OpenFlow 1.1, OFPC_MODIFY and OFPFC_MODIFY_STRICT add a
new flow if there is no match and the mask is zero (or not
given).
- The "cookie" field in OFPT_FLOW_MOD and NXT_FLOW_MOD messages
is used as the cookie value for OFPFC_ADD commands, as
described in OpenFlow 1.0. For OFPFC_MODIFY and
OFPFC_MODIFY_STRICT commands, the "cookie" field is used as a
new cookie for flows that match unless it is UINT64_MAX, in
which case the flow's cookie is not updated.
- The "cookie" field in OFPT_FLOW_MOD and NXT_FLOW_MOD messages
is used as the cookie value for OFPFC_ADD commands, as
described in OpenFlow 1.0. For OFPFC_MODIFY and
OFPFC_MODIFY_STRICT commands, the "cookie" field is used as a
new cookie for flows that match unless it is UINT64_MAX, in
which case the flow's cookie is not updated.
- NXT_PACKET_IN (the Nicira extended version of
OFPT_PACKET_IN) reports the cookie of the rule that
generated the packet, or all-1-bits if no rule generated the
packet. (Older versions of OVS used all-0-bits instead of
all-1-bits.)
- NXT_PACKET_IN (the Nicira extended version of
OFPT_PACKET_IN) reports the cookie of the rule that
generated the packet, or all-1-bits if no rule generated the
packet. (Older versions of OVS used all-0-bits instead of
all-1-bits.)
The following table shows the handling of different protocols when
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
======================
@@ -567,11 +578,11 @@ understood.
Open vSwitch will process the following extension headers and continue
to the next header:
* Fragment (see the next section)
* AH (Authentication Header)
* Hop-by-Hop Options
* Routing
* Destination Options
* Fragment (see the next section)
* AH (Authentication Header)
* Hop-by-Hop Options
* Routing
* Destination Options
When a header is encountered that is not in that list, it is considered
"terminal". A terminal header's IPv6 protocol value is stored in
@@ -617,28 +628,28 @@ former case "out-of-band control", the latter case "in-band control".
Out-of-band control has the following benefits:
- Simplicity: Out-of-band control slightly simplifies the switch
implementation.
- Simplicity: Out-of-band control slightly simplifies the switch
implementation.
- Reliability: Excessive switch traffic volume cannot interfere
with control traffic.
- Reliability: Excessive switch traffic volume cannot interfere
with control traffic.
- Integrity: Machines not on the control network cannot
impersonate a switch or a controller.
- Integrity: Machines not on the control network cannot
impersonate a switch or a controller.
- Confidentiality: Machines not on the control network cannot
snoop on control traffic.
- Confidentiality: Machines not on the control network cannot
snoop on control traffic.
In-band control, on the other hand, has the following advantages:
- No dedicated port: There is no need to dedicate a physical
switch port to control, which is important on switches that have
few ports (e.g. wireless routers, low-end embedded platforms).
- No dedicated port: There is no need to dedicate a physical
switch port to control, which is important on switches that have
few ports (e.g. wireless routers, low-end embedded platforms).
- No dedicated network: There is no need to build and maintain a
separate control network. This is important in many
environments because it reduces proliferation of switches and
wiring.
- No dedicated network: There is no need to build and maintain a
separate control network. This is important in many
environments because it reduces proliferation of switches and
wiring.
Open vSwitch supports both out-of-band and in-band control. This
section describes the principles behind in-band control. See the
@@ -662,77 +673,77 @@ the controller.
The following points describe important special cases of this
principle.
- In-band control must be implemented regardless of whether the
switch is connected.
- In-band control must be implemented regardless of whether the
switch is connected.
It is tempting to implement the in-band control rules only when
the switch is not connected to the controller, using the
reasoning that the controller should have complete control once
it has established a connection with the switch.
It is tempting to implement the in-band control rules only when
the switch is not connected to the controller, using the
reasoning that the controller should have complete control once
it has established a connection with the switch.
This does not work in practice. Consider the case where the
switch is connected to the controller. Occasionally it can
happen that the controller forgets or otherwise needs to obtain
the MAC address of the switch. To do so, the controller sends a
broadcast ARP request. A switch that implements the in-band
control rules only when it is disconnected will then send an
OFPT_PACKET_IN message up to the controller. The controller will
be unable to respond, because it does not know the MAC address of
the switch. This is a deadlock situation that can only be
resolved by the switch noticing that its connection to the
controller has hung and reconnecting.
This does not work in practice. Consider the case where the
switch is connected to the controller. Occasionally it can
happen that the controller forgets or otherwise needs to obtain
the MAC address of the switch. To do so, the controller sends a
broadcast ARP request. A switch that implements the in-band
control rules only when it is disconnected will then send an
OFPT_PACKET_IN message up to the controller. The controller will
be unable to respond, because it does not know the MAC address of
the switch. This is a deadlock situation that can only be
resolved by the switch noticing that its connection to the
controller has hung and reconnecting.
- In-band control must override flows set up by the controller.
- In-band control must override flows set up by the controller.
It is reasonable to assume that flows set up by the OpenFlow
controller should take precedence over in-band control, on the
basis that the controller should be in charge of the switch.
It is reasonable to assume that flows set up by the OpenFlow
controller should take precedence over in-band control, on the
basis that the controller should be in charge of the switch.
Again, this does not work in practice. Reasonable controller
implementations may set up a "last resort" fallback rule that
wildcards every field and, e.g., sends it up to the controller or
discards it. If a controller does that, then it will isolate
itself from the switch.
Again, this does not work in practice. Reasonable controller
implementations may set up a "last resort" fallback rule that
wildcards every field and, e.g., sends it up to the controller or
discards it. If a controller does that, then it will isolate
itself from the switch.
- The switch must recognize all control traffic.
- The switch must recognize all control traffic.
The fundamental principle of in-band control states, in part,
that a switch must recognize control traffic without involving
the OpenFlow controller. More specifically, the switch must
recognize *all* control traffic. "False negatives", that is,
packets that constitute control traffic but that the switch does
not recognize as control traffic, lead to control traffic storms.
The fundamental principle of in-band control states, in part,
that a switch must recognize control traffic without involving
the OpenFlow controller. More specifically, the switch must
recognize *all* control traffic. "False negatives", that is,
packets that constitute control traffic but that the switch does
not recognize as control traffic, lead to control traffic storms.
Consider an OpenFlow switch that only recognizes control packets
sent to or from that switch. Now suppose that two switches of
this type, named A and B, are connected to ports on an Ethernet
hub (not a switch) and that an OpenFlow controller is connected
to a third hub port. In this setup, control traffic sent by
switch A will be seen by switch B, which will send it to the
controller as part of an OFPT_PACKET_IN message. Switch A will
then see the OFPT_PACKET_IN message's packet, re-encapsulate it
in another OFPT_PACKET_IN, and send it to the controller. Switch
B will then see that OFPT_PACKET_IN, and so on in an infinite
loop.
Consider an OpenFlow switch that only recognizes control packets
sent to or from that switch. Now suppose that two switches of
this type, named A and B, are connected to ports on an Ethernet
hub (not a switch) and that an OpenFlow controller is connected
to a third hub port. In this setup, control traffic sent by
switch A will be seen by switch B, which will send it to the
controller as part of an OFPT_PACKET_IN message. Switch A will
then see the OFPT_PACKET_IN message's packet, re-encapsulate it
in another OFPT_PACKET_IN, and send it to the controller. Switch
B will then see that OFPT_PACKET_IN, and so on in an infinite
loop.
Incidentally, the consequences of "false positives", where
packets that are not control traffic are nevertheless recognized
as control traffic, are much less severe. The controller will
not be able to control their behavior, but the network will
remain in working order. False positives do constitute a
security problem.
Incidentally, the consequences of "false positives", where
packets that are not control traffic are nevertheless recognized
as control traffic, are much less severe. The controller will
not be able to control their behavior, but the network will
remain in working order. False positives do constitute a
security problem.
- The switch should use echo-requests to detect disconnection.
- The switch should use echo-requests to detect disconnection.
TCP will notice that a connection has hung, but this can take a
considerable amount of time. For example, with default settings
the Linux kernel TCP implementation will retransmit for between
13 and 30 minutes, depending on the connection's retransmission
timeout, according to kernel documentation. This is far too long
for a switch to be disconnected, so an OpenFlow switch should
implement its own connection timeout. OpenFlow OFPT_ECHO_REQUEST
messages are the best way to do this, since they test the
OpenFlow connection itself.
TCP will notice that a connection has hung, but this can take a
considerable amount of time. For example, with default settings
the Linux kernel TCP implementation will retransmit for between
13 and 30 minutes, depending on the connection's retransmission
timeout, according to kernel documentation. This is far too long
for a switch to be disconnected, so an OpenFlow switch should
implement its own connection timeout. OpenFlow OFPT_ECHO_REQUEST
messages are the best way to do this, since they test the
OpenFlow connection itself.
Implementation
--------------
@@ -831,67 +842,67 @@ With a few notable exceptions below, in-band should work in most
network setups. The following are considered "supported' in the
current implementation:
- Locally Connected. The switch and remote are on the same
subnet. This uses rules (a), (b), (c), (h), and (i).
- Locally Connected. The switch and remote are on the same
subnet. This uses rules (a), (b), (c), (h), and (i).
- Reached through Gateway. The switch and remote are on
different subnets and must go through a gateway. This uses
rules (a), (b), (c), (h), and (i).
- Reached through Gateway. The switch and remote are on
different subnets and must go through a gateway. This uses
rules (a), (b), (c), (h), and (i).
- Between Switch and Remote. This switch is between another
switch and the remote, and we want to allow the other
switch's traffic through. This uses rules (d), (e), (h), and
(i). It uses (b) and (c) indirectly in order to know the MAC
address for rules (d) and (e). Note that DHCP for the other
switch will not work unless an OpenFlow controller explicitly lets this
switch pass the traffic.
- Between Switch and Remote. This switch is between another
switch and the remote, and we want to allow the other
switch's traffic through. This uses rules (d), (e), (h), and
(i). It uses (b) and (c) indirectly in order to know the MAC
address for rules (d) and (e). Note that DHCP for the other
switch will not work unless an OpenFlow controller explicitly lets this
switch pass the traffic.
- Between Switch and Gateway. This switch is between another
switch and the gateway, and we want to allow the other switch's
traffic through. This uses the same rules and logic as the
"Between Switch and Remote" configuration described earlier.
- Between Switch and Gateway. This switch is between another
switch and the gateway, and we want to allow the other switch's
traffic through. This uses the same rules and logic as the
"Between Switch and Remote" configuration described earlier.
- Remote on Local VM. The remote is a guest VM on the
system running in-band control. This uses rules (a), (b), (c),
(h), and (i).
- Remote on Local VM. The remote is a guest VM on the
system running in-band control. This uses rules (a), (b), (c),
(h), and (i).
- Remote on Local VM with Different Networks. The remote
is a guest VM on the system running in-band control, but the
local port is not used to connect to the remote. For
example, an IP address is configured on eth0 of the switch. The
remote's VM is connected through eth1 of the switch, but an
IP address has not been configured for that port on the switch.
As such, the switch will use eth0 to connect to the remote,
and eth1's rules about the local port will not work. In the
example, the switch attached to eth0 would use rules (a), (b),
(c), (h), and (i) on eth0. The switch attached to eth1 would use
rules (f), (g), (h), and (i).
- Remote on Local VM with Different Networks. The remote
is a guest VM on the system running in-band control, but the
local port is not used to connect to the remote. For
example, an IP address is configured on eth0 of the switch. The
remote's VM is connected through eth1 of the switch, but an
IP address has not been configured for that port on the switch.
As such, the switch will use eth0 to connect to the remote,
and eth1's rules about the local port will not work. In the
example, the switch attached to eth0 would use rules (a), (b),
(c), (h), and (i) on eth0. The switch attached to eth1 would use
rules (f), (g), (h), and (i).
The following are explicitly *not* supported by in-band control:
- Specify Remote by Name. Currently, the remote must be
identified by IP address. A naive approach would be to permit
all DNS traffic. Unfortunately, this would prevent the
controller from defining any policy over DNS. Since switches
that are located behind us need to connect to the remote,
in-band cannot simply add a rule that allows DNS traffic from
the local port. The "correct" way to support this is to parse
DNS requests to allow all traffic related to a request for the
remote's name through. Due to the potential security
problems and amount of processing, we decided to hold off for
the time-being.
- Specify Remote by Name. Currently, the remote must be
identified by IP address. A naive approach would be to permit
all DNS traffic. Unfortunately, this would prevent the
controller from defining any policy over DNS. Since switches
that are located behind us need to connect to the remote,
in-band cannot simply add a rule that allows DNS traffic from
the local port. The "correct" way to support this is to parse
DNS requests to allow all traffic related to a request for the
remote's name through. Due to the potential security
problems and amount of processing, we decided to hold off for
the time-being.
- Differing Remotes for Switches. All switches must know
the L3 addresses for all the remotes that other switches
may use, since rules need to be set up to allow traffic related
to those remotes through. See rules (f), (g), (h), and (i).
- Differing Remotes for Switches. All switches must know
the L3 addresses for all the remotes that other switches
may use, since rules need to be set up to allow traffic related
to those remotes through. See rules (f), (g), (h), and (i).
- Differing Routes for Switches. In order for the switch to
allow other switches to connect to a remote through a
gateway, it allows the gateway's traffic through with rules (d)
and (e). If the routes to the remote differ for the two
switches, we will not know the MAC address of the alternate
gateway.
- Differing Routes for Switches. In order for the switch to
allow other switches to connect to a remote through a
gateway, it allows the gateway's traffic through with rules (d)
and (e). If the routes to the remote differ for the two
switches, we will not know the MAC address of the alternate
gateway.
Action Reproduction
@@ -907,21 +918,21 @@ some exceptional cases. This section lists the exceptions that
controller authors must keep in mind if they compare actual actions
against desired actions in a bytewise fashion:
- Open vSwitch zeros padding bytes in action structures,
regardless of their values when the flows were added.
- Open vSwitch zeros padding bytes in action structures,
regardless of their values when the flows were added.
- Open vSwitch "normalizes" the instructions in OpenFlow 1.1
(and later) in the following way:
- Open vSwitch "normalizes" the instructions in OpenFlow 1.1
(and later) in the following way:
* OVS sorts the instructions into the following order:
Apply-Actions, Clear-Actions, Write-Actions,
Write-Metadata, Goto-Table.
* OVS sorts the instructions into the following order:
Apply-Actions, Clear-Actions, Write-Actions,
Write-Metadata, Goto-Table.
* OVS drops Apply-Actions instructions that have empty
action lists.
* OVS drops Apply-Actions instructions that have empty
action lists.
* OVS drops Write-Actions instructions that have empty
action sets.
* OVS drops Write-Actions instructions that have empty
action sets.
Please report other discrepancies, if you notice any, so that we can
fix or document them.

648
FAQ → FAQ.md
View File

File diff suppressed because it is too large Load Diff

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

24
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
@@ -20,43 +20,43 @@ Setup
First, create the Open vSwitch bridge by using the ovs-vsctl utility (this
must be done with administrative privileges):
% ovs-vsctl add-br ovsbr
% ovs-vsctl add-br ovsbr
Once that is done, create a VM, if necessary, and edit its Domain XML file:
% virsh edit <vm>
% 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
the ovsbr bridge.
% ovs-vsctl show
% ovs-vsctl show
Troubleshooting
---------------

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

108
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
@@ -29,21 +29,21 @@ private/public key pair and a certificate that signs that public key.
Typically, the Open vSwitch generates its own public/private key pair.
There are two common ways to obtain a certificate for a switch:
* Self-signed certificates: The Open vSwitch signs its certificate
with its own private key. In this case, each switch must be
individually approved by the OpenFlow controller(s), since there
is no central authority.
* Self-signed certificates: The Open vSwitch signs its certificate
with its own private key. In this case, each switch must be
individually approved by the OpenFlow controller(s), since there
is no central authority.
This is the only switch PKI model currently supported by NOX
(http://noxrepo.org).
This is the only switch PKI model currently supported by NOX
(http://noxrepo.org).
* Switch certificate authority: A certificate authority (the
"switch CA") signs each Open vSwitch's public key. The OpenFlow
controllers then check that any connecting switches'
certificates are signed by that certificate authority.
* Switch certificate authority: A certificate authority (the
"switch CA") signs each Open vSwitch's public key. The OpenFlow
controllers then check that any connecting switches'
certificates are signed by that certificate authority.
This is the only switch PKI model supported by the simple
OpenFlow controller included with Open vSwitch.
This is the only switch PKI model supported by the simple
OpenFlow controller included with Open vSwitch.
Each Open vSwitch must also have a copy of the CA certificate for the
certificate authority that signs OpenFlow controllers' keys (the
@@ -52,15 +52,15 @@ certificate is installed on all of the switches within a given
administrative unit. There are two common ways for a switch to obtain
the controller CA certificate:
* Manually copy the certificate to the switch through some secure
means, e.g. using a USB flash drive, or over the network with
"scp", or even FTP or HTTP followed by manual verification.
* Manually copy the certificate to the switch through some secure
means, e.g. using a USB flash drive, or over the network with
"scp", or even FTP or HTTP followed by manual verification.
* Open vSwitch "bootstrap" mode, in which Open vSwitch accepts and
saves the controller CA certificate that it obtains from the
OpenFlow controller on its first connection. Thereafter the
switch will only connect to controllers signed by the same CA
certificate.
* Open vSwitch "bootstrap" mode, in which Open vSwitch accepts and
saves the controller CA certificate that it obtains from the
OpenFlow controller on its first connection. Thereafter the
switch will only connect to controllers signed by the same CA
certificate.
Establishing a Public Key Infrastructure
----------------------------------------
@@ -82,24 +82,24 @@ The pki directory contains two important subdirectories. The
controllerca subdirectory contains controller CA files, including the
following:
- cacert.pem: Root certificate for the controller certificate
authority. Each Open vSwitch must have a copy of this file to
allow it to authenticate valid controllers.
- cacert.pem: Root certificate for the controller certificate
authority. Each Open vSwitch must have a copy of this file to
allow it to authenticate valid controllers.
- private/cakey.pem: Private signing key for the controller
certificate authority. This file must be kept secret. There is
no need for switches or controllers to have a copy of it.
- private/cakey.pem: Private signing key for the controller
certificate authority. This file must be kept secret. There is
no need for switches or controllers to have a copy of it.
The switchca subdirectory contains switch CA files, analogous to those
in the controllerca subdirectory:
- cacert.pem: Root certificate for the switch certificate
authority. The OpenFlow controller must have this file to
enable it to authenticate valid switches.
- cacert.pem: Root certificate for the switch certificate
authority. The OpenFlow controller must have this file to
enable it to authenticate valid switches.
- private/cakey.pem: Private signing key for the switch
certificate authority. This file must be kept secret. There is
no need for switches or controllers to have a copy of it.
- private/cakey.pem: Private signing key for the switch
certificate authority. This file must be kept secret. There is
no need for switches or controllers to have a copy of it.
After you create the initial structure, you can create keys and
certificates for switches and controllers with ovs-pki. Refer to the
@@ -141,12 +141,12 @@ your controller to approve.
The "ovs-pki self-sign" command has the following output:
* sc-privkey.pem, the switch private key file. For security,
the contents of this file must remain secret. There is
ordinarily no need to copy this file off the Open vSwitch.
* sc-privkey.pem, the switch private key file. For security,
the contents of this file must remain secret. There is
ordinarily no need to copy this file off the Open vSwitch.
* sc-cert.pem, the switch certificate, signed by the switch's
own private key. Its contents are not a secret.
* sc-cert.pem, the switch certificate, signed by the switch's
own private key. Its contents are not a secret.
2. Optionally, copy controllerca/cacert.pem from the machine that has
the OpenFlow PKI structure and verify that it is correct.
@@ -170,11 +170,11 @@ from the machine hosting the PKI to the switch.
This command has the following output:
* sc-privkey.pem, the switch private key file. For
security, the contents of this file must remain secret.
* sc-privkey.pem, the switch private key file. For
security, the contents of this file must remain secret.
* sc-cert.pem, the switch certificate. Its contents are
not a secret.
* sc-cert.pem, the switch certificate. Its contents are
not a secret.
2. Copy sc-privkey.pem and sc-cert.pem, plus controllerca/cacert.pem,
to the Open vSwitch.
@@ -211,15 +211,15 @@ more secure.
The "ovs-pki req" command has the following output:
* sc-privkey.pem, the switch private key file. For security,
the contents of this file must remain secret. There is
ordinarily no need to copy this file off the Open vSwitch.
* sc-privkey.pem, the switch private key file. For security,
the contents of this file must remain secret. There is
ordinarily no need to copy this file off the Open vSwitch.
* sc-req.pem, the switch "certificate request", which is
essentially the switch's public key. Its contents are not a
secret.
* sc-req.pem, the switch "certificate request", which is
essentially the switch's public key. Its contents are not a
secret.
* A fingerprint, on stdout.
* A fingerprint, on stdout.
2. Write the fingerprint down on a slip of paper and copy sc-req.pem
to the machine that contains the PKI structure.
@@ -280,10 +280,10 @@ switches in a given administrative unit. If you used the
instructions above to build your PKI, then this file will be named
cacert.pem:
- The root certificate for the controller certificate authority.
The Open vSwitch verifies it that is authorized to connect to an
OpenFlow controller by verifying a signature against this CA
certificate.
- The root certificate for the controller certificate authority.
The Open vSwitch verifies it that is authorized to connect to an
OpenFlow controller by verifying a signature against this CA
certificate.
Once you have these files, configure ovs-vswitchd to use them using
the ovs-vsctl "set-ssl" command, e.g.:

24
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++:
---------------------------------
@@ -52,16 +52,16 @@ or from a distribution tar ball.
* If you pulled the sources directly from an Open vSwitch Git tree,
run boot.sh in the top source directory:
% ./boot.sh
% ./boot.sh
* In the top source directory, configure the package by running the
configure script. You should provide some configure options to choose
the right compiler, linker, libraries, Open vSwitch component installation
directories, etc. 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"
% ./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"
By default, the above enables compiler optimization for fast code.
For default compiler optimization, pass the "--with-debug" configure
@@ -69,11 +69,11 @@ or from a distribution tar ball.
* Run make for the ported executables in the top source directory, e.g.:
% make
% make
* To run all the unit tests:
% make check
% make check
OpenSSL, Open vSwitch and Visual C++
------------------------------------
@@ -90,10 +90,10 @@ Note down the directory where OpenSSL is installed (e.g.: C:/OpenSSL-Win32).
* While configuring the package, specify the OpenSSL directory path.
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"
% ./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"
* 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.

236
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
------------------
@@ -18,28 +18,28 @@ Build Requirements
To compile the userspace programs in the Open vSwitch distribution,
you will need the following software:
- GNU make.
- GNU make.
- A C compiler, such as:
- A C compiler, such as:
* GCC 4.x.
* GCC 4.x.
* Clang. Clang 3.4 and later provide useful static semantic
analysis and thread-safety checks. For Ubuntu, there are
nightly built packages available on clang's website.
* Clang. Clang 3.4 and later provide useful static semantic
analysis and thread-safety checks. For Ubuntu, there are
nightly built packages available on clang's website.
While OVS may be compatible with other compilers, optimal
support for atomic operations may be missing, making OVS very
slow (see lib/ovs-atomic.h).
While OVS may be compatible with other compilers, optimal
support for atomic operations may be missing, making OVS very
slow (see lib/ovs-atomic.h).
- libssl, from OpenSSL, is optional but recommended if you plan to
connect the Open vSwitch to an OpenFlow controller. libssl is
required to establish confidentiality and authenticity in the
connections from an Open vSwitch to an OpenFlow controller. If
libssl is installed, then Open vSwitch will automatically build
with support for it.
- libssl, from OpenSSL, is optional but recommended if you plan to
connect the Open vSwitch to an OpenFlow controller. libssl is
required to establish confidentiality and authenticity in the
connections from an Open vSwitch to an OpenFlow controller. If
libssl is installed, then Open vSwitch will automatically build
with support for it.
- Python 2.x, for x >= 4.
- Python 2.x, for x >= 4.
On Linux, you may choose to compile the kernel module that comes with
the Open vSwitch distribution or to use the kernel module built into
@@ -51,76 +51,76 @@ at some cost in features and performance (see INSTALL.userspace for
details). To compile the kernel module on Linux, you must also
install the following:
- A supported Linux kernel version. Please refer to README.md for a
list of supported versions.
- A supported Linux kernel version. Please refer to README.md for a
list of supported versions.
The Open vSwitch datapath requires bridging support
(CONFIG_BRIDGE) to be built as a kernel module. (This is common
in kernels provided by Linux distributions.) The bridge module
must not be loaded or in use. If the bridge module is running
(check with "lsmod | grep bridge"), you must remove it ("rmmod
bridge") before starting the datapath.
The Open vSwitch datapath requires bridging support
(CONFIG_BRIDGE) to be built as a kernel module. (This is common
in kernels provided by Linux distributions.) The bridge module
must not be loaded or in use. If the bridge module is running
(check with "lsmod | grep bridge"), you must remove it ("rmmod
bridge") before starting the datapath.
For optional support of ingress policing, you must enable kernel
configuration options NET_CLS_BASIC, NET_SCH_INGRESS, and
NET_ACT_POLICE, either built-in or as modules. (NET_CLS_POLICE is
obsolete and not needed.)
For optional support of ingress policing, you must enable kernel
configuration options NET_CLS_BASIC, NET_SCH_INGRESS, and
NET_ACT_POLICE, either built-in or as modules. (NET_CLS_POLICE is
obsolete and not needed.)
To use GRE tunneling on Linux 2.6.37 or newer, kernel support
for GRE demultiplexing (CONFIG_NET_IPGRE_DEMUX) must be compiled
in or available as a module. Also, on kernels before 3.11, the
ip_gre module, for GRE tunnels over IP (NET_IPGRE), must not be
loaded or compiled in.
To use GRE tunneling on Linux 2.6.37 or newer, kernel support
for GRE demultiplexing (CONFIG_NET_IPGRE_DEMUX) must be compiled
in or available as a module. Also, on kernels before 3.11, the
ip_gre module, for GRE tunnels over IP (NET_IPGRE), must not be
loaded or compiled in.
To configure HTB or HFSC quality of service with Open vSwitch,
you must enable the respective configuration options.
To configure HTB or HFSC quality of service with Open vSwitch,
you must enable the respective configuration options.
To use Open vSwitch support for TAP devices, you must enable
CONFIG_TUN.
To use Open vSwitch support for TAP devices, you must enable
CONFIG_TUN.
- To build a kernel module, you need the same version of GCC that
was used to build that kernel.
- To build a kernel module, you need the same version of GCC that
was used to build that kernel.
- A kernel build directory corresponding to the Linux kernel image
the module is to run on. Under Debian and Ubuntu, for example,
each linux-image package containing a kernel binary has a
corresponding linux-headers package with the required build
infrastructure.
- A kernel build directory corresponding to the Linux kernel image
the module is to run on. Under Debian and Ubuntu, for example,
each linux-image package containing a kernel binary has a
corresponding linux-headers package with the required build
infrastructure.
If you are working from a Git tree or snapshot (instead of from a
distribution tarball), or if you modify the Open vSwitch build system
or the database schema, you will also need the following software:
- Autoconf version 2.63 or later.
- Autoconf version 2.63 or later.
- Automake version 1.10 or later.
- Automake version 1.10 or later.
- libtool version 2.4 or later. (Older versions might work too.)
- libtool version 2.4 or later. (Older versions might work too.)
To run the unit tests, you also need:
- Perl. Version 5.10.1 is known to work. Earlier versions should
also work.
- Perl. Version 5.10.1 is known to work. Earlier versions should
also work.
The ovs-vswitchd.conf.db(5) manpage will include an E-R diagram, in
formats other than plain text, only if you have the following:
- "dot" from graphviz (http://www.graphviz.org/).
- "dot" from graphviz (http://www.graphviz.org/).
- Perl. Version 5.10.1 is known to work. Earlier versions should
also work.
- Perl. Version 5.10.1 is known to work. Earlier versions should
also work.
- Python 2.x, for x >= 4.
- Python 2.x, for x >= 4.
If you are going to extensively modify Open vSwitch, please consider
installing the following to obtain better warnings:
- "sparse" version 0.4.4 or later
(http://www.kernel.org/pub/software/devel/sparse/dist/).
- "sparse" version 0.4.4 or later
(http://www.kernel.org/pub/software/devel/sparse/dist/).
- GNU make.
- GNU make.
- clang, version 3.4 or later
- clang, version 3.4 or later
Also, you may find the ovs-dev script found in utilities/ovs-dev.py useful.
@@ -130,16 +130,16 @@ Installation Requirements
The machine on which Open vSwitch is to be installed must have the
following software:
- libc compatible with the libc used for build.
- libc compatible with the libc used for build.
- libssl compatible with the libssl used for build, if OpenSSL was
used for the build.
- libssl compatible with the libssl used for build, if OpenSSL was
used for the build.
- On Linux, the same kernel version configured as part of the build.
- On Linux, the same kernel version configured as part of the build.
- For optional support of ingress policing on Linux, the "tc" program
from iproute2 (part of all major distributions and available at
http://www.linux-foundation.org/en/Net:Iproute2).
- For optional support of ingress policing on Linux, the "tc" program
from iproute2 (part of all major distributions and available at
http://www.linux-foundation.org/en/Net:Iproute2).
On Linux you should ensure that /dev/urandom exists. To support TAP
devices, you must also ensure that /dev/net/tun exists.
@@ -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.

18
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
@@ -76,7 +76,7 @@ Other settings
On NetBSD, depending on your network topology and applications, the
following configuration might help. See sysctl(7).
sysctl net.inet.ip.checkinterface=1
sysctl net.inet.ip.checkinterface=1
Bug Reporting
-------------

16
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
@@ -90,13 +90,13 @@ distinguish between multiple hypervisors.
Most of this configuration can be done with the ovs-ctl command at
startup. For example:
ovs-ctl --system-type="XenServer" --system-version="6.0.0-50762p" \
--system-id="${UUID}" "${other_options}" start
ovs-ctl --system-type="XenServer" --system-version="6.0.0-50762p" \
--system-id="${UUID}" "${other_options}" start
Alternatively, the ovs-vsctl command may be used to set a particular
value at runtime. For example:
ovs-vsctl set open_vswitch . external-ids:system-id='"${UUID}"'
ovs-vsctl set open_vswitch . external-ids:system-id='"${UUID}"'
The 'other_config:enable-statistics' key may be set to "true" to have OVS
populate the database with statistics (e.g., number of CPUs, memory,
@@ -113,12 +113,12 @@ UUID returned by 'xe network-list' for that particular bridge.
For example, to set the identifier for bridge "br0", the following
command can be used:
ovs-vsctl set Bridge br0 external-ids:bridge-id='"${UUID}"'
ovs-vsctl set Bridge br0 external-ids:bridge-id='"${UUID}"'
The MAC address of the bridge may be manually configured by setting it
with the "other_config:hwaddr" key. For example:
ovs-vsctl set Bridge br0 other_config:hwaddr="12:34:56:78:90:ab"
ovs-vsctl set Bridge br0 other_config:hwaddr="12:34:56:78:90:ab"
Interface table
@@ -165,5 +165,5 @@ As in the previous tables, the ovs-vsctl command may be used to
configure the values. For example, to set the 'iface-id' on eth0, the
following command can be used:
ovs-vsctl set Interface eth0 external-ids:iface-id='"${UUID}"'
ovs-vsctl set Interface eth0 external-ids:iface-id='"${UUID}"'

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.

120
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
@@ -44,22 +44,22 @@ vSwitch from a porter's perspective.
Some of the components are generic. Modulo bugs or inadequacies,
these components should not need to be modified as part of a port:
- "ovs-vswitchd" is the main Open vSwitch userspace program, in
vswitchd/. It reads the desired Open vSwitch configuration from
the ovsdb-server program over an IPC channel and passes this
configuration down to the "ofproto" library. It also passes
certain status and statistical information from ofproto back
into the database.
- "ovs-vswitchd" is the main Open vSwitch userspace program, in
vswitchd/. It reads the desired Open vSwitch configuration from
the ovsdb-server program over an IPC channel and passes this
configuration down to the "ofproto" library. It also passes
certain status and statistical information from ofproto back
into the database.
- "ofproto" is the Open vSwitch library, in ofproto/, that
implements an OpenFlow switch. It talks to OpenFlow controllers
over the network and to switch hardware or software through an
"ofproto provider", explained further below.
- "ofproto" is the Open vSwitch library, in ofproto/, that
implements an OpenFlow switch. It talks to OpenFlow controllers
over the network and to switch hardware or software through an
"ofproto provider", explained further below.
- "netdev" is the Open vSwitch library, in lib/netdev.c, that
abstracts interacting with network devices, that is, Ethernet
interfaces. The netdev library is a thin layer over "netdev
provider" code, explained further below.
- "netdev" is the Open vSwitch library, in lib/netdev.c, that
abstracts interacting with network devices, that is, Ethernet
interfaces. The netdev library is a thin layer over "netdev
provider" code, explained further below.
The other components may need attention during a port. You will
almost certainly have to implement a "netdev provider". Depending on
@@ -87,35 +87,35 @@ this as a bug.
The netdev interface can be divided into a few rough categories:
* Functions required to properly implement OpenFlow features. For
example, OpenFlow requires the ability to report the Ethernet
hardware address of a port. These functions must be implemented
for minimally correct operation.
* Functions required to properly implement OpenFlow features. For
example, OpenFlow requires the ability to report the Ethernet
hardware address of a port. These functions must be implemented
for minimally correct operation.
* Functions required to implement optional Open vSwitch features.
For example, the Open vSwitch support for in-band control
requires netdev support for inspecting the TCP/IP stack's ARP
table. These functions must be implemented if the corresponding
OVS features are to work, but may be omitted initially.
* Functions required to implement optional Open vSwitch features.
For example, the Open vSwitch support for in-band control
requires netdev support for inspecting the TCP/IP stack's ARP
table. These functions must be implemented if the corresponding
OVS features are to work, but may be omitted initially.
* Functions needed in some implementations but not in others. For
example, most kinds of ports (see below) do not need
functionality to receive packets from a network device.
* Functions needed in some implementations but not in others. For
example, most kinds of ports (see below) do not need
functionality to receive packets from a network device.
The existing netdev implementations may serve as useful examples
during a port:
* lib/netdev-linux.c implements netdev functionality for Linux
network devices, using Linux kernel calls. It may be a good
place to start for full-featured netdev implementations.
* lib/netdev-linux.c implements netdev functionality for Linux
network devices, using Linux kernel calls. It may be a good
place to start for full-featured netdev implementations.
* lib/netdev-vport.c provides support for "virtual ports"
implemented by the Open vSwitch datapath module for the Linux
kernel. This may serve as a model for minimal netdev
implementations.
* lib/netdev-vport.c provides support for "virtual ports"
implemented by the Open vSwitch datapath module for the Linux
kernel. This may serve as a model for minimal netdev
implementations.
* lib/netdev-dummy.c is a fake netdev implementation useful only
for testing.
* lib/netdev-dummy.c is a fake netdev implementation useful only
for testing.
Porting Strategies
@@ -129,28 +129,28 @@ 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
"ofproto provider" or a "dpif provider". Which you should choose
depends on a few different factors:
* Only an ofproto provider can take full advantage of hardware
with built-in support for wildcards (e.g. an ACL table or a
TCAM).
* Only an ofproto provider can take full advantage of hardware
with built-in support for wildcards (e.g. an ACL table or a
TCAM).
* A dpif provider can take advantage of the Open vSwitch built-in
implementations of bonding, LACP, 802.1ag, 802.1Q VLANs, and
other features. An ofproto provider has to provide its own
implementations, if the hardware can support them at all.
* A dpif provider can take advantage of the Open vSwitch built-in
implementations of bonding, LACP, 802.1ag, 802.1Q VLANs, and
other features. An ofproto provider has to provide its own
implementations, if the hardware can support them at all.
* A dpif provider is usually easier to implement, but most
appropriate for software switching. It "explodes" wildcard
rules into exact-match entries (with an optional wildcard mask).
This allows fast hash lookups in software, but makes
inefficient use of TCAMs in hardware that support wildcarding.
* A dpif provider is usually easier to implement, but most
appropriate for software switching. It "explodes" wildcard
rules into exact-match entries (with an optional wildcard mask).
This allows fast hash lookups in software, but makes
inefficient use of TCAMs in hardware that support wildcarding.
The following sections describe how to implement each kind of port.
@@ -232,16 +232,16 @@ requirements are unclear, please report this as a bug.
There are two existing dpif implementations that may serve as
useful examples during a port:
* lib/dpif-netlink.c is a Linux-specific dpif implementation that
talks to an Open vSwitch-specific kernel module (whose sources
are in the "datapath" directory). The kernel module performs
all of the switching work, passing packets that do not match any
flow table entry up to userspace. This dpif implementation is
essentially a wrapper around calls into the kernel module.
* lib/dpif-netlink.c is a Linux-specific dpif implementation that
talks to an Open vSwitch-specific kernel module (whose sources
are in the "datapath" directory). The kernel module performs
all of the switching work, passing packets that do not match any
flow table entry up to userspace. This dpif implementation is
essentially a wrapper around calls into the kernel module.
* lib/dpif-netdev.c is a generic dpif implementation that performs
all switching internally. This is how the Open vSwitch
userspace switch is implemented.
* lib/dpif-netdev.c is a generic dpif implementation that performs
all switching internally. This is how the Open vSwitch
userspace switch is implemented.
Miscellaneous Notes

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/

38
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.
@@ -254,24 +254,24 @@ work.
Please consider the following:
* Testing. Please test your code.
* 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.
* 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.
* 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.
* 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).
* 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.
* The patch submission guidelines (see [CONTRIBUTING](CONTRIBUTING.md)).
I recommend using "git send-email", which automatically follows a
lot of those guidelines.
Bug Reporting

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))

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

@@ -41,25 +41,25 @@ flow key that it parsed from the packet. Userspace then extracts its
own notion of a flow key from the packet and compares it against the
kernel-provided version:
- If userspace's notion of the flow key for the packet matches the
kernel's, then nothing special is necessary.
- If userspace's notion of the flow key for the packet matches the
kernel's, then nothing special is necessary.
- If the kernel's flow key includes more fields than the userspace
version of the flow key, for example if the kernel decoded IPv6
headers but userspace stopped at the Ethernet type (because it
does not understand IPv6), then again nothing special is
necessary. Userspace can still set up a flow in the usual way,
as long as it uses the kernel-provided flow key to do it.
- If the kernel's flow key includes more fields than the userspace
version of the flow key, for example if the kernel decoded IPv6
headers but userspace stopped at the Ethernet type (because it
does not understand IPv6), then again nothing special is
necessary. Userspace can still set up a flow in the usual way,
as long as it uses the kernel-provided flow key to do it.
- If the userspace flow key includes more fields than the
kernel's, for example if userspace decoded an IPv6 header but
the kernel stopped at the Ethernet type, then userspace can
forward the packet manually, without setting up a flow in the
kernel. This case is bad for performance because every packet
that the kernel considers part of the flow must go to userspace,
but the forwarding behavior is correct. (If userspace can
determine that the values of the extra fields would not affect
forwarding behavior, then it could set up a flow anyway.)
- If the userspace flow key includes more fields than the
kernel's, for example if userspace decoded an IPv6 header but
the kernel stopped at the Ethernet type, then userspace can
forward the packet manually, without setting up a flow in the
kernel. This case is bad for performance because every packet
that the kernel considers part of the flow must go to userspace,
but the forwarding behavior is correct. (If userspace can
determine that the values of the extra fields would not affect
forwarding behavior, then it could set up a flow anyway.)
How flow keys evolve over time is important to making this work, so
the following sections go into detail.
@@ -225,11 +225,11 @@ Other rules
The other rules for flow keys are much less subtle:
- Duplicate attributes are not allowed at a given nesting level.
- Duplicate attributes are not allowed at a given nesting level.
- Ordering of attributes is not significant.
- Ordering of attributes is not significant.
- When the kernel sends a given flow key to userspace, it always
composes it the same way. This allows userspace to hash and
compare entire flow keys that it may not be able to fully
interpret.
- When the kernel sends a given flow key to userspace, it always
composes it the same way. This allows userspace to hash and
compare entire flow keys that it may not be able to fully
interpret.

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

173
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,48 +37,48 @@ 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
without any options.
* If you have already installed Open vSwitch on your system, then
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
the Open vSwitch build directory for DIRECTORY.
* 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
the Open vSwitch build directory for DIRECTORY.
* As a slight variant on the latter, you can run "make sandbox"
from an Open vSwitch build directory.
* 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:
1. CAUTION: Deletes any subdirectory of the current directory
named "sandbox" and any files in that directory.
1. CAUTION: Deletes any subdirectory of the current directory
named "sandbox" and any files in that directory.
2. Creates a new directory "sandbox" in the current directory.
2. Creates a new directory "sandbox" in the current directory.
3. Sets up special environment variables that ensure that Open
vSwitch programs will look inside the "sandbox" directory
instead of in the Open vSwitch installation directory.
3. Sets up special environment variables that ensure that Open
vSwitch programs will look inside the "sandbox" directory
instead of in the Open vSwitch installation directory.
4. If you are using a built but not installed Open vSwitch,
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
you built.
4. If you are using a built but not installed Open vSwitch,
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
you built.
5. Creates an empty Open vSwitch configuration database under
"sandbox".
5. Creates an empty Open vSwitch configuration database under
"sandbox".
6. Starts ovsdb-server running under "sandbox".
6. Starts ovsdb-server running under "sandbox".
7. Starts ovs-vswitchd running under "sandbox", passing special
options that enable a special "dummy" mode for testing.
7. Starts ovs-vswitchd running under "sandbox", passing special
options that enable a special "dummy" mode for testing.
8. Starts a nested interactive shell inside "sandbox".
8. Starts a nested interactive shell inside "sandbox".
At this point, you can run all the usual Open vSwitch utilities from
the nested shell environment. You can, for example, use ovs-vsctl to
@@ -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
@@ -115,16 +115,16 @@ MAC-learning switch with VLAN trunk and access ports. Outside of the
Open vSwitch features that we will discuss, OpenFlow provides at least
two ways to implement such a switch:
1. An OpenFlow controller to implement MAC learning in a
"reactive" fashion. Whenever a new MAC appears on the switch,
or a MAC moves from one switch port to another, the controller
adjusts the OpenFlow flow table to match.
1. An OpenFlow controller to implement MAC learning in a
"reactive" fashion. Whenever a new MAC appears on the switch,
or a MAC moves from one switch port to another, the controller
adjusts the OpenFlow flow table to match.
2. The "normal" action. OpenFlow defines this action to submit a
packet to "the traditional non-OpenFlow pipeline of the
switch". That is, if a flow uses this action, then the packets
in the flow go through the switch in the same way that they
would if OpenFlow was not configured on the switch.
2. The "normal" action. OpenFlow defines this action to submit a
packet to "the traditional non-OpenFlow pipeline of the
switch". That is, if a flow uses this action, then the packets
in the flow go through the switch in the same way that they
would if OpenFlow was not configured on the switch.
Each of these approaches has unfortunate pitfalls. In the first
approach, using an OpenFlow controller to implement MAC learning, has
@@ -147,17 +147,17 @@ features.
Scenario
========
--------
We will construct Open vSwitch flow tables for a VLAN-capable,
MAC-learning switch that has four ports:
* p1, a trunk port that carries all VLANs, on OpenFlow port 1.
* p1, a trunk port that carries all VLANs, on OpenFlow port 1.
* p2, an access port for VLAN 20, on OpenFlow port 2.
* p2, an access port for VLAN 20, on OpenFlow port 2.
* p3 and p4, both access ports for VLAN 30, on OpenFlow ports 3
and 4, respectively.
* p3 and p4, both access ports for VLAN 30, on OpenFlow ports 3
and 4, respectively.
>>> The ports' names are not significant. You could call them eth1
through eth4, or any other names you like.
@@ -168,15 +168,15 @@ MAC-learning switch that has four ports:
Our switch design will consist of five main flow tables, each of which
implements one stage in the switch pipeline:
Table 0: Admission control.
Table 0: Admission control.
Table 1: VLAN input processing.
Table 1: VLAN input processing.
Table 2: Learn source MAC and VLAN for ingress port.
Table 2: Learn source MAC and VLAN for ingress port.
Table 3: Look up learned port for destination MAC and VLAN.
Table 3: Look up learned port for destination MAC and VLAN.
Table 4: Output processing.
Table 4: Output processing.
The section below describes how to set up the scenario, followed by a
section for each OpenFlow table.
@@ -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:
@@ -212,7 +212,7 @@ do it:
for i in 1 2 3 4; do
ovs-vsctl add-port br0 p$i -- set Interface p$i ofport_request=$i
ovs-ofctl mod-port br0 p$i up
ovs-ofctl mod-port br0 p$i up
done
In addition to adding a port, the ovs-vsctl command above sets its
@@ -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
@@ -372,10 +371,10 @@ header, tag it with the access port's VLAN number, and then pass it
along to the next stage:
ovs-ofctl add-flows br0 - <<'EOF'
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
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
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
@@ -721,10 +717,10 @@ For output to the access ports, we just have to strip the VLAN header
before outputting the packet:
ovs-ofctl add-flows br0 - <<'EOF'
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
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
The only slightly tricky part is flooding multicast and broadcast
packets and unicast packets with unlearned destinations. For those,
@@ -734,10 +730,10 @@ copy output to the trunk port but not in copies output to access
ports:
ovs-ofctl add-flows br0 - <<'EOF'
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
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
>>> 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