An OpenFlow controller.
Summary:
Core Features:
type optional string, either primary or
service
target string
connection_mode optional string, either in-band or
out-of-band
Controller Failure Detection and Handling:
max_backoff optional integer, at least 1,000
inactivity_probe optional integer
Asynchronous Messages:
enable_async_messages optional boolean
Controller Rate Limiting:
controller_queue_size optional integer, in range 1 to 512
controller_rate_limit optional integer, at least 100
controller_burst_limit optional integer, at least 25
Controller Rate Limiting Statistics:
status : packet-in-TYPE-bypassed
optional string, containing an
integer, at least 0
status : packet-in-TYPE-queued
optional string, containing an
integer, at least 0
status : packet-in-TYPE-dropped
optional string, containing an
integer, at least 0
status : packet-in-TYPE-backlog
optional string, containing an
integer, at least 0
Additional In-Band Configuration:
local_ip optional string
local_netmask optional string
local_gateway optional string
Controller Status:
is_connected boolean
role optional string, one of master,
other, or slave
status : last_error optional string
status : state optional string, one of ACTIVE,
BACKOFF, CONNECTING, IDLE, or VOID
status : sec_since_connect optional string, containing an
integer, at least 0
status : sec_since_disconnect
optional string, containing an
integer, at least 1
Connection Parameters:
other_config : dscp optional string, containing an
integer
Common Columns:
external_ids map of string-string pairs
other_config map of string-string pairs
Details:
Core Features:
type: optional string, either primary or service
Open vSwitch supports two kinds of OpenFlow controllers. A
bridge may have any number of each kind:
Primary controllers
This is the kind of controller envisioned by the
OpenFlow specifications. Usually, a primary
controller implements a network policy by taking
charge of the switch's flow table.
The fail_mode column in the Bridge table applies to
primary controllers.
When multiple primary controllers are configured,
Open vSwitch connects to all of them
simultaneously. OpenFlow provides few facilities to
allow multiple controllers to coordinate in
interacting with a single switch, so more than one
primary controller should be specified only if the
controllers are themselves designed to coordinate
with each other.
Service controllers
These kinds of OpenFlow controller connections are
intended for occasional support and maintenance
use, e.g. with ovs-ofctl. Usually a service
controller connects only briefly to inspect or
modify some of a switch's state.
The fail_mode column in the Bridge table does not
apply to service controllers.
By default, Open vSwitch treats controllers with active
connection methods as primary controllers and those with
passive connection methods as service controllers. Set
this column to the desired type to override this default.
target: string
Connection method for controller.
The following active connection methods are currently
supported:
ssl:host[:port]
The specified SSL port on the host at the given
host, which can either be a DNS name (if built with
unbound library) or an IP address. The ssl column
in the Open_vSwitch table must point to a valid SSL
configuration when this form is used.
If port is not specified, it defaults to 6653.
SSL support is an optional feature that is not
always built as part of Open vSwitch.
tcp:host[:port]
The specified TCP port on the host at the given
host, which can either be a DNS name (if built with
unbound library) or an IP address (IPv4 or IPv6).
If host is an IPv6 address, wrap it in square
brackets, e.g. tcp:[::1]:6653.
If port is not specified, it defaults to 6653.
The following passive connection methods are currently
supported:
pssl:[port][:host]
Listens for SSL connections on the specified TCP
port. If host, which can either be a DNS name (if
built with unbound library) or an IP address, is
specified, then connections are restricted to the
resolved or specified local IP address (either IPv4
or IPv6). If host is an IPv6 address, wrap it in
square brackets, e.g. pssl:6653:[::1].
If port is not specified, it defaults to 6653. If
host is not specified then it listens only on IPv4
(but not IPv6) addresses. The ssl column in the
Open_vSwitch table must point to a valid SSL
configuration when this form is used.
If port is not specified, it currently to 6653.
SSL support is an optional feature that is not
always built as part of Open vSwitch.
ptcp:[port][:host]
Listens for connections on the specified TCP port.
If host, which can either be a DNS name (if built
with unbound library) or an IP address, is
specified, then connections are restricted to the
resolved or specified local IP address (either IPv4
or IPv6). If host is an IPv6 address, wrap it in
square brackets, e.g. ptcp:6653:[::1]. If host is
not specified then it listens only on IPv4
addresses.
If port is not specified, it defaults to 6653.
When multiple controllers are configured for a single
bridge, the target values must be unique. Duplicate target
values yield unspecified results.
connection_mode: optional string, either in-band or out-of-band
If it is specified, this setting must be one of the
following strings that describes how Open vSwitch contacts
this OpenFlow controller over the network:
in-band
In this mode, this controller's OpenFlow traffic
travels over the bridge associated with the
controller. With this setting, Open vSwitch allows
traffic to and from the controller regardless of
the contents of the OpenFlow flow table.
(Otherwise, Open vSwitch would never be able to
connect to the controller, because it did not have
a flow to enable it.) This is the most common
connection mode because it is not necessary to
maintain two independent networks.
out-of-band
In this mode, OpenFlow traffic uses a control
network separate from the bridge associated with
this controller, that is, the bridge does not use
any of its own network devices to communicate with
the controller. The control network must be
configured separately, before or after ovs-vswitchd
is started.
If not specified, the default is implementation-specific.
Controller Failure Detection and Handling:
max_backoff: optional integer, at least 1,000
Maximum number of milliseconds to wait between connection
attempts. Default is implementation-specific.
inactivity_probe: optional integer
Maximum number of milliseconds of idle time on connection
to controller before sending an inactivity probe message.
If Open vSwitch does not communicate with the controller
for the specified number of seconds, it will send a probe.
If a response is not received for the same additional
amount of time, Open vSwitch assumes the connection has
been broken and attempts to reconnect. Default is
implementation-specific. A value of 0 disables inactivity
probes.
Asynchronous Messages:
OpenFlow switches send certain messages to controllers
spontanenously, that is, not in response to any request from the
controller. These messages are called ``asynchronous messages.''
These columns allow asynchronous messages to be limited or
disabled to ensure the best use of network resources.
enable_async_messages: optional boolean
The OpenFlow protocol enables asynchronous messages at
time of connection establishment, which means that a
controller can receive asynchronous messages, potentially
many of them, even if it turns them off immediately after
connecting. Set this column to false to change Open
vSwitch behavior to disable, by default, all asynchronous
messages. The controller can use the NXT_SET_ASYNC_CONFIG
Nicira extension to OpenFlow to turn on any messages that
it does want to receive, if any.
Controller Rate Limiting:
A switch can forward packets to a controller over the OpenFlow
protocol. Forwarding packets this way at too high a rate can
overwhelm a controller, frustrate use of the OpenFlow connection
for other purposes, increase the latency of flow setup, and use
an unreasonable amount of bandwidth. Therefore, Open vSwitch
supports limiting the rate of packet forwarding to a controller.
There are two main reasons in OpenFlow for a packet to be sent to
a controller: either the packet ``misses'' in the flow table,
that is, there is no matching flow, or a flow table action says
to send the packet to the controller. Open vSwitch limits the
rate of each kind of packet separately at the configured rate.
Therefore, the actual rate that packets are sent to the
controller can be up to twice the configured rate, when packets
are sent for both reasons.
This feature is specific to forwarding packets over an OpenFlow
connection. It is not general-purpose QoS. See the QoS table for
quality of service configuration, and ingress_policing_rate in
the Interface table for ingress policing configuration.
controller_queue_size: optional integer, in range 1 to 512
This sets the maximum size of the queue of packets that
need to be sent to this OpenFlow controller. The value
must be less than 512. If not specified the queue size is
limited to the value set for the management controller in
other_config:controller-queue-size if present or 100
packets by default. Note: increasing the queue size might
have a negative impact on latency.
controller_rate_limit: optional integer, at least 100
The maximum rate at which the switch will forward packets
to the OpenFlow controller, in packets per second. If no
value is specified, rate limiting is disabled.
controller_burst_limit: optional integer, at least 25
When a high rate triggers rate-limiting, Open vSwitch
queues packets to the controller for each port and
transmits them to the controller at the configured rate.
This value limits the number of queued packets. Ports on a
bridge share the packet queue fairly.
This value has no effect unless controller_rate_limit is
configured. The current default when this value is not
specified is one-quarter of controller_rate_limit, meaning
that queuing can delay forwarding a packet to the
controller by up to 250 ms.
Controller Rate Limiting Statistics:
These values report the effects of rate limiting. Their values
are relative to establishment of the most recent OpenFlow
connection, or since rate limiting was enabled, whichever
happened more recently. Each consists of two values, one with
TYPE replaced by miss for rate limiting flow table misses, and
the other with TYPE replaced by action for rate limiting packets
sent by OpenFlow actions.
These statistics are reported only when controller rate limiting
is enabled.
status : packet-in-TYPE-bypassed: optional string, containing an
integer, at least 0
Number of packets sent directly to the controller, without
queuing, because the rate did not exceed the configured
maximum.
status : packet-in-TYPE-queued: optional string, containing an
integer, at least 0
Number of packets added to the queue to send later.
status : packet-in-TYPE-dropped: optional string, containing an
integer, at least 0
Number of packets added to the queue that were later
dropped due to overflow. This value is less than or equal
to status:packet-in-TYPE-queued.
status : packet-in-TYPE-backlog: optional string, containing an
integer, at least 0
Number of packets currently queued. The other statistics
increase monotonically, but this one fluctuates between 0
and the controller_burst_limit as conditions change.
Additional In-Band Configuration:
These values are considered only in in-band control mode (see
connection_mode).
When multiple controllers are configured on a single bridge,
there should be only one set of unique values in these columns.
If different values are set for these columns in different
controllers, the effect is unspecified.
local_ip: optional string
The IP address to configure on the local port, e.g.
192.168.0.123. If this value is unset, then local_netmask
and local_gateway are ignored.
local_netmask: optional string
The IP netmask to configure on the local port, e.g.
255.255.255.0. If local_ip is set but this value is unset,
then the default is chosen based on whether the IP address
is class A, B, or C.
local_gateway: optional string
The IP address of the gateway to configure on the local
port, as a string, e.g. 192.168.0.1. Leave this column
unset if this network has no gateway.
Controller Status:
is_connected: boolean
true if currently connected to this controller, false
otherwise.
role: optional string, one of master, other, or slave
The level of authority this controller has on the
associated bridge. Possible values are:
other Allows the controller access to all OpenFlow
features.
master Equivalent to other, except that there may be at
most one such controller at a time. If a given
controller promotes itself to this role,
ovs-vswitchd demotes any existing controller with
the role to slave.
slave Allows the controller read-only access to OpenFlow
features. Attempts to modify the flow table will be
rejected with an error. Such controllers do not
receive OFPT_PACKET_IN or OFPT_FLOW_REMOVED
messages, but they do receive OFPT_PORT_STATUS
messages.
status : last_error: optional string
A human-readable description of the last error on the
connection to the controller; i.e. strerror(errno). This
key will exist only if an error has occurred.
status : state: optional string, one of ACTIVE, BACKOFF,
CONNECTING, IDLE, or VOID
The state of the connection to the controller:
VOID Connection is disabled.
BACKOFF
Attempting to reconnect at an increasing period.
CONNECTING
Attempting to connect.
ACTIVE Connected, remote host responsive.
IDLE Connection is idle. Waiting for response to keep-
alive.
These values may change in the future. They are provided
only for human consumption.
status : sec_since_connect: optional string, containing an
integer, at least 0
The amount of time since this controller last successfully
connected to the switch (in seconds). Value is empty if
controller has never successfully connected.
status : sec_since_disconnect: optional string, containing an
integer, at least 1
The amount of time since this controller last disconnected
from the switch (in seconds). Value is empty if controller
has never disconnected.
Connection Parameters:
Additional configuration for a connection between the controller
and the Open vSwitch.
other_config : dscp: optional string, containing an integer
The Differentiated Service Code Point (DSCP) is specified
using 6 bits in the Type of Service (TOS) field in the IP
header. DSCP provides a mechanism to classify the network
traffic and provide Quality of Service (QoS) on IP
networks. The DSCP value specified here is used when
establishing the connection between the controller and the
Open vSwitch. If no value is specified, a default value of
48 is chosen. Valid DSCP values must be in the range 0 to
63.
Common Columns:
The overall purpose of these columns is described under Common
Columns at the beginning of this document.
external_ids: map of string-string pairs
other_config: map of string-string pairs
