man hammer(8) - HAMMER file system utility

NAME

hammer - HAMMER file system utility

SYNOPSIS

hammer [-h2qrv] [-b bandwidth] [-c cyclefile] [-f blkdev[:blkdev]*] [-i delay] [-t seconds] command [argument ...]

DESCRIPTION

This manual page documents the hammer utility which provides miscellaneous functions related to managing a HAMMER file system. For a general introduction to the HAMMER file system, its features, and examples on how to set up and maintain one, see HAMMER(5).

The options are as follows:

-h

Get help.

-2

Tell the mirror commands to use a 2-way protocol, which allows automatic negotiation of transaction id ranges. This option is automatically enabled by the mirror-copy command.

-b bandwidth

Specify a bandwidth limit in bytes per second for mirroring streams. This option is typically used to prevent batch mirroring operations from loading down the machine. The bandwidth may be suffixed with `k', `m', or `g' to specify values in kilobytes, megabytes, and gigabytes per second. If no suffix is specified, bytes per second is assumed.

-c cyclefile

When pruning and reblocking you can instruction hammer to start at the object id stored in the specified file. If the file does not exist hammer will start at the beginning. If hammer is told to run for a specific period of time and is unable to complete the operation it will write out the current object id so the next run can pick up where it left off. If hammer runs to completion it will delete cyclefile.

-f blkdev[:blkdev]*

Specify the volumes making up a HAMMER file system.

-i delay

When maintaining a streaming mirroring this option specifies the minimum delay after a batch ends before the next batch is allowed to start. The default is five seconds.

-q

Decrease verbosement. May be specified multiple times.

-r

Specify recursion for those commands which support it.

-t seconds

When pruning and reblocking you can tell the utility to stop after a certain period of time. This option is used along with the -c cyclefile option to prune or reblock a portion of the file system incrementally.

-v

Increase verboseness. May be specified multiple times.

The commands are as follows:

synctid filesystem [quick]

Generates a guaranteed, formal 64 bit transaction id representing the current state of the specified HAMMER file system. The file system will be synced to the media.

If the quick keyword is specified the file system will be softsynced, meaning that a crash might still undo the state of the file system as of the transaction id returned but any new modifications will occur after the returned transaction id as expected.

bstats [interval]

Output HAMMER B-tree statistics until interrupted. Pause interval seconds between each display. The default interval is one second.

iostats [interval]

Output HAMMER I/O statistics until interrupted. Pause interval seconds between each display. The default interval is one second.

history path ...

Show the modification history for HAMMER file's inode and data.

show Dump the B-tree. This command needs the -f flag.

namekey1 filename

Generate a HAMMER 64 bit directory hash for the specified file name, using the original directory hash algorithm in version 1 of the filesystem. The low 32 bits are used as an iterator for hash collisions and will be output as 0.

namekey2 filename

Generate a HAMMER 64 bit directory hash for the specified file name, using the new directory hash algorithm in version 2 of the filesystem. The low 32 bits are still used as an iterator but will start out containing part of the hash key.

namekey32 filename

Generate the top 32 bits of a HAMMER 64 bit directory hash for the specified file name.

cleanup [filesystem ...]

This is a meta-command which executes snapshot, pruning, and reblocking commands on the specified HAMMER file system. If no filesystem is specified this command will clean-up all HAMMER file systems in use, including PFS's. To do this it will scan all HAMMER and null mounts, extract PFS id's, and clean-up each PFS found.

This command will by default access a snapshots subdirectory and a snapshots/config file for each filesystem, creating them if necessary. The format of the configuration file is:

snapshots <period> <retention-time> [any]

prune <period> <max-runtime>

reblock <period> <1/3 max-runtime>

recopy <period> <1/3 max-runtime>

Defaults are:

snapshots 1d 60d # 0d 60d for PFS /tmp, /var/tmp, /usr/obj

prune 1d 5m

reblock 1d 5m

recopy 30d 10m

Time is given with a suffix of d, h, m or s meaning day, hour, minute and second.

If the snapshots directive has a period of 0 and a retention time of 0 then snapshot generation is disabled, removal of old snapshots are disabled, and prunes will use prune-everything. If the snapshots directive has a period of 0 but a non-zero retention time then this command will not create any new snapshots but will remove old snapshots it finds based on the retention time.

By default only snapshots in the form: snap-yyyymmdd[-hhmm] are processed. If the any directive is specified as a third argument on the snapshots config line then any softlink of the form *[- or .]yyyymmdd[-hhmm] will be processed.

A prune max-runtime of 0 means unlimited.

If period hasn't passed since the previous cleanup run nothing is done. For example a day has passed when midnight is passed (localtime). By default, DragonFly is set up to run hammer cleanup nightly via periodic(8).

The default configuration file will create a daily snapshot, do a daily pruning and reblocking run and a monthly recopy run. Reblocking is defragmentation with a level of 95%, and recopy is full defragmentation.

