INSTALL-BMX.txt

mod_bmx Basic Management Extensions for Apache

See the NOTICE file distributed with this work for information
regarding copyright ownership.  See the LICENSE file distributed
with this work for information regarding licensing.
=====================================================================

Please see the README.txt file for an overview of the BMX module
as well as API documentation details. You will also find source
code documentation in HTML form (generated by doxygen) within the
docs/html directory.

Requirements:
-------------

Building from the distributed tarball:
* Apache 2.0.49+, 2.2.0+, 2.4.0+
    - with headers, DSO support (mod_so, enabled with --enable-so), and apxs
* GNU Make
* C Compiler (tested with GNU GCC)
* Perl (for apxs)

Building Instructions:
----------------------

1. Install Apache (from RPM or by hand or however you prefer)

2. If the desired 'apxs' is in your PATH, then simply run
     ./configure.apxs

3. If 'apxs' is not in your PATH, or you are building for a specific httpd
     APXS=/path/to/your/apxs ./configure.apxs

4. Compile it by running
    make

5. (optional) Install it by running
    make install
    - This will automatically insert LoadModule statements into your
      httpd.conf to enable BMX and all available plugins (including the
      example module).

- See the "Configuration" section below for instructions on setting up your
  httpd.conf before starting Apache for the first time.


Alternate in-tree build
-----------------------

1. Unpack the httpd sources

2. Unpack the bmx sources on top of it, such that modules/bmx/ is
   aligned with the other modules/ trees. 

Then, either;

3.0. Re- ./buildconf to include the modules/bmx/ tree in the standard 
     build ./configure options.

3.1. ./configure --enable-bmx --enable-bmx-vhost --enable-bmx-status
     then make and make install as usual (or include bmx etc in the module
     list with traditional --enable-[modules|mods-static|mods-shared] options).
 
- or -
    
3.0. [WARNING: This option may not behave correctly for multiple modules]
     To build the modules in-tree, without the re- ./buildconf step, when
     building httpd 2.2 and later, you may simply include;

     ./configure --with-module=bmx:bmx \
                 --with-module=bmx:bmx_status \
                 --with-module=bmx:bmx_vhost \
     ...


Building Documentation
----------------------

6. (optional) Build documentation by running
    make docs
    - This will run doxygen to update the HTML docs in the docs/html
      directory.

7. (optional) If you built the doxygen documentation, you can also
   produce a PDF of the documentation by doing the following:
    cd docs/latex
    make


Configuration:
--------------

Configuration of mod_bmx is very straightforward. First, include the proper
LoadModule directives for each BMX plugin you require (the mod_bmx core
module is always required whenever using any other mod_bmx_* plugin).

Next, you must enable BMX Query service from at least one location. For
example, to service BMX Queries from http://localhost/bmx, you would add
the following to your httpd.conf:

<Location /bmx>
    SetHandler bmx-handler
</Location>

You may wish to restrict this to a certain Virtual Host by placing the
above within a <VirtualHost> section of your configuration.

You can also combine the above with Basic Authentication (password auth).
Please refer to the Apache documentation for details:
http://httpd.apache.org/docs/2.0/howto/auth.html

One example of Basic Authenticated BMX Query interface:

<Location /bmx>
    SetHandler bmx-handler
    AuthType Basic
    AuthName "BMX Query Interface"
    AuthUserFile /usr/local/apache/passwd/passwords
    Require group bmx
</Location>


Available Directives:
---------------------

LoadModule (required for each BMX plugin needed)
    Use the 'LoadModule' directive to load BMX plugins into Apache,
    for example:

    LoadModule bmx_module         modules/mod_bmx.so
    LoadModule bmx_status_module  modules/mod_bmx_status.so
    LoadModule bmx_vhost_module   modules/mod_bmx_vhost.so

BMXVHostDBMFilename (optional)
    Use BMXVhostDBMFilename to specify the name of the file where
    BMX will store VHost data while Apache is shut down. The default
    is 'logs/bmx_vhost.db' which means mod_bmx_vhost will store the
    DBM file under your logs directory.

BMXVHostLockFilename (optional)
    Use BMXVHostLockFilename to specify the name of the lock file
    that mod_bmx_vhost will use to protect access to the persistent
    DBMFilename above. The default is 'logs/bmx_vhost.db.lock" which
    means mod_bmx_vhost will store a lock file under your logs directory.


$Id: INSTALL.txt,v 1.4 2007/11/05 22:15:44 aaron Exp $