IRCu readme.log

Older versions of ircd had no consistent way of logging various actions. Some things, such as G-lines, were written out to log files with names compiled into the server. Others could only be logged through syslog. Some required that their log files exist beforehand. For u2.10.11, this situation has changed dramatically.

All logging in the server is now unified through a single logging subsystem. Unfortunately, the server still does not generate all the logs that it could, and some more tuning is in store for the next major release of ircd. Nevertheless, the logs that are generated are far more consistent, and those log messages may be sent to a given file, to syslog, or even to online operators--or any combination of these three methods. This file is intended to describe configuration of the logging subsystem.

All logs are classified by a "subsystem" and a "level." The subsystem is a major classification; each subsystem may be configured individually. The level classification is used to indicate how important the message is; subsystems may be configured to omit log messages with less than a certain importance--not unlike syslog.

Levels

Levels are used to classify the importance of various log messages. The most important level is the "CRIT" level; the least important is the "DEBUG" level. Each of the levels is also mapped to a corresponding syslog level, and some may even force generation of certain types of server notices. Each importance level is described below.

* CRIT - Used for very critical notifications, such as server termination. This is mapped to the corresponding "CRIT" syslog priority. This will also generate server notices to the "OLDSNO" server notice mask.

* ERROR - Used to report important error conditions. This is mapped to the corresponding "ERR" syslog priority.

* WARNING - Used to warn about certain conditions. This is mapped to  the corresponding "WARNING" syslog priority.

* NOTICE - Used for reporting important information. This is mapped to the corresponding "NOTICE" syslog priority.

* TRACE - Used to tracing operation of the server. This is mapped to  the corresponding "INFO" syslog priority.

* INFO - Used for reporting unimportant but potentially useful information. This is mapped to the corresponding "INFO" syslog priority.

* DEBUG - Used for reporting debugging information. This is mapped to the corresponding "DEBUG" syslog priority. This will also generate server notices to the "DEBUG" server notice mask.

Subsystems

All of the subsystems are described below, along with their default logging configuration. There are no default log files to log to, and the default logging level is INFO (unless the server is compiled with debugging enabled)--this means that only notices of importance INFO or higher will be logged.

* SYSTEM - Used to report information that affects the server as a  whole. By default, log messages to this subsystem go nowhere.

* CONFIG - Used to report information concerning the configuration file. By default, log messages to this subsystem go to the default syslog facility, which defaults to "USER," and to the "OLDSNO" server notice mask.

* OPERMODE - Used to report usage of /OPMODE and /CLEARMODE. By  default, log messages to this subsystem go to the "HACK4" server notice mask.

* GLINE - Used to report usage of /GLINE, particularly BADCHANs. By  default, log messages to this subsystem go to the "GLINE" server notice mask.

* JUPE - Used to report usage of /JUPE. By default, log messages to  this subsystem go to the "NETWORK" server notice mask.

* WHO - Used to report usage of the extended features of /WHO (/WHOX). By default, log messages to this subsystem go nowhere.

* NETWORK - Used to report net junctions and net breaks. By default, log messages to this subsystem go to the "NETWORK" server notice mask.

* OPERKILL - Used to report usage of /KILL by IRC operators. By  default, log messages to this subsystem go nowhere.

* SERVKILL - Used to report usage of /KILL by other servers. By  default, log messages to this subsystem go nowhere.

* USER - Used to report user sign-ons and sign-offs. By default, log messages to this subsystem go nowhere.

* OPER - Used to report usage of /OPER, either successfully or  unsuccessfully. By default, log messages to this subsystem go to  the "OLDREALOP" server notice mask.

* RESOLVER - Used to report error messages or other conditions from the resolver and authentication system. By default, log messages to this subsystem go nowhere.

* SOCKET - Used to report problems with sockets. By default, log messages to this subsystem go nowhere.

* DEBUG - Used only when debugging is enabled. All log messages to  this subsystem go either to the console or to the debug log file compiled into the server, as well as to the "DEBUG" server notice mask. This is the only subsystem with a default log file.

* OLDLOG - Not used anywhere. This is a left-over from when the logging subsystem was first created. Log messages to this subsystem go nowhere.

* DNSBL - Used to report dnsbl checking, marking, and exemption. Use the INFO level for most of the dnsbl logging information.

Configuration

The true power of the logging subsystem comes from its extremely flexible configuration. The default server facility can be configured, as can the facility for each individual subsystem described above. Moreover, administrators can configure the server to log to specific files, send selected log messages to operators subscribed to any server notice mask, and even change the default log level for each subsystem.

The logging subsystem has a set of tables mapping names to the numerical values used internally. Subsystems, levels, syslog facilities, and server notice masks are all configured using strings. These tables even include special strings, such as "DEFAULT" and "NONE." Each possible configuration piece is described below.

Default Syslog Facility

The IRC server has a default facility that it uses when sending log messages to syslog. The default facility may be overridden for each individual subsystem, but the default itself can be changed with an appropriate F-line in the configuration file. The facility normally defaults to "USER," but may be configured to be any of AUTH, CRON, DAEMON, LOCAL0, LOCAL1, LOCAL2, LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7, LPR, MAIL, NEWS, USER, or UUCP. Some systems also have the AUTHPRIV facility. To configure this default, add an F-line to the configuration file that looks like "F:LOG: "; should be replaced with the string for the desired default syslog facility.

Log Files

Each subsystem may be configured to send its log messages to any single log file with an F-line like "F:LOG: :FILE: "; should be replaced with one of the subsystem names described above, and should be a file name for the log file. The file name may be relative to the server's data directory ("DPATH"), or it may be an absolute path name. Note that if you're using chroot, these absolute path names will be relative to the server's root directory.

Logging to Syslog

By default, except for the CONFIG subsystem, no logs are sent to syslog. This can be overridden using an F-line like "F:LOG: :FACILITY: ";, as above, should be replaced with one of the subsystem names described above, and must be one of the facility strings mentioned under "Default Syslog Facility." The facility string may also be "NONE," to turn off syslog for that subsystem, and "DEFAULT," to use the server's default facility. Please don't confuse a DEFAULT facility with the default for a particular subsystem; only the CONFIG subsystem defaults to DEFAULT, whereas all the rest default to NONE.

Logging via Server Notices

Log messages can be sent to online IRC operators. Many subsystems actually default to this behavior, in fact. For security, log messages containing IP addresses or other extremely sensitive data will never be sent via server notices, but all others can be sent to a specific server notice mask. (For more information about server notice masks, please see doc/snomask.html.) The available mask names are OLDSNO, SERVKILL, OPERKILL, HACK2, HACK3, UNAUTH, TCPCOMMON, TOOMANY, HACK4, GLINE, NETWORK, IPMISMATCH, THROTTLE, OLDREALOP, CONNEXIT, and DEBUG. The special mask name "NONE" inhibits sending of server notices for a particular subsystem. The F-line for this configuration looks like "F:LOG: :SNOMASK: "; again, is one of the subsystems described above, and is one of the mask names.

Setting Minimum Logging Level

The minimum log level for a particular subsystem may be set with an F-line like "F:LOG: :LEVEL: "; here, is yet again one of the subsystems described above, and is one of the level names, also described above.