\input texinfo   @c -*-texinfo-*-
@setfilename rottlog.info
@settitle GNU Rot[t]log version @value{VERSION} 


@copying
GNU rottlog
Copyright @copyright{} 2002, 2003, 2004, 2005 Stefano Falsetto
Copyright @copyright{} 2008, 2009 David Egan Evans

@quotation
Permission is granted to copy, distribute or modify this document (or
both) under the terms of the GNU Free Documentation License, Version 1.3,
or any later version published by the Free Software Foundation; with
no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled ``GNU Free
Documentation License.''
@end quotation
@end copying

@paragraphindent none

@iftex
@parskip = 0.5@normalbaselineskip plus 3pt minus 1pt
@end iftex

@set lq ``
@set rq ''

@headings off
@everyheading GNU Rot[t]log @| @| 
@everyfooting December 2009 @| @thispage @| GNU Rot[t]log

@node Top

@chapter GNU Rot[t]log
@include vers_rott8.texi
This is the GNU Rot[t]log info manual version @value{VERSION}
GNU Rot[t]log is the GNU log management utility. It was originally
authored in 2000 by Stefano Falsetto to rotate his logs. It has similar
syntax to Red Hat's logrotate(8), and is written in @b{bash.}

GNU Rot[t]log is designed to simplify administration of systems that
generate large numbers of log files. It allows automatic rotation,
compression, and archiving of logs. It also mails reports to the system
administrator. Each log file may be handled daily, weekly, monthly,
in user-defined days, or when it becomes too large.

Normally, rottlog is run as a daily cron job. The logfiles cannot be
modified multiple times per period unless the @code{-f} or @code{--force}
option is used.

@ifnottex
@menu
* Synopsis and Options::	    Command line options and description
* Mandatory RC Variables::          Variables that must be defined
* Optional RC Variables::           Variables that can be defined
* Global period file structure::    The global structure of confguration files
* Configuration parameters::        All the commands used by GNU Rot[t]log
* Use of meta-variables::           How to use meta-variables
* RC File Examples::                Examples of the master rc file
* Period Related File Examples::    Examples of period related files
* Files::			    Files used by rottlog
* Bugs::                            Information on submitting bug reports
* GNU Free Documentation License::  The license for this documentation.
* Index of Variables and Commands::
* Index of meta-variables:: 
* Index of concepts::

@end menu
@end ifnottex

Version @value{VERSION}

@node Synopsis and Options

@section Synopsis and Options
@b{rottlog [options]}

@table @code
@item --checkrc @var{<rcfile>},@var{<rcfile>},... 
Check syntax of specified configuration file(s). @var{<rcfile>} must be 
one, or more, of: @i{daily, weekly, monthly, all}.

@item --help
Display help page and exit.

@item --version
Display version, disclaimer, and exit.

@item -d
Display default options that are assumed, even if not explicitly
used, and exit. 

@item -l @var{logfile}
Show contents of archived @var{logfile} with default pager.  @var{logfile}
can be an absolute, or relative, filename. If @var{logfile} is a relative
filename, it will be searched in @code{$packdir} directory.

@item -p @var{program}"
Use @var{program} for paging output of showlog. Useful only 
with @code{--showlog}.  rottlog relies on system @var{pager} 
variable by default.

@item -s @var{logfile}
Display a summary of syntax statistics about @var{logfile}. 
It is like @code{--checkrc} but more verbose.

@item -f @code{[<daily>]} @code{[<weekly>]} @code{[<monthly>]}
Force rotation and archiving of logfiles, even if unnecessary.  This might
be useful after adding new entries to a configuration file. If daily,
weekly, or monthly is not used, the program will force rotation and
archiving of all entries in all config files.  Using @code{--force}
option will force rotation and archiving of specified config file, and
will check for rotation and archiving of remaining config files
that follows in time.

@item -v
rottlog STDERR verbosity.  Remember that crontab sends its default output
via email.

@end table

@node Mandatory RC Variables
@section Mandatory RC Variables

The main config file is named @code{rc} and is the first file read by rottlog. 
Each line can be defined with a variable and default value,
@code{variable=value}.  Some variables do not need a value,
@code{variable}.  Variables are split in two categories: mandatory and
optional.  @code{rc} can be overridden by "period-related" config files.

