Commit | Line | Data |
---|---|---|
0dfeb6c8 | 1 | .\" Copyright (c) 2007 The DragonFly Project. All rights reserved. |
7bb56fa9 | 2 | .\" |
0dfeb6c8 MD |
3 | .\" This code is derived from software contributed to The DragonFly Project |
4 | .\" by Matthew Dillon <dillon@backplane.com> | |
7bb56fa9 | 5 | .\" |
0dfeb6c8 MD |
6 | .\" Redistribution and use in source and binary forms, with or without |
7 | .\" modification, are permitted provided that the following conditions | |
8 | .\" are met: | |
7bb56fa9 | 9 | .\" |
0dfeb6c8 MD |
10 | .\" 1. Redistributions of source code must retain the above copyright |
11 | .\" notice, this list of conditions and the following disclaimer. | |
12 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
13 | .\" notice, this list of conditions and the following disclaimer in | |
14 | .\" the documentation and/or other materials provided with the | |
15 | .\" distribution. | |
16 | .\" 3. Neither the name of The DragonFly Project nor the names of its | |
17 | .\" contributors may be used to endorse or promote products derived | |
18 | .\" from this software without specific, prior written permission. | |
7bb56fa9 | 19 | .\" |
0dfeb6c8 MD |
20 | .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
21 | .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | |
22 | .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS | |
23 | .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE | |
24 | .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, | |
25 | .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, | |
26 | .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; | |
27 | .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED | |
28 | .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, | |
29 | .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT | |
30 | .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
31 | .\" SUCH DAMAGE. | |
7bb56fa9 | 32 | .\" |
173523ff | 33 | .Dd September 21, 2015 |
0dfeb6c8 MD |
34 | .Dt HAMMER 8 |
35 | .Os | |
36 | .Sh NAME | |
37 | .Nm hammer | |
38 | .Nd HAMMER file system utility | |
39 | .Sh SYNOPSIS | |
40 | .Nm | |
4567021b TN |
41 | .Fl h |
42 | .Nm | |
5e1e1454 | 43 | .Op Fl 2ABFqrvXy |
48eadef9 | 44 | .Op Fl b Ar bandwidth |
5f22d366 | 45 | .Op Fl C Ar cachesize Ns Op Ns Cm \&: Ns Ar readahead |
69f5a58c MD |
46 | .Op Fl R Ar restrictcmd |
47 | .Op Fl T Ar restrictpath | |
d7ae405c | 48 | .Op Fl c Ar cyclefile |
269cdd19 | 49 | .Op Fl e Ar scoreboardfile |
f6532f03 | 50 | .Op Fl f Ar blkdevs |
6d9ab5c5 | 51 | .\" .Op Fl s Ar linkpath |
48eadef9 | 52 | .Op Fl i Ar delay |
6c45ca3e | 53 | .Op Fl p Ar ssh-port |
3d7b2393 | 54 | .Op Fl S Ar splitsize |
5f22d366 | 55 | .Op Fl t Ar seconds |
fbe1c665 | 56 | .Op Fl m Ar memlimit |
0dfeb6c8 | 57 | .Ar command |
34bb69d8 | 58 | .Op Ar argument ... |
0dfeb6c8 | 59 | .Sh DESCRIPTION |
6d9ab5c5 | 60 | This manual page documents the |
0dfeb6c8 | 61 | .Nm |
6d9ab5c5 | 62 | utility which provides miscellaneous functions related to managing a |
b4448f1a TN |
63 | .Nm HAMMER |
64 | file system. | |
65 | For a general introduction to the | |
66 | .Nm HAMMER | |
67 | file system, its features, and | |
6d9ab5c5 | 68 | examples on how to set up and maintain one, see |
b4448f1a | 69 | .Xr HAMMER 5 . |
0dfeb6c8 MD |
70 | .Pp |
71 | The options are as follows: | |
72 | .Bl -tag -width indent | |
d4e5b69b MD |
73 | .It Fl 2 |
74 | Tell the mirror commands to use a 2-way protocol, which allows | |
2010519f TN |
75 | automatic negotiation of transaction id ranges. |
76 | This option is automatically enabled by the | |
4567021b | 77 | .Cm mirror-copy |
d4e5b69b | 78 | command. |
5e1e1454 TK |
79 | .It Fl A |
80 | Make per PFS commands perform on all PFSs if possible. | |
81 | If the command supports this option, it targets all PFSs of the | |
82 | .Nm HAMMER | |
83 | filesystem that the | |
84 | .Ar filesystem | |
85 | argument (of that command) belongs to. | |
86 | Currently | |
87 | .Cm rebalance , | |
88 | .Cm reblock , | |
89 | .Cm reblock-btree , | |
90 | .Cm reblock-inodes , | |
91 | .Cm reblock-dirs | |
92 | and | |
93 | .Cm reblock-data | |
94 | commands support this option. | |
95 | If the command does not support this option, it does nothing. | |
5f22d366 TN |
96 | .It Fl B |
97 | Bulk transfer. | |
98 | .Cm Mirror-stream | |
99 | will not attempt to break-up large initial bulk transfers into smaller | |
100 | pieces. | |
101 | This can save time but if the link is lost in the middle of the | |
102 | initial bulk transfer you will have to start over from scratch. | |
103 | For more information see the | |
104 | .Fl S | |
105 | option. | |
48eadef9 MD |
106 | .It Fl b Ar bandwidth |
107 | Specify a bandwidth limit in bytes per second for mirroring streams. | |
108 | This option is typically used to prevent batch mirroring operations from | |
109 | loading down the machine. | |
15fa4caf | 110 | The bandwidth may be suffixed with |
4567021b | 111 | .Cm k , m , |
15fa4caf | 112 | or |
4567021b | 113 | .Cm g |
2010519f | 114 | to specify values in kilobytes, megabytes, and gigabytes per second. |
224ac2f2 | 115 | If no suffix is specified, bytes per second is assumed. |
527a7bdb MD |
116 | .Pp |
117 | Unfortunately this is only applicable to the pre-compression bandwidth | |
118 | when compression is used, so a better solution would probably be to | |
119 | use a | |
120 | .Xr ipfw 8 | |
121 | pipe or a | |
122 | .Xr pf 4 | |
123 | queue. | |
5f22d366 TN |
124 | .It Fl C Ar cachesize Ns Op Ns Cm \&: Ns Ar readahead |
125 | Set the memory cache size for any raw | |
126 | .Tn I/O . | |
127 | The default is 16MB. | |
128 | A suffix of | |
129 | .Cm k | |
130 | for kilobytes and | |
131 | .Cm m | |
132 | for megabytes is allowed, | |
133 | else the cache size is specified in bytes. | |
134 | .Pp | |
135 | The read-behind/read-ahead defaults to 4 | |
136 | .Nm HAMMER | |
137 | blocks. | |
138 | .Pp | |
139 | This option is typically only used with diagnostic commands | |
140 | as kernel-supported commands will use the kernel's buffer cache. | |
69f5a58c MD |
141 | .It Fl R Ar restrictcmd |
142 | This option is used by hammer ssh-remote to restrict the command later | |
143 | on in the argument list. Multiple commands may be specified, separated | |
144 | by a comma (all one argument). | |
145 | .It Fl T Ar restrictpath | |
146 | This option is used by hammer ssh-remote to restrict the filesystem path | |
147 | specified later on in the argument list. | |
d7ae405c | 148 | .It Fl c Ar cyclefile |
aaf93065 | 149 | When pruning, rebalancing or reblocking you can tell the utility |
2010519f | 150 | to start at the object id stored in the specified file. |
84082922 | 151 | If the file does not exist |
15fa4caf | 152 | .Nm |
84082922 TN |
153 | will start at the beginning. |
154 | If | |
15fa4caf | 155 | .Nm |
5f22d366 TN |
156 | is told to run for a specific period of time |
157 | .Pq Fl t | |
158 | and is unable to complete the operation it will write out | |
159 | the current object id so the next run can pick up where it left off. | |
84082922 TN |
160 | If |
161 | .Nm | |
483bb69b TN |
162 | runs to completion it will delete |
163 | .Ar cyclefile . | |
269cdd19 MD |
164 | .It Fl e Ar scoreboardfile |
165 | Update scoreboard file with progress, primarily used by mirror-stream. | |
5f22d366 TN |
166 | .It Fl F |
167 | Force operation. | |
168 | E.g.\& | |
169 | .Cm cleanup | |
170 | will not check that time period has elapsed if this option is given. | |
f6532f03 | 171 | .It Fl f Ar blkdevs |
b4448f1a TN |
172 | Specify the volumes making up a |
173 | .Nm HAMMER | |
174 | file system. | |
f6532f03 TN |
175 | .Ar Blkdevs |
176 | is a colon-separated list of devices, each specifying a | |
177 | .Nm HAMMER | |
178 | volume. | |
5f22d366 TN |
179 | .It Fl h |
180 | Show usage. | |
48eadef9 | 181 | .It Fl i Ar delay |
5f22d366 TN |
182 | Specify delay in seconds for |
183 | .Cm mirror-read-stream . | |
48eadef9 MD |
184 | When maintaining a streaming mirroring this option specifies the |
185 | minimum delay after a batch ends before the next batch is allowed | |
186 | to start. | |
187 | The default is five seconds. | |
fbe1c665 MD |
188 | .It Fl m Ar memlimit |
189 | Specify the maximum amount of memory | |
190 | .Nm | |
191 | will allocate during a dedup pass. | |
0362ff63 | 192 | Specify a suffix 'm', 'g', or 't' for megabytes, gigabytes, or terabytes. |
fbe1c665 MD |
193 | By default |
194 | .Nm | |
195 | will allocate up to 1G of ram to hold CRC/SHA tables while running dedup. | |
196 | When the limit is reached the dedup code restricts the range of CRCs to | |
197 | keep memory use within bounds and runs multiple passes as necessary until | |
198 | the entire filesystem has been deduped. | |
6c45ca3e | 199 | .It Fl p Ar ssh-port |
5f22d366 | 200 | Pass the |
aaf93065 TN |
201 | .Fl p Ar ssh-port |
202 | option to | |
203 | .Xr ssh 1 | |
204 | when using a remote | |
6c45ca3e | 205 | specification for the source and/or destination. |
e95314de | 206 | .It Fl q |
bb92c669 | 207 | Decrease verboseness. |
2010519f | 208 | May be specified multiple times. |
bb8e52c0 TN |
209 | .It Fl r |
210 | Specify recursion for those commands which support it. | |
3d7b2393 MD |
211 | .It Fl S Ar splitsize |
212 | Specify the bulk splitup size in bytes for mirroring streams. | |
aaf93065 TN |
213 | When a |
214 | .Cm mirror-stream | |
215 | is first started | |
3d7b2393 MD |
216 | .Nm |
217 | will do an initial run-through of the data to calculate good | |
27eff55e | 218 | transaction ids to cut up the bulk transfers, creating |
3d7b2393 MD |
219 | restart points in case the stream is interrupted. |
220 | If we don't do this and the stream is interrupted it might | |
221 | have to start all over again. | |
5f22d366 TN |
222 | The default is a |
223 | .Ar splitsize | |
224 | of 4GB. | |
3d7b2393 MD |
225 | .Pp |
226 | At the moment the run-through is disk-bandwidth-heavy but some | |
227 | future version will limit the run-through to just the B-Tree | |
228 | records and not the record data. | |
229 | .Pp | |
230 | The splitsize may be suffixed with | |
231 | .Cm k , m , | |
232 | or | |
233 | .Cm g | |
aaf93065 | 234 | to specify values in kilobytes, megabytes, or gigabytes. |
3d7b2393 | 235 | If no suffix is specified, bytes is assumed. |
527a7bdb MD |
236 | .Pp |
237 | When mirroring very large filesystems the minimum recommended | |
5f22d366 | 238 | split size is 4GB. |
527a7bdb MD |
239 | A small split size may wind up generating a great deal of overhead |
240 | but very little actual incremental data and is not recommended. | |
5f22d366 TN |
241 | .It Fl t Ar seconds |
242 | Specify timeout in seconds. | |
243 | When pruning, rebalancing, reblocking or mirror-reading | |
244 | you can tell the utility to stop after a certain period of time. | |
245 | A value of 0 means unlimited. | |
246 | This option is used along with the | |
247 | .Fl c Ar cyclefile | |
248 | option to prune, rebalance or reblock incrementally. | |
249 | .It Fl v | |
250 | Increase verboseness. | |
251 | May be specified multiple times. | |
3a998207 | 252 | .It Fl X |
aaf93065 | 253 | Enable compression for any remote ssh specifications. |
aaf93065 TN |
254 | This option is typically used with the mirroring directives. |
255 | .It Fl y | |
5f22d366 TN |
256 | Force |
257 | .Dq yes | |
258 | for interactive questions. | |
0dfeb6c8 MD |
259 | .El |
260 | .Pp | |
261 | The commands are as follows: | |
262 | .Bl -tag -width indent | |
15fa4caf | 263 | .\" ==== synctid ==== |
4567021b | 264 | .It Cm synctid Ar filesystem Op Cm quick |
5f22d366 | 265 | Generate a guaranteed, formal 64-bit transaction id representing the |
b4448f1a TN |
266 | current state of the specified |
267 | .Nm HAMMER | |
2010519f TN |
268 | file system. |
269 | The file system will be synced to the media. | |
367431cf MD |
270 | .Pp |
271 | If the | |
4567021b | 272 | .Cm quick |
b4448f1a TN |
273 | keyword is specified the file system will be soft-synced, meaning that a |
274 | crash might still undo the state of the file system as of the transaction | |
367431cf MD |
275 | id returned but any new modifications will occur after the returned |
276 | transaction id as expected. | |
bf2c6489 | 277 | .Pp |
16265794 TN |
278 | This operation does not create a snapshot. |
279 | It is meant to be used | |
bf2c6489 | 280 | to track temporary fine-grained changes to a subset of files and |
16265794 TN |
281 | will only remain valid for |
282 | .Ql @@ | |
5f22d366 | 283 | access purposes for the |
bf2c6489 | 284 | .Cm prune-min |
16265794 TN |
285 | period configured for the PFS. |
286 | If you desire a real snapshot then the | |
bf2c6489 MD |
287 | .Cm snapq |
288 | directive may be what you are looking for. | |
15fa4caf | 289 | .\" ==== bstats ==== |
4567021b | 290 | .It Cm bstats Op Ar interval |
b4448f1a TN |
291 | Output |
292 | .Nm HAMMER | |
aaf93065 | 293 | B-Tree statistics until interrupted. |
84082922 TN |
294 | Pause |
295 | .Ar interval | |
b4448f1a | 296 | seconds between each display. |
84082922 | 297 | The default interval is one second. |
15fa4caf | 298 | .\" ==== iostats ==== |
4567021b | 299 | .It Cm iostats Op Ar interval |
b4448f1a TN |
300 | Output |
301 | .Nm HAMMER | |
4567021b TN |
302 | .Tn I/O |
303 | statistics until interrupted. | |
84082922 TN |
304 | Pause |
305 | .Ar interval | |
b4448f1a | 306 | seconds between each display. |
84082922 | 307 | The default interval is one second. |
3f760d89 TK |
308 | .\" ==== stats ==== |
309 | .It Cm stats Op Ar interval | |
310 | Output | |
311 | .Nm HAMMER | |
312 | B-Tree and | |
313 | .Tn I/O | |
314 | statistics until interrupted. | |
315 | Pause | |
316 | .Ar interval | |
317 | seconds between each display. | |
318 | The default interval is one second. | |
15fa4caf | 319 | .\" ==== history ==== |
8907a51b | 320 | .It Cm history Ns Oo Cm @ Ns Ar offset Ns Oo Cm \&, Ns Ar length Oc Oc Ar path Ns Oo Cm @ Ns Ar offset Ns Oo Cm \&, Ns Ar length Oc Oc Ar ... |
5f22d366 | 321 | Show the modification history for inode and data of |
b4448f1a | 322 | .Nm HAMMER |
5f22d366 TN |
323 | files. |
324 | If | |
325 | .Ar offset | |
326 | is given history is shown for data block at given offset, | |
327 | otherwise history is shown for inode. | |
328 | If | |
329 | .Fl v | |
330 | is specified | |
331 | .Ar length | |
332 | data bytes at given offset are dumped for each version, | |
333 | default is 32. | |
334 | .Pp | |
335 | For each | |
336 | .Ar path | |
337 | this directive shows object id and sync status, | |
338 | and for each object version it shows transaction id and time stamp. | |
339 | Files has to exist for this directive to be applicable, | |
340 | to track inodes which has been deleted or renamed see | |
341 | .Xr undo 1 . | |
8907a51b TK |
342 | .Pp |
343 | Different | |
344 | .Ar offset | |
345 | and | |
346 | .Ar length | |
347 | can be used for each | |
348 | .Ar path | |
349 | by specifying | |
350 | .Ar offset | |
351 | and | |
352 | .Ar length | |
353 | for each | |
354 | .Ar path . | |
b46b99bf | 355 | .\" ==== blockmap ==== |
4567021b TN |
356 | .It Cm blockmap |
357 | Dump the blockmap for the file system. | |
358 | The | |
359 | .Nm HAMMER | |
360 | blockmap is two-layer | |
361 | blockmap representing the maximum possible file system size of 1 Exabyte. | |
b46b99bf | 362 | Needless to say the second layer is only present for blocks which exist. |
4567021b TN |
363 | .Nm HAMMER Ns 's |
364 | blockmap represents 8-Megabyte blocks, called big-blocks. | |
365 | Each big-block has an append | |
b46b99bf MD |
366 | point, a free byte count, and a typed zone id which allows content to be |
367 | reverse engineered to some degree. | |
368 | .Pp | |
4567021b TN |
369 | In |
370 | .Nm HAMMER | |
aaf93065 | 371 | allocations are essentially appended to a selected big-block using |
4567021b TN |
372 | the append offset and deducted from the free byte count. |
373 | When space is freed the free byte count is adjusted but | |
374 | .Nm HAMMER | |
375 | does not track holes in big-blocks for reallocation. | |
376 | A big-block must be completely freed, either | |
377 | through normal file system operations or through reblocking, before | |
b46b99bf MD |
378 | it can be reused. |
379 | .Pp | |
380 | Data blocks can be shared by deducting the space used from the free byte | |
bb29b5d8 | 381 | count for each shared references. |
4567021b | 382 | This means the free byte count can legally go negative. |
b46b99bf MD |
383 | .Pp |
384 | This command needs the | |
5f22d366 TN |
385 | .Fl f Ar blkdevs |
386 | option. | |
6ed4c886 MD |
387 | .\" ==== checkmap ==== |
388 | .It Cm checkmap | |
389 | Check the blockmap allocation count. | |
390 | .Nm | |
f8589256 TK |
391 | will scan the freemap, B-Tree, UNDO FIFO, then collect allocation information, |
392 | and construct a blockmap in-memory. | |
5f22d366 | 393 | It will then check that blockmap against the on-disk blockmap. |
c71cab34 MD |
394 | .Pp |
395 | This command needs the | |
5f22d366 TN |
396 | .Fl f Ar blkdevs |
397 | option. | |
15fa4caf | 398 | .\" ==== show ==== |
34909d8e | 399 | .It Cm show Op Ar localization Ns Op Cm \&: Ns Ar object_id Ns Op Cm \&: Ns Ar rec_type Ns Op Cm \&: Ns Ar key Ns Op Cm \&: Ns Ar create_tid |
aaf93065 | 400 | Dump the B-Tree. |
4567021b | 401 | By default this command will validate all B-Tree |
b46b99bf MD |
402 | linkages and CRCs, including data CRCs, and will report the most verbose |
403 | information it can dig up. | |
16265794 TN |
404 | Any errors will show up with a |
405 | .Ql B | |
406 | in column 1 along with various | |
b46b99bf MD |
407 | other error flags. |
408 | .Pp | |
5f22d366 TN |
409 | If you specify |
410 | .Ar localization | |
411 | or | |
412 | .Ar localization Ns Cm \&: Ns Ar object_id | |
34909d8e TK |
413 | or |
414 | .Ar localization Ns Cm \&: Ns Ar object_id Ns Cm \&: Ns Ar rec_type | |
415 | or | |
416 | .Ar localization Ns Cm \&: Ns Ar object_id Ns Cm \&: Ns Ar rec_type Ns Cm \&: Ns Ar key | |
417 | or | |
418 | .Ar localization Ns Cm \&: Ns Ar object_id Ns Cm \&: Ns Ar rec_type Ns Cm \&: Ns Ar key Ns Cm \&: Ns Ar create_tid | |
f6532f03 | 419 | the dump will |
e7f926a5 | 420 | search for the key printing nodes as it recurses down, and then |
aaf93065 TN |
421 | will iterate forwards. |
422 | These fields are specified in HEX. | |
8add7974 | 423 | Note that the PFS id is the top 16 bits of the 32-bit localization |
aaf93065 | 424 | field so PFS #1 would be 00010000. |
e7f926a5 | 425 | .Pp |
b46b99bf MD |
426 | If you use |
427 | .Fl q | |
428 | the command will report less information about the inode contents. | |
429 | .Pp | |
430 | If you use | |
431 | .Fl qq | |
432 | the command will not report the content of the inode or other typed | |
433 | data at all. | |
434 | .Pp | |
435 | If you use | |
436 | .Fl qqq | |
437 | the command will not report volume header information, big-block fill | |
4567021b | 438 | ratios, mirror transaction ids, or report or check data CRCs. |
aaf93065 | 439 | B-Tree CRCs and linkages are still checked. |
b46b99bf | 440 | .Pp |
2010519f | 441 | This command needs the |
5f22d366 TN |
442 | .Fl f Ar blkdevs |
443 | option. | |
f6532f03 TN |
444 | .\" ==== show-undo ==== |
445 | .It Cm show-undo | |
446 | .Nm ( HAMMER | |
447 | VERSION 4+) | |
5f22d366 | 448 | Dump the UNDO/REDO map. |
f6532f03 TN |
449 | .Pp |
450 | This command needs the | |
5f22d366 TN |
451 | .Fl f Ar blkdevs |
452 | option. | |
84082922 | 453 | .\" .It Ar blockmap |
aaf93065 | 454 | .\" Dump the B-Tree, record, large-data, and small-data blockmaps, showing |
84082922 | 455 | .\" physical block assignments and free space percentages. |
69f5a58c MD |
456 | .\" ==== ssh-remote ==== |
457 | .It Cm ssh-remote Ar command Ar targetdir | |
458 | Used in a ssh authorized_keys line such as | |
459 | command="/sbin/hammer ssh-remote mirror-read /fubarmount" ... to allow | |
460 | mirror-read or mirror-write access to a particular subdirectory tree. | |
461 | This way you do not have to give shell access to the remote box. | |
462 | .Nm | |
463 | will obtain the original command line from the SSH_ORIGINAL_COMMAND | |
464 | environment variable, validate it against the restriction, and then | |
465 | re-exec hammer with the validated arguments. | |
466 | .Pp | |
467 | The remote hammer command does not allow the | |
468 | .Fl c | |
469 | or | |
470 | .Fl f | |
471 | options to be passed in. | |
b9107f58 MD |
472 | .\" ==== recover ==== |
473 | .It Cm recover Ar targetdir | |
5f22d366 TN |
474 | Recover data from a corrupted |
475 | .Nm HAMMER | |
476 | filesystem. | |
b9107f58 | 477 | This is a low level command which operates on the filesystem image and |
5f22d366 TN |
478 | attempts to locate and recover files from a corrupted filesystem. |
479 | The entire image is scanned linearly looking for B-Tree nodes. | |
480 | Any node | |
481 | found which passes its CRC test is scanned for file, inode, and directory | |
b9107f58 MD |
482 | fragments and the target directory is populated with the resulting data. |
483 | files and directories in the target directory are initially named after | |
2e27fe5d | 484 | the object id and are renamed as fragmentary information is processed. |
b9107f58 | 485 | .Pp |
5f22d366 | 486 | This command keeps track of filename/object_id translations and may eat a |
b9107f58 MD |
487 | considerably amount of memory while operating. |
488 | .Pp | |
489 | This command is literally the last line of defense when it comes to | |
490 | recovering data from a dead filesystem. | |
4bb3dee9 SW |
491 | .Pp |
492 | This command needs the | |
5f22d366 TN |
493 | .Fl f Ar blkdevs |
494 | option. | |
5e435c92 | 495 | .\" ==== namekey1 ==== |
4567021b | 496 | .It Cm namekey1 Ar filename |
b4448f1a TN |
497 | Generate a |
498 | .Nm HAMMER | |
5f22d366 | 499 | 64-bit directory hash for the specified file name, using |
4567021b | 500 | the original directory hash algorithm in version 1 of the file system. |
cbd800c2 MD |
501 | The low 32 bits are used as an iterator for hash collisions and will be |
502 | output as 0. | |
5e435c92 | 503 | .\" ==== namekey2 ==== |
4567021b | 504 | .It Cm namekey2 Ar filename |
5e435c92 MD |
505 | Generate a |
506 | .Nm HAMMER | |
5f22d366 | 507 | 64-bit directory hash for the specified file name, using |
4567021b | 508 | the new directory hash algorithm in version 2 of the file system. |
5e435c92 MD |
509 | The low 32 bits are still used as an iterator but will start out containing |
510 | part of the hash key. | |
15fa4caf | 511 | .\" ==== namekey32 ==== |
4567021b | 512 | .It Cm namekey32 Ar filename |
b4448f1a TN |
513 | Generate the top 32 bits of a |
514 | .Nm HAMMER | |
2010519f | 515 | 64 bit directory hash for the specified file name. |
b66b9421 | 516 | .\" ==== info ==== |
8a03ae8a | 517 | .It Cm info Ar dirpath ... |
d428efb7 | 518 | Show extended information about all |
4567021b | 519 | .Nm HAMMER |
d428efb7 AHJ |
520 | file systems mounted in the system or the one mounted in |
521 | .Ar dirpath | |
522 | when this argument is specified. | |
523 | .Pp | |
32f05ed4 | 524 | The information is divided into sections: |
aaf93065 | 525 | .Bl -tag -width indent |
32f05ed4 AHJ |
526 | .It Volume identification |
527 | General information, like the label of the | |
528 | .Nm HAMMER | |
529 | filesystem, the number of volumes it contains, the FSID, and the | |
530 | .Nm HAMMER | |
531 | version being used. | |
d165c90a TK |
532 | .It Big-block information |
533 | Big-block statistics, such as total, used, reserved and free big-blocks. | |
32f05ed4 AHJ |
534 | .It Space information |
535 | Information about space used on the filesystem. | |
536 | Currently total size, used, reserved and free space are displayed. | |
aaf93065 | 537 | .It PFS information |
32f05ed4 AHJ |
538 | Basic information about the PFSs currently present on a |
539 | .Nm HAMMER | |
540 | filesystem. | |
541 | .Pp | |
542 | .Dq PFS ID | |
543 | is the ID of the PFS, with 0 being the root PFS. | |
544 | .Dq Snaps | |
545 | is the current snapshot count on the PFS. | |
546 | .Dq Mounted on | |
547 | displays the mount point of the PFS is currently mounted on (if any). | |
548 | .El | |
6a6e350f | 549 | .\" ==== cleanup ==== |
4567021b | 550 | .It Cm cleanup Op Ar filesystem ... |
bb29b5d8 MD |
551 | This is a meta-command which executes snapshot, prune, rebalance, dedup |
552 | and reblock commands on the specified | |
226f3799 | 553 | .Nm HAMMER |
16265794 | 554 | file systems. |
226f3799 TN |
555 | If no |
556 | .Ar filesystem | |
557 | is specified this command will clean-up all | |
558 | .Nm HAMMER | |
559 | file systems in use, including PFS's. | |
560 | To do this it will scan all | |
561 | .Nm HAMMER | |
562 | and | |
563 | .Nm null | |
6a6e350f MD |
564 | mounts, extract PFS id's, and clean-up each PFS found. |
565 | .Pp | |
f85afb25 | 566 | This command will access a snapshots |
16265794 | 567 | directory and a configuration file for each |
226f3799 TN |
568 | .Ar filesystem , |
569 | creating them if necessary. | |
f85afb25 TN |
570 | .Bl -tag -width indent |
571 | .It Nm HAMMER No version 2- | |
572 | The configuration file is | |
16265794 TN |
573 | .Pa config |
574 | in the snapshots directory which defaults to | |
575 | .Pa <pfs>/snapshots . | |
f85afb25 | 576 | .It Nm HAMMER No version 3+ |
f6532f03 TN |
577 | The configuration file is saved in file system meta-data, see |
578 | .Nm | |
579 | .Cm config . | |
16265794 TN |
580 | The snapshots directory defaults to |
581 | .Pa /var/hammer/<pfs> | |
582 | .Pa ( /var/hammer/root | |
583 | for root mount). | |
f85afb25 | 584 | .El |
16265794 | 585 | .Pp |
226f3799 TN |
586 | The format of the configuration file is: |
587 | .Bd -literal -offset indent | |
5e435c92 | 588 | snapshots <period> <retention-time> [any] |
226f3799 | 589 | prune <period> <max-runtime> |
f13fea8b | 590 | rebalance <period> <max-runtime> |
bb29b5d8 | 591 | dedup <period> <max-runtime> |
4567021b TN |
592 | reblock <period> <max-runtime> |
593 | recopy <period> <max-runtime> | |
594 | .Ed | |
595 | .Pp | |
226f3799 | 596 | Defaults are: |
4567021b TN |
597 | .Bd -literal -offset indent |
598 | snapshots 1d 60d # 0d 0d for PFS /tmp, /var/tmp, /usr/obj | |
226f3799 | 599 | prune 1d 5m |
f13fea8b | 600 | rebalance 1d 5m |
bb29b5d8 | 601 | dedup 1d 5m |
226f3799 TN |
602 | reblock 1d 5m |
603 | recopy 30d 10m | |
604 | .Ed | |
6a6e350f | 605 | .Pp |
483bb69b | 606 | Time is given with a suffix of |
226f3799 TN |
607 | .Cm d , |
608 | .Cm h , | |
609 | .Cm m | |
483bb69b | 610 | or |
226f3799 TN |
611 | .Cm s |
612 | meaning day, hour, minute and second. | |
5e435c92 | 613 | .Pp |
4567021b TN |
614 | If the |
615 | .Cm snapshots | |
616 | directive has a period of 0 and a retention time of 0 | |
5e435c92 MD |
617 | then snapshot generation is disabled, removal of old snapshots are |
618 | disabled, and prunes will use | |
4567021b | 619 | .Cm prune-everything . |
0551025b | 620 | .Pp |
4567021b TN |
621 | If the |
622 | .Cm snapshots | |
623 | directive has a period of 0 but a non-zero retention time | |
5e435c92 | 624 | then this command will not create any new snapshots but will remove old |
5f22d366 TN |
625 | snapshots it finds based on the retention time. |
626 | This form should be | |
0551025b MD |
627 | used on PFS masters where you are generating your own snapshot softlinks |
628 | manually and on PFS slaves when all you wish to do is prune away existing | |
629 | snapshots inherited via the mirroring stream. | |
5e435c92 | 630 | .Pp |
4567021b TN |
631 | By default only snapshots in the form |
632 | .Ql snap- Ns Ar yyyymmdd Ns Op - Ns Ar HHMM | |
633 | are processed. | |
5e435c92 | 634 | If the |
4567021b TN |
635 | .Cm any |
636 | directive is specified as a third argument on the | |
637 | .Cm snapshots | |
638 | config line then any softlink of the form | |
639 | .Ql *- Ns Ar yyyymmdd Ns Op - Ns Ar HHMM | |
640 | or | |
641 | .Ql *. Ns Ar yyyymmdd Ns Op - Ns Ar HHMM | |
642 | will be processed. | |
5e435c92 | 643 | .Pp |
d106bba4 | 644 | A period of 0 for prune, rebalance, dedup, reblock or recopy disables the directive. |
5f22d366 | 645 | A max-runtime of 0 means unlimited. |
226f3799 | 646 | .Pp |
e0331f4f | 647 | If period hasn't passed since the previous |
4567021b | 648 | .Cm cleanup |
483bb69b TN |
649 | run nothing is done. |
650 | For example a day has passed when midnight is passed (localtime). | |
5f22d366 TN |
651 | If the |
652 | .Fl F | |
653 | flag is given the period is ignored. | |
e0331f4f SW |
654 | By default, |
655 | .Dx | |
656 | is set up to run | |
5f22d366 | 657 | .Nm Cm cleanup |
e0331f4f SW |
658 | nightly via |
659 | .Xr periodic 8 . | |
226f3799 TN |
660 | .Pp |
661 | The default configuration file will create a daily snapshot, do a daily | |
bb29b5d8 | 662 | pruning, rebalancing, deduping and reblocking run and a monthly recopy run. |
226f3799 TN |
663 | Reblocking is defragmentation with a level of 95%, |
664 | and recopy is full defragmentation. | |
665 | .Pp | |
5f22d366 TN |
666 | By default prune, dedup and rebalance operations are time limited to 5 minutes, |
667 | and reblock operations to a bit over 5 minutes, | |
4567021b TN |
668 | and recopy operations to a bit over 10 minutes. |
669 | Reblocking and recopy runs are each broken down into four separate functions: | |
78c4be83 | 670 | B-Tree, inodes, dirs and data. |
4567021b | 671 | Each function is time limited to the time given in the configuration file, |
78c4be83 | 672 | but the B-Tree, inodes and dirs functions usually does not take very long time, |
4567021b | 673 | full defragmentation is always used for these three functions. |
226f3799 | 674 | Also note that this directive will by default disable snapshots on |
2010519f | 675 | the following PFS's: |
6a6e350f | 676 | .Pa /tmp , |
226f3799 | 677 | .Pa /var/tmp |
6a6e350f | 678 | and |
226f3799 | 679 | .Pa /usr/obj . |
6a6e350f | 680 | .Pp |
16265794 | 681 | The defaults may be adjusted by modifying the configuration file. |
6a6e350f MD |
682 | The pruning and reblocking commands automatically maintain a cyclefile |
683 | for incremental operation. | |
4567021b TN |
684 | If you interrupt (^C) the program the cyclefile will be updated, |
685 | but a sub-command | |
226f3799 TN |
686 | may continue to run in the background for a few seconds until the |
687 | .Nm HAMMER | |
6a6e350f | 688 | ioctl detects the interrupt. |
226f3799 | 689 | The |
4567021b | 690 | .Cm snapshots |
226f3799 | 691 | PFS option can be set to use another location for the snapshots directory. |
6a6e350f MD |
692 | .Pp |
693 | Work on this command is still in progress. | |
4567021b TN |
694 | Expected additions: |
695 | An ability to remove snapshots dynamically as the | |
226f3799 | 696 | file system becomes full. |
a360fdde JM |
697 | .\" ==== abort-cleanup ==== |
698 | .It Cm abort-cleanup | |
699 | This command will terminate all active | |
700 | .Cm cleanup | |
701 | processes. | |
83f2a3aa | 702 | .\" ==== config ==== |
16265794 TN |
703 | .It Cm config Op Ar filesystem Op Ar configfile |
704 | .Nm ( HAMMER | |
705 | VERSION 3+) | |
aaf93065 TN |
706 | Show or change configuration for |
707 | .Ar filesystem . | |
16265794 TN |
708 | If zero or one arguments are specified this function dumps the current |
709 | configuration file to stdout. | |
710 | Zero arguments specifies the PFS containing the current directory. | |
f6532f03 | 711 | This configuration file is stored in file system meta-data. |
83f2a3aa MD |
712 | If two arguments are specified this function installs a new config file. |
713 | .Pp | |
714 | In | |
715 | .Nm HAMMER | |
16265794 TN |
716 | versions less than 3 the configuration file is by default stored in |
717 | .Pa <pfs>/snapshots/config , | |
f6532f03 | 718 | but in all later versions the configuration file is stored in file system |
83f2a3aa | 719 | meta-data. |
16265794 TN |
720 | .\" ==== viconfig ==== |
721 | .It Cm viconfig Op Ar filesystem | |
722 | .Nm ( HAMMER | |
723 | VERSION 3+) | |
f6532f03 | 724 | Edit the configuration file and reinstall into file system meta-data when done. |
16265794 | 725 | Zero arguments specifies the PFS containing the current directory. |
d121f61c MN |
726 | .\" ==== volume-add ==== |
727 | .It Cm volume-add Ar device Ar filesystem | |
5f22d366 TN |
728 | Add volume |
729 | .Ar device | |
730 | to | |
731 | .Ar filesystem . | |
732 | This will format | |
ceed7673 MN |
733 | .Ar device |
734 | and add all of its space to | |
735 | .Ar filesystem . | |
5f22d366 TN |
736 | A |
737 | .Nm HAMMER | |
738 | file system can use up to 256 volumes. | |
ceed7673 | 739 | .Pp |
4567021b TN |
740 | .Em NOTE! |
741 | All existing data contained on | |
ceed7673 | 742 | .Ar device |
4567021b TN |
743 | will be destroyed by this operation! |
744 | If | |
ceed7673 MN |
745 | .Ar device |
746 | contains a valid | |
747 | .Nm HAMMER | |
f6532f03 | 748 | file system, formatting will be denied. |
5f22d366 | 749 | You can overcome this sanity check by using |
ceed7673 MN |
750 | .Xr dd 1 |
751 | to erase the beginning sectors of the device. | |
5f22d366 TN |
752 | .Pp |
753 | Remember that you have to specify | |
ceed7673 | 754 | .Ar device , |
f6532f03 TN |
755 | together with any other device that make up the file system, |
756 | colon-separated to | |
757 | .Pa /etc/fstab | |
758 | and | |
ceed7673 | 759 | .Xr mount_hammer 8 . |
5f22d366 TN |
760 | If |
761 | .Ar filesystem | |
762 | is root file system, also remember to add | |
763 | .Ar device | |
764 | to | |
765 | .Va vfs.root.mountfrom | |
766 | in | |
767 | .Pa /boot/loader.conf , | |
768 | see | |
769 | .Xr loader 8 . | |
865c9609 MN |
770 | .\" ==== volume-del ==== |
771 | .It Cm volume-del Ar device Ar filesystem | |
5f22d366 | 772 | Remove volume |
865c9609 MN |
773 | .Ar device |
774 | from | |
775 | .Ar filesystem . | |
776 | .Pp | |
777 | Remember that you have to remove | |
778 | .Ar device | |
779 | from the colon-separated list in | |
780 | .Pa /etc/fstab | |
781 | and | |
782 | .Xr mount_hammer 8 . | |
5f22d366 TN |
783 | If |
784 | .Ar filesystem | |
785 | is root file system, also remember to remove | |
786 | .Ar device | |
787 | from | |
788 | .Va vfs.root.mountfrom | |
789 | in | |
790 | .Pa /boot/loader.conf , | |
791 | see | |
792 | .Xr loader 8 . | |
1e94cea6 | 793 | .Pp |
dae8f186 TK |
794 | It is not possible to remove the |
795 | .Ar root-volume | |
796 | as it contains | |
797 | .Ar filesystem | |
798 | meta data such as | |
799 | .Nm HAMMER Ns 's | |
800 | layer1 blockmap and UNDO FIFO. | |
801 | .Pp | |
1e94cea6 TK |
802 | This command may |
803 | .Cm reblock | |
7c5aac38 | 804 | filesystem before it attempts to remove the volume if the volume is not empty. |
e914c91d SK |
805 | .\" ==== volume-list ==== |
806 | .It Cm volume-list Ar filesystem | |
5f22d366 | 807 | List the volumes that make up |
e914c91d | 808 | .Ar filesystem . |
b45632fb TK |
809 | .\" ==== volume-blkdevs ==== |
810 | .It Cm volume-blkdevs Ar filesystem | |
811 | List the volumes that make up | |
812 | .Ar filesystem | |
813 | in | |
814 | .Ar blkdevs | |
815 | format. | |
0e999592 | 816 | .\" ==== snapshot ==== |
4567021b | 817 | .It Cm snapshot Oo Ar filesystem Oc Ar snapshot-dir |
16265794 | 818 | .It Cm snapshot Ar filesystem Ar snapshot-dir Op Ar note |
5f22d366 | 819 | Take a snapshot of the file system either explicitly given by |
0e999592 TN |
820 | .Ar filesystem |
821 | or implicitly derived from the | |
822 | .Ar snapshot-dir | |
823 | argument and creates a symlink in the directory provided by | |
824 | .Ar snapshot-dir | |
825 | pointing to the snapshot. | |
826 | If | |
827 | .Ar snapshot-dir | |
828 | is not a directory, it is assumed to be a format string passed to | |
829 | .Xr strftime 3 | |
830 | with the current time as parameter. | |
831 | If | |
832 | .Ar snapshot-dir | |
4567021b | 833 | refers to an existing directory, a default format string of |
5f22d366 | 834 | .Ql snap-%Y%m%d-%H%M |
0e999592 TN |
835 | is assumed and used as name for the newly created symlink. |
836 | .Pp | |
5f22d366 | 837 | Snapshot is a per PFS operation, so each PFS in a |
0e999592 | 838 | .Nm HAMMER |
5f22d366 | 839 | file system have to be snapshot separately. |
0e999592 TN |
840 | .Pp |
841 | Example, assuming that | |
842 | .Pa /mysnapshots | |
843 | is on file system | |
844 | .Pa / | |
845 | and that | |
846 | .Pa /obj | |
16265794 TN |
847 | and |
848 | .Pa /usr | |
849 | are file systems on their own, the following invocations: | |
0e999592 TN |
850 | .Bd -literal -offset indent |
851 | hammer snapshot /mysnapshots | |
852 | ||
853 | hammer snapshot /mysnapshots/%Y-%m-%d | |
854 | ||
855 | hammer snapshot /obj /mysnapshots/obj-%Y-%m-%d | |
b5ec5ad4 | 856 | |
16265794 | 857 | hammer snapshot /usr /my/snaps/usr "note" |
0e999592 TN |
858 | .Ed |
859 | .Pp | |
b5ec5ad4 | 860 | Would create symlinks similar to: |
0e999592 TN |
861 | .Bd -literal -offset indent |
862 | /mysnapshots/snap-20080627-1210 -> /@@0x10d2cd05b7270d16 | |
863 | ||
864 | /mysnapshots/2008-06-27 -> /@@0x10d2cd05b7270d16 | |
865 | ||
866 | /mysnapshots/obj-2008-06-27 -> /obj@@0x10d2cd05b7270d16 | |
16265794 TN |
867 | |
868 | /my/snaps/usr/snap-20080627-1210 -> /usr@@0x10d2cd05b7270d16 | |
0e999592 | 869 | .Ed |
b5ec5ad4 MD |
870 | .Pp |
871 | When run on a | |
872 | .Nm HAMMER | |
f6532f03 | 873 | version 3+ file system the snapshot is also recorded in file system meta-data |
16265794 TN |
874 | along with the optional |
875 | .Ar note . | |
876 | See the | |
b5ec5ad4 MD |
877 | .Cm snapls |
878 | directive. | |
83f2a3aa | 879 | .\" ==== snap* ==== |
16265794 TN |
880 | .It Cm snap Ar path Op Ar note |
881 | .Nm ( HAMMER | |
882 | VERSION 3+) | |
883 | Create a snapshot for the PFS containing | |
884 | .Ar path | |
885 | and create a snapshot softlink. | |
886 | If the path specified is a | |
83f2a3aa MD |
887 | directory a standard snapshot softlink will be created in the directory. |
888 | The snapshot softlink points to the base of the mounted PFS. | |
16265794 TN |
889 | .It Cm snaplo Ar path Op Ar note |
890 | .Nm ( HAMMER | |
891 | VERSION 3+) | |
892 | Create a snapshot for the PFS containing | |
893 | .Ar path | |
894 | and create a snapshot softlink. | |
895 | If the path specified is a | |
83f2a3aa MD |
896 | directory a standard snapshot softlink will be created in the directory. |
897 | The snapshot softlink points into the directory it is contained in. | |
16265794 TN |
898 | .It Cm snapq Ar dir Op Ar note |
899 | .Nm ( HAMMER | |
900 | VERSION 3+) | |
83f2a3aa | 901 | Create a snapshot for the PFS containing the specified directory but do |
16265794 TN |
902 | not create a softlink. |
903 | Instead output a path which can be used to access | |
83f2a3aa | 904 | the directory via the snapshot. |
bf2c6489 | 905 | .Pp |
16265794 TN |
906 | An absolute or relative path may be specified. |
907 | The path will be used as-is as a prefix in the path output to stdout. | |
908 | As with the other | |
bf2c6489 | 909 | snap and snapshot directives the snapshot transaction id will be registered |
f6532f03 | 910 | in the file system meta-data. |
ef872b8d | 911 | .It Cm snaprm Ar path Ar ... |
5f22d366 TN |
912 | .It Cm snaprm Ar transaction_id Ar ... |
913 | .It Cm snaprm Ar filesystem Ar transaction_id Ar ... | |
16265794 TN |
914 | .Nm ( HAMMER |
915 | VERSION 3+) | |
916 | Remove a snapshot given its softlink or transaction id. | |
917 | If specifying a transaction id | |
f6532f03 | 918 | the snapshot is removed from file system meta-data but you are responsible |
83f2a3aa | 919 | for removing any related softlinks. |
ef872b8d MD |
920 | .Pp |
921 | If a softlink path is specified the filesystem and transaction id | |
922 | is derived from the contents of the softlink. | |
5f22d366 TN |
923 | If just a transaction id is specified it is assumed to be a snapshot in the |
924 | .Nm HAMMER | |
925 | filesystem you are currently chdir'd into. | |
ef872b8d | 926 | You can also specify the filesystem and transaction id explicitly. |
16265794 TN |
927 | .It Cm snapls Op Ar path ... |
928 | .Nm ( HAMMER | |
929 | VERSION 3+) | |
930 | Dump the snapshot meta-data for PFSs containing each | |
931 | .Ar path | |
932 | listing all available snapshots and their notes. | |
933 | If no arguments are specified snapshots for the PFS containing the | |
934 | current directory are listed. | |
f6532f03 | 935 | This is the definitive list of snapshots for the file system. |
15fa4caf | 936 | .\" ==== prune ==== |
4567021b | 937 | .It Cm prune Ar softlink-dir |
b4448f1a TN |
938 | Prune the file system based on previously created snapshot softlinks. |
939 | Pruning is the act of deleting file system history. | |
84082922 | 940 | The |
4567021b TN |
941 | .Cm prune |
942 | command will delete file system history such that | |
b4448f1a | 943 | the file system state is retained for the given snapshots, |
4567021b TN |
944 | and all history after the latest snapshot. |
945 | By setting the per PFS parameter | |
946 | .Cm prune-min , | |
947 | history is guaranteed to be saved at least this time interval. | |
948 | All other history is deleted. | |
84082922 | 949 | .Pp |
e8969ef0 | 950 | The target directory is expected to contain softlinks pointing to |
2010519f TN |
951 | snapshots of the file systems you wish to retain. |
952 | The directory is scanned non-recursively and the mount points and | |
953 | transaction ids stored in the softlinks are extracted and sorted. | |
b4448f1a | 954 | The file system is then explicitly pruned according to what is found. |
4567021b TN |
955 | Cleaning out portions of the file system is as simple as removing a |
956 | snapshot softlink and then running the | |
957 | .Cm prune | |
e8969ef0 MD |
958 | command. |
959 | .Pp | |
960 | As a safety measure pruning only occurs if one or more softlinks are found | |
4567021b TN |
961 | containing the |
962 | .Ql @@ | |
963 | snapshot id extension. | |
e8969ef0 | 964 | Currently the scanned softlink directory must contain softlinks pointing |
b4448f1a TN |
965 | to a single |
966 | .Nm HAMMER | |
2010519f TN |
967 | mount. |
968 | The softlinks may specify absolute or relative paths. | |
4567021b TN |
969 | Softlinks must use 20-character |
970 | .Ql @@0x%016llx | |
971 | transaction ids, as might be returned from | |
972 | .Nm Cm synctid Ar filesystem . | |
e8969ef0 | 973 | .Pp |
5f22d366 | 974 | Pruning is a per PFS operation, so each PFS in a |
15fa4caf | 975 | .Nm HAMMER |
5f22d366 | 976 | file system have to be pruned separately. |
15fa4caf TN |
977 | .Pp |
978 | Note that pruning a file system may not immediately free-up space, | |
979 | though typically some space will be freed if a large number of records are | |
2010519f TN |
980 | pruned out. |
981 | The file system must be reblocked to completely recover all available space. | |
15fa4caf | 982 | .Pp |
4567021b TN |
983 | Example, lets say your that you didn't set |
984 | .Cm prune-min , | |
985 | and snapshot directory contains the following links: | |
226f3799 | 986 | .Bd -literal -offset indent |
f51a18e7 SW |
987 | lrwxr-xr-x 1 root wheel 29 May 31 17:57 snap1 -> |
988 | /usr/obj/@@0x10d2cd05b7270d16 | |
989 | ||
990 | lrwxr-xr-x 1 root wheel 29 May 31 17:58 snap2 -> | |
991 | /usr/obj/@@0x10d2cd13f3fde98f | |
992 | ||
993 | lrwxr-xr-x 1 root wheel 29 May 31 17:59 snap3 -> | |
994 | /usr/obj/@@0x10d2cd222adee364 | |
995 | .Ed | |
e8969ef0 | 996 | .Pp |
84082922 | 997 | If you were to run the |
4567021b | 998 | .Cm prune |
b4448f1a TN |
999 | command on this directory, then the |
1000 | .Nm HAMMER | |
f51a18e7 SW |
1001 | .Pa /usr/obj |
1002 | mount will be pruned to retain the above three snapshots. | |
2010519f TN |
1003 | In addition, history for modifications made to the file system older than |
1004 | the oldest snapshot will be destroyed and history for potentially fine-grained | |
1005 | modifications made to the file system more recently than the most recent | |
1006 | snapshot will be retained. | |
1007 | .Pp | |
1008 | If you then delete the | |
1009 | .Pa snap2 | |
1010 | softlink and rerun the | |
4567021b | 1011 | .Cm prune |
84082922 TN |
1012 | command, |
1013 | history for modifications pertaining to that snapshot would be destroyed. | |
83f2a3aa MD |
1014 | .Pp |
1015 | In | |
1016 | .Nm HAMMER | |
f6532f03 TN |
1017 | file system versions 3+ this command also scans the snapshots stored |
1018 | in the file system meta-data and includes them in the prune. | |
15fa4caf | 1019 | .\" ==== prune-everything ==== |
4567021b | 1020 | .It Cm prune-everything Ar filesystem |
5f22d366 TN |
1021 | Remove all historical records from |
1022 | .Ar filesystem . | |
1023 | Use this directive with caution on PFSs where you intend to use history. | |
83f2a3aa MD |
1024 | .Pp |
1025 | This command does not remove snapshot softlinks but will delete all | |
f6532f03 | 1026 | snapshots recorded in file system meta-data (for file system version 3+). |
83f2a3aa | 1027 | The user is responsible for deleting any softlinks. |
aaf93065 | 1028 | .Pp |
5f22d366 | 1029 | Pruning is a per PFS operation, so each PFS in a |
aaf93065 | 1030 | .Nm HAMMER |
5f22d366 | 1031 | file system have to be pruned separately. |
797a0b63 | 1032 | .\" ==== rebalance ==== |
f6532f03 | 1033 | .It Cm rebalance Ar filesystem Op Ar saturation_percentage |
5f22d366 | 1034 | Rebalance the B-Tree, nodes with small number of |
797a0b63 MD |
1035 | elements will be combined and element counts will be smoothed out |
1036 | between nodes. | |
1037 | .Pp | |
f6532f03 | 1038 | The saturation percentage is between 50% and 100%. |
953bfaa2 | 1039 | The default is 85% (the |
f6532f03 TN |
1040 | .Sq % |
1041 | suffix is not needed). | |
aaf93065 | 1042 | .Pp |
5f22d366 | 1043 | Rebalancing is a per PFS operation, so each PFS in a |
aaf93065 | 1044 | .Nm HAMMER |
5f22d366 | 1045 | file system have to be rebalanced separately. |
bb29b5d8 MD |
1046 | .\" ==== dedup ==== |
1047 | .It Cm dedup Ar filesystem | |
1048 | .Nm ( HAMMER | |
1049 | VERSION 5+) | |
5f22d366 TN |
1050 | Perform offline (post-process) deduplication. |
1051 | Deduplication occurs at | |
bb29b5d8 | 1052 | the block level, currently only data blocks of the same size can be |
5f22d366 TN |
1053 | deduped, metadata blocks can not. |
1054 | The hash function used for comparing | |
bb29b5d8 MD |
1055 | data blocks is CRC-32 (CRCs are computed anyways as part of |
1056 | .Nm HAMMER | |
5f22d366 TN |
1057 | data integrity features, so there's no additional overhead). |
1058 | Since CRC is a weak hash function a byte-by-byte comparison is done | |
1059 | before actual deduping. | |
1060 | In case of a CRC collision (two data blocks have the same CRC | |
bb29b5d8 MD |
1061 | but different contents) the checksum is upgraded to SHA-256. |
1062 | .Pp | |
1063 | Currently | |
1064 | .Nm HAMMER | |
1065 | reblocker may partially blow up (re-expand) dedup (reblocker's normal | |
1066 | operation is to reallocate every record, so it's possible for deduped | |
1067 | blocks to be re-expanded back). | |
1068 | .Pp | |
5f22d366 | 1069 | Deduplication is a per PFS operation, so each PFS in a |
bb29b5d8 | 1070 | .Nm HAMMER |
5f22d366 TN |
1071 | file system have to be deduped separately. |
1072 | This also | |
bb29b5d8 MD |
1073 | means that if you have duplicated data in two different PFSs that data |
1074 | won't be deduped, however the addition of such feature is planned. | |
fbe1c665 MD |
1075 | .Pp |
1076 | The | |
1077 | .Fl m Ar memlimit | |
1078 | option should be used to limit memory use during the dedup run if the | |
1079 | default 1G limit is too much for the machine. | |
bb29b5d8 MD |
1080 | .\" ==== dedup-simulate ==== |
1081 | .It Cm dedup-simulate Ar filesystem | |
bb29b5d8 MD |
1082 | Shows potential space savings (simulated dedup ratio) one can get after |
1083 | running | |
1084 | .Cm dedup | |
5f22d366 TN |
1085 | command. |
1086 | If the estimated dedup ratio is greater than 1.00 you will see | |
1087 | dedup space savings. | |
1088 | Remember that this is an estimated number, in | |
bb29b5d8 MD |
1089 | practice real dedup ratio will be slightly smaller because of |
1090 | .Nm HAMMER | |
a981af19 | 1091 | big-block underflows, B-Tree locking issues and other factors. |
eae1bb35 ID |
1092 | .Pp |
1093 | Note that deduplication currently works only on bulk data so if you | |
1094 | try to run | |
1095 | .Cm dedup-simulate | |
1096 | or | |
1097 | .Cm dedup | |
1098 | commands on a PFS that contains metadata only (directory entries, | |
1099 | softlinks) you will get a 0.00 dedup ratio. | |
fbe1c665 MD |
1100 | .Pp |
1101 | The | |
1102 | .Fl m Ar memlimit | |
1103 | option should be used to limit memory use during the dedup run if the | |
1104 | default 1G limit is too much for the machine. | |
16265794 | 1105 | .\" ==== reblock* ==== |
4567021b TN |
1106 | .It Cm reblock Ar filesystem Op Ar fill_percentage |
1107 | .It Cm reblock-btree Ar filesystem Op Ar fill_percentage | |
1108 | .It Cm reblock-inodes Ar filesystem Op Ar fill_percentage | |
1109 | .It Cm reblock-dirs Ar filesystem Op Ar fill_percentage | |
1110 | .It Cm reblock-data Ar filesystem Op Ar fill_percentage | |
9e29c876 | 1111 | Attempt to defragment and free space for reuse by reblocking a live |
b4448f1a TN |
1112 | .Nm HAMMER |
1113 | file system. | |
4567021b | 1114 | Big-blocks cannot be reused by |
b4448f1a TN |
1115 | .Nm HAMMER |
1116 | until they are completely free. | |
9e29c876 | 1117 | This command also has the effect of reordering all elements, effectively |
b4448f1a | 1118 | defragmenting the file system. |
ba7b52c9 | 1119 | .Pp |
b4448f1a | 1120 | The default fill percentage is 100% and will cause the file system to be |
2010519f TN |
1121 | completely defragmented. |
1122 | All specified element types will be reallocated and rewritten. | |
1123 | If you wish to quickly free up space instead try specifying | |
15fa4caf TN |
1124 | a smaller fill percentage, such as 90% or 80% (the |
1125 | .Sq % | |
1126 | suffix is not needed). | |
ba7b52c9 | 1127 | .Pp |
9e29c876 | 1128 | Since this command may rewrite the entire contents of the disk it is |
84082922 TN |
1129 | best to do it incrementally from a |
1130 | .Xr cron 8 | |
1131 | job along with the | |
9e29c876 MD |
1132 | .Fl c Ar cyclefile |
1133 | and | |
99d6191f | 1134 | .Fl t Ar seconds |
9e29c876 | 1135 | options to limit the run time. |
b4448f1a | 1136 | The file system would thus be defragmented over long period of time. |
9e29c876 MD |
1137 | .Pp |
1138 | It is recommended that separate invocations be used for each data type. | |
aaf93065 | 1139 | B-Tree nodes, inodes, and directories are typically the most important |
2010519f TN |
1140 | elements needing defragmentation. |
1141 | Data can be defragmented over a longer period of time. | |
15fa4caf | 1142 | .Pp |
5f22d366 | 1143 | Reblocking is a per PFS operation, so each PFS in a |
15fa4caf | 1144 | .Nm HAMMER |
5f22d366 | 1145 | file system have to be reblocked separately. |
15fa4caf | 1146 | .\" ==== pfs-status ==== |
4567021b | 1147 | .It Cm pfs-status Ar dirpath ... |
34ebae70 | 1148 | Retrieve the mirroring configuration parameters for the specified |
b4448f1a | 1149 | .Nm HAMMER |
2010519f | 1150 | file systems or pseudo-filesystems (PFS's). |
15fa4caf | 1151 | .\" ==== pfs-master ==== |
4567021b | 1152 | .It Cm pfs-master Ar dirpath Op Ar options |
b4448f1a TN |
1153 | Create a pseudo-filesystem (PFS) inside a |
1154 | .Nm HAMMER | |
1155 | file system. | |
5f22d366 | 1156 | Up to 65536 PFSs can be created. |
765c85a8 | 1157 | Each PFS uses an independent inode numbering space making it suitable |
5f22d366 | 1158 | for replication. |
d4e5b69b MD |
1159 | .Pp |
1160 | The | |
4567021b | 1161 | .Cm pfs-master |
d4e5b69b MD |
1162 | directive creates a PFS that you can read, write, and use as a mirroring |
1163 | source. | |
bb8e52c0 | 1164 | .Pp |
5f22d366 TN |
1165 | A PFS can only be truly destroyed with the |
1166 | .Cm pfs-destroy | |
1167 | directive. | |
1168 | Removing the softlink will not destroy the underlying PFS. | |
1169 | .Pp | |
1170 | A PFS can only be created in the root PFS (PFS# 0), | |
1171 | not in a PFS created by | |
1172 | .Cm pfs-master | |
1173 | or | |
1174 | .Cm pfs-slave | |
1175 | (PFS# >0). | |
1176 | .Pp | |
1177 | It is recommended that | |
1178 | .Ar dirpath | |
1179 | is of the form | |
1180 | .Pa <fs>/pfs/<name> | |
1181 | (i.e.\& located in | |
8add7974 | 1182 | .Pa PFS |
5f22d366 TN |
1183 | directory at root of |
1184 | .Nm HAMMER | |
1185 | file system). | |
1186 | .Pp | |
bb8e52c0 TN |
1187 | It is recommended to use a |
1188 | .Nm null | |
5f22d366 | 1189 | mount to access a PFS, except for root PFS, for more information see |
bb8e52c0 | 1190 | .Xr HAMMER 5 . |
15fa4caf | 1191 | .\" ==== pfs-slave ==== |
4567021b | 1192 | .It Cm pfs-slave Ar dirpath Op Ar options |
b4448f1a TN |
1193 | Create a pseudo-filesystem (PFS) inside a |
1194 | .Nm HAMMER | |
1195 | file system. | |
5f22d366 | 1196 | Up to 65536 PFSs can be created. |
765c85a8 | 1197 | Each PFS uses an independent inode numbering space making it suitable |
5f22d366 | 1198 | for replication. |
d4e5b69b MD |
1199 | .Pp |
1200 | The | |
4567021b | 1201 | .Cm pfs-slave |
5f22d366 | 1202 | directive creates a PFS that you can use as a mirroring source or target. |
d4e5b69b MD |
1203 | You will not be able to access a slave PFS until you have completed the |
1204 | first mirroring operation with it as the target (its root directory will | |
1205 | not exist until then). | |
34ebae70 | 1206 | .Pp |
4567021b | 1207 | Access to the pfs-slave via the special softlink, as described in the |
006a05b7 | 1208 | .Sx PSEUDO-FILESYSTEM (PFS) NOTES |
2010519f | 1209 | below, allows |
b4448f1a TN |
1210 | .Nm HAMMER |
1211 | to | |
84082922 TN |
1212 | dynamically modify the snapshot transaction id by returning a dynamic result |
1213 | from | |
1214 | .Xr readlink 2 | |
1215 | calls. | |
d4e5b69b | 1216 | .Pp |
765c85a8 | 1217 | A PFS can only be truly destroyed with the |
4567021b | 1218 | .Cm pfs-destroy |
d4e5b69b MD |
1219 | directive. |
1220 | Removing the softlink will not destroy the underlying PFS. | |
bb8e52c0 | 1221 | .Pp |
5f22d366 TN |
1222 | A PFS can only be created in the root PFS (PFS# 0), |
1223 | not in a PFS created by | |
1224 | .Cm pfs-master | |
1225 | or | |
1226 | .Cm pfs-slave | |
1227 | (PFS# >0). | |
1228 | .Pp | |
1229 | It is recommended that | |
1230 | .Ar dirpath | |
1231 | is of the form | |
1232 | .Pa <fs>/pfs/<name> | |
1233 | (i.e.\& located in | |
8add7974 | 1234 | .Pa PFS |
5f22d366 TN |
1235 | directory at root of |
1236 | .Nm HAMMER | |
1237 | file system). | |
1238 | .Pp | |
bb8e52c0 TN |
1239 | It is recommended to use a |
1240 | .Nm null | |
5f22d366 | 1241 | mount to access a PFS, except for root PFS, for more information see |
bb8e52c0 | 1242 | .Xr HAMMER 5 . |
15fa4caf | 1243 | .\" ==== pfs-update ==== |
4567021b | 1244 | .It Cm pfs-update Ar dirpath Op Ar options |
b4448f1a TN |
1245 | Update the configuration parameters for an existing |
1246 | .Nm HAMMER | |
4567021b | 1247 | file system or pseudo-filesystem. |
2010519f | 1248 | Options that may be specified: |
34ebae70 | 1249 | .Bl -tag -width indent |
4567021b | 1250 | .It Cm sync-beg-tid= Ns Ar 0x16llx |
2010519f TN |
1251 | This is the automatic snapshot access starting transaction id for |
1252 | mirroring slaves. | |
34ebae70 | 1253 | This parameter is normally updated automatically by the |
4567021b | 1254 | .Cm mirror-write |
34ebae70 MD |
1255 | directive. |
1256 | .Pp | |
1257 | It is important to note that accessing a mirroring slave | |
765c85a8 | 1258 | with a transaction id greater than the last fully synchronized transaction |
34ebae70 MD |
1259 | id can result in an unreliable snapshot since you will be accessing |
1260 | data that is still undergoing synchronization. | |
1261 | .Pp | |
4567021b TN |
1262 | Manually modifying this field is dangerous and can result in a broken mirror. |
1263 | .It Cm sync-end-tid= Ns Ar 0x16llx | |
ddc8e722 | 1264 | This is the current synchronization point for mirroring slaves. |
34ebae70 | 1265 | This parameter is normally updated automatically by the |
4567021b | 1266 | .Cm mirror-write |
34ebae70 MD |
1267 | directive. |
1268 | .Pp | |
2010519f | 1269 | Manually modifying this field is dangerous and can result in a broken mirror. |
4567021b | 1270 | .It Cm shared-uuid= Ns Ar uuid |
2010519f TN |
1271 | Set the shared UUID for this file system. |
1272 | All mirrors must have the same shared UUID. | |
1273 | For safety purposes the | |
4567021b | 1274 | .Cm mirror-write |
2010519f | 1275 | directives will refuse to operate on a target with a different shared UUID. |
34ebae70 | 1276 | .Pp |
84082922 | 1277 | Changing the shared UUID on an existing, non-empty mirroring target, |
2010519f TN |
1278 | including an empty but not completely pruned target, |
1279 | can lead to corruption of the mirroring target. | |
4567021b | 1280 | .It Cm unique-uuid= Ns Ar uuid |
2010519f TN |
1281 | Set the unique UUID for this file system. |
1282 | This UUID should not be used anywhere else, | |
1283 | even on exact copies of the file system. | |
4567021b | 1284 | .It Cm label= Ns Ar string |
b4448f1a | 1285 | Set a descriptive label for this file system. |
4567021b | 1286 | .It Cm snapshots= Ns Ar string |
226f3799 TN |
1287 | Specify the snapshots directory which |
1288 | .Nm | |
4567021b | 1289 | .Cm cleanup |
2010519f | 1290 | will use to manage this PFS. |
f85afb25 TN |
1291 | .Bl -tag -width indent |
1292 | .It Nm HAMMER No version 2- | |
2010519f | 1293 | The snapshots directory does not need to be configured for |
226f3799 TN |
1294 | PFS masters and will default to |
1295 | .Pa <pfs>/snapshots . | |
ff1c9800 MD |
1296 | .Pp |
1297 | PFS slaves are mirroring slaves so you cannot configure a snapshots | |
1298 | directory on the slave itself to be managed by the slave's machine. | |
226f3799 TN |
1299 | In fact, the slave will likely have a |
1300 | .Pa snapshots | |
1301 | sub-directory mirrored | |
ff1c9800 | 1302 | from the master, but that directory contains the configuration the master |
226f3799 | 1303 | is using for its copy of the file system, not the configuration that we |
ff1c9800 MD |
1304 | want to use for our slave. |
1305 | .Pp | |
226f3799 TN |
1306 | It is recommended that |
1307 | .Pa <fs>/var/slaves/<name> | |
1308 | be configured for a PFS slave, where | |
1309 | .Pa <fs> | |
1310 | is the base | |
1311 | .Nm HAMMER | |
1312 | file system, and | |
1313 | .Pa <name> | |
1314 | is an appropriate label. | |
f85afb25 TN |
1315 | .It Nm HAMMER No version 3+ |
1316 | The snapshots directory does not need to be configured for PFS masters or | |
1317 | slaves. | |
1318 | The snapshots directory defaults to | |
1319 | .Pa /var/hammer/<pfs> | |
1320 | .Pa ( /var/hammer/root | |
1321 | for root mount). | |
1322 | .El | |
1323 | .Pp | |
2010519f | 1324 | You can control snapshot retention on your slave independent of the master. |
4567021b TN |
1325 | .It Cm snapshots-clear |
1326 | Zero out the | |
1327 | .Cm snapshots | |
1328 | directory path for this PFS. | |
1329 | .It Cm prune-min= Ns Ar N Ns Cm d | |
f85afb25 TN |
1330 | .It Cm prune-min= Ns Oo Ar N Ns Cm d/ Oc Ns \ |
1331 | Ar hh Ns Op Cm \&: Ns Ar mm Ns Op Cm \&: Ns Ar ss | |
e7f926a5 MD |
1332 | Set the minimum fine-grained data retention period. |
1333 | .Nm HAMMER | |
0bd7a37c MD |
1334 | always retains fine-grained history up to the most recent snapshot. |
1335 | You can extend the retention period further by specifying a non-zero | |
4567021b TN |
1336 | pruning minimum. |
1337 | Any snapshot softlinks within the retention period are ignored | |
5f22d366 | 1338 | for the purposes of pruning (i.e.\& the fine grained history is retained). |
4567021b TN |
1339 | Number of days, hours, minutes and seconds are given as |
1340 | .Ar N , hh , mm | |
1341 | and | |
1342 | .Ar ss . | |
0bd7a37c MD |
1343 | .Pp |
1344 | Because the transaction id in the snapshot softlink cannot be used | |
1345 | to calculate a timestamp, | |
1346 | .Nm HAMMER | |
4567021b TN |
1347 | uses the earlier of the |
1348 | .Fa st_ctime | |
1349 | or | |
1350 | .Fa st_mtime | |
1351 | field of the softlink to | |
0bd7a37c MD |
1352 | determine which snapshots fall within the retention period. |
1353 | Users must be sure to retain one of these two fields when manipulating | |
1354 | the softlink. | |
34ebae70 | 1355 | .El |
34bb69d8 | 1356 | .\" ==== pfs-upgrade ==== |
4567021b | 1357 | .It Cm pfs-upgrade Ar dirpath |
2010519f | 1358 | Upgrade a PFS from slave to master operation. |
4567021b | 1359 | The PFS will be rolled back to the current end synchronization transaction id |
2010519f | 1360 | (removing any partial synchronizations), and will then become writable. |
34bb69d8 TN |
1361 | .Pp |
1362 | .Em WARNING! | |
1363 | .Nm HAMMER | |
1364 | currently supports only single masters and using | |
2010519f TN |
1365 | this command can easily result in file system corruption |
1366 | if you don't know what you are doing. | |
34bb69d8 TN |
1367 | .Pp |
1368 | This directive will refuse to run if any programs have open descriptors | |
1369 | in the PFS, including programs chdir'd into the PFS. | |
1370 | .\" ==== pfs-downgrade ==== | |
4567021b | 1371 | .It Cm pfs-downgrade Ar dirpath |
aaf93065 | 1372 | Downgrade a master PFS from master to slave operation. |
2010519f | 1373 | The PFS becomes read-only and access will be locked to its |
4567021b | 1374 | .Cm sync-end-tid . |
34bb69d8 TN |
1375 | .Pp |
1376 | This directive will refuse to run if any programs have open descriptors | |
1377 | in the PFS, including programs chdir'd into the PFS. | |
1378 | .\" ==== pfs-destroy ==== | |
4567021b | 1379 | .It Cm pfs-destroy Ar dirpath |
34bb69d8 TN |
1380 | This permanently destroys a PFS. |
1381 | .Pp | |
1382 | This directive will refuse to run if any programs have open descriptors | |
1383 | in the PFS, including programs chdir'd into the PFS. | |
5f22d366 TN |
1384 | As safety measure the |
1385 | .Fl y | |
1386 | flag have no effect on this directive. | |
15fa4caf | 1387 | .\" ==== mirror-read ==== |
4567021b | 1388 | .It Cm mirror-read Ar filesystem Op Ar begin-tid |
34ebae70 | 1389 | Generate a mirroring stream to stdout. |
48eadef9 | 1390 | The stream ends when the transaction id space has been exhausted. |
5f22d366 TN |
1391 | .Ar filesystem |
1392 | may be a master or slave PFS. | |
15fa4caf | 1393 | .\" ==== mirror-read-stream ==== |
4567021b | 1394 | .It Cm mirror-read-stream Ar filesystem Op Ar begin-tid |
48eadef9 MD |
1395 | Generate a mirroring stream to stdout. |
1396 | Upon completion the stream is paused until new data is synced to the | |
aaf93065 TN |
1397 | .Ar filesystem , |
1398 | then resumed. | |
48eadef9 | 1399 | Operation continues until the pipe is broken. |
aaf93065 TN |
1400 | See the |
1401 | .Cm mirror-stream | |
1402 | command for more details. | |
15fa4caf | 1403 | .\" ==== mirror-write ==== |
4567021b | 1404 | .It Cm mirror-write Ar filesystem |
34bb69d8 | 1405 | Take a mirroring stream on stdin. |
5f22d366 TN |
1406 | .Ar filesystem |
1407 | must be a slave PFS. | |
34ebae70 MD |
1408 | .Pp |
1409 | This command will fail if the | |
4567021b | 1410 | .Cm shared-uuid |
b4448f1a | 1411 | configuration field for the two file systems do not match. |
aaf93065 TN |
1412 | See the |
1413 | .Cm mirror-copy | |
1414 | command for more details. | |
01a72c9f MD |
1415 | .Pp |
1416 | If the target PFS does not exist this command will ask you whether | |
1417 | you want to create a compatible PFS slave for the target or not. | |
15fa4caf | 1418 | .\" ==== mirror-dump ==== |
9f1b0121 | 1419 | .It Ar mirror-dump Ar [header] |
15fa4caf | 1420 | A |
4567021b | 1421 | .Cm mirror-read |
15fa4caf | 1422 | can be piped into a |
4567021b | 1423 | .Cm mirror-dump |
2010519f | 1424 | to dump an ASCII representation of the mirroring stream. |
9f1b0121 AHJ |
1425 | If the keyword |
1426 | .Ar header | |
1427 | is specified, only the header information is shown. | |
15fa4caf | 1428 | .\" ==== mirror-copy ==== |
4567021b | 1429 | .\".It Cm mirror-copy Ar [[user@]host:]filesystem [[user@]host:]filesystem |
f85afb25 | 1430 | .It Cm mirror-copy \ |
f6532f03 TN |
1431 | Oo Oo Ar user Ns Cm @ Oc Ns Ar host Ns Cm \&: Oc Ns Ar filesystem \ |
1432 | Oo Oo Ar user Ns Cm @ Oc Ns Ar host Ns Cm \&: Oc Ns Ar filesystem | |
84082922 | 1433 | This is a shortcut which pipes a |
4567021b | 1434 | .Cm mirror-read |
84082922 | 1435 | command to a |
4567021b | 1436 | .Cm mirror-write |
2010519f TN |
1437 | command. |
1438 | If a remote host specification is made the program forks a | |
6d9ab5c5 | 1439 | .Xr ssh 1 |
e2c596b1 CT |
1440 | (or other program as specified by the |
1441 | .Ev HAMMER_RSH | |
1442 | environment variable) and execs the | |
4567021b | 1443 | .Cm mirror-read |
84082922 | 1444 | and/or |
4567021b | 1445 | .Cm mirror-write |
84082922 | 1446 | on the appropriate host. |
9c67b4d2 | 1447 | The source may be a master or slave PFS, and the target must be a slave PFS. |
d4e5b69b | 1448 | .Pp |
aaf93065 TN |
1449 | This command also establishes full duplex communication and turns on |
1450 | the 2-way protocol feature | |
1451 | .Fl ( 2 ) | |
1452 | which automatically negotiates transaction id | |
2010519f | 1453 | ranges without having to use a cyclefile. |
84082922 | 1454 | If the operation completes successfully the target PFS's |
4567021b | 1455 | .Cm sync-end-tid |
2010519f TN |
1456 | will be updated. |
1457 | Note that you must re-chdir into the target PFS to see the updated information. | |
1458 | If you do not you will still be in the previous snapshot. | |
01a72c9f MD |
1459 | .Pp |
1460 | If the target PFS does not exist this command will ask you whether | |
1461 | you want to create a compatible PFS slave for the target or not. | |
15fa4caf | 1462 | .\" ==== mirror-stream ==== |
4567021b | 1463 | .\".It Cm mirror-stream Ar [[user@]host:]filesystem [[user@]host:]filesystem |
f85afb25 | 1464 | .It Cm mirror-stream \ |
f6532f03 TN |
1465 | Oo Oo Ar user Ns Cm @ Oc Ns Ar host Ns Cm \&: Oc Ns Ar filesystem \ |
1466 | Oo Oo Ar user Ns Cm @ Oc Ns Ar host Ns Cm \&: Oc Ns Ar filesystem | |
aaf93065 TN |
1467 | This is a shortcut which pipes a |
1468 | .Cm mirror-read-stream | |
1469 | command to a | |
1470 | .Cm mirror-write | |
1471 | command. | |
48eadef9 | 1472 | This command works similarly to |
4567021b | 1473 | .Cm mirror-copy |
e7f926a5 MD |
1474 | but does not exit after the initial mirroring completes. |
1475 | The mirroring operation will resume as changes continue to be made to the | |
aaf93065 | 1476 | source. |
2010519f | 1477 | The command is commonly used with |
48eadef9 MD |
1478 | .Fl i Ar delay |
1479 | and | |
1480 | .Fl b Ar bandwidth | |
1481 | options to keep the mirroring target in sync with the source on a continuing | |
1482 | basis. | |
e7f926a5 MD |
1483 | .Pp |
1484 | If the pipe is broken the command will automatically retry after sleeping | |
4567021b TN |
1485 | for a short while. |
1486 | The time slept will be 15 seconds plus the time given in the | |
0bd7a37c MD |
1487 | .Fl i |
1488 | option. | |
e7f926a5 MD |
1489 | .Pp |
1490 | This command also detects the initial-mirroring case and spends some | |
1491 | time scanning the B-Tree to find good break points, allowing the initial | |
5f22d366 | 1492 | bulk mirroring operation to be broken down into 4GB pieces. |
e7f926a5 MD |
1493 | This means that the user can kill and restart the operation and it will |
1494 | not have to start from scratch once it has gotten past the first chunk. | |
0bd7a37c | 1495 | The |
aaf93065 TN |
1496 | .Fl S |
1497 | option may be used to change the size of pieces and the | |
0bd7a37c MD |
1498 | .Fl B |
1499 | option may be used to disable this feature and perform an initial bulk | |
1500 | transfer instead. | |
de1c0b31 | 1501 | .\" ==== version ==== |
4567021b | 1502 | .It Cm version Ar filesystem |
3f2565b9 SW |
1503 | This command returns the |
1504 | .Nm HAMMER | |
4567021b TN |
1505 | file system version for the specified |
1506 | .Ar filesystem | |
1507 | as well as the range of versions supported in the kernel. | |
de1c0b31 MD |
1508 | The |
1509 | .Fl q | |
1510 | option may be used to remove the summary at the end. | |
1511 | .\" ==== version-upgrade ==== | |
4567021b | 1512 | .It Cm version-upgrade Ar filesystem Ar version Op Cm force |
5f22d366 | 1513 | Upgrade the |
3f2565b9 | 1514 | .Nm HAMMER |
4567021b TN |
1515 | .Ar filesystem |
1516 | to the specified | |
1517 | .Ar version . | |
1518 | Once upgraded a file system may not be downgraded. | |
1519 | If you wish to upgrade a file system to a version greater or equal to the | |
5f22d366 | 1520 | work-in-progress (WIP) version number you must specify the |
4567021b | 1521 | .Cm force |
de1c0b31 MD |
1522 | directive. |
1523 | Use of WIP versions should be relegated to testing and may require wiping | |
f6532f03 | 1524 | the file system as development progresses, even though the WIP version might |
de1c0b31 MD |
1525 | not change. |
1526 | .Pp | |
4567021b TN |
1527 | .Em NOTE! |
1528 | This command operates on the entire | |
3f2565b9 | 1529 | .Nm HAMMER |
4567021b | 1530 | file system and is not a per PFS operation. |
3f2565b9 | 1531 | All PFS's will be affected. |
de1c0b31 MD |
1532 | .Bl -tag -width indent |
1533 | .It 1 | |
3f2565b9 SW |
1534 | .Dx 2.0 |
1535 | default version, first | |
1536 | .Nm HAMMER | |
1537 | release. | |
de1c0b31 | 1538 | .It 2 |
f6532f03 TN |
1539 | .Dx 2.3 . |
1540 | New directory entry layout. | |
4567021b | 1541 | This version is using a new directory hash key. |
16265794 | 1542 | .It 3 |
856bc468 | 1543 | .Dx 2.5 . |
f6532f03 | 1544 | New snapshot management, using file system meta-data for saving |
16265794 TN |
1545 | configuration file and snapshots (transaction ids etc.). |
1546 | Also default snapshots directory has changed. | |
1547 | .It 4 | |
9d0a6205 | 1548 | .Dx 2.6 |
856bc468 | 1549 | default version. |
5f22d366 TN |
1550 | New undo/redo/flush, giving |
1551 | .Nm HAMMER | |
1552 | a much faster sync and fsync. | |
3fda8610 SW |
1553 | .It 5 |
1554 | .Dx 2.9 . | |
5f22d366 TN |
1555 | Deduplication support. |
1556 | .It 6 | |
1557 | .Dx 2.9 . | |
1558 | Directory hash ALG1. | |
1559 | Tends to maintain inode number / directory name entry ordering better | |
1560 | for files after minor renaming. | |
de1c0b31 | 1561 | .El |
0dfeb6c8 | 1562 | .El |
4567021b | 1563 | .Sh PSEUDO-FILESYSTEM (PFS) NOTES |
b4448f1a TN |
1564 | The root of a PFS is not hooked into the primary |
1565 | .Nm HAMMER | |
2010519f | 1566 | file system as a directory. |
b4448f1a TN |
1567 | Instead, |
1568 | .Nm HAMMER | |
4567021b TN |
1569 | creates a special softlink called |
1570 | .Ql @@PFS%05d | |
1571 | (exactly 10 characters long) in the primary | |
b4448f1a TN |
1572 | .Nm HAMMER |
1573 | file system. | |
1574 | .Nm HAMMER | |
1575 | then modifies the contents of the softlink as read by | |
9c67b4d2 | 1576 | .Xr readlink 2 , |
84082922 | 1577 | and thus what you see with an |
16265794 | 1578 | .Nm ls |
84082922 | 1579 | command or if you were to |
16265794 | 1580 | .Nm cd |
84082922 | 1581 | into the link. |
9c67b4d2 MD |
1582 | If the PFS is a master the link reflects the current state of the PFS. |
1583 | If the PFS is a slave the link reflects the last completed snapshot, and the | |
1584 | contents of the link will change when the next snapshot is completed, and | |
1585 | so forth. | |
1586 | .Pp | |
2010519f | 1587 | The |
9c67b4d2 | 1588 | .Nm |
2010519f | 1589 | utility employs numerous safeties to reduce user foot-shooting. |
9c67b4d2 | 1590 | The |
4567021b | 1591 | .Cm mirror-copy |
9c67b4d2 | 1592 | directive requires that the target be configured as a slave and that the |
4567021b | 1593 | .Cm shared-uuid |
9c67b4d2 | 1594 | field of the mirroring source and target match. |
3d048a1b MD |
1595 | .Sh DOUBLE_BUFFER MODE |
1596 | There is a limit to the number of vnodes the kernel can cache, and because | |
1597 | file buffers are associated with a vnode the related data cache can get | |
1598 | blown away when operating on large numbers of files even if the system has | |
1599 | sufficient memory to hold the file data. | |
1600 | .Pp | |
5f22d366 TN |
1601 | If you turn on |
1602 | .Nm HAMMER Ns 's | |
1603 | double buffer mode by setting the | |
1604 | .Xr sysctl 8 | |
1605 | node | |
3d048a1b MD |
1606 | .Va vfs.hammer.double_buffer |
1607 | to 1 | |
1608 | .Nm HAMMER | |
1609 | will cache file data via the block device and copy it into the per-file | |
1610 | buffers as needed. The data will be double-cached at least until the | |
1611 | buffer cache throws away the file buffer. | |
bedb3c1c | 1612 | This mode is typically used in conjunction with |
3d048a1b MD |
1613 | .Xr swapcache 8 |
1614 | when | |
1615 | .Va vm.swapcache.data_enable | |
1616 | is turned on in order to prevent unnecessary re-caching of file data | |
1617 | due to vnode recycling. | |
5f22d366 TN |
1618 | The swapcache will save the cached VM pages related to |
1619 | .Nm HAMMER Ns 's | |
1620 | block | |
3d048a1b MD |
1621 | device (which doesn't recycle unless you umount the filesystem) instead |
1622 | of the cached VM pages backing the file vnodes. | |
125966e8 | 1623 | .Pp |
7c5aac38 | 1624 | Double buffering is normally desirable when working with large filesystems, |
125966e8 MD |
1625 | particularly when swapcache is used. |
1626 | The swapcache can only back active VM objects, including the block device, | |
1627 | and large filesystems often have far more inodes than the kernel can support. | |
1628 | In addition, when using this mode, you may wish to reduce the | |
1629 | .Va kern.maxvnodes | |
1630 | setting for the system to force the system to do less caching of logical | |
1631 | file buffers and more caching of device buffers, since the device buffers | |
1632 | are backing the logical file buffers. | |
bf2c6489 | 1633 | .Sh UPGRADE INSTRUCTIONS HAMMER V1 TO V2 |
16265794 | 1634 | This upgrade changes the way directory entries are stored. |
f6532f03 | 1635 | It is possible to upgrade a V1 file system to V2 in place, but |
bf2c6489 MD |
1636 | directories created prior to the upgrade will continue to use |
1637 | the old layout. | |
1638 | .Pp | |
1639 | Note that the slave mirroring code in the target kernel had bugs in | |
1640 | V1 which can create an incompatible root directory on the slave. | |
16265794 TN |
1641 | Do not mix a |
1642 | .Nm HAMMER | |
1643 | master created after the upgrade with a | |
1644 | .Nm HAMMER | |
bf2c6489 MD |
1645 | slave created prior to the upgrade. |
1646 | .Pp | |
1647 | Any directories created after upgrading will use a new layout. | |
1648 | .Sh UPGRADE INSTRUCTIONS HAMMER V2 TO V3 | |
16265794 | 1649 | This upgrade adds meta-data elements to the B-Tree. |
f6532f03 | 1650 | It is possible to upgrade a V2 file system to V3 in place. |
16265794 TN |
1651 | After issuing the upgrade be sure to run a |
1652 | .Nm | |
1653 | .Cm cleanup | |
1654 | to perform post-upgrade tasks. | |
bf2c6489 | 1655 | .Pp |
16265794 TN |
1656 | After making this upgrade running a |
1657 | .Nm | |
1658 | .Cm cleanup | |
1659 | will move the | |
1660 | .Pa <pfs>/snapshots | |
bf2c6489 | 1661 | directory for each PFS mount into |
16265794 TN |
1662 | .Pa /var/hammer/<pfs> . |
1663 | A | |
1664 | .Nm HAMMER | |
1665 | root mount will migrate | |
bf2c6489 MD |
1666 | .Pa /snapshots |
1667 | into | |
1668 | .Pa /var/hammer/root . | |
1669 | Migration occurs only once and only if you have not specified | |
16265794 TN |
1670 | a snapshots directory in the PFS configuration. |
1671 | If you have specified a snapshots directory in the PFS configuration no | |
bf2c6489 MD |
1672 | automatic migration will occur. |
1673 | .Pp | |
1674 | For slaves, if you desire, you can migrate your snapshots | |
1675 | config to the new location manually and then clear the | |
1676 | snapshot directory configuration in the slave PFS. | |
1677 | The new snapshots hierarchy is designed to work with | |
1678 | both master and slave PFSs equally well. | |
1679 | .Pp | |
f6532f03 | 1680 | In addition, the old config file will be moved to file system meta-data, |
16265794 TN |
1681 | editable via the new |
1682 | .Nm | |
bf2c6489 | 1683 | .Cm viconfig |
16265794 TN |
1684 | directive. |
1685 | The old config file will be deleted. | |
bf2c6489 MD |
1686 | Migration occurs only once. |
1687 | .Pp | |
f6532f03 | 1688 | The V3 file system has new |
bf2c6489 MD |
1689 | .Cm snap* |
1690 | directives for creating snapshots. | |
1691 | All snapshot directives, including the original, will create | |
1692 | meta-data entries for the snapshots and the pruning code will | |
1693 | automatically incorporate these entries into its list and | |
1694 | expire them the same way it expires softlinks. | |
16265794 | 1695 | If you by accident blow away your snapshot softlinks you can use the |
bf2c6489 | 1696 | .Cm snapls |
f6532f03 | 1697 | directive to get a definitive list from the file system meta-data and |
bf2c6489 | 1698 | regenerate them from that list. |
92ed14a3 | 1699 | .Pp |
16265794 TN |
1700 | .Em WARNING! |
1701 | If you are using | |
1702 | .Nm | |
f6532f03 | 1703 | to backup file systems your scripts may be using the |
92ed14a3 | 1704 | .Cm synctid |
16265794 TN |
1705 | directive to generate transaction ids. |
1706 | This directive does not create a snapshot. | |
1707 | You will have to modify your scripts to use the | |
92ed14a3 MD |
1708 | .Cm snapq |
1709 | directive to generate the linkbuf for the softlink you create, or | |
1710 | use one of the other | |
1711 | .Cm snap* | |
1712 | directives. | |
1713 | The older | |
1714 | .Cm snapshot | |
1715 | directive will continue to work as expected and in V3 it will also | |
f6532f03 | 1716 | record the snapshot transaction id in file system meta-data. |
16265794 TN |
1717 | You may also want to make use of the new |
1718 | .Ar note | |
1719 | tag for the meta-data. | |
92ed14a3 | 1720 | .Pp |
16265794 TN |
1721 | .Em WARNING! |
1722 | If you used to remove snapshot softlinks with | |
92ed14a3 MD |
1723 | .Nm rm |
1724 | you should probably start using the | |
1725 | .Cm snaprm | |
1726 | directive instead to also remove the related meta-data. | |
1727 | The pruning code scans the meta-data so just removing the | |
1728 | softlink is not sufficient. | |
856bc468 TN |
1729 | .Sh UPGRADE INSTRUCTIONS HAMMER V3 TO V4 |
1730 | This upgrade changes undo/flush, giving faster sync. | |
1731 | It is possible to upgrade a V3 file system to V4 in place. | |
5f22d366 TN |
1732 | This upgrade reformats the UNDO/REDO FIFO (typically 1GB), |
1733 | so upgrade might take a minute or two depending. | |
856bc468 | 1734 | .Pp |
5f22d366 | 1735 | Version 4 allows the UNDO/REDO FIFO to be flushed without also having |
856bc468 | 1736 | to flush the volume header, removing 2 of the 4 disk syncs typically |
aaf93065 TN |
1737 | required for an |
1738 | .Fn fsync | |
1739 | and removing 1 of the 2 disk syncs typically | |
856bc468 | 1740 | required for a flush sequence. |
5f22d366 TN |
1741 | Version 4 also implements the REDO log (see |
1742 | .Sx FSYNC FLUSH MODES | |
1743 | below) which is capable | |
9d0a6205 | 1744 | of fsync()ing with either one disk flush or zero disk flushes. |
3fda8610 | 1745 | .Sh UPGRADE INSTRUCTIONS HAMMER V4 TO V5 |
5f22d366 TN |
1746 | This upgrade brings in deduplication support. |
1747 | It is possible to upgrade a V4 file system to V5 in place. | |
1748 | Technically it makes the layer2 | |
1749 | .Va bytes_free | |
1750 | field a signed value instead of unsigned, allowing it to go negative. | |
1751 | A version 5 filesystem is required for dedup operation. | |
1752 | .Sh UPGRADE INSTRUCTIONS HAMMER V5 TO V6 | |
1753 | It is possible to upgrade a V5 file system to V6 in place. | |
152385a8 | 1754 | .Sh FSYNC FLUSH MODES |
aaf93065 TN |
1755 | .Nm HAMMER |
1756 | implements five different fsync flush modes via the | |
1757 | .Va vfs.hammer.fsync_mode | |
1758 | sysctl, for | |
1759 | .Nm HAMMER | |
1760 | version 4+ file systems. | |
152385a8 | 1761 | .Pp |
9d0a6205 | 1762 | As of |
aaf93065 | 1763 | .Dx 2.6 |
9d0a6205 MD |
1764 | fsync mode 3 is set by default. |
1765 | REDO operation and recovery is enabled by default. | |
152385a8 MD |
1766 | .Bl -tag -width indent |
1767 | .It mode 0 | |
1768 | Full synchronous fsync semantics without REDO. | |
1769 | .Pp | |
aaf93065 TN |
1770 | .Nm HAMMER |
1771 | will not generate REDOs. | |
1772 | A | |
1773 | .Fn fsync | |
1774 | will completely sync | |
152385a8 | 1775 | the data and meta-data and double-flush the FIFO, including |
aaf93065 TN |
1776 | issuing two disk synchronization commands. |
1777 | The data is guaranteed | |
1778 | to be on the media as of when | |
1779 | .Fn fsync | |
1780 | returns. | |
152385a8 | 1781 | Needless to say, this is slow. |
152385a8 MD |
1782 | .It mode 1 |
1783 | Relaxed asynchronous fsync semantics without REDO. | |
1784 | .Pp | |
1785 | This mode works the same as mode 0 except the last disk synchronization | |
aaf93065 TN |
1786 | command is not issued. |
1787 | It is faster than mode 0 but not even remotely | |
152385a8 MD |
1788 | close to the speed you get with mode 2 or mode 3. |
1789 | .Pp | |
1790 | Note that there is no chance of meta-data corruption when using this | |
aaf93065 TN |
1791 | mode, it simply means that the data you wrote and then |
1792 | .Fn fsync Ns 'd | |
1793 | might not have made it to the media if the storage system crashes at a bad | |
152385a8 | 1794 | time. |
152385a8 MD |
1795 | .It mode 2 |
1796 | Full synchronous fsync semantics using REDO. | |
5f22d366 TN |
1797 | NOTE: If not running a |
1798 | .Nm HAMMER | |
1799 | version 4 filesystem or later mode 0 is silently used. | |
152385a8 | 1800 | .Pp |
aaf93065 TN |
1801 | .Nm HAMMER |
1802 | will generate REDOs in the UNDO/REDO FIFO based on a heuristic. | |
1803 | If this is sufficient to satisfy the | |
1804 | .Fn fsync | |
5f22d366 | 1805 | operation the blocks will be written out and |
aaf93065 TN |
1806 | .Nm HAMMER |
1807 | will wait for the I/Os to complete, | |
152385a8 MD |
1808 | and then followup with a disk sync command to guarantee the data |
1809 | is on the media before returning. | |
1810 | This is slower than mode 3 and can result in significant disk or | |
1811 | SSDs overheads, though not as bad as mode 0 or mode 1. | |
152385a8 MD |
1812 | .It mode 3 |
1813 | Relaxed asynchronous fsync semantics using REDO. | |
5f22d366 TN |
1814 | NOTE: If not running a |
1815 | .Nm HAMMER | |
1816 | version 4 filesystem or later mode 1 is silently used. | |
152385a8 | 1817 | .Pp |
aaf93065 TN |
1818 | .Nm HAMMER |
1819 | will generate REDOs in the UNDO/REDO FIFO based on a heuristic. | |
1820 | If this is sufficient to satisfy the | |
1821 | .Fn fsync | |
1822 | operation the blocks | |
1823 | will be written out and | |
1824 | .Nm HAMMER | |
1825 | will wait for the I/Os to complete, | |
152385a8 MD |
1826 | but will |
1827 | .Em NOT | |
1828 | issue a disk synchronization command. | |
1829 | .Pp | |
1830 | Note that there is no chance of meta-data corruption when using this | |
aaf93065 TN |
1831 | mode, it simply means that the data you wrote and then |
1832 | .Fn fsync Ns 'd | |
1833 | might | |
152385a8 MD |
1834 | not have made it to the media if the storage system crashes at a bad |
1835 | time. | |
1836 | .Pp | |
1837 | This mode is the fastest production fsyncing mode available. | |
aaf93065 TN |
1838 | This mode is equivalent to how the UFS fsync in the |
1839 | .Bx Ns s | |
1840 | operates. | |
152385a8 MD |
1841 | .It mode 4 |
1842 | fsync is ignored. | |
1843 | .Pp | |
aaf93065 TN |
1844 | Calls to |
1845 | .Fn fsync | |
1846 | will be ignored. | |
1847 | This mode is primarily designed | |
152385a8 MD |
1848 | for testing and should not be used on a production system. |
1849 | .El | |
3120b3e8 MD |
1850 | .Sh RESTORING FROM A SNAPSHOT BACKUP |
1851 | You restore a snapshot by copying it over to live, but there is a caveat. | |
1852 | The mtime and atime fields for files accessed via a snapshot is locked | |
1853 | to the ctime in order to keep the snapshot consistent, because neither | |
1854 | mtime nor atime changes roll any history. | |
1855 | .Pp | |
1856 | In order to avoid unnecessary copying it is recommended that you use | |
1857 | .Nm cpdup | |
1858 | .Fl VV | |
1859 | .Fl v | |
5f22d366 TN |
1860 | when doing the copyback. |
1861 | Also make sure you traverse the snapshot softlink by appending a ".", | |
1862 | as in "<snapshotpath>/.", and you match up the directory properly. | |
1863 | .Sh RESTORING A PFS FROM A MIRROR | |
1864 | A PFS can be restored from a mirror with | |
1865 | .Cm mirror-copy . | |
1866 | .Cm config | |
1867 | data must be copied separately. | |
1868 | At last the PFS can be upgraded to master using | |
1869 | .Cm pfs-upgrade . | |
1870 | .Pp | |
1871 | It is not possible to restore the root PFS (PFS# 0) by using mirroring, | |
1872 | as the root PFS is always a master PFS. | |
1873 | A normal copy (e.g.\& using | |
1874 | .Xr cpdup 1 ) | |
1875 | must be done, ignoring history. | |
1876 | If history is important, old root PFS can me restored to a new PFS, and | |
1877 | important directories/files can be | |
1878 | .Nm null | |
1879 | mounted to the new PFS. | |
aaf93065 | 1880 | .Sh ENVIRONMENT |
e2c596b1 CT |
1881 | The following environment variables affect the execution of |
1882 | .Nm : | |
aaf93065 TN |
1883 | .Bl -tag -width ".Ev EDITOR" |
1884 | .It Ev EDITOR | |
1885 | The editor program specified in the variable | |
1886 | .Ev EDITOR | |
1887 | will be invoked instead of the default editor, which is | |
1888 | .Xr vi 1 . | |
e2c596b1 CT |
1889 | .It Ev HAMMER_RSH |
1890 | The command specified in the variable | |
1891 | .Ev HAMMER_RSH | |
1892 | will be used to initiate remote operations for the mirror-copy and | |
1893 | mirror-stream commands instead of the default command, which is | |
1894 | .Xr ssh 1 . | |
1895 | The program will be invoked via | |
1896 | .Xr execvp 3 | |
1897 | using a typical | |
1898 | .Xr rsh 1 | |
1899 | style | |
1900 | .Cm -l user host <remote-command> | |
1901 | command line. | |
aaf93065 TN |
1902 | .It Ev VISUAL |
1903 | Same effect as | |
1904 | .Ev EDITOR | |
1905 | variable. | |
8a403cd0 | 1906 | .El |
226f3799 TN |
1907 | .Sh FILES |
1908 | .Bl -tag -width ".It Pa <fs>/var/slaves/<name>" -compact | |
4567021b | 1909 | .It Pa <pfs>/snapshots |
226f3799 | 1910 | default per PFS snapshots directory |
16265794 TN |
1911 | .Nm ( HAMMER |
1912 | VERSION 2-) | |
1913 | .It Pa /var/hammer/<pfs> | |
1914 | default per PFS snapshots directory (not root) | |
1915 | .Nm ( HAMMER | |
1916 | VERSION 3+) | |
1917 | .It Pa /var/hammer/root | |
1918 | default snapshots directory for root directory | |
1919 | .Nm ( HAMMER | |
1920 | VERSION 3+) | |
226f3799 | 1921 | .It Pa <snapshots>/config |
4567021b | 1922 | per PFS |
226f3799 | 1923 | .Nm |
4567021b | 1924 | .Cm cleanup |
226f3799 | 1925 | configuration file |
16265794 TN |
1926 | .Nm ( HAMMER |
1927 | VERSION 2-) | |
226f3799 TN |
1928 | .It Pa <fs>/var/slaves/<name> |
1929 | recommended slave PFS snapshots directory | |
16265794 TN |
1930 | .Nm ( HAMMER |
1931 | VERSION 2-) | |
5f22d366 TN |
1932 | .It Pa <fs>/pfs |
1933 | recommended PFS directory | |
226f3799 | 1934 | .El |
2d8ff97d NA |
1935 | .Sh EXIT STATUS |
1936 | .Ex -std | |
0dfeb6c8 | 1937 | .Sh SEE ALSO |
4567021b | 1938 | .Xr ssh 1 , |
84082922 | 1939 | .Xr undo 1 , |
b4448f1a | 1940 | .Xr HAMMER 5 , |
e0331f4f | 1941 | .Xr periodic.conf 5 , |
5f22d366 | 1942 | .Xr loader 8 , |
84082922 | 1943 | .Xr mount_hammer 8 , |
bb8e52c0 | 1944 | .Xr mount_null 8 , |
5f22d366 TN |
1945 | .Xr newfs_hammer 8 , |
1946 | .Xr swapcache 8 , | |
1947 | .Xr sysctl 8 | |
0dfeb6c8 MD |
1948 | .Sh HISTORY |
1949 | The | |
1950 | .Nm | |
1951 | utility first appeared in | |
1952 | .Dx 1.11 . | |
1953 | .Sh AUTHORS | |
1cb631f7 | 1954 | .An Matthew Dillon Aq Mt dillon@backplane.com |