mod_vhs 1.0 - Virtual Hosting module

mod_vhs is an Apache 2.0 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_vh

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

You will need a installed libhome into your system. Please fetch it at
http://pll.sourceforge.net/ before.

mod_vhs can be installed and configured using Apache 2.0 apxs tool :

$ apxs -i -a -c -L/usr/local/lib -lhome mod_vhs.c

If you need PHP support and "open_basedir", you can use :
$ apxs -i -a -c -I/usr/local/include/php -I/usr/local/include/php/Zend \
  -DHAVE_MOD_PHP_SUPPORT -L/usr/local/lib -lhome mod_vhs.c

This will, as root, install mod_vhs into Apache 2.0 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
			enabled.
vhs_libhome_tag :	Set Libhome tag. See home.conf(5) man page for usage.
			This option is not required, if not set the libhome
			tage will be set to "mod_vhs".
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.
vhs_Default_Host_redirect:
			boolean (On / Off), default to Off.
			If set, the mod_vhs module will issue a redirect 
			instead of parsing the request into internal Apache
			handler. If you use this option, then vhs_Default_Host
			MUST have the correct URI protocol (eg http://the.domain.com/)
			instead of only a plain host.
			Also notice that there is *NO* tests against infinite
			loops of redirects.
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
			used.
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_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_Alias, vhs_ScriptAlias, vhs_ScriptAliasMatch, vhs_RedirectTemp and
vhs_RedirectPermanent :	mod_alias 100% compatible options inside mod_vhs.
			Please see http://httpd.apache.org/docs-2.0/mod_alias.html
			for more informations.

Notes about vhs_PHP* values :

	All this options *will* override the default PHP values you have
	set into php.ini. For example if you have in php.ini safe_mode = On,
	and in a <VirtualHost></> you get a vhs_PHPsafe_mode Off then the
	value of php.ini will be safe_mode = Off. 

Example :

You have set home.conf with such data :

mode ldap
ld_hosts 127.0.0.1
ld_base . ou=whosting,dc=kazar,dc=net
ld_version 3
ld_timeout 5

[mod_vhs]
log.stderr y
where wwwDomain
user wwwDomain
home homeDirectory
uid uidNumber
gid gidNumber
gecos description
passwd "*"
shell /dev/null
quota FTPQuotaMBytes
class admin@foo.com

You get such ldap entry :

#
# LDAPv3
# base <ou=whosting,dc=kazar,dc=net> with scope sub
# filter: wwwDomain=jb.kazar.net
# requesting: ALL
#

# 'jb.kazar.net', whosting, kazar.net
dn: wwwDomain='jb.kazar.net',ou=whosting,dc=kazar,dc=net
objectClass: top
objectClass: kazarPerson
objectClass: PureFTPdUser
uid: jb
description: JB Home page
uidNumber: 65534
gidNumber: 65534
FTPuid: 65534
FTPgid: 65534
FTPStatus: enabled
userPassword:: xxxxxxxxxxxxx
homeDirectory: /hosting/http/j/b/k/jb.kazar.net/
FTPQuotaMBytes: 50

A simple test to see if your libhome map will work :

$ home_finger -t mod_vhs jb.kazar.net
login: jb.kazar.net
passwd: *
uid: 65534
gid: 65534
gecos: JB Home page
home: /hosting/http/j/b/k/jb.kazar.net/
shell: 
expire: 0
quota: 50
class: admin@foo.com

Note that class will be used for server admin mail inside Apache (usualy 
diplayed for webmasters, and/or errors).

Then if you set the DNS entry for jb.kazar.net to 10.1.2.3, the following 
apache2 configuration file will look for jb.kazar.net files in 
/hosting/http/j/b/k/jb.kazar.net/ :-)

NameVirtualHost 10.1.2.3

<VirtualHost 10.1.2.3>
    vhs_Default_Host devnull.oav.net
</VirtualHost>

Other handlers should still work accordingly.  mod_vhs 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.

<VirtualHost 10.2.3.4>
    vhs_Default_Host devnull.oav.net

    <Directory /hosting/http/j/b/k/jb.kazar.net>
        AddHandler tcl-handler tm

        Tcl_ContentHandler content_handler
    </Directory>
</VirtualHost>

With PHP support you can do also :

<VirtualHost 1.2.3.4>
   vhs_Default_Host www.mydomain.com
   vhs_PHPsafe_mode On
   vhs_PHPopen_basedir On
</VirtualHost>


<VirtualHost 1.2.3.5>
   vhs_Default_Host www.mydomain.com
   vhs_PHPsafe_mode Off
   vhs_PHPopen_basedir Off
</VirtualHost>


Additional Information

mod_vhs will check on every connection if data exist or not. If you don't want
to hammer your LDAP/MySQL server please use cache_file and cache_ttl values in
home.conf(5).

References

mod_vhs is an Apache 2.0 module using libhome library, more about 
Apache Web Server can be found at http://www.apache.org/.
Documentation regarding libhome can be found at http://pll.sourceforge.net/
This module was highly inspired from mod_vdbh, I wishe to send many thanks
to Michael K Link <mlink@apache.org> that helped me a lot to give me a 
good start to make my module work, mod_vdbh homepage : http://www.synthemesc.com/mod_vdbh/.


Author

Send bugs, ideas, fixes, patches, and food to :
Xavier Beaudouin <kiwi@oav.net>

Home page of this module 

http://www.oav.net/projects/mod_vhs/
