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