ovsdb: Add documentation for ovsdb-server and ovsdb-tool programs.

7 files changed, 172 insertions, 9 deletions

diff --git a/lib/automake.mk b/lib/automake.mk
index 7e70822a..0e93369a 100644
--- a/lib/automake.mk
+++ b/lib/automake.mk
@@ -184,10 +184,13 @@ EXTRA_DIST += \
 
 EXTRA_DIST += \
 	lib/common.man \
+	lib/common-syn.man \
 	lib/daemon.man \
+	lib/daemon-syn.man \
 	lib/dpif.man \
 	lib/leak-checker.man \
 	lib/vlog-unixctl.man \
+	lib/vlog-syn.man \
 	lib/vlog.man
 
 
diff --git a/lib/common-syn.man b/lib/common-syn.man
new file mode 100644
index 00000000..ae1bed51
--- /dev/null
+++ b/lib/common-syn.man
@@ -0,0 +1,4 @@
+.IP "Common options:"
+[\fB-h\fR | \fB--help\fR]
+[\fB-V\fR | \fB--version\fR]
+
diff --git a/lib/daemon-syn.man b/lib/daemon-syn.man
new file mode 100644
index 00000000..49705644
--- /dev/null
+++ b/lib/daemon-syn.man
@@ -0,0 +1,5 @@
+.IP "Daemon options:"
+[\fB--pidfile\fR[\fB=\fIpidfile\fR]]
+[\fB--overwrite-pidfile\fR]
+[\fB--detach\fR]
+[\fB--no-chdir\fR]
diff --git a/lib/vlog-syn.man b/lib/vlog-syn.man
new file mode 100644
index 00000000..873b2f0b
--- /dev/null
+++ b/lib/vlog-syn.man
@@ -0,0 +1,6 @@
+.IP "Logging options:"
+[\fB-v\fR[\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]]]\&...
+.br
+[\fB--verbose[=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]]]\&...
+.br
+[\fB--log-file\fR[\fB=\fIfile\fR]]
diff --git a/ovsdb/automake.mk b/ovsdb/automake.mk
index d2a3e04c..5670281b 100644
--- a/ovsdb/automake.mk
+++ b/ovsdb/automake.mk
@@ -28,17 +28,16 @@ ovsdb_libovsdb_a_SOURCES = \
 bin_PROGRAMS += ovsdb/ovsdb-tool
 ovsdb_ovsdb_tool_SOURCES = ovsdb/ovsdb-tool.c
 ovsdb_ovsdb_tool_LDADD = ovsdb/libovsdb.a lib/libopenvswitch.a
-
-## ovsdb-tool.8
-#man_MANS += ovsdb/ovsdb-tool.8
-#DISTCLEANFILES += ovsdb/ovsdb-tool.8
-#EXTRA_DIST += ovsdb/ovsdb-tool.8.in
+# ovsdb-tool.1
+man_MANS += ovsdb/ovsdb-tool.1
+DISTCLEANFILES += ovsdb/ovsdb-tool.1
+EXTRA_DIST += ovsdb/ovsdb-tool.1.in
 
 # ovsdb-server
 sbin_PROGRAMS += ovsdb/ovsdb-server
 ovsdb_ovsdb_server_SOURCES = ovsdb/ovsdb-server.c
 ovsdb_ovsdb_server_LDADD = ovsdb/libovsdb.a lib/libopenvswitch.a $(FAULT_LIBS)
