Apache Named Virtual Server tutorial

What is a virtual server?

Put simply its more than one web server on one machine running a single copy of apache. Each of virtual server appears to be totally separate complete with its own directory structure and configuration files. Apache supports two types of virtual server, these being IP and name based. With IP based servers each server is referenced by a unique IP address, while the name based server is referenced by domain name and share a common single IP address. Its this second type that we will be configuring in these examples.

The example.

Suppose you are a small company that's develops web sites, you have three current projects that need to be worked on concurrently, but you only have one machine that can be used as a web server that is attached to the company internal network, in addition you have full Internet access on the network via router.

Each of these projects has a registered domain name that will be used for the finished site, and as you have routed Internet access on your internal network you need to be able to separate the development server from the Internet server. To achieve this you decide on the following naming conventions.

Internet domain name : showsite.com
Internal development name : local.showsite.com

Internet domain name : bigcompany.com
Internal development name : local.bigcompany.com

Internet domain name : smallshop.com
Internal development name : local.smallshop.com

Your web server is running Redhat Linux 6.2, and has a IP address of 192.168.10.10, and that apache was installed from the source tarball not the Redhat RPM's. If not I will first go through a very very brief tutorial of compiling and installing from the source code. If you have the server already installed and are happy with it skip this section.

Compile and install the server from the source code.

In my case I would always download the latest source tarball from or one of the many mirrors. As for the actual method of the install, refer to the doco that comes with the source, but for those who cannot wait here is the simple compile and install with all the default settings.

As root Change into the source directory and type the following.

./configure
make
make install

This will install the server in /usr/local/apache/ with all the defaults, which by the way is not in many cases the thing you want to do, but for the purpose of this document its what we want, there are many good texts on apache configuration that will help you more.

OK its installed now start it, to make sure all is well with the world...

/usr/local/apache/bin/apactrl start

which should respond with a message stating that httpd is started. One final test, start your browser, point it at 192.168.10.10, which is the default page for the server, you will see the apache logo and a message stating that the server is actually working.

Now for the actual configuration.

The first thing to do now that you have verified that the server is running, is to update your name resolution lookup, which for the purposes of this example is based on the local hosts file. Without this your browser will not be able to find the virtual servers. On a Linux machine, the file lives in the /etc directory, when logged in as root edit this file and add the following lines.

192.168.10.10     local.showsite.com
192.168.10.10     local.bigcompany.com
192.168.10.10     local.smallshop.com

Yes the IP address is the same for all three of these servers, this is correct as the server name is used as part of the HTTP 1.1 header to determine which server the request is to.

Now your browser knows how to get to the new servers, its time to create the directory structure. For this example I will use the following :-

/usr/home/www_root/showsite/public_html/
/usr/home/www_root/showsite/public_html/cgi-bin
/usr/home/www_root/showsite/public_html/images

/usr/home/www_root/bigcompany/public_html/
/usr/home/www_root/bigcompany/public_html/cgi-bin
/usr/home/www_root/bigcompany/public_html/images

/usr/home/www_root/smallshop/public_html/
/usr/home/www_root/smallshop/public_html/cgi-bin
/usr/home/www_root/smallshop/public_html/images

With the directories created, we need to put at least one HTML document in each public_html directory to avoid confusion later on. While this is not a HTML tutorial, I will give a very simple example which will work.

<html>
   <head>
      <title>local.smallshop.com</title>
   </head>

   <body bgcolor='#FFFFFF'>
      <h2>local.smallshop.com</h2>
   </body>
</html>

With this you need to put one copy in each of the public_html directories you created, changing the 'smallshop' to 'showsite' or 'bigcompany' where necessary.

But what about the cgi-bin I hear you ask, well thats well outside this document, there will be another to cover very basic CGI programming coming real soon. which will be linked to from here.

Now for the actual configuration of the server. But before we dive into this first some background on the apache server. The main configuration file is httpd.conf and is usually found in the /usr/local/apache/conf directory, open it in your favorite text editor and you will see its a simple text file, yes just like all the other Linux config files. As for the contents, its actually quite friendly, there are notes included on more or less every section. The only thing you really need to know is that lines that start with a # are ignored.

With that out of the way its in at the deep end, the first thing you need to do is add a line that defines the IP address you are using for the virtual servers. This is done with the NameVirtualHost directive, if you search for this you will find two examples, add the following after these.

NameVirtualHost 192.168.10.10

Simple as that, but I hear you say the one of the examples has :80 on the end of the line, true, this is if you want to set the default TCP port to anything other than 80. This is not really needed here, but for those interested I have added some information on this at the end of this section.

After this directive you will see the example of the virtual hosts provided to help you, I will cover this in detail as its important you fully understand this.

First off we need to define the server which looks like this.

<VirtualHost 192.168.10.10>
</VirtualHost>

Each server you define is enclosed between the <VirtualHost> and </VirtualHost> directives, (Yes it does look a little like HTML) what this means is that apache knows there is a virtual host that needs supporting at that IP address. And that all the directives enclosed are only applied to that specific virtual server and will over ride any settings else where in the httpd.conf file. Now we move onto giving it something to support. Between those directives the following is needed.

