1OVSDB(7)                         Open vSwitch                         OVSDB(7)
2
3
4

NAME

6       ovsdb - Open vSwitch Database (Overview)
7

DESCRIPTION

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
16       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
23       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
33       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
44       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
50       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

SCHEMAS

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
65       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
73       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
85       Very old OVSDB schemas do not have a version, but RFC 7047 mandates it.
86
87       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

SERVICE MODELS

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
109       RFC 7047, which specifies the OVSDB protocol, does not mandate or spec‐
110       ify any particular service model.
111
112       The following sections describe the individual service models.
113
114   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
124       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
127       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
133   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
142       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
154       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
164       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
174       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
181       Open  vSwitch  2.6  introduced  support  for  the active-backup service
182       model.
183
184   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
195       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
200       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
206       Open vSwitch 2.9 introduced support for the clustered service model.
207
208   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
217       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
233       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
236       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
245       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
251       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
256   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
265       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
277       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
284       · 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
292       · 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
299       · 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
303       · A write-heavy client should connect to the leader, to avoid the over‐
304         head of followers forwarding transactions to the leader.
305
306       · 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
312         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
317       · 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

DATABASE REPLICATION

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
334       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
338       A database can have multiple replicas.
339
340       Open vSwitch 2.6 introduced support for database replication.
341

CONNECTION METHODS

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
352       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
359       OVSDB supports the following active connection methods:
360
361       ssl:<host>:<port>
362              The specified SSL or TLS <port> on the given <host>.
363
364       tcp:<host>:<port>
365              The specified TCP <port> on the given <host>.
366
367       unix:<file>
368              On Unix-like systems, connect to the Unix domain  server  socket
369              named <file>.
370
371              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
375       <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
381              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
388       OVSDB supports the following passive connection methods:
389
390       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
396       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
401       punix:<file>
402              On Unix-like systems, listens for connections on the Unix domain
403              socket named <file>.
404
405              On Windows, listens on a local named pipe, creating a named pipe
406              <file> to mimic the behavior of a Unix domain socket.
407
408       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
416       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
422       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

DATABASE LIFE CYCLE

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
431   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
436   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
442       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
448       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
455       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
460       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
472       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
477       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
482   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
487   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
498       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
512       Converting  a  database  can  lose data, so it is wise to make a backup
513       beforehand.
514
515       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
520       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
528       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
533   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
542   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
550       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
561   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
571       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
576   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
584   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
592       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
598       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
604       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

SEE ALSO

609       RFC 7047, “The Open vSwitch Database Management Protocol.”
610
611       Open  vSwitch   implementations   of   generic   OVSDB   functionality:
612       ovsdb-server(1), ovsdb-client(1), ovsdb-tool(1).
613
614       Tools  for  working  with  databases  that have specific OVSDB schemas:
615       ovs-vsctl(8), vtep-ctl(8), ovn-nbctl(8), ovn-sbctl(8).
616
617       OVSDB   schemas   for   Open   vSwitch   and   related   functionality:
618       ovs-vswitchd.conf.db(5), vtep(5), ovn-nb(5), ovn-sb(5).
619

AUTHOR

621       The Open vSwitch Development Community
622
624       2020, The Open vSwitch Development Community
625
626
627
628
6292.12                             Jan 29, 2020                         OVSDB(7)
Impressum