X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=utilities%2Fovs-ctl.8;h=97294af86b9d81d8e5216fce9a7fb3f9bfd1faa7;hb=7d78f21c057ff50a823220d809ac38c3d907243c;hp=885771c985a34950a5a67f52c8c7f4b7a1007b0c;hpb=2bed68ff28f525b2153131df64976d4aea2b3aa0;p=sliver-openvswitch.git

diff --git a/utilities/ovs-ctl.8 b/utilities/ovs-ctl.8
index 885771c98..97294af86 100644
--- a/utilities/ovs-ctl.8
+++ b/utilities/ovs-ctl.8
@@ -27,6 +27,10 @@ ovs\-ctl \- OVS startup helper script
 \fBovs\-ctl version
 .br
 \fBovs\-ctl
+[\fIoptions\fR]
+\fBload\-kmod\fR
+.br
+\fBovs\-ctl
 \fB\-\-system\-id=random\fR|\fIuuid\fR
 [\fIoptions\fR]
 \fBforce\-reload\-kmod\fR
@@ -109,9 +113,8 @@ ID that persists from one run to another (stored in a file).  When
 another string is specified \fBovs\-ctl\fR uses it literally.
 .
 .PP
-On systems that have the \fBlsb_release\fR program, \fBovs\-ctl\fR
-chooses reasonable defaults for the following options.  Other systems
-should specify values:
+The following options should be specified if the defaults are not
+suitable:
 .
 .IP "\fB\-\-system\-type=\fItype\fR"
 .IQ "\fB\-\-system\-version=\fIversion\fR"
@@ -120,6 +123,11 @@ Sets the value to store in the \fBsystem-type\fR and
 \fBOpen_vSwitch\fR table.  Remote managers may use these values to
 determine the kind of system to which they are connected (primarily
 for display to human administrators).
+.IP
+When not specified, \fBovs\-ctl\fR uses values from the optional
+\fBsystem\-type.conf\fR and \fBsystem\-version.conf\fR files(see section
+\fBFILES\fR) or it uses the \fBlsb_release\fR program, if present, to
+provide reasonable defaults.
 .
 .PP
 The following options are also likely to be useful:
@@ -160,8 +168,38 @@ suppresses that behavior.
 .
 .IP "\fB\-\-ovsdb\-server\-priority=\fIniceness\fR"
 .IQ "\fB\-\-ovs\-vswitchd\-priority=\fIniceness\fR"
-Sets the \fBnice\fR(1) level used for \fBovsdb\-server\fR and
-\fBovs\-vswitchd\fR, respectively.  Both default to \fB\-10\fR.
+Sets the \fBnice\fR(1) level used for each daemon.  All of them
+default to \fB\-10\fR.
+.
+.IP "\fB\-\-ovsdb\-server\-wrapper=\fIwrapper\fR"
+.IQ "\fB\-\-ovs\-vswitchd\-wrapper=\fIwrapper\fR"
+.
+Configures the specified daemon to run under \fIwrapper\fR, which is
+one of the following:
+.
+.RS
+.IP "\fBvalgrind\fR"
+Run the daemon under \fBvalgrind\fR(1), if it is installed, logging to
+\fIdaemon\fB.valgrind.log.\fIpid\fR in the log directory.
+.
+.IP "\fBstrace\fR"
+Run the daemon under \fBstrace\fR(1), if it is installed, logging to
+\fIdaemon\fB.strace.log.\fIpid\fR in the log directory.
+.
+.IP "\fBglibc\fR"
+Enable GNU C library features designed to find memory errors.
+.RE
+.
+.IP
+By default, no wrapper is used.
+.
+.IP
+Each of the wrappers can expose bugs in Open vSwitch that lead to
+incorrect operation, including crashes.  The \fBvalgrind\fR and
+\fBstrace\fR wrappers greatly slow daemon operations so they should
+not be used in production.  They also produce voluminous logs that can
+quickly fill small disk partitions.  The \fBglibc\fR wrapper is less
+resource-intensive but still somewhat slows the daemons.
 .
 .PP
 The following options control file locations.  They should only be
@@ -178,22 +216,36 @@ Overrides the file name for the Unix domain socket used to connect to
 .IP "\fB\-\-db\-schema=\fIschema\fR"
 Overrides the file name for the OVS database schema.
 .
+.IP "\fB\-\-extra-dbs=\fIfile\fR"
+Adds \fIfile\fR as an extra database for \fBovsdb\-server\fR to serve
+out.  Multiple space-separated file names may also be specified.
+\fIfile\fR should begin with \fB/\fR; if it does not, then it will be
+taken as relative to \fIdbdir\fR.
+.
 .SH "The ``stop'' command"
 .
 .PP
-The \fBstart\fR command shuts down Open vSwitch.  If
-\fBovs\-vswitchd\fR is running, kills it and waits for it to
-terminate, then it does the same for \fBovsdb\-server\fR.
+The \fBstop\fR command does not unload the Open vSwitch kernel
+modules.
 .
 .PP
 This command does nothing and finishes successfully if the OVS daemons
 aren't running.
 .
+.SH "The ``restart'' command"
+.
+.PP
+The \fBrestart\fR command performs a \fBstop\fR followed by a \fBstart\fR
+command.  The command can take the same options as that of the \fBstart\fR
+command. In addition, it saves and restores Openflow flows for each
+individual bridge.
+.
 .SH "The ``status'' command"
 .
 .PP
-The \fBstatus\fR command checks whether the OVS daemons are running
-and prints messages with that information.  It exits with status 0 if
+The \fBstatus\fR command checks whether the OVS daemons
+\fBovs-vswitchd\fR and \fBovsdb\-server\fR are running and prints
+messages with that information.  It exits with status 0 if
 the daemons are running, 1 otherwise.
 .
 .SH "The ``version'' command"
