Update hammer.8:
[dragonfly.git] / sbin / hammer / hammer.8
1 .\" Copyright (c) 2007 The DragonFly Project.  All rights reserved.
2 .\" 
3 .\" This code is derived from software contributed to The DragonFly Project
4 .\" by Matthew Dillon <dillon@backplane.com>
5 .\" 
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 
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.
19 .\" 
32 .\" 
33 .\" $DragonFly: src/sbin/hammer/hammer.8,v 1.43 2008/07/27 21:59:44 thomas Exp $
34 .Dd July 27, 2008
35 .Dt HAMMER 8
36 .Os
37 .Sh NAME
38 .Nm hammer
39 .Nd HAMMER file system utility
41 .Nm
42 .Op Fl h2rv
43 .Op Fl c Ar cyclefile
44 .Op Fl f Ar blkdev[:blkdev]*
45 .\" .Op Fl s Ar linkpath
46 .Op Fl t Ar seconds
47 .Ar command
48 .Ar [argument ...]
50 This manual page documents the
51 .Nm
52 utility which provides miscellaneous functions related to managing a
54 file system.
55 For a general introduction to the
57 file system, its features, and
58 examples on how to set up and maintain one, see
59 .Xr HAMMER 5 .
60 .Pp
61 The options are as follows:
62 .Bl -tag -width indent
63 .It Fl h
64 Get help.
65 .It Fl 2
66 Tell the mirror commands to use a 2-way protocol, which allows
67 automatic negotiation of transaction id ranges.  This option is
68 automatically enabled by the
69 .Ar mirror-copy
70 command.
71 .It Fl r
72 Specify recursion for those commands which support it.
73 .It Fl c Ar cyclefile
74 When pruning and reblocking you can instruction
75 .Nm
76 to start at the
77 object id stored in the specified file.
78 If the file does not exist
79 Nm
80 will start at the beginning.
81 If
82 Nm
83 is told to run for a
84 specific period of time and is unable to complete the operation it will
85 write out the current object id so the next run can pick up where it left
86 off.
87 If
88 .Nm
89 runs to completion it will delete the cyclefile.
90 .It Fl f Ar blkdev[:blkdev]*
91 Specify the volumes making up a
93 file system.
94 .\" .It Fl s Ar linkpath
95 .\" When pruning a filesystem you can instruct
96 .\" .Nm to create softlinks
97 .\" to available snapshots.
98 .It Fl t Ar seconds
99 When pruning and reblocking you can tell the utility to stop after a
100 certain period of time.  This option is used along with the cycle file
101 option to prune or reblock a portion of the file system incrementally.
102 .It Fl v
103 Increase verboseness.  May be specified multiple times.
104 .El
105 .Pp
106 The commands are as follows:
107 .Bl -tag -width indent
108 .It Ar synctid Ar filesystem Op quick
109 Generates a guaranteed, formal 64 bit transaction id representing the
110 current state of the specified
111 .Nm HAMMER
112 file system.  The file system will
113 be synced to the media.
114 .Pp
115 If the
116 .Ar quick
117 keyword is specified the file system will be soft-synced, meaning that a
118 crash might still undo the state of the file system as of the transaction
119 id returned but any new modifications will occur after the returned
120 transaction id as expected.
121 .It Ar bstats Op interval
122 Output
123 .Nm HAMMER
124 B-tree statistics until interrupted.
125 Pause
126 .Ar interval
127 seconds between each display.
128 The default interval is one second.
129 .It Ar iostats Op interval
130 Output
131 .Nm HAMMER
132 I/O statistics until interrupted.
133 Pause
134 .Ar interval
135 seconds between each display.
136 The default interval is one second.
137 .It Ar history Ar path ...
138 Show the modification history for
139 .Nm HAMMER
140 file's inode and data.
141 .It Ar show
142 Dump the B-tree. This command needs the
143 .Fl f
144 flag.
145 .\" .It Ar blockmap
146 .\" Dump the B-tree, record, large-data, and small-data blockmaps, showing
147 .\" physical block assignments and free space percentages.
148 .It Ar namekey Ar filename
149 Generate a
150 .Nm HAMMER
151 64 bit directory hash for the specified file name.
152 The low 32 bits are used as an iterator for hash collisions and will be
153 output as 0.
154 .It Ar namekey32 Ar filename
155 Generate the top 32 bits of a
156 .Nm HAMMER
157 64 bit directory hash for the specified
158 file name.
159 .It Ar prune Ar softlink-dir
160 Prune the file system based on previously created snapshot softlinks.
161 Pruning is the act of deleting file system history.
162 The
163 .Ar prune
164 command
165 will delete file system history such that
166 the file system state is retained for the given snapshots,
167 and all history after the latest snapshot,
168 but all other history is deleted.
169 .Pp
170 The target directory is expected to contain softlinks pointing to
171 snapshots of the file systems you wish to retain.  The directory is scanned
172 non-recursively and the mount points and transaction ids stored in the
173 softlinks are extracted and sorted.
174 The file system is then explicitly pruned according to what is found.
175 Cleaning out portions of the file system is as simple as removing a softlink
176 and then running the
177 .Ar prune
178 command.
179 .Pp
180 As a safety measure pruning only occurs if one or more softlinks are found
181 containing the @@ snapshot id extension.
182 .Pp
183 Currently the scanned softlink directory must contain softlinks pointing
184 to a single
185 .Nm HAMMER
186 mount.  The softlinks may specify absolute or relative
187 paths.  Softlinks must use 20-character (@@0x%016llx) transaction ids,
188 as might be returned from
189 .Dq Nm Ar synctid filesystem .
190 .Pp
191 Example, lets say your snapshot directory contains the following links:
192 .Bd -literal
193 lrwxr-xr-x  1 root  wheel  29 May 31 17:57 snap1 ->
194 /usr/obj/@@0x10d2cd05b7270d16
196 lrwxr-xr-x  1 root  wheel  29 May 31 17:58 snap2 ->
197 /usr/obj/@@0x10d2cd13f3fde98f
199 lrwxr-xr-x  1 root  wheel  29 May 31 17:59 snap3 ->
200 /usr/obj/@@0x10d2cd222adee364
201 .Ed
202 .Pp
203 If you were to run the
204 .Ar prune
205 command on this directory, then the
206 .Nm HAMMER
207 .Pa /usr/obj
208 mount will be pruned to retain the above three snapshots.
209 In addition, history for modifications made to the file system older than the oldest
210 snapshot will be destroyed and history for potentially fine-grained modifications made
211 to the file system more recently than the most recent snapshot will be
212 retained.
213 .Pp
214 If you then delete the snap2 softlink and rerun the
215 .Ar prune
216 command,
217 history for modifications pertaining to that snapshot would be destroyed.
218 .It Ar prune-everything Ar filesystem
219 This command will remove all historical records from the file system.
220 This directive is not normally used on a production system.
221 .Pp
222 Note that pruning a file system may not immediately free-up space,
223 though typically some space will be freed if a large number of records are
224 pruned out.  The file system must be reblocked to completely recover all
225 available space.
226 .It Ar snapshot Ar snapshot-dir
227 .It Ar snapshot Ar filesystem snapshot-dir
228 Takes a snapshot of the file system either explicitly given by
229 .Ar filesystem
230 or implicitly derived from the
231 .Ar snapshot-dir
232 argument and creates a symlink in the directory provided by
233 .Ar snapshot-dir
234 pointing to the snapshot.
235 If
236 .Ar snapshot-dir
237 is not a directory, it is assumed to be a format string
238 passed to
239 .Xr strftime 3
240 with the current time as parameter.
241 If
242 .Ar snapshot-dir
243 refers to an existing directory, a default format string of "snap-%Y%d%m-%H%M"
244 is assumed and used as name for the newly created symlink.
245 Assuming that
246 .Pa /mysnapshots
247 is on file system
248 .Pa /
249 and that
250 .Pa /obj
251 is a file system on its own, the following invocations:
252 .Bd -literal
253 hammer snapshot /mysnapshots
255 hammer snapshot /mysnapshots/%Y-%m-%d
257 hammer snapshot /obj /mysnapshots/obj-%Y-%m-%d
258 .Ed
259 .Pp
260 would create symlinks similar to:
261 .Bd -literal
262 /mysnapshots/snap-20080627-1210 -> /@@0x10d2cd05b7270d16
264 /mysnapshots/2008-06-27 -> /@@0x10d2cd05b7270d16
266 /mysnapshots/obj-2008-06-27 -> /obj@@0x10d2cd05b7270d16
267 .Ed
268 .It Ar reblock Ar filesystem Op Ar fill_percentage
269 .It Ar reblock-btree Ar filesystem Op Ar fill_percentage
270 .It Ar reblock-inodes Ar filesystem Op Ar fill_percentage
271 .It Ar reblock-dirs Ar filesystem Op Ar fill_percentage
272 .It Ar reblock-data Ar filesystem Op Ar fill_percentage
273 Attempt to defragment and free space for reuse by reblocking a live
274 .Nm HAMMER
275 file system.
276 Big blocks cannot be reused by
277 .Nm HAMMER
278 until they are completely free.
279 This command also has the effect of reordering all elements, effectively
280 defragmenting the file system.
281 .Pp
282 The default fill percentage is 100% and will cause the file system to be
283 completely defragmented.  All specified element types will be reallocated
284 and rewritten.  If you wish to quickly free up space instead try specifying
285 a smaller fill percentage, such as 90% or 80% (the '%' suffix is not needed).
286 .Pp
287 Since this command may rewrite the entire contents of the disk it is
288 best to do it incrementally from a
289 .Xr cron 8
290 job along with the
291 .Fl c Ar cyclefile
292 and
293 .Fl t Ar seconds
294 options to limit the run time.
295 The file system would thus be defragmented over long period of time.
296 .Pp
297 It is recommended that separate invocations be used for each data type.
298 B-tree nodes, inodes, and directories are typically the most important
299 elements needing defragmentation.  Data can be defragmented over a longer
300 period of time.
301 .It Ar pfs-status Ar dirpath
302 Retrieve the mirroring configuration parameters for the specified
303 .Nm HAMMER
304 file system or pseudo-filesystem.
305 .It Ar pfs-master Ar dirpath Op options
306 Create a pseudo-filesystem (PFS) inside a
307 .Nm HAMMER
308 file system.
309 Up to 65535 such file systems can be created.
310 Each PFS uses an independent inode numbering space making it suitable
311 for use as a replication source or target.
312 .Pp
313 The
314 .Ar pfs-master
315 directive creates a PFS that you can read, write, and use as a mirroring
316 source.
317 .It Ar pfs-slave Ar dirpath Op options
318 Create a pseudo-filesystem (PFS) inside a
319 .Nm HAMMER
320 file system.
321 Up to 65535 such file systems can be created.
322 Each PFS uses an independent inode numbering space making it suitable
323 for use as a replication source or target.
324 .Pp
325 The
326 .Ar pfs-slave
327 directive creates a PFS that you can use as a mirroring target.
328 You will not be able to access a slave PFS until you have completed the
329 first mirroring operation with it as the target (its root directory will
330 not exist until then).
331 .Pp
332 Access to the pfs-slave via the special softlink,
333 as described in the PFS NOTES below, allows
334 .Nm HAMMER
335 to
336 dynamically modify the snapshot transaction id by returning a dynamic result
337 from
338 .Xr readlink 2
339 calls.
340 .Pp
341 A PFS can only be truly destroyed with the
342 .Ar pfs-destroy
343 directive.
344 Removing the softlink will not destroy the underlying PFS.
345 .It Ar pfs-upgrade Ar dirpath
346 Upgrade a PFS from slave to master operation.  The PFS will be rolled back
347 to the current end synchronization tid (removing any partial synchronizations),
348 and will then becomes writable.
349 .Pp
350 .Em WARNING!
351 .Nm HAMMER
352 currently supports only single masters and using
353 this command can easily result in file system corruption if you don't
354 know what you are doing.
355 .Pp
356 This directive will refuse to run if any programs have open descriptors
357 in the PFS, including programs chdir'd into the PFS.
358 .It Ar pfs-downgrade Ar dirpath
359 Downgrade a master PFS from master to slave operation.  The PFS becomes
360 read-only and access will be locked to its
361 .Ar sync-end-tid .
362 .Pp
363 This directive will refuse to run if any programs have open descriptors
364 in the PFS, including programs chdir'd into the PFS.
365 .It Ar pfs-destroy Ar dirpath
366 This permanently destroys a PFS.
367 .Pp
368 This directive will refuse to run if any programs have open descriptors
369 in the PFS, including programs chdir'd into the PFS.
370 .It Ar pfs-update Ar dirpath Op options
371 Update the configuration parameters for an existing
372 .Nm HAMMER
373 file system
374 or pseudo-filesystem.  Options that may be specified:
375 .Bl -tag -width indent
376 .It sync-beg-tid=0x16llx
377 This is the automatic snapshot access starting transaction id for mirroring slaves.
378 This parameter is normally updated automatically by the
379 .Ar mirror-write
380 directive.
381 .Pp
382 It is important to note that accessing a mirroring slave
383 with a transaction id greater than the last fully synchronized transaction
384 id can result in an unreliable snapshot since you will be accessing
385 data that is still undergoing synchronization.
386 .Pp
387 Manually modifying this field is dangerous and can result in a broken
388 mirror.
389 .It sync-end-tid=0x16llx
390 This is the current synchronization point for mirroring slaves.
391 This parameter is normally updated automatically by the
392 .Ar mirror-write
393 directive.
394 .Pp
395 Manually modifying this field is dangerous and can result in a broken
396 mirror.
397 .It shared-uuid=<uuid>
398 Set the shared UUID for this file system.  All mirrors must have the same
399 shared UUID.  For safety purposes the mirror-write directives will refuse
400 to operate on a target with a different shared UUID.
401 .Pp
402 Changing the shared UUID on an existing, non-empty mirroring target,
403 including an empty but not completely pruned target, can lead
404 to corruption of the mirroring target.
405 .It unique-uuid=<uuid>
406 Set the unique UUID for this file system.  This UUID should not be used
407 anywhere else, even on exact copies of the file system.
408 .It label=<string>
409 Set a descriptive label for this file system.
410 .El
411 .It Ar mirror-read Ar filesystem Op Ar <begin-tid>
412 Generate a mirroring stream to stdout.
413 .It Ar mirror-write Ar filesystem Op Ar
414 Take a mirroring stream on stdin and output it to stdout.
415 .Pp
416 This command will fail if the
417 .Ar shared-uuid
418 configuration field for the two file systems do not match.
419 .It Ar mirror-dump
420 A mirror-read can be piped into a mirror-dump to dump an ascii
421 representation of the mirroring stream.
422 .It Ar mirror-copy Ar [[user@]host:]filesystem Ar [[user@]host:]filesystem
423 This is a shortcut which pipes a
424 .Ar mirror-read
425 command to a
426 .Ar mirror-write
427 command.  If a remote host specification is made the program forks a
428 .Xr ssh 1
429 and execs the
430 .Ar mirror-read
431 and/or
432 .Ar mirror-write
433 on the appropriate host.
434 The source may be a master or slave PFS, and the target must be a slave PFS.
435 .Pp
436 This command also established full duplex communication and turns on
437 the two-way protocol feature which automatically negotiates transaction id ranges
438 without having to use a cycle file.
439 If the operation completes successfully the target PFS's
440 .Ar sync-end-tid
441 will
442 be updated.  Note that you must re-chdir into the target PFS to see the
443 updated information.  If you do not you will still be in the previous snapshot.
444 .El
445 .\".Sh EXAMPLES
447 The root of a PFS is not hooked into the primary
448 .Nm HAMMER
449 file system as a
450 directory.
451 Instead,
452 .Nm HAMMER
453 creates a special softlink called "@@PFS%05d" (exactly 10
454 characters long) in the primary
455 .Nm HAMMER
456 file system.
457 .Nm HAMMER
458 then modifies the contents of the softlink as read by
459 .Xr readlink 2 ,
460 and thus what you see with an
461 .Xr ls 1
462 command or if you were to
463 .Xr cd 1
464 into the link.
465 If the PFS is a master the link reflects the current state of the PFS.
466 If the PFS is a slave the link reflects the last completed snapshot, and the
467 contents of the link will change when the next snapshot is completed, and
468 so forth.
469 .Pp
470 PFS support is currently very new and experimental.  The
471 .Nm
472 utility
473 employs numerous safeties to reduce user foot-shooting.
474 The
475 .Ar mirror-copy
476 directive requires that the target be configured as a slave and that the
477 .Ar shared-uuid
478 field of the mirroring source and target match.
480 .Ex -std
481 .Sh SEE ALSO
482 .Xr undo 1 ,
483 .Xr HAMMER 5 ,
484 .Xr mount_hammer 8 ,
485 .Xr newfs_hammer 8
487 The
488 .Nm
489 utility first appeared in
490 .Dx 1.11 .
492 .An Matthew Dillon Aq dillon@backplane.com