Refactor initscripts into distro-independent and distro-specific pieces.

This should make it easier to add OVS support to new distributions.

1 files changed, 309 insertions, 0 deletions

diff --git a/utilities/ovs-ctl.8 b/utilities/ovs-ctl.8
new file mode 100644
index 00000000..d649d562
--- /dev/null
+++ b/utilities/ovs-ctl.8
@@ -0,0 +1,309 @@
+.\" -*- nroff -*-
+.de IQ
+.  br
+.  ns
+.  IP "\\$1"
+..
+.de ST
+.  PP
+.  RS -0.15in
+.  I "\\$1"
+.  RE
+..
+.TH ovs\-ctl 8 "June 2011" "Open vSwitch" "Open vSwitch Manual"
+.ds PN ovs\-ctl
+.
+.SH NAME
+ovs\-ctl \- OVS startup helper script
+.
+.SH SYNOPSIS
+\fBovs\-ctl\fR [\fB\-\-system\-id=random\fR | \fIuuid\fR]
+[\fIoptions\fR] \fBstart
+.br
+\fBovs\-ctl stop
+.br
+\fBovs\-ctl status
+.br
+\fBovs\-ctl version
+.br
+\fBovs\-ctl force-reload-kmod
+.br
+\fBovs\-ctl help \fR| \fB\-h \fR| \fB\-\-help
+.br
+\fBovs\-ctl \-\-version
+.
+.SH DESCRIPTION
+.
+.PP
+The \fBovs\-ctl\fR program starts, stops, and checks the status of
+Open vSwitch daemons.  It is not meant to be invoked directly by
+system administrators but to be called internally by system startup
+scripts.
+.
+.PP
+Each of \fBovs\-ctl\fR's commands is described separately below.
+.
+.SH "The ``start'' command"
+.
+.PP
+The \fBstart\fR command starts Open vSwitch.  It performs the
+following tasks:
+.
+.IP 1.
+Loads the Open vSwitch kernel module.  If this fails, and the Linux
+bridge module is loaded but no bridges exist, it tries to unload the
+bridge module and tries loading the Open vSwitch kernel module again.
+(This is because the Open vSwitch kernel module cannot coexist with
+the Linux bridge module before 2.6.37.)
+.
+.PP
+The \fBstart\fR command skips the following steps if
+\fBovsdb\-server\fR is already running:
+.IP 2.
+If the Open vSwitch database file does not exist, it creates it.
+If the database does exist, but it has an obsolete version, it
+upgrades it to the latest schema.
+.
+.IP 3.
+Starts \fBovsdb-server\fR.
+.
+.IP 4.
+Initializes a few values inside the database.
+.
+.IP 5.
+If the \fB\-\-delete\-bridges\fR option was used, deletes all of the
+bridges from the database.
+.
+.PP
+The \fBstart\fR command skips the following step if
+\fBovs\-vswitchd\fR is already running:
+.IP 6.
+Starts \fBovs\-vswitchd\fR.
+.
+.SS "Options"
+.PP
+Several command-line options influence the \fBstart\fR command's
+behavior.  Some form of the following option should ordinarily be
+specified:
+.
+.IP "\fB\-\-system\-id=\fIuuid\fR"
+.IQ "\fB\-\-system\-id=random\fR"
+This specifies a unique system identifier to store into
+\fBexternal-ids:system-id\fR in the database's \fBOpen_vSwitch\fR
+table.  Remote managers that talk to the Open vSwitch database server
+over network protocols use this value to identify and distinguish Open
+vSwitch instances, so it should be unique (at least) within OVS
+instances that will connect to a single controller.
+.IP
+When \fBrandom\fR is specified, \fBovs\-ctl\fR will generate a random
+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:
+.
+.IP "\fB\-\-system\-type=\fItype\fR"
+.IQ "\fB\-\-system\-version=\fIversion\fR"
+Sets the value to store in the \fBsystem-type\fR and
+\fBsystem-version\fR columns, respectively, in the database's
+\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).
+.
+.PP
+The following options are also likely to be useful:
+.
+.IP "\fB\-\-external\-id=\(dq\fIname\fB=\fIvalue\fB\(dq"
+Sets \fBexternal-ids:\fIname\fR to \fIvalue\fR in the database's
+\fBOpen_vSwitch\fR table.  Specifying this option multiple times adds
+multiple key-value pairs.
+.
+.IP "\fB\-\-delete\-bridges\fR"
+Ordinarily Open vSwitch bridges persist from one system boot to the
+next, as long as the database is preserved.  Some environments instead
+expect to re-create all of the bridges and other configuration state
+on every boot.  This option supports that, by deleting all Open
+vSwitch bridges after starting \fBovsdb\-server\fR but before starting
+\fBovs\-vswitchd\fR.
+.
+.PP
+The following options are less important:
+.
+.IP "\fB\-\-daemon-cwd=\fIdirectory\fR"
+Specifies the current working directory that the OVS daemons should
+run from.  The default is \fB/\fR (the root directory) if this option
+is not specified.  (This option is useful because most systems create
+core files in a process's current working directory and because a file
+system that is in use as a process's current working directory cannot
+be unmounted.)
+.
+.IP "\fB\-\-no\-force\-corefiles\fR"
+By default, \fBovs\-ctl\fR enables core dumps for the OVS daemons.
+This option disables that behavior.
+.
+.IP "\fB\-\-no\-mlockall\fR"
+By default \fBovs\-ctl\fR passes \fB\-\-mlockall\fR to
+\fBovs\-vswitchd\fR, requesting that it lock all of its virtual
+memory, preventing it from being paged to disk.  This option
+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.
+.
+.PP
+The following options control file locations.  They should only be
+used if the default locations cannot be used.  See \fBFILES\fR, below,
+for more information.
+.
+.IP "\fB\-\-db\-file=\fIfile\fR"
+Overrides the file name for the OVS database.
+.
+.IP "\fB\-\-db\-sock=\fIsocket\fR"
+Overrides the file name for the Unix domain socket used to connect to
+\fBovsdb\-server\fR.
+.
+.IP "\fB\-\-db\-schema=\fIschema\fR"
+Overrides the file name for the OVS database schema.
+.
+.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.
+.
+.PP
+This command does nothing and finishes successfully if the OVS daemons
+aren't running.
+.
+.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 daemons are running, 1 otherwise.
+.
+.SH "The ``version'' command"
+.
+.PP
+The \fBversion\fR command runs \fBovsdb\-server \-\-version\fR and
+\fBovs\-vswitchd \-\-version\fR.
+.
+.SH "The ``force\-reload\-kmod'' command"
+.
+.PP
+The \fBforce\-reload\-kmod\fR command allows upgrading the Open
+vSwitch kernel module without rebooting.  It performs the following
+tasks:
+.
+.IP 1.
+Gets a list of OVS ``internal'' interfaces, that is, network devices
+implemented by Open vSwitch.  The most common examples of these are
+bridge ``local ports''.
+.
+.IP 2.
+Stops the Open vSwitch daemons, as if by a call to \fBovs\-ctl
+stop\fR.
+.
+.IP 3.
+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.
+.
+.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.
+.
+.PP
+Because \fBforce\-kmod\-reload\fR internally stops and starts OVS, it
+accepts all of the options accepted by the \fBstart\fR command.
+.
+.SS "The ``help'' command"
+.
+Prints a usage message and exits successfully.
+.
+.SH "EXIT STATUS"
+.
+\fBovs\-ctl\fR exits with status 0 on success and nonzero on failure.
+The \fBstart\fR command is considered to succeed if OVS is already
+started; the \fBstop\fR command is considered to succeed if OVS is
+already stopped.
+.
+.SH "ENVIRONMENT"
+.
+The following environment variables affect \fBovs\-ctl\fR:
+.
+.IP "\fBPATH\fR"
+\fBovs\-ctl\fR does not hardcode the location of any of the programs
+that it runs.  \fBovs\-ctl\fR will add the \fIsbindir\fR and
+\fIbindir\fR that were specified at \fBconfigure\fR time to
+\fBPATH\fR, if they are not already present.
+.
+.IP "\fBOVS_LOGDIR\fR"
+.IQ "\fBOVS_RUNDIR\fR"
+.IQ "\fBOVS_SYSCONFDIR\fR"
+.IQ "\fBOVS_PKGDATADIR\fR"
+.IQ "\fBOVS_BINDIR\fR"
+.IQ "\fBOVS_SBINDIR\fR"
+Setting one of these variables in the environment overrides the
+respective \fBconfigure\fR option, both for \fBovs\-ctl\fR itself and
+for the other Open vSwitch programs that it runs.
+.
+.SH "FILES"
+.
+\fBovs\-ctl\fR uses the following files:
+.
+.IP "\fBovs\-lib.sh"
+Shell function library used internally by \fBovs\-ctl\fR.  It must be
+installed in the same directory as \fBovs\-ctl\fR.
+.
+.IP "\fIlogdir\fB/\fIdaemon\fB.log\fR"
+Per-daemon logfiles.
+.
+.IP "\fIrundir\fB/\fIdaemon\fB.pid\fR"
+Per-daemon pidfiles to track whether a daemon is running and with what
+process ID.
+.
+.IP "\fIpkgdatadir\fB/vswitch.ovsschema\fR"
+The OVS database schema used to initialize the database (use
+\fB\-\-db\-schema to override this location).
+.
+.IP "\fIsysconfdir\fB/openvswitch/conf.db\fR"
+The OVS database (use \fB\-\-db\-file\fR to override this location).
+.
+.IP "\fIrundir\fB/openvswitch/db.sock\fR"
+The Unix domain socket used for local communication with
+\fBovsdb\-server\fR (use \fB\-\-db\-sock\fR to override this
+location).
+.
+.IP "\fIsysconfdir\fB/openvswitch/system-id.conf\fR"
+The persistent system UUID created and read by
+\fB\-\-system\-id=random\fR.
+.
+.SH "EXAMPLE"
+.
+.PP
+The files \fBdebian/openvswitch\-switch.init\fR and
+\fBxenserver/etc_init.d_openvswitch\fR in the Open vSwitch source
+distribution are good examples of how to use \fBovs\-ctl\fR.
+.
+.SH "SEE ALSO"
+.
+\fBREADME\fR, \fBINSTALL.LINUX\fR, \fBovsdb\-server\fR(8),
+\fBovs\-vswitchd\fR(8).