From 748d04c5c242a1dfcc932220eabd14f778e386c9 Mon Sep 17 00:00:00 2001 From: Michael Vrable Date: Tue, 29 May 2012 21:39:49 -0700 Subject: [PATCH] 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. --- doc/format.txt | 36 +++++++++++++++++++++--------------- main.cc | 16 +++++++++------- 2 files changed, 30 insertions(+), 22 deletions(-) diff --git a/doc/format.txt b/doc/format.txt index 2ab2696..c273e21 100644 --- 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. 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 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 --- 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 #include @@ -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()); -- 2.20.1