HomeDoor 2.0 User's Guide

Appendixes

 

Registering Domain Names

Before a domain name will be accessible on the Internet, you must first register the name with InterNIC (NIC stands for Network Information Center), or the registration authority for your country. Details of this procedure are given in Chapter 9 of Providing Internet Services via the Mac OS and Chapter 4 of Getting Your Apple Internet Server Online. Briefly, the process is:

You will be notified via e-mail when the registration is complete. The person assigned as Billing Contact will be sent an invoice for $100 within ten days of registration. This fee covers the first two years.

 


Registering Virtual Server Names with Search Engines

There are several issues relating to virtual servers and search engines:

There are techniques you can use to avoid these problems, one technique for each method of implementing virtual Web servers.

Redirection - Register a URL of the form "www2.companyX.com/companyX/".

Mapping - If you have chosen to always return an error page for unsupported browsers, those virtual servers will not be searchable by search engines that do not implement the host field. The default error-handling method or the optional method with the "home pages only" sub-option will work, but you must register a URL of the form "www.yourwebserver.com/companyX/", or alternatively, make a DNS alias to your "real" server and use that in the URL.

 


Setup Example: Browser-Independent Redirection

This example assumes you want to use redirection to implement virtual Web servers for company X and company Y. It also assumes you want the location field of the browser to not contain the "real" Web server's name when a virtual Web server is accessed. If you purchased HomeDoor as part of the Multi-domain Webmaster Suite, you should run Multi-domain DNS Assistant, which will take you through configuring your DNS step by step, and will automatically create theneeded files, saving you considerable work. If you did not purchase HomeDoor as part of the Multi-domain Webmaster Suite, as a HomeDoor user you can purchase the Suite at a special price. Contact Open Door Networks for ordering information.

We assume that you have chosen domain names of companyX.com and companyY.com, and host names of www.companyX.com and www.companyY.com. The actual Web server's host name is assumed to be www.yourwebserver.com at address 10.0.0.254. This example further assumes that you have registered the domain names yourwebserver.com, companyX.com and companyY.com with the InterNIC. Details on how to register domain names are in Registering Domain Names above. You only need to register these domain names if your pages are going to be accessed across the Internet. If your pages will only be accessed locally, domain name registration is not required.

Step 1. Acquire additional IP addresses for your virtual Web servers. Although these addresses do not have to be consecutive, they do have to be within a range of 255 addresses from each other. We'll assume the addresses you are given are 10.0.0.1 and 10.0.0.2. These addresses must be valid for the network on which the HomeDoor Macintosh will be placed.

Step 2. Configure your DNS to point the name www.companyX.com to the address 10.0.0.1 and www.companyY.com to 10.0.0.2. The files CompanyXHosts.txt and CompanyYHosts.txt are sample hosts files which you could use to do this configuration. You should first look at the file HomeDoorSampleHosts.txt, which is assumed to be the base host file, normally called simply "hosts" . This file contains general comments on the format of a DNS hosts file.

Step 3. Configure your DNS with DNS aliases to your actual Web server. These aliases, which are not strictly necessary, are used so that the "location" field, displayed in many Web browsers, shows the original domain name as opposed to your actual server's domain name. Specifically, configure your DNS so that www2.companyX.com and www2.companyY.com are both aliases to www.yourwebserver.com. See the CNAME statements in the sample hosts files for details.

Step 4. If desired, configure your DNS with mail host information for the CompanyX and CompanyY virtual domains. This step is only necessary if you will be providing mail service to these virtual domains and wish to be able to have mail addresses of the form name@CompanyX.com. You will also need to configure your mail server to accept mail to these domains, and to use a multi-domain mail product like MailDoor.

S tep 5. Configure reverse lookup information into your DNS. Reverse lookup information, as shown in the ReverseZones.txt file, is used to map IP addresses back to domain names. This step is in no way necessary, and in fact will only work if you are the only one providing primary name service for your domain. If your ISP is providing any primary name service for your domain, they must handle reverse lookup information.

