Being a weekend server administrator, whenever I start a new server project, it unfailingly kicks off a second project, namely how to actually learn how to do some technical task the first project requires, one I can no longer fake by selective copying from somebody else's config file.

Today's self-taught lesson? How to set up subdomains on the Apache HTTP server.

A subdomain is a precursor that can be placed on a domain name. For instance, in "mail.yoursite.com" the word "mail" is the subdomain of the "yoursite.com" domain name.

For this walk-through on how I set up my own subdomains, I'm running my own Linux box, with Apache version 2.2.17,. And for purposes of this demonstration, I've not included any sudo prefixes, assuming you know when to use them, if you use 'em.

Step 1: Change your DNS Zone File

Before I dug into Apache to set up a subdomain, I let my domain name registrar know of the subdomains I wanted to use. To do this, I signed onto my registrar's site for managing my domain names, and went to edit my DNS Zone File.

A DNS Zone File is used by Internet routers to keep track of where to send traffic that comes to your domain name. Mail traffic can be forwarded to the mail server, while FTP traffic could be to a server with a different IP address, and so on.

Because Zone Files are not hierarchical, each subdomain must have its own entry in the file.

Anyway, when I got to the space where I could edit my DNS Zone File, I looked for the "CName" table, which documents the "alias" records. To create a new entry, I added the name of my subdomain under the host column, and an "@" sign under the "points to" column:

The "@" is shorthand for the IP address of the domain name, which was defined in the Host (or "A") table in the DNS Zone File.

And that's it, basically. Except for a bit of waiting.

It usually takes about an hour for the changes to the Zone File to propagate across the Net. You can tell if it has been activated by pinging it to see if you get a response back. In the first ping below, the subdomain has been registered in the zone file. In the second ping, that subdomain has not been registered.

If you're following along, you might have noticed that when you enter your subdomain.domain.com address into a browser -- once the Zone File has propagated across the Internet -- the server directs you to the main site's home page. That's a start.

Step 2: Change Apache Settings

In effect, you've instructed how the world to beat a path to your subdomain, and the rest of the work is concerns setting up the server to field the requests correctly! Now, it's time to configure Apache!

At the command line, with my text editor, I opened "apache2.conf" in the /etc/apache2 directory. As the name states it is the configuration file for Apache. At the bottom of the apache2.conf file, after the last commented text, "#Include the virtual host configurations" is where we need to add our additional configuration instructions that Apache will follow once it is restarted.

A virtual host, defined as Apache in code as VirtualHost, allows a single instance of Apache to run multiple sites. Each site gets its own configuration entry in the apache2.conf file. In Apache technical argot, you are creating multiple name-based VirtualHosts for the same IP number.

Depending on how your copy of Apache has been set up you may already see an entry for a virtual host, for the main site for the domain. Mine looked like this...

NameVirtualHost 75.99.43.16

<VirtualHost 75.99.43.16>
ServerName www.joabj.com
ServerAlias joabj.com
DocumentRoot /var/www
</VirtualHost>

To add in support for subdomains, I created a VirtualHost entry for each subdomain, using the same IP number. So for technique.joabj.com and fishing.joabj.com, I added these entries respectively...

<VirtualHost 75.99.43.16>
ServerName technique.joabj.com
DocumentRoot /var/www/Technique
</VirtualHost>

<VirtualHost 75.99.43.16>
ServerName fishing.joabj.com
DocumentRoot /var/www/fishing
</VirtualHost>

In these examples, the VirtualHost IP number is the same for the main (www.joabj.com) site. The ServerName entry indicated the name of the fully qualified Web address of the subdomain ("technique.joabj.com") and the DocumentRoot indicated where the root directory for this subdomain exists in the server's own file system ("/var/www/technique").

In effect, you could could build an entire site for the subdomain, based in the root document folder. Note you need an index.html in the subdomain's root directory for Apache to display some content when subdomain.domain.com is called.

And, as always, don't forget to restart your Apache server after making any configurations. In Ubuntu land, it is done thusly at the command line:

service apache2 restart

/etc/init.d/apache2 restart

Embarrassingly enough this took me about a week to figure out, but if you are running a blog on the subdomain and you want all the individual pages on the blog to be based on the subdomain address as well, then you have to make a settings change in the within Wordpress itself (or any other blogging platform that assembles pages on the fly I suppose). Specifically, you will need to change the default site address.

On Wordpress, you go to General --> Settings and enter the full subdomain address under "Site Address" thusly: