docs/docs/howtos/howtorecoverdataonhammerfs/index.mdwn

   1 [[!toc  levels=3]]
   2 # Introduction
   3 The purpose of this document is to demonstrate to the reader how to restore data on a hammer
   4 filesystem(files/directories). This will also cover how to adjust history retention.
   5
   6 # Getting history records of a file
   7
   8 To get all history records of a file we will use hammer utility with 'history' command giving it
   9 file name as argument.
  10
  11         # echo "Hello" > test
  12         # hammer history test
  13         test    0000000110d66ec3 clean {
  14            0000000110d6e970 04-Jan-2011 15:36:38
  15         }
  16
  17         # echo "world" >> test
  18         # hammer history test
  19         test    0000000110d66ec3 clean {
  20            0000000110d6e970 04-Jan-2011 15:36:38
  21            0000000110d6e9d0 04-Jan-2011 15:37:09
  22         }
  23
  24         # echo "some more data" >> test
  25         # hammer history test
  26         test    0000000110d66ec3 clean {
  27            0000000110d6e970 04-Jan-2011 15:36:38
  28            0000000110d6e9d0 04-Jan-2011 15:37:09
  29            0000000110d6ea10 04-Jan-2011 15:37:40
  30         }
  31
  32 You probably wonder what are these strange hexadecimal numbers are:
  33
  34        0000000110d6e970
  35            0000000110d6e9d0
  36            0000000110d6ea10
  37
  38 Well, they are transaction ids. Transaction id is a 64 bit hexadecimal number used by hammer file
  39 system to refer to historical file or directory data.You will need them to restore file to a prior
  40 version.
  41
  42 #File restoring
  43
  44 To restore a file to a prior version we will use **undo** utility. For example lets restore the test
  45 file to it's prior version created in previous section.
  46
  47         # hammer history test
  48         test    0000000110d66ec3 clean {
  49            0000000110d6e970 04-Jan-2011 15:36:38
  50            0000000110d6e9d0 04-Jan-2011 15:37:09
  51            0000000110d6ea10 04-Jan-2011 15:37:40
  52         }
  53
  54 Get data that refers to transaction id and put it in test.old
  55
  56         # undo -o test.old -t 0x0000000110d6e9d0 test
  57         # cat test.old
  58         Hello
  59         world
  60         # cat test
  61         Hello
  62         world
  63         some more data
  64
  65 You can aslo specify the 'd' flag and get a diff output
  66
  67     # undo -d -o test.diff -t 0x0000000110d6e9d0 test
  68     # cat test.diff
  69     --- test@@0x000000110d6e9d0   2010-01-04 15:36:31 -0600
  70     +++ test       2011-01-04 15:37:32 -0600
  71     @@ -1,2 +1,3 @@
  72      Hello
  73      world
  74     +some more data
  75
  76 # Directory restoring
  77
  78 To restore directory to a prior version we are going to be using **cpdup** command and special hammer notation '@@'.
  79
  80 first we need to get history records for the directory, to get them we are going to use **undo** utility.
  81
  82         # undo -ai test
  83         test: ITERATE ENTIRE HISTORY
  84                0x00000001126152b0 04-Jan-2011 21:08:22
  85                0x0000000112615330 04-Jan-2011 21:08:42
  86         # ls test
  87         testfile1 testfile2
  88
  89 As you can see i already create two files in the test directory.
  90 Now lets restore prior version of the test directory.
  91
  92         # cpdup test@@0x00000001126152b0 testold
  93         # ls testold
  94         testfile1
  95
  96 You can use '@@' notation to access to prior versions of files or directories.
  97 Example:
  98
  99         dirname/filename@@0x_64bit tid
 100
 101 However the common way of accessing history is by taking a snapshot.
 102
 103 # Adjusting History retention
 104 Hammer will efficiently fill your hard disk with history if you don't prune, or defrag.To cleanup and free space there is a **hammer cleanup** command it reblocks,prunes,rebalances,etc. DragonFly runs it by the default nightly via [periodic(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=periodic&section=8).
 105
 106 **hammer cleanup** will access the configuration file for each filesystem, creating them if necessary.
 107
 108 The format of the configuration file(**hammer viconfig** filesystem):
 109
 110            snapshots  <period> <retention-time> [any]
 111            prune      <period> <max-runtime>
 112            rebalance  <period> <max-runtime>
 113            dedup      <period> <max-runtime>
 114            reblock    <period> <max-runtime>
 115            recopy     <period> <max-runtime>
 116
 117 Defaults are:
 118
 119            snapshots  1d 60d
 120            prune      1d 5m
 121            rebalance  1d 5m
 122            dedup      1d 5m
 123            reblock    1d 5m
 124            recopy     30d 10m
 125
 126 If period hasn't passed since the previous cleanup run nothing is done.
 127
 128 By the default configuration file a daily snapshot will be created daily and kept for 60 days, you can find your snapshots in /var/hammer/&lt;pfs&gt;/snapshots.
 129 For the other actions (prune, rebalance, dedup, reblock, recopy), the second parameter is the maximum time the action may take.
 130
 131 For instance
 132            dedup      1d 30m
 133 means, that once per day, your hammer file systems will be deduplicated for up to 30 minutes.
 134
 135 Reblocking will reorder all elements and thus defragment the file system and free space for reuse. And do a montly recopy run.
 136
 137 You can read the full details HAMMER(8).