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
- Create a new subfolder in your server root (the folder that contains
your server application)
- 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
- Simply go to the configuration menu and click on "List of hosts"
or enter pi_admin.welcome?hosts.
- Click at the position in the list where you like the new host to be
inserted.
- 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. |