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