xenserver: Consistently use spaces instead of tabs in init script.
[openvswitch] / ovsdb / ovsdb-tool.1.in
1 .\" -*- nroff -*-
2 .de IQ
3 .  br
4 .  ns
5 .  IP "\\$1"
6 ..
7 .\" -*- nroff -*-
8 .TH ovsdb\-tool 1 "November 2009" "Open vSwitch" "Open vSwitch Manual"
9 .ds PN ovsdb\-tool
10 .
11 .SH NAME
12 ovsdb\-tool \- Open vSwitch database management utility
13 .
14 .SH SYNOPSIS
15 \fBovsdb\-tool \fR[\fIoptions\fR] \fBcreate\fI db schema\fR
16 .br
17 \fBovsdb\-tool \fR[\fIoptions\fR] \fBcompact \fIdb \fR[\fItarget\fR]
18 .br
19 \fBovsdb\-tool \fR[\fIoptions\fR] \fBconvert\fI db schema
20 \fR[\fItarget\fR]
21 .br
22 \fBovsdb\-tool \fR[\fIoptions\fR] \fBdb\-version\fI db\fR
23 .br
24 \fBovsdb\-tool \fR[\fIoptions\fR] \fBschema\-version\fI schema\fR
25 .br
26 \fBovsdb\-tool \fR[\fIoptions\fR] \fBquery\fI db transaction\fR
27 .br
28 \fBovsdb\-tool \fR[\fIoptions\fR] \fBtransact\fI db transaction\fR
29 .br
30 \fBovsdb\-tool \fR[\fIoptions\fR] [\fB\-m\fR | \fB\-\-more\fR]... \fBshow\-log\fI db\fR
31 .br
32 \fBovsdb\-tool help\fR
33 .so lib/vlog-syn.man
34 .so lib/common-syn.man
35 .
36 .SH DESCRIPTION
37 The \fBovsdb\-tool\fR program is a command-line tool for managing Open
38 vSwitch database (OVSDB) files.  It does not interact directly with
39 running Open vSwitch database servers (instead, use
40 \fBovsdb\-client\fR).
41 .
42 .SS "Basic Commands"
43 .IP "\fBcreate\fI db schema\fR"
44 Reads an OVSDB schema from the file named \fIschema\fR and creates a
45 new OVSDB database file named \fIdb\fR using that schema.  The new
46 database is initially empty.  This command will not overwrite an
47 existing \fIdb\fR.
48 .IP
49 \fIschema\fR must contain an OVSDB schema in JSON format.  Refer to
50 the OVSDB specification for details.
51 .
52 .IP "\fBcompact\fI db \fR[\fItarget\fR]"
53 Reads \fIdb\fR and writes a compacted version.  If \fItarget\fR is
54 specified, the compacted version is written as a new file named
55 \fItarget\fR, which must not already exist.  If \fItarget\fR is
56 omitted, then the compacted version of the database replaces \fIdb\fR
57 in-place.
58 .
59 .IP "\fBconvert\fI db schema \fR[\fItarget\fR]"
60 Reads \fIdb\fR, translating it into to the schema specified in
61 \fIschema\fR, and writes out the new interpretation.  If \fItarget\fR
62 is specified, the translated version is written as a new file named
63 \fItarget\fR, which must not already exist.  If \fItarget\fR is
64 omitted, then the translated version of the database replaces \fIdb\fR
65 in-place.
66 .IP
67 This command can do simple ``upgrades'' and ``downgrades'' on a
68 database's schema.  The data in \fIdb\fR must be valid when
69 interpreted under \fIschema\fR, with only one exception: data in
70 \fIdb\fR for tables and columns that do not exist in \fIschema\fR are
71 ignored.  Columns that exist in \fIschema\fR but not in \fIdb\fR are
72 set to their default values.  All of \fIschema\fR's constraints apply
73 in full.
74 .
75 .IP "\fBdb\-version\fI db\fR"
76 Reads \fIdb\fR and prints the version number of the schema embedded
77 within the database on stdout.  A schema version number has the form
78 \fIx\fB.\fIy\fB.\fIz\fR.  See \fBovs\-vswitchd.conf.db\fR(5) for
79 details.
80 .IP
81 Schema version numbers and Open vSwitch version numbers are
82 independent.
83 .IP
84 If \fIdb\fR was created before schema versioning was introduced, then
85 it will not have a version number and this command will print a blank
86 line.
87 .
88 .IP "\fBschema\-version\fI schema\fR"
89 Reads \fIschema\fR and prints the schema's version number on stdout.
90 .IP
91 If \fIschema\fR was created before versioning was introduced, then it
92 does not have a version number and this command will print a blank
93 line.
94 .
95 .IP "\fBquery\fI db transaction\fR"
96 Opens \fIdb\fR, executes \fItransaction\fR on it, and prints the
97 results.  The \fItransaction\fR must be a JSON array in the format of
98 the \fBparams\fR array for the JSON-RPC \fBtransact\fR method, as
99 described in the OVSDB specification.
100 .IP
101 The \fIdb\fR is opened for read-only access, so this command may
102 safely run concurrently with other database activity, including
103 \fBovsdb\-server\fR and other database writers.  The \fItransaction\fR
104 may specify database modifications, but these will have no effect on
105 \fIdb\fR.
106 .
107 .IP "\fBtransact\fI db transaction\fR"
108 Opens \fIdb\fR, executes \fItransaction\fR on it, prints the results,
109 and commits any changes to \fIdb\fR.  The \fItransaction\fR must be a
110 JSON array in the format of the \fBparams\fR array for the JSON-RPC
111 \fBtransact\fR method, as described in the OVSDB specification.
112 .IP
113 The \fIdb\fR is opened and locked for read/write access, so this
114 command will fail if the database is opened for writing by any other
115 process, including \fBovsdb\-server\fR(1).  Use \fBovsdb\-client\fR(1),
116 instead, to write to a database that is served by
117 \fBovsdb\-server\fR(1).
118 .
119 .IP "\fBshow\-log\fI db\fR"
120 Prints a summary of the records in \fBdb\fR's log, including the time
121 and date at which each database change occurred and any associated
122 comment.  This may be useful for debugging.
123 .PP
124 To increase the verbosity of output, add \fB\-m\fR (or \fB\-\-more\fR)
125 one or more times to the command line.  With one \fB\-m\fR,
126 \fBshow\-log\fR prints a summary of the records added, deleted, or
127 modified by each transaction.  With two \fB\-m\fRs, \fBshow\-log\fR
128 also prints the values of the columns modified by each change to a
129 record.
130 .
131 .SH OPTIONS
132 .SS "Logging Options"
133 .so lib/vlog.man
134 .SS "Other Options"
135 .so lib/common.man
136 .SH "SEE ALSO"
137 .
138 \fBovsdb\-server\fR(1),
139 \fBovsdb\-client\fR(1),
140 and the OVSDB specification.