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