Building Web applications in Domino 6: A tutorial on Web site addressing

by
John
Chamberlain

Level: Beginner
Works with: Domino 6
Updated: 01-Oct-2002

What is a Web site? At first glance, this seems to be a trivial question. Everybody who browses the Web knows what a Web site is. A Web site is simply some place to go—a destination—on the World Wide Web. Web sites are discussed in newspaper columns and magazines, advertised in every kind of media imaginable including banner ads and spam, and hyperlinked from other Web sites (the web part of World Wide Web).

But who or what creates the destination? Essentially, a Web site is the online embodiment of something, somebody, or somewhere. Web sites represent all of the innumerable ways humans can organize themselves: individuals, communities, ethnic groups, religions, governments, educational and charitable institutions, businesses of all sizes—you name it, it's got a Web site.

What distinguishes one Web site from another? How you get there (the URL) certainly, but also content (the data on the site, such as pages and graphics), functionality (how site visitors interact with the content, such as navigation, reading, analysis, and perhaps creating new content), and security (who is allowed to visit the site and what privileges they are given).

So, we can define a Web site more technically as a uniquely-addressable Internet destination supporting HTTP (the HyperText Transfer Protocol) whose purpose is to provide content and functionality supplied by the entity that maintains the site, within the bounds of the security restrictions defined by that entity for the site.

With this definition in mind, we can assert that anyone who wants to create and maintain a Web site must answer three questions:

How will visitors get to my site?
Who will be allowed to visit my site?
What will visitors see and do when they get there?

This article explores the first question: How will visitors get to my site? The Domino 6 server implements the concept of Web sites with a new architecture that is very powerful, yet easy to set up and administer. This article discusses the fundamentals of Web site addressing and how they are implemented in Domino 6. It includes a short tutorial in creating multiple Web sites on a single Domino 6 server.

This article will be of interest to all system administrators and webmasters who plan to host Web sites with Domino 6. It assumes a familiarity with the Domino Directory and administrative tasks.

Internet addressing and Web sites
You are probably aware that machines attached to the Internet are assigned numeric IP addresses, and that the Internet Domain Name System (DNS) allows IP addresses to be mapped to human-friendly host names. For example, if you enter the URL http://www.lotus.com into a browser, the browser consults DNS to find the IP address of the machine that hosts the Lotus Web site. If you are unsure how all this works, take a look at the Basics of Internet addressing sidebar for an overview of the basic concepts of Internet addressing.

