$Id: README.txt,v 1.2 2001/06/10 18:32:45 carlos Exp $


------------------------------------------------------------
                 SQL Include Apache module
                (C) 2001 by Marcin Orlowski
------------------------------------------------------------
  carlos@amiga.com.pl          http://wfmh.org.pl/~carlos/
------------------------------------------------------------
                         W.F.M.H.


What is it?
------------

mod_sqlinclude is an Apache module which implements Include-alike
command, which, as its origin, includes the external data into
Apache configuration file, but instead of taking the real files
SQLInclude fetches and includes data from MySQL database.


Requirements
--------------

 - MySQL database server (http://mysql.com)
 - Apache web server

The modules was written, and tested against

 - Server version: Apache/1.3.19 (Unix) Debian/GNU
 - mysql  Ver 11.15 Distrib 3.23.37,

under GNU Debian/Linux, but it should run with other (older and newer)
versions too, as it does not use any version specific features.


How to compile and install the module?
---------------------------------------

To compile the module you will have to have developer files for mysql
and apache installed (under debian look for apache-dev and mysql-dev
packages)

 - unpack the archive
 - enter into the directory that holds
   the upacked source code (mod_sqlinclude.c)
 - type make
 - type make install  (as root)
 - restart apache ("apachectl restart" or "make restart")

from now you shall have mod_sqlinclude ready up
and running.


Troubleshoting
----------------

Q: I can't compile
A: Make sure you have apache and mysql development files. These are mosly
   packed in NAME-dev.xxx (xxx=deb or rpm) packages, so just install them

Q: Apache can't see the modules (it rejects the commands)
A: Make sure it's properly installed. In particular check the httpd.conf
   and see if LoadModule entry is present, and if it points to the module.
   On my config this line looks like:

   LoadModule sqlinclude_module /usr/lib/apache/1.3/mod_sqlinclude.so

Q: The module works, but it can't connect to the database
A: Make sure the user you want the module to authenticate is valid
   MySQL user (read: it exists in mysql.user table). Other cause
   of unsucessful connection is restricted host access for that user.
   Make sure your the machine apache runs on is allowed to connect
   to MySQL AND authenticate as the given user (check the Host column
   in your mysql.user table). If unsure either put '%' (which is
   the wildcard matching any host) or put the apache's host name
   there.


How to use
-----------

Once you have it complied and installed, modify your httpd.conf file
(usually resides in /etc/apache). Here are the config commands that
mod_sqlinclude implements and handles. Since Apache process config
line by line, you will have to specify all the connection parameter
before you do the SQLInclude:

 - SQL_ServerName "your_sql_server_name.com"
     cannonical name of your MySQL server you want to connect to
     If not specified, "localhost" will be used.

 - SQL_ServerPort number
     specifies the port number on which your SQL server installed
     on SQLI_ServerName specified host listens for incomming
     connection. When not specified, default MySQL port is used
     (it's recommended to not use this command unless really needed).

 - SQL_SQLUser sql_user_name
     specifies MySQL user name the module shall authenticate as
     while connecting to the SQL server. When not given, the
     "sqlinclude" will be taken.

 - SQL_SQLPassword password
     specifies the SQL password for SQLI_SQLUser. No default,
     so make sure you give one.

     NOTE: The password is stored in plain text, so make sure
           the httpd.conf is readable to noone except root!

 - SQL_Include sql_query
     this command does the thing. When invoked mod_sqlinclude module
     tries to connect to the server as specified using previously
     described command, and the perform the sql_query. The 1st
     column of returned rows will then be taken and passed to Apache
     for further processing.

     NOTE: as the module ignores other than 1st column, doing SELECTs
           like "SELECT * ..." instead if "SELECT column ..." just
           wastes your resources and makes NO real adventages.

 - SQL_AbortOnError On/Off
	  When set to 'On' any apache syntax error (in included data) will
     cause module to abort further row processing. The default is 'Off'
     which will tell module to process all the data without taking much 
     respect for Apache opinion about that data

 - SQL_UseNameColumn On/Off
	  When set to 'On', the mod_sqlinclude will treat row[1] of returned
     data as the descriptive string of the record (I suggest to make
     it unique). This increases readability of syntax error messages,
     as it become easier to find out which exactly record is buggy.
     Default is 'Off', which makes the mod to generate 'SQLxxx' name
     with xxx being replaced with row number. It may be useful only
     if order of your data is always the same (say you use ORDER BY)

     NOTE: make sure your SELECT clause returns TWO columns when using
           this option. Module simply expects it to be there and will
           try to use it *WITHOUT* any checks!
     	


Usage example
------------------

[snipplet of example httpd.conf]

SQL_ServerName  my.server.com
SQL_SQLUser     apache_sql
SQL_SQLPassword open_sessame
SQL_Include "SELECT apache_data FROM include WHERE ip='127.0.0.1'"

[another snipplet. example of using SQL_UseNameColumn]

SQL_ServerName  my.server.com
SQL_SQLUser     apache_sql
SQL_SQLPassword open_sessame
SQL_UseNameColumn On
SQLI_Include "SELECT apache_data,name FROM include"

License
----------

mod_sqlinclude is licensed under BSD license.


Bugs
----------

None known. The module will be revised soon, but as for now, I haven't
seen anything critical. Did you? Let me know!