Comments may appear anywhere in the config file as long as the first
non-whitespace character on the line is a @code{#}.
Example:
@example
  # This is a valid comment
  logpart 100b # This is an INVALID comment
@end example

Following are the mandatory variables needed to make rottlog to work:
@display
  compress=<options>
  extension=<ext>
  fromuser=<sender address>
  mail=<mailer prg> (1)
  maxdepth=<depth>
  nomail (1)
  packdir=<archive-dir>
  packer=<absolute-filename>
  pager=<pager-program>
  touser=<receiver address>
  uncompress=<options>
  unpacker=<absolute-filename>

  (1) Can't be used together
@end display
Where:

@vtable @code

@item compress=<options>
This variable defines options to be used with the packer program to compress data

@strong{IMPORTANT:} 
The packer program sends output to STDOUT, (ie for gzip/bzip2 use @code{-c} flag).

@item extension=<ext>
This variable is used to expand meta-variable @var{@@COMP_EXT},
gz for gzip, bz2 for bzip2, etc.

@item fromuser=<sender address>
Default FROM: address in mail messages sent after each rotation.

@item mail=<mailer prg>
Mail program to send messages.
Example:
@display
 - for sendmail use: @code{mail="sendmail -t"}
 - for qmail use: @code{mail="qmail-inject -h"}
@end display

@item maxdepth=<depth>
Default maximum depth to search for files when using * glob in log
filename definition block.

@item nomail
Don't mail rottlog's activity report. This variable is used if the 'mail'
option won't be used.

@item packdir=<archive-dir>
Default basedir to store rotated and archived files.
This variable is used to expand @var{@@DEF_DIR} meta-variable.

@item packer=<absolute-filename>
Complete filename to be used for compressed logs.

@item pager=<pager-program>
Filename of program to use with @code{--showlog} parameter. It's
used in a pipe, so it must be a program able to read from STDIN.
The @code{--showlog} option will not be available if this variable is
not defined, and each time rottlog is called, a warning message will
be printed.

@item touser=<receiver address>
Recipient address of mail messages sent by "fromuser".

@item uncompress=<options>
Options to be used with unpacker program.

@strong{IMPORTANT:}
Unpacker program must output data to STDOUT. (For gunzip/bunzip2 use -c.)

@item unpacker=<complete-filename>
Complete filename to be used for uncompressed logs.

@end vtable

@node Optional RC Variables
@section Optional RC Variables

Following are optional variables:

@display
  createdir
  default_storefile=<storefile>
  dir_grp=<group>
  dir_own=<owner>
  dir_perm=<permissions>
  follow_symlinks
  ifempty
  maxage=<days>
  missingok
  nocompress
  nocreate
  nomissingok
  notifempty
  remove_missing
  SunMon=<sun|mon>
  tabooext=<list>
@end display

Where:

@ftable @code
@item createdir
Create directories specified in storedir if needed. It's useful to use
with meta-vars.
@xref{Use of meta-variables}.

@item default_storefile=<storefile>
Default filename to use with archived androtated logfiles. It's useful
to use with meta-vars. 
@xref{Use of meta-variables}.

@strong{WARNING:}
Time-related meta-vars are NOT compatible with rotate parameter.

If @code{default_storefile} is defined using @var{@@WEEK}, @var{@@DAY},
@var{@@MONTH}, or @var{@@YEAR} meta-variables, each config file containing 
a logfile to be rotated will not be valid.

@item dir_grp=<group>
Default group of newly created directory. Must exist in @code{/etc/group}
file.  Use with createdir option.  

@item dir_own=<owner>
Default owner of newly created directory. Must exist in @code{/etc/passwd}
file.  Used with createdir option. 

@item dir_perm=<permissions>
Default permission of newly created directory. Only numeric notation
is permitted.  Used with createdir option.  

@item follow_symlinks
Follow symlinks to logfiles. Default behaviour is to not follow
symlinks.

@item ifempty
Rotate logfiles even if they are empty.

@item maxage
Remove archived logs older than <days> days. The age is only checked
if the logfile is to be managed.

@item missingok
If a logfile is missing, go to the next one without issuing an
error message. Last action, if defined, will be performed.  Post rotate
script, if defined, will not be performed.  

@item nocompress
Don't compress logfiles to be archived and rotated.

@item nocreate
Don't create a new filename. Can't be used with logpart option.  

@item nomissingok
rottlog will return an error message and stop execution
if the a file is missing.

@item notifempty
Do not rotate a logfile if it is empty.

@item remove_missing
rottlog will stop execution if a delayed file no longer exists
or is not readable.

@item SunMon=<sun|mon>
Use Sunday or Monday as first day of week.
This option is useful only in conjunction with @@WEEK meta-variable.

@item tabooext=<list>
The list of files expanded with * glob will not include
files with extensions contained in <list>. If a + precedes this 
list of extensions, the current taboo extension list is augmented, 
otherwise it is replaced. At startup, the taboo extension list 
contains: .new .rpmorig, .rpmsave, ,v, .swp, .rpmnew, and ~.

@end ftable

@node Global period file structure

@section Global period file structure

Global structure of a period-config file is:

@example
out-of-block-definitions

configuration-block-1-start @{
  block-contents
@}

configuration-block-2-start @{
  block-contents
@}
@end example

Comments may appear anywhere in the config file as long as the first
non-whitespace character on the line is a #.

At the beginning of all the period related config files (exactly before,
and out of, all configuration blocks) all options from the main rc config
file can be used.  So it can define period-related default values and
override its values inside per-logfile block definitions.

Here is another out-of-block definition:

@example
include CONFIGFILE[,CONFIGFILE,...]
@end example

This option includes specified files as if they were written at
the end of configuration file.  Nested includes are not supported.
The @var{configfile} must be an absolute filename, or a filename with the
@code{*} wildcard.  To include all files in a directory, the search path
must be used @code{path-to-dir/*} (i.e. @code{/etc/rottlog/monthly.d/*}).
If this line is too long, a @code{\} character can be inserted at
the end of the line, continuing on the following line.  

A @code{configuration-block-n-start} is a list of one, or more,
comma separated filenames to be archived, or rotated.  A configuration
block for a set of filenames, all stored in a single dir, can be used:
@code{path-to-dir/*} (i.e. @code{/var/adm/apachelogs/*}).  If a filename
contains special characters like @code{]} or @code{@@@{} you must protect
them from expansion with a double slash (i.e. apache\\[1\\].log).  If the
same logfile is used more than one time in the same configuration file,
it will be used in only the first defined block.

All expanded filenames will be checked to not have an extension
contained in the @var{def_taboo_ext} variable. @xref{tabooext}.

@node Configuration parameters

@section Configuration parameters

A configuration block can include one or more of following keywords:
@display
append-only
collate logfile
create mode owner group
createdir [<perms>] [<own> <grp>]
create_logrotate
delaycompress
dateext
dateoffset
day_based
firstaction ... endaction
ifempty
lastaction ... endaction
logpart <qdldl>
log_rotate
mailopt <what>
maxage <days>
maxdepth <depth>
missingok
month_based
nocompress
nocreate
nomail
nosharedscripts
nostoredir
notifempty
period <period-definitions>
postrotate ... endscript
prerotate ... endscript
rotate number
sharedscripts
size num[b,k,M]
start <number>
storedir <dirname>
storefile <filename>
tabooext <list>
tarcollate <logfile>
touser <email address>
week_based
year_based
@end display
Where:

@vtable @code
@item append-only

To be used only on ext[23] fs.  Set append only attribute to a logfile.
(More precisely: remove this attribute before handling log, and reset
it after all operations are preformed).

@item collate

Store more than one logfile in one compressed file.  This option makes
possible to weekly rotate a logfile (i.e. in a small volume), and monthly
store a compressed file containing previously rotated files (i.e. in a
bigger backup volume).

If used in monthly configuration file, @var{logfile} will be searched
in weekly configuration file.  If used in weekly configuration
file, @var{logfile} will be searched in daily configuration file.
This parameter can't be used in daily configuration file.

Logfiles to be referenced with collate option must use rotate option with
correct periods:

- collate monthly a weekly rotated file : rotate 4

- collate weekly a daily rotated file   : rotate 7

Example: Collect monthly a weekly rotated log.daemon

In weekly configuration file:
@example
  /var/adm/log.daemon @{
    storedir /mnt/tiny/@@YEAR/@@BASENAME
    createdir 4700 stefano root
    create 600 stefano root
    prerotate
        /sbin/killall -HUP syslogd
    endscript
    # Important!
    rotate 4
    delaycompress
  @}
@end example

In monthly configuration file:
@example
  /var/adm/log.daemon @{
    storedir /mnt/BigVolume/Collections/@@YEAR/@@BASENAME
    createdir
    collate
  @}
@end example

In /mnt/BigVolume/Collections/2002/log.daemon will be stored a file called
log.daemon.<number> containing log.daemon.1, log.daemon.2, log.daemon.3
and log.daemon.4 weekly created in the /mnt/tiny/2002/log.daemon dir.

This option is compatible only with following:
@display
- [no]storedir
- storefile
- createdir
- [no]missingok (TODO)
- firstaction/lastaction
- prerotate/postrotate
- nocompress
 touser
- nomail
- ifempty/notifempty are silently ignored.
@end display

@item create [[@var{mode}] [@var{owner} @var{group}]]

Immediately after rotation, and before the postrotate script is run,
the log file is created with the same name as the log file just rotated.
@var{mode} specifies the mode for the log file in octal notation (the
same as chmod(2)), @var{owner} specifies the user name who will own the
log file, and group specifies the @var{group} the log file will belong to.

If none of the three parameters are specified, and @code{create_logrotate}
is set to 0 (or undef), the new file will be created with permissions
and owner defined in default variables @code{fil_perm}, @code{fil_own},
and @code{fil_grp}. You can specify @var{mode} only, or @var{mode}
and @var{owner}, but you can't specify @var{mode} and @var{group}
(second parameter is always interpreted as owner).  If none of the three
parameters are specified, and @code{create_logrotate} is set to 1, the
new file will be created with permissions and owner of old logfile.

@item createdir [@var{perms}] [@var{own grp}]

Create (if needed) a directory to store archived or rotated logs with
specified permissions and owner:group. If none of the three parameters is
specified the directory will be created with permissions and owner defined
in default variables @var{dir_perm}, @var{dir_own}, and @var{dir_grp}.
You can specify @var{perms} only, or @var{perms} and @var{own}, but
you can't specify @var{perms} and @var{grp} (second parameter is always
interpreted as owner).  @var{perms} specifies the mode for the log file
in octal notation (the same as chmod(2)).

@strong{IMPORTANT:}
If directory hierarchy to be created is deeper than one directory,
only the last directory will have the owner and permissions expected.
Example:
@example
  storedir 2002/04/apache_logs
  createdir 4300 rottlog
@end example

If dir 2002 is not already present on your box you will have (assuming
that rottlog is run by user stefano):
@example
$ ls -od 2002 2002/04 2002/04/apache_logs
drwxr-xr-x  2 stefano 1024 Apr 11 18:35 2002/
drwxr-xr-x  2 stefano 1024 Apr 11 18:35 2002/04
d-ws------  2 rottlog 1024 Apr 11 18:35 2002/04/apache_logs
@end example

@item create_logrtate

Create a new 0-size file with permission of just-rotated logfile. This is
a parameter used for compatibility with logrotate. @strong{IMPORTANT:} 
it needs @code{create}.

@item delaycompress

Postpone compression of the previous log file until the next rotation
cycle.  It can be used when some program can not be told to close its
logfile and thus might continue writing to the previous log file for
some time.

@item dateext

Archive old versions of log files, adding a daily extension, like
YYYYMMDD, instead of simply adding a number. This is a shortcut for:
@code{storefile @@BASENAME.@@NEXT_EXT-@@YEAR@@MONTH@@DAY}

@item dateoffset @var{<+/-day>}

Force time related metavariables to be calculed with <day> days of
offset.  Example: if today is 5 August, and "dateoffset -1" is used,
the @@DAY metavariable will be expanded as 04, not 05.

@item day_based
Force @code{@@NEXT_EXT} generation to be on a daily basis. This is
useful only if @code{@@DAY} metavariable is used in storefile.  See
@xref{month_based}.

@item firstaction @var{EXIT_CODE}... endaction

The unique line between firstaction and endaction (both of which must
appear on lines by themselves) are executed before any operation. It
will be performed during parameter parsing, before filename and
metavars expansion.  Optional parameter @var{EXIT_CODE} is the default
exit code expected at the action. If not specified 0 will be expected.
If used in a multiple files definition, the action will be run only one
time, before processing the first file.

@item ifempty

Rotate the log file even if it is empty.

@item lastaction @var{EXIT_CODE}... endaction

The unique line between lastaction and endaction (both of which must
appear on lines by themselves) are executed after all operations. It
will be performed just before handling the next logfile.  Optional
parameter @var{EXIT_CODE} is the default exit code expected by the
action.  If not specified 0 will be expected.

If used to define multiple files, the action will be run only one
time, after processing all files.

@item logpart @var{qdldl}

Leave a part of log to archive/rotate in new logfile.
@var{qdldl} can be:

@display
<number>l
<number>b
"<regexp>"
"<#1 day>"
@end display

where @code{l} and @code{b} stands for lines and bytes respectively.
@code{regexp} is a regular expression used by grep to find the first
line to leave in log.
@code{"#1 day"} is a shortcut to a regexp corresponding to the first
day of the current month.

@item log_rotate

Allows rottlog to use a different algorithm to rotate logs. In
particular it will use the logrotate algorithm. This is a parameter
used for compatibility with logrotate.

@item mailopt @var{what}

Allows rottlog to send detailed mail messages.
@var{what} can be a valid combination of:

@multitable {maillast|overwrite|over} {@result{}} {AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA}
@item all|a                   @tab @result{} @tab Mail all sorts of information
@item maillast|overwrite|over @tab @result{} @tab Attach to-be-overwrited files to mail in plain text
@item ziplast|zip             @tab @result{} @tab Attach to-be-overwrited files to mail in compressed format              
@item error|err               @tab @result{} @tab Mail only error messages
@item none|nomail             @tab @result{} @tab Don't mail anything
@end multitable

@item maxage @var{<days>}
Remove archived logs older than <days> days. The age is only checked
if the logfile is to be managed.  If maxage is used without <days>,
the default is 365 days.

@item maxdepth @var{<depth>}

Default maximum depth to search for files when using the * metachar in
log filename definition.

@item missingok

If the log file is missing, go on to the next one without issuing an
error message. Default behaviour is to stop executing and return an
error exit code.

@item month_based
@anchor{month_based} 
Force @code{@@NEXT_EXT} generation to be on a monthly basis.  This is
useful only if the @code{@@MONTH} metavariable is used in storefile.

Example:
@example
$ date
Fri Feb 25 14:34:04 CET 2005
$ ls
apache.log-2005-01.1
apache.log-2004-02.1
apache.log-2004-08.1
$ rottlog
$ ls
apache.log-2005-01.1
apache.log-2004-02.1
apache.log-2004-08.1
apache.log-2005-02.2
@end example
In the above example, month_based is used to order apache.log 
files on a month basis:
@example
$ ls *-02*
apache.log-2004-02.1
apache.log-2005-02.2
@end example

@item nocompress

Old versions of log files are not compressed with packer defined in
rc file.

@item nocreate

Don't create a new logfile. Can't be used with logpart.

@item nomail

Don't send notification email message.

@item nosharedscripts

Run prerotate and postrotate scripts for every script which is 
rotated (this is the default, and overrides the sharedscripts option).

@item nostoredir

Logs are rotated/archived in the same directory the log normally
resides in.

@item notifempty

Do not rotate the log if it is empty.

@item period @var{period-definitions}

@strong{WARNING: This option can be used only in custom configuration file.}

This is a very powerful option able to force an action on the time
interval specified.  This is useful when a system administrator must
force rotation of some logfiles in times different from the canonical
monthly, weekly, and daily.

@var{period-definitions} is a comma-separated list of items defining
a day, or a set of days, a month, or a set of months, and so on.
Usable items can be:

@multitable {<monthname>} {@result{}} {AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA}
@item DD                @tab @result{} @tab Each DDth day of the month      
@item DDd               @tab @result{} @tab Each DD days
@item WWw               @tab @result{} @tab Each WW weeks
@item mmM               @tab @result{} @tab Each mm months
@item <weekday>         @tab @result{} @tab Each <weekday> of the week
@item <monthname>       @tab @result{} @tab Each <monthname> of the year
@item HH:MM             @tab @result{} @tab At specified hour and minutes (*)
@item 0                 @tab @result{} @tab Each time rottlog is called (*)
@end multitable
(*) It depends on rottlog's entries in crontab

Where
@display
<weekday> can be short:
    mon, tue, wed, thu, fri, sat, sun
 or long:
    monday, tuesday, wednesday, thursday, friday,
    saturday, sunday

<monthname> can be short:
    jan, feb, mar, apr, may, jun, jul, aug, sep,
    oct, nov, dec
 or long:
    january, february, march, april, may, june,
    july, august, september, october, november,
    december
@end display

Following characters can add use of logical functions and ranges:

@multitable {AAAAAAAAAAAAAAAAAAAA} {@result{}} {AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA}
@item , (comma)                 @tab @result{} @tab OR
@item " " (white space)         @tab @result{} @tab AND
@item ! (exclamation mark)      @tab @result{} @tab NOT
@item - (minus)                 @tab @result{} @tab Week or month range
@item + (plus)                  @tab @result{} @tab Week or month list (Inlined OR)
@end multitable

Minus character can be used to define a range of days or months,
can't use long and short mixed range definitions, (i.e. it's
valid to use sep-dec but not september-dec).

While the minus character is used to define a range of days or months,
plus char can be used to define a list of days or months. In fact it
can be used as a shortcut to comma.  See below for more information.

The NOT operator must be used before an operator to negate. In a
range, or list, a not operator can only be used before its
definition. (i.e. it's valid to write @code{!mon-thu}, but it's not
valid to write @code{mon-!thu}.  It's valid to write
@code{!mon+fri+sat}, but it's not valid to write @code{mon+!fri+sat})

Comma-separated tokens are analyzed in the given order. When one
meets a true condition, the check is stopped without continuing to
parse further.

@strong{WARNING: Correct behaviour of rottlog with period parameter strictly depends from correct configuration of rottlog's crontab.}

Some examples:
@example
1) period mon-wed 21:00,sat 10:00
@end example
Is equivalent to:
@example
   period mon 21:00,tue 21:00,wed 21:00,sat 10:00
@end example

This means that rotation must be performed if rottlog is run and today
is Monday and it is 21:00 hours, or today is Tuesday and it is 21:00
hours, and so on with Wednesday, or today is saturday and it is
10:00 hours.

@example
2) period !mon-wed 21:00,wed 19:00
@end example
Is equivalent to:
@example
   period !mon !tue !wed 21:00,mon 19:00
@end example

This means that rotation must be performed if rottlog is run and
today is not Monday, Tuesday, nor Wednsday and it is 21:00 hours,
or today is Monday and it is 19:00 hours.

@example
3) period jan-jun 23:00,jul-sep 10:00,oct-dec 23:00
@end example
Is equivalent to:
@example
   period !jul-sep 23:00,jul-sep 10:00
@end example

This means that rotation must be performed if rottlog is run and today
is not in a month between (or including) July and September and it is
23:00 hours, or today is in a month between (or including) July and
September and it is 10:00 hours.

@example
4) period mon+fri jul-sep 22:00,
          !jul-sep mon-sat 01:00 (all in one line)
@end example

Is equivalent to:
@example
  period mon jul-sep 22:00, fri jul-sep 22:00,
          !jul-sep mon-sat 01:00 (all in one line)
@end example

This means that rotation must be performed if rottlog is run and today
is Monday or Friday in a month between (or including) July to
September and it's 22:00, or today is not in a month between (or
including) July to September and it's between (or including) Monday
through Saturday and it's 01:00.

This sample can be made to use the + operator. It's handy not to have
to write a long line like the latter, but a more compact line like the
former is better.

@item postrotate ... endscript

Lines between postrotate and endscript (both of which must
appear on lines by themselves) are executed after the log file is
archived/rotated.  Can be used with metavariables. 
@xref{Use of meta-variables}, for details.

@item prerotate ... endscript

Lines between prerotate and endscript (both of which must appear
on lines by themselves) are executed before the log file is
archived/rotated.  Can be used with metavariables. 
@xref{Use of meta-variables}, for details.

@item rotate @var{number}

Log files are rotated <number> times before being overwritten.
Rot[t]log uses two rotation methods: a rottlog method and the
logrotate method. The native method will order rotated files by
extension. The logrotate method can be used adding the log_rotate
option to the configuration block. The following example will show the
differences between the two methods:

@example
# In weekly configuration file
/var/http/logs/access.log @{
  rotate 4
  log_rotate
@}
/var/http/logs/error.log @{
  rotate 4
@}
@end example

The following are saved as specified above:

@multitable {week 10} {access.log.99} {@result{}} {access.log.99}
@item week 1:           @tab access.log         @tab @result{} @tab access.log.1
@item                   @tab error.log          @tab @result{} @tab error.log.1
@item @tab @tab @tab
@item week 2:           @tab access.log.1       @tab @result{} @tab access.log.2
@item                   @tab access.log         @tab @result{} @tab access.log.1
@item                   @tab error.log          @tab @result{} @tab error.log.2
@item @tab @tab @tab
@item week 3:           @tab access.log.2       @tab @result{} @tab access.log.3
@item                   @tab access.log.1       @tab @result{} @tab access.log.2
@item                   @tab access.log         @tab @result{} @tab access.log.1
@item                   @tab error.log          @tab @result{} @tab error.log.3
@item @tab @tab @tab
@item week 4:           @tab access.log.3       @tab @result{} @tab access.log.4
@item                   @tab access.log.2       @tab @result{} @tab access.log.3
@item                   @tab access.log.1       @tab @result{} @tab access.log.2
@item                   @tab access.log         @tab @result{} @tab access.log.1
@item                   @tab error.log          @tab @result{} @tab error.log.4
@end multitable

After four weeks, the first archived access.log will be access.log.4
and first archived error.log will still be error.log.1

@item sharedscripts

Let the postrotate script be run only once, after handling the last file in
a multiple file definition block:

@example
/var/adm/log.* @{
  sharedscripts
  postrotate
    killall -HUP syslogd
  endscript
@}
@end example

The killall command will be run only after handling all log files
beginning with "log" in the /var/adm dir.

@item size @var{num}[b,k,M]

Rotate a logfile only if it grows the specified dimension.
Parameter must be a number followed by one of following chars:
@display
b - means bytes
k - means kbytes (num * 1024)
M - means megabytes (num * 1000000)
@end display

If none of these three characters is used, b is default.

@item start @var{number}

Number to use as the base for rotation. Extensions will start from the
specified @code{number}. The files will be rotated the number of times
specified in the rotate option, minus the 'start' number.

@item storedir @var{dirname}

If @code{dirname} is a relative dirname it will be appended to
packdir, defined in the rc file; if @code{dirname} is an absolute
dirname it will be used instead of packdir. Can be used with
metavariables.  @xref{Use of meta-variables}, for details.

@item storefile @var{filename}

Filename of compressed logfile to be used (filename only).  Can be
used with metavariables.  @xref{Use of meta-variables}, for details.

@item tabooext <list>

@anchor{tabooext} 
The list of files expanded with the * wildchar will not include files
with an extension contained in <list>. If a + precedes this list of
extensions, the current taboo extension list is augmented, otherwise
it is replaced. At startup, the taboo extension list contains: .new
.rpmorig, .rpmsave, ,v, .swp, .rpmnew, and ~.

@item tarcollate

Same as collate, but store files in a compressed tar file. In addition
this option is compatible with ifempty option too. If set, a void file
will be archived with tar. If not set, it will be skipped.

Tar archive will contain relative dirnames if possible (if archived,
files are in subdirs of packdir defined in main rc file), or absolute
dirname.

@item touser @var{e-mail} 

Override global value of touser variable defined in rc file.

@item week_based
Force @code{@@NEXT_EXT} generation to be on a week basis. This is
useful only if @code{@@WEEK} metavar is used in storefile. See
@xref{month_based}, for more information.

@item year_based

Force @code{@@NEXT_EXT} generation to be on a yearly basis. This is
useful only if @code{@@YEAR} metavar is used in storefile.  See
@xref{month_based}, for more information.

@end vtable

@node Use of meta-variables

@section Use of meta-variables

In monthly/weekly/daily logs metavariables can be used.  Metavariables
are identifiers of a runtime defined value and can be used while using
following parameters:

@display
storedir
storefile
prerotate...endscript
postrotate...endscript
@end display

List of handled metavariables:

@ftable @code
@item @b{@@DIRNAME}
Dir containing logfile to be archived/rotated.

@item @b{@@FILENAME}
Name of the file to be rotated with numerical extension 
(@code{@@BASENAME.@@NEXT_EXT}).

@item @b{@@BASENAME}
Name of the file to be rotated, without extension.

@item @b{@@DEF_DIR}
Default dir of archive dir (corresponding to packdir variable).

@item @b{@@COMP_EXT}
Extension of compressed file (corresponding to extension variable).

@item @b{@@NEXT_EXT}
Next available numbered extension in destination dir.

@item @b{@@TEMPDIR}
Name of a temporary directory.

@item @b{@@1..@@n}
String corresponding to first, second, etc, on directory in dirname of
file to archive/rotate

@item @b{@@YEAR}
Return current 4 digit year (i.e. 1970).
@comment @strong{Can't be used in custom config files to define store[dir,file] if using rotate parameter too.}

@item @b{@@MONTH}
Return current month (01..12).
@comment @strong{Can't be used in monthly and custom config files to define store[dir,file] if using rotate parameter too.}

@item @b{@@WEEK}
Return number of week in year (0..53) to SunMon variable.
@comment @strong{Can't be used in monthly, weekly, and custom config files to define store[dir,file] if using rotate parameter too.}

@item @b{@@DAY}
Return current day of month (01..31).
@comment @strong{Can't be used in monthly, weekly, daily, and custom config files to define store[dir,file] if using rotate parameter too.}

Values of metavariables are defined while the script is running, so a block definition like this

@example
/var/adm/log.* @{
  storedir /var/adm/archive-log/@@BASENAME
  rotate 5
  ...
@}
@end example

means that rottlog will rotate 5 times all files in /var/adm beginning
with "log." and store each file in a dir named with logname.
(i.e. /var/adm/archive-log/log.kern, /var/adm/archive-log/log.daemon...)

@strong{WARNING: Metavariables substitution is merely textual!}

So in a block like this
@example
/var/http/www.mysite.com/log/access.log @{
  storefile @@3-@@13-@@FILENAME
  rotate 4
  ....
@}
@end example
rottlog will create logfiles called something like
www.mysite.com-var3-access.log.1

Because @@13 is not defined (complete absolute filename in first line of
block definition contains only 5 tokens) and only @@1 will be substituted.
Following text will not be affected (remaining 3-) and will @strong{NOT}
generate an error code.

@end ftable

@node RC File Examples

@section RC File Examples

@b{Example 1}.
Basic configuration for main rc file.  Rottlog will use gzip/gunzip to
compress/uncompress data.  MTA used is sendmail, with administrator
contact email of master@@example.net.  Rotation algorithm and use of
file creation attribute will be the same as logrotate.  For security,
symbolic links will not be followed.

@findex gzip
@findex gunzip
@findex logrotate
@findex create@t{_}logrotate
@findex log@t{_}rotate
@cindex logrotate compatibility

@example
# This file has been created for maximum compatibility with logrotate
#
# Compressor program
packer=gzip

# Packer's options to compress and send to stdout
compress="-9c"

# DE-Compressor program
unpacker=gunzip

# Decompressor's options to send output do stdout
uncompress="-c"

# Normal extension of compressed files
extension="gz"

# Pager used to view uncompressed logs
pager="less"

# default basedir to store rotated/archived files
packdir="/var/log/rottlog"

# Sender of mail messages
fromuser="rottlog@@example.net"

# Receiver of mail messages
touser="master@@example.net"

# don't rotate/archive files of 0 size
notifempty=1

# Mail program to send messages.
mail="/usr/sbin/sendmail -t"

# Default Maximum depth to use with * metachar
maxdepth=0

# set to 0 will not follow symlinks
follow@t{_}symlinks=0

# Silently remove from status file no longer existant delayed logfiles
remove_missing

# Store archived logfiles in the same directory where "live" logfiles
# resides
nostoredir

# Copy mode, owner, and group from old logfile, if create is called
# without parameters (logrotate behaviour)
create_logrotate

# Rotate files with logrotate behaviour
log_rotate

@end example

@node Period Related File Examples

@section Period Related File Examples

Using Meta Variables and a rotation algorithm it is possible to rotate
logs so that a file rotated once is never touched again (unless deleted),
making log rotation much more compatible with host-based intrusion
detection schemes.  Words beginning by @@ are special Meta Variables
used to create dynamic fields like file and directory names to use.

The following examples will use defaults defined in the previous section.
These examples are valid in all monthly, weekly, and daily config files.


@b{Example 1}.
Use @code{/var/log/rottlog/log.daemon} and leave in new logfile events
from first day of actual month (logpart).  After that, a script
will be called to restart syslogd (postrotate/endscript).
@findex logpart
@cindex partial archiving
@example
/var/log/rottlog/log.daemon @{
   postrotate
      /sbin/killall -HUP syslogd
   endscript
   logpart "#1 day"
@}
@end example

@b{Example 2}.
Same as Example 1, but archived logfile compression is postponed
to the next time rottlog will handle @code{/var/log/rottlog/log.daemon}
(delaycompress).
@findex delaycompress
@cindex postponed compression
@example
/var/log/rottlog/log.daemon @{
   postrotate
      /sbin/killall -HUP syslogd
   endscript
   logpart "#1 day"
   delaycompress
@}
@end example

@b{Example 3}.
Split log files; postrotate script will be run for each single logfile.
@cindex multiple logfiles
@findex delaycompress
@findex postrotate
@example
/var/log/rottlog/log.daemon,/var/log/rottlog/log.debug @{
   postrotate
      /sbin/killall -HUP syslogd
   endscript
   logpart "#1 day"
   delaycompress
@}
@end example

@b{Example 4}.
Rotate 6 times all files in @code{/var/log/apache} dir (@code{rotate}).
Archived logfiles will not be compressed (@code{nocompress}) and they
will be stored in an apache-archives subdir of "packdir" defined in main
rc configuration file (@code{storedir}). If a logfile has size 0 it will
not be handled (@code{notifempty}).
@findex rotate
@findex nocompress
@findex storedir
@findex notifempty
@cindex skip 0 size files
@example
/var/log/apache/* @{
   storedir apache-archives
   rotate 6
   notifempty
   nocompress
@}
@end example

@b{Example 5}.
Archive @code{wtmp} and @code{lastlog} files and touch new 0 byte files
with specified permissions, owner and group (@code{create}).  Report
message will be sent to a different user from those specified in main
rc config file (@code{touser}).  Logfile compression is postponed to
the next rotation cycle.
@findex create
@findex touser
@findex delaycompress
@cindex creating new files
@example
/var/adm/wtmp,/var/adm/lastlog @{
        create 644 root root
        delaycompress
        touser "admin@@example.net"
@}
@end example

@b{Example 6}.
Rotate twice all logfiles in @code{/var/log} called @code{log.a*},
descending two levels of recursion to find files.  Store compressed
logfiles in a dir called something like:
@findex rotate
@findex maxdepth
@findex storedir
@findex append-only
@findex createdir
@findex size
@example
$packdir/<actual year>/<actual month>/<logfile basename>
@end example
This is done using META-VARIABLES in storedir parameter.

@xref{Use of meta-variables}, for details.

New 0 byte files will be created with specified permissions, owner and
group (@code{create}), and will be set with the append-only attribute
(@code{append-only}).  Don't rotate logs if they are smaller than 1
Megabyte (@code{size}).
@example
/var/log/log.a* @{
     # Descend two levels of depth to find files respecting criteria
     # (beginning by log.a)
     maxdepth 2

     # Use of meta-variables. storedir will be expanded for each processed 
     # file (so i.e. will be used 2002/04/log.auth, 2002/04/log.apache, ....)
     # to store compressed archived logs
     storedir @@YEAR/@@MONTH/@@BASENAME

     # Make new dirs if necessary with specified permissions, owner and group
     # ALERT: See README for more details.
     createdir 0640 root loggers

     # Rotate files with a 6 month period.
     rotate 6

     # Flag to use only with an ext2 filesystem. Add append-only attribute
     # to logfile
     append-only

     # Don't rotate if logfile is smaller than 1 Megabyte
     size 1M
@}
@end example

@b{Example 7}.
Archive all logfiles stored in local @code{/usr/local/apache/logs} dir in
a remote NFS volume, mounted during rottlog's execution. Will be
used @code{firstaction}...@code{endaction} to mount nfs remote volume, and
@code{lastaction}...@code{endaction} to umount it. Archived logfiles are
stored in a dir available only after firstaction is performed and is defined
during rottlog's execution.
@findex firstaction
@findex storedir
@findex createdir
@findex notifempty
@findex postrotate
@findex lastaction
@cindex last action
@cindex first action
@cindex mounting an NFS volume
@cindex postrotate script
@example
/usr/local/apache/logs/* @{
  # Action between firstaction and endaction tags will be performed before
  # all logfiles are rotated/archived
  firstaction
    mount fserver.example.net:/LogArchive /mnt/LogVol
  endaction

  # Define a destination directory available only after firstaction
  # is performed
  storedir /mnt/LogVol/@@YEAR/@@MONTH/@@BASENAME

  # Permissions about newly created dir
  createdir 0640 root loggers
  notifempty

  # After each log file is rotated following commands will be executed
  postrotate
    /usr/local/apache/bin/apachectl restart
    /usr/local/bin/my-nice-script.sh
  endscript

  # Action between lastaction and endaction tags will be performed after
  # all logfiles has been rotated/archived.
  lastaction
    umount /mnt/LogVol
  endaction
@}
@end example

@b{Example 8}. Archive all logfiles stored in the local
@code{/usr/local/squid/logs/} directory onto tape. Before archive the
logfile, it will be saved in a temporary directory that will be removed
immediately after handled last logfile in this block.
@findex firstaction
@findex storedir
@findex notifempty
@findex postrotate
@findex lastaction
@cindex post rotate script
@cindex first action
@cindex last action

@example
/usr/local/squid/logs/* @{
  # Action between firstaction and endaction tags will be performed
  # before all logfiles are rotated/archived
  firstaction
    mt -f /dev/nst0 eom
  endaction

  # Define a temporary storedir
  storedir @@TEMPDIR

  # Define filename of logs to be archived
  storefile @@FILENAME.@@WEEK@@YEAR

  # Don't archive file if it's empty
  notifempty

  # After each log file is rotated following commands will be executed
  postrotate
    star -cv -f /dev/nst0 @@TEMPDIR/@@FILENAME.@@WEEK@@YEAR
  endscript

  # Action between lastaction and endaction tags will be performed after
  # all logfiles has been rotated/archived
  lastaction
    mt -f /dev/nst0 offline
  endaction
@}
@end example

@b{Example 9}. Archive @code{log.daemon} only on 15th day of the month, and
will compress the archived logfile next month.
@findex delaycompress
@findex period
@cindex custom period
@cindex fixed day of a month
@example
/var/adm/log.daemon @{
        # These actions will be performed after archived each logfile
        postrotate
            /sbin/killall -HUP syslogd
        endscript
        delaycompress
        # rottlog will handle this file only on 15th day of the month
        period 15
@}
@end example

@b{Example 10}. Rotate @code{fetchmail.log} five times before overwriting,
each three days, So the file @code{fetchmail.log.1} will be overwrited each
15 days.
@findex rotate
@findex period
@cindex custom period
@example
/var/log/fetchmail.log @{
        # Handle this file every three days
        period 3d
        # Handle logfile on a 5-period basis. So fetchmail.log.1 will be
        # overwritten every 15 days
        rotate 5
@}
@end example

@b{Example 11}. Archive @code{log.auth} using different behaviour in different
year periods. If we are in summer (july to september), @code{log.auth}
will be archived on monday or friday at 22:00. If we are not in summer,
the file will be archived from monday to saturday at
01:00.
@findex period
@cindex custom period
@example
/var/adm/log.auth @{
        # rottlog will handle this file:
        # monday or friday on 22:00 during summer (july to september)
        # from monday to saturday on 01:00 otherwise
        period mon+fri jul-sep 22:00, !jul-sep mon-sat 01:00
@}
@end example

@b{Example 12}. Rotate @code{log.auth} with logrotate algorithm.
@findex log@t{_}rotate
@findex rotate
@cindex logrotate compatibility
@cindex logrotate rotate algorithm
@example
/var/adm/log.auth @{
  log_rotate
  rotate 4
@}
@end example

@b{Example 13}. Rotate @code{log.auth} using logrotate algorithm and
rottlog create parameter. This means that the new logfile will be
created with 0600 mode and owner stefano, group root.
@findex log@t{_}rotate
@findex create
@cindex logrotate compatibility
@cindex logrotate rotate algorithm
@example
/var/adm/log.auth @{
  log_rotate
  create 600 stefano root
  rotate 4
@}
@end example

@b{Example 14}. Rotate @code{log.auth} using logrotate algorithm and
create parameter. This means that the new logfile will be created with
same permission and owner.group of just-rotated @code{log.auth}.
@findex log@t{_}rotate
@findex create@t{_}logrotate
@findex rotate
@cindex logrotate compatibility
@cindex logrotate rotate algorithm
@cindex logrotate create new file

@example
/var/adm/log.auth @{
  log_rotate
  create_logrotate
  rotate 4
@}
@end example

@b{Example 15}. Store apache logs from many virtual hosts each odd days if
it is not Summer, otherwise it will store logs only Wednesday and Saturday

@example
  /hosts/domain1.com/log/access_log,/hosts/domain1.com/log/error_log,\
  /hosts/domain2.com/log/access_log,/hosts/domain2.com/log/error_log,\
  /hosts/domain3.com/log/access_log,/hosts/domain3.com/log/error_log,\
  /hosts/domain4.com/log/access_log,/hosts/domain4.com/log/error_log,\
  /hosts/domain5.com/log/access_log,/hosts/domain5.com/log/error_log @{
  # @@1 stays for: first token in path parsing
  # @@2 stays for: second token in path parsing
  storedir @@1/@@2/log/@@MONTH-@@YEAR

  # Create new directories if not yet existant with specified
  # permissions, owner and group
  createdir 0644 apache apache

  # Defines archived filenames
  storefile @@BASENAME.@@DAY.gz

  # Create new 0-size logfiles in place of archived with specified
  # permissions, owner and group
  create 0644 apache apache

  # Force archiving of logfiles:
  # 1 - Monday, wednesday, friday and sunday if actual month is not
  #     between july and august
  # 2 - Wednesday and saturday if actual month is between july and
  #     august
  period !jul-aug mon+wed+fri+sun, jul-aug wed+sat

  # Handle this file even if it is empty
  ifempty

  # Don't mail to administrator report for each log file handled
  nomail
@}
@end example

@b{Example 16}. 

@example
/var/adm/messages @{
   # Store compressed messages in $packdir/messages
   storedir messages
   # These actions will be performed before archiving the logfile
   prerotate
   /sbin/killall -STOP myprogram
   endscript
   # Rotate logs with extensions from .1 to .5
   rotate 5
   # Don't rotate log if it's empty
   notifempty
@}
@end example


@node Files

@section Files

@table @code
@item @b{@@ETCDIR/rc}

@quotation
The main configuration file.
@end quotation

@item @b{@@ETCDIR/monthly}

@quotation
Configuration file to handle monthly log rotation.
@end quotation

@item @b{@@ETCDIR/weekly}

@quotation
Configuration file to handle weekly log rotation.
@end quotation

@item @b{@@ETCDIR/daily}

@quotation
Configuration file to handle daily log rotation.
@end quotation

@item @b{@@ETCDIR/custom}

@quotation
Configuration file to handle custom log rotation.
@end quotation

@item @b{@@STATDIR}

@item @b{/var/lock/LOCK.rottlog}
@comment TROFF INPUT: .RS

@quotation
Lockfile to prevent running multiple instances of rottlog.
@end quotation

@end table

@node Bugs

@section Bugs

If you find a bug in this program, or documentation, please email
@email{bug-rottlog@@gnu.org}, or through Bug Tracker at
@url{https://savannah.gnu.org@/bugs@/?group=rottlog}.  

@node GNU Free Documentation License
@section GFDL
@include doclicense.texi

@node Index of Variables and Commands
@section Mandatory Variables
@printindex vr

@node Index of meta-variables
@section Index of meta-variables
@printindex fn

@node Index of concepts
@section Index of concepts
@printindex cp

@bye
