Index: ossp-pkg/shtool/sh.rotate RCS File: /v/ossp/cvs/ossp-pkg/shtool/sh.rotate,v rcsdiff -q -kk '-r1.9' '-r1.10' -u '/v/ossp/cvs/ossp-pkg/shtool/sh.rotate,v' 2>/dev/null --- 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 -## 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 ] [-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 ] [...]" +str_usage="[-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 ] [-m|--mode ] [-o|--owner ] [-g|--group ] [-M|--migrate ] [-P|--prolog ] [-E|--epilog ] [...]" 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 - B log file rotation + +=head1 SYNOPSIS + +B +[B<-v>|B<--verbose>] +[B<-t>|B<--trace>] +[B<-f>|B<--force>] +[B<-n>|B<--num-files> I] +[B<-s>|B<--size> I] +[B<-c>|B<--copy>] +[B<-r>|B<--remove>] +[B<-a>|B<--archive-dir> I] +[B<-z>|B<--compress> [I:]I] +[B<-b>|B<--background>] +[B<-d>|B<--delay>] +[B<-p>|B<--pad> I] +[B<-m>|B<--mode> I] +[B<-o>|B<--owner> I] +[B<-g>|B<--group> I] +[B<-M>|B<--migrate> I] +[B<-P>|B<--prolog> I] +[B<-E>|B<--epilog> I] +I [I ...] + +=head1 DESCRIPTION + +This command rotates a logfile I by subsequently creating up to +I (optionally compressed) archive files of it. Archive files are +named "I.I[I" where I is the +version number, 0 being the newest and "I-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 +4. truncate/recreate I + +=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 + +Create I archive files. Default is 10. + +=item B<-s>, B<--size> I + +Only rotate if logfile exceeds I. The argument I can be +specified also with the trailing units C (kilo), C (mega) or C +(giga). The "prolog" and "epilog" are only executed if rotation actually +takes place. + +=item B<-c>, B<--copy> + +Copy I to archive then truncate original. The default is to move +I 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. In the copy +case the application will write to the original I. The drawback +of the copy approach is that logfile entries are lost when they are +written to I 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 after rotation instead of providing a new empty file. + +=item B<-a>, B<--archive-dir> I + +Specify the archive directory. Default is to create archives in the same +directory as I is located. + +=item B<-z>, B<--compress> [I:]I + +Enables compression of archive files with compression level I 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 + +Enables padding with leading zeros in the I part of the filename +"I.II". The default padding I 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 + +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 + +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 + +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 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 + +Execute a "migration" command just before the archive file number +I-1 is removed from the filesystem. The specified I receives +the archive filename as command line argument. + +=item B<-P>, B<--prolog> I + +Execute a "prolog" command before the rotation step. Useful in +conjunction with B<-s>. + +=item B<-E>, B<--epilog> I + +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 B command was originally written by Ralf S. +Engelschall Erse@engelschall.comE in 2001 for B. +Its development was prompted by the need to have a flexible +logfile rotation facility in the B project. + +=head1 SEE ALSO + +shtool(1), BSD newsyslog(8). + +=cut +