1OVSDB(7) Open vSwitch OVSDB(7)
2
6 ovsdb - Open vSwitch Database (Overview)
7
9 OVSDB, the Open vSwitch Database, is a network-accessible database sys‐
10 tem. Schemas in OVSDB specify the tables in a database and their col‐
11 umns’ types and can include data, uniqueness, and referential integrity
12 constraints. OVSDB offers atomic, consistent, isolated, durable trans‐
13 actions. RFC 7047 specifies the JSON-RPC based protocol that OVSDB
14 clients and servers use to communicate.
15 The OVSDB protocol is well suited for state synchronization because it
17 allows each client to monitor the contents of a whole database or a
18 subset of it. Whenever a monitored portion of the database changes,
19 the server tells the client what rows were added or modified (including
20 the new contents) or deleted. Thus, OVSDB clients can easily keep
21 track of the newest contents of any part of the database.
22 While OVSDB is general-purpose and not particularly specialized for use
24 with Open vSwitch, Open vSwitch does use it for multiple purposes. The
25 leading use of OVSDB is for configuring and monitoring ovs-vswitchd(8),
26 the Open vSwitch switch daemon, using the schema documented in
27 ovs-vswitchd.conf.db(5). The Open Virtual Network (OVN) sub-project of
28 OVS uses two OVSDB schemas, documented in ovn-nb(5) and ovn-sb(5).
29 Finally, Open vSwitch includes the “VTEP” schema, documented in vtep(5)
30 that many third-party hardware switches support for configuring VXLAN,
31 although OVS itself does not directly use this schema.
32 The OVSDB protocol specification allows independent, interoperable
34 implementations of OVSDB to be developed. Open vSwitch includes an
35 OVSDB server implementation named ovsdb-server(1), which supports sev‐
36 eral protocol extensions documented in its manpage, and a basic com‐
37 mand-line OVSDB client named ovsdb-client(1), as well as OVSDB client
38 libraries for C and for Python. Open vSwitch documentation often
39 speaks of these OVSDB implementations in Open vSwitch as simply
40 “OVSDB,” even though that is distinct from the OVSDB protocol; we make
41 the distinction explicit only when it might otherwise be unclear from
42 the context.
43 In addition to these generic OVSDB server and client tools, Open
45 vSwitch includes tools for working with databases that have specific
46 schemas: ovs-vsctl works with the ovs-vswitchd configuration database,
47 vtep-ctl works with the VTEP database, ovn-nbctl works with the OVN
48 Northbound database, and so on.
49 RFC 7047 specifies the OVSDB protocol but it does not specify an
51 on-disk storage format. Open vSwitch includes ovsdb-tool(1) for work‐
52 ing with its own on-disk database formats. The most notable feature of
53 this format is that ovsdb-tool(1) makes it easy for users to print the
54 transactions that have changed a database since the last time it was
55 compacted. This feature is often useful for troubleshooting.
56
58 Schemas in OVSDB have a JSON format that is specified in RFC 7047.
59 They are often stored in files with an extension .ovsschema. An
60 on-disk database in OVSDB includes a schema and data, embedding both
61 into a single file. The Open vSwitch utility ovsdb-tool has commands
62 that work with schema files and with the schemas embedded in database
63 files.
64 An Open vSwitch schema has three important identifiers. The first is
66 its name, which is also the name used in JSON-RPC calls to identify a
67 database based on that schema. For example, the schema used to config‐
68 ure Open vSwitch has the name Open_vSwitch. Schema names begin with a
69 letter or an underscore, followed by any number of letters, under‐
70 scores, or digits. The ovsdb-tool commands schema-name and db-name
71 extract the schema name from a schema or database file, respectively.
72 An OVSDB schema also has a version of the form x.y.z e.g. 1.2.3.
74 Schemas managed within the Open vSwitch project manage version number‐
75 ing in the following way (but OVSDB does not mandate this approach).
76 Whenever we change the database schema in a non-backward compatible way
77 (e.g. when we delete a column or a table), we increment <x> and set <y>
78 and <z> to 0. When we change the database schema in a backward compat‐
79 ible way (e.g. when we add a new column), we increment <y> and set <z>
80 to 0. When we change the database schema cosmetically (e.g. we rein‐
81 dent its syntax), we increment <z>. The ovsdb-tool commands
82 schema-version and db-version extract the schema version from a schema
83 or database file, respectively.
84 Very old OVSDB schemas do not have a version, but RFC 7047 mandates it.
86 An OVSDB schema optionally has a “checksum.” RFC 7047 does not specify
88 the use of the checksum and recommends that clients ignore it. Open
89 vSwitch uses the checksum to remind developers to update the version:
90 at build time, if the schema’s embedded checksum, ignoring the checksum
91 field itself, does not match the schema’s content, then it fails the
92 build with a recommendation to update the version and the checksum.
93 Thus, a developer who changes the schema, but does not update the ver‐
94 sion, receives an automatic reminder. In practice this has been an
95 effective way to ensure compliance with the version number policy. The
96 ovsdb-tool commands schema-cksum and db-cksum extract the schema check‐
97 sum from a schema or database file, respectively.
98
100 OVSDB supports three service models for databases: standalone,
101 active-backup, and clustered. The service models provide different
102 compromises among consistency, availability, and partition tolerance.
103 They also differ in the number of servers required and in terms of per‐
104 formance. The standalone and active-backup database service models
105 share one on-disk format, and clustered databases use a different for‐
106 mat, but the OVSDB programs work with both formats. ovsdb(5) documents
107 these file formats.
108 RFC 7047, which specifies the OVSDB protocol, does not mandate or spec‐
110 ify any particular service model.
111 The following sections describe the individual service models.
113 Standalone Database Service Model
115 A standalone database runs a single server. If the server stops run‐
116 ning, the database becomes inaccessible, and if the server’s storage is
117 lost or corrupted, the database’s content is lost. This service model
118 is appropriate when the database controls a process or activity to
119 which it is linked via “fate-sharing.” For example, an OVSDB instance
120 that controls an Open vSwitch virtual switch daemon, ovs-vswitchd, is a
121 standalone database because a server failure would take out both the
122 database and the virtual switch.
123 To set up a standalone database, use ovsdb-tool create to create a
125 database file, then run ovsdb-server to start the database service.
126 To configure a client, such as ovs-vswitchd or ovs-vsctl, to use a
128 standalone database, configure the server to listen on a “connection
129 method” that the client can reach, then point the client to that con‐
130 nection method. See Connection Methods below for information about
131 connection methods.
132 Active-Backup Database Service Model
134 An active-backup database runs two servers (on different hosts). At
135 any given time, one of the servers is designated with the active role
136 and the other the backup role. An active server behaves just like a
137 standalone server. A backup server makes an OVSDB connection to the
138 active server and uses it to continuously replicate its content as it
139 changes in real time. OVSDB clients can connect to either server but
140 only the active server allows data modification or lock transactions.
141 Setup for an active-backup database starts from a working standalone
143 database service, which is initially the active server. On another
144 node, to set up a backup server, create a database file with the same
145 schema as the active server. The initial contents of the database file
146 do not matter, as long as the schema is correct, so ovsdb-tool create
147 will work, as will copying the database file from the active server.
148 Then use ovsdb-server --sync-from=<active> to start the backup server,
149 where <active> is an OVSDB connection method (see Connection Methods
150 below) that connects to the active server. At that point, the backup
151 server will fetch a copy of the active database and keep it up-to-date
152 until it is killed.
153 When the active server in an active-backup server pair fails, an admin‐
155 istrator can switch the backup server to an active role with the
156 ovs-appctl command ovsdb-server/disconnect-active-ovsdb-server.
157 Clients then have read/write access to the now-active server. Of
158 course, administrators are slow to respond compared to software, so in
159 practice external management software detects the active server’s fail‐
160 ure and changes the backup server’s role. For example, the “Integra‐
161 tion Guide for Centralized Control” in the Open vSwitch documentation
162 describes how to use Pacemaker for this purpose in OVN.
163 Suppose an active server fails and its backup is promoted to active.
165 If the failed server is revived, it must be started as a backup server.
166 Otherwise, if both servers are active, then they may start out of sync,
167 if the database changed while the server was down, and they will con‐
168 tinue to diverge over time. This also happens if the software managing
169 the database servers cannot reach the active server and therefore
170 switches the backup to active, but other hosts can reach both servers.
171 These “split-brain” problems are unsolvable in general for server
172 pairs.
173 Compared to a standalone server, the active-backup service model some‐
175 what increases availability, at a risk of split-brain. It adds gener‐
176 ally insignificant performance overhead. On the other hand, the clus‐
177 tered service model, discussed below, requires at least 3 servers and
178 has greater performance overhead, but it avoids the need for external
179 management software and eliminates the possibility of split-brain.
180 Open vSwitch 2.6 introduced support for the active-backup service
182 model.
183 Clustered Database Service Model
185 A clustered database runs across 3 or 5 or more database servers (the
186 cluster) on different hosts. Servers in a cluster automatically syn‐
187 chronize writes within the cluster. A 3-server cluster can remain
188 available in the face of at most 1 server failure; a 5-server cluster
189 tolerates up to 2 failures. Clusters larger than 5 servers will also
190 work, with every 2 added servers allowing the cluster to tolerate 1
191 more failure, but write performance decreases. The number of servers
192 should be odd: a 4- or 6-server cluster cannot tolerate more failures
193 than a 3- or 5-server cluster, respectively.
194 To set up a clustered database, first initialize it on a single node by
196 running ovsdb-tool create-cluster, then start ovsdb-server. Depending
197 on its arguments, the create-cluster command can create an empty data‐
198 base or copy a standalone database’s contents into the new database.
199 To configure a client, such as ovn-controller or ovn-sbctl, to use a
201 clustered database, first configure all of the servers to listen on a
202 connection method that the client can reach, then point the client to
203 all of the servers’ connection methods, comma-separated. See
204 Connection Methods, below, for more detail.
205 Open vSwitch 2.9 introduced support for the clustered service model.
207 How to Maintain a Clustered Database
209 To add a server to a cluster, run ovsdb-tool join-cluster on the new
210 server and start ovsdb-server. To remove a running server from a clus‐
211 ter, use ovs-appctl to invoke the cluster/leave command. When a server
212 fails and cannot be recovered, e.g. because its hard disk crashed, or
213 to otherwise remove a server that is down from a cluster, use
214 ovs-appctl to invoke cluster/kick to make the remaining servers kick it
215 out of the cluster.
216 The above methods for adding and removing servers only work for healthy
218 clusters, that is, for clusters with no more failures than their maxi‐
219 mum tolerance. For example, in a 3-server cluster, the failure of 2
220 servers prevents servers joining or leaving the cluster (as well as
221 database access). To prevent data loss or inconsistency, the preferred
222 solution to this problem is to bring up enough of the failed servers to
223 make the cluster healthy again, then if necessary remove any remaining
224 failed servers and add new ones. If this cannot be done, though, use
225 ovs-appctl to invoke cluster/leave --force on a running server. This
226 command forces the server to which it is directed to leave its cluster
227 and form a new single-node cluster that contains only itself. The data
228 in the new cluster may be inconsistent with the former cluster: trans‐
229 actions not yet replicated to the server will be lost, and transactions
230 not yet applied to the cluster may be committed. Afterward, any
231 servers in its former cluster will regard the server to have failed.
232 Once a server leaves a cluster, it may never rejoin it. Instead, cre‐
234 ate a new server and join it to the cluster.
235 The servers in a cluster synchronize data over a cluster management
237 protocol that is specific to Open vSwitch; it is not the same as the
238 OVSDB protocol specified in RFC 7047. For this purpose, a server in a
239 cluster is tied to a particular IP address and TCP port, which is spec‐
240 ified in the ovsdb-tool command that creates or joins the cluster. The
241 TCP port used for clustering must be different from that used for OVSDB
242 clients. To change the port or address of a server in a cluster, first
243 remove it from the cluster, then add it back with the new address.
244 To upgrade the ovsdb-server processes in a cluster from one version of
246 Open vSwitch to another, upgrading them one at a time will keep the
247 cluster healthy during the upgrade process. (This is different from
248 upgrading a database schema, which is covered later under Upgrading or
249 Downgrading a Database.)
250 Clustered OVSDB does not support the OVSDB “ephemeral columns” feature.
252 ovsdb-tool and ovsdb-client change ephemeral columns into persistent
253 ones when they work with schemas for clustered databases. Future ver‐
254 sions of OVSDB might add support for this feature.
255 Understanding Cluster Consistency
257 To ensure consistency, clustered OVSDB uses the Raft algorithm
258 described in Diego Ongaro’s Ph.D. thesis, “Consensus: Bridging Theory
259 and Practice”. In an operational Raft cluster, at any given time a
260 single server is the “leader” and the other nodes are “followers”.
261 Only the leader processes transactions, but a transaction is only com‐
262 mitted when a majority of the servers confirm to the leader that they
263 have written it to persistent storage.
264 In most database systems, read and write access to the database happens
266 through transactions. In such a system, Raft allows a cluster to
267 present a strongly consistent transactional interface. OVSDB uses con‐
268 ventional transactions for writes, but clients often effectively do
269 reads a different way, by asking the server to “monitor” a database or
270 a subset of one on the client’s behalf. Whenever monitored data
271 changes, the server automatically tells the client what changed, which
272 allows the client to maintain an accurate snapshot of the database in
273 its memory. Of course, at any given time, the snapshot may be somewhat
274 dated since some of it could have changed without the change notifica‐
275 tion yet being received and processed by the client.
276 Given this unconventional usage model, OVSDB also adopts an unconven‐
278 tional clustering model. Each server in a cluster acts independently
279 for the purpose of monitors and read-only transactions, without verify‐
280 ing that data is up-to-date with the leader. Servers forward transac‐
281 tions that write to the database to the leader for execution, ensuring
282 consistency. This has the following consequences:
283 · Transactions that involve writes, against any server in the cluster,
285 are linearizable if clients take care to use correct prerequisites,
286 which is the same condition required for linearizability in a stand‐
287 alone OVSDB. (Actually, “at-least-once” consistency, because OVSDB
288 does not have a session mechanism to drop duplicate transactions if a
289 connection drops after the server commits it but before the client
290 receives the result.)
291 · Read-only transactions can yield results based on a stale version of
293 the database, if they are executed against a follower. Transactions
294 on the leader always yield fresh results. (With monitors, as
295 explained above, a client can always see stale data even without
296 clustering, so clustering does not change the consistency model for
297 monitors.)
298 · Monitor-based (or read-heavy) workloads scale well across a cluster,
300 because clustering OVSDB adds no additional work or communication for
301 reads and monitors.
302 · A write-heavy client should connect to the leader, to avoid the over‐
304 head of followers forwarding transactions to the leader.
305 · When a client conducts a mix of read and write transactions across
307 more than one server in a cluster, it can see inconsistent results
308 because a read transaction might read stale data whose updates have
309 not yet propagated from the leader. By default, ovn-sbctl and simi‐
310 lar utilities connect to the cluster leader to avoid this issue.
311 The same might occur for transactions against a single follower
313 except that the OVSDB server ensures that the results of a write for‐
314 warded to the leader by a given server are visible at that server
315 before it replies to the requesting client.
316 · If a client uses a database on one server in a cluster, then another
318 server in the cluster (perhaps because the first server failed), the
319 client could observe stale data. Clustered OVSDB clients, however,
320 can use a column in the _Server database to detect that data on a
321 server is older than data that the client previously read. The OVSDB
322 client library in Open vSwitch uses this feature to avoid servers
323 with stale data.
324
326 OVSDB can layer replication on top of any of its service models.
327 Replication, in this context, means to make, and keep up-to-date, a
328 read-only copy of the contents of a database (the replica). One use of
329 replication is to keep an up-to-date backup of a database. A replica
330 used solely for backup would not need to support clients of its own. A
331 set of replicas that do serve clients could be used to scale out read
332 access to the primary database.
333 A database replica is set up in the same way as a backup server in an
335 active-backup pair, with the difference that the replica is never pro‐
336 moted to an active role.
337 A database can have multiple replicas.
339 Open vSwitch 2.6 introduced support for database replication.
341
343 An OVSDB connection method is a string that specifies how to make a
344 JSON-RPC connection between an OVSDB client and server. Connection
345 methods are part of the Open vSwitch implementation of OVSDB and not
346 specified by RFC 7047. ovsdb-server uses connection methods to specify
347 how it should listen for connections from clients and ovsdb-client uses
348 them to specify how it should connect to a server. Connections in the
349 opposite direction, where ovsdb-server connects to a client that is
350 configured to listen for an incoming connection, are also possible.
351 Connection methods are classified as active or passive. An active con‐
353 nection method makes an outgoing connection to a remote host; a passive
354 connection method listens for connections from remote hosts. The most
355 common arrangement is to configure an OVSDB server with passive connec‐
356 tion methods and clients with active ones, but the OVSDB implementation
357 in Open vSwitch supports the opposite arrangement as well.
358 OVSDB supports the following active connection methods:
360 ssl:<host>:<port>
362 The specified SSL or TLS <port> on the given <host>.
363 tcp:<host>:<port>
365 The specified TCP <port> on the given <host>.
366 unix:<file>
368 On Unix-like systems, connect to the Unix domain server socket
369 named <file>.
370 On Windows, connect to a local named pipe that is represented by
372 a file created in the path <file> to mimic the behavior of a
373 Unix domain socket.
374 <method1>,<method2>,…,<methodN>
376 For a clustered database service to be highly available, a
377 client must be able to connect to any of the servers in the
378 cluster. To do so, specify connection methods for each of the
379 servers separated by commas (and optional spaces).
380 In theory, if machines go up and down and IP addresses change in
382 the right way, a client could talk to the wrong instance of a
383 database. To avoid this possibility, add cid:<uuid> to the list
384 of methods, where <uuid> is the cluster ID of the desired data‐
385 base cluster, as printed by ovsdb-tool db-cid. This feature is
386 optional.
387 OVSDB supports the following passive connection methods:
389 pssl:<port>[:<ip>]
391 Listen on the given TCP <port> for SSL or TLS connections. By
392 default, connections are not bound to a particular local IP
393 address. Specifying <ip> limits connections to those from the
394 given IP.
395 ptcp:<port>[:<ip>]
397 Listen on the given TCP <port>. By default, connections are not
398 bound to a particular local IP address. Specifying <ip> limits
399 connections to those from the given IP.
400 punix:<file>
402 On Unix-like systems, listens for connections on the Unix domain
403 socket named <file>.
404 On Windows, listens on a local named pipe, creating a named pipe
406 <file> to mimic the behavior of a Unix domain socket.
407 All IP-based connection methods accept IPv4 and IPv6 addresses. To
409 specify an IPv6 address, wrap it in square brackets, e.g.
410 ssl:[::1]:6640. Passive IP-based connection methods by default listen
411 for IPv4 connections only; use [::] as the address to accept both IPv4
412 and IPv6 connections, e.g. pssl:6640:[::]. DNS names are also accepted
413 if built with unbound library. On Linux, use %<device> to designate a
414 scope for IPv6 link-level addresses, e.g. ssl:[fe80::1234%eth0]:6653.
415 The <port> may be omitted from connection methods that use a port num‐
417 ber. The default <port> for TCP-based connection methods is 6640, e.g.
418 pssl: is equivalent to pssl:6640. In Open vSwitch prior to version
419 2.4.0, the default port was 6632. To avoid incompatibility between
420 older and newer versions, we encourage users to specify a port number.
421 The ssl and pssl connection methods requires additional configuration
423 through --private-key, --certificate, and --ca-cert command line
424 options. Open vSwitch can be built without SSL support, in which case
425 these connection methods are not supported.
426
428 This section describes how to handle various events in the life cycle
429 of a database using the Open vSwitch implementation of OVSDB.
430 Creating a Database
432 Creating and starting up the service for a new database was covered
433 separately for each database service model in the Service Models sec‐
434 tion, above.
435 Backing Up and Restoring a Database
437 OVSDB is often used in contexts where the database contents are not
438 particularly valuable. For example, in many systems, the database for
439 configuring ovs-vswitchd is essentially rebuilt from scratch at boot
440 time. It is not worthwhile to back up these databases.
441 When OVSDB is used for valuable data, a backup strategy is worth con‐
443 sidering. One way is to use database replication, discussed above in
444 Database Replication which keeps an online, up-to-date copy of a data‐
445 base, possibly on a remote system. This works with all OVSDB service
446 models.
447 A more common backup strategy is to periodically take and store a snap‐
449 shot. For the standalone and active-backup service models, making a
450 copy of the database file, e.g. using cp, effectively makes a snapshot,
451 and because OVSDB database files are append-only, it works even if the
452 database is being modified when the snapshot takes place. This
453 approach does not work for clustered databases.
454 Another way to make a backup, which works with all OVSDB service mod‐
456 els, is to use ovsdb-client backup, which connects to a running data‐
457 base server and outputs an atomic snapshot of its schema and content,
458 in the same format used for standalone and active-backup databases.
459 Multiple options are also available when the time comes to restore a
461 database from a backup. For the standalone and active-backup service
462 models, one option is to stop the database server or servers, overwrite
463 the database file with the backup (e.g. with cp), and then restart the
464 servers. Another way, which works with any service model, is to use
465 ovsdb-client restore, which connects to a running database server and
466 replaces the data in one of its databases by a provided snapshot. The
467 advantage of ovsdb-client restore is that it causes zero downtime for
468 the database and its server. It has the downside that UUIDs of rows in
469 the restored database will differ from those in the snapshot, because
470 the OVSDB protocol does not allow clients to specify row UUIDs.
471 None of these approaches saves and restores data in columns that the
473 schema designates as ephemeral. This is by design: the designer of a
474 schema only marks a column as ephemeral if it is acceptable for its
475 data to be lost when a database server restarts.
476 Clustering and backup serve different purposes. Clustering increases
478 availability, but it does not protect against data loss if, for exam‐
479 ple, a malicious or malfunctioning OVSDB client deletes or tampers with
480 data.
481 Changing Database Service Model
483 Use ovsdb-tool create-cluster to create a clustered database from the
484 contents of a standalone database. Use ovsdb-tool backup to create a
485 standalone database from the contents of a clustered database.
486 Upgrading or Downgrading a Database
488 The evolution of a piece of software can require changes to the schemas
489 of the databases that it uses. For example, new features might require
490 new tables or new columns in existing tables, or conceptual changes
491 might require a database to be reorganized in other ways. In some
492 cases, the easiest way to deal with a change in a database schema is to
493 delete the existing database and start fresh with the new schema, espe‐
494 cially if the data in the database is easy to reconstruct. But in many
495 other cases, it is better to convert the database from one schema to
496 another.
497 The OVSDB implementation in Open vSwitch has built-in support for some
499 simple cases of converting a database from one schema to another. This
500 support can handle changes that add or remove database columns or
501 tables or that eliminate constraints (for example, changing a column
502 that must have exactly one value into one that has one or more values).
503 It can also handle changes that add constraints or make them stricter,
504 but only if the existing data in the database satisfies the new con‐
505 straints (for example, changing a column that has one or more values
506 into a column with exactly one value, if every row in the column has
507 exactly one value). The built-in conversion can cause data loss in
508 obvious ways, for example if the new schema removes tables or columns,
509 or indirectly, for example by deleting unreferenced rows in tables that
510 the new schema marks for garbage collection.
511 Converting a database can lose data, so it is wise to make a backup
513 beforehand.
514 To use OVSDB’s built-in support for schema conversion with a standalone
516 or active-backup database, first stop the database server or servers,
517 then use ovsdb-tool convert to convert it to the new schema, and then
518 restart the database server.
519 OVSDB also supports online database schema conversion for any of its
521 database service models. To convert a database online, use
522 ovsdb-client convert. The conversion is atomic, consistent, isolated,
523 and durable. ovsdb-server disconnects any clients connected when the
524 conversion takes place (except clients that use the set_db_change_aware
525 Open vSwitch extension RPC). Upon reconnection, clients will discover
526 that the schema has changed.
527 Schema versions and checksums (see Schemas above) can give hints about
529 whether a database needs to be converted to a new schema. If there is
530 any question, though, the needs-conversion command on ovsdb-tool and
531 ovsdb-client can provide a definitive answer.
532 Working with Database History
534 Both on-disk database formats that OVSDB supports are organized as a
535 stream of transaction records. Each record describes a change to the
536 database as a list of rows that were inserted or deleted or modified,
537 along with the details. Therefore, in normal operation, a database
538 file only grows, as each change causes another record to be appended at
539 the end. Usually, a user has no need to understand this file struc‐
540 ture. This section covers some exceptions.
541 Compacting Databases
543 If OVSDB database files were truly append-only, then over time they
544 would grow without bound. To avoid this problem, OVSDB can compact a
545 database file, that is, replace it by a new version that contains only
546 the current database contents, as if it had been inserted by a single
547 transaction. From time to time, ovsdb-server automatically compacts a
548 database that grows much larger than its minimum size.
549 Because ovsdb-server automatically compacts databases, it is usually
551 not necessary to compact them manually, but OVSDB still offers a few
552 ways to do it. First, ovsdb-tool compact can compact a standalone or
553 active-backup database that is not currently being served by
554 ovsdb-server (or otherwise locked for writing by another process). To
555 compact any database that is currently being served by ovsdb-server,
556 use ovs-appctl to send the ovsdb-server/compact command. Each server
557 in an active-backup or clustered database maintains its database file
558 independently, so to compact all of them, issue this command separately
559 on each server.
560 Viewing History
562 The ovsdb-tool utility’s show-log command displays the transaction
563 records in an OVSDB database file in a human-readable format. By
564 default, it shows minimal detail, but adding the option -m once or
565 twice increases the level of detail. In addition to the transaction
566 data, it shows the time and date of each transaction and any “comment”
567 added to the transaction by the client. The comments can be helpful
568 for quickly understanding a transaction; for example, ovs-vsctl adds
569 its command line to the transactions that it makes.
570 The show-log command works with both OVSDB file formats, but the
572 details of the output format differ. For active-backup and clustered
573 databases, the sequence of transactions in each server’s log will dif‐
574 fer, even at points when they reflect the same data.
575 Truncating History
577 It may occasionally be useful to “roll back” a database file to an ear‐
578 lier point. Because of the organization of OVSDB records, this is easy
579 to do. Start by noting the record number <i> of the first record to
580 delete in ovsdb-tool show-log output. Each record is two lines of
581 plain text, so trimming the log is as simple as running head -n <j>,
582 where <j> = 2 * <i>.
583 Corruption
585 When ovsdb-server opens an OVSDB database file, of any kind, it reads
586 as many transaction records as it can from the file until it reaches
587 the end of the file or it encounters a corrupted record. At that point
588 it stops reading and regards the data that it has read to this point as
589 the full contents of the database file, effectively rolling the data‐
590 base back to an earlier point.
591 Each transaction record contains an embedded SHA-1 checksum, which the
593 server verifies as it reads a database file. It detects corruption
594 when a checksum fails to verify. Even though SHA-1 is no longer con‐
595 sidered secure for use in cryptography, it is acceptable for this pur‐
596 pose because it is not used to defend against malicious attackers.
597 The first record in a standalone or active-backup database file speci‐
599 fies the schema. ovsdb-server will refuse to work with a database
600 where this record is corrupted, or with a clustered database file with
601 corruption in the first few records. Delete and recreate such a data‐
602 base, or restore it from a backup.
603 When ovsdb-server adds records to a database file in which it detected
605 corruption, it first truncates the file just after the last good
606 record.
607
609 RFC 7047, “The Open vSwitch Database Management Protocol.”
610 Open vSwitch implementations of generic OVSDB functionality:
612 ovsdb-server(1), ovsdb-client(1), ovsdb-tool(1).
613 Tools for working with databases that have specific OVSDB schemas:
615 ovs-vsctl(8), vtep-ctl(8), ovn-nbctl(8), ovn-sbctl(8).
616 OVSDB schemas for Open vSwitch and related functionality:
618 ovs-vswitchd.conf.db(5), vtep(5), ovn-nb(5), ovn-sb(5).
619
621 The Open vSwitch Development Community
622
624 2019, The Open vSwitch Development Community
6252.12 Sep 10, 2019 OVSDB(7)