mod_injection Users Manual

Peter Jones

pjones@pmade.org
    

Copyright  2002, 2003 by Peter Jones (http://pmade.org/pjones/)

This is the manual for the mod_injection Apache module.

The latest version of this manual can be found at http://pmade.org/pjones/
software/mod_injection/.

Redistribution and use in source (SGML DocBook) and 'compiled' forms (SGML,
HTML, PDF, PostScript, RTF and so forth) with or without modification, are
permitted provided that the following conditions are met:

 1. Redistributions of source code (SGML DocBook) must retain the above
    copyright notice, this list of conditions and the following disclaimer
    as the first lines of this file unmodified.
   
 2. Redistributions in compiled form (transformed to other DTDs, converted
    to PDF, PostScript, RTF and other formats) must reproduce the above
    copyright notice, this list of conditions and the following disclaimer
    in the documentation and/or other materials provided with the
    distribution.
   
    Important: THIS DOCUMENTATION IS PROVIDED BY THE AUTHORS "AS IS" AND
    ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY
    DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
    OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
    STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
    IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
    POSSIBILITY OF SUCH DAMAGE.
   
---------------------------------------------------------------------------

Table of Contents
1. Introduction
   
    1.1. What is mod_injection?
    1.2. Features
   
2. Building and Installing
3. Apache Configuration
   
    3.1. Loading the Module
    3.2. Enabling the Module
    3.3. Setting the MIME Type
    3.4. Configuration Reference
   
A. Requirements
B. Revision History
   
    B.1. Version 0.3.1
    B.2. Version 0.3.0
    B.3. Version 0.2.0
    B.4. Version 0.1.0
   
C. Credits

---------------------------------------------------------------------------

Chapter 1. Introduction

1.1. What is mod_injection?

mod_injection is an Apache 2.0.X filter module. It allows you to inject
text in the HTTP response after a HTML tag or after any given text string.
The main intention of this module is to add a banner to several HTML pages
on the fly.

---------------------------------------------------------------------------

1.2. Features

mod_injection has the following features.

  * Injection can happen after any HTML tag (default is the BODY tag).
   
  * Injection can also happen after a specific text string has been seen in
    the output.
   
  * Injection of a string from the Apache configuration file.
   
  * Injection of an entire URI.
   
  * Injection is based on the Content-Type. You can specify which MIME
    types you want to inject for.
   
---------------------------------------------------------------------------

Chapter 2. Building and Installing

This section will show you how to install mod_injection using the supplied
Makefiles.

  * Make sure that apxs is either in your path or make sure that you give
    it to make like this: make APXS=/path/to/apxs
   
  * From the top directory, run make. This must be GNU make and on some
    systems it is called gmake.
   
  * After everything is done compiling you can run make install.
   
  * Update your Apache configuration file.
   
---------------------------------------------------------------------------

Chapter 3. Apache Configuration

3.1. Loading the Module

The first thing that you need to do is load mod_injection. If your module
directory is called modules you can load mod_injection with the following
Apache configuration directive:

    LoadModule injection_module modules/mod_injection.so


---------------------------------------------------------------------------

3.2. Enabling the Module

Like other filter modules, there are many different ways to enable
mod_injection. If you wanted to link mod_injection to a file extension you
could do the following.

    AddOutputFilter INJECTION .html



Most likely you are going to want to filter all files under a given
directory regardless of their file extension. Here is an example of an
Apache directory directive that uses mod_injection.

    <Directory />
        SetOutputFilter INJECTION
        InjectString "<h1>Injected</h1>"
    </Directory>


---------------------------------------------------------------------------

3.3. Setting the MIME Type

By default, mod_injection only filters content that has a MIME type of text
/html. You can override this using the InjectType configuration directive.

This directive can be repeated as many times as you wish. It can also
contain shell style glob patterns. Here is an example that tells
mod_injection to filter any content that has a MIME type that begins with
text/.

    InjectType text/*


---------------------------------------------------------------------------

3.4. Configuration Reference

This final section on configuration will explain all the directives that
mod_injection can use.

  * InjectTag - Set the tag to inject after. Example: InjectTag title
   
  * InjectAfter - Set a string to find and inject after. Example:
    InjectAfter "<!-- here -->"
   
  * InjectString - Set a string to inject at the injection point. Example:
    InjectString "<h1>Injected!<h1>"
   
  * InjectURI - Set the name of a URI that should be injected at the
    injection point. Example: InjectURI /injectme.html
   
  * InjectType - Add a MIME type to filter. If you don't use this, the
    default type is text/html. This option can also have shell style glob
    patterns like text/*.
   
    Note: You cannot use InjectString and InjectURI in the same location.
    Only use one at a time.
   
    Note: You cannot use InjectTag and InjectAfter in the same location.
    Only use one at a time.
   
---------------------------------------------------------------------------

Appendix A. Requirements

mod_injection should compile anywhere that Apache does. You need the
following software tools to build mod_injection.

Required Software

  * The Apache web server, at least version 2.0.40.
   
  * The same C compiler you used to compile Apache.
   
  * GNU Make (since the Apache build Makefiles use GNU specific code).
   
  * The apxs program that comes with Apache.
   
---------------------------------------------------------------------------

Appendix B. Revision History

B.1. Version 0.3.1

February 04, 2003

  * Fixed a bug where mod_injection would try to run on a response that
    contained no body. This would cause a core dump because mod_injection
    would try to inspect a NULL content type header.
   
---------------------------------------------------------------------------

B.2. Version 0.3.0

October 18, 2002

  * Added InjectTag to set the name of the tag to inject after. Default is
    still BODY.
   
  * Added InjectAfter so you can set a string to inject after.
   
---------------------------------------------------------------------------

B.3. Version 0.2.0

October 17, 2002

  * Updated for Apache filter API change. This change requires you to be
    using at least version 2.0.40 of the Apache web server.
   
  * Removed the InjectFile directive for security reasons. You can use the
    InjectURI directive to get the same results.
   
  * Added some safety checks to make sure the configuration is sane.
   
  * Optimized the code, mod_injection works much faster now.
   
---------------------------------------------------------------------------

B.4. Version 0.1.0

May 19, 2002

First public version.

---------------------------------------------------------------------------

Appendix C. Credits

mod_injection was written by Peter Jones.

I also would like to say thank you to Sebastian Wolfgarten for including
mod_injection in his book "Apache Webserver 2.0".

---------------------------------------------------------------------------
