[irc/quakenet/snircd.git] / doc / 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.
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.
Commit	Line	Data
189935b1	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.