| Red Hat Specific mod_auth_mellon Information |
| ============================================ |
| |
| This README contains information specific to Red Hat's distribution of |
| ``mod_auth_mellon``. |
| |
| Diagnostic Logging |
| |
| |
| Diagnostic logging can be used to collect run time information to help |
| diagnose problems with your ``mod_auth_mellon`` deployment. Please see |
| the "Mellon Diagnostics" section in the Mellon User Guide for more |
| details. |
| |
| How to enable diagnostic logging on Red Hat systems |
| ``````````````````````````````````````````````````` |
| |
| Diagnostic logging adds overhead to the execution of |
| ``mod_auth_mellon``. The code to emit diagnostic logging must be |
| compiled into ``mod_auth_mellon`` at build time. In addition the |
| diagnostic log file may contain security sensitive information which |
| should not normally be written to a log file. If you have a |
| version of ``mod_auth_mellon`` which was built with diagnostics you |
| can disable diagnostic logging via the ``MellonDiagnosticsEnable`` |
| configuration directive. However given human nature the potential to |
| enable diagnostic logging while resolving a problem and then forget to |
| disable it is not a situation that should exist by default. Therefore |
| given the overhead consideration and the desire to avoid enabling |
| diagnostic logging by mistake the Red Hat ``mod_auth_mellon`` RPM's |
| ship with two versions of the ``mod_auth_mellon`` Apache module. |
| |
| 1. The ``mod_auth_mellon`` RPM contains the normal Apache module |
| ``/usr/lib*/httpd/modules/mod_auth_mellon.so`` |
| |
| 2. The ``mod_auth_mellon-diagnostics`` RPM contains the diagnostic |
| version of the Apache module |
| ``/usr/lib*/httpd/modules/mod_auth_mellon-diagnostics.so`` |
| |
| Because each version of the module has a different name both the |
| normal and diagnostic modules can be installed simultaneously without |
| conflict. But Apache will only load one of the two modules. Which |
| module is loaded is controlled by the |
| ``/etc/httpd/conf.modules.d/10-auth_mellon.conf`` config file which |
| has a line in it which looks like this:: |
| |
| LoadModule auth_mellon_module modules/mod_auth_mellon.so |
| |
| To load the diagnostics version of the module you need to change the |
| module name so it looks like this:: |
| |
| LoadModule auth_mellon_module modules/mod_auth_mellon-diagnostics.so |
| |
| **Don't forget to change it back again when you're done debugging.** |
| |
| You'll also need to enable the collection of diagnostic information, |
| do this by adding this directive at the top of your Mellon conf.d |
| config file or inside your virtual host config (diagnostics are per |
| server instance):: |
| |
| MellonDiagnosticsEnable On |
| |
| .. NOTE:: |
| Some versions of the Mellon User Guide have a typo in the name of |
| this directive, it incorrectly uses ``MellonDiagnosticEnable`` |
| instead of ``MellonDiagnosticsEnable``. The difference is |
| Diagnostics is plural. |
| |
| The Apache ``error_log`` will contain a message indicating how it |
| processed the ``MellonDiagnosticsEnable`` directive. If you loaded the |
| standard module without diagnostics you'll see a message like this:: |
| |
| MellonDiagnosticsEnable has no effect because Mellon was not |
| compiled with diagnostics enabled, use |
| ./configure --enable-diagnostics at build time to turn this |
| feature on. |
| |
| If you've loaded the diagnostics version of the module you'll see a |
| message in the ``error_log`` like this:: |
| |
| mellon diagnostics enabled for virtual server *:443 |
| (/etc/httpd/conf.d/my_server.conf:7) |
| ServerName=https://my_server.example.com:443, diagnostics |
| filename=logs/mellon_diagnostics |
| |