| 1 |
// $Id: INSTALL.txt,v 1.25 2009/10/31 18:28:32 agentken Exp $
|
| 2 |
|
| 3 |
/**
|
| 4 |
* @file
|
| 5 |
* INSTALL file for Domain Access.
|
| 6 |
*/
|
| 7 |
|
| 8 |
Domain Access
|
| 9 |
A domain-based access control system.
|
| 10 |
|
| 11 |
CONTENTS
|
| 12 |
--------
|
| 13 |
|
| 14 |
1. Introduction
|
| 15 |
2. Installation
|
| 16 |
2.1 Before Installing
|
| 17 |
2.2 Server Configuration
|
| 18 |
2.3 Setting DOMAIN_INSTALL_RULE
|
| 19 |
2.4 Setting DOMAIN_SITE_GRANT
|
| 20 |
2.5 Setting DOMAIN_ASSIGN_USERS
|
| 21 |
3. Installing the Module
|
| 22 |
3.1 After Installation
|
| 23 |
4. Configuring settings.php
|
| 24 |
4.1 $base_url
|
| 25 |
4.2 $db_prefix
|
| 26 |
4.3 $cookie_domain
|
| 27 |
4.4 Add settings.inc
|
| 28 |
4.4.1 Installation
|
| 29 |
4.4.2 Option 1
|
| 30 |
4.4.3 Option 2
|
| 31 |
4.4.4 Testing Your Configuration
|
| 32 |
4.4.5 Additional Resources
|
| 33 |
4.5 custom_url_rewrite_outbound()
|
| 34 |
5. Additional Module Installation
|
| 35 |
5.1 Domain Strict
|
| 36 |
6. Uninstalling
|
| 37 |
|
| 38 |
----
|
| 39 |
1. Introduction
|
| 40 |
|
| 41 |
The Domain Access module is a Node Access module. It is designed to
|
| 42 |
restrict access to content.
|
| 43 |
|
| 44 |
WARNINGS:
|
| 45 |
- Failure to install or uninstall this module according to instructions
|
| 46 |
may cause errors in your site.
|
| 47 |
- Node Access rules never apply to user 1 (the site admin) or to users
|
| 48 |
with the 'administer nodes' permission. As such, these users will always
|
| 49 |
be able to see all content on your site(s). To verify that Domain Access
|
| 50 |
is working correctly, you will need to turn on its debug mode or view the
|
| 51 |
site as a user without this permission. You may also enable the 'Enforce
|
| 52 |
rules on adminstrators' setting, which will apply Domain Access
|
| 53 |
restrcitions to all users. (See section 4.3.3 of README.txt for more
|
| 54 |
details on this feature.)
|
| 55 |
|
| 56 |
----
|
| 57 |
2. Installation
|
| 58 |
|
| 59 |
This module requires some advanced understanding of Drupal and of
|
| 60 |
how DNS servers behave. If you simply untar the download and
|
| 61 |
activate the module, it may not work correctly.
|
| 62 |
|
| 63 |
Domain Access works by reading the inbound HTTP_HOST request
|
| 64 |
and serving content appropriate to the requested domain. For this to
|
| 65 |
work properly, all domains for your site must be routed to the same
|
| 66 |
Drupal installation on your webserver.
|
| 67 |
|
| 68 |
Domain Access was not designed to run on shared hosts, and you may need
|
| 69 |
assistance from your provider to make it work correctly.
|
| 70 |
|
| 71 |
For more background on DNS and virtual host configuration, please try the
|
| 72 |
following documentation:
|
| 73 |
|
| 74 |
For a general overview:
|
| 75 |
- http://en.wikipedia.org/wiki/Virtual_hosting
|
| 76 |
|
| 77 |
In-depth documentation with many examples for specific situations:
|
| 78 |
- http://httpd.apache.org/docs/2.0/vhosts/
|
| 79 |
- http://httpd.apache.org/docs/2.0/vhosts/examples.html
|
| 80 |
|
| 81 |
When you enable the module, it will create a {domain} table in your Drupal
|
| 82 |
database.
|
| 83 |
|
| 84 |
On installation, all existing nodes on your site will be assigned to the default
|
| 85 |
(primary) domain for your web site as well as to all subdomains.
|
| 86 |
In order to change this behavior, see sections 2.3 and 2.4 below.
|
| 87 |
|
| 88 |
----
|
| 89 |
2.1 Before Installing
|
| 90 |
|
| 91 |
You will need to do the following before you install the module.
|
| 92 |
|
| 93 |
- Read this document
|
| 94 |
- Configure your web server DNS records appropriately
|
| 95 |
- Read the supplied README.txt
|
| 96 |
- Install and configure Drupal normally.
|
| 97 |
|
| 98 |
WARNING: The Domain Access module series instructs you to add a
|
| 99 |
file include to your settings.php file. Do not add this command until
|
| 100 |
after you have installed Drupal.
|
| 101 |
|
| 102 |
----
|
| 103 |
2.2 Server Configuration
|
| 104 |
|
| 105 |
For the module to work correctly, the DNS record of your server must accept
|
| 106 |
multiple DNS entries [most servers do]. Your new virtual host(s) must then
|
| 107 |
be correctly configured for your server. In general, this involves small
|
| 108 |
additions to the hosts file and the httpd.conf file.
|
| 109 |
|
| 110 |
In order for the Apache server to find your virtual host(s), it absolutely
|
| 111 |
needs two pieces of information: the ServerName (hostname & port the server
|
| 112 |
uses to identify itself) and an IP address.
|
| 113 |
|
| 114 |
The two basic methods for doing this are to either:
|
| 115 |
|
| 116 |
- Set up WildCard DNS, so that *.example.com resolves to your Drupal site.
|
| 117 |
(The asterisk indicates any and all names carrying the < example.com >
|
| 118 |
suffix)
|
| 119 |
- Set up each VirtualHost specifically, so that one.example.com,
|
| 120 |
two.example.com, (and so on) all resolve to your Drupal site.
|
| 121 |
|
| 122 |
For example, on a local testing machine, VirtualHosts in my hosts file could be
|
| 123 |
configured in the following way:
|
| 124 |
|
| 125 |
- ken.test => 127.0.0.1
|
| 126 |
- one.ken.test => 127.0.0.1
|
| 127 |
- two.ken.test => 127.0.0.1
|
| 128 |
- foo.test => 127.0.0.1
|
| 129 |
|
| 130 |
With their port and document root defined (WildCard set up) in the httpd.conf
|
| 131 |
file:
|
| 132 |
|
| 133 |
<VirtualHost *:80>
|
| 134 |
DocumentRoot /path/to/drupal/install
|
| 135 |
ServerName ken.test
|
| 136 |
ServerAlias *.ken.test foo.test
|
| 137 |
</VirtualHost>
|
| 138 |
|
| 139 |
In this case any subdomain (*.ken.test) and another domain foo.test resolve to
|
| 140 |
the same location. When configuring DNS for Domain Access, the document root is
|
| 141 |
the same for all the VirtualHosts. The documentRoot directive sets the directory
|
| 142 |
from which httpd will serve files. For DA, there is one Drupal installation and
|
| 143 |
it is this installation built on a single database that is serving the files.
|
| 144 |
|
| 145 |
This becomes even clearer when the VirtualHosts are set up specifically,
|
| 146 |
each with its own VirtualHost block in the httpd.conf file, for example:
|
| 147 |
|
| 148 |
<VirtualHost 127.0.0.1:80>
|
| 149 |
DocumentRoot /path/to/drupal/install
|
| 150 |
ServerName ken.test
|
| 151 |
</VirtualHost>
|
| 152 |
|
| 153 |
<VirtualHost 127.0.0.1:80>
|
| 154 |
DocumentRoot /path/to/drupal/install
|
| 155 |
ServerName two.ken.test
|
| 156 |
</VirtualHost>
|
| 157 |
|
| 158 |
<VirtualHost 127.0.0.1:80>
|
| 159 |
DocumentRoot /path/to/drupal/install
|
| 160 |
ServerName foo.test
|
| 161 |
</VirtualHost>
|
| 162 |
|
| 163 |
This example gives a general idea of what is involved, but it is beyond the
|
| 164 |
scope of this document to explain how to configure your specific DNS server
|
| 165 |
situation, which may involve considerable research, trial & error or a call for
|
| 166 |
help. Shared server situations can be particularly complicated and you should
|
| 167 |
contact their administration for help with configuration if their online help
|
| 168 |
files do not make things clear enough.
|
| 169 |
|
| 170 |
After you have enabled multiple DNS entries to resolve to your single,
|
| 171 |
default Drupal installation, you may activate the module and configure its
|
| 172 |
settings at Admin > Build > Domains.
|
| 173 |
|
| 174 |
----
|
| 175 |
2.3 Setting DOMAIN_INSTALL_RULE
|
| 176 |
|
| 177 |
This is an advanced instruction, and may be ignored.
|
| 178 |
|
| 179 |
At the top of the domain.module file, you will find this line:
|
| 180 |
|
| 181 |
define('DOMAIN_INSTALL_RULE', TRUE);
|
| 182 |
|
| 183 |
This setting controls the default behavior of the module when installing over
|
| 184 |
an existing installation. If set to TRUE, the Domain Access module will assign
|
| 185 |
all existing nodes to be viewable by your primary domain.
|
| 186 |
|
| 187 |
If you set this value to FALSE, existing content will not be visible on your
|
| 188 |
primary domain unless DOMAIN_SITE_GRANT is set to TRUE.
|
| 189 |
|
| 190 |
For more details, see section 5 of README.txt.
|
| 191 |
|
| 192 |
----
|
| 193 |
2.4 Setting DOMAIN_SITE_GRANT
|
| 194 |
|
| 195 |
At the top of the domain.module file, you will find this line:
|
| 196 |
|
| 197 |
define('DOMAIN_SITE_GRANT', TRUE);
|
| 198 |
|
| 199 |
This setting controls the default behavior for viewing affiliate content.
|
| 200 |
By design, the Domain Access module allows site administrators to assign
|
| 201 |
content to 'all affiliates.' If this value is set to TRUE, then content
|
| 202 |
assigned to all affiliates can be seen by all users on all current domains.
|
| 203 |
|
| 204 |
On install, setting this value to TRUE will assign all current content to
|
| 205 |
be viewable on all domains.
|
| 206 |
|
| 207 |
Normally, you will not need to edit this value.
|
| 208 |
|
| 209 |
----
|
| 210 |
2.5 Setting DOMAIN_ASSIGN_USERS
|
| 211 |
|
| 212 |
At the top of the domain.module file, you will find this line:
|
| 213 |
|
| 214 |
define('DOMAIN_ASSIGN_USERS', TRUE);
|
| 215 |
|
| 216 |
After you install the Domain Access module, all new users who
|
| 217 |
register will automatically be assign to the domain from which
|
| 218 |
their account was created. This value is used to determine
|
| 219 |
advanced editing access and can be used by modules such as
|
| 220 |
Domain Strict.
|
| 221 |
|
| 222 |
On install, setting this value to TRUE will assign all current users
|
| 223 |
to be members of the default domain. Set the value to FALSE
|
| 224 |
and the module will not assign users to any domains.
|
| 225 |
|
| 226 |
Normally, you will not need to edit this value.
|
| 227 |
|
| 228 |
After installation and configuration, users with the appropriate
|
| 229 |
permissions may batch assign users to domains from
|
| 230 |
Administer > User Management > Users.
|
| 231 |
|
| 232 |
----
|
| 233 |
3. Installing the Module
|
| 234 |
|
| 235 |
After you have prepared your server and made any edits to the
|
| 236 |
default module behavior, you may install Domain Access like any
|
| 237 |
other Drupal module.
|
| 238 |
|
| 239 |
----
|
| 240 |
3.1 After Installation
|
| 241 |
|
| 242 |
Note that as of 6.x.2.0, the primary domain is created for you on
|
| 243 |
installation.
|
| 244 |
|
| 245 |
The primary domain will use the SERVER_NAME value of the request made
|
| 246 |
when installing the module. This value may be edited by going to
|
| 247 |
Admin > Build > Domains and editing the Primary Domain value.
|
| 248 |
|
| 249 |
After you install the module, you should visit Admin > Users > Permissions
|
| 250 |
and set the module permissions; normally you will give your site
|
| 251 |
administrators the following permissions:
|
| 252 |
|
| 253 |
-- 'administer domains'
|
| 254 |
-- 'set domain access'
|
| 255 |
|
| 256 |
After saving permissions, go to Admin > Build > Domains and configure
|
| 257 |
your site's Primary Domain.
|
| 258 |
|
| 259 |
For more information, see README.txt.
|
| 260 |
|
| 261 |
----
|
| 262 |
4. Configuring settings.php
|
| 263 |
|
| 264 |
Remember, the Domain Access module lets you run multiple sites
|
| 265 |
from a single installation. You only need one settings.php file.
|
| 266 |
|
| 267 |
As a result, some options in your settings.php file need to be
|
| 268 |
considered carefully.
|
| 269 |
|
| 270 |
----
|
| 271 |
4.1 $base_url
|
| 272 |
|
| 273 |
The $base_url setting is normally not set. With Domain Access, you
|
| 274 |
cannot set this value manually.
|
| 275 |
|
| 276 |
Since mutliple domains are involved, Drupal needs to be allowed to
|
| 277 |
set this value. (For the technical, this happens in the conf_init()
|
| 278 |
function).
|
| 279 |
|
| 280 |
----
|
| 281 |
4.2 $db_prefix
|
| 282 |
|
| 283 |
The $db_prefix value allows for table prefixing of your Drupal database
|
| 284 |
in the event that you run more than one site from a single database.
|
| 285 |
|
| 286 |
$db_prefix can be used normally with Domain Access.
|
| 287 |
|
| 288 |
However, the Domain Prefix module provides for dynamic table prefixing
|
| 289 |
based on the currently active domain. If you use the Domain Prefix module
|
| 290 |
you can only set $db_prefix as a string value, not an array.
|
| 291 |
|
| 292 |
For more detail, see INSTALL.txt in the domain_prefix folder.
|
| 293 |
|
| 294 |
----
|
| 295 |
4.3 $cookie_domain
|
| 296 |
|
| 297 |
By design, Drupal cookies are set for the current website on login. That is, if
|
| 298 |
you login from www.example.com, the cookie will be set from the domain
|
| 299 |
'www.example.com.'
|
| 300 |
|
| 301 |
However, a cookie from www.example.com is not valid on one.example.com.
|
| 302 |
|
| 303 |
In order to provide for login across your active domains, you must set the
|
| 304 |
$cookie_domain value to the string indicating your root domain.
|
| 305 |
|
| 306 |
Typically, this value is '.example.com'.
|
| 307 |
|
| 308 |
If your domains do not share the top-level, then you may need to login to
|
| 309 |
each site separately or use a module such as Single SignOn.
|
| 310 |
|
| 311 |
NOTE: After you change your cookie value, you will need to logout and
|
| 312 |
log back in for the new cookie to take effect.
|
| 313 |
|
| 314 |
----
|
| 315 |
4.4 Add settings.inc
|
| 316 |
|
| 317 |
For Domain Access to work, you must add some code to your settings.php
|
| 318 |
file. This code will load the Domain Access bootstrap routines that determine
|
| 319 |
how your site is being requested.
|
| 320 |
|
| 321 |
If you do not add settings.inc to your settings.php file, Domain Access will
|
| 322 |
fail to load and report an error message to site administrators.
|
| 323 |
|
| 324 |
IMPORTANT: You must add these lines to settings.php after the $db_url
|
| 325 |
has been set; otherwise, Drupal will fail to load. Normally, you should add
|
| 326 |
these lines to the end of the settings.php file.
|
| 327 |
|
| 328 |
----
|
| 329 |
4.4.1 Installation
|
| 330 |
|
| 331 |
In the Domain Access download, find the following file:
|
| 332 |
|
| 333 |
domain > settings.inc
|
| 334 |
|
| 335 |
You will need to load this file from inside your settings.php file. There
|
| 336 |
are two methods for this.
|
| 337 |
|
| 338 |
----
|
| 339 |
4.4.2 Option 1 -- Preferred
|
| 340 |
|
| 341 |
This method is preferred, since any updates to the module release
|
| 342 |
will be reflected in this file.
|
| 343 |
|
| 344 |
NOTE: the elements inside the ==== marks are php code that
|
| 345 |
should be copied into your settings.php file. DO NOT COPY THE ==== MARKS.
|
| 346 |
|
| 347 |
Add the following lines to the end of your settings.php file:
|
| 348 |
|
| 349 |
====
|
| 350 |
/**
|
| 351 |
* Add the domain module setup routine.
|
| 352 |
*/
|
| 353 |
include './path/to/modules/domain/settings.inc';
|
| 354 |
====
|
| 355 |
|
| 356 |
In this case, change 'path/to/modules' with the directory where your modules are
|
| 357 |
stored. Typically this will be 'sites/all/modules', which makes the lines:
|
| 358 |
|
| 359 |
====
|
| 360 |
/**
|
| 361 |
* Add the domain module setup routine.
|
| 362 |
*/
|
| 363 |
include './sites/all/modules/domain/settings.inc';
|
| 364 |
====
|
| 365 |
|
| 366 |
----
|
| 367 |
4.4.3 Option 2
|
| 368 |
|
| 369 |
If you are having difficulty determining the correct path, copy the following
|
| 370 |
files into your settings folder.
|
| 371 |
|
| 372 |
domain > domain.bootstrap.inc
|
| 373 |
domain > settings.inc
|
| 374 |
domain > settings_custom_url.inc
|
| 375 |
|
| 376 |
The files should be in the same directory as your active settings.php file.
|
| 377 |
Then add the following lines:
|
| 378 |
|
| 379 |
====
|
| 380 |
/**
|
| 381 |
* Add the custom_url_rewrite_outbound function.
|
| 382 |
*/
|
| 383 |
include 'settings.inc';
|
| 384 |
====
|
| 385 |
|
| 386 |
----
|
| 387 |
4.4.4 Testing Your Configuration
|
| 388 |
|
| 389 |
After editing your settings.php file, go to Admin > Build > Domains. You may
|
| 390 |
see a warning at the top of the page:
|
| 391 |
|
| 392 |
"Domain access failed to load during phase: -1. Please check your settings.php
|
| 393 |
file and site configuration."
|
| 394 |
|
| 395 |
This message means that your PHP server cannot find the include file. You
|
| 396 |
may need to test other path options for the include code.
|
| 397 |
|
| 398 |
----
|
| 399 |
4.4.5 Additional Resources
|
| 400 |
|
| 401 |
If you are having trouble configuring the include, you should check your
|
| 402 |
PHP include path. You may need to use an absolute path to your server root.
|
| 403 |
|
| 404 |
http://us3.php.net/manual/en/ini.core.php#ini.include-path
|
| 405 |
|
| 406 |
You may also copy the entire function custom_url_rewrite_outbound() directly
|
| 407 |
into your settings.php file.
|
| 408 |
|
| 409 |
----
|
| 410 |
4.5 custom_url_rewrite_outbound()
|
| 411 |
|
| 412 |
custom_url_rewrite_outbound() is a special function that you can add
|
| 413 |
to settings.php to alter how Drupal writes links to content.
|
| 414 |
|
| 415 |
Domain Access implements this function within the context of the
|
| 416 |
URL Alter module, http://drupal.org/project/url_alter, which is a
|
| 417 |
functional backport of changes implemented in Drupal 7.
|
| 418 |
|
| 419 |
If your site uses custom code to implement custom_url_rewrite_outbound(),
|
| 420 |
consider upgrading to the URL Alter module for full compatibility.
|
| 421 |
|
| 422 |
You may also call the function domain_url_rewrite_outbound() directly in
|
| 423 |
your custom code.
|
| 424 |
|
| 425 |
NOTE: Domain Access does not use custom_url_rewrite_inbound().
|
| 426 |
|
| 427 |
For more information, see
|
| 428 |
http://api.drupal.org/api/function/custom_url_rewrite_outbound/6
|
| 429 |
http://drupal.org/node/450344
|
| 430 |
http://drupal.org/node/529026
|
| 431 |
|
| 432 |
----
|
| 433 |
5. Additional Module Installation
|
| 434 |
|
| 435 |
The Domain Access module includes several sub-modules. Two of these
|
| 436 |
have their own INSTALL.txt instructions.
|
| 437 |
|
| 438 |
----
|
| 439 |
5.1 Domain Strict
|
| 440 |
|
| 441 |
While this module requires no additional installation, it fundamentally
|
| 442 |
changes the behavior of the Domain Access module.
|
| 443 |
|
| 444 |
Under Domain Strict, only authenticated users (those who have registered)
|
| 445 |
are given any domain-specific privileges.
|
| 446 |
|
| 447 |
Anonymous users will only be able to view content that is assigned to "all
|
| 448 |
affiliates."
|
| 449 |
|
| 450 |
As a result, enabling this module may cause content to disappear from your
|
| 451 |
site for users who are not logged in. This is by design.
|
| 452 |
|
| 453 |
Refer to domain > domain_strict > README.txt
|
| 454 |
|
| 455 |
----
|
| 456 |
6. Uninstalling
|
| 457 |
|
| 458 |
When you disable this module, it will reset your {node_access} tables and
|
| 459 |
remove all records from the {domain_access} table. This will remove all
|
| 460 |
access rules associated with this module.
|
| 461 |
|
| 462 |
You may then uninstall the module normally.
|
| 463 |
|
| 464 |
You should also revert the patches that you applied and remove
|
| 465 |
any extra code from your settings.php file.
|
| 466 |
|
| 467 |
To revert a patch, see http://drupal.org/patch/reverse
|
Parent Directory
| 
Revision Log
| 
Revision Graph