1 files changed, 83 insertions, 0 deletions
diff --git a/README.redhat.rst b/README.redhat.rst
new file mode 100644
index 0000000..a834aae
--- /dev/null
+++ b/README.redhat.rst
@@ -0,0 +1,83 @@
+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