ovsdb-tool: Add new "db-name" and "schema-name" commands.

[mirror_ovs.git] / ovsdb / ovsdb-tool.1.in

.\" -*- nroff -*-
.de IQ
.  br
.  ns
.  IP "\\$1"
..
.\" -*- nroff -*-
.TH ovsdb\-tool 1 "@VERSION@" "Open vSwitch" "Open vSwitch Manual"
.ds PN ovsdb\-tool
.
.SH NAME
ovsdb\-tool \- Open vSwitch database management utility
.
.SH SYNOPSIS
.IP "Database Creation Commands:"
\fBovsdb\-tool \fR[\fIoptions\fR] \fBcreate \fR[\fIdb\fR [\fIschema\fR]]
.br
.IP "Version Management Commands:"
\fBovsdb\-tool \fR[\fIoptions\fR] \fBconvert \fR[\fIdb\fR [\fIschema
\fR[\fItarget\fR]]]
.br
\fBovsdb\-tool \fR[\fIoptions\fR] \fBneeds\-conversion \fR[\fIdb\fR [\fIschema\fR]]
.br
\fBovsdb\-tool \fR[\fIoptions\fR] \fBdb\-version \fR[\fIdb\fR]
.br
\fBovsdb\-tool \fR[\fIoptions\fR] \fBschema\-version \fR[\fIschema\fR]
.br
\fBovsdb\-tool \fR[\fIoptions\fR] \fBdb\-cksum \fR[\fIdb\fR]
.br
\fBovsdb\-tool \fR[\fIoptions\fR] \fBschema\-cksum \fR[\fIschema\fR]
.IP "Other commands:"
\fBovsdb\-tool \fR[\fIoptions\fR] \fBcompact \fR[\fIdb\fR [\fItarget\fR]]
.br
\fBovsdb\-tool \fR[\fIoptions\fR] \fBquery \fR[\fIdb\fR] \fItransaction\fR
.br
\fBovsdb\-tool \fR[\fIoptions\fR] \fBtransact \fR[\fIdb\fR] \fItransaction\fR
.br
\fBovsdb\-tool \fR[\fIoptions\fR] [\fB\-m\fR | \fB\-\-more\fR]... \fBshow\-log \fR[\fIdb\fR]
.br
\fBovsdb\-tool \fR[\fIoptions\fR] \fBdb\-name \fR[\fIdb\fR]
.br
\fBovsdb\-tool \fR[\fIoptions\fR] \fBschema\-name \fR[\fIschema\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).
For an introduction to OVSDB and its implementation in Open vSwitch,
see \fBovsdb\fR(7).
.PP
This OVSDB implementation supports standalone and active-backup
database service models with a common on-disk format  For a
specification of this format, see \fBovsdb\fR(5).  For more
information on OVSDB service models, see the \fBService Models\fR
section in \fBovsdb\fR(7).
.
.SS "Database Creation Commands"
This command creates a new OVSDB database file.
It will not overwrite an existing database file.  To
replace an existing database with a new one, first delete the old one.
.
.IP "\fBcreate\fI db schema\fR"
Use this command to create the database for controlling
\fBovs\-vswitchd\fR or another standalone or active-backup database.
It creates database file \fIdb\fR with the given \fIschema\fR, which
must be the name of a file that contains an OVSDB schema in JSON
format, as specified in the OVSDB specification.  The new database is
initially empty.
.
.SS "Version Management Commands"
.so ovsdb/ovsdb-schemas.man
.PP
These commands work with different versions of OVSDB schemas and
databases.
.
.IP "\fBconvert\fI db schema \fR[\fItarget\fR]"
Reads \fIdb\fR, translating it into to the schema specified in
\fIschema\fR, and writes out the new interpretation.  If \fItarget\fR
is specified, the translated version is written as a new file named
\fItarget\fR, which must not already exist.  If \fItarget\fR is
omitted, then the translated version of the database replaces \fIdb\fR
in-place.  In-place conversion cannot take place if the database is
currently being served by \fBovsdb\-server\fR (instead, either stop
\fBovsdb\-server\fR first or use \fBovsdb\-client\fR's \fBconvert\fR
command).
.IP
This command can do simple ``upgrades'' and ``downgrades'' on a
database's schema.  The data in \fIdb\fR must be valid when
interpreted under \fIschema\fR, with only one exception: data in
\fIdb\fR for tables and columns that do not exist in \fIschema\fR are
ignored.  Columns that exist in \fIschema\fR but not in \fIdb\fR are
set to their default values.  All of \fIschema\fR's constraints apply
in full.
.IP
Some uses of this command can cause unrecoverable data loss.  For
example, converting a database from a schema that has a given column
or table to one that does not will delete all data in that column or
table.  Back up critical databases before converting them.
.IP
.IP "\fBneeds\-conversion\fI db schema\fR"
Reads the schema embedded in \fIdb\fR and the JSON schema from
\fIschema\fR and compares them.  If the schemas are the same, prints
\fBno\fR on stdout; if they differ, prints \fByes\fR.
.IP
.IP "\fBdb\-version\fI db\fR"
.IQ "\fBschema\-version\fI schema\fR"
Prints the version number in the schema embedded within the database
\fIdb\fR or in the JSON schema \fIschema\fR on stdout.
If \fIschema\fR or \fIdb\fR was created before schema versioning was
introduced, then it will not have a version number and this command
will print a blank line.
.IP
.IP "\fBdb\-cksum\fI db\fR"
.IQ "\fBschema\-cksum\fI schema\fR"
Prints the checksum in the schema embedded within the database
\fIdb\fR or of the JSON schema \fIschema\fR on stdout.
If \fIschema\fR or \fIdb\fR was created before schema checksums were
introduced, then it will not have a checksum and this command
will print a blank line.
.IP
.SS "Other Commands"
.
.IP "\fBcompact\fI db \fR[\fItarget\fR]"
Reads \fIdb\fR and writes a compacted version.  If \fItarget\fR is
specified, the compacted version is written as a new file named
\fItarget\fR, which must not already exist.  If \fItarget\fR is
omitted, then the compacted version of the database replaces \fIdb\fR
in-place.  This command is not needed in normal operation because
\fBovsdb\-server\fR from time to time automatically compacts a
database that grows much larger than its minimum size.
.IP
This command does not work if \fIdb\fR is currently being served by
\fBovsdb\-server\fR, or if it is otherwise locked for writing by
another process.  Instead, send the \fBovsdb\-server/compact\fR
command to \fBovsdb\-server\fR, via \fBovs\-appctl\fR).
.
.IP "[\fB\-\-rbac\-role=\fIrole\fR] \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
This command opens \fIdb\fR for read-only access, so it 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.
.IP
By default, the transaction is executed using the ``superuser'' RBAC
role.  Use \fB\-\-rbac\-role\fR to specify a different role.
.
.IP "[\fR\-\-rbac\-role=\fIrole\fR] \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
This command does not work if \fIdb\fR is currently being served by
\fBovsdb\-server\fR, or if it is otherwise locked for writing by
another process.  Instead, use \fBovsdb\-client\fR's \fBtransact\fR
command to send the query to \fBovsdb\-server\fR.
.IP
By default, the transaction is executed using the ``superuser'' RBAC
role.  Use \fB\-\-rbac\-role\fR to specify a different role.
.
.IP "\fBshow\-log\fI db\fR"
Prints a summary of the records in \fIdb\fR's log, including the time
and date at which each database change occurred and any associated
comment.  This may be useful for debugging.
.IP
To increase the verbosity of output, add \fB\-m\fR (or \fB\-\-more\fR)
one or more times to the command line.  With one \fB\-m\fR,
\fBshow\-log\fR prints a summary of the records added, deleted, or
modified by each transaction.  With two \fB\-m\fRs, \fBshow\-log\fR
also prints the values of the columns modified by each change to a
record.
.
.IP "\fBdb\-name \fR[\fIdb\fR]"
.IQ "\fBschema\-name \fR[\fIschema\fR]"
Prints the name of the schema embedded within the database \fIdb\fR or
in the JSON schema \fIschema\fR on stdout.
.
.SH OPTIONS
.SS "Logging Options"
.so lib/vlog.man
.SS "Other Options"
.so lib/common.man
.SH "FILES"
The default \fIdb\fR is \fB@DBDIR@/conf.db\fR.  The
default \fIschema\fR is \fB@pkgdatadir@/vswitch.ovsschema\fR.  The
\fBhelp\fR command also displays these defaults.
.SH "SEE ALSO"
.
\fBovsdb\fR(7),
\fBovsdb\-server\fR(1),
\fBovsdb\-client\fR(1).