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