ovsdb/ovsdb-tool.1.in

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