Log block

The log block is used to log server messages to log files but also to decide which messages get sent to which snomasks (server notices). It is normal to have several log blocks.

If you have no log block that logs to disk then UnrealIRCd will by default log everything to ircd.log. Logging to disk is available in standard text format (easy to read) or in json format (very detailed).

Syntax

All log blocks have at least one item in source in destination, like this:

log {
        source {
                // Sources go here (can be multiple items)
        };
        destination {
                // Destination goes here (usually only one, but can be multiple items)
        };
};

To create your own log block you:

• First read Step 1 to select the source
• Then read Step 2 to select a destination (there are also examples mentioned there)

Step 1: select sources (events)

log {
        source {
                <source1>;
                <source2>;
                ...
        };
}

Here you select the log sources you want to log. This can be:

• A subsystem, like: oper
• A log level severity, like: info
• An event id, like: LINK_CONNECTING

Or a combination of the above, eg link.LINK_CONNECTING. You can also use negative matchers by use of an exclamation mark (!), eg: !link.LINK_CONNECTING.

See Log sources for a full list of subsystems and event ids.

Finally, there are also two special log sources:

• all: this includes everything
• nomatch: this includes anything that is not matched elsewhere. It should only be used for snomask s, as is done in conf/snomasks.default.conf. End-users should not change/use it.

Step 2: specify where to log to

Once you have selected one or more sources, you now specify where to log to: a file, syslog, snomask, channel or remote. Choose 1 of the options below.

Logging to a file

log {
        source {
                !debug;
                all;
        }
        destination {
                file "ircd.log" {
                        maxsize 100M; /* optional */
                        type text; /* either 'text' or 'json' */
                };
        }
}

The log::destination::file specifies where to log to. Examples:

• ircd.log: a literal filename
• ircd.%Y-%m-%d.log: a filename with strftime formatting. This example will give you a new log file for every day such as: ircd.2020-01-31.log.
• /var/log/unrealircd/ircd.log: a full path (NOTE: be sure UnrealIRCd can write to the directory)

It has several options:

• log::destination::file::maxsize: a maximum size of the log file. When the log file reaches this limit then log file will be renamed to name-of-log-file.old (overwriting any previous such .old file). You can use K/M/G to specify kilobytes/megabytes/gigabytes.
• log::destination::file::type: the logging output type. Use text for human readable text, or json for more detailed machine readable output, see JSON logging.

Example: log all messages to disk

This simply logs all messages to disk in a human readable way:

log {
        source {
                !debug;
                all;
        }
        destination {
                file "ircd.log" { maxsize 100M; }
        }
}

Example 2: log all messages to disk in JSON format

This uses the JSON logging format. This is easier to parse by machines (external programs) and the logs include a lot more detail:

log {
        source {
                all;
                !debug;
        }
        destination {
                file "ircd.json.log" { maxsize 100M; type json; }
        }
}

Logging to syslog

If you want to log to *NIX syslog then you can do so like this:

log {
        source {
                all;
                !debug;
        }
        destination { syslog; }
}

Logging to a snomask

destination { snomask X; }

This specifies to which snomask the messages should go. The specified snomask should be a single letter. See below for an example.

Example: create your own custom snomask

Normally server notices regarding server linking end up in the "catch all" snomask s which generally all IRCOps have set, so all IRCOps will see them.

Maybe you don't like that and want to create a new snomask L for all the linking messages:

/* Custom snomask L for linking messages */
log {
        source {
                link;
        }
        destination {
                snomask L;
        }
}

After you add this, IRCOps will no longer see server messages about linking anymore by default. Only IRCOps who set themselves MODE yournick +s +L will see the linking messages. And naturally you can add L to oper::snomask for those IRCOps who still want to see these messages.

You can create as many snomasks as you like, as long as there are letters available. The standard default list of snomasks can be found here.

Logging to a channel

This feature is only available in UnrealIRCd 6.0.2 and later

This sends all the server notices to a channel:

log {
        source {
                !debug;
                all;
        }
        destination {
                channel "#opers" {
                        /* The following fields are optional. This shows the defaults: */
                        color yes; /* Log with colors? 'yes' or 'no'. Default is yes, unless overriden by set::server-notice-colors */
                        show-event yes; /* Show the event, eg connect.LOCAL_CLIENT_CONNECT. Default is yes, unless overriden by set::server-notice-show-event */
                        json-message-tag yes; /* Include JSON data in message tags */
                        oper-only yes; /* Only send messages to IRCOps in the channel */
                }
        }
}

Important notes on channel messages:

• Messages are only delivered to locally connected users. It is recommended you use the same log blocks with the same channels and options on all your servers, if you want to see the messages everywhere no matter where you are connected to.
• Because these are not "real" private messages in a channel, they will not show up in channel history (+H).
• Via the json-message-tag option you can enable (the default) or disable JSON logging. See Enabling JSON logging on IRC on how JSON messages are delivered over IRC using message tags.
• By default messages are only shown to IRCOps for security reasons. You can turn this off by setting oper-only no; but this is NOT recommended because then accidentally regular users may see a lot of sensitive information, not only in the text but also via the json-message-tag. So be very careful if you turn this off.

Logging to a remote IRC server

This means the log message should be forwarded to all other servers. This is used in conf/snomasks.default.conf so things like link errors and oper-ups can be seen network-wide. End-users probably don't need to change/use this. Important: if you use this incorrectly, you may see duplicate server notices.