ovsdb/ovsdb-client.1.in

   1 .\" -*- nroff -*-
   2 .de IQ
   3 .  br
   4 .  ns
   5 .  IP "\\$1"
   6 ..
   7 .\" -*- nroff -*-
   8 .TH ovsdb\-client 1 "@VERSION@" "Open vSwitch" "Open vSwitch Manual"
   9 .\" This program's name:
  10 .ds PN ovsdb\-client
  11 .
  12 .SH NAME
  13 ovsdb\-client \- command-line interface to \fBovsdb-server\fR(1)
  14 .
  15 .SH SYNOPSIS
  16 \fBovsdb\-client \fR[\fIoptions\fR] \fBlist\-dbs \fR[\fIserver\fR]
  17 .br
  18 \fBovsdb\-client \fR[\fIoptions\fR] \fBget\-schema \fR[\fIserver\fR] \fR[\fIdatabase\fR]
  19 .br
  20 \fBovsdb\-client \fR[\fIoptions\fR] \fBget\-schema\-version\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR]
  21 .br
  22 \fBovsdb\-client \fR[\fIoptions\fR] \fBlist\-tables\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR]
  23 .br
  24 \fBovsdb\-client \fR[\fIoptions\fR] \fBlist\-columns\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR] [\fItable\fR]
  25 .br
  26 \fBovsdb\-client \fR[\fIoptions\fR] \fBtransact\fI \fR[\fIserver\fR] \fItransaction\fR
  27 .br
  28 \fBovsdb\-client \fR[\fIoptions\fR] \fBdump\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR]\fR [\fItable\fR
  29 [\fIcolumn\fR...]]
  30 .br
  31 \fBovsdb\-client \fR[\fIoptions\fR] \fBmonitor\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR] \fItable\fR
  32 [\fIcolumn\fR[\fB,\fIcolumn\fR]...]...
  33 .br
  34 \fBovsdb\-client \fR[\fIoptions\fR] \fBmonitor\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR] \fBALL\fR
  35 .br
  36 \fBovsdb\-client \fR[\fIoptions\fR] \fBmonitor-cond\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR] \fIconditions
  37 \fItable\fR [\fIcolumn\fR[\fB,\fIcolumn\fR]...]...
  38 .br
  39 \fBovsdb\-client \fR[\fIoptions\fR] \fBlock\fI \fR[\fIserver\fR] \fIlock\fR
  40 .br
  41 \fBovsdb\-client \fR[\fIoptions\fR] \fBsteal\fI \fR[\fIserver\fR] \fIlock\fR
  42 .br
  43 \fBovsdb\-client \fR[\fIoptions\fR] \fBunlock\fI \fR[\fIserver\fR] \fIlock\fR
  44 .br
  45 \fBovsdb\-client help\fR
  46 .IP "Output formatting options:"
  47 [\fB\-\-format=\fIformat\fR]
  48 [\fB\-\-data=\fIformat\fR]
  49 [\fB\-\-no-heading\fR]
  50 [\fB\-\-pretty\fR]
  51 [\fB\-\-bare\fR]
  52 [\fB\-\-no\-heading\fR]
  53 [\fB\-\-timestamp\fR]
  54 .so lib/daemon-syn.man
  55 .so lib/vlog-syn.man
  56 .so lib/ssl-syn.man
  57 .so lib/ssl-bootstrap-syn.man
  58 .so lib/ssl-connect-syn.man
  59 .so lib/common-syn.man
  60 .
  61 .SH DESCRIPTION
  62 The \fBovsdb\-client\fR program is a command-line client for
  63 interacting with a running \fBovsdb\-server\fR process.
  64 Each command connects to an OVSDB server, which is
  65 \fBunix:@RUNDIR@/db.sock\fR by default, or may be specified as
  66 \fIserver\fR in one of the following forms:
  67 .RS
  68 .so ovsdb/remote-active.man
  69 .so ovsdb/remote-passive.man
  70 .RE
  71 .PP
  72 The default \fIdatabase\fR is \fBOpen_vSwitch\fR.
  73 .
  74 .SS "Commands"
  75 The following commands are implemented:
  76 .IP "\fBlist\-dbs \fR[\fIserver\fR]"
  77 Connects to \fIserver\fR, retrieves the list of known databases, and
  78 prints them one per line.  These database names are the ones that may
  79 be used for \fIdatabase\fR in the following commands.
  80 .
  81 .IP "\fBget\-schema \fR[\fIserver\fR] \fR[\fIdatabase\fR]"
  82 Connects to \fIserver\fR, retrieves the schema for \fIdatabase\fR, and
  83 prints it in JSON format.
  84 .
  85 .IP "\fBget\-schema\-version\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR]"
  86 Connects to \fIserver\fR, retrieves the schema for \fIdatabase\fR, and
  87 prints its version number on stdout.  A schema version number has the form
  88 \fIx\fB.\fIy\fB.\fIz\fR.  See \fBovs\-vswitchd.conf.db\fR(5) for
  89 details.
  90 .IP
  91 Schema version numbers and Open vSwitch version numbers are
  92 independent.
  93 .IP
  94 If \fIdatabase\fR was created before schema versioning was introduced,
  95 then it will not have a version number and this command will print a
  96 blank line.
  97 .
  98 .IP "\fBlist\-tables\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR]"
  99 Connects to \fIserver\fR, retrieves the schema for \fIdatabase\fR, and
 100 prints a table listing the name of each table
 101 within the database.
 102 .
 103 .IP "\fBlist\-columns\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR] \fItable\fR"
 104 Connects to \fIserver\fR, retrieves the schema for \fIdatabase\fR, and
 105 prints a table listing the name and type of each
 106 column.  If \fItable\fR is specified, only columns in that table are
 107 listed; otherwise, the tables include columns in all tables.
 108 .
 109 .IP "\fBtransact\fI \fR[\fIserver\fR] \fItransaction\fR"
 110 Connects to \fIserver\fR, sends it the specified \fItransaction\fR,
 111 which must be a JSON array containing one or more valid OVSDB
 112 operations, and prints the received reply on stdout.
 113 .
 114 .IP "\fBdump\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR]\fR [\fItable \fR[\fIcolumn\fR...]]"
 115 Connects to \fIserver\fR, retrieves all of the data in \fIdatabase\fR,
 116 and prints it on stdout as a series of tables. If \fItable\fR is
 117 specified, only that table is retrieved.  If at least one \fIcolumn\fR
 118 is specified, only those columns are retrieved.
 119 .
 120 .IP "\fBmonitor\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR] \fItable\fR [\fIcolumn\fR[\fB,\fIcolumn\fR]...]..."
 121 .IQ "\fBmonitor-cond\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR] \fIconditions\fR \fItable\fR [\fIcolumn\fR[\fB,\fIcolumn\fR]...]..."
 122 Connects to \fIserver\fR and monitors the contents of rows that match conditions in
 123 \fItable\fR in \fIdatabase\fR. By default, the initial contents of \fItable\fR are
 124 printed, followed by each change as it occurs.  If conditions empty,
 125 all rows will be monitored. If at least one \fIcolumn\fR is specified, only those
 126 columns are monitored.  The following \fIcolumn\fR names have special meanings:
 127 .RS
 128 .IP "\fB!initial\fR"
 129 Do not print the initial contents of the specified columns.
 130 .IP "\fB!insert\fR"
 131 Do not print newly inserted rows.
 132 .IP "\fB!delete\fR"
 133 Do not print deleted rows.
 134 .IP "\fB!modify\fR"
 135 Do not print modifications to existing rows.
 136 .RE
 137 .IP
 138 Multiple [\fIcolumn\fR[\fB,\fIcolumn\fR]...] groups may be specified
 139 as separate arguments, e.g. to apply different reporting parameters to
 140 each group.  Whether multiple groups or only a single group is
 141 specified, any given column may only be mentioned once on the command
 142 line.
 143 .IP
 144 \fBconditions\fR is a JSON array of <condition> as defined in RFC 7047 5.1
 145 with the following change: A condition can be either a 3-element JSON array
 146 as deescribed in the RFC or a boolean value..
 147 .IP
 148 If \fB\-\-detach\fR is used with \fBmonitor\fR or \fBmonitor-cond\fR, then
 149 \fBovsdb\-client\fR detaches after it has successfully received and
 150 printed the initial contents of \fItable\fR.
 151 .IP
 152 The \fBmonitor\fR command uses RFC 7047 "monitor" method to open a monitor
 153 session with the server. The \fBmonitor-cond\fR command uses RFC 7047
 154 extension "monitor_cond" method. See \fBovsdb\-server\fR(1) for details.
 155 .IP "\fBmonitor\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR] \fBALL\fR"
 156 Connects to \fIserver\fR and monitors the contents of all tables in
 157 \fIdatabase\fR.  Prints initial values and all kinds of changes to all
 158 columns in the database.  The \fB\-\-detach\fR option causes
 159 \fBovsdb\-client\fR to detach after it successfully receives and
 160 prints the initial database contents.
 161 .IP
 162 The \fBmonitor\fR command uses RFC 7047 "monitor" method to open a monitor
 163 session with the server.
 164 .
 165 .SH TESTING COMMANDS
 166 The following commands are mostly of interest for testing the correctness
 167 of the OVSDB server.
 168 .
 169 .IP "\fBovsdb\-client\fR [\fIoptions\fR] \fBlock\fI \fR[\fIserver\fR] \fIlock\fR"
 170 .IQ "\fBovsdb\-client\fR [\fIoptions\fR] \fBsteal\fI \fR[\fIserver\fR] \fIlock\fR"
 171 .IQ "\fBovsdb\-client\fR [\fIoptions\fR] \fBunlock\fI \fR[\fIserver\fR] \fIlock\fR"
 172 Connects to \fIserver\fR and issues corresponding RFC 7047 lock operations
 173 on \fIlock\fR. Prints json reply or subsequent update messages.
 174 The \fB\-\-detach\fR option causes \fBovsdb\-client\fR to detach after it
 175 successfully receives and prints the initial reply.
 176 .IP
 177 When running with the \fB\-\-detach\fR option, \fBlock\fR, \fBsteal\fR,
 178 \fBunlock\fR and \fBexit\fR commands can be issued by using
 179 \fBovs-appctl\fR. \fBexit\fR command causes the \fBovsdb\-client\fR to
 180 close its \fBovsdb\-server\fR connection before exit.
 181 The \fBlock\fR, \fBsteal\fR and \fBunlock\fR commands can be used to
 182 issue additional lock operations over the same \fBovsdb\-server\fR connection. All above commands take a single \fIlock\fR argument, which does not have
 183 to be the same as the \fIlock\fR that \fBovsdb\-client\fR started with.
 184 .
 185 .SH OPTIONS
 186 .SS "Output Formatting Options"
 187 Much of the output from \fBovsdb\-client\fR is in the form of tables.
 188 The following options controlling output formatting:
 189 .
 190 .ds TD (default)
 191 .so lib/table.man
 192 .
 193 .IP "\fB\-\-timestamp\fR"
 194 For the \fBmonitor\fR and \fBmonitor-cond\fR commands, add a timestamp to each
 195 table update.  Most output formats add the timestamp on a line of its own
 196 just above the table.  The JSON output format puts the timestamp in a
 197 member of the top-level JSON object named \fBtime\fR.
 198 .
 199 .SS "Daemon Options"
 200 The daemon options apply only to the \fBmonitor\fR and \fBmonitor-cond\fR commands.
 201 With any other command, they have no effect.
 202 .ds DD
 203 .so lib/daemon.man
 204 .SS "Logging Options"
 205 .so lib/vlog.man
 206 .SS "Public Key Infrastructure Options"
 207 .so lib/ssl.man
 208 .so lib/ssl-bootstrap.man
 209 .SS "SSL Connection Options"
 210 .so lib/ssl-connect.man
 211 .SS "Other Options"
 212 .so lib/common.man
 213 .SH "SEE ALSO"
 214 .
 215 \fBovsdb\-server\fR(1),
 216 \fBovsdb\-client\fR(1),
 217 and the OVSDB specification.