(no commit message)

diff --git a/docs/docs/howtos/howtorecoverdataonhammerfs/index.mdwn b/docs/docs/howtos/howtorecoverdataonhammerfs/index.mdwn
new file mode 100644 (file)
index 0000000..8f3cec5
--- /dev/null
+++ b/docs/docs/howtos/howtorecoverdataonhammerfs/index.mdwn
@@ -0,0 +1,134 @@
+[[!toc  levels=3]]
+# Introduction
+The purpose of this document is to demonstarate to the reader how to restore data on a hammer 
+filesystem(files/directories). This will also cover how to adjust history retention.
+
+# Getting history records of a file
+
+To get all history records of a file we will use hammer utility with 'history' command giving it 
+file name as argument.
+
+       # echo "Hello" > test
+       # hammer history test
+       test    0000000110d66ec3 clean {
+          0000000110d6e970 04-Jan-2011 15:36:38
+       }
+
+       # echo "world" >> test
+       # hammer history test   
+       test    0000000110d66ec3 clean {
+          0000000110d6e970 04-Jan-2011 15:36:38
+          0000000110d6e9d0 04-Jan-2011 15:37:09
+       }
+
+       # echo "some more data" >> test
+       # hammer history test
+       test    0000000110d66ec3 clean {
+          0000000110d6e970 04-Jan-2011 15:36:38
+          0000000110d6e9d0 04-Jan-2011 15:37:09
+          0000000110d6ea10 04-Jan-2011 15:37:40
+       }
+
+You probably wonder what are these strange hexadecimal numbers are:
+
+       0000000110d6e970
+          0000000110d6e9d0
+          0000000110d6ea10
+
+Well, they are transaction ids. Transaction id is a 64 bit hexadecimal number used by hammer file 
+system to refer to historical file or directory data.You will need them to restore file to a prior 
+version.
+
+#File restoring
+
+To restore a file to a prior version we will use **undo** utility. For example lets restore the test 
+file to it's prior version created in previous section.
+
+       # hammer history test
+       test    0000000110d66ec3 clean { 
+          0000000110d6e970 04-Jan-2011 15:36:38
+          0000000110d6e9d0 04-Jan-2011 15:37:09
+          0000000110d6ea10 04-Jan-2011 15:37:40
+       }
+
+Get data that refers to transaction id and put it in test.old
+
+       # undo -o test.old -t 0x0000000110d6e9d0 test
+       # cat test.old
+       Hello
+       world
+       # cat test
+       Hello
+       world
+       some more data
+
+You can aslo specify the 'd' flag and get a diff output
+
+    # undo -d -o test.diff -t 0x0000000110d6e9d0 test
+    # cat test.diff
+    --- test@@0x000000110d6e9d0   2010-01-04 15:36:31 -0600
+    +++ test       2011-01-04 15:37:32 -0600
+    @@ -1,2 +1,3 @@
+     Hello
+     world
+    +some more data
+
+# Directory restoring
+
+To restore directory to a prior version we are going to be using **cpdup** command and special hammer notation '@@'.
+
+first we need to get history records for the directory, to get them we are going to use **undo** utility.
+
+       # undo -ai test
+       test: ITERATE ENTIRE HISTORY
+              0x00000001126152b0 04-Jan-2011 21:08:22
+              0x0000000112615330 04-Jan-2011 21:08:42
+       # ls test
+       testfile1 testfile2
+
+As you can see i already create two files in the test directory.
+Now lets restore prior version of the test directory.
+
+       # cpdup test@@0x00000001126152b0 testold
+       # ls testold
+       testfile1
+
+You can use '@@' notation to access to prior versions of files or directories.
+Example:
+
+       dirname/filename@@0x_64bit tid
+
+However the common way of accessing history is by taking a snapshot.
+
+# Adjusting History retention
+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).
+
+**hammer cleanup** will access the configuration file for each filesystem, creating them if necessary.
+
+The format of the configuration file(**hammer viconfig** filesystem):
+
+          snapshots  <period> <retention-time> [any]
+          prune      <period> <max-runtime>
+          rebalance  <period> <max-runtime>
+          dedup      <period> <max-runtime>
+          reblock    <period> <max-runtime>
+          recopy     <period> <max-runtime>
+
+Defaults are:
+
+          snapshots  1d 60d
+          prune      1d 5m
+          rebalance  1d 5m
+          dedup      1d 5m
+          reblock    1d 5m
+          recopy     30d 10m
+
+If period hasn't passed since the previous cleanup run nothing is done.
+
+By the default configuration file will create a daily snapshot, basicly what it means is it will make a snapshot every 24hr for 60 days, you can find your snapshots in /var/hammer/<pfs>/snapshots.
+It will aslo do a daily pruning for example if you want it to run everyday for 30 minutes the configuration will look like this:
+
+           prune      1d 30m
+
+rebalancing, deduping(This feature is introduced in 2.9 DragonFly kernel version wich at the moment is being developed),
+reblocking - reblocking will reorder all elements and thus defragment the file system and free space for reuse. And do a montly recopy run.