Step 6. Create folders on your Web server for the company X and company Y virtual Web servers. We'll assume you create folders called CompanyX and CompanyY, respectively, at the root of your Web server. Create files called default.html (or whatever your server's default home page file name is) within each of these directories. These files are the default home pages for the virtual Web servers. Create any other files or directories within these directories that you wish to appear in the virtual Web servers.

Step 7. Configure HomeDoor with the redirection information. Specifically, in the Redirection window, the HomeDoor address range should be 10.0.0.1 to 10.0.0.2, with 10.0.0.1 redirected to http://www2.companyX.com/companyX/ and 10.0.0.2 redirected to http://www2.companyY.com/companyY/. Remember that the www2's have been configured to be DNS aliases to your actual Web server.

Step 8. Save the HomeDoor information. Be sure to restart the Macintosh if you have not done so since installing HomeDoor. The virtual domains www.companyX.com and www.companyY.com should now be active. Be sure to check them from a Macintosh other than the one on which HomeDoor is running.

 


Setup Example: Host Field Mapping

This example assumes you want to use host field mapping to implement virtual Web servers for company X and company Y.

We assume that you have chosen domain names of companyX.com and companyY.com, and host names of www.companyX.com and www.companyY.com. The actual Web server's host name is assumed to be www.yourwebserver.com at address 10.0.0.254. This example further assumes that you have registered the domain names yourwebserver.com, companyX.com and companyY.com with the InterNIC. Details on how to register domain names are in Registering Domain Names above. You only need to register these domain names if your pages are going to be accessed across the Internet. If your pages will only be accessed locally, domain name registration is not required.

Step 1. Configure your DNS to point the names www.companyX.com and www.companyY.com to 10.0.0.254 (the actual Web server's address).

Step 2. Create folders on your Web server for the CompanyX and CompanyY virtual Web servers. We'll assume you create folders called companyX and companyY, respectively, at the root of your Web server. Create files called default.html (or whatever your server's default home page file name is) within each of these directories. These files are the default home pages for the domains. Create any other files or directories within these directories that you wish to appear in the virtual domains.

Step 3. Configure HomeDoor by associating host names with folder names. In our example, in the Mapping window of HomeDoor Admin associate the pathname "/companyX" in the "Pathname to Insert" column with the host name "www.companyX.com" in the "Host Name" column, and likewise for "/companyY" and "www.companyY.com".

Step 4. Configure error handling. To get started, the default methods will suffice. For more detailed information, see the Error Configuration section of the Admin Reference.

 


Changing Methods

Redirection to Mapping: To change a virtual Web server from the original browser-independent redirection method to the new host field mapping method, do the following steps:

  1. Find the DNS zone file for the domain associated with the virtual server. In that file, make a list of all the entries which point to the HomeDoor-specific address you have been using for that server. There will usually just be one such entry, of the form www.companyX.com. In some cases, you may have made an alias (CNAME) to the HomeDoor address as well (for instance companyX.com in addition to www.companyX.com) The zone file may also have an entry of the form www2.companyX.com, but this entry should be pointing to your "real" server, not to the HomeDoor address. DO NOT INCLUDE WWW2 ALIASES IN THE LIST - only list entries which point to the HomeDoor address for the virtual server.

  2. Change all entries which point to the HomeDoor address for the virtual server to point to your "real" server instead. If you have an entry of the form www2.companyX.com, that entry should already be pointing to your "real" server, and should require no modification. Do not delete any entries. Do not save your changes yet.

  3. Enter the host name(s) from your list in step 1 (such as www.companyX.com) into the Mapping window of HomeDoor Admin, associating the pathname to the virtual server's folder with each of them (usually "/companyX"). YOU SHOULD NOT MAKE AN ENTRY FOR ANY WWW2 ALIAS. Save the changes.

  4. Save your DNS changes and restart your DNS if necessary. Remember that DNS entries are cached by end-user machines and by intermediate DNS's throughout the Internet. For this reason, your changes may not take effect for up to a day, so be sure to KEEP THE REDIRECTION ENTRY in HomeDoor for at least that period of time. If you wish to test your change immediately, you will need to go to a machine which is configured to use your DNS and restart that machine.

  5. If you have changed the Mapping error-handling preferences from the defaults, you may have to make additional changes, as indicated in the Error Configuration: Host not Found in Host List section of the Admin Reference.

