| 1 | This file documents the main classes, data structures, file formats, |
|---|
| 2 | etc used in Brackup. |
|---|
| 3 | |
|---|
| 4 | ---------------------------------------------------------------------------- |
|---|
| 5 | Class-wise, we have: |
|---|
| 6 | ---------------------------------------------------------------------------- |
|---|
| 7 | |
|---|
| 8 | Root -- describes a path on the filesystem to be backed up. has as |
|---|
| 9 | properties how small large files are cut up into |
|---|
| 10 | ("chunk_size"), what files to ignore, and the encryption |
|---|
| 11 | settings. |
|---|
| 12 | |
|---|
| 13 | Target -- a destination for the backups. |
|---|
| 14 | |
|---|
| 15 | File -- a directory, symlink, or file in a Root. |
|---|
| 16 | |
|---|
| 17 | Chunk -- part of a file, defined as an offset and length. depending |
|---|
| 18 | on encryption settings, the serialized backup length can be |
|---|
| 19 | more or less than the unencrypted length. |
|---|
| 20 | |
|---|
| 21 | Backup -- a snapshot in time of all a Root's Files and Chunks. |
|---|
| 22 | during the backup, the Target is consulted to see if it |
|---|
| 23 | has chunks before they're re-stored. The backup upon |
|---|
| 24 | completion writes a structured file as described below. |
|---|
| 25 | |
|---|
| 26 | DigestDatabase -- the digest database, a property of the Root, acts |
|---|
| 27 | mostly as a cache, but is pretty important when |
|---|
| 28 | using encryption. If you lose the database, all your |
|---|
| 29 | files will need to be re-encrypted, as Brackup won't |
|---|
| 30 | know if the chunks already exist, as encryption makes |
|---|
| 31 | different files each time. Note that you don't need |
|---|
| 32 | the digest database to do a restore. |
|---|
| 33 | |
|---|
| 34 | |
|---|
| 35 | ---------------------------------------------------------------------------- |
|---|
| 36 | DigestDatabase |
|---|
| 37 | ---------------------------------------------------------------------------- |
|---|
| 38 | |
|---|
| 39 | The digest database is an SQLite file, but in theory can be anything |
|---|
| 40 | that implements a dictionary (get/set keys/values). |
|---|
| 41 | |
|---|
| 42 | The keys/values used are: |
|---|
| 43 | |
|---|
| 44 | <FileCacheKey> --> <TypedDigest(original_unencrypted_file)> |
|---|
| 45 | |
|---|
| 46 | <ChunkCacheKey> --> <ChunkDetails> |
|---|
| 47 | |
|---|
| 48 | Where: |
|---|
| 49 | |
|---|
| 50 | FileCacheKey ::= "[" <RootName> "]" <FileRelativePath> ":" join(",", <ctime>, <mtime>, <size>, <inode>) |
|---|
| 51 | |
|---|
| 52 | ChunkCacheKey ::= <TypedDigest(original_unencrypted_file)> "-" <raw_offset> "-" <raw_length> "-" <gpg-recipient> |
|---|
| 53 | |
|---|
| 54 | ChunkDetails ::= <EncryptedLength> " " <TypedDigest(encrypted_chunk)> |
|---|
| 55 | |
|---|
| 56 | TypedDigest ::= <DigestAlgo> ":" <hex_digest> |
|---|
| 57 | |
|---|
| 58 | DigestAlgo ::= { "sha1" } |
|---|
| 59 | |
|---|
| 60 | |
|---|
| 61 | ---------------------------------------------------------------------------- |
|---|
| 62 | [backup-name].brackup format (RFC-822-like) |
|---|
| 63 | ---------------------------------------------------------------------------- |
|---|
| 64 | |
|---|
| 65 | Keys: |
|---|
| 66 | ----- |
|---|
| 67 | |
|---|
| 68 | Path: relative path |
|---|
| 69 | Size: unencrypted size |
|---|
| 70 | Digest: unencrypted digest (see TypedDigest format above) |
|---|
| 71 | Type: "l" for symlink, "d" for directory, else regular file if blank |
|---|
| 72 | Link: the symlink's target |
|---|
| 73 | Chunks: whitespace-separated "offset;length;enclength;encdigest" |
|---|
| 74 | |
|---|
| 75 | Example: |
|---|
| 76 | -------- |
|---|
| 77 | |
|---|
| 78 | Path: Some file.dat |
|---|
| 79 | Size: 4550656 |
|---|
| 80 | Digest: sha1:f822dd41714070a09df1cf19e80a12720ed20b43 |
|---|
| 81 | Chunks: 0;1048576;1032436;sha1:a303f69348cf6e4c40faf199e11d6705eb200eed |
|---|
| 82 | 1048576;1048576;1041619;sha1:95e81460845f27940d209b5482c672e3ad0e8646 |
|---|
| 83 | 2097152;1048576;1041937;sha1:a7b9d3eb26cb7b9969032d62576c0c1634ed8665 |
|---|
| 84 | 3145728;1048576;1042934;sha1:645689dfc08e35851ccfb4e9d2d3eb69a684ef92 |
|---|
| 85 | 4194304;356352;343473;sha1:14e65a999edd9f2a54fc218abbee07611c9743b9 |
|---|
| 86 | |
|---|
| 87 | Path: Another file.dat |
|---|
| 88 | Size: 3184274 |
|---|
| 89 | Digest: sha1:f7e3c4b75fe041f58464c36583fec1f4361a4676 |
|---|
| 90 | Chunks: 0;1048576;1030710;sha1:af185012fcf3d178c863b2aaef76f3f83863f579 |
|---|
| 91 | 1048576;1048576;1036044;sha1:1c08a500fba4751aea5d617a92f13373d0fd057e |
|---|
| 92 | 2097152;1048576;1035307;sha1:313f9ce3ba8a5e9c5361c587fed4e55d720e48c4 |
|---|
| 93 | 3145728;38546;38510;sha1:de1687f379f8b4ce505f0ee5652f1c85505fb5be |
|---|
| 94 | |
|---|
| 95 | Path: trunk/brackup |
|---|
| 96 | Size: 1510 |
|---|
| 97 | Digest: sha1:9242d98205094044a938e79b94a1fc505bdf50fe |
|---|
| 98 | Chunks: 0;1510;1819;sha1:34ddb242c4d88a4df82145de2b04dd6c0d26cd58 |
|---|
| 99 | |
|---|
| 100 | Path: trunk/brackup.dat |
|---|
| 101 | Size: 15151 |
|---|
| 102 | Digest: sha1:1e427622cadb31ea006c273b86457178f38a7c75 |
|---|
| 103 | Chunks: 0;15151;5096;sha1:5672f3d6ee89d0c7a039fc050ad4c315f3580533 |
|---|
| 104 | |
|---|
| 105 | Path: trunk/B_TO_THE_BIZZLE |
|---|
| 106 | Type: l |
|---|
| 107 | Link: F_TO_THE_FIZZLE |
|---|
| 108 | |
|---|
| 109 | Path: trunk/.svn |
|---|
| 110 | Type: d |
|---|
| 111 | |
|---|
| 112 | Path: trunk/.svn/entries |
|---|
| 113 | Size: 686 |
|---|
| 114 | Digest: sha1:9a9b269fa1c7ae74ca0a1a08f028c4e294bf9128 |
|---|
| 115 | Chunks: 0;686;1465;sha1:346d53cd2366efb4cb8b4ae918e860f0244dbd5d |
|---|
