]>
Commit | Line | Data |
---|---|---|
f7f62235 BP |
1 | .\" -*- nroff -*- |
2 | .de IQ | |
3 | . br | |
4 | . ns | |
5 | . IP "\\$1" | |
6 | .. | |
7 | .\" -*- nroff -*- | |
d2cb6c95 | 8 | .TH ovsdb\-tool 1 "@VERSION@" "Open vSwitch" "Open vSwitch Manual" |
f7f62235 BP |
9 | .ds PN ovsdb\-tool |
10 | . | |
11 | .SH NAME | |
12 | ovsdb\-tool \- Open vSwitch database management utility | |
13 | . | |
14 | .SH SYNOPSIS | |
e4476f74 | 15 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBcreate \fR[\fIdb\fR [\fIschema\fR]] |
f7f62235 | 16 | .br |
e4476f74 | 17 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBcompact \fR[\fIdb\fR [\fItarget\fR]] |
8159b984 | 18 | .br |
e4476f74 BP |
19 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBconvert \fR[\fIdb\fR [\fIschema |
20 | \fR[\fItarget\fR]]] | |
8159b984 | 21 | .br |
e4476f74 | 22 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBneeds\-conversion \fR[\fIdb\fR [\fIschema\fR]] |
403e3a25 | 23 | .br |
e4476f74 | 24 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBdb\-version \fR[\fIdb\fR] |
8159b984 | 25 | .br |
e4476f74 | 26 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBschema\-version \fR[\fIschema\fR] |
8159b984 | 27 | .br |
e4476f74 | 28 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBdb\-cksum \fR[\fIdb\fR] |
6aa09313 | 29 | .br |
e4476f74 | 30 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBschema\-cksum \fR[\fIschema\fR] |
6aa09313 | 31 | .br |
e4476f74 | 32 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBquery \fR[\fIdb\fR] \fItransaction\fR |
f7f62235 | 33 | .br |
e4476f74 | 34 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBtransact \fR[\fIdb\fR] \fItransaction\fR |
f7f62235 | 35 | .br |
e4476f74 | 36 | \fBovsdb\-tool \fR[\fIoptions\fR] [\fB\-m\fR | \fB\-\-more\fR]... \fBshow\-log \fR[\fIdb\fR] |
722f6301 | 37 | .br |
f7f62235 BP |
38 | \fBovsdb\-tool help\fR |
39 | .so lib/vlog-syn.man | |
40 | .so lib/common-syn.man | |
41 | . | |
42 | .SH DESCRIPTION | |
43 | The \fBovsdb\-tool\fR program is a command-line tool for managing Open | |
44 | vSwitch database (OVSDB) files. It does not interact directly with | |
45 | running Open vSwitch database servers (instead, use | |
46 | \fBovsdb\-client\fR). | |
47 | . | |
48 | .SS "Basic Commands" | |
49 | .IP "\fBcreate\fI db schema\fR" | |
50 | Reads an OVSDB schema from the file named \fIschema\fR and creates a | |
51 | new OVSDB database file named \fIdb\fR using that schema. The new | |
52 | database is initially empty. This command will not overwrite an | |
53 | existing \fIdb\fR. | |
54 | .IP | |
55 | \fIschema\fR must contain an OVSDB schema in JSON format. Refer to | |
56 | the OVSDB specification for details. | |
57 | . | |
1e19e50e BP |
58 | .IP "\fBcompact\fI db \fR[\fItarget\fR]" |
59 | Reads \fIdb\fR and writes a compacted version. If \fItarget\fR is | |
60 | specified, the compacted version is written as a new file named | |
61 | \fItarget\fR, which must not already exist. If \fItarget\fR is | |
62 | omitted, then the compacted version of the database replaces \fIdb\fR | |
63 | in-place. | |
64 | . | |
51738fe1 BP |
65 | .SS "Version Management Commands" |
66 | .PP | |
67 | An OVSDB schema has a schema version number, and an OVSDB database | |
68 | embeds a particular version of an OVSDB schema. These version numbers | |
69 | take the form \fIx\fB.\fIy\fB.\fIz\fR, e.g. \fB1.2.3\fR. The OVSDB | |
70 | implementation does not enforce a particular version numbering scheme, | |
71 | but schemas managed within the Open vSwitch project use the following | |
72 | approach. Whenever the database schema is changed in a non-backward | |
73 | compatible way (e.g. deleting a column or a table), \fIx\fR is | |
74 | incremented (and \fIy\fR and \fIz\fR are reset to 0). When the | |
75 | database schema is changed in a backward compatible way (e.g. adding a | |
76 | new column), \fIy\fR is incremented (and \fIz\fR is reset to 0). When | |
77 | the database schema is changed cosmetically (e.g. reindenting its | |
78 | syntax), \fIz\fR is incremented. | |
79 | . | |
80 | .PP | |
81 | Some OVSDB databases and schemas, especially very old ones, do not | |
82 | have a version number. | |
83 | . | |
84 | .PP | |
85 | These commands work with different versions of OVSDB schemas and | |
86 | databases. | |
87 | . | |
1e19e50e BP |
88 | .IP "\fBconvert\fI db schema \fR[\fItarget\fR]" |
89 | Reads \fIdb\fR, translating it into to the schema specified in | |
90 | \fIschema\fR, and writes out the new interpretation. If \fItarget\fR | |
91 | is specified, the translated version is written as a new file named | |
92 | \fItarget\fR, which must not already exist. If \fItarget\fR is | |
93 | omitted, then the translated version of the database replaces \fIdb\fR | |
94 | in-place. | |
95 | .IP | |
96 | This command can do simple ``upgrades'' and ``downgrades'' on a | |
97 | database's schema. The data in \fIdb\fR must be valid when | |
98 | interpreted under \fIschema\fR, with only one exception: data in | |
99 | \fIdb\fR for tables and columns that do not exist in \fIschema\fR are | |
100 | ignored. Columns that exist in \fIschema\fR but not in \fIdb\fR are | |
101 | set to their default values. All of \fIschema\fR's constraints apply | |
102 | in full. | |
103 | . | |
403e3a25 BP |
104 | .IP "\fBneeds\-conversion\fI db schema\fR" |
105 | Reads the schema embedded in \fIdb\fR and the standalone schema in | |
106 | \fIschema\fR and compares them. If the schemas are the same, prints | |
107 | \fBno\fR on stdout; if they differ, print \fByes\fR. | |
108 | . | |
8159b984 | 109 | .IP "\fBdb\-version\fI db\fR" |
6aa09313 BP |
110 | .IQ "\fBschema\-version\fI schema\fR" |
111 | Prints the version number in the schema embedded within the database | |
112 | \fIdb\fR or in the standalone schema \fIschema\fR on stdout. A schema | |
113 | version number has the form \fIx\fB.\fIy\fB.\fIz\fR. See | |
114 | \fBovs\-vswitchd.conf.db\fR(5) for details. | |
8159b984 BP |
115 | .IP |
116 | Schema version numbers and Open vSwitch version numbers are | |
117 | independent. | |
118 | .IP | |
6aa09313 BP |
119 | If \fIschema\fR or \fIdb\fR was created before schema versioning was |
120 | introduced, then it will not have a version number and this command | |
121 | will print a blank line. | |
8159b984 | 122 | . |
6aa09313 BP |
123 | .IP "\fBdb\-cksum\fI db\fR" |
124 | .IQ "\fBschema\-cksum\fI schema\fR" | |
125 | Prints the checksum in the schema embedded within the database | |
126 | \fIdb\fR or of the standalone schema \fIschema\fR on stdout. | |
8159b984 | 127 | .IP |
de66aa57 BP |
128 | If \fIschema\fR or \fIdb\fR was created before schema checksums were |
129 | introduced, then it will not have a checksum and this command | |
6aa09313 | 130 | will print a blank line. |
8159b984 | 131 | . |
51738fe1 BP |
132 | .SS "Other Commands" |
133 | . | |
f7f62235 BP |
134 | .IP "\fBquery\fI db transaction\fR" |
135 | Opens \fIdb\fR, executes \fItransaction\fR on it, and prints the | |
136 | results. The \fItransaction\fR must be a JSON array in the format of | |
137 | the \fBparams\fR array for the JSON-RPC \fBtransact\fR method, as | |
138 | described in the OVSDB specification. | |
139 | .IP | |
140 | The \fIdb\fR is opened for read-only access, so this command may | |
141 | safely run concurrently with other database activity, including | |
4e312e69 | 142 | \fBovsdb\-server\fR and other database writers. The \fItransaction\fR |
f7f62235 BP |
143 | may specify database modifications, but these will have no effect on |
144 | \fIdb\fR. | |
145 | . | |
722f6301 | 146 | .IP "\fBtransact\fI db transaction\fR" |
f7f62235 BP |
147 | Opens \fIdb\fR, executes \fItransaction\fR on it, prints the results, |
148 | and commits any changes to \fIdb\fR. The \fItransaction\fR must be a | |
149 | JSON array in the format of the \fBparams\fR array for the JSON-RPC | |
150 | \fBtransact\fR method, as described in the OVSDB specification. | |
151 | .IP | |
152 | The \fIdb\fR is opened and locked for read/write access, so this | |
153 | command will fail if the database is opened for writing by any other | |
4e312e69 | 154 | process, including \fBovsdb\-server\fR(1). Use \fBovsdb\-client\fR(1), |
f7f62235 | 155 | instead, to write to a database that is served by |
4e312e69 | 156 | \fBovsdb\-server\fR(1). |
f7f62235 | 157 | . |
4e312e69 | 158 | .IP "\fBshow\-log\fI db\fR" |
9d02e3da | 159 | Prints a summary of the records in \fIdb\fR's log, including the time |
722f6301 BP |
160 | and date at which each database change occurred and any associated |
161 | comment. This may be useful for debugging. | |
5dfad3fa | 162 | .IP |
4e312e69 BP |
163 | To increase the verbosity of output, add \fB\-m\fR (or \fB\-\-more\fR) |
164 | one or more times to the command line. With one \fB\-m\fR, | |
c6782bb0 | 165 | \fBshow\-log\fR prints a summary of the records added, deleted, or |
4e312e69 | 166 | modified by each transaction. With two \fB\-m\fRs, \fBshow\-log\fR |
c6782bb0 BP |
167 | also prints the values of the columns modified by each change to a |
168 | record. | |
722f6301 | 169 | . |
f7f62235 BP |
170 | .SH OPTIONS |
171 | .SS "Logging Options" | |
172 | .so lib/vlog.man | |
173 | .SS "Other Options" | |
174 | .so lib/common.man | |
e4476f74 | 175 | .SH "FILES" |
f973f2af | 176 | The default \fIdb\fR is \fB@DBDIR@/conf.db\fR. The |
e4476f74 BP |
177 | default \fIschema\fR is \fB@pkgdatadir@/vswitch.ovsschema\fR. The |
178 | \fBhelp\fR command also displays these defaults. | |
f7f62235 BP |
179 | .SH "SEE ALSO" |
180 | . | |
181 | \fBovsdb\-server\fR(1), | |
182 | \fBovsdb\-client\fR(1), | |
183 | and the OVSDB specification. |