What is a subdomain? When you surf the web, you often see URLs like http://www.yoursite.com. In addition to that, you may see ones like http://games.yoursite.com. Instead of www, you have "games." This entire URL is a subdomain and "games" makes it unique from http://www.yoursite.com. URL redirection services such as CJB.Net give a subdomain by letting you vary the variable in the URL http://variable.cjb.net. Because even subdomains - which would normally be expensive because they point to unique IP addresses (which in turn, point to your server). However, I learned a trick which allows you to have unlimited subdomains by taking advantage of the $ENV{'HTTP_HOST'} variable (see Perl Case Study - Environment CGI).

This might be useful to you if you have:
1.your own domain name like http://www.yoursite.com
2.wildcard subdomains enabled on your server
3.Server Side Includes enabled on your server

How can you tell if you have wildcard subdomains enabled? Just type in any subdomain to your domain name. If something like http://perl.yoursite.com loads the same page as http://www.yoursite.com, then you have wildcard subdomains enabled (try several different subdomain possibilities to make sure).

What about Server Side Includes (abbreviated as SSI)? Create a text file (and put anything you'd like to in it, like "hello." We'll thus call it hello.txt. Then create a HTML page and put the following tag in the body:

<!--#include file="hello.txt"-->

Put these both in the same directory/folder on your server, then try to view them in your browser. If the browser printed out something like ...

[an error occurred while processing this directive]

... or nothing at all (!) your server is not SSI enabled.

If you're still with me, let's start on the script algorithm.

#!/usr/local/bin/perl
###############
# File: subdomains.cgi

#This will return the URL after http://
#If used on this server, it would have a value of library.advanced.org
$hostname = $ENV{'HTTP_HOST'};

#Notice that there are three parts to the URL
#(1) library (2) advanced (3) org
#In general, this is how subdomains are laid out - with the
#key difference being the first value (library).

#Use a split function to separate this $hostname into its three parts
#Conveniently, there is a period separating each part of the $hostname.
@parts = split(/\./,$hostname);

#Now we have:
#$parts[0] = "library";
#$parts[1] = "advanced";
#$parts[2] = "org";

#This will essentially be redirection. If you have not already read
#Perl Case Study - Redirect CGI, check it out now. Since
#$parts[1] and $parts[2] are the same for every subdomain, we
#want to work exclusively with $parts[0].

#Depending on what $parts[0] is, you will redirect the visitor to a
#specified URL. There is a modification of this routine which we
#will get to in a moment whereby you can dynamically create the
#specified page.

#Let's store the specified redirection URLs in a separate file. I'll
#call it urls.txt.

open(URLS,"urls.txt");
  @urls = <URLS>;
close(URLS);

foreach $pair(@urls) {
  $chomp($pair);
  ($subdomain,$url) = split(/\|/,$pair);
  if($subdomain eq $parts[0]) { print "Location: $url\n\n"; last }
}

Since this server doesn't allow wildcard subdomain names, we don't have an example installed to show you, but after consulting an Apache server administrator, I've been told that it is very simple to modify an Apache file on the server to enable this feature: "It's a matter of prepending one line in the DNS entry by two characters, then adding another line in your domain's section of the apache config." - aka Spock.

How do you implement this script? No your users will not have to type in the url to call the script directly (that would defeat the purpose of the subdomain-based redirection). Remember how I said that any subdomain would go to the index page on your server (index.shtml)? Well, if you have server side includes, you cound literally embed a call to execute the cgi script right in your index page! Your index.shtml page should consist of one line:

<!--#include virtual="subdomains.cgi"-->

And that's it. When the page (index.shtml - .shtml is the most common extension for server side include enabled pages but whatever the name of the default page that loads should work as long as it allows SSI) loads, the $ENV{'HTTP_HOST'} will capture the subdomain name that was entered in the browser to reach the page and you're on your way :)

As for the modification I mentioned in the script above, you have the option, in your urls.txt file to specify the file on your server to show. Instead of redirecting your visitors, just open the file:

open(URLS,"urls.txt");
  @urls = <URLS>;
close(URLS);

foreach $pair(@urls) {
  $chomp($pair);
  ($subdomain,$file) = split(/\|/,$pair);
  if($subdomain eq $parts[0]) {

     print "Content-type: text/html\n\n";

     open(PAGE,"$file");
     @page = <PAGE>;
     close(PAGE);

     foreach $line(@page) { print "$page\n"; }

     last
  }
}

This snippet of code in place of the redirection code will instead open a local file and return the contents of the page directly into the index.shtml file for display (this takes greater advantage of the server side include "dynamics" of index.shtml).

Can it capture the HTML of a page on someone elses server? Yes, but we haven't gotten around to learning this neat little function yet. Speaking of which ... check out the next case study :)

Last Updated August 11, 1999

Perl Case Study - News Grabber CGI