From 30a41049bef4e0368b040451f4173fda21dd9773 Mon Sep 17 00:00:00 2001 From: Jacob Shivers Date: Mon, 7 Mar 2022 14:19:20 -0500 Subject: [PATCH] KRB5_TRACE documentation for gssproxy Added KRB5_TRACE.md to provide a brief overview on how to enable low level Kerberos tracing below gssapi via KRB5_TRACE. Updated gssproxy.conf man page to cite newly added doc when mentioning KRB5_TRACE behavior. Signed-off-by: Jacob Shivers --- docs/KRB5_TRACE.md | 36 ++++++++++++++++++++++++++++++++++++ man/gssproxy.conf.5.xml | 2 +- 2 files changed, 37 insertions(+), 1 deletion(-) create mode 100644 docs/KRB5_TRACE.md diff --git a/docs/KRB5_TRACE.md b/docs/KRB5_TRACE.md new file mode 100644 index 0000000..6a23760 --- /dev/null +++ b/docs/KRB5_TRACE.md @@ -0,0 +1,36 @@ +# Setting KRB5_TRACE for gssproxy + +Enabling `KRB5_TRACE` output as described in `# man gssproxy.conf`: + +**At level 3 and above, KRB5_TRACE output is logged. If KRB5_TRACE was already set in the execution environment, trace output is sent to its value instead.** + +can be done either by including `KRB5_TRACE=/path/to/location` when executing gssproxy at the command line or by including a location within a drop file loaded by systemd. Systemd uses unix sockets to redirect outputs to the journal, and this means `/dev/stderr` ends up pointing to a name that cannot be used as a path to open the stderr descriptor. A drop file is necessary to record `KRB5_TRACE` information as gssproxy directs `KRB5_TRACE` to `/dev/stderr` by default. + +The output can be directed to any location, but gssproxy only has write access to `/var/lib/gssproxy` by default. This means that for a host system using SELinux either a custom module policy will need to be created or SELinux will need to be put into permissive mode. + +As setting `KRB5_TRACE` output is not designed to be continually logged nor treated as traditional log output, it is recommended to direct the trace output to `/var/lib/gssproxy`. + +- Increase gssproxy debugging so that `KRB5_TRACE` information is logged as described in `# man gssproxy.conf`. + +~~~~ +# echo ' debug_level = 3' >> /etc/gssproxy/gssproxy.conf +~~~~ + + - Create a drop file for gssproxy to log `KRB5_TRACE` output to a file under `/var/lib/gssproxy` + +~~~~ +# mkdir /etc/systemd/system/gssproxy.service.d + +# cat < /etc/systemd/system/gssproxy.service.d/99-trace.conf +[Service] +Environment=KRB5_TRACE=/var/lib/gssproxy/gssproxy.krb5_trace +EOF +~~~~ + + - Reload the service files and restart the `gssproxy` service + +~~~~ +# systemctl daemon-reload + +# systemctl restart gssproxy +~~~~ diff --git a/man/gssproxy.conf.5.xml b/man/gssproxy.conf.5.xml index f02b1d3..e778583 100644 --- a/man/gssproxy.conf.5.xml +++ b/man/gssproxy.conf.5.xml @@ -216,7 +216,7 @@ At level 3 and above, KRB5_TRACE output is logged. If KRB5_TRACE was already set in the execution environment, trace output is sent to its value - instead. + instead. Refer to docs/KRB5_TRACE.md for more information. Default: 1 if debug is true, otherwise 0