metalog.conf(5)

NAME

metalog.conf - configuration file for metalog

SYNTAX

[default values]

<section title :>
<section values>

<section 2 title :>
<section 2 values>

# Comments are introduced with "#", which is ONLY allowed at the beginning of a line.

<etc.>

DESCRIPTION

[default values] will be used if you do not redefine them in a section. You can choose <section title> as you wish. It doesn't mean anything, just allow you to keep an easy to read config file.

Values names can be one of the following:

maxsize = <number (bytes)>
    Once a logfile has exceeded the value defined (in bytes), it will be rotated. If maxfile is equal to zero, it disables log rotation. Defining a default value is a good idea.

maxtime = <number (seconds)>
    Once a logfile is older than the value defined (in seconds), it will be rotated. Defining a default value is a good idea.

    NB: A logfile is rotated when either maxsize or maxtime limit is reached. If either one or both is equal 0, then log rotation is disabled.

maxfiles = <number>
    This value indicates the maximum number of rotated files kept. So you'll have x rotated files (log-date-string filename type), plus the file named "current".

facility = "<facility>"
    Only records a message if the application that issued it uses syslog facility <facility>. Facility names are : "auth", "authpriv", "cron", "daemon", "ftp", "kern", "lpr", "mail", "news", "security", "syslog", "user", "uucp", "local0", "local1" ... "local7". All kernel messages are logged with facility "kern". A section can have several "facility = ..." lines to match more than one facility. If <facility> is "*", it'll match all the facilities.

remote_host = <IP address or domain name>
    Log entries are sent to the remote log server defined by this IP address or domain name. This can only be defined in the default values section. Before configuring other remote host options (port, format, ...) remote_host must be set. All log messages are sent there, limitations via "ratelimit", "ratelimit_burst" or "showrepeats" are ignored for log message sent to the remote log server. In case a domain or host name is configured, the necessary DNS request will be repeated after every failed attempt or after 120 seconds when the name has been successfully resolved.

remote_host[<name>] = <IP address or domain name>
    Equal to remote_host, but can be used multiple times to add more remote log servers. The name part can be any string, but must be the same for remote_port[<name>] etc.

remote_port = <value>
    The UDP port of the remote log server. Default is "514". This can only be defined in the default values section.

remote_port[<name>] = <value>
    Equal to remote_port, but can be used multiple times to add more remote log servers.The name part can be any string, but must be the same for remote_host[<name>] etc.

remote_log = <number>
    Default is 0. Log messages are sent to the remote log server when set to 1. Can be defined for default values or in sections.

remote_log[<name>] = <number>
    Equal to remote_log, but can be used multiple times to add more remote log servers. The name part can be any string, but must be the same for remote_host[<name>] etc.

remote_format = <format>
    Default is legacy_timestamp. Log messages are sent to the remote log server with the defined format. Format options are : "legacy", "legacy_timestamp", "rfc3164" and "rfc5424"

remote_format[<name>] = <format>
    Equal to remote_format, but can be used multiple times to add more remote log servers. The name part can be any string, but must be the same for remote_host[<name>] etc.

remote_severity_level = <severity level>
    Default is 7. Log messages are sent to the remote log server only when its urgency is inferior or equal to <severity level>. Level '0' is the most critical one, while level '7' is for debugging messages.

remote_severity_level[<name>] = <severity level>
    Equal to remote_severity_level, but can be used multiple times to add more remote log servers. The name part can be any string, but must be the same for remote_host[<name>] etc.

log_format = <format>
    Default is legacy_timestamp. Log messages are written to filesystem or stdout with the defined format. Format options are: "legacy", "legacy_timestamp", "rfc3164" and "rfc5424"

log_severity = <number>
    Default is 0. Log the severity level when logging in "legacy", "legacy_timestamp". The severity level will always be part of log entries when in "rfc3164" or "rfc5424".

break = <number>
    Default is 0. If set to 1 and a section is matched, perform action, but don't consider any more possible section matches below this one in the config file. This is useful for creating a config where specific types of log messages are matched and dispatched, while a "catch-all" section at the bottom of the config file handles the default case.

    Using 0 would cause messages to be potentially handled by multiple sections, causing message duplication, while using 1 on the sections above a final "catch-all" would avoid duplication.

minimum = <level>
    Only record a message if its urgency is inferior or equal to <level>. Level '0' is the most critical one, while level '7' is for debugging messages. 5 will strip all non-important messages. The default minimum level is 7 (i.e. keep all messages).

