--- shtool.pod 2001/09/23 10:58:10 1.55
+++ shtool.pod 2001/09/23 11:15:57 1.56
@@ -246,6 +246,10 @@
Fix file permissions inside a source tree by cleaning up the permission bits.
+=item B<rotate>
+
+Rotate a logfile.
+
=item B<tarball>
Roll standardized distribution tarballs.
@@ -525,6 +529,80 @@
shtool fixperm -v *
...
+=item B<rotate> [B<-v>|B<--verbose>] [B<-t>|B<--trace>] [B<-f>|B<--force>] [B<-n>|B<--num-files> I<count>] [B<-s>|B<--min-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<-o>|B<--owner> I<owner>] [B<-g>|B<--group> I<group>] [B<-m>|B<--mode> I<mode>] [B<-M>|B<--migrate> I<cmd>] [B<-P>|B<--prolog> I<cmd>] [B<-E>|B<--epilog> I<cmd>] I<file> [...]
+
+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 archive file
+number I<count>-1; 2. move archive file number I<N>-1 to I<N> for I<N>
+counting from 1 to I<count>-1; 3. move I<file> to archive file number 0;
+4. creating a new and empty instance of I<file>.
+
+Option ``B<-s>'' can be used to only start a rotation step if I<file> is
+at least I<size> bytes long. The argument I<size> can be specified also
+with the trailing units C<K> (kilo), C<M> (mega) or C<G> (giga).
+
+Option ``B<-c>'' changes the approach of moving I<file> to archive file
+number 0: instead of a move followed by the creation of a new I<file>, a
+copy is performed followed by a truncation of I<file>. The difference is
+that in the first case (the default), if an application has I<file>
+still opened, after the rotation step it will have archive file number
+0 opened and usually has to reopen the new I<file>, while in the second
+case the application can keep its open file handles to I<file>. The
+drawback of the second approach is that logfile entries are lost when
+they are written to I<file> between the executation of the copy and the
+subsequent truncation operation.
+
+Option ``B<-r>'' removes I<file> after rotation instead of providing a
+new empty file. Option ``B<-a>'' forces archive files to be created in
+the separate directory I<dir>.
+
+Option ``B<-z>'' enables compression of archive files with compression
+level I<level> (if option ``B<-b>'' is present, compression takes place in
+background). By default, the tools bzip2(1), gzip(1) and compress(1) are
+searched for in C<$PATH> (in this order), but one also can override this
+by prefixing the compression level with one of the three particular tool
+names. Option ``B<-d>'' delays the compression of archive file number 0.
+This is useful if option ``B<-c>'' is not used, because an application
+might still write to archive file 0 (through an open file handle).
+
+Option ``B<-p>'' 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.
+
+Options ``B<-o>'', ``B<-g>'' and ``B<-m>'' can be used to make sure that
+the created files have particular file attributes. The valid arguments
+are the same as for chown(1), chgrp(1) and chmod(1). Be aware that using
+options ``B<-o>'' and ``B<-g>'' require root privileges.
+
+Option ``B<-M>'' allows one to execute a "migration" command just before
+the archive file number I<count>-1 is removed from the filesystem. The
+specified I<cmd> gets the archive filename as an argument appended.
+Options ``B<-P>'' (prolog) and ``B<-E>'' (epilog) can be used to execute
+commands before and after the rotation step. They are interesting in
+conjunction with option ``B<-s>'', because they are not executed at all
+if it is decided that no rotation step is performed.
+
+Option ``B<-f>'' (force) can be used to allow the archive directory
+(option ``B<-a>'') to be silently created if it still does not exist and
+that still not existing intermediate logfiles are silently skipped in
+the rotation step.
+
+Option ``B<-v>'' (verbose) can be used to display the files which are
+rotated. Option ``B<-t>'' (trace) can be used to enable the output of
+the essential shell commands which are executed for the rotation step.
+
+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
+
=item B<tarball> [B<-t>|B<--trace>] [B<-v>|B<--verbose>] [B<-o>|B<--output> I<tarball>] [B<-c>|B<--compress> I<prog>] [B<-u>|B<--user> I<user>] [B<-g>|B<--group> I<group>] [B<-e>|B<--exclude> I<pattern>] I<path> [I<path> ...]
This command is for `rolling' distribution `tarballs', i.e. for the creation
|
