]>
Commit | Line | Data |
---|---|---|
f7f62235 | 1 | .\" -*- nroff -*- |
9bccc3ff | 2 | .so lib/ovs.tmac |
d2cb6c95 | 3 | .TH ovsdb\-tool 1 "@VERSION@" "Open vSwitch" "Open vSwitch Manual" |
f7f62235 BP |
4 | .ds PN ovsdb\-tool |
5 | . | |
6 | .SH NAME | |
7 | ovsdb\-tool \- Open vSwitch database management utility | |
8 | . | |
9 | .SH SYNOPSIS | |
12b84d50 | 10 | .IP "Database Creation Commands:" |
e4476f74 | 11 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBcreate \fR[\fIdb\fR [\fIschema\fR]] |
f7f62235 | 12 | .br |
1b1d2e6d BP |
13 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBcreate\-cluster \fIdb contents address\fR |
14 | .br | |
15 | \fBovsdb\-tool \fR[\fIoptions\fR] [\fB\-\-cid=\fIuuid\fR] \fBjoin\-cluster\fI db name local remote\fR... | |
12b84d50 | 16 | .IP "Version Management Commands:" |
e4476f74 BP |
17 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBconvert \fR[\fIdb\fR [\fIschema |
18 | \fR[\fItarget\fR]]] | |
8159b984 | 19 | .br |
e4476f74 | 20 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBneeds\-conversion \fR[\fIdb\fR [\fIschema\fR]] |
403e3a25 | 21 | .br |
e4476f74 | 22 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBdb\-version \fR[\fIdb\fR] |
8159b984 | 23 | .br |
e4476f74 | 24 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBschema\-version \fR[\fIschema\fR] |
8159b984 | 25 | .br |
e4476f74 | 26 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBdb\-cksum \fR[\fIdb\fR] |
6aa09313 | 27 | .br |
e4476f74 | 28 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBschema\-cksum \fR[\fIschema\fR] |
1b1d2e6d BP |
29 | .br |
30 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBcompare-versions\fI a op b\fR | |
12b84d50 BP |
31 | .IP "Other commands:" |
32 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBcompact \fR[\fIdb\fR [\fItarget\fR]] | |
6aa09313 | 33 | .br |
ba19e98c | 34 | \fBovsdb\-tool \fR[\fIoptions\fR] [\fB\-\-rbac\-role=\fIrole\fR] \fBquery \fR[\fIdb\fR] \fItransaction\fR |
f7f62235 | 35 | .br |
ba19e98c | 36 | \fBovsdb\-tool \fR[\fIoptions\fR] [\fB\-\-rbac\-role=\fIrole\fR] \fBtransact \fR[\fIdb\fR] \fItransaction\fR |
f7f62235 | 37 | .br |
e4476f74 | 38 | \fBovsdb\-tool \fR[\fIoptions\fR] [\fB\-m\fR | \fB\-\-more\fR]... \fBshow\-log \fR[\fIdb\fR] |
722f6301 | 39 | .br |
1b1d2e6d BP |
40 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBcheck\-cluster \fIdb\fR... |
41 | .br | |
439902cb BP |
42 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBdb\-name \fR[\fIdb\fR] |
43 | .br | |
44 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBschema\-name \fR[\fIschema\fR] | |
45 | .br | |
1b1d2e6d BP |
46 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBdb\-cid\fI db\fR |
47 | .br | |
48 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBdb\-sid\fI db\fR | |
49 | .br | |
50 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBdb\-local\-address db\fR | |
51 | .br | |
f7f62235 BP |
52 | \fBovsdb\-tool help\fR |
53 | .so lib/vlog-syn.man | |
54 | .so lib/common-syn.man | |
55 | . | |
56 | .SH DESCRIPTION | |
57 | The \fBovsdb\-tool\fR program is a command-line tool for managing Open | |
58 | vSwitch database (OVSDB) files. It does not interact directly with | |
59 | running Open vSwitch database servers (instead, use | |
60 | \fBovsdb\-client\fR). | |
12b84d50 BP |
61 | For an introduction to OVSDB and its implementation in Open vSwitch, |
62 | see \fBovsdb\fR(7). | |
63 | .PP | |
ba19e98c JP |
64 | Each command that takes an optional \fIdb\fR or \fIschema\fR argument |
65 | has a default file location if it is not specified.. The default | |
66 | \fIdb\fR is \fB@DBDIR@/conf.db\fR. The default \fIschema\fR is | |
67 | \fB@pkgdatadir@/vswitch.ovsschema\fR. | |
68 | .PP | |
12b84d50 | 69 | This OVSDB implementation supports standalone and active-backup |
1b1d2e6d BP |
70 | database service models with one on-disk format and a clustered |
71 | database service model with a different format. \fBovsdb\-tool\fR | |
72 | supports both formats, but some commands are appropriate for only one | |
73 | format, as documented for individual commands below. For a | |
74 | specification of these formats, see \fBovsdb\fR(5). For more | |
12b84d50 BP |
75 | information on OVSDB service models, see the \fBService Models\fR |
76 | section in \fBovsdb\fR(7). | |
f7f62235 | 77 | . |
12b84d50 | 78 | .SS "Database Creation Commands" |
1b1d2e6d BP |
79 | These commands create a new OVSDB database file. |
80 | They will not overwrite an existing database file. To | |
12b84d50 | 81 | replace an existing database with a new one, first delete the old one. |
f7f62235 | 82 | . |
ba19e98c | 83 | .IP "\fBcreate \fR[\fIdb\fR [\fIschema\fR]]" |
12b84d50 BP |
84 | Use this command to create the database for controlling |
85 | \fBovs\-vswitchd\fR or another standalone or active-backup database. | |
86 | It creates database file \fIdb\fR with the given \fIschema\fR, which | |
87 | must be the name of a file that contains an OVSDB schema in JSON | |
88 | format, as specified in the OVSDB specification. The new database is | |
1b1d2e6d BP |
89 | initially empty. (You can use \fBcp\fR to copy a database including |
90 | both its schema and data.) | |
91 | . | |
92 | .IP "\fBcreate\-cluster\fI db contents local" | |
93 | Use this command to initialize the first server in a high-availability | |
94 | cluster of 3 (or more) database servers, e.g. for an OVN northbound or | |
95 | southbound database in an environment that cannot tolerate a single | |
96 | point of failure. It creates clustered database file \fIdb\fR and | |
97 | configures the server to listen on \fIlocal\fR, which must take the | |
98 | form \fIprotocol\fB:\fIip\fB:\fIport\fR, where \fIprotocol\fR is | |
99 | \fBtcp\fR or \fBssl\fR, \fIip\fR is the server's IP (either an IPv4 | |
100 | address or an IPv6 address enclosed in square brackets), and | |
101 | \fIport\fR is a TCP port number. Only one address is specified, for | |
102 | the first server in the cluster, ordinarily the one for the server | |
103 | running \fBcreate\-cluster\fR. The address is used for communication | |
104 | within the cluster, not for communicating with OVSDB clients, and must | |
105 | not use the same port used for the OVSDB protocol. | |
106 | .IP | |
107 | The new database is initialized with \fIcontents\fR, which must name a | |
108 | file that contains either an OVSDB schema in JSON format or a | |
109 | standalone OVSDB database. If it is a schema file, the new database | |
110 | will initially be empty, with the given schema. If it is a database | |
111 | file, the new database will have the same schema and contents. | |
112 | . | |
113 | .IP "[\fB\-\-cid=\fIuuid\fR] \fBjoin\-cluster\fI db name local remote\fR..." | |
114 | Use this command to initialize each server after the first one in an | |
115 | OVSDB high-availability cluster. It creates clustered database file | |
116 | \fIdb\fR for a database named \fIname\fR, and | |
117 | configures the server to listen on \fIlocal\fR and to initially | |
118 | connect to \fIremote\fR, which must be a server that already belongs | |
119 | to the cluster. \fIlocal\fR and \fIremote\fR use the same | |
120 | \fIprotocol\fB:\fIip\fB:\fIport\fR syntax as \fBcreate\-cluster\fR. | |
121 | .IP | |
122 | The \fIname\fR must be the name of the schema or database passed to | |
123 | \fBcreate\-cluster\fR. For example, the name of the OVN Southbound | |
124 | database schema is \fBOVN_Southbound\fR. Use \fBovsdb\-tool\fR's | |
125 | \fBschema\-name\fR or \fBdb\-name\fR command to find out the name of a | |
126 | schema or database, respectively. | |
127 | .IP | |
128 | This command does not do any network access, which means that it | |
129 | cannot actually join the new server to the cluster. Instead, the | |
130 | \fIdb\fR file that it creates prepares the server to join the cluster | |
131 | the first time that \fBovsdb\-server\fR serves it. As part of joining | |
132 | the cluster, the new server retrieves the database schema and obtains | |
133 | the list of all cluster members. Only after that does it become a | |
134 | full member of the cluster. | |
135 | .IP | |
136 | Optionally, more than one \fIremote\fR may be specified; for example, | |
137 | in a cluster that already contains multiple servers, one could specify | |
138 | all the existing servers. This is beneficial if some of the existing | |
139 | servers are down while the new server joins, but it is not otherwise | |
140 | needed. | |
141 | .IP | |
142 | By default, the \fIdb\fR created by \fBjoin\-cluster\fR will join any | |
143 | clustered database named \fIname\fR that is available at a | |
144 | \fIremote\fR. In theory, if machines go up and down and IP addresses | |
145 | change in the right way, it could join the wrong database cluster. To | |
146 | avoid this possibility, specify \fB\-\-cid=\fIuuid\fR, where | |
147 | \fIuuid\fR is the cluster ID of the cluster to join, as printed by | |
148 | \fBovsdb\-tool get\-cid\fR. | |
1e19e50e | 149 | . |
51738fe1 | 150 | .SS "Version Management Commands" |
12b84d50 | 151 | .so ovsdb/ovsdb-schemas.man |
51738fe1 BP |
152 | .PP |
153 | These commands work with different versions of OVSDB schemas and | |
154 | databases. | |
155 | . | |
ba19e98c | 156 | .IP "\fBconvert \fR[\fIdb\fR [\fIschema \fR[\fItarget\fR]]]" |
1e19e50e BP |
157 | Reads \fIdb\fR, translating it into to the schema specified in |
158 | \fIschema\fR, and writes out the new interpretation. If \fItarget\fR | |
159 | is specified, the translated version is written as a new file named | |
160 | \fItarget\fR, which must not already exist. If \fItarget\fR is | |
161 | omitted, then the translated version of the database replaces \fIdb\fR | |
12b84d50 BP |
162 | in-place. In-place conversion cannot take place if the database is |
163 | currently being served by \fBovsdb\-server\fR (instead, either stop | |
164 | \fBovsdb\-server\fR first or use \fBovsdb\-client\fR's \fBconvert\fR | |
165 | command). | |
1e19e50e BP |
166 | .IP |
167 | This command can do simple ``upgrades'' and ``downgrades'' on a | |
168 | database's schema. The data in \fIdb\fR must be valid when | |
169 | interpreted under \fIschema\fR, with only one exception: data in | |
170 | \fIdb\fR for tables and columns that do not exist in \fIschema\fR are | |
171 | ignored. Columns that exist in \fIschema\fR but not in \fIdb\fR are | |
172 | set to their default values. All of \fIschema\fR's constraints apply | |
173 | in full. | |
12b84d50 BP |
174 | .IP |
175 | Some uses of this command can cause unrecoverable data loss. For | |
176 | example, converting a database from a schema that has a given column | |
177 | or table to one that does not will delete all data in that column or | |
178 | table. Back up critical databases before converting them. | |
179 | .IP | |
1b1d2e6d BP |
180 | This command is for standalone and active-backup databases only. For |
181 | clustered databases, use \fBovsdb\-client\fR's \fBconvert\fR command | |
182 | to convert them online. | |
183 | . | |
ba19e98c | 184 | .IP "\fBneeds\-conversion \fR[\fIdb\fR [\fIschema\fR]]" |
12b84d50 | 185 | Reads the schema embedded in \fIdb\fR and the JSON schema from |
403e3a25 | 186 | \fIschema\fR and compares them. If the schemas are the same, prints |
12b84d50 BP |
187 | \fBno\fR on stdout; if they differ, prints \fByes\fR. |
188 | .IP | |
1b1d2e6d BP |
189 | This command is for standalone and active-backup databases only. For |
190 | clustered databases, use \fBovsdb\-client\fR's \fBneeds-conversion\fR | |
191 | command instead. | |
192 | . | |
ba19e98c JP |
193 | .IP "\fBdb\-version \fR[\fIdb\fR]" |
194 | .IQ "\fBschema\-version \fR[\fIschema\fR]" | |
6aa09313 | 195 | Prints the version number in the schema embedded within the database |
12b84d50 | 196 | \fIdb\fR or in the JSON schema \fIschema\fR on stdout. |
6aa09313 BP |
197 | If \fIschema\fR or \fIdb\fR was created before schema versioning was |
198 | introduced, then it will not have a version number and this command | |
199 | will print a blank line. | |
12b84d50 | 200 | .IP |
1b1d2e6d BP |
201 | The \fBdb\-version\fR command is for standalone and active-backup |
202 | databases only. For clustered databases, use \fBovsdb\-client\fR's | |
203 | \fBschema\-version\fR command instead. | |
204 | . | |
ba19e98c JP |
205 | .IP "\fBdb\-cksum \fR[\fIdb\fR]" |
206 | .IQ "\fBschema\-cksum \fR[\fIschema\fR]" | |
6aa09313 | 207 | Prints the checksum in the schema embedded within the database |
12b84d50 | 208 | \fIdb\fR or of the JSON schema \fIschema\fR on stdout. |
de66aa57 BP |
209 | If \fIschema\fR or \fIdb\fR was created before schema checksums were |
210 | introduced, then it will not have a checksum and this command | |
6aa09313 | 211 | will print a blank line. |
12b84d50 | 212 | .IP |
1b1d2e6d BP |
213 | The \fBdb\-cksum\fR command is for standalone and active-backup |
214 | databases only. For clustered databases, use \fBovsdb\-client\fR's | |
215 | \fBschema\-cksum\fR command instead. | |
216 | . | |
217 | .IP "\fBcompare-versions\fI a op b\fR" | |
218 | Compares \fIa\fR and \fIb\fR according to \fIop\fR. Both \fIa\fR and | |
219 | \fIb\fR must be OVSDB schema version numbers in the form | |
220 | \fIx\fB.\fIy\fB.\fIz\fR, as described in \fBovsdb\fR(7), and \fIop\fR | |
221 | must be one of \fB< <= == >= > !=\fR. If the comparison is true, | |
222 | exits with status 0; if it is false, exits with status 2. (Exit | |
223 | status 1 indicates an error, e.g. \fIa\fR or \fIb\fR is the wrong | |
224 | syntax for an OVSDB version or \fIop\fR is not a valid comparison | |
225 | operator.) | |
226 | . | |
51738fe1 BP |
227 | .SS "Other Commands" |
228 | . | |
ba19e98c | 229 | .IP "\fBcompact \fR[\fIdb\fR [\fItarget\fR]]" |
12b84d50 BP |
230 | Reads \fIdb\fR and writes a compacted version. If \fItarget\fR is |
231 | specified, the compacted version is written as a new file named | |
232 | \fItarget\fR, which must not already exist. If \fItarget\fR is | |
233 | omitted, then the compacted version of the database replaces \fIdb\fR | |
234 | in-place. This command is not needed in normal operation because | |
235 | \fBovsdb\-server\fR from time to time automatically compacts a | |
236 | database that grows much larger than its minimum size. | |
237 | .IP | |
238 | This command does not work if \fIdb\fR is currently being served by | |
239 | \fBovsdb\-server\fR, or if it is otherwise locked for writing by | |
1b1d2e6d BP |
240 | another process. This command also does not work with clustered |
241 | databases. Instead, in either case, send the | |
242 | \fBovsdb\-server/compact\fR command to \fBovsdb\-server\fR, via | |
243 | \fBovs\-appctl\fR). | |
12b84d50 | 244 | . |
ba19e98c | 245 | .IP "[\fB\-\-rbac\-role=\fIrole\fR] \fBquery \fR[\fIdb\fR] \fItransaction\fR" |
f7f62235 BP |
246 | Opens \fIdb\fR, executes \fItransaction\fR on it, and prints the |
247 | results. The \fItransaction\fR must be a JSON array in the format of | |
248 | the \fBparams\fR array for the JSON-RPC \fBtransact\fR method, as | |
249 | described in the OVSDB specification. | |
250 | .IP | |
12b84d50 | 251 | This command opens \fIdb\fR for read-only access, so it may |
f7f62235 | 252 | safely run concurrently with other database activity, including |
4e312e69 | 253 | \fBovsdb\-server\fR and other database writers. The \fItransaction\fR |
f7f62235 BP |
254 | may specify database modifications, but these will have no effect on |
255 | \fIdb\fR. | |
d6db7b3c LR |
256 | .IP |
257 | By default, the transaction is executed using the ``superuser'' RBAC | |
258 | role. Use \fB\-\-rbac\-role\fR to specify a different role. | |
1b1d2e6d BP |
259 | .IP |
260 | This command does not work with clustered databases. Instead, use | |
261 | \fBovsdb-client\fR's \fBquery\fR command to send the query to | |
262 | \fBovsdb\-server\fR. | |
f7f62235 | 263 | . |
ba19e98c | 264 | .IP "[\fB\-\-rbac\-role=\fIrole\fR] \fBtransact \fR[\fIdb\fR] \fItransaction\fR" |
f7f62235 BP |
265 | Opens \fIdb\fR, executes \fItransaction\fR on it, prints the results, |
266 | and commits any changes to \fIdb\fR. The \fItransaction\fR must be a | |
267 | JSON array in the format of the \fBparams\fR array for the JSON-RPC | |
268 | \fBtransact\fR method, as described in the OVSDB specification. | |
269 | .IP | |
12b84d50 BP |
270 | This command does not work if \fIdb\fR is currently being served by |
271 | \fBovsdb\-server\fR, or if it is otherwise locked for writing by | |
1b1d2e6d BP |
272 | another process. This command also does not work with clustered |
273 | databases. Instead, in either case, use \fBovsdb\-client\fR's | |
274 | \fBtransact\fR command to send the query to \fBovsdb\-server\fR. | |
d6db7b3c LR |
275 | .IP |
276 | By default, the transaction is executed using the ``superuser'' RBAC | |
277 | role. Use \fB\-\-rbac\-role\fR to specify a different role. | |
f7f62235 | 278 | . |
ba19e98c | 279 | .IP "[\fB\-m\fR | \fB\-\-more\fR]... \fBshow\-log \fR[\fIdb\fR]" |
9d02e3da | 280 | Prints a summary of the records in \fIdb\fR's log, including the time |
722f6301 BP |
281 | and date at which each database change occurred and any associated |
282 | comment. This may be useful for debugging. | |
5dfad3fa | 283 | .IP |
4e312e69 BP |
284 | To increase the verbosity of output, add \fB\-m\fR (or \fB\-\-more\fR) |
285 | one or more times to the command line. With one \fB\-m\fR, | |
c6782bb0 | 286 | \fBshow\-log\fR prints a summary of the records added, deleted, or |
4e312e69 | 287 | modified by each transaction. With two \fB\-m\fRs, \fBshow\-log\fR |
c6782bb0 BP |
288 | also prints the values of the columns modified by each change to a |
289 | record. | |
1b1d2e6d BP |
290 | .IP |
291 | This command works with standalone and active-backup databases and | |
292 | with clustered databases, but the output formats are different. | |
293 | . | |
294 | .IP "\fBcheck\-cluster \fIdb\fR..." | |
295 | Reads all of the records in the supplied databases, which must be | |
296 | collected from different servers (and ideally all the servers) in a | |
297 | single cluster. Checks each database for self-consistency and the set | |
298 | together for cross-consistency. If \fBovsdb\-tool\fR detects unusual | |
299 | but not necessarily incorrect content, it prints a warning or warnings | |
300 | on stdout. If \fBovsdb\-tool\fR find consistency errors, it prints an | |
301 | error on stderr and exits with status 1. Errors typically indicate | |
302 | bugs in \fBovsdb\-server\fR; please consider reporting them to the | |
303 | Open vSwitch developers. | |
722f6301 | 304 | . |
12b84d50 BP |
305 | .IP "\fBdb\-name \fR[\fIdb\fR]" |
306 | .IQ "\fBschema\-name \fR[\fIschema\fR]" | |
307 | Prints the name of the schema embedded within the database \fIdb\fR or | |
308 | in the JSON schema \fIschema\fR on stdout. | |
309 | . | |
1b1d2e6d BP |
310 | .IP "\fBdb\-cid\fI db\fR" |
311 | Prints the cluster ID, which is a UUID that identifies the cluster, | |
312 | for \fIdb\fR. If \fIdb\fR is a database newly created by | |
313 | \fBovsdb\-tool cluster\-join\fR that has not yet successfully joined | |
314 | its cluster, and \fB\-\-cid\fR was not specified on the | |
315 | \fBcluster\-join\fR command line, then this command will output an | |
316 | error, and exit with status 2, because the cluster ID is not yet | |
317 | known. This command works only with clustered databases. | |
318 | .IP | |
319 | The all-zeros UUID is not a valid cluster ID. | |
320 | . | |
321 | .IP "\fBdb\-sid\fI db\fR" | |
322 | Prints the server ID, which is a UUID that identifies the server, for | |
323 | \fIdb\fR. This command works only with clustered databases. It works | |
324 | even if \fIdb\fR is a database newly created by \fBovsdb\-tool | |
325 | cluster\-join\fR that has not yet successfully joined its cluster. | |
326 | . | |
327 | .IP "\fBdb\-local\-address db\fR" | |
328 | Prints the local address used for database clustering for \fIdb\fR, in | |
329 | the same \fIprotocol\fB:\fIip\fB:\fIport\fR form used on | |
330 | \fBcreate\-cluster\fR and \fBjoin\-cluster\fR. | |
331 | . | |
332 | .IP "\fBdb\-is\-clustered\fI db\fR" | |
333 | .IQ "\fBdb\-is\-standalone\fI db\fR" | |
334 | Tests whether \fIdb\fR is a database file in clustered or standalone | |
335 | format, respectively. If so, exits with status 0; if not, exits with | |
336 | status 2. (Exit status 1 indicates an error, e.g. \fIdb\fR is not an | |
337 | OVSDB database or does not exist.) | |
338 | . | |
f7f62235 BP |
339 | .SH OPTIONS |
340 | .SS "Logging Options" | |
341 | .so lib/vlog.man | |
342 | .SS "Other Options" | |
343 | .so lib/common.man | |
e4476f74 | 344 | .SH "FILES" |
f973f2af | 345 | The default \fIdb\fR is \fB@DBDIR@/conf.db\fR. The |
e4476f74 BP |
346 | default \fIschema\fR is \fB@pkgdatadir@/vswitch.ovsschema\fR. The |
347 | \fBhelp\fR command also displays these defaults. | |
f7f62235 BP |
348 | .SH "SEE ALSO" |
349 | . | |
12b84d50 | 350 | \fBovsdb\fR(7), |
f7f62235 | 351 | \fBovsdb\-server\fR(1), |
12b84d50 | 352 | \fBovsdb\-client\fR(1). |