MFC r1.5 r1.49 r1.40 (HEAD):
authorThomas Nikolajsen <thomas@dragonflybsd.org>
Sun, 28 Sep 2008 22:10:15 +0000 (28 22:10 +0000)
committerThomas Nikolajsen <thomas@dragonflybsd.org>
Sun, 28 Sep 2008 22:10:15 +0000 (28 22:10 +0000)
 * Fix `cleanup' usage to match program
 * Expand `cleanup' description
 * Add note that `snapshot' is a per PFS operation
 * Sync recommended path for slave PFS snapshots to program
 * Add `-offset indent' to .Bd where missing
 * Break too long line

sbin/hammer/cmd_cleanup.c
sbin/hammer/hammer.8
sbin/hammer/hammer.c

index 8fc1e57..bce18ea 100644 (file)
@@ -31,7 +31,7 @@
  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  * SUCH DAMAGE.
  * 
- * $DragonFly: src/sbin/hammer/cmd_cleanup.c,v 1.4.2.2 2008/09/25 01:39:33 dillon Exp $
+ * $DragonFly: src/sbin/hammer/cmd_cleanup.c,v 1.4.2.3 2008/09/28 22:10:15 thomas Exp $
  */
 /*
  * Clean up a specific HAMMER filesystem or all HAMMER filesystems.
@@ -289,7 +289,8 @@ do_cleanup(const char *path)
                } else if (strcmp(cmd, "prune") == 0) {
                        if (check_period(snapshots_path, cmd, arg1, &savet)) {
                                if (prune_warning)
-                                       printf("run - WARNING snapshot softlinks present but snapshots disabled\n");
+                                       printf("run - WARNING snapshot softlinks present "
+                                               "but snapshots disabled\n");
                                else
                                        printf("run\n");
                                r = cleanup_prune(path, snapshots_path,
index c5887bb..7ec6a7d 100644 (file)
@@ -30,8 +30,8 @@
 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\" 
-.\" $DragonFly: src/sbin/hammer/hammer.8,v 1.38.2.6 2008/09/25 01:39:33 dillon Exp $
-.Dd July 27, 2008
+.\" $DragonFly: src/sbin/hammer/hammer.8,v 1.38.2.7 2008/09/28 22:10:15 thomas Exp $
+.Dd September 28, 2008
 .Dt HAMMER 8
 .Os
 .Sh NAME
@@ -104,10 +104,6 @@ runs to completion it will delete the cyclefile.
 Specify the volumes making up a
 .Nm HAMMER
 file system.
-.\" .It Fl s Ar linkpath
-.\" When pruning a filesystem you can instruct
-.\" .Nm to create softlinks
-.\" to available snapshots.
 .It Fl i Ar delay
 When maintaining a streaming mirroring this option specifies the
 minimum delay after a batch ends before the next batch is allowed
@@ -182,41 +178,99 @@ Generate the top 32 bits of a
 64 bit directory hash for the specified
 file name.
 .\" ==== cleanup ====
-.It Ar cleanup Op Ar filesystem
+.It Ar cleanup Op Ar filesystem ...
 This is a meta-command which executes snapshot, pruning, and reblocking
-commands on the specified HAMMER filesystem.
-If no filesystem is specified this command will scan all HAMMER and nullfs
+commands on the specified
+.Nm HAMMER
+file system.
+If no
+.Ar filesystem
+is specified this command will clean-up all
+.Nm HAMMER
+file systems in use, including PFS's.
+To do this it will scan all
+.Nm HAMMER
+and
+.Nm null
 mounts, extract PFS id's, and clean-up each PFS found.
 .Pp
-This command will access a
-.Ar snapshots
+This command will by default access a
+.Pa snapshots
 subdirectory and a
-.Ar snapshots/config
-file for each filesystem, creating them if necessary.
-The default configuration file will create a daily snapshot, do a daily
-pruning and reblocking run with a fragmentation level of 95%, and
-a monthly unconditional reblocking run.
+.Pa snapshots/config
+file for each
+.Ar filesystem ,
+creating them if necessary.
+The format of the configuration file is:
+.Bd -literal -offset indent
+snapshots  <period> <retensiontime>
+prune      <period> <max-runtime>
+reblock    <period> <1/3 max-runtime>
+recopy     <period> <1/3 max-runtime>
+
+Defaults are:
+snapshots  1d 60d  # 0 60d  for PFS /tmp, /var/tmp, /usr/obj
+prune      1d 5m
+reblock    1d 5m
+recopy     30d 10m
+.Ed
 .Pp
-All operations are limited to 5 minutes per function by default.
-Reblocking runs are broken down into three separate functions and
-take 15 minutes.  
-Also note that this directive will disable snapshots on
+Time is in seconds, it can be given with a suffix of
+.Cm d ,
+.Cm h ,
+.Cm m
+and
+.Cm s
+meaning day, hour, minute and second.
+A snapshots period of 0 disables snapshot generation and prunes using
+.Ar prune-everything ,
+if no snapshots exists.
+A prune max-runtime of 0 means unlimited.
+.Pp
+It is recommended to run
+.Ar cleanup
+once a day, depending on the configured period,
+from a
+.Xr cron 8
+job.
+For example:
+.Bd -literal -offset indent
+15 2 * * * hammer cleanup >>/var/log/hammer.log 2>&1
+.Ed
+.Pp
+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.
+.Pp
+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 PFSs:
 .Pa /tmp ,
-.Pa /var/tmp ,
+.Pa /var/tmp
 and
-.Pa /usr/obj
-by default.
+.Pa /usr/obj .
 .Pp
-The defaults may be adjusted by modifying the config file.
+The defaults may be adjusted by modifying the
+.Pa config
+file.
 The pruning and reblocking commands automatically maintain a cyclefile
 for incremental operation.
-If you ^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
+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
+.Nm HAMMER
 ioctl detects the interrupt.
+The
+.Ar snapshots
+PFS option can be set to use another location for the snapshots directory.
 .Pp
 Work on this command is still in progress.
 Expected additions:  An ability to remove snapshots dynamically as the
-filesystem becomes full.
+file system becomes full.
 .\" ==== prune ====
 .It Ar prune Ar softlink-dir
 Prune the file system based on previously created snapshot softlinks.
@@ -249,7 +303,7 @@ paths.  Softlinks must use 20-character (@@0x%016llx) transaction ids,
 as might be returned from
 .Dq Nm Ar synctid filesystem .
 .Pp
-Pruning is a per-PFS operation, so a
+Pruning is a per PFS operation, so a
 .Nm HAMMER
 file system and each PFS in it have to be pruned separately.
 .Pp
@@ -259,7 +313,7 @@ pruned out.  The file system must be reblocked to completely recover all
 available space.
 .Pp
 Example, lets say your snapshot directory contains the following links:
-.Bd -literal
+.Bd -literal -offset indent
 lrwxr-xr-x  1 root  wheel  29 May 31 17:57 snap1 ->
 /usr/obj/@@0x10d2cd05b7270d16
 
@@ -310,6 +364,10 @@ If
 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.
 .Pp
+Snapshot is a per PFS operation, so a
+.Nm HAMMER
+file system and each PFS in it have to be snapshot separately.
+.Pp
 Example, assuming that
 .Pa /mysnapshots
 is on file system
@@ -317,7 +375,7 @@ is on file system
 and that
 .Pa /obj
 is a file system on its own, the following invocations:
-.Bd -literal
+.Bd -literal -offset indent
 hammer snapshot /mysnapshots
 
 hammer snapshot /mysnapshots/%Y-%m-%d
@@ -326,7 +384,7 @@ hammer snapshot /obj /mysnapshots/obj-%Y-%m-%d
 .Ed
 .Pp
 would create symlinks similar to:
-.Bd -literal
+.Bd -literal -offset indent
 /mysnapshots/snap-20080627-1210 -> /@@0x10d2cd05b7270d16
 
 /mysnapshots/2008-06-27 -> /@@0x10d2cd05b7270d16
@@ -370,7 +428,7 @@ B-tree nodes, inodes, and directories are typically the most important
 elements needing defragmentation.  Data can be defragmented over a longer
 period of time.
 .Pp
-Reblocking is a per-PFS operation, so a
+Reblocking is a per PFS operation, so a
 .Nm HAMMER
 file system and each PFS in it have to be reblocked separately.
 .\" ==== pfs-status ====
@@ -464,20 +522,34 @@ anywhere else, even on exact copies of the file system.
 .It label=<string>
 Set a descriptive label for this file system.
 .It snapshots=<string>
-Specify the snapshots directory which 'hammer cleanup' will use to manage
+Specify the snapshots directory which
+.Nm
+.Ar cleanup
+will use to manage
 this PFS.  The snapshots directory does not need to be configured for 
-PFS masters and will default to "<fs>/snapshots".
+PFS masters and will default to
+.Pa <pfs>/snapshots .
 .Pp
 PFS slaves are mirroring slaves so you cannot configure a snapshots
 directory on the slave itself to be managed by the slave's machine.
-In fact, the slave will likely have a 'snapshots' sub-directory mirrored
+In fact, the slave will likely have a
+.Pa snapshots
+sub-directory mirrored
 from the master, but that directory contains the configuration the master
-is using for its copy of the filesystem, not the configuration that we
+is using for its copy of the file system, not the configuration that we
 want to use for our slave.
 .Pp
-It is recommended that "/var/slaves/<name>" be configured for a PFS
-slave, where <name> is an appropriate label.  You can control snapshot
-retention on your slave independant of the master. 
+It is recommended that
+.Pa <fs>/var/slaves/<name>
+be configured for a PFS slave, where
+.Pa <fs>
+is the base
+.Nm HAMMER
+file system, and
+.Pa <name>
+is an appropriate label.
+You can control snapshot
+retention on your slave independent of the master. 
 .It snapshots-clear
 Zero out the snapshots directory path for this PFS.
 .El
@@ -606,6 +678,17 @@ directive requires that the target be configured as a slave and that the
 field of the mirroring source and target match.
 .Sh DIAGNOSTICS
 .Ex -std
+.Sh FILES
+.Bl -tag -width ".It Pa <fs>/var/slaves/<name>" -compact
+.It Pa snapshots
+default per PFS snapshots directory
+.It Pa <snapshots>/config
+.Nm
+.Ar cleanup
+configuration file
+.It Pa <fs>/var/slaves/<name>
+recommended slave PFS snapshots directory
+.El
 .Sh SEE ALSO
 .Xr undo 1 ,
 .Xr HAMMER 5 ,
index 62d38f3..269535d 100644 (file)
@@ -31,7 +31,7 @@
  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  * SUCH DAMAGE.
  * 
- * $DragonFly: src/sbin/hammer/hammer.c,v 1.33.2.4 2008/09/25 01:39:33 dillon Exp $
+ * $DragonFly: src/sbin/hammer/hammer.c,v 1.33.2.5 2008/09/28 22:10:15 thomas Exp $
  */
 
 #include "hammer.h"
@@ -305,7 +305,7 @@ usage(int exit_code)
        fprintf(stderr, 
                "hammer -h\n"
                "hammer [-v] [-t seconds] [-c cyclefile] command [argument ...]\n"
-               "hammer cleanup [<filesystem>]\n"
+               "hammer cleanup [<filesystem> ...]\n"
                "hammer synctid <filesystem> [quick]\n"
                "hammer namekey[32] <path>\n"
                "hammer prune <softlink-dir>\n"