Document and handle include ordering for stop-processing

Stop-processing block prefixes (!!, ++, ::) can only suppress rules
that follow in the parsed order.  A snippet in /etc/syslog.d/ cannot
gate rules that were already parsed from the main config file above
the include line.

Fix this by moving the include directive in the shipped syslog.conf to
sit before the general catch-all rules, so snippets are evaluated first
and their stop-blocks take effect.

Document the ordering constraint in two places in syslog.conf(5):
in the include description, where the interaction is explained and
the shipped file's structure is called out; and in the Stop Processing
example section, where a direct note warns users who place stop-blocks
in syslog.d/ snippets.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>

Author: troglobit

man/syslog.conf.5

@@ -390,9 +390,28 @@ The
 option can be used to include all files with names ending in '.conf' and
 not beginning with a '.' contained in the directory following the
 keyword.  This keyword can only be used in the first level configuration
-file.  The included example
+file.  Included files are parsed in glob order and their rules are
+inserted into the rule list at the position of the
+.Ql include
+line.
+.Pp
+This ordering matters for stop-processing blocks
+.Pq Ql !! , ++ , ::
+\&: such a block can only suppress rules that appear
+.Em after
+it in the parsed list.  Rules already processed before the
+.Ql include
+line are unaffected.  For snippets in
+.Pa /etc/syslog.d/
+to be able to prevent messages from reaching the general catch-all rules
+in the main configuration file, the
+.Ql include
+line must appear
+.Em before
+those catch-all rules.  The shipped
 .Pa /etc/syslog.conf
-has the following at the end:
+is structured accordingly.
+.Pp
 .Bd -literal -offset indent
 #
 # Drop your subsystem .conf file in /etc/syslog.d/
@@ -908,6 +927,20 @@ are routed to their own log and nowhere else:
 daemon.info                  /var/log/spamd
 !*
 .Ed
+.Pp
+.Sy Note:
+stop-processing only suppresses rules that follow the matching rule in
+the parsed order.
+A stop-block placed in a snippet under
+.Pa /etc/syslog.d/
+cannot suppress rules already parsed from the main configuration file
+above the
+.Ql include
+line.
+Place the
+.Ql include
+directive before any general catch-all rules so that snippets are
+evaluated first.
 .Ss Critical
 This stores all messages of priority
 .Ql crit

syslog.conf

@@ -7,7 +7,14 @@
 # First some standard log files.  Log by facility.
 #
 auth,authpriv.*			 /var/log/auth.log
-*.*;auth,authpriv.none		-/var/log/syslog
+
+#
+# Include all config files in /etc/syslog.d/ before the catch-all rules
+# below.  This allows snippets to use stop-processing block prefixes
+# (!!, ++, ::) to capture messages exclusively, preventing them from
+# also being matched by the general rules that follow.
+#
+include /etc/syslog.d/*.conf
 
 #cron.*				/var/log/cron.log
 #daemon.*			-/var/log/daemon.log
@@ -16,6 +23,8 @@ kern.*				-/var/log/kern.log
 mail.*				-/var/log/mail.log
 #user.*				-/var/log/user.log
 
+*.*;auth,authpriv.none		-/var/log/syslog
+
 #
 # Logging for the mail system.  Split it up so that
 # it is easy to write scripts to parse these files.
@@ -77,8 +86,3 @@ secure_mode 1
 #
 #rotate_size  1M
 #rotate_count 5
-
-#
-# Include all config files in /etc/syslog.d/
-#
-include /etc/syslog.d/*.conf