tools - Implement a simple hammer-backup script.
[dragonfly.git] / tools / tools / hammer-backup / README
CommitLineData
7962c9dc
AHJ
11. What is hammer-backup?
2
3This script operates HAMMER PFSes and dumps its contents for backup
4purposes.
5
6It uses mirror-read directive (see 'man 8 hammer') to perform a
7dump to stdout that is redirected to a file with or without
8compression.
9
10It can take two types of backup:
11
12 a) Full: Where ALL the data of the PFS is sent to a file.
13 b) Inremental: It requires a previous full backup.
14
15Additionally to the backup data itself, it creates a .bkp file
16which contains metadata relative to the full and/or incremental
17backups.
18
19The format is the following
20
21 filename,rsv01,rsv02,backup type,shared uuid,last TID,md5 hash
22
23 filename : Backup data file file.
24 rsv01,rsv02: Reserved fields
25 backup type: 1 or 2 (full or incremental, respectively)
26 shared uuid: PFS shared UUID for mirror ops
27 last TID : Last transaction ID. Next incr. backup starting TID
28 md5 hash : For restoring purposes
29
30Example:
31 $ head -1 20140305222026_pfs_t1_full.xz.bkp
32 20140305222026_pfs_t1_full.xz.bkp,,,f,e8decfc5-a4ab-11e3-942b-f56d04d293e0,000000011b36be30,05482d26644bd1e76e69d83002e08258
33
342. How to use it?
35
36General usage.
37
38Usage: hammer-backup [-h] [-v] [-i <full-backup-file>] [-f] [-c <compress-rate>] -d [<backup-dir>] <path-to-PFS>
39
40 -h: Help outputo above.
41 -v: Verbose
42 -i <full-backup-file>: Incremental backup. Needs the full backup metadata file.
43 Relative path to -d
44 -f: Full backup
45 -c: Compress rate for xz(1)
46 -d: Backup directory
47 <path-to-PFS>: PFS path to backup
48
492.1 Performing a full backup
50
51# ./hammer-backup -v -f -c 6 -d /root/backups /pfs/var
52INFO: Full backup.
53INFO: XZ compression level 6.
54INFO: Backup directory is /root/backups.
55INFO: Validating PFS
56INFO: Initiating full backup
57INFO: Launching: hammer -y -v mirror-read /pfs/var 2> /tmp/tmp.UdOwvYhv | xz -c -6 > /root/backups/20140308001146_pfs_var.xz
58INFO: Backup completed.
59
60NOTE: -v is optional. Also note /pfs/var is found in standard installations.
61
622.2 Perform an incremental backup over a full one
63
64First list the backups avail:
65
66# ./hammer-backup -l -d /root/backups
6720140308001146_pfs_var.xz.bkp:
68 full: 20140308001146_pfs_var.xz endtid: 0x000000011db6dc20 md5: 303ee864f4a747d9da7d556e83b05de5
69
70You can then specify the .bkp file you want. See the timestamp, and the path to
71PFS separated by '_' are embedded to it.
72
73# ./hammer-backup -c 6 -v -i 20140308001146_pfs_var.xz.bkp -d /root/backups /pfs/var
74INFO: Incremental backup.
75INFO: Backup directory is /root/backups.
76INFO: Validating PFS
77INFO: Initiating incremental backup
78INFO: Launching: hammer -y -v mirror-read /pfs/var 0x000000011db6dc20 2> /tmp/tmp.AleUwNnA | xz -c -6 > /root/backups/20140308002450_pfs_var.xz
79INFO: Backup completed.
80
81# ./hammer-backup -l -d /root/backups
8220140308001146_pfs_var.xz.bkp:
83 full: 20140308001146_pfs_var.xz endtid: 0x000000011db6dc20 md5: 303ee864f4a747d9da7d556e83b05de5
84 incr: 20140308002450_pfs_var.xz endtid: 0x000000011db6e440 md5: 7a7c2799b880a293f2c8270c6a9b22aa
85
863.0 Recovering a PFS.
87
88If you are very familiar with HAMMER you can do it manually, so following our
89previous example:
90
91 - Locate the backup we want to recover.
92 # ./hammer-backup -l -d /root/backups
93 20140308001146_pfs_var.xz.bkp:
94 full: 20140308001146_pfs_var.xz endtid: 0x000000011db6dc20 md5: 303ee864f4a747d9da7d556e83b05de5
95 incr: 20140308002450_pfs_var.xz endtid: 0x000000011db6e440 md5: 7a7c2799b880a293f2c8270c6a9b22aa
96
97 - Mirror-write the files in the correct order. First the full, then the
98 incremental ones. NOTE: -y on the hammer command will actually create
99 a slave PFS.
100 # unxz -c /root/backups/20140308001146_pfs_var.xz | hammer -y mirror-write /pfs/var_2
101 PFS slave /pfs/var_2 does not exist. Auto create new slave PFS!
102 Creating PFS #10 succeeded!
103 /pfs/var_2
104 sync-beg-tid=0x0000000000000001
105 sync-end-tid=0x0000000000000001
106 shared-uuid=ce020232-9a71-11e3-8278-f56d04d293e0
107 unique-uuid=e569a0c9-a650-11e3-942b-f56d04d293e0
108 slave
109 label=""
110 prune-min=00:00:00
111 operating as a SLAVE
112 snapshots directory defaults to /var/hammer/<pfs>
113 Source can update synctid to 0x000000011db6dc20
114
115 - Next, incremental ones:
116 # unxz -c /root/backups/20140308002450_pfs_var.xz | hammer -y mirror-write /pfs/var_2
117 Source can update synctid to 0x000000011db6e440
118
119 - Once done, you can just upgrade the /pfs/var_2
120 # hammer pfs-upgrade /pfs/var_2
121 pfs-upgrade of PFS#10 () succeeded
122
123For the example we used you have to make sure no process is using the current
124/var PFS, and if none is you can just go ahead and unmount it. Afterwards you
125can modify the symbolic link in /pfs to point to the restored one as needed.
126
1274.0 Manipulating dumps
128
129You can upload the .xz files and the .bkp files whenever you want, for example a
130remote FTP server.