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       The  servers  in  a  cluster synchronize data over a cluster management
234       protocol that is specific to Open vSwitch; it is not the  same  as  the
235       OVSDB  protocol specified in RFC 7047.  For this purpose, a server in a
236       cluster is tied to a particular IP address and TCP port, which is spec‐
237       ified in the ovsdb-tool command that creates or joins the cluster.  The
238       TCP port used for clustering must be different from that used for OVSDB
239       clients.  To change the port or address of a server in a cluster, first
240       remove it from the cluster, then add it back with the new address.
241
242       To upgrade the ovsdb-server processes in a cluster from one version  of
243       Open  vSwitch  to  another,  upgrading them one at a time will keep the
244       cluster healthy during the upgrade process.  (This  is  different  from
245       upgrading  a database schema, which is covered later under Upgrading or
246       Downgrading a Database.)
247
248       Clustered OVSDB does not support the OVSDB “ephemeral columns” feature.
249       ovsdb-tool  and  ovsdb-client  change ephemeral columns into persistent
250       ones when they work with schemas for clustered databases.  Future  ver‐
251       sions of OVSDB might add support for this feature.
252
253   Understanding Cluster Consistency
254       To   ensure  consistency,  clustered  OVSDB  uses  the  Raft  algorithm
255       described in Diego Ongaro’s Ph.D. thesis, “Consensus:  Bridging  Theory
256       and  Practice”.   In  an  operational Raft cluster, at any given time a
257       single server is the “leader” and  the  other  nodes  are  “followers”.
258       Only  the leader processes transactions, but a transaction is only com‐
259       mitted when a majority of the servers confirm to the leader  that  they
260       have written it to persistent storage.
261
262       In most database systems, read and write access to the database happens
263       through transactions.  In such a  system,  Raft  allows  a  cluster  to
264       present a strongly consistent transactional interface.  OVSDB uses con‐
265       ventional transactions for writes, but  clients  often  effectively  do
266       reads  a different way, by asking the server to “monitor” a database or
267       a subset of one  on  the  client’s  behalf.   Whenever  monitored  data
268       changes,  the server automatically tells the client what changed, which
269       allows the client to maintain an accurate snapshot of the  database  in
270       its memory.  Of course, at any given time, the snapshot may be somewhat
271       dated since some of it could have changed without the change  notifica‐
272       tion yet being received and processed by the client.
273
274       Given  this  unconventional usage model, OVSDB also adopts an unconven‐
275       tional clustering model.  Each server in a cluster  acts  independently
276       for the purpose of monitors and read-only transactions, without verify‐
277       ing that data is up-to-date with the leader.  Servers forward  transac‐
278       tions  that write to the database to the leader for execution, ensuring
279       consistency.  This has the following consequences:
280
281       · Transactions that involve writes, against any server in the  cluster,
282         are  linearizable  if clients take care to use correct prerequisites,
283         which is the same condition required for linearizability in a  stand‐
284         alone  OVSDB.   (Actually, “at-least-once” consistency, because OVSDB
285         does not have a session mechanism to drop duplicate transactions if a
286         connection  drops  after  the server commits it but before the client
287         receives the result.)
288
289       · Read-only transactions can yield results based on a stale version  of
290         the  database, if they are executed against a follower.  Transactions
291         on the  leader  always  yield  fresh  results.   (With  monitors,  as
292         explained  above,  a  client  can  always see stale data even without
293         clustering, so clustering does not change the consistency  model  for
294         monitors.)
295
296       · Monitor-based  (or read-heavy) workloads scale well across a cluster,
297         because clustering OVSDB adds no additional work or communication for
298         reads and monitors.
299
300       · A write-heavy client should connect to the leader, to avoid the over‐
301         head of followers forwarding transactions to the leader.
302
303       · When a client conducts a mix of read and  write  transactions  across
304         more  than  one  server in a cluster, it can see inconsistent results
305         because a read transaction might read stale data whose  updates  have
306         not  yet propagated from the leader.  By default, ovn-sbctl and simi‐
307         lar utilities connect to the cluster leader to avoid this issue.
308
309         The same might occur  for  transactions  against  a  single  follower
310         except that the OVSDB server ensures that the results of a write for‐
311         warded to the leader by a given server are  visible  at  that  server
312         before it replies to the requesting client.
313
314       · If  a client uses a database on one server in a cluster, then another
315         server in the cluster (perhaps because the first server failed),  the
316         client  could  observe stale data.  Clustered OVSDB clients, however,
317         can use a column in the _Server database to detect  that  data  on  a
318         server is older than data that the client previously read.  The OVSDB
319         client library in Open vSwitch uses this  feature  to  avoid  servers
320         with stale data.
321

