Implement "control = debug" ACL control. Fixes: #937

3 files changed, 35 insertions, 3 deletions

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 003ae6db8..02020dc50 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -1,4 +1,4 @@
-. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.79 2010/06/05 23:50:18 pdp Exp $
+. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.80 2010/06/06 00:25:46 pdp Exp $
 .
 . /////////////////////////////////////////////////////////////////////////////
 . This is the primary source of the Exim Manual. It is an xfpt document that is
@@ -25772,6 +25772,23 @@ warn  control = caseful_local_part
 Notice that we put back the lower cased version afterwards, assuming that
 is what is wanted for subsequent tests.
 
+.vitem &*control&~=&~debug/*&<&'options'&>
+.cindex "&ACL;" "enabling debug logging"
+.cindex "debugging" "enabling from an ACL"
+This control turns on debug logging, almost as though Exim had been invoked
+with &`-d`&, with the output going to a new logfile, by default called
+&'debuglog'&.  The filename can be adjusted with the &'tag'& option, which
+may access any variables already defined.  The logging may be adjusted with
+the &'opts'& option, which takes the same values as the &`-d`& command-line
+option.  Some examples (which depend on variables that don't exist in all
+contexts):
+.code
+      control = debug
+      control = debug/tag=.$sender_host_address
+      control = debug/opts=+expand+acl
+      control = debug/tag=.$message_exim_id/opts=+expand
+.endd
+
 .vitem &*control&~=&~enforce_sync*& &&&
        &*control&~=&~no_enforce_sync*&
 .cindex "SMTP" "synchronization checking"
diff --git a/doc/doc-txt/ChangeLog b/doc/doc-txt/ChangeLog
index 0591e4115..b89d1b44c 100644
--- a/doc/doc-txt/ChangeLog
+++ b/doc/doc-txt/ChangeLog
@@ -1,9 +1,10 @@
-$Cambridge: exim/doc/doc-txt/ChangeLog,v 1.622 2010/06/05 23:50:18 pdp Exp $
+$Cambridge: exim/doc/doc-txt/ChangeLog,v 1.623 2010/06/06 00:27:52 pdp Exp $
 
 Change log file for Exim from version 4.21
 -------------------------------------------
 
 Exim version 4.73
+-----------------
 
 PP/01 Date: & Message-Id: revert to normally being appended to a message,
       only prepend for the Resent-* case.  Fixes regression introduced in
@@ -33,6 +34,8 @@ PP/08 Bugzilla 926: switch ClamAV to use the new zINSTREAM API for content
 
 PP/09 Implemented reverse_ip expansion operator.
 
+PP/10 Bugzilla 937: provide a "debug" ACL control.
+
 
 Exim version 4.72
 -----------------
diff --git a/doc/doc-txt/NewStuff b/doc/doc-txt/NewStuff
index 35ed9a399..a8606870c 100644
--- a/doc/doc-txt/NewStuff
+++ b/doc/doc-txt/NewStuff
@@ -1,4 +1,4 @@
-$Cambridge: exim/doc/doc-txt/NewStuff,v 1.169 2010/06/05 23:50:18 pdp Exp $
+$Cambridge: exim/doc/doc-txt/NewStuff,v 1.170 2010/06/06 00:27:52 pdp Exp $
 
 New Features in Exim
 --------------------
@@ -51,6 +51,18 @@ Version 4.73
       ${reverse_ip:2001:0db8:c42:9:1:abcd:192.0.2.3}
        -> 3.0.2.0.0.0.0.c.d.c.b.a.1.0.0.0.9.0.0.0.2.4.c.0.8.b.d.0.1.0.0.2
 
+ 6. There is a new ACL control called "debug", to enable debug logging.
+    This allows selective logging of certain incoming transactions within
+    production environments, with some care.  It takes two options, "tag"
+    and "opts"; "tag" is included in the filename of the log and "opts"
+    is used as per the -d<options> command-line option.  Examples, which
+    don't all make sense in all contexts:
+
+      control = debug
+      control = debug/tag=.$sender_host_address
+      control = debug/opts=+expand+acl
+      control = debug/tag=.$message_exim_id/opts=+expand
+
 
 Version 4.72
 ------------