mod_vhost_dbd

Introduction

mod_vhost_dbd has one directive:

DBDocRoot SQL [ PARAM ... ]

mod_vhost_dbd overrides the DocumentRoot directory using an SQL query.

The query returns the new root directory as the first column of a single result row. If no rows are returned by the query, the original DocumentRoot directory is not replaced.

DBDocRoot "SELECT WebDir FROM WebTable WHERE WebName = %s"  HOSTNAME

DBDocRoot can be used at the Server or the Virtual Host level.

Details

SQL is an SQL statement which returns no more than one row, with the directory in the first column. This directory is used instead of the existing document root set by the DocumentRoot directive.

PARAM ... arguments are inserted into the SQL statement at request time. Use one PARAM for each parameter marker in your SQL statement. In the examples, %s is the parameter marker. PARAM may be any of these words (space separated, not case sensitive):

HOSTNAME
requested hostname
may be NULL if there is no Host header. e.g. HTTP 1.0 or FTP requests

IP
server IP address
as a string, never NULL

PORT
server port number
as string, never NULL

URI
The request URI
never NULL

URIn where n is 1-9
Pass only the first n segments of the URI to the query
never NULL

• You must have an Apache DBD driver and mod_dbd loaded and configured to use mod_vhost_dbd.

• Use LoadModule to enable mod_vhost_dbd.

  LoadModule vhost_dbd_module modules/mod_vhost_dbd.so
  

• If your query returns no rows, the existing document root is used. If your query returns more than one row, the request is rejected with a 500 Internal Server Error.

• Do not put a semicolon at the end of your SQL statement.

• PARAM names can be repeated as necessary. For example: to only look up hosts containing ".acme." for port 80 requests:

          DBDocRoot "SELECT DocRoot FROM myTable WHERE %s LIKE '%%.acme.%%' AND Host = %s AND %s = 80" HOSTNAME HOSTNAME PORT
  

• DBDocRoot can use the name of a statement previously defined with the DBDPrepareSQL directive as the SQL parameter. For example:

  DBDPrepareSQL "SELECT WebDir FROM WebTable WHERE WebName = %s"  HostLookup
  ...
  DBDocRoot HostLookup  HOSTNAME
  

• Some databases (for example: Firebird) may report errors when statements for DBDocRoot are prepared with DBDPrepareSQL. In this case, DBDPrepareSQL cannot be used for virtual host statements.

• For Apache 2.2 prior to version 2.2.9, use parameter markers appropriate to your database. For example: Use ? for ODBC or SQLite. Use %s for MySQL, etc.
• For Apache 2.2.9+ always use %s as a parameter marker in your SQL statement. If your SQL statement contains other % characters (for example, in a LIKE clause), use %% to prevent them from being misinterpreted as parameter markers.
• For Apache 2.2.9+, any additional columns which are returned will set an environment variable with the same name as the column name. If the column value is NULL, any existing environment variable which matches the column name will be unset.
• Using a URI PARAM increases the number of database queries required because each request requires a new query. Using only the leading portion of the URI can reduce the number of database queries required. When multiple requests are made on the same keep-alive connection which have the same URIn value, only one query is performed.

• If the URI is /alpha/beta/gamma/delta/index.html:

     URI1 is /alpha
     URI2 is /alpha/beta
     URI3 is /alpha/beta/gamma
     ...
     URI5 is /alpha/beta/gamma/delta/index.html
     URI6 is /alpha/beta/gamma/delta/index.html
     ...
     URI9 is /alpha/beta/gamma/delta/index.html
     URI  is /alpha/beta/gamma/delta/index.html
  

• If mod_ftp is used, an additional PARAM name is available. FTPUSER can be specified to pass the logged-in FTP user name. This parameter is not available for HTTP requests.

• Setting LogLevel debug will print additional information in the Apache error log which can help to diagnose SQL query problems.
• The httpd server variable: document_root is not changed by mod_vhost_dbd. It remains as the value set by the DocumentRoot directive in the httpd configuration file. For example, these variables will contain the directory path set in the httpd configuration file - not the directory path set by DBDocRoot:

PHP
$_SERVER['DOCUMENT_ROOT']

CGI
environment variable: DOCUMENT_ROOT

J2EE
GetServletContext().GetRealPath("/")

[Anonymous]

Originally posted by: ashishpa...@gmail.com

Does this cache the result for a HOSTNAME lookup, or does it make a call for each request which are coming from various connections? Can we specify a TTL?

[Anonymous]

Originally posted by: ashishpa...@gmail.com

Downloaded and tested, there is no cache. For every single request, a SQL call is made. :-s

[Anonymous]

Originally posted by: Thomas.D...@gmail.com

A HOSTNAME (or any other) lookup will only be performed once within a single keep-alive connection if all the web page requests use exactly the same SQL query. See: http://httpd.apache.org/docs/current/mod/core.html#keepalivetimeout

No other query caching is done by mod_vhost_dbd. Note that most databases, like MySQL, have a query cache to expedite the processing of repeated SQL queries.

[Anonymous]

Originally posted by: daveu...@gmail.com

Is there a way to handle db connectivity issues? Such as, if communication to the db server isn't functioning, have it fall back to the default docroot rather than throw a server error?

[Anonymous]

Originally posted by: j...@tenka.se

Hi,

I wish to pick up different SSL certs from MySQL for different domains. Is it possible with this module?

Any advice? Pls help.

Thanks,

Jon