By default prune and reblock operations are limited to 5 minutes per function, and recopy operations are limited to 10 minutes per function. Reblocking and recopy runs are each broken down into three separate functions (btree, inodes and data) and are thus by default limited to 15 and 30 minutes respectively. Also note that this directive will by default disable snapshots on the following PFS's: /tmp, /var/tmp and /usr/obj.

The defaults may be adjusted by modifying the config file. The pruning and reblocking commands automatically maintain a cyclefile for incremental operation. If you interrupt (^C) the program the cyclefile will be updated, but a sub-command may continue to run in the background for a few seconds until the HAMMER ioctl detects the interrupt. The snapshots PFS option can be set to use another location for the snapshots directory.

Work on this command is still in progress. Expected additions: An ability to remove snapshots dynamically as the file system becomes full.

snapshot [filesystem] snapshot-dir

Takes a snapshot of the file system either explicitly given by filesystem or implicitly derived from the snapshot-dir argument and creates a symlink in the directory provided by snapshot-dir pointing to the snapshot. If snapshot-dir is not a directory, it is assumed to be a format string passed to strftime(3) with the current time as parameter. If snapshot-dir refers to an existing directory, a default format string of "snap-%Y%d%m-%H%M" is assumed and used as name for the newly created symlink.

Snapshot is a per PFS operation, so a HAMMER file system and each PFS in it have to be snapshot separately.

Example, assuming that /mysnapshots is on file system / and that /obj is a file system on its own, the following invocations:

hammer snapshot /mysnapshots

hammer snapshot /mysnapshots/%Y-%m-%d

hammer snapshot /obj /mysnapshots/obj-%Y-%m-%d

would create symlinks similar to:

/mysnapshots/snap-20080627-1210 -> /@@0x10d2cd05b7270d16

/mysnapshots/2008-06-27 -> /@@0x10d2cd05b7270d16

/mysnapshots/obj-2008-06-27 -> /obj@@0x10d2cd05b7270d16

prune softlink-dir

Prune the file system based on previously created snapshot softlinks. Pruning is the act of deleting file system history. The prune command will delete file system history such that the file system state is retained for the given snapshots, and all history after the latest snapshot, but all other history is deleted.

The target directory is expected to contain softlinks pointing to snapshots of the file systems you wish to retain. The directory is scanned non-recursively and the mount points and transaction ids stored in the softlinks are extracted and sorted. The file system is then explicitly pruned according to what is found. Cleaning out portions of the file system is as simple as removing a softlink and then running the prune command.

As a safety measure pruning only occurs if one or more softlinks are found containing the @@ snapshot id extension. Currently the scanned softlink directory must contain softlinks pointing to a single HAMMER mount. The softlinks may specify absolute or relative paths. Softlinks must use 20-character (@@0x%016llx) transaction ids, as might be returned from ``hammer synctid filesystem''.

Pruning is a per PFS operation, so a HAMMER file system and each PFS in it have to be pruned separately.

Note that pruning a file system may not immediately free-up space, though typically some space will be freed if a large number of records are pruned out. The file system must be reblocked to completely recover all available space.

Example, lets say your snapshot directory contains the following links:

lrwxr-xr-x 1 root wheel 29 May 31 17:57 snap1 -> /usr/obj/@@0x10d2cd05b7270d16

lrwxr-xr-x 1 root wheel 29 May 31 17:58 snap2 -> /usr/obj/@@0x10d2cd13f3fde98f

lrwxr-xr-x 1 root wheel 29 May 31 17:59 snap3 -> /usr/obj/@@0x10d2cd222adee364

If you were to run the prune command on this directory, then the HAMMER /usr/obj mount will be pruned to retain the above three snapshots. In addition, history for modifications made to the file system older than the oldest snapshot will be destroyed and history for potentially fine-grained modifications made to the file system more recently than the most recent snapshot will be retained.

If you then delete the snap2 softlink and rerun the prune command, history for modifications pertaining to that snapshot would be destroyed.

prune-everything filesystem

This command will remove all historical records from the file system. This directive is not normally used on a production system.

reblock filesystem [fill_percentage]

reblock-btree filesystem [fill_percentage]

reblock-inodes filesystem [fill_percentage]

reblock-dirs filesystem [fill_percentage]

reblock-data filesystem [fill_percentage]

Attempt to defragment and free space for reuse by reblocking a live HAMMER file system. Big blocks cannot be reused by HAMMER until they are completely free. This command also has the effect of reordering all elements, effectively defragmenting the file system.

The default fill percentage is 100% and will cause the file system to be completely defragmented. All specified element types will be reallocated and rewritten. If you wish to quickly free up space instead try specifying a smaller fill percentage, such as 90% or 80% (the `%' suffix is not needed).

Since this command may rewrite the entire contents of the disk it is best to do it incrementally from a cron(8) job along with the -c cyclefile and -t seconds options to limit the run time. The file system would thus be defragmented over long period of time.

It is recommended that separate invocations be used for each data type. B-tree nodes, inodes, and directories are typically the most important elements needing defragmentation. Data can be defragmented over a longer period of time.

Reblocking is a per PFS operation, so a HAMMER file system and each PFS in it have to be reblocked separately.