Suppose you visit www.lotus.com, located at the IP address 129.42.242.50, and then visit another Web site, for example www.ibm.com. You would assume that www.ibm.com would map to another address, and you would be right (it's 129.42.17.99). So, if you think of a "Web site" as being a destination with a unique host name such as www.lotus.com or www.ibm.com, then it seems a safe assumption that every Web site would have a unique IP address too.

But in fact that assumption is wrong. DNS does not enforce a one-to-one mapping of host names to IP addresses; it is perfectly possible, and in fact quite common, to have more than one host name mapped to the same IP address. Such host names are called aliases. In the Web server world, host name aliases allow a webmaster to set up multiple Web sites on the same physical machine. For example, the webmaster for Domino Inc., the fictitious company we'll use in our tutorial, may want to use one Web server, whose IP address is 9.95.65.107, to host the three Web sites: www.dominoinc.com, products.dominoinc.com, and support.dominoinc.dom. To do this, the webmaster simply notifies her DNS administrator (it may be the IT department or her ISP) to add those three names to the public DNS database and assign them all to 9.95.65.107.

The question is, when the dominoinc.com Web server receives a request, how does it know which logical Web site the request is for since the destination IP address in the packets will be the same for all three sites? The answer is in a feature of the HTTP protocol itself, the Host header. For example, if I request the URL http://products.dominoinc.com/whatsnew, the browser will generate an HTTP request that starts something like this:

GET /whatsnew HTTP/1.1
Host: products.dominoinc.com

In reality, the browser will typically send a lot more headers than this, but we're only concerned with Host for now. By examining the Host header, the destination server can determine which logical Web site the user wants.

The Host header is usually a direct copy of the hostname typed in the URL; this leads to some interesting cases. For example, if my machine is on the dominoinc.com intranet, the local name resolver will default to dominoinc.com; and I can just use the host name in the URL, typing http://products/whatsnew. In this case, the browser generates the request:

GET /whatsnew HTTP/1.1
Host: products

Or, if I happen to know the IP address of the dominoinc.com Web server, I could type http://9.95.65.107/whatsnew, and the browser would generate:

GET /whatsnew HTTP/1.1
Host: 9.95.65.107

The point is that the browser usually creates the Host header directly from the requested URL; it's up to the destination host to interpret it. The Domino 6 Web server can be configured to handle all three of the above examples, as we'll see later on.

(By the way, we're oversimplifying the HTTP protocol a bit. The Host header is optional for version 1.0 of the HTTP protocol; it's mandatory for version 1.1. All browsers in common use today send a Host header even if they are using HTTP 1.0. However, it is possible to use another client such as telnet to send an HTTP 1.0 request without a Host header. If Domino 6 receives an HTTP 1.0 request without a Host header, it will fall back to using the destination IP address as described below. Domino 6 will immediately reject an HTTP 1.1 request without a Host header.)

Preparing the client for the Domino 6 tutorial
Okay, we've gone over a lot of theory; now we're ready to try a real-life example in Domino 6. The rest of this article goes through a step-by-step tutorial that sets up a Domino 6 server to host three Web sites. The tutorial assumes you have administrator access to a Domino 6 server. You will also need a browser client—ideally a separate machine, but you can use a browser on the server. We will assume that your server and browser machines are using some version of Windows.

We will set up two Web sites:

www.dominoinc.com
products.dominoinc.com

You may wonder how you can use these names, since you're not in the dominoinc.com domain (in fact, as of this writing, this domain doesn't even exist). It's no problem because you can configure the address mappings for these names right on your own client.

All machines that support the TCP/IP protocols contain a "hosts" file somewhere in their system directories. This file contains a list of host names and IP addresses. In the early days of the Internet, the hosts file was the primary mechanism for name resolution. Keeping the hosts files synchronized across machines became a practical impossibility as the Internet grew, which was the chief reason for the development of DNS. Today the hosts file is still useful for cases where a machine cannot get access through DNS and for defining private name mappings, as in our tutorial.

On Windows platforms, the default location of the hosts file is:

Windows NT and 2000: c:\winnt\system32\drivers\etc\hosts
Windows 95/98: c:\windows\hosts

So to begin, use Notepad to open the hosts file on your browser machine. A default hosts file looks something like this:

Before adding lines for the tutorial Web sites, you need to know the IP address of your Domino 6 server. Go to the server machine, open a command prompt and enter the command line:

ipconfig

The result will look something like the following screen, showing the machine's IP address (in this case, the server is located at 9.95.26.100):

