HomeDoor 2.0 User's Guide

HomeDoor Reference

 

This chapter deals with the fundamental operation of HomeDoor, covering both methods (redirection, implemented through the extension, and mapping, implemented through the plug-in). For related information, see Admin Reference and Appendixes.


Common Issues

 

Memory Requirements

Extension:

The HomeDoor 2.0 extension uses up to 512KB of RAM. No configuration for this memory usage is necessary on your part.

Plug-in:

The HomeDoor Plug-in uses up to 100 KB of RAM. You need to add 100 KB to WebSTAR's memory allocation, as follows:

 

Method Tradeoffs

Table 1 is a summary of the advantages and disadvantages of each method of implementing virtual Web servers. The principal tradeoffs are that redirection works with all browsers and all Web servers, but requires an IP address for each virtual server, while mapping works only with newer browsers, only with WebSTAR 1.3.2 or later, and uses just one IP address. See the Browsers Not Supporting the HTTP 1.1 Host Field appendix for a partial list of browsers which will not work with host field mapping.

Browser-independent redirection HTTP 1.1 host field mapping
+ Works with all browsers - Not supported by old browsers
+ Works with all servers - Requires new WebSTAR or other server
+ Can run on any Mac - Must run on the same Mac as WebSTAR
+ Each domain gets own IP address * - All domains merged into same IP address *
+ Visit-by-visit log available - No additional logging data available
+ Can support multiple servers concurrently - One copy needed for each server
   
- Requires 1 IP address per domain * + Just one IP address needed for all domains *
- Requires Ethernet IP network + Works with any IP network connection
- Changes URL in "Location" field + URL unchanged in "Location" field
- Only works on the default port (80) + Works on any port

Table 1. Advantages/Disadvantages of the Two Methods

* The requirement of browser-independent redirection for one IP address per domain is both an advantage and a disadvantage. One advantage is that you can provide a tangible IP address to the owner of the site, making them feel more like they are really running their own server (since, for instance, the address is separately pingable). Also, certain search engines require that a server have its own IP address for that search engine to work correctly (since, for efficiency reasons, they save the IP address rather than the host name). The disadvantage of requiring one IP address per domain is that, in some situations, IP addresses may be scarce resources.

 

The HomeDoor Log File

Browser-independent redirection works in such a way that, in general, only the first access from a particular browser to a particular host name goes through HomeDoor (see How Browser-Independent Redirection Works elsewhere in this chapter). Logging such accesses produces a very useful summary of the number of "visits" to a particular virtual Web site. So unlike the Web server's overall log, which lists every single "hit" to the server and pages within it, the HomeDoor log provides data that is often more meaningful. The HomeDoor log also serves as a good centralized information facility when HomeDoor is being used with multiple Web servers. Logging is turned on and off through the Redirection Preferences dialog. This dialog is covered in detail in the Redirection Status section of the Admin Reference.

Host field mapping, on the other hand, results in HomeDoor processing every single access to the Web server. Logging such accesses would provide no significant advantage over the server's logging mechanism, and is therefore not supported.

For redirection, 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 read by any word processor. The file consists of one line for each log entry. Each line consists of a number of fields delimited by tabs. Details of the log file format are found in the Log File Format appendix. The HomeDoor log can be processed and analyzed in real time by the LogDoor Multi-domain Web Site Monitor.

 

Backing Up HomeDoor

Browser-independent redirection:

To back up the settings for the redirection method, simply back up the extension.

Host field mapping:

The settings for host field mapping are stored in a preferences file "HomeDoor Plug-in Prefs" that resides in the same folder as the plug-in. To back up the plug-in's settings, just back up the preferences file.

 

Virtual Web Server Limitations

 

Where To Run HomeDoor

The HomeDoor extension can run on a Mac which is concurrently providing or accessing IP-based services via MacTCP or Open Transport's TCP/IP. Specifically, you can run the HomeDoor extension on the Mac that is running your Web server.

If you do run the HomeDoor extension on a Macintosh which is also running MacTCP or Open Transport's TCP/IP, you must be sure that HomeDoor is not configured with a URL for the IP address assigned to that Macintosh. Otherwise TCP/IP services may not function, since HomeDoor will take over that address.

If you wish to install the extension on one Macintosh and the plug-in on another, you will need to install a copy of Admin on each machine. The terms of your HomeDoor license allow this. This is the only situation where HomeDoor Admin may be copied, however.

 

URLs for Folders Not Ending With "/"

If a user specifies a URL for a folder within a virtual Web server but does not end the URL with a "/", the "real" server name will appear in the user's location field of their browser. Such a URL is technically invalid but when the server gets the request, instead of returning an error message it attempts to fix the URL by doing a redirect with the slash added. When doing so it also substitutes the "real" Web server's name, since it does not know the virtual server's name. For example, a request such as "http://www.companyX.com/foldername" would be redirected to "http://www.yourwebserver.com/companyX/foldername/".


Extension

 

How Browser-Independent Redirection Works

This section describes the interactions among a user, your DNS, the HomeDoor extension and your Web server. See Figure 1 below. The sample URLs and IP addresses are taken from the Configuring For Browser-Independent Redirection section of Getting Started.

1. A user requests the home page from site "http://www.companyX.com". This happens to be a virtual site served by HomeDoor, but neither the user nor the user's browser knows this. The browser asks the domain name system for the IP address for the hostname part of this URL. The DNS looks up "www.companyX.com" and returns the associated IP address, 10.0.0.1. This is in fact an address for HomeDoor, but the browser doesn't know this either.

