Release Polish Step 1 / README + smart.conf

README.md

@@ -431,26 +431,6 @@ Typical access URLs:
 
 For production use, HTTPS should be preferred.
 
-## Native helper logging
-
-The native helper programs `check_login` and `smart_userlist` read their log
-destination and verbosity from `smart.conf` when called by the WebUI.
-
-They use the same Perl frontend settings:
-
-```perl
-$smart_log_path = '/var/log/mars_nwe/smart.log';
-$smart_debug_level = 'info';
-```
-
-The generated `config.h` also provides fallback defaults for these values, so
-the helpers can still write useful diagnostics when they are executed manually
-or before `smart.conf` could be loaded.
-
-`check_login` logs authentication and authorization results, but never logs the
-submitted password.  `smart_userlist` keeps its tab-separated user-list output
-on stdout unchanged and writes diagnostics only to the configured log file.
-
 ## Unix user discovery helper
 
 The WebUI user editor can assign a MARS_NWE bindery user to a local Unix user.
@@ -471,6 +451,38 @@ $smart_userlist_path = '/usr/libexec/mars_nwe/smart_userlist';
 If the path is not set explicitly, SMArT falls back to the standard libexec
 location generated by the build system.
 
+When called by the WebUI, the helper also reads `smart.conf` so diagnostics can
+use `$smart_log_path` and `$smart_debug_level`.
+
 ## Summary
 
 SMArT is now an integrated part of the `mars_nwe` release. It includes a dedicated `nwwebui` service, form-based sessions, PAM authentication with configurable administrator group restriction, service control, validation pages, import helpers, improved bindery command handling, and configurable logging.
+
+## Logging overview
+
+SMArT uses two related but separate log-level settings:
+
+- `$nw_log_level` controls the native `nwwebui` HTTP/HTTPS frontend and writes
+  to `$nw_log_file`.
+- `$smart_debug_level` controls the Perl application scripts and native helper
+  tools such as `check_login` and `smart_userlist`; these messages are written
+  to `$smart_log_path`.
+
+Both settings use the same named levels:
+
+```text
+error
+warning
+info
+debug
+trace
+```
+
+`info` is the recommended normal setting.  Use `debug` or `trace` only while
+troubleshooting a specific problem.  Trace logging may include submitted bindery
+payload data and can produce a large amount of output.
+
+The login helper logs authentication and authorization results, but never logs
+the submitted password.  `smart_userlist` keeps its tab-separated user list on
+stdout and writes diagnostics only to the configured SMArT log file.
+

smart.conf.cmake

@@ -62,9 +62,13 @@ $smart_static_dir = '@MARS_NWE_INSTALL_FULL_LIBEXECDIR@/static';
 $smart_log_path = '@MARS_NWE_LOG_DIR@/smart.log';
 
 # Path to the PAM-based login helper used for SMArT authentication.
+# The helper reads this smart.conf file for logging settings and the required
+# admin group.  Passwords are never written to the log.
 $smart_check_login = '@MARS_NWE_INSTALL_FULL_LIBEXECDIR@/check_login';
 
 # Path to the native Unix-user enumeration helper used by the user editor.
+# The helper writes diagnostics to $smart_log_path and keeps the user list on
+# stdout for the WebUI.
 $smart_userlist_path = '@MARS_NWE_INSTALL_FULL_LIBEXECDIR@/smart_userlist';
 
 # Unix group allowed to log in to the SMArT/nwwebui admin interface.
@@ -76,7 +80,7 @@ $smart_userlist_path = '@MARS_NWE_INSTALL_FULL_LIBEXECDIR@/smart_userlist';
 # existing installations: the root user is allowed because its primary Unix
 # group is normally also "root".  Do not add normal users to the "root" group.
 #
-# For delegated administration, use a dedicated group instead, for example:
+# For delegated administration, build with a dedicated group, for example:
 #
 #   cmake -DMARS_NWE_SMART_ADMIN_GROUP=nwadmin ...
 #   groupadd nwadmin
@@ -86,8 +90,6 @@ $smart_userlist_path = '@MARS_NWE_INSTALL_FULL_LIBEXECDIR@/smart_userlist';
 # login session before NSS/PAM reports the new membership.
 $smart_admin_group = '@MARS_NWE_SMART_ADMIN_GROUP@';
 
-
-
 # Path to the SMArT service-control helper.
 $smart_control_path = '@MARS_NWE_INSTALL_FULL_LIBEXECDIR@/control';
 
@@ -130,6 +132,9 @@ $nw_bind_ip = '0.0.0.0';
 
 # Log level used by the native nwwebui frontend service.
 #
+# This controls the C-based HTTP/HTTPS frontend process and is written to
+# $nw_log_file.  It is separate from $smart_debug_level below.
+#
 # Supported values, from quiet to verbose:
 #
 #   error   - only real errors
@@ -182,14 +187,13 @@ $nw_key_file = '@MARS_NWE_INSTALL_FULL_CONFDIR@/server.key';
 $smart_session_dir = '/run/mars-nwe-webui';
 $smart_session_timeout = 3600;
 
-
-# SMArT Perl logging verbosity.
+# SMArT Perl/helper logging verbosity.
 #
-# This controls log messages written by the Perl CGI-style helper scripts
-# such as apply.pl.  The messages are written to the SMArT log file configured
-# for the WebUI, normally:
+# This controls log messages written by the Perl CGI-style helper scripts and
+# native SMArT helper tools such as apply.pl, check_login and smart_userlist.
+# These messages are written to:
 #
-#   /var/log/mars_nwe/smart.log
+#   $smart_log_path
 #
 # Supported values, from quiet to verbose:
 #
@@ -203,6 +207,11 @@ $smart_session_timeout = 3600;
 #
 #   $smart_debug_level = 'info';
 #
+# Use 'debug' or 'trace' only while troubleshooting a concrete problem.  Trace
+# logging may include submitted bindery payload data and can produce a lot of
+# output.  After debugging, switch back to 'info'.
+$smart_debug_level = 'info';
+#
 # Use 'trace' only while debugging a concrete problem.  Trace logging may
 # include submitted bindery payload data and can produce a lot of log output.
 # After debugging, switch back to 'info'.