-## ovsdb-server.8
-#man_MANS += ovsdb/ovsdb-server.8
-#DISTCLEANFILES += ovsdb/ovsdb-server.8
-#EXTRA_DIST += ovsdb/ovsdb-server.8.in
+# ovsdb-server.1
+man_MANS += ovsdb/ovsdb-server.1
+DISTCLEANFILES += ovsdb/ovsdb-server.1
+EXTRA_DIST += ovsdb/ovsdb-server.1.in
diff --git a/ovsdb/ovsdb-server.1.in b/ovsdb/ovsdb-server.1.in
new file mode 100644
index 00000000..d24e443f
--- /dev/null
+++ b/ovsdb/ovsdb-server.1.in
@@ -0,0 +1,72 @@
+.\" -*- nroff -*-
+.TH ovsdb\-server 1 "November 2009" "Open vSwitch" "Open vSwitch Manual"
+.ds PN ovsdb\-server
+.
+.SH NAME
+ovsdb\-server \- Open vSwitch database server
+.
+.SH SYNOPSIS
+\fBovsdb\-server\fR
+\fIdatabase\fR
+[\fB--connect \fIremote\fR]\&...
+[\fB--listen \fIlocal\fR]\&...
+.so lib/daemon-syn.man
+.so lib/vlog-syn.man
+.so lib/common-syn.man
+.
+.SH DESCRIPTION
+The \fBovsdb\-server\fR program provides RPC interfaces to an Open
+vSwitch database (OVSDB).  It can listen for JSON-RPC connections from
+TCP/IP or Unix domain socket clients (with \fB\-\-listen\fR), connect to
+remote JSON-RPC TCP/IP or Unix domain socket clients (with
+\fB\-\-connect\fR).
+.PP
+The name of the OVSDB file must be specified on the command line as
+\fIdatabase\fR, which must already have been created and initialized
+using, for example, \fBovsdb\-tool create\fR.
+.
+.SH OPTIONS
+.
+.IP "\fB\-\-listen=\fIlocal\fR"
+Makes \fBovsdb\-server\fR listen for JSON-RPC connections on
+\fIlocal\fR, which must take one of the following forms:
+.
+.RS
+.IP "\fBptcp:\fIport\fR[\fB:\fIip\fR]"
+Listens for JSON-RPC connections on the given TCP \fIport\fR.  By
+default, \fB\*(PN\fR listens for connections to any local IP address,
+but \fIip\fR may be specified to listen only for connections to the
+given \fIip\fR.
+.IP "\fBpunix:\fIfile\fR"
+Listens for JSON-RPC connections on the Unix domain server socket
+named \fIfile\fR.
+.RE
+.
+.IP "\fB\-\-connect=\fIremote\fR"
+Makes \fBovsdb\-server\fR initiate a JSON-RPC connection to
+\fIremote\fR, which must take one of the forms listed below.  The
+current implementation only attempts to connect once, and does not
+reconnect after a failure or after the connection closes.  This will
+be fixed later.
+.
+.RS
+.IP "\fBtcp:\fIip\fB:\fIport\fR"
+Connects to the given TCP \fIport\fR on \fIip\fR.
+.IP "\fBunix:\fIfile\fR"
+Connects to the Unix domain server socket named \fIfile\fR.
+.RE
+.
+.SS "Daemon Options"
+.so lib/daemon.man
+.SS "Logging Options"
+.so lib/vlog.man
+.SS "Other Options"
+.so lib/common.man
+.SH "RUNTIME MANAGEMENT COMMANDS"
+\fBovs\-appctl\fR(8) can send commands to a running
+\fBovsdb\-server\fR process.  The currently supported commands are
+described below.
+.so lib/vlog-unixctl.man
+.SH "SEE ALSO"
+.
+.BR ovsdb\-tool (1).
diff --git a/ovsdb/ovsdb-tool.1.in b/ovsdb/ovsdb-tool.1.in
new file mode 100644
index 00000000..56713103
--- /dev/null
+++ b/ovsdb/ovsdb-tool.1.in
@@ -0,0 +1,74 @@
+.\" -*- nroff -*-
+.de IQ
+.  br
+.  ns
+.  IP "\\$1"
+..
+.\" -*- nroff -*-
+.TH ovsdb\-tool 1 "November 2009" "Open vSwitch" "Open vSwitch Manual"
+.ds PN ovsdb\-tool
+.
+.SH NAME
+ovsdb\-tool \- Open vSwitch database management utility
+.
+.SH SYNOPSIS
+\fBovsdb\-tool \fR[\fIoptions\fR] \fBcreate\fI db schema\fR
+.br
+\fBovsdb\-tool \fR[\fIoptions\fR] \fBquery\fI db transaction\fR
+.br
+\fBovsdb\-tool \fR[\fIoptions\fR] \fBtransact\fI db transaction\fR
+.br
+\fBovsdb\-tool help\fR
+.so lib/vlog-syn.man
+.so lib/common-syn.man
+.
+.SH DESCRIPTION
+The \fBovsdb\-tool\fR program is a command-line tool for managing Open
+vSwitch database (OVSDB) files.  It does not interact directly with
+running Open vSwitch database servers (instead, use
+\fBovsdb\-client\fR).
+.
+.SS "Basic Commands"
+.IP "\fBcreate\fI db schema\fR"
+Reads an OVSDB schema from the file named \fIschema\fR and creates a
+new OVSDB database file named \fIdb\fR using that schema.  The new
+database is initially empty.  This command will not overwrite an
+existing \fIdb\fR.
+.IP
+\fIschema\fR must contain an OVSDB schema in JSON format.  Refer to
+the OVSDB specification for details.
+.
+.IP "\fBquery\fI db transaction\fR"
+Opens \fIdb\fR, executes \fItransaction\fR on it, and prints the
+results.  The \fItransaction\fR must be a JSON array in the format of
+the \fBparams\fR array for the JSON-RPC \fBtransact\fR method, as
+described in the OVSDB specification.
+.IP
+The \fIdb\fR is opened for read-only access, so this command may
+safely run concurrently with other database activity, including
+\fBovsdb-server\fR and other database writers.  The \fItransaction\fR
+may specify database modifications, but these will have no effect on
+\fIdb\fR.
+.
+.IQ "\fBtransact\fI db transaction\fR"
+Opens \fIdb\fR, executes \fItransaction\fR on it, prints the results,
+and commits any changes to \fIdb\fR.  The \fItransaction\fR must be a
+JSON array in the format of the \fBparams\fR array for the JSON-RPC
+\fBtransact\fR method, as described in the OVSDB specification.
+.IP
+The \fIdb\fR is opened and locked for read/write access, so this
+command will fail if the database is opened for writing by any other
+process, including \fBovsdb-server\fR(1).  Use \fBovsdb\-client\fR(1),
+instead, to write to a database that is served by
+\fBovsdb-server\fR(1).
+.
+.SH OPTIONS
+.SS "Logging Options"
+.so lib/vlog.man
+.SS "Other Options"
+.so lib/common.man
+.SH "SEE ALSO"
+.
+\fBovsdb\-server\fR(1),
+\fBovsdb\-client\fR(1),
+and the OVSDB specification.