From: Justin Pettit Date: Wed, 4 Feb 2009 22:26:11 +0000 (-0800) Subject: Changed control protocol name to OpenFlow Management Protocol. X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d5f19352721f170adaf0ae08ecc70ccad142d018;p=openvswitch Changed control protocol name to OpenFlow Management Protocol. --- diff --git a/doc/ofcp-spec/ofcp-spec.tex b/doc/ofcp-spec/ofcp-spec.tex deleted file mode 100644 index db7be031..00000000 --- a/doc/ofcp-spec/ofcp-spec.tex +++ /dev/null @@ -1,642 +0,0 @@ -% Created 2009-02-02 Mon 17:09 -\documentclass[11pt,a4paper]{article} -\usepackage[utf8]{inputenc} -\usepackage[T1]{fontenc} -\usepackage{graphicx} -\usepackage{longtable} -\usepackage{hyperref} - - -\title{Remote Switch Control Protocol} -\author{Keith Amidon} -\date{02 February 2009} - -\begin{document} - -\maketitle - -\setcounter{tocdepth}{3} -\tableofcontents -\vspace*{1cm} - -\section{Goals} -\label{sec-1} - - -The high-level design goals for the protocol are described in this -section. - -\begin{itemize} -\item Rapid implementation - - Most importantly, Nicira must implement the protocol quickly to - meet current business objectives. However, the ability to implement - the protocol rapidly should be a benefit to anyone implementing the - protocol. -\item Support ``all'' switch features - - The controller should be able to learn about all available switch - features and retrieve and modify their values through the protocol. -\item ``Multi-master'' - - It must be possible to make changes at both the controller and the - switch. When changes are made and connectivity exists between the - switch and the controller, both sides should be resynchronized - within a short period of time (< 1 sec??). -\item Extensible - - To support future enhancements, the protocol must be capable of - accommodating additional configuration settings and - upgrading/downgrading configuration appropriately. -\item Scalable - - The protocol should be able to handle any size switch, from a few - ports to hundreds of ports. -\item Minimal cost of implementation on the switch - - One of the selling points of OpenFlow is the ability to take cost - out of switches by implementing complex network-wide functionality - in the controller. It is thus preferable to minimize the cost of - implementation on the switch. -\end{itemize} -\section{Specification} -\label{sec-2} - - - The remote switch control protocol is based on the OpenFlow - protocol, with which it is often expected to be used. It augments - the flow table management provided by the OpenFlow protocol with - more general switch management functions required in a full-featured - switch. - -\subsection{Connection Maintenance} -\label{sec-2.1} - - - As with OpenFlow, the switch is responsible for initiating the - connection to the controller at a user configurable IP address and - TCP port. The default destination port for the connection is 6632, - one less than the default OpenFlow destination port 6633. The IP - address of the controller may be discovered through the same - discovery protocol defined for OpenFlow. - - The switch must attempt to maintain an open connection to the - controller at all times while in an operational state, although the - exact details for detecting connection failure and opening a new - connection are left to individual implementations. - - After connection establishment, both sides must send \hyperref[sec-2.6.1]{hello messages} - to each other before any other messages are sent. - - While the default ports for OpenFlow and the Remote Switch Control - Protocol are different, the latter is deliberately designed to be - able to coexist on the same port, in which case the appropriate - connection type can be determined by examining the initial hello - message sent after connection establishment. - -\subsection{Encryption} -\label{sec-2.2} - - - The remote switch control protocol uses the same encryption - mechanism defined in the analogous section of the OpenFlow - specification. It is expected, but not required, that the remote - switch control protocol will use the same keys as the OpenFlow - protocol for authentication of either end of the connection. - -\subsection{Framing} -\label{sec-2.3} - - - The remote switch control protocol uses the same basic header as - the OpenFlow protocol, defined as \verb|ofp_header| in the OpenFlow - specification. The fields of this header are used in the same way - as they are in the OpenFlow protocol except that the type IDs - generally have different meanings. However, a few message types - are shared among the two protocols, in which case they have the - same message type code in both protocols. - - Each message type is further described in subsequent sections of - this document. The message types IDs are defined by: - -{ \footnotesize - -\begin{verbatim} - enum rscp_type { - RSCP_HELLO, /* Message Types Shared with OpenFlow. */ - RSCP_ERROR, /* Message Types Shared with OpenFlow. */ - RSCP_ECHO_REQUEST, /* Message Types Shared with OpenFlow. */ - RSCP_ECHO_REPLY, /* Message Types Shared with OpenFlow. */ - RSCP_VENDOR, /* Message Types Shared with OpenFlow. */ - RSCP_RESERVED_0, /* Reserved Message Types. */ - RSCP_RESERVED_1, /* Reserved Message Types. */ - RSCP_EXTENDED_DATA, /* Extended Data Message */ - RSCP_CAPABILITY_REQUEST,/* Remote Control Protocol-specific. */ - RSCP_CAPABILITY_REPLY, /* Remote Control Protocol-specific. */ - RSCP_SWITCH_RESOURCES, /* Remote Control Protocol-specific. */ - RSCP_CONFIG_UPDATE, /* Remote Control Protocol-specific. */ - RSCP_CONFIG_UPDATE_ACK, /* Remote Control Protocol-specific. */ - RSCP_HOST_INFO /* Remote Control Protocol-specific. */ - }; - -\end{verbatim} - - -} - -\subsection{Type/Length/Value Encoding in Messages} -\label{sec-2.4} - - - Some messages use a type/length/value (TLV) encoding scheme for - data transferred in the message body. This is done for primarily - for flexibility and extensibility. - - When present, TLVs occur in sequence until a TLV is encountered - with type \verb|RSCPTLV_END|. This TLV must have a length of zero. A - single TLV of type \verb|RSCPTLV_END| would represent an empty list of - TLVs. - - The TLV message format is defined by: - -{ \footnotesize - -\begin{verbatim} - enum rscp_tlv_type { - RSCPTLV_END = 0, - }, - - struct rscp_tlv { - uint16_t type; /* Type of value. */ - uint16_t len; /* Length of value (excluding type & len). */ - data[0]; /* Value data as defined by type & len. */ - }; - -\end{verbatim} - - -} - - The meaning of the \verb|type| field is unique to each message type - that uses the TLV encoding except that type code 0 must always - indicate the end of the TLV encoded data. Implementations must - skip unknown type values and continue processing to enhance - forward compatibility. - -\subsection{Reserved Message Types} -\label{sec-2.5} - - - Because of the use the same basic message framing, distinguishing - the remote switch control protocol from OpenFlow could be - difficult. The definition and required use of the remote switch - control protocol \hyperref[sec-2.6.1]{hello messsage} is intended to be compatible with - OpenFlow while facilitating this differentiation. - - To further assist in differentiation, the message type IDs for the - feature request and feature reply messages defined in the OpenFlow - specification are reserved in the remote switch control protocol. - If either the switch or the controller receives one of these - message type IDs on a connection expected to be a remote switch - control protocol connection, it must reply with an \hyperref[sec-2.6.5]{error message} - specifying reserved message type code and then terminate the - connection. - -\subsection{Messages Types Shared with OpenFlow} -\label{sec-2.6} - - - There are a few message types used by the remote switch control - protocol that are used for essentially the same purposes in it and - the OpenFlow protocol and have identical or compatible message - formats. These message types use the same message type ID in both - protocols. - -\subsubsection{Hello} -\label{sec-2.6.1} - - - This message is the same as the OpenFlow message except that - after the OpenFlow header the data of the message includes the - UTF-8 encoded string ``REMOTE SWITCH CONTROL PROTOCOL''. This - simplifies debugging and allows automatic detection of the - protocol. - -\subsubsection{Echo Request} -\label{sec-2.6.2} - - - This message works exactly as the corresponding message in - OpenFlow. - -\subsubsection{Echo Reply} -\label{sec-2.6.3} - - - This message works exactly as the corresponding message in - OpenFlow. - -\subsubsection{Vendor} -\label{sec-2.6.4} - - - This message works exactly as the corresponding message in - OpenFlow. - -\subsubsection{Error} -\label{sec-2.6.5} - - - This message works the same as the corresponding message in - OpenFlow with the exception that all the meaning of the type and - code fields are unique to each protocol. - - For the remote switch control protocol, the type values are - defined by: - -{ \footnotesize - -\begin{verbatim} - enum rscp_error_type { - RSCPET_HELLO_FAILED, /* Hello failed. */ - RSCPET_BAD_REQUEST, /* Request was not understood. */ - RSCPET_UNKNOWN_FORMAT, /* Format of typed data not understood. */ - RSCPET_CONFIG_ERROR /* Error processing configuration update. */ - }; - -\end{verbatim} - - -} - - The \verb|RSCPET_HELLO_FAILED| type is exactly analogous to the - \verb|OFPET_HELLO_FAILED| type in OpenFlow. A single code is currently - defined: - -{ \footnotesize - -\begin{verbatim} - enum rscp_hello_failed_code { - RSCPHFC_INCOMPATIBLE, /* Hello failed */ - }; - -\end{verbatim} - - -} - - The \verb|RSCPET_BAD_REQUEST| type is also similar to the - \verb|OFPET_HELLO_FAILED| type in OpenFlow. The subtypes are: - -{ \footnotesize - -\begin{verbatim} - enum rscp_bad_request_code { - RSCPBRC_BAD_VERSION, /* ofp_header.version not supported. */ - RSCPBRC_BAD_TYPE, /* ofp_header.type not supported. */ - RSCPBRC_RESERVED_0, /* For ID alignment w/compatible codes - * in OpenFlow */ - RSCPBRC_BAD_VENDOR, /* Vendor not supported. */ - RSCPBRC_BAD_SUBTYPE /* Vendor subtype not supported. */ - }; - -\end{verbatim} - - -} - - The \verb|data| field contains at least 64 bytes of the failed request. - - The \verb|RSCPET_UNKNOWN_FORMAT| type is used when the format specified - for a message such as \hyperref[sec-2.8.2]{capabilities request} or - \hyperref[sec-2.8.4]{configuration update} is unknown. The \verb|code| field is not used in - this error. The \verb|data| field contains a sequence of 32-bit - unsigned integers representing acceptable format types in order - from most preferred to least. - -\subsection{Extended Data Message} -\label{sec-2.7} - - - Because the OpenFlow message header only has a 16-bit length field, - the largest possible message size is 64kB. This may be - insufficient for some message types such as the configuration - update message. The extended data message removes this restriction - by encapsulating the message body of the original message (without - the base OpenFlow header) in more than one extended data messages. - - The extended data message format is: - -{ \footnotesize - -\begin{verbatim} - enum rscped_flags { - MORE_DATA = 1 - }; - - struct rscp_extended_data { - uint8_t type, /* Type code of the encapsulated message */ - uint8_t flags, - uint8_t pad[6], /* Maintain same alignment as regular body */ - uint8_t data[0]; /* Message body fragment */ - }; - -\end{verbatim} - - -} - - The MORE\_{}DATA flag must be set in every extended data message - sequence encapsulating a message body too long to fit in a single - standard message except the last message, in which the it must be - cleared. All but the final messages should typically be maximum - length, although this is not required. - - To simplify implementations, messages MUST NOT be sent encapsulated - in extended data messages if they will fit in a single regular - message. - -\subsection{Remote Control Protocol-specific Messages} -\label{sec-2.8} - - - The remaining message types are specific to the remote - switch control protocol. - -\subsubsection{Switch Resources} -\label{sec-2.8.1} - -\begin{itemize} -\item TODO Describe reply in detail -\end{itemize} - The switch resources message describes the resources available on - the switch. It must be sent by the switch to the controller - immediately after the initial hello exchange at connection - establishment and any time thereafter when resources change on the - switch. - -\subsubsection{Capabilities Request} -\label{sec-2.8.2} - - - The capabilities request message is sent from the controller to - the switch, which replies with a \hyperref[sec-2.8.3]{capabilities reply} message. - While not required, the controller will typically send a - capabilities request message after receiving the hello message on - connection establishment to determine switch capabilities. In - this way, it is very similar to the feature request and reply - messages in the OpenFlow specification. However, because the - encoding of the capabilities is different, the messages have - different names. - - The capabilities request message format is: - -{ \footnotesize - -\begin{verbatim} - struct rscp_capabilities_request { - uint32_t format; /* Format in which to send capabilities */ - }; - -\end{verbatim} - - -} - - The only field in this message, \verb|format|, specifies tedhe format - the controller expects for the reply. The only capabilities - format current specified is the \hyperref[*==Simple==Capabilities==Format]{Simple Capabilities Format}. - - On receipt of a capabilities request message, the switch must - send a capabilities reply in the specified format to the - controller or an \hyperref[*==Unknown==capabilities==format]{unknown capabilities format error message} in - reply. - -\subsubsection{Capabilities Reply} -\label{sec-2.8.3} - - - The capabilities reply message is sent from the switch to the - controller in response to a \hyperref[sec-2.8.2]{capabilities request} message from the - controller. The capabilities reply message format is: - -{ \footnotesize - -\begin{verbatim} - struct rscp_capabilities_reply { - uint32_t format; /* Format of capabilities info */ - uint8_t data[0]; /* Capabilities data */ - }; - -\end{verbatim} - - -} - - The \verb|format| specifies the format of the capabilities data. It - must be the same as the \verb|format| field in the - \hyperref[sec-2.8.2]{capabilities request}. - -\paragraph{Simple Capability Format} -\label{sec-2.8.3.1} - -\begin{itemize} -\item Basically, same as vswitchd configuration syntax -\item Each key/value pair is contained on a single line. The line - separator is a single newline character. -\item Keys have hierarchy based on controlling entities domain - name. Initially all keys will be `com.nicira'\ldots{} -\item Values can just be true/false to indicate the presence/absence - of a feature (or just not present for the absences). -\item Values can also be strings and/or numbers indicating limits on - specific capabilities, etc. -\item It should be possible to use a capabilities reply to determine - whether additional remote switch control protocol message - types are supported or not to minimize the need to change the - protocol version in the framing header. -\end{itemize} -\subsubsection{Configuration Update} -\label{sec-2.8.4} - - - The configuration update message can be sent asynchronously in - either direction. It's purpose is to inform the peer that a - configuration value has changed. On receipt of a configuration - update message, the message must be processed and a corresponding - configuration update reply message describing the results of that - processing sent back to the peer. - - The format of the configuration update message is: - -{ \footnotesize - -\begin{verbatim} - struct rscp_config_update { - uint32_t format; /* Format of capabilities info */ - uint8_t cookie[20]; /* Collision detect cookie */ - uint8_t data[0]; /* Capabilities data */ - }; - -\end{verbatim} - - -} - - The \verb|format| field specifies the format in which the - configuration data is presented. The only format currently - supported is the \hyperref[sec-2.8.4.1]{Simple Configuration Format}. - - The \verb|cookie| field is used to detect simultaneous configuration - changes on both peers. The use of the field is described in the - \hyperref[sec-2.8.4.2]{detection of simultaneous changes section}. - - On receipt of a configuration update message the message must be - processed and either a \hyperref[*==Configuration==Update==Reply]{configuration update reply} or an - \hyperref[sec-2.6.5]{error message}. - -\paragraph{Simple Configuration Format} -\label{sec-2.8.4.1} - -\begin{itemize} -\item TODO complete this section more fully. -\item Basically, the current vswitchd configuration file format -\item Keys in ``fully specified form'' (no sections) -\item Keys sorted as by implementation now -\end{itemize} -\paragraph{Detection of simultaneous changes} -\label{sec-2.8.4.2} - -\begin{itemize} -\item TODO Describe simultaneous change detection more completely. -\item Collision detect cookie values are a SHA-1 hash of last - configuration accepted from peer, over sorted keys \& values in - memory. -\item To prevent inadvertent overwriting of data, the switch is - treated as the master for all updates. It should refuse - updates with an incorrect cookie. Controller is responsible - for dealing with recovering from simultaneous changes by - merging configurations or whatever other means necessary. -\end{itemize} -\subsubsection{Configuration Update Acknowledgment} -\label{sec-2.8.5} - - - The configuration update acknowledgment is sent in response to a - \hyperref[sec-2.8.4]{configuration update} message. It indicates the update has been - successfully accepted and processed. The message body consists - of an updated collision detect cookie: - -{ \footnotesize - -\begin{verbatim} - struct rscp_config_update_ack { - uint8_t cookie[20]; /* Collision detect cookie */ - }; - -\end{verbatim} - - -} - -\subsubsection{Host Info} -\label{sec-2.8.6} - - - In some cases, the switch may definitively know additional - information about one or more hosts present on a given datapath - and port. In these cases the switch may send the host info - message to the controller to provide this information. - - The format of the host info message is: - -{ \footnotesize - -\begin{verbatim} - struct rscp_host_info { - uint64_t datapath_id; /* Referenced datapath. */ - uint16_t port_id; /* Referenced port. */ - data[0]; /* TLV encoded data about host. */ - }; - -\end{verbatim} - - -} - - The data in the message is encoded as described in the - \hyperref[sec-2.4]{Type/Length/Value Encoding in Messages} section. - -{ \footnotesize - -\begin{verbatim} - enum rscp_host_info_tlv_type { - RSCPHITLV_END = 0, /* End of TLV records. */ - RSCPHITLV_HOST_DLADDR , /* Host MAC address. */ - RSCPHITLV_HOST_UUID /* Host unique identifier. */ - }; - -\end{verbatim} - - -} - - The value for \verb|RSCPHITLV_HOST_DLADDR| is a six-byte MAC address. - The value for \verb|RSCPHITLV_HOST_UUID| is a variable length - universally unique identifier for the host. - -\section{Design Rationale} -\label{sec-3} - - -\subsection{Why specify an additional protocol} -\label{sec-3.1} - - - The core purpose of OpenFlow is to manage the flow table in the - switch. There are many other activities required to fully manage a - switch, configuring ports, updating stats, etc. Some of these - require significant data transfer that could interfere with the - primary purpose of OpenFlow. - - Switches from existing vendors typically already have their own - methods for accomplishing these tasks. A vendor considering - adopting OpenFlow may not wish to re-implement this support. If - the core OpenFlow specification required such a reimplementation, - it could likely reduce the adoption of OpenFlow or considerably - slow the process of standardization of new protocol messages to - accomplish these tasks, extending the time before implementations - appeared on the market. - -\subsection{Use of a non-standard protocol} -\label{sec-3.2} - - - The requirements for the protocol, including bidirectional - asynchronous messaging are not well supported by any widely - implemented protocol used for similar purposes. It is expected - most implementers of the remote switch protocol will also be - implementers of the OpenFlow protocol and thus specifying a similar - protocol will increase code reuse. - -\subsection{Reuse of some OpenFlow messages} -\label{sec-3.3} - - - The messaging requirements of OpenFlow and the remote control - protocol are similar in a few areas. Reusing the same messages in - those areas should further contribute to code reuse. - -\subsection{Connection direction from switch to controller} -\label{sec-3.4} - - -\subsection{Use of vswitchd configuration file format for config documents} -\label{sec-3.5} - - - Simply put, it is available to Nicira already and matches the - initial requirements for switch configuration management. - - -\end{document} - diff --git a/doc/ofmp-spec/ofmp-spec.tex b/doc/ofmp-spec/ofmp-spec.tex new file mode 100644 index 00000000..90a73ab6 --- /dev/null +++ b/doc/ofmp-spec/ofmp-spec.tex @@ -0,0 +1,640 @@ +% Created 2009-02-02 Mon 17:09 +\documentclass[11pt,a4paper]{article} +\usepackage[utf8]{inputenc} +\usepackage[T1]{fontenc} +\usepackage{graphicx} +\usepackage{longtable} +\usepackage{hyperref} + + +\title{OpenFlow Management Protocol} +\author{Version 0.0.1 (Wire Protocol 0x80)} +\date{04 February 2009} + +\begin{document} + +\maketitle + +\setcounter{tocdepth}{3} +\tableofcontents +\vspace*{1cm} + +\section{Goals} +\label{sec-1} + + +The high-level design goals for the protocol are described in this +section. + +\begin{itemize} +\item Rapid implementation + + Most importantly, Nicira must implement the protocol quickly to + meet current business objectives. However, the ability to implement + the protocol rapidly should be a benefit to anyone implementing the + protocol. +\item Support ``all'' switch features + + The controller should be able to learn about all available switch + features and retrieve and modify their values through the protocol. +\item ``Multi-master'' + + It must be possible to make changes at both the controller and the + switch. When changes are made and connectivity exists between the + switch and the controller, both sides should be resynchronized + within a short period of time (< 1 sec??). +\item Extensible + + To support future enhancements, the protocol must be capable of + accommodating additional configuration settings and + upgrading/downgrading configuration appropriately. +\item Scalable + + The protocol should be able to handle any size switch, from a few + ports to hundreds of ports. +\item Minimal cost of implementation on the switch + + One of the selling points of OpenFlow is the ability to take cost + out of switches by implementing complex network-wide functionality + in the controller. It is thus preferable to minimize the cost of + implementation on the switch. +\end{itemize} +\section{Specification} +\label{sec-2} + + + The OpenFlow Management Protocol is based on the OpenFlow + protocol, with which it is often expected to be used. It augments + the flow table management provided by the OpenFlow protocol with + more general switch management functions required in a full-featured + switch. + +\subsection{Connection Maintenance} +\label{sec-2.1} + + + As with OpenFlow, the switch is responsible for initiating the + connection to the controller at a user configurable IP address and + TCP port. The default destination port for the connection is 6632, + one less than the default OpenFlow destination port 6633. The IP + address of the controller may be discovered through the same + discovery protocol defined for OpenFlow. + + The switch must attempt to maintain an open connection to the + controller at all times while in an operational state, although the + exact details for detecting connection failure and opening a new + connection are left to individual implementations. + + After connection establishment, both sides must send \hyperref[sec-2.6.1]{hello messages} + to each other before any other messages are sent. + + While the default ports for OpenFlow and the OpenFlow Management + Protocol are different, the latter is deliberately designed to be + able to coexist on the same port, in which case the appropriate + connection type can be determined by examining the initial hello + message sent after connection establishment. + +\subsection{Encryption} +\label{sec-2.2} + + + The OpenFlow Management Protocol uses the same encryption + mechanism defined in the analogous section of the OpenFlow + specification. It is expected, but not required, that the + Management Protocol will use the same keys as the OpenFlow + protocol for authentication of either end of the connection. + +\subsection{Framing} +\label{sec-2.3} + + + The Management Protocol uses the same basic header as + the OpenFlow protocol, defined as \verb|ofp_header| in the OpenFlow + specification. The fields of this header are used in the same way + as they are in the OpenFlow protocol except that the type IDs + generally have different meanings. However, a few message types + are shared among the two protocols, in which case they have the + same message type code in both protocols. + + Each message type is further described in subsequent sections of + this document. The message types IDs are defined by: + +{ \footnotesize + +\begin{verbatim} + enum ofmp_type { + OFMP_HELLO, /* Message Types Shared with OpenFlow. */ + OFMP_ERROR, /* Message Types Shared with OpenFlow. */ + OFMP_ECHO_REQUEST, /* Message Types Shared with OpenFlow. */ + OFMP_ECHO_REPLY, /* Message Types Shared with OpenFlow. */ + OFMP_VENDOR, /* Message Types Shared with OpenFlow. */ + OFMP_RESERVED_0, /* Reserved Message Types. */ + OFMP_RESERVED_1, /* Reserved Message Types. */ + OFMP_EXTENDED_DATA, /* Extended Data Message */ + OFMP_CAPABILITY_REQUEST,/* Management Protocol-specific. */ + OFMP_CAPABILITY_REPLY, /* Management Protocol-specific. */ + OFMP_SWITCH_RESOURCES, /* Management Protocol-specific. */ + OFMP_CONFIG_UPDATE, /* Management Protocol-specific. */ + OFMP_CONFIG_UPDATE_ACK, /* Management Protocol-specific. */ + OFMP_HOST_INFO /* Management Protocol-specific. */ + }; + +\end{verbatim} + + +} + +\subsection{Type/Length/Value Encoding in Messages} +\label{sec-2.4} + + + Some messages use a type/length/value (TLV) encoding scheme for + data transferred in the message body. This is done for primarily + for flexibility and extensibility. + + When present, TLVs occur in sequence until a TLV is encountered + with type \verb|OFMPTLV_END|. This TLV must have a length of zero. A + single TLV of type \verb|OFMPTLV_END| would represent an empty list of + TLVs. + + The TLV message format is defined by: + +{ \footnotesize + +\begin{verbatim} + enum ofmp_tlv_type { + OFMPTLV_END = 0, + }, + + struct ofmp_tlv { + uint16_t type; /* Type of value. */ + uint16_t len; /* Length of value (excluding type & len). */ + data[0]; /* Value data as defined by type & len. */ + }; + +\end{verbatim} + + +} + + The meaning of the \verb|type| field is unique to each message type + that uses the TLV encoding except that type code 0 must always + indicate the end of the TLV encoded data. Implementations must + skip unknown type values and continue processing to enhance + forward compatibility. + +\subsection{Reserved Message Types} +\label{sec-2.5} + + + Because of the use the same basic message framing, distinguishing + the OpenFlow Management Protocol from OpenFlow could be + difficult. The definition and required use of the Management + Protocol \hyperref[sec-2.6.1]{hello message} is intended to be compatible with + OpenFlow while facilitating this differentiation. + + To further assist in differentiation, the message type IDs for the + feature request and feature reply messages defined in the OpenFlow + specification are reserved in the Management Protocol. + If either the switch or the controller receives one of these + message type IDs on a connection expected to be a Management + Protocol connection, it must reply with an \hyperref[sec-2.6.5]{error message} + specifying reserved message type code and then terminate the + connection. + +\subsection{Messages Types Shared with OpenFlow} +\label{sec-2.6} + + + There are a few message types used by the Management + Protocol that are used for essentially the same purposes in it and + the OpenFlow protocol and have identical or compatible message + formats. These message types use the same message type ID in both + protocols. + +\subsubsection{Hello} +\label{sec-2.6.1} + + + This message is the same as the OpenFlow message except that + after the OpenFlow header the data of the message includes the + UTF-8 encoded string ``OPENFLOW MANAGEMENT PROTOCOL''. This + simplifies debugging and allows automatic detection of the + protocol. + +\subsubsection{Echo Request} +\label{sec-2.6.2} + + + This message works exactly as the corresponding message in + OpenFlow. + +\subsubsection{Echo Reply} +\label{sec-2.6.3} + + + This message works exactly as the corresponding message in + OpenFlow. + +\subsubsection{Vendor} +\label{sec-2.6.4} + + + This message works exactly as the corresponding message in + OpenFlow. + +\subsubsection{Error} +\label{sec-2.6.5} + + + This message works the same as the corresponding message in + OpenFlow with the exception that all the meaning of the type and + code fields are unique to each protocol. + + For the Management Protocol, the type values are defined by: + +{ \footnotesize + +\begin{verbatim} + enum ofmp_error_type { + OFMPET_HELLO_FAILED, /* Hello failed. */ + OFMPET_BAD_REQUEST, /* Request was not understood. */ + OFMPET_UNKNOWN_FORMAT, /* Format of typed data not understood. */ + OFMPET_CONFIG_ERROR /* Error processing configuration update. */ + }; + +\end{verbatim} + + +} + + The \verb|OFMPET_HELLO_FAILED| type is exactly analogous to the + \verb|OFPET_HELLO_FAILED| type in OpenFlow. A single code is currently + defined: + +{ \footnotesize + +\begin{verbatim} + enum ofmp_hello_failed_code { + OFMPHFC_INCOMPATIBLE, /* Hello failed */ + }; + +\end{verbatim} + + +} + + The \verb|OFMPET_BAD_REQUEST| type is also similar to the + \verb|OFPET_HELLO_FAILED| type in OpenFlow. The subtypes are: + +{ \footnotesize + +\begin{verbatim} + enum ofmp_bad_request_code { + OFMPBRC_BAD_VERSION, /* ofp_header.version not supported. */ + OFMPBRC_BAD_TYPE, /* ofp_header.type not supported. */ + OFMPBRC_RESERVED_0, /* For ID alignment w/compatible codes + * in OpenFlow */ + OFMPBRC_BAD_VENDOR, /* Vendor not supported. */ + OFMPBRC_BAD_SUBTYPE /* Vendor subtype not supported. */ + }; + +\end{verbatim} + + +} + + The \verb|data| field contains at least 64 bytes of the failed request. + + The \verb|OFMPET_UNKNOWN_FORMAT| type is used when the format specified + for a message such as \hyperref[sec-2.8.2]{capabilities request} or + \hyperref[sec-2.8.4]{configuration update} is unknown. The \verb|code| field is not used in + this error. The \verb|data| field contains a sequence of 32-bit + unsigned integers representing acceptable format types in order + from most preferred to least. + +\subsection{Extended Data Message} +\label{sec-2.7} + + + Because the OpenFlow message header only has a 16-bit length field, + the largest possible message size is 64kB. This may be + insufficient for some message types such as the configuration + update message. The extended data message removes this restriction + by encapsulating the message body of the original message (without + the base OpenFlow header) in more than one extended data messages. + + The extended data message format is: + +{ \footnotesize + +\begin{verbatim} + enum ofmped_flags { + MORE_DATA = 1 + }; + + struct ofmp_extended_data { + uint8_t type, /* Type code of the encapsulated message */ + uint8_t flags, + uint8_t pad[6], /* Maintain same alignment as regular body */ + uint8_t data[0]; /* Message body fragment */ + }; + +\end{verbatim} + + +} + + The MORE\_{}DATA flag must be set in every extended data message + sequence encapsulating a message body too long to fit in a single + standard message except the last message, in which the it must be + cleared. All but the final messages should typically be maximum + length, although this is not required. + + To simplify implementations, messages MUST NOT be sent encapsulated + in extended data messages if they will fit in a single regular + message. + +\subsection{OpenFlow Management Protocol-specific Messages} +\label{sec-2.8} + + + The remaining message types are specific to the Management Protocol. + +\subsubsection{Switch Resources} +\label{sec-2.8.1} + +\begin{itemize} +\item TODO Describe reply in detail +\end{itemize} + The switch resources message describes the resources available on + the switch. It must be sent by the switch to the controller + immediately after the initial hello exchange at connection + establishment and any time thereafter when resources change on the + switch. + +\subsubsection{Capabilities Request} +\label{sec-2.8.2} + + + The capabilities request message is sent from the controller to + the switch, which replies with a \hyperref[sec-2.8.3]{capabilities reply} message. + While not required, the controller will typically send a + capabilities request message after receiving the hello message on + connection establishment to determine switch capabilities. In + this way, it is very similar to the feature request and reply + messages in the OpenFlow specification. However, because the + encoding of the capabilities is different, the messages have + different names. + + The capabilities request message format is: + +{ \footnotesize + +\begin{verbatim} + struct ofmp_capabilities_request { + uint32_t format; /* Format in which to send capabilities */ + }; + +\end{verbatim} + + +} + + The only field in this message, \verb|format|, specifies the format + the controller expects for the reply. The only capabilities + format current specified is the \hyperref[*==Simple==Capabilities==Format]{Simple Capabilities Format}. + + On receipt of a capabilities request message, the switch must + send a capabilities reply in the specified format to the + controller or an \hyperref[*==Unknown==capabilities==format]{unknown capabilities format error message} in + reply. + +\subsubsection{Capabilities Reply} +\label{sec-2.8.3} + + + The capabilities reply message is sent from the switch to the + controller in response to a \hyperref[sec-2.8.2]{capabilities request} message from the + controller. The capabilities reply message format is: + +{ \footnotesize + +\begin{verbatim} + struct ofmp_capabilities_reply { + uint32_t format; /* Format of capabilities info */ + uint8_t data[0]; /* Capabilities data */ + }; + +\end{verbatim} + + +} + + The \verb|format| specifies the format of the capabilities data. It + must be the same as the \verb|format| field in the + \hyperref[sec-2.8.2]{capabilities request}. + +\paragraph{Simple Capability Format} +\label{sec-2.8.3.1} + +\begin{itemize} +\item Basically, same as vswitchd configuration syntax +\item Each key/value pair is contained on a single line. The line + separator is a single newline character. +\item Keys have hierarchy based on controlling entities domain + name. Initially all keys will be `com.nicira'\ldots{} +\item Values can just be true/false to indicate the presence/absence + of a feature (or just not present for the absences). +\item Values can also be strings and/or numbers indicating limits on + specific capabilities, etc. +\item It should be possible to use a capabilities reply to determine + whether additional OpenFlow Management Protocol message + types are supported or not to minimize the need to change the + protocol version in the framing header. +\end{itemize} +\subsubsection{Configuration Update} +\label{sec-2.8.4} + + + The configuration update message can be sent asynchronously in + either direction. It's purpose is to inform the peer that a + configuration value has changed. On receipt of a configuration + update message, the message must be processed and a corresponding + configuration update reply message describing the results of that + processing sent back to the peer. + + The format of the configuration update message is: + +{ \footnotesize + +\begin{verbatim} + struct ofmp_config_update { + uint32_t format; /* Format of capabilities info */ + uint8_t cookie[20]; /* Collision detect cookie */ + uint8_t data[0]; /* Capabilities data */ + }; + +\end{verbatim} + + +} + + The \verb|format| field specifies the format in which the + configuration data is presented. The only format currently + supported is the \hyperref[sec-2.8.4.1]{Simple Configuration Format}. + + The \verb|cookie| field is used to detect simultaneous configuration + changes on both peers. The use of the field is described in the + \hyperref[sec-2.8.4.2]{detection of simultaneous changes section}. + + On receipt of a configuration update message the message must be + processed and either a \hyperref[*==Configuration==Update==Reply]{configuration update reply} or an + \hyperref[sec-2.6.5]{error message}. + +\paragraph{Simple Configuration Format} +\label{sec-2.8.4.1} + +\begin{itemize} +\item TODO complete this section more fully. +\item Basically, the current vswitchd configuration file format +\item Keys in ``fully specified form'' (no sections) +\item Keys sorted as by implementation now +\end{itemize} +\paragraph{Detection of simultaneous changes} +\label{sec-2.8.4.2} + +\begin{itemize} +\item TODO Describe simultaneous change detection more completely. +\item Collision detect cookie values are a SHA-1 hash of last + configuration accepted from peer, over sorted keys \& values in + memory. +\item To prevent inadvertent overwriting of data, the switch is + treated as the master for all updates. It should refuse + updates with an incorrect cookie. Controller is responsible + for dealing with recovering from simultaneous changes by + merging configurations or whatever other means necessary. +\end{itemize} +\subsubsection{Configuration Update Acknowledgment} +\label{sec-2.8.5} + + + The configuration update acknowledgment is sent in response to a + \hyperref[sec-2.8.4]{configuration update} message. It indicates the update has been + successfully accepted and processed. The message body consists + of an updated collision detect cookie: + +{ \footnotesize + +\begin{verbatim} + struct ofmp_config_update_ack { + uint8_t cookie[20]; /* Collision detect cookie */ + }; + +\end{verbatim} + + +} + +\subsubsection{Host Info} +\label{sec-2.8.6} + + + In some cases, the switch may definitively know additional + information about one or more hosts present on a given datapath + and port. In these cases the switch may send the host info + message to the controller to provide this information. + + The format of the host info message is: + +{ \footnotesize + +\begin{verbatim} + struct ofmp_host_info { + uint64_t datapath_id; /* Referenced datapath. */ + uint16_t port_id; /* Referenced port. */ + data[0]; /* TLV encoded data about host. */ + }; + +\end{verbatim} + + +} + + The data in the message is encoded as described in the + \hyperref[sec-2.4]{Type/Length/Value Encoding in Messages} section. + +{ \footnotesize + +\begin{verbatim} + enum ofmp_host_info_tlv_type { + OFMPHITLV_END = 0, /* End of TLV records. */ + OFMPHITLV_HOST_DLADDR , /* Host MAC address. */ + OFMPHITLV_HOST_UUID /* Host unique identifier. */ + }; + +\end{verbatim} + + +} + + The value for \verb|OFMPHITLV_HOST_DLADDR| is a six-byte MAC address. + The value for \verb|OFMPHITLV_HOST_UUID| is a variable length + universally unique identifier for the host. + +\section{Design Rationale} +\label{sec-3} + + +\subsection{Why specify an additional protocol} +\label{sec-3.1} + + + The core purpose of OpenFlow is to manage the flow table in the + switch. There are many other activities required to fully manage a + switch, configuring ports, updating stats, etc. Some of these + require significant data transfer that could interfere with the + primary purpose of OpenFlow. + + Switches from existing vendors typically already have their own + methods for accomplishing these tasks. A vendor considering + adopting OpenFlow may not wish to re-implement this support. If + the core OpenFlow specification required such a reimplementation, + it could likely reduce the adoption of OpenFlow or considerably + slow the process of standardization of new protocol messages to + accomplish these tasks, extending the time before implementations + appeared on the market. + +\subsection{Use of a non-standard protocol} +\label{sec-3.2} + + + The requirements for the protocol, including bidirectional + asynchronous messaging are not well supported by any widely + implemented protocol used for similar purposes. It is expected + most implementers of the remote switch protocol will also be + implementers of the OpenFlow protocol and thus specifying a similar + protocol will increase code reuse. + +\subsection{Reuse of some OpenFlow messages} +\label{sec-3.3} + + + The messaging requirements of OpenFlow and the OpenFlow Management + Protocol are similar in a few areas. Reusing the same messages in + those areas should further contribute to code reuse. + +\subsection{Connection direction from switch to controller} +\label{sec-3.4} + + +\subsection{Use of vswitchd configuration file format for config documents} +\label{sec-3.5} + + + Simply put, it is available to Nicira already and matches the + initial requirements for switch configuration management. + + +\end{document} +