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) 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
33       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
43       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
48       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

SCHEMAS

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
63       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
71       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
83       Very old OVSDB schemas do not have a version, but RFC 7047 mandates it.
84
85       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

SERVICE MODELS

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
107       RFC 7047, which specifies the OVSDB protocol, does not mandate or spec‐
108       ify any particular service model.
109
110       The following sections describe the individual service models.
111
112   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
122       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
125       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
131   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
140       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
152       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
162       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
172       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
179       Open  vSwitch  2.6  introduced  support  for  the active-backup service
180       model.
181
182       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
189   Clustered Database Service Model
190       A clustered database runs across 3 or 5 or more database  servers  (the
191       cluster)  on  different hosts.  Servers in a cluster automatically syn‐
192       chronize writes within the cluster.   A  3-server  cluster  can  remain
193       available  in  the face of at most 1 server failure; a 5-server cluster
194       tolerates up to 2 failures.  Clusters larger than 5 servers  will  also
195       work,  with  every  2  added servers allowing the cluster to tolerate 1
196       more failure, but write performance decreases.  The number  of  servers
197       should  be  odd: a 4- or 6-server cluster cannot tolerate more failures
198       than a 3- or 5-server cluster, respectively.
199
200       To set up a clustered database, first initialize it on a single node by
201       running  ovsdb-tool create-cluster, then start ovsdb-server.  Depending
202       on its arguments, the create-cluster command can create an empty  data‐
203       base or copy a standalone database’s contents into the new database.
204
205       To  configure a client to use a clustered database, first configure all
206       of the servers to listen on a connection method  that  the  client  can
207       reach, then point the client to all of the servers’ connection methods,
208       comma-separated.  See Connection Methods, below, for more detail.
209
210       Open vSwitch 2.9 introduced support for the clustered service model.
211
212   How to Maintain a Clustered Database
213       To add a server to a cluster, run ovsdb-tool join-cluster  on  the  new
214       server and start ovsdb-server.  To remove a running server from a clus‐
215       ter, use ovs-appctl to invoke the cluster/leave command.  When a server
216       fails  and  cannot be recovered, e.g. because its hard disk crashed, or
217       to otherwise remove a server that is down from a cluster,  use  ovs-ap‐
218       pctl  to  invoke cluster/kick to make the remaining servers kick it out
219       of the cluster.
220
221       The above methods for adding and removing servers only work for healthy
222       clusters,  that is, for clusters with no more failures than their maxi‐
223       mum tolerance.  For example, in a 3-server cluster, the  failure  of  2
224       servers  prevents  servers  joining  or leaving the cluster (as well as
225       database access).  To prevent data loss or inconsistency, the preferred
226       solution to this problem is to bring up enough of the failed servers to
227       make the cluster healthy again, then if necessary remove any  remaining
228       failed  servers  and add new ones.  If this cannot be done, though, use
229       ovs-appctl to invoke cluster/leave --force on a running  server.   This
230       command  forces the server to which it is directed to leave its cluster
231       and form a new single-node cluster that contains only itself.  The data
232       in  the new cluster may be inconsistent with the former cluster: trans‐
233       actions not yet replicated to the server will be lost, and transactions
234       not  yet  applied  to  the  cluster  may  be committed.  Afterward, any
235       servers in its former cluster will regard the server to have failed.
236
237       Once a server leaves a cluster, it may never rejoin it.  Instead,  cre‐
238       ate a new server and join it to the cluster.
239
240       The  servers  in  a  cluster synchronize data over a cluster management
241       protocol that is specific to Open vSwitch; it is not the  same  as  the
242       OVSDB  protocol specified in RFC 7047.  For this purpose, a server in a
243       cluster is tied to a particular IP address and TCP port, which is spec‐
244       ified in the ovsdb-tool command that creates or joins the cluster.  The
245       TCP port used for clustering must be different from that used for OVSDB
246       clients.  To change the port or address of a server in a cluster, first
247       remove it from the cluster, then add it back with the new address.
248
249       To upgrade the ovsdb-server processes in a cluster from one version  of
250       Open  vSwitch  to  another,  upgrading them one at a time will keep the
251       cluster healthy during the upgrade process.  (This  is  different  from
252       upgrading  a database schema, which is covered later under Upgrading or
253       Downgrading a Database.)
254
255       IMPORTANT:
256          There was a change of a database file format in  version  2.15.   To
257          upgrade/downgrade  the  ovsdb-server  processes  across this version
258          follow the instructions described under Upgrading from version  2.14
259          and  earlier to 2.15 and later and Downgrading from version 2.15 and
260          later to 2.14 and earlier.
261
262       Clustered OVSDB does not support the OVSDB “ephemeral columns” feature.
263       ovsdb-tool  and  ovsdb-client  change ephemeral columns into persistent
264       ones when they work with schemas for clustered databases.  Future  ver‐
265       sions of OVSDB might add support for this feature.
266
267   Upgrading from version 2.14 and earlier to 2.15 and later
268       There  is  a  change  of  a  database  file format in version 2.15 that
269       doesn’t allow older versions of ovsdb-server to read the database  file
270       modified  by the ovsdb-server version 2.15 or later.  This also affects
271       runtime communications between servers  in  active-backup  and  cluster
272       service  models. To upgrade the ovsdb-server processes from one version
273       of Open vSwitch (2.14 or earlier) to another (2.15 or higher)  instruc‐
274       tions  below  should  be  followed. (This is different from upgrading a
275       database schema, which is covered later under Upgrading or  Downgrading
276       a Database.)
277
278       In  case of standalone service model no special handling during upgrade
279       is required.
280
281       For the active-backup service  model,  administrator  needs  to  update
282       backup  ovsdb-server  first and the active one after that, or shut down
283       both servers and upgrade at the same time.
284
285       For the cluster service model recommended upgrade strategy  is  follow‐
286       ing:
287
288       1. Upgrade  processes  one  at a time.  Each ovsdb-server process after
289          upgrade should be started  with  --disable-file-column-diff  command
290          line argument.
291
292       2. When  all  ovsdb-server processes upgraded, use ovs-appctl to invoke
293          ovsdb/file/column-diff-enable command on each of them or restart all
294          ovsdb-server  processes  one  at  a time without --disable-file-col‐
295          umn-diff command line option.
296
297   Downgrading from version 2.15 and later to 2.14 and earlier
298       Similar to upgrading covered under Upgrading from version 2.14 and ear‐
299       lier  to 2.15 and later, downgrading from the ovsdb-server version 2.15
300       and later to 2.14 and earlier requires additional steps. (This is  dif‐
301       ferent  from  upgrading a database schema, which is covered later under
302       Upgrading or Downgrading a Database.)
303
304       For all service models it’s required to:
305
306       1. Stop all ovsdb-server processes (single process for standalone  ser‐
307          vice  model,  all  involved  processes for active-backup and cluster
308          service models).
309
310       2. Compact all database files with ovsdb-tool compact command.
311
312       3. Downgrade and restart ovsdb-server processes.
313
314   Understanding Cluster Consistency
315       To ensure consistency, clustered OVSDB  uses  the  Raft  algorithm  de‐
316       scribed in Diego Ongaro’s Ph.D. thesis, “Consensus: Bridging Theory and
317       Practice”.  In an operational Raft cluster, at any given time a  single
318       server  is  the “leader” and the other nodes are “followers”.  Only the
319       leader processes transactions, but a transaction is only committed when
320       a  majority of the servers confirm to the leader that they have written
321       it to persistent storage.
322
323       In most database systems, read and write access to the database happens
324       through  transactions.   In  such  a  system,  Raft allows a cluster to
325       present a strongly consistent transactional interface.  OVSDB uses con‐
326       ventional  transactions  for  writes,  but clients often effectively do
327       reads a different way, by asking the server to “monitor” a database  or
328       a  subset  of  one  on  the  client’s  behalf.  Whenever monitored data
329       changes, the server automatically tells the client what changed,  which
330       allows  the  client to maintain an accurate snapshot of the database in
331       its memory.  Of course, at any given time, the snapshot may be somewhat
332       dated  since some of it could have changed without the change notifica‐
333       tion yet being received and processed by the client.
334
335       Given this unconventional usage model, OVSDB also adopts  an  unconven‐
336       tional  clustering  model.  Each server in a cluster acts independently
337       for the purpose of monitors and read-only transactions, without verify‐
338       ing  that data is up-to-date with the leader.  Servers forward transac‐
339       tions that write to the database to the leader for execution,  ensuring
340       consistency.  This has the following consequences:
341
342       • Transactions  that involve writes, against any server in the cluster,
343         are linearizable if clients take care to use  correct  prerequisites,
344         which  is the same condition required for linearizability in a stand‐
345         alone OVSDB.  (Actually, “at-least-once” consistency,  because  OVSDB
346         does not have a session mechanism to drop duplicate transactions if a
347         connection drops after the server commits it but  before  the  client
348         receives the result.)
349
350       • Read-only  transactions can yield results based on a stale version of
351         the database, if they are executed against a follower.   Transactions
352         on  the  leader  always  yield fresh results.  (With monitors, as ex‐
353         plained above, a client can always see stale data even without  clus‐
354         tering, so clustering does not change the consistency model for moni‐
355         tors.)
356
357       • Monitor-based (or read-heavy) workloads scale well across a  cluster,
358         because clustering OVSDB adds no additional work or communication for
359         reads and monitors.
360
361       • A write-heavy client should connect to the leader, to avoid the over‐
362         head of followers forwarding transactions to the leader.
363
364       • When  a  client  conducts a mix of read and write transactions across
365         more than one server in a cluster, it can  see  inconsistent  results
366         because  a  read transaction might read stale data whose updates have
367         not yet propagated from the leader.  By default,  utilities  such  as
368         ovn-sbctl (in OVN) connect to the cluster leader to avoid this issue.
369
370         The  same  might occur for transactions against a single follower ex‐
371         cept that the OVSDB server ensures that the results of a  write  for‐
372         warded to the leader by a given server are visible at that server be‐
373         fore it replies to the requesting client.
374
375       • If a client uses a database on one server in a cluster, then  another
376         server  in the cluster (perhaps because the first server failed), the
377         client could observe stale data.  Clustered OVSDB  clients,  however,
378         can  use  a  column  in the _Server database to detect that data on a
379         server is older than data that the client previously read.  The OVSDB
380         client  library  in  Open  vSwitch uses this feature to avoid servers
381         with stale data.
382
383   Relay Service Model
384       A relay database is a way to scale out read-mostly access to the exist‐
385       ing database working in any service model including relay.
386
387       Relay  database  creates and maintains an OVSDB connection with another
388       OVSDB server.  It uses this connection to maintain an in-memory copy of
389       the  remote  database  (a.k.a.  the  relay  source)  keeping  the  copy
390       up-to-date as the database content changes on the relay source  in  the
391       real time.
392
393       The  purpose  of  relay  server  is to scale out the number of database
394       clients.  Read-only transactions and monitor requests are fully handled
395       by the relay server itself.  For the transactions that request database
396       modifications, relay works as a proxy between the client and the  relay
397       source, i.e. it forwards transactions and replies between them.
398
399       Compared to the clustered and active-backup models, relay service model
400       provides read and write access to the database similarly to a clustered
401       database  (and  even  more  scalable), but with generally insignificant
402       performance overhead of an active-backup model.  At the  same  time  it
403       doesn’t  increase  availability that needs to be covered by the service
404       model of the relay source.
405
406       Relay database has no on-disk storage and therefore cannot be converted
407       to any other service model.
408
409       If there is already a database started in any service model, to start a
410       relay database server use ovsdb-server relay:<DB_NAME>:<relay  source>,
411       where  <DB_NAME> is the database name as specified in the schema of the
412       database that existing server runs, and <relay source> is an OVSDB con‐
413       nection  method (see Connection Methods below) that connects to the ex‐
414       isting database server.  <relay source> could contain a comma-separated
415       list  of connection methods, e.g. to connect to any server of the clus‐
416       tered database.  Multiple relay servers could be started for  the  same
417       relay source.
418
419       Since the way relays handle read and write transactions is very similar
420       to the clustered model where “cluster” means “set of relay servers con‐
421       nected  to  the same relay source”, “follower” means “relay server” and
422       the “leader” means “relay source”, same consistency consequences as for
423       the clustered model applies to relay as well (See Understanding Cluster
424       Consistency above).
425
426       Open vSwitch 2.16 introduced support for relay service model.
427

