Some updates to the backup format:

  - The name of the descriptor file is now based on the timestamp in UTC,
    not local time.  This should give better behavior in the case of
    frequent snapshots and daylight saving time changes.
  - Update the backup format to v0.11 (other changes may yet come before
    release); with this also include a name change from "LBS" to "Cumulus"
    in the format name.

diff --git a/doc/format.txt b/doc/format.txt
index 2ab2696..c273e21 100644 (file)
--- a/doc/format.txt
+++ b/doc/format.txt
@@ -1,16 +1,13 @@
                        Backup Format Description
          for Cumulus: Efficient Filesystem Backup to the Cloud
-                      Version: "LBS Snapshot v0.8"
+                   Version: "Cumulus Snapshot v0.11"
 
 NOTE: This format specification is intended to be mostly stable, but is
 still subject to change before the 1.0 release.  The code may provide
 additional useful documentation on the format.
 
-NOTE2: The name of this project has changed from LBS to Cumulus.
-However, to avoid introducing gratuitous changes into the format, in
-most cases any references to "LBS" in the format description have been
-left as-is.  The name may be changed in the future if the format is
-updated.
+NOTE2: The name of this project has changed from LBS to Cumulus.  In
+some areas the name "LBS" is still used.
 
 This document simply describes the snapshot format.  It is described
 from the point of view of a decompressor which wishes to restore the
@@ -275,20 +272,29 @@ The name of snapshot descriptor file is
 logically distinct sets of snapshots (such as snapshots for two
 different directory trees) that are being stored in the same location.
 <timestamp> gives the date and time the snapshot was taken; the format
-is %Y%m%dT%H%M%S (20070806T092239 means 2007-08-06 09:22:39).
+is %Y%m%dT%H%M%S (20070806T092239 means 2007-08-06 09:22:39).  It is
+recommended that the timestamp be given in UTC for consistent sorting
+even if the offset from UTC to local time changes, however the
+authoritative timestamp (including timezone) can be found in the Date
+field.  (In version v0.10 and earlier the timestamp is given in local
+time; in current versions UTC is used.)
 
 The contents of the descriptor are a set of RFC 822-style headers (much
 like the metadata listing).  The fields which are defined are:
-    Format: The string "LBS Snapshot v0.6" which identifies this file as
-        a Cumulus backup descriptor.  The version number (v0.6) might
-        change if there are changes to the format.  It is expected that
-        at some point, once the format is stabilized, the version
-        identifier will be changed to v1.0.
+    Format: The string "Cumulus Snapshot v0.11" which identifies this
+        file as a Cumulus backup descriptor.  The version number (v0.11)
+        might change if there are changes to the format.  It is expected
+        that at some point, once the format is stabilized, the version
+        identifier will be changed to v1.0.  (Earlier versions, format
+        v0.8 and earlier, used the string "LBS Snapshot" instead of
+        "Cumulus Snapshot", reflecting an earlier name for the project.
+        Consumers should be prepared for either name.)
     Producer: A informative string which identifies the program that
         produced the backup.
-    Date: The date the snapshot was produced.  This matches the
-        timestamp encoded in the filename, but is written out in full.
-        A timezone is given.  For example: "2007-08-06 09:22:39 -0700".
+    Date: The date the snapshot was produced, in the local time zone.
+        This matches the timestamp encoded in the filename, but is
+        written out in full.  A timezone (offset from UTC) is given.
+        For example: "2007-08-06 02:22:39 -0700".
     Scheme: The <scheme> field from the descriptor filename.
     Segments: A whitespace-seprated list of segment names.  Any segment
         which is referenced by this snapshot must be included in the

diff --git a/main.cc b/main.cc
index 8af3175..45a4154 100644 (file)
--- a/main.cc
+++ b/main.cc
@@ -18,8 +18,8 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  */
 
-/* Main entry point for LBS.  Contains logic for traversing the filesystem and
- * constructing a backup. */
+/* Main entry point for Cumulus.  Contains logic for traversing the filesystem
+ * and constructing a backup. */
 
 #include <dirent.h>
 #include <errno.h>
@@ -812,11 +812,12 @@ int main(int argc, char *argv[])
     /* Store the time when the backup started, so it can be included in the
      * snapshot name. */
     time_t now;
-    struct tm time_buf;
+    struct tm time_buf_local, time_buf_utc;
     char desc_buf[256];
     time(&now);
-    localtime_r(&now, &time_buf);
-    strftime(desc_buf, sizeof(desc_buf), "%Y%m%dT%H%M%S", &time_buf);
+    localtime_r(&now, &time_buf_local);
+    gmtime_r(&now, &time_buf_utc);
+    strftime(desc_buf, sizeof(desc_buf), "%Y%m%dT%H%M%S", &time_buf_utc);
 
     /* Open the local database which tracks all objects that are stored
      * remotely, for efficient incrementals.  Provide it with the name of this
@@ -919,9 +920,10 @@ int main(int argc, char *argv[])
     }
     FILE *descriptor = fdopen(descriptor_fd, "w");
 
-    fprintf(descriptor, "Format: LBS Snapshot v0.8\n");
+    fprintf(descriptor, "Format: Cumulus Snapshot v0.11\n");
     fprintf(descriptor, "Producer: Cumulus %s\n", cumulus_version);
-    strftime(desc_buf, sizeof(desc_buf), "%Y-%m-%d %H:%M:%S %z", &time_buf);
+    strftime(desc_buf, sizeof(desc_buf), "%Y-%m-%d %H:%M:%S %z",
+             &time_buf_local);
     fprintf(descriptor, "Date: %s\n", desc_buf);
     if (backup_scheme.size() > 0)
         fprintf(descriptor, "Scheme: %s\n", backup_scheme.c_str());