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