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 \fBovsdb\-tool \fR[\fIoptions\fR] \fBcreate \fR[\fIdb\fR [\fIschema\fR]]
  16 .br
  17 \fBovsdb\-tool \fR[\fIoptions\fR] \fBcompact \fR[\fIdb\fR [\fItarget\fR]]
  18 .br
  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 .br
  32 \fBovsdb\-tool \fR[\fIoptions\fR] \fBquery \fR[\fIdb\fR] \fItransaction\fR
  33 .br
  34 \fBovsdb\-tool \fR[\fIoptions\fR] \fBtransact \fR[\fIdb\fR] \fItransaction\fR
  35 .br
  36 \fBovsdb\-tool \fR[\fIoptions\fR] [\fB\-m\fR | \fB\-\-more\fR]... \fBshow\-log \fR[\fIdb\fR]
  37 .br
  38 \fBovsdb\-tool help\fR
  39 .so lib/vlog-syn.man
  40 .so lib/common-syn.man
  41 .
  42 .SH DESCRIPTION
  43 The \fBovsdb\-tool\fR program is a command-line tool for managing Open
  44 vSwitch database (OVSDB) files.  It does not interact directly with
  45 running Open vSwitch database servers (instead, use
  46 \fBovsdb\-client\fR).
  47 .
  48 .SS "Basic Commands"
  49 .IP "\fBcreate\fI db schema\fR"
  50 Reads an OVSDB schema from the file named \fIschema\fR and creates a
  51 new OVSDB database file named \fIdb\fR using that schema.  The new
  52 database is initially empty.  This command will not overwrite an
  53 existing \fIdb\fR.
  54 .IP
  55 \fIschema\fR must contain an OVSDB schema in JSON format.  Refer to
  56 the OVSDB specification for details.
  57 .
  58 .IP "\fBcompact\fI db \fR[\fItarget\fR]"
  59 Reads \fIdb\fR and writes a compacted version.  If \fItarget\fR is
  60 specified, the compacted version is written as a new file named
  61 \fItarget\fR, which must not already exist.  If \fItarget\fR is
  62 omitted, then the compacted version of the database replaces \fIdb\fR
  63 in-place.
  64 .
  65 .IP "\fBconvert\fI db schema \fR[\fItarget\fR]"
  66 Reads \fIdb\fR, translating it into to the schema specified in
  67 \fIschema\fR, and writes out the new interpretation.  If \fItarget\fR
  68 is specified, the translated version is written as a new file named
  69 \fItarget\fR, which must not already exist.  If \fItarget\fR is
  70 omitted, then the translated version of the database replaces \fIdb\fR
  71 in-place.
  72 .IP
  73 This command can do simple ``upgrades'' and ``downgrades'' on a
  74 database's schema.  The data in \fIdb\fR must be valid when
  75 interpreted under \fIschema\fR, with only one exception: data in
  76 \fIdb\fR for tables and columns that do not exist in \fIschema\fR are
  77 ignored.  Columns that exist in \fIschema\fR but not in \fIdb\fR are
  78 set to their default values.  All of \fIschema\fR's constraints apply
  79 in full.
  80 .
  81 .IP "\fBneeds\-conversion\fI db schema\fR"
  82 Reads the schema embedded in \fIdb\fR and the standalone schema in
  83 \fIschema\fR and compares them.  If the schemas are the same, prints
  84 \fBno\fR on stdout; if they differ, print \fByes\fR.
  85 .
  86 .IP "\fBdb\-version\fI db\fR"
  87 .IQ "\fBschema\-version\fI schema\fR"
  88 Prints the version number in the schema embedded within the database
  89 \fIdb\fR or in the standalone schema \fIschema\fR on stdout.  A schema
  90 version number has the form \fIx\fB.\fIy\fB.\fIz\fR.  See
  91 \fBovs\-vswitchd.conf.db\fR(5) for details.
  92 .IP
  93 Schema version numbers and Open vSwitch version numbers are
  94 independent.
  95 .IP
  96 If \fIschema\fR or \fIdb\fR was created before schema versioning was
  97 introduced, then it will not have a version number and this command
  98 will print a blank line.
  99 .
 100 .IP "\fBdb\-cksum\fI db\fR"
 101 .IQ "\fBschema\-cksum\fI schema\fR"
 102 Prints the checksum in the schema embedded within the database
 103 \fIdb\fR or of the standalone schema \fIschema\fR on stdout.
 104 .IP
 105 If \fIschema\fR or \fIdb\fR was created before schema checksums were
 106 introduced, then it will not have a checksum and this command
 107 will print a blank line.
 108 .
 109 .IP "\fBquery\fI db transaction\fR"
 110 Opens \fIdb\fR, executes \fItransaction\fR on it, and prints the
 111 results.  The \fItransaction\fR must be a JSON array in the format of
 112 the \fBparams\fR array for the JSON-RPC \fBtransact\fR method, as
 113 described in the OVSDB specification.
 114 .IP
 115 The \fIdb\fR is opened for read-only access, so this command may
 116 safely run concurrently with other database activity, including
 117 \fBovsdb\-server\fR and other database writers.  The \fItransaction\fR
 118 may specify database modifications, but these will have no effect on
 119 \fIdb\fR.
 120 .
 121 .IP "\fBtransact\fI db transaction\fR"
 122 Opens \fIdb\fR, executes \fItransaction\fR on it, prints the results,
 123 and commits any changes to \fIdb\fR.  The \fItransaction\fR must be a
 124 JSON array in the format of the \fBparams\fR array for the JSON-RPC
 125 \fBtransact\fR method, as described in the OVSDB specification.
 126 .IP
 127 The \fIdb\fR is opened and locked for read/write access, so this
 128 command will fail if the database is opened for writing by any other
 129 process, including \fBovsdb\-server\fR(1).  Use \fBovsdb\-client\fR(1),
 130 instead, to write to a database that is served by
 131 \fBovsdb\-server\fR(1).
 132 .
 133 .IP "\fBshow\-log\fI db\fR"
 134 Prints a summary of the records in \fIdb\fR's log, including the time
 135 and date at which each database change occurred and any associated
 136 comment.  This may be useful for debugging.
 137 .IP
 138 To increase the verbosity of output, add \fB\-m\fR (or \fB\-\-more\fR)
 139 one or more times to the command line.  With one \fB\-m\fR,
 140 \fBshow\-log\fR prints a summary of the records added, deleted, or
 141 modified by each transaction.  With two \fB\-m\fRs, \fBshow\-log\fR
 142 also prints the values of the columns modified by each change to a
 143 record.
 144 .
 145 .SH OPTIONS
 146 .SS "Logging Options"
 147 .so lib/vlog.man
 148 .SS "Other Options"
 149 .so lib/common.man
 150 .SH "FILES"
 151 The default \fIdb\fR is \fB@DBDIR@/conf.db\fR.  The
 152 default \fIschema\fR is \fB@pkgdatadir@/vswitch.ovsschema\fR.  The
 153 \fBhelp\fR command also displays these defaults.
 154 .SH "SEE ALSO"
 155 .
 156 \fBovsdb\-server\fR(1),
 157 \fBovsdb\-client\fR(1),
 158 and the OVSDB specification.