Sophie: apache-mod_vdbh-1:1.0.3-12mdv2010.0 i586

apache-mod_vdbh-1.0.3-12mdv2010.0.i586.rpm

mod_vdbh 1.0 - Virtual Database Hosting module

mod_vdbh is an Apache Web Server module allowing mass virtual hosting without the need for file based configuration. The virtual host paths are translated from a MySQL database at request time, thus the configuration can be changed without having to restart Apache Web Server.

Building and Installing Apache with mod_vdbh

mod_vdbh is configured using the Apache 2.0 configuration system. Normally a vanilla install of Apache doesnÕt require a rebuild of the configuration system, but since mod_vdbh requires libraries not usually built into Apache it is necessary to rebuild the configure script using GNU autoconf. If the GNU autoconf tools are not installed on the system then they can be downloaded from a GNU distribution site, for more information check the GNU autoconf website http://www.gnu.org/software/autoconf/. Please note that GNU autoconf also requires a recent release of an m4 macro processor which can also be found at a GNU distribution site. The next step is to download the mod_vdbh source from http://www.synthemesc.com/

Once the package is downloaded de-archive it and move it to the Apache 2.0 modules directory. The resultant directory name should be mod_vdbh after de-archiving.

$ mv mod_vdbh httpd-2.0.43/modules/mod_vdbh

Now the Apache configuration system is ready to be rebuilt and include mod_vdbh. Change directory to the root level of the Apache 2.0 source and rebuild the configuration system by typing the following commands.

$ ./buildconf

Running the configure script with the help flag will show that mod_vdbh configuration macros have been assimilated into the Apache configuration system.

$ ./configure --help
--disable-vdbh mass virtual hosting module
--with-mysqldir=DIR MySQL directory prefix

mod_vdbh is enabled by default once the Apache configuration has been rebuilt. If it is necessary to disable mod_vdbh then this may be accomplished with the --disable-vdbh option passed to the configure script.

The --with-mysqldir=DIR will specify a non-default location to find the MySQL libraries and include files, usually located by default in /usr/local.

The next step is to configure the Apache build process by running the configure script. During configuration we will see status output, the mod_vdbh configuration status output will look similar to the following.

