// $Id: INSTALL.txt,v 1.6.2.7 2009-10-31 19:10:30 agentken Exp $ /** * @file * INSTALL file for Domain Access. */ Domain Access A domain-based access control system. CONTENTS -------- 1. Introduction 2. Installation 2.1 Before Installing 2.2 Server Configuration 2.3 Setting DOMAIN_INSTALL_RULE 2.4 Setting DOMAIN_EDITOR_RULE 2.5 Setting DOMAIN_SITE_GRANT 3. Patches to Drupal Core 3.1 multiple_node_access.patch 3.2 custom_url_rewrite_outbound.patch 4. Configuring settings.php 4.1 $base_url 4.2 $db_prefix 4.3 $cookie_domain 4.4 custom_url_rewrite_outbound() 4.4.1 Installation 4.4.2 Option 1 4.4.3 Option 2 4.4.4 Testing Your Configuration 4.4.5 Additional Resources 5. Additional Module Installation 5.1 Domain Configuration 5.2 Domain Prefix 5.3 Domain Strict 6. Uninstalling ---- 1. Introduction The Domain Access module is a Node Access module. It is designed to restrict access to content. WARNINGS: - Failure to install or uninstall this module according to instructions may cause errors in your site. - Node Access rules never apply to user 1 (the site admin) or to users with the 'administer nodes' permission. As such, these users will always be able to see all content on your site(s). To verify that Domain Access is working correctly, you will need to turn on its debug mode or view the site as a user without this permission. You may also enable the 'Enforce rules on adminstrators' setting, which will apply Domain Access restrcitions to all users. (See section 4.2.4 of README.txt for more details on this feature.) ---- 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. Domain Access works by reading the inbound HTTP_HOST request and serving content appropriate to the requested domain. For this to work properly, all domains for your site must be routed to the same Drupal installation on your webserver. Domain Access was not designed to run on shared hosts, and you may need assistance from your provider to make it 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. All existing nodes on your site will be assigned to the default domain for your web site and to all affiliates. If you wish to alter this behavior, see sections 2.4 through 2.6 of README.txt ---- 2.1 Before Installing You will need to do the following before you install the module. - Read this document - Configure your web server DNS records appropriately - Read the supplied README.txt - Install and configure Drupal normally. WARNING: The Domain Access module series instructs you to add several file includes to your settings.php file. Do not add these commands until after you have installed Drupal. ---- 2.2 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, (and so on) 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 - one.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: DocumentRoot /path/to/drupal/install ServerName ken.test ServerAlias *.ken.test foo.test 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: DocumentRoot /path/to/drupal/install ServerName ken.test DocumentRoot /path/to/drupal/install ServerName two.ken.test DocumentRoot /path/to/drupal/install ServerName foo.test 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. ---- 2.3 Setting DOMAIN_INSTALL_RULE This is an advanced instruction, and may be ignored. At the top of the domain.module file, you will find this line: define('DOMAIN_INSTALL_RULE', TRUE); This setting controls the default behavior of the module when installing over an existing installation. If set to TRUE, the Domain Access module will assign all existing nodes to be viewable by your primary domain. If you set this value to FALSE, existing content will not be visible on your primary domain unless DOMAIN_SITE_GRANT is set to TRUE. For more details, see section 5 of README.txt. ---- 2.4 Setting DOMAIN_EDITOR_RULE This is an advanced instruction, and may be ignored. At the top of the domain.module file, you will find this line: define('DOMAIN_EDITOR_RULE', FALSE); This setting controls the default behavior for affiliate editors. If DOMAIN_INSTALL_RULE is set to FALSE, you may change this value to TRUE if you intend to use editing controls. If this is set to TRUE, all existing nodes on your site will be editable by users who are assigned as editors of your root domain. See section 3 and section 5 of README.txt for more information. ---- 2.5 Setting DOMAIN_SITE_GRANT At the top of the domain.module file, you will find this line: define('DOMAIN_SITE_GRANT', TRUE); This setting controls the default behavior for viewing affiliate content. By design, the Domain Access module allows site administrators to assign content to 'all affiliates.' If this value is set to TRUE, then content assigned to all affiliates can be seen by all users on all current domains. On install, setting this value to TRUE will assign all current content to be viewable on all domains. Normally, you will not need to edit this value. ---- 3. Patches to Drupal Core (optional) The following patches are optional. They affect advanced behavior of the Domain Access module. Patches are distributed in the 'patches' folder of the download. To apply these patches, place them in your root Drupal folder. Then follow the instructions at: http://drupal.org/patch/apply ---- 3.1 multiple_node_access.patch You should apply this patch only if you use Domain Access along with another Node Access module, such as Organic Groups (OG). The multiple_node_access.patch allows Drupal to run more than one node access control scheme in parallel. Instead of using OR logic to determine node access, this patch uses subselects to enable AND logic for multiple node access rules. WARNING: This patch uses subselect statements and requires pgSQL or MySQL 4.1 or higher. To apply to patch, find the file: domain > patches > multiple_node_access.patch Copy the file to your root Drupal directory. From the command line, go to the Drupal root directory and run the command: patch -p0 < multiple_node_access.patch For more information, see http://drupal.org/patch/apply Developers: see http://drupal.org/node/191375 for more information. This patch is being submitted to Drupal core for version 7. ---- 3.2 custom_url_rewrite_outbound.patch This patch is only needed if: -- You wish to allow searching of all domains from any domain. -- You use a content aggregation module such as MySite. -- You get "access denied" errors when linking to items on a user's Track page. -- You want to turn on the advanced setting "Search Engine Optimization" to avoid content from being indexed on multiple domains. This patch allows modules to edit the path to a Drupal object. In the above cases, some content can only be viewed from certain domains, so we must write absolute links to that content. This patch introduces backports custom_url_rewrite_outbound() to Drupal 5. To apply to patch, find the file: domain > patches > custom_url_rewrite_outbound.patch Copy the file to your root Drupal directory. From the command line, go to the Drupal root directory and run the command: patch -p0 < custom_url_rewrite_outbound.patch For more information, see http://drupal.org/patch/apply After you install this patch, you must edit your settings.php file. See section 4.4 for detailed instructions. Developers: see http://drupal.org/node/207330 for more information. ---- 4. Configuring settings.php Remember, the Domain Access module lets you run multiple sites from a single installation. You only need one settings.php file. As a result, some options in your settings.php file need to be considered carefully. ---- 4.1 $base_url The $base_url setting is normally not set. With Domain Access, you cannot set this value manually. Since mutliple domains are involved, Drupal needs to be allowed to set this value. (For the technical, this happens in the conf_init() function). ---- 4.2 $db_prefix The $db_prefix value allows for table prefixing of your Drupal database in the event that you run more than one site from a single database. $db_prefix can be used normally with Domain Access. However, the Domain Prefix module provides for dynamic table prefixing based on the currently active domain. If you use the Domain Prefix module you can only set $db_prefix as a string value, not an array. For more detail, see INSTALL.txt in the domain_prefix folder. ---- 4.3 $cookie_domain By design, Drupal cookies are set for the current website on login. That is, if you login from www.example.com, the cookie will be set from the domain 'www.example.com.' However, a cookie from www.example.com is not valid on one.example.com. In order to provide for login across your active domains, you must set the $cookie_domain value to the string indicating your root domain. Typically, this value is '.example.com'. If your domains do not share the top-level, then you may need to login to each site separately or use a module such as Single SignOn. ---- 4.4 custom_url_rewrite_outbound() If you applied the custom_url_rewrite_outbound.patch, you must enable the function inside your settings.php file. The easiest way to do this is by using a PHP include to the file provided. If your site currently implements this function or its Drupal 5 equivalent, custom_url_rewrite(), you will need to make custom edits to your current file. Either move the function from domain/settings.inc into your current function, or vice versa. For more information, see http://api.drupal.org/api/function/custom_url_rewrite/5 ---- 4.4.1 Installation In the Domain Access download, find the following file: domain > settings_custom_url.inc You will need to load this file from inside your settings.php file. There are two methods for this. ---- 4.4.2 Option 1 -- Preferred This method is preferred, since any updates to the module release will be reflected in this file. NOTE: the elements inside the ==== marks are php code that should be copied into your settings.php file. DO NOT COPY THE ==== MARKS. Add the following lines to the end of your settings.php file: ==== /** * Add the custom_url_rewrite_outbound function. */ include './path/to/modules/domain/settings_custom_url.inc'; ==== In this case, change 'path/to/modules' with the directory where your modules are stored. Typically this will be 'sites/all/modules', which makes the lines: ==== /** * Add the custom_url_rewrite_outbound function. */ include './sites/all/modules/domain/settings_custom_url.inc'; ==== ---- 4.4.3 Option 2 If you are having difficulty determining the correct path, copy the file into your settings folder. domain > settings_custom_url.inc The file should be in the same directory as your active settings.php file. Then add the following lines: ==== /** * Add the custom_url_rewrite_outbound function. */ include 'settings_custom_url.inc'; ==== ---- 4.4.4 Testing Your Configuration After editing your settings.php file, go to Admin > Build > Domains. You may see a warning at the top of the page: "The custom_url_rewrite_outbound() patch is not installed..." This message means that your PHP server cannot find the include file. You may need to test other path options for the include code. ---- 4.4.5 Additional Resources If you are having trouble configuring the include, you should check your PHP include path. You may need to use an absolute path to your server root. http://us3.php.net/manual/en/ini.core.php#ini.include-path You may also copy the entire function custom_url_rewrite_outbound() directly into your settings.php file. ---- 5. Additional Module Installation The Domain Access module includes several sub-modules. Two of these have their own INSTALL.txt instructions. ---- 5.1 Domain Configuration Refer to domain > domain_conf > INSTALL.txt ---- 5.2 Domain Prefix Refer to domain > domain_prefix > INSTALL.txt ---- 5.3 Domain Strict While this module requires no additional installation, it fundamentally changes the behavior of the Domain Access module. Under Domain Strict, only authenticated users (those who have registered) are given any domain-specific privileges. Anonymous users will only be able to view content that is assigned to "all affiliates." As a result, enabling this module may cause content to disappear from your site for users who are not logged in. This is by design. Refer to domain > domain_strict > README.txt ---- 6. Uninstalling When you disable this module, it will reset your {node_access} tables and remove all records from the {domain_access} table. This will remove all access rules associated with this module. You may then uninstall the module normally. You should also revert the patches that you applied and remove any extra code from your settings.php file. To revert a patch, see http://drupal.org/patch/reverse