Adding a Virtual Host


Domains and Hosts

Before we start, I have to make sure that everyone knows the difference between a "host" and a "domain". I will try to use the term "host" in this documentation, as it is more general as the term "domain":

A "domain" is something like "lycos.com" or "altavista.digital.com". It will *not* contain a reference to a specific computer name like "www" or "welcome". A "host" is a full reference. It starts with the name of the computer followed by the domain this host is located. Names like "www" are common for websites, but you can give your (virtual) server any name you like (e.g. welcome.comcon.de).

To add a virtual host, just

  1. Create a new subfolder in your server root (the folder that contains your server application)
  2. Create an entry in the host list which points to the new subfolder


Creating a subfolder

You can create up to 10000 virtual domains. Each virtual domain will have its own server root folder. You just need to create a new folder in the server root. This folder

  • should not contain slashes (/) or spaces
  • should not be too long (smaller is better)
  • can be of any name, they don't have to be named similiar to the virtual host they will contain

You even can create virtual root folders that are more than one level deep. e.g. you can create a folder named "comp1" which contains two other subfolders "sales" and "john_doe". These two subfolders will represent two new virtual hosts that may be accessed by sales.company1.com and john.company1.com:

    Server Root
    Server Application
    comp1
    index.html
    sales
    order.acgi
    john_doe
    home.ssi

In the example above there are three virtual domains that belong to company1:

  • www.company1.com (/comp1 + index.html)
  • sales.company1.com (/comp1/sales + order.acgi)
  • john.company1.com (/comp1/john_doe + home.ssi)


Adding an entry to the host list

  1. Simply go to the configuration menu and click on "List of hosts" or enter pi_admin.welcome?hosts.
  2. Click at the position in the list where you like the new host to be inserted.
  3. Click "Insert" and a new default entry will been generated before the selected item.

You will get a page where you can set the options for that virtual host:

Description
This field contains a brief description for the automatic host list. If you leave this field empty, this host is not included in the automatic host list. So you can decide to make only specific hosts public.

Virtual Host:
This is the host string. It can be anything, that is used to be between http:// and the first / in the url. Example: http://welcome.comcon.de:8080/test.html. You don't need to add :80 as it is default. This field cannot be empty.

Host Folder:
This is the relative path to the subfolder that will contain this virtual host. If you leave this empty, Welcome will use the real server root (not recommended).

Index File:
Every virtual host can have its own index file. There are three options you can choose:
none
- Welcome will not add anything to a path that ends in a "/". Use this option only if you are using another software that depends on urls that end in a slash (e.g. Starnine Directory Indexer)
original - Welcome will add the original index file (the one that is configured in the server prefs) if a path does not contain a file reference (in other words, the path ends in a "/")
file name - same as "original", but you can choose any name for the index file you like. This is the option you will use in most cases.

Error File:
Every virtual host can have its own error file. If you would like to use this field, you need to set the servers error configuration to "error.welcome". In this case, and if you leave "Error File:" empty, Welcome will use a built-in default error page.
To use this field, put a relative mac path (separated by ":") into it. The path should start with a ":" and will be relative to the servers root. Example: ":subfolder:myerror.txt"

Slash Handling (radio buttons at the bottom)
Normally, you don't have to change these settings. They are for compatibility with other plugins and cgis:

  • "Never add a slash" will not modify URLs if they are missing a slash. Take care, that this may produce unexpected results with URLs like www.foo.com/subfolder
  • "Simple check for missing slash" is the faster way to add the missing slash, but it fails for URLs that end in a file without a suffix
  • "Check for file/folder before adding a slash" is the recommended setting. It will do anything possible to process URLs that miss the ending slash

Hit Statistics
If you like to collect hits for this particular host, then check this checkbox. You can define a color by using the three color precentage fields. They will define a RGB Color in percent (0-100) and if your browser supports JavaScript, you can see the color displayed in realtime.
Please note, that if more than one host with the same subfolder exists, hits will be logged to the topmost host with the same subfolder (including the color of that host). In this case, you can think of the current host as an alias to the main virtual host (within a group of hosts sharing the same subfolder).



Multiple hosts with the same virtual subfolder

If you have some variations of hosts (e.g. www.foo.com, foo.com and your IP address) you should add all these to the list of hosts and set their subfolders to be the same. Welcome checks if any hosts have the same subfolder and will declare their topmost host the "default" host for that subfolder. It will receive all the hists and it will be used if an old browsers includes the subfolder in a request. There is no need to group these hosts together in clusters - if they share a subfolder, they belong together.