--- sh.rotate 2004/01/01 16:54:20 1.9
+++ sh.rotate 2004/02/12 16:06:27 1.10
@@ -1,7 +1,6 @@
##
## rotate -- Logfile rotation
## Copyright (c) 2001-2004 Ralf S. Engelschall <rse@engelschall.com>
-## Originally written for use in OpenPKG
##
## This file is part of shtool and free software; you can redistribute
## it and/or modify it under the terms of the GNU General Public
@@ -20,7 +19,7 @@
##
str_tool="rotate"
-str_usage="[-v|--verbose] [-t|--trace] [-f|--force] [-n|--num-files <count>] [-s|--size <size>] [-c|--copy] [-r|--remove] [-a|--archive-dir <dir>] [-z|--compress [<tool>:]<level>] [-b|--background] [-d|--delay] [-p|--pad <len>] [-o|--owner <owner>] [-g|--group <group>] [-m|--mode <mode>] [-M|--migrate <cmd>] [-P|--prolog <cmd>] [-E|--epilog <cmd>] <file> [...]"
+str_usage="[-v|--verbose] [-t|--trace] [-f|--force] [-n|--num-files <count>] [-s|--size <size>] [-c|--copy] [-r|--remove] [-a|--archive-dir <dir>] [-z|--compress [<tool>:]<level>] [-b|--background] [-d|--delay] [-p|--pad <len>] [-m|--mode <mode>] [-o|--owner <owner>] [-g|--group <group>] [-M|--migrate <cmd>] [-P|--prolog <cmd>] [-E|--epilog <cmd>] <file> [...]"
arg_spec="1+"
opt_spec="v.t.f.n:s:c.r.a:z:b.d.p:o:g:m:M:P:E:"
opt_alias="v:verbose,t:trace,f:force,n:num-files,s:size,c:copy,r:remove,a:archive-dir,z:compress,b:background,d:delay,p:pad,o:owner,g:group,m:mode,M:migrate,P:prolog,E:epilog"
@@ -400,3 +399,192 @@
fi
done
+shtool_exit 0
+
+##
+## manual page
+##
+
+=pod
+
+=head1 NAME
+
+B<shtool rotate> - B<GNU shtool> log file rotation
+
+=head1 SYNOPSIS
+
+B<shtool rotate>
+[B<-v>|B<--verbose>]
+[B<-t>|B<--trace>]
+[B<-f>|B<--force>]
+[B<-n>|B<--num-files> I<count>]
+[B<-s>|B<--size> I<size>]
+[B<-c>|B<--copy>]
+[B<-r>|B<--remove>]
+[B<-a>|B<--archive-dir> I<dir>]
+[B<-z>|B<--compress> [I<tool>:]I<level>]
+[B<-b>|B<--background>]
+[B<-d>|B<--delay>]
+[B<-p>|B<--pad> I<len>]
+[B<-m>|B<--mode> I<mode>]
+[B<-o>|B<--owner> I<owner>]
+[B<-g>|B<--group> I<group>]
+[B<-M>|B<--migrate> I<cmd>]
+[B<-P>|B<--prolog> I<cmd>]
+[B<-E>|B<--epilog> I<cmd>]
+I<file> [I<file> ...]
+
+=head1 DESCRIPTION
+
+This command rotates a logfile I<file> by subsequently creating up to
+I<count> (optionally compressed) archive files of it. Archive files are
+named "I<file>.I<number>[I<compress-suffix]>" where I<number> is the
+version number, 0 being the newest and "I<count>-1" the oldest.
+
+A rotation step consists of the following steps
+
+1. remove last archive file
+2. shift archive file numbers
+3. create archive file 0 from I<file>
+4. truncate/recreate I<file>
+
+=head1 OPTIONS
+
+The following command line options are available.
+
+=over 4
+
+=item B<-v>, B<--verbose>
+
+Display some processing information.
+
+=item B<-t>, B<--trace>
+
+Enable the output of the essential shell commands which are executed.
+
+=item B<-f>, B<--force>
+
+Force silent creation of archive directory if it does not exists. Also
+skip missing intermediate logfiles in the rotation step. Default is to
+exit with error in both cases. FIXME
+
+=item B<-n>, B<--num-files> I<count>
+
+Create I<count> archive files. Default is 10.
+
+=item B<-s>, B<--size> I<size>
+
+Only rotate if logfile exceeds I<size>. The argument I<size> can be
+specified also with the trailing units C<K> (kilo), C<M> (mega) or C<G>
+(giga). The "prolog" and "epilog" are only executed if rotation actually
+takes place.
+
+=item B<-c>, B<--copy>
+
+Copy I<file> to archive then truncate original. The default is to move
+I<file> to archive.
+
+Unless an application reopens its logfile it will continue to write
+to the same file. In the default move case the application will write
+to the archive which it had previously opened as I<file>. In the copy
+case the application will write to the original I<file>. The drawback
+of the copy approach is that logfile entries are lost when they are
+written to I<file> between the execution of the copy and the truncation
+operation. The drawback of the move approach is that the application
+needs to detect the move or must be triggered to reopen its log (i.e.
+through epilog).
+
+=item B<-r>, B<--remove>
+
+Removes I<file> after rotation instead of providing a new empty file.
+
+=item B<-a>, B<--archive-dir> I<dir>
+
+Specify the archive directory. Default is to create archives in the same
+directory as I<file> is located.
+
+=item B<-z>, B<--compress> [I<tool>:]I<level>
+
+Enables compression of archive files with compression level I<level> By
+default, the tools bzip2(1), gzip(1) and compress(1) are searched for in
+C<$PATH>, but one also can override this by prefixing the compression
+level with one of the three particular tool names.
+
+=item B<-b>, B<--background>
+
+Enable background compression.
+
+=item B<-d>, B<--delay>
+
+Delays the compression of archive file number 0. This is useful if
+``B<-c>'' is not used, because an application might continue to write to
+archive file 0 through an already open file handle.
+
+=item B<-p>, B<--pad> I<len>
+
+Enables padding with leading zeros in the I<number> part of the filename
+"I<file>.I<number>I<compress-suffix>". The default padding I<len> is 1.
+This is interesting if more than 10 archive files are used, because it
+leads to still sorted directory listings.
+
+=item B<-m>, B<--mode> I<mode>
+
+The file mode applied to the created files, see chmod(1). Setting mode to
+C<-> skips this step and leaves the operating system default which is
+usually based on umask(1). Some file modes require superuser privileges
+to be set. Default is 0755.
+
+=item B<-o>, B<--owner> I<owner>
+
+The file owner name or id applied to the created files, see chown(1). This
+option requires superuser privileges to execute. Default is to skip this
+step and leave the operating system default which is usually based on
+the executing uid or the parent setuid directory.
+
+=item B<-g>, B<--group> I<group>
+
+The file group name or id applied to the created files, see chgrp(1). This
+option requires superuser privileges to execute to the fullest extend,
+otherwise the choice of I<group> is limited on most operating systems.
+Default is to skip this step and leave the operating system default
+which is usually based on the executing gid or the parent setgid
+directory.
+
+=item B<-M>, B<--migrate> I<cmd>
+
+Execute a "migration" command just before the archive file number
+I<count>-1 is removed from the filesystem. The specified I<cmd> receives
+the archive filename as command line argument.
+
+=item B<-P>, B<--prolog> I<cmd>
+
+Execute a "prolog" command before the rotation step. Useful in
+conjunction with B<-s>.
+
+=item B<-E>, B<--epilog> I<cmd>
+
+Execute a "epilog" command after the rotation step. Useful in
+conjunction with B<-s>.
+
+=back
+
+=head1 EXAMPLE
+
+ # shell script
+ shtool rotate -n10 -s1M -zbzip2:9 -d -r /var/log/ap.access.log
+ shtool rotate -n5 -s128K -zbzip2:9 -d -r /var/log/ap.error.log
+ apachectl graceful
+
+=head1 HISTORY
+
+The B<GNU shtool> B<rotate> command was originally written by Ralf S.
+Engelschall E<lt>rse@engelschall.comE<gt> in 2001 for B<GNU shtool>.
+Its development was prompted by the need to have a flexible
+logfile rotation facility in the B<OpenPKG> project.
+
+=head1 SEE ALSO
+
+shtool(1), BSD newsyslog(8).
+
+=cut
+
|
