mod_vhs 1.1 - Virtual Hosting module

mod_vhs is an Apache 2.2 Web Server module allowing mass virtual hosting without
the need for file based configuration. The virtual host paths are translated
from a any database supported by libhome at request time.

Building and Installing Apache with mod_vhs

mod_vhs is configured using the Apache 2.2 apxs system. Normaly all Apache 2.2
system should have this tool installed, so if you don't have it, you'll have
a problem :)

You will need an apache 2.2 (mod_vhs 1.1 doesn't support apache 2.0, so
upgrade !) with either mod_ldap support or mod_dbd.

mod_vhs can be installed and configured using provided Makefile. Please
edit the Makefile and update it as your convience.

This will, as root, install mod_vhs into Apache 2.2 module directory and 
enable it in the configuration file. This is the prefered way to do it.
mod_vhs is enabled by default once the Apache configuration has been rebuilt.

Note: you can use a "slow" way to install it (eg: add the files into 
      apache 2 source tree and remake the configuration file, but I have
      never try that... so use a your own risk !).

Configuring mod_vhs in Apache Configure Files

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

EnableVHS: Enable or Disable mod_vhs. Per default VHS is NOT

vhs_LogNotFound: Enable or Disable logging into error log when
			mod_vhs cannot find the hostname in database.
			Per default this option is disabled.

vhs_Path_Prefix: Sets an optional location to prefix translations by.
			This option is not required.

vhs_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.
			Since we use internaly HTTP Rediect you MUST use 
			an URI.

vhs_Lamer: boolean (On / Off), default to Off.
			If set, this will enable "lamer mode" option to
			allow people that always add an "www." to web
			addresses to be magicaly handled by this module.

vhs_PHPsafe_mode: boolean (On / Off), default Off.
			If set, and if you have compiled mod_vhs with PHP
			support it will set safe_mode to on for the 
			virtual host otherwise php.ini defaults will be
			Notice this code is added only uppon compilation 
			the -DOLD_PHP.
			This code is not maintained anymore.

vhs_PHPopen_basedir: boolean (On / Off), default Off.
			If set, and if you have compiled mod_vhs with PHP
			support, it will set open_basedir to the home 
			directory given by libhome/mod_vhs otherwise php.ini
			defaults will be used.

vhs_open_basedir_path: string. The open_basedir path that will be used to
			be set when vhs_PHPopen_basedir is set AND 

vhs_append_open_basedir: boolean (On / Off), default Off.
			Is set, mod_vhs will append the homedir path into
			NOTE :	mod_vhs open_basedir option will OVERIDE
			php.ini settings.

vhs_PHPdisplay_errors:	boolean (On / Off), default Off.
			If set, and if you have compiled mod_vhs with PHP
			support, it will enable display_errors to be shown,
			otherwise php.ini defaults will be used.

vhs_PHPopt_fromdb:	boolean (On / Off), default Off,
			If set, and if you have compiled mod_vhs with PHP
			support, it will alter PHP configuration using
			libhome passwd unused field. See README.phpopt
			for more detailed example.

vhs_Alias, vhs_ScriptAlias, vhs_ScriptAliasMatch, vhs_RedirectTemp and
vhs_RedirectPermanent :	mod_alias 100% compatible options inside mod_vhs.
			Please see
			for more informations.

