1ovsdb-server(1) Open vSwitch Manual ovsdb-server(1)
2
6 ovsdb-server - Open vSwitch database server
7
9 ovsdb-server [database]... [--remote=remote]... [--run=command]
10 Daemon options:
12 [--pidfile[=pidfile]] [--overwrite-pidfile] [--detach]
13 [--no-chdir]
14 Logging options:
16 [-v[module[:facility[:level]]]]...
17 [--verbose[=module[:facility[:level]]]]...
18 [--log-file[=file]]
19 Public key infrastructure options:
21 [--private-key=privkey.pem]
22 [--certificate=cert.pem]
23 [--ca-cert=cacert.pem]
24 [--bootstrap-ca-cert=cacert.pem]
25 Runtime management options:
27 --unixctl=socket
28 Common options:
30 [-h | --help] [-V | --version]
31
34 The ovsdb-server program provides RPC interfaces to one or more Open
35 vSwitch databases (OVSDBs). It supports JSON-RPC client connections
36 over active or passive TCP/IP or Unix domain sockets.
37 Each OVSDB file may be specified on the command line as database. If
39 none is specified, the default is /etc/openvswitch/conf.db. The data‐
40 base files must already have been created and initialized using, for
41 example, ovsdb-tool create.
42
44 --remote=remote
45 Adds remote as a connection method used by ovsdb-server. remote
46 must take one of the following forms:
47 pssl:port[:ip]
49 Listen on the given SSL port for a connection. By
50 default, connections are not bound to a particular local
51 IP address, but specifying ip limits connections to those
52 from the given ip. The --private-key, --certificate, and
53 --ca-cert options are mandatory when this form is used.
54 ptcp:port[:ip]
56 Listen on the given TCP port for a connection. By
57 default, connections are not bound to a particular local
58 IP address, but ip may be specified to listen only for
59 connections to the given ip.
60 punix:file
62 Listen on the Unix domain server socket named file for a
63 connection.
64 ssl:ip:port
66 The specified SSL port on the host at the given ip, which
67 must be expressed as an IP address (not a DNS name). The
68 --private-key, --certificate, and --ca-cert options are
69 mandatory when this form is used.
70 tcp:ip:port
72 Connect to the given TCP port on ip.
73 unix:file
75 Connect to the Unix domain server socket named file.
76 db:db,table,column
78 Reads additional connection methods from column in all of
79 the rows in table within db. As the contents of column
80 changes, ovsdb-server also adds and drops connection
81 methods accordingly.
82 If column's type is string or set of strings, then the
84 connection methods are taken directly from the column.
85 The connection methods in the column must have one of the
86 forms described above.
87 If column's type is UUID or set of UUIDs and references a
89 table, then each UUID is looked up in the referenced ta‐
90 ble to obtain a row. The following columns in the row,
91 if present and of the correct type, configure a connec‐
92 tion method. Any additional columns are ignored.
93 target (string)
95 Connection method, in one of the forms described
96 above. This column is mandatory: if it is missing
97 or empty then no connection method can be config‐
98 ured.
99 max_backoff (integer)
101 Maximum number of milliseconds to wait between
102 connection attempts.
103 inactivity_probe (integer)
105 Maximum number of milliseconds of idle time on
106 connection to client before sending an inactivity
107 probe message.
108 It is an error for column to have another type.
110 --run=command]
112 Ordinarily ovsdb-server runs forever, or until it is told to
113 exit (see RUNTIME MANAGEMENT COMMANDS below). With this option,
114 ovsdb-server instead starts a shell subprocess running command.
115 When the subprocess terminates, ovsdb-server also exits grace‐
116 fully. If the subprocess exits normally with exit code 0, then
117 ovsdb-server exits with exit code 0 also; otherwise, it exits
118 with exit code 1.
119 This option can be useful where a database server is needed only
121 to run a single command, e.g.: ovsdb-server
122 --remote=punix:socket --run='ovsdb-client dump unix:socket
123 Open_vSwitch'
124 Daemon Options
126 --pidfile[=pidfile]
127 Causes a file (by default, ovsdb-server.pid) to be created indi‐
128 cating the PID of the running process. If the pidfile argument
129 is not specified, or if it does not begin with /, then it is
130 created in /var/run/openvswitch.
131 If --pidfile is not specified, no pidfile is created.
133 --overwrite-pidfile
135 By default, when --pidfile is specified and the specified pid‐
136 file already exists and is locked by a running process,
137 ovsdb-server refuses to start. Specify --overwrite-pidfile to
138 cause it to instead overwrite the pidfile.
139 When --pidfile is not specified, this option has no effect.
141 --detach
143 Causes ovsdb-server to detach itself from the foreground session
144 and run as a background process. ovsdb-server detaches only
145 after it starts listening on all configured remotes.
146 --monitor
148 Creates an additional process to monitor the ovsdb-server dae‐
149 mon. If the daemon dies due to a signal that indicates a pro‐
150 gramming error (e.g. SIGSEGV, SIGABRT), then the monitor process
151 starts a new copy of it. If the daemon die or exits for another
152 reason, the monitor process exits.
153 This option is normally used with --detach, but it also func‐
155 tions without it.
156 --no-chdir
158 By default, when --detach is specified, ovsdb-server changes its
159 current working directory to the root directory after it
160 detaches. Otherwise, invoking ovsdb-server from a carelessly
161 chosen directory would prevent the administrator from unmounting
162 the file system that holds that directory.
163 Specifying --no-chdir suppresses this behavior, preventing
165 ovsdb-server from changing its current working directory. This
166 may be useful for collecting core files, since it is common
167 behavior to write core dumps into the current working directory
168 and the root directory is not a good directory to use.
169 This option has no effect when --detach is not specified.
171 Logging Options
173 -v[spec]
174 --verbose=[spec]
175 Sets logging levels. Without any spec, sets the log level for
176 every module and facility to dbg. Otherwise, spec is a list of
177 words separated by spaces or commas or colons, up to one from
178 each category below:
179 · A valid module name, as displayed by the vlog/list com‐
181 mand on ovs-appctl(8), limits the log level change to the
182 specified module.
183 · syslog, console, or file, to limit the log level change
185 to only to the system log, to the console, or to a file,
186 respectively.
187 · off, emer, err, warn, info, or dbg, to control the log
189 level. Messages of the given severity or higher will be
190 logged, and messages of lower severity will be filtered
191 out. off filters out all messages. See ovs-appctl(8)
192 for a definition of each log level.
193 Case is not significant within spec.
195 Regardless of the log levels set for file, logging to a file
197 will not take place unless --log-file is also specified (see
198 below).
199 For compatibility with older versions of OVS, any is accepted as
201 a word but has no effect.
202 -v
204 --verbose
205 Sets the maximum logging verbosity level, equivalent to --ver‐
206 bose=dbg.
207 --log-file[=file]
209 Enables logging to a file. If file is specified, then it is
210 used as the exact name for the log file. The default log file
211 name used if file is omitted is /var/log/open‐
212 vswitch/ovsdb-server.log.
213 Public Key Infrastructure Options
215 The options described below for configuring the SSL public key infra‐
216 structure accept a special syntax for obtaining their configuration
217 from the database. If any of these options is given db:db,table,column
218 as its argument, then the actual file name is read from the specified
219 column in table within the db database. The column must have type
220 string or set of strings. The first nonempty string in the table is
221 taken as the file name. (This means that ordinarily there should be at
222 most one row in table.)
223 -p privkey.pem
225 --private-key=privkey.pem
226 Specifies a PEM file containing the private key used as
227 ovsdb-server's identity for outgoing SSL connections.
228 -c cert.pem
230 --certificate=cert.pem
231 Specifies a PEM file containing a certificate that certifies the
232 private key specified on -p or --private-key to be trustworthy.
233 The certificate must be signed by the certificate authority (CA)
234 that the peer in SSL connections will use to verify it.
235 -C cacert.pem
237 --ca-cert=cacert.pem
238 Specifies a PEM file containing the CA certificate that
239 ovsdb-server should use to verify certificates presented to it
240 by SSL peers. (This may be the same certificate that SSL peers
241 use to verify the certificate specified on -c or --certificate,
242 or it may be a different one, depending on the PKI design in
243 use.)
244 -C none
246 --ca-cert=none
247 Disables verification of certificates presented by SSL peers.
248 This introduces a security risk, because it means that certifi‐
249 cates cannot be verified to be those of known trusted hosts.
250 --bootstrap-ca-cert=cacert.pem
252 When cacert.pem exists, this option has the same effect as -C or
253 --ca-cert. If it does not exist, then ovsdb-server will attempt
254 to obtain the CA certificate from the SSL peer on its first SSL
255 connection and save it to the named PEM file. If it is success‐
256 ful, it will immediately drop the connection and reconnect, and
257 from then on all SSL connections must be authenticated by a cer‐
258 tificate signed by the CA certificate thus obtained.
259 This option exposes the SSL connection to a man-in-the-middle
261 attack obtaining the initial CA certificate, but it may be use‐
262 ful for bootstrapping.
263 This option is only useful if the SSL peer sends its CA certifi‐
265 cate as part of the SSL certificate chain. The SSL protocol
266 does not require the server to send the CA certificate, but
267 ovsdb-client(8) can be configured to do so with the
268 --peer-ca-cert option.
269 This option is mutually exclusive with -C and --ca-cert.
271 Other Options
273 --unixctl=socket
274 Sets the name of the control socket on which ovsdb-server lis‐
275 tens for runtime management commands (see RUNTIME MANAGEMENT
276 COMMANDS, below). If socket does not begin with /, it is inter‐
277 preted as relative to /var/run/openvswitch. If --unixctl is not
278 used at all, the default socket is /var/run/open‐
279 vswitch/ovsdb-server.pid.ctl, where pid is ovsdb-server's
280 process ID. Specifying none for socket disables the control
281 socket feature.
282 -h
284 --help Prints a brief help message to the console.
285 -V
287 --version
288 Prints version information to the console.
289
291 ovs-appctl(8) can send commands to a running ovsdb-server process. The
292 currently supported commands are described below.
293 OVSDB-SERVER COMMANDS
295 These commands are specific to ovsdb-server.
296 exit Causes ovsdb-server to gracefully terminate.
298 ovsdb-server/compact [db]...
300 Compacts each database db in-place. If no db is specified, com‐
301 pacts every database in-place. Databases are also automatically
302 compacted occasionally.
303 ovsdb-server/reconnect
305 Makes ovsdb-server drop all of the JSON-RPC connections to data‐
306 base clients and reconnect.
307 This command might be useful for debugging issues with database
309 clients.
310 ovsdb-server/add-remote remote
312 Adds a remote, as if --remote=remote had been specified on the
313 ovsdb-server command line. (If remote is already a remote, this
314 command succeeds without changing the configuration.)
315 ovsdb-server/remove-remote remote
317 Removes the specified remote from the configuration, failing
318 with an error if remote is not configured as a remote. This
319 command only works with remotes that were named on --remote or
320 ovsdb-server/add-remote, that is, it will not remove remotes
321 added indirectly because they were read from the database by
322 configuring a db:db,table,column remote. (You can remove a
323 database source with ovsdb-server/remove-remote db:db,table,col‐
324 umn, but not individual remotes found indirectly through the
325 database.)
326 ovsdb-server/list-remotes
328 Outputs a list of the currently configured remotes named on
329 --remote or ovsdb-server/add-remote, that is, it does not list
330 remotes added indirectly because they were read from the data‐
331 base by configuring a db:db,table,column remote.
332 ovsdb-server/add-db database
334 Adds the database to the running ovsdb-server. The database
335 file must already have been created and initialized using, for
336 example, ovsdb-tool create.
337 ovsdb-server/remove-db database
339 Removes database from the running ovsdb-server. database must
340 be a database name as listed by ovsdb-server/list-dbs.
341 If a remote has been configured that points to the specified
343 database (e.g. --remote=db:database,... on the command line),
344 then it will be disabled until another database with the same
345 name is added again (with ovsdb-server/add-db).
346 Any public key infrastructure options specified through this
348 database (e.g. --private-key=db:database,... on the command
349 line) will be disabled until another database with the same name
350 is added again (with ovsdb-server/add-db).
351 ovsdb-server/list-dbs
353 Outputs a list of the currently configured databases added
354 either through the command line or through the
355 ovsdb-server/add-db command.
356 VLOG COMMANDS
358 These commands manage ovsdb-server's logging settings.
359 vlog/set [spec]
361 Sets logging levels. Without any spec, sets the log level for
362 every module and facility to dbg. Otherwise, spec is a list of
363 words separated by spaces or commas or colons, up to one from
364 each category below:
365 · A valid module name, as displayed by the vlog/list com‐
367 mand on ovs-appctl(8), limits the log level change to the
368 specified module.
369 · syslog, console, or file, to limit the log level change
371 to only to the system log, to the console, or to a file,
372 respectively.
373 · off, emer, err, warn, info, or dbg, to control the log
375 level. Messages of the given severity or higher will be
376 logged, and messages of lower severity will be filtered
377 out. off filters out all messages. See ovs-appctl(8)
378 for a definition of each log level.
379 Case is not significant within spec.
381 Regardless of the log levels set for file, logging to a file
383 will not take place unless ovsdb-server was invoked with the
384 --log-file option.
385 For compatibility with older versions of OVS, any is accepted as
387 a word but has no effect.
388 vlog/set PATTERN:facility:pattern
390 Sets the log pattern for facility to pattern. Refer to
391 ovs-appctl(8) for a description of the valid syntax for pattern.
392 vlog/list
394 Lists the supported logging modules and their current levels.
395 vlog/reopen
397 Causes ovsdb-server to close and reopen its log file. (This is
398 useful after rotating log files, to cause a new log file to be
399 used.)
400 This has no effect unless ovsdb-server was invoked with the
402 --log-file option.
403 vlog/disable-rate-limit [module]...
405 vlog/enable-rate-limit [module]...
406 By default, ovsdb-server limits the rate at which certain mes‐
407 sages can be logged. When a message would appear more fre‐
408 quently than the limit, it is suppressed. This saves disk
409 space, makes logs easier to read, and speeds up execution, but
410 occasionally troubleshooting requires more detail. Therefore,
411 vlog/disable-rate-limit allows rate limits to be disabled at the
412 level of an individual log module. Specify one or more module
413 names, as displayed by the vlog/list command. Specifying either
414 no module names at all or the keyword any disables rate limits
415 for every log module.
416 The vlog/enable-rate-limit command, whose syntax is the same as
418 vlog/disable-rate-limit, can be used to re-enable a rate limit
419 that was previously disabled.
420 MEMORY COMMANDS
422 These commands report memory usage.
423 memory/show
425 Displays some basic statistics about ovsdb-server's memory
426 usage. ovsdb-server also logs this information soon after
427 startup and periodically as its memory consumption grows.
428 COVERAGE COMMANDS
430 These commands manage ovsdb-server's ``coverage counters,'' which count
431 the number of times particular events occur during a daemon's runtime.
432 In addition to these commands, ovsdb-server automatically logs coverage
433 counter values, at INFO level, when it detects that the daemon's main
434 loop takes unusually long to run.
435 Coverage counters are useful mainly for performance analysis and debug‐
437 ging.
438 coverage/show
440 Displays the values of all of the coverage counters.
441
443 ovsdb-tool(1).
444Open vSwitch 2.0.0 ovsdb-server(1)