Blame SOURCES/README.redhat.rst

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