[[!toc  levels=3]]
# Introduction
The purpose of this document is to demonstrate 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 efficiantly 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.