Sentence made no sense before. Also, 2.9 is no longer "being developed currently".
[ikiwiki.git] / 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 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/&lt;pfs&gt;/snapshots.
129 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:
130
131            prune      1d 30m
132
133 Reblocking will reorder all elements and thus defragment the file system and free space for reuse. And do a montly recopy run.