X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=vswitchd%2Fovs-vswitchd.8.in;h=817cec24edc88044b0e06fb7e595635b7ff2580f;hb=HEAD;hp=6941bdf5e51070afb831f4546764c8b6154f165c;hpb=3b01baa3970139c3a195017ab1ea3e42761e3db2;p=sliver-openvswitch.git diff --git a/vswitchd/ovs-vswitchd.8.in b/vswitchd/ovs-vswitchd.8.in index 6941bdf5e..817cec24e 100644 --- a/vswitchd/ovs-vswitchd.8.in +++ b/vswitchd/ovs-vswitchd.8.in @@ -1,28 +1,36 @@ -.TH ovs\-vswitchd 8 "June 2009" "Open vSwitch" "Open vSwitch Manual" +.\" -*- nroff -*- +.de IQ +. br +. ns +. IP "\\$1" +.. +.TH ovs\-vswitchd 8 "@VERSION@" "Open vSwitch" "Open vSwitch Manual" +.\" This program's name: .ds PN ovs\-vswitchd . .SH NAME ovs\-vswitchd \- Open vSwitch daemon . .SH SYNOPSIS -.B ovs\-vswitchd -\fIconfig\fR +\fBovs\-vswitchd \fR[\fIdatabase\fR] . .SH DESCRIPTION -A daemon that manages and controls any number of Open vSwitch switches +A daemon that manages and controls any number of Open vSwitch switches on the local machine. .PP -The mandatory \fIconfig\fR argument specifies a configuration file. -For a description of \fBovs\-vswitchd\fR configuration syntax, see -\fBovs\-vswitchd.conf\fR(5). +The \fIdatabase\fR argument specifies how \fBovs\-vswitchd\fR connects +to \fBovsdb\-server\fR. The default is \fBunix:@RUNDIR@/db.sock\fR. +The following forms are accepted: +.so ovsdb/remote-active.man +.so ovsdb/remote-passive.man .PP -At startup or upon receipt of a \fBSIGHUP\fR signal, \fBovs\-vswitchd\fR -reads the configuration file. It sets up Open vSwitch datapaths and then -operates switching across each bridge described in its configuration -files. If a logfile was specified on the command line it will also -be opened or reopened. +\fBovs\-vswitchd\fR retrieves its configuration from \fIdatabase\fR at +startup. It sets up Open vSwitch datapaths and then operates +switching across each bridge described in its configuration files. As +the database changes, \fBovs\-vswitchd\fR automatically updates its +configuration to match. .PP -\fBovs\-vswitchd\fR switches may be configured with any of the following +\fBovs\-vswitchd\fR switches may be configured with any of the following features: . .IP \(bu @@ -42,6 +50,9 @@ Port mirroring, with optional VLAN tagging. NetFlow v5 flow logging. . .IP \(bu +sFlow(R) monitoring. +. +.IP \(bu Connectivity to an external OpenFlow controller, such as NOX. . .PP @@ -61,27 +72,224 @@ Open vSwitch distribution for instructions on how to build and load the Open vSwitch kernel module. .PP .SH OPTIONS -.IP "\fB--fake-proc-net\fR" -Causes \fBovs\-vswitchd\fR to simulate some files in \fB/proc/net/vlan\fR -and \fB/proc/net/bonding\fR that some legacy software expects to -exist. This option should only be used if such legacy software is -actually in use. It requires the \fBbrcompat_mod.ko\fR kernel module -to be loaded. +.IP "\fB\-\-mlockall\fR" +Causes \fBovs\-vswitchd\fR to call the \fBmlockall()\fR function, to +attempt to lock all of its process memory into physical RAM, +preventing the kernel from paging any of its memory to disk. This +helps to avoid networking interruptions due to system memory pressure. +.IP +Some systems do not support \fBmlockall()\fR at all, and other systems +only allow privileged users, such as the superuser, to use it. +\fBovs\-vswitchd\fR emits a log message if \fBmlockall()\fR is +unavailable or unsuccessful. . +.IP "\fB\-\-enable\-of14\fR" +Specifying this option allows OpenFlow 1.4 to be used if it is enabled +through the \fBprotocols\fR column in the \fBController\fR. Without +this option, \fBovs\-vswitchd\fR will not use OpenFlow 1.4 even if it +is enabled that way. This option is present because OpenFlow 1.4 +support is not safe: the daemon will abort when certain unimplemented +features are tested. Thus, for now it is suitable only for +experimental use. When the support is implemented safely, this option +will be removed. +. +.SS "Daemon Options" +.ds DD \ +\fBovs\-vswitchd\fR detaches only after it has connected to the \ +database, retrieved the initial configuration, and set up that \ +configuration. .so lib/daemon.man +.SS "Service Options" +.so lib/service.man +.SS "Public Key Infrastructure Options" +.so lib/ssl.man +.so lib/ssl-bootstrap.man .so lib/vlog.man .so lib/common.man -.so lib/leak-checker.man . -.SH "BUGS" +.SH "RUNTIME MANAGEMENT COMMANDS" +\fBovs\-appctl\fR(8) can send commands to a running +\fBovs\-vswitchd\fR process. The currently supported commands are +described below. The command descriptions assume an understanding of +how to configure Open vSwitch. +.SS "GENERAL COMMANDS" +.IP "\fBexit\fR" +Causes \fBovs\-vswitchd\fR to gracefully terminate. +.IP "\fBqos/show\fR \fIinterface\fR" +Queries the kernel for Quality of Service configuration and statistics +associated with the given \fIinterface\fR. +.IP "\fBbfd/show\fR [\fIinterface\fR]" +Displays detailed information about Bidirectional Forwarding Detection +configured on \fIinterface\fR. If \fIinterface\fR is not specified, +then displays detailed information about all interfaces with BFD +enabled. +.IP "\fBbfd/set-forwarding\fR [\fIinterface\fR] \fIstatus\fR" +Force the fault status of the BFD module on \fIinterface\fR (or all +interfaces if none is given) to be \fIstatus\fR. \fIstatus\fR can be +"true", "false", or "normal" which reverts to the standard behavior. +.IP "\fBcfm/show\fR [\fIinterface\fR]" +Displays detailed information about Connectivity Fault Management +configured on \fIinterface\fR. If \fIinterface\fR is not specified, +then displays detailed information about all interfaces with CFM +enabled. +.IP "\fBcfm/set-fault\fR [\fIinterface\fR] \fIstatus\fR" +Force the fault status of the CFM module on \fIinterface\fR (or all +interfaces if none is given) to be \fIstatus\fR. \fIstatus\fR can be +"true", "false", or "normal" which reverts to the standard behavior. +.IP "\fBstp/tcn\fR [\fIbridge\fR]" +Forces a topology change event on \fIbridge\fR if it's running STP. This +may cause it to send Topology Change Notifications to its peers and flush +its MAC table.. If no \fIbridge\fR is given, forces a topology change +event on all bridges. +.SS "BRIDGE COMMANDS" +These commands manage bridges. +.IP "\fBfdb/flush\fR [\fIbridge\fR]" +Flushes \fIbridge\fR MAC address learning table, or all learning tables +if no \fIbridge\fR is given. +.IP "\fBfdb/show\fR \fIbridge\fR" +Lists each MAC address/VLAN pair learned by the specified \fIbridge\fR, +along with the port on which it was learned and the age of the entry, +in seconds. +.IP "\fBbridge/reconnect\fR [\fIbridge\fR]" +Makes \fIbridge\fR drop all of its OpenFlow controller connections and +reconnect. If \fIbridge\fR is not specified, then all bridges drop +their controller connections and reconnect. +.IP +This command might be useful for debugging OpenFlow controller issues. +. +.IP "\fBbridge/dump\-flows\fR \fIbridge\fR" +Lists all flows in \fIbridge\fR, including those normally hidden to +commands such as \fBovs\-ofctl dump\-flows\fR. Flows set up by mechanisms +such as in-band control and fail-open are hidden from the controller +since it is not allowed to modify or override them. +.SS "BOND COMMANDS" +These commands manage bonded ports on an Open vSwitch's bridges. To +understand some of these commands, it is important to understand a +detail of the bonding implementation called ``source load balancing'' +(SLB). Instead of directly assigning Ethernet source addresses to +slaves, the bonding implementation computes a function that maps an +48-bit Ethernet source addresses into an 8-bit value (a ``MAC hash'' +value). All of the Ethernet addresses that map to a single 8-bit +value are then assigned to a single slave. +.IP "\fBbond/list\fR" +Lists all of the bonds, and their slaves, on each bridge. +. +.IP "\fBbond/show\fR [\fIport\fR]" +Lists all of the bond-specific information (updelay, downdelay, time +until the next rebalance) about the given bonded \fIport\fR, or all +bonded ports if no \fIport\fR is given. Also lists information about +each slave: whether it is enabled or disabled, the time to completion +of an updelay or downdelay if one is in progress, whether it is the +active slave, the hashes assigned to the slave. Any LACP information +related to this bond may be found using the \fBlacp/show\fR command. +. +.IP "\fBbond/migrate\fR \fIport\fR \fIhash\fR \fIslave\fR" +Only valid for SLB bonds. Assigns a given MAC hash to a new slave. +\fIport\fR specifies the bond port, \fIhash\fR the MAC hash to be +migrated (as a decimal number between 0 and 255), and \fIslave\fR the +new slave to be assigned. +.IP +The reassignment is not permanent: rebalancing or fail-over will +cause the MAC hash to be shifted to a new slave in the usual +manner. +.IP +A MAC hash cannot be migrated to a disabled slave. +.IP "\fBbond/set\-active\-slave\fR \fIport\fR \fIslave\fR" +Sets \fIslave\fR as the active slave on \fIport\fR. \fIslave\fR must +currently be enabled. +.IP +The setting is not permanent: a new active slave will be selected +if \fIslave\fR becomes disabled. +.IP "\fBbond/enable\-slave\fR \fIport\fR \fIslave\fR" +.IQ "\fBbond/disable\-slave\fR \fIport\fR \fIslave\fR" +Enables (or disables) \fIslave\fR on the given bond \fIport\fR, skipping any +updelay (or downdelay). +.IP +This setting is not permanent: it persists only until the carrier +status of \fIslave\fR changes. +.IP "\fBbond/hash\fR \fImac\fR [\fIvlan\fR] [\fIbasis\fR]" +Returns the hash value which would be used for \fImac\fR with \fIvlan\fR +and \fIbasis\fR if specified. +. +.IP "\fBlacp/show\fR [\fIport\fR]" +Lists all of the LACP related information about the given \fIport\fR: +active or passive, aggregation key, system id, and system priority. Also +lists information about each slave: whether it is enabled or disabled, +whether it is attached or detached, port id and priority, actor +information, and partner information. If \fIport\fR is not specified, +then displays detailed information about all interfaces with CFM +enabled. +. +.so ofproto/ofproto-dpif-unixctl.man +.so ofproto/ofproto-unixctl.man +.so lib/vlog-unixctl.man +.so lib/memory-unixctl.man +.so lib/coverage-unixctl.man +. +.SH "OPENFLOW IMPLEMENTATION" +. +.PP +This section documents aspects of OpenFlow for which the OpenFlow +specification requires documentation. +. +.SS "Packet buffering." +The OpenFlow specification, version 1.2, says: +. +.IP +Switches that implement buffering are expected to expose, through +documentation, both the amount of available buffering, and the length +of time before buffers may be reused. +. +.PP +Open vSwitch maintains a separate set of 256 packet buffers for each +OpenFlow connection. Any given packet buffer is preserved until it is +referenced by an \fBOFPT_FLOW_MOD\fR or \fBOFPT_PACKET_OUT\fR request +or for 5 seconds, whichever comes first. +. +.SH "LIMITS" . -Only Open vSwitch kernel-based datapaths are currently supported. In the -future, this restriction may be lifted. .PP -Only Linux 2.6.\fIx\fR is currently supported. +We believe these limits to be accurate as of this writing. These +limits assume the use of the Linux kernel datapath. +. +.IP \(bu +\fBovs\-vswitchd\fR started through \fBovs\-ctl\fR(8) provides a limit of 7500 +file descriptors. The limits on the number of bridges and ports is decided by +the availability of file descriptors. With the Linux kernel datapath, creation +of a single bridge consumes 3 file descriptors and adding a port consumes +1 file descriptor. Performance will degrade beyond 1,024 ports per bridge due +to fixed hash table sizing. Other platforms may have different limitations. +. +.IP \(bu +2,048 MAC learning entries per bridge, by default. (This is +configurable via \fBother\-config:mac\-table\-size\fR in the +\fBBridge\fR table. See \fBovs\-vswitchd.conf.db\fR(5) for details.) +. +.IP \(bu +Kernel flows are limited only by memory available to the kernel. +Performance will degrade beyond 1,048,576 kernel flows per bridge with +a 32-bit kernel, beyond 262,144 with a 64-bit kernel. +(\fBovs\-vswitchd\fR should never install anywhere near that many +flows.) +. +.IP \(bu +OpenFlow flows are limited only by available memory. Performance is +linear in the number of unique wildcard patterns. That is, an +OpenFlow table that contains many flows that all match on the same +fields in the same way has a constant-time lookup, but a table that +contains many flows that match on different fields requires lookup +time linear in the number of flows. +. +.IP \(bu +255 ports per bridge participating in 802.1D Spanning Tree Protocol. +. +.IP \(bu +32 mirrors per bridge. +. +.IP \(bu +15 bytes for the name of a port. (This is a Linux kernel limitation.) . .SH "SEE ALSO" .BR ovs\-appctl (8), -.BR ovs\-vswitchd.conf (5), -.BR ovs\-brcompatd (8), +.BR ovsdb\-server (1), \fBINSTALL.Linux\fR in the Open vSwitch distribution.