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

NAME

6       ovsdb - Open vSwitch Database (File Formats)
7

DESCRIPTION

9       OVSDB,  the  Open  vSwitch Database, is a database system whose network
10       protocol is specified by RFC 7047.  The RFC does not specify an on-disk
11       storage  format.   The  OVSDB implementation in Open vSwitch implements
12       two storage formats: one for standalone (and active-backup)  databases,
13       and  the other for clustered databases.  This manpage documents both of
14       these formats.
15
16       Most users do not need to be concerned with  this  specification.   In‐
17       stead,  to  manipulate OVSDB files, refer to ovsdb-tool(1).  For an in‐
18       troduction to OVSDB as a whole, read ovsdb(7).
19
20       OVSDB files explicitly record changes that are implied by the  database
21       schema.  For example, the OVSDB “garbage collection” feature means that
22       when a client removes the last reference to  a  garbage-collected  row,
23       the  database server automatically removes that row.  The database file
24       explicitly records the deletion of the garbage-collected row,  so  that
25       the reader does not need to infer it.
26
27       OVSDB files do not include the values of ephemeral columns.
28
29       Standalone  and clustered database files share the common structure de‐
30       scribed here.  They are text files encoded in UTF-8  with  LF  (U+000A)
31       line  ends,  organized  as  append-only series of records.  Each record
32       consists of 2 lines of text.
33
34       The first line in each record has the  format  OVSDB  <magic>  <length>
35       <hash>,  where  <magic> is JSON for standalone databases or CLUSTER for
36       clustered databases, <length> is a positive decimal integer, and <hash>
37       is  a  SHA-1 checksum expressed as 40 hexadecimal digits.  Words in the
38       first line must be separated by exactly one space.
39
40       The second line must be exactly length bytes long  (including  the  LF)
41       and its SHA-1 checksum (including the LF) must match hash exactly.  The
42       line’s contents must be a valid JSON object as specified by  RFC  4627.
43       Strings  in  the  JSON  object must be valid UTF-8.  To ensure that the
44       second line is exactly one line of text, the OVSDB  implementation  ex‐
45       presses  any  LF  characters  within a JSON string as \n.  For the same
46       reason, and to save space, the OVSDB implementation  does  not  “pretty
47       print”  the JSON object with spaces and LFs.  (The OVSDB implementation
48       tolerates LFs when reading an OVSDB database file, as  long  as  length
49       and hash are correct.)
50
51   JSON Notation
52       We  use  notation  from  RFC  7047  here  to  describe the JSON data in
53       records.  In addition to the notation defined there, we add the follow‐
54       ing:
55
56       <raw-uuid>
57              A  36-character  JSON  string that contains a UUID in the format
58              described          by          RFC          4122,           e.g.
59              "550e8400-e29b-41d4-a716-446655440000"
60
61   Standalone Format
62       The  first record in a standalone database contains the JSON schema for
63       the database, as specified in RFC 7047.  Only this record is  mandatory
64       (a  standalone  file  that  contains  only a schema represents an empty
65       database).
66
67       The second and subsequent records in a standalone database are transac‐
68       tion records.  Each record may have the following optional special mem‐
69       bers, which do not have any semantics but are often useful to  adminis‐
70       trators looking through a database log with ovsdb-tool show-log:
71
72       "_date": <integer>
73              The  time  at which the transaction was committed, as an integer
74              number of milliseconds since the Unix epoch.  Early versions  of
75              OVSDB  counted seconds instead of milliseconds; these can be de‐
76              tected by noticing that their values are less than 2**32.
77
78              OVSDB always writes a _date member.
79
80       "_comment": <string>
81              A JSON string that specifies the comment provided in a  transac‐
82              tion  comment  operation.  If a transaction has multiple comment
83              operations, OVSDB concatenates them into a single _comment  mem‐
84              ber, separated by a new-line.
85
86              OVSDB  only  writes  a _comment member if it would be a nonempty
87              string.
88
89       Each of these records also has one or more additional members, each  of
90       which maps from the name of a database table to a <table-txn>:
91
92       <table-txn>
93              A  JSON  object that describes the effects of a transaction on a
94              database table.  Its names are <raw-uuid>s for rows in the table
95              and its values are <row-txn>s.
96
97       <row-txn>
98              Either  null,  which indicates that the transaction deleted this
99              row, or a JSON object that describes  how  the  transaction  in‐
100              serted or modified the row, whose names are the names of columns
101              and whose values are <value>s that give the column’s new value.
102
103              For new rows, the OVSDB implementation omits columns whose  val‐
104              ues  have the default values for their types defined in RFC 7047
105              section 5.2.1; for modified rows, the OVSDB implementation omits
106              columns whose values are unchanged.
107
108   Clustered Format
109       The clustered format has the following additional notation:
110
111       <uint64>
112              A  JSON  integer that represents a 64-bit unsigned integer.  The
113              OVS JSON implementation only  supports  integers  in  the  range
114              -2**63  through  2**63-1, so 64-bit unsigned integer values from
115              2**63 through 2**64-1 are expressed as negative numbers.
116
117       <address>
118              A JSON string that represents a network address to support clus‐
119              tering,   in  the  <protocol>:<ip>:<port>  syntax  described  in
120              ovsdb-tool(1).
121
122       <servers>
123              A JSON object whose names are <raw-uuid>s that identify  servers
124              and whose values are <address>es that specify those servers’ ad‐
125              dresses.
126
127       <cluster-txn>
128              A JSON array with two elements:
129
130              1. The first element is either a <database-schema> or  null.   A
131                 <database-schema>  element  is  always  present  in the first
132                 record of a clustered database  to  indicate  the  database’s
133                 initial  schema.  If it is not null in a later record, it in‐
134                 dicates a change of schema for the database.
135
136              2. The second element is either a transaction record in the for‐
137                 mat described under Standalone Format above, or null.
138
139              When  a schema is present, the transaction record is relative to
140              an empty database.  That is, a schema change effectively  resets
141              the  database to empty and the transaction record represents the
142              full database contents.  This allows readers to be  ignorant  of
143              the full semantics of schema change.
144
145       The  first  record  in a clustered database contains the following mem‐
146       bers, all of which are required, except prev_election_timer:
147
148       "server_id": <raw-uuid>
149              The server’s own UUID, which must be unique within the cluster.
150
151       "local_address": <address>
152              The address on which the server  listens  for  connections  from
153              other servers in the cluster.
154
155       "name": <id>
156              The database schema name.  It is only important when a server is
157              in the process of joining a cluster: a server will only  join  a
158              cluster  if the name matches.  (If the database schema name were
159              unique, then we would not also need a cluster ID.)
160
161       "cluster_id": <raw-uuid>
162              The cluster’s UUID.  The all-zeros UUID is not a  valid  cluster
163              ID.
164
165       "prev_term": <uint64> and "prev_index": <uint64>
166              The Raft term and index just before the beginning of the log.
167
168       "prev_servers": <servers>
169              The set of one or more servers in the cluster at index “prev_in‐
170              dex” and term “prev_term”.  It might not include this server, if
171              it was not the initial server in the cluster.
172
173       "prev_election_timer": <uint64>
174              The  election base time before the beginning of the log.  If not
175              exist, the default value 1000 ms is used as if  it  exists  this
176              record.
177
178       "prev_data": <json-value> and "prev_eid": <raw-uuid>
179              A snapshot of the data in the database at index “prev_index” and
180              term “prev_term”, and the entry ID for that data.  The  snapshot
181              must contain a schema.
182
183       The  second and subsequent records, if present, in a clustered database
184       represent changes to the database,  to  the  cluster  state,  or  both.
185       There  are several types of these records.  The most important types of
186       records directly represent persistent state described in the Raft spec‐
187       ification:
188
189       Entry  A Raft log entry.
190
191       Term   The start of a new term.
192
193       Vote   The server’s vote for a leader in the current term.
194
195       The  following  additional  types  of  records  aid debugging and trou‐
196       bleshooting, but they do not affect correctness.
197
198       Leader Identifies a newly elected leader for the current term.
199
200       Commit Index
201              An update to the server’s commit_index.
202
203       Note   A human-readable description of some event.
204
205       The table below identifies the members that each type  of  record  con‐
206       tains.   “yes”  indicates that a member is required, “?” that it is op‐
207       tional, blank that it is forbidden, and [1] that data and eid  must  be
208       either both present or both absent.
209
210           ┌───────────┬───────┬──────┬──────┬────────┬────────────┬──────┐
211           │member     │ Entry │ Term │ Vote │ Leader │ Commit In‐ │ Note │
212           │           │       │      │      │        │ dex        │      │
213           ├───────────┼───────┼──────┼──────┼────────┼────────────┼──────┤
214           │comment    │ ?     │ ?    │ ?    │ ?      │ ?          │ ?    │
215           ├───────────┼───────┼──────┼──────┼────────┼────────────┼──────┤
216           │term       │ yes   │ yes  │ yes  │ yes    │            │      │
217           ├───────────┼───────┼──────┼──────┼────────┼────────────┼──────┤
218           │index      │ yes   │      │      │        │            │      │
219           ├───────────┼───────┼──────┼──────┼────────┼────────────┼──────┤
220           │servers    │ ?     │      │      │        │            │      │
221           ├───────────┼───────┼──────┼──────┼────────┼────────────┼──────┤
222           │elec‐      │ ?     │      │      │        │            │      │
223           │tion_timer │       │      │      │        │            │      │
224           ├───────────┼───────┼──────┼──────┼────────┼────────────┼──────┤
225           │data       │ [1]   │      │      │        │            │      │
226           ├───────────┼───────┼──────┼──────┼────────┼────────────┼──────┤
227           │eid        │ [1]   │      │      │        │            │      │
228           ├───────────┼───────┼──────┼──────┼────────┼────────────┼──────┤
229           │vote       │       │      │ yes  │        │            │      │
230           ├───────────┼───────┼──────┼──────┼────────┼────────────┼──────┤
231           │leader     │       │      │      │ yes    │            │      │
232           ├───────────┼───────┼──────┼──────┼────────┼────────────┼──────┤
233           │commit_in‐ │       │      │      │        │ yes        │      │
234           │dex        │       │      │      │        │            │      │
235           ├───────────┼───────┼──────┼──────┼────────┼────────────┼──────┤
236           │note       │       │      │      │        │            │ yes  │
237           └───────────┴───────┴──────┴──────┴────────┴────────────┴──────┘
238
239       The members are:
240
241       "comment": <string>
242              A human-readable string giving an administrator more information
243              about the reason a record was emitted.
244
245       "term": <uint64>
246              The term in which the activity occurred.
247
248       "index": <uint64>
249              The index of a log entry.
250
251       "servers": <servers>
252              Server configuration in a log entry.
253
254       "election_timer": <uint64>
255              Leader election timeout base value in a log entry.
256
257       "data": <json-value>
258              The data in a log entry.
259
260       "eid": <raw-uuid>
261              Entry ID in a log entry.
262
263       "vote": <raw-uuid>
264              The server ID for which this server voted.
265
266       "leader": <raw-uuid>
267              The  server  ID of the server.  Emitted by both leaders and fol‐
268              lowers when a leader is elected.
269
270       "commit_index": <uint64>
271              Updated commit_index value.
272
273       "note": <string>
274              One of a few special strings indicating important  events.   The
275              currently defined strings are:
276
277              "transfer leadership"
278                     This  server transferred leadership to a different server
279                     (with details included in comment).
280
281              "left" This server finished leaving  the  cluster.   (This  lets
282                     subsequent  readers  know  that the server is not part of
283                     the cluster and should not attempt to connect to it.)
284
285   Joining a Cluster
286       In addition to general format for a clustered database, there is also a
287       special  case  for  a database file created by ovsdb-tool join-cluster.
288       Such a file contains exactly one record, which conveys the  information
289       passed to the join-cluster command.  It has the following members:
290
291       "server_id": <raw-uuid> and "local_address": <address> and "name": <id>
292              These have the same semantics described above in the general de‐
293              scription of the format.
294
295       "cluster_id": <raw-uuid>
296              This is provided only if the  user  gave  the  --cid  option  to
297              join-cluster.  It has the same semantics described above.
298
299       "remote_addresses"; [<address>*]
300              One or more remote servers to contact for joining the cluster.
301
302       When  the  server  successfully joins the cluster, the database file is
303       replaced by one described in Clustered Format.
304

AUTHOR

306       The Open vSwitch Development Community
307
309       2021, The Open vSwitch Development Community
310
311
312
313
3142.15                             Feb 21, 2021                         OVSDB(5)
Impressum