Now you can add the mappings for the Web sites to your hosts file on your browser machine. In addition to mapping the two sites we are going to set up, www.dominoinc.com and products.dominoinc.com, add a mapping for whoops.dominoinc.com, which we'll use to demonstrate how Domino 6 handles hosts that don't exist. Enter the following lines in the hosts file (be sure to substitute your server's actual IP address in the mappings):

9.95.26.100 www.dominoinc.com
9.95.26.100 products.dominoinc.com
9.95.26.100 whoops.dominoinc.com

When you're done, the hosts file should look something like this:

Now save the hosts file and close Notepad.

To test out the mappings, you can use the Ping command, which simply verifies that an IP address is reachable. Open a command prompt on your browser machine and enter the command:

ping www.dominoinc.com

The Ping command uses the hosts file to get the IP address of www.dominoinc.com and then tries to open a temporary connection to that address:

Use the Ping command with the other names you added to the hosts file. If you can successfully ping all three, your browser machine is all set. If you cannot ping the host, check the hosts file for inaccuracies.

Using the Domino 6 server Web Site document
In Domino R4 and R5, the HTTP protocol is configured mainly through settings in the Server document in the Domino Directory. There is also a Server\Web Configurations view in which URL mappings, file protection documents, and virtual servers (the R5 version of multiple Web sites) can be configured.

In Domino 6, all Internet protocols, including HTTP, are configured through Domino Directory documents in a new Server view called Internet Sites. For HTTP, this view combines the R5 functionality of the Server document and the Server\Web Configurations view. The primary HTTP configuration document in Domino 6 is the Web Site document. Most of the HTTP options in the R5 Server record have been moved to the Web Site document. Only a few low-level settings remain in the Server document, such as port assignments and threading options.

For this tutorial, we will assume that you are using a freshly-installed Domino 6 server. The Server\Internet Sites view starts out empty, but you'll soon correct that. First, take a look at the new Web Site document:

Open the server's Domino Directory (names.nsf) in Notes, and go to the Server\Internet Sites view.
Click the Add Internet Site button.
Select Web to open a new Web Site document.

All of the fields that identify the Web site are located on the Basics tab. Let's discuss each of the fields on this tab.

Descriptive name for this site
This is a text field that you can fill in with any helpful description of the site. The contents of this field appear in the view, so you can also control the sort order of the Web sites with this field.

Organization
The Internet Sites view is categorized on this field. If the server is running in ASP (application service provider) mode, this field must be set to the name of the registered hosted organization that owns this site. In non-ASP mode (such as in our tutorial), you can put any value you want in this field.

Use this web site to handle requests which cannot be mapped to any other web sites
This option is used to designate a "default" Web site. We'll describe the use of default Web sites later in this article.

Host names or addresses mapped to this site
This field is where you enter the list of one or more DNS host names and/or destination IP addresses that should be handled by this site. Normally, you would just list host names, expecting incoming requests to have valid Host headers. However, there are two cases where you must use IP addresses:

If the Web site is enabled for SSL, you must specify the IP address. That is because of a chicken-and-egg problem: the server can't read an SSL request's Host header until the request is decrypted, but the server can't decrypt the request without knowing which Web site's SSL keyring to use. Therefore, since the Host header is unavailable, the server must fall back to matching the destination IP address to a Web site.
If you expect your site to be accessed by HTTP 1.0 clients that may not send Host headers, for example, early versions of Internet-enabled applications.

Domino servers that host this site
This field lets you indicate which Domino servers that share this Domino Directory are actually set up to host this Web site. The values in this field must be hierarchical Domino server names (such as host1/dominoinc), not DNS names (such as www.dominoinc.com). You must specify at least one server. If all servers are hosting this Web site, you can specify an asterisk as a wildcard.

Other configuration options
The other tabs in the Web Site document contain all of the options that can be configured on a Web site level. There is a wide array of settings available, but we will not cover these tabs in this article. However, we will set the Home URL field in each site we create so that we can distinguish the sites in a browser.

Creating the sample Web Site documents
Let's go ahead now and create the Web sites. For now, follow this tutorial; later we will discuss why we created the sites in a particular order.

On the Basics tab, fill in the fields of the Web Site document as follows:


Field	Setting
Descriptive name for this site	1. Home site
Organization	Domino Inc.
Use this Web site to handle requests which cannot be mapped to any other Web sites	No
Host names or addresses mapped to this site	www.dominoinc.com
Domino servers that host this site	*

On the Configuration tab, set the Home URL field to /home.html.
Click the Save & Close button to save the Web site.
From the Internet Sites view, click the Add Internet Site button, and choose Web to create another Web Site document.

On the Basics tab, fill in the fields in this Web Site document as follows:


Field	Setting
Descriptive name for this site	2. Product site
Organization	Domino Inc.
Use this Web site to handle requests which cannot be mapped to any other Web sites	No
Host names or addresses mapped to this site	products.dominoinc.com
Domino servers that host this site	*

On the Configuration tab, set the Home URL field to /products.html.
Click the Save & Close button to save the Web site. The Internet Sites view will list the two Web Sites, as shown below:

$Server\Internet Sites view$

There is one more thing to do before you can test the sites. As explained above, the new Server\Internet Sites view replaces the functionality of the R5 Server\Web Configurations view. However, for backward compatibility with R5, the Domino 6 Web server will continue to use the old Server\Web Configurations view by default. To enable the new Server\Internet Sites view, you must change one setting in the Server document:

Go to the Server\Servers view and open the Server document.
On the left of the Basics tab, select "Loads Internet configurations from Server\Internet Sites documents" to enable this option:
Save the Server document.

Testing the sites
Next you need to create the home pages for the Web sites. A home page can be any type of resource supported by the Domino 6 Web server, for example, a document or view in a database, or a Java servlet. However, for this tutorial, you will use simple HTML files. You create these files in the Domino 6 server's main HTML directory, which by default is c:\Lotus\Domino\Data\domino\html. Using Notepad or any other convenient editor:

Create a file in the HTML directory called home.html. The file should contain this one line:

<html>This is the home page for www.dominoinc.com</html>
Create another file called products.html that contains this line:

<html>And this is the home page for products.dominoinc.com</html>
Create another file called default.html that contains this line (we'll use this file later):

<html>This is the default Web site</html>
Now you are ready to start the Web server. On the Domino 6 server console, enter the command:

load http

When the console displays the message HTTP Server: Started, you're ready to test your sites.

Open a browser on your client machine and enter the URL http://www.dominoinc.com. You should see the following home page:
Now enter the URL http://products.dominoinc.com. You should see the other home page:
To see what happens if you send a Host header that hasn't been mapped to a Web site, enter the URL http://whoops.dominoinc.com. An error is returned:

If the Domino 6 Web server cannot match a request to a Web site, it will refuse to process the request. This is a new security feature introduced for Domino 6 to help guard against DNS misconfigurations, which might inadvertently be caused by anyone in the chain of webmaster, IT department, and ISP.

It is a fact of life these days that all public Internet sites are constantly probed by attackers looking for open ports and misconfigured addresses. For this reason, we strongly recommend that you always use explicit host names for your sites and let Domino 6 reject requests that can't be mapped. However, Domino 6 also provides an alternative way to handle unmapped requests: the default Web site.

Setting up a default Web site
A default Web site is a special site that is not explicitly mapped to any host names or addresses. Domino 6 will use the default site to handle requests that cannot be mapped to any other site. For the security reasons just mentioned, we strongly recommend that you do not set up a default site on servers accessible through the public Internet. However, a default site may be convenient for test environments or low-security company intranets.

For now, let's accept the security risk and create a default site for Domino Inc. Note that there isn't any point in creating more than one default site, because Domino 6 will always use the first one it finds in the view.

Create a new Web Site document and fill in the Basics tab as follows. (Notice that when you set the Default site field to Yes, the "Host names and addresses mapped to this site" field will no longer be displayed.)


Field	Setting
Descriptive name for this site	3. Default site
Organization	Domino Inc.
Use this Web site to handle requests which cannot be mapped to any other Web sites	Yes
Domino servers that host this site	*

On the Configuration tab, set the Home URL field to /default.html (which you created earlier, before testing the site).
Save the new Web site.
On the Domino 6 server console, enter the command:

tell http restart

This causes the HTTP task to reload its configuration information.
Return to your browser and enter the URL http://whoops.dominoinc.com again. Instead of an error, you should now get the home page for the default site:

Mapping a Web site to an IP address
Now let's examine what happens with a Web site mapped to an IP address rather than a host name.

Create a new Web Site document and fill in the Basics tab as follows, using your server's actual IP address for the "Host names or addresses mapped to this site" field:


Field	Setting
Descriptive name for this site	0. Address site
Organization	Domino Inc.
Use this Web site to handle requests which cannot be mapped to any other Web sites	No
Host names or addresses mapped to this site	your server's IP address
Domino servers that host this site	*

On the Configuration tab, set the Home URL field to /address.html. Save the new Web Site document.
The Internet Sites view should now have four documents, as shown below:
Create the file address.html in the HTML directory with this line:

<html>This Web site is mapped to the IP address</html>
On the Domino 6 server console, enter the command:

tell http restart
Now go to your browser and enter the URL http://whoops.dominoinc.com once again. This time you get the home page for the IP address site:

whoops.dominoinc.com mapping to the IP address

Domino 6 matches the request to the Web site based on the destination IP address. However, there's a serious problem with our setup. If you enter the first URL, http://[www.dominoinc.com, again, you expect to get home.html but instead you'll see address.html. (Note that to see this in Internet Explorer, you may have to do a Ctrl-F5 to force the browser to refresh its cache).

www.dominoinc.com mapping to the IP address

This happens because Domino 6 scans the Internet Sites view from top to bottom and uses the first Web site that matches. If the first Web site specifies the IP address, then all requests directed to that address will match that site regardless of the Host header. To prevent this problem, you should make sure that sites identified by IP addresses are sorted below all sites identified by host names.

For our Domino Inc. sites, we can correct the situation by changing the Descriptive name for the IP address site from 0. Address site to 4. Address site.

By the way, mapping an IP address to a Web site also covers the case where the browser sends the IP address as the Host header, as described previously. This situation is very rare today, but you may occasionally encounter it when following links through a very old or very informal site. Since the applications on your Domino 6 server are under your control, you can and should require that all embedded links use host names, not IP addresses.

How Domino 6 matches requests to Web sites
To reinforce what we've learned working through the tutorial, here is the complete procedure Domino 6 follows to match an incoming request to a Web site:

Domino 6 scans the Internet Sites view from top to bottom. For each Web site, Domino 6 asks the question: Do any of the values in the Web site host names field match the request's Host header? If there is a match, then Domino 6 uses that site. If there isn't a match, then Domino 6 asks: Does any value in the host names field match the request's destination IP address? If there is a match, then Domino 6 uses that site. If there isn't, then Domino 6 proceeds to the next Web site in the view, repeating the questions.
If the request cannot be matched to any of the Web sites, then Domino 6 uses the default Web site, if one has been defined.
If there isn't a default Web site, then Domino 6 rejects the request and returns an error to the browser.

If the incoming request does not include a Host header or is SSL-encrypted, the procedure is the same except that Domino 6 matches only on the IP address.

Web site addressing best practices
As you can appreciate after working through the tutorial, properly setting up the addressing for your Web sites is critical for two reasons: insuring that your users get where they want to go and insuring that you have control over where users can try to go.

Here are our recommendations for configuring the addressing of Web sites for proper operation and greatest security:

Use DNS host names wherever possible to identify your Web sites. Note that the host name field allows multiple values to handle the case where a Web site has a number of host name aliases.
Use an IP address to identify a site only if it is explicitly required. There are only two common cases where an IP address is required: if a site supports SSL or if you know the site will be accessed by clients that do not send Host headers.
Make sure that the Internet Sites view is sorted so that all sites identified by IP addresses appear below sites identified by host names. Otherwise the IP-address sites may "hide" host name sites.
Do not create a default Web site on a server connected to the Internet or to any network where security is a concern. Let the server reject requests that cannot be mapped to a Web site.

Converting R5 Web sites to Domino 6
If you are currently using R5 for Web applications, you may wonder what will happen when you upgrade to Domino 6. As we discussed above, by default the Domino 6 Web server will continue to operate in R5 compatible mode, using the Server\Web Configurations view and all of the settings in the Server document. You tell the server to use the new Server\Internet Sites view by setting the Server document option "Loads Internet configurations from Server\Internet Sites documents," as you did in this tutorial.

The principle difference between R5 and Domino 6 is that the R5 HTTP server task always has an active default Web site. This default site is defined by the Server document settings on the Internet Protocols tab. The R5 administrator can define additional Web sites by creating Virtual Server and Virtual Host documents as responses to the Server document. These "virtual" sites inherit the default Web site options, except for the small number of settings that can be specified in the virtual site documents, the most important of which is the addressing of the site (host name or IP address). The most significant difference between a Virtual Server and a Virtual Host is that a Virtual Server is mapped to a destination IP address and can therefore be assigned its own SSL keyring, whereas a Virtual Host is mapped to a DNS host name and uses the default keyring (that is, the keyring specified in the Server document).

By contrast, Domino 6 does not have an automatic default site; if you want one, you must explicitly define it, as you did in the tutorial. Also, every Domino 6 Web site is completely independent of other sites, including the default site; there is no inheritance from the default site.

When you upgrade an R5 server to Domino 6, you are not required to immediately convert the HTTP task to the new view. However, if you want to use new Domino 6 features such as WebDAV, you must convert. Even if you are not required to convert to the new view, we strongly suggest that you do so as soon as practicable. Eventually you will want to take advantage of a Domino 6 feature that is only available with the new Internet Sites view.

About the author
John Chamberlain is a Software Quality Architect on the Domino 6 Web Server team.