From f7f62235b12e5769096dab86980247265b8c4b71 Mon Sep 17 00:00:00 2001 From: Ben Pfaff Date: Fri, 6 Nov 2009 15:35:10 -0800 Subject: [PATCH] ovsdb: Add documentation for ovsdb-server and ovsdb-tool programs. --- lib/automake.mk | 3 ++ lib/common-syn.man | 4 +++ lib/daemon-syn.man | 5 +++ lib/vlog-syn.man | 6 ++++ ovsdb/automake.mk | 17 +++++----- ovsdb/ovsdb-server.1.in | 72 +++++++++++++++++++++++++++++++++++++++ ovsdb/ovsdb-tool.1.in | 74 +++++++++++++++++++++++++++++++++++++++++ 7 files changed, 172 insertions(+), 9 deletions(-) create mode 100644 lib/common-syn.man create mode 100644 lib/daemon-syn.man create mode 100644 lib/vlog-syn.man create mode 100644 ovsdb/ovsdb-server.1.in create mode 100644 ovsdb/ovsdb-tool.1.in diff --git a/lib/automake.mk b/lib/automake.mk index 7e70822af..0e93369a9 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 000000000..ae1bed51d --- /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 000000000..49705644e --- /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 000000000..873b2f0ba --- /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 d2a3e04ce..5670281bf 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 000000000..d24e443f3 --- /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 000000000..567131039 --- /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. -- 2.20.1