Mapping to Redirection: To change a virtual Web server from the host field mapping method to the old browser-independent redirection method, do the following steps:

  1. Add the entry to Admin's Redirection window, as described in the Adding a Server Entry section of the Admin Reference.

  2. Change the DNS entry to use the new IP address. See "Browser-Independent Redirection Method" in the Pre-Configuration Tasks section of Getting Started.

  3. After several days, delete the virtual server's entry in the HomeDoor Admin Mapping window. As mentioned in the above section, due to DNS caching the changes in step 2 may not take effect for all users for a few days.

 


Log File Format

For redirection only, HomeDoor creates a log file which is useful for determining the number of visits to a virtual site. The HomeDoor log file is named HomeDoor Log and is stored in the Preferences folder within the system folder on the machine where the HomeDoor extension is installed. The log file is stored in text format, and can be processed by the LogDoor Multi-domain Web Site Monitor or read by any word processor. The file consists of one line for each log entry. Each entry consists of a number of fields, with each field delimited by a tab.

The first two fields in every HomeDoor log entry are always the date and time of the entry. The date is always in mm/dd/yy format, with two digits each for the month, day and year. The time is always in 24 hour format hh:mm:ss, with two digits each for the hour, minute and second.

HomeDoor log entries can be either status entries or access entries. In a status entry, the date and time fields are followed by a status information field. The status information field simply describes a significant event such as HomeDoor's loading or starting up or an error of some sort. Status entries should be self-explanatory. An example status entry is shown below:

04/08/96 09:57:46 A new HomeDoor configuration has been loaded.

Access entries are in a format which is meant to be compatible with programs which read and process WebSTAR log files. Specifically, the date and time are followed, in order, by status, IP address and URL fields.

Status - the status in HomeDoor access entries is always OK. This field is included for compatibility with WebSTAR log processing programs, and for future use.

04/08/96 09:58:00 OK 198.68.10.4 http://www2.companyX.com/companyX/file

In general, if HomeDoor logging is enabled, there will be one log file entry for each access made through HomeDoor's redirection method. Accesses made to pages not served by HomeDoor (such as those through relative URLs) will not be logged, nor will pages served through host field mapping. Under certain rare conditions involving retransmissions, there may be more than one log file entry for a particular access. Multiple consecutive log entries from the same IP address and for the same URL may indicate a network reliability problem.

 


Browsers Not Supporting the HTTP 1.1 Host Field

Below is a partial list of browsers known to not support the HTTP 1.1 "host" field. If you need HomeDoor to support a browser on this list, you must use HomeDoor's browser-independent redirection technique, as opposed to its host field mapping technique. A current lis t is available from Open Door Networks.

To build this list, we monitored hits to one of the Web servers we use to host customer pages for a four day period, between 4pm April 23, 1997 and 4pm April 27, 1997. Since we are a Web provider, hosting Web sites for a wide range of customers, we feel that our list is fairly representative, although we do not claim that this is a scientific study.

Summary:

Of over 56,000 total hits to the server, 4,441, or 8% did not contain the Host field. The most popular browsers were:

There also were a disproportionately large number of hits from unidentified browsers. Some of these were probably from search engines which don't implement the host field, but we are not sure what else falls in this category.

The number of hits from non-host-field browsers is diminishing rapidly. Our previous survey, taken less then four months ago, showed 19% of the hits from such browsers.

A more complete list of browsers:

