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) project uses
28 two OVSDB schemas, documented as part of that project. Finally, Open
29 vSwitch includes the “VTEP” schema, documented in vtep(5) that many
30 third-party hardware switches support for configuring VXLAN, although
31 OVS itself does not directly use this schema.
32 The OVSDB protocol specification allows independent, interoperable im‐
34 plementations of OVSDB to be developed. Open vSwitch includes an OVSDB
35 server implementation named ovsdb-server(1), which supports several
36 protocol extensions documented in its manpage, and a basic command-line
37 OVSDB client named ovsdb-client(1), as well as OVSDB client libraries
38 for C and for Python. Open vSwitch documentation often speaks of these
39 OVSDB implementations in Open vSwitch as simply “OVSDB,” even though
40 that is distinct from the OVSDB protocol; we make the distinction ex‐
41 plicit only when it might otherwise be unclear from the context.
42 In addition to these generic OVSDB server and client tools, Open
44 vSwitch includes tools for working with databases that have specific
45 schemas: ovs-vsctl works with the ovs-vswitchd configuration database
46 and vtep-ctl works with the VTEP database.
47 RFC 7047 specifies the OVSDB protocol but it does not specify an
49 on-disk storage format. Open vSwitch includes ovsdb-tool(1) for work‐
50 ing with its own on-disk database formats. The most notable feature of
51 this format is that ovsdb-tool(1) makes it easy for users to print the
52 transactions that have changed a database since the last time it was
53 compacted. This feature is often useful for troubleshooting.
54
56 Schemas in OVSDB have a JSON format that is specified in RFC 7047.
57 They are often stored in files with an extension .ovsschema. An
58 on-disk database in OVSDB includes a schema and data, embedding both
59 into a single file. The Open vSwitch utility ovsdb-tool has commands
60 that work with schema files and with the schemas embedded in database
61 files.
62 An Open vSwitch schema has three important identifiers. The first is
64 its name, which is also the name used in JSON-RPC calls to identify a
65 database based on that schema. For example, the schema used to config‐
66 ure Open vSwitch has the name Open_vSwitch. Schema names begin with a
67 letter or an underscore, followed by any number of letters, under‐
68 scores, or digits. The ovsdb-tool commands schema-name and db-name ex‐
69 tract the schema name from a schema or database file, respectively.
70 An OVSDB schema also has a version of the form x.y.z e.g. 1.2.3.
72 Schemas managed within the Open vSwitch project manage version number‐
73 ing in the following way (but OVSDB does not mandate this approach).
74 Whenever we change the database schema in a non-backward compatible way
75 (e.g. when we delete a column or a table), we increment <x> and set <y>
76 and <z> to 0. When we change the database schema in a backward compat‐
77 ible way (e.g. when we add a new column), we increment <y> and set <z>
78 to 0. When we change the database schema cosmetically (e.g. we rein‐
79 dent its syntax), we increment <z>. The ovsdb-tool commands
80 schema-version and db-version extract the schema version from a schema
81 or database file, respectively.
82 Very old OVSDB schemas do not have a version, but RFC 7047 mandates it.
84 An OVSDB schema optionally has a “checksum.” RFC 7047 does not specify
86 the use of the checksum and recommends that clients ignore it. Open
87 vSwitch uses the checksum to remind developers to update the version:
88 at build time, if the schema’s embedded checksum, ignoring the checksum
89 field itself, does not match the schema’s content, then it fails the
90 build with a recommendation to update the version and the checksum.
91 Thus, a developer who changes the schema, but does not update the ver‐
92 sion, receives an automatic reminder. In practice this has been an ef‐
93 fective way to ensure compliance with the version number policy. The
94 ovsdb-tool commands schema-cksum and db-cksum extract the schema check‐
95 sum from a schema or database file, respectively.
96
98 OVSDB supports four service models for databases: standalone, ac‐
99 tive-backup, relay and clustered. The service models provide different
100 compromises among consistency, availability, and partition tolerance.
101 They also differ in the number of servers required and in terms of per‐
102 formance. The standalone and active-backup database service models
103 share one on-disk format, and clustered databases use a different for‐
104 mat, but the OVSDB programs work with both formats. ovsdb(5) documents
105 these file formats. Relay databases have no on-disk storage.
106 RFC 7047, which specifies the OVSDB protocol, does not mandate or spec‐
108 ify any particular service model.
109 The following sections describe the individual service models.
111 Standalone Database Service Model
113 A standalone database runs a single server. If the server stops run‐
114 ning, the database becomes inaccessible, and if the server’s storage is
115 lost or corrupted, the database’s content is lost. This service model
116 is appropriate when the database controls a process or activity to
117 which it is linked via “fate-sharing.” For example, an OVSDB instance
118 that controls an Open vSwitch virtual switch daemon, ovs-vswitchd, is a
119 standalone database because a server failure would take out both the
120 database and the virtual switch.
121 To set up a standalone database, use ovsdb-tool create to create a
123 database file, then run ovsdb-server to start the database service.
124 To configure a client, such as ovs-vswitchd or ovs-vsctl, to use a
126 standalone database, configure the server to listen on a “connection
127 method” that the client can reach, then point the client to that con‐
128 nection method. See Connection Methods below for information about
129 connection methods.
130 Active-Backup Database Service Model
132 An active-backup database runs two servers (on different hosts). At
133 any given time, one of the servers is designated with the active role
134 and the other the backup role. An active server behaves just like a
135 standalone server. A backup server makes an OVSDB connection to the
136 active server and uses it to continuously replicate its content as it
137 changes in real time. OVSDB clients can connect to either server but
138 only the active server allows data modification or lock transactions.
139 Setup for an active-backup database starts from a working standalone
141 database service, which is initially the active server. On another
142 node, to set up a backup server, create a database file with the same
143 schema as the active server. The initial contents of the database file
144 do not matter, as long as the schema is correct, so ovsdb-tool create
145 will work, as will copying the database file from the active server.
146 Then use ovsdb-server --sync-from=<active> to start the backup server,
147 where <active> is an OVSDB connection method (see Connection Methods
148 below) that connects to the active server. At that point, the backup
149 server will fetch a copy of the active database and keep it up-to-date
150 until it is killed.
151 When the active server in an active-backup server pair fails, an admin‐
153 istrator can switch the backup server to an active role with the
154 ovs-appctl command ovsdb-server/disconnect-active-ovsdb-server.
155 Clients then have read/write access to the now-active server. Of
156 course, administrators are slow to respond compared to software, so in
157 practice external management software detects the active server’s fail‐
158 ure and changes the backup server’s role. For example, the “Integra‐
159 tion Guide for Centralized Control” in the OVN documentation describes
160 how to use Pacemaker for this purpose in OVN.
161 Suppose an active server fails and its backup is promoted to active.
163 If the failed server is revived, it must be started as a backup server.
164 Otherwise, if both servers are active, then they may start out of sync,
165 if the database changed while the server was down, and they will con‐
166 tinue to diverge over time. This also happens if the software managing
167 the database servers cannot reach the active server and therefore
168 switches the backup to active, but other hosts can reach both servers.
169 These “split-brain” problems are unsolvable in general for server
170 pairs.
171 Compared to a standalone server, the active-backup service model some‐
173 what increases availability, at a risk of split-brain. It adds gener‐
174 ally insignificant performance overhead. On the other hand, the clus‐
175 tered service model, discussed below, requires at least 3 servers and
176 has greater performance overhead, but it avoids the need for external
177 management software and eliminates the possibility of split-brain.
178 Open vSwitch 2.6 introduced support for the active-backup service
180 model.
181 IMPORTANT:
183 There was a change of a database file format in version 2.15. To
184 upgrade/downgrade the ovsdb-server processes across this version
185 follow the instructions described under Upgrading from version 2.14
186 and earlier to 2.15 and later and Downgrading from version 2.15 and
187 later to 2.14 and earlier.
188 Another change happened in version 3.2. To upgrade/downgrade the
190 ovsdb-server processes across this version follow the instructions
191 described under Upgrading from version 3.1 and earlier to 3.2 and
192 later and Downgrading from version 3.2 and later to 3.1 and earlier.
193 Clustered Database Service Model
195 A clustered database runs across 3 or 5 or more database servers (the
196 cluster) on different hosts. Servers in a cluster automatically syn‐
197 chronize writes within the cluster. A 3-server cluster can remain
198 available in the face of at most 1 server failure; a 5-server cluster
199 tolerates up to 2 failures. Clusters larger than 5 servers will also
200 work, with every 2 added servers allowing the cluster to tolerate 1
201 more failure, but write performance decreases. The number of servers
202 should be odd: a 4- or 6-server cluster cannot tolerate more failures
203 than a 3- or 5-server cluster, respectively.
204 To set up a clustered database, first initialize it on a single node by
206 running ovsdb-tool create-cluster, then start ovsdb-server. Depending
207 on its arguments, the create-cluster command can create an empty data‐
208 base or copy a standalone database’s contents into the new database.
209 To configure a client to use a clustered database, first configure all
211 of the servers to listen on a connection method that the client can
212 reach, then point the client to all of the servers’ connection methods,
213 comma-separated. See Connection Methods, below, for more detail.
214 Open vSwitch 2.9 introduced support for the clustered service model.
216 How to Maintain a Clustered Database
218 To add a server to a cluster, run ovsdb-tool join-cluster on the new
219 server and start ovsdb-server. To remove a running server from a clus‐
220 ter, use ovs-appctl to invoke the cluster/leave command. When a server
221 fails and cannot be recovered, e.g. because its hard disk crashed, or
222 to otherwise remove a server that is down from a cluster, use ovs-ap‐
223 pctl to invoke cluster/kick to make the remaining servers kick it out
224 of the cluster.
225 The above methods for adding and removing servers only work for healthy
227 clusters, that is, for clusters with no more failures than their maxi‐
228 mum tolerance. For example, in a 3-server cluster, the failure of 2
229 servers prevents servers joining or leaving the cluster (as well as
230 database access). To prevent data loss or inconsistency, the preferred
231 solution to this problem is to bring up enough of the failed servers to
232 make the cluster healthy again, then if necessary remove any remaining
233 failed servers and add new ones. If this cannot be done, though, use
234 ovs-appctl to invoke cluster/leave --force on a running server. This
235 command forces the server to which it is directed to leave its cluster
236 and form a new single-node cluster that contains only itself. The data
237 in the new cluster may be inconsistent with the former cluster: trans‐
238 actions not yet replicated to the server will be lost, and transactions
239 not yet applied to the cluster may be committed. Afterward, any
240 servers in its former cluster will regard the server to have failed.
241 Once a server leaves a cluster, it may never rejoin it. Instead, cre‐
243 ate a new server and join it to the cluster.
244 The servers in a cluster synchronize data over a cluster management
246 protocol that is specific to Open vSwitch; it is not the same as the
247 OVSDB protocol specified in RFC 7047. For this purpose, a server in a
248 cluster is tied to a particular IP address and TCP port, which is spec‐
249 ified in the ovsdb-tool command that creates or joins the cluster. The
250 TCP port used for clustering must be different from that used for OVSDB
251 clients. To change the port or address of a server in a cluster, first
252 remove it from the cluster, then add it back with the new address.
253 To upgrade the ovsdb-server processes in a cluster from one version of
255 Open vSwitch to another, upgrading them one at a time will keep the
256 cluster healthy during the upgrade process. (This is different from
257 upgrading a database schema, which is covered later under Upgrading or
258 Downgrading a Database.)
259 IMPORTANT:
261 There was a change of a database file format in version 2.15. To
262 upgrade/downgrade the ovsdb-server processes across this version
263 follow the instructions described under Upgrading from version 2.14
264 and earlier to 2.15 and later and Downgrading from version 2.15 and
265 later to 2.14 and earlier.
266 Another change happened in version 3.2. To upgrade/downgrade the
268 ovsdb-server processes across this version follow the instructions
269 described under Upgrading from version 3.1 and earlier to 3.2 and
270 later and Downgrading from version 3.2 and later to 3.1 and earlier.
271 Clustered OVSDB does not support the OVSDB “ephemeral columns” feature.
273 ovsdb-tool and ovsdb-client change ephemeral columns into persistent
274 ones when they work with schemas for clustered databases. Future ver‐
275 sions of OVSDB might add support for this feature.
276 Upgrading from version 2.14 and earlier to 2.15 and later
278 There is a change of a database file format in version 2.15 that
279 doesn’t allow older versions of ovsdb-server to read the database file
280 modified by the ovsdb-server version 2.15 or later. This also affects
281 runtime communications between servers in active-backup and cluster
282 service models. To upgrade the ovsdb-server processes from one version
283 of Open vSwitch (2.14 or earlier) to another (2.15 or higher) instruc‐
284 tions below should be followed. (This is different from upgrading a
285 database schema, which is covered later under Upgrading or Downgrading
286 a Database.)
287 In case of standalone service model no special handling during upgrade
289 is required.
290 For the active-backup service model, administrator needs to update
292 backup ovsdb-server first and the active one after that, or shut down
293 both servers and upgrade at the same time.
294 For the cluster service model recommended upgrade strategy is follow‐
296 ing:
297 1. Upgrade processes one at a time. Each ovsdb-server process after
299 upgrade should be started with --disable-file-column-diff command
300 line argument.
301 2. When all ovsdb-server processes upgraded, use ovs-appctl to invoke
303 ovsdb/file/column-diff-enable command on each of them or restart all
304 ovsdb-server processes one at a time without --disable-file-col‐
305 umn-diff command line option.
306 Downgrading from version 2.15 and later to 2.14 and earlier
308 Similar to upgrading covered under Upgrading from version 2.14 and ear‐
309 lier to 2.15 and later, downgrading from the ovsdb-server version 2.15
310 and later to 2.14 and earlier requires additional steps. (This is dif‐
311 ferent from upgrading a database schema, which is covered later under
312 Upgrading or Downgrading a Database.)
313 For all service models it’s required to:
315 1. Stop all ovsdb-server processes (single process for standalone ser‐
317 vice model, all involved processes for active-backup and cluster
318 service models).
319 2. Compact all database files with ovsdb-tool compact command.
321 3. Downgrade and restart ovsdb-server processes.
323 Upgrading from version 3.1 and earlier to 3.2 and later
325 There is another change of a database file format in version 3.2 that
326 doesn’t allow older versions of ovsdb-server to read the database file
327 modified by the ovsdb-server version 3.2 or later. This also affects
328 runtime communications between servers in cluster service models. To
329 upgrade the ovsdb-server processes from one version of Open vSwitch
330 (3.1 or earlier) to another (3.2 or higher) instructions below should
331 be followed. (This is different from upgrading a database schema, which
332 is covered later under Upgrading or Downgrading a Database.)
333 In case of standalone or active-backup service model no special han‐
335 dling during upgrade is required.
336 For the cluster service model recommended upgrade strategy is follow‐
338 ing:
339 1. Upgrade processes one at a time. Each ovsdb-server process after
341 upgrade should be started with --disable-file-no-data-conversion
342 command line argument.
343 2. When all ovsdb-server processes upgraded, use ovs-appctl to invoke
345 ovsdb/file/no-data-conversion-enable command on each of them or
346 restart all ovsdb-server processes one at a time without --dis‐
347 able-file-no-data-conversion command line option.
348 Downgrading from version 3.2 and later to 3.1 and earlier
350 Similar to upgrading covered under Upgrading from version 3.1 and ear‐
351 lier to 3.2 and later, downgrading from the ovsdb-server version 3.2
352 and later to 3.1 and earlier requires additional steps. (This is dif‐
353 ferent from upgrading a database schema, which is covered later under
354 Upgrading or Downgrading a Database.)
355 For all service models it’s required to:
357 1. Compact all database files via ovsdb-server/compact command with
359 ovs-appctl utility. This should be done for each involved
360 ovsdb-server process separately (single process for standalone ser‐
361 vice model, all involved processes for active-backup and cluster
362 service models).
363 2. Stop all ovsdb-server processes. Make sure that no database schema
365 conversion operations were performed between steps 1 and 2. For
366 standalone and active-backup service models, the database compaction
367 can be performed after stopping all the processes instead with the
368 ovsdb-tool compact command.
369 3. Downgrade and restart ovsdb-server processes.
371 Understanding Cluster Consistency
373 To ensure consistency, clustered OVSDB uses the Raft algorithm de‐
374 scribed in Diego Ongaro’s Ph.D. thesis, “Consensus: Bridging Theory and
375 Practice”. In an operational Raft cluster, at any given time a single
376 server is the “leader” and the other nodes are “followers”. Only the
377 leader processes transactions, but a transaction is only committed when
378 a majority of the servers confirm to the leader that they have written
379 it to persistent storage.
380 In most database systems, read and write access to the database happens
382 through transactions. In such a system, Raft allows a cluster to
383 present a strongly consistent transactional interface. OVSDB uses con‐
384 ventional transactions for writes, but clients often effectively do
385 reads a different way, by asking the server to “monitor” a database or
386 a subset of one on the client’s behalf. Whenever monitored data
387 changes, the server automatically tells the client what changed, which
388 allows the client to maintain an accurate snapshot of the database in
389 its memory. Of course, at any given time, the snapshot may be somewhat
390 dated since some of it could have changed without the change notifica‐
391 tion yet being received and processed by the client.
392 Given this unconventional usage model, OVSDB also adopts an unconven‐
394 tional clustering model. Each server in a cluster acts independently
395 for the purpose of monitors and read-only transactions, without verify‐
396 ing that data is up-to-date with the leader. Servers forward transac‐
397 tions that write to the database to the leader for execution, ensuring
398 consistency. This has the following consequences:
399 • Transactions that involve writes, against any server in the cluster,
401 are linearizable if clients take care to use correct prerequisites,
402 which is the same condition required for linearizability in a stand‐
403 alone OVSDB. (Actually, “at-least-once” consistency, because OVSDB
404 does not have a session mechanism to drop duplicate transactions if a
405 connection drops after the server commits it but before the client
406 receives the result.)
407 • Read-only transactions can yield results based on a stale version of
409 the database, if they are executed against a follower. Transactions
410 on the leader always yield fresh results. (With monitors, as ex‐
411 plained above, a client can always see stale data even without clus‐
412 tering, so clustering does not change the consistency model for moni‐
413 tors.)
414 • Monitor-based (or read-heavy) workloads scale well across a cluster,
416 because clustering OVSDB adds no additional work or communication for
417 reads and monitors.
418 • A write-heavy client should connect to the leader, to avoid the over‐
420 head of followers forwarding transactions to the leader.
421 • When a client conducts a mix of read and write transactions across
423 more than one server in a cluster, it can see inconsistent results
424 because a read transaction might read stale data whose updates have
425 not yet propagated from the leader. By default, utilities such as
426 ovn-sbctl (in OVN) connect to the cluster leader to avoid this issue.
427 The same might occur for transactions against a single follower ex‐
429 cept that the OVSDB server ensures that the results of a write for‐
430 warded to the leader by a given server are visible at that server be‐
431 fore it replies to the requesting client.
432 • If a client uses a database on one server in a cluster, then another
434 server in the cluster (perhaps because the first server failed), the
435 client could observe stale data. Clustered OVSDB clients, however,
436 can use a column in the _Server database to detect that data on a
437 server is older than data that the client previously read. The OVSDB
438 client library in Open vSwitch uses this feature to avoid servers
439 with stale data.
440 Relay Service Model
442 A relay database is a way to scale out read-mostly access to the exist‐
443 ing database working in any service model including relay.
444 Relay database creates and maintains an OVSDB connection with another
446 OVSDB server. It uses this connection to maintain an in-memory copy of
447 the remote database (a.k.a. the relay source) keeping the copy
448 up-to-date as the database content changes on the relay source in the
449 real time.
450 The purpose of relay server is to scale out the number of database
452 clients. Read-only transactions and monitor requests are fully handled
453 by the relay server itself. For the transactions that request database
454 modifications, relay works as a proxy between the client and the relay
455 source, i.e. it forwards transactions and replies between them.
456 Compared to the clustered and active-backup models, relay service model
458 provides read and write access to the database similarly to a clustered
459 database (and even more scalable), but with generally insignificant
460 performance overhead of an active-backup model. At the same time it
461 doesn’t increase availability that needs to be covered by the service
462 model of the relay source.
463 Relay database has no on-disk storage and therefore cannot be converted
465 to any other service model.
466 If there is already a database started in any service model, to start a
468 relay database server use ovsdb-server relay:<DB_NAME>:<relay source>,
469 where <DB_NAME> is the database name as specified in the schema of the
470 database that existing server runs, and <relay source> is an OVSDB con‐
471 nection method (see Connection Methods below) that connects to the ex‐
472 isting database server. <relay source> could contain a comma-separated
473 list of connection methods, e.g. to connect to any server of the clus‐
474 tered database. Multiple relay servers could be started for the same
475 relay source.
476 Since the way relays handle read and write transactions is very similar
478 to the clustered model where “cluster” means “set of relay servers con‐
479 nected to the same relay source”, “follower” means “relay server” and
480 the “leader” means “relay source”, same consistency consequences as for
481 the clustered model applies to relay as well (See Understanding Cluster
482 Consistency above).
483 Open vSwitch 2.16 introduced support for relay service model.
485
487 OVSDB can layer replication on top of any of its service models.
488 Replication, in this context, means to make, and keep up-to-date, a
489 read-only copy of the contents of a database (the replica). One use of
490 replication is to keep an up-to-date backup of a database. A replica
491 used solely for backup would not need to support clients of its own. A
492 set of replicas that do serve clients could be used to scale out read
493 access to the primary database, however Relay Service Model is more
494 suitable for that purpose.
495 A database replica is set up in the same way as a backup server in an
497 active-backup pair, with the difference that the replica is never pro‐
498 moted to an active role.
499 A database can have multiple replicas.
501 Open vSwitch 2.6 introduced support for database replication.
503
505 An OVSDB connection method is a string that specifies how to make a
506 JSON-RPC connection between an OVSDB client and server. Connection
507 methods are part of the Open vSwitch implementation of OVSDB and not
508 specified by RFC 7047. ovsdb-server uses connection methods to specify
509 how it should listen for connections from clients and ovsdb-client uses
510 them to specify how it should connect to a server. Connections in the
511 opposite direction, where ovsdb-server connects to a client that is
512 configured to listen for an incoming connection, are also possible.
513 Connection methods are classified as active or passive. An active con‐
515 nection method makes an outgoing connection to a remote host; a passive
516 connection method listens for connections from remote hosts. The most
517 common arrangement is to configure an OVSDB server with passive connec‐
518 tion methods and clients with active ones, but the OVSDB implementation
519 in Open vSwitch supports the opposite arrangement as well.
520 OVSDB supports the following active connection methods:
522 ssl:<host>:<port>
524 The specified SSL or TLS <port> on the given <host>.
525 tcp:<host>:<port>
527 The specified TCP <port> on the given <host>.
528 unix:<file>
530 On Unix-like systems, connect to the Unix domain server socket
531 named <file>.
532 On Windows, connect to a local named pipe that is represented by
534 a file created in the path <file> to mimic the behavior of a
535 Unix domain socket.
536 <method1>,<method2>,…,<methodN>
538 For a clustered database service to be highly available, a
539 client must be able to connect to any of the servers in the
540 cluster. To do so, specify connection methods for each of the
541 servers separated by commas (and optional spaces).
542 In theory, if machines go up and down and IP addresses change in
544 the right way, a client could talk to the wrong instance of a
545 database. To avoid this possibility, add cid:<uuid> to the list
546 of methods, where <uuid> is the cluster ID of the desired data‐
547 base cluster, as printed by ovsdb-tool db-cid. This feature is
548 optional.
549 OVSDB supports the following passive connection methods:
551 pssl:<port>[:<ip>]
553 Listen on the given TCP <port> for SSL or TLS connections. By
554 default, connections are not bound to a particular local IP ad‐
555 dress. Specifying <ip> limits connections to those from the
556 given IP.
557 ptcp:<port>[:<ip>]
559 Listen on the given TCP <port>. By default, connections are not
560 bound to a particular local IP address. Specifying <ip> limits
561 connections to those from the given IP.
562 punix:<file>
564 On Unix-like systems, listens for connections on the Unix domain
565 socket named <file>.
566 On Windows, listens on a local named pipe, creating a named pipe
568 <file> to mimic the behavior of a Unix domain socket. The ACLs
569 of the named pipe include LocalSystem, Administrators, and Cre‐
570 ator Owner.
571 All IP-based connection methods accept IPv4 and IPv6 addresses. To
573 specify an IPv6 address, wrap it in square brackets, e.g.
574 ssl:[::1]:6640. Passive IP-based connection methods by default listen
575 for IPv4 connections only; use [::] as the address to accept both IPv4
576 and IPv6 connections, e.g. pssl:6640:[::]. DNS names are also accepted
577 if built with unbound library. On Linux, use %<device> to designate a
578 scope for IPv6 link-level addresses, e.g. ssl:[fe80::1234%eth0]:6653.
579 The <port> may be omitted from connection methods that use a port num‐
581 ber. The default <port> for TCP-based connection methods is 6640, e.g.
582 pssl: is equivalent to pssl:6640. In Open vSwitch prior to version
583 2.4.0, the default port was 6632. To avoid incompatibility between
584 older and newer versions, we encourage users to specify a port number.
585 The ssl and pssl connection methods requires additional configuration
587 through --private-key, --certificate, and --ca-cert command line op‐
588 tions. Open vSwitch can be built without SSL support, in which case
589 these connection methods are not supported.
590
592 This section describes how to handle various events in the life cycle
593 of a database using the Open vSwitch implementation of OVSDB.
594 Creating a Database
596 Creating and starting up the service for a new database was covered
597 separately for each database service model in the Service Models sec‐
598 tion, above.
599 Backing Up and Restoring a Database
601 OVSDB is often used in contexts where the database contents are not
602 particularly valuable. For example, in many systems, the database for
603 configuring ovs-vswitchd is essentially rebuilt from scratch at boot
604 time. It is not worthwhile to back up these databases.
605 When OVSDB is used for valuable data, a backup strategy is worth con‐
607 sidering. One way is to use database replication, discussed above in
608 Database Replication which keeps an online, up-to-date copy of a data‐
609 base, possibly on a remote system. This works with all OVSDB service
610 models.
611 A more common backup strategy is to periodically take and store a snap‐
613 shot. For the standalone and active-backup service models, making a
614 copy of the database file, e.g. using cp, effectively makes a snapshot,
615 and because OVSDB database files are append-only, it works even if the
616 database is being modified when the snapshot takes place. This ap‐
617 proach does not work for clustered databases.
618 Another way to make a backup, which works with all OVSDB service mod‐
620 els, is to use ovsdb-client backup, which connects to a running data‐
621 base server and outputs an atomic snapshot of its schema and content,
622 in the same format used for standalone and active-backup databases.
623 Multiple options are also available when the time comes to restore a
625 database from a backup. For the standalone and active-backup service
626 models, one option is to stop the database server or servers, overwrite
627 the database file with the backup (e.g. with cp), and then restart the
628 servers. Another way, which works with any service model, is to use
629 ovsdb-client restore, which connects to a running database server and
630 replaces the data in one of its databases by a provided snapshot. The
631 advantage of ovsdb-client restore is that it causes zero downtime for
632 the database and its server. It has the downside that UUIDs of rows in
633 the restored database will differ from those in the snapshot, because
634 the OVSDB protocol does not allow clients to specify row UUIDs.
635 None of these approaches saves and restores data in columns that the
637 schema designates as ephemeral. This is by design: the designer of a
638 schema only marks a column as ephemeral if it is acceptable for its
639 data to be lost when a database server restarts.
640 Clustering and backup serve different purposes. Clustering increases
642 availability, but it does not protect against data loss if, for exam‐
643 ple, a malicious or malfunctioning OVSDB client deletes or tampers with
644 data.
645 Changing Database Service Model
647 Use ovsdb-tool create-cluster to create a clustered database from the
648 contents of a standalone database. Use ovsdb-client backup to create a
649 standalone database from the contents of a running clustered database.
650 When the cluster is down and cannot be revived, ovsdb-client backup
651 will not work.
652 Use ovsdb-tool cluster-to-standalone to convert clustered database to
654 standalone database when the cluster is down and cannot be revived.
655 Upgrading or Downgrading a Database
657 The evolution of a piece of software can require changes to the schemas
658 of the databases that it uses. For example, new features might require
659 new tables or new columns in existing tables, or conceptual changes
660 might require a database to be reorganized in other ways. In some
661 cases, the easiest way to deal with a change in a database schema is to
662 delete the existing database and start fresh with the new schema, espe‐
663 cially if the data in the database is easy to reconstruct. But in many
664 other cases, it is better to convert the database from one schema to
665 another.
666 The OVSDB implementation in Open vSwitch has built-in support for some
668 simple cases of converting a database from one schema to another. This
669 support can handle changes that add or remove database columns or ta‐
670 bles or that eliminate constraints (for example, changing a column that
671 must have exactly one value into one that has one or more values). It
672 can also handle changes that add constraints or make them stricter, but
673 only if the existing data in the database satisfies the new constraints
674 (for example, changing a column that has one or more values into a col‐
675 umn with exactly one value, if every row in the column has exactly one
676 value). The built-in conversion can cause data loss in obvious ways,
677 for example if the new schema removes tables or columns, or indirectly,
678 for example by deleting unreferenced rows in tables that the new schema
679 marks for garbage collection.
680 Converting a database can lose data, so it is wise to make a backup be‐
682 forehand.
683 To use OVSDB’s built-in support for schema conversion with a standalone
685 or active-backup database, first stop the database server or servers,
686 then use ovsdb-tool convert to convert it to the new schema, and then
687 restart the database server.
688 OVSDB also supports online database schema conversion for any of its
690 database service models. To convert a database online, use
691 ovsdb-client convert. The conversion is atomic, consistent, isolated,
692 and durable. ovsdb-server disconnects any clients connected when the
693 conversion takes place (except clients that use the set_db_change_aware
694 Open vSwitch extension RPC). Upon reconnection, clients will discover
695 that the schema has changed.
696 Schema versions and checksums (see Schemas above) can give hints about
698 whether a database needs to be converted to a new schema. If there is
699 any question, though, the needs-conversion command on ovsdb-tool and
700 ovsdb-client can provide a definitive answer.
701 Working with Database History
703 Both on-disk database formats that OVSDB supports are organized as a
704 stream of transaction records. Each record describes a change to the
705 database as a list of rows that were inserted or deleted or modified,
706 along with the details. Therefore, in normal operation, a database
707 file only grows, as each change causes another record to be appended at
708 the end. Usually, a user has no need to understand this file struc‐
709 ture. This section covers some exceptions.
710 Compacting Databases
712 If OVSDB database files were truly append-only, then over time they
713 would grow without bound. To avoid this problem, OVSDB can compact a
714 database file, that is, replace it by a new version that contains only
715 the current database contents, as if it had been inserted by a single
716 transaction. From time to time, ovsdb-server automatically compacts a
717 database that grows much larger than its minimum size.
718 Because ovsdb-server automatically compacts databases, it is usually
720 not necessary to compact them manually, but OVSDB still offers a few
721 ways to do it. First, ovsdb-tool compact can compact a standalone or
722 active-backup database that is not currently being served by
723 ovsdb-server (or otherwise locked for writing by another process). To
724 compact any database that is currently being served by ovsdb-server,
725 use ovs-appctl to send the ovsdb-server/compact command. Each server
726 in an active-backup or clustered database maintains its database file
727 independently, so to compact all of them, issue this command separately
728 on each server.
729 Viewing History
731 The ovsdb-tool utility’s show-log command displays the transaction
732 records in an OVSDB database file in a human-readable format. By de‐
733 fault, it shows minimal detail, but adding the option -m once or twice
734 increases the level of detail. In addition to the transaction data, it
735 shows the time and date of each transaction and any “comment” added to
736 the transaction by the client. The comments can be helpful for quickly
737 understanding a transaction; for example, ovs-vsctl adds its command
738 line to the transactions that it makes.
739 The show-log command works with both OVSDB file formats, but the de‐
741 tails of the output format differ. For active-backup and clustered
742 databases, the sequence of transactions in each server’s log will dif‐
743 fer, even at points when they reflect the same data.
744 Truncating History
746 It may occasionally be useful to “roll back” a database file to an ear‐
747 lier point. Because of the organization of OVSDB records, this is easy
748 to do. Start by noting the record number <i> of the first record to
749 delete in ovsdb-tool show-log output. Each record is two lines of
750 plain text, so trimming the log is as simple as running head -n <j>,
751 where <j> = 2 * <i>.
752 Corruption
754 When ovsdb-server opens an OVSDB database file, of any kind, it reads
755 as many transaction records as it can from the file until it reaches
756 the end of the file or it encounters a corrupted record. At that point
757 it stops reading and regards the data that it has read to this point as
758 the full contents of the database file, effectively rolling the data‐
759 base back to an earlier point.
760 Each transaction record contains an embedded SHA-1 checksum, which the
762 server verifies as it reads a database file. It detects corruption
763 when a checksum fails to verify. Even though SHA-1 is no longer con‐
764 sidered secure for use in cryptography, it is acceptable for this pur‐
765 pose because it is not used to defend against malicious attackers.
766 The first record in a standalone or active-backup database file speci‐
768 fies the schema. ovsdb-server will refuse to work with a database
769 where this record is corrupted, or with a clustered database file with
770 corruption in the first few records. Delete and recreate such a data‐
771 base, or restore it from a backup.
772 When ovsdb-server adds records to a database file in which it detected
774 corruption, it first truncates the file just after the last good
775 record.
776
778 RFC 7047, “The Open vSwitch Database Management Protocol.”
779 Open vSwitch implementations of generic OVSDB functionality:
781 ovsdb-server(1), ovsdb-client(1), ovsdb-tool(1).
782 Tools for working with databases that have specific OVSDB schemas:
784 ovs-vsctl(8), vtep-ctl(8), and (in OVN) ovn-nbctl(8), ovn-sbctl(8).
785 OVSDB schemas for Open vSwitch and related functionality:
787 ovs-vswitchd.conf.db(5), vtep(5), and (in OVN) ovn-nb(5), ovn-sb(5).
788
790 The Open vSwitch Development Community
791
793 2016-2023, The Open vSwitch Development Community
7943.2 Oct 04, 2023 OVSDB(7)