]>
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 |
12b84d50 | 18 | .IP "Version Management Commands:" |
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] |
12b84d50 BP |
31 | .IP "Other commands:" |
32 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBcompact \fR[\fIdb\fR [\fItarget\fR]] | |
6aa09313 | 33 | .br |
e4476f74 | 34 | \fBovsdb\-tool \fR[\fIoptions\fR] \fBquery \fR[\fIdb\fR] \fItransaction\fR |
f7f62235 | 35 | .br |
e4476f74 | 36 | \fBovsdb\-tool \fR[\fIoptions\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 |
f7f62235 BP |
40 | \fBovsdb\-tool help\fR |
41 | .so lib/vlog-syn.man | |
42 | .so lib/common-syn.man | |
43 | . | |
44 | .SH DESCRIPTION | |
45 | The \fBovsdb\-tool\fR program is a command-line tool for managing Open | |
46 | vSwitch database (OVSDB) files. It does not interact directly with | |
47 | running Open vSwitch database servers (instead, use | |
48 | \fBovsdb\-client\fR). | |
12b84d50 BP |
49 | For an introduction to OVSDB and its implementation in Open vSwitch, |
50 | see \fBovsdb\fR(7). | |
51 | .PP | |
52 | This OVSDB implementation supports standalone and active-backup | |
53 | database service models with a common on-disk format For a | |
54 | specification of this format, see \fBovsdb\fR(5). For more | |
55 | information on OVSDB service models, see the \fBService Models\fR | |
56 | section in \fBovsdb\fR(7). | |
f7f62235 | 57 | . |
12b84d50 BP |
58 | .SS "Database Creation Commands" |
59 | This command creates a new OVSDB database file. | |
60 | It will not overwrite an existing database file. To | |
61 | replace an existing database with a new one, first delete the old one. | |
f7f62235 | 62 | . |
12b84d50 BP |
63 | .IP "\fBcreate\fI db schema\fR" |
64 | Use this command to create the database for controlling | |
65 | \fBovs\-vswitchd\fR or another standalone or active-backup database. | |
66 | It creates database file \fIdb\fR with the given \fIschema\fR, which | |
67 | must be the name of a file that contains an OVSDB schema in JSON | |
68 | format, as specified in the OVSDB specification. The new database is | |
69 | initially empty. | |
1e19e50e | 70 | . |
51738fe1 | 71 | .SS "Version Management Commands" |
12b84d50 | 72 | .so ovsdb/ovsdb-schemas.man |
51738fe1 BP |
73 | .PP |
74 | These commands work with different versions of OVSDB schemas and | |
75 | databases. | |
76 | . | |
1e19e50e BP |
77 | .IP "\fBconvert\fI db schema \fR[\fItarget\fR]" |
78 | Reads \fIdb\fR, translating it into to the schema specified in | |
79 | \fIschema\fR, and writes out the new interpretation. If \fItarget\fR | |
80 | is specified, the translated version is written as a new file named | |
81 | \fItarget\fR, which must not already exist. If \fItarget\fR is | |
82 | omitted, then the translated version of the database replaces \fIdb\fR | |
12b84d50 BP |
83 | in-place. In-place conversion cannot take place if the database is |
84 | currently being served by \fBovsdb\-server\fR (instead, either stop | |
85 | \fBovsdb\-server\fR first or use \fBovsdb\-client\fR's \fBconvert\fR | |
86 | command). | |
1e19e50e BP |
87 | .IP |
88 | This command can do simple ``upgrades'' and ``downgrades'' on a | |
89 | database's schema. The data in \fIdb\fR must be valid when | |
90 | interpreted under \fIschema\fR, with only one exception: data in | |
91 | \fIdb\fR for tables and columns that do not exist in \fIschema\fR are | |
92 | ignored. Columns that exist in \fIschema\fR but not in \fIdb\fR are | |
93 | set to their default values. All of \fIschema\fR's constraints apply | |
94 | in full. | |
12b84d50 BP |
95 | .IP |
96 | Some uses of this command can cause unrecoverable data loss. For | |
97 | example, converting a database from a schema that has a given column | |
98 | or table to one that does not will delete all data in that column or | |
99 | table. Back up critical databases before converting them. | |
100 | .IP | |
403e3a25 | 101 | .IP "\fBneeds\-conversion\fI db schema\fR" |
12b84d50 | 102 | Reads the schema embedded in \fIdb\fR and the JSON schema from |
403e3a25 | 103 | \fIschema\fR and compares them. If the schemas are the same, prints |
12b84d50 BP |
104 | \fBno\fR on stdout; if they differ, prints \fByes\fR. |
105 | .IP | |
8159b984 | 106 | .IP "\fBdb\-version\fI db\fR" |
6aa09313 BP |
107 | .IQ "\fBschema\-version\fI schema\fR" |
108 | Prints the version number in the schema embedded within the database | |
12b84d50 | 109 | \fIdb\fR or in the JSON schema \fIschema\fR on stdout. |
6aa09313 BP |
110 | If \fIschema\fR or \fIdb\fR was created before schema versioning was |
111 | introduced, then it will not have a version number and this command | |
112 | will print a blank line. | |
12b84d50 | 113 | .IP |
6aa09313 BP |
114 | .IP "\fBdb\-cksum\fI db\fR" |
115 | .IQ "\fBschema\-cksum\fI schema\fR" | |
116 | Prints the checksum in the schema embedded within the database | |
12b84d50 | 117 | \fIdb\fR or of the JSON schema \fIschema\fR on stdout. |
de66aa57 BP |
118 | If \fIschema\fR or \fIdb\fR was created before schema checksums were |
119 | introduced, then it will not have a checksum and this command | |
6aa09313 | 120 | will print a blank line. |
12b84d50 | 121 | .IP |
51738fe1 BP |
122 | .SS "Other Commands" |
123 | . | |
12b84d50 BP |
124 | .IP "\fBcompact\fI db \fR[\fItarget\fR]" |
125 | Reads \fIdb\fR and writes a compacted version. If \fItarget\fR is | |
126 | specified, the compacted version is written as a new file named | |
127 | \fItarget\fR, which must not already exist. If \fItarget\fR is | |
128 | omitted, then the compacted version of the database replaces \fIdb\fR | |
129 | in-place. This command is not needed in normal operation because | |
130 | \fBovsdb\-server\fR from time to time automatically compacts a | |
131 | database that grows much larger than its minimum size. | |
132 | .IP | |
133 | This command does not work if \fIdb\fR is currently being served by | |
134 | \fBovsdb\-server\fR, or if it is otherwise locked for writing by | |
135 | another process. Instead, send the \fBovsdb\-server/compact\fR | |
136 | command to \fBovsdb\-server\fR, via \fBovs\-appctl\fR). | |
137 | . | |
d6db7b3c | 138 | .IP "[\fB\-\-rbac\-role=\fIrole\fR] \fBquery\fI db transaction\fR" |
f7f62235 BP |
139 | Opens \fIdb\fR, executes \fItransaction\fR on it, and prints the |
140 | results. The \fItransaction\fR must be a JSON array in the format of | |
141 | the \fBparams\fR array for the JSON-RPC \fBtransact\fR method, as | |
142 | described in the OVSDB specification. | |
143 | .IP | |
12b84d50 | 144 | This command opens \fIdb\fR for read-only access, so it may |
f7f62235 | 145 | safely run concurrently with other database activity, including |
4e312e69 | 146 | \fBovsdb\-server\fR and other database writers. The \fItransaction\fR |
f7f62235 BP |
147 | may specify database modifications, but these will have no effect on |
148 | \fIdb\fR. | |
d6db7b3c LR |
149 | .IP |
150 | By default, the transaction is executed using the ``superuser'' RBAC | |
151 | role. Use \fB\-\-rbac\-role\fR to specify a different role. | |
f7f62235 | 152 | . |
d6db7b3c | 153 | .IP "[\fR\-\-rbac\-role=\fIrole\fR] \fBtransact\fI db transaction\fR" |
f7f62235 BP |
154 | Opens \fIdb\fR, executes \fItransaction\fR on it, prints the results, |
155 | and commits any changes to \fIdb\fR. The \fItransaction\fR must be a | |
156 | JSON array in the format of the \fBparams\fR array for the JSON-RPC | |
157 | \fBtransact\fR method, as described in the OVSDB specification. | |
158 | .IP | |
12b84d50 BP |
159 | This command does not work if \fIdb\fR is currently being served by |
160 | \fBovsdb\-server\fR, or if it is otherwise locked for writing by | |
161 | another process. Instead, use \fBovsdb\-client\fR's \fBtransact\fR | |
162 | command to send the query to \fBovsdb\-server\fR. | |
d6db7b3c LR |
163 | .IP |
164 | By default, the transaction is executed using the ``superuser'' RBAC | |
165 | role. Use \fB\-\-rbac\-role\fR to specify a different role. | |
f7f62235 | 166 | . |
4e312e69 | 167 | .IP "\fBshow\-log\fI db\fR" |
9d02e3da | 168 | Prints a summary of the records in \fIdb\fR's log, including the time |
722f6301 BP |
169 | and date at which each database change occurred and any associated |
170 | comment. This may be useful for debugging. | |
5dfad3fa | 171 | .IP |
4e312e69 BP |
172 | To increase the verbosity of output, add \fB\-m\fR (or \fB\-\-more\fR) |
173 | one or more times to the command line. With one \fB\-m\fR, | |
c6782bb0 | 174 | \fBshow\-log\fR prints a summary of the records added, deleted, or |
4e312e69 | 175 | modified by each transaction. With two \fB\-m\fRs, \fBshow\-log\fR |
c6782bb0 BP |
176 | also prints the values of the columns modified by each change to a |
177 | record. | |
722f6301 | 178 | . |
12b84d50 BP |
179 | .IP "\fBdb\-name \fR[\fIdb\fR]" |
180 | .IQ "\fBschema\-name \fR[\fIschema\fR]" | |
181 | Prints the name of the schema embedded within the database \fIdb\fR or | |
182 | in the JSON schema \fIschema\fR on stdout. | |
183 | . | |
f7f62235 BP |
184 | .SH OPTIONS |
185 | .SS "Logging Options" | |
186 | .so lib/vlog.man | |
187 | .SS "Other Options" | |
188 | .so lib/common.man | |
e4476f74 | 189 | .SH "FILES" |
f973f2af | 190 | The default \fIdb\fR is \fB@DBDIR@/conf.db\fR. The |
e4476f74 BP |
191 | default \fIschema\fR is \fB@pkgdatadir@/vswitch.ovsschema\fR. The |
192 | \fBhelp\fR command also displays these defaults. | |
f7f62235 BP |
193 | .SH "SEE ALSO" |
194 | . | |
12b84d50 | 195 | \fBovsdb\fR(7), |
f7f62235 | 196 | \fBovsdb\-server\fR(1), |
12b84d50 | 197 | \fBovsdb\-client\fR(1). |