checking whether to enable mod_vdbh... yes (default)
using `/usr/local' as MySQL directory prefix
adding "-L/usr/local/lib/mysql" to LDFLAGS
checking for mysql_init in -lmysqlclient... yes
adding "-lmysqlclient" to LIBS
adding "-R/usr/local/lib/mysql" to LDFLAGS
adding "-I/usr/local/include/mysql" to INCLUDES

If configuration fails the most likely problem is that the MySQL distribution isn't installed or is in a directory that couldn't be found, try passing --with-mysqldir=DIR to configure to specify a directory tree that MySQL is installed at.

After configuration has completed the Apache web server can be compiled. Change directory to the root level of the Apache 2.0 source distribution and execute the following commands.

$ make
$ make install

This will compile Apache 2.0 with mod_vdbh and install the distribution in the location specified at configuration time. The Apache 2.0 binary will contain a statically linked mod_vdbh module which may also statically link MySQL libraries depending on your MySQL installation.

Configuring mod_vdbh in Apache Configure Files

In order to use mod_vdbh with Apache Web Server server configuration blocks will need to be configured with mod_vdbh configuration directives described in the table below. mod_vdbh configuration directives must be located in a server configuration block (ie <VirtualHost></VirtualHost>).

vdbh This switch makes mod_vdbh active for the specified server.
vdbh_CLIENT_COMPRESS Enables the CLIENT_COMPRESS option with a MySQL server allowing the connection data to be compressed. Using this option will likely require more cpu time and less network bandwidth.
vdbh_CLIENT_SSL Enables the CLIENT_SSL option when communicating with a MySQL server.
vdbh_MySQL_Database Sets the database name to use when running a query for file name translations.
vdbh_MySQL_Table Sets the table name to use when running a query for file name translations.
vdbh_MySQL_Host_Field Sets the name of the host field in the table specified by vdbh_MySQL_Table.
vdbh_MySQL_Path_Field Sets the name of the path field in the table specified by vdbh_MySQL_Table.
vdbh_MySQL_Environment_Field Sets the name of the environment field in the table specified by vdbh_MySQL_Table. This optional field contains data that will be set to the VDBH_ENVIRONMENT variable.
vdbh_MySQL_Host Sets the internet hostname where the MySQL server is located at. This option is not required and defaults to localhost.
vdbh_MySQL_Port Sets the port number to connect to when making a connection to a MySQL server. This option is not required and defaults to 0 for using a UNIX domain socket.
vdbh_MySQL_Username Sets the username required to gain access to the MySQL server. This option is not required.
vdbh_MySQL_Password Sets the password required to gain access to the MySQL server. This option is not required.
vdbh_Path_Prefix Sets an optional location to prefix translations by. This option is not required.
vdbh_Default_Host Sets the default host to use if a non-HTTP/1.1 request was received. This option is not required and usually won't do anything because the Apache Web Server by default catches these errors.
vdbh_Declines Sets a list of glob patterns to match URIs against. If any match occurs then the URI is declined to the next translate phase.

The vdbh_MySQL_Host_Field and vdbh_MySQL_Path_Field along with vdbh_MySQL_Environment_Field are available as environment variables and can be included in logs if a LogFormat is defined for them. The environment variables are labled VDBH_HOST, VDBH_PATH, and VDBH_ENVIRONMENT. Information on how to use LogFormat is available at http://httpd.apache.org/docs/mod/mod_log_config.html. An example configuration may look something like this.

NameVirtualHost 206.9.161.29

<VirtualHost 206.9.161.29>
vdbh On
vdbh_CLIENT_COMPRESS On
vdbh_MySQL_Database virtual_hosts
vdbh_MySQL_Table virtual_hosts
vdbh_MySQL_Host_Field server
vdbh_MySQL_Path_Field path
vdbh_MySQL_Environment_Field environment_variable
vdbh_Default_Host julia.fractal.net
vdbh_Declines .htpasswd *.txt
</VirtualHost>

The corresponding database schema would look like this.

CREATE TABLE virtual_hosts (
server char(255) NOT NULL,
path char(255),
environment_variable char(255),
PRIMARY KEY (server)
);

INSERT INTO virtual_hosts VALUES ('julia.fractal.net','/export/home/mlink/public_html','julia.fractal.net');
INSERT INTO virtual_hosts VALUES ('visualphixation.com','/export/home/carlosp','visualphixation.com');
INSERT INTO virtual_hosts VALUES ('www.visualphixation.com','/export/home/carlosp','www.visualphixation.com');
INSERT INTO virtual_hosts VALUES ('www.fractal.net','/export/web/www.fractal.net','www.fractal.net');
INSERT INTO virtual_hosts VALUES ('fractal.net','/export/web/www.fractal.net','fractal.net');

Other handlers should still work accordingly. mod_vdbh declares its translate_name phase as AP_HOOK_FIRST so it can run before other translations. An example configuration allowing mod_tcl in specific directories follows.

<Directory /export/web/www.fractal.net>
AddHandler tcl-handler tm

Tcl_ContentHandler content_handler
</Directory>

<Directory /export/web/www.fractal.net/images>
SetHandler default-handler

Options Indexes FollowSymLinks

AllowOverride None

Order allow,deny
Allow from all
</Directory>

<Directory /export/web/www.fractal.net/files>
SetHandler default-handler

Options Indexes FollowSymLinks

AllowOverride None

Order allow,deny
Allow from all
</Directory>
</VirtualHost>

Additional Information

mod_vdbh assumes that its connection to the MySQL server is persistent. If there are excessive disconnections try setting the wait_timeout variable for MySQL to a larger value. Apache Web Server 2.0 is required, and at least MySQL 3.23 is required.

References

mod_vdbh is an Apache 2.0 module using MySQL libraries, more about Apache Web Server can be found at http://www.apache.org/. Documentation regarding MySQL can be found at http://www.mysql.com/