--- /dev/null
+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" = "<facility>";
+<facility> 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" = "<subsys>" "FILE"
+"<file>"; <subsys> should be replaced with one of the subsystem names
+described above, and <file> 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" =
+"<subsys>" "FACILITY" "<facility>"; <subsys>, as above, should be
+replaced with one of the subsystem names described above, and
+<facility> 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" = "<subsys>" "SNOMASK" "<mask>"; again,
+<subsys> is one of the subsystems described above, and <mask> 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" = "<subsys>" "LEVEL" "<level>"; here,
+<subsys> is yet again one of the subsystems described above, and
+<level> is one of the level names, also described above.