ovsdb/ovsdb-server.1.in

   1 .\" -*- nroff -*-
   2 .de IQ
   3 .  br
   4 .  ns
   5 .  IP "\\$1"
   6 ..
   7 .TH ovsdb\-server 1 "@VERSION@" "Open vSwitch" "Open vSwitch Manual"
   8 .\" This program's name:
   9 .ds PN ovsdb\-server
  10 .
  11 .SH NAME
  12 ovsdb\-server \- Open vSwitch database server
  13 .
  14 .SH SYNOPSIS
  15 \fBovsdb\-server\fR
  16 [\fIdatabase\fR]\&...
  17 [\fB\-\-remote=\fIremote\fR]\&...
  18 [\fB\-\-run=\fIcommand\fR]
  19 .so lib/daemon-syn.man
  20 .so lib/service-syn.man
  21 .so lib/vlog-syn.man
  22 .IP "Active-backup options:"
  23 [\fB\-\-sync\-from=\fIserver\fR]
  24 [\fB\-\-sync\-exclude-tables=\fIdb\fB:\fItable\fR[\fB,\fIdb\fB:\fItable\fR]...\fR]
  25 [\fB\-\-active\fR]
  26 .so lib/ssl-syn.man
  27 .so lib/ssl-bootstrap-syn.man
  28 .so lib/ssl-peer-ca-cert-syn.man
  29 .so lib/ssl-connect-syn.man
  30 .so lib/unixctl-syn.man
  31 .so lib/common-syn.man
  32 .
  33 .SH DESCRIPTION
  34 The \fBovsdb\-server\fR program provides RPC interfaces to one or more
  35 Open vSwitch databases (OVSDBs).  It supports JSON-RPC client
  36 connections over active or passive TCP/IP or Unix domain sockets.
  37 For an introduction to OVSDB and its implementation in Open vSwitch,
  38 see \fBovsdb\fR(7).
  39 .PP
  40 Each OVSDB file may be specified on the command line as \fIdatabase\fR.
  41 If none is specified, the default is \fB@DBDIR@/conf.db\fR.  The database
  42 files must already have been created and initialized using, for
  43 example, \fBovsdb\-tool create\fR.
  44 .PP
  45 This OVSDB implementation supports standalone and active-backup
  46 databases, as well as database replication.
  47 See the Service Models section of \fBovsdb\fR(7) for more information.
  48 .SH OPTIONS
  49 .
  50 .IP "\fB\-\-remote=\fIremote\fR"
  51 Adds \fIremote\fR as a connection method used by \fBovsdb\-server\fR.
  52 The \fIremote\fR may be an OVSDB active or passive connection method,
  53 e.g. \fBpssl:6640\fR, as described in \fBovsdb\fR(7).  The following
  54 additional form is also supported:
  55 .
  56 .RS
  57 .IP "\fBdb:\fIdb\fB,\fItable\fB,\fIcolumn\fR"
  58 Reads additional connection methods from \fIcolumn\fR in all of the
  59 rows in \fItable\fR within \fIdb\fR.  As the contents of \fIcolumn\fR changes,
  60 \fBovsdb\-server\fR also adds and drops connection methods accordingly.
  61 .IP
  62 If \fIcolumn\fR's type is string or set of strings, then the
  63 connection methods are taken directly from the column.  The connection
  64 methods in the column must have one of the forms described above.
  65 .IP
  66 If \fIcolumn\fR's type is UUID or set of UUIDs and references a table,
  67 then each UUID is looked up in the referenced table to obtain a row.
  68 The following columns in the row, if present and of the correct type,
  69 configure a connection method.  Any additional columns are ignored.
  70 .RS
  71 .IP "\fBtarget\fR (string)"
  72 Connection method, in one of the forms described above.  This column
  73 is mandatory: if it is missing or empty then no connection method can
  74 be configured.
  75 .IP "\fBmax_backoff\fR (integer)"
  76 Maximum number of milliseconds to wait between connection attempts.
  77 .IP "\fBinactivity_probe\fR (integer)"
  78 Maximum number of milliseconds of idle time on connection to
  79 client before sending an inactivity probe message.
  80 .IP "\fBread_only\fR (boolean)"
  81 If true, only read-only transactions are allowed on this connection.
  82 .RE
  83 .IP
  84 It is an error for \fIcolumn\fR to have another type.
  85 .RE
  86 .
  87 .IP
  88 To connect or listen on multiple connection methods, use multiple
  89 \fB\-\-remote\fR options.
  90 .
  91 .IP "\fB\-\-run=\fIcommand\fR]"
  92 Ordinarily \fBovsdb\-server\fR runs forever, or until it is told to
  93 exit (see \fBRUNTIME MANAGEMENT COMMANDS\fR below).  With this option,
  94 \fBovsdb\-server\fR instead starts a shell subprocess running
  95 \fIcommand\fR.  When the subprocess terminates, \fBovsdb\-server\fR
  96 also exits gracefully.  If the subprocess exits normally with exit
  97 code 0, then \fBovsdb\-server\fR exits with exit code 0 also;
  98 otherwise, it exits with exit code 1.
  99 .IP
 100 This option can be useful where a database server is needed only to
 101 run a single command, e.g.:
 102 .B "ovsdb\-server \-\-remote=punix:socket \-\-run='ovsdb\-client dump unix:socket Open_vSwitch'"
 103 .IP
 104 This option is not supported on Windows platform.
 105 .SS "Daemon Options"
 106 .ds DD \
 107 \fBovsdb\-server\fR detaches only after it starts listening on all \
 108 configured remotes.
 109 .so lib/daemon.man
 110 .SS "Service Options"
 111 .so lib/service.man
 112 .SS "Logging Options"
 113 .so lib/vlog.man
 114 .SS "Active-Backup Options"
 115 These options support the \fBovsdb\-server\fR active-backup service
 116 model and database replication.  By
 117 default, when it serves a database in this format, \fBovsdb\-server\fR
 118 runs as a standalone server.  These options can configure it for
 119 active-backup use:
 120 .IP \(bu
 121 Use \fB\-\-sync\-from=\fIserver\fR to start the server in the backup
 122 role, replicating data from \fIserver\fR.  When \fBovsdb\-server\fR is
 123 running as a backup server, it rejects all transactions that can
 124 modify the database content, including lock commands.  The same form
 125 can be used to configure the local database as a replica of
 126 \fIserver\fR.
 127 .IP \(bu
 128 Use \fB\-\-sync\-from=\fIserver\fB \-\-active\fR to start the server
 129 in the active role, but prepared to switch to the backup role in which
 130 it would replicate data from \fIserver\fR.  When \fBovsdb\-server\fR
 131 runs in active mode, it allows all transactions, including those that
 132 modify the database.
 133 .PP
 134 At runtime, management commands can change a server's role and otherwise
 135 manage active-backup features.  See \fBActive-Backup Commands\fR, below,
 136 for more information.
 137 .TP
 138 \fB\-\-sync\-from=\fIserver\fR
 139 Sets up \fBovsdb\-server\fR to synchronize its databases with the
 140 databases in \fIserver\fR, which must be an active connection method
 141 in one of the forms documented in \fBovsdb\-client\fR(1).  Every
 142 transaction committed by \fIserver\fR will be replicated to
 143 \fBovsdb\-server\fR.  This option makes \fBovsdb\-server\fR start
 144 as a backup server; add \fB\-\-active\fR to make it start as an
 145 active server.
 146 .TP
 147 \fB\-\-sync\-exclude-tables=\fIdb\fB:\fItable\fR[\fB,\fIdb\fB:\fItable\fR]...\fR
 148 Causes the specified tables to be excluded from replication.
 149 .TP
 150 \fB\-\-active\fR
 151 By default, \fB\-\-sync\-from\fR makes \fBovsdb\-server\fR start up as
 152 a backup for \fIserver\fR.  With \fB\-\-active\fR, however,
 153 \fBovsdb\-server\fR starts as an active server.  Use this option to
 154 allow the syncing options to be specified using command line options,
 155 yet start the server, as the default, active server.  To switch the
 156 running server to backup mode, use \fBovs-appctl(1)\fR to execute the
 157 \fBovsdb\-server/connect\-active\-ovsdb\-server\fR command.
 158 .SS "Public Key Infrastructure Options"
 159 The options described below for configuring the SSL public key
 160 infrastructure accept a special syntax for obtaining their
 161 configuration from the database.  If any of these options is given
 162 \fBdb:\fIdb\fB,\fItable\fB,\fIcolumn\fR as its argument, then the
 163 actual file name is read from the specified \fIcolumn\fR in \fItable\fR
 164 within the \fIdb\fR database.  The \fIcolumn\fR must have type
 165 string or set of strings.  The first nonempty string in the table is taken
 166 as the file name.  (This means that ordinarily there should be at most
 167 one row in \fItable\fR.)
 168 .so lib/ssl.man
 169 .so lib/ssl-bootstrap.man
 170 .so lib/ssl-peer-ca-cert.man
 171 .SS "SSL Connection Options"
 172 .so lib/ssl-connect.man
 173 .SS "Other Options"
 174 .so lib/unixctl.man
 175 .so lib/common.man
 176 .SH "RUNTIME MANAGEMENT COMMANDS"
 177 \fBovs\-appctl\fR(8) can send commands to a running
 178 \fBovsdb\-server\fR process.  The currently supported commands are
 179 described below.
 180 .SS "\fBovsdb\-server\fR Commands"
 181 These commands are specific to \fBovsdb\-server\fR.
 182 .IP "\fBexit\fR"
 183 Causes \fBovsdb\-server\fR to gracefully terminate.
 184 .IP "\fBovsdb\-server/compact\fR [\fIdb\fR]"
 185 Compacts database \fIdb\fR in-place.  If \fIdb\fR is not
 186 specified, compacts every database in-place.  A database is also
 187 compacted automatically when a transaction is logged if it is over 4
 188 times as large as its previous compacted size (and at least 10 MB),
 189 but not before 100 commits have been added or 10 minutes have elapsed
 190 since the last compaction.
 191 .
 192 .IP "\fBovsdb\-server/reconnect\fR"
 193 Makes \fBovsdb\-server\fR drop all of the JSON\-RPC
 194 connections to database clients and reconnect.
 195 .IP
 196 This command might be useful for debugging issues with database
 197 clients.
 198 .
 199 .IP "\fBovsdb\-server/add\-remote \fIremote\fR"
 200 Adds a remote, as if \fB\-\-remote=\fIremote\fR had been specified on
 201 the \fBovsdb\-server\fR command line.  (If \fIremote\fR is already a
 202 remote, this command succeeds without changing the configuration.)
 203 .
 204 .IP "\fBovsdb\-server/remove\-remote \fIremote\fR"
 205 Removes the specified \fIremote\fR from the configuration, failing
 206 with an error if \fIremote\fR is not configured as a remote.  This
 207 command only works with remotes that were named on \fB\-\-remote\fR or
 208 \fBovsdb\-server/add\-remote\fR, that is, it will not remove remotes
 209 added indirectly because they were read from the database by
 210 configuring a \fBdb:\fIdb\fB,\fItable\fB,\fIcolumn\fR remote.
 211 (You can remove a database source with \fBovsdb\-server/remove\-remote
 212 \fBdb:\fIdb\fB,\fItable\fB,\fIcolumn\fR, but not individual
 213 remotes found indirectly through the database.)
 214 .
 215 .IP "\fBovsdb\-server/list\-remotes"
 216 Outputs a list of the currently configured remotes named on
 217 \fB\-\-remote\fR or \fBovsdb\-server/add\-remote\fR, that is, it does
 218 not list remotes added indirectly because they were read from the
 219 database by configuring a
 220 \fBdb:\fIdb\fB,\fItable\fB,\fIcolumn\fR remote.
 221 .
 222 .IP "\fBovsdb\-server/add\-db \fIdatabase\fR"
 223 Adds the \fIdatabase\fR to the running \fBovsdb\-server\fR.  The database
 224 file must already have been created and initialized using, for example,
 225 \fBovsdb\-tool create\fR.
 226 .
 227 .IP "\fBovsdb\-server/remove\-db \fIdatabase\fR"
 228 Removes \fIdatabase\fR from the running \fBovsdb\-server\fR.  \fIdatabase\fR
 229 must be a database name as listed by \fBovsdb-server/list\-dbs\fR.
 230 .IP
 231 If a remote has been configured that points to the specified
 232 \fIdatabase\fR (e.g. \fB\-\-remote=db:\fIdatabase\fB,\fR... on the
 233 command line), then it will be disabled until another database with
 234 the same name is added again (with \fBovsdb\-server/add\-db\fR).
 235 .IP
 236 Any public key infrastructure options specified through this database
 237 (e.g. \fB\-\-private\-key=db:\fIdatabase,\fR... on the command line)
 238 will be disabled until another database with the same name is added
 239 again (with \fBovsdb\-server/add\-db\fR).
 240 .
 241 .IP "\fBovsdb\-server/list\-dbs"
 242 Outputs a list of the currently configured databases added either through
 243 the command line or through the \fBovsdb\-server/add\-db\fR command.
 244 .
 245 .SS "Active-Backup Commands"
 246 .PP
 247 These commands query and update the role of \fBovsdb\-server\fR within
 248 an active-backup pair of servers.  See \fBActive-Backup Options\fR,
 249 above, and \fBActive-Backup Database Service Model\fR in
 250 \fBovsdb\fR(7) for more information.
 251 .
 252 .IP "\fBovsdb\-server/set\-active\-ovsdb\-server \fIserver"
 253 Sets  the active \fIserver\fR from which \fBovsdb\-server\fR connects through
 254 \fBovsdb\-server/connect\-active\-ovsdb\-server\fR.
 255 This overrides the \fB\-\-sync\-from\fR command-line option.
 256 .
 257 .IP "\fBovsdb\-server/get\-active\-ovsdb\-server"
 258 Gets the active server from which \fBovsdb\-server\fR is currently synchronizing
 259 its databases.
 260 .
 261 .IP "\fBovsdb\-server/connect\-active\-ovsdb\-server"
 262 Switches the server to a backup role.  The server starts synchronizing
 263 its databases with the active server specified by
 264 \fBovsdb\-server/set\-active\-ovsdb\-server\fR (or the
 265 \fB\-\-sync\-from\fR command-line option) and closes all existing
 266 client connections, which requires clients to reconnect.
 267 .
 268 .IP "\fBovsdb\-server/disconnect\-active\-ovsdb\-server"
 269 Switches the server to an active role.  The server stops synchronizing
 270 its databases with an active server and closes all existing client
 271 connections, which requires clients to reconnect.
 272 .
 273 .IP "\fBovsdb\-server/set\-sync\-exclude\-tables \fIdb\fB:\fItable\fR[\fB,\fIdb\fB:\fItable\fR]..."
 274 Sets the \fItable\fR within \fIdb\fR that will be excluded from synchronization.
 275 This overrides the \fB\-\-sync\-exclude-tables\fR command-line option.
 276 .
 277 .IP "\fBovsdb\-server/get\-sync\-exclude\-tables"
 278 Gets  the  tables  that are currently excluded from synchronization.
 279 .
 280 .IP "\fBovsdb\-server/sync\-status"
 281 Prints a summary of replication run time information. The \fBstate\fR
 282 information is always provided, indicating whether the server is running
 283 in the \fIactive\fR or the \fIbackup\fR mode.
 284 When running in backup mode, replication connection status, which
 285 can be either \fIconnecting\fR, \fIreplicating\fR or \fIerror\fR, are shown.
 286 When the connection is in \fIreplicating\fR state, further output shows
 287 the list of databases currently replicating, and the tables that are
 288 excluded.
 289 .
 290 .so lib/vlog-unixctl.man
 291 .so lib/memory-unixctl.man
 292 .so lib/coverage-unixctl.man
 293 .SH "BUGS"
 294 .
 295 In Open vSwitch before version 2.4, when \fBovsdb\-server\fR sent
 296 JSON-RPC error responses to some requests, it incorrectly formulated
 297 them with the \fBresult\fR and \fBerror\fR swapped, so that the
 298 response appeared to indicate success (with a nonsensical result)
 299 rather than an error.  The requests that suffered from this problem
 300 were:
 301 .
 302 .IP \fBtransact\fR
 303 .IQ \fBget_schema\fR
 304 Only if the request names a nonexistent database.
 305 .IP \fBmonitor\fR
 306 .IQ \fBlock\fR
 307 .IQ \fBunlock\fR
 308 In all error cases.
 309 .
 310 .PP
 311 Of these cases, the only error that a well-written application is
 312 likely to encounter in practice is \fBmonitor\fR of tables or columns
 313 that do not exist, in an situation where the application has been
 314 upgraded but the old database schema is still temporarily in use.  To
 315 handle this situation gracefully, we recommend that clients should
 316 treat a \fBmonitor\fR response with a \fBresult\fR that contains an
 317 \fBerror\fR key-value pair as an error (assuming that the database
 318 being monitored does not contain a table named \fBerror\fR).
 319 .
 320 .SH "SEE ALSO"
 321 \fBovsdb\fR(7),
 322 \fBovsdb\-tool\fR(1),
 323 \fBovsdb\-server\fR(5),
 324 \fBovsdb\-server\fR(7).