DATABASE REPLICATION

429       OVSDB can layer replication on  top  of  any  of  its  service  models.
430       Replication,  in  this  context,  means to make, and keep up-to-date, a
431       read-only copy of the contents of a database (the replica).  One use of
432       replication  is  to keep an up-to-date backup of a database.  A replica
433       used solely for backup would not need to support clients of its own.  A
434       set  of  replicas that do serve clients could be used to scale out read
435       access to the primary database, however Relay  Service  Model  is  more
436       suitable for that purpose.
437
438       A  database  replica is set up in the same way as a backup server in an
439       active-backup pair, with the difference that the replica is never  pro‐
440       moted to an active role.
441
442       A database can have multiple replicas.
443
444       Open vSwitch 2.6 introduced support for database replication.
445

CONNECTION METHODS

447       An  OVSDB  connection  method  is a string that specifies how to make a
448       JSON-RPC connection between an OVSDB  client  and  server.   Connection
449       methods  are  part  of the Open vSwitch implementation of OVSDB and not
450       specified by RFC 7047.  ovsdb-server uses connection methods to specify
451       how it should listen for connections from clients and ovsdb-client uses
452       them to specify how it should connect to a server.  Connections in  the
453       opposite  direction,  where  ovsdb-server  connects to a client that is
454       configured to listen for an incoming connection, are also possible.
455
456       Connection methods are classified as active or passive.  An active con‐
457       nection method makes an outgoing connection to a remote host; a passive
458       connection method listens for connections from remote hosts.  The  most
459       common arrangement is to configure an OVSDB server with passive connec‐
460       tion methods and clients with active ones, but the OVSDB implementation
461       in Open vSwitch supports the opposite arrangement as well.
462
463       OVSDB supports the following active connection methods:
464
465       ssl:<host>:<port>
466              The specified SSL or TLS <port> on the given <host>.
467
468       tcp:<host>:<port>
469              The specified TCP <port> on the given <host>.
470
471       unix:<file>
472              On  Unix-like  systems, connect to the Unix domain server socket
473              named <file>.
474
475              On Windows, connect to a local named pipe that is represented by
476              a  file  created  in  the path <file> to mimic the behavior of a
477              Unix domain socket.
478
479       <method1>,<method2>,…,<methodN>
480              For a clustered database  service  to  be  highly  available,  a
481              client  must  be  able  to  connect to any of the servers in the
482              cluster.  To do so, specify connection methods for each  of  the
483              servers separated by commas (and optional spaces).
484
485              In theory, if machines go up and down and IP addresses change in
486              the right way, a client could talk to the wrong  instance  of  a
487              database.  To avoid this possibility, add cid:<uuid> to the list
488              of methods, where <uuid> is the cluster ID of the desired  data‐
489              base  cluster, as printed by ovsdb-tool db-cid.  This feature is
490              optional.
491
492       OVSDB supports the following passive connection methods:
493
494       pssl:<port>[:<ip>]
495              Listen on the given TCP <port> for SSL or TLS  connections.   By
496              default,  connections are not bound to a particular local IP ad‐
497              dress.  Specifying <ip> limits connections  to  those  from  the
498              given IP.
499
500       ptcp:<port>[:<ip>]
501              Listen on the given TCP <port>.  By default, connections are not
502              bound to a particular local IP address.  Specifying <ip>  limits
503              connections to those from the given IP.
504
505       punix:<file>
506              On Unix-like systems, listens for connections on the Unix domain
507              socket named <file>.
508
509              On Windows, listens on a local named pipe, creating a named pipe
510              <file>  to  mimic the behavior of a Unix domain socket. The ACLs
511              of the named pipe include LocalSystem, Administrators, and  Cre‐
512              ator Owner.
513
514       All  IP-based  connection  methods  accept IPv4 and IPv6 addresses.  To
515       specify  an  IPv6  address,  wrap   it   in   square   brackets,   e.g.
516       ssl:[::1]:6640.   Passive IP-based connection methods by default listen
517       for IPv4 connections only; use [::] as the address to accept both  IPv4
518       and IPv6 connections, e.g. pssl:6640:[::].  DNS names are also accepted
519       if built with unbound library.  On Linux, use %<device> to designate  a
520       scope for IPv6 link-level addresses, e.g. ssl:[fe80::1234%eth0]:6653.
521
522       The  <port> may be omitted from connection methods that use a port num‐
523       ber.  The default <port> for TCP-based connection methods is 6640, e.g.
524       pssl:  is  equivalent  to  pssl:6640.  In Open vSwitch prior to version
525       2.4.0, the default port was 6632.   To  avoid  incompatibility  between
526       older and newer versions, we encourage users to specify a port number.
527
528       The  ssl  and pssl connection methods requires additional configuration
529       through --private-key, --certificate, and --ca-cert  command  line  op‐
530       tions.   Open  vSwitch  can be built without SSL support, in which case
531       these connection methods are not supported.
532