ServerName local.smallshop.com

This as the name suggests is the domain name for the virtual server. Its a good idea in a development environment not to use the Internet domain name as this will make live testing interesting, when the browser has the local version and the hosted version with the same name. In my case I use local.domainname for the local version, its entirely up-to you.

DocumentRoot /usr/home/www_root/showsite/public_html/

this is the root of your new site, where most of your HTML normally lives. You will put your index.html here.

ErrorLog /usr/home/www_root/showsite/error_log

By default apache puts the server error log in /usr/local/apache/logs, which is not that useful when you have multiple virtual servers, as all the error messages for these servers end up in the single error_log file. The ErrorLog directive creates a dedicated error log file for the virtual server being defined. Much better yes?

DirectoryIndex default.html

This is the default HTML document thats loaded when no document is named on the URL line in your browser. By default its defined as either index.html or default.html. By using this directive as part of the virtual server definition you can make this any valid document or CGI script, thats under the directory you defined with the DocumentRoot directive earlier or with the addition of a partial path thats referenced from DocumentRoot any other document/script in another directory, for example.

DirectoryIndex cgi-bin/default.cgi

will set the virtual server default document to the default.cgi script.

This next section deals with the use of CGI scripts, skip this if you do not want this to be available as part of your virtual server.

ScriptAlias /cgi-bin/ /usr/home/www_root/showsite/public_html/cgi-bin/

Looking at this line you will see that this time there are two parameters, the first being the actual alias which in this example is /cgi-bin/ although you can call it anything you want, it defines where the CGI scripts used on this server are executed from, the second is the real location for the alias referenced from the root of the machine, not the server. Be careful with this one, you must put the / on the ends of the alias and the directory or nothing will work, and no error will be reported. Helpful yes?

Now the alias has been defined we need set the server permissions (not to be confused with file system permissions) for the specific directory pointed to by the ScriptAlias directive. This is done like this

<Directory /usr/home/www_root/showsite/public_html/cgi-bin>
</Directory>

You will see that the above example is just like the VirtualHost directives in that it has to be terminated. What this means is that any directives enclosed in this was are only applied to the directory named in the <Directory> directive.

First we need to set the permissions for the cgi-bin directory named in the <Directory> directive, this is done in the form of options which are defined by the Options directive, which is used like this.

Options +ExecCGI

This does exactly what it says, it adds the ability to execute CGI scripts, The plus sign adds this ability, and the opposite is also true, if this was replaced with a minus sign then this ability is removed. Remember that as this is enclosed with <Directory></Directory> the Options +ExecCGI only applies to the named directory and will override any other Options settings else where in the httpd.conf

At this point the server knows that CGI is to be executed in this directory, now you need to tell the server what files are CGI, which is done by file extensions just like the Microsoft world. To do this you need to tell the server how to handle files with the specific extensions, which is done like this.

AddHandler cgi-script .cgi .pl

This adds a handler of the type cgi-script, and associates all files with the .cgi and .pl extensions to this handler, but only, as mentioned above in the directory named in the <Directory> directive. Its good practice to use .cgi for all your scripts, although you do not have to, what ever you define here will work. For this example I have defined both .cgi and .pl for the cgi file types, this is a standard that I use in sites developed, .pl is used for function libraries and .cgi for all the scripts.

After all this your CGI directory configuration looks like this.

<Directory /usr/home/www_root/showsite/public_html/cgi-bin>
        Options +ExecCGI
        AddHandler cgi-scripts .cgi .pl
</Directory>

A quick recap on this CGI stuff, the above example will allow for the execution of CGI scripts from the /usr/home/www_root/showsite/public_html/cgi-bin where these scripts have an extension of .cgi or .pl.

Now this is getting close to the end of this configuration, before this end is reached I need to go into file permissions as this is a vital part of CGI. Each file needs to have access permissions set with the following command

chmod 755 nameofscript

You can do this to each file or the whole cgi-bin directory, by replacing the 'nameofscript' with * when in the cgi-bin directory.

Thats it, you need to do nothing else to your script files.

At this point we have gone through the basic configuration directives for your virtual server under apache. At this point your full virtual server configuration should look something like this. (only the local.smallshop.com example is shown here)

NameVirtualHost 192.168.10.10
<VirtualHost 192.168.10.10>
        ServerName local.smallshop.com
        DocumentRoot /usr/home/www_root/showsite/public_html/
        ErrorLog /usr/home/www_root/showsite/error_log
        DirectoryIndex default.html
        ScriptAlias /cgi-bin/ /usr/home/www_root/showsite/public_html/cgi-bin/
        <Directory /usr/home/www_root/showsite/public_html/cgi-bin>
                Options +ExecCGI
                AddHandler cgi-scripts .cgi .pl
        </Directory>
</VirtualHost>

Now with the above you will be able to point your favorite browser at local.smallshop.com, you will get the simple HTML document called default.html that you copied into the /usr/home/smallshop/public_html directory earlier. Now if you do not get this document, you will need to go back and check the configuration, typos, spelling etc.

Links and Related Pages

• Starting Apache Server at boot time
• Basic Apache/PHP/MySQL Installation