]> git.proxmox.com Git - mirror_ovs.git/blame - ovsdb/ovsdb-server.1.in
raft: Avoid sending equal snapshots.
[mirror_ovs.git] / ovsdb / ovsdb-server.1.in
CommitLineData
f7f62235 1.\" -*- nroff -*-
9bccc3ff 2.so lib/ovs.tmac
d2cb6c95 3.TH ovsdb\-server 1 "@VERSION@" "Open vSwitch" "Open vSwitch Manual"
a946ed39 4.\" This program's name:
f7f62235
BP
5.ds PN ovsdb\-server
6.
7.SH NAME
8ovsdb\-server \- Open vSwitch database server
9.
10.SH SYNOPSIS
11\fBovsdb\-server\fR
b4e8d170 12[\fIdatabase\fR]\&...
a946ed39
BP
13[\fB\-\-remote=\fIremote\fR]\&...
14[\fB\-\-run=\fIcommand\fR]
15.so lib/daemon-syn.man
42dd41ef 16.so lib/service-syn.man
a946ed39 17.so lib/vlog-syn.man
12b84d50
BP
18.IP "Active-backup options:"
19[\fB\-\-sync\-from=\fIserver\fR]
20[\fB\-\-sync\-exclude-tables=\fIdb\fB:\fItable\fR[\fB,\fIdb\fB:\fItable\fR]...\fR]
21[\fB\-\-active\fR]
812560d7
BP
22.so lib/ssl-syn.man
23.so lib/ssl-bootstrap-syn.man
5bf6cbd6 24.so lib/ssl-peer-ca-cert-syn.man
e18a1d08 25.so lib/ssl-connect-syn.man
a946ed39
BP
26.so lib/unixctl-syn.man
27.so lib/common-syn.man
f7f62235
BP
28.
29.SH DESCRIPTION
b4e8d170
BP
30The \fBovsdb\-server\fR program provides RPC interfaces to one or more
31Open vSwitch databases (OVSDBs). It supports JSON-RPC client
32connections over active or passive TCP/IP or Unix domain sockets.
12b84d50
BP
33For an introduction to OVSDB and its implementation in Open vSwitch,
34see \fBovsdb\fR(7).
f7f62235 35.PP
b4e8d170
BP
36Each OVSDB file may be specified on the command line as \fIdatabase\fR.
37If none is specified, the default is \fB@DBDIR@/conf.db\fR. The database
38files must already have been created and initialized using, for
1b1d2e6d
BP
39example, \fBovsdb\-tool\fR's \fBcreate\fR, \fBcreate\-cluster\fR, or
40\fBjoin\-cluster\fR command.
e51879e9 41.PP
1b1d2e6d
BP
42This OVSDB implementation supports standalone, active-backup, and
43clustered database service models, as well as database replication.
12b84d50 44See the Service Models section of \fBovsdb\fR(7) for more information.
6bb9b060 45.PP
1b1d2e6d
BP
46For clustered databases, when the \fB\-\-detach\fR option is used,
47\fBovsdb\-server\fR detaches without waiting for the server to
48successfully join a cluster (if the database file is freshly created
49with \fBovsdb\-tool join\-cluster\fR) or connect to a cluster that it
50has already joined. Use \fBovsdb\-client wait\fR (see
51\fBovsdb\-client\fR(1)) to wait until the server has successfully
52joined and connected to a cluster.
53.PP
6bb9b060
BP
54In addition to user-specified databases, \fBovsdb\-server\fR version
552.9 and later also always hosts a built-in database named
56\fB_Server\fR. Please see \fBovsdb\-server\fR(5) for documentation on
57this database's schema.
58.
f7f62235
BP
59.SH OPTIONS
60.
0b1fae1b
BP
61.IP "\fB\-\-remote=\fIremote\fR"
62Adds \fIremote\fR as a connection method used by \fBovsdb\-server\fR.
12b84d50
BP
63The \fIremote\fR may be an OVSDB active or passive connection method,
64e.g. \fBpssl:6640\fR, as described in \fBovsdb\fR(7). The following
65additional form is also supported:
f7f62235
BP
66.
67.RS
fb6de52c 68.IP "\fBdb:\fIdb\fB,\fItable\fB,\fIcolumn\fR"
a976b2ec 69Reads additional connection methods from \fIcolumn\fR in all of the
fb6de52c
GS
70rows in \fItable\fR within \fIdb\fR. As the contents of \fIcolumn\fR changes,
71\fBovsdb\-server\fR also adds and drops connection methods accordingly.
94db5407
BP
72.IP
73If \fIcolumn\fR's type is string or set of strings, then the
74connection methods are taken directly from the column. The connection
75methods in the column must have one of the forms described above.
76.IP
77If \fIcolumn\fR's type is UUID or set of UUIDs and references a table,
78then each UUID is looked up in the referenced table to obtain a row.
79The following columns in the row, if present and of the correct type,
80configure a connection method. Any additional columns are ignored.
81.RS
82.IP "\fBtarget\fR (string)"
83Connection method, in one of the forms described above. This column
84is mandatory: if it is missing or empty then no connection method can
85be configured.
86.IP "\fBmax_backoff\fR (integer)"
87Maximum number of milliseconds to wait between connection attempts.
b4e8d170 88.IP "\fBinactivity_probe\fR (integer)"
94db5407
BP
89Maximum number of milliseconds of idle time on connection to
90client before sending an inactivity probe message.
9c1a1182
LR
91.IP "\fBread_only\fR (boolean)"
92If true, only read-only transactions are allowed on this connection.
94db5407
BP
93.RE
94.IP
95It is an error for \fIcolumn\fR to have another type.
f7f62235
BP
96.RE
97.
9f33227d
BP
98.IP
99To connect or listen on multiple connection methods, use multiple
100\fB\-\-remote\fR options.
101.
475afa1b
BP
102.IP "\fB\-\-run=\fIcommand\fR]"
103Ordinarily \fBovsdb\-server\fR runs forever, or until it is told to
104exit (see \fBRUNTIME MANAGEMENT COMMANDS\fR below). With this option,
105\fBovsdb\-server\fR instead starts a shell subprocess running
106\fIcommand\fR. When the subprocess terminates, \fBovsdb\-server\fR
107also exits gracefully. If the subprocess exits normally with exit
108code 0, then \fBovsdb\-server\fR exits with exit code 0 also;
109otherwise, it exits with exit code 1.
110.IP
111This option can be useful where a database server is needed only to
112run a single command, e.g.:
4e312e69 113.B "ovsdb\-server \-\-remote=punix:socket \-\-run='ovsdb\-client dump unix:socket Open_vSwitch'"
41064650
GS
114.IP
115This option is not supported on Windows platform.
f7f62235 116.SS "Daemon Options"
a7ff9bd7
BP
117.ds DD \
118\fBovsdb\-server\fR detaches only after it starts listening on all \
1b1d2e6d
BP
119configured remotes. At this point, all standalone and active-backup \
120databases are ready for use. Clustered databases only become ready \
121for use after they finish joining their clusters (which could have \
122already happened in previous runs of \fBovsdb\-server\fR).
f7f62235 123.so lib/daemon.man
42dd41ef
GS
124.SS "Service Options"
125.so lib/service.man
f7f62235
BP
126.SS "Logging Options"
127.so lib/vlog.man
12b84d50
BP
128.SS "Active-Backup Options"
129These options support the \fBovsdb\-server\fR active-backup service
1b1d2e6d
BP
130model and database replication. These options apply only to databases
131in the format used for standalone and active-backup databases, which
132is the database format created by \fBovsdb\-tool create\fR. By
12b84d50
BP
133default, when it serves a database in this format, \fBovsdb\-server\fR
134runs as a standalone server. These options can configure it for
135active-backup use:
136.IP \(bu
137Use \fB\-\-sync\-from=\fIserver\fR to start the server in the backup
138role, replicating data from \fIserver\fR. When \fBovsdb\-server\fR is
139running as a backup server, it rejects all transactions that can
140modify the database content, including lock commands. The same form
141can be used to configure the local database as a replica of
142\fIserver\fR.
143.IP \(bu
144Use \fB\-\-sync\-from=\fIserver\fB \-\-active\fR to start the server
145in the active role, but prepared to switch to the backup role in which
146it would replicate data from \fIserver\fR. When \fBovsdb\-server\fR
147runs in active mode, it allows all transactions, including those that
148modify the database.
149.PP
150At runtime, management commands can change a server's role and otherwise
151manage active-backup features. See \fBActive-Backup Commands\fR, below,
152for more information.
153.TP
154\fB\-\-sync\-from=\fIserver\fR
155Sets up \fBovsdb\-server\fR to synchronize its databases with the
156databases in \fIserver\fR, which must be an active connection method
157in one of the forms documented in \fBovsdb\-client\fR(1). Every
158transaction committed by \fIserver\fR will be replicated to
159\fBovsdb\-server\fR. This option makes \fBovsdb\-server\fR start
160as a backup server; add \fB\-\-active\fR to make it start as an
161active server.
162.TP
163\fB\-\-sync\-exclude-tables=\fIdb\fB:\fItable\fR[\fB,\fIdb\fB:\fItable\fR]...\fR
164Causes the specified tables to be excluded from replication.
165.TP
166\fB\-\-active\fR
167By default, \fB\-\-sync\-from\fR makes \fBovsdb\-server\fR start up as
168a backup for \fIserver\fR. With \fB\-\-active\fR, however,
169\fBovsdb\-server\fR starts as an active server. Use this option to
170allow the syncing options to be specified using command line options,
171yet start the server, as the default, active server. To switch the
172running server to backup mode, use \fBovs-appctl(1)\fR to execute the
173\fBovsdb\-server/connect\-active\-ovsdb\-server\fR command.
ac300505 174.SS "Public Key Infrastructure Options"
78876719
BP
175The options described below for configuring the SSL public key
176infrastructure accept a special syntax for obtaining their
177configuration from the database. If any of these options is given
fb6de52c 178\fBdb:\fIdb\fB,\fItable\fB,\fIcolumn\fR as its argument, then the
4206b80f 179actual file name is read from the specified \fIcolumn\fR in \fItable\fR
fb6de52c 180within the \fIdb\fR database. The \fIcolumn\fR must have type
4206b80f
HM
181string or set of strings. The first nonempty string in the table is taken
182as the file name. (This means that ordinarily there should be at most
78876719 183one row in \fItable\fR.)
9467fe62 184.so lib/ssl.man
a976b2ec 185.so lib/ssl-bootstrap.man
5bf6cbd6 186.so lib/ssl-peer-ca-cert.man
e18a1d08
ER
187.SS "SSL Connection Options"
188.so lib/ssl-connect.man
f7f62235 189.SS "Other Options"
7b38bdc8 190.so lib/unixctl.man
f7f62235
BP
191.so lib/common.man
192.SH "RUNTIME MANAGEMENT COMMANDS"
193\fBovs\-appctl\fR(8) can send commands to a running
194\fBovsdb\-server\fR process. The currently supported commands are
195described below.
12b84d50 196.SS "\fBovsdb\-server\fR Commands"
475afa1b
BP
197These commands are specific to \fBovsdb\-server\fR.
198.IP "\fBexit\fR"
199Causes \fBovsdb\-server\fR to gracefully terminate.
30f81288
JP
200.IP "\fBovsdb\-server/compact\fR [\fIdb\fR]"
201Compacts database \fIdb\fR in-place. If \fIdb\fR is not
448b2003 202specified, compacts every database in-place. A database is also
1cfdc175 203compacted automatically when a transaction is logged if it is over 2
448b2003
BP
204times as large as its previous compacted size (and at least 10 MB),
205but not before 100 commits have been added or 10 minutes have elapsed
1cfdc175
DA
206since the last compaction. It will also be compacted automatically
207after 24 hours since the last compaction if 100 commits were added
208regardless of its size.
31d0b6c9
BP
209.
210.IP "\fBovsdb\-server/reconnect\fR"
211Makes \fBovsdb\-server\fR drop all of the JSON\-RPC
212connections to database clients and reconnect.
213.IP
214This command might be useful for debugging issues with database
215clients.
216.
b421d2af
BP
217.IP "\fBovsdb\-server/add\-remote \fIremote\fR"
218Adds a remote, as if \fB\-\-remote=\fIremote\fR had been specified on
219the \fBovsdb\-server\fR command line. (If \fIremote\fR is already a
220remote, this command succeeds without changing the configuration.)
221.
222.IP "\fBovsdb\-server/remove\-remote \fIremote\fR"
223Removes the specified \fIremote\fR from the configuration, failing
224with an error if \fIremote\fR is not configured as a remote. This
225command only works with remotes that were named on \fB\-\-remote\fR or
226\fBovsdb\-server/add\-remote\fR, that is, it will not remove remotes
227added indirectly because they were read from the database by
fb6de52c 228configuring a \fBdb:\fIdb\fB,\fItable\fB,\fIcolumn\fR remote.
b421d2af 229(You can remove a database source with \fBovsdb\-server/remove\-remote
fb6de52c 230\fBdb:\fIdb\fB,\fItable\fB,\fIcolumn\fR, but not individual
b421d2af
BP
231remotes found indirectly through the database.)
232.
233.IP "\fBovsdb\-server/list\-remotes"
234Outputs a list of the currently configured remotes named on
235\fB\-\-remote\fR or \fBovsdb\-server/add\-remote\fR, that is, it does
236not list remotes added indirectly because they were read from the
237database by configuring a
fb6de52c 238\fBdb:\fIdb\fB,\fItable\fB,\fIcolumn\fR remote.
b421d2af 239.
0a3b723b
BP
240.IP "\fBovsdb\-server/add\-db \fIdatabase\fR"
241Adds the \fIdatabase\fR to the running \fBovsdb\-server\fR. The database
242file must already have been created and initialized using, for example,
243\fBovsdb\-tool create\fR.
244.
245.IP "\fBovsdb\-server/remove\-db \fIdatabase\fR"
246Removes \fIdatabase\fR from the running \fBovsdb\-server\fR. \fIdatabase\fR
247must be a database name as listed by \fBovsdb-server/list\-dbs\fR.
248.IP
249If a remote has been configured that points to the specified
250\fIdatabase\fR (e.g. \fB\-\-remote=db:\fIdatabase\fB,\fR... on the
251command line), then it will be disabled until another database with
252the same name is added again (with \fBovsdb\-server/add\-db\fR).
253.IP
254Any public key infrastructure options specified through this database
255(e.g. \fB\-\-private\-key=db:\fIdatabase,\fR... on the command line)
256will be disabled until another database with the same name is added
257again (with \fBovsdb\-server/add\-db\fR).
258.
259.IP "\fBovsdb\-server/list\-dbs"
260Outputs a list of the currently configured databases added either through
261the command line or through the \fBovsdb\-server/add\-db\fR command.
262.
12b84d50
BP
263.SS "Active-Backup Commands"
264.PP
265These commands query and update the role of \fBovsdb\-server\fR within
266an active-backup pair of servers. See \fBActive-Backup Options\fR,
267above, and \fBActive-Backup Database Service Model\fR in
268\fBovsdb\fR(7) for more information.
269.
f53d7518
AZ
270.IP "\fBovsdb\-server/set\-active\-ovsdb\-server \fIserver"
271Sets the active \fIserver\fR from which \fBovsdb\-server\fR connects through
272\fBovsdb\-server/connect\-active\-ovsdb\-server\fR.
12b84d50 273This overrides the \fB\-\-sync\-from\fR command-line option.
9dc05cdc 274.
f53d7518
AZ
275.IP "\fBovsdb\-server/get\-active\-ovsdb\-server"
276Gets the active server from which \fBovsdb\-server\fR is currently synchronizing
9dc05cdc
MC
277its databases.
278.
f53d7518 279.IP "\fBovsdb\-server/connect\-active\-ovsdb\-server"
12b84d50
BP
280Switches the server to a backup role. The server starts synchronizing
281its databases with the active server specified by
282\fBovsdb\-server/set\-active\-ovsdb\-server\fR (or the
283\fB\-\-sync\-from\fR command-line option) and closes all existing
284client connections, which requires clients to reconnect.
9dc05cdc 285.
f53d7518 286.IP "\fBovsdb\-server/disconnect\-active\-ovsdb\-server"
12b84d50
BP
287Switches the server to an active role. The server stops synchronizing
288its databases with an active server and closes all existing client
289connections, which requires clients to reconnect.
9dc05cdc 290.
e988b8ab
NS
291.IP "\fBovsdb\-server/set\-active\-ovsdb\-server\-probe\-interval \fIprobe interval"
292Sets the probe interval (in milli seconds) for the connection to
293active \fIserver\fR.
294.
295.
60e0cd04 296.IP "\fBovsdb\-server/set\-sync\-exclude\-tables \fIdb\fB:\fItable\fR[\fB,\fIdb\fB:\fItable\fR]..."
12b84d50
BP
297Sets the \fItable\fR within \fIdb\fR that will be excluded from synchronization.
298This overrides the \fB\-\-sync\-exclude-tables\fR command-line option.
9dc05cdc 299.
60e0cd04 300.IP "\fBovsdb\-server/get\-sync\-exclude\-tables"
9dc05cdc
MC
301Gets the tables that are currently excluded from synchronization.
302.
60e0cd04
AZ
303.IP "\fBovsdb\-server/sync\-status"
304Prints a summary of replication run time information. The \fBstate\fR
305information is always provided, indicating whether the server is running
306in the \fIactive\fR or the \fIbackup\fR mode.
307When running in backup mode, replication connection status, which
308can be either \fIconnecting\fR, \fIreplicating\fR or \fIerror\fR, are shown.
309When the connection is in \fIreplicating\fR state, further output shows
310the list of databases currently replicating, and the tables that are
311excluded.
312.
1b1d2e6d
BP
313.SS "Cluster Commands"
314These commands support the \fBovsdb\-server\fR clustered service model.
315They apply only to databases in the format used for clustered databases,
316which is the database format created by \fBovsdb\-tool create\-cluster\fR
317and \fBovsdb\-tool join\-cluster\fR.
318.
319.IP "\fBcluster/cid \fIdb\fR"
320Prints the cluster ID for \fIdb\fR, which is a UUID that identifies
321the cluster. If \fIdb\fR is a database newly created by
322\fBovsdb\-tool cluster\-join\fR that has not yet successfully joined
323its cluster, and \fB\-\-cid\fR was not specified on the
324\fBcluster\-join\fR command line, then this command will report an
325error because the cluster ID is not yet known.
326.
327.IP "\fBcluster/sid \fIdb\fR"
328Prints the server ID for \fIdb\fR, which is a UUID that identifies
329this server within the cluster.
330.
331.IP "\fBcluster/status \fIdb\fR"
332Prints this server's status within the cluster and the status of its
333connections to other servers in the cluster.
334.
335.IP "\fBcluster/leave \fIdb\fR"
336This command starts the server gracefully
337removing itself from its cluster. At least one server must remain,
338and the cluster must be healthy, that is, over half of the cluster's
339servers must be up.
340.IP
341When the server successfully leaves the cluster, it stops serving
342\fIdb\fR, as if \fBovsdb\-server/remove\-db \fIdb\fR had been
343executed.
344.IP
345Use \fBovsdb\-client wait\fR (see \fBovsdb\-client\fR(1)) to wait
346until the server has left the cluster.
80c42f7f
BP
347.IP
348Once a server leaves a cluster, it may never rejoin it. Instead,
349create a new server and join it to the cluster.
43a6cf35
MM
350.IP
351Note that removing the server from the cluster alters the total size
352of the cluster. For example, if you remove two servers from a three
353server cluster, then the "cluster" becomes a single functioning server.
354This does not result in a three server cluster that lacks quorum.
1b1d2e6d
BP
355.
356.IP "\fBcluster/kick \fIdb server\fR"
357Start graceful removal of \fIserver\fR from \fIdb\fR's cluster, like
358\fBcluster/leave\fR (without \fB\-\-force\fR) except that it can
359remove any server, not just this one.
360.IP
361\fIserver\fR may be a server ID, as printed by \fBcluster/sid\fR, or
362the server's local network address as passed to \fBovsdb-tool\fR's
363\fBcreate\-cluster\fR or \fBjoin\-cluster\fR command. Use
364\fBcluster/status\fR to see a list of cluster members.
365.
8e354614
HZ
366.IP "\fBcluster/change-election-timer \fIdb time\fR"
367Change the leader election timeout base value of the cluster, in milliseconds.
368.IP
369Leader election will be initiated by a follower if there is no heartbeat
370received from the leader within this time plus a random time within 1 second.
371.IP
372The default value is 1000, if not changed with this command. This command can
373be used to adjust the value when necessary, according to the expected load and
374response time of the servers.
375.IP
376This command must be executed on the leader. It initiates the change to the
377cluster. To see if the change takes effect (committed), use
378\fBcluster/status\fR to show the current setting. Once a change is committed,
379it persists at server restarts.
380.
f7f62235 381.so lib/vlog-unixctl.man
149ff68a 382.so lib/memory-unixctl.man
a5f607bc 383.so lib/coverage-unixctl.man
508624b6
BP
384.SH "BUGS"
385.
386In Open vSwitch before version 2.4, when \fBovsdb\-server\fR sent
387JSON-RPC error responses to some requests, it incorrectly formulated
388them with the \fBresult\fR and \fBerror\fR swapped, so that the
389response appeared to indicate success (with a nonsensical result)
390rather than an error. The requests that suffered from this problem
391were:
392.
393.IP \fBtransact\fR
394.IQ \fBget_schema\fR
395Only if the request names a nonexistent database.
396.IP \fBmonitor\fR
397.IQ \fBlock\fR
398.IQ \fBunlock\fR
399In all error cases.
400.
401.PP
402Of these cases, the only error that a well-written application is
403likely to encounter in practice is \fBmonitor\fR of tables or columns
404that do not exist, in an situation where the application has been
405upgraded but the old database schema is still temporarily in use. To
406handle this situation gracefully, we recommend that clients should
407treat a \fBmonitor\fR response with a \fBresult\fR that contains an
408\fBerror\fR key-value pair as an error (assuming that the database
409being monitored does not contain a table named \fBerror\fR).
410.
f7f62235 411.SH "SEE ALSO"
12b84d50
BP
412\fBovsdb\fR(7),
413\fBovsdb\-tool\fR(1),
414\fBovsdb\-server\fR(5),
415\fBovsdb\-server\fR(7).