1.5 Configuration parameters

A configuration block can include one or more of following keywords:

     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

Where:

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).

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, logfile will be searched in weekly configuration file. If used in weekly configuration file, 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:

            /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
            }

In monthly configuration file:

            /var/adm/log.daemon {
              storedir /mnt/BigVolume/Collections/@YEAR/@BASENAME
              createdir
              collate
            }

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:

          - [no]storedir
          - storefile
          - createdir
          - [no]missingok (TODO)
          - firstaction/lastaction
          - prerotate/postrotate
          - nocompress
           touser
          - nomail
          - ifempty/notifempty are silently ignored.

create [[mode] [owner 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. mode specifies the mode for the log file in octal notation (the same as chmod(2)), owner specifies the user name who will own the log file, and group specifies the group the log file will belong to.

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

createdir [perms] [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 dir_perm, dir_own, and dir_grp. You can specify perms only, or perms and own, but you can't specify perms and grp (second parameter is always interpreted as owner). perms specifies the mode for the log file in octal notation (the same as chmod(2)).

IMPORTANT: If directory hierarchy to be created is deeper than one directory, only the last directory will have the owner and permissions expected. Example:

            storedir 2002/04/apache_logs
            createdir 4300 rottlog

If dir 2002 is not already present on your box you will have (assuming that rottlog is run by user stefano):

          $ 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

create_logrtate

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

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.

dateext

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

dateoffset <+/-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.

day_based

Force @NEXT_EXT generation to be on a daily basis. This is useful only if @DAY metavariable is used in storefile. See See month_based.

firstaction 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 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.

ifempty

Rotate the log file even if it is empty.

lastaction 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 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.

logpart qdldl

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

          <number>l
          <number>b
          "<regexp>"
          "<#1 day>"

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

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.

mailopt what

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

all|a		Mail all sorts of informations
maillast|overwrite|over		Attach to-be-overwrited files to mail in plain text
ziplast|zip		Attach to-be-overwrited files to mail in compressed format
error|err		Mail only error messages
none|nomail		Don't mail anything

maxage <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.

maxdepth <depth>

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

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.

month_based

Force @NEXT_EXT generation to be on a monthly basis. This is useful only if the @MONTH metavariable is used in storefile.

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

In the above example, month_based is used to order apache.log files on a month basis:

          $ ls *-02*
          apache.log-2004-02.1
          apache.log-2005-02.2

nocompress

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

nocreate

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

nomail

Don't send notification email message.

nosharedscripts

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

nostoredir

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

notifempty

Do not rotate the log if it is empty.

period period-definitions

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.

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:

DD		Each DDth day of the month
DDd		Each DD days
WWw		Each WW weeks
mmM		Each mm months
<weekday>		Each <weekday> of the week
<monthname>		Each <monthname> of the year
HH:MM		At specified hour and minutes (*)
0		Each time rottlog is called (*)

(*) It depends on rottlog's entries in crontab

Where

          <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

Following characters can add use of logical functions and ranges:

, (comma)		OR
" " (white space)		AND
! (exclamation mark)		NOT
- (minus)		Week or month range
+ (plus)		Week or month list (Inlined OR)

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 !mon-thu, but it's not valid to write mon-!thu. It's valid to write !mon+fri+sat, but it's not valid to write 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.

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

Some examples:

          1) period mon-wed 21:00,sat 10:00

Is equivalent to:

             period mon 21:00,tue 21:00,wed 21:00,sat 10:00

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.

          2) period !mon-wed 21:00,wed 19:00

Is equivalent to:

             period !mon !tue !wed 21:00,mon 19:00

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.

          3) period jan-jun 23:00,jul-sep 10:00,oct-dec 23:00

Is equivalent to:

             period !jul-sep 23:00,jul-sep 10:00

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.

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

Is equivalent to:

            period mon jul-sep 22:00, fri jul-sep 22:00,
                    !jul-sep mon-sat 01:00 (all in one line)

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.

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. See Use of meta-variables, for details.

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. See Use of meta-variables, for details.

rotate 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:

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

The following are saved as specified above:

week 1:	access.log		access.log.1
	error.log		error.log.1
week 2:	access.log.1		access.log.2
	access.log		access.log.1
	error.log		error.log.2
week 3:	access.log.2		access.log.3
	access.log.1		access.log.2
	access.log		access.log.1
	error.log		error.log.3
week 4:	access.log.3		access.log.4
	access.log.2		access.log.3
	access.log.1		access.log.2
	access.log		access.log.1
	error.log		error.log.4

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

sharedscripts

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

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

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

size 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:

          b - means bytes
          k - means kbytes (num * 1024)
          M - means megabytes (num * 1000000)

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

start number

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

storedir dirname

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

storefile filename

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

tabooext <list>

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 ~.

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.

touser e-mail

Override global value of touser variable defined in rc file.

week_based

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

year_based

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