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 [-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
  49 2.1 Performing a full backup
  50
  51 # ./hammer-backup -v -f -c 6 -d /root/backups /pfs/var
  52 INFO: Full backup.
  53 INFO: XZ compression level 6.
  54 INFO: Backup directory is /root/backups.
  55 INFO: Validating PFS
  56 INFO: Initiating full backup
  57 INFO: Launching: hammer -y -v mirror-read /pfs/var  2> /tmp/tmp.UdOwvYhv         | xz -c -6 > /root/backups/20140308001146_pfs_var.xz
  58 INFO: Backup completed.
  59
  60 NOTE: -v is optional. Also note /pfs/var is found in standard installations.
  61
  62 2.2 Perform an incremental backup over a full one
  63
  64 First list the backups avail:
  65
  66 # ./hammer-backup -l -d /root/backups
  67 20140308001146_pfs_var.xz.bkp:
  68  full: 20140308001146_pfs_var.xz endtid: 0x000000011db6dc20 md5: 303ee864f4a747d9da7d556e83b05de5
  69
  70 You can then specify the .bkp file you want. See the timestamp, and the path to
  71 PFS separated by '_' are embedded to it.
  72
  73 # ./hammer-backup -c 6 -v -i 20140308001146_pfs_var.xz.bkp -d /root/backups /pfs/var
  74 INFO: Incremental backup.
  75 INFO: Backup directory is /root/backups.
  76 INFO: Validating PFS
  77 INFO: Initiating incremental backup
  78 INFO: Launching: hammer -y -v mirror-read /pfs/var 0x000000011db6dc20 2> /tmp/tmp.AleUwNnA       | xz -c -6 > /root/backups/20140308002450_pfs_var.xz
  79 INFO: Backup completed.
  80
  81 # ./hammer-backup -l -d /root/backups
  82 20140308001146_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
  86 3.0 Recovering a PFS.
  87
  88 If you are very familiar with HAMMER you can do it manually, so following our
  89 previous 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
 123 For 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
 125 can modify the symbolic link in /pfs to point to the restored one as needed.
 126
 127 4.0 Manipulating dumps
 128
 129 You can upload the .xz files and the .bkp files whenever you want, for example a
 130 remote FTP server.