DATABASE REPLICATION

323       OVSDB  can  layer  replication  on  top  of  any of its service models.
324       Replication, in this context, means to make,  and  keep  up-to-date,  a
325       read-only copy of the contents of a database (the replica).  One use of
326       replication is to keep an up-to-date backup of a database.   A  replica
327       used solely for backup would not need to support clients of its own.  A
328       set of replicas that do serve clients could be used to scale  out  read
329       access to the primary database.
330
331       A  database  replica is set up in the same way as a backup server in an
332       active-backup pair, with the difference that the replica is never  pro‐
333       moted to an active role.
334
335       A database can have multiple replicas.
336
337       Open vSwitch 2.6 introduced support for database replication.
338

CONNECTION METHODS

340       An  OVSDB  connection  method  is a string that specifies how to make a
341       JSON-RPC connection between an OVSDB  client  and  server.   Connection
342       methods  are  part  of the Open vSwitch implementation of OVSDB and not
343       specified by RFC 7047.  ovsdb-server uses connection methods to specify
344       how it should listen for connections from clients and ovsdb-client uses
345       them to specify how it should connect to a server.  Connections in  the
346       opposite  direction,  where  ovsdb-server  connects to a client that is
347       configured to listen for an incoming connection, are also possible.
348
349       Connection methods are classified as active or passive.  An active con‐
350       nection method makes an outgoing connection to a remote host; a passive
351       connection method listens for connections from remote hosts.  The  most
352       common arrangement is to configure an OVSDB server with passive connec‐
353       tion methods and clients with active ones, but the OVSDB implementation
354       in Open vSwitch supports the opposite arrangement as well.
355
356       OVSDB supports the following active connection methods:
357
358       ssl:<host>:<port>
359              The specified SSL or TLS <port> on the given <host>.
360
361       tcp:<host>:<port>
362              The specified TCP <port> on the given <host>.
363
364       unix:<file>
365              On  Unix-like  systems, connect to the Unix domain server socket
366              named <file>.
367
368              On Windows, connect to a local named pipe that is represented by
369              a  file  created  in  the path <file> to mimic the behavior of a
370              Unix domain socket.
371
372       <method1>,<method2>,…,<methodN>
373              For a clustered database  service  to  be  highly  available,  a
374              client  must  be  able  to  connect to any of the servers in the
375              cluster.  To do so, specify connection methods for each  of  the
376              servers separated by commas (and optional spaces).
377
378              In theory, if machines go up and down and IP addresses change in
379              the right way, a client could talk to the wrong  instance  of  a
380              database.  To avoid this possibility, add cid:<uuid> to the list
381              of methods, where <uuid> is the cluster ID of the desired  data‐
382              base cluster, as printed by ovsdb-tool get-cid.  This feature is
383              optional.
384
385       OVSDB supports the following passive connection methods:
386
387       pssl:<port>[:<ip>]
388              Listen on the given TCP <port> for SSL or TLS  connections.   By
389              default,  connections  are  not  bound  to a particular local IP
390              address.  Specifying <ip> limits connections to those  from  the
391              given IP.
392
393       ptcp:<port>[:<ip>]
394              Listen on the given TCP <port>.  By default, connections are not
395              bound to a particular local IP address.  Specifying <ip>  limits
396              connections to those from the given IP.
397
398       punix:<file>
399              On Unix-like systems, listens for connections on the Unix domain
400              socket named <file>.
401
402              On Windows, listens on a local named pipe, creating a named pipe
403              <file> to mimic the behavior of a Unix domain socket.
404
405       All  IP-based  connection  methods  accept IPv4 and IPv6 addresses.  To
406       specify  an  IPv6  address,  wrap   it   in   square   brackets,   e.g.
407       ssl:[::1]:6640.   Passive IP-based connection methods by default listen
408       for IPv4 connections only; use [::] as the address to accept both  IPv4
409       and IPv6 connections, e.g. pssl:6640:[::].  DNS names are also accepted
410       if built with unbound library.  On Linux, use %<device> to designate  a
411       scope for IPv6 link-level addresses, e.g. ssl:[fe80::1234%eth0]:6653.
412
413       The  <port> may be omitted from connection methods that use a port num‐
414       ber.  The default <port> for TCP-based connection methods is 6640, e.g.
415       pssl:  is  equivalent  to  pssl:6640.  In Open vSwitch prior to version
416       2.4.0, the default port was 6632.   To  avoid  incompatibility  between
417       older and newer versions, we encourage users to specify a port number.
418
419       The  ssl  and pssl connection methods requires additional configuration
420       through  --private-key,  --certificate,  and  --ca-cert  command   line
421       options.   Open vSwitch can be built without SSL support, in which case
422       these connection methods are not supported.
423

