WN home page

Version 2.5.0
[Previous] [Next] [Up] [Top] [Search] [Index]

Multi-homed or Virtual Servers on the WN Server

Many systems allow multiple IP addresses for a single host. For systems with this capability it is possible to use a different data hierarchy for each IP address to which your host responds. Sometimes this is referred to as "virtual hosts" or a "multi-homed" server since when combined with DNS aliasing it permits a single server to appear to be multiple servers on different hosts. Unfortunately, I cannot help you in configuring your system to respond to multiple IP addresses. (Some information about this can be found at http://www.thesphere.com/%7Edlp/TwoServers/) However, if your system supports this capability you can have different data hierarchies for each IP address if you run the stand-alone version of the server (wnsd).

12.1 One Server per Virtual Host

There are two ways to have multiple virtual hosts. Assuming that you actually have more than one network interface (i.e. more than one NIC), the easiest is to run multiple instances of the server each with a different IP address indicated on the command line via the -i option.

For example running the commands:

wnsd -i -L abc.log /abc/root
wnsd -i -L def.log /def/root

will start two instances of the server, both on the same port (80) but responding to different IP addresses.


wnsd -h www.abc.com -L abc.log /abc/root
wnsd -h www.def.com -L def.log /def/root

will start two instances of the server, both on the same port (80) but responding to different IP addresses. The server will ascertain the appropriate IP address by using the UNIX gethostbyname(3) system call for the name supplied on the command line.

Note: To use this method make sure the "#define USE_VIRTUAL_HOSTS" line in config.h is commented out.

This method has the disadvantage of using somewhat more resources than the alternate method (described below) because at least one instance of the server for each host name is running at all times and thus using memory. On the other hand with this method it is possible to specify a different log file for each host, while the method below uses only one log file and a utility to separate it into the contributions of each host.

12.2 A Single Server with Multiple Virtual Hosts

The second method to implement a multi-homed server involves only a single initial instance of the server which responds to all requests and changes the document root as appropriate based on the IP address or host name to which the request was sent. To use this method you need to edit the config.h file and uncomment the line containing "#define USE_VIRTUAL_HOSTS".

Then you have two choices. You can either create a file containing a list of the virtual hosts or you can build this list into the compiled version of the sever by editing one of the source files and recompiling. If you have only a few virtual hosts and you don't anticipate adding new ones, I recommend compiling in the list. This is easy to do and much more efficient if you use wnd with the UNIX inetd(8) system utility. If you use wnsd there is little difference in efficiency.

12.2.1 Using a Virtual Hosts List File

You can either compile in the list of virtual hosts or keep this list in a file which will be read each time the server starts. The second option is described here and the first is described in the next section. To use a virtual host file you must uncomment the line containing "#define VIRTUAL_HOSTS_FILE" in the file config.h and change the quoted path to the full path of a file containing virtual host information in a format described below. Then you must recompile the server. Once this has been done you may change the file you use with the -V option to the server. But to turn this feature on, it is necessary that "#define VIRTUAL_HOSTS_FILE" be uncommented when the server is compiled. Each time this file is changed, in order for the change to take effect, you will need to restart the server or send it the SIGHUP signal with the UNIX kill(1) utility.

The format of this file is one line per virtual host. Each such line should have the form:

hostname IP_address root_path vhost_nickname user group flag

with the four parts separated by white space. For example entries might be:

myhost.com /usr/wn/myroot myhost bob mygroup 0
client.com /usr/wn/client client george clientgroup 1

In particular the hostname should be a fully qualified domain name. The user and group fields are the name of the user and group to be passed to suexec if it is used. If it is not these can be set to the string NULL. However, if suexec is used, both the user and group must be defined for each virtual host -- they could have the value of the user and group under which your server runs. The flag field currently has only two allowable values, 0 and 1. The value 1 indicates that user home directories are not permitted for this virtual host. Lines in this file which are empty or start with '#' are ignored. When using verbose logging the nickname will be enclosed in angle brackets and used as the last field of each log entry. If the nickname is omitted a number will be used representing the position of virtual host in the virtual host file.

By default there is a maximum of 64 virtual hosts allowed in a virtual host file. But this can be increased by editing the file wn/vhost.c and changing the line "#define MAXVHOSTS (64)". Just replace the 64 with the value you wish.

WN supports the "Host: " header implemented by some browsers (e.g. Netscape Communicator) and so-called "full URL requests". For browsers that support either of these features it is now possible to have multiple virtual hosts with a single IP address. The HTTP/1.1 protocol requires browsers to support the "Host: " header.

Using this feature requires nothing beyond setting up the server exactly as described above for virtual hosts. Of course, all your virtual hosts will have the same IP number if your system only has one. Then if a browser provides the "Host: " header (which should contain the hostname and port it is trying to access) the WN server will use the root data directory you specified for that host name. Similarly if a full URL request like "GET http://host.abc.com/dir/foo.html" is used the server will use the root data directory corresponding to "host.abc.com". If the browser provides neither of these the server will use the first root data directory whose IP number matches (which will be the first in your list if you have only one IP address).

12.2.2 Compiling in the List of Virtual Hosts

To compile in the list of virtual hosts you need to edit the file wn/vhost.h. This file is quite short and contains something like:

char *
vhostlist[][7] =
    { "realname.com" , "", ROOT_DIR, "nickname0", "usr0", "grp0", "0" },
    { "virtual1.com" , "", "/var/data1", "nickname1", NULL, NULL, NULL },
    { "virtual2.com" , "", "/var/data2", "nickname2", "usr2", "grp2", "1" },
    { "another.ip.com", "", "/var/data3", "nickname3", "usr3", "grp3", "1" },

The line containing { "virtual2.com", "", "/var/data2", "nickname1" }, etc., should be replaced by a line containing one of the IP addresses of your host instead of "", the correct system path to the corresponding data root instead of "/var/data1", one of the hostnames that corresponds to this IP address, and a nickname to use in logging. The "usr2" and "grp2" are only used with suexec and can have the value NULL if you are not using suexec. The final entry in this line is a string representing a flag for use with virtual hosting. For the moment it should only be NULL or one of the quoted strings "0" or "1". The quoted string "1" disallows the use of any user home directories for URL's referring to this virtual host. The values NULL or "0" are equivalent and give the default behavior which allows serving from user home directories only if the server was compiled with this feature enabled. The hostname in these lines is used by the server in only two ways: when a redirect header is sent, and to pass the correct server host name to CGI/1.1 programs in the environment variable. The nicknames are used as a field of a verbose log entry. When using verbose logging the nickname (enclosed in angle brackets) will be the last field of each log entry. If the nickname is NULL then a number will be used for its value representing the position of virtual host in the virtual host file.

All the lines of this file should be changed in a similar fashion. You may have more as many lines as you wish and you should remove any of the lines you don't need. Don't change anything else. In particular make sure that the { NULL, NULL, NULL, NULL, NULL, NULL, NULL } line is unchanged and that you change only the parts inside quotation marks. If the IP address by which the server is accessed does not match any of the addresses listed in this file then the server will use the default data root (as specified when you ran the configure program or edited the value of "#define ROOT_DIR" in config.h).

The server will not produce separate log files for each IP address. However, if the server is configured to produce verbose logs then each entry is tagged at the end with the nickname of the virtual host which received the request. The wnv2c utility can then be used to produce separate log files for each IP address.

WN version 2.5.0
Copyright © 1998-2005 John Franks <john@math.northwestern.edu>
licensed under the GNU Free Documentation License
Last modified: Sat June 18 2005
[Previous] [Next] [Up] [Top] [Search] [Index]