kernel - Fix boot-time panic in NATA revealed by new callout mechanics
[dragonfly.git] / tools / tools / hammer-backup / README
1 1. What is hammer-backup?
2
3 This script operates HAMMER PFSes and dumps its contents for backup
4 purposes.
5
6 It uses mirror-read directive (see 'man 8 hammer') to perform a
7 dump to stdout that is redirected to a file with or without
8 compression.
9
10 It 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
15 Additionally to the backup data itself, it creates a .bkp file
16 which contains metadata relative to the full and/or incremental
17 backups.
18
19 The 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
30 Example:
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
34 2. How to use it?
35
36 General usage.
37
38 Usage: hammer-backup.sh [-h] [-l] [-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. You can specify 'auto' and the
44                         script should determine what's the latest full backup.
45  -f: Full backup
46  -c: Compress rate for xz(1)
47  -d: Backup directory
48  -l: List backups from backup directory.
49  -k: Validates integrity of all backup files.
50  <path-to-PFS>: PFS path to backup
51
52 2.1 Performing a full backup
53
54 # ./hammer-backup -v -f -c 6 -d /root/backups /pfs/var
55 INFO: Full backup.
56 INFO: XZ compression level 6.
57 INFO: Backup directory is /root/backups.
58 INFO: Validating PFS
59 INFO: Initiating full backup
60 INFO: Launching: hammer -y -v mirror-read /pfs/var  2> /tmp/tmp.UdOwvYhv         | xz -c -6 > /root/backups/20140308001146_pfs_var.xz
61 INFO: Backup completed.
62
63 NOTE: -v is optional. Also note /pfs/var is found in standard installations.
64
65 2.2 Perform an incremental backup over a full one
66
67 First list the backups available:
68
69 # ./hammer-backup -l -d /root/backups
70 20140308001146_pfs_var.xz.bkp:
71  full: 20140308001146_pfs_var.xz endtid: 0x000000011db6dc20 md5: 303ee864f4a747d9da7d556e83b05de5
72
73 You can then specify the .bkp file you want. See the timestamp, and the path to
74 PFS separated by '_' are embedded to it.
75
76 # ./hammer-backup -c 6 -v -i 20140308001146_pfs_var.xz.bkp -d /root/backups /pfs/var
77 INFO: Incremental backup.
78 INFO: Backup directory is /root/backups.
79 INFO: Validating PFS
80 INFO: Initiating incremental backup
81 INFO: Launching: hammer -y -v mirror-read /pfs/var 0x000000011db6dc20 2> /tmp/tmp.AleUwNnA       | xz -c -6 > /root/backups/20140308002450_pfs_var.xz
82 INFO: Backup completed.
83
84 # ./hammer-backup -l -d /root/backups
85 20140308001146_pfs_var.xz.bkp:
86  full: 20140308001146_pfs_var.xz endtid: 0x000000011db6dc20 md5: 303ee864f4a747d9da7d556e83b05de5
87         incr: 20140308002450_pfs_var.xz endtid: 0x000000011db6e440 md5: 7a7c2799b880a293f2c8270c6a9b22aa
88
89 3.0 Recovering a PFS.
90
91 If you are very familiar with HAMMER you can do it manually, so following our
92 previous example:
93
94  - Locate the backup we want to recover.
95    # ./hammer-backup -l -d /root/backups
96    20140308001146_pfs_var.xz.bkp:
97     full: 20140308001146_pfs_var.xz endtid: 0x000000011db6dc20 md5: 303ee864f4a747d9da7d556e83b05de5
98          incr: 20140308002450_pfs_var.xz endtid: 0x000000011db6e440 md5: 7a7c2799b880a293f2c8270c6a9b22aa
99
100  - Mirror-write the files in the correct order. First the full, then the
101    incremental ones. NOTE: -y on the hammer command will actually create
102    a slave PFS.
103    # unxz -c /root/backups/20140308001146_pfs_var.xz | hammer -y mirror-write /pfs/var_2
104    PFS slave /pfs/var_2 does not exist. Auto create new slave PFS!
105    Creating PFS #10        succeeded!
106    /pfs/var_2
107        sync-beg-tid=0x0000000000000001
108        sync-end-tid=0x0000000000000001
109        shared-uuid=ce020232-9a71-11e3-8278-f56d04d293e0
110        unique-uuid=e569a0c9-a650-11e3-942b-f56d04d293e0
111        slave
112        label=""
113        prune-min=00:00:00
114        operating as a SLAVE
115        snapshots directory defaults to /var/hammer/<pfs>
116    Source can update synctid to 0x000000011db6dc20
117
118  - Next, incremental ones:
119    # unxz -c /root/backups/20140308002450_pfs_var.xz | hammer -y mirror-write /pfs/var_2
120    Source can update synctid to 0x000000011db6e440
121
122  - Once done, you can just upgrade the /pfs/var_2
123    # hammer pfs-upgrade /pfs/var_2
124    pfs-upgrade of PFS#10 () succeeded
125
126 For the example we used you have to make sure no process is using the current
127 /var PFS, and if none is you can just go ahead and unmount it. Afterwards you
128 can modify the symbolic link in /pfs to point to the restored one as needed.
129
130 4.0 Manipulating dumps
131
132 You can upload the .xz files and the .bkp files whenever you want, for example a
133 remote FTP server.