maximum = <level>
    Don't log if the message level exceeds that value. By default, maximum is the largest possible level.

logdir = "/dir/where/logs/will/be/written/"
    Files will be written under the specified directory. The special value "NONE" will skip the log message.

perms = <mode>
    Permissions for the log directory. Defaults to 0700

program = "name"
    Can be used to do filtering instead of facility. Remember to use the executable name.

regex = "perl compatible regular expression"
    Can be used when you only want to log messages that match the pattern (like "invalid", "fail", etc...) to send them to a single directory.

    Multiple regex may be defined in a single section, only one must match.

neg_regex = "perl compatible regular expression"
    Can be used when you only want to log messages that do not match the pattern.

    A neg_regex match will override any regex matches and not log the message.

    When one or more regex are provided, at least one of them must match to log the message. The lack of any regex will result in message being logged when no neg_regex match.

    Multiple neg_regex may be defined in a section, only one must match.

postrotate_cmd = "/path/to/a/program"
    Run specified program after a log file has been rotated.

    The program is passed the date, the program name ("metalog"), and the new logfile name.

program_regex = "perl compatible regular expression"
    Similar to program, this is a regex that matches the program name to send all messages from related programs to the same log file.

    Multiple program_regex may be defined in a section, only one must match.

program_neg_regex = "perl compatible regular expression"
    The inverse of program_regex to filter out logs from programs that match.

    A program_neg_regex match will override any program_regex matches and not log the message.

    When one or more program_regex are provided, at least one of them must match to log the message. The lack of any program_regex will result in message being logged when no program_neg_regex match.

    Multiple program_neg_regex may be defined in a section, only one must match.

showrepeats = <number>
    Set to 0 to filter out repeat log messages.

command = "/path/to/program/to/execute"
    Run the specified program as soon as something is logged in a given section.

    The program is passed the date, the matching program name, and the log message.

    In case the program doesn't exist at metalog startup, metalog will not exit and just ignore that config line.

stamp_fmt = "%b %e %T"
    Format of the human readable timestamp prepended to all log messages. The format string supports all conversion specifications from strftime plus %[nnn]N for nanoseconds (default: nine numbers long, can be shortened with nnn < 9). The format string with %[nnn]N replaced is then passed to the strftime(3) function. An empty string is used to disable timestamps (for cases where the log messages already include its own). Will be ignored for logging if log_format and for remote logging if remote_format is set to rfc3164 or rfc5424.

flush = <number>
    If set to 0, matching log messages will always be buffered. If set to 1, they will always be written to the file system immediately.

    Both settings override the global default given through command line parameters (-a/-s) or signals.

ratelimit = "5/m"
    Limits the rate of logged messages to the specified number of messages per unit of time. Valid units of time are second, minute, hour and day, each identified by its first letter. Fractional values are allowed such as "0.5/m" to make human parsing easier.

    A limit of 0 (the default) may be used to disable any rate limit handling. In this case, the unit of time may be omitted.

ratelimit_burst = <number>
    Up to this number of lines will be printed at the beginning of a burst of message, if the rate of messages has been well below the limit before. The specified message rate will not be exceeded. The default value of 1 disables special treatment for bursts. Values less than 1 are invalid and will be rejected.

configdir = "/path/to/directory/with/more/config/files"
    This optional directory can contain more config files that will get interpreted at metalog start. Only file names ending with ".conf" are interpreted. This option is only allowed once, all repetitions will be ignored. The content of the additional config files will be appended to the existing config in alphanumeric order of the file names, to get a determined behaviour of metalog.

socket = "/path/to/logging/socket"
    Listen and filter on an additional logging socket. If creation of the sockets fails metalog will continue without that source of logs.

compress = <number>
    Default is 0. If set to 1, rotated logs are compressed in gzip format. This option will be ignored if metalog was built without compression support.

compress_delay = <number>
    Default is 0. The number of most recent rotated log files to leave uncompressed.

FILES

Note that the exact paths depend on the build settings. These are the standard paths.

/etc/metalog.conf

AUTHORS

Mike Frysinger <vapier@gentoo.org>
Laurent Wandrebeck (low) <wandre.l@free.fr>
Leo Lipelis <aeoo@gentoo.org>
Hendrik Visage <hvisage@users.sourceforge.net>
Frank DENIS (Jedi/Sector One) <j@pureftpd.org>

SEE ALSO
metalog(8)