diff --git a/README.md b/README.md index 04a1215..8d53aa2 100644 --- a/README.md +++ b/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. + diff --git a/smart.conf.cmake b/smart.conf.cmake index 6327420..cfc6699 100644 --- a/smart.conf.cmake +++ b/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'.