2. The browser sends a request for the home page to address 10.0.0.1. The request goes to HomeDoor, which returns a URL pointing to the actual Web server and the appropriate subdirectory: "http://www.yourwebserver.com/companyX/". If the URL the user originally typed in was "http://www.companyX.com/filename", the URL returned by HomeDoor would be "http://www.yourwebserver.com/companyX/filename"; that is, HomeDoor would append the request's pathname to the URL that HomeDoor was configured with.

3. The browser asks the domain name system for the IP address for the host name part of this new URL, and the DNS returns 10.0.0.254.

4. Finally, the browser sends a request which includes the full URL of the page to address 10.0.0.254. This request goes to the Web server and the home page of the virtual server is returned.

In this simple example, the location field of the user's browser will show "http://www.yourwebserver.com/companyX" instead of "www.companyX.com". There is a way to not have your "real" server's domain name appear in the location field, and this is covered in the Browsers' Display of HomeDoor URLs section of this chapter.


Figure 1. How Redirection Works

 

Browser-independent redirection limitations

 

Browsers' Display of HomeDoor URLs

Most Web browsers have an area where they display the "location" of the current page. Many browsers will display the actual URL in this area (that is, the URL to which the browser has been redirected, not the original URL). Normally this URL will contain the "real" server's name. If it is desired that the "real" server's name not be displayed, you can have your network administrator set up a DNS alias to the actual Web server and use HomeDoor to redirect to that alias. For instance, instead of redirecting http://www.companyX.com to http://www.yourwebserver.com/companyX/, you could redirect it to http://www2.companyX.com/companyX/, where www2.companyX.com is a DNS alias to www.yourwebserver.com. A complete example of how to set up HomeDoor redirection and your DNS for this type of display is available in the Setup Example: Browser-Independent Redirection appendix. Open Door Networks also has a FAQ available on this subject.

 

Multiple Ethernet Ports

If the HomeDoor extension is running on a Macintosh with multiple Ethernet ports (for instance the built-in Ethernet and an Ethernet card), it will be active on the first Ethernet port it finds. The order the HomeDoor extension searches in is the built-in Ethernet first, followed by cards in slots in numerical order of the slots themselves (refer to your Macintosh's user guide for the specific numerical order of your Mac's slots). The Ethernet port used by the HomeDoor extension will not necessarily be the same as the port used by the Mac's AppleTalk or TCP/IP implementation.


Plug-in

 

How Host Field Mapping Works

Host field mapping takes advantage of a feature in the HTTP 1.1 specification (implemented by most recent browsers). HTTP 1.1 specifies a new field, the "host" field, which indicates the actual name of the specific Web server being accessed at a given address. Thus, to implement multi-domain Web service on a single machine with HTTP 1.1, it is no longer necessary to assign that machine multiple IP addresses.

To perform host field mapping, HomeDoor acts as a plug-in for WebSTAR 1.3.2 or later and compatible servers. HomeDoor must act as a plug-in because it must intercept all requests to the server before they are processed by that server, and map the HTTP 1.1 host field to a particular folder on the server. It must also process requests sent by old browsers that do not include the host field, and potentially map those requests to a particular error page. Unlike browser-independent redirection, HomeDoor can not receive requests directly because the machine on which it is running is only assigned a single IP address, which is managed by the Web server.

Following is the sequence of events when a user requests a page:

1. As shown in Figure 2, a user requests the home page from site "http://www.companyX.com". This happens to be a virtual site served by HomeDoor, but neither the user nor the user's browser knows this. The browser asks the domain name system for the IP address for the hostname part of this URL. The DNS looks up "www.companyX.com" and returns the associated IP address, 10.0.0.254. This is the address of the "real" server.

Figure 2.

 

In Figure 3, step 1, the browser requests the home page from IP address 10.0.0.254. The URL and host fields are also shown. In step 2, before the Web server performs any processing on this request, it passes the request intact to the HomeDoor plug-in. HomeDoor examines the host field in the request, and looks that field up in a table of the Web servers it is supporting. The table associates the host name of the virtual Web server (www.companyX.com) with a folder name (/companyX) on the actual Web server. HomeDoor then changes the pathname in the request to include the indicated folder name, and in step 3 passes the modified request back to the Web server. In step 4, the Web server returns the desired page. If the request is from a browser which does not include the host field, or the host being requested is not HomeDoor's table, HomeDoor by default passes the URL to the Web server unmodified, or can be configured to change the URL to point to an error page instead.


Figure 3. How Host Field Mapping Works

 

Running on Other Ports

Host field mapping will work on any port. To use a port other than the default one (port 80), just set up WebSTAR to use that port; whatever port WebSTAR uses, HomeDoor's host field mapping uses. Follow WebSTAR's documentation on how to set WebSTAR up to use a port other than the default.

 

Virtual SSL Servers

Although in theory HomeDoor Plug-in can be used to implement virtual SSL servers, such an implementation will not work, since digital certificates contain the actual domain name of the "real" SSL server. Users accessing a virtual SSL server would be returned an error message due to the mismatch of the virtual server's name and the name on the digital certificate.

 

HomeDoor Plug-in Messages

HomeDoor Plug-in will write messages to the display, and possibly to WebSTAR's log file. These messages will provide information about initialization, serious errors, and shutdown.

 

Activating And Deactivating HomeDoor Plug-in

To activate HomeDoor Plug-in:

  1. Drag HomeDoor Plug-in into WebSTAR's plug-in folder.
  2. Quit and restart WebSTAR.

To Deactivate HomeDoor Plug-in:

  1. Quit WebSTAR
  2. Drag HomeDoor Plug-in from WebSTAR's plug-in folder.
  3. Restart WebSTAR.


Back to Table of Contents
Back to Getting Started
Forward to Admin Reference