Browser Hits
Agent: Kaylon Powermarks 11
ArchitextSpider 36
doctitle.pl/0.3 libwww-perl/0.40 5
Enhanced_Mosaic/2.01 Mac_68000 PSI/1 6
Enhanced_Mosaic/2.01a4 Win32 IBM/1 5
Lynx/2-4 libwww/2.14 95
Microsoft Internet Explorer/4.40.308 (Windows 95) 17
Mozilla/0.96 Beta (Windows) 6
Mozilla/1.0 (Windows) 8
Mozilla/1.0N (Macintosh) 9
Mozilla/1.0N (Windows) 147
Mozilla/1.1 (Windows; U; 16bit) 17
Mozilla/1.1 (X11; U; HP-UX A.09.07 9000/715) 9
Mozilla/1.12(Macintosh; I; PPC) 80
Mozilla/1.12I [ja] (Windows; I; 32bit) 6
Mozilla/1.1N (Macintosh; I; 68K) 159
Mozilla/1.1N (Macintosh; I; PPC) 11
Mozilla/1.1N (Windows; I; 16bit) 232
Mozilla/1.2 (Windows; U; 16bit) 6
Mozilla/1.22 (compatible; MSIE 2.0; Windows 3.1) 178
Mozilla/1.22 (compatible; MSIE 2.0; Windows 95) 247
Mozilla/1.22 (compatible; MSIE 2.0d; Windows NT) 56
Mozilla/1.22 (compatible; Quarterdeck Mosaic Version 2.03.001 /Windows/Domestic) 7
Mozilla/1.22 (Windows; I; 16bit) 788
Mozilla/1.2b5 (Windows; I; 16bit) 22
Mozilla/1.2N (Windows; I; 16bit) 19
Mozilla/2.0 (Compatible; AOL-IWENG 3.0; Win16) 8
Mozilla/2.0 (compatible; MSIE 2.1; Windows 3.1) 467
Mozilla/2.0 (compatible; MSIE 3.01; Windows 95) 12
Mozilla/2.0 Compatible (Macintosh;U;PPC) 31
Mozilla/2.10.28bS Win16 FTP Software/Spyglass/28bS 20
NetCruiser/V2.1.1 18
Netscape-Proxy/2.5 (Batch update) 6
PRODIGY-WB/3.2b 333
Quarterdeck Mosaic Version 1.01 13
Scholastic Search 8
SPRY_Mosaic/v7.36 (Windows 16-bit) SPRY_package/v4.00 88
Spyglass_Mosaic/2.10 Windows Datastorm/3.00 6
WebChat URL-Cache Server 5
WebCompass 2.0 36
   
Others 1208


URLs in HTML Documents

This appendix provides details of how to specify URLs on multi-domain Web servers which use HomeDoor to provide multi-domain Web service. The Overview section covers the broad issues, and the sections that follow provide in-depth details.

Overview

A particular virtual server on a multi-domain Web server can be accessed in one of two ways. Using the standard HomeDoor example, the virtual server www.companyX.com on the real server www.yourwebserver.com can be accessed as:

http://www.companyX.com

or

http://www.yourwebserver.com/companyX/

The first URL is usually preferred, but the second URL works as well (as do equivalent URLs with aliases for www.yourwebserver.com). When specifying a URL in an HTML document, if a URL of either of the above forms is used, it is called an "absolute URL." When specifying absolute URLs in HTML documents, either of the above forms can be used and should always work. An absolute URL reference can thus look like either:

<A HREF="http://www.companyX.com/path"> or
<A HREF="http://www.yourwebserver.com/companyX/path">

A second way of specifying a URL in an HTML document is a "fully relative URL." Fully relative URLs are always relative to the location of the document specifying the fully relative URL, and raise no significant issues*. A fully relative URL is always of the form:

<A HREF="path">

A third type of URL used in HTML documents is the "root-relative URL." Unlike the other two forms, root-relative URLs do raise issues, especially when used with HomeDoor's host field mapping method. A root relative URL is of the form:

<A HREF="/path">

