1ovsdb-client(1) Open vSwitch Manual ovsdb-client(1)
2
6 ovsdb-client - command-line interface to ovsdb-server(1)
7
9 ovsdb-client [options] list-dbs [server]
10 ovsdb-client [options] get-schema [server] [database]
11 ovsdb-client [options] get-schema-version [server] [database]
12 ovsdb-client [options] list-tables [server] [database]
13 ovsdb-client [options] list-columns [server] [database] [table]
14 ovsdb-client [options] transact [server] transaction
15 ovsdb-client [options] dump [server] [database]
16 ovsdb-client [options] monitor [server] [database] table [column[,col‐
17 umn]...]...
18 ovsdb-client help
19 Output formatting options:
21 [--format=format] [--data=format] [--no-heading] [--pretty]
22 [--bare] [--no-heading] [--timestamp]
23 Daemon options:
25 [--pidfile[=pidfile]] [--overwrite-pidfile] [--detach]
26 [--no-chdir]
27 Logging options:
29 [-v[module[:facility[:level]]]]...
30 [--verbose[=module[:facility[:level]]]]...
31 [--log-file[=file]]
32 Public key infrastructure options:
34 [--private-key=privkey.pem]
35 [--certificate=cert.pem]
36 [--ca-cert=cacert.pem]
37 [--bootstrap-ca-cert=cacert.pem]
38 Common options:
40 [-h | --help] [-V | --version]
41
44 The ovsdb-client program is a command-line client for interacting with
45 a running ovsdb-server process. Each command connects to an OVSDB
46 server, which is unix:/var/run/openvswitch/db.sock by default, or may
47 be specified as server in one of the following forms:
48 ssl:ip:port
50 The specified SSL port on the host at the given ip, which
51 must be expressed as an IP address (not a DNS name). The
52 --private-key, --certificate, and --ca-cert options are
53 mandatory when this form is used.
54 tcp:ip:port
56 Connect to the given TCP port on ip.
57 unix:file
59 Connect to the Unix domain server socket named file.
60 pssl:port[:ip]
62 Listen on the given SSL port for a connection. By
63 default, connections are not bound to a particular local
64 IP address, but specifying ip limits connections to those
65 from the given ip. The --private-key, --certificate, and
66 --ca-cert options are mandatory when this form is used.
67 ptcp:port[:ip]
69 Listen on the given TCP port for a connection. By
70 default, connections are not bound to a particular local
71 IP address, but ip may be specified to listen only for
72 connections to the given ip.
73 punix:file
75 Listen on the Unix domain server socket named file for a
76 connection.
77 The default database is Open_vSwitch.
79 Commands
81 The following commands are implemented:
82 list-dbs [server]
84 Connects to server, retrieves the list of known databases, and
85 prints them one per line. These database names are the ones
86 that may be used for database in the following commands.
87 get-schema [server] [database]
89 Connects to server, retrieves the schema for database, and
90 prints it in JSON format.
91 get-schema-version [server] [database]
93 Connects to server, retrieves the schema for database, and
94 prints its version number on stdout. A schema version number
95 has the form x.y.z. See ovs-vswitchd.conf.db(5) for details.
96 Schema version numbers and Open vSwitch version numbers are
98 independent.
99 If database was created before schema versioning was introduced,
101 then it will not have a version number and this command will
102 print a blank line.
103 list-tables [server] [database]
105 Connects to server, retrieves the schema for database, and
106 prints a table listing the name of each table within the data‐
107 base.
108 list-columns [server] [database] table
110 Connects to server, retrieves the schema for database, and
111 prints a table listing the name and type of each column. If ta‐
112 ble is specified, only columns in that table are listed; other‐
113 wise, the tables include columns in all tables.
114 transact [server] transaction
116 Connects to server, sends it the specified transaction, which
117 must be a JSON array containing one or more valid OVSDB opera‐
118 tions, and prints the received reply on stdout.
119 dump [server] [database]
121 Connects to server, retrieves all of the data in database, and
122 prints it on stdout as a series of tables.
123 monitor [server] [database] table [column[,column]...]...
125 Connects to server and monitors the contents of table in data‐
126 base. By default, the initial contents of table are printed,
127 followed by each change as it occurs. If at least one column is
128 specified, only those columns are monitored. The following col‐
129 umn names have special meanings:
130 !initial
132 Do not print the initial contents of the specified col‐
133 umns.
134 !insert
136 Do not print newly inserted rows.
137 !delete
139 Do not print deleted rows.
140 !modify
142 Do not print modifications to existing rows.
143 Multiple [column[,column]...] groups may be specified as sepa‐
145 rate arguments, e.g. to apply different reporting parameters to
146 each group. Whether multiple groups or only a single group is
147 specified, any given column may only be mentioned once on the
148 command line.
149 If --detach is used with monitor, then ovsdb-client detaches
151 after it has successfully received and printed the initial con‐
152 tents of table.
153
155 Output Formatting Options
156 Much of the output from ovsdb-client is in the form of tables. The
157 following options controlling output formatting:
158 -f format
160 --format=format
161 Sets the type of table formatting. The following types of for‐
162 mat are available:
163 table (default)
165 2-D text tables with aligned columns.
166 list A list with one column per line and rows separated by a
168 blank line.
169 html HTML tables.
171 csv Comma-separated values as defined in RFC 4180.
173 json JSON format as defined in RFC 4627. The output is a
175 sequence of JSON objects, each of which corresponds to
176 one table. Each JSON object has the following members
177 with the noted values:
178 caption
180 The table's caption. This member is omitted if
181 the table has no caption.
182 headings
184 An array with one element per table column. Each
185 array element is a string giving the corresponding
186 column's heading.
187 data An array with one element per table row. Each
189 element is also an array with one element per ta‐
190 ble column. The elements of this second-level
191 array are the cells that constitute the table.
192 Cells that represent OVSDB data or data types are
193 expressed in the format described in the OVSDB
194 specification; other cells are simply expressed as
195 text strings.
196 -d format
198 --data=format
199 Sets the formatting for cells within output tables. The follow‐
200 ing types of format are available:
201 string (default)
203 The simple format described in the Database Values sec‐
204 tion of ovs-vsctl(8).
205 bare The simple format with punctuation stripped off: [] and
207 {} are omitted around sets, maps, and empty columns,
208 items within sets and maps are space-separated, and
209 strings are never quoted. This format may be easier for
210 scripts to parse.
211 json JSON.
213 The json output format always outputs cells in JSON format,
215 ignoring this option.
216 --no-heading
218 This option suppresses the heading row that otherwise appears in
219 the first row of table output.
220 --pretty
222 By default, JSON in output is printed as compactly as possible.
223 This option causes JSON in output to be printed in a more read‐
224 able fashion. Members of objects and elements of arrays are
225 printed one per line, with indentation.
226 This option does not affect JSON in tables, which is always
228 printed compactly.
229 --bare Equivalent to --format=list --data=bare --no-headings.
231 --timestamp
233 For the monitor command, adds a timestamp to each table update.
234 Most output formats add the timestamp on a line of its own just
235 above the table. The JSON output format puts the timestamp in a
236 member of the top-level JSON object named time.
237 Daemon Options
239 The daemon options apply only to the monitor command. With any other
240 command, they have no effect.
241 --pidfile[=pidfile]
243 Causes a file (by default, ovsdb-client.pid) to be created indi‐
244 cating the PID of the running process. If the pidfile argument
245 is not specified, or if it does not begin with /, then it is
246 created in /var/run/openvswitch.
247 If --pidfile is not specified, no pidfile is created.
249 --overwrite-pidfile
251 By default, when --pidfile is specified and the specified pid‐
252 file already exists and is locked by a running process,
253 ovsdb-client refuses to start. Specify --overwrite-pidfile to
254 cause it to instead overwrite the pidfile.
255 When --pidfile is not specified, this option has no effect.
257 --detach
259 Causes ovsdb-client to detach itself from the foreground session
260 and run as a background process.
261 --monitor
263 Creates an additional process to monitor the ovsdb-client dae‐
264 mon. If the daemon dies due to a signal that indicates a pro‐
265 gramming error (e.g. SIGSEGV, SIGABRT), then the monitor process
266 starts a new copy of it. If the daemon die or exits for another
267 reason, the monitor process exits.
268 This option is normally used with --detach, but it also func‐
270 tions without it.
271 --no-chdir
273 By default, when --detach is specified, ovsdb-client changes its
274 current working directory to the root directory after it
275 detaches. Otherwise, invoking ovsdb-client from a carelessly
276 chosen directory would prevent the administrator from unmounting
277 the file system that holds that directory.
278 Specifying --no-chdir suppresses this behavior, preventing
280 ovsdb-client from changing its current working directory. This
281 may be useful for collecting core files, since it is common
282 behavior to write core dumps into the current working directory
283 and the root directory is not a good directory to use.
284 This option has no effect when --detach is not specified.
286 Logging Options
288 -v[spec]
289 --verbose=[spec]
290 Sets logging levels. Without any spec, sets the log level for
291 every module and facility to dbg. Otherwise, spec is a list of
292 words separated by spaces or commas or colons, up to one from
293 each category below:
294 · A valid module name, as displayed by the vlog/list com‐
296 mand on ovs-appctl(8), limits the log level change to the
297 specified module.
298 · syslog, console, or file, to limit the log level change
300 to only to the system log, to the console, or to a file,
301 respectively.
302 · off, emer, err, warn, info, or dbg, to control the log
304 level. Messages of the given severity or higher will be
305 logged, and messages of lower severity will be filtered
306 out. off filters out all messages. See ovs-appctl(8)
307 for a definition of each log level.
308 Case is not significant within spec.
310 Regardless of the log levels set for file, logging to a file
312 will not take place unless --log-file is also specified (see
313 below).
314 For compatibility with older versions of OVS, any is accepted as
316 a word but has no effect.
317 -v
319 --verbose
320 Sets the maximum logging verbosity level, equivalent to --ver‐
321 bose=dbg.
322 --log-file[=file]
324 Enables logging to a file. If file is specified, then it is
325 used as the exact name for the log file. The default log file
326 name used if file is omitted is /var/log/open‐
327 vswitch/ovsdb-client.log.
328 Public Key Infrastructure Options
330 -p privkey.pem
331 --private-key=privkey.pem
332 Specifies a PEM file containing the private key used as
333 ovsdb-client's identity for outgoing SSL connections.
334 -c cert.pem
336 --certificate=cert.pem
337 Specifies a PEM file containing a certificate that certifies the
338 private key specified on -p or --private-key to be trustworthy.
339 The certificate must be signed by the certificate authority (CA)
340 that the peer in SSL connections will use to verify it.
341 -C cacert.pem
343 --ca-cert=cacert.pem
344 Specifies a PEM file containing the CA certificate that
345 ovsdb-client should use to verify certificates presented to it
346 by SSL peers. (This may be the same certificate that SSL peers
347 use to verify the certificate specified on -c or --certificate,
348 or it may be a different one, depending on the PKI design in
349 use.)
350 -C none
352 --ca-cert=none
353 Disables verification of certificates presented by SSL peers.
354 This introduces a security risk, because it means that certifi‐
355 cates cannot be verified to be those of known trusted hosts.
356 --bootstrap-ca-cert=cacert.pem
358 When cacert.pem exists, this option has the same effect as -C or
359 --ca-cert. If it does not exist, then ovsdb-client will attempt
360 to obtain the CA certificate from the SSL peer on its first SSL
361 connection and save it to the named PEM file. If it is success‐
362 ful, it will immediately drop the connection and reconnect, and
363 from then on all SSL connections must be authenticated by a cer‐
364 tificate signed by the CA certificate thus obtained.
365 This option exposes the SSL connection to a man-in-the-middle
367 attack obtaining the initial CA certificate, but it may be use‐
368 ful for bootstrapping.
369 This option is only useful if the SSL peer sends its CA certifi‐
371 cate as part of the SSL certificate chain. The SSL protocol
372 does not require the server to send the CA certificate, but
373 ovsdb-server(8) can be configured to do so with the
374 --peer-ca-cert option.
375 This option is mutually exclusive with -C and --ca-cert.
377 Other Options
379 -h
380 --help Prints a brief help message to the console.
381 -V
383 --version
384 Prints version information to the console.
385
387 ovsdb-server(1), ovsdb-client(1), and the OVSDB specification.
388Open vSwitch 2.0.0 ovsdb-client(1)