ovsdb/ovsdb-client.1.in

   1 .\" -*- nroff -*-
   2 .so lib/ovs.tmac
   3 .TH ovsdb\-client 1 "@VERSION@" "Open vSwitch" "Open vSwitch Manual"
   4 .\" This program's name:
   5 .ds PN ovsdb\-client
   6 .
   7 .SH NAME
   8 ovsdb\-client \- command-line interface to \fBovsdb-server\fR(1)
   9 .
  10 .SH SYNOPSIS
  11 .IP "Server-Level Commands:"
  12 \fBovsdb\-client\fR [\fIoptions\fR] \fBlist\-dbs\fR [\fIserver\fR]
  13 .IP "Database Schema Commands:"
  14 \fBovsdb\-client\fR [\fIoptions\fR] \fBget\-schema\fR [\fIserver\fR] [\fIdatabase\fR]
  15 .br
  16 \fBovsdb\-client\fR [\fIoptions\fR] \fBlist\-tables\fR [\fIserver\fR] [\fIdatabase\fR]
  17 .br
  18 \fBovsdb\-client\fR [\fIoptions\fR] \fBlist\-columns\fR [\fIserver\fR] [\fIdatabase\fR] [\fItable\fR]
  19 .IP "Database Version Management Commands:"
  20 \fBovsdb\-client \fR[\fIoptions\fR] \fBconvert \fR[\fIserver\fR] \fIschema\fR
  21 .br
  22 \fBovsdb\-client \fR[\fIoptions\fR] \fBneeds\-conversion \fR[\fIserver\fR] \fIschema\fR
  23 .br
  24 \fBovsdb\-client\fR [\fIoptions\fR] \fBget\-schema\-version\fR [\fIserver\fR] [\fIdatabase\fR]
  25 .IP "Data Management Commands:"
  26 \fBovsdb\-client\fR [\fIoptions\fR] \fBtransact\fR [\fIserver\fR] \fItransaction\fR
  27 .br
  28 \fBovsdb\-client\fR [\fIoptions\fR] \fBquery\fR [\fIserver\fR] \fItransaction\fR
  29 .br
  30 \fBovsdb\-client\fR [\fIoptions\fR] \fBdump\fR [\fIserver\fR] [\fIdatabase\fR] [\fItable\fR
  31 [\fIcolumn\fR...]]
  32 .br
  33 \fBovsdb\-client\fR [\fIoptions\fR]
  34 \fBbackup\fR [\fIserver\fR] [\fIdatabase\fR] \fB> \fIsnapshot\fR
  35 .br
  36 \fBovsdb\-client\fR [\fIoptions\fR] [\fB\-\-force\fR]
  37 \fBrestore\fR [\fIserver\fR] [\fIdatabase\fR] \fB< \fIsnapshot\fR
  38 .br
  39 \fBovsdb\-client\fR [\fIoptions\fR] \fBmonitor\fR [\fIserver\fR] [\fIdatabase\fR] \fItable\fR
  40 [\fIcolumn\fR[\fB,\fIcolumn\fR]...]...
  41 .br
  42 \fBovsdb\-client\fR [\fIoptions\fR] \fBmonitor\fR [\fIserver\fR] [\fIdatabase\fR] \fBALL\fR
  43 .br
  44 \fBovsdb\-client\fR [\fIoptions\fR] \fBmonitor\-cond\fR [\fIserver\fR] [\fIdatabase\fR] \fIconditions
  45 \fItable\fR [\fIcolumn\fR[\fB,\fIcolumn\fR]...]...
  46 .br
  47 \fBovsdb\-client \fR[\fIoptions\fR] \fBwait\fR \fR[\fIserver\fR] \fIdatabase\fR \fIstate\fR
  48 .IP "Testing Commands:"
  49 \fBovsdb\-client\fR [\fIoptions\fR] \fBlock\fR [\fIserver\fR] \fIlock\fR
  50 .br
  51 \fBovsdb\-client\fR [\fIoptions\fR] \fBsteal\fR [\fIserver\fR] \fIlock\fR
  52 .br
  53 \fBovsdb\-client\fR [\fIoptions\fR] \fBunlock\fR [\fIserver\fR] \fIlock\fR
  54 .br
  55 .IP "Other Commands:"
  56 \fBovsdb\-client help\fR
  57 .IP "Cluster Options:"
  58 [\fB\-\-no\-leader\-only\fR]
  59 .IP "Output formatting options:"
  60 [\fB\-\-format=\fIformat\fR]
  61 [\fB\-\-data=\fIformat\fR]
  62 [\fB\-\-no-headings\fR]
  63 [\fB\-\-pretty\fR]
  64 [\fB\-\-bare\fR]
  65 [\fB\-\-timestamp\fR]
  66 .so lib/daemon-syn.man
  67 .so lib/vlog-syn.man
  68 .so lib/ssl-syn.man
  69 .so lib/ssl-bootstrap-syn.man
  70 .so lib/ssl-connect-syn.man
  71 .so lib/common-syn.man
  72 .
  73 .SH DESCRIPTION
  74 The \fBovsdb\-client\fR program is a command-line client for
  75 interacting with a running \fBovsdb\-server\fR process.
  76 Each command connects to the specified OVSDB \fIserver\fR, which may
  77 be an OVSDB active or passive connection method, as described in
  78 \fBovsdb\fR(7).  The default server is \fBunix:@RUNDIR@/db.sock\fR
  79 and
  80 the default \fIdatabase\fR is \fBOpen_vSwitch\fR.
  81 .PP
  82 \fBovsdb\-client\fR supports the
  83 \fImethod1\fB,\fImethod2\fB,\fR...\fB,\fImethodN\fR syntax described
  84 in \fBovsdb\fR(7) for connecting to a cluster.  When this syntax is
  85 used, \fBovsdb\-client\fR tries the cluster members in random order
  86 until it finds the cluster leader.  Specify the
  87 \fB\-\-no\-leader\-only\fR option to instead accept any server that is
  88 connected to the cluster.
  89 .PP
  90 For an introduction to OVSDB and its implementation in Open vSwitch,
  91 see \fBovsdb\fR(7).
  92 .PP
  93 The following sections describe the commands that \fBovsdb\-client\fR
  94 supports.
  95 .SS "Server-Level Commands"
  96 Most \fBovsdb\-client\fR commands work with an individual database,
  97 but these commands apply to an entire database server.
  98 .
  99 .IP "\fBlist\-dbs\fR [\fIserver\fR]"
 100 Connects to \fIserver\fR, retrieves the list of known databases, and
 101 prints them one per line.  These database names are the ones that
 102 other commands may use for \fIdatabase\fR.
 103 .
 104 .SS "Database Schema Commands"
 105 .PP
 106 These commands obtain the schema from a database and print it or part
 107 of it.
 108 .
 109 .IP "\fBget\-schema\fR [\fIserver\fR] [\fIdatabase\fR]"
 110 Connects to \fIserver\fR, retrieves the schema for \fIdatabase\fR, and
 111 prints it in JSON format.
 112 .
 113 .IP "\fBlist\-tables\fR [\fIserver\fR] [\fIdatabase\fR]"
 114 Connects to \fIserver\fR, retrieves the schema for \fIdatabase\fR, and
 115 prints a table listing the name of each table
 116 within the database.
 117 .
 118 .IP "\fBlist\-columns\fR [\fIserver\fR] [\fIdatabase\fR] \fItable\fR"
 119 Connects to \fIserver\fR, retrieves the schema for \fIdatabase\fR, and
 120 prints a table listing the name and type of each
 121 column.  If \fItable\fR is specified, only columns in that table are
 122 listed; otherwise, the tables include columns in all tables.
 123 .
 124 .SS "Database Version Management Commands"
 125 .so ovsdb/ovsdb-schemas.man
 126 .PP
 127 These commands work with different versions of OVSDB schemas and
 128 databases.
 129 .
 130 .IP "\fBconvert \fR[\fIserver\fR] \fIschema\fR"
 131 Reads an OVSDB schema in JSON format, as specified in the OVSDB
 132 specification, from \fIschema\fR, then connects to \fIserver\fR and
 133 requests the server to convert the database whose name is specified in
 134 \fIschema\fR to the schema also specified in \fIschema\fR.
 135 .IP
 136 The conversion is atomic, consistent, isolated, and durable.
 137 Following the schema change, the server notifies clients that use the
 138 \fBset_db_change_aware\fR RPC introduced in Open vSwitch 2.9 and
 139 cancels their outstanding transactions and monitors.  The server
 140 disconnects other clients, enabling them to notice the change when
 141 they reconnect.
 142 .IP
 143 This command can do simple ``upgrades'' and ``downgrades'' on a
 144 database's schema.  The data in the database must be valid when
 145 interpreted under \fIschema\fR, with only one exception: data for
 146 tables and columns that do not exist in \fIschema\fR are ignored.
 147 Columns that exist in \fIschema\fR but not in the database are set to
 148 their default values.  All of \fIschema\fR's constraints apply in
 149 full.
 150 .IP
 151 Some uses of this command can cause unrecoverable data loss.  For
 152 example, converting a database from a schema that has a given column
 153 or table to one that does not will delete all data in that column or
 154 table.  Back up critical databases before converting them.
 155 .IP
 156 This command works with clustered and standalone databases.
 157 Standalone databases may also be converted (offline) with
 158 \fBovsdb\-tool\fR's \fBconvert\fR command.
 159 .
 160 .IP "\fBneeds\-conversion \fR[\fIserver\fR] \fIschema\fR"
 161 Reads the schema from \fIschema\fR, then connects to \fIserver\fR and
 162 requests the schema from the database whose name is specified in
 163 \fIschema\fR.  If the two schemas are the same, prints \fBno\fR on
 164 stdout; if they differ, prints \fByes\fR.
 165 .
 166 .IP "\fBget\-schema\-version \fR[\fIserver\fR] [\fIdatabase\fR]"
 167 Connects to \fIserver\fR, retrieves the schema for \fIdatabase\fR, and
 168 prints its version number on stdout.
 169 If \fIdatabase\fR was created before schema versioning was introduced,
 170 then it will not have a version number and this command will print a
 171 blank line.
 172 .
 173 .IP "\fBget\-schema\-cksum\fR [\fIserver\fR] [\fIdatabase\fR]"
 174 Connects to \fIserver\fR, retrieves the schema for \fIdatabase\fR, and
 175 prints its checksum on stdout.  If \fIdatabase\fR does not include a
 176 checksum, prints a blank line.
 177 .
 178 .SS "Data Management Commands"
 179 .PP
 180 These commands read or modify the data in a database.
 181 .
 182 .IP "\fBtransact\fR [\fIserver\fR] \fItransaction\fR"
 183 Connects to \fIserver\fR, sends it the specified \fItransaction\fR,
 184 which must be a JSON array appropriate for use as the \fBparams\fR to
 185 a JSON-RPC \fBtransact\fR request, and prints the received reply on
 186 stdout.
 187 .
 188 .IP "\fBquery\fR [\fIserver\fR] \fItransaction\fR"
 189 This commands acts like a read-only version of \fBtransact\fR.
 190 It connects to \fIserver\fR, sends it the specified \fItransaction\fR,
 191 which must be a JSON array appropriate for use as the \fBparams\fR to
 192 a JSON-RPC \fBtransact\fR request, and prints the received reply on
 193 stdout.  To ensure that the transaction does not modify the database,
 194 this command appends an \fBabort\fR operation to the set of operations
 195 included in \fItransaction\fR before sending it to the database, and
 196 then removes the \fBabort\fR result from the reply (if it is present).
 197 .
 198 .IP "\fBdump\fR [\fIserver\fR] [\fIdatabase\fR] [\fItable\fR [\fIcolumn\fR...]]"
 199 Connects to \fIserver\fR, retrieves all of the data in \fIdatabase\fR,
 200 and prints it on stdout as a series of tables. If \fItable\fR is
 201 specified, only that table is retrieved.  If at least one \fIcolumn\fR
 202 is specified, only those columns are retrieved.
 203 .
 204 .IP "\fBbackup\fR [\fIserver\fR] [\fIdatabase\fR] \fB> \fIsnapshot\fR"
 205 Connects to \fIserver\fR, retrieves a snapshot of the schema and data
 206 in \fIdatabase\fR, and prints it on stdout in the format used for
 207 OVSDB standalone and active-backup databases.  This is an appropriate
 208 way to back up any remote database.  The database snapshot that it
 209 outputs is suitable to be served up directly by \fBovsdb\-server\fR or
 210 used as the input to \fBovsdb\-client restore\fR.
 211 .IP
 212 Another way to back up a standalone or active-backup database is to
 213 copy its database file, e.g. with \fBcp\fR.  This is safe even if the
 214 database is in use.
 215 .IP
 216 The output does not include ephemeral columns, which by design do not
 217 survive across restarts of \fBovsdb\-server\fR.
 218 .
 219 .IP "[\fB\-\-force\fR] \fBrestore\fR [\fIserver\fR] [\fIdatabase\fR] \fB< \fIsnapshot\fR"
 220 Reads \fIsnapshot\fR, which must be a OVSDB standalone or
 221 active-backup database (possibly but not necessarily created by
 222 \fBovsdb\-client backup).  Then, connects to \fIserver\fR, verifies
 223 that \fIdatabase\fR and \fIsnapshot\fR have the same schema, then
 224 deletes all of the data in \fIdatabase\fR and replaces it by
 225 \fIsnapshot\fR.  The replacement happens atomically, in a single
 226 transaction.
 227 .IP
 228 UUIDs for rows in the restored database will differ from those in
 229 \fIsnapshot\fR, because the OVSDB protocol does not allow clients to
 230 specify row UUIDs.  Another way to restore a standalone or active-backup
 231 database, which does also restore row UUIDs, is to stop
 232 the server or servers, replace the database file by the snapshot, then
 233 restart the database.  Either way, ephemeral columns are not restored,
 234 since by design they do not survive across restarts of
 235 \fBovsdb\-server\fR.
 236 .IP
 237 Normally \fBrestore\fR exits with a failure if \fBsnapshot\fR and the
 238 server's database have different schemas.  In such a case, it is a
 239 good idea to convert the database to the new schema before restoring,
 240 e.g. with \fBovsdb\-client convert\fR.  Use \fB\-\-force\fR to proceed
 241 regardless of schema differences even though the restore might fail
 242 with an error or succeed with surprising results.
 243 .
 244 .IP "\fBmonitor\fR [\fIserver\fR] [\fIdatabase\fR] \fItable\fR [\fIcolumn\fR[\fB,\fIcolumn\fR]...]..."
 245 .IQ "\fBmonitor\-cond\fR [\fIserver\fR] [\fIdatabase\fR] \fIconditions\fR \fItable\fR [\fIcolumn\fR[\fB,\fIcolumn\fR]...]..."
 246 Connects to \fIserver\fR and monitors the contents of rows that match conditions in
 247 \fItable\fR in \fIdatabase\fR. By default, the initial contents of \fItable\fR are
 248 printed, followed by each change as it occurs.  If conditions empty,
 249 all rows will be monitored. If at least one \fIcolumn\fR is specified, only those
 250 columns are monitored.  The following \fIcolumn\fR names have special meanings:
 251 .RS
 252 .IP "\fB!initial\fR"
 253 Do not print the initial contents of the specified columns.
 254 .IP "\fB!insert\fR"
 255 Do not print newly inserted rows.
 256 .IP "\fB!delete\fR"
 257 Do not print deleted rows.
 258 .IP "\fB!modify\fR"
 259 Do not print modifications to existing rows.
 260 .RE
 261 .IP
 262 Multiple [\fIcolumn\fR[\fB,\fIcolumn\fR]...] groups may be specified
 263 as separate arguments, e.g. to apply different reporting parameters to
 264 each group.  Whether multiple groups or only a single group is
 265 specified, any given column may only be mentioned once on the command
 266 line.
 267 .IP
 268 \fBconditions\fR is a JSON array of <condition> as defined in RFC 7047 5.1
 269 with the following change: A condition can be either a 3-element JSON array
 270 as deescribed in the RFC or a boolean value..
 271 .IP
 272 If \fB\-\-detach\fR is used with \fBmonitor\fR or \fBmonitor\-cond\fR, then
 273 \fBovsdb\-client\fR detaches after it has successfully received and
 274 printed the initial contents of \fItable\fR.
 275 .IP
 276 The \fBmonitor\fR command uses RFC 7047 "monitor" method to open a monitor
 277 session with the server. The \fBmonitor\-cond\fR command uses RFC 7047
 278 extension "monitor_cond" method. See \fBovsdb\-server\fR(1) for details.
 279 .IP "\fBmonitor\fI \fR[\fIserver\fR] \fR[\fIdatabase\fR] \fBALL\fR"
 280 Connects to \fIserver\fR and monitors the contents of all tables in
 281 \fIdatabase\fR.  Prints initial values and all kinds of changes to all
 282 columns in the database.  The \fB\-\-detach\fR option causes
 283 \fBovsdb\-client\fR to detach after it successfully receives and
 284 prints the initial database contents.
 285 .IP
 286 The \fBmonitor\fR command uses RFC 7047 "monitor" method to open a monitor
 287 session with the server.
 288 .
 289 .IP "\fBwait\fR \fR[\fIserver\fR] \fIdatabase state\fR"
 290 Waits for \fIdatabase\fR on \fIserver\fR to enter a desired \fIstate\fR,
 291 which may be one of:
 292 .RS
 293 .IP "\fBadded\fR"
 294 Waits until a database with the given name has been added to
 295 \fIserver\fR.
 296 .IP "\fBconnected\fR"
 297 Waits until a database with the given name has been added to
 298 \fIserver\fR.  Then, if \fIdatabase\fR is clustered, additionally
 299 waits until it has joined and connected to its cluster.
 300 .IP "\fBremoved\fR"
 301 Waits until \fIdatabase\fR has been removed from the database server.
 302 This can also be used to wait for a database to complete leaving its
 303 cluster, because \fBovsdb\-server\fR removes a database at that point.
 304 .RE
 305 .IP
 306 \fIdatabase\fR is mandatory for this command because it is often used
 307 to check for databases that have not yet been added to the server, so
 308 that the \fBovsdb\-client\fR semantics of acting on a default database
 309 do not work.
 310 .IP
 311 This command acts on a particular database server, not on a cluster,
 312 so \fIserver\fR must name a single server, not a comma-delimited list
 313 of servers.
 314 .SS "Testing commands"
 315 These commands are mostly of interest for testing the correctness
 316 of the OVSDB server.
 317 .
 318 .IP "\fBlock\fR [\fIserver\fR] \fIlock\fR"
 319 .IQ "\fBsteal\fR [\fIserver\fR] \fIlock\fR"
 320 .IQ "\fBunlock\fR [\fIserver\fR] \fIlock\fR"
 321 Connects to \fIserver\fR and issues corresponding RFC 7047 lock operations
 322 on \fIlock\fR. Prints json reply or subsequent update messages.
 323 The \fB\-\-detach\fR option causes \fBovsdb\-client\fR to detach after it
 324 successfully receives and prints the initial reply.
 325 .IP
 326 When running with the \fB\-\-detach\fR option, \fBlock\fR, \fBsteal\fR,
 327 \fBunlock\fR and \fBexit\fR commands can be issued by using
 328 \fBovs-appctl\fR. \fBexit\fR command causes the \fBovsdb\-client\fR to
 329 close its \fBovsdb\-server\fR connection before exit.
 330 The \fBlock\fR, \fBsteal\fR and \fBunlock\fR commands can be used to
 331 issue additional lock operations over the same \fBovsdb\-server\fR connection. All above commands take a single \fIlock\fR argument, which does not have
 332 to be the same as the \fIlock\fR that \fBovsdb\-client\fR started with.
 333 .
 334 .SH OPTIONS
 335 .SS "Output Formatting Options"
 336 Much of the output from \fBovsdb\-client\fR is in the form of tables.
 337 The following options controlling output formatting:
 338 .
 339 .ds TD (default)
 340 .so lib/table.man
 341 .
 342 .IP "\fB\-\-timestamp\fR"
 343 For the \fBmonitor\fR and \fBmonitor\-cond\fR commands, add a timestamp to each
 344 table update.  Most output formats add the timestamp on a line of its own
 345 just above the table.  The JSON output format puts the timestamp in a
 346 member of the top-level JSON object named \fBtime\fR.
 347 .
 348 .IP "\fB\-t\fR"
 349 .IQ "\fB\-\-timeout=\fIsecs\fR"
 350 Limits \fBovsdb\-client\fR runtime to approximately \fIsecs\fR
 351 seconds.  If the timeout expires, \fBovsdb\-client\fR will exit with a
 352 \fBSIGALRM\fR signal.
 353 .
 354 .SS "Daemon Options"
 355 The daemon options apply only to the \fBmonitor\fR and \fBmonitor\-cond\fR commands.
 356 With any other command, they have no effect.
 357 .ds DD
 358 .so lib/daemon.man
 359 .SS "Logging Options"
 360 .so lib/vlog.man
 361 .SS "Public Key Infrastructure Options"
 362 .so lib/ssl.man
 363 .so lib/ssl-bootstrap.man
 364 .SS "SSL Connection Options"
 365 .so lib/ssl-connect.man
 366 .SS "Other Options"
 367 .so lib/common.man
 368 .SH "SEE ALSO"
 369 .
 370 \fBovsdb\fR(7),
 371 \fBovsdb\-server\fR(1),
 372 \fBovsdb\-client\fR(1).