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