update docs on "suppress_secrets"

diff --git a/doc/antora/modules/raddb/pages/radiusd.conf.adoc b/doc/antora/modules/raddb/pages/radiusd.conf.adoc
index 2032b2c98979fbc45538c169432ca8986e3d0d00..099dde22460a86f6b7af84e1a6b3ba264ab9ee8f 100644 (file)
--- a/doc/antora/modules/raddb/pages/radiusd.conf.adoc
+++ b/doc/antora/modules/raddb/pages/radiusd.conf.adoc
@@ -271,20 +271,37 @@ The exact values permitted here are _OS-dependent_.  You probably
 don't want to change this.
 
 
-Suppress "secret" values when printing them in debug mode.
+suppress_secrets:: Suppress "secret" values when printing
+them in debug mode.
 
 
-Setting this to "yes" means that the server prints a series
-of dots:
+Setting this to "yes" means that the server does not print
+the contents of "secret" values such as passwords.  It
+instead prints a place-holder value "<<< secret >>>", as
+follows:
 
-  .......
+...
+&User-Password = "<<< secret >>>"
+...
 
-instead of the value, for attributes which contain secret
-information.  e.g. User-Name, Tunnel-Password, etc.
+Note that secret values are tracked across string
+expansions, string modifications, concatenations, etc.!
+i.e. if a User-Password is placed into a Reply-Message,
+then the value of the Reply-Message is also marked
+"secret".
 
 This configuration is disabled by default.  It is extremely
-important for administrators to be able to debug user logins
-by seeing what is actually being sent.
+important for administrators to be able to debug user
+logins by seeing what is actually being sent.
+
+In most cases it is not useful to suppress secrets in an
+attempt to "be more secure".  Any administrator who can see
+the debug ouput is usually also able to view and/or modify
+the servers configuration (including passwords in
+databases!).  And any "low level" administrator who can
+only see the debug output will usually need to see the
+actual passwords in order to verify what the user is
+entering.
 
 
 

diff --git a/raddb/radiusd.conf.in b/raddb/radiusd.conf.in
index a566883a70c29f9f3e08ee125373120837c89801..8ae2a64d5ff0711cbca684166a13fd2a627fe0bd 100644 (file)
--- a/raddb/radiusd.conf.in
+++ b/raddb/radiusd.conf.in
@@ -303,20 +303,37 @@ log {
        #
        syslog_facility = daemon
 
-       #  Suppress "secret" values when printing them in debug mode.
+       #  suppress_secrets:: Suppress "secret" values when printing
+       #  them in debug mode.
        #
        #
-       #  Setting this to "yes" means that the server prints a series
-       #  of dots:
+       #  Setting this to "yes" means that the server does not print
+       #  the contents of "secret" values such as passwords.  It
+       #  instead prints a place-holder value "<<< secret >>>", as
+       #  follows:
        #
-       #    .......
+       #       ...
+       #       &User-Password = "<<< secret >>>"
+       #       ...
        #
-       #  instead of the value, for attributes which contain secret
-       #  information.  e.g. User-Name, Tunnel-Password, etc.
+       #  Note that secret values are tracked across string
+       #  expansions, string modifications, concatenations, etc.!
+       #  i.e. if a User-Password is placed into a Reply-Message,
+       #  then the value of the Reply-Message is also marked
+       #  "secret".
        #
        #  This configuration is disabled by default.  It is extremely
-       #  important for administrators to be able to debug user logins
-       #  by seeing what is actually being sent.
+       #  important for administrators to be able to debug user
+       #  logins by seeing what is actually being sent.
+       #
+       #  In most cases it is not useful to suppress secrets in an
+       #  attempt to "be more secure".  Any administrator who can see
+       #  the debug ouput is usually also able to view and/or modify
+       #  the servers configuration (including passwords in
+       #  databases!).  And any "low level" administrator who can
+       #  only see the debug output will usually need to see the
+       #  actual passwords in order to verify what the user is
+       #  entering.
        #
 #      suppress_secrets = no
 }