From 542cc9bb8b8817866afcd692a78fa591db5839dc Mon Sep 17 00:00:00 2001 From: Thomas Graf Date: Tue, 28 Oct 2014 11:19:52 +0100 Subject: [PATCH] doc: Convert docs to Markdown language 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 Signed-off-by: Ben Pfaff --- CONTRIBUTING => CONTRIBUTING.md | 94 +-- CodingStyle => CodingStyle.md | 164 ++--- DESIGN => DESIGN.md | 581 ++++++++-------- FAQ => FAQ.md | 664 +++++++++---------- INSTALL.DPDK | 252 ------- INSTALL.DPDK.md | 284 ++++++++ INSTALL.Debian => INSTALL.Debian.md | 24 +- INSTALL.Docker => INSTALL.Docker.md | 23 +- INSTALL.Fedora => INSTALL.Fedora.md | 20 +- INSTALL.KVM => INSTALL.KVM.md | 27 +- INSTALL.Libvirt => INSTALL.Libvirt.md | 24 +- INSTALL.NetBSD => INSTALL.NetBSD.md | 26 +- INSTALL.RHEL => INSTALL.RHEL.md | 38 +- INSTALL.SSL => INSTALL.SSL.md | 108 +-- INSTALL.Windows => INSTALL.Windows.md | 24 +- INSTALL.XenServer => INSTALL.XenServer.md | 34 +- INSTALL => INSTALL.md | 236 +++---- INSTALL.userspace => INSTALL.userspace.md | 18 +- IntegrationGuide => IntegrationGuide.md | 16 +- Makefile.am | 50 +- NEWS | 4 +- OPENFLOW-1.1+ | 231 ------- OPENFLOW-1.1+.md | 231 +++++++ PORTING => PORTING.md | 120 ++-- README-lisp => README-lisp.md | 0 README.md | 21 +- REPORTING-BUGS | 56 -- REPORTING-BUGS.md | 56 ++ TODO => TODO.md | 38 +- WHY-OVS => WHY-OVS.md | 4 +- datapath/Modules.mk | 2 +- datapath/{README => README.md} | 50 +- lib/dpif.h | 2 +- rhel/openvswitch-fedora.spec.in | 2 +- rhel/openvswitch.spec.in | 4 +- third-party/{README => README.md} | 0 third-party/automake.mk | 2 +- tutorial/{Tutorial => Tutorial.md} | 173 +++-- tutorial/automake.mk | 2 +- utilities/ovs-ctl.8 | 2 +- vtep/{README.ovs-vtep => README.ovs-vtep.md} | 17 +- vtep/automake.mk | 2 +- 42 files changed, 1900 insertions(+), 1826 deletions(-) rename CONTRIBUTING => CONTRIBUTING.md (78%) rename CodingStyle => CodingStyle.md (81%) rename DESIGN => DESIGN.md (62%) rename FAQ => FAQ.md (73%) delete mode 100644 INSTALL.DPDK create mode 100644 INSTALL.DPDK.md rename INSTALL.Debian => INSTALL.Debian.md (79%) rename INSTALL.Docker => INSTALL.Docker.md (84%) rename INSTALL.Fedora => INSTALL.Fedora.md (86%) rename INSTALL.KVM => INSTALL.KVM.md (73%) rename INSTALL.Libvirt => INSTALL.Libvirt.md (82%) rename INSTALL.NetBSD => INSTALL.NetBSD.md (60%) rename INSTALL.RHEL => INSTALL.RHEL.md (85%) rename INSTALL.SSL => INSTALL.SSL.md (74%) rename INSTALL.Windows => INSTALL.Windows.md (95%) rename INSTALL.XenServer => INSTALL.XenServer.md (88%) rename INSTALL => INSTALL.md (76%) rename INSTALL.userspace => INSTALL.userspace.md (84%) rename IntegrationGuide => IntegrationGuide.md (93%) delete mode 100644 OPENFLOW-1.1+ create mode 100644 OPENFLOW-1.1+.md rename PORTING => PORTING.md (74%) rename README-lisp => README-lisp.md (100%) delete mode 100644 REPORTING-BUGS create mode 100644 REPORTING-BUGS.md rename TODO => TODO.md (90%) rename WHY-OVS => WHY-OVS.md (98%) rename datapath/{README => README.md} (86%) rename third-party/{README => README.md} (100%) rename tutorial/{Tutorial => Tutorial.md} (87%) rename vtep/{README.ovs-vtep => README.ovs-vtep.md} (93%) diff --git a/CONTRIBUTING b/CONTRIBUTING.md similarity index 78% rename from CONTRIBUTING rename to CONTRIBUTING.md index dfbb17155..b434e78e3 100644 --- a/CONTRIBUTING +++ b/CONTRIBUTING.md @@ -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 /] : +`[PATCH /] : ` - - [PATCH /] 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 /]` 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. - - : 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. + - `:` 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. - - briefly describes the change. + - `` briefly describes the change. -The subject, minus the [PATCH /] prefix, becomes the first line +The subject, minus the `[PATCH /]` 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: ", followed by a blank line. This +`From: `, 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 Date: Thu, 8 Dec 2011 13:17:24 -0800 @@ -313,4 +314,5 @@ index fdd952e..f6cb88e 100644 both_modules += brcompat -- 1.7.7.3 +``` diff --git a/CodingStyle b/CodingStyle.md similarity index 81% rename from CodingStyle rename to CodingStyle.md index d1ef65b5a..b69b5d61e 100644 --- a/CodingStyle +++ b/CodingStyle.md @@ -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 -#include directives should appear in the following order: +`#include` directives should appear in the following order: - 1. #include +1. `#include ` - 2. The module's own headers, if any. Including this before any - other header (besides ) 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 ) 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, PRIu, and PRIx 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" - * and . + * and . - * bool and , 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 , 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. diff --git a/DESIGN b/DESIGN.md similarity index 62% rename from DESIGN rename to DESIGN.md index f864135a8..6f8d09072 100644 --- a/DESIGN +++ b/DESIGN.md @@ -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). 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). 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. - 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. + 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. - - - 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. - - - 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.) + - 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). + + - 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.) 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. - - 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. - - - 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. - - 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 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. - - 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. - - 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. + - 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. + + 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. + + 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. + + - 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. + + 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. + + - 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. 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). - - - 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 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 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). + - 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). + + - 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. + + - 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). 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. - - - 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. + - 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 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. diff --git a/FAQ b/FAQ.md similarity index 73% rename from FAQ rename to FAQ.md index 9e74a3f46..01228eb85 100644 --- a/FAQ +++ b/FAQ.md @@ -1,12 +1,12 @@ - Open vSwitch - Frequently Asked Questions ========================== +Open vSwitch + General ------- -Q: What is Open vSwitch? +### Q: What is Open vSwitch? A: Open vSwitch is a production quality open source software switch designed to be used as a vswitch in virtualized server @@ -24,7 +24,7 @@ A: Open vSwitch is a production quality open source software switch Open vSwitch will be able to take advantage of on-NIC switching chipsets as their functionality matures. -Q: What virtualization platforms can use Open vSwitch? +### Q: What virtualization platforms can use Open vSwitch? A: Open vSwitch can currently run on any Linux-based virtualization platform (kernel 2.6.32 and newer), including: KVM, VirtualBox, Xen, @@ -34,7 +34,7 @@ A: Open vSwitch can currently run on any Linux-based virtualization inquires about integrating Open vSwitch with other virtualization platforms. -Q: How can I try Open vSwitch? +### Q: How can I try Open vSwitch? A: The Open vSwitch source code can be built on a Linux system. You can build and experiment with Open vSwitch on any Linux machine. @@ -47,7 +47,7 @@ A: The Open vSwitch source code can be built on a Linux system. You can integrated with a particular platform may not be the most recent Open vSwitch release. -Q: Does Open vSwitch only work on Linux? +### Q: Does Open vSwitch only work on Linux? A: No, Open vSwitch has been ported to a number of different operating systems and hardware platforms. Most of the development work occurs @@ -59,22 +59,20 @@ A: No, Open vSwitch has been ported to a number of different operating Linux and will provide the highest performance. However, a userspace datapath is available that should be very portable. -Q: What's involved with porting Open vSwitch to a new platform or - switching ASIC? +### Q: What's involved with porting Open vSwitch to a new platform or switching ASIC? -A: The PORTING document describes how one would go about porting Open - vSwitch to a new operating system or hardware platform. +A: The [PORTING](PORTING.md) document describes how one would go about + porting Open vSwitch to a new operating system or hardware platform. -Q: Why would I use Open vSwitch instead of the Linux bridge? +### Q: Why would I use Open vSwitch instead of the Linux bridge? A: Open vSwitch is specially designed to make it easier to manage VM network configuration and monitor state spread across many physical - hosts in dynamic virtualized environments. Please see WHY-OVS for a - more detailed description of how Open vSwitch relates to the Linux - Bridge. + hosts in dynamic virtualized environments. Please see + [WHY-OVS](WHY-OVS.md) for a more detailed description of how Open + vSwitch relates to the Linux Bridge. -Q: How is Open vSwitch related to distributed virtual switches like the - VMware vNetwork distributed switch or the Cisco Nexus 1000V? +### Q: How is Open vSwitch related to distributed virtual switches like the VMware vNetwork distributed switch or the Cisco Nexus 1000V? A: Distributed vswitch applications (e.g., VMware vNetwork distributed switch, Cisco Nexus 1000V) provide a centralized way to configure and @@ -93,7 +91,7 @@ A: Distributed vswitch applications (e.g., VMware vNetwork distributed extend to provide distributed vswitch capabilities that are closely integrated with their virtualization management platform. -Q: Why doesn't Open vSwitch support distribution? +### Q: Why doesn't Open vSwitch support distribution? A: Open vSwitch is intended to be a useful component for building flexible network infrastructure. There are many different approaches @@ -103,21 +101,20 @@ A: Open vSwitch is intended to be a useful component for building support all as a primitive building block rather than choose a particular point in the distributed design space. -Q: How can I contribute to the Open vSwitch Community? +### Q: How can I contribute to the Open vSwitch Community? A: You can start by joining the mailing lists and helping to answer questions. You can also suggest improvements to documentation. If you have a feature or bug you would like to work on, send a mail to one of the mailing lists: - http://openvswitch.org/mlists/ + http://openvswitch.org/mlists/ Releases -------- -Q: What does it mean for an Open vSwitch release to be LTS (long-term - support)? +### Q: What does it mean for an Open vSwitch release to be LTS (long-term support)? A: All official releases have been through a comprehensive testing process and are suitable for production use. Planned releases will @@ -127,7 +124,7 @@ A: All official releases have been through a comprehensive testing supplanted by the next major release. The current LTS release is 1.9.x. -Q: What Linux kernel versions does each Open vSwitch release work with? +### Q: What Linux kernel versions does each Open vSwitch release work with? A: The following table lists the Linux kernel versions against which the given versions of the Open vSwitch kernel module will successfully @@ -137,19 +134,19 @@ A: The following table lists the Linux kernel versions against which the most notably true of Red Hat Enterprise Linux (RHEL) kernels, which are extensively modified from upstream. - Open vSwitch Linux kernel - ------------ ------------- - 1.4.x 2.6.18 to 3.2 - 1.5.x 2.6.18 to 3.2 - 1.6.x 2.6.18 to 3.2 - 1.7.x 2.6.18 to 3.3 - 1.8.x 2.6.18 to 3.4 - 1.9.x 2.6.18 to 3.8 - 1.10.x 2.6.18 to 3.8 - 1.11.x 2.6.18 to 3.8 - 2.0.x 2.6.32 to 3.10 - 2.1.x 2.6.32 to 3.11 - 2.3.x 2.6.32 to 3.14 +| Open vSwitch | Linux kernel +|:------------:|:-------------: +| 1.4.x | 2.6.18 to 3.2 +| 1.5.x | 2.6.18 to 3.2 +| 1.6.x | 2.6.18 to 3.2 +| 1.7.x | 2.6.18 to 3.3 +| 1.8.x | 2.6.18 to 3.4 +| 1.9.x | 2.6.18 to 3.8 +| 1.10.x | 2.6.18 to 3.8 +| 1.11.x | 2.6.18 to 3.8 +| 2.0.x | 2.6.32 to 3.10 +| 2.1.x | 2.6.32 to 3.11 +| 2.3.x | 2.6.32 to 3.14 Open vSwitch userspace should also work with the Linux kernel module built into Linux 3.3 and later. @@ -158,7 +155,7 @@ A: The following table lists the Linux kernel versions against which the It should build against almost any kernel, certainly against 2.6.32 and later. -Q: I get an error like this when I configure Open vSwitch: +### Q: I get an error like this when I configure Open vSwitch: configure: error: Linux kernel in is version , but version newer than is not supported (please refer to the @@ -175,8 +172,7 @@ A: If there is a newer version of Open vSwitch, consider building that compatible with all versions of the Open vSwitch kernel module, so this will also work. See also the following question. -Q: What features are not available in the Open vSwitch kernel datapath - that ships as part of the upstream Linux kernel? +### Q: What features are not available in the Open vSwitch kernel datapath that ships as part of the upstream Linux kernel? A: The kernel module in upstream Linux does not include support for LISP. Work is in progress to add support for LISP to the upstream @@ -190,19 +186,18 @@ A: The kernel module in upstream Linux does not include support for Linux release or using the kernel module paired with the userspace distribution. -Q: Why do tunnels not work when using a kernel module other than the - one packaged with Open vSwitch? +### Q: Why do tunnels not work when using a kernel module other than the one packaged with Open vSwitch? A: Support for tunnels was added to the upstream Linux kernel module after the rest of Open vSwitch. As a result, some kernels may contain support for Open vSwitch but not tunnels. The minimum kernel version that supports each tunnel protocol is: - Protocol Linux Kernel - -------- ------------ - GRE 3.11 - VXLAN 3.12 - LISP +| Protocol | Linux Kernel +|:--------:|:-------------: +| GRE | 3.11 +| VXLAN | 3.12 +| LISP | If you are using a version of the kernel that is older than the one listed above, it is still possible to use that tunnel protocol. However, @@ -211,19 +206,19 @@ A: Support for tunnels was added to the upstream Linux kernel module persist after doing this, check to make sure that the module that is loaded is the one you expect. -Q: What features are not available when using the userspace datapath? +### Q: What features are not available when using the userspace datapath? A: Tunnel virtual ports are not supported, as described in the previous answer. It is also not possible to use queue-related actions. On Linux kernels before 2.6.39, maximum-sized VLAN packets may not be transmitted. -Q: What Linux kernel versions does IPFIX flow monitoring work with? +### Q: What Linux kernel versions does IPFIX flow monitoring work with? A: IPFIX flow monitoring requires the Linux kernel module from Open vSwitch version 1.10.90 or later. -Q: Should userspace or kernel be upgraded first to minimize downtime? +### Q: Should userspace or kernel be upgraded first to minimize downtime? In general, the Open vSwitch userspace should be used with the kernel version included in the same release or with the version @@ -231,7 +226,7 @@ Q: Should userspace or kernel be upgraded first to minimize downtime? of Open vSwitch it is best to migrate userspace first to reduce the possibility of incompatibilities. -Q: What happened to the bridge compatibility feature? +### Q: What happened to the bridge compatibility feature? A: Bridge compatibility was a feature of Open vSwitch 1.9 and earlier. When it was enabled, Open vSwitch imitated the interface of the @@ -254,14 +249,13 @@ A: Bridge compatibility was a feature of Open vSwitch 1.9 and earlier. Terminology ----------- -Q: I thought Open vSwitch was a virtual Ethernet switch, but the - documentation keeps talking about bridges. What's a bridge? +### Q: I thought Open vSwitch was a virtual Ethernet switch, but the documentation keeps talking about bridges. What's a bridge? A: In networking, the terms "bridge" and "switch" are synonyms. Open vSwitch implements an Ethernet switch, which means that it is also an Ethernet bridge. -Q: What's a VLAN? +### Q: What's a VLAN? A: See the "VLAN" section below. @@ -269,7 +263,7 @@ A: See the "VLAN" section below. Basic Configuration ------------------- -Q: How do I configure a port as an access port? +### Q: How do I configure a port as an access port? A: Add "tag=VLAN" to your "ovs-vsctl add-port" command. For example, the following commands configure br0 with eth0 as a trunk port (the @@ -284,8 +278,7 @@ A: Add "tag=VLAN" to your "ovs-vsctl add-port" command. For example, ovs-vsctl set port tap0 tag=9 -Q: How do I configure a port as a SPAN port, that is, enable mirroring - of all traffic to that port? +### Q: How do I configure a port as a SPAN port, that is, enable mirroring of all traffic to that port? A: The following commands configure br0 with eth0 and tap0 as trunk ports. All traffic coming in or going out on eth0 or tap0 is also @@ -303,42 +296,41 @@ A: The following commands configure br0 with eth0 and tap0 as trunk ovs-vsctl clear bridge br0 mirrors -Q: Does Open vSwitch support configuring a port in promiscuous mode? +### Q: Does Open vSwitch support configuring a port in promiscuous mode? A: Yes. How you configure it depends on what you mean by "promiscuous mode": - - Conventionally, "promiscuous mode" is a feature of a network - interface card. Ordinarily, a NIC passes to the CPU only the - packets actually destined to its host machine. It discards - the rest to avoid wasting memory and CPU cycles. When - promiscuous mode is enabled, however, it passes every packet - to the CPU. On an old-style shared-media or hub-based - network, this allows the host to spy on all packets on the - network. But in the switched networks that are almost - everywhere these days, promiscuous mode doesn't have much - effect, because few packets not destined to a host are - delivered to the host's NIC. - - This form of promiscuous mode is configured in the guest OS of - the VMs on your bridge, e.g. with "ifconfig". - - - The VMware vSwitch uses a different definition of "promiscuous - mode". When you configure promiscuous mode on a VMware vNIC, - the vSwitch sends a copy of every packet received by the - vSwitch to that vNIC. That has a much bigger effect than just - enabling promiscuous mode in a guest OS. Rather than getting - a few stray packets for which the switch does not yet know the - correct destination, the vNIC gets every packet. The effect - is similar to replacing the vSwitch by a virtual hub. - - This "promiscuous mode" is what switches normally call "port - mirroring" or "SPAN". For information on how to configure - SPAN, see "How do I configure a port as a SPAN port, that is, - enable mirroring of all traffic to that port?" - -Q: How do I configure a VLAN as an RSPAN VLAN, that is, enable - mirroring of all traffic to that VLAN? + - Conventionally, "promiscuous mode" is a feature of a network + interface card. Ordinarily, a NIC passes to the CPU only the + packets actually destined to its host machine. It discards + the rest to avoid wasting memory and CPU cycles. When + promiscuous mode is enabled, however, it passes every packet + to the CPU. On an old-style shared-media or hub-based + network, this allows the host to spy on all packets on the + network. But in the switched networks that are almost + everywhere these days, promiscuous mode doesn't have much + effect, because few packets not destined to a host are + delivered to the host's NIC. + + This form of promiscuous mode is configured in the guest OS of + the VMs on your bridge, e.g. with "ifconfig". + + - The VMware vSwitch uses a different definition of "promiscuous + mode". When you configure promiscuous mode on a VMware vNIC, + the vSwitch sends a copy of every packet received by the + vSwitch to that vNIC. That has a much bigger effect than just + enabling promiscuous mode in a guest OS. Rather than getting + a few stray packets for which the switch does not yet know the + correct destination, the vNIC gets every packet. The effect + is similar to replacing the vSwitch by a virtual hub. + + This "promiscuous mode" is what switches normally call "port + mirroring" or "SPAN". For information on how to configure + SPAN, see "How do I configure a port as a SPAN port, that is, + enable mirroring of all traffic to that port?" + +### Q: How do I configure a VLAN as an RSPAN VLAN, that is, enable mirroring of all traffic to that VLAN? A: The following commands configure br0 with eth0 as a trunk port and tap0 as an access port for VLAN 10. All traffic coming in or going @@ -364,7 +356,7 @@ A: The following commands configure br0 with eth0 as a trunk port and GRE tunnel has fewer caveats than mirroring to a VLAN and should generally be preferred. -Q: Can I mirror more than one input VLAN to an RSPAN VLAN? +### Q: Can I mirror more than one input VLAN to an RSPAN VLAN? A: Yes, but mirroring to a VLAN strips the original VLAN tag in favor of the specified output-vlan. This loss of information may make @@ -388,7 +380,7 @@ A: Yes, but mirroring to a VLAN strips the original VLAN tag in favor GRE tunnel has fewer caveats than mirroring to a VLAN and should generally be preferred. -Q: How do I configure mirroring of all traffic to a GRE tunnel? +### Q: How do I configure mirroring of all traffic to a GRE tunnel? A: The following commands configure br0 with eth0 and tap0 as trunk ports. All traffic coming in or going out on eth0 or tap0 is also @@ -409,13 +401,13 @@ A: The following commands configure br0 with eth0 and tap0 as trunk ovs-vsctl clear bridge br0 mirrors ovs-vcstl del-port br0 gre0 -Q: Does Open vSwitch support ERSPAN? +### Q: Does Open vSwitch support ERSPAN? A: No. ERSPAN is an undocumented proprietary protocol. As an alternative, Open vSwitch supports mirroring to a GRE tunnel (see above). -Q: How do I connect two bridges? +### Q: How do I connect two bridges? A: First, why do you want to do this? Two connected bridges are not much different from a single bridge, so you might as well just have @@ -452,8 +444,7 @@ A: First, why do you want to do this? Two connected bridges are not ports will not work with the userspace datapath, only with the kernel module. -Q: How do I configure a bridge without an OpenFlow local port? - (Local port in the sense of OFPP_LOCAL) +### Q: How do I configure a bridge without an OpenFlow local port? (Local port in the sense of OFPP_LOCAL) A: Open vSwitch does not support such a configuration. Bridges always have their local ports. @@ -462,65 +453,65 @@ A: Open vSwitch does not support such a configuration. Implementation Details ---------------------- -Q: I hear OVS has a couple of kinds of flows. Can you tell me about them? +### Q: I hear OVS has a couple of kinds of flows. Can you tell me about them? A: Open vSwitch uses different kinds of flows for different purposes: - - OpenFlow flows are the most important kind of flow. OpenFlow - controllers use these flows to define a switch's policy. - OpenFlow flows support wildcards, priorities, and multiple - tables. - - When in-band control is in use, Open vSwitch sets up a few - "hidden" flows, with priority higher than a controller or the - user can configure, that are not visible via OpenFlow. (See - the "Controller" section of the FAQ for more information - about hidden flows.) - - - The Open vSwitch software switch implementation uses a second - kind of flow internally. These flows, called "datapath" or - "kernel" flows, do not support priorities and comprise only a - single table, which makes them suitable for caching. (Like - OpenFlow flows, datapath flows do support wildcarding, in Open - vSwitch 1.11 and later.) OpenFlow flows and datapath flows - also support different actions and number ports differently. - - Datapath flows are an implementation detail that is subject to - change in future versions of Open vSwitch. Even with the - current version of Open vSwitch, hardware switch - implementations do not necessarily use this architecture. + - OpenFlow flows are the most important kind of flow. OpenFlow + controllers use these flows to define a switch's policy. + OpenFlow flows support wildcards, priorities, and multiple + tables. + + When in-band control is in use, Open vSwitch sets up a few + "hidden" flows, with priority higher than a controller or the + user can configure, that are not visible via OpenFlow. (See + the "Controller" section of the FAQ for more information + about hidden flows.) + + - The Open vSwitch software switch implementation uses a second + kind of flow internally. These flows, called "datapath" or + "kernel" flows, do not support priorities and comprise only a + single table, which makes them suitable for caching. (Like + OpenFlow flows, datapath flows do support wildcarding, in Open + vSwitch 1.11 and later.) OpenFlow flows and datapath flows + also support different actions and number ports differently. + + Datapath flows are an implementation detail that is subject to + change in future versions of Open vSwitch. Even with the + current version of Open vSwitch, hardware switch + implementations do not necessarily use this architecture. Users and controllers directly control only the OpenFlow flow table. Open vSwitch manages the datapath flow table itself, so users should not normally be concerned with it. -Q: Why are there so many different ways to dump flows? +### Q: Why are there so many different ways to dump flows? A: Open vSwitch has two kinds of flows (see the previous question), so it has commands with different purposes for dumping each kind of flow: - - "ovs-ofctl dump-flows
" dumps OpenFlow flows, excluding - hidden flows. This is the most commonly useful form of flow - dump. (Unlike the other commands, this should work with any - OpenFlow switch, not just Open vSwitch.) + - `ovs-ofctl dump-flows
` dumps OpenFlow flows, excluding + hidden flows. This is the most commonly useful form of flow + dump. (Unlike the other commands, this should work with any + OpenFlow switch, not just Open vSwitch.) - - "ovs-appctl bridge/dump-flows
" dumps OpenFlow flows, - including hidden flows. This is occasionally useful for - troubleshooting suspected issues with in-band control. + - `ovs-appctl bridge/dump-flows
` dumps OpenFlow flows, + including hidden flows. This is occasionally useful for + troubleshooting suspected issues with in-band control. - - "ovs-dpctl dump-flows [dp]" dumps the datapath flow table - entries for a Linux kernel-based datapath. In Open vSwitch - 1.10 and later, ovs-vswitchd merges multiple switches into a - single datapath, so it will show all the flows on all your - kernel-based switches. This command can occasionally be - useful for debugging. + - `ovs-dpctl dump-flows [dp]` dumps the datapath flow table + entries for a Linux kernel-based datapath. In Open vSwitch + 1.10 and later, ovs-vswitchd merges multiple switches into a + single datapath, so it will show all the flows on all your + kernel-based switches. This command can occasionally be + useful for debugging. - - "ovs-appctl dpif/dump-flows
", new in Open vSwitch 1.10, - dumps datapath flows for only the specified bridge, regardless - of the type. + - `ovs-appctl dpif/dump-flows
`, new in Open vSwitch 1.10, + dumps datapath flows for only the specified bridge, regardless + of the type. -Q: How does multicast snooping works with VLANs? +### Q: How does multicast snooping works with VLANs? A: Open vSwitch maintains snooping tables for each VLAN. @@ -528,7 +519,7 @@ A: Open vSwitch maintains snooping tables for each VLAN. Performance ----------- -Q: I just upgraded and I see a performance drop. Why? +### Q: I just upgraded and I see a performance drop. Why? A: The OVS kernel datapath may have been updated to a newer version than the OVS userspace components. Sometimes new versions of OVS kernel @@ -549,7 +540,7 @@ A: The OVS kernel datapath may have been updated to a newer version than Configuration Problems ---------------------- -Q: I created a bridge and added my Ethernet port to it, using commands +### Q: I created a bridge and added my Ethernet port to it, using commands like these: ovs-vsctl add-br br0 @@ -594,8 +585,8 @@ A: A physical Ethernet device that is part of an Open vSwitch bridge devices. It applies to all network devices except Open vSwitch "internal" devices. -Q: I created a bridge and added a couple of Ethernet ports to it, - using commands like these: +### Q: I created a bridge and added a couple of Ethernet ports to it, +### using commands like these: ovs-vsctl add-br br0 ovs-vsctl add-port br0 eth0 @@ -616,52 +607,52 @@ A: More than likely, you've looped your network. Probably, eth0 and The solution depends on what you are trying to do: - - If you added eth0 and eth1 to get higher bandwidth or higher - reliability between OVS and your physical Ethernet switch, - use a bond. The following commands create br0 and then add - eth0 and eth1 as a bond: + - If you added eth0 and eth1 to get higher bandwidth or higher + reliability between OVS and your physical Ethernet switch, + use a bond. The following commands create br0 and then add + eth0 and eth1 as a bond: - ovs-vsctl add-br br0 - ovs-vsctl add-bond br0 bond0 eth0 eth1 + ovs-vsctl add-br br0 + ovs-vsctl add-bond br0 bond0 eth0 eth1 - Bonds have tons of configuration options. Please read the - documentation on the Port table in ovs-vswitchd.conf.db(5) - for all the details. + Bonds have tons of configuration options. Please read the + documentation on the Port table in ovs-vswitchd.conf.db(5) + for all the details. - - Perhaps you don't actually need eth0 and eth1 to be on the - same bridge. For example, if you simply want to be able to - connect each of them to virtual machines, then you can put - each of them on a bridge of its own: + - Perhaps you don't actually need eth0 and eth1 to be on the + same bridge. For example, if you simply want to be able to + connect each of them to virtual machines, then you can put + each of them on a bridge of its own: - ovs-vsctl add-br br0 - ovs-vsctl add-port br0 eth0 + ovs-vsctl add-br br0 + ovs-vsctl add-port br0 eth0 - ovs-vsctl add-br br1 - ovs-vsctl add-port br1 eth1 + ovs-vsctl add-br br1 + ovs-vsctl add-port br1 eth1 - and then connect VMs to br0 and br1. (A potential - disadvantage is that traffic cannot directly pass between br0 - and br1. Instead, it will go out eth0 and come back in eth1, - or vice versa.) + and then connect VMs to br0 and br1. (A potential + disadvantage is that traffic cannot directly pass between br0 + and br1. Instead, it will go out eth0 and come back in eth1, + or vice versa.) - - If you have a redundant or complex network topology and you - want to prevent loops, turn on spanning tree protocol (STP). - The following commands create br0, enable STP, and add eth0 - and eth1 to the bridge. The order is important because you - don't want have to have a loop in your network even - transiently: + - If you have a redundant or complex network topology and you + want to prevent loops, turn on spanning tree protocol (STP). + The following commands create br0, enable STP, and add eth0 + and eth1 to the bridge. The order is important because you + don't want have to have a loop in your network even + transiently: - ovs-vsctl add-br br0 - ovs-vsctl set bridge br0 stp_enable=true - ovs-vsctl add-port br0 eth0 - ovs-vsctl add-port br0 eth1 + ovs-vsctl add-br br0 + ovs-vsctl set bridge br0 stp_enable=true + ovs-vsctl add-port br0 eth0 + ovs-vsctl add-port br0 eth1 - The Open vSwitch implementation of STP is not well tested. - Please report any bugs you observe, but if you'd rather avoid - acting as a beta tester then another option might be your - best shot. + The Open vSwitch implementation of STP is not well tested. + Please report any bugs you observe, but if you'd rather avoid + acting as a beta tester then another option might be your + best shot. -Q: I can't seem to use Open vSwitch in a wireless network. +### Q: I can't seem to use Open vSwitch in a wireless network. A: Wireless base stations generally only allow packets with the source MAC address of NIC that completed the initial handshake. @@ -672,17 +663,17 @@ A: Wireless base stations generally only allow packets with the source point, so the same problems will show up with the Linux bridge or any other way to do bridging. -Q: I can't seem to add my PPP interface to an Open vSwitch bridge. +### Q: I can't seem to add my PPP interface to an Open vSwitch bridge. A: PPP most commonly carries IP packets, but Open vSwitch works only with Ethernet frames. The correct way to interface PPP to an Ethernet network is usually to use routing instead of switching. -Q: Is there any documentation on the database tables and fields? +### Q: Is there any documentation on the database tables and fields? A: Yes. ovs-vswitchd.conf.db(5) is a comprehensive reference. -Q: When I run ovs-dpctl I no longer see the bridges I created. Instead, +### Q: When I run ovs-dpctl I no longer see the bridges I created. Instead, I only see a datapath called "ovs-system". How can I see datapath information about a particular bridge? @@ -690,7 +681,7 @@ A: In version 1.9.0, OVS switched to using a single datapath that is shared by all bridges of that type. The "ovs-appctl dpif/*" commands provide similar functionality that is scoped by the bridge. -Q: I created a GRE port using ovs-vsctl so why can't I send traffic or +### Q: I created a GRE port using ovs-vsctl so why can't I send traffic or see the port in the datapath? A: On Linux kernels before 3.11, the OVS GRE module and Linux GRE module @@ -698,10 +689,10 @@ A: On Linux kernels before 3.11, the OVS GRE module and Linux GRE module Linux GRE module is already loaded and blocking OVS (to confirm, check dmesg for errors regarding GRE registration). To fix this, unload all GRE modules that appear in lsmod as well as the OVS kernel module. You - can then reload the OVS module following the directions in INSTALL, - which will ensure that dependencies are satisfied. + can then reload the OVS module following the directions in + [INSTALL](INSTALL.md), which will ensure that dependencies are satisfied. -Q: Open vSwitch does not seem to obey my packet filter rules. +### Q: Open vSwitch does not seem to obey my packet filter rules. A: It depends on mechanisms and configurations you want to use. @@ -731,7 +722,7 @@ A: It depends on mechanisms and configurations you want to use. you want to use ebtables rules.) On NetBSD, you might want to consider using the bridge(4) with BRIDGE_IPF option. -Q: It seems that Open vSwitch does nothing when I removed a port and +### Q: It seems that Open vSwitch does nothing when I removed a port and then immediately put it back. For example, consider that p1 is a port of type=internal: @@ -762,7 +753,7 @@ A: It's an expected behaviour. Quality of Service (QoS) ------------------------ -Q: How do I configure Quality of Service (QoS)? +### Q: How do I configure Quality of Service (QoS)? A: Suppose that you want to set up bridge br0 connected to physical Ethernet port eth0 (a 1 Gbps device) and virtual machine interfaces @@ -824,7 +815,7 @@ A: Suppose that you want to set up bridge br0 connected to physical --all option), then you will have to destroy QoS and Queue records individually. -Q: I configured Quality of Service (QoS) in my OpenFlow network by +### Q: I configured Quality of Service (QoS) in my OpenFlow network by adding records to the QoS and Queue table, but the results aren't what I expect. @@ -835,7 +826,7 @@ A: Did you install OpenFlow flows that use your queues? This is the Refer to the previous question for an example. -Q: I'd like to take advantage of some QoS feature that Open vSwitch +### Q: I'd like to take advantage of some QoS feature that Open vSwitch doesn't yet support. How do I do that? A: Open vSwitch does not implement QoS itself. Instead, it can @@ -848,27 +839,27 @@ A: Open vSwitch does not implement QoS itself. Instead, it can Linux QoS doesn't support the feature you want, then first you have to add that support to Linux.) -Q: I configured QoS, correctly, but my measurements show that it isn't +### Q: I configured QoS, correctly, but my measurements show that it isn't working as well as I expect. A: With the Linux kernel, the Open vSwitch implementation of QoS has two aspects: - - Open vSwitch configures a subset of Linux kernel QoS - features, according to what is in OVSDB. It is possible that - this code has bugs. If you believe that this is so, then you - can configure the Linux traffic control (QoS) stack directly - with the "tc" program. If you get better results that way, - you can send a detailed bug report to bugs@openvswitch.org. + - Open vSwitch configures a subset of Linux kernel QoS + features, according to what is in OVSDB. It is possible that + this code has bugs. If you believe that this is so, then you + can configure the Linux traffic control (QoS) stack directly + with the "tc" program. If you get better results that way, + you can send a detailed bug report to bugs@openvswitch.org. - It is certain that Open vSwitch cannot configure every Linux - kernel QoS feature. If you need some feature that OVS cannot - configure, then you can also use "tc" directly (or add that - feature to OVS). + It is certain that Open vSwitch cannot configure every Linux + kernel QoS feature. If you need some feature that OVS cannot + configure, then you can also use "tc" directly (or add that + feature to OVS). - - The Open vSwitch implementation of OpenFlow allows flows to - be directed to particular queues. This is pretty simple and - unlikely to have serious bugs at this point. + - The Open vSwitch implementation of OpenFlow allows flows to + be directed to particular queues. This is pretty simple and + unlikely to have serious bugs at this point. However, most problems with QoS on Linux are not bugs in Open vSwitch at all. They tend to be either configuration errors @@ -880,7 +871,7 @@ A: With the Linux kernel, the Open vSwitch implementation of QoS has tc-htb(8), tc-hfsc(8)), web resources (e.g. http://lartc.org/), or mailing lists (e.g. http://vger.kernel.org/vger-lists.html#netdev). -Q: Does Open vSwitch support OpenFlow meters? +### Q: Does Open vSwitch support OpenFlow meters? A: Since version 2.0, Open vSwitch has OpenFlow protocol support for OpenFlow meters. There is no implementation of meters in the Open @@ -891,7 +882,7 @@ A: Since version 2.0, Open vSwitch has OpenFlow protocol support for VLANs ----- -Q: What's a VLAN? +### Q: What's a VLAN? A: At the simplest level, a VLAN (short for "virtual LAN") is a way to partition a single switch into multiple switches. Suppose, for @@ -945,40 +936,40 @@ A: At the simplest level, a VLAN (short for "virtual LAN") is a way to numbers. (That said, VLAN 0 is usually synonymous with a packet that has no VLAN header, and VLAN 4095 is reserved.) -Q: VLANs don't work. +### Q: VLANs don't work. A: Many drivers in Linux kernels before version 3.3 had VLAN-related bugs. If you are having problems with VLANs that you suspect to be driver related, then you have several options: - - Upgrade to Linux 3.3 or later. + - Upgrade to Linux 3.3 or later. - - Build and install a fixed version of the particular driver - that is causing trouble, if one is available. + - Build and install a fixed version of the particular driver + that is causing trouble, if one is available. - - Use a NIC whose driver does not have VLAN problems. + - Use a NIC whose driver does not have VLAN problems. - - Use "VLAN splinters", a feature in Open vSwitch 1.4 and later - that works around bugs in kernel drivers. To enable VLAN - splinters on interface eth0, use the command: + - Use "VLAN splinters", a feature in Open vSwitch 1.4 and later + that works around bugs in kernel drivers. To enable VLAN + splinters on interface eth0, use the command: - ovs-vsctl set interface eth0 other-config:enable-vlan-splinters=true + ovs-vsctl set interface eth0 other-config:enable-vlan-splinters=true - For VLAN splinters to be effective, Open vSwitch must know - which VLANs are in use. See the "VLAN splinters" section in - the Interface table in ovs-vswitchd.conf.db(5) for details on - how Open vSwitch infers in-use VLANs. + For VLAN splinters to be effective, Open vSwitch must know + which VLANs are in use. See the "VLAN splinters" section in + the Interface table in ovs-vswitchd.conf.db(5) for details on + how Open vSwitch infers in-use VLANs. - VLAN splinters increase memory use and reduce performance, so - use them only if needed. + VLAN splinters increase memory use and reduce performance, so + use them only if needed. - - Apply the "vlan workaround" patch from the XenServer kernel - patch queue, build Open vSwitch against this patched kernel, - and then use ovs-vlan-bug-workaround(8) to enable the VLAN - workaround for each interface whose driver is buggy. + - Apply the "vlan workaround" patch from the XenServer kernel + patch queue, build Open vSwitch against this patched kernel, + and then use ovs-vlan-bug-workaround(8) to enable the VLAN + workaround for each interface whose driver is buggy. - (This is a nontrivial exercise, so this option is included - only for completeness.) + (This is a nontrivial exercise, so this option is included + only for completeness.) It is not always easy to tell whether a Linux kernel driver has buggy VLAN support. The ovs-vlan-test(8) and ovs-test(8) utilities @@ -986,13 +977,13 @@ A: Many drivers in Linux kernels before version 3.3 had VLAN-related utilities, ovs-test(8) is newer and more thorough, but ovs-vlan-test(8) may be easier to use. -Q: VLANs still don't work. I've tested the driver so I know that it's OK. +### Q: VLANs still don't work. I've tested the driver so I know that it's OK. A: Do you have VLANs enabled on the physical switch that OVS is attached to? Make sure that the port is configured to trunk the VLAN or VLANs that you are using with OVS. -Q: Outgoing VLAN-tagged traffic goes through OVS to my physical switch +### Q: Outgoing VLAN-tagged traffic goes through OVS to my physical switch and to its destination host, but OVS seems to drop incoming return traffic. @@ -1004,22 +995,22 @@ A: It's possible that you have the VLAN configured on your physical If this is the case, you have two choices: - - Change the physical switch port configuration to tag packets - it forwards to OVS with the native VLAN instead of forwarding - them untagged. + - Change the physical switch port configuration to tag packets + it forwards to OVS with the native VLAN instead of forwarding + them untagged. - - Change the OVS configuration for the physical port to a - native VLAN mode. For example, the following sets up a - bridge with port eth0 in "native-tagged" mode in VLAN 9: + - Change the OVS configuration for the physical port to a + native VLAN mode. For example, the following sets up a + bridge with port eth0 in "native-tagged" mode in VLAN 9: - ovs-vsctl add-br br0 - ovs-vsctl add-port br0 eth0 tag=9 vlan_mode=native-tagged + ovs-vsctl add-br br0 + ovs-vsctl add-port br0 eth0 tag=9 vlan_mode=native-tagged - In this situation, "native-untagged" mode will probably work - equally well. Refer to the documentation for the Port table - in ovs-vswitchd.conf.db(5) for more information. + In this situation, "native-untagged" mode will probably work + equally well. Refer to the documentation for the Port table + in ovs-vswitchd.conf.db(5) for more information. -Q: I added a pair of VMs on different VLANs, like this: +### Q: I added a pair of VMs on different VLANs, like this: ovs-vsctl add-br br0 ovs-vsctl add-port br0 eth0 @@ -1038,7 +1029,7 @@ A: It is to be expected that the VMs can't access each other. VLANs the machines you are trying to access are not on VLAN 9 (or 10) and that the Internet is not available on VLAN 9 (or 10). -Q: I added a pair of VMs on the same VLAN, like this: +### Q: I added a pair of VMs on the same VLAN, like this: ovs-vsctl add-br br0 ovs-vsctl add-port br0 eth0 @@ -1053,7 +1044,7 @@ A: It seems likely that the machines you are trying to access in the available on VLAN 9. Also, ensure VLAN 9 is set up as an allowed trunk VLAN on the upstream switch port to which eth0 is connected. -Q: Can I configure an IP address on a VLAN? +### Q: Can I configure an IP address on a VLAN? A: Yes. Use an "internal port" configured as an access port. For example, the following configures IP address 192.168.0.7 on VLAN 9. @@ -1069,7 +1060,7 @@ A: Yes. Use an "internal port" configured as an access port. For See also the following question. -Q: I configured one IP address on VLAN 0 and another on VLAN 9, like +### Q: I configured one IP address on VLAN 0 and another on VLAN 9, like this: ovs-vsctl add-br br0 @@ -1084,20 +1075,20 @@ Q: I configured one IP address on VLAN 0 and another on VLAN 9, like A: RFC 1122 section 3.3.4.2 "Multihoming Requirements" describes two approaches to IP address handling in Internet hosts: - - In the "Strong ES Model", where an ES is a host ("End - System"), an IP address is primarily associated with a - particular interface. The host discards packets that arrive - on interface A if they are destined for an IP address that is - configured on interface B. The host never sends packets from - interface A using a source address configured on interface B. - - - In the "Weak ES Model", an IP address is primarily associated - with a host. The host accepts packets that arrive on any - interface if they are destined for any of the host's IP - addresses, even if the address is configured on some - interface other than the one on which it arrived. The host - does not restrict itself to sending packets from an IP - address associated with the originating interface. + - In the "Strong ES Model", where an ES is a host ("End + System"), an IP address is primarily associated with a + particular interface. The host discards packets that arrive + on interface A if they are destined for an IP address that is + configured on interface B. The host never sends packets from + interface A using a source address configured on interface B. + + - In the "Weak ES Model", an IP address is primarily associated + with a host. The host accepts packets that arrive on any + interface if they are destined for any of the host's IP + addresses, even if the address is configured on some + interface other than the one on which it arrived. The host + does not restrict itself to sending packets from an IP + address associated with the originating interface. Linux uses the weak ES model. That means that when packets destined to the VLAN 9 IP address arrive on eth0 and are bridged to @@ -1111,7 +1102,7 @@ A: RFC 1122 section 3.3.4.2 "Multihoming Requirements" describes two BSD uses the strong ES model. -Q: My OpenFlow controller doesn't see the VLANs that I expect. +### Q: My OpenFlow controller doesn't see the VLANs that I expect. A: The configuration for VLANs in the Open vSwitch database (e.g. via ovs-vsctl) only affects traffic that goes through Open vSwitch's @@ -1129,15 +1120,15 @@ A: The configuration for VLANs in the Open vSwitch database (e.g. via controller. In situations where this is not suitable, you can implement VLAN handling yourself, e.g.: - - If a packet comes in on an access port, and the flow table - needs to send it out on a trunk port, then the flow can add - the appropriate VLAN tag with the "mod_vlan_vid" action. + - If a packet comes in on an access port, and the flow table + needs to send it out on a trunk port, then the flow can add + the appropriate VLAN tag with the "mod_vlan_vid" action. - - If a packet comes in on a trunk port, and the flow table - needs to send it out on an access port, then the flow can - strip the VLAN tag with the "strip_vlan" action. + - If a packet comes in on a trunk port, and the flow table + needs to send it out on an access port, then the flow can + strip the VLAN tag with the "strip_vlan" action. -Q: I configured ports on a bridge as access ports with different VLAN +### Q: I configured ports on a bridge as access ports with different VLAN tags, like this: ovs-vsctl add-br br0 @@ -1155,7 +1146,7 @@ A: Do you have a controller configured on br0 (as the commands above OpenFlow controller doesn't see the VLANs that I expect," and you can refer to the answer there for more information. -Q: How MAC learning works with VLANs? +### Q: How MAC learning works with VLANs? A: Open vSwitch implements Independent VLAN Learning (IVL) for OFPP_NORMAL action. I.e. it logically has separate learning tables @@ -1165,7 +1156,7 @@ A: Open vSwitch implements Independent VLAN Learning (IVL) for VXLANs ----- -Q: What's a VXLAN? +### Q: What's a VXLAN? A: VXLAN stands for Virtual eXtensible Local Area Network, and is a means to solve the scaling challenges of VLAN networks in a multi-tenant @@ -1175,7 +1166,7 @@ A: VXLAN stands for Virtual eXtensible Local Area Network, and is a means http://tools.ietf.org/html/draft-mahalingam-dutt-dcops-vxlan-03 -Q: How much of the VXLAN protocol does Open vSwitch currently support? +### Q: How much of the VXLAN protocol does Open vSwitch currently support? A: Open vSwitch currently supports the framing format for packets on the wire. There is currently no support for the multicast aspects of VXLAN. @@ -1183,7 +1174,7 @@ A: Open vSwitch currently supports the framing format for packets on the pre-provision MAC to IP address mappings either manually or from a controller. -Q: What destination UDP port does the VXLAN implementation in Open vSwitch +### Q: What destination UDP port does the VXLAN implementation in Open vSwitch use? A: By default, Open vSwitch will use the assigned IANA port for VXLAN, which @@ -1200,13 +1191,13 @@ A: By default, Open vSwitch will use the assigned IANA port for VXLAN, which Using OpenFlow (Manually or Via Controller) ------------------------------------------- -Q: What versions of OpenFlow does Open vSwitch support? +### Q: What versions of OpenFlow does Open vSwitch support? A: The following table lists the versions of OpenFlow supported by each version of Open vSwitch: Open vSwitch OF1.0 OF1.1 OF1.2 OF1.3 OF1.4 OF1.5 - =============== ===== ===== ===== ===== ===== ===== + ###============ ===== ===== ===== ===== ===== ===== 1.9 and earlier yes --- --- --- --- --- 1.10 yes --- [*] [*] --- --- 1.11 yes --- [*] [*] --- --- @@ -1225,17 +1216,17 @@ A: The following table lists the versions of OpenFlow supported by vSwitch 2.3 and later, but not enabled by default. In any case, the user may override the default: - - To enable OpenFlow 1.0, 1.1, 1.2, and 1.3 on bridge br0: + - To enable OpenFlow 1.0, 1.1, 1.2, and 1.3 on bridge br0: - ovs-vsctl set bridge br0 protocols=OpenFlow10,OpenFlow11,OpenFlow12,OpenFlow13 + ovs-vsctl set bridge br0 protocols=OpenFlow10,OpenFlow11,OpenFlow12,OpenFlow13 - - To enable OpenFlow 1.0, 1.1, 1.2, 1.3, 1.4, and 1.5 on bridge br0: + - To enable OpenFlow 1.0, 1.1, 1.2, 1.3, 1.4, and 1.5 on bridge br0: - ovs-vsctl set bridge br0 protocols=OpenFlow10,OpenFlow11,OpenFlow12,OpenFlow13,OpenFlow14,OpenFlow15 + ovs-vsctl set bridge br0 protocols=OpenFlow10,OpenFlow11,OpenFlow12,OpenFlow13,OpenFlow14,OpenFlow15 - - To enable only OpenFlow 1.0 on bridge br0: + - To enable only OpenFlow 1.0 on bridge br0: - ovs-vsctl set bridge br0 protocols=OpenFlow10 + ovs-vsctl set bridge br0 protocols=OpenFlow10 All current versions of ovs-ofctl enable only OpenFlow 1.0 by default. Use the -O option to enable support for later versions of @@ -1252,7 +1243,7 @@ A: The following table lists the versions of OpenFlow supported by by default. Also, the OpenFlow 1.5 specification is still under development and thus subject to change. -Q: Does Open vSwitch support MPLS? +### Q: Does Open vSwitch support MPLS? A: Before version 1.11, Open vSwitch did not support MPLS. That is, these versions can match on MPLS Ethernet types, but they cannot @@ -1275,7 +1266,7 @@ A: Before version 1.11, Open vSwitch did not support MPLS. That is, Open vSwitch version 2.4 will have kernel support for MPLS, yielding improved performance. -Q: I'm getting "error type 45250 code 0". What's that? +### Q: I'm getting "error type 45250 code 0". What's that? A: This is a Open vSwitch extension to OpenFlow error codes. Open vSwitch uses this extension when it must report an error to an @@ -1329,7 +1320,7 @@ A: By default, Open vSwitch assumes that OpenFlow controllers are ovs-vsctl set controller br0 connection-mode=out-of-band -Q: I configured all my controllers for out-of-band control mode but +### Q: I configured all my controllers for out-of-band control mode but "ovs-appctl bridge/dump-flows" still shows some hidden flows. A: You probably have a remote manager configured (e.g. with "ovs-vsctl @@ -1343,11 +1334,11 @@ A: You probably have a remote manager configured (e.g. with "ovs-vsctl if all the bridge's controllers were configured for out-of-band control. -Q: My OpenFlow controller doesn't see the VLANs that I expect. +### Q: My OpenFlow controller doesn't see the VLANs that I expect. A: See answer under "VLANs", above. -Q: I ran "ovs-ofctl add-flow br0 nw_dst=192.168.0.1,actions=drop" +### Q: I ran "ovs-ofctl add-flow br0 nw_dst=192.168.0.1,actions=drop" but I got a funny message like this: ofp_util|INFO|normalization changed ofp_match, details: @@ -1378,7 +1369,7 @@ A: The term "normalization" in the log message means that a flow TCP source port 1234, write "tcp,tp_src=1234", or to match UDP source port 1234, write "udp,tp_src=1234". -Q: How can I figure out the OpenFlow port number for a given port? +### Q: How can I figure out the OpenFlow port number for a given port? A: The OFPT_FEATURES_REQUEST message requests an OpenFlow switch to respond with an OFPT_FEATURES_REPLY that, among other information, @@ -1406,32 +1397,32 @@ A: The OFPT_FEATURES_REQUEST message requests an OpenFlow switch to normally an intermittent condition (unless ovs-vswitchd is not running). -Q: I added some flows with my controller or with ovs-ofctl, but when I +### Q: I added some flows with my controller or with ovs-ofctl, but when I run "ovs-dpctl dump-flows" I don't see them. A: ovs-dpctl queries a kernel datapath, not an OpenFlow switch. It won't display the information that you want. You want to use "ovs-ofctl dump-flows" instead. -Q: It looks like each of the interfaces in my bonded port shows up +### Q: It looks like each of the interfaces in my bonded port shows up as an individual OpenFlow port. Is that right? A: Yes, Open vSwitch makes individual bond interfaces visible as OpenFlow ports, rather than the bond as a whole. The interfaces are treated together as a bond for only a few purposes: - - Sending a packet to the OFPP_NORMAL port. (When an OpenFlow - controller is not configured, this happens implicitly to - every packet.) + - Sending a packet to the OFPP_NORMAL port. (When an OpenFlow + controller is not configured, this happens implicitly to + every packet.) - - Mirrors configured for output to a bonded port. + - Mirrors configured for output to a bonded port. It would make a lot of sense for Open vSwitch to present a bond as a single OpenFlow port. If you want to contribute an implementation of such a feature, please bring it up on the Open vSwitch development mailing list at dev@openvswitch.org. -Q: I have a sophisticated network setup involving Open vSwitch, VMs or +### Q: I have a sophisticated network setup involving Open vSwitch, VMs or multiple hosts, and other components. The behavior isn't what I expect. Help! @@ -1449,71 +1440,71 @@ A: To debug network behavior problems, trace the path of a packet, Tools available for tracing include the following: - - "tcpdump" and "wireshark" for observing hops across network - devices, such as Open vSwitch internal devices and physical - wires. + - "tcpdump" and "wireshark" for observing hops across network + devices, such as Open vSwitch internal devices and physical + wires. - - "ovs-appctl dpif/dump-flows
" in Open vSwitch 1.10 and - later or "ovs-dpctl dump-flows
" in earlier versions. - These tools allow one to observe the actions being taken on - packets in ongoing flows. + - "ovs-appctl dpif/dump-flows
" in Open vSwitch 1.10 and + later or "ovs-dpctl dump-flows
" in earlier versions. + These tools allow one to observe the actions being taken on + packets in ongoing flows. - See ovs-vswitchd(8) for "ovs-appctl dpif/dump-flows" - documentation, ovs-dpctl(8) for "ovs-dpctl dump-flows" - documentation, and "Why are there so many different ways to - dump flows?" above for some background. + See ovs-vswitchd(8) for "ovs-appctl dpif/dump-flows" + documentation, ovs-dpctl(8) for "ovs-dpctl dump-flows" + documentation, and "Why are there so many different ways to + dump flows?" above for some background. - - "ovs-appctl ofproto/trace" to observe the logic behind how - ovs-vswitchd treats packets. See ovs-vswitchd(8) for - documentation. You can out more details about a given flow - that "ovs-dpctl dump-flows" displays, by cutting and pasting - a flow from the output into an "ovs-appctl ofproto/trace" - command. + - "ovs-appctl ofproto/trace" to observe the logic behind how + ovs-vswitchd treats packets. See ovs-vswitchd(8) for + documentation. You can out more details about a given flow + that "ovs-dpctl dump-flows" displays, by cutting and pasting + a flow from the output into an "ovs-appctl ofproto/trace" + command. - - SPAN, RSPAN, and ERSPAN features of physical switches, to - observe what goes on at these physical hops. + - SPAN, RSPAN, and ERSPAN features of physical switches, to + observe what goes on at these physical hops. Starting at the origin of a given packet, observe the packet at each hop in turn. For example, in one plausible scenario, you might: - 1. "tcpdump" the "eth" interface through which an ARP egresses - a VM, from inside the VM. + 1. "tcpdump" the "eth" interface through which an ARP egresses + a VM, from inside the VM. - 2. "tcpdump" the "vif" or "tap" interface through which the ARP - ingresses the host machine. + 2. "tcpdump" the "vif" or "tap" interface through which the ARP + ingresses the host machine. - 3. Use "ovs-dpctl dump-flows" to spot the ARP flow and observe - the host interface through which the ARP egresses the - physical machine. You may need to use "ovs-dpctl show" to - interpret the port numbers. If the output seems surprising, - you can use "ovs-appctl ofproto/trace" to observe details of - how ovs-vswitchd determined the actions in the "ovs-dpctl - dump-flows" output. + 3. Use "ovs-dpctl dump-flows" to spot the ARP flow and observe + the host interface through which the ARP egresses the + physical machine. You may need to use "ovs-dpctl show" to + interpret the port numbers. If the output seems surprising, + you can use "ovs-appctl ofproto/trace" to observe details of + how ovs-vswitchd determined the actions in the "ovs-dpctl + dump-flows" output. - 4. "tcpdump" the "eth" interface through which the ARP egresses - the physical machine. + 4. "tcpdump" the "eth" interface through which the ARP egresses + the physical machine. - 5. "tcpdump" the "eth" interface through which the ARP - ingresses the physical machine, at the remote host that - receives the ARP. + 5. "tcpdump" the "eth" interface through which the ARP + ingresses the physical machine, at the remote host that + receives the ARP. - 6. Use "ovs-dpctl dump-flows" to spot the ARP flow on the - remote host that receives the ARP and observe the VM "vif" - or "tap" interface to which the flow is directed. Again, - "ovs-dpctl show" and "ovs-appctl ofproto/trace" might help. + 6. Use "ovs-dpctl dump-flows" to spot the ARP flow on the + remote host that receives the ARP and observe the VM "vif" + or "tap" interface to which the flow is directed. Again, + "ovs-dpctl show" and "ovs-appctl ofproto/trace" might help. - 7. "tcpdump" the "vif" or "tap" interface to which the ARP is - directed. + 7. "tcpdump" the "vif" or "tap" interface to which the ARP is + directed. - 8. "tcpdump" the "eth" interface through which the ARP - ingresses a VM, from inside the VM. + 8. "tcpdump" the "eth" interface through which the ARP + ingresses a VM, from inside the VM. It is likely that during one of these steps you will figure out the problem. If not, then follow the ARP reply back to the origin, in reverse. -Q: How do I make a flow drop packets? +### Q: How do I make a flow drop packets? A: To drop a packet is to receive it without forwarding it. OpenFlow explicitly specifies forwarding actions. Thus, a flow with an @@ -1534,7 +1525,7 @@ A: To drop a packet is to receive it without forwarding it. OpenFlow "drop" is not an action, either in OpenFlow or Open vSwitch. Rather, it is only a way to say that there are no actions. -Q: I added a flow to send packets out the ingress port, like this: +### Q: I added a flow to send packets out the ingress port, like this: ovs-ofctl add-flow br0 in_port=2,actions=2 @@ -1584,7 +1575,7 @@ A: Yes, OpenFlow requires a switch to ignore attempts to send a packet 2,3,4,5,6,\ pop:NXM_OF_IN_PORT[] -Q: My bridge br0 has host 192.168.0.1 on port 1 and host 192.168.0.2 +### Q: My bridge br0 has host 192.168.0.1 on port 1 and host 192.168.0.2 on port 2. I set up flows to forward only traffic destined to the other host and drop other traffic, like this: @@ -1618,7 +1609,7 @@ A: These flows drop the ARP packets that IP hosts use to establish IP priority=5,in_port=1,dl_dst=01:00:00:00:00:00/01:00:00:00:00:00,actions=2 priority=5,in_port=2,dl_dst=01:00:00:00:00:00/01:00:00:00:00:00,actions=1 -Q: My bridge disconnects from my controller on add-port/del-port. +### Q: My bridge disconnects from my controller on add-port/del-port. A: Reconfiguring your bridge can change your bridge's datapath-id because Open vSwitch generates datapath-id from the MAC address of one of its ports. @@ -1633,13 +1624,14 @@ A: Reconfiguring your bridge can change your bridge's datapath-id because Development ----------- -Q: How do I implement a new OpenFlow message? +### Q: How do I implement a new OpenFlow message? A: Add your new message to "enum ofpraw" and "enum ofptype" in lib/ofp-msgs.h, following the existing pattern. Then recompile and fix all of the new warnings, implementing new functionality for the new message as needed. (If you configure with --enable-Werror, as - described in INSTALL, then it is impossible to miss any warnings.) + described in [INSTALL](INSTALL.md), then it is impossible to miss + any warnings.) If you need to add an OpenFlow vendor extension message for a vendor that doesn't yet have any extension messages, then you will diff --git a/INSTALL.DPDK b/INSTALL.DPDK deleted file mode 100644 index d3b03cf0d..000000000 --- a/INSTALL.DPDK +++ /dev/null @@ -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= - -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= - -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. diff --git a/INSTALL.DPDK.md b/INSTALL.DPDK.md new file mode 100644 index 000000000..d612b8fe3 --- /dev/null +++ b/INSTALL.DPDK.md @@ -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= + + 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= + + 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. diff --git a/INSTALL.Debian b/INSTALL.Debian.md similarity index 79% rename from INSTALL.Debian rename to INSTALL.Debian.md index 34251a1b5..59e0c973b 100644 --- a/INSTALL.Debian +++ b/INSTALL.Debian.md @@ -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. diff --git a/INSTALL.Docker b/INSTALL.Docker.md similarity index 84% rename from INSTALL.Docker rename to INSTALL.Docker.md index 1c492f3fe..29560363f 100644 --- a/INSTALL.Docker +++ b/INSTALL.Docker.md @@ -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. diff --git a/INSTALL.Fedora b/INSTALL.Fedora.md similarity index 86% rename from INSTALL.Fedora rename to INSTALL.Fedora.md index aa76c06ab..bfde181cd 100644 --- a/INSTALL.Fedora +++ b/INSTALL.Fedora.md @@ -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 diff --git a/INSTALL.KVM b/INSTALL.KVM.md similarity index 73% rename from INSTALL.KVM rename to INSTALL.KVM.md index 01b11710e..4d847b6e9 100644 --- a/INSTALL.KVM +++ b/INSTALL.KVM.md @@ -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 diff --git a/INSTALL.Libvirt b/INSTALL.Libvirt.md similarity index 82% rename from INSTALL.Libvirt rename to INSTALL.Libvirt.md index fc5575cb9..0ee676cb7 100644 --- a/INSTALL.Libvirt +++ b/INSTALL.Libvirt.md @@ -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 + % virsh edit -Lookup in the Domain XML file the section. There should be one +Lookup in the Domain XML file the `` section. There should be one such XML section for each interface the VM has. - ... +```
- ... +``` And change it to something like this: - ... +```
- ... + ``` -The interface type must be set to "bridge". The XML element +The interface type must be set to "bridge". The `` XML element specifies to which bridge this interface will be attached to. The - element indicates that the bridge in element is an +`` element indicates that the bridge in `` 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 --------------- diff --git a/INSTALL.NetBSD b/INSTALL.NetBSD.md similarity index 60% rename from INSTALL.NetBSD rename to INSTALL.NetBSD.md index aab8793e9..47322505a 100644 --- a/INSTALL.NetBSD +++ b/INSTALL.NetBSD.md @@ -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 diff --git a/INSTALL.RHEL b/INSTALL.RHEL.md similarity index 85% rename from INSTALL.RHEL rename to INSTALL.RHEL.md index 080296b9c..1d3d0f8ae 100644 --- a/INSTALL.RHEL +++ b/INSTALL.RHEL.md @@ -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/ ls -l build/ + ``` - where is the version number of the RHEL 6 kernel. (The + where `` 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/ rm build ln -s /usr/src/kernels/ build + ``` - where is the name of an existing directory under - /usr/src/kernels, whose name should be similar to but may + where `` is the name of an existing directory under + /usr/src/kernels, whose name should be similar to `` 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 diff --git a/INSTALL.SSL b/INSTALL.SSL.md similarity index 74% rename from INSTALL.SSL rename to INSTALL.SSL.md index a6931d20c..aecb2b5f3 100644 --- a/INSTALL.SSL +++ b/INSTALL.SSL.md @@ -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.: diff --git a/INSTALL.Windows b/INSTALL.Windows.md similarity index 95% rename from INSTALL.Windows rename to INSTALL.Windows.md index bba0710b8..fd333bc0f 100644 --- a/INSTALL.Windows +++ b/INSTALL.Windows.md @@ -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. diff --git a/INSTALL.XenServer b/INSTALL.XenServer.md similarity index 88% rename from INSTALL.XenServer rename to INSTALL.XenServer.md index 8c07d24f9..e4408ddf8 100644 --- a/INSTALL.XenServer +++ b/INSTALL.XenServer.md @@ -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= KERNEL_NAME= 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: - is the version number that appears in the + `` is the version number that appears in the name of the Open vSwitch tarball, e.g. 0.90.0. - is the name of the XenServer kernel package, + `` is the name of the XenServer kernel package, e.g. kernel-xen or kernel-NAME-xen, without the "kernel-" prefix. - is the output of: + `` is the output of: rpm -q --queryformat "%{Version}-%{Release}" , e.g. 2.6.32.12-0.7.1.xs5.6.100.323.170596, where is the name of the -devel package corresponding to . - is either "xen" or "kdump". + `` 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@: @@ -93,12 +96,13 @@ copy the "openvswitch" and "openvswitch-modules-xen" RPMs to that host with (At this point you will have to enter '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@ + `ssh root@` (At this point you will have to enter '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. diff --git a/INSTALL b/INSTALL.md similarity index 76% rename from INSTALL rename to INSTALL.md index 3cfdc0412..536cbfbc4 100644 --- a/INSTALL +++ b/INSTALL.md @@ -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 are reported in files -named tests/testsuite.dir//valgrind.*. You may find that the +you do this, the "valgrind" results for test `` are reported in files +named `tests/testsuite.dir//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= -where is the absolute path to the "oft" program in + `make check-oftest OFT=` +where `` 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= OFTFLAGS='--verbose -T basic.Echo' + `make check-oftest OFT= 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= OFTFLAGS='--port=6653' + `make check-oftest OFT= 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= -where is the absolute path to the root of the Ryu -source distribution. The default is $srcdir/../ryu + `make check-ryu RYUDIR=` +where `` is the absolute path to the root of the Ryu +source distribution. The default `` 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. diff --git a/INSTALL.userspace b/INSTALL.userspace.md similarity index 84% rename from INSTALL.userspace rename to INSTALL.userspace.md index f54b93e2e..a9f881c32 100644 --- a/INSTALL.userspace +++ b/INSTALL.userspace.md @@ -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 ------------- diff --git a/IntegrationGuide b/IntegrationGuide.md similarity index 93% rename from IntegrationGuide rename to IntegrationGuide.md index 976936b71..5d3e574b6 100644 --- a/IntegrationGuide +++ b/IntegrationGuide.md @@ -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}"' diff --git a/Makefile.am b/Makefile.am index 846172d85..343dffa18 100644 --- a/Makefile.am +++ b/Makefile.am @@ -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 diff --git a/NEWS b/NEWS index abcb52571..31d00de9c 100644 --- a/NEWS +++ b/NEWS @@ -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' diff --git a/OPENFLOW-1.1+ b/OPENFLOW-1.1+ deleted file mode 100644 index 01adf7267..000000000 --- a/OPENFLOW-1.1+ +++ /dev/null @@ -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. diff --git a/OPENFLOW-1.1+.md b/OPENFLOW-1.1+.md new file mode 100644 index 000000000..36fd1681b --- /dev/null +++ b/OPENFLOW-1.1+.md @@ -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. diff --git a/PORTING b/PORTING.md similarity index 74% rename from PORTING rename to PORTING.md index 79b1aaf84..7e5de00d3 100644 --- a/PORTING +++ b/PORTING.md @@ -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 diff --git a/README-lisp b/README-lisp.md similarity index 100% rename from README-lisp rename to README-lisp.md diff --git a/README.md b/README.md index 538613062..5084c310d 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/REPORTING-BUGS b/REPORTING-BUGS deleted file mode 100644 index 86510d276..000000000 --- a/REPORTING-BUGS +++ /dev/null @@ -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 " - for each 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/ diff --git a/REPORTING-BUGS.md b/REPORTING-BUGS.md new file mode 100644 index 000000000..4e08cb1e0 --- /dev/null +++ b/REPORTING-BUGS.md @@ -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 ` + for each `` 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/ diff --git a/TODO b/TODO.md similarity index 90% rename from TODO rename to TODO.md index e11089ac7..581e213b6 100644 --- a/TODO +++ b/TODO.md @@ -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 diff --git a/WHY-OVS b/WHY-OVS.md similarity index 98% rename from WHY-OVS rename to WHY-OVS.md index f5f47ff2b..d31e69e71 100644 --- a/WHY-OVS +++ b/WHY-OVS.md @@ -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 diff --git a/datapath/Modules.mk b/datapath/Modules.mk index 90e158cd2..72cb4dcbf 100644 --- a/datapath/Modules.mk +++ b/datapath/Modules.mk @@ -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)) diff --git a/datapath/README b/datapath/README.md similarity index 86% rename from datapath/README rename to datapath/README.md index 37c20ee24..a8effa354 100644 --- a/datapath/README +++ b/datapath/README.md @@ -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 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 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 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. diff --git a/lib/dpif.h b/lib/dpif.h index f88fa78d8..c6e045bec 100644 --- a/lib/dpif.h +++ b/lib/dpif.h @@ -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. diff --git a/rhel/openvswitch-fedora.spec.in b/rhel/openvswitch-fedora.spec.in index d3b0ecb1f..0a1fe00e3 100644 --- a/rhel/openvswitch-fedora.spec.in +++ b/rhel/openvswitch-fedora.spec.in @@ -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 diff --git a/rhel/openvswitch.spec.in b/rhel/openvswitch.spec.in index 5d26d5940..9100ad095 100644 --- a/rhel/openvswitch.spec.in +++ b/rhel/openvswitch.spec.in @@ -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 diff --git a/third-party/README b/third-party/README.md similarity index 100% rename from third-party/README rename to third-party/README.md diff --git a/third-party/automake.mk b/third-party/automake.mk index 02636bb53..bce5f8b5e 100644 --- a/third-party/automake.mk +++ b/third-party/automake.mk @@ -1,3 +1,3 @@ EXTRA_DIST += \ - third-party/README \ + third-party/README.md \ third-party/ofp-tcpdump.patch diff --git a/tutorial/Tutorial b/tutorial/Tutorial.md similarity index 87% rename from tutorial/Tutorial rename to tutorial/Tutorial.md index 0506a2075..0cf52fb15 100644 --- a/tutorial/Tutorial +++ b/tutorial/Tutorial.md @@ -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: diff --git a/tutorial/automake.mk b/tutorial/automake.mk index 82ad66d73..8a75a836f 100644 --- a/tutorial/automake.mk +++ b/tutorial/automake.mk @@ -1,5 +1,5 @@ EXTRA_DIST += \ - tutorial/Tutorial \ + tutorial/Tutorial.md \ tutorial/ovs-sandbox \ tutorial/t-setup \ tutorial/t-stage0 \ diff --git a/utilities/ovs-ctl.8 b/utilities/ovs-ctl.8 index 0f7040318..2720d8c8e 100644 --- a/utilities/ovs-ctl.8 +++ b/utilities/ovs-ctl.8 @@ -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). diff --git a/vtep/README.ovs-vtep b/vtep/README.ovs-vtep.md similarity index 93% rename from vtep/README.ovs-vtep rename to vtep/README.ovs-vtep.md index 5ce63c7cb..e3bb8bbed 100644 --- a/vtep/README.ovs-vtep +++ b/vtep/README.ovs-vtep.md @@ -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 diff --git a/vtep/automake.mk b/vtep/automake.mk index 360ed3557..f2a1db290 100644 --- a/vtep/automake.mk +++ b/vtep/automake.mk @@ -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 -- 2.20.1