doc/readme.log

   1 Older versions of ircd had no consistent way of logging various
   2 actions.  Some things, such as G-lines, were written out to log files
   3 with names compiled into the server.  Others could only be logged
   4 through syslog.  Some required that their log files exist beforehand.
   5 Starting with u2.10.11, this situation has changed dramatically.
   6
   7 All logging in the server is now unified through a single logging
   8 subsystem.  Unfortunately, the server still does not generate all the
   9 logs that it could, and some more tuning is in store for the next
  10 major release of ircd.  Nevertheless, the logs that are generated are
  11 far more consistent, and those log messages may be sent to a given
  12 file, to syslog, or even to online operators--or any combination of
  13 these three methods.  This file is intended to describe configuration
  14 of the logging subsystem.
  15
  16 All logs are classified by a "subsystem" and a "level."  The subsystem
  17 is a major classification; each subsystem may be configured
  18 individually.  The level classification is used to indicate how
  19 important the message is; subsystems may be configured to omit log
  20 messages with less than a certain importance--not unlike syslog.
  21
  22 Levels
  23
  24 Levels are used to classify the importance of various log messages.
  25 The most important level is the "CRIT" level; the least important is
  26 the "DEBUG" level.  Each of the levels is also mapped to a
  27 corresponding syslog level, and some may even force generation of
  28 certain types of server notices.  Each importance level is described
  29 below.
  30
  31  * CRIT - Used for very critical notifications, such as server
  32    termination.  This is mapped to the corresponding "CRIT" syslog
  33    priority.  This will also generate server notices to the "OLDSNO"
  34    server notice mask.
  35
  36  * ERROR - Used to report important error conditions.  This is mapped
  37    to the corresponding "ERR" syslog priority.
  38
  39  * WARNING - Used to warn about certain conditions.  This is mapped to
  40    the corresponding "WARNING" syslog priority.
  41
  42  * NOTICE - Used for reporting important information.  This is mapped
  43    to the corresponding "NOTICE" syslog priority.
  44
  45  * TRACE - Used to tracing operation of the server.  This is mapped to
  46    the corresponding "INFO" syslog priority.
  47
  48  * INFO - Used for reporting unimportant but potentially useful
  49    information.  This is mapped to the corresponding "INFO" syslog
  50    priority.
  51
  52  * DEBUG - Used for reporting debugging information.  This is mapped
  53    to the corresponding "DEBUG" syslog priority.  This will also
  54    generate server notices to the "DEBUG" server notice mask.
  55
  56 Subsystems
  57
  58 All of the subsystems are described below, along with their default
  59 logging configuration.  There are no default log files to log to, and
  60 the default logging level is INFO (unless the server is compiled with
  61 debugging enabled)--this means that only notices of importance INFO or
  62 higher will be logged.
  63
  64  * SYSTEM - Used to report information that affects the server as a
  65    whole.  By default, log messages to this subsystem go nowhere.
  66
  67  * CONFIG - Used to report information concerning the configuration
  68    file.  By default, log messages to this subsystem go to the default
  69    syslog facility, which defaults to "USER," and to the "OLDSNO"
  70    server notice mask.
  71
  72  * OPERMODE - Used to report usage of /OPMODE and /CLEARMODE.  By
  73    default, log messages to this subsystem go to the "HACK4" server
  74    notice mask.
  75
  76  * GLINE - Used to report usage of /GLINE, particularly BADCHANs.  By
  77    default, log messages to this subsystem go to the "GLINE" server
  78    notice mask.
  79
  80  * JUPE - Used to report usage of /JUPE.  By default, log messages to
  81    this subsystem go to the "NETWORK" server notice mask.
  82
  83  * WHO - Used to report usage of the extended features of /WHO
  84    (/WHOX).  By default, log messages to this subsystem go nowhere.
  85
  86  * NETWORK - Used to report net junctions and net breaks.  By default,
  87    log messages to this subsystem go to the "NETWORK" server notice
  88    mask.
  89
  90  * OPERKILL - Used to report usage of /KILL by IRC operators.  By
  91    default, log messages to this subsystem go nowhere.
  92
  93  * SERVKILL - Used to report usage of /KILL by other servers.  By
  94    default, log messages to this subsystem go nowhere.
  95
  96  * USER - Used to report user sign-ons and sign-offs.  By default, log
  97    messages to this subsystem go nowhere.
  98
  99  * OPER - Used to report usage of /OPER, either successfully or
 100    unsuccessfully.  By default, log messages to this subsystem go to
 101    the "OLDREALOP" server notice mask.
 102
 103  * RESOLVER - Used to report error messages or other conditions from
 104    the resolver and authentication system.  By default, log messages
 105    to this subsystem go nowhere.
 106
 107  * SOCKET - Used to report problems with sockets.  By default, log
 108    messages to this subsystem go nowhere.
 109
 110  * IAUTH - Used to report connects, disconnects and errors for the
 111    IAuth authorization mechanism.  By default, log messages to this
 112    subsystem go to the "NETWORK" server notice mask.
 113
 114  * DEBUG - Used only when debugging is enabled.  All log messages to
 115    this subsystem go either to the console or to the debug log file
 116    compiled into the server, as well as to the "DEBUG" server notice
 117    mask.  This is the only subsystem with a default log file.
 118
 119 Configuration
 120
 121 The true power of the logging subsystem comes from its extremely
 122 flexible configuration.  The default server facility can be
 123 configured, as can the facility for each individual subsystem
 124 described above.  Moreover, administrators can configure the server to
 125 log to specific files, send selected log messages to operators
 126 subscribed to any server notice mask, and even change the default log
 127 level for each subsystem.
 128
 129 The logging subsystem has a set of tables mapping names to the
 130 numerical values used internally.  Subsystems, levels, syslog
 131 facilities, and server notice masks are all configured using strings.
 132 These tables even include special strings, such as "DEFAULT" and
 133 "NONE."  Each possible configuration piece is described below.
 134
 135 Default Syslog Facility
 136
 137 The IRC server has a default facility that it uses when sending log
 138 messages to syslog.  The default facility may be overridden for each
 139 individual subsystem, but the default itself can be changed with an
 140 appropriate Feature entry in the configuration file.  The facility
 141 normally defaults to "USER," but may be configured to be any of AUTH,
 142 CRON, DAEMON, LOCAL0, LOCAL1, LOCAL2, LOCAL3, LOCAL4, LOCAL5, LOCAL6,
 143 LOCAL7, LPR, MAIL, NEWS, USER, or UUCP.  Some systems also have the
 144 AUTHPRIV facility.  To configure this default, add a Feature line to
 145 the configuration file that looks like "LOG" = "<facility>";
 146 <facility> should be replaced with the string for the desired default
 147 syslog facility.
 148
 149 Log Files
 150
 151 Each subsystem may be configured to send its log messages to any
 152 single log file with a Feature entry like "LOG" = "<subsys>" "FILE"
 153 "<file>"; <subsys> should be replaced with one of the subsystem names
 154 described above, and <file> should be a file name for the log file.
 155 The file name may be relative to the server's data directory
 156 ("DPATH"), or it may be an absolute path name.  Note that if you're
 157 using chroot, these absolute path names will be relative to the
 158 server's root directory.
 159
 160 Logging to Syslog
 161
 162 By default, except for the CONFIG subsystem, no logs are sent to
 163 syslog.  This can be overridden using an Feature entry like "LOG" =
 164 "<subsys>" "FACILITY" "<facility>"; <subsys>, as above, should be
 165 replaced with one of the subsystem names described above, and
 166 <facility> must be one of the facility strings mentioned under
 167 "Default Syslog Facility."  The facility string may also be "NONE," to
 168 turn off syslog for that subsystem, and "DEFAULT," to use the server's
 169 default facility.  Please don't confuse a DEFAULT facility with the
 170 default for a particular subsystem; only the CONFIG subsystem defaults
 171 to DEFAULT, whereas all the rest default to NONE.
 172
 173 Logging via Server Notices
 174
 175 Log messages can be sent to online IRC operators.  Many subsystems
 176 actually default to this behavior, in fact.  For security, log
 177 messages containing IP addresses or other extremely sensitive data
 178 will never be sent via server notices, but all others can be sent to a
 179 specific server notice mask.  (For more information about server
 180 notice masks, please see doc/snomask.html.)  The available mask names
 181 are OLDSNO, SERVKILL, OPERKILL, HACK2, HACK3, UNAUTH, TCPCOMMON,
 182 TOOMANY, HACK4, GLINE, NETWORK, IPMISMATCH, THROTTLE, OLDREALOP,
 183 CONNEXIT, and DEBUG.  The special mask name "NONE" inhibits sending of
 184 server notices for a particular subsystem.  The Feature entry for this
 185 configuration looks like "LOG" = "<subsys>" "SNOMASK" "<mask>"; again,
 186 <subsys> is one of the subsystems described above, and <mask> is one
 187 of the mask names.
 188
 189 Setting Minimum Logging Level
 190
 191 The minimum log level for a particular subsystem may be set with an
 192 Feature entry like "LOG" = "<subsys>" "LEVEL" "<level>"; here,
 193 <subsys> is yet again one of the subsystems described above, and
 194 <level> is one of the level names, also described above.