mod_ldap and mod_dbd stuff
			Since version 1.1.0 or newer, we stop tu use libhome as backend
			and we use internal Apache stuff.
			For LDAP we use mod_ldap that have internal caching system
			For SQL  we use mod_dbd
			Because of these change, mod_vhs 1.1.0 is compatible ONLY
			with Apache 2.2.x

			LDAP Only directives (only readed when mod_vhs builded with LDAP)
			See README.LDAP for detailed informations.

			An optional DN used to bind to the server when searching for
			entries. If not provied, mod_vhs will use an anonymous bind.
			An bind password to use in conjonction with the bind DN. Note
			that the bind password is probably sensitive data, and should be
			properly protected. You should only use the vhs_LDAPBindDN and
			vhs_LDAPBindPassword if you absolutely need them to search the 

			This directive specifies when mod_vhs will de-references aliases
			during LDAP operations. The default is always.

			A RFC 2255 URL which specifies the LDAP search parameters to use.
			The syntax of the URL is :
				For regular ldap, use the string ldap. For secure LDAP, use
				ldaps instead. Secure LDAP is only available is Apache was
				linked to an LDAP library with SSL support
				The name/port of the LDAP server (default to localhost:389 for
				ldap, and localhost:636 for ldaps). To specify multiple, redundant 
				LDAP server, just list all servers, separated by spaces. mod_vhs
				will try connecting to each servers in turn, until it make a 
				successfull connection.
				Once a connection has been made to server, that connection remains
				active for the life of the httpd process, or until the LDAP server
				goes down.
				If the LDAP server goes down and break the existing connection,
				mod_vhs will attends to re-connect, starting with the primary 
				server, and trying each redundant server in turn. Note that is
				different than a true round-robin search.
				The DN of the branch of the directory where all searches start from.
				At the very last, this must be the top of you directory tree, but
				could also specifiy a subtree in the directory.
				The attribute to search for. Don't change search attribute in
				mod_vhs or you will break the module.
				The scope of the search. Can be either "one" or "sub". Not that
				scope of "base" is also supported by RFC 2255, but not supported
				in this module. If the scope is not provided, or if "base" scope
				is specified, the default is to use a scope of "sub".
				A valid LDAP search filer. If not provided, default to 
				(|(apacheServername=vhost)(apacheServerAlias=vhost)). Filter are
				limited to approximately 8000 caracters (the definition of
				MAX_STRING_LEN in the Apache source code). This should be
				more than sufficient for any application. Don't changer filter
				unless you know what your are doing.

vhs_LDAPSetFilter	Use the filter given ing vhs_LDAPUrl instead of the compiled one.
			See README.LDAP for more informations

			mod_dbd support (when compiled with DBD support)

vhs_DBD_SQL_Label	The name used for the DBDPrepareSQL label to get data from DBD.
			mod_vhs use the following SQL column names to get it's values.

			ServerName -> "ServerName" of "VirtualHost" e.g.
			ServerAdmin -> "ServerAdmin" of "VirtualHost" e.g.
			DocumentRoot -> "DocumentRoot"  of "VirtualHost" e.g. var/www/htdocs
			suexec_uid -> user ID (UID) either for apache2-mpm-itk or suPHP
			suexec_gid -> group ID (GID) either for apache2-mpm-itk or suPHP
			php_env -> PHP options e.g. open_basedir=/tmp/:/var/www/;upload_tmp_dir=/var/www/tmp;session.save_path=/var/www/tmp;upload_max_filesize=200M;post_max_size=200M;
			associateddomain -> the value of VH_GECOS HTTP header, normally this can be the "ServerName"

			A sample query: 
			SELECT ServerName, 
			FROM mod_vhs_table 
			WHERE ServerName = %s 
			If you have different column names you can use something like this:
			SELECT vHost AS ServerName, 
					admin AS ServerAdmin, 
					docRoot AS DocumentRoot, 
					uidNumber AS suexec_uid, 
					gidNumber AS suexec_gid, 
					SetEnv AS php_env,
					vHost AS associateddomain
			FROM my_vhost_table 
			WHERE vHost = %s 
			AND IsDeactivated = '0'
			Note: "%s" is the hostname requested by the client

			apache2-mpm-itk support (when compiled with apache2-mpm-itk support)

vhs_itk_enable: boolean (On / Off), default Off.		
			When on, it changes UID/GID to the one given either on LDAP or DBD

			memcached support (when compiled with memcached support)
vhs_Memcached: boolean (On / Off), default Off.
			When on, results from DBD/LDAP requests are cached.
vhs_MemcachedInstance: string. Name of the mod_vhs instance.
			 Use a short, but descriptive name. e.g. super-server
vhs_MemcachedLifeTime: interger. Lifetime (in seconds) associated with stored
			objects in memcache daemon(s). Default is 600 s.

Notes about vhs_PHP* values :

	All this options *will* override the default PHP values you have
	set into php.ini. 

Additional Information

mod_vhs will check on every connection if data exist or not. On mod_ldap mode,
it will use mod_ldap caching feature to avoid to hammer the LDAP server. On mod_dbd
unfortunalty there is no caching feature on apache 2.2 so, EVERY REQUEST DOES A SQL


mod_vhs is an Apache 2.2 module using libhome library, more about 
Apache Web Server can be found at
This module was highly inspired from mod_vdbh, I wishe to send many thanks
to Michael K Link <> that helped me a lot to give me a 
good start to make my module work, mod_vdbh homepage :


Send bugs, ideas, fixes, patches, and food to :
Xavier Beaudouin <>

Home page of this module