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.