From e26e70e6de17b4a0b3282a77bc4733080ba4ec9d Mon Sep 17 00:00:00 2001 From: Thomas Nikolajsen Date: Sun, 28 Sep 2008 22:10:15 +0000 Subject: [PATCH] MFC r1.5 r1.49 r1.40 (HEAD): * 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 | 5 +- sbin/hammer/hammer.8 | 161 +++++++++++++++++++++++++++++++++++----------- sbin/hammer/hammer.c | 4 +- 3 files changed, 127 insertions(+), 43 deletions(-) diff --git a/sbin/hammer/cmd_cleanup.c b/sbin/hammer/cmd_cleanup.c index 8fc1e572e0..bce18eaf08 100644 --- a/sbin/hammer/cmd_cleanup.c +++ b/sbin/hammer/cmd_cleanup.c @@ -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, diff --git a/sbin/hammer/hammer.8 b/sbin/hammer/hammer.8 index c5887bbfb4..7ec6a7d659 100644 --- a/sbin/hammer/hammer.8 +++ b/sbin/hammer/hammer.8 @@ -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 +prune +reblock <1/3 max-runtime> +recopy <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= Set a descriptive label for this file system. .It snapshots= -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 "/snapshots". +PFS masters and will default to +.Pa /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/" be configured for a PFS -slave, where is an appropriate label. You can control snapshot -retention on your slave independant of the master. +It is recommended that +.Pa /var/slaves/ +be configured for a PFS slave, where +.Pa +is the base +.Nm HAMMER +file system, and +.Pa +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 /var/slaves/" -compact +.It Pa snapshots +default per PFS snapshots directory +.It Pa /config +.Nm +.Ar cleanup +configuration file +.It Pa /var/slaves/ +recommended slave PFS snapshots directory +.El .Sh SEE ALSO .Xr undo 1 , .Xr HAMMER 5 , diff --git a/sbin/hammer/hammer.c b/sbin/hammer/hammer.c index 62d38f3dfc..269535dbf3 100644 --- a/sbin/hammer/hammer.c +++ b/sbin/hammer/hammer.c @@ -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 []\n" + "hammer cleanup [ ...]\n" "hammer synctid [quick]\n" "hammer namekey[32] \n" "hammer prune \n" -- 2.11.4.GIT