You are here

README.txt in Domain Access 6.2

README file for Domain Alias

File

domain_alias/README.txt
View source
  1. /**
  2. * @file
  3. * README file for Domain Alias
  4. */
  5. Domain Access: Domain Alias
  6. Advanced domain matching methods for Domain Access.
  7. CONTENTS
  8. --------
  9. 1. Introduction
  10. 1.1 Use-Case
  11. 1.2 Example
  12. 1.3 Developers
  13. 2. Installation
  14. 2.1 Dependencies
  15. 2.2 Configuration Options
  16. 3. Alias Management
  17. 3.1 Creating Aliases
  18. 3.2 Updating Aliases
  19. 3.3 Pattern Matching Options
  20. 3.4 Redirecting Aliases
  21. 4. Domain Alias Switcher Block
  22. 5. Developer Notes
  23. 5.1 Database Schema
  24. ----
  25. 1. Introduction
  26. The Domain Access: Domain Alias module, is an optional extension of the
  27. Domain Access module. Domain Alias provides advanced options
  28. for configuring domain request handling by your site.
  29. ----
  30. 1.1 Use-Case
  31. Some sites have very specific rules for displaying their urls to users.
  32. For example, yahoo.com redirects all site visitors to www.yahoo.com,
  33. whereas drupal.org redirects all requests to www.drupal.org to the
  34. canonical url drupal.org.
  35. Supporting these conflicting rules led to the creation of Domain Alias,
  36. a system for managing domain handling for multiple domains that
  37. should be treated as a single domain by the Domain Access module.
  38. This module is useful for cases where wildcard DNS is supported, or
  39. when you cannot modify your DNS hosts file.
  40. ----
  41. 1.2 Example
  42. Let us assume that our main site is example.com and we run two
  43. sub sites at users.example.com and testing.example.com.
  44. Out sample site allows wildcard DNS, so any request to
  45. *.example.com will be passed to our Drupal site. We would like the
  46. following rules to be obeyed:
  47. -- www.example.com should redirect to example.com.
  48. -- exmpl.com, which we also own, should be treated as a request to
  49. example.com.
  50. -- *.users.example.com should inherit the settings for users.example.com.
  51. -- *.testing.example.com should be treated as invalid and directed to
  52. example.com.
  53. Under this complex scenario, we would configure the following domains:
  54. -- Primary domains == example.com
  55. -- Domain 1 == users.example.com
  56. -- Domain 2 == testing.example.com
  57. Under Domain Alias, we would then enable the following settings for each domain.
  58. == example.com ==
  59. exmple.com [no redirect]
  60. www.example.com [redirect]
  61. *.testing.example.com [redirect]
  62. == users.example.com ==
  63. *.users.example.com [no redirect]
  64. == testing.example.com ==
  65. No aliases needed.
  66. See section 3 for more information about configuring aliases.
  67. ----
  68. 1.3 Developers
  69. Original code by bforchhammer -- -http://drupal.org/user/216396.
  70. See http://drupal.org/node/284422 for bacjground.
  71. ----
  72. 2. Installation
  73. The Domain Alias module is included in the Domain Access download. To install,
  74. untar the domain package and place the entire folder in your modules directory.
  75. When you enable the module, it will create a {domain_alias} table in your Drupal
  76. database.
  77. ----
  78. 2.1 Dependencies
  79. Domain Alias requires the Domain Access module be installed and active.
  80. ----
  81. 3. Alias Management
  82. The Domain Alias module adds a new column to the Domain List table. If you
  83. go to the Domain List at Admin > Build > Domains > Domain List. You should
  84. now see an "Aliases" column in your domain list.
  85. ----
  86. 3.1 Creating Aliases
  87. To create a new alias, go to the Domain List at Admin > Build > Domains > Domain
  88. List. You should see an "Aliases" column in your domain list.
  89. Click on the 'add alias' link. You will be presented with a form devided into
  90. two parts. The top section, 'Registered aliases for *' will be empty initially.
  91. Under 'Add new aliases,' you may add up to five (5) aliases at a time. (If you
  92. need to add more, enter the first five and save the form.)
  93. Check the 'redirect' box only if you wish to redirect requests made to the alias
  94. to go to the regsitered domain for that alias.
  95. Enter the pattern(s) that you wish to match and click 'Save aliases.'
  96. ----
  97. 3.2 Updating Aliases
  98. Once you have created a set of aliases, the 'Aliases' column on the Domain List
  99. will show the current aliases, with a link to 'edit aliases.'
  100. Clicking on this link will show the Edit domain aliases page; this time, the top
  101. section of the form will show your current registered aliases.
  102. To modify an alias, simply change the pattern text or toggle the redirect
  103. option.
  104. To delete an alias, check the 'Delete' box on the right side of the form.
  105. Click 'Save aliases' to make your changes.
  106. ----
  107. 3.3 Pattern Matching Options
  108. The patterns that you may enter can be simple strings, like one.example.com.
  109. You may also use wildcard characters for advanced pattern matching.
  110. You may specify a pattern for your domains by using * (asterisk) to match any
  111. number of random characters and ? (question mark) to match exactly one random
  112. character.
  113. For example: *.example.com would match any HTTP request made to a subdomain of
  114. example.com to the domain record for example.com.
  115. Using wildcards is a good way to reduce the number of aliases that you need to
  116. maintain.
  117. NOTE: Only one wildcard is allowed per alias.
  118. ----
  119. 3.4 Redirecting Aliases
  120. For each alias that you create, you have the option of forcing a redirect when
  121. users make a request to that domain. If enabled, redirects will send the user
  122. to the registered domain.
  123. This setting is unique to each alias.
  124. For example, you may want to handle requests to example.com as follows:
  125. -- Leave www.example.com alone.
  126. -- Direct all other requests to example.com.
  127. In this case, example.com is the 'registered domain,' and you would create the
  128. following aliases:
  129. -- www.example.com [no redirect]
  130. -- *.example.com [redirect]
  131. This feature can be used in conjunction with the Domain Access setting for WWW
  132. Prefix Handling (see 4.3.5 WWW Prefix Handling in the main README.txt). However,
  133. you must take care not to set up an infinite redirect loop when configuring your
  134. aliases.
  135. ----
  136. 4. Domain Alias Switcher Block
  137. Instead of using the Domain Switcher block provided by Domain Access, Domain
  138. Alias provides a substitute block for debugging.
  139. The block presents a nested list of domains and aliases, highlighting both the
  140. currently active domain (in boldface) and the active alias (in italics), if
  141. applicable.
  142. Note that the block uses string substitution and may write links that fail to
  143. resolve on your site -- this is intentional and is a DNS issue, not a bug. In
  144. some cases, the module will write the entry as plain text to avoid such 'dead'
  145. links. For example:
  146. Your site has the following domains and aliases:
  147. -- example.com
  148. -- www.example.com
  149. -- one.example.com
  150. -- *.example.com
  151. -- foo.one.example.com
  152. -- foo.*.example.com
  153. If you send a request to 'bar.example.com' the domain switcher will write
  154. the following links:
  155. -- example.com
  156. -- www.example.com
  157. -- one.example.com
  158. -- bar.example.com
  159. -- foo.one.example.com
  160. -- foo.bar.example.com
  161. If your server is not configured to handle all of the above DNS requests, you
  162. may get a server error when you click on a link.
  163. NOTE: that this only works with the * wildcard, and assumes that the * reprsents
  164. an entire node of the host string.
  165. WARNING: The Domain Alias Switcher block should not be used as a navigation tool
  166. for normal site visitors. It is provided to site developers to aid in debugging.
  167. ----
  168. 5. Developer Notes
  169. For information on the development of Domain Alias, see:
  170. -- http://drupal.org/node/284422
  171. -- http://drupal.org/node/306495
  172. -- http://drupal.org/node/293453
  173. ----
  174. 5.1 Database Schema
  175. Installing the module creates a {domain_conf} table that contains:
  176. - alias_id
  177. Integer, unique
  178. The lookup key for the record.
  179. - domain_id
  180. Integer
  181. The matching key for this record, foreign key to the {domain} table.
  182. - pattern
  183. Varchar (255)
  184. The alias pattern to match against inbound requests.
  185. - redirect
  186. Integer (tiny)
  187. A boolean flag indicating that requests made to this alias should be
  188. redirected to the assigned domain_id.