ITS#5904

CHANGES

@@ -70,6 +70,7 @@ OpenLDAP 2.4.14 Engineering
 		admin24 added limits chapter (ITS#5818)
 		admin24 access-control clarify global ACLS (ITS#5851,ITS#5852)
 		admin24 search on nested naming contexts (ITS#5788)
+		admin24 consistent loglevel documentation (ITS#5904)
 		slapd-bdb/hdb expansion on dncachesize behavior (ITS#5721)
 		slapo-constraint(5) example fix (ITS#5895)
 		slap*(8) man pages should mention slapd-config (ITS#5828)

doc/guide/admin/runningslapd.sdf

@@ -80,35 +80,30 @@ debugging levels are
 
 !block table; colaligns="RL"; align=Center; \
 	title="Table 7.1: Debugging Levels"
-Level	Description
--1	enable all debugging
-0	no debugging
-1	trace function calls
-2	debug packet handling
-4	heavy trace debugging
-8	connection management
-16	print out packets sent and received
-32	search filter processing
-64	configuration file processing
-128	access control list processing
-256	stats log connections/operations/results
-512	stats log entries sent
-1024	print communication with shell backends
-2048	print entry parsing debugging
+Level	Keyword		Description
+-1	any		enable all debugging
+0			no debugging
+1	(0x1 trace)	trace function calls
+2	(0x2 packets)	debug packet handling
+4	(0x4 args)	heavy trace debugging
+8	(0x8 conns)	connection management
+16	(0x10 BER)	print out packets sent and received
+32	(0x20 filter)	search filter processing
+64	(0x40 config)	configuration processing
+128	(0x80 ACL)	access control list processing
+256	(0x100 stats)	stats log connections/operations/results
+512	(0x200 stats2)	stats log entries sent
+1024	(0x400 shell)	print communication with shell backends
+2048	(0x800 parse)	print entry parsing debugging
+16384	(0x4000 sync)	syncrepl consumer processing
+32768	(0x8000 none)	only messages that get logged whatever log level is set
 !endblock
 
-You may enable multiple levels by specifying the debug option
-once for each desired level.  Or, since debugging levels are
-additive, you can do the math yourself. That is, if you want
-to trace function calls and watch the config file being
-processed, you could set level to the sum of those two levels
-(in this case, {{EX: -d 65}}).  Or, you can let slapd do the
-math, (e.g. {{EX: -d 1 -d 64}}).  Consult {{F: <ldap_log.h>}} for
-more details.
+You may enable multiple levels by specifying the debug option once for each desired level.  Or, since debugging levels are additive, you can do the math yourself. That is, if you want to trace function calls and watch the config file being processed, you could set level to the sum of those two levels (in this case, {{EX: -d 65}}).  Or, you can let slapd do the math, (e.g. {{EX: -d 1 -d 64}}).  Consult {{F: <ldap_log.h>}} for more details.
 
-Note: slapd must have been compiled with {{EX:-DLDAP_DEBUG}}
+Note: slapd must have been compiled with {{EX:--enable-debug}}
 defined for any debugging information beyond the two stats levels
-to be available.
+to be available (the default).
 
 
 H2: Starting slapd

doc/guide/admin/slapdconf2.sdf

@@ -176,40 +176,60 @@ or consult the table below. The possible values for <level> are:
 
 !block table; colaligns="RL"; align=Center; \
 	title="Table 5.1: Debugging Levels"
-Level	Keyword	Description
--1	Any	enable all debugging
-0		no debugging
-1	Trace	trace function calls
-2	Packets	debug packet handling
-4	Args	heavy trace debugging
-8	Conns	connection management
-16	BER	print out packets sent and received
-32	Filter	search filter processing
-64	Config	configuration processing
-128	ACL	access control list processing
-256	Stats	stats log connections/operations/results
-512	Stats2	stats log entries sent
-1024	Shell	print communication with shell backends
-2048	Parse	print entry parsing debugging
-4096	Cache	database cache processing
-8192	Index	database indexing
-16384	Sync	syncrepl consumer processing
+Level	Keyword		Description
+-1	any		enable all debugging
+0			no debugging
+1	(0x1 trace)	trace function callss
+2	(0x2 packets)	debug packet handling
+4	(0x4 args)	heavy trace debugging
+8	(0x8 conns)	connection management
+16	(0x10 BER)	print out packets sent and received
+32	(0x20 filter)	search filter processing
+64	(0x40 config)	configuration processing
+128	(0x80 ACL)	access control list processing
+256	(0x100 stats)	stats log connections/operations/results
+512	(0x200 stats2)	stats log entries sent
+1024	(0x400 shell)	print communication with shell backends
+2048	(0x800 parse)	print entry parsing debugging
+16384	(0x4000 sync)	syncrepl consumer processing
+32768	(0x8000 none)	only messages that get logged whatever log level is set
 !endblock
 
-\Example:
+The desired log level can be input as a single integer that
+combines the (ORed) desired levels, both in decimal or in hexadecimal 
+notation, as a list of integers (that are ORed internally), or as a list of the names that are shown between brackets, such that
+
+>		olcLogLevel 129
+>		olcLogLevel 0x81
+>		olcLogLevel 128 1
+>		olcLogLevel 0x80 0x1
+>		olcLogLevel acl trace
+
+are equivalent.
+
+\Examples:
 
-E: olcLogLevel: -1
+E: olcLogLevel -1
 
 This will cause lots and lots of debugging information to be
 logged.
 
-E: olcLogLevel: Conns Filter
+E: olcLogLevel conns filter
 
 Just log the connection and search filter processing.
 
+E: olcLogLevel none
+
+Log those messages that are logged regardless of the configured loglevel. This
+differs from setting the log level to 0, when no logging occurs. At least the
+{{EX:None}} level is required to have high priority messages logged.
+
 \Default:
 
-E: olcLogLevel: Stats
+E: olcLogLevel stats
+
+Basic stats logging is configured by default. However, if no olcLogLevel is
+defined, no logging occurs (equivalent to a 0 level).
 
 
 H4: olcReferral <URI>

doc/guide/admin/slapdconfig.sdf

@@ -136,40 +136,67 @@ and operation statistics should be syslogged (currently logged to
 the {{syslogd}}(8) {{EX:LOG_LOCAL4}} facility). You must have
 configured OpenLDAP {{EX:--enable-debug}} (the default) for this
 to work (except for the two statistics levels, which are always
-enabled).  Log levels are additive. To display what numbers
-correspond to what kind of debugging, invoke slapd with {{EX:-d?}}
+enabled). Log levels may be specified as integers or by keyword.
+Multiple log levels may be used and the levels are additive. To display what
+numbers correspond to what kind of debugging, invoke slapd with {{EX:-d?}}
 or consult the table below. The possible values for <integer> are:
 
 !block table; colaligns="RL"; align=Center; \
 	title="Table 6.1: Debugging Levels"
-Level	Description
--1	enable all debugging
-0	no debugging
-1	trace function calls
-2	debug packet handling
-4	heavy trace debugging
-8	connection management
-16	print out packets sent and received
-32	search filter processing
-64	configuration file processing
-128	access control list processing
-256	stats log connections/operations/results
-512	stats log entries sent
-1024	print communication with shell backends
-2048	print entry parsing debugging
+Level	Keyword		Description
+-1	any		enable all debugging
+0			no debugging
+1	(0x1 trace)	trace function calls
+2	(0x2 packets)	debug packet handling
+4	(0x4 args)	heavy trace debugging
+8	(0x8 conns)	connection management
+16	(0x10 BER)	print out packets sent and received
+32	(0x20 filter)	search filter processing
+64	(0x40 config)	configuration processing
+128	(0x80 ACL)	access control list processing
+256	(0x100 stats)	stats log connections/operations/results
+512	(0x200 stats2)	stats log entries sent
+1024	(0x400 shell)	print communication with shell backends
+2048	(0x800 parse)	print entry parsing debugging
+16384	(0x4000 sync)	syncrepl consumer processing
+32768	(0x8000 none)	only messages that get logged whatever log level is set
 !endblock
 
-\Example:
+The desired log level can be input as a single integer that
+combines the (ORed) desired levels, both in decimal or in hexadecimal 
+notation, as a list of integers (that are ORed internally), or as a list of the names that are shown between brackets, such that
+
+>		loglevel 129
+>		loglevel 0x81
+>		loglevel 128 1
+>		loglevel 0x80 0x1
+>		loglevel acl trace
+
+are equivalent.
+
+\Examples:
 
 E: loglevel -1
 
 This will cause lots and lots of debugging information to be
 logged.
 
+E: loglevel conns filter
+
+Just log the connection and search filter processing.
+
+E: loglevel none
+
+Log those messages that are logged regardless of the configured loglevel. This
+differs from setting the log level to 0, when no logging occurs. At least the
+{{EX:None}} level is required to have high priority messages logged.
+
 \Default:
 
-E: loglevel 256
+E: loglevel stats
 
+Basic stats logging is configured by default. However, if no loglevel is
+defined, no logging occurs (equivalent to a 0 level).
 
 H4: objectclass <{{REF:RFC4512}} Object Class Description>