X-Git-Url: http://git.pk910.de/?p=ircu2.10.12-pk.git;a=blobdiff_plain;f=doc%2Freadme.log;fp=doc%2Freadme.log;h=1e635ca144b091b2cc3fe8ffca74982dfbbdc8e8;hp=0000000000000000000000000000000000000000;hb=0400a5a6479398d82526785c18c0df8bc8b92dce;hpb=d17e10da972ce5776c60b4c317267c6abe0e1ead diff --git a/doc/readme.log b/doc/readme.log new file mode 100644 index 0000000..1e635ca --- /dev/null +++ b/doc/readme.log @@ -0,0 +1,194 @@ +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. +Starting with 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. + + * IAUTH - Used to report connects, disconnects and errors for the + IAuth authorization mechanism. By default, log messages to this + subsystem go to the "NETWORK" server notice mask. + + * 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. + +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 Feature entry 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 a Feature line to +the configuration file that looks like "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 a Feature entry like "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 Feature entry like "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 Feature entry for this +configuration looks like "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 +Feature entry like "LOG" = "" "LEVEL" ""; here, + is yet again one of the subsystems described above, and + is one of the level names, also described above.