and indicates that the path is relative to the root of the server on which the document specifying the root-relative URL resides. But, since a virtual server can be viewed as having two roots (the root of the virtual server and the root of the real server), root-relative URLs are ambiguous as to exactly what they're specifying. Root relative URLs should thus be avoided in HTML documents on virtual servers. If root-relative URLs must be specified, they should always be specified relative to the root of the real server. Details as to why are included in the sections below.

*See the URLs and Host Field Mapping section below for a minor issue regarding fully relative URLs and the use of the ".." construct.

Types of URLs - A Closer Look

There are three types of URLs which can be used in HTML documents:

Two Views

When specifying URLs, there are two possible views of a multi-domain server which can be taken. The first is to specify the URLs relative to the real server itself, and the second is to specify the URLs relative to the virtual server being created by HomeDoor.

Using the example in the HomeDoor Users' Guide, assume your real server is www.yourwebserver.com, and HomeDoor is creating a virtual server at www.companyX.com. The virtual server is actually stored in a folder called "companyX" at the root of www.yourwebserver.com.

URLs and Browser-Independent Redirection

HomeDoor's browser-independent redirection is a fairly straightforward technique which eliminates any ambiguity from root-relative URLs. Since browser-independent redirection works independently of the Web server, a very simple rule can be stated:

This rule is due to the fact that HomeDoor redirects the Web browser by giving the browser a full path to page being accessed (the only form of redirection allowed by HTTP). The browser then knows that the virtual server is really just a directory within your real server. Thus the browser always accesses items relative to the root of the real server, and thus all root-relative URLs are interpreted that way. (For HomeDoor experts, this access may be through a DNS alias to the real server of the form http://www2.companyX.com, but the principal remains the same -- the access is still relative to the root of the real server).

Additionally, with browser-independent redirection there are no issues with the ".." construct of directory-relative URLs, since the browser has a full view of your real server and can traverse up and down all directories within that server.

URLs and Host Field Mapping

Host field mapping works in concert with your Web server, and thus introduces ambiguity into root-relative URLs, plus causes some problems with the ".." construct of directory-relative URLs. Unlike browser-independent redirection, host field mapping fools the browser into really believing that each virtual server is a completely independent entity. Since the browser doesn't know anything about the real server on which the virtual server resides, it will always interpret root-relative URLs as relative to the root of the virtual server. From this point of view, the desired rule for host field mapping is:

There are a number cases where this rule is not desirable however:

These restrictions would probably be considered acceptable, however there are additional problems. The above rule assumes that the browser is accessing the pages off of the virtual Web server (that is, the first access was through a URL of the form http://www.companyX.com/path). It is also possible, however, for the browser to access the same pages off the real Web server (http://www.yourwebserver.com/companyX/path). Here are some examples:

Finally, there is an additional problem:

To summarize, in host field mapping all root-relative URLs must be relative to whichever server (real or virtual) the initial access to the pages is made through. Unfortunately most HTML is static code, and cannot change based on the initial access. Additionally, certain CGIs will generate HTML that assumes accesses are through the real server. Such HTML will not work when accessed through a virtual server.

What's to Be Done?

So what should be done about root-relative URLs? The simple answer is that they should not be used in a virtual server environment. Either absolute or fully relative URLs should be used, both of which are non-ambiguous. There may be situations, however, where such an answer is unacceptable, especially with some current CGIs.

Since we cannot always control whether accesses are made through the real Web server or the virtual one, the HomeDoor plug-in (which implements host field mapping) must attempt to resolve the ambiguity itself. Since current CGIs will always generate root-relative URLs relative to the root of the real server, and since that's also the way such URLs are specified for browser-independent redirection, the HomeDoor plug-in is implemented assuming the following rule:

As long as root-relative URLs are always specified in this way, the plug-in can resolve the ambiguity. It does so using the following simple rule:

There are a few limitations to this scheme:

Thus, the complete rule for host field mapping is:


Back to Table of Contents
Back to Troubleshooting