metalog.conf(5)

✨ metalog.conf — the config file for metalog, bestie ✨

So you've got yourself a metalog.conf(5) moment, huh? This is the manual page for the config file of metalog, the log daemon. It's genuinely not that deep once you get the vibe, and I'm gonna walk you through every single option because I refuse to let you guess. 🫶

---

🎀 SYNTAX 🎀

Here's the whole shape of the thing:

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

Real talk: comments start with # and that is ONLY allowed at the very beginning of a line. Not after a value. Not mid-line. Beginning of the line, periodt. 💅

---

💅 DESCRIPTION 💅

So the [default values] block? Those are your fallback settings, and they get used whenever you don't redefine them inside a section. You can name <section title> literally whatever you want — it carries zero meaning, it's just there so your config file is easy to read with your human eyes. Cute, functional, we love that for us. 🌸

Value names can be one of the following:

🍓 maxsize = <number (bytes)>

The moment a logfile goes over the number you set (in bytes), it gets rotated. And listen — if maxfile is equal to zero, log rotation is disabled. Setting a default value here is a good idea, fr fr.

🍓 maxtime = <number (seconds)>

Once a logfile is older than the value you set (in seconds), it gets rotated. Also a good idea to define a default value here.

NB: a logfile gets rotated when either the maxsize or the maxtime limit is reached. If either one or both of them is equal to 0, then log rotation is disabled. 😭

🍓 maxfiles = <number>

This one says how many rotated files you're keeping around, max. So you'll have x rotated files (in the log-date-string filename type style), plus the file named current.

🍓 facility = "<facility>"

Only records a message if the app that issued it uses syslog facility <facility>. The facility names are: "auth", "authpriv", "cron", "daemon", "ftp", "kern", "lpr", "mail", "news", "security", "syslog", "user", "uucp", "local0", "local1" ... "local7". Every single kernel message gets logged with facility "kern". A section can have several facility = ... lines so you match more than one facility. And if <facility> is "*", it'll match all the facilities. catch them all energy 🌈

🍓 remote_host = <IP address or domain name>

Log entries get sent to the remote log server defined by this IP address or domain name. This one can only be defined in the default values section. Before you configure the other remote host options (port, format, ...) remote_host must be set — it's the main character of remote config. 💅 All log messages are sent there, and limitations via "ratelimit", "ratelimit_burst" or "showrepeats" are ignored for log messages sent to the remote log server. If you configure a domain or host name, 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 you can use it multiple times to add more remote log servers. The name part can be any string, but it must be the same for remote_port[<name>] etc.

🍓 remote_port = <value>

The UDP port of the remote log server. Default is "514". This one can only be defined in the default values section.

🍓 remote_port[<name>] = <value>

Equal to remote_port, but you can use it multiple times to add more remote log servers. The name part can be any string, but it 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 this is set to 1. Can be defined for default values or in sections.

🍓 remote_log[<name>] = <number>

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

🍓 remote_format = <format>

Default is legacy_timestamp. Log messages get sent to the remote log server with the format you define. Format options are: "legacy", "legacy_timestamp", "rfc3164" and "rfc5424".

🍓 remote_format[<name>] = <format>

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

🍓 remote_severity_level = <severity level>

Default is 7. Log messages get sent to the remote log server only when their 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 you can use it multiple times to add more remote log servers. The name part can be any string, but it must be the same for remote_host[<name>] etc.

🍓 log_format = <format>

Default is legacy_timestamp. Log messages get written to the filesystem or stdout with the format you define. Format options are: "legacy", "legacy_timestamp", "rfc3164" and "rfc5424".

🍓 log_severity = <number>

Default is 0. Log the severity level when you're logging in "legacy" or "legacy_timestamp". The severity level will always be part of log entries when you're in "rfc3164" or "rfc5424" — no takebacks, that's just how it is. 💀

🍓 break = <number>

Default is 0. If you set it to 1 and a section is matched, it performs the action, but then it does not consider any more possible section matches below this one in the config file. This is iconic for building a config where specific types of log messages get 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 that duplication. Don't get caught duplicating, bestie. 🙈

🍓 minimum = <level>

Only records 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 get written under the directory you specify. The special value "NONE" will skip the log message entirely. 🚫

🍓 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, okay? 👑

🍓 regex = "perl compatible regular expression"

Can be used when you only want to log messages that match the pattern (like "invalid", "fail", etc...) so you can send them to a single directory.

Multiple regex may be defined in a single section, and 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 the message being logged when no neg_regex match happens.

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

🍓 postrotate_cmd = "/path/to/a/program"

Run the 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, so you can send all messages from related programs to the same log file. 🫶

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

🍓 program_neg_regex = "perl compatible regular expression"

The inverse of program_regex, for filtering 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 the message being logged when no program_neg_regex match happens.

Multiple program_neg_regex may be defined in a section, and 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 — it'll just ignore that config line. chillest daemon behavior honestly 😌

🍓 stamp_fmt = "%b %e %T"

Format of the human readable timestamp that gets prepended to all log messages. The format string supports all conversion specifications from strftime plus %[nnn]N for nanoseconds (default: nine numbers long, and it 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 their own). It 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 messages, 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. ❌

---

...and that's not even the end, bestie — there's more of this page coming, so don't you dare close the tab. 💖

• configdir = "/path/to/directory/with/more/config/files" — bestie, this is the optional little folder of extra config files that get read the second metalog starts up. 💖 Only file names that end in .conf are interpreted, so don't go naming your files all willy-nilly. This option is only allowed once — every repetition after the first just gets ignored, no drama, no error, just vibes. The contents of those extra config files get appended to the existing config in alphanumeric order of the file names, so that metalog's behaviour stays determined and predictable. ✨
• socket = "/path/to/logging/socket" — listen and filter on an additional logging socket, because why have one source of logs when you could have more. 🫶 Heads up though: if creating the sockets fails, metalog will just carry on without that source of logs. It's giving resilience, honestly.
• compress = <number> — default is 0. If you set it to 1, rotated logs get compressed in gzip format. 🎀 But lowkey important: this option gets ignored if metalog was built without compression support. So if nothing's happening, that's why, iykyk.
• compress_delay = <number> — default is 0. This is the number of the most recent rotated log files to leave uncompressed. So like, a lil grace period for the freshest ones. 🌸

---

📁 FILES 📁

Okay so real talk — the exact paths depend on the build settings. These are the standard paths, your mileage may vary depending on how it was compiled. 🙈

• /etc/metalog.conf

---

👑 AUTHORS 👑

The absolute icons who made this happen, no cap:

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

Go read that one too, bestie, it's the whole main character of this operation. 💅

---

That's the whole page, babe! 💖 This was metalog.conf(5) from the metalog family, page 4 of the man set, and Frank DENIS is the one credited down in the corner of the original. Now go forth and configure your logs like the icon you are. ✨🎀🦋