@@ -215,34 +267,56 @@ implemented by Open vSwitch.  The most common examples of these are
 bridge ``local ports''.
 .
 .IP 2.
+Saves the Openflow flows of each bridge.
+.
+.IP 3.
 Stops the Open vSwitch daemons, as if by a call to \fBovs\-ctl
 stop\fR.
 .
-.IP 3.
+.IP 4.
 Saves the kernel configuration state of the OVS internal interfaces
 listed in step 1, including IP and IPv6 addresses and routing table
 entries.
 .
-.IP 4.
-Unloads the Open vSwitch kernel module.
-.
 .IP 5.
-Starts OVS back up, as if by a call to \fBovs\-ctl start\fR.  This
-reloads the kernel module and restarts the OVS daemons.
+Unloads the Open vSwitch kernel module (including the bridge
+compatibility module if it is loaded).
 .
 .IP 6.
-Restores the kernel configuration state that was saved in step 3.
-.
-.PP
-The steps above are often enough to hot-upgrade a new kernel module
-with only a few seconds of downtime.  DHCP is a common problem: if the
-ISC DHCP client is running on an OVS internal interface, then it will
-have to be restarted after completing the above procedure.
+Starts OVS back up, as if by a call to \fBovs\-ctl start\fR.  This
+reloads the kernel module, restarts the OVS daemons and finally
+restores the saved Openflow flows.
+.
+.IP 7.
+Restores the kernel configuration state that was saved in step 4.
+.
+.IP 8.
+Checks for daemons that may need to be restarted because they have
+packet sockets that are listening on old instances of Open vSwitch
+kernel interfaces and, if it finds any, prints a warning on stdout.
+DHCP is a common example: if the ISC DHCP client is running on an OVS
+internal interface, then it will have to be restarted after completing
+the above procedure.  (It would be nice if \fBovs\-ctl\fR could restart
+daemons automatically, but the details are far too specific to a
+particular distribution and installation.)
 .
 .PP
 \fBforce\-kmod\-reload\fR internally stops and starts OVS, so it
 accepts all of the options accepted by the \fBstart\fR command.
 .
+.SH "The ``load\-kmod'' command"
+.
+.PP
+The \fBload\-kmod\fR command loads the openvswitch kernel modules if
+they are not already loaded. This operation also occurs as part of
+the \fBstart\fR command. The motivation for providing the \fBload\-kmod\fR
+command is to allow errors when loading modules to be handled separatetly
+from other errors that may occur when running the \fBstart\fR command.
+.
+.PP
+By default the \fBload\-kmod\fR command attempts to load the
+openvswitch kernel module.
+.
 .SH "The ``enable\-protocol'' command"
 .
 .PP
@@ -289,6 +363,11 @@ and allowed only with \fB\-\-protocol=tcp\fR or
 .
 Prints a usage message and exits successfully.
 .
+.SH "OPTIONS"
+.PP
+In addition to the options listed for each command above, this option
+controls the behavior of several of \fBovs\-ctl\fR's commands.
+.
 .SH "EXIT STATUS"
 .
 \fBovs\-ctl\fR exits with status 0 on success and nonzero on failure.
@@ -308,6 +387,7 @@ that it runs.  \fBovs\-ctl\fR will add the \fIsbindir\fR and
 .
 .IP "\fBOVS_LOGDIR\fR"
 .IQ "\fBOVS_RUNDIR\fR"
+.IQ "\fBOVS_DBDIR\fR"
 .IQ "\fBOVS_SYSCONFDIR\fR"
 .IQ "\fBOVS_PKGDATADIR\fR"
 .IQ "\fBOVS_BINDIR\fR"
@@ -320,7 +400,7 @@ for the other Open vSwitch programs that it runs.
 .
 \fBovs\-ctl\fR uses the following files:
 .
-.IP "\fBovs\-lib.sh"
+.IP "\fBovs\-lib"
 Shell function library used internally by \fBovs\-ctl\fR.  It must be
 installed in the same directory as \fBovs\-ctl\fR.
 .
@@ -335,7 +415,7 @@ process ID.
 The OVS database schema used to initialize the database (use
 \fB\-\-db\-schema to override this location).
 .
-.IP "\fIsysconfdir\fB/openvswitch/conf.db\fR"
+.IP "\fIdbdir\fB/conf.db\fR"
 The OVS database (use \fB\-\-db\-file\fR to override this location).
 .
 .IP "\fIrundir\fB/openvswitch/db.sock\fR"
@@ -347,6 +427,11 @@ location).
 The persistent system UUID created and read by
 \fB\-\-system\-id=random\fR.
 .
+.IP "\fIsysconfdir\fB/openvswitch/system\-type.conf\fR"
+.IQ "\fIsysconfdir\fB/openvswitch/system\-version.conf\fR"
+The \fBsystem\-type\fR  and \fBsystem\-version\fR values stored in the database's
+\fBOpen_vSwitch\fR table when not specified as a command-line option.
+.
 .SH "EXAMPLE"
 .
 .PP
@@ -356,5 +441,5 @@ distribution are good examples of how to use \fBovs\-ctl\fR.
 .
 .SH "SEE ALSO"
 .
-\fBREADME\fR, \fBINSTALL.LINUX\fR, \fBovsdb\-server\fR(8),
+\fBREADME\fR, \fBINSTALL.Linux\fR, \fBovsdb\-server\fR(8),
 \fBovs\-vswitchd\fR(8).