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. It is available in the CRB repository.
   ``/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