[ovs-dev] [IPv6 7/7] DESIGN: Add document describing design decisions in OVS.

[Justin Pettit]

A first cut at describing design decisions made in Open vSwitch.  The
primary purpose is to document decisions that may impact deployments
using different assumptions than those we made.  Currently, only IPv6 is
discussed.

xxx This version does not properly describe fragment handling, since
xxx it was still under discussion.  It will be resolved before being
xxx pushed.
---
 DESIGN      |   80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 Makefile.am |    1 +
 2 files changed, 81 insertions(+), 0 deletions(-)
 create mode 100644 DESIGN

diff --git a/DESIGN b/DESIGN
new file mode 100644
index 0000000..9f099e8
--- /dev/null
+++ b/DESIGN
@@ -0,0 +1,80 @@
+                     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
+impossible to predict how Open vSwitch will be used in all environments.
+Understanding assumptions made by Open vSwitch is critical to a
+successful deployment.  The end of this document contains contact
+information that can be used to let us know how we can make Open vSwitch
+more generally useful.
+
+
+IPv6
+====
+
+Open vSwitch supports stateless handling of IPv6 packets.  Flows can be
+written to support matching TCP, UDP, and ICMPv6 headers within an IPv6
+packet.  Deeper matching of some Neighbor Discovery messages is also
+supported.
+
+IPv6 was not designed to interact well with middle-boxes.  This,
+combined with Open vSwitch's stateless nature, have affected the
+processing of IPv6 traffic, which is detailed below.
+
+Extension Headers
+-----------------
+
+The IPv6 header is incredibly basic with the intention of only
+containing information relevant for routing packets between two
+endpoints.  IPv6 relies heavily on the use of extension headers to
+provide any other functionality.  Unfortunately, the extension headers
+were designed in such a way that it is impossible to move to the next
+header (including the layer-4 payload) unless the current header is
+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
+    * Mobility
+
+When a header is encountered that is not in that list, it is considered
+"terminal".  A terminal header's IP protocol value is stored in
+"nw_proto" for matching purposes.  If a terminal header is TCP, UDP, or
+ICMPv6, the packet will be further processed in an attempt to extract
+layer-4 information.
+
+Fragments
+---------
+
+IPv6 requires that every link in the internet have an MTU of 1280 octets
+or greater (RFC 2460).  As such, we make the assumption that a terminal
+header (as described above in "Extension Headers") is reachable in the
+first fragment.  In this case, the terminal header's IP protocol type is
+stored in the "nw_proto" field for matching purposes.  If a terminal
+header cannot be found in the first fragment (one with a fragment offset
+of zero), the packet is dropped.  Subsequent fragments (those with a
+non-zero fragment offset) are always allowed and the "nw_proto" field is
+set to the header type for fragments (44).
+
+Jumbograms
+----------
+
+An IPv6 jumbogram (RFC 2675) is a packet containing a payload longer
+than 65,535 octets.  A jumbogram is only relevant in subnets with a link
+MTU greater than 65,575 octets, and are not required to be supported on
+nodes that do not connect to link with such large MTUs.  Use of
+jumbograms require changes to TCP and UDP in order to work around 16-bit
+assumptions in those protocols.  Currently, Open vSwitch doesn't process
+jumbograms.
+
+
+Suggestions
+===========
+
+Suggestions to improve Open vSwitch are welcome at discuss at openvswitch.org.
diff --git a/Makefile.am b/Makefile.am
index deae512..71a0652 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -31,6 +31,7 @@ CLEAN_LOCAL =
 DISTCLEANFILES =
 EXTRA_DIST = \
 	CodingStyle \
+	DESIGN \
 	INSTALL.KVM \
 	INSTALL.Linux \
 	INSTALL.OpenFlow \
-- 
1.7.1