
 <  BEFORE INSTALLING  >

You will need to do the following before you install the module.

  - Read this document
  - Configure your web server's DNS records appropriately
  - Read the supplied README.txt
  - First install and configure Drupal normally.

IMPORTANT : The Domain Access module series instructs you to add some code,
actually a file include command, to your Drupal install's  settings.php file.
DO NOT add this command UNTIL AFTER you have installed your primary Drupal site.
----

 <  INSTALLATION  >

1.  Introduction

The Domain Access module is a Node Access module.  It is designed to partition
access to content over a series of one primary and one or more subdomains. 

The network established by Domain access functions with a single, central Drupal
install with a single settings.php file. The distribution of content across the
subdomains is accomplished through the adjustment of access permissions. There
are several ways to adjust your permissions both with DA and by enabling the
modules packaged with it or by adding other, contributed modules.

 [To get a better idea of these possibilities, please check the accompanying Readme.txt
  file as well as the install.txt files included with other modules in this package.]

WARNINGS: 
 - Failure to install or uninstall this module according to instructions
   may cause errors in your site.
 - Once DA is installed, the superuser [user ID1], who is by definition
   above permissions, will see all content assigned to any given page at
   all times. You must set some basic permissions and then log in as a
   simple anonymous or authenticated user (depending on how you have set
   up your permissions) to see Domain Access at work. This is not a system
   failure.  Domain Access was intentionally built to function in this fashion.
----

2.  Installation

This module requires some advanced understanding of Drupal and of how DNS servers behave.  
If you simply untar the download and activate the module, it may not work correctly.

For more background on DNS and virtual host configuration,
please try the following documentation:

For a general overview:
  - http://en.wikipedia.org/wiki/Virtual_hosting

In-depth documentation with many examples for specific situations:
  - http://httpd.apache.org/docs/2.0/vhosts/
  - http://httpd.apache.org/docs/2.0/vhosts/examples.html

When you enable the module, it will create a {domain} table in your Drupal database
as well as open a < Domains > section under Site Building in the Administer section
of the Drupal back-office.

On installation, all existing nodes [content] on your site will be assigned to the
default (primary) domain for your web site as well as  to all subdomains.  
In order to change this behavior, see sections 2.4 through 2.6 of README.txt
----

2.1    Server Configuration

For the module to work correctly, the DNS record of your server must accept
multiple DNS entries [most servers do]. Your new virtual host(s) must then
be correctly configured for your server.  In general, this involves small
additions to the hosts file and the httpd.conf file. 
In order for the Apache server to find your virtual host(s), it absolutely
needs two pieces of information: the ServerName (hostname & port the server
uses to identify itself) and an IP address. 

The two basic methods for doing this are to either:

  - Set up WildCard DNS, so that *.example.com resolves to your Drupal site.
    (The asterisk indicates “any and  all names” carrying the < example.com > suffix) 
  - Set up each VirtualHost specifically, so that one.example.com, two.example.com, etc.
    all resolve to your Drupal site.

For example, on a local testing machine, VirtualHosts in my hosts file could be
configured in the following way:

  - ken.test => 127.0.0.1
  - two.ken.test => 127.0.0.1
  - foo.test => 127.0.0.1

with their port and document root defined (WildCard set up) in the httpd.conf file:

<VirtualHost *:80>
DocumentRoot /path/to/drupal/install
ServerName ken.test
ServerAlias *.ken.test foo.test
</VirtualHost>

In this case any subdomain (*.ken.test) and another domain foo.test resolve to the
same location. When configuring DNS for Domain Access, the document root is the same
for all the VirtualHosts. The documentRoot directive sets the directory from which
httpd will serve files. For DA, there is one Drupal installation and it is this
installation built on a single database that is serving the files. 

This becomes even clearer when the VirtualHosts are set up specifically,
each with its own VirtualHost block in the httpd.conf file, for example:

<VirtualHost 127.0.0.1:80>
DocumentRoot /path/to/drupal/install
ServerName ken.test
</VirtualHost>

<VirtualHost 127.0.0.1:80>
DocumentRoot /path/to/drupal/install
ServerName two.ken.test
</VirtualHost>

<VirtualHost 127.0.0.1:80>
DocumentRoot /path/to/drupal/install
ServerName foo.test
</VirtualHost>

This example gives a general idea of what is involved, but It is beyond the scope
of this document to explain how to configure your specific DNS server situation,
which may involve considerable research, trial & error or a call for help.
Shared server situations can be particularly complicated and you should contact
their administration for help with configuration if their online help files do
not make things clear enough.

After you have enabled multiple DNS entries to resolve to your single, 
default Drupal installation, you may activate the module and configure its
settings at Admin > build > Domains in the Drupal back-office.

NOTE: When configured, the site name defined in the DA settings will 
override any previous definition in the Drupal back-office 
(Drupal > admin > settings > site-information) across all sites within your 
DA series [the same for: mission statement, slogan, footer, etc.].  To set
different Site Information for each subdomain, the Domain_conf module should
be enabled and configured [See Domain_Conf Readme.txt ].