DATABASE LIFE CYCLE

425       This section describes how to handle various events in the  life  cycle
426       of a database using the Open vSwitch implementation of OVSDB.
427
428   Creating a Database
429       Creating  and  starting  up  the service for a new database was covered
430       separately for each database service model in the Service  Models  sec‐
431       tion, above.
432
433   Backing Up and Restoring a Database
434       OVSDB  is  often  used  in contexts where the database contents are not
435       particularly valuable.  For example, in many systems, the database  for
436       configuring  ovs-vswitchd  is  essentially rebuilt from scratch at boot
437       time.  It is not worthwhile to back up these databases.
438
439       When OVSDB is used for valuable data, a backup strategy is  worth  con‐
440       sidering.   One  way is to use database replication, discussed above in
441       Database Replication which keeps an online, up-to-date copy of a  data‐
442       base,  possibly  on a remote system.  This works with all OVSDB service
443       models.
444
445       A more common backup strategy is to periodically take and store a snap‐
446       shot.   For  the  standalone and active-backup service models, making a
447       copy of the database file, e.g. using cp, effectively makes a snapshot,
448       and  because OVSDB database files are append-only, it works even if the
449       database is  being  modified  when  the  snapshot  takes  place.   This
450       approach does not work for clustered databases.
451
452       Another  way  to make a backup, which works with all OVSDB service mod‐
453       els, is to use ovsdb-client backup, which connects to a  running  data‐
454       base  server  and outputs an atomic snapshot of its schema and content,
455       in the same format used for standalone and active-backup databases.
456
457       Multiple options are also available when the time comes  to  restore  a
458       database  from  a backup.  For the standalone and active-backup service
459       models, one option is to stop the database server or servers, overwrite
460       the  database file with the backup (e.g. with cp), and then restart the
461       servers.  Another way, which works with any service model,  is  to  use
462       ovsdb-client  restore,  which connects to a running database server and
463       replaces the data in one of its databases by a provided snapshot.   The
464       advantage  of  ovsdb-client restore is that it causes zero downtime for
465       the database and its server.  It has the downside that UUIDs of rows in
466       the  restored  database will differ from those in the snapshot, because
467       the OVSDB protocol does not allow clients to specify row UUIDs.
468
469       None of these approaches saves and restores data in  columns  that  the
470       schema  designates  as ephemeral.  This is by design: the designer of a
471       schema only marks a column as ephemeral if it  is  acceptable  for  its
472       data to be lost when a database server restarts.
473
474       Clustering  and  backup serve different purposes.  Clustering increases
475       availability, but it does not protect against data loss if,  for  exam‐
476       ple, a malicious or malfunctioning OVSDB client deletes or tampers with
477       data.
478
479   Changing Database Service Model
480       Use ovsdb-tool create-cluster to create a clustered database  from  the
481       contents  of  a standalone database.  Use ovsdb-tool backup to create a
482       standalone database from the contents of a clustered database.
483
484   Upgrading or Downgrading a Database
485       The evolution of a piece of software can require changes to the schemas
486       of the databases that it uses.  For example, new features might require
487       new tables or new columns in existing  tables,  or  conceptual  changes
488       might  require  a  database  to  be reorganized in other ways.  In some
489       cases, the easiest way to deal with a change in a database schema is to
490       delete the existing database and start fresh with the new schema, espe‐
491       cially if the data in the database is easy to reconstruct.  But in many
492       other  cases,  it  is better to convert the database from one schema to
493       another.
494
495       The OVSDB implementation in Open vSwitch has built-in support for  some
496       simple cases of converting a database from one schema to another.  This
497       support can handle changes that  add  or  remove  database  columns  or
498       tables  or  that  eliminate constraints (for example, changing a column
499       that must have exactly one value into one that has one or more values).
500       It  can also handle changes that add constraints or make them stricter,
501       but only if the existing data in the database satisfies  the  new  con‐
502       straints  (for  example,  changing a column that has one or more values
503       into a column with exactly one value, if every row in  the  column  has
504       exactly  one  value).   The  built-in conversion can cause data loss in
505       obvious ways, for example if the new schema removes tables or  columns,
506       or indirectly, for example by deleting unreferenced rows in tables that
507       the new schema marks for garbage collection.
508
509       Converting a database can lose data, so it is wise  to  make  a  backup
510       beforehand.
511
512       To use OVSDB’s built-in support for schema conversion with a standalone
513       or active-backup database, first stop the database server  or  servers,
514       then  use  ovsdb-tool convert to convert it to the new schema, and then
515       restart the database server.
516
517       OVSDB also supports online database schema conversion for  any  of  its
518       database   service   models.    To   convert  a  database  online,  use
519       ovsdb-client convert.  The conversion is atomic, consistent,  isolated,
520       and  durable.   ovsdb-server disconnects any clients connected when the
521       conversion takes place (except clients that use the set_db_change_aware
522       Open  vSwitch extension RPC).  Upon reconnection, clients will discover
523       that the schema has changed.
524
525       Schema versions and checksums (see Schemas above) can give hints  about
526       whether  a database needs to be converted to a new schema.  If there is
527       any question, though, the needs-conversion command  on  ovsdb-tool  and
528       ovsdb-client can provide a definitive answer.
529
530   Working with Database History
531       Both  on-disk  database  formats that OVSDB supports are organized as a
532       stream of transaction records.  Each record describes a change  to  the
533       database  as  a list of rows that were inserted or deleted or modified,
534       along with the details.  Therefore, in  normal  operation,  a  database
535       file only grows, as each change causes another record to be appended at
536       the end.  Usually, a user has no need to understand  this  file  struc‐
537       ture.  This section covers some exceptions.
538
539   Compacting Databases
540       If  OVSDB  database  files  were truly append-only, then over time they
541       would grow without bound.  To avoid this problem, OVSDB can  compact  a
542       database  file, that is, replace it by a new version that contains only
543       the current database contents, as if it had been inserted by  a  single
544       transaction.   From time to time, ovsdb-server automatically compacts a
545       database that grows much larger than its minimum size.
546
547       Because ovsdb-server automatically compacts databases,  it  is  usually
548       not  necessary  to  compact them manually, but OVSDB still offers a few
549       ways to do it.  First, ovsdb-tool compact can compact a  standalone  or
550       active-backup   database   that   is  not  currently  being  served  by
551       ovsdb-server (or otherwise locked for writing by another process).   To
552       compact  any  database  that is currently being served by ovsdb-server,
553       use ovs-appctl to send the ovsdb-server/compact command.   Each  server
554       in  an  active-backup or clustered database maintains its database file
555       independently, so to compact all of them, issue this command separately
556       on each server.
557
558   Viewing History
559       The  ovsdb-tool  utility’s  show-log  command  displays the transaction
560       records in an OVSDB database  file  in  a  human-readable  format.   By
561       default,  it  shows  minimal  detail,  but adding the option -m once or
562       twice increases the level of detail.  In addition  to  the  transaction
563       data,  it shows the time and date of each transaction and any “comment”
564       added to the transaction by the client.  The comments  can  be  helpful
565       for  quickly  understanding  a transaction; for example, ovs-vsctl adds
566       its command line to the transactions that it makes.
567
568       The show-log command works  with  both  OVSDB  file  formats,  but  the
569       details  of  the output format differ.  For active-backup and clustered
570       databases, the sequence of transactions in each server’s log will  dif‐
571       fer, even at points when they reflect the same data.
572
573   Truncating History
574       It may occasionally be useful to “roll back” a database file to an ear‐
575       lier point.  Because of the organization of OVSDB records, this is easy
576       to  do.   Start  by noting the record number <i> of the first record to
577       delete in ovsdb-tool show-log output.  Each  record  is  two  lines  of
578       plain  text,  so  trimming the log is as simple as running head -n <j>,
579       where <j> = 2 * <i>.
580
581   Corruption
582       When ovsdb-server opens an OVSDB database file, of any kind,  it  reads
583       as  many  transaction  records as it can from the file until it reaches
584       the end of the file or it encounters a corrupted record.  At that point
585       it stops reading and regards the data that it has read to this point as
586       the full contents of the database file, effectively rolling  the  data‐
587       base back to an earlier point.
588
589       Each  transaction record contains an embedded SHA-1 checksum, which the
590       server verifies as it reads a database  file.   It  detects  corruption
591       when  a  checksum fails to verify.  Even though SHA-1 is no longer con‐
592       sidered secure for use in cryptography, it is acceptable for this  pur‐
593       pose because it is not used to defend against malicious attackers.
594
595       The  first record in a standalone or active-backup database file speci‐
596       fies the schema.  ovsdb-server will refuse  to  work  with  a  database
597       where  this record is corrupted, or with a clustered database file with
598       corruption in the first few records.  Delete and recreate such a  data‐
599       base, or restore it from a backup.
600
601       When  ovsdb-server adds records to a database file in which it detected
602       corruption, it first truncates  the  file  just  after  the  last  good
603       record.
604

SEE ALSO

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

AUTHOR

618       The Open vSwitch Development Community
619
621       2016, The Open vSwitch Development Community
622
623
624
625
6262.10                             Nov 11, 2018                         OVSDB(7)
Impressum