Include timestamps in reconstructed segment metadata.

[cumulus.git] / doc / format.txt

diff --git a/doc/format.txt b/doc/format.txt
index c273e21..19bf2f2 100644 (file)
--- a/doc/format.txt
+++ b/doc/format.txt
@@ -19,6 +19,30 @@ This document does not explain the rationale behind the format; for
 that, see design.txt.
 
 
 that, see design.txt.
 
 

+BACKUP REPOSITORY LAYOUT
+========================
+
+Cumulus backups are stored using a relatively simple layout.  Data files
+described below are written into one of several directories on the
+backup server, depending on their purpose:
+    snapshots/
+        Snapshot descriptor files, which quickly summarize each backup
+        snapshot stored.
+    segments0/
+    segments1/
+        Storage of the bulk of the backup data, in compressed/encrypted
+        form.  Technically any segment could be stored in either
+        directory (both directories will be searched when looking for a
+        segment).  However, data in segments0 might be faster to access
+        (but more expensive) depending on the storage backend.  The
+        intent is that segments0 can store filesystem tree metadata and
+        segments1 can store file contents.
+    meta/
+        Snapshot-specific metadata that is not core to the backup.  This
+        can include checksums of segments, some data for rebuilding
+        local database contents, etc.
+
+

 DATA CHECKSUMS
 ==============
 
 DATA CHECKSUMS
 ==============
 


@@ -32,8 +56,10 @@ format.  The general format used is
     <algorithm>=<hexdigits>
 
 <algorithm> identifies the checksum algorithm used, and allows new
     <algorithm>=<hexdigits>
 
 <algorithm> identifies the checksum algorithm used, and allows new

-algorithms to be added later.  At the moment, the only permissible value
-is "sha1", indicating a SHA-1 checksum.
+algorithms to be added later.  Permissible values are:
+    "sha1": SHA-1
+    "sha224": SHA-224 (added in version 0.11)
+    "sha256": SHA-256 (added in version 0.11)

 
 <hexdigits> is a sequence of hexadecimal digits which encode the
 checksum value.  For sha1, <hexdigits> should be precisely 40 digits
 
 <hexdigits> is a sequence of hexadecimal digits which encode the
 checksum value.  For sha1, <hexdigits> should be precisely 40 digits


@@ -69,6 +95,8 @@ fixed points; an example UUID is
 This segment could be stored in the filesystem as a file
     a704eeae-97f2-4f30-91a4-d4473956366b.tar
 The UUID used to name a segment is assigned when the segment is created.
 This segment could be stored in the filesystem as a file
     a704eeae-97f2-4f30-91a4-d4473956366b.tar
 The UUID used to name a segment is assigned when the segment is created.

+These files are stored in either the segments0 or segments1 directories
+on the backup server.

 
 Filters can be layered on top of the segment storage to provide
 compression, encryption, or other features.  For example, the example
 
 Filters can be layered on top of the segment storage to provide
 compression, encryption, or other features.  For example, the example


@@ -99,8 +127,8 @@ object.
 
 NOTE: When naming an object, the segment portion consists of the UUID
 only.  Any extensions appended to the segment when storing it as a file
 
 NOTE: When naming an object, the segment portion consists of the UUID
 only.  Any extensions appended to the segment when storing it as a file

-in the filesystem (for example, .tar.bz2) are _not_ part of the name of
-the object.
+in the filesystem (for example, .tar.bz2) and path information (for
+example, segments0) are _not_ part of the name of the object.

 
 There are two additional components which may appear in an object name;
 both are optional.
 
 There are two additional components which may appear in an object name;
 both are optional.