From: Alan T. DeKok <aland@freeradius.org>
Date: Fri, 31 May 2024 11:54:21 +0000 (-0400)
Subject: update docs on "suppress_secrets"
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=fb948827294b72ea96cc36ad8008035c772a8ae3;p=thirdparty%2Ffreeradius-server.git

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 2032b2c9897..099dde22460 100644
--- 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 a566883a70c..8ae2a64d5ff 100644
--- 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
 }