DATABASE LIFE CYCLE

534       This section describes how to handle various events in the  life  cycle
535       of a database using the Open vSwitch implementation of OVSDB.
536
537   Creating a Database
538       Creating  and  starting  up  the service for a new database was covered
539       separately for each database service model in the Service  Models  sec‐
540       tion, above.
541
542   Backing Up and Restoring a Database
543       OVSDB  is  often  used  in contexts where the database contents are not
544       particularly valuable.  For example, in many systems, the database  for
545       configuring  ovs-vswitchd  is  essentially rebuilt from scratch at boot
546       time.  It is not worthwhile to back up these databases.
547
548       When OVSDB is used for valuable data, a backup strategy is  worth  con‐
549       sidering.   One  way is to use database replication, discussed above in
550       Database Replication which keeps an online, up-to-date copy of a  data‐
551       base,  possibly  on a remote system.  This works with all OVSDB service
552       models.
553
554       A more common backup strategy is to periodically take and store a snap‐
555       shot.   For  the  standalone and active-backup service models, making a
556       copy of the database file, e.g. using cp, effectively makes a snapshot,
557       and  because OVSDB database files are append-only, it works even if the
558       database is being modified when the snapshot  takes  place.   This  ap‐
559       proach does not work for clustered databases.
560
561       Another  way  to make a backup, which works with all OVSDB service mod‐
562       els, is to use ovsdb-client backup, which connects to a  running  data‐
563       base  server  and outputs an atomic snapshot of its schema and content,
564       in the same format used for standalone and active-backup databases.
565
566       Multiple options are also available when the time comes  to  restore  a
567       database  from  a backup.  For the standalone and active-backup service
568       models, one option is to stop the database server or servers, overwrite
569       the  database file with the backup (e.g. with cp), and then restart the
570       servers.  Another way, which works with any service model,  is  to  use
571       ovsdb-client  restore,  which connects to a running database server and
572       replaces the data in one of its databases by a provided snapshot.   The
573       advantage  of  ovsdb-client restore is that it causes zero downtime for
574       the database and its server.  It has the downside that UUIDs of rows in
575       the  restored  database will differ from those in the snapshot, because
576       the OVSDB protocol does not allow clients to specify row UUIDs.
577
578       None of these approaches saves and restores data in  columns  that  the
579       schema  designates  as ephemeral.  This is by design: the designer of a
580       schema only marks a column as ephemeral if it  is  acceptable  for  its
581       data to be lost when a database server restarts.
582
583       Clustering  and  backup serve different purposes.  Clustering increases
584       availability, but it does not protect against data loss if,  for  exam‐
585       ple, a malicious or malfunctioning OVSDB client deletes or tampers with
586       data.
587
588   Changing Database Service Model
589       Use ovsdb-tool create-cluster to create a clustered database  from  the
590       contents of a standalone database.  Use ovsdb-client backup to create a
591       standalone database from the contents of a running clustered  database.
592       When  the  cluster  is  down and cannot be revived, ovsdb-client backup
593       will not work.
594
595       Use ovsdb-tool cluster-to-standalone to convert clustered  database  to
596       standalone database when the cluster is down and cannot be revived.
597
598   Upgrading or Downgrading a Database
599       The evolution of a piece of software can require changes to the schemas
600       of the databases that it uses.  For example, new features might require
601       new  tables  or  new  columns in existing tables, or conceptual changes
602       might require a database to be reorganized  in  other  ways.   In  some
603       cases, the easiest way to deal with a change in a database schema is to
604       delete the existing database and start fresh with the new schema, espe‐
605       cially if the data in the database is easy to reconstruct.  But in many
606       other cases, it is better to convert the database from  one  schema  to
607       another.
608
609       The  OVSDB implementation in Open vSwitch has built-in support for some
610       simple cases of converting a database from one schema to another.  This
611       support  can  handle changes that add or remove database columns or ta‐
612       bles or that eliminate constraints (for example, changing a column that
613       must  have exactly one value into one that has one or more values).  It
614       can also handle changes that add constraints or make them stricter, but
615       only if the existing data in the database satisfies the new constraints
616       (for example, changing a column that has one or more values into a col‐
617       umn  with exactly one value, if every row in the column has exactly one
618       value).  The built-in conversion can cause data loss in  obvious  ways,
619       for example if the new schema removes tables or columns, or indirectly,
620       for example by deleting unreferenced rows in tables that the new schema
621       marks for garbage collection.
622
623       Converting a database can lose data, so it is wise to make a backup be‐
624       forehand.
625
626       To use OVSDB’s built-in support for schema conversion with a standalone
627       or  active-backup  database, first stop the database server or servers,
628       then use ovsdb-tool convert to convert it to the new schema,  and  then
629       restart the database server.
630
631       OVSDB  also  supports  online database schema conversion for any of its
632       database  service  models.   To  convert   a   database   online,   use
633       ovsdb-client  convert.  The conversion is atomic, consistent, isolated,
634       and durable.  ovsdb-server disconnects any clients connected  when  the
635       conversion takes place (except clients that use the set_db_change_aware
636       Open vSwitch extension RPC).  Upon reconnection, clients will  discover
637       that the schema has changed.
638
639       Schema  versions and checksums (see Schemas above) can give hints about
640       whether a database needs to be converted to a new schema.  If there  is
641       any  question,  though,  the needs-conversion command on ovsdb-tool and
642       ovsdb-client can provide a definitive answer.
643
644   Working with Database History
645       Both on-disk database formats that OVSDB supports are  organized  as  a
646       stream  of  transaction records.  Each record describes a change to the
647       database as a list of rows that were inserted or deleted  or  modified,
648       along  with  the  details.   Therefore, in normal operation, a database
649       file only grows, as each change causes another record to be appended at
650       the  end.   Usually,  a user has no need to understand this file struc‐
651       ture.  This section covers some exceptions.
652
653   Compacting Databases
654       If OVSDB database files were truly append-only,  then  over  time  they
655       would  grow  without bound.  To avoid this problem, OVSDB can compact a
656       database file, that is, replace it by a new version that contains  only
657       the  current  database contents, as if it had been inserted by a single
658       transaction.  From time to time, ovsdb-server automatically compacts  a
659       database that grows much larger than its minimum size.
660
661       Because  ovsdb-server  automatically  compacts databases, it is usually
662       not necessary to compact them manually, but OVSDB still  offers  a  few
663       ways  to  do it.  First, ovsdb-tool compact can compact a standalone or
664       active-backup  database  that  is  not  currently   being   served   by
665       ovsdb-server  (or otherwise locked for writing by another process).  To
666       compact any database that is currently being  served  by  ovsdb-server,
667       use  ovs-appctl  to send the ovsdb-server/compact command.  Each server
668       in an active-backup or clustered database maintains its  database  file
669       independently, so to compact all of them, issue this command separately
670       on each server.
671
672   Viewing History
673       The ovsdb-tool utility’s  show-log  command  displays  the  transaction
674       records  in  an OVSDB database file in a human-readable format.  By de‐
675       fault, it shows minimal detail, but adding the option -m once or  twice
676       increases the level of detail.  In addition to the transaction data, it
677       shows the time and date of each transaction and any “comment” added  to
678       the transaction by the client.  The comments can be helpful for quickly
679       understanding a transaction; for example, ovs-vsctl  adds  its  command
680       line to the transactions that it makes.
681
682       The  show-log  command  works with both OVSDB file formats, but the de‐
683       tails of the output format differ.   For  active-backup  and  clustered
684       databases,  the sequence of transactions in each server’s log will dif‐
685       fer, even at points when they reflect the same data.
686
687   Truncating History
688       It may occasionally be useful to “roll back” a database file to an ear‐
689       lier point.  Because of the organization of OVSDB records, this is easy
690       to do.  Start by noting the record number <i> of the  first  record  to
691       delete  in  ovsdb-tool  show-log  output.   Each record is two lines of
692       plain text, so trimming the log is as simple as running  head  -n  <j>,
693       where <j> = 2 * <i>.
694
695   Corruption
696       When  ovsdb-server  opens an OVSDB database file, of any kind, it reads
697       as many transaction records as it can from the file  until  it  reaches
698       the end of the file or it encounters a corrupted record.  At that point
699       it stops reading and regards the data that it has read to this point as
700       the  full  contents of the database file, effectively rolling the data‐
701       base back to an earlier point.
702
703       Each transaction record contains an embedded SHA-1 checksum, which  the
704       server  verifies  as  it  reads a database file.  It detects corruption
705       when a checksum fails to verify.  Even though SHA-1 is no  longer  con‐
706       sidered  secure for use in cryptography, it is acceptable for this pur‐
707       pose because it is not used to defend against malicious attackers.
708
709       The first record in a standalone or active-backup database file  speci‐
710       fies  the  schema.   ovsdb-server  will  refuse to work with a database
711       where this record is corrupted, or with a clustered database file  with
712       corruption  in the first few records.  Delete and recreate such a data‐
713       base, or restore it from a backup.
714
715       When ovsdb-server adds records to a database file in which it  detected
716       corruption,  it  first  truncates  the  file  just  after the last good
717       record.
718

SEE ALSO

720       RFC 7047, “The Open vSwitch Database Management Protocol.”
721
722       Open  vSwitch   implementations   of   generic   OVSDB   functionality:
723       ovsdb-server(1), ovsdb-client(1), ovsdb-tool(1).
724
725       Tools  for  working  with  databases  that have specific OVSDB schemas:
726       ovs-vsctl(8), vtep-ctl(8), and (in OVN) ovn-nbctl(8), ovn-sbctl(8).
727
728       OVSDB   schemas   for   Open   vSwitch   and   related   functionality:
729       ovs-vswitchd.conf.db(5), vtep(5), and (in OVN) ovn-nb(5), ovn-sb(5).
730

AUTHOR

732       The Open vSwitch Development Community
733
735       2016-2022, The Open vSwitch Development Community
736
737
738
739
7402.17                             Jul 22, 2022                         OVSDB(7)
Impressum