1 .\" Copyright (c) 2007 The DragonFly Project. All rights reserved.
3 .\" This code is derived from software contributed to The DragonFly Project
4 .\" by Matthew Dillon <dillon@backplane.com>
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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
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.
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
33 .\" $DragonFly: src/sbin/hammer/hammer.8,v 1.46 2008/08/21 23:28:43 thomas Exp $
39 .Nd HAMMER file system utility
45 .Op Fl f Ar blkdev[:blkdev]*
46 .\" .Op Fl s Ar linkpath
52 This manual page documents the
54 utility which provides miscellaneous functions related to managing a
57 For a general introduction to the
59 file system, its features, and
60 examples on how to set up and maintain one, see
63 The options are as follows:
64 .Bl -tag -width indent
68 Tell the mirror commands to use a 2-way protocol, which allows
69 automatic negotiation of transaction id ranges. This option is
70 automatically enabled by the
74 Specify recursion for those commands which support it.
76 Specify a bandwidth limit in bytes per second for mirroring streams.
77 This option is typically used to prevent batch mirroring operations from
78 loading down the machine.
79 The bandwidth may be suffixed with
85 values in kilobytes, megabytes, and gigabytes per second.
87 When pruning and reblocking you can instruction
90 object id stored in the specified file.
91 If the file does not exist
93 will start at the beginning.
97 specific period of time and is unable to complete the operation it will
98 write out the current object id so the next run can pick up where it left
102 runs to completion it will delete the cyclefile.
103 .It Fl f Ar blkdev[:blkdev]*
104 Specify the volumes making up a
107 .\" .It Fl s Ar linkpath
108 .\" When pruning a filesystem you can instruct
109 .\" .Nm to create softlinks
110 .\" to available snapshots.
112 When maintaining a streaming mirroring this option specifies the
113 minimum delay after a batch ends before the next batch is allowed
115 The default is five seconds.
117 When pruning and reblocking you can tell the utility to stop after a
118 certain period of time. This option is used along with the cycle file
119 option to prune or reblock a portion of the file system incrementally.
121 Increase verboseness. May be specified multiple times.
124 The commands are as follows:
125 .Bl -tag -width indent
126 .\" ==== synctid ====
127 .It Ar synctid Ar filesystem Op quick
128 Generates a guaranteed, formal 64 bit transaction id representing the
129 current state of the specified
131 file system. The file system will
132 be synced to the media.
136 keyword is specified the file system will be soft-synced, meaning that a
137 crash might still undo the state of the file system as of the transaction
138 id returned but any new modifications will occur after the returned
139 transaction id as expected.
141 .It Ar bstats Op interval
144 B-tree statistics until interrupted.
147 seconds between each display.
148 The default interval is one second.
149 .\" ==== iostats ====
150 .It Ar iostats Op interval
153 I/O statistics until interrupted.
156 seconds between each display.
157 The default interval is one second.
158 .\" ==== history ====
159 .It Ar history Ar path ...
160 Show the modification history for
162 file's inode and data.
165 Dump the B-tree. This command needs the
169 .\" Dump the B-tree, record, large-data, and small-data blockmaps, showing
170 .\" physical block assignments and free space percentages.
171 .\" ==== namekey ====
172 .It Ar namekey Ar filename
175 64 bit directory hash for the specified file name.
176 The low 32 bits are used as an iterator for hash collisions and will be
178 .\" ==== namekey32 ====
179 .It Ar namekey32 Ar filename
180 Generate the top 32 bits of a
182 64 bit directory hash for the specified
185 .It Ar prune Ar softlink-dir
186 Prune the file system based on previously created snapshot softlinks.
187 Pruning is the act of deleting file system history.
191 will delete file system history such that
192 the file system state is retained for the given snapshots,
193 and all history after the latest snapshot,
194 but all other history is deleted.
196 The target directory is expected to contain softlinks pointing to
197 snapshots of the file systems you wish to retain. The directory is scanned
198 non-recursively and the mount points and transaction ids stored in the
199 softlinks are extracted and sorted.
200 The file system is then explicitly pruned according to what is found.
201 Cleaning out portions of the file system is as simple as removing a softlink
206 As a safety measure pruning only occurs if one or more softlinks are found
207 containing the @@ snapshot id extension.
208 Currently the scanned softlink directory must contain softlinks pointing
211 mount. The softlinks may specify absolute or relative
212 paths. Softlinks must use 20-character (@@0x%016llx) transaction ids,
213 as might be returned from
214 .Dq Nm Ar synctid filesystem .
216 Pruning is a per-PFS operation, so a
218 file system and each PFS in it have to be pruned separately.
220 Note that pruning a file system may not immediately free-up space,
221 though typically some space will be freed if a large number of records are
222 pruned out. The file system must be reblocked to completely recover all
225 Example, lets say your snapshot directory contains the following links:
227 lrwxr-xr-x 1 root wheel 29 May 31 17:57 snap1 ->
228 /usr/obj/@@0x10d2cd05b7270d16
230 lrwxr-xr-x 1 root wheel 29 May 31 17:58 snap2 ->
231 /usr/obj/@@0x10d2cd13f3fde98f
233 lrwxr-xr-x 1 root wheel 29 May 31 17:59 snap3 ->
234 /usr/obj/@@0x10d2cd222adee364
237 If you were to run the
239 command on this directory, then the
242 mount will be pruned to retain the above three snapshots.
243 In addition, history for modifications made to the file system older than the oldest
244 snapshot will be destroyed and history for potentially fine-grained modifications made
245 to the file system more recently than the most recent snapshot will be
248 If you then delete the snap2 softlink and rerun the
251 history for modifications pertaining to that snapshot would be destroyed.
252 .\" ==== prune-everything ====
253 .It Ar prune-everything Ar filesystem
254 This command will remove all historical records from the file system.
255 This directive is not normally used on a production system.
256 .\" ==== snapshot ====
257 .It Ar snapshot Ar snapshot-dir
258 .It Ar snapshot Ar filesystem snapshot-dir
259 Takes a snapshot of the file system either explicitly given by
261 or implicitly derived from the
263 argument and creates a symlink in the directory provided by
265 pointing to the snapshot.
268 is not a directory, it is assumed to be a format string
271 with the current time as parameter.
274 refers to an existing directory, a default format string of "snap-%Y%d%m-%H%M"
275 is assumed and used as name for the newly created symlink.
277 Example, assuming that
283 is a file system on its own, the following invocations:
285 hammer snapshot /mysnapshots
287 hammer snapshot /mysnapshots/%Y-%m-%d
289 hammer snapshot /obj /mysnapshots/obj-%Y-%m-%d
292 would create symlinks similar to:
294 /mysnapshots/snap-20080627-1210 -> /@@0x10d2cd05b7270d16
296 /mysnapshots/2008-06-27 -> /@@0x10d2cd05b7270d16
298 /mysnapshots/obj-2008-06-27 -> /obj@@0x10d2cd05b7270d16
300 .\" ==== reblock ====
301 .It Ar reblock Ar filesystem Op Ar fill_percentage
302 .It Ar reblock-btree Ar filesystem Op Ar fill_percentage
303 .It Ar reblock-inodes Ar filesystem Op Ar fill_percentage
304 .It Ar reblock-dirs Ar filesystem Op Ar fill_percentage
305 .It Ar reblock-data Ar filesystem Op Ar fill_percentage
306 Attempt to defragment and free space for reuse by reblocking a live
309 Big blocks cannot be reused by
311 until they are completely free.
312 This command also has the effect of reordering all elements, effectively
313 defragmenting the file system.
315 The default fill percentage is 100% and will cause the file system to be
316 completely defragmented. All specified element types will be reallocated
317 and rewritten. If you wish to quickly free up space instead try specifying
318 a smaller fill percentage, such as 90% or 80% (the
320 suffix is not needed).
322 Since this command may rewrite the entire contents of the disk it is
323 best to do it incrementally from a
329 options to limit the run time.
330 The file system would thus be defragmented over long period of time.
332 It is recommended that separate invocations be used for each data type.
333 B-tree nodes, inodes, and directories are typically the most important
334 elements needing defragmentation. Data can be defragmented over a longer
337 Reblocking is a per-PFS operation, so a
339 file system and each PFS in it have to be reblocked separately.
340 .\" ==== pfs-status ====
341 .It Ar pfs-status Ar dirpath ...
342 Retrieve the mirroring configuration parameters for the specified
344 file systems or pseudo-filesystems.
345 .\" ==== pfs-master ====
346 .It Ar pfs-master Ar dirpath Op options
347 Create a pseudo-filesystem (PFS) inside a
350 Up to 65535 such file systems can be created.
351 Each PFS uses an independent inode numbering space making it suitable
352 for use as a replication source or target.
356 directive creates a PFS that you can read, write, and use as a mirroring
358 .\" ==== pfs-slave ====
359 .It Ar pfs-slave Ar dirpath Op options
360 Create a pseudo-filesystem (PFS) inside a
363 Up to 65535 such file systems can be created.
364 Each PFS uses an independent inode numbering space making it suitable
365 for use as a replication source or target.
369 directive creates a PFS that you can use as a mirroring target.
370 You will not be able to access a slave PFS until you have completed the
371 first mirroring operation with it as the target (its root directory will
372 not exist until then).
374 Access to the pfs-slave via the special softlink,
375 as described in the PFS NOTES below, allows
378 dynamically modify the snapshot transaction id by returning a dynamic result
383 A PFS can only be truly destroyed with the
386 Removing the softlink will not destroy the underlying PFS.
387 .\" ==== pfs-update ====
388 .It Ar pfs-update Ar dirpath Op options
389 Update the configuration parameters for an existing
392 or pseudo-filesystem. Options that may be specified:
393 .Bl -tag -width indent
394 .It sync-beg-tid=0x16llx
395 This is the automatic snapshot access starting transaction id for mirroring slaves.
396 This parameter is normally updated automatically by the
400 It is important to note that accessing a mirroring slave
401 with a transaction id greater than the last fully synchronized transaction
402 id can result in an unreliable snapshot since you will be accessing
403 data that is still undergoing synchronization.
405 Manually modifying this field is dangerous and can result in a broken
407 .It sync-end-tid=0x16llx
408 This is the current synchronization point for mirroring slaves.
409 This parameter is normally updated automatically by the
413 Manually modifying this field is dangerous and can result in a broken
415 .It shared-uuid=<uuid>
416 Set the shared UUID for this file system. All mirrors must have the same
417 shared UUID. For safety purposes the
419 directives will refuse
420 to operate on a target with a different shared UUID.
422 Changing the shared UUID on an existing, non-empty mirroring target,
423 including an empty but not completely pruned target, can lead
424 to corruption of the mirroring target.
425 .It unique-uuid=<uuid>
426 Set the unique UUID for this file system. This UUID should not be used
427 anywhere else, even on exact copies of the file system.
429 Set a descriptive label for this file system.
431 .\" ==== pfs-upgrade ====
432 .It Ar pfs-upgrade Ar dirpath
433 Upgrade a PFS from slave to master operation. The PFS will be rolled back
434 to the current end synchronization tid (removing any partial synchronizations),
435 and will then becomes writable.
439 currently supports only single masters and using
440 this command can easily result in file system corruption if you don't
441 know what you are doing.
443 This directive will refuse to run if any programs have open descriptors
444 in the PFS, including programs chdir'd into the PFS.
445 .\" ==== pfs-downgrade ====
446 .It Ar pfs-downgrade Ar dirpath
447 Downgrade a master PFS from master to slave operation. The PFS becomes
448 read-only and access will be locked to its
451 This directive will refuse to run if any programs have open descriptors
452 in the PFS, including programs chdir'd into the PFS.
453 .\" ==== pfs-destroy ====
454 .It Ar pfs-destroy Ar dirpath
455 This permanently destroys a PFS.
457 This directive will refuse to run if any programs have open descriptors
458 in the PFS, including programs chdir'd into the PFS.
459 .\" ==== mirror-read ====
460 .It Ar mirror-read Ar filesystem Op Ar <begin-tid>
461 Generate a mirroring stream to stdout.
462 The stream ends when the transaction id space has been exhausted.
463 .\" ==== mirror-read-stream ====
464 .It Ar mirror-read-stream Ar filesystem Op Ar <begin-tid>
465 Generate a mirroring stream to stdout.
466 Upon completion the stream is paused until new data is synced to the
467 master, then resumed.
468 Operation continues until the pipe is broken.
469 .\" ==== mirror-write ====
470 .It Ar mirror-write Ar filesystem
471 Take a mirroring stream on stdin.
473 This command will fail if the
475 configuration field for the two file systems do not match.
476 .\" ==== mirror-dump ====
483 representation of the mirroring stream.
484 .\" ==== mirror-copy ====
485 .It Ar mirror-copy Ar [[user@]host:]filesystem Ar [[user@]host:]filesystem
486 This is a shortcut which pipes a
490 command. If a remote host specification is made the program forks a
496 on the appropriate host.
497 The source may be a master or slave PFS, and the target must be a slave PFS.
499 This command also established full duplex communication and turns on
500 the two-way protocol feature which automatically negotiates transaction id ranges
501 without having to use a cycle file.
502 If the operation completes successfully the target PFS's
505 be updated. Note that you must re-chdir into the target PFS to see the
506 updated information. If you do not you will still be in the previous snapshot.
507 .\" ==== mirror-stream ====
508 .It Ar mirror-stream Ar [[user@]host:]filesystem Ar [[user@]host:]filesystem
509 This command works similarly to
511 but does not exit unless the pipe is broken.
512 This command will resume the mirroring operation whenever the master is
513 synced. The command is commonly used with
517 options to keep the mirroring target in sync with the source on a continuing
521 .Sh PSEUDO FILESYSTEM (PFS) NOTES
522 The root of a PFS is not hooked into the primary
528 creates a special softlink called "@@PFS%05d" (exactly 10
529 characters long) in the primary
533 then modifies the contents of the softlink as read by
535 and thus what you see with an
537 command or if you were to
540 If the PFS is a master the link reflects the current state of the PFS.
541 If the PFS is a slave the link reflects the last completed snapshot, and the
542 contents of the link will change when the next snapshot is completed, and
545 PFS support is currently very new and experimental. The
548 employs numerous safeties to reduce user foot-shooting.
551 directive requires that the target be configured as a slave and that the
553 field of the mirroring source and target match.
564 utility first appeared in
567 .An Matthew Dillon Aq dillon@backplane.com