allow "destination = NULL" for log debug { ... }

and include sample log debug section

doc/antora/modules/reference/pages/xlat/log.adoc

@@ -27,7 +27,7 @@ This function is normally used to _add_ a new log destination.  Any extra debug
 
 An existing log destination can be set multiple times.  The first time it is set, the log destination is added.  The second and subsequent times it is set, the log level is changed.  The server will not send duplicate messages to the same logging destination.
 
-If a filename is specified, then the first argument must be a log section which has `destination = files`.  If so, that section is used as a template for log configuration.  However, the given `filename` is used instead of the `filename` in the log section.
+If a filename is specified, then the first argument must be a log section which has `destination = files` or `destination=null`.  If so, that section is used as a template for log configuration.  However, `filename` passed to the function is used instead of any `file` specified in the named log section.
 
 This parameter allows for logging to go to a file which is specific to a particular request.
 

raddb/radiusd.conf.in

@@ -321,6 +321,32 @@ log {
 #	suppress_secrets = no
 }
 
+#
+#  Perform debug logging to a special file.
+#
+#  This log section is generally used for per-request debug logging.
+#  For example, the following function calls can be placed in an
+#  `unlang` block, where it will:
+#
+#	* delete any pre-exising debug log for this user
+#	  do not do this for EAP sessions, as they use multiple round trips.
+#	* use the 'log debug' section as a template
+#	* set the debug level for this request to '2'
+#	* over-ride the log file, and set it to be based on the `User-Name`.
+#
+#  The file will be closed when the request exits.  It is the admins
+#  responsibility to ensure that the debug files are periodically cleaned up.
+#  The server does not do this automatically.
+#
+#	%file.rm("${logdir}/debug/%{User-Name}.log")
+#	%log.destination('debug', 2, "${logdir}/debug/%{User-Name}.log")
+#
+log debug {
+	destination = null
+	colourise = no
+	timestamp = yes
+}
+
 #
 #  .ENVIRONMENT VARIABLES
 #

src/lib/server/log.c

@@ -1205,6 +1205,9 @@ int log_parse_section(CONF_SECTION *cs)
 		talloc_set_destructor(log, _log_free);
 		break;
 
+	case L_DST_NULL:
+		break;
+
 	default:		/* look for stdout / stderr? */
 		talloc_const_free(log_destination);
 		log_destination = NULL;

src/lib/unlang/xlat_builtin.c

@@ -1194,7 +1194,7 @@ static xlat_action_t xlat_func_log_dst(UNUSED TALLOC_CTX *ctx, UNUSED fr_dcursor
 
 	if (lvl) level = lvl->vb_uint32;
 
-	if (!file || (log->dst != L_DST_FILES)) {
+	if (!file || ((log->dst != L_DST_NULL) && (log->dst != L_DST_FILES))) {
 		request_log_prepend(request, log, level);
 		return XLAT_ACTION_DONE;
 	}
@@ -1207,6 +1207,7 @@ static xlat_action_t xlat_func_log_dst(UNUSED TALLOC_CTX *ctx, UNUSED fr_dcursor
 	/*
 	 *	Open the new filename.
 	 */
+	dbg->dst = L_DST_FILES;
 	dbg->file = talloc_strdup(dbg, file->vb_strvalue);
 	dbg->fd = open(dbg->file, O_WRONLY | O_CREAT | O_CLOEXEC);
 	if (!dbg->fd) {