Drupal Installation guide

PDF

مستند

2010-05-10

Installation guide

Drupal provides an installation script that automatically populates database tables and configures the correct settings in the settings.php file.

This section covers preparing for installation, running the installation script itself, and the steps that should be done after running the installation script has completed. It also explains how to do a "multi site" installation, where a number of different Drupal sites run off the same code base.

Before proceeding with your first Drupal installation, you should also review the best practices section. For help with Drupal terms, see the terminology page.

Other tools

Some of the steps in the installation process can be performed with tools such as graphical applications for moving files and managing databases or tools that are provided by your hosting service. This documentation focuses on performing tasks at the command line. For information on using other tools, see the documentation that accompanies the application or is provided by your hosting service.

Creating a test site on a local computer

It is considered a good practice to do all development work on a separate test site before making changes to a production site. A test site allows you to evaluate the impact of upgrades, new modules, modifications to themes etc. without causing disruption to your live site. For information about setting up a web server on a local computer, see the Local Server Setup section of the Developing for Drupal guide.

Alternative methods for installation

Some web hosting companies offer "one-click" installations of Drupal, or specific Drupal support. You may be able to locate one on the

Drupal hosting handbook page .

There is also a handbook page listing Drupal distributions , which include installation profiles and pre-packaged distributions of Drupal and modules. These may be of help as well.

System requirements

Note: if you meet these requirements but still have problems with your site, be sure to read through the Webhosting Troubleshooting FAQ .

Resources

A minimum base installation requires at least 3MB of disk space but you should assume that your actual disk space will be somewhat higher.

For example, if you install many contributed modules and contributed themes, the actual disk space for your installation could easily be 40

MB or more (exclusive of database content, media, backups and other files).

A useful FAQ ( http://drupal.org/node/59680 ) explains how to use phpinfo to get the details of your system. For example, phpinfo will tell you if you have a database already installed and what version your system is running. Phpinfo will also tell you what php variables are set as well as many other helpful things.

Web server

Drupal has been deployed successfully on both Apache and IIS.

Apache (Recommended)

Drupal will work on Apache 1.3 or Apache 2.x hosted on UNIX/Linux, OS X, or Windows. The majority of Drupal development and deployment is done on Apache, so there is more community experience and testing performed on Apache than on other web servers.

You can use the Apache 'mod_rewrite' extension to allow for clean URLs.

Microsoft IIS

Drupal core will work using IIS 5, IIS 6, or IIS 7 if PHP is configured correctly.

To achieve clean URLs you may need to use a third party product. For IIS7 you can use the Microsoft URL Rewrite Module or a third party solution.

When using Drupal on IIS 7 with fastcgi you must install Hotfix kb954946 , or wait until the hotfix appears in a package update

(recommended). KB954946 was included in Windows 2008 Server SP2

Drupal is being developed to be web server independent, but we have limited or no reports of successful use on web servers not listed here.

The total file size of your Drupal installation will depend on what you add to your site, but Drupal

2 to 3 MB uncompressed. The exact size depends on the version of Drupal you have installed.

core

files alone will take up approximately

1 of 183

2010-05-10

Database server

Recommended: MySQL 4.1 or MySQL 5.0

Drupal 5.x and earlier supports MySQL 3.23.17

or higher. MySQL 4.1 or higher is strongly recommended.

Drupal 6 supports MySQL 4.1 or higher.

Drupal 7 will only support MySQL 5.0.15 or higher, and requires the PDO database extension for PHP (see PHP section below).

NOTE: Drupal makes use of some features not available on some inexpensive hosting plans so please check that your host allows database accounts with the following rights:

SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER.

These rights are sufficient to run Drupal core 6.x.

Some contributed modules, and also Drupal core 5.x (but not Drupal core 6.x), additionally require the following rights:

CREATE TEMPORARY TABLES, LOCK TABLES.

Note: If your system/host is running MySQL 4.1 or newer and you receive the error "Client does not support authentication protocol requested by server", address the problem by following the instructions provided by MySQL AB. There is a minor OS issue with some

MySQL 5+ installations primarily on Windows but affecting some versions of Unix/Linux as well.

Note: When using Drupal 5.x or later, particularly with contributed modules, it may be necessary to set the system variable max_allowed_packet to at least 16M. Some inexpensive hosting plans set this value too low (the MySQL default is only 1M). In that case, you may need to choose a better hosting plan. A value of 1M may be sufficient for 5.x.

Note: Drupal supports MyISAM and InnoDB table types. NDB tables (MySQL Cluster) are not supported.

Note that if your web hosting account is set up with a graphic control panel such as Plesk or CPanel, it is very likely that you do not need to worry about installing a driver for MySQL -- it is probably already installed on your server. You might wish to simply create your database and proceed with installing Drupal, and then refer back to Drupal documentation for specific troubleshooting help if you run into problems.

PostgreSQL 7.4 or higher

Note: Some contributed modules are not as abstracted from MySQL-specific code as everyone would like. If you are familiar with

PostgreSQL please file issues with those contributed modules as you find them.

Drupal 7 will only support PostgreSQL 8.3 or higher

PHP 5.2.6 for Windows has a bug in its pgsql extension. You will need to replace it with the php_pgsql.dll from version 5.2.5.

Currently Microsoft SQL Server and Oracle are not supported, but various efforts are underway to supply schema. Please see discussions in the Enterprise Group if you are interested in working on this.

PHP

Recommended: PHP 5.2.x

Required: PHP version 4.4.0 or higher (Contributed modules may not support this version of PHP)

PHP 5.3 is not yet supported by Drupal 5.x, but is supported by Drupal 6.14 core and higher (see the release notes for 6.14

) and also by Drupal 7.x. Note that some contributed modules may not be compatible with PHP 5.3, and that some PHP 5.3 configurations still show warnings with Drupal 6.14; work is ongoing to resolve the latter in #360605: PHP 5.3 Compatibility .

PHP 5.2 or higher will be a requirement for Drupal 7.

PHP memory requirements can vary significantly depending on your use of modules. While 16 MB may be sufficient for a default Drupal

6 installation and 30 MB may be sufficient for a default Drupal 7 installation, a production site with a number of commonly used modules enabled (CCK, Views etc.) could require 64 MB or more. Some installations may require much more, especially with media-rich implementations. If you are using a hosting service it is important to verify that your host can provide sufficient memory for the set of modules you are deploying or may deploy in the future. (See the Increase PHP memory limit page in the additional information on modifying the PHP memory limit.)

The PHP extension for connecting to your chosen database must be installed and enabled. Drupal's currently supported database connectors are: mysql (the original MySQL extension), mysqli (an improved connector for newer MySQL installations), and pgsql (for

PostgreSQL). Note: PHP 5.x no longer enables the mysql extension by default. Please read the links above for installing and enabling your chosen connector. Additionally, Drupal 6.x does not provide the option to select the mysql connector if mysqli is enabled in your

PHP configuration.

PHP XML extension (for Blog API, Drupal, and Ping modules). This extension is enabled by default in a standard PHP installation; the

Windows version of PHP has built-in support for this extension.

An image library for PHP such as the GD library is needed for image manipulation (resizing user pictures, image and imagecache modules). GD is included with PHP 4.3 and higher and enabled by default. ImageMagick is also supported for basic image manipulations in Drupal core but there is much less support from contributed modules.

PHP

needs

the following recommended ): configuration

recommend

directives

the following setting: session.cache_limiter

: nocache

Troubleshooting FAQ

for Drupal to work (only directives that differ from the default php.ini-dist register_globals : off; this is the default value, but some hosts have it enabled error_reporting set to E_ALL & ~E_NOTICE. Work is ongoing to change this to E_ALL for Drupal 6 and Drupal 7.

for php.inisafe_mode : off. Safe mode may interfere with file and image uploads.

Php Data Objects (PDO) must be activated for Drupal 7 to install and run correctly. Look in your php.ini. Uncomment (remove the leading semicolin) at line extension=php_pdo.dll, extension=php_pdo_mysql.dll. If these lines are not there, you will need to add them. You can also use pecl install pdo

to install pdo, and then pecl install pdo_mysql database driver. More information can be found on the What is PDO page .

(for instance), to install the PDO

In addition, we

Some of these settings are contained in the default .htaccess file that ships with Drupal, so you shouldn't need to set them explicitly.

Note, however, that setting PHP configuration options from .htaccess only works under the following conditions:

2 of 183

2010-05-10

With Apache (or a compatible web server)

If the .htaccess file is actually read, i.e. AllowOverride is not None

If PHP is installed as an Apache module

See the PHP manual for how to change configuration settings for other interfaces to PHP.

Drupal 7 may require the time parameter to be at least 30 seconds.

In some shared hosting environments, access to these settings is restricted. If you cannot make these changes yourself, please ask your hosting provider to adjust them for you.

Browser requirements

Websites built using just Drupal core (i.e. with no additional, contributed modules ) are compatible with, and fully functional, in all modern browsers that support CSS and JavaScript. However, browsers have varying levels of compliance with Internet standards such as CSS 2, so there may be minor variations in appearance.

Here is an incomplete list of browsers that are known to work well with Drupal core and support all of its features:

Internet Explorer 6.x and later

Firefox 2.x and later

Opera 7 and later

Safari 1.x and later

Camino 1.x and later

Google Chrome

It is also possible to use a browser that does not support JavaScript with Drupal, although the functionality will of course be slightly different.

For instance, in Drupal 6 running in a browser with JavaScript enabled, you can use a drag-and-drop interface to position blocks on the

Blocks administration page (admin >> site building >> blocks). If you don't have JavaScript, you will still be able to position blocks, but you will use an interface more like Drupal 5, where you will assign numerical weights to the blocks.

It is also possible to use a browser that does not support CSS with Drupal, but of course the site will not look very similar to how it looks in a browser that does support CSS.

Some contributed modules and themes may not be compatible with all browsers. If you find a problem with browser compatibility in a contributed module or theme, or some functionality in a contributed module that does not work at all without JavaScript enabled, please submit an issue to report it to the module or theme maintainer.

Known Issues

It's worth mentioning here that IE6 has an problem with loading more than 30 stylesheets, and it's fairly easy to run into this problem once you start adding contrib modules.

Capacity Planning

There are no definite figures available for Drupal's resource requirements. They will vary depending on what modules you have installed, how many users you have, and what proportion log in rather than browse anonymously.

In the absence of definite information, here are some relevant discussions:

Need suggested baselines for Server Resource Requirements

It would help to know baseline requirements for Drupal and just the Core Modules:

- Simultaneous MySQL Connections

- Simultaneous PHP Connections

- CPU Thresholds

The following discussions state:

"Drupal regularly makes more than 100 queries per page load"

(Does 1 query = 1 connection?) http://drupal.org/node/190070

Some combinations of modules and options have a big impact and would be worth measuring in D7. Menu entries expanded for drop down menus + path aliases + logged in users in D6: http://drupal.org/node/625898 "Executed 595 queries in 207 milliseconds."

"Is it reasonable to expect 100s of simultaneous connections" http://drupal.org/node/312868

Measuring stuff

The Devel module, http://drupal.org/project/devel , counts database calls and execution times.

3 of 183

2010-05-10

Firefox Firebug measures and displays the download times within the browser. See the overhead of adding Google analytics to a page. (for many sites, it is the slowest download.) See the overhead of splitting a CSS file into two files for easier maintenance. See the time saved by

Drupal CSS and Javascript merging.

Measure your Drupal 6 configuration and modules to see what has the greatest impact on performance then look in the issues to see if there are major changes for the D7 versions.

Measure for both anonymous users and logged in users. A feature might add hundreds or thousands of database calls. That extra overhead might occur once every 5 minutes for anonymous users and once every page for logged in users.

Remeasure after adding a module. When you add a cloud display module, you might add a read of every node for every display. You might find an alternative module that performs the reads less frequently and caches the result.

Remeasure after changing a setting. An example: Adding path aliases in Drupal 6 had the side effect of adding a database call for every entry in the menu, a significant difference for logged in users. Combine that with hidden entries behind drop down menus and you could have a big overhead. Now do something as simple as listing your main menu and select

Expanded

for items with a lot of children. You could be adding hundreds of menu entries to an otherwise small small menu. A logged in user will get a fresh menu on every page view.

Remeasure after changing themes. Some themes add their own file and database accesses. Run Firebug to compare the CSS and Javascript file downloads, especially if the theme creates problems with CSS or Javascript merging.

Check known Drupal 6 performance problems in D7. Some parts of D7 are different and some parts hardly changed. If you know of something that had a big impact in D6 then check it in D7. Where the impact is similar, either document the problem or open an issue for possible improvement.

Check the impact of Fields in your favourite add on modules. An add on module in D6 might add a special table with one row per node. In

D7 the same module might add a field to the existing node fields. The change from separate tables to a single table might make things faster by reducing accesses. The change might also slow things down because the separate table uses an index for a lookup while the merged table uses a standard row by row search. It is worth reporting the results, both positive and negative, to the module developers.

What is PDO?

PDO is an acronym for PHP Data Objects. PDO is a lean, consistent way to access databases. This means developers can write portable code much easier. PDO is not an abstraction layer like PearDB. PDO is a more like a data access layer which uses a unified API (Application

Programming Interface).

How to enable PDO

To enable PDO configure --enable-pdo and --with-pdo_sqlite --with_pdo_mysql or whatever database needs supporting by PDO.

Windows users

For Apache, you will need to make sure php_pdo.dll and php_pdo_mysql.dll exist in the php/ext directory, un-comment or add the appropriate lines in php.ini, and restart the web server.

For IIS, PDO DLLs are not enabled by default. The preferred method for enabling them is to go to the Control Panel | Add/Remove

Programs, highlight your PHP installation and click "Change" (Change/Remove - XP). Specify "FastCGI", then modify the installed extensions to include these two, then restart your server.

Macintosh users

Method 1

OS X 10.5: Detailed, step-by-step instructions are available here:

Getting PHP + GD + pdo_mysql working on OSX 10.5 (aka recompiling everything)

Getting PHP + GD + PostgreSQL working on OSX 10.5 (aka recompiling everything)

OS X 10.6: OS 10.6 comes with the PDO extension enabled by default. (For instructions on configuring your development environment, see:

Drupal 6 on OS X 10.6

Method 2

MAMP comes pre-configured with the PDO extension. For more information, see: HowTo: Create a local environment using MAMP .

Linux users

PDO is enabled by default as of php 5.1.0 on most linux systems. There is documentation to enable PDO for a mysql specific-driver .

Ubuntu

As with most Linux systems, PDO support is present in PHP5 in all recent Ubuntu distributions, and certainly in PHP 5.2 which is required for

Drupal 7. If you find that PDO support is not enabled, install the following packages and restart the server.

4 of 183

2010-05-10 sudo apt-get install php5-common php5-mysql sudo /etc/init.d/apache2 reload

Before restarting the server, make sure that extension=pdo.so

their own .ini files inside /etc/php5/conf.d.

and extension=pdo_mysql.so

are being loaded, either in the php.ini file or in

Ubuntu PDO Troubleshooting

Do not

use the PECL PDO installer. The project is horribly outdated and abandoned. (See http://pecl.php.net/package/PDO .) Cases have been reported where PECL PDO support seems enabled but it doesn't work correctly. One symptom was the inability to install Drupal 7 alpha4 or newer.

If you have already installed PECL PDO, you will need to remove it and then reinstall the following PHP packages, because PHP's PDO drivers have probably been overwritten.

sudo pecl uninstall pdo_mysql sudo pecl uninstall pdo sudo apt-get install --reinstall php5-common php5-mysql sudo /etc/init.d/apache2 reload

Again. before restarting the server, make sure that extension=pdo.so

or in their own .ini files inside /etc/php5/conf.d

and extension=pdo_mysql.so

are being loaded, either in the php.ini file

Basic installation

Quick install for experts

This page provides a summary of the command line instructions for installing Drupal on a typical UNIX/Linux web server. Every step contains a link to more detailed installation instructions where you also can find information about installing Drupal on other systems.

If you have problems, read Troubleshooting common problems .

Read more about system requirements (among which detailed PHP-settings and browser requirements).

1. Download and extract files

Download Drupal from http://drupal.org/project/drupal and extract the files with a compression tool (such as tar or 7-zip).

wget http://drupal.org/files/projects/drupal-x.x.tar.gz

tar -zxvf drupal-x.x.tar.gz

Move the files to a directory within your web server's document root or your public HTML directory using the following command, substituting drupal-x.x with the actual version number. (On many *nix computers the path from the server's root will be

/var/www/

.) mv drupal-x.x /var/www/

You can install and use Drupal in other languages by downloading translations from http://drupal.org/project/translation . Extract the files into the Drupal directory (e.g. /var/www/drupal-x.x)

Read more about downloading and extracting Drupal (includes instructions for FTP, Windows and Mac OS).

2. Create the configuration file and grant permissions

In the sites/default directory, copy the default.settings.php file and name the copied file as settings.php.

cp sites/default/default.settings.php sites/default/settings.php

Give the web server write privileges (

666

or u=rw,g=rw,o=rw

) to the configuration file.

chmod a+w sites/default/settings.php

Give the web server write privileges to the sites/default directory.

chmod a+w sites/default

Read more about preparing the configuration file.

3. Create the Drupal database

To complete the installation, you must create a database for Drupal to use. You can do this by command line or through phpMyAdmin (or another web interface).

mysqladmin -u username -p create databasename

Where 'username' is a MySQL user which has the CREATE and GRANT privileges. MySQL will prompt for the 'username' database password.

Next you must set the access database rights. Log in to MySQL:

5 of 183

2010-05-10 mysql -u username -p

At the MySQL prompt, enter:

GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES

ON databasename.*

TO 'username'@'localhost' IDENTIFIED BY 'password';

Where:

'databasename' is the name of your database

'username' is the username of your MySQL account

'localhost' is the server name used to access MySQL

'password' is the password required for that username

If successful, MySQL will reply with:

Query OK, 0 rows affected

Read more about creating the database (among which instructions on using phpMyAdmin, and PostgreSQL and SQLite as database).

4. Run the installation script

To run the installation script, point your browser to the base URL of your website (e.g. http://www.example.com

, http://www.example.com/drupal or http://localhost/drupal ).

The installation wizard will guide you through several screens to set up the database, add the first user account, and provide basic web site settings. Follow the wizard to finalize the installation and start working with your Drupal website.

Read more about the installation script (along with a detailed description of all the available options).

Before you begin

Drupal provides an installation script that automatically populates database tables and configures the correct settings in the settings.php file.

This Installation Guide covers:

Preparing to install

Downloading software

Modifying file permissions

Running the installation script

Troubleshooting problems

Optional: Multi-site installation

(where a number of different Drupal sites run off the same code base)

About this guide

This guide focuses on installing Drupal on a remote server running *nix (Linux, Unix, or similar) and performing tasks at the command line.

You should have a terminal program and be comfortable using a text-based interface.

If you do not have "shell access"

(the ability to connect to the remote computer using the command line) to the remote server and/or if you would prefer to use an ftp client instead of command-line commands: See "Alternative tools" below.

If you are installing Drupal on a

Windows Server

, see the "For Windows Users" notes in each section.

For IIS installations

, this guide assumes you have created a web site using the IIS Manager.

Helpful Info

Before proceeding with your first Drupal installation, you should also review:

Drupal requirements

Web Hosting Issues

Drupal best practices section

Drupal terminology

Alternative tools

Some of the steps in the installation process can be performed with tools such as graphical applications for moving files (File Transfer

Protocol-FTP applications) or managing databases. This documentation focuses on performing tasks at the command line. For information on using other tools, see the documentation that accompanies the application or is provided by your hosting service.

Some FTP information you might find helpful:

How to install drupal for newbies using windows, FTP and phpMyAdmin

Videocast of Drupal 6 installation

Modifying Linux, Unix, and Mac file permissions

6 of 183

2010-05-10

Creating a test site

For help setting up a test site running on the same codebase, see the [D6

Advanced and multisite installation guide].

You should also review Copying a live site via command line

Alternative methods for installation

Some web hosting companies offer "one-click" installations of Drupal, or specific Drupal support. You may be able to locate one on the

Drupal hosting handbook page .

There is a handbook page listing Drupal distributions , which include installation profiles and pre-packaged distributions of Drupal and modules. These may be of help as well.

Step 1: Download and uncompress Drupal

Drupal is available in several versions.

The "recommended release" is the latest stable release.

To learn more about versions, see the Drupal version information page.

Information about Drupal translations is available at http://drupal.org/project/translations .

Downloading Drupal

Before you begin, log in to your server and navigate to the directory from which you will be serving your Drupal site. On many *nix computers the path from the server's root will be /var/www/html, so domains, the path will be different -- perhaps the command cd ~/www your hosting provider for assistance.

cd /var/www/html

. On a shared server, or a server that hosts multiple cd ~/public_html

will work. If you are unsure of the directory, ask

Download Drupal using any download utility, the two most popular of which are are:

wget

and

curl

. Not every computer has both. The commands wget http://ftp.drupal.org/files/projects/drupal-x.x.tar.gz

or curl -O http://drupal.org/files/projects/drupal-x.x.tar.gz

(

Note that the option for the curl command is the upper case letter "O" and not the numeral that stands for zero

(Replace the "http://drupal.org/files/projects/drupal-x.x.tar.gz" string with the link for the version you will be installing.)

Uncompressing Drupal

Type the following command (replacing "x.x" with your downloaded version): tar -xzvf drupal-x.x.tar.gz

Remove the compressed file by typing rm drupal-x.x.tar.gz

Moving Drupal to its intended location

Now you need to move the contents of the directory:

drupal-x.x

directory one level "up" into the web server's document root or your public HTML mv drupal-x.x/* drupal-x.x/.htaccess ./

The files from the directory you downloaded and decompressed have now been moved up a level into your web directory, and you can delete the drupal-x.x directory (which is now empty): rmdir drupal-x.x

Before continuing to the next page ...

The base URL for your Drupal installation will be set in your Web server's configuration file. You will need to know this URL before proceeding to the next steps of the installation. If you are installing Drupal on your local machine the base URL may be: http://localhost . If you are installing Drupal to a Web server your base URL may be a specific domain name (such as http://example.com

OS-Specific Instructions

7 of 183

2010-05-10

For other operating systems besides *nix, refer to your site's operating system's page for instructions and notes.

Macintosh Download Notes

If you are installing on a Mac server, or are creating a test site on your Mac, you may also want review these handbook pages during installation:

1. http://drupal.org/node/369107

2. http://drupal.org/node/22676 -- especially if you are unsure of the "web server's document root or the location of your public HTML directory

SELinux Download Notes

Note for SELinux users

Users of Fedora or other distributions with SELinux (Security Enhanced Linux) should not move files unpacked into their home directory into the Web directory

/var/www/html

.+++++WHY NOT JUST HAVE THEM DL TO THE WEB DIRECTORY & UNPACK THERE TO BEGIN WITH? (as per the DL instructions I just modified) I do not know anything about SELinux (unless my CentOS server *is* SELinux ... which statement reveals my utter ignorance) so could someone else please check this Note for SELinux users section? ty --kazar 2009-08-18+++++

As posted at http://drupal.org/node/50280 moving a file preserves the context with the directory in which it was created. In this case the files are incorrectly associated with the home directory ( user_home_t

) instead of the web directory ( httpd_sys_content_t

Instead, copying the files to the directory

/var/www/html

will cause them to inherit the context of the correct directory: cp -R drupal-x.x/* drupal-x.x/.htaccess /var/www/html

If you have already moved the files you may re-associate the files using the command chcon

to change the security context for the files: chcon -R -t httpd_sys_content_t /var/www/html

See: SELinux may cause mysterious permission problems

Windows Download Instructions

Prerequisites

Unzip program for processing .tar.gz files. .tar.gz is a format Windows doesn't understand by default. This tutorial assumes you've downloaded and installed the freely available utility 7-Zip to allow you to extract utilities are also available.

.tar.gz

files. A number of other file compression

Download Drupal

1. At the project download page.

, find the version you want to download. In this case, select the first Drupal 7 version under the section

'Official Releases'. Click on 'Download'. Save the file (don't open it with another program.)

2. Uncompress the file. Right-click on the .tar.gz file and select Open With...|7-Zip. The final Drupal folder will appear. Hilight it, click

Extract, and specify the folder into which you would like to extract it.

Note: If you extract the files into a folder other than your web site's folder, copy the contents of the Drupal folder into the appropriate web folder, rather than cutting/pasting them. (This will ensure the files will inherit the appropriate permissions for the web server.)

3. Create the files folder. In the sites/default folder, create a folder called files and grant modify permissions for it to IIS_WPG (IIS6) or

IIS_IUSRS (IIS7).

4. IIS7: Create/modify web.config file. Drupal distributions come with .htaccess files for *nix use; IIS7 users should convert this file to a web.config file for their site. If you have used the IIS Manager to create a new site, a basic web.config file will exist in your site's root directory. Edit the file to look like this example:

<?xml version="1.0" encoding="UTF-8"?>

<system.webServer>

<!--

Caching configuration was not delegated by default. Some hosters may not delegate the caching

configuration to site owners by default and that may cause errors when users install. Uncomment

this if you want to and are allowed to enable caching

-->

<!--

</profiles>

</caching>

-->

8 of 183

2010-05-10

<rules>

<!-- rule name="postinst-redirect" stopProcessing="true">

</rule -->

</rule>

</rule>

<!-- To redirect all users to access the site WITH the 'www.' prefix, http://example.com/ ... will be redirected to http://www.example.com/ ...)

adapt and uncomment the following: -->

<!--

</conditions>

</rule>

-->

<!-- To redirect all users to access the site WITHOUT the 'www.' prefix, http://www.example.com/ ... will be redirected to http://example.com/ ...)

adapt and uncomment the following: -->

<!--

</conditions>

</rule>

-->

</conditions>

</rule>

</rules>

</rewrite>

<!-- httpErrors>

</httpErrors -->

<files>

</files>

</defaultDocument>

</system.webServer>

</configuration>

Step 2: Create the database

Before running the installation script, you must create an empty database and database user (a user name assigned the rights to use the

Drupal database).

This page offers guidance for creating your Drupal database using a Web browser-based control panel (such as "CPanel" or "Plesk"), or by using phpMyAdmin (another browser-based database utility), or by creating the database directly from the MySQL or PostgreSQL command prompt (for more advanced users).

Create a database using a browser-based control panel

Most web hosting accounts provide a Web-based control panel to help you administer your site. These tools include easy-to-use features for creating a new database, and for creating a "user" with rights to the database. To create a database using a browser-based control panel consult the documentation or ask your web host service provider.

When you create the user for your database, you may see a page where you can specify the privileges that user will have for various operations on the database. In most Web control panels' "database wizard", if you simply check "All" privileges for the user you create (and then uncheck "Grant" if it is listed as a privilege) your user will be set up correctly.

Take note of the username, password, database name and hostname (e.g., are you installing in

www.example.com

, or in

drupal.example.com

www.example.com/blog

etc.) as you create the database. You will enter these items into fields in your browser when running the install script (see next page ).

Note that in many cases when creating databases and users via a Web-based graphic interface, the user name you use to log into your

9 of 183

2010-05-10 control panel is added as a prefix to the database name and possibly to the database user name as well. For example, if you log into your

Web site control panel as "webadmin" and create a database named "drupal7db" and a user for that database named "d7user", when running the Install script (see next page) the database and user may need to be typed in as "webadmin_drupal7db" and "webadmin_d7user".

(This is because many hosting accounts are on shared servers, and on one server each database and user name must be unique across all accounts on the server.)

If you have created your database and user via a Web-based interface, you can skip the remainder of this page and continue with the install instructions on the next page.

Create database and user using PHPMyAdmin

This presumes you have root access to PHPMyAdmin

1. Log in to PHPMyAdmin as the root user

2. Click

Privileges

3. In the

4. In the

Host

User name

Add a new User

field, enter the username you wish to use

field, select

Local

which is more secure, unless you will be accessing the database with this user from another server

5. Enter or generate a password for the user.

6. In the Database for User list, select

Create database with same name and grant all privileges

and click Go

You have now created a user that has all privileges only on the database with the same name. This is more secure than using a general username & password for all your sites on the same server, as it limits access to your databases if someone gets hold of your database logins.

If you want to have a different name for database and user, just select the created database, then operations tab. You will find an option

Rename database to

. If you need more details about using PHPMyAdmin, check out the official wiki .

Take note of the username, password, database name and hostname (e.g., are you installing in

www.example.com

, or in

drupal.example.com

www.example.com/blog

etc.) as you create the database. You will enter these items into fields in your browser when running the install script ( see next page ).

Note that in many cases when creating databases and users using a web interface, the user name you use to log in to your control panel is added as a prefix to the database name and possibly to the database user name as well. For example, if you log into your Web site control panel as "webadmin" and create a database named "drupal7db" and a user for that database named "d7user", when running the Install script (see next page) the database and user may need to be typed in as "webadmin_drupal7db" and "webadmin_d7user". (This is because many hosting accounts are on shared servers, and on one server each database and user name must be unique across all accounts on the server.)

If you have created your database and user via phpMyAdmin, you can skip the remainder of this page and continue with the install instructions on the next page.

Create a database from the command line

If you do not use a Web control panel or are experienced with and prefer to use MySQL or PostgreSQL commands, you can follow the information below.

Additional information about privileges, and instructions to create a database using the command line are available in INSTALL.mysql.txt (for

MySQL) or INSTALL.pgsql.txt (for PostgreSQL).

Create a database using MySQL commands

For information on installing and configuring MySQL see http://dev.mysql.com/tech-resources/articles/mysql_intro.html

In the following examples, 'username' is an example MySQL user who will have the CREATE and GRANT privileges and 'databasename' is the name of the new database Use the appropriate names for your system.

1. Create a new database for your site.

mysqladmin -u username -p create databasename

MySQL prompts for the 'username' database password, and creates the initial database files.

2. Log in and set the access database rights: mysql -u username -p

MySQL prompts for the 'username' database password.

3. At the MySQL prompt, set the permissions using the following command:

GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, LOCK TABLES, CREATE TEMPORARY TABLES ON `databasename`.*

TO 'username'@'localhost' IDENTIFIED BY 'password';

In this case:

'databasename' is the name of your database

'username@localhost' is the username of your MySQL account

'password' is the password required for that username

10 of 183

You will need the

around the database name if you have used a MySQL escape character in your schema name.

2010-05-10

Eg: drupal_test_account.* should be drupal\_test\_account.* for security (underscore is a wildcard). This requires the ` wrapper.

`drupal\_test\_account`.*

Note: unless your database user has all of the privileges listed above, you will not be able to run Drupal.

4. If successful, MySQL will reply with:

Query OK, 0 rows affected

5. To activate the new permissions, enter the following command:

FLUSH PRIVILEGES;

The database should be created with UTF-8 (Unicode) encoding.

Create a database using PostgreSQL

The database must be created with UTF-8 (Unicode) encoding.

1. Create a database user

This step is only necessary if you don't already have a user setup (e.g. by your host) or you want to create new user for use with

Drupal only. The following command creates a new user named 'username' (you should substitute this with the desired username), and prompts for a password for that user: createuser --pwprompt --encrypted --no-adduser

--no-createdb username

If everything works correctly, you'll see a

CREATE USER

notice.

2. Create the database

This step is only necessary if you don't already have a database setup (e.g. by your host) or you want to create new database for use with Drupal only. The following command creates a new database named "databasename" (you should substitute this with the desired database name), which is owned by previously created "username": createdb --encoding=UNICODE --owner=username databasename

If everything works correctly, you'll see a

CREATE DATABASE

notice.

Step 3: settings.php

You must create a settings.php file and set some permissions.

Settings.php

Your Drupal download comes with a sample configuration file at sites/default /default.settings.php

installer. It must be copied and the new file must be given the correct name.

. The default file is not used by the

1. Copy the default.settings.php

to settings.php

You can do this from the command line (working from the root of the directory containing your Drupal installation) using cp sites/default/default.settings.php sites/default/settings.php

NOTE: Do not simply rename the file. The Drupal installer will need both files.

2. You should now have both a default.settings.php and settings.php file in your sites/default

directory.

3. Make the settings file writeable, so that the installer can edit it, using chmod a+w sites/default/settings.php

or chmod 666 sites/default/settings.php

Both commands have the same effect.

Several FTP tools like Filezilla, Transmit, and Fetch allow you to change file permissions, using a 'file attribute' or 'get info' command. In this case the octal or numeric value file permission should be set to 666. If your ftp client has checkboxes for setting permissions, check both the Read and Write boxes for "Owner", "Group", and "Others" (leaving the Execute boxes unchecked).

4. To let the files directory be created automatically, give the web server write privileges to the sites/default directory.

chmod a+w sites/default

OS-Specific Instructions

For other operating systems besides *nix, refer to your site's operating system's page for instructions and notes.

Fedora Linux

You will need to put selinux in permissive mode to have the permissions modified by the install script. Even if you have the permissions set correctly for settings.php the install script will think you don't if selinux is active.

11 of 183

2010-05-10

You may need to turn off selinux during your Drupal install and turn it on after the install is complete.

Remember that permissions must also be set to allow writing to the default folder so that the startup script can create the files folder inside it.

IIS (Windows)

On a Windows system using IIS, right-click on sites/default/settings.php and grant Modify permissions to IIS_WPG (IIS6) or IIS_IUSRS

(IIS7).

IIS7: You can also do this from the command line from within your \Drupal directory:

C:\inetpub\wwwroot\Drupal>icacls sites\default\settings.php /grant BUILTIN\IIS_IUSRS:(M)

The installer will change the file back to Read Only after installation, but you should verify this after installation. For more information about modifying Windows file permissions, see the Troubleshooting FAQ .

Mac OS X

Optional instructions on setting up a local MAMP (Mac Apache MySQL PHP) server.

For an external server, follow these steps:

1. Install Drupal 7.0 as a soft link from

/Users/xxx/Sites/drupal

, user xxx is in the "_www" group and make the entire installation is group writable. Create

/Library/WebServer/Documents/xxx

/Users/xxx/Sites

2. Re-writing seems to be enabled by default in Apache2 on Leopard. Enable PHP5 and virtual hosts in Apache2, i.e. by uncommenting these lines in

/etc/apache2/httpd.conf

#<br /># Dynamic Shared Object (DSO) Support<br />#<br />...<br /><br />LoadModule libexec/apache2/libphp5.so<br /><br

/>...<br /><br /># Virtual hosts<br />Include /private/etc/apache2/extra/httpd-vhosts.conf

3. Add a virtual host stanza to the

/private/etc/apache2/extra/httpd-vhosts.conf

file that has at least this in it:

<VirtualHost *:80><br />    DocumentRoot /Library/WebServer/Documents<br />   

ServerName localhost<br />    <br />    <Directory

"/Library/WebServer/Documents"><br />        Options FollowSymLinks Indexes

MultiViews<br />        AllowOverride All<br />       

Order allow,deny<br />        Allow from all<br />   

</Directory><br /></VirtualHost>

4. Add a variant of the

RewriteBase /drupal

line in the stock

/Users/xxx/Sites/drupal/.htaccess

file:

<IfModule mod_rewrite.c><br /> RewriteEngine on<br /><br /> ...<br /><br /> # Modify the RewriteBase if you are using

Drupal in a subdirectory or in a<br /> # VirtualDocumentRoot and the rewrite rules are not working properly.<br /> # For example if your site is at <a href="http://example.com/drupal" title="http://example.com/drupal" rel="nofollow">http://example.com/drupal</a> uncomment and<br /> # modify the following line:<br /> # RewriteBase

/drupal<br /> RewriteBase /xxx/drupal<br /><br /> ...<br /><br /> # Rewrite URLs of the form 'x' to the form

'index.php?q=x'.<br /> RewriteCond %{REQUEST_FILENAME} !-f<br /> RewriteCond %{REQUEST_FILENAME} !-d<br />

RewriteCond %{REQUEST_URI} !=/favicon.ico<br /> RewriteRule ^(.*)$ index.php?q=$1 [L,QSA]<br /></IfModule>

5. Make a copy of the

/Users/xxx/Sites/drupal/sites/default

directory is writable by the

_www

group.

6. Manually create the database in MySQL. Make a copy of

directory tree as

/Users/xxx/Sites/drupal/sites/localhost

. Make sure this

/Users/xxx/Sites/drupal/sites/localhost/default.settings.php

file as

/Users/xxx/Sites/drupal/sites/settings.php

and make this file writable by the

_www

/Users/xxx/Sites/drupal/sites/settings.php

group. Configure the database in

/**<br /> * Database settings:<br /> *<br />...<br /><br /> */<br />#$db_url =

'mysql://username:password@localhost/databasename';

7. Rebuild PHP5 to include the GD tools according to the instructions here .

8. After modifying the file permissions in the next step, go to

Run the install script .

http://localhost/xxx/drupal/install.php

. The pages came up as shown on the

Step 4: Run the installation script

For Drupal 6

To run the install script point your browser to the base URL of your website.

The base URL is defined in your Web server configuration file and is specific to the document root where you placed your Drupal files. If you have installed Drupal on a Web server this will likely be a domain name such as http://example.com

. If you have installed Drupal on your desktop machine this URL might be http://localhost .

12 of 183

You will be guided through several screens to set up the database, create tables, add the first user account and provide basic web site settings.

13 of 183

2010-05-10

If you get any errors regarding the files directory and its permissions, see [#394704].

For Drupal 7

To run the Drupal install script, point your browser to the base URL of your web site.

The "base URL" means the document root (directory) where you placed your Drupal files (and is defined in your web server configuration file). If you have installed Drupal on a web host this will likely be a domain name such as http://www.example.com

a subfolder, then you should point your browser to the subfolder (e.g. desktop machine this URL might be http://localhost/drupal

http://example.com/subfolder

. If you installed Drupal in

). If you have installed Drupal on your

If the installation process does not simply appear by entering the base URL of your site, add the file name "install.php" (for example http://www.example.com/install.php

You will be guided through several screens:

1. Choose which profile to use for the installation (standard or minimal).

Most people should select the "standard" option. The standard option comes with default content types already enabled, such as and

Page

, and with appropriate publishing options already set. (Of course you can later edit these default content types and their settings, or add additional ones.) The standard profile also has a useful collection of modules pre-enabled for you.

Article

The "minimal" option is targeted toward more experienced Drupal site creators who wish to set up their own content types with associated publishing options. The minimal profile has only three modules enabled: Block , Database logging , and Update status .

2. Select a language

If you want to install using a language other than the default English, click the

Learn how to install Drupal in other languages

link.

3. Verify requirements

If your installation directory is not yet configured properly, you will be informed at this step. You can correct the settings individually and either refresh the browser screen or click 'Try again' to see whether there are any errors left.

Possible errors include:

Missing directories and/or incorrect permissions

14 of 183

2010-05-10

The installer will attempt to automatically set up a number of directories, but this may fail due to permission settings. In this case you will find the missing directories listed.

sites/default/files sites/default/private sites/default/private/files

These directories should be set to the following permissions chmod o+w sites/default/files

OR chmod 777 sites/default/files

Missing settings.php or incorrect permissions

If settings.php

is missing or not accessible, follow the instructions in Step 2: Modify file permission . Note that you will need

both

the default.settings.php and settings.php files.

4. Set up database

Enter the database name as well as the username and password for the database that you created in Step 3: Create Drupal's database .

This username and password information allows Drupal to access your database, so the install script can create tables. Note that this is

not

the username and password for administering Drupal; these will be created in the next step.

The

Advanced options

will allow you to change the database host ('localhost' is usually used in this entry: wamp/bin/apache/Apache2.2.11/bin/php.ini

as an example of the location on a Windows box running WAMP ). You can also change the port and the table prefix. You only need to change the port if you are using a non-standard port number. The table prefix is useful if you are installing multiple instances of Drupal tables that share the same database.

Click

Save and continue

at the bottom of the page.

5. Install profile

A progress bar will appear and display notes from the installer regarding the progress of the installation. If no errors are encountered, the next page will automatically load in your browser.

6. Configure site

Input the information for the first user account (which will be automatically assigned full administration permissions) and provide basic web site settings.

In the

Site name

field enter the name you wish to use for the site. You can also edit it later through the administration interface.

Site e-mail address

registration information.

field, enter the e-mail address that will be used by Drupal when it sends out notifications such as

Site maintenance account

field, enter the

Username

E-mail address

, and

password

for the main administration account.

Note that there is a distinction, as of Drupal 7, between the main administration account that you set up on this page, and the

"Administrator"

site administrator

user role that you will see when you visit the "Roles" and "Permissions" pages in the administration interface. The account you set up in the

Site maintenance account

those of you familiar with that account from earlier versions of Drupal.)

section during installation is a super-user who has overall control over every aspect of the management and configuration of the site. (This will be www.example.com/user/1

, for

In the

Server settings

field, select your

Update notifications

Default country

and

Default time zone

field leave both boxes checked if you want your Drupal server to alert you when updates are required.

Often updates relate to security issues and are important to perform. However, if you have restricted Internet connectivity (for example if you are behind a corporate firewall) you may want to leave these settings unchecked and test them later.

Click "Save and continue". On success you will see the correct them now.

Drupal installation complete

screen. If there are any error messages, review and

Secure your site

After the installation is complete, remove write permissions for the settings.php file.

chmod u=rw,o=r,a=r sites/default/settings.php

OR chmod 644 sites/default/settings.php

If you make manual changes to the settings.php file later, be sure to protect it again after making your modifications.

Failure to remove write permissions to that file is a security risk. (Although the default location for the settings.php file is at sites/default/settings.php, it may be in another location if you use the multi-site setup.)

Installing an installation profile

What is an installation profile?

From Installation profiles :

Installation profiles are a feature in Drupal core that was added in the 5.x series. The Drupal installer allows you to specify an installation profile which defines which modules should be enabled, and can customize the new installation after they have been installed. This will allow customized "distributions" that enable and configure a set of modules that work together for a specific kind of site (Drupal for bloggers, Drupal for musicians, Drupal for developers, and so on).

Please note that an installation profile can only be used when you're installing a new Drupal instance. This means that you can not run an installation profile on an existing Drupal to add extra functionality. You can also only select one installation profile, it is not possible to install a wiki installation profile along with a French language profile for instance.

15 of 183

2010-05-10

The installation of an installation profile is not required, but optional.

Installing the profile

1. Start by downloading the installation profile and unpacking it.

2. Copy the entire directory that you just unpacked into the profiles

directory of your core installation. For example, if you have core installed at

/home/www/htdocs

and you downloaded and unpacked an installation profile called "fooprofile", you would want to copy the entire "fooprofile" directory into

/home/www/htdocs/profiles/fooprofile

3. Read the documentation on the installation pack you downloaded. This can either be found on the profile's project page (example:

Innovation News Installation Profile ) or in the README.TXT that came with the download (example: Drupal Hebrew Installation Profile ).

It should contain installation instructions such as listing the required extra modules and/or themes that you will have to download.

4. Download these modules and themes and put them in the right directory. This is usually sites/all/modules

and sites/all/themes

5. Go to your site's install.php and select which installation profile to install.

Enjoy your fresh pre-configured Drupal installation!

After Installation

Now that you've installed Drupal, there are a few tasks you need to do:

Set up cron

Configuring cron is an extremely important task in your Drupal website setup. Search module's indexing of your website's content, aggregator module's retrieval of feeds, ping module's notification of other sites of updates, and system module's routine maintenance tasks, such as pruning of logs, all depend a properly configured cron job.

What is a cron job?

Many Drupal modules have tasks that have to take place from time to time. Think of cron as the tolling of a bell, letting Drupal know that it should perform the appropriate tasks.

The actual "cron job" is a time-triggered action that is usually (and most efficiently) performed by your website's hosting server, but can also be configured by a remote service or even from your own desktop.

For your Drupal site, what actually happens is that the cron job triggers an invisible visit to the site's cron.php file

( http://www.example.com/cron.php

) which, in turn, executes tasks on behalf of installed modules.

Configuring cron jobs

Cron is a daemon that executes commands at specified intervals. These commands are called "cron jobs." Cron is available on Unix, Linux and Mac servers. Windows servers use a Scheduled Task to execute commands.

There is a video, How To: Setting up Drupal's Cron that talks about cron and shows various ways of configuring it.

The cron command

In the following example, the crontab command shown below will activate the cron tasks automatically on the hour:

0 * * * * wget -O - -q -t 1 http://www.example.com/cron.php

In the above sample, the

0 * * * *

represents when the task should happen. The first figure represents minutes – in this case, on the "zero" minute, or top of the hour. (If the number were, say, 10, then the action would take place at 10 minutes past the hour.) The other figures represent, respectively, hour, day, month and day of the week. A

is a wildcard, meaning "every time."

The rest of the line basically tells the server to "ping" the url http://www.example.com/cron.php

Here is a diagram of the general crontab syntax, for illustration:

# +---------------- minute (0 - 59)

# | +------------- hour (0 - 23)

# | | +---------- day of month (1 - 31)

# | | | +------- month (1 - 12)

# | | | | +---- day of week (0 - 7) (Sunday=0 or 7)

# | | | | |

* * * * * command to be executed

Thus, the cron command example above means "ping http://www.example.com/cron.php

at the zero minute on every hour of every day of every month of every day of the week."

How Drupal uses cron

16 of 183

2010-05-10

Every Drupal install requires regular actions to handle maintenance tasks such as cleaning up log files and checking for updates. Cron.php is the file that Drupal uses to run the maintenance process.

For instance, if your site were maintenance.

www.example.com

, loading the URL

http://www.example.com/cron.php

in your browser would run the

This page is automatically set up when you install Drupal. Simply loading the URL will run the maintenance. Nothing more is required.

For a modest personal site, you might set up this cron job to run once a day. For a more active site you might want to run that job more often—perhaps every few hours or every hour. This regular visit will tell Drupal to perform its periodic tasks, and this will help keep your system running smoothly.

How to set up a cron job

Cron jobs are scheduled by setting up a "crontab." A crontab is a text file that contains the commands to be run. This file can be created and edited either through the command line interface, or, if you manage your website through a web-based control panel such as cpanel or

Plesk, you will use the web interface. Check with your hosting company for detailed instructions if you are using a web-based control panel.

To edit a crontab through the command line, type: crontab -e

If this fails, see the

Troubleshooting Cron section below.

Add ONE of the following lines:

45 * * * * /usr/bin/lynx -source http://example.com/cron.php

45 * * * * /usr/bin/wget -O - -q -t 1 http://www.example.com/cron.php

45 * * * * curl --silent --compressed http://example.com/cron.php

This would have a lynx , wget , or curl visit your cron page 45 minutes after every hour.

Three options are provided in case either wget, lynx or curl are not installed on the server. Any will do the job well.

Learn more about the crontab file syntax here to set up the cron job to run more or less often.

There are many ways to configure a cron job. If you have full access to crontab features, you should be able to simply paste in one of the above example commands –

be sure to replace "example.com" with your own web domain or docroot

If you're on shared hosting, you should be able to find cron job configuration somewhere in your hosting control panel. Some hosts even have cron "wizards" that walk you through the cron configuration, making it much easier if cron is new to you. On a Windows system you can accomplish the same thing with scheduled tasks to launch Internet Explorer pointed to the URL.

Some hosting companies do not permit local loopback, so using wget, curl or lynx will not work. If this is the case, and they run PHP as a

CGI (check with your hosting company to see if this is the case), the following will run the cron locally:-

/usr/bin/php /home/sites/example.com/public_html/cron.php

Some hosting companies don’t allow access to cron

If your hosting company restricts access to cron you have many options.

Ask the company to give you access, or to set up a cron job for you

Ask someone else with access to a server to set up a cron job for you. Any Unix, Linux, or Mac server with access to the internet can have a cron job to regularly visit your site. There are also some companies that offer cron services.

Use the Poor Man's Cron module .

Find an online cron service . Many are free but with restrictions.

Cron doesn't guarantee your commands will run at the specified interval. But Drupal will try its best to come as close as possible. The more you visit cron.php, the more accurate cron will be.

Troubleshooting cron jobs

If you receive a permission denied error after starting crontab -e, you may need to use sudo: sudo crontab -e

You may need to adjust the path to wget, lynx or curl in your crontab. For example, the cron example listed above contains the line:

45 * * * * /usr/bin/lynx -source http://example.com/cron.php

However, Lynx may be in a different location on your server, or not installed at all. To find out where Lynx is installed, enter: whereis lynx or which lynx

17 of 183

2010-05-10

If it is not located at /usr/bin/lynx adjust the path as needed. The same applies for wget and curl. If none are installed ask a server administrator for help.

It may be necessary to change http://example.com/cron.php to the location of your Drupal installation. For example, if you have Drupal installed in a subdirectory, it might be http://www.example.com/drupal/cron.php

Example scripts

Drupal ships with two example scripts in the scripts directory, cron-curl.sh and cron-lynx.sh. You can call these scripts from cron as well:

45 * * * * /home/www/drupal/scripts/cron-lynx.sh

Note that the scripts will need to be updated with the path to your directory and URL.

Running cron as an authenticated user

#!/bin/sh

# Reference http://drupal.org/node/479948#comment-1673488 by pearlbear

SITE=https://dev.example.com/

USERNAME=user.name

PASS=ChangeMe!!12

COOKIES=/tmp/cron-cookies.txt

WGETPARAMS="--quiet -O /dev/null --no-check-certificate --save-cookies $COOKIES --keep-session-cookies --load-cookies $COOKIES"

# if you run drupal in a default language different than English you need to modify this

LOGIN="Log%20in" wget $WGETPARAMS "${SITE}user" wget $WGETPARAMS --post-data="name=$USERNAME&pass=$PASS&op=$LOGIN&form_id=user_login" "${SITE}user" wget $WGETPARAMS " ${SITE}cron.php"

Security notes

It is possible to run cron.php directly via scripts/drupal.sh with Drupal 6. Drupal.sh allows a Drupal page to be executed from a shell script.

To do so, add the following cron job to run as the Apache user.

/full/path/to/drupal.sh --root /full/path/to/site/root/ http://default/cron.php

Note that http://default/cron.php

is NOT shown as an example, it should be used as is, without changes.

Taking this approach allows cron.php to be blocked to prevent remote access.

To block remote access to cron.php, in the server, .htaccess or vhost configuration file add this section:

Order Deny,Allow

Deny from all

Allow from localhost

Allow from 127.0.0.1

Allow from xx.xx.xx.xx <-- your IP address

</Files>

If you take this approach and use drupal.sh to call cron.php, it is probably best not to use the root user to run the cron job. A non-privileged user account, or the Apache account user, for example http-service or www-data, is a better choice. To do so, call crontab -e when logged in as a non-privileged user, or for the Apache account on a Debian server, for example, you can add a user parameter: sudo crontab -e -u www-data

The downside to this method is that any URLs generated by cron jobs using this method will not be properly formed, starting with

"http://default/".

Tips and tricks

Cron Sandbox is a useful site for testing cron entries.

Multiple sites

If you run many sites, you can use this tip to make managing your cron jobs easier. To minimize the clutter, create a /etc/cron.5min

directory and have crontab read this directory every five minutes.

*/5 * * * * root run-parts /etc/cron.5min

Then place multiple individual files into the /etc/cron.5min directory, one for each site. The files can be named "site1", "site2", etc. -- note that

run-parts

may fail to detect files which contain a dot (.) in their name. To make sure that all of your files are visible to cron, type this at a shell prompt:

$ sudo run-parts --test /etc/cron.5min

and make sure that all of your files are listed.

Each of the files in /etc/cron.5min should contain one line:

/usr/bin/lynx -source http://(full site URL)/cron.php > /dev/null 2>&1

18 of 183

2010-05-10 or, alternatively, one of the

curl

wget

commands specified above.

If this doesn't work, try putting another line at the start of each file:

#!/bin/sh and make sure that the files are executable by doing

$ sudo chmod u+x /etc/cron.5min/*

For more information about using cron in a multisite configuration, see the Multisite Cron section of this guide.

SSL

When using SSL, add one additional argument when calling wget: --no-check-certificate. Do not put “--no-check-certificate” between the -0 and the -.

45 * * * * /usr/bin/wget --no-check-certificate --quiet -O - https://example.com/cron.php

Configuring an editor for cron

You can specify which text editor (emacs, vi, nano, etc.) you want to use to edit the crontab. To tell the system which editor you want to use, type: export EDITOR=nano

Configuring cron jobs in Cpanel

Cpanel controls domains. WHM, Web Host Manager, is the Cpanel product for controlling domains in a Virtual Private Server. If there is no cron option in your Cpanel, you may have to add cron in WHM. Cron may be in different places in the various Cpanel themes. In the Crimson smoke theme, you select Advanced then Cron jobs.

You are offered the option of standard or an "advanced" Unix style user interface. You may see an error message similar to the following.

/usr/bin/crontab permissions are wrong. Please set to 4755

The Unix style interface dumps you in a page where you can enter a command the same as described on the main Configuring cron jobs page.

The standard page lets you select the number of minutes, hours, days, or months from selection lists.

Configuring cron jobs on MAMP localhost

These are instructions for setting up a cron job on your localhost using MAMP on a Mac.

1. In Terminal type crontab -e

. This allows you to add a cron job, using the vim editor.

2. Press i

on your keyboard to go into vim's insert mode.

3. Type in you cron command. For example, to run at minute 5 of every hour using curl, use:

5 * * * * /usr/bin/curl --silent --compressed http://localhost:8888/cron.php

But to run every 5 minutes, use:

*/5 * * * * /usr/bin/curl --silent --compressed http://localhost:8888/cron.php

Note that if you are not using MAMP's default 8888 port, you should leave that off.

4. While in insert mode you can use the arrows and delete keys as you would normally.

5. Press escape key to exit vim's insert mode.

6. Type

(Must be capital letters -- saves the file and exits crontab).

7. Verify the cron job details by typing crontab -l

(that's a lower case L) at the terminal prompt.

I recommend that you first try setting the job to run every 2 minutes (with */2), so that you can check, reasonably quickly, that it is running.

Then edit crontab again and change the curl command to your preferred time.

Non-Vim althernative

For those with a reservation against Vim (or any other command-line editor), you can do it like this:

- Create a document with your editor of choice.

- Add the cronjobs you want to add, like described above.

- Save the file as "mycron.txt" on your desktop (or any other place you like).

cd ~/Desktop

- Open up a Terminal window, and go to the desktop (

- Type in crontab mycron.txt

- Type in crontab -l

to verify that your commands were added to cron.

Note: This method will overwrite the entire crontab, so keep the mycron.txt file available. When you need to add or change cronjobs, just edit that file and repeat the crontab mycron.txt

command to update your cronjobs.

Configuring cron jobs on DreamHost

On DreamHost you can configure cron jobs using either the web panel or the shell.

19 of 183

2010-05-10

Setting up cron jobs using the web panel

Visit https://panel.dreamhost.com/index.cgi?tree=goodies.cron&

Click 'Add a New Cron Job' and enter the following command: curl --silent --compressed http://example.com/cron.php

Note: The above code is dependent on http being accessible. If you want to run a cron job on a password protect domain, use the include the following with the absolute path for your domain to cron.php instead of the example:

/dh/cgi-system/php5.cgi /home/username/example.com/drupal/cron.php

In the same interface, you should specify a title (such as 'Drupal Cron'), e-mail address for results (not recommended), and a run interval. If you have more than one Drupal site, you can add more than one command per cron job (one per line).

Setting up cron jobs using the shell

This information comes from the Dreamhost knowledge base.

Via the "crontab" command from the shell.

crontab -l will show you your currently set up cron jobs on the server.

crontab -r will delete your current cron jobs.

crontab -e will allow you to add or edit your current cron jobs by using your default text editor to edit your "crontab file".

Your crontab includes all the cron jobs you'd like, with one cron entry per line. A cron entry looks like this:

45 2 * * * curl --silent --compressed http://example.com/cron.php

The first number is the minute of the hour for the command to run on.

The second number is the hour of the day for the command to run on.

The third number is the day of the month for the command to run on.

The fourth number is the month of the year for the command to run on.

The fifth number is the day of the week for the command to run on.

Here are some examples to help you learn the syntax for the numbers:

32 * * * * : will be run every hour on the 32nd minute.

12,42 * * * * : will be run twice an hour on the 12th and 42nd minutes.

*/15 */2 * * *: will be run at 0:00, 0:15, 0:30, 0:45, 2:00, 2:15, 2:30, ...

43 18 * * 7: will be run at 6:43pm every Sunday.

You can also edit crontab on a local file. Upload it to a directory and run:

crontab YourFileName

It'll replace your crontab with what's on the text file, without having to edit it online. This is useful if you're using a telnet client which doesn't support ANSI control codes (such as the Windows' one) and can't understand what the heck is going on on the editors.

In my own experience, I found that only by entering one cron command per line worked (one line each for :10, :20, :30, etc.). I could not get crontab to take the "*/15" argument, so I worked around it. Also, if you have ANY character after the last command (space, CR, whatever) the file will not take.

I like this file-load approach because I have a basic command file to edit or call up again if needed. Afterwards, running crontab -l will confirm that the job did take.

Configuring cron jobs on Media Temple Grid Servers (gs)

Through my experience and to my knowledge, cron jobs on Media Temple's Grid Servers must be run via an .sh file in the "/scripts" directory of your Drupal installation. This was confusing to me as I've always setup cron jobs in cPanel. Media Temple does not use cPanel. Following the steps to setup a cron job like

45 * * * * /usr/bin/wget -O - -q http://www.example.com/cron.php

will not work in Media Temple's cron job creation tool.

through a typical cPanel interface

Use the following steps to get cron jobs working on a Media Temple Grid Server:

1. Log into your (mt) AccountCenter and go to your WebControl panel.

2. Click on the "Cron Jobs" icon to enter the cron configuration page.

3. Select the "Add a new cron job" button.

4. Enter an email address for the "Output email".

Note:Leave this blank if you don't want constant emails.

5. Enter the following in the "command to run" text box: curl http://www.example.com/cron.php

where "example.com" is your domain name.

6. Under "Scheduling Settings" select how often you want your cron job to run.

7. Note the Media Temple will not allow a cron job to run more often than "every 5 minutes".

To setup a cron job to run once an hour:

Under the "minutes" entry, specify the minute value on which the cron job will start each hour.

20 of 183

2010-05-10

Then select the following radio boxes: hour, day, month, day of the week.

Configuring cron jobs on Windows

To setup a Windows machine to run cron.php at a specific time follow the specific instructions below. This can be useful if you are not familiar with Linux/Unix, or if your web host does not offer the ability to run cron jobs; you can run them remotely from your own computer.

Note: These instructions were written for Windows XP but should be similar in other versions of Windows.

Creating a Scheduled Task

1. Open Scheduler

2. Go to Start > Programs > Accessories > System Tools > Scheduled Tasks

3. Double-click Add Scheduled Task

4. The Scheduled Task Wizard will appear. Click Next.

5. Select the program to run. Choose your

6. Give the task a Name, such as

browser

Drupal Cron Job

from the list (for example, Internet Explorer or Mozilla Firefox). Click Next.

, and choose the Frequency with which to perform the task (for example, Daily)). Click

Next.

7. Choose specific date and time options (this step will vary, depending on the option selected in the previous step). When finished, click Next.

8. Enter your password if prompted. Change the username if required (for example, you'd like the task to run under a user with fewer privileges security reasons). Click Next.

9. On the final page, select the checkbox Open advanced properties for this task when I click Finish and click Finish.

Configuring the task

1. Go to the task's setting page either by checking the checkbox at the end of the last step, or by double-clicking on the task.

2. In the Run box, after the text that is there now (for example,

C:\PROGRA~1\MOZILL~1\firefox.exe

), enter a space and then type the address to your website's cron.php page in double quotations (for example, C:\PROGRA~1\MOZILL~1\firefox.exe

http://www.example.com/cron.php

3. To set a frequency more often than Daily (for example, hourly), click the Schedule tab, then click Advanced. Here you can set options such as Repeat task, every 1 hour for 23 hours. Click Ok when finished.

4. Change the start time on the task to one minute from the current time. This will allow you to test the task and make sure that it is working.

5. When all settings have been configured to your liking, click Apply and OK (note: you may be prompted for your password)

Command-line version

Another way to perform the above commands is by using the schtasks (or at in Windows 2000) command from the command line. To duplicate the example above, which runs Firefox hourly to execute http://www.example.com/cron.php

, open a command prompt (Start >

Programs > Accessories > Command Prompt) and enter: schtasks /create /tn "Drupal Cron Job" /tr "C:\PROGRA~1\MOZILL~1\firefox.exe http://www.example.com/cron.php" /sc hourly

Enter your password if prompted.

Using wget for Windows to run cron

If for whatever reason you'd rather not deal with a browser window popping up on the machine, you can use wget, the Windows port of which works more or less the same as it does in UNIX. curl and lynx also have windows ports but wget is probably the easiest to set up and use.

Grab a copy of wget from your choice of either the author's site or from SourceForge . Install it to the location of your choice.

Follow the steps for Creating A Scheduled Task above, except select wget.exe as the program to run (you may need to click the Browse button to locate it if you installed from a .zip file, for example). When you get to the Advanced Properties dialog, paste in the following after the program path:

-O - -q -t 1 http://www.example.com/cron.php

Adjust the rest of the options as described above and test it.

Configuring cron jobs on ixWebHosting

Click on "Manage" following this path: My Products >> Hosting Products >> Manage

This will take you to H-Sphere page. Click on "FTP Manager" under FTP.

You'll see one of the parameters as Crontab. The Value will be set to Off by default. Click on the Off button.(Note: If it's been set to On, click on Edit button)

This will take you to list of cron jobs(should be empty at first).

Fill in the Mail-To field with an email address where you want cron run success/failure messages sent.

21 of 183

2010-05-10

The other fields are:

TT- Opens up a help popup.

Minute - Set to "0" to run at every time the clock strikes 0th minute.

Hour - Set to "*" to run every hour or say for example "8" to run at 8am in the morning.

Day of month - Set to "*" to run every day in the month.

Month - Set to "*" to run every month.

Day of week - Set to "*" to run every day of week.

Command - This is the only tricky part. Copy paste command below replacing "example.com" with the actual site name.

/usr/bin/curl -o /dev/null http://example.com/cron.php

Delete - Can be checked to delete previously stored cron jobs.(will otherwise state "New")

That should be it. Click on "Submit Query" to save cron job. You can add multiple ones by filling in the last row which is always empty and cannot be deleted.

Hope this helps. If pictures help, I'll re-edit this post with some.

Configuring cron on Mac OS X Server 10.5.x and later

Drupal documentation refers to running cron jobs periodically. But OS X Server (at least Leopard Server) has a kernel bug that results in a log message from cron jobs to the effect “Could not setup Mach task special port 9: (os/kern) no access”. Not a joyful message to come across, though it appears to be harmless.

In addition, OS X doesn’t come with wget, so the suggested cron call in the Drupal docs doesn’t work anyhow.

To avoid both of these problems, put a call to curl in a launchd daemon .plist file (e.g. /Library/LaunchDaemons/drupal-cron-

call.plist), thusly:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

<dict>

<key>Label</key>

<string>com.{domain-name}.drupal-cron</string>

<key>UserName</key>

<string>nobody</string>

<key>GroupName</key>

<key>ProgramArguments</key>

<array>

<string>http://localhost/{drupal-subdirectory/}cron.php</string>

</array>

<key>RunAtLoad</key>

<true/>

<key>StartCalendarInterval</key>

<dict>

<key>Minute</key>

</dict>

</plist>

Then launchctl load /Library/LaunchDaemons/drupal-cron-call.plist and enjoy.

Notes:

“http://localhost/{drupal-subdirectory/}cron.php” might be replaced with “http://{domain-name}/cron.php” for a production server.

Be sure to replace {domain-name} and/or {drupal-subdirectory/} placeholders (in sample .plist file above) with appropriate values.

For non-production environments, StartCalendarInterval, which always runs at nine minutes past the hour in this example, should perhaps be replaced with StartInterval, which always runs after a specified number of seconds have elapsed (since the last run). For production environments, it’s nice to run cron by the clock, but development computers may be asleep during arbitrary times and thus benefit from the elapsed-time approach. To change this, replace:

<key>StartCalendarInterval</key>

<dict>

<key>Minute</key>

</dict> with:

<key>StartInterval</key>

(This example runs every hour.)

Configuring cron on Rackspace Cloud Sites

In the Features tab of your domain, go to "Scheduled Tasks (Cron Jobs)". Then:

1. Click on "add new task"

2. Enter a task name (such as "Drupal Cron")

3. Enter an email address for output (results of each cron run will be emailed to this address)

22 of 183

2010-05-10

4. For Command Language, select "HTTP"

5. For Command to Run, enter the url of the cron.php file (for example, http://www.example.com/cron.php

)

6. Select the interval to run the cron task (no more frequently than once every 5 minutes)

7. Click on "Save Task"

That should do it.

Cronjobs without wget/lynx or curl

Some of you might have trouble getting lynx or wget to work. This may be the case if "localhost" is not permitted.

Then wget, lynx or curl won't work on the local machine. If you are not willing to depend on others to perform cronjobs and you dislike poormans cron, try this script.

touch ~/scripts/cron-php.sh

chmod 700 ~/scripts/cron-php.sh

vi ~/scripts/cron-php.sh

#!/bin/bash

# Simple cron script for those who cannot

# use wget, lynx or curl because the host

# closed the localhost loop.

# Usage:

# - put this file in the ~/scripts dir

# - add a cronjob pointing to this script

# Copyright OCS - 2006

# Copyright [email protected]

- 2008

# This script is provided under the GPL.

# v 0.1 original release

# V 0.2 added PHP parser options and verbosity

# setting to keep it quiet so real errors can

# be reported by cron.

#############################

# CONFIGURATION OPTIONS

#############################

# Complete local path

# Set the complete local path

# to where the cron.php file

# is (ie the root path)

# Default is /var/www/html/ root_path=/var/www/html/

# Complete php path

# Set the complete path

# to the php parser if

# different from standard parse=/usr/bin/php

# PHP parser options

# Defaulting to not report notices.

parse_options="-d error_reporting=2037"

# Verbosity

# Default to only report errors.

verbose=false

##############################

# END OF CONFIGURATION OPTIONS

############################## cd $root_path if [ -e "cron.php" ] then

$parse $parse_options cron.php

if [ "$?" -ne "0" ]

then

echo "cron.php not parsed."

else

if $verbose

then

echo "cron.php has succesfully been parsed."

fi else

echo "cron.php not found."

exit fi exit and then the crontab itself: crontab -e

* * * * * ~/scripts/cron-php.sh

where ~ is the directory where your drupal install is (the script defaults to /var/www/html/ but your professional hosting company will probably use /home/your.domain.tld/www

23 of 183

2010-05-10

Another multi site cron without lynx/wget or curl

Try A multi-site cron script without lynx/wget/curl

Multisite cron without wget/lynx or curl

I recently moved my sites to a new host, and they don't allow me to use either wget or curl from cron. Since I'm running multiple sites, I also can't just run cron.php directly. However, I can use the 'exec()' PHP call, so I came up with these two scripts: runcron.php:

#!/usr/local/bin/php

<?php

$SITES = array( 'www.mainsite.com' , 'www.subsite1.com' , 'www.subsite2.com' , ... );

$_SERVER [ 'SCRIPT_NAME' ] = '/cron.php' ;

$_SERVER [ 'SCRIPT_FILENAME' ] = '/cron.php' ; foreach( $SITES as $site ) { exec ( "./runsitecron.php " .

$site );

}

?> runsitecron.php:

#!/usr/local/bin/php

<?php

$_SERVER [ 'SCRIPT_NAME' ] = '/cron.php' ;

$_SERVER [ 'SCRIPT_FILENAME' ] = '/cron.php' ;

$_SERVER [ 'HTTP_HOST' ] = $_SERVER [ "argv" ][ 1 ]; include "cron.php" ;

Then I just call 'runcron.php' from my crontab and it runs Drupal's 'cron.php' for each of my sites.

Using Perl to run cron

If you're having problems with cron using curl and wget is not allowed on your server try out the curl call from the shell on another box - you may find you get HTML delivered saying "page not found."

If this is the case you can also use Perl to perform the call to the cron script.

You need command line access to Perl and the LWP::Simple module installed. Your crontab entry then becomes:

45 * * * * perl -MLWP::Simple -e "getprint 'http://yourdomainhere/cron.php'"

Multisite cron

Sites that make use of Drupal's multisite feature need to take extra steps to ensure that each site gets it cron run, rather than just the default site. The following pages have ways that people have addressed this issue. Feel free to add your own solution as a child page.

Automatic multisite cron using php5

Create a new file preferably in the same directory as your drupal dir. Name it 'cronall.php' or something. Copy the following script into it.

Then adjust the settings in the file, and visit the script with your webbrowser, to see if it is setup correctly.

Then create a cronjob for the cronall.php script, and you're done.

<?php

/**

* This script scans the sites directory, and uses a regular expression to extract the sitenames.

* It then uses this sitename to execute the cronjob for these sites.

* You then only have to create a cronjob for this script.

* In this way, you can create and delete sites on the fly, but all their cronjobs will be executed.

/***********

* SETTINGS

**********/

//the location of the 'sites' directory relative to this script.

$sitesDir = '../drupal/sites' ;

/**

* A regular expression that matches the name of the directories in

* the 'sites' dir that you want to execute cronjobs for, with a

* backreference around the actual site name. (so we can exclude the

* domain part)

* If you don't know regular expressions you might want to brush up

* on them: <a href="http://www.regular-expressions.info/tutorial.html

" title="http://www.regular-expressions.info/tutorial.html

" rel="nofollow">http://www.regular-expressions.info/tutorial.html

</a> *

* Alternatively, you can just copy the name of one of the directories

* in the site dir, put a backslash \ in front of all dots . and replace

24 of 183

2010-05-10

* the actual name of the site with ([a-zA-Z0-9_-])

$siteNameRegExp = 'www\.example\.com\.([a-zA-Z0-9_-])' ;

//the url of the cron script, you should insert %s where the sitename should be inserted later.

$cronUrl = 'http://www.example.com/%s/cron.php' ;

//any other sites that you want to execute cronjobs for. Just comment this if you haven't got any.

$addedSites = array( 'drupal' );

/***********

* END SETTINGS

**********/ error_reporting ( E_ALL );

$sites = array();

$handle = opendir ( $sitesDir ); while ( $file = readdir ( $handle )) {

if( ereg ( $siteNameRegExp , $file )){

$sites [] = ereg_replace ( $siteNameRegExp , '\\1' , $file );

}

//default site if(isset( $addedSites ) && is_array ( $addedSites )){

$sites = array_merge ( $sites , $addedSites );

} foreach( $sites as $site ){

$cmd = 'wget --spider ' .

sprintf ( $cronUrl , $site );

echo 'Executing command: ' .

$cmd .

'<br>' ; exec ( $cmd );

}

Cron script for multi source, multi site setup

I've just hacked up this little script as I have multiple installations of drupal each with multiple sites that get more each day. This should figure out which sites cron should run for.

#!/bin/bash

SITESROOT=/var/www/sites

MYIPRANGE=41.204.221

# get the base installs cd $SITESROOT for drupaldir in $(find . -maxdepth 2 -name INSTALL.mysql.txt | awk -F/ '{print $2}') do

cd $SITESROOT/$drupaldir/sites

for site in $(find -L . -maxdepth 1 -type d -iregex "./[a-z].*\.[a-z].*" | awk -F/ '{print $2}')

IP=$(dig $site | sed '/AUTHORITY SECTION/,$d' | grep -v "^;" | grep "IN[[:space:]]*A" | sed 's/.*A\W*//' )

if echo $IP | grep -q $MYIPRANGE

then

#echo "Doing cron for $site"

wget -O - -q http://$site/cron.php

else

a=1

#echo "Skipping cron for $site"

done done

Multi-site Cron Bash Script

A quick bash script to run cron for multiple sites:

#!/bin/bash

## Define your websites in an array sites=(example.com example2.com example3.com) len=${#sites[*]} for((i=0; i<$len; i++)); do

wget -q http://${sites[${i}]}/cron.php

# You may remove (or comment) the following line if you

# wish to retain the downloaded file.

rm cron.php

done

Multisite cron without wget/curl

#!/usr/bin/php5

<?php

/**

* This script scans the sites directory, and uses a regular expression to extract the sitenames.

* It then uses this sitename to execute the cronjob for these sites.

* You then only have to create one cronjob for this script.

* In this way, you can create and delete sites on the fly, but all their cronjobs will be executed.

* Carl van Denzen, june 2009:

* Options for this script:

* -h <hostname> (p.e. arjan.vandenzen.nl)

* -r <regexp> (p.e. .+\.vandenzen\.nl) This will be used in most cases.

* -a

* When this script is invoked with parameter -r, then it will call

25 of 183

* itself for every host in the sites directory that matches the -r regexp.

* These calls will be with the -h <hostname> argument set to the site name.

* When invoked with -h option (only ONE is allowed), it will run cron

* for the named hostname site.

* When this script is invoked without parameters, it will die. This is to avoid

* runaway scripts.

* Purpose of this behaviour:

* You can add this script to your crontab with parameter -a: it will run

* for every site found in the drupal sites directory. This is the regular

* drupal/cron.php behaviour.

* In a one-site set-up it will only run for the default directory.

* In a multi-site set-up it will run for all sites (beware of the default directory?)

* You can add this script to your crontab with the -r parameter and it will only run cron

* for the sites that match the <regexp>. This is primarily meant for a multi-site set-up

* when the sites directory contains sites that you want to exclude from running cron

* (p.e. the "default" site).

* You can add this script to your crontab with the -h option to run cron

* for only the specified site (only one allowed).

* Without parameters it will do nothing.

* I have seen some problems with argument parsing that made me

* afraid of doing things like calling the same script. I would have preferred

* that this script would cron all sites if it was invoked without parameters.

* This script calls itself for every site (in a new command shell).

* It is impossible to do this in a

* php function (i.e. without invoking a new process) because the drupal

* bootstrap coding cannot (easily) be called multiple times.

* Disadvantages of this script:

* pearl5 is needed for Console/Getopt.php

* It is not efficient because for every host a new php process is

* created.

* Advantage:

* For me it works.

* It is only one script (I saw other solutions that used two scripts

* to accomplish this task).

* It doesn't use wget or similar programs that try to start cron

* by making a connection to the cron.php file. This strategy didn't

* work for me, because my website hoster doesn't allow outgoing

* connections.

/***********

* SETTINGS

**********/

//the location of the 'sites' directory relative to this script.

$sitesDir = 'sites' ;

/**

* A regular expression that matches the name of the directories in

* the 'sites' dir that you want to execute cronjobs for, with a

* backreference around the actual site name. (so we can exclude the

* domain part)

$siteNameRegExp = '(.*\.example\.com)' ;

$debug = 0 ;

/***********

* END SETTINGS

**********/

* Do default action like old cron.php (i.e. before

* the year 2008) script in Drupal 6.x

*/ function do_old_cron () { drupal_bootstrap ( DRUPAL_BOOTSTRAP_FULL ); drupal_cron_run ();

}

* some sanity checks

*/ if (!isset( $_SERVER [ 'argv' ])) {

// print('server argv not set<br/>'); do_old_cron ();

} error_reporting ( E_ALL ); include ( "Console/Getopt.php" );

// initialize object

$cg = new Console_Getopt ();

/* define list of allowed options - p = a:all sites, h:one site, r:sites that match regular expression */

$allowedShortOptions = "ah:r:" ;

// read the command line

$args = $cg -> readPHPArgv ();

// get the options

$ret = $cg -> getopt ( $args , $allowedShortOptions );

// check for errors and die with an error message if there was a problem if ( PEAR :: isError ( $ret )) {

die ( "Error in command line: " . $ret -> getMessage () . "\n" );

} ini_set ( 'include_path' , ini_get ( 'include_path' ). PATH_SEPARATOR . './scripts' );

/* This doesn't work in every case: getopt function is not always available

2010-05-10

26 of 183

$options = getopt("h:r:"); var_dump($options);

*/ include_once './includes/bootstrap.inc' ; function cron_one_site ( $sitename ) {

$_SERVER [ 'SCRIPT_NAME' ] = '/cron.php' ;

$_SERVER [ 'SCRIPT_FILENAME' ] = '/cron.php' ;

$_SERVER [ 'HTTP_HOST' ] = $sitename ;

$_SERVER [ 'REMOTE_ADDR' ] = 'localhost' ;

$_SERVER [ 'REQUEST_METHOD' ] = 'GET' ; drupal_bootstrap ( DRUPAL_BOOTSTRAP_FULL );

echo "Hostname is: $hostname<br/>\n" ;

print 'conf_path is ' .

conf_path () . '<br/>' ; drupal_cron_run ();

}

* Call this script for every site in regexp (call

* it with -h option for every site).

*/ function cron_regexp ( $siteNameRegExp ) {

global $sitesDir ;

global $debug ;

$sites = array();

// Get the name of this script, so we can call it recursively

// doesn't work: argv is not defined: $thisScript=$argv[0];

$argv = $_SERVER [ "argv" ];

$thisScript = $argv [ 0 ];

$handle = opendir ( $sitesDir );

while ( $file = readdir ( $handle )) {

if ( $debug > 0 ) {

if ( file_exists ( "$sitesDir/$file/settings.php" )) {

print( 'Yes: ' );

} else {

print( "No: " );

}

print( "exists $sitesDir/$file/settings.php<br/>" );

}

if (( $file != 'all' ) && ( file_exists ( "$sitesDir/$file/settings.php" ))) {

// preg expects the pattern to be enclosed in a (freely chosen)

// delimiter. I have chosen ^ because I think that will never

// be used in a host name if( preg_match ( '^' .

$siteNameRegExp .

'^' , $file )){

if ( $debug > 0 ) {

print '$file is ' .

$file .

', $siteNameRegExp is ' .

$siteNameRegExp .

'<br/>\n' ;

}

$sites [] = $file ;

}

foreach( $sites as $site ){

if ( $debug > 0 ) {

print 'Doing site ' .

$site .

'<br/>\n' ;

}

$commandline = '/usr/bin/php5 ' .

$thisScript .

' -h ' .

$site ; exec ( $commandline , $out1 , $out2 );

if ( $debug > 0 ) {

print 'Commandline is ' .

$commandline .

'<br/>\n' ;

print 'out1 is ' .

implode ( '\n' , $out1 ).

'<br/>\n' ;

print 'out2 is ' .

implode ( '\n' , $out2 ).

'<br/>\n' ;

}

// display the options

//print_r($ret); if ( $debug > 0 ) { print_r ( $_SERVER );

}

// parse the options array

$opts = $ret [ 0 ]; if ( sizeof ( $opts ) > 0 ) {

// if at least one option is present foreach ( $opts as $opt ) {

switch ( $opt [ 0 ]) {

// handle the all sites option case 'a' :

$re = '.*' ; cron_regexp ( $re );

break;

// handle the hostname case 'h' :

$hostname = $opt [ 1 ]; cron_one_site ( $hostname );

break;

/* handle the regexp option. */ case 'r' :

$re = $opt [ 1 ]; // regular expression cron_regexp ( $re );

break;

default:

print 'Usage: <br/>\n' ;

print '- h hostname<br/>\n' ;

print '- r regexp<br/>\n' ;

print '- a (do all sites)<br/>\n' ;

break;

}

* Some experienced I had with this script at your-webhost.nl in june 2009

* // $_SERVER["PHP_SELF"] is not set

27 of 183

2010-05-10

Multisite with cron-curl.sh

I have domain1.com hosted as the primary domain with domain2.com "parked" at domain1.com. My public_html/sites folder looks like this: sites/all sites/default sites/domain2

My webhost (an Apache server running Cpanel 11) blocks user access to lynx or wget, so the normal recommendations for setting up a crontab were not working for me. However, I discovered a suggestion in http://drupal.org/cron to try the cron-curl.sh script that ships with

Drupal in the "scripts" folder. I edited cron-curl.sh so that it includes the following line: curl --silent --compressed http://domain1.com/cron.php

And then I set up a crontab that looks like this:

*/2 * * * * /home/webhostaccountname/public_html/scripts/cron-curl.sh

After remembering to set the file permissions on cron-curl.sh so that it could be executed, the cron job worked perfectly. The "*/2" executes the crontab every other minute for testing purposes only.

So, then I went back into cron-curl.sh and added the following line: curl --silent --compressed http://domain2.com/cron.php

Again, success! I'm watching the logs for both domain1.com and domain2.com. Cron jobs are being executed every 2 minutes for both domains.

Run cron.php with python.

I was unable to run cron.php from the cpanel cron on a multisite because I had no access to curl, lynx and wget. I knew I had python installed in the shared server so what I did was to create a python script in my home folder called

wget.py

import sys, urllib def reporthook(*a): print a for url in sys.argv[1:]:

i = url.rfind('/')

file = url[i+1:]

print url, "->", file

urllib.urlopen(url)

Then, in the cron configuration, just add the command:

/path/to/python /path/to/wget.py url1/cron.php url2/cron.php url3/cron.php

Attachment Size

wget.py_.txt

218 bytes

Simple wget multisite cron, lazy method

I just wrote this script for running the crons on all my drupal sites before I discovered this section in the documentation. This works well for me because I'm lazy and I don't have to maintain a list of my drupal sites somewhere for it to run all my crons. The script simply reads the domains from my sites folder. It works well for me, but I think it might not work for every situation, ymmv.

Create an executable called

drupalcron

#!/bin/bash

#change the following line to match your sites folder cd /var/www/drupal/htdocs/sites

#the next line gets only directories, not symlinks (and not the 'all' nor 'default' directories) for f in `ls -Fd *.*|grep '/$'`

#remove the 'echo' from the following line after making sure it looks right do echo wget -O - -q -t 1 http://${f}cron.php

done

Please note, the script will only echo the command and not actually do anything. This is so that you can check to see if it looks right first.

Please read the comments in the script. If the output is what you expect, then delete the word the wget commands next time.

echo

from the

do

line and then it will execute

Then simply add that to your crontab however you wish:

10 * * * * /path/to/drupalcron > /dev/null 2>&1

Running cron manually

28 of 183

2010-05-10

To run a cron job manually, simply visit your own site's url at http://example.com/cron.php

with your web browser, and cron will run and complete in the background. You'll be left with a blank white page, which is normal. Use the browser's back button to return to the previous page and continue where you left off. It doesn't matter how long you wait while you're seeing the blank white page, and returning to the previous page at any time won't stop the cron process from running.

Core provides a convenience link for running cron manually too. Look at the Status page's link: /admin/logs/status/run-cron?

destination=admin%2Flogs%2Fstatus. You can paste that into your own site's address bar any time you want to run a cron.

In addition, if you have the update_status.module

installed, and you should since it's simply glorious, you'll be presented with a custom link on your admin/logs/updates page.

For Drupal 6.x, see in your site:

Administer > Reports > Status report > Cron maintenance tasks > Run cron manually

Setting up cron on Hostmonster through the cPanel interface

1. Logging into the cPanel interface for your hostmonster account, scroll to the bottom and look in the "Advanced" section

2. Select "Cron Jobs." It is represented with a calendar icon

3. Select "Standard"

Do not use an email address or you will be hit with a notification every time the cron job runs

4. Enter the following command: php /home/+++Your hostmonster login username+++/public_html/cron.php

This is only for your main domain, subdomains are in different folders

5. Select the number of times that you would like the cron job to run

6. See if it works -you can check whether or not a Cron Job has been run in the Logs menu in Drupal

Solving cron problems

There can be several reasons why cron will not run on your site. Issues with cron can make that cron hangs, redirects or gives a 404 error.

Try the following checklist to solve problems with cron:

Try if you can run cron manually: go to admin/reports/status and click the "run cron manually" link. If it runs you need to check your setup of crontab, see http://drupal.org/cron . A less recommended solution, but acceptable if you don't need a very regular cron run, is to install the Poormanscron module.

If the "run cron manually" link does not work it means there is a problem with cron itself

Cron might be cached in a bad way. Clear cache on admin/settings/performance. Or truncate all tables starting with cache_. Or you could search for cached instances of cron.

Cron takes too long to run. If cron has never run before and your site is allready some time online, certain tables that need to be cleaned by cron might be huge. Check the size of the watchdog, sessions or acceslog tables and truncate (empty) if needed.

If your server has restarted during a cron run, you might need to delete two cron variables. Search in the variables table for cron_last and cron_semaphore and delete these entries.

USE Name_Of_Your_Drupal_Database;

DELETE FROM variable WHERE name="cron_semaphore";

DELETE FROM variable WHERE name = "cron_last";

Or you might use in a php script: variable_del('cron_semaphore'); variable_del('cron_last');

Certain modules might cause cron not to run or give a 404 error (page not found). Disable suspect modules (those that call hook_cron) one by one and try to run cron manually every time. You can check if a module uses cron with

<?php

echo theme ( 'item_list' , module_implements ( 'cron' ));

The core Search module is one of these that uses cron and has been responsible for cron problems. So disable search, clear cache, run cron, enable search again.

If cron.php gets redirected you might have the issue http://drupal.org/node/102138 with drupal_goto(), try one of the solutions there.

The files directory

After installing Drupal, it is helpful to have a writable directory so that you can upload your own content files. If you skip this step, you may get an error message stating that "sites/default/files does not exist ..."

Here’s how:

1. Make a directory called 'files' in the sites/default folder.

2. Assign write permissions to it with the following command (from the installation directory): chmod -R a+wrx sites/default/files or chmod -R 777 sites/default/files

Also, most FTP programs allow you to create the files directory and set its permissions. Be sure to give read, write, and execute permissions to everyone (777). FYI: chmod a+rwx is equivalent to chmod 777

29 of 183

2010-05-10

Troubleshoot installation problems

Links to some of the more common installation issues are listed below. More troubleshooting information is available at the Troubleshooting

FAQ.

Fatal error: Allowed memory size of n bytes exhausted

The error "Allowed memory size exhausted" indicates that Drupal needs more memory than has been allocated under current settings. This error can be resolved by adding an extra line to Drupal's configuration files .

Failed to connect to your MySQL database server

The installation script cannot connect to the database. Check if the username, password and hostname that you provided are correct.

Cannot create directories 'files' or 'private'

The installation script needs permissions to create these directories inside the sites/default folder .

Cannot write to configuration files settings.php

The installation script needs permissions to write to the configuration files settings.php

Blank page (White Screen of Death)

Occasionally the page is completely blank (No content. No errors.) This is what is sometimes referred to as the "White Screen of Death".

There are several reasons why this might occur

"Your PHP configuration only supports the SQLite database type" on the database configuration page

during install

Drupal 7 now requires PHP to have the PDO (Php Data Object) extension enabled or compiled in. Older or home-brewed versions of PHP may not have this enabled by default. Check your phpinfo for the "pdo_mysql" extension, or see the instructions for enabling it. Discussion

Other errors

Host-specific error messages

What permissions does Drupal need?

Why is this uploading stuff so difficult

All my pages are blank

White screen of death fixing step by step

Client does not support authentication protocol

500 internal server error

Got a packet bigger than 'max-allowed-packet'

Lock tables sequences write error

Error on installation step 3

Database setup fails to proceed

Translation issues

Clean URLs how-to

Advanced and multisite installation

The following pages cover some special installation cases, such as running several Drupal sites from a single code base (also known as multisite installations) and specifying a database table prefix.

Modify the file system path

The files directory created in the initial install is the default file system path used to store all uploaded files, as well as some temporary files created by Drupal. After installation, the settings for the file system path may be modified to store uploaded files in a different location.

It is not necessary to modify this path, but you may wish to change it if: your site runs multiple Drupal installations from a single codebase (modify the file system path of each installation to a different directory so that uploads do not overlap between installations); or, your site runs a number of web server front-ends behind a load balancer or reverse proxy (modify the file system path on each server to point to a shared file repository).

30 of 183

2010-05-10

To modify the file system path:

1. Ensure that the new location for the path exists or create it if necessary. To create a new directory named uploads, for example, use the following command from a shell or system prompt (while in the installation directory): mkdir uploads

2. Ensure that the new location for the path is writable by the web server process. To grant write permissions for a directory named uploads, you may need to use the following command from a shell or system prompt (while in the installation directory): chmod o+w uploads

3. Access the file system path settings in Drupal by selecting these menu items from the Navigation menu:

Administer > Site configuration > File system

4. Enter the path to the new location (e.g.: uploads) at the File System Path prompt.

Note

Changing the file system path after files have been uploaded may cause unexpected problems on an existing site. If you modify the file system path on an existing site, remember to copy all files from the original location to the new location.

Some administrators suggest making the documentation files, especially CHANGELOG.txt, non-readable so that the exact version of Drupal you are running is slightly more difficult to determine. If you wish to implement this optional security measure, use the following command from a shell or system prompt (while in the installation directory): chmod a-r CHANGELOG.txt

Note that the example only affects CHANGELOG.txt. To completely hide all documentation files from public view, repeat this command for each of the Drupal documentation files in the installation directory, substituting the name of each file for CHANGELOG.txt in the example.

Run multiple sites from the same code base (multi-site)

If you are running more than one Drupal site, you can simplify management and upgrading of your sites by using the multi-site feature.

Multi-site allows you to share a single Drupal installation (including core code, contributed modules, and themes) among several sites.

This is particularly useful for managing the code since each upgrade only needs to be done once. Each site will have its own database and its own configuration settings, so each site will have its own content, settings, enabled modules, and enabled theme. However, the sites are sharing a code base and web document root, so there may be security concerns (see section below for more information).

Overview of the Process

To create a new site using a shared Drupal code base you must complete the following steps:

1. Create a new database for the site.

2. Create a new subdirectory of the 'sites' directory with the name of your new site (see below for information on how to name the subdirectory).

3. Copy the file into the subdirectory you created in the previous step. Rename the new file to

sites/default/default.settings.php

settings.php

4. Adjust the permissions of the new site directory, and grant write permissions on the configuration file

5. Make symbolic links if you are using a subdirectory such as example.com/subdir and not a subdomain such as subd.example.com (see the subdirectory multi-site section below for details).

6. In a Web browser, navigate to the URL of the new site and continue with the standard Drupal installation procedure.

It may also be necessary to modify your Web server's configuration file (often named httpd.conf

for Apache) to allow Drupal to override

Apache's settings. This is true for all installations of Drupal and is not specific to the multi-site install. Additional information is available in the

Best Practices: Configuring Apache and PHP for Drupal in a Shared Environment section of the Install Guide.

Details of the Process

Domains, URLs, and sites subdirectory name

The new subdirectory of the sites directory has a name that is constructed from the site's URL. For example, the configuration for www.example.com

would be in sites/example.com/settings.php

. You do not need to include 'www' as part of the directory name.

Drupal will use the same sites/example.com

directory for any subdomain of example.com

, including www, unless there is an alternative, matching subdomain sites subdirectory. For instance, URL http://sub.example.com

would be served from sites/sub.example.com

, if it exists.

For a subdirectory URL, such as http://example.com/subdir

, name the sites subdirectory as follows: sites/example.com.subdir

-- and read the section below on getting subdirectory multi-site working.

If you are installing on a non-standard port, the port number is treated as the first part of the subdomain. For example, http://www.example.com:8080

could be loaded from sites/8080.example.com

. If that directory doesn't exist, Drupal would then look for sites/example.com

, just like a real subdomain.

Site-specific modules and themes

Each site configuration can have its own site-specific modules and themes in addition to those installed in the standard 'modules' and

'themes' directories. To use site-specific modules or themes, simply create a 'modules' or 'themes' directory within the site configuration directory. For example, if sub.example.com has a custom theme and a custom module that should not be accessible to other sites, the setup would look like this:

31 of 183

2010-05-10 sites/sub.example.com/settings.php sites/sub.example.com/themes/custom_theme sites/sub.example.com/modules/custom_module

Document root

One area of frequent confusion is that in a Drupal multisite installation the webserver document root is the same for all sites. For example with the following three sites: example.com, sub.example.com and example.com/site3 there will be a single Drupal directory and all sites will be calling the same index.php file.

Some webhosts automatically create a new directory (i.e. example.com) when creating a new domain or subdomain. In this case it is necessary to make it into a symbolic link to the main Drupal directory, or better yet when creating the domain or subdomain, set it to use the same document root as the site where you have Drupal installed.

Subdirectory multi-site

If you are attempting to get Drupal multi-site working using subdirectory URLs rather than subdomain or different domain URLs, you may encounter problems. You'll start out by making a directory such as sites/example.com.subdir

, and putting a settings.php file there. If this works for you, great! But it probably will not, until you make a symbolic link that tells your web server that the document root for http://example.com/subdir type:

is the same as the document root for http://example.com

. To do this, go to the example.com document root and ln -s . subdir

(substituting the actual name of the subdirectory you want to make work).

If your codebase itself is in a subdirectory, then link your new site to the directory: ls -s drupaldir subdir

This symbolic link is enough to resolve issues with subdirectory multi-site installations on at least some web hosts. But if you still encounter problems, such as issues getting clean URLs to work (especially if you had to edit the .htaccess file to get clean URLs working on the main example.com domain site), you may find this forum suggestion useful: http://drupal.org/node/239583#comment-786932

Note that these problems do not usually occur for multi-site installations using a subdomain, so you might want to try that if you cannot get subdirectory multi-site to work. (However, subdomains are not good for search engine rankings!)

Localhost alias for local workstation

On many systems it is possible to create entries in a "hosts" file to create aliases for the localhost name for a local workstation. By creating aliases for localhost it is possible to create names such as localdev1.example.com and localdev2.example.com, both for the local computer.

If on the other hand you use subdirectories in your local web root, create a symbolic link like this: ls -s drupaldir subdir and name your site folder localhost.subdir.

Domain name changes

Once a site is in production in a particular subdirectory under the sites directory, the subdirectory should not be renamed, even if the Web site URL changes. This is because several database tables (for example: system and files) include references to "sites/www.mydomain.com."

Instead of renaming the sites directory, you can create a symlink to the new URL from the old one. Navigate to the sites directory and then use the following command:

$ ln -s /path/to/drupal/sites/old.domainname.com new.domainname.com

Security Concerns

You might want to reconsider using Drupal's multi-site configuration, in situations where the administrators for all of the sites being run from the same code base are not either the same person or a small group with a high level of mutual trust. The reason is that anyone with full administrative privileges on a Drupal site can execute arbitrary PHP code on that site through various means (even without FTP access to the site), and that arbitrary PHP code could be used from one site to affect another site, if the two sites are in the same HTTP document root and sharing the same Drupal code.

So, unless you completely trust all of the administrators of the sites you are considering running from the same Drupal code base to be knowledgeable, careful, and not malicious, you might want to consider installing their Drupal sites in completely separate areas of the web server that are not able to affect each other via PHP scripting.

Comprehensive Multi-site Video

Running a successful multi-site install requires knowledge of how Drupal handles multiple sites and how various features of Apache can be leveraged to make the multi-site much easier to manage.

The video at this link provides a great deal of detail and comprehensive conf files for an Apache multi-site install of Drupal

32 of 183

2010-05-10

Video about Multisites vs. Multiple Sites at GotDrupal.com

Domain Access

The Domain Access project is a group of lightweight modules that provide tools for running a group of affiliated sites from one Drupal installation and a single shared database. The module allows you to share users, content, and configurations across a group of sites such as:

- example.com

- one.example.com

- two.example.com

- my.example.com

- thisexample.com

<-- can use any domain string

- example.com:3000

<-- treats non-standard ports as unique

By default, these sites share all tables in your Drupal installation. The Domain Prefix module allows for selective, dynamic table prefixing for advanced users.

The module uses Drupal's Node Access system to determine what content is available on each site in the network. Unlike other multi-domain modules for Drupal, the Domain Access module determines user access based on the active domain that the user is viewing, rather than which group or site the user belongs to.

Installation and configuration

Make sure to install and configure your Drupal site before installing Domain Access. You only need one settings.php file.

For detailed instructions, see INSTALL.txt in the module directory.

To install the module, simply untar the download and put it in your site's modules directory and enable the module normally.

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. As of 6.x.2.0, the primary domain is created for you in domain table on installation, previous versions store the primary domain in variables table.

How to add a patch that will synchronize file paths between dev and prod/live sites

If you have built your Drupal site on a development machine using multi-site configuration, you've discovered that there's a headache that will occur once you've ported your site to its live box. If you are about to do this, then you'll soon see the problem.

The problem lays within the site/files directory. Once you've uploaded your development site to its live server, you'll discover that you have to go into your tables and change the paths for images and other files. On your development box, you named, just for the sake of example, your site: drupal/sites/mygreatwebsite.com And in both of these directories, you've added a files directory.

To the world, that site will be: thegreatestwebsite.com and its file structure is drupal/sites/thegreatestwebsite.com Once you went live, you'll see that the paths to your images, pdf and other files looks something like this: http://thegreatestwebsite.com/sites/thegreatestwebsite.com/files/myimage...

On one hand, you gulp at the length of that url. Next, you sigh because you realize that you have to change the path -- in the database.

Drupal 7 has a fix for this -- not the length (that's another story) but for the path problem.

And, while it won't be committed to Drupal 6, there is a patch that you can add to Drupal 6 -- if you don't mind doing that no-no: patching core.

You'll find the patch here: http://drupal.org/user/216078 It's called: multisite-d6-2.patch

Here are the steps I used to install this on a WinXP machine. To do patching, I use cygwin patch utility. Please change words that are italicized to domains/paths applicable to your site.

1. Place patch in

apache2/triad/htdocs

2. In command screen go to

3. Run the patch: patch -p0 < folder

apache2triad/htdocs/drupal

../thepatch.patch

4. Make sure there is a files directory located as follows: folder

apache2triad/htdocs/drupal/sites/water/files

5. Production and development sites should BOTH contain:

sites/water/files

6. Files system path on both local development box and production site ---- sites/water/files

7. Create a file named "sites.php" and put it into: drupal/sites/ Content of file:

<?php

$sites = array(

'water.uida.local' => 'water' ,

'water.uida.edu' => 'water' ,

);

33 of 183

2010-05-10

Note that this file can also be created by copying the default.sites.php file created when the patch was installed. Copy it and rename it to sites.php Open the file and remove the hash marks (#) that are located in front of the array at the bottom of the file. Replace the variables in the array with your configuration.

8. Clear caches. Run update.php if you are updating an already created site.

9. Add a "hacks.txt" file to your site, perhaps, to make sure others know about this core change and how it affects updates.

If you are doing this on an established site, you'll need to modify the path for your images/files as they'll be pointing to the old directory under sites.

Multi-site on Linux

Software installed:

Drupal 6

Apache 1.3

Red Hat 6.1 (Although other distributions will work)

PHP5

PostgreSQL 7.4

The process:

1. Install the Drupal core download from Drupal.org.

2. Install default Drupal site. I created mine with a "dummyUSER" user and "dummyDB" database with Drupal code in apache/htdocs/drupal

3. Once you have this working then create a new dir "example1.com" directly under "sites" dir.

mkdir sites/example1.com

cp -R sites/default/* sites/example1.com/

4. Create a new database "example1DB" and new user "example1USER" in database.

5. Edit the

sites/example1.com/settings.php

and change the following:

$db_url = 'pgsql://dummyUSER:dummyPSSWDl@localhost/dummyDB'; to

$db_url = 'pgsql://example1USER:example1PSSWDl@localhost/example1DB';

(this step is optional, normally Drupal will recognise the base url automatically):

# $base_url = 'http://www.example.com'; to

$base_url = 'http://www.example1.com';

(Remove the '#' [comment])

6. cp apache/htdocs/drupal/install.php to apache/htdocs/drupal/sites/example1.com/

7. Point your browser to www.example1.com

. Drupal will show you lot of errors.

8. Once it shows you errors you are all good. Just point your browser to www.example1.com/install.php

and it will present you the installation screen. Install from there on.

9. Repeat the above process for www.example2.com

Note

If it says the site is offline then your database information in settings.php is not correct. If it says site not found then your base url in settings.php is not correct.

Multi-site on Mac

To get multi-sites working on apache on a Mac, see "HowTo: Configure your local workstation to serve multiple sites using Drupal's multisite configurations and Apache's VirtualHost" .

Multi-site on Windows

Software

This guide assumes you have installed WAMPServer, which you can download below:

WampServer - includes Apache, PHP, and MySQL.

Alternatively, you can install another WAMP package, but you will need to adjust the paths as necessary.

Process

1. Set up Drupal as usual

1. Install WampServer (or another 'WAMP' package) and make sure that Apache and MySQL services are running.

2. open phpMyAdmin in your browser

localhost/phpmyadmin

3. Create a new database -- we'll call it here create a second and third database, which we'll call but to keep things simple here, we'll stick with the default user a tool like 7-zip to unpack the Drupal tar.gz file).

http://localhost/drupal-6.x

. Enter the

drupal6

4. Download Drupal 6 into WampServer's

wamp/www

(or it can be launched via the WampServer icon in your system tray.)

because this will be our base installation which we will leave untouched. While you're

site1

and

root site2

. You can also change the database privileges if you want,

and no password.

5. Do your first Drupal installation by pointing your browser to your Drupal folder, which should be something like

drupal6

folder (or the

htdocs

folder in Xampp and some other packages). (You'll need

database and user settings (

root

and no password in this example). Complete the

34 of 183

2010-05-10 installation, but then leave it alone.

2. Prepare the files for your new multi-sites

1. Find Drupal's

sites

folder, make a copy of the

default

folder and rename it to the URL you want for your first test site. To keep it simple, we'll make it the same as the first test site database: within this new folder. The can create a contributed modules together in the

2. Use a text editor to open the database, and the database user name and password, eg:

site1

. While you're here, create

files, tmp

and

themes

sub-folders

themes

sub-folder will be used for any custom theme you create specifically for this site. Similarly, you

modules

sub-folder for any module you use only with this site. However, generally, I find it easier to keep all

sites/all/modules

folder so I can use them with all my test sites.

settings.php

file in your new

site1

folder and change

$db_url

line to reflect your first test site mysql://username:password@localhost/site1

Also, change the $base_url to the above site URL, eg:

$base_url = 'http://site1';

// NO trailing slash!

3. Repeat the above 2 steps for the other test site (

site2

)

3. Adjust windows so it can find the new site at a new made-up name

Find the Windows

hosts

file, which should be in Windows'

System32/drivers/etc

folder, make a backup of that file and then open the

hosts

file in a text editor. Here, add new lines mapping your localhost IP address to match the URLs of your test sites and your original

Drupal site. In our example, it would look like this:

127.0.0.1 localhost

127.0.0.1 site1

127.0.0.1 site2

127.0.0.1 drupal6

This is telling Windows Networking that http://site1/ do with this file is make sure the "Virtual hosts" line is active by removing the

before

Include conf/extra/httpd-vhosts.conf

2. Make a backup of that editor and add these lines:

is

a name for this machine.

4. Adjust Apache so it responds to requests for the new names

1. Find the Apache

httpd.conf

file which, in WampServer, should be in the version number). Sorry, I can't remember where Xampp installs this, but it will be in the Apache folder. Anyway, all you need to

httpd-vhosts.conf

file (which is in Apache's

wamp/bin/ApacheX.X/conf conf/extra

folder), then open

folder (where X.X is the Apache

httpd-vhosts.conf

with a text

DocumentRoot C:/wamp/www/drupal-6.x

ServerName site1

</VirtualHost> where

C:/wamp/www/drupal-6.x

is the path to the Drupal installation folder and localhost URL (if you want to keep this active), eg:

site1

is the URL for your first test site. Add another entry for your other test site, another entry for your original Drupal installation and another entry for WampServer's

DocumentRoot C:/wamp/www/drupal-6.x

ServerName site2

</VirtualHost>

DocumentRoot C:/wamp/www/drupal-6.x

ServerName drupal6

</VirtualHost>

DocumentRoot C:/wamp/www

ServerName localhost

</VirtualHost>

3. Restart Apache for the changes to take effect. With WampServer, this is done by selecting the WampServer icon in the system tray and then "Restart all services".

5. Now you're ready to install each Drupal test site using your browser, eg: http://site1/install.php

http://site2/install.php

And that's it. You can access your two test sites anytime WampServer is running by using the http://site1 and http://site1 URLs.

As I said, it's not exactly simple, but it is well worth the effort. Now you can do whatever you like with your test sites. If you mess up with, say, site1, just delete the

site1

folder, the

site1

database in phpMyAdmin and the site1 entries in the Windows

hosts

and Apache

httpdvhosts.conf

files and start again. Alternatively, if a site works out and you want to go live with it, the multi-site approach makes this easier

(in my opinion).

One final caveat: I'm no expert. This technique works for me (apart from one corporate environment with a particularly annoying proxy server), but I'd welcome any feedback, especially if there are any accuracies.

Multi-site with single codebase, different content databases, shared user database, shared sign-on

SECURITY ALERT - The Shared Sign-On module this tutorial formerly relied on has been withdrawn because of security risks. It is no longer available at all. There is a replacement module called Single Sign On . It should replace the Shared Sign-On module, but currently reports problems with user registration and recommends registration happens through the master site. If your solution requires branded registration pages, you could create a suite of registration pages on the master site and use the Theme Key module to apply the correct theme to each one, for a seamless user experience (except for the URL, obviously).

WARNING - Following this approach will make updates potentially trickier. It's not a major issue, but you must be mindful that you are sharing some tables amongst several Drupal instances, so you will need to be aware of install and update hooks which want to make changes to any shared tables. For example, it is possible for the update or install scripts of a module unique to one instance to break other instances if it makes changes to shared tables. There are other multi-site solutions , so plan carefully before selecting which one is right for you.

35 of 183

2010-05-10

This tutorial makes two assumptions:

1. You are _not_ a total newbie

2. You have downloaded MySQL GUI Tools (to make life easier) - clearly this is not a pre-requisite - if you know and prefer command line

MySQL then you can replicate the steps I provide easily enough: http://dev.mysql.com/downloads/gui-tools/5.0.html

Make a copy of /sites/default to /sites/site1 and another to /sites/site2. You may add modules and themes directories in these new directories in the usual way for site-specific configurations. A files directory should be there already but create it if not. Rename

/sites/site1/default.settings.php to settings.php and /sites/site2/default.settings.php to settings.php (and, for Linux, make sure both new files directories are writeable by the web user).

Add these lines to your hosts files:

127.0.0.1 site1

127.0.0.1 site2

Create three empty MySQL databases: drupal_site1 drupal_site2 drupal_shared_tables

Go to http://site1 and run through the install process in the normal way, using the database name 'drupal_site1'.

In MySQL Administrator create a new back-up project of the 'drupal_site1' database containing _only_ the tables you want to share, save it and run it. The result should be a .sql file somewhere on your computer. For reference, the Drupal 6.x tables for sharing users are as follows: authmap profile_fields profile_values role sessions users

The absolute basic essential tables (if you don't want to share any data except for the users and sessions, no profile data, roles, etc.) are: sessions users

IMPORTANT: if you have Open ID authentication enabled you will also need to share the openid_associations

table.

(This is not a definitive list. Nothing stops you from sharing taxonomy, etc. For example, with this configuration permissions are _not_ shared

- each site has its own permissions matrix - but you might want to share one across all sites. Ditto with enabled modules.)

Edit the .sql script you created and update the database name within to 'drupal_shared_tables'. Using the Restore interface, run the .sql

script. You should now have a database called 'drupal_shared_tables' containing only the list of tables above.

Go to http://site2 and run through the install process in the normal way, using the database name 'drupal_site2'.

Go back to your original 'drupal_site1' database and drop the same list of tables from the schema. Ditto for the 'drupal_site2' database.

Now our databases are ready.

Browse to your Drupal application and edit /sites/site1/settings.php. Change these lines (usually starting at line 93 in Drupal 6.3):

<?php

$db_url = 'mysqli://user:password@localhost/drupal_site1' ;

$db_prefix = '' ;

To:

<?php

$db_url = 'mysqli://user:password@localhost/drupal_site1' ;

$db_prefix = array(

'default' => '' ,

'authmap' => 'drupal_shared_tables.' ,

'profile_fields' => 'drupal_shared_tables.' ,

'profile_values' => 'drupal_shared_tables.' ,

'role' => 'drupal_shared_tables.' ,

'sessions' => 'drupal_shared_tables.' ,

'users' => 'drupal_shared_tables.' ,

);

Note the all important trailing dot on the end of drupal_shared_tables - this is vital! You're pre-pending table name info to Drupal's default table name, so you need the dot or Drupal will try to select: drupal_site_1.drupal_shared_tablesauthmap

Instead of the desired: drupal_shared_tables.authmap

Do the same for /sites/site2/settings.php, but with $db_url set to drupal_site2.

36 of 183

2010-05-10

You should now be able to login as the super user on both sites separately ( http://site1/user or http://site2/user ), using the credentials you entered when you installed site1, give them both different settings, modules, permissions and content but use the same user credentials.

Moreover, if you create a user on site1, you will see them in users in site2, but with an entirely independent set of permissions you can decide on a site level.

Now for the shared logins. Download and unzip the Single Sign On module in to /sites/all/modules.

Enable the Single Sign On Controller module on the site you want to use as the master for logins (the controller) - in our case, site1. Enable the Single Sign On Client module on all other sites, for this example just site2.

Then IMMEDIATELY add the following line to settings.php for both sites (see the Single Sign-On README ) or you will get PHP errors:

<?php

# Single Sign On settings:

$conf [ 'session_inc' ] = 'sites/all/modules/sso/session.singlesignon.inc' ;

Copy and paste the Controller information on site1 (found at admin/settings/singlesignon-controller) over to the Client settings on site2 (go to admin/settings/singlesignon-client). Save settings on site2 and logout of both sites. Clear your cookies to avoid any hang-overs from presingle-sign-on days.

Go to http://site1/user and login. Now go to http://site2 . You should stay logged in. Logout again and see you are logged out in both locations. Reverse it so you login on site2 and visit site1. Neat, huh? =)

Need a new site? Take a copy of /sites/default to /sites/new-site, make the necessary vhosts (optional, see below) and DNS/hosts changes, create a blank database, run the Drupal installer, drop the tables you don't want from your new database (the shared ones), edit settings.php

adding the $db_prefix array as above, configure Single Sign-On and you're done!

Optional Apache settings

If you would like to set different Apache settings for your various sites (e.g. different access and error logs for each) add a vhost entry to

Apache looking something like this:

DocumentRoot "c:/path/to/drupal"

ServerName site1

ServerAlias site2

CustomLog logs/d6_access_log.log common

</IfModule>

ErrorLog logs/d6_error_log.log

Options +Indexes

AllowOverride All

Allow from all

</Directory>

</VirtualHost>

This is not usually necessary.

IMPORTANT - if any of your client sites have any URLs that need to be accessed without an authentication check, the site concerned

_must_ have a line in the 'Request paths' box of Single Sign On Client settings to exclude that URL from being redirected to the controller site for authentication. These settings can be found under 'Bot recognition' settings (admin/settings/singlesignon-client). For example, if one of your clients uses the Services module to expose Drupal-based web services you would add a line like this to that box, in order to exclude all your endpoints from the authentication check: services/*

Remember, this only applies to client sites, not the controller, and must be done on all sites.

Multisite Manager module

The Multisite Manager contributed module allows creation of new Drupal sites from a central Drupal site without the creator having access to database info. The new site is installed either in the same database with a different prefix or if the drupal db_user has access to create a database and grant privileges, then possibly there.

Get started by reading the INSTALL.txt

documentation.

More help on some gotchas exists below.

File names

In a situation where you have an existing file for a site http://www.mysite.com

and you want to multisite http://www.myothersite.com

into it you need to make a new directory to the /sites directory you will find within the mysite file system.

This directory should be called /sites/myothersite.com.

When you set up a new Drupal site you are asked for the database name, username, password and the prefix of files relevant to the site. This information has to be entered into Database Manager in http://www.mysite.com/admin/settings/multisite_manager and will generate a script

This script -

which currently does not include the database password and omits the initial <?php

settings.php and pasted into the directory you set up above.

What Happens Next

Log into http://www.myothersite.com

normally and the normal Drupal set up screens will appear.

Complete this and then create the new site as if it were free standing.

- should be copied into a file called

37 of 183

2010-05-10

Notes on Multi-sites with Separate Code bases

A simple Multi-Site install uses different databases for each site that the installation is hosting. In a nutshell, a simple Multi-Site extends a

"Singular-Site" installation by the web developer (that's you) adding folders for each site that is served by the installation, in the "sites" directory.

The "default" Folder

When you install a fresh copy of Drupal, a "default" folder is created inside "theRootOfYourInstallation/sites". Inside this folder resides a file called "settings.php" which contains this line of code:

$db_url = 'mysql://username:password@pathTodataBase'; to securely access your database.

During the initial database installation wizard, Drupal populates that particular line of code with values you entered into the fields.

The reason this is called "default" is because, well, this is the default folder that Drupal looks into to find (in the "settings.php" file) they keys to access the databases. The "default" folder can also contain other items, such as a folder called "files" that contains the files for the default installation.

The Key to Understanding Multi-Sites

For continuity, I will use "example.com" as the domain name for the "default" installation / folder and "doesthiswork.com" as the domain name for the site we are adding to this installation.

Now that you know about the "default" folder, you can begin to understand how to add multiple sites to one installation: to add another

site to this installation,

1. Create a sibling of the "default" folder with the domain name of "doesthiswork.com" . It is way important to use the extenstion (the

.com or .edu, or .org).

2. Inside this folder, you will include a fresh version of "settings.php" (renamed from a "default.settings.php" taken from the zipped files of fresh Drupal core files)

3. Make sure that you have a fresh database created with no tables in it. Write down the path to the database, the username and password

4. Now you are ready to point your site to the root of the installation. The tricky part of this "simple" instruction is find where your DNS provider lets you point to another site. An example of a solution to this step is this: Say my "default" domain name (that goes to the default folder) is http://www.example.com and a domain /site that I want to add to this installation is

http://www.doesthiswork.com. In the DNS panel for http://www.doesthiswork.com

, I would point the CNAME to http://www.example.com

. When Drupal gets a request for "doesthiswork.com", it will find the doesthiswork.com folder in sites.

5. The first time you go to "doesthiswork.com", you will be greeted with the welcoming Drupal Installation Wizard". Once you finish the installation wizard, the keys to your database kingdom will be saved an you will be free to enter your new Drupal site.

So, what's the key to understanding how this works? It is: for every site that you add on this installation, you will need to create a separate domain name folder in sites with (at least) a "settings.php" file. Each folder/settings.php file points to a different database

installation. Drupal uses the files stored on the multisite server, in addition to the data in each database to serve up the site.

For each new site that you add, you will have to run through the installation wizard, setting up the site and adding content. ( See installation profiles to make your life easier!

) To reiterate: when you update a module, you will have to run "http://www.example.com/update.php" and

"http://www.doesthiswork.com/update.php" (and other update.php's for each site on your multi-site install) to update EACH database. You might think that this is still alot of work... but it really is a time saver.

Remember to: put your sites in maintainence mode (admin/settings/site-maintenance)before run cron manually (admin/reports/status/run-cron) and clear the cache (admin/settings/performance) after you run update.php !

Additional Files to place inside your "default" sibling

You can also have

Files

Theme

Modules as folders in the "doesthiswork.com" folders. Those items will only be seen by the "doesthiswork.com" installation. As you might have guessed, items in the "theRootOfYourInstallation/sites/all" folder will be avaliable to ALL the site in your Multi-site install.

If you place all your modules in the "theRootOfYourInstallation/sites/all" folder, when you upgrade to an newer version, you only have to replace the module there. However, you need to "update.php" on all sites in your multi-site... including your default site.

One of the things that can trip you up is forgetting to create a "files" folder in your "doesthiswork.com" folder. Make sure you have done that to keep separate files from "different" sites.

38 of 183

2010-05-10

Multi-site how-tos

Instructions on multi-site configuration (also known as "multisite" and "single code base" installations) can be found within the installation instructions.

Here are some useful links:

Search results

4.6 Multi-Site from single code base

Multi-Site .htaccess configuration multi-site, single installation, shared db, single sign on. is this possible?

Automatic Multi-site registration

Using Multi-Site (4.x)

Multihosting Off Single Codebase (4.x)

Multisite and symlinks doesn't work

Sharing tables between installations (4.x)

10 Minute Multisite Install & Configuration

Multisite 10 minute Install:

Server: LAMP

SSH (telnet) Client: ssh (PuTTY if you are using Windows to access your LAMP host)

Must have root access to your server.

If website in question is an addon domain, i.e., addon.example.com, then substitute "addon" for "www" in steps below.

For list of Linux commands visit: http://www.oreillynet.com/linux/cmd/ or http://www.ss64.com/bash/

Here we go:

[login via ssh / PuTTY]

Debian (Ubuntu)

Debian and offshoot distributions (e.g. Ubuntu) make installation and configuration very easy. This was done on a Debian distribution,

Ubuntu should work identically.

Installation

Assumption: apache2 and mysql are already installed. If not, use apt-get install

to install and configure them.

# apt-get install drupal6

Answer the questions. This will install everything necessary to run drupal and do the basic configuration, including creating an empty database for drupal.

Configure database for drupal6 with dbconfig-common? [YES]

Database type to be used by drupal6: [mysql]

Password of your database's administrative user: [enter mysql root password]

MySQL application password for drupal6: [create a password for your drupal6 db]

(enter the password again for verification)

You now have a basic

unconfigured

Drupal6 installation using the database drupal6

and accessible at http://www.example.com/drupal6

Do not use it.

This is the "prototype" installation that we will use to create the sites we really want to use.

Create Site Databases

The easiest way to create databases for your sites is to use dpkg-reconfigure

and answer the questions.

# dpkg-reconfigure drupal6

Re-install database for drupal6? [YES]

Database type to be used by drupal6: [mysql]

Connection method for MySQL database of drupal6: [unix socket]

Name of your database's administrative user: [root]

Password of your database's administrative user: [enter mysql root password] username for drupal6: [ENTER YOUR DB SITE *USERNAME* HERE (e.g. mysite)] database name for drupal6: [ENTER YOUR DB *SITE* NAME HERE (e.g. mysite)]

Notes:

1. Repeat the above for each site you want to support.

39 of 183

2010-05-10

2. I used the same name for the database and the site. KISS.

3. Don't use periods (e.g. mysite.com is a bad choice). If you want to spell out the whole name, use underscores instead of periods (e.g.

mysite_com).

4. The above method ends up using the same site database password for all the sites you create. Advice: use mysql-admin

(or mysql

) to use different passwords for each site.

Configure Apache2 for Sites

Apache2 needs to be configured to support vhost

access to your new sites.

Create vhost

site configuration files in

/etc/apache2/sites-available/

# Virtual hosting configuration for Drupal

ServerAdmin [your email address]

DocumentRoot /usr/share/drupal6/

ServerName [your vhost#1 name]

ServerAlias [if you want to support www.example.com

and example.com]

RewriteEngine On

RewriteOptions inherit

</VirtualHost>

ServerAdmin [your email address]

DocumentRoot /usr/share/drupal6/

ServerName [your vhost#2 name]

ServerAlias [if you want to support www.example1.com

and example1.com]

RewriteEngine On

RewriteOptions inherit

</VirtualHost>

[...repeat for all your vhosts]

Notes:

Modify the above items that are in

[square brackets]

You likely will want to support port 443 ( https

) as well. See Apache documentation for detailed instructions.

I've chosen to put all the vhosts in one file named

drupal

. You may want to use one file per vhost.

Sym-link the drupal

file in the sites-enabled

directory to enable it in your site:

# cd /etc/apache2/sites-enabled

# ln -s ../sites-available/drupal .

...and reload Apache2 to pick up your configuration changes...

# /etc/init.d/apache2 reload

Create Drupal Site Configurations

We need to create Drupal configurations for each site by copying the default configuration to the Drupal site subdirectory.

# cd /etc/drupal/6/sites/

# cp -a default [site1.com]

# cp -a default [site2.com]

...and edit the configurations to use the right database, MySQL user name, and password...

# vi site1.com/dbconfig.php

# vi site2.com/dbconfig.php

Notes:

Modify the above items that are in

[square brackets]

Run Drupal and Configure Your Sites

Browse to your sites, running install.php

(e.g. http://www.example.com/install.php

) to configure them.

Manual

Get to location where Drupal core will be located:

[/]# cd /var/www

Upload Drupal core:

"x.x" should be replaced with the version of Drupal you're installing, e.g. "5.2"

[/var/www]# wget http://ftp.osuosl.org/pub/drupal/files/projects/drupal-x.x.tar.gz

40 of 183

2010-05-10

Unpack Drupal core:

[/var/www]# tar -zxvf drupal-5.2.tar.gz

Move contents of Drupal core (including .htaccess) to html:

[/var/www]# mv drupal-x.x/* drupal-x.x/.htaccess /var/www/html

Clean-up:

[/var/www]# rm drupal-x.x.tar.gz

[/var/www]# rm drupal-5.2

Create the files directory per Drupal instructions and change permissions (will change permission again after install):

[/var/www]# cd html

[/var/www/html]# mkdir files

[/var/www/html]# chmod 777 files

Make directories that will hold custom and contributes modules and themes:

[/var/www/html]# cd sites/all

[/var/www/html/sites/all]# mkdir modules

[/var/www/html/sites/all]# mkdir themes

[/var/www/html/sites/all]# cd modules

[/var/www/html/sites/all/modules]# mkdir custom

[/var/www/html/sites/all/modules]# mkdir contrib

[/var/www/html/sites/all/modules]# cd ../

[/var/www/html/sites/all]# cd themes

[/var/www/html/sites/all/themes]# mkdir custom

[/var/www/html/sites/all/themes]# mkdir contrib

Create directory "www.example.com.tld":

[/var/www/html/sites/all/themes]# cd ../

[/var/www/html/sites/all]# cd ../

[/var/www/html/sites]# mkdir www.example.com

Change permission of "settings.php" per Drupal instructions and copy "settings.php" in default to www.example.com:

[/var/www/html/sites]# cd default

[/var/www/html/sites/default]# chmod 777 settings.php

[/var/www/html/sites/default]# cd ../

[/var/www/html/sites]# cp -a default www.example.com

Create database and user with permissions:

[/var/www/html/sites]# mysql mysql> CREATE DATABASE wwwexamplecom_drupal; mysql> GRANT ALL PRIVILEGES ON wwwwexamplecom_drupal_drupal.* TO 'wwwexamplecom_drupal_myusername'@'localhost' IDENTIFIED BY

'mypassword'; mysql> \q

Go back to PuTTY to chmod on settings.php in www.example.com:

[/var/www/html/sites]# cd www.example.com

[/var/www/html/sites/www.example.com]# chmod 755 settings.php

[/var/www/html/sites/www.example.com]# logout

What next?:

Make changes to "settings.php" in www.example.com

? I've read that it's not necessary to make changes to setting.php.

Make changes to "httpd.conf" in /usr/local/apache/conf?

I've been using WHM to create accounts, putting Drupal in public_html and having no problems. But when it comes to parting from the WHM abstraction and getting multisite set-up correctly this is the end of the proverbial road for me.

Could use help...:

1. Help making improvements to steps articulated above

2. Help with next steps so that I/we can get on to grander things, like creating modules, custom themes, profiles, (and maybe - just

41 of 183

2010-05-10 maybe - spend some time working on business strategy :-)

Setting up multi-site Drupal on Windows or Linux consolidated instructions

If you are new to Drupal and Apache, these instructions will walk you through most of the things you need to do, to get Drupal up and running on Linux or Windows. I haven't covered the details of setting up a database in MySQL with phpMyAdmin, but I do show you how to configure Apache so that this works. For the Linux instructions the file paths are typical for SuSE Linux 10.1 - for most other Linuxes the htdocs path is likely to start at a different place, but the principles are the same.

We will assume you want to make a local installation on a Windows PC and an installation reachable via the Internet on a Linux server.

Hosts file

You will find the hosts file at the following locations:

- on Windows: c:\windows\system32\drivers\etc\hosts

- on Linux: /etc/hosts

In these instructions, we will assume you want to install a number of sites at:

On Windows (local): strawberry.loc and blueberry.site

On Linux (Internet): yourdomain.com and blueberry.com

The hosts file will look as follows for the Windows example:

127.0.0.1 localhost

127.0.0.1 strawberry.loc

127.0.0.1 blueberry.site blueberry

For a Linux internet server the hosts file should look as follows: ipaddress yourhostname.yourdomain.com yourhostname

127.0.0.1 localhost

Please note that for the Linux server on the Internet you only need to have the Fully Qualified Domainname (FQD) in the form of yourhostname.yourdomain.com in the hosts file. On a Linux system working with DNS, you DO NOT need to make any entries other than the primary FQD in the hosts file. If you want to have a local site at blueberry.site on Linux, you should add the following line to the Linux hosts file:

127.0.0.1 blueberry.site blueberry

Of course blueberry.site would not be reachable through the Internet, because the Internet DNS system would know nothing about it, whereas it would work for a local user on that computer because the local system would know how to deal with it by looking up the information in the computer's hosts file.

DNS

Set up the DNS entries for every domainname your server is hosting. Each one of these domains needs to be resolved to your server's ip address. You will normally be able to configure this with your domain registrar or hosting provider.

For a local Windows or Linux installation, e.g. for development, no DNS configuration is necessary - the entries in the hosts file on your computer are sufficient. Please note that the default localhosts entry in the hosts file is not sufficient to get multi sites working on a Drupal installation.

Apache

Configure Apache for all the different domain names that your web server will be serving.

For Linux (our examples use paths for SuSE Linux > 10.0) the best place to do this is in the vhosts.conf

file in the

/etc/apache2/vhosts.d

directory (you can call this file {anything}.conf). Actually every filename ending in .conf in the vhosts.d directory will be picked up, so beware of multiple overlapping entries - they will confuse the web server.

The entries can also be placed in the

/etc/apache2/httpd.conf

file initially to keep things simple. Later it is better to do it in the vhosts.conf

file - this way, in case of an update of the Apache software, if the httpd.conf

file is overwritten, your configuration will survive.

For Windows, you can get Apache, MySQL and PHP from: http://www.apachefriends.org/en/xampp-windows.html

If you installed XAMPP in the default directory on Windows, the vhosts file will be at: c:\program files\xampp\apache\conf\extra\httpd-vhosts.conf

The entries can also be placed in the c:\program files\xampp\apache\conf\httpd.conf

file initially to keep things simple.

On Linux (the paths in the example are for SuSE Linux), your vhosts.conf

file (or entries at the end of the httpd.conf

file) should look as follows:

# First entry of this file should be the NameVirtualHost entry, unless it is already there

# If you want your web server to respond on a different port from the default

# replace 80 with that port number

# Available alternative port numbers are 8080 and 2222

42 of 183

2010-05-10

NameVirtualHost *:80

# For each domain you want to serve up with Drupal,

# you need an entry that will match the incoming domain

# You do not need a separate entry for each subdomain - Drupal takes care of that

# The following entry takes care of :

# yourdomain.com

# www.yourdomain.com

# bla.yourdomain.com

# gaga.yourdomain.com

# etc.

# In the following we assume that the Apache htdocs directory is at /srv/www/htdocs

# and that Drupal has been installed in /srv/www/htdocs/drupal

DocumentRoot /srv/www/htdocs/drupal

ServerName yourdomain.com

ServerAlias *.yourdomain.com

Allow from all

Options +Includes +Indexes +FollowSymLinks

AllowOverride all

</Directory>

</VirtualHost>

# The following entry takes care of :

# blueberry.com

# www.blueberry.com

# bla.blueberry.com

# gaga.blueberry.com

# etc.

# In the following we assume that the Apache htdocs directory is at /srv/www/htdocs

# and that Drupal has been installed in /srv/www/htdocs/drupal

DocumentRoot /srv/www/htdocs/drupal

ServerName blueberry.com

ServerAlias *.blueberry.com

Allow from all

Options +Includes +Indexes +FollowSymLinks

AllowOverride all

</Directory>

</VirtualHost>

# On Linux, you will also need an entry to ensure that your phpMyAdmin works

# - you will need phpMyAdmin to set up and manage your MySQL databases

# I assume here that you have unpacked and copied the phpMyAdmin files to

# /srv/www/htdocs/phpMyAdmin

# Please note that in the following, the DocumentRoot and Directory command

# both need to use phpMyAdmin

# using phpmyadmin doesn't work even though phpmyadmin

# is a symbolic link to phpMyAdmin

ServerName phpmyadmin.yourdomain.com

DocumentRoot /srv/www/htdocs/phpMyAdmin

allow from all

Options +Indexes +Includes +FollowSymLinks

AllowOverride FileInfo Options

</Directory>

</VirtualHost>

For the local Windows example, your httpd-vhosts.conf

file (or entries at the end of the httpd.conf

file) should look as follows:

# First entry of this file should be the NameVirtualHost entry, unless it is already there

# If you want your web server to respond on a different port from the default

# replace 80 with that port number

# Available alternative port numbers are 8080 and 2222

NameVirtualHost *:80

# For each domain you want to serve up with Drupal,

# you need an entry that will match the incoming domain

# You do not need a separate entry for each subdomain - Drupal takes care of that

# The following entry takes care of e.g:

# strawberry.loc

# www.strawberry.loc

# bla.strawberry.loc

# gaga.strawberry.loc

# etc.

# In the following we assume that the Apache htdocs directory is at

# c:/program files/xampp/htdocs

# and that Drupal has been installed in c:/program files/xampp/htdocs/drupal

DocumentRoot "c:/program files/xampp/htdocs/drupal"

ServerName strawberry.loc

ServerAlias *.yourdomain.com

Allow from all

Options +Includes +Indexes +FollowSymLinks

AllowOverride all

</Directory>

</VirtualHost>

43 of 183

2010-05-10

# The following entry takes care of e.g:

# blueberry.site

# www.blueberry.site

# bla.blueberry.site

# gaga.blueberry.site

# etc.

# In the following we assume that the Apache htdocs directory is at

# c:/program files/xampp/htdocs

# and that Drupal has been installed in c:/program files/xampp/htdocs/drupal

DocumentRoot "c:/program files/xampp/htdocs/drupal"

ServerName blueberry.site

ServerAlias *.blueberry.site

Allow from all

Options +Includes +Indexes +FollowSymLinks

AllowOverride all

</Directory>

</VirtualHost>

It seems that the first entry in vhosts.conf becomes the default Apache server, whereas the last entry in httpd.conf

becomes the default.

On Windows, you get to phpMyAdmin by pointing your browser to http://localhost/phpmyadmin , if it is installed in the default location under the xampp directory.

Drupal

Make sure that the settings.php

file in

/srv/www/htdocs/drupal/sites/default on Linux or

c:\program files\xampp\htdocs\drupal\sites\default on Windows is the default file that came with the Drupal distribution. Now point your browser to http://yourdomain.com

and you will see the Drupal install screen which will walk you through the installation for the site http://yourdomain.com

It will ask you for

- the name of the MySQL database

- the database user and password, and

- ask you to set up the first user who will become the administrator of the site.

It is IMPORTANT that the you use this original settings.php file, OR ELSE the Drupal install procedure DOES NOT WORK when you go to http://yourdomain.com

. The reason for this is that if you use an existing installations settings.php

file, Drupal thinks the site is already configured and DOES NOT start the one time start up installation.

Do the same for any other domains you intend to use and have configured in Apache.

Independent Site at a subdomain

To have http://bla.yourdomain.com

(Linux example) or http://bla.strawberry.loc

(Windows local) be a different Drupal site, create a directory called:

/srv/www/htdocs/drupal/sites/bla.yourdomain.com on Linux or

c:\program files\xampp\htdocs\drupal\sites\bla.stawberry.loc on Windows and copy the default settings.php

file that came with the Drupal distribution into the above directory.

It is IMPORTANT that the you use this original settings.php file, OR ELSE the easy Drupal install procedure DOES NOT WORK. Make sure you have created a separate database for this site in MySQL before starting the install. Just point the browser to: http://bla.yourdomain.com

on Linux hosting server or http://bla.strawberry.loc

on your Windows server to start the installation. Again, It will ask you:

- for the name of the MySQL database

- for the database user and password, and

- to set up the first user who will become the administrator of the site.

Repeat the above for any other sub-domains you want to configure such as http://hello.blueberry.site

on Windows.

Independent site at a sub URL

To set up a separate Drupal site at http://www.yourdomain.com/gugu create a directory called

/srv/www/htdocs/drupal/sites/www.yourdomain.com.gugu

c:\program files\xampp\htdocs\drupal\sites\www.stawberry.loc.gugu on Windows and copy the default settings.php

file that came with the Drupal distribution into the above directory.

It is IMPORTANT that the you use this original settings.php file, OR ELSE the Drupal install procedure DOES NOT WORK. Make sure you have created a separate database for this site in MySQL before starting the install. Just point the browser to: http://www.yourdomain.com/gugu on Linux or http://www.strawberry.com/gugu on Windows

44 of 183

2010-05-10 to start the installation. You will be asked:

- for the name of the MySQL database

- for the database user and password, and

- to set up the first user who will become the administrator of the site.

Mechanism for setting up sub-domain and sub-directory/sub-URL sites

For details on how Drupal uses the sites directory structure, read the

INSTALL.txt

file in the top level drupal directory. Here is the relevant excerpt:

MULTISITE CONFIGURATION

A single Drupal installation can host several Drupal-powered sites, each with its own individual configuration.

Additional site configurations are created in subdirectories within the 'sites' directory. Each subdirectory must have a 'settings.php' file which specifies the configuration settings. The easiest way to create additional sites is to copy the 'default' directory and modify the 'settings.php' file as appropriate. The new directory name is constructed from the site's URL. The configuration for www.example.com

could be in 'sites/example.com/settings.php' (note that 'www.' should be omitted if users can access your site at http://example.com/ ).

Sites do not have to have a different domain. You can also use subdomains and subdirectories for Drupal sites. For example, example.com, sub.example.com, and sub.example.com/site3 can all be defined as independent Drupal sites. The setup for a configuration such as this would look like the following: sites/default/settings.php

sites/example.com/settings.php

sites/sub.example.com/settings.php

sites/sub.example.com.site3/settings.php

When searching for a site configuration (for example www.sub.example.com/site3 ),

Drupal will search for configuration files in the following order, using the first configuration it finds: sites/www.sub.example.com.site3/settings.php

sites/sub.example.com.site3/settings.php

sites/example.com.site3/settings.php

sites/www.sub.example.com/settings.php

sites/sub.example.com/settings.php

sites/example.com/settings.php

sites/default/settings.php

If you are installing on a non-standard port, the port number is treated as the deepest subdomain. For example: http://www.example.com:8080/ could be loaded from sites/8080.www.example.com/. The port number will be removed according to the pattern above if no port-specific configuration is found, just like a real subdomain.

Each site configuration can have its own site-specific modules and themes in addition to those installed in the standard 'modules'and 'themes' directories.

To use site-specific modules or themes, simply create a 'modules' or 'themes' directory within the site configuration directory. For example, if sub.example.com has a custom theme and a custom module that should not be accessible to other sites, the setup would look like this: sites/sub.example.com/: settings.php

themes/custom_theme modules/custom_module

NOTE: for more information about multiple virtual hosts or the configuration settings, consult the Drupal handbook at drupal.org.

Permissions

FINALLY, make sure all the directories from /srv/www/htdocs/drupal downwards are accessible by the web server. On SuSE Linux, execute: chown -R wwwrun:www /srv/www/htdocs/drupal to ensure that the directories have the right permissions. The userid (uid) is wwrun and the group id (gid) is www.

These can also be configured somewhere in Apache. For other Linux distributions, find out as what user and group Apache runs as and

45 of 183

2010-05-10 where the htdocs Apache web server root directory is.

Nothing further can stand in the way of your Drupal development - enjoy.

5 minute multisite using Cpanel

You want petermoulding.biz

, cjm.net.au

, and unlevelhome.com

on the same server, or virtual private server, using one copy of Drupal and a separate database for each site. You are using Cpanel. The first site will take whatever time you need to upload and install Drupal. The second and subsequent sites will take 5 minutes each. This example uses Drupal 6. Drupal 7 appears to be the same.

First site

I assume you have the first site set up. You used WHM to create a database account for petermoulding.biz then went into Cpanel for petermoulding.biz to set up email and install Drupal. You now have petermoulding.biz working with Drupal 6.

When you created petermoulding.biz, you created a user for the account and I will assume the user is named pb. Use the MySQL Databases option or the wizard. I use the MySQL Databases option. You create a database named drupal and cpanel shows a database named pb_drupal. You create a user named drupal for the database and Cpanel displays user pb_drupal. You then connect user pb_drupal to database pb_drupal with all privileges.

You use the Cpanel Email Accounts page to create some email accounts for petermoulding.biz including one named boss. You will use boss

(at) petermoulding.biz as the email address when you create the administration account during the Drupal installation.

When installing Drupal, you create directories /sites/default/ and /sites/default/files/ plus file /sites/default/settings.php. You set the permissions to 777 then run the installation step then set /sites/default/settings.php back to 644. You will repeat this step once for each new site.

Second site

Go into Cpanel on petermoulding.biz and park domain cjm.net.au on petermoulding.biz. While you are there, park unlevelhome.com on petermoulding.biz. If you run into a limit on the number of parked domains, you can go back into WHM to increase the limit. You want a database per domain so while in WHM, increase the limit on the number of databases.

Create a database and database user for cjm.net.au, perhaps user pb_cjm connected to database pb_cjm. Repeate for unlevelhome.com with user pb_unlevel connected to database pb_unlevel.

Go into Email Accounts and create boss (at) cjm.net.au plus boss (at) unlevelhome.com.

You probably used FTP to upload Drupal 6 to petermoulding.biz. I will assume FTP. There is a file manger in Cpanel that does similar things to Filezilla and other FTP programs. Go into /sites/ and create directory cjm.net.au. While in /sites/, create directory unlevelhome.com.

Create directories /sites/cjm.net.au/files/ and /sites/unlevelhome.com/files/ with permission 777.

Copy /sites/default/default.settings.php to /sites/cjm.net.au/ and rename the file to settings.php then give it permission 777. Copy

/sites/default/default.settings.php to /sites/unlevelhome.com/ and rename the file to settings.php then give it permission 777.

Do you notice how you are repeating part of the original installation? Yeah, it gets boring if you have 2000 sites.

Visit http://cjm.net.au/ and up pops the Drupal 6 installation process, exactly the same as happened with petermoulding.biz. Answer the same questions. Use the right database name, database user name, and password.

Visit http://unlevelhome.com/ and up pops the Drupal 6 installation process, exactly the same as for petermoulding.biz and cjm.net.au.

Third site

Done! You could do ten at a time if you can keep track of all the passwords. Replace your Drupal Beginner t-shirt with the Drupal Do It In My

Sleep t-shirt.

Themes

Put standard themes in /sites/all/themes/ to let every site use the themes. Site specific custom themes go in a /themes/ directory within the site. A cjm theme would go in /sites/cjm.net.au/themes/ as /sites/cjm.net.au/themes/cjm/.

Modules

You have a separate database for every site so you can activate different modules for each site. Put the modules in /sites/all/modules/ then let each site switch them on or off.

Update notifications

Drupal automatically checks for code updates unless you turn off update notifications. You have only one copy of the code so switch off

46 of 183

2010-05-10 update notifications for all sites after the first.

Ok, darumaki pointed out the case where different sites use different modules. "This might be fine if every site was using the same modules, however, a typical multi-site setup usually involves each site using different modules, therefore, it should not be advised to turn off updates on the other sites, because updates only checks the modules that are enabled and not all the modules in the module directory." You could turn on every single module in your base domain, to get update notifications, or you could turn on updates in just those domains with something different.

The same consideration applies to themes because theme updates are detected and notified the same as module updates. The main saving from turning off updates is when you set up 3550 identical sites for the 3550 members of a professional association. They want separate databases for client privacy but they all get the same modules and features as specified by their association.

Maintenance

You have one copy of the code so put all the sites offline before updating the code. You have a database for every site so run update.php on every site before switching the sites back online.

Which site goes first?

The first site is locked in place while any other sites are parked on top. Use a throwaway site for the first site. When I registered petermoulding.com, I registered the .biz and some other variations for experiments. I used the .biz domain name as the base site for the multisite setup because the .biz domain name will not be visited by anyone but me. Each time I load a new theme into /sites/all/themes/, I can activate it in petermoulding.biz for testing. When one of the added on sites becomes to busy for the server, I can move the added on site without disturbing the other sites.

The first site is also the default site your customers will see when there is a setup failure in Drupal or Apache. Put contact information on the first site so people can report failed Web sites.

Cpanel interface

Cpanel provides several themes and each theme shows different combinations of buttons. I use crimson_smoke for these screen shots.

Domains

Go to the domains section to park your new domain, unlevelhome.com, to your existing domain, petermoulding.biz. Do not use Subdomain or

Addon domain for this part of the setup.

Subdomains

You add subdomains in the form x.example.com. For domain unlevelhome.com, you might add forums.unlevelhome.com and shop.unlevelhome.com. First you would park unlevelhome.com on petermoulding.biz and create unlevelhome.com in Drupal following the instructions on this page then you would look at adding forums and shop to unlevelhome.com. Adding subdomains should be covered in another page because there would be considerations around sharing user ids across the domains.

The following image shows the Cpanel subdomain page. You can add, edit, and delete subdomains. If you leave the document root field empty, the result will be similar to parking a domain and should let you use multisite. Multisiting forums.unlevelhome.com next to unlevelhome.com would require public_html/sites/forums.unlevelhome.com/settings.php, another database, and a way to share the login.

47 of 183

2010-05-10

Addon domains

Addon domains are similar to parked domains but add more complications. Do not use Addon domains for the procedure in this page, use

Parked domains.

The following image shows the Cpanel domain addon page. Notice the password field. Addon domains have a subaccount type arrangement you might use if you want to delegate administration to someone else. You could put several domains in one WHM account using separate subdirectories and give each site administrator separate FTP access. The separate FTP access does not work with multisite because they all share the same directories. Instead use Parked domains and control uploading of files using a Drupal module.

If you insist on using Addon domains instead of Parked domains then set Docuement root to public_html/. Drupal multisite is based on all page requests from all sites going to the same public_html/index.php.

Parked domains

You can park domain egjhnbhniu.com on example.com and Drupal can separate the two if they have separate multisite settings. You use

Parked domains without redirection. A request for egjhnbhniu.com/food/turnip goes to public_html/index.php then Drupal looks for

48 of 183

2010-05-10 public_html/sites/egjhnbhniu.com/settings.php and uses the database from the settings file. If public_html/sites/egjhnbhniu.com/settings.php

is missing, Drupal uses public_html/sites/defaults/settings.php and you see a page from example.com.

The following image shows the simple Cpanel domain parking page. It is simple because their are no passwords or document root settings.

This is all you need for multisite.

Redirects

A redirect sends one domain to somewhere on another domain. egjhnbhniu.com could be redirected to example.com/test-sites/egjhnbhniu/.

A common use is for personal Web sites. You create example.com/~george then, for your birthday, grandma buys george.com for you. You can redirect george.com to example.com/~george. When visitors visit george.com, they see example.com/~george so do not redirect, add george.com as a subdomain with a document root of ~george.

49 of 183

2010-05-10

Drupal in a subdirectory

When you install Drupal in /home/example/public_html/, unlevelhome.com is in /home/example/public_html/sites/unlevelhome.com/ and you access Drupal as http://unlevelhome.com/ . If you install Drupal in a subdirectory, for example /home/example/public_html/drupal-6.13/, you can access Drupal as http://unlevelhome.com/drupal-6.13/.

An alternative is to change the way you park the domain. Put /drupal-6.13 the Domain Root setting. Set Domain Root to

/public_html/drupal-6.13 and access Drupal as http://unlevelhome.com/ .

Drupal lookup documentation

There are lots of questions about the Drupal lookup sequence to get from a domain name to a settings.php file. The Drupal documentation is in INSTALL.txt under the heading MULTISITE CONFIGURATION. The following list is the lookup sequence from Drupal 6.12 INSTALL.txt for www.sub.example.com/site3 . Note that Drupal will not look in

sites/sub/settings.php

sites/site3/settings.php

sites/www.sub.example.com.site3/settings.php

sites/sub.example.com.site3/settings.php

sites/example.com.site3/settings.php

sites/www.sub.example.com/settings.php

sites/sub.example.com/settings.php

sites/example.com/settings.php

sites/default/settings.php

Attachment

cpanel-domains.png

cpanel-subdomains.png

Size

14.89 KB

12.98 KB cpanel-addon-domains.png

16.95 KB cpanel-parked-domains.png

14.3 KB cpanel-redirects.png

17.45 KB

Access all multisites with www. only [.htaccess]

The default .htaccess RewriteRule to redirect every multisite.com to www.multisite.com

does not work properly.

If you have problems with that too, just leave the two lines uncommented, and ADD THE FOLLOWING 3 LINES FOR EVERY MULTISITE you set up:

RewriteCond %{HTTP_HOST} mysite\.com$ [NC]

RewriteCond %{HTTP_HOST} !^www\.mysite\.com$ [NC]

RewriteRule ^(.*)$ http://www.mysite.com/$1 [L,R=301]

(Thanks to Florian!)

Drupal as a library

Short introduction on how to share drupal with all users on a shared server (without having troubles with file-permissions).

Note: it is still possible to use the Multisite option of drupal.

example server's file-structure:

/path/to/phplibraries/drupal (chmod 644)

/home/

user1/ (example.com)

lib (symbolic link => /path/to/phplibraries/)

public_html/

main/

files/

includes (symbolic link => /home/user1/lib/drupal/includes)

misc (symbolic link => /home/user1/lib/drupal/misc)

modules (symbolic link => /home/user1/lib/drupal/modules)

profiles (symbolic link => /home/user1/lib/drupal/profiles)

sites/

all (symbolic link => /home/user1/lib/drupal/sites/all)

default (symbolic link => /home/user1/lib/drupal/sites/default)

example.com/

settings.php

themes (symbolic link => /home/user1/lib/drupal/themes)

.htaccess (copy from drupal/.htaccess)

cron.php (copy from drupal/cron.php)

index.php (copy from drupal/index.php)

install.php (copy from drupal/install.php)

robots.txt (copy from drupal/robots.txt)

update.php (copy from drupal/update.php)

xmlrpc.php (copy from drupal/xmlrpc.php)

.htaccess (1)

user2/ (example2.com)

(same as user1)

50 of 183

2010-05-10

user3/ (example3.com)

(same as user1)

etc...

.htaccess (1)

this isn't neccessary but it keeps public_hml/ clean when several sites are maintained by one user. When only one site is maintained the contents of the main/ directory could be moved to public_html/ itself

Options +FollowSymLinks

DirectoryIndex index.php

RewriteEngine on

RewriteCond %{REQUEST_FILENAME} !-f

RewriteCond %{HTTP_HOST} ^example\.com$ [NC]

RewriteRule ^(.*) main/$1 [L,QSA]

</IfModule>

Installing virtual hosts for Drupal sites and subsites

The purpose of this guide is to concisely summarize how to implement apache vhost settings for each site or subsite.

All steps for this tutorial were implemented with Debian using Apache version 2.0.54.

1. Gain entrance into your shell system, and su to root or another user that can edit apache2 configuration files.

2. Go to your apache configuration files: cd /etc/apache2/sites-available

3. Create a configuration file for your new site. For an example site, www.example.com

, we make the site as such: nano example.com

ServerAdmin me@myserver

DocumentRoot /home/web/drupal/

ServerName www.example.com

ServerAlias example.com *.example.com

RewriteEngine On

RewriteOptions inherit

CustomLog /var/log/apache2/example.com.log combined

</VirtualHost>

ServerAdmin me@myserver

DocumentRoot /home/web/drupal/

ServerName www.example.com

ServerAlias example.com *.example.com

RewriteEngine On

RewriteOptions inherit

CustomLog /var/log/apache2/example.com.log combined

# SSL Specific options

SSLEngine on

SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL

SSLCertificateFile /etc/ssl/apache/CA.crt

SSLCertificateKeyFile /etc/ssl/apache/CA.key

SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown

</VirtualHost>

4. Activate the site's configuration: a2ensite www.example.com

5. Reload Apache's configuration:

/etc/init.d/apache2 force-reload

Done!

If you get an apache error '/home/www/drupal5/.htaccess: Option Indexes not allowed here'

Assuming that my apache2 DocumentRoot is at /home/www, and that drupal is linked to the doc root by ln -s /usr/share/drupal5 /home/www/ add the following to /etc/apache2/conf.d/drupal.conf

Options +FollowSymLinks Indexes

AllowOverride All order allow,deny allow from all

</Directory>

Multi-Site, Single Codebase, Shared Database, Shared Sign-on

5.x

This document is written with assumptions that you have: installed Drupal 5 before access to your server via ssh / telnet access to MySQL database / you can setup your own MySQL database

51 of 183

2010-05-10

In this example, I will setup two sites using:

Drupal 5

One database on MySQL

Linux-based server

Also:

Website’s url is: www.example.com

Drupal is installed in: /var/www/drupal

Names of sites are: ‘site_1’ and ‘site_2’

These sites will share session and user-related tables so once users login to one of the sites, they can view the other site without logging in.

User roles and profiles are also shared among the two sites. And to be clear, "shared sign on" means that when you created a user/pass on one site, it will work on the other site(s). It doesn't mean that you'll be automatically logged in to all sites at once (if that's what you want there are two modules to help: singlesignon and fierce_sso.)

1. Prepare database and database user

1.1. create a database and user

In this example, I will use:

DB name: drupal_db

DB username: druser

Password: twosites

Access right: SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES

2. create and modify site configuration

2.1. duplicate settings folder

Duplicate a folder contains site config information under drupal/sites/ dru@/var/www/drupal/sites: cp –R default/ www.example.com.site_1

dru@/var/www/drupal/sites: cp –R default/ www.example.com.site_2

2.2. Modify config files

2.2.1. provide DB connection detail

Open settings.php in a folder under www.example.com/site_1 . Go to line 93 (or somewhere around there) and you should find a line that goes:

$db_url = 'mysql://username:password@localhost/databasename'; change this line with your DB name, DB user and password. It will look like:

$db_url = 'mysql://druser:twosites@localhost/drupal_db';

2.2.2. set prefixes for table names

just below the line we just changed above, there is a line that goes like:

$db_prefix=’’;

Since we want to share a database among two sites but not completely, we decide which tables to share / not to share. This can be done by adding prefixes to table names. An example given below is for sharing user-related tables, sequences (this table is a ‘counter’ of users, nodes and other stuff) and session information.

$db_prefix = array(

'default' => 'site_1_',

'users' => 'shared_',

'sessions' => 'shared_',

'role' => 'shared_',

'authmap' => 'shared_',

'sequences' => 'shared_',

'profile_fields' => 'shared_',

'profile_values' => 'shared_',

'users_roles' => 'shared_',

); the second line that goes:

'default' => 'site_1_', this means tables that are not shared with other sites will have a prefix ‘site_1_’. So for example, table name ‘node’ will be ‘site_1_node’.

Now, when you finish editing this file, open and edit drupal/sites/www.example.com.site_2/settings.php. This time, you enter the exact same information for the database connection. So the line around 93 should look like:

52 of 183

2010-05-10

$db_url = 'mysql://druser:twosites@localhost/drupal_db';

Then, you add an array of prefixes, which will look like:

$db_prefix = array(

'default' => 'site_2_',

'users' => 'shared_',

'sessions' => 'shared_',

'role' => 'shared_',

'authmap' => 'shared_',

'sequences' => 'shared_',

'profile_fields' => 'shared_',

'profile_values' => 'shared_',

'users_roles' => 'shared_',

); notice a prefix in the second line is now ‘site_2_’. At the installation, all tables will have this prefix except for the ones that are specifically given a prefix ‘shared_’.

3. create static links

In order to access site_1 and site_2 from web browser, you have to make static links to drupal directory. In the directory /var/www, enter the following commands: ln -s drupal site_1 ln -s drupal site_2 now access ‘www.example.com/site_1’ (and ‘site_2’). If you see a drupalicon and a message like ‘Unable to select database’, go back to 2.2.1

of this manual and check if you have all details correct, including a single-quotation and semicolon.

If you see hundreds of messages like ‘Warning: Table 'continuu_test.access' doesn't exist’, you are almost there. While this may look scary or makes you think you have done something wrong, it is just saying that it cannot find tables Drupal needs to have access to. This is simply because we have not yet finished installing Drupal. All the necessary tables will be created in the next step, which is described below.

4. install drupal

Since we have entered information for database connection, we can run the install script (install.php) straight away, instead of giving all the detail to installation wizard. From your web browser, just access: http://www.example.com/site_1/install.php

http://www.example.com/site_2/install.php

Installation should complete within a second (or two). If you fail to install: read the error message and find out what is wrong (wrong DB name, username or password, etc.) make sure $db_url (around line 93 in settings.php) ends with a quotation mark and semicolon. ( ‘; )

If you have two separate Drupal sites and are thinking about merging them with above method, I would recommend you not to do it. Yes, it is not impossible. You can rename tables and modify values in sequence table and so on, but i tried it and had a hell of a hard time... If you have sites already setup, using CAS or other authentication services is more appropriate than merging.

Multi-Sites Using XAMPP on Windows XP

This procedure allows you to create multiple sites sharing one common set of Drupal core modules, and has been tested on Windows XP

(SP2), Apache 2.2.3, MySQL 5.0.24a, PHP 5.1.6, Drupal 5.2..... I'm assuming that you have a working Drupal installation already. Please

note that this hasn't been tested with XAMPP 1.7.1 (MySQL 5.0.51a, PHP 5.2.9 Apache 2.2.11) and Drupal 6.x!

1. Create a new MySQL database with appropriate rights.

eg. mydb

2. Create a new folder in your sites folder by copying the default folder and then renaming it with the name of your new site.

eg. mysite

3. Create the following sub-folders in the above folder for stuff unique to your new site.

mysite\files mysite\modules mysite\themes mysite\tmp

4. Edit the database and base URL in the settings.php file in the folder you have just renamed.

$db_url = 'mysql://username:password@localhost/mydb';

$base_url = 'http://mysite'; // NO trailing slash!

5. Create a new host in the Windows XP hosts file with same name as new folder.

127.0.0.1 mysite

53 of 183

2010-05-10

6. Create a new Virtual Host in the Apache httpd-vhost.conf file with forward slashes in the full pathname (include <> tags as per the examples in the file).

VirtualHost *:80

DocumentRoot "C:/Program Files/xampp/htdocs/drupal"

ServerName mysite

VirtualHost

7. Restart the Apache server to load the virtual hosts.

8. Point your web browser at new folder and install Drupal.

http://mysite/install.php

9. Create your first user and Administer the File System paths to match step three above.

sites/mysite/files sites/mysite/tmp

You can use the Windows Search to find the above files if your not familiar with their locations.

Good luck!

Multi-site setup using CPanel

After some searching around, I found out how to do multi-site setup using CPanel.

1. Create your initial Drupal site at www.example.com

. Drupal 5.x makes this very easy to do, as it will automatically install the database for you -- all you have to do is input the database information.

2. Create a folder in the sites/ folder that matches the subdomain you want to create (so for site1.example.com, the folder name would be site1.example.com).

3. Duplicate the settings.php file from the default folder and place it in your newly created folder from step 2.

4. Edit the settings.php file you just placed in the site1.example.com folder so that it does not point to a database. You can replace the line that has your other site's database information with this:

$db_url = 'mysql://username:password@localhost/databasename';

This will allow step 9 below to load your database tables.

5. In CPanel, set up the subdomain. For the above example of site1.example.com, a folder named site1 will be automatically created by

CPanel.

6. Delete the folder that was created.

7. Use the following example to create and upload a php file onto your site. An easy way to do this is to use Notepad, pasting in the text below, editing as necessary, and then saving as multisite.php. Afterwards, upload via FTP or CPanel's File Manager. Make sure you change the path to whatever the path to your web root is.

<?php

symlink ( '/home/username/public_html/' , 'site1' );

8. Go to the location of the php file in your browser (such as www.example.com/multisite.php

)

This will create a symlink, allowing your subdomain to work properly.

9. Go to your subdomain. Drupal will ask for your database information and then install the tables necessary to run the new site.

10. You're all set to use the new site.

If you run into any problems, or have questions, use the contact form attached to my user account here to contact me.

truly simple cPanel multsite setup

No single multisite setup method above got me all the way there; if you have cPanel and Drupal installed on your original domain, follow these straightforward instructions to set up a multisite:

For 'www.yourlovelysite.com':

1. in cPanel, go to 'Subdomains'

2. enter a name for you subdomain; this is followed by '.' and your original domain name automatically, e.g. 'sub1' becomes

'sub1.yourlovelysite.com'.

3. enter a 'Document Root'; this needs to point to the folder in your directory containing the 'index.php' file that a Drupal installation creates,

54 of 183

2010-05-10 e.g. 'public_html', and Create. Please note cPanel may automatically insert "public_html/sub1" - delete "sub1".

4. in cPanel, go to 'MySQL Databases'.

5. name a new database and 'Create Database'.

6. scroll down to 'MySQL Users' and 'Add New User' - and insert a username and password (twice) - give the user all privileges. Make a note of username/password.

7. in 'Add User to Database', associate your new username with the name of the database just created.

8. in cPanel, go to 'File Manager' - though this can be done using Dreamweaver or other ftp software - create a new folder in the 'sites' folder, which is in the root of the Drupal installation, named after your subdomain, e.g. 'sub1.yourlovelysite.com'.

9. copy the file 'settings.php' from the 'sites/default' folder, which you should have already from your original Drupal install, and paste it into your new subdomain folder 'sub1.yourlovelysite.com'.

10. grant this new 'settings.php' all permissions.

11. open 'settings.php' and locate the line "$db_url = 'mysql://username:password@localhost/databasename';".

12. replace each 'variable' with the respective thing, e.g. $db_url =

'mysql://newdatabaseusername:newdatabasepassword@localhost/newdatabasename'; and save.

13. now you have a database for your new subdomain which you access using 'settings.php' in your new subdomain folder.

14. go to 'sub1.yourlovelysite.com/install.php' and follow the familiar steps for a Drupal installation.

That should do it.

You can repeat this method over and over: sub2, sub3... and so on.

Important:

When you upload files/images to your subdomain, by default, Drupal will place that file in 'sites/default/files'. To organise and to avoid your subdomains overwriting each others' files, change the 'file system path' in 'Administer > Site configuration > File system' to something like:

'sites/sub1.yourlovelysite.com/files'. This should be remembered/reversed if the subdomain is ever moved to its own site, otherwise your pictures will disappear as Drupal is looking in the wrong place for them.

Multiple domains or vhosts using different databases

Apache supports both IP- and name-based virtual hosts (vhosts). While running more than one engine (by using vhosts) can be very useful for development and testing purpose, it is most useful for hosting companies. Therefore, we support vhosts in the best possible way in order to make the life of all administrators easier. We do so by making it possible to run an unlimited number of vhosts on the same physical source tree, through using different configuration files. Moreover, you can setup multiple configuration files in your includes-directory.

$ ls -l sites/*/*.php

-rw-rw-r-- 1 drupal drupal sites/www.example1.com/settings.php

-rw-rw-r-- 1 drupal drupal sites/www.example2.com/settings.php

The only thing left to do is to set up the corresponding vhosts in your Apache configuration file. Note that the DocumentRoot points to the same source tree twice:

NameVirtualHost 127.0.0.1

DocumentRoot /home/www/drupal

ServerName www.example1.com

DocumentRoot /home/www/drupal

ServerName www.example2.com

Remember that, as of Drupal 4.6, you can have site specific modules and themes as well. Just create a directory under the sites/www.example1.com called 'modules' and place the site specific modules in it. The same applies to themes as well.

Consult the INSTALL.txt that came with your Drupal installation for more details.

Note that the same effect can be accomplished without further editing httpd.conf if Apache's default virtual server has the Drupal directory as its document root.

Sharing Drupal tables between databases using MySQL5 Views

Problem: You'd like to share some data between two different drupal websites without changing any Drupal code or otherwise having to lift much of a finger. But you don't want to share information unless it meets certain requirements (for example, only users labeled "foo" in somedatabase.sometable) For our example, we'll use the users table.

Solution: Use MySQL5 Views ( http://dev.mysql.com/doc/refman/5.0/en/views.html

)

Our "master" users table resides in a database called "master". The database of the site that will have restricted access to our masters users table is called "banana". Assumming you're starting with a fresh instance of the Drupal schema in your database "banana", do this:

55 of 183

2010-05-10 mysql> use banana; mysql> drop table users; mysql> CREATE VIEW users AS mysql> SELECT * mysql> FROM master.users mysql> WHERE uid IN ( mysql> SELECT uid mysql> FROM somedatabase.sometable

mysql> WHERE uid = 0 mysql> OR label = 'foo' mysql> )

Drupal will use banana.users just as it would a normal users table. No other modifications are necessary. Now only "foo" users will be included in the users table for your banana website.

Note: Drupal has a dependency that is not really documented. Every users table must have an entry that contains uid=0. It's a "stub" entry that Drupal needs to function properly. A workaround for this dependency is to include "user 0" in the results set that defines your view.

See, wasn't that easy?

Multiple domains using the same database

If you want to host multiple domains (or subdomains) on top of the same database (e.g. http://example.com/ and http://www.example.com/ ), simply use symbolic links to setup the required configuration files:

$ ln -s sites/example.com sites/www.example.com

$ ls -l sites

-rw-rw-r-- 1 drupal drupal sites/example.com

lrwxrwxrrx 1 drupal drupal sites/www.example.com -> sites/example.com

If your installation isn't in the root folder then you need to specify the path to the Drupal installation. For example if the URL to your installation is http://www.example.com/drupal/ you would use sites/www.example.com.drupal with a settings.php file in it.

If you want cookies to be shared between two sites, you will need to set the value of PHP's session.cookie_domain correctly. In the case above, set it to ".example.com". You can do this through Drupal's .htaccess file.

Multisite setup using a single Drupal instance

Note

The downside of the following technique is that no two host can share the same IP and different SSL certificates for secure login. This opens up vulnerabilities to your drupal installation.

Multi-site/Single Instance

This article is intended for administrators who want to set up multiple sites (perhaps for multiple clients) running on a single Drupal installation. The goal is to keep everyone's site separate (different themes, content, enabled modules etc...) while sharing a single Drupal codebase.

I won't go into full details on how to install Drupal in a shared hosting environment, there are several other articles you can reference on that topic, although knowing the following is helpful:

You will need to setup a new MySql database noting its name. That database should be assigned a user who has full privileges. Make sure you have the username/password for the DB user handy.

Under the root/sites/default directory is a file called default.settings.php. This file must be re-named to settings.php and placed on the server and made writable.

Certain PHP functions may need to be turned on or off (When running the install script the first time it should provide this information)

Since many shared hosts run CPanel you should be able to take advantage of php.ini Quick Config a nice non threatening web interface that is easier to modify compared to adding a php.ini file with custom overrides or doing the same with your .htaccess file.

Although not required, I would recommend that your Drupal implimentation be installed on your primary domain so that it is placed in the html root (i.e. /public_html/). I'll explain how this can make your life easier in a bit.

We will assume that you have successfully installed and tested your Drupal installation. Lets assume it is named www.myDupalSite.com

. Now it's time to create another site by following these steps:

Make sure that www.mysecondsite.com

is parked on your server. By default (at least in CPanel) it will point to your root html directory which is exactly what we want.

Assuming the parked domain has propagated typing in www.mysecondsite.com

at this point should show you your drupal implimentation at www.myDupalSite.com

Create a new MySQL database to house the second sites content and information.

Assign a database user (with full permissions) creating this account if necessary. You may use the same master user account for all

Drupal databases if desired.

Create a directory for root/sites/mysecondsite.com

Copy the settings.php file in your root/sites/default directory to your root/sites/mysecondsite.com directory. Make sure it has the appropriate file permissions

56 of 183

2010-05-10

Open the file and modify the database (and database user) settings to point to your second web sites database

Now you can go to http://www.mysecondsite.com/update.php

and run through the implimentation to populate your new Drupal site database.

Congratulations you should now have 2 separate websites capable of using different themes and with different content running on a single

Drupal instance.

Some good things to be aware of regarding multi-site implementations:

If it is appropriate for all modules and themes to be shared with all sites then you can disable update checking on all but your primary

Drupal implimentation (which should have all modules enabled). In instances where some sites may have exclusive access to themes and/or modules you don't wish to make generally available you may need to enable update checking for those sites.

Themes that you wish to be made available to all sites should be placed in /sites/all/themes/theme_name/. A Theme that should be made available to a specific sites (i.e. mysecondsite.com) should be placed in root/sites/mysecondsite.com/themes/theme_name/

Availability of modules is similar to themes. Utilize root/sites/all/modules when you want a module to be available to all Drupal instances (each instance can choose to enable or disable the module).

Although you are running a single instance of Drupal you have multiple databases that may need to be updated when a new version comes out. Please make sure to disable your sites and run the update.php file once for each site before re-enabling sites when finished.

Same codebase, completely different content and users

This document assumes the following:

You want to create more than one Drupal site using the same codebase (the same basic set of Drupal files, uploaded into one location).

You know how to install mysql tables in your database.

You know how to set up subdomains/folders/other domains that you want to use.

You have already downloaded Drupal 4.7, and set up one MAIN site.

This document contains instructions on how to create completely separate Drupal site, with different configurations, users and content. Nothing is shared between the installations except the codebase.

Some definitions:

codebase: the basic set of Drupal files, included in the .tar.gz

file. the stuff that makes Drupal work.

database: a collection of

tables

that stores data.

Affected files: settings.php (sites/default/...) database.mysql

For this example, we will assume the following: www.example.com: the MAIN site, where the codebase has already been uploaded, and settings.php has been properly configured.

sub1.example.com; www.example.com/sub2; www.subexample.com

: the other sites we will create.

1. Create the following folders in your sites directory: sites/sub1.example.com/ sites/www.example.com.sub2/ sites/www.sub3example.com/

Copy the settings.php file from sites/default into each of the above folders.

2. There are different database files (inside the database folder). Select the one that is appropriate for your database version. Copy it to each of the folders you made in step 1. This is OPTIONAL, but it will help you keep things straight.

3. Decide on SEPARATE PREFIXES for each site. Below is what we will use for the example:

site

sub1.example.com

www.example.com,sub2

database prefix

sub1_ sub2_

57 of 183

2010-05-10 www.sub3example.com

sub3_

4. Configure your settings.php for each site.

This code MUST BE CHANGED FOR EACH SITE:

$db_url = 'mysql://username:password@localhost/databasename';

Note; if you are using the same database as the MAIN site, the $db_url is the same.

OPTIONAL:

# $base_url = 'http://www.example.com'; // NO trailing slash!

# $conf = array(

# 'site_name' => 'My Drupal site',

# 'theme_default' => 'pushbutton',

# 'anonymous' => 'Visitor'

# );

For sub1.example.com, the settings would be:

$db_prefix = 'sub1_';

$base_url = 'http://sub1.example.com';

$conf = array(

'site_name' => 'My SUB1 Drupal Site',

'theme_default' => 'pushbutton',

'anonymous' => 'Visitor'

);

For www.example.com/sub2 , the settings would be:

$db_prefix = 'sub2_';

$base_url = 'http://www.example.com/sub2';

$conf = array(

'site_name' => 'My SUB2 Drupal Site',

'theme_default' => 'fancy',

'anonymous' => 'Anonymous'

);

For www.sub3example.com

, the settings would be:

$db_prefix = 'sub3_';

$base_url = 'http://www.sub3example.com';

$conf = array(

'site_name' => 'My SUB3 Drupal Site',

'theme_default' => 'marvin',

'anonymous' => 'Guests'

);

6. Upload the modified settings.php files in their respective folders.

7. Open the database file you copied into each sites folder. Find the following (don't forget the SPACE at the end!!!):

CREATE TABLE

INSERT INTO

Replace each 'create table' and 'insert into' with 'create table dbprefix_' and 'insert into dbprefix_'

For sub1.example.com:

CREATE TABLE >> CREATE TABLE sub1_

INSERT INTO >> INSERT INTO sub1_

8. Upload the modified mysql files into the database you specified in your settings.php.

9. Voila!

Setting up multi-site Drupal 5 on Windows or Linux consolidated instructions

We will assume you want to make a local installation on a Windows PC and an installation reachable via the Internet on a Linux server.

58 of 183

2010-05-10

Hosts file

You will find the hosts file at the following locations:

- on Windows: c:\windows\system32\drivers\etc\hosts

- on Linux: /etc/hosts

In these instructions, we will assume you want to install a number of sites at:

On Windows (local): strawberry.loc and blueberry.site

On Linux (Internet): yourdomain.com and blueberry.com

The hosts file will look as follows for the Windows example:

127.0.0.1 localhost

127.0.0.1 strawberry.loc

127.0.0.1 blueberry.site blueberry

For a Linux internet server the hosts file should look as follows: ipaddress yourhostname.yourdomain.com yourhostname

127.0.0.1 localhost

127.0.0.1 blueberry.site blueberry

DNS

Apache

Configure Apache for all the different domain names that your web server will be serving.

For Linux (our examples use paths for SuSE Linux > 10.0) the best place to do this is in the vhosts.conf

file in the

/etc/apache2/vhosts.d

The entries can also be placed in the

/etc/apache2/httpd.conf

file initially to keep things simple. Later it is better to do it in the vhosts.conf

file - this way, in case of an update of the Apache software, if the httpd.conf

file is overwritten, your configuration will survive.

For Windows, you can get Apache, MySQL and PHP from: http://www.apachefriends.org/en/xampp-windows.html

If you installed XAMPP in the default directory on Windows, the vhosts file will be at: c:\program files\xampp\apache\conf\extra\httpd-vhosts.conf

The entries can also be placed in the c:\program files\xampp\apache\conf\httpd.conf

file initially to keep things simple.

On Linux (the paths in the example are for SuSE Linux), your follows: vhosts.conf

file (or entries at the end of the httpd.conf

file) should look as

# First entry of this file should be the NameVirtualHost entry, unless it is already there

# If you want your web server to respond on a different port from the default

# replace 80 with that port number

# Available alternative port numbers are 8080 and 2222

NameVirtualHost *:80

# For each domain you want to serve up with Drupal,

# you need an entry that will match the incoming domain

# You do not need a separate entry for each subdomain - Drupal takes care of that

# The following entry takes care of :

# yourdomain.com

# www.yourdomain.com

# bla.yourdomain.com

# gaga.yourdomain.com

# etc.

# In the following we assume that the Apache htdocs directory is at /srv/www/htdocs

# and that Drupal has been installed in /srv/www/htdocs/drupal

DocumentRoot /srv/www/htdocs/drupal

ServerName yourdomain.com

ServerAlias *.yourdomain.com

59 of 183

2010-05-10

Allow from all

Options +Includes +Indexes +FollowSymLinks

AllowOverride all

</Directory>

</VirtualHost>

# The following entry takes care of :

# blueberry.com

# www.blueberry.com

# bla.blueberry.com

# gaga.blueberry.com

# etc.

# In the following we assume that the Apache htdocs directory is at /srv/www/htdocs

# and that Drupal has been installed in /srv/www/htdocs/drupal

DocumentRoot /srv/www/htdocs/drupal

ServerName blueberry.com

ServerAlias *.blueberry.com

Allow from all

Options +Includes +Indexes +FollowSymLinks

AllowOverride all

</Directory>

</VirtualHost>

# On Linux, you will also need an entry to ensure that your phpMyAdmin works

# - you will need phpMyAdmin to set up and manage your MySQL databases

# I assume here that you have unpacked and copied the phpMyAdmin files to

# /srv/www/htdocs/phpMyAdmin

# Please note that in the following, the DocumentRoot and Directory command

# both need to use phpMyAdmin

# using phpmyadmin doesn't work even though phpmyadmin

# is a symbolic link to phpMyAdmin

ServerName phpmyadmin.yourdomain.com

DocumentRoot /srv/www/htdocs/phpMyAdmin

allow from all

Options +Indexes +Includes +FollowSymLinks

AllowOverride FileInfo Options

</Directory>

</VirtualHost>

For the local Windows example, your httpd-vhosts.conf

file (or entries at the end of the httpd.conf

file) should look as follows:

# First entry of this file should be the NameVirtualHost entry, unless it is already there

# If you want your web server to respond on a different port from the default

# replace 80 with that port number

# Available alternative port numbers are 8080 and 2222

NameVirtualHost *:80

# For each domain you want to serve up with Drupal,

# you need an entry that will match the incoming domain

# You do not need a separate entry for each subdomain - Drupal takes care of that

# The following entry takes care of e.g:

# strawberry.loc

# www.strawberry.loc

# bla.strawberry.loc

# gaga.strawberry.loc

# etc.

# In the following we assume that the Apache htdocs directory is at

# c:/program files/xampp/htdocs

# and that Drupal has been installed in c:/program files/xampp/htdocs/drupal

DocumentRoot "c:/program files/xampp/htdocs/drupal"

ServerName strawberry.loc

ServerAlias *.yourdomain.com

Allow from all

Options +Includes +Indexes +FollowSymLinks

AllowOverride all

</Directory>

</VirtualHost>

# The following entry takes care of e.g:

# blueberry.site

# www.blueberry.site

# bla.blueberry.site

# gaga.blueberry.site

# etc.

# In the following we assume that the Apache htdocs directory is at

# c:/program files/xampp/htdocs

# and that Drupal has been installed in c:/program files/xampp/htdocs/drupal

DocumentRoot "c:/program files/xampp/htdocs/drupal"

ServerName blueberry.site

ServerAlias *.blueberry.site

Allow from all

Options +Includes +Indexes +FollowSymLinks

AllowOverride all

</Directory>

60 of 183

2010-05-10

</VirtualHost>

It seems that the first entry in vhosts.conf becomes the default Apache server, whereas the last entry in httpd.conf

becomes the default.

On Windows, you get to phpMyAdmin by pointing your browser to http://localhost/phpmyadmin , if it is installed in the default location under the xampp directory.

Drupal

Make sure that the settings.php

file in

/srv/www/htdocs/drupal/sites/default on Linux or

c:\program files\xampp\htdocs\drupal\sites\default on Windows is the default file that came with the Drupal distribution. Now point your browser to http://yourdomain.com

and you will see the Drupal install screen which will walk you through the installation for the site http://yourdomain.com

It will ask you for

- the name of the MySQL database

- the database user and password, and

- ask you to set up the first user who will become the administrator of the site.

It is IMPORTANT that the you use this original settings.php file, OR ELSE the Drupal install procedure DOES NOT WORK when you go to http://yourdomain.com

. The reason for this is that if you use an existing installations settings.php

file, Drupal thinks the site is already configured and DOES NOT start the one time start up installation.

Do the same for any other domains you intend to use and have configured in Apache.

Independent Site at a subdomain

To have http://bla.yourdomain.com

(Linux example) or http://bla.strawberry.loc

(Windows local) be a different Drupal site, create a directory called:

/srv/www/htdocs/drupal/sites/bla.yourdomain.com on Linux or

c:\program files\xampp\htdocs\drupal\sites\bla.stawberry.loc on Windows and copy the default settings.php

file that came with the Drupal distribution into the above directory.

on Linux hosting server or http://bla.strawberry.loc

on your Windows server to start the installation. Again, It will ask you:

- for the name of the MySQL database

- for the database user and password, and

- to set up the first user who will become the administrator of the site.

Repeat the above for any other sub-domains you want to configure such as http://hello.blueberry.site

on Windows.

Independent site at a sub URL

To set up a separate Drupal site at http://www.yourdomain.com/gugu create a directory called

/srv/www/htdocs/drupal/sites/www.yourdomain.com.gugu

c:\program files\xampp\htdocs\drupal\sites\www.stawberry.loc.gugu on Windows and copy the default settings.php

file that came with the Drupal distribution into the above directory.

- for the name of the MySQL database

- for the database user and password, and

- to set up the first user who will become the administrator of the site.

Mechanism for setting up sub-domain and sub-directory/sub-URL sites

For details on how Drupal uses the sites directory structure, read the

INSTALL.txt

file in the top level drupal directory. Here is the relevant excerpt:

MULTISITE CONFIGURATION

61 of 183

2010-05-10

A single Drupal installation can host several Drupal-powered sites, each with its own individual configuration.

could be in 'sites/example.com/settings.php' (note that 'www.' should be omitted if users can access your site at http://example.com/ ).

sites/example.com/settings.php

sites/sub.example.com/settings.php

sites/sub.example.com.site3/settings.php

When searching for a site configuration (for example www.sub.example.com/site3 ),

Drupal will search for configuration files in the following order, using the first configuration it finds: sites/www.sub.example.com.site3/settings.php

sites/sub.example.com.site3/settings.php

sites/example.com.site3/settings.php

sites/www.sub.example.com/settings.php

sites/sub.example.com/settings.php

sites/example.com/settings.php

sites/default/settings.php

Each site configuration can have its own site-specific modules and themes in addition to those installed in the standard 'modules'and 'themes' directories.

themes/custom_theme modules/custom_module

NOTE: for more information about multiple virtual hosts or the configuration settings, consult the Drupal handbook at drupal.org.

Permissions

These can also be configured somewhere in Apache. For other Linux distributions, find out as what user and group Apache runs as and where the htdocs Apache web server root directory is.

Nothing further can stand in the way of your Drupal development - enjoy.

Setup of /sites directory for multi-site

Drupal's multi-site hosting capability is built in with any installation. This is great news for users who run numerous web sites from a single hosting account. A

single

Drupal installation can be used to run multiple domains, which makes it much easier to manage and maintain the code base. Even if you are dealing with only one domain, the multi-site capability may be valuable by providing the ability to run a separate domain or sub-domain for a development version.

This page describes the set-up of the /sites directory for multi-sites.

62 of 183

2010-05-10

With version 5.x, the intended location for all non-core elements of a Drupal installation is in a separate /sites directory inside the Drupal installation.

Directory

/drupal/sites/all

Contents

/modules

/themes

(used by all sites)

/drupal/sites/default

(used when there is no /sites/example.com directory)

/files settings.php

/drupal/sites/example1.com

/drupal/sites/example2.com

/files

/modules

/themes

/tmp settings.php

/files

/modules

/themes

/tmp settings.php

The intended best practice configuration is to create a /sites/example.com directory for each domain. It should contain a site-specific settings.php file and /files directory. Configure Drupal site settings to specify 'File System Directory' of 'sites/example.com/files' instead of the default 'files'. It's possible to do this with an existing web site, but moving file uploads around can cause a lot of confusion if there are already URLs pointing to the old locations.

Domain specific modules and themes should also be placed in /sites/example.com/modules and /sites/example.com/themes respectively.

Contributed modules and additional themes which are for use by all domains in a multi-site installation should be placed in /sites/all/modules and /sites/all/themes. Note that there shouldn't be a /sites/all/files or /sites/all/settings.php.

The /sites/default directory should contain /files and settings.php, for use if the /sites/example.com directory doesn't exist for a domain.

In addition to multiple sites, such as example1.com and example2.com, sub domains are also easily set up. Adding sub3.example2.com and sub3.example2.com/site4, the directory structure for these four sites would be:

/drupal/sites/all/modules

/drupal/sites/all/themes

/drupal/sites/default/files

/drupal/sites/default/settings.php

/drupal/sites/example1.com/files

/drupal/sites/example1.com/modules

/drupal/sites/example1.com/settings.php

/drupal/sites/example1.com/themes

/drupal/sites/example1.com/tmp

/drupal/sites/example2.com/files

/drupal/sites/example2.com/modules

/drupal/sites/example2.com/themes

/drupal/sites/example2.com/tmp

/drupal/sites/example2.com/settings.php

/drupal/sites/sub3.example2.com/files

/drupal/sites/sub3.example2.com/modules

/drupal/sites/sub3.example2.com/settings.php

/drupal/sites/sub3.example2.com/themes

/drupal/sites/sub3.example2.com/tmp

/drupal/sites/sub3.example2.com.site4/files

/drupal/sites/sub3.example2.com.site4/modules

/drupal/sites/sub3.example2.com.site4/settings.php

/drupal/sites/sub3.example2.com.site4/themes

/drupal/sites/sub3.example2.com.site4/tmp

Note that Drupal reconizes www.example.com

as a sub-domain of example.com.

If you wish to point both of them to the same site, use

/drupal/sites/example.com/

option in your .htaccess

as your directory, and uncomment the corresponding

Once you've done this, the file structure of your site will be cleanly organized:

The main Drupal directory will contain only the standard 'core' files.

Themes and modules that are shared among

all

sites are properly placed in /sites/all

Site-specific themes, modules, and files are compartmentalized and properly placed in /sites/example.com, /sites/example1.com,

/sites/sub3.example2.com and /sites/sub3.example2.com.site4 .

/sites/default/settings.php and /sites/default/files will be used if /sites/example.com directory does not exist.

Backing up the /sites directory and your Drupal database will give you everything you need to restore the site in the event of a crash, or to move to a new server.

Adding a domain is easy: just copy the /sites/default directory to /sites/example5.com

To help keep files organized you may choose to use shortcuts to point relevant files and directories that are stored elsewhere in your Drupal installation. These short-cuts (like a desktop "alias") are referred to as "symbolic links" on a Web server. Symbolic links can be used for several purposes:

Even if using default settings, a good option is to use links from /sites/example.com directory to point to the /sites/default directory.

That way, if the settings and /files are ever changed from the default and actually placed in /sites/example.com, their location does not

63 of 183

2010-05-10

'move' and no links are broken.

Links could also be used to point the /sites/default directory to your primary site.

A /files directory could easily be shared across two domains without being shared across the remaining domains.

A non-domain-name path for /files can be setup. If it is possible that the domain name might change (say, from a development name), then you can set up a link from /drupal/sites/moniker to /drupal/sites/example.com, where 'moniker' is a short version of the site name that will remain constant even if /example.com changes.

If you are working from the command line on a Linux, Unix or OSX server you can create a symbolic link using the following command:

$ ln -s /path/to/actual/file/or/directory name_of_shortcut

Although the /sites/default directory

/sites/example.com. Similarly, although contributed modules recommended.

could

contain a /modules and /themes directory, these elements should usually be placed in /sites/all or

could

be placed in /drupal/modules as was the practice in version 4.7, this is not

Multi-site directory setup for sub-domains, including non-standard ports, is described in the installation instructions found in INSTALL.txt.

See multidomain for a contributed module that allows spanning one site across multiple domains, so that specific content types appear on specific domains or sub-domains.

Version 4.6 and 4.7: Best practice for multi-site set-up under version 4.6 and 4.7 is similar to 5.x. The primary difference is that there is no /sites/all directory. Instead, /modules and /themes that are available for all domains are kept in /drupal/modules and /drupal/themes.

Files Directory

The following user-submitted code may be useful in redirecting URLs for the /files directory to the /sites/example.com/files directory. The following code is added to the [drupal_root]/files/.htaccess file:

RewriteEngine On

RewriteCond %{REQUEST_FILENAME} !-f

RewriteCond %{REQUEST_FILENAME} !-d

RewriteRule ^(.*)$ /sites/%{HTTP_HOST}/files/$1 [L]

If the .htaccess method doesn't work, try this user-contributed code for use in settings.php, instead of .htaccess.

In settings.php, put this code:

<?php

$conf [ 'file_directory_temp' ] = 'sites/' .

substr ( strrchr ( dirname ( __FILE__ ), '/' ), 1 ) .

'tmp' ;

$conf [ 'file_directory_path' ] = 'sites/' .

substr ( strrchr ( dirname ( __FILE__ ), '/' ), 1 ) .

'/files' ;

Video about Multisite optimization

Here is a video I'm contributing about configuring a Multisite Drupal install within an Apache server environment.

It provides a number of tips related to optimizing the httpd.conf file for better security on files such as install.php, cron.php and update.php.

It also provides tips on managing the multisite configuration by using a dedicated drupal.conf file and controlling access to sensitive areas of the site (like

/admin

) using an ip.conf file.

One other valuable tip is temporarily using the apache directive DirectoryIndex (while updating drupal) to point all sites managed in the multisite install to a different index page (such as offline.php) so you don't have to go into every site and turn on maintenance mode (which can be a pain).

Share a single database across multiple sites

Some web hosts limit their customers to one database. Thus, no duplicate table names are possible. In order to assure that these admins can still use Drupal, and even use multiple installations of Drupal, Drupal offers

table prefixing

In order to use this feature, you must currently edit the script choice. If you are adding contributed modules you will need to also modify INSERT and REPLACE statements to have a prefix as well. For example, change all statements from the format of database/database.x

in order to create tables prefixed by the string of your

CREATE TABLE access

INSERT INTO system VALUES ('modules/filter.module','filter','module','',1,0,0);

Becomes,

CREATE TABLE dr1_access

INSERT INTO dr1_system VALUES ('modules/filter.module','filter','module','',1,0,0);

Then use

dr1_

(for example) as value of $db_prefix in your sites/example.com/settings.php

file.

You can also use the prefix.sh in the scripts subdirectory of your Drupal install to do this automatically. You can then update several sites in one swoop with a (bash shell) command-line like for F in '' prefix1 prefix2; do \

for S in `find ./modules --name \*mysql`; do \

scripts/dbprefix.sh $F < $S | grep -v DROP |\

mysql -h DBHOST -u DBUSER -pPASSWD DATABASE; \

done;

done

64 of 183

2010-05-10

NOTE:that not all scripts end in mysql, but you get the idea; the '' prefix tells the script to run with no prefix at all, ie a straight command that just lets me process all my sites together.

cat -

Here is a PHP script that creates all of the database tables for all sites in /drupal/sites/*. It works for DRUPAL-4-6. See the Database Table

Creation script issue for more info.

If you want to share users across multiple sites, you'll need to use a $db_prefix along these lines:

<?php

$db_prefix = array(

'default' => 'thissite_' ,

'authmap' => 'shared_' ,

'profile_fields' => 'shared_' ,

'profile_values' => 'shared_' ,

'role' => 'shared_' ,

'sequences' => 'shared_' ,

'sessions' => 'shared_' ,

'users' => 'shared_' ,

'users_roles' => 'shared_' ,

'users_uid_seq' => 'shared_' , // for pgsql

);

See the sharing tables and sharing tables across databases sections.

Share tables across instances (not recommended)

Please note: This procedure could result in unexpected results, depending on which tables you choose to share, including broken version updates and/or security holes.

For instance, if one site is compromised, an attacker could compromise the shared database tables and compromise your other sites. Think about both the settings to be shared and be aware of the risks involved. You can, however, host multiple sites in the same database (with no shared tables) by using site-wide table prefixes.

By using table prefixes on some tables but not others, you can cause multiple Drupal installations to share a set of common tables. One interesting application for this is to share the taxonomy tables (vocabularies, term_data). Another interesting use is to share

Drupal installations.

users

across

In order to use this capability, create two drupal installs in same DB using different database prefixes. In this example, one is prefixed

'master_' and the other 'slave1_'. Then edit the settings.php file of 'slave1_' so that it points some tables to the 'master_'. For sharing users, add the following:

$db_prefix = array(

"default" => "slave1_", // the prefix for tables that are not shared.

"users" => "master_",

"sessions" => "master_",

"authmap" => "master_",

"sequences" => "master_",

"profile_fields" => "master_",

"profile_values" => "master_",

);

Note: The actual tables that you will share depends on your installation.

However, the following tables contain data that is highly site specific and therefore should not be shared: cache variable

There is a limitation in that you can only explicitly specify which tables will be shared and not the other way round. The following may fail

(however a recently deleted comment on this page by marcob suggests this has been fixed:

$db_prefix = array(

// Be careful of this setup.

'default' => 'primary_',

'cache' => 'slave1_',

'node' => 'slave1_',

'system' => 'slave1_',

// etc...

);

Setup tip for Drupal 5

For Drupal 5+, an easy way to get started with table sharing across instances is to run the installer twice using the same database - it will create the prefixed tables and handle all the initial INSERTS (as with the 'system' and 'menu' tables, etc) for all your different prefixes.

Using schema prefixes with PostgreSQL

This page discusses usage of PostgreSQL schemas for prefixes. "Normal" prefixes can be used in the same way as in MySQL, so they won't be discussed here.

PostgreSQL has something called 'schemas' ( http://www.postgresql.org/docs/current/static/ddl-schemas.html

). They can be very handy sometimes, but if you don't know what they are, you probably don't actually need them and can stop reading here.

65 of 183

2010-05-10

Schemas can be used as prefixes within Drupal. That is, with a multisite setup, each site can reside in its own schema, and shared tables can reside in a "shared" schema (or even in the public schema).

There is one annoyance: the upgrade will fail. This is unfortunate, but nothing can be done as the "normal" (not schema) and schema prefixes are just incompatibile. If you are interested in the details, please see http://drupal.org/node/40034 .

But, don't worry. This can be easily fixed by changing the update script (update.php and updates.inc) a bit. The problem lies in the

CREATE

[UNIQUE] INDEX

and

ALTER TABLE ... DROP/ADD CONSTRAINT

statesments. When schema prefixes are used, queries like this are executed:

CREATE INDEX prefix.search_total_word_idx ON prefix.search_total(word)

ALTER TABLE prefix.boxes DROP CONSTRAINT prefix.boxes_title_key

ALTER TABLE test.contact ADD CONSTRAINT test.contact_category_key UNIQUE (category)

The prefix must be removed from the index and constraint name--that is they must be changed to:

CREATE INDEX search_total_word_idx ON prefix.search_total(word)

ALTER TABLE prefix.boxes DROP CONSTRAINT boxes_title_key

ALTER TABLE test.contact ADD CONSTRAINT contact_category_key UNIQUE (category)

You can easily search for names.

CREATE INDEX

CREATE UNIQUE INDEX

and

ADD/DROP CONSTRAINT

statements and remove the

{}

from index/constraint

The best way is to run a test upgrade. You'll see a list of failed queries and it will be easier for you to change them.

Another remark: you can't use prefix.sh to prefix the tables, it will produce incorrect

CREATE [UNIQUE] INDEX

queries. This, also, can be easily fixed, by changing: s/^CREATE INDEX $.*$ ON /CREATE INDEX $PREFIX\\1 ON $PREFIX/; s/^CREATE UNIQUE INDEX $.*$ ON /CREATE UNIQUE INDEX $PREFIX\\1 ON $PREFIX/; to: s/^CREATE INDEX $.*$ ON /CREATE INDEX \\1 ON $PREFIX/; s/^CREATE UNIQUE INDEX $.*$ ON /CREATE UNIQUE INDEX \\1 ON $PREFIX/;

An alternate approach

Here's what you need to do if you want to solve it this way:

1. Add the following at the top of your database.pgsql file:

CREATE SCHEMA schemaname;

SET search_path TO schemaname;

2. Edit drupal/includes/database.pgsql.inc, replacing the function db_connect() with:

<?php

function db_connect ( $url ) {

$url = parse_url ( $url );

$db_and_schema = explode ( "." , substr ( $url [ 'path' ], 1 ));

$conn_string = ' user=' . $url [ 'user' ] .

' dbname=' . $db_and_schema [ '0' ] .

' password=' . $url [ 'pass' ] . ' host=' .

strtr ( $url [ 'host' ], '+' , '/' );

$conn_string .= isset( $url [ 'port' ]) ? ' port=' . $url [ 'port' ] : '' ;

$connection = pg_connect ( $conn_string ) or die( pg_last_error ());

if(!empty( $db_and_schema [ '1' ])) pg_query ( 'SET search_path TO ' .

$db_and_schema [ '1' ]);

return $connection ;

}

3. Finally, use a db_url akin to such in your settings.php file(s):

$db_url = 'pgsql://user:password@+tmp/dbname.schemaname';

Not thoroughly tested, but works for me (on 4.6.3).

This also fixes the inability to specify a Unix socket as the host - the +tmp gets replaced with /tmp for pg_connect().

Drupal 6.x

SQL command after database connect

Actually, as of Drupal 6.9, I couldn't find a file named updates.inc, and a grep 'CONSTRAINT' update.php modules/update/* returned nothing.

In the second solution, the trick is to

* embed the schema name in $dburl (in settings.php),

* then modify db_connect() code to

o extract the schema name from $dburl

o rebuild a suitable connection string (remove it from $db_url) for

pg_connect()

o build and send a SQL instruction to the engine, telling it to use the specified schema.

Searching db_connect() in Drupal site, I found this old post #26549: SQL command after database connect ", unfortunately closed. The links it points to restrict the idea to fixing encoding (now rigidly set to utf-8).

66 of 183

2010-05-10

It sounds to me like a cleaner and more flexible version of the second approach described here.

I posted this alternate solution as #375763: Running site-specific SQL commands on database connect

Moving Drupal tables to their dedicated PostgreSQL schema

After applying the patch I submitted in #375763: Running site-specific SQL commands on database connect, I created a blog entry, with PHP code input format, and the following body content:

<?php

global $db_type ; if ( $db_type != 'pgsql' )

die ( "This tool is intended for PostgreSQL databases only.

Current engine: $db_type" );

$res = db_query ( "SELECT current_schema();" );

$pg_schema_active = db_result ( $res );

$pg_schema_new = 'drupal' ; if ( $pg_schema_active == $pg_schema_new ) {

echo "<p>Current schema is '$pg_schema_new' already.\n" ;

echo "The following is useless.</p>\n" ;

} echo <<< EOT

<p>To move your Drupal tables from current PostgreSQL schema

"<code>$pg_schema_active;</code>" to their dedicated

"<code>$pg_schema_new;</code>" namespace, you need to:

</p>

<ol>

<li>save this code in a file, e.g. "<code>migrate-drupal-schema.sql</code>"</li>

<li>put your Drupal site offline (maintenance mode).</li>

<li>Enable PostgreSQL schema support in your Drupal site (Issue [#375763])</li>

<li>execute sql code with 'psql' or 'phppgadmin' for example</li>

<li>edit your <code>settings.php</code> file and add (a good place is just below \$db_url and \$db_prefix):

<pre>

\$db_after_connect_sql = "SET search path TO $pg_schema_new;";

<pre>

</li>

<li>Put your Drupal site back online.</li>

</ol>

EOT;

$drupal_schema = drupal_get_schema ( NULL , TRUE );

$migrate_sql = "CREATE schema $pg_schema_new;\n\n" ; foreach ( array_keys ( $drupal_schema ) as $table_name ) {

$migrate_sql .= "ALTER TABLE $pg_schema_active.$table_name SET SCHEMA $pg_schema_new;\n" ;

} echo "<textarea cols=\"80\" rows=\"15\" name=\"migrate-drupal-schema\">\n" ; echo $migrate_sql ; echo "</textarea>\n" ;

Its output should be self explanatory. Please post comments in the support forum if you have problems.

Define shared variables for all sites

When you create a multi-site installation, an important table to duplicate is the variable table. However, by duplicating this table, you will also duplicate some variables that you might prefer not to. To force a set value for these variables, for all of your websites, you can do the following.

First, you will probably have a settings.php file for each site in your installation, like sites/example.com/settings.php. Edit each file and add the following to the end.

include_once ('./sites/default/shared_variables.php');

Now, in the default directory, add a file called sites/default/shared_variables.php

containing the following.

<?php

/**

* These variables are fixed for all sites that have this line of

* code in their settings.php file:

* include_once ('./sites/default/shared_variables.php');

$conf = array(

'site_name' => 'All these sites are belong to us.' ,

'theme_default' => 'pushbutton' ,

'anonymous' => 'Visitor'

);

The element names (eg. 'site_name') correspond to a variable in the file.

variable

table. So no matter how many copies of the variable table that you need, each site in your multi-site installation will defer to the variables that you define in the $conf array in your shared_variables.php

The disadvantage is that these variables cannot be edited via the Drupal admin pages.

Clean URLs

67 of 183

2010-05-10

By default, Drupal uses and generates URLs for your site's pages that look like "http://www.example.com/?q=node/83." This style of URLs can be hard to read, and can prevent some search engines from indexing all the pages of your site. Research suggests this may not be as great an issue for some of the major search engines as it once was; however, it is worth noting the recommendation from Google's webmaster guidelines stating:

If you decide to use dynamic pages (i.e., the URL contains a "?" character), be aware that not every search engine spider crawls dynamic pages as well as static pages. It helps to keep the parameters short and the number of them few.

If you are unhappy with the default URLs in Drupal, you may be able to tell Drupal to use "clean URLs", eliminating the "?q=" in your site's

URLs, and this page explains how to do it. The instructions below are largely applicable only for the most common server setup, which is an

Apache web server running on some flavor of Unix/Linux, with the mod_rewrite Apache module configured and mod_rewrite enabled in httpd.conf configuration file. If you are running Drupal on a different type of server, check the links section below (just above the Comments section of this page) to see if there might be something that addresses your server configuration on a different page.

Before enabling clean URLs in the Drupal configuration screens (see below), you may need to prepare your server for clean URLs to work.

There are two ways to prepare your server for clean URLs to work in Drupal. If you have complete control of your server, for example because you run your own server, are installing a development site on your personal computer, or have a dedicated server hosting account, then you should enable clean URLs in the httpd.conf file for better performance and security. However, if you have a shared hosting account

(at DreamHost, BlueHost, HostGator, GoDaddy, 1and1, et al.), you will not be able to modify the httpd.conf file and should use the Drupal

.htaccess file instead.

Enabling Clean URLs in Drupal

Note: The standard Drupal installation contains a sample .htaccess file which supports clean URLs. It is easy to miss copying this file, because of the leading "dot". So before trying to enable Clean URLs, make sure this file exists in your Drupal installation.

Drupal 6.x

In Drupal 6, the installer tests for compatibility with Clean URLs as a part of the installation process. If the installer was not able to run the test successfully at install time, you can later follow the instructions below for Drupal 5 to get Clean URLs working. There is one minor difference: Drupal 6 will run the clean URL test automatically when you navigate to the Clean URLs configuration page and will show the results, in place of giving you a link to run the test manually.

Also note that even if Clean URLs are successfully enabled at install-time, if you have a dedicated server you may still want to follow the steps below to enable the more efficient httpd.conf rewrite method for clean URLs. If you choose to do that, you might want to turn off

Clean URLs while you are working on the server.

Drupal 5.x

Here are the steps necessary to enable Clean URLs in Drupal 5:

1. Goto the administer >> site configuration >> clean urls section of the administrative interface.

2. Look for the paragraph that reads as follows:

This option makes Drupal emit "clean" URLs (i.e. without ?q= in the URL.) Before enabling clean URLs, you must perform a test to determine if your server is properly configured. If you are able to see this page again after clicking the "Run the clean URL test" link, the test has succeeded and the radio buttons above will be available. If instead you are directed to a

"Page not found" error, you will need to change the configuration of your server. The handbook page on Clean URLs has additional troubleshooting information. Run the clean URL test.

3. Click on the Run the clean URL test link at the end of the above paragraph.

4. If the test is successful, set Clean URLs to "enabled" and save the configuration. If the test is not successful, use the steps below to fix your server configuration and try again.

Prior to Drupal 5.x

For Drupal versions prior to Drupal 5, there is no automatic Clean URLs test or link. Instead, you can test manually by typing in the Clean

URL for your settings page: http://www.example.com/admin/settings

(where www.example.com

is replaced by your hostname). If this results in seeing the settings page, and no errors, then Clean URLs are safe to enable, and you can do so with the setting on this page. If there is an error, follow the instructions below to configure your server.

Error recovery

Enabling "Clean URLs" when your server is not properly configured (i.e. if the Clean URLs tests described above fail) can make it difficult to navigate back to administration pages to undo your mistake, because all the Drupal-generated menus and links will have URLs that do not work. If you find yourself in this situation, you can return to the administrative settings page by typing in the URL in the 'non-clean' form: http://www.example.com/?q=admin/settings urls

for the admin settings page in Drupal 4.x, or http://www.example.com/?q=admin/settings/clean-

to get to the Drupal 5 or Drupal 6 Clean URLs settings page. Once there, you should be able to reset to not using Clean URLs.

There are additional instructions for recovering from malfunctioning Clean URLs the Handbook page Unset clean URLs .

Server configuration for Clean URLs on a dedicated server, with httpd.conf

68 of 183

2010-05-10

Enabling clean URLs on a dedicated server involves these steps:

1. Enable mod_rewrite for Apache. You can talk to your web host or consult the Apache documentation for mod_rewrite to get more information on how to do this. At a minimum, this will involve making sure that mod_rewrite is enabled for your installation of Apache.

To test if mod_rewrite is available in Apache2, you can type the following at a command prompt, to list all installed Apache modules: apache2ctl -M

On some systems this command may be: apachectl -M

In the output, check to see if the rewrite_module

is included in the list of modules.

If the rewrite module is not in the list, it will have to be either compiled-in or made available as a loadable module. Generally speaking, you can tell Apache to load the module by including

LoadModule rewrite_module modules/mod_rewrite.so

AddModule mod_rewrite.c

in your Apache configuration file (see below for information on the configuration file). Be sure to uncomment AddModule mod_rewrite.c, if it is in your configuration file but has been commented out. The following may work to enable the module without editing any files: a2enmod rewrite

Note that these approaches may not work for all combinations of operating system and Apache server -- consult the Apache documentation that came with your Apache software for the correct syntax.

Remember to restart Apache for the new configuration to take effect.

2. The next step is to locate the appropriate Apache configuration file for your site. Depending on your server configuration, the appropriate Apache configuration file could be httpd.conf, a virtual-host-specific file (vhost.conf), a specific site file (e.g. "default"), or apache2.conf. They are usually located in

/etc/httpd/conf

/etc/apache2

, or a sub-directory; if not, try the command: find /etc -name httpd* to find the file if it is located elsewhere in your file system.

If you do not have write permissions to these files, and Clean URLs are not working out-of-the-box for you, you may have to ask your systems administrator or hosting provider for help. You may still be able to troubleshoot a little however.

read

these configuration files to

3. The next step is to copy or include the Drupal-specific settings directly into your configuration file. There are instructions here for how to include the Drupal directives in your configuration file. Consult the .htaccess file in Drupal page for examples of rules, such as the following:

RewriteEngine on

RewriteBase /

RewriteCond %{REQUEST_FILENAME} !-f

RewriteCond %{REQUEST_FILENAME} !-d

RewriteRule ^(.*)$ index.php?q=$1 [L,QSA]

</Directory>

Note: If you do not want to put the rewrite rules in your Apache configuration file, you can still simply use the Drupal .htaccess file (as you would if you were on shared hosting). You will need to have the Allow Override directive set in your Apache configuration file (this will allow local .htaccess overrides on your site):

AllowOverride All

AccessFileName .htaccess

Read " Behind the scenes with Apache's .htaccess

for a thorough review of .htaccess; this other site has samples of Apache 2 directives .

Note Regarding MultiViews: Apache supports a feature called "MultiViews" (more generally: "Content Negotiation"), which allows navigation to your pages without the need for file extensions. For instance, if you had a file called "evaluation.txt", a MultiViews-enabled site could access this file with the URL "example.com/evaluation". While MultiViews can be a handy feature when used knowingly, it can cause problems when Drupal's Clean URLs are enabled. Unless you know what you're doing, you should not use MultiViews if you plan to use the

Clean URLs feature of Drupal. However, MultiViews is not enabled in a default Apache installation, so it is likely that this note will not apply.

Consult the Apache documentation for further information about MultiViews .

Server configuration for Clean URLs on a shared server, with .htaccess

The standard Drupal installation contains a sample .htaccess file which should be sufficient to get Clean URLs running. It is easy to miss copying this file, because of the leading "dot". So before trying to enable Clean URLs, make sure this file exists in your Drupal installation.

If you have this file installed, but Clean URLs still do not work, you can try some of the troubleshooting suggestions below. If you still cannot get Clean URLs to work, contact your hosting provider.

Fixing problems

69 of 183

2010-05-10

RewriteBase setting

The main configuration option which may need to be changed for your site is the

RewriteBase

. This can be specified in the Drupal .htaccess

file or in the httpd.conf file, depending on where you are putting the Drupal rewrite directives (see above). By default, the RewriteBase setting is commented out of the Drupal .htaccess file, and that works well for many configurations.

If you are having trouble getting Clean URLs to work, you may need to change this setting. For example, if your Apache DocumentRoot is

/var/www/

(i.e., /var/www/index.html is what is displayed when you point your browser at installation is installed in the subdirectory

/var/www/mysite/ http://www.example.com/

, then the RewriteBase could be set to

) and your Drupal

RewriteBase /mysite and that might help. In some configurations, setting

RewriteBase / will allow clean URLs to work.

Multi-site

RewriteBase

works when your Drupal installation serves only one site, or when all the sites it serves are in the same subdirectory of their domains. For example,

RewriteBase / will work for the following sites: http://www.example.com/ http://www.example2.com/ http://www.example3.com/

And

RewriteBase /mysite will work for the following sites: http://www.example.com/mysite http://www.example2.com/mysite http://www.example3.com/mysite

However, if your sites are in different subdirectories,

RewriteBase

will not work. You will need to create a special rule for each subdirectory.

For example, your Drupal installation may serve the following sites: http://www.example.com/ http://www.example.com/mysite

In order to enable clean URLs for both sites, you will need to add

RewriteCond %{REQUEST_FILENAME} !-f

RewriteCond %{REQUEST_FILENAME} !-d

RewriteCond %{REQUEST_URI} ^/mysite/(.*)$

RewriteRule ^(.*)$ /mysite/index.php?q=$1 [L,QSA] before the existing rewrite rules.

Location of index.php

For some server configurations, another change to the Drupal .htaccess file may be necessary. Find a line that looks like this, near the end of your Drupal .htaccess file:

RewriteRule ^(.*)$ index.php?q=$1 [L,QSA]

You may need to replace index.php

with the URL path to your Drupal installation's index.php file (only the part after the base URL). For instance, if your site's home page URL is http://example.com/subdir/

, you might need to use

/subdir/index.php

instead of index.php

. If your site's home page URL is not all server configurations.

http://example.com/

, you might need to use

/index.php

instead of index.php

. This is necessary on some, but

Even cleaner URLs with the Path Module

Using

Clean URLs

will cause Drupal to generate URLs in the form "http://www.example.com/node/83." In order to change the 'node/number' portion of the URL to something more like 'news/june-1st-news' a site will need the Path module enabled. See the Path module handbook page for more information on using the path module.

A step-by-step process for enabling clean URLs

I am running vmware workstation with Ubuntu 8.10 with LAMP and Drupal 6.6.

70 of 183

How I was able to enable clean URLs.

1. Enable the Apache Module

Open Terminal and type:

apache2ctl -M

to see if rewrite_module is there. If it is not there, first go to the file browser and navigate to

/etc/apache2/mods-available folder and confirm that rewrite.load

exists. If it does not exist, then the rest of this won't help until it does.

If it does exist, we need to create a symlink from mods-enabled to mods-available. So in Terminal type or copy/paste:

2010-05-10

cd /etc/apache2/mods-enabled ln -s ../mods-available/rewrite.load

(that first letter is a lowercase L )

If permission is denied, put sudo

before ln

sudo ln -s ../mods-available/rewrite.load

2. Check the Apache Module

Confirm that rewrite.load

apache2ctl -M

is now in the mods-enabled folder by opening the folder and finding it, or typing into Terminal

So far so good? Great!

3. Enable AllowOverride All

Next we need to open sites-enabled

in the apache2 folder:

/etc/apache2/sites-enabled and right-click the 000-default file and click the permissions tab. If the access is read-only, open Terminal and type:

sudo nautilus /etc

Doing that pops up the file browser as root. Navigate to

000-default

again:

/etc/apache2/sites-enabled/000-default

Right-click again, go to permissions and change all the read only's to read and write (mine change back automatically after I close the file directory but you might want to double-check.)

In this file it will say AllowOverride None in several places, each time inside of a different Directory tag. Find the one for where you've installed Drupal, and change it to AllowOverride All. For instance, if Drupal is installed at under the Directory "/home/username/www" grouping.

/home/username/www/drupal6

, then it may be

Explanation

AllowOverride All

is an Apache directive that tell it to

read and set any of the instructions found in .htaccess files.

On some servers this is restricted - allowing you to change the error document, but not the directory indexes for example. The

.htaccess file that comes with Drupal expects to be able to set a few (reasonably safe) overrides, so we tell Apache to obey

(allow) these instructions.

After this, open Terminal and and restart apache by typing:

sudo /etc/init.d/apache2 restart

You must restart Apache after every change you make to the apache files (if you expect to see changes in Drupal, for example).

Last but not least, I COULD VERY WELL BE WRONG AND DOING SOMETHING QUITE AWFUL, but it did work for me.

I figured this out after finding these two sites: http://www.jonathansblog.net/node/22 and http://linux.derkeiler.com/Mailing-

Lists/Debian/2005-03/2483.html

~Admerin

Configuring clean URLs for various systems

This section provides instructions for configuring clean URLs on specific hosts.

Apache 2 configuration of clean URLs on Debian

Note: This article needs to be updated for Debian "Etch" and "Lenny" releases. (as of March 2009)

If you're running Apache 2 on Debian stable, in order to install the rewrite module you simply need to:

# a2enmod rewrite then restart the webserver:

# /etc/init.d/apache2 restart

71 of 183

2010-05-10 then edit either /etc/apache2/sites-enabled/drupal or to your .htaccess and ensure it looks something like this:

# Apache/PHP/site settings:

# Protect files and directories from prying eyes:

order deny,allow

deny from all

</Files>

# Set some options

Options -Indexes

Options +FollowSymLinks

# Customized server error messages:

ErrorDocument 404 /index.php

# Set the default handler to index.php:

DirectoryIndex index.php

# Overload PHP variables:

# If you are using Apache 2, you have to use <IfModule sapi_apache2.c>

# instead of <IfModule mod_php4.c>.

php_value register_globals 0

php_value track_vars 1

php_value short_open_tag 1

php_value magic_quotes_gpc 0

php_value magic_quotes_runtime 0

php_value magic_quotes_sybase 0

php_value arg_separator.output "&"

php_value session.cache_expire 200000

php_value session.gc_maxlifetime 200000

php_value session.cookie_lifetime 2000000

php_value session.auto_start 0

php_value session.save_handler user

php_value session.cache_limiter none

php_value allow_call_time_pass_reference On

</IfModule>

# Various rewrite rules

RewriteEngine on

Options All

# Modify the RewriteBase if you are using Drupal in a subdirectory and the

# rewrite rules are not working properly:

RewriteBase /drupal

# Rewrite old-style URLS of the form 'node.php?id=x':

RewriteCond %{REQUEST_FILENAME} !-f

RewriteCond %{REQUEST_FILENAME} !-d

RewriteCond %{QUERY_STRING} ^id=([^&]+)$

RewriteRule node.php index.php?q=node/view/%1 [L]

# Rewrite old-style URLs of the form 'module.php?mod=x':

RewriteCond %{REQUEST_FILENAME} !-f

RewriteCond %{REQUEST_FILENAME} !-d

RewriteCond %{QUERY_STRING} ^mod=([^&]+)$

RewriteRule module.php index.php?q=%1 [L]

# Rewrite URLs of the form 'index.php?q=x':

RewriteCond %{REQUEST_FILENAME} !-f

RewriteCond %{REQUEST_FILENAME} !-d

RewriteRule ^(.*)$ index.php?q=$1 [L,QSA]

</IfModule>

# $Id: .htaccess,v 1.58 2004/10/09 20:41:49 dries Exp $

This is because the debian package installs the drupal "sites-enabled" virtual host, result being that drupal is accessed from http://example.com/drupal , hence the need to uncomment RewriteBase. Change it to the base that corresponds to your system.

ref: http://www.debian-administration.org/articles/136 http://drupal.org/node/14322

Sean K. O'Brien

CTO

Colley Graphics, LLC http://www.colleygraphics.com

Apache 2 on Debian Lenny w/Backports Drupal 6.16 (and

Squeeze)

These instructions enable you to configure apache2 to support Drupal's

(currently drupal6 6.16-1~bpo50+1). Therefore, these instructions

Clean URLs should

for a default lenny backports installation of drupal 6

also cleanly work for Debian Squeeze (currently in testing). The default installation serves drupal 6 as http://localhost/drupal6/ . These instructions may work for earlier versions of Drupal 6 on Lenny and possibly Etch and possibly Ubuntu versions. Please comment if you have success with these other versions.

For information about Debian Backports, visit http://www.backports.org/ .

How To

72 of 183

2010-05-10

To enable

Clean URLs

in the defalt configuration, first, ensure that the apache2 "Rewrite Module" is enabled: sudo a2enmod rewrite

Next,

edit one and only one file,

/etc/apache2/conf.d/drupal6.conf

, and make these mods a symlink: /etc/apache2/conf.d/drupal6.conf -> /etc/drupal/6/apache.conf):

within

the

block (careful, this file is

1. Change

AllowOverride

None

2. Add the Rewrite Module directive

RewriteBase

, setting it to

/drupal6

Include

the default drupal 6 .httaccess file,

/usr/share/drupal6/.htaccess

The modified

/etc/apache2/conf.d/drupal6.conf

file will now look like this (changes in bold-italic):

Alias /drupal6 /usr/share/drupal6

Options +FollowSymLinks

# AllowOverride All

AllowOverride None

order allow,deny

allow from all

<IfModule mod_rewrite.c>

RewriteBase /drupal6

</IfModule>

Include /usr/share/drupal6/.htaccess

</Directory>

After changing the file, restart apache2 with the command: sudo /etc/init.d/apache2 restart

Then navigate to your drupal adminstrative site configuration enable

Clean URLs

and test.

Clean URLs

page, ensure that the system is correctly configured, and then

Discussion

Changing

AllowOveride once (at startup).

to None and including the

.htaccess

file within the

means that Apache2 will only load the .htaccess file

I recommend

against

the practice of adding more every web request, instead of just once on startup.

AllowOveride All

directives because this will cause apache2 to read the

.htaccess

file on

The

RewriteBase /drupal6

directive appears as a comment in the

/usr/share/drupal6/.htaccess

file, but I recommend putting the directive in the conf.d/drupal6.conf file because why change more config files than necessary?

Apache 2 on Ubuntu

There are two methods for setting up Drupal 5.x/6.x with Apache on Ubuntu. The first (preferred) method edits the 'Virtual Host configuration, which is the default setup on Ubuntu (even for a single-site webserver). The second edits the main apache2.conf, which is typical for an older setup.

Method 1: 'Virtual Host' setup

First, from the linux command line, enable the rewrite module for apache with this command: sudo a2enmod rewrite

Next, use an editor (such as nano available/

) to edit the appropriate Apache configuration file for your Drupal site in the

/etc/apache2/sites-

directory. For a single site, the file is

/etc/apache2/sites-available/default

; if you have multiple sites, the file names should reflect the names of the sites to which they refer. Thus, to edit the default site configuration, use sudo nano /etc/apache2/sites-available/default

Look for the

Sub Domain Setup

73 of 183

2010-05-10

An alternative to multiple virtual hosts files is to use subdomains. This allows you to use a wild-card in the Server Alias. This allows for both a simple multi-site Drupal setup, as well as multi Drupal versions. Instead of multiple virtual hosts files, you define a subdomain for each drupal profile.

Consider the following and modify your configuration file to fit your needs.

1. http://myproject.dr5.example/

2. http://myproject.dr6.example/

3. http://myproject2.dr6.example/

Here is an example of a partial listing of a virtual host configuration file that would support the

last two lines in the above example

is not intended to be a COMPLETE configuration file, but rather provide guidance for your development setup.

. Note this

DocumentRoot "/www/Dr6"

ServerName example

ServerAlias *.dr6.example

AllowOverride All

</Directory>

Edit & save your config file to suit your development needs. Assuming the site is already enabled, then reload Apache.

Method 2: apache2.conf

Then you have to enabled the rewrite module(mod_rewrite). You no longer have to do the:

LoadModule rewrite_module modules/mod_rewrite.so

AddModule mod_rewrite.c

It's now as easy as: sudo a2enmod rewrite

To disable this module it's just: sudo a2dismod rewrite with Apache version 2, the httpd.conf has been deprecated and the new file is located at:

/etc/apache2/apache2.conf

in this file you need to add your directory and the allow override to give access to your drupal site.

so look for a section in your apache2.conf that has Directory tags and just add another section:

AllowOverride all

</Directory>

*keep in mind that my website is in a subdirectory (drupal_website_install) and so you may need to edit the above to reflect this. By this I mean if i go into my webbrowser I need to go to http://localhost/drupal_website_install/

After you edit you apache2.conf as listed above you need to restart the server by:

/etc/init.d/apache2 reload

Problems with Rewrite

If you are having problems with getting your rewrite to work you can always use logging. To do that add this to the end of

/etc/apache2/apache2.conf

RewriteLog "/var/log/apache2/rewrite.log"

RewriteLogLevel 3

Level 0 is no logging

Level 9 is log everything

You can pick the level to determine the amount of output you need.

***Security Warning: Make sure to take the log code out, disable it, or put the log file in a directory that can't be read by normal users (as shown above) otherwise it can result in a security breach.*** hopefully this helps some people and saves them the time that I spent trying to get it working.

Finish - Enable Clean URLs

Now browse to your site, login, click administer, find "Clean URLs" and browse to that page, run the test for "Clean URLs" (In Drupal 4.6 -

5.x this is buried in the paragraph explaining "clean Urls").

If your setup is like mine, you should now have Clean URLs in drupal.

Boost .htaccess for clean urls on specific shared hosts

This code was taken from the Boost module and modified just a little bit. Please note that this implements a static cache of pages

for anonymous users on your site. Read the Boost documentation to understand what this means.

74 of 183

2010-05-10

Various users have reported that this .htaccess file works on the following hosts:

1and1.com

byethost.com

dotster ehostpros.com

ehosting.ca

hostmonster.com

IXWebhosting.com

mediatemple.net

siteground.com

Site5.com

godaddy.com

There is no guarantee this will work for you though.

Instructions:

Create a text file, copy and paste the code below and save it as .htaccess

Upload the file and put it in the public_html directory of your site.

Modify "

RewriteBase /

" in line 68 to "

RewriteBase /example

" if your site is in subdirectory "example."

# Apache/PHP/Drupal settings:

# Protect files and directories from prying eyes.

Order deny,allow

Deny from all

</FilesMatch>

# Set some options.

Options -Indexes

Options +FollowSymLinks

# Customized error messages.

ErrorDocument 404 /index.php

# Set the default handler.

DirectoryIndex index.php

# Override PHP settings. More in sites/default/settings.php

# but the following cannot be changed at runtime.

# PHP 4, Apache 1

php_value magic_quotes_gpc 0

php_value register_globals 0

php_value session.auto_start 0

</IfModule>

# PHP 4, Apache 2

php_value magic_quotes_gpc 0

php_value register_globals 0

php_value session.auto_start 0

</IfModule>

# PHP 5, Apache 1 and 2

php_value magic_quotes_gpc 0

php_value register_globals 0

php_value session.auto_start 0

</IfModule>

# Reduce the time dynamically generated pages are cache-able.

ExpiresByType text/html A1

</IfModule>

# Various rewrite rules.

RewriteEngine on

# If your site can be accessed both with and without the prefix www.

# you can use one of the following settings to force user to use only one option:

# If you want the site to be accessed WITH the www. only, adapt and uncomment the following:

# RewriteCond %{HTTP_HOST} !^www\.example\.com$ [NC]

# RewriteRule .* http://www.example.com/ [L,R=301]

# If you want the site to be accessed only WITHOUT the www. , adapt and uncomment the following:

# RewriteCond %{HTTP_HOST} !^example\.com$ [NC]

# RewriteRule .* http://example.com/ [L,R=301]

# Modify the RewriteBase if you are using Drupal in a subdirectory and

# the rewrite rules are not working properly.

RewriteBase /

# Rewrite old-style URLs of the form 'node.php?id=x'.

#RewriteCond %{REQUEST_FILENAME} !-f

#RewriteCond %{REQUEST_FILENAME} !-d

#RewriteCond %{QUERY_STRING} ^id=([^&]+)$

#RewriteRule node.php index.php?q=node/view/%1 [L]

75 of 183

2010-05-10

# Rewrite old-style URLs of the form 'module.php?mod=x'.

#RewriteCond %{REQUEST_FILENAME} !-f

#RewriteCond %{REQUEST_FILENAME} !-d

#RewriteCond %{QUERY_STRING} ^mod=([^&]+)$

#RewriteRule module.php index.php?q=%1 [L]

# Rewrite rules for static page caching provided by the Boost module

# BOOST START

AddCharset utf-8 .html

</IfModule>

RewriteCond %{REQUEST_URI} !^/cache

RewriteCond %{REQUEST_URI} !^/user/login

RewriteCond %{REQUEST_URI} !^/admin

RewriteCond %{HTTP_COOKIE} !DRUPAL_UID

RewriteCond %{REQUEST_METHOD} ^GET$

RewriteCond %{QUERY_STRING} ^$

RewriteCond %{DOCUMENT_ROOT}/cache/%{SERVER_NAME}/0/%{REQUEST_URI} -d

RewriteCond %{DOCUMENT_ROOT}/cache/%{SERVER_NAME}/0/%{REQUEST_URI}/index.html -f

RewriteRule ^(.*)$ cache/%{SERVER_NAME}/0/$1/index.html [L]

RewriteCond %{REQUEST_URI} !^/cache

RewriteCond %{REQUEST_URI} !^/user/login

RewriteCond %{REQUEST_URI} !^/admin

RewriteCond %{HTTP_COOKIE} !DRUPAL_UID

RewriteCond %{REQUEST_METHOD} ^GET$

RewriteCond %{QUERY_STRING} ^$

RewriteCond %{DOCUMENT_ROOT}/cache/%{SERVER_NAME}/0/%{REQUEST_URI}.html -f

RewriteRule ^(.*)$ cache/%{SERVER_NAME}/0/$1.html [L]

# BOOST END

# Rewrite current-style URLs of the form 'index.php?q=x'.

RewriteCond %{REQUEST_FILENAME} !-f

RewriteCond %{REQUEST_FILENAME} !-d

RewriteRule ^(.*)$ index.php?q=$1 [L,QSA]

</IfModule>

# $Id: boosted.txt,v 1.4 2006/12/05 10:39:19 arto Exp $

Drupal 6.x

This .htaccess code works just fine for Drupal 6.4 BUT any internal links in the form 'directory/file.xxx' or just 'file.xxx' need to be changed to include a leading '/'.

Clean URL Support in Abyss

This clean URL implementation has been tested on Abyss X1, one which has a properly set Custom Error Page 404 to any arbitrary file that, for this purpose, will be referenced as "/url_rewrite.php". Due to the generalized design of this solution, this method could theoretically work on virtually any webserver that can redirect missing URI location onto a php resource. The method described here works only on webservers with a singular host configuration.

One esoteric requirement is for the webserver to pass the server variable REQUEST_URI containing the value of the original resource requested. For more information on configuring Abyss X1 for this purpose, please visit this Aprelium forum resource .

This solution could be rendered academic if Aprelium finally decides to implement URL rewrite in Abyss internally. This method is useful for

Abyss webservers version 2.3.2 and most other versions prior to this specific release. Another drawback is that the URL rewrite becomes only invisible to the machine but is always visible to the human.

The idea is to pass (or redirect) the missing URI location on the HTTP-404 handler "/url_rewrite.php". For illustrative examples, let's look at the following scenarios:

1. http://www.example.com/node/add => "/node/add" not found, pass to 404 handler "/url_rewrite.php" => "/url_rewrite.php" determines "/index.php?q=node/add" exists and serves that instead.

2. http://www.example.com/admin/settings => "/admin/settings" not found, pass to 404 handler "/url_rewrite.php" => "/url_rewrite.php" determines "/index.php?q=admin/settings" exists and serves that instead.

3. http://www.example.com/no_exist/location => "/no_exist/location" not found, pass to 404 handler "/url_rewrite.php" =>

"/url_rewrite.php" determines "/index.php?q=no_exist/location" exists and serves that instead but lets Drupal display the proper "page not found" informational message.

Here are the steps in letting this method apply to your setup.

1. Create the following file and save it as "/url_rewrite.php".

<?php

/* Add in this array the list of (old path => new path) pairs */

$redirection = array(

'^(.*)$' => 'index.php?q=$1'

); if (!

file_exists ( $_SERVER [ "REQUEST_URI" ]))

/* Get the URI and trim leading slashes */

$uri = ltrim ( $_SERVER [ "REQUEST_URI" ], "/" );

{ foreach ( $redirection as $key => $value )

{

if ( eregi ( $key , $uri ))

{

/* Convert the replacement string syntax - $1 -> \1 */

/* and perform the substitution */

$uri = str_replace ( "index.php" , "" , substr ( $uri , 0 ));

$new_uri = str_replace ( "?" , "&" , $uri );

$new_uri = "/index.php?q=" .

$new_uri ;

$new_uri = str_replace ( "%26" , "&" , $new_uri );

break;

}

76 of 183

2010-05-10

}

} if (isset( $new_uri ))

{ header ( "Status: 307" ); header ( "Location: $new_uri" );

exit;

}

<HTML>

<HEAD>

<TITLE>Not Found</TITLE>

</HEAD>

<BODY>

The object <tt> <?php echo $uri ; ?> </tt> is not available.

</BODY>

</HTML>

2. In the Abyss web console, enter the Custom Error Pages, add a 404 Status Code entry with the Associated URL value

"/url_rewrite.php". Click OK and restart the Abyss webserver.

3. Test for functionality by querying your website directly with URI's such as: http://www.example.com/admin/settings http://www.example.com/node/add

If the redirection works properly, proceed to the next steps. If the redirection would not work, check if the steps above have been strictly followed. Modify only those things that you have absolute knowledge of.

4. Log on to your website and log on to your "/admin/settings" page. Under General Settings section, enable Clean URLs. If the Clean

URLs option is grayed out, add the line "$conf['clean_url'] = 1;" in your settings.php, then repeat this step. Don't forget to click the

"Save configuration" button.

5. If things do not work out, completely remove the line "$conf['clean_url'] = 1;" from your settings.php. And browse to your http://www.example.com/index.php?q=admin/settings page to disable Clean URLs properly.

"No Tricks" Clean URL Support in Abyss 2.4 and later

Version 2.4 of Abyss and later offers native URL rewriting support, so using tricks with 404 pages as outlined on this page is no longer necessary. Here's a better way to do it.

1. Log in to the Web Server Console at http://localhost:9999/ .

2. Click the "Configure" button next to the relative host in the list.

3. Click on the "URL Rewriting" icon.

4. The "URL Rewriting Rules" list will probably be blank. Click the "Add" button at the bottom to add a new rule.

5. Our first rule is going to tell Abyss to not rewrite paths that are comprised of just a slash, or which contain a dot in them. (Or, more correctly, to rewrite them in exactly the way it found them.) The former are going to be requests for your home page, and the latter are most likely going to be requests for files which we don't want to pass through Drupal, like images, JavaScript files, etc. In the

"Virtual Path Regular Expression" field, enter this:

(^/$|(.*)\.(.*))

6. Make sure that the "If this rule matches" menu is set to "Perform an internal redirection," and enter simply this in the "Redirect to" field:

7. Check the "Append Query String" box.

8. From the "Next Action" menu, select "Stop matching."

9. All other check boxes should be left unchecked. Click OK.

10. Abyss will take you back to the "URL Rewriting Rules" list, and probably give you a message that it wants to restart. Ignore it for now until we add the second rule. Click the "Add" button again.

11. In the "Virtual Path Regular Expression" field, enter:

^([^\?]*)$

12. Again, we want to "Perform an internal redirection." Put this in the "Redirect to" field:

/index.php?q=$1

13. Again, check the "Append Query String" checkbox, and set "Next Action" to "Stop matching." Click OK.

14. Now, if you see the two rules you created above in the URL Rewriting Rules list, take Abyss up on its offer to restart the server.

15. Visit your site in a web browser, log in as an administrator, open up the "Clean URLs" page in the "Site configuration" section, cross your fingers, and turn on clean URLs.

Incidentally, we've found that Abyss works quite well with Drupal when configured this way; however, it was unable to cope with the volume of traffic our site was receiving, and often responded with page load times well into the double digits. I would not recommend using Abyss for anything but the most lightly-trafficked Drupal installations.

Caution

There are some apparent weaknesses in the approach listed above as:

^/$|(.*)\.(.*)

. If we used Drupal's URL aliases feature, for example node 125 is aliased as "/mr.edmons_approach_to_the_tuna_recipe", the rewrite would fail as Abyss would be looking for a physical resource named "/mr.edmons_approach_to_the_tuna_recipe". A better approach has been described in this Abyss forum resource http://www.aprelium.com/forum/viewtopic.php?t=14948 .

In addition, the approach used in that solution transforms requests like page indexes. And then, it uses

REQUEST_FILENAME Is not a directory accurate in leaving the file and directory requests intact.

^(.*)\?(.*)=(.*)$ into

and

/index.php?q=$1&$2=$3

REQUEST_FILENAME Is not a file

to support multi-

as conditions, making it more

Via this approach, special cases can also be covered for Drupal installations located in subpaths.

77 of 183

2010-05-10

Clean URL support in XAMPP

Clean URLs do not work out of the box on XAMPP 1.5.x with PHP4 due to a problem in Apache's module load order; mod_rewrite work properly. To remedy this you will need to edit the file

[path_to_xampp]/apache/conf/httpd.conf

will not

mod_rewrite location

Remove the # at the beginning of this line:

LoadModule rewrite_module modules/mod_rewrite.so

and move it to just above or below

#LoadModule cache_module modules/mod_cache.so

AllowOverride

If the mod_rewrite

change does not work, you also need to check that

AllowOverride All

is set for the directory Drupal is in. Do this in httpd.conf

or extra/httpd-xampp.conf

Open up file \apache\conf\extra\httpd-xampp.conf

Put this code in:

Alias /drupal "C:/Program Files/xampp/htdocs/drupal/"

AllowOverride All

Order allow,deny

Allow from all

</Directory>

Remember to change the path to match your installation location.

If you're not sure where to add it, it might be worth putting it under the entry

Alias /security "C:/Program Files/xampp/security/htdocs/"

...

</Directory> which should already exist.

Always restart Apache after you make changes or the changes to its configuration files won't have an effect.

Drupal Directory

If Drupal is not installed in the document root, the next thing you'll have to do is modify the file the commentsign (#) in front of

RewriteBase

and, if necessary, modify the path:

.htaccess

that comes with Drupal. Remove

RewriteBase /drupal

Finally, in Drupal go to

Administer » Site Configuration » Clean URLs

"Enabled" option for Clean URLs and save the settings.

(admin/settings/clean-urls) and run the clean URL test. Then click the

Clean URLs in Mac OS X Server

For Mac OS X Server 10.4 (Tiger Server) and most likely previous versions as well, do not make changes to

/etc/httpd/httpd.conf

the

AllowOverride All

directive to work. The correct file to add the

AllowOverride All

directive is in the directory

expecting

/etc/httpd/sites/

. In that directory are the virtual host configuration files. Each virtual server has a configuration file in that directory so it is in those files that you must enable

AllowOverride All

. If you only have one web server on your server configured, then the file you want to modify is

/etc/httpd/sites/0000_any_80_.conf

Clean URLs on IIS

Drupal can display brief, "clean" URLs like those at drupal.org

. For Apache sites, mod_rewrite powers this feature. On IIS you'll use either a third-party module or (on IIS7) Microsoft's URL Rewrite module to add this functionality. Refer to your specific IIS version below for details.

Some Third Party ISAPI Rewrite Modules

ISAPI Rewrite by Helicon software. There is a free "lite" and a paid version. IIS Aid has an article on configuring the Helicon module.

There is also an important note about .htaccess files with ISAPI_Rewrite 3 here .

Check this thread for some approaches to setting up ISAPI_Rewrite .

Ionic's ISAPI Rewrite Filter

78 of 183

2010-05-10

Micronovae's IIS Mod-Rewrite (the "standard" version works w/IIS5) ( documentation ).

IIS7

The best method is Microsoft's URL Rewrite Module for IIS7, available via the Web Platform Installer on Windows Server 2008 and Vista.

Download and documentation are also available on Microsoft's IIS.Net site . You can also use third party rewrite modules (see list above).

Note: Service Pack 2 for Windows Server 2008 & Vista contained important IIS7 bug fixes ( KB954946 ) that affect how REQUEST_URI works.

You can download the patch individually or SP2 from the MS website. IIS7 URL Rewrite Home contains useful explanations and links, including a walkthrough video.

You will also need to enable (if you haven't already) FastCGI .

After setting up the rewrite module and enabling FastCGI you will need to edit your site's web.config file. On IIS7, the web.config file replicates and replaces the functionality of .htaccess (which is included in your Drupal distribution). Here is the web.config file provided with the Acquia Drupal distribution for your reference (if you used the Acquia Drupal Web Platform Installer this is already included):

<?xml version="1.0" encoding="UTF-8"?>

<system.webServer>

<!--

Caching configuration was not delegated by default. Some hosters may not delegate the caching

configuration to site owners by default and that may cause errors when users install. Uncomment

this if you want to and are allowed to enable caching

-->

<!--

</profiles>

</caching>

-->

<rules>

<!-- rule name="postinst-redirect" stopProcessing="true">

</rule -->

</rule>

</rule>

<!-- To redirect all users to access the site WITH the 'www.' prefix, http://example.com/ ... will be redirected to http://www.example.com/ ...)

adapt and uncomment the following: -->

<!--

</conditions>

</rule>

-->

<!-- To redirect all users to access the site WITHOUT the 'www.' prefix, http://www.example.com/ ... will be redirected to http://example.com/ ...)

adapt and uncomment the following: -->

<!--

</conditions>

</rule>

-->

</conditions>

</rule>

</rules>

</rewrite>

<!-- httpErrors>

</httpErrors -->

<files>

79 of 183

2010-05-10

</files>

</defaultDocument>

</system.webServer>

</configuration>

IIS6

On IIS6, you can use third party modules (see above) to add mod_rewrite-like functionality to IIS. You will also want to download and set up the FastCGI module .

IIS5

On IIS5, you can use third party modules (see above) to add mod_rewrite-like functionality to IIS. Due to improved application pool security implemented in IIS6+, deployment on IIS6+ is recommended.

IIS5 Alternative: Creating a Custom Error Handler

Note: This method seems to work for IIS5 but not IIS6+.

You probably want to disable logging in IIS, since every page view is considered an error using this technique.

make sure your Drupal is working well without clean urls enabled.

open your Internet Services Manager or MMC and browse to the root directory of the web site where you installed Drupal. You cannot just browse to a subdirectory if you happenned to install to a subdirectory.

right click and select properties -> custom errors tab set the HTTP Error 404 and 405 lines to MessageType=URL, URL=/index.php. If you are using Drupal in a subdirectory, prepend your subdir before /index.php

paste the following code into the bottom of settings.php

file, which is usually located under sites/default/ be edited. If you aren't using a subdirectory, set $sub_directory to "". then set $active=1 and enjoy!

. the first two lines should

<?php

// CONFIGURATION

$sub_dir = "/41/" ; // enter a subdirectory, if any. otherwise, use ""

$active = 0 ; // set to 1 if using clean URLS with IIS

// CODE if ( $active && strstr ( $_SERVER [ "QUERY_STRING" ], ";" )) {

$qs = explode ( ";" , $_SERVER [ "QUERY_STRING" ]);

$url = array_pop ( $qs );

$parts = parse_url ( $url );

unset( $_GET , $_SERVER [ 'QUERY_STRING' ]); // remove cruft added by IIS if ( $sub_dir ) {

$parts [ "path" ] = substr ( $parts [ "path" ], strlen ( $sub_dir ));

}

$_GET [ "q" ] = trim ( $parts [ "path" ], "/" );

$_SERVER [ "REQUEST_URI" ] = $parts [ "path" ];

if( array_key_exists ( "query" , $parts ) && $parts [ "query" ] ) {

$_SERVER [ "REQUEST_URI" ] .= '?' . $parts [ "query" ];

$_SERVER [ "QUERY_STRING" ] = $parts [ "query" ];

$_SERVER [ "ARGV" ] = array( $parts [ "query" ]); parse_str ( $parts [ 'query' ], $arr );

$_GET = array_merge ( $_GET , $arr );

$_REQUEST = array_merge ( $_REQUEST , $arr );

}

?> at this point, you should be able to request clean url pages and receive a proper page in response. for example, request the page

/node/1

and hopefully you will see your first node shown. you should not use the q= syntax; use the clean url syntax. if you get an IIS error, you have a problem. please fix redo the above and then retest.

browse to index.php?q=admin/system, enable clean URLS, and press Submit.

you may get a php error if your php error reporting in your php.ini file is set to high. Try this setting in your php.ini file error_reporting = E_ALL & ~E_NOTICE

IIS CleanURLs using some of the available ISAPI filters.

There is a free version called ISAPI_Rewrite Lite that should get clean URLs working for IIS.

General configuration:

1. Make sure

IIS_WPG

and

NETWORK SERVICE

have access to the .htaccess file - otherwise ISAPI_Rewrite cannot read the configuration httpd.ini (2.x) or .htaccess (3.x) files.

2. D5: Add

$conf['clean_url'] = 1

to your settings.php - to manually enable clean urls.

3. D6: There are no changes required - it simply works.

ISAPI_Rewrite 3.x:

You don't need to change the standard Drupal .htaccess file. Helicon ISAPI_Rewrite 3.x was designed to maintain maximum Apache mod_rewrite compatibility. Us the latest version of ISAPI_Rewrite 3.x (>=3.1.0.56 is required) with Drupal. If you cannot get it working out if the box - enable the

LogLevel

ISAPI_Rewrite.

( http://www.helicontech.com/isapi_rewrite/doc/LogLevel.htm

) setting and try to figure out what's broken in

80 of 183

2010-05-10

ISAPI_Rewrite 2.x: Configuration example if Drupal is installed in webservers root

[ISAPI_Rewrite]

# Accept a url with the following directories and pass them through unchanged.

# Make URLs sane

RewriteRule /cron\.php $0 [I,L]

RewriteRule /index\.php.* $0 [I,L]

RewriteRule /install\.php.* $0 [I,L]

RewriteRule /update\.php.* $0 [I,L]

RewriteRule /xmlrpc\.php $0 [I,L]

# activate rewriting for custom modules (for e.g. banner.module)

RewriteRule /banner_db\.php $0 [I,L]

RewriteRule /banner_file\.php $0 [I,L]

# deactivate rewriting for custom modules (for e.g. robotstxt.module)

RewriteRule /robots\.txt.* $0 [I,L]

RewriteRule /(.*)\?(.*) /index.php\?q=$1&$2 [I,L]

RewriteRule /(.*) /index.php\?q=$1 [I,L]

ISAPI_Rewrite 2.x: Configuration example if Drupal is installed in a subdirectory (Requires

ISAPI_Rewrite >=2.9 Build 63)

[ISAPI_Rewrite]

# You must change/remove prefixes if Drupal is not installed in a subdirectory

# Specify namespaces with UriMatchPrefix - DO NOT CHANGE ORDER

UriMatchPrefix /drupal

# Accept a url with the following directories and pass them through unchanged.

# Make URLs sane

RewriteRule /cron\.php $0 [I,L]

RewriteRule /index\.php.* $0 [I,L]

RewriteRule /install\.php.* $0 [I,L]

RewriteRule /update\.php.* $0 [I,L]

RewriteRule /xmlrpc\.php $0 [I,L]

# activate rewriting for custom modules (for e.g. banner.module)

RewriteRule /banner_db\.php $0 [I,L]

RewriteRule /banner_file\.php $0 [I,L]

# deactivate rewriting for custom modules (for e.g. robotstxt.module)

RewriteRule /robots\.txt.* $0 [I,L]

# specify namespaces with UriFormatPrefix - DO NOT CHANGE ORDER

UriFormatPrefix /drupal

RewriteRule /(.*)\?(.*) /index.php\?q=$1&$2 [I,L]

RewriteRule /(.*) /index.php\?q=$1 [I,L]

# reset namespaces to default

UriMatchPrefix

UriFormatPrefix

Translating Apache's rewrite rules

RewriteCond %{REQUEST_FILENAME} !-f

RewriteCond %{REQUEST_FILENAME} !-d

In plain English: If the REQUEST_FILENAME variable does not exist (not an existing file and not an existing directory) then apply the rule:

RewriteRule ^(.*)$ index.php?q=$1 [L,QSA]"

After much research this exact functionalty does not appear to exist in any ISAPI module for IIS. I think the following solution will help solve this issue. It probably works with most "ISAPI rewrite" modules (they just need the "stop the rewriting process" option).

With this approach you basically revert the "Apache Rewrite" logic. First define rules for known files/folders (like /themes/ ..etc..).

Have those "matching rules" exit, so rules processing stops before going to the next rule. With mod_rewrite.dll you can do that with the option [l].

Here is what my rules file looks (so far) like (using mod_rewrite.dll):

RewriteRule ^/index.php\?q\=(.*)$ /index.php?q=$1 [l]

RewriteRule ^/themes/(.*)$ /themes/$1 [l]

RewriteRule ^/misc/(.*)$ /misc/$1 [l]

RewriteRule ^/(.*)$ /index.php?q=$1 [l]

Remember, you have to add an "exiting" rule for all known folders/files before hitting the final rule. The first rule is to avoid recursion and exit immediatly if the URL already has index.php?q=.

To better understand the Apache rules here are the definitions of the main options:

'last|L' (last rule)

Stop the rewriting process here and don't apply any more rewriting rules. Use this flag to prevent the currently rewritten URL from being rewritten further by following rules.

'qsappend|QSA' (query string append)

This flag forces the rewriting engine to append a query string part in the substitution string to the existing one instead of replacing it. Use

81 of 183

2010-05-10 this when you want to add more data to the query string via a rewrite rule.

REQUEST_FILENAME

The full local filesystem path to the file or script matching the request.

'-d' (is directory)

Treats the TestString as a pathname and tests if it exists and is a directory.

'-f' (is regular file)

Treats the TestString as a pathname and tests if it exists and is a regular file.

Note: Getting Apache running on MS Windows is not that bad (I had been delaying it for years). In reality it's a matter of a few hours to get going. http://www.sitebuddy.com

aims to save you time in that endeavor.

Clean URLs with Easyphp.

To get that the clear URLs works in Easyphp 1.8 you have to join the httpd.conf file and change this two lines:

#LoadModule rewrite_module modules/mod_rewrite.so

and

#AddModule mod_rewrite.c

and leave like this in the same line.

LoadModule rewrite_module modules/mod_rewrite.so

AddModule mod_rewrite.c

and Re-start the server.

Easyphp have the mod_rewrite within.

If there is any problem tell me.

Oskar Calvo.

Clean URLs for EasyPHP 2 (with Apache 2)

For EsayPHP 2

1. Uncomment this:

#LoadModule rewrite_module modules/mod_rewrite.so

2. Under

Change

AllowOverride None to

AllowOverride All

Clean URLs with Lighttpd

For those who have stepped up a notch in performance and moved from Apache to Lighttpd , you need to fix you clean URLs. There are two ways to do so:

Using url rewrites

First you can use the following configuration for Lighty's mod_rewrite module: url.rewrite-final = (

"^/system/test/(.*)$" => "/index.php?q=system/test/$1",

"^/([^.?]*)\?(.*)$" => "/index.php?q=$1&$2",

"^/([^.?]*)$" => "/index.php?q=$1",

"^/rss.xml" => "/index.php?q=rss.xml"

)

The first line ensures that Drupal's clean URL check (when saving Settings) succeeds (Drupal makes an HTTP request for a path of the form

/system/test/yLgnwqqUu5cWnvPi4Hrz.png

). It's a special case that must be handled separately (read on for the reason).

The two following lines let Drupal handle any URL that doesn't contain a dot. This is significant because we can assume, fairly confidently, that addresses like

/node/add

are Drupal URLs, but addresses such as

/themes/bluemarine/style.css

are physical files. So the above configuration will work for all cases where this assumption holds true; if there are exceptions to the rule, they can be manually added to the rewrite configuration.

82 of 183

2010-05-10

The last line handles the important exception of rss.xml, a Drupal URL that contains a dot.

See also the related discussion at http://drupal.org/node/20766

Using mod magnet

Second you can use lighty's mod magnet module together with a simple lua scripts. Have a look at the tutorials http://realize.be/drupal-lighttpd-clean-urls-made-easy or http://more.zites.net/lighttpd_and_drupal_clean_urls_flexible

This way has the advantage that there are no problems with dots.

Clean URLs with Zeus

The Zeus server does not support all aspects of the Apache .htaccess file that ships with Drupal; in particular, the RewriteRules that allow clean URLs are not interpreted by Zeus.

To set up clean URLs on a Zeus server, create a file called rewrite.script in the root of your Drupal installation, and put into it the following script:

RULE_0_START:

# get the document root map path into SCRATCH:DOCROOT from /

# initialize our variables set SCRATCH:ORIG_URL = %{URL} set SCRATCH:REQUEST_URI = %{URL}

# see if theres any queries in our URL match URL into $ with ^(.*)\?(.*)$ if matched then

set SCRATCH:REQUEST_URI = $1

set SCRATCH:QUERY_STRING = $2 endif

RULE_0_END:

RULE_1_START:

# prepare to search for file, rewrite if its not found set SCRATCH:REQUEST_FILENAME = %{SCRATCH:DOCROOT} set SCRATCH:REQUEST_FILENAME . %{SCRATCH:REQUEST_URI}

# check to see if the file requested is an actual file or

# a directory with possibly an index. don't rewrite if so look for file at %{SCRATCH:REQUEST_FILENAME} if not exists then

look for dir at %{SCRATCH:REQUEST_FILENAME}

if not exists then

set URL = /index.php?q=%{SCRATCH:REQUEST_URI}

goto QSA_RULE_START

endif endif

# if we made it here then its a file or dir and no rewrite goto END

RULE_1_END:

QSA_RULE_START:

# append the query string if there was one originally

# the same as [QSA,L] for apache match SCRATCH:ORIG_URL into % with \?(.*)$ if matched then

set URL = %{URL}&%{SCRATCH:QUERY_STRING} endif goto END

QSA_RULE_END:

For more details, tweaks, etc, see this forum post: http://drupal.org/node/46508

Enabling Clean URLs on a Netfirms Server

I am setting up a site for a client on a Netfirms server. We need clean URLs, so I made the necessary changes to the .htaccess file (i.e., set the rewrite base to the proper location). I then went to the clean URLs page on the site, and ran the test. The URL display indicated that in fact clean URLs were working.

Yet the radio button that would allow me to select clean URLs remained grey (that is, I could not select that as an option).

Here is what I did to correct this and enable clean URLs:

1. Use phpMyAdmin to get into the database for the site.

2. Back up the database.

3. Click the

SQL

tab.

4. Enter the following into the query box:

UPDATE `variable` SET `value` = 's:1:"1";' WHERE `name` = 'clean_url' LIMIT 1 ;

83 of 183

2010-05-10

5. Click

Go

6. Return to the clean URLs page on your site and reload the page.

7. If the button is still greyed out, change a setting on your site. For example, go to site configuration, file system, and change

public

private.

and click

Submit.

8. Return to the clean URL page on your site, reload the page, and it should now allow you to enable clean URLs.

9. Return to the file system config page and reset file download method to public.

10. Live happily ever after.

Example Clean URL configuration of httpd.conf for performance

Note the following directions do not adequately cover everything that needs to be included in a site's Apache configuration

file to make sure the site is secure. The files directory needs a SetHandler directive per http://drupal.org/files/sa-2006-

006/advisory.txt

Enabling .htaccess in Apache requires more work on the part of the server. A full explanation can be found here: http://www.serverwatch.com/tutorials/article.php/3436911

Suffice it to say that it is in your interest to not use .htaccess files and even disable them if you are concerned about squeezing more performance out of apache.

I moved the rewrite rules (all of the sample .htaccess file really) to /etc/httpd/conf/drupal.conf. Then for each virtual host, one can add the line:

Include conf/drupal.conf

The rewrite rules change slightly:

# Rewrite current-style URLs of the form 'index.php?q=x'.

RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-f

RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-d

RewriteRule ^(.*)$ /index.php?q=$1 [L,QSA]

Note that I added %{DOCUMENT_ROOT} and a leading slash in front of index.php -- because I have index.php installed in my document root. If you install it in another directory, you will want to give the relative path to it from document root with the leading slash.

Important: If you forget the leading slash (more specifically, forget to give the relative path with leading slash), Apache will give you a "400

Bad Request" error.

This is better. But we still have a problem where every request will check for the existence of a file and a directory before we apply the rewrite rule. The OS may be able to cache some of that information, but it would still be better to avoid the two file-system checks in the first place.

There are some directories that we should not rewrite. And there are certain extensions that we should not rewrite. Using this information, we can update the rewrite rule to send everything to index.php that does not fall into this category. The first rule excludes the directories

"files", "misc", and "uploads". The second rule excludes the extensions you see. Add more if you have other extensions in your directory that should not get passed to index.php.

RewriteCond %{REQUEST_FILENAME} !^/$

RewriteCond %{REQUEST_FILENAME} !^/(files|misc|uploads)(/.*)?

RewriteCond %{REQUEST_FILENAME} !\.(php|ico|png|jpg|gif|css|js|html?)(\W.*)?

RewriteRule ^(.*)$ /index.php?q=$1 [L,QSA]

Note: This sort of directive will disable ImageCache and any other modules that depend on passing requests for files that are not found to index.php.

Compliance with SA-2006-006

Add this to your http.conf file; be sure to change the webroot path

/var/www/html/ your running drupal in multiple sub directories then you need to add this in for each one. (/var/www/html/sitea, /var/www/html/siteb,

/var/www/html/sitec, ...etc). This is compatible with mulitsite due to the

so it matches your webroot path. Also be aware that if sites/*/files

SetHandler Drupal_Security_Do_Not_Remove_See_SA_2006_006

Options None

Options +FollowSymLinks

</Directory>

See Directory Directive for the * syntax and other tips.

Getting Clean URLS Working on Mac OSX Tiger (Client not

Server)

84 of 183

2010-05-10

The Apache htdocs directory in Mac OSX is by default located in /Library/Webserver/Documents. If you copied your Drupal files to this folder via the Finder, you will miss the .htaccess file with the mod_rewrite rules to allow clean urls because .htaccess is a hidden file that Finder does not see.

To remedy this, open the Terminal in your /Applications/Utilities folder and type the following (this example assumes you have a copy of

Drupal 5.2 on your Desktop):

$ cd ~/Desktop/drupal-5.2/

$ cp .htaccess /Library/Webserver/Documents

Now go back and enable clean urls and you should be good to go.

Extra info

Actually there's another issue caused by the default Apache configuration where the AllowOverride value is set to None

Open your httpd.conf file (I use the command pico /etc/httpd/httpd.conf) look for:

# This controls which options the .htaccess files in directories can

# override. Can also be "All", or any combination of "Options", "FileInfo",

# "AuthConfig", and "Limit"

AllowOverride None and set allowoverride to All

Save, restart apache and you're set!

Setting up clean URLs above web document root on virtual private servers

To set up clean URLs above web document root on virtual private servers, you need to change a setting in httpd.conf.

(default setting)

Options FollowSymLinks

AllowOverride None

Change it to

Options FollowSymLinks

AllowOverride All

None of the other changes discussed in this section of the handbook were necessary (and in fact had to be undone).

The hosting provide said this does not provide any security issues (no guarantees).

reboot vps after making change

This is excellent advice. I installed a test site at /var/www/test. My live site is at /var/www/html. The live site worked fine. In the test site i went to set clean url's and got an apache error.

This fixed it.

One minor note. I had to reset the vps before the changes took affect. With my hosting company this is simply a menu selection in their control panel, so if you have this setup and make the change and it does not work.

Ask your provider to reset your Virtual Private Server. This is simular to stopping and starting Apache on a Windows install.

Burn a searchable site to CD using Server2Go

Server2Go is a Webserver that runs out of the box without any installation and on write protected media. This means that you can use

Server2Go to develop your Drupal site locally (or copy over a Drupal site you have already made) and then burn it to a CD. The CD version will be fully searchable and will run all Drupal's php magic!

The clever part is that Server2Go copies all the databases to a temp folder once the CD is launched. This means your Drupal site will behave as if it is live so it can be searched etc. However, although you can also add content to the site when it is launched from the CD this will obviously not be recorded to the CD as the CD is read only! The next time you launch the CD you'll be back with your original burnt site.

This tutorial is quite long, but the result is worth it in the end.

1. Download server2go mini package (NOTE: this tutorial has only been confirmed to work with the mini package [Apache 2.0.61], the package with the latest version of Apache did not work)

2. Unzip where you want it. The folder will be called 'server2go_a2_psm_mini'. In this tutorial we will rename the folder 'Drupal_S2G' to

85 of 183

2010-05-10 make file addresses easier to write out.

Check Server2Go is working by double clicking the Server2Go.exe file. You should get the splash screen saying "congratulations...." opening up in Internet Explorer.

3. OPTIONAL STEP. You can skip this step if you can assume that anyone launching your site on CD will be happy using Internet Explorer.

However, you can have Portable Firefox as the browser included on the CD. To do this: a. Download the latest version of Portable Firefox (tested working with Firefox 2 and 3).

b. Install Portable Firefox in the 'Drupal_S2G' folder (click on 'Browse' to locate the folder on your computer).

c. Launch Portable Firefox by clicking on FirefoxPortable.exe in ( store. You can choose a blank page as the firefox home page in 'Options' and hide the Bookmarks Toolbar so you have a cleaner looking browser window when it launches. Close Portable Firefox. Opening and closing the application is important!

d. Go to (

Drupal_S2G > FirefoxPortable > App > firefox

FirefoxPortable.exe in ( e. Create a file FirefoxPortable.ini in ( f. Paste the following in the file:

Drupal_S2G > FirefoxPortable

) and rename firefox.exe to ffp.exe IMPORTANT: Leave the

Drupal_S2G > FirefoxPortable

) unchanged!

Drupal_S2G > FirefoxPortable

). You can choose to disable session

). You can use a program like Notepad++ to do this.

[FirefoxPortable]

FirefoxDirectory=App\firefox

ProfileDirectory=Data\profile

SettingsDirectory=Data\settings

PluginsDirectory=Data\plugins

FirefoxExecutable=ffp.EXE

AdditionalParameters=

LocalHomepage=

WaitForFirefox=true

DisableSplashScreen=true

AllowMultipleInstances=true

DisableIntelligentStart=false

SkipChromeFix=false

SkipCompregFix=false

RunLocally=false

NOTE: THESE SETTINGS ARE FOR SITE DEVELOPMENT. THEY WILL NEED TO BE CHANGED WHEN BURNING THE SITE TO CD

(see instructions below).

g. Open the pms_config.ini in (

[line 52] BrowserType=PORTABLEFIREFOX

[line 56] BrowserPath=FirefoxPortable/FirefoxPortable.EXE

h. Check it works by launching the Server2Go.exe

4. Change the following settings in the pms_config.ini file in ( a. [line 21] StartLocal=1 (this is for using when you want to develop the website and have to write files. If you want to use server2go to run off a read-only CD at a later point, you will have to change it back to =0) b. [line 61] BrowserSize=MAXIMIZE NOTE: INTERNET EXPLORER ONLY. IGNORE IF USING PORTABLE FIREFOX c. [line 69] LocalMirror=0 this is so that the things you do to build your site are saved rather than carried out in a temporary folder d. Make a note of this value: 'HostName=127.0.0.1' [line 33] and this 'MySQLPort=7188' [line 80] as we need them later.

5. Make the following changes in ( and can provide clean-urls:

6. Change the following setting in (

Drupal_S2G

) and change the following: a. [line 201] max_execution_time = 60 (instead of 30) b. [line 202] memory_limit = 64M (instead of 8M)

Drupal_S2G

) the main folder (use a program like Notepad++ to change it):

Drupal_S2G > server > config_tpl > php.ini

)to make sure Apache has the right settings to run Drupal,

Drupal_S2G > server > config_tpl > httpd.conf

) a. [line 164] Remove the '#' so it reads LoadModule rewrite_module modules/mod_rewrite.so

7. Download Drupal 6.X (latest version) and unzip it into the htdocs folder. You can unzip it so that it sits in a folder inside the htdocs folder. This means you'll have a folder inside htdocs called 'drupal.6.4' or something similar.

NOTE: YOU CAN IMPORT A SITE YOU HAVE ALREADY DEVELOPED. SEARCH THE DRUPAL HANDBOOK FOR ADVICE ON IMPORTING A

DRUPAL SITE TO A LOCAL INSTALLATION.

You can rename it to anything you want, but in this case we'll call it 'drupal' so all Drupal's files will sit in (

drupal

)

Drupal_S2G > htdocs >

8. Do the things the Drupal set up will tell you to do which are: a. Create a folder called 'files' in the main drupal folder i.e.(

Drupal_S2G > htdocs > drupal > files

Drupal_S2G > htdocs > drupal > sites > all

> modules

) and (

Drupal_S2G > htdocs > drupal > sites > all > themes

)

) b. Create a 'modules' folder and a 'themes' folder in the default folder, this is where you will place your add-on modules and themes i.e. ( c. Copy the default settings file and rename it settings i.e. copy (

Drupal_S2G > htdocs > drupal > sites > default > default.settings.php

) and paste it in the same folder, re-naming it to settings.php

9. Now we're going to add the database that Drupal needs to run.

a. Start server2go.exe in the 'Drupal_S2G' folder. It should open up the Server2Go start-page in a new browser (Internet Explorer if you didn't do the Firefox Portable Apps change) b. Go to the phpmyadmin link under 'Tools' on the right-hand side.

c. Click on priveleges d. Click on 'Add user' e. Under username put 'admin' (or whatever you want to call your user); set 'host' as 'local' and set your own password (write it down!) f. Under database for user choose 'none' g. Under 'global priveleges' click on 'check all'

86 of 183

2010-05-10 h. Click on 'Go'. You should get a message saying 'You have added a new user' i. Click on the databases link and you'll see a box at the bottom of the page that says 'create database'. Put in the name of your database. Let's call it 'drupal' and press 'create'. You should get a message saying 'Database drupal has been created.' j. Click on the picture of a house to go to the phpmyadmin home page. Then select 'databases' and click on 'drupal'.

k. Click on the 'priveleges' tab at the top of the page and check that 'admin' is one of the users listed as having access to the database. All done!

NOTE: READ OTHER DRUPAL HANDBOOK INFORMATION ABOUT SECURITY AND CREATING DATABASES. THIS IS A QUICK

METHOD AND NOT NECESSARILY VERY SECURE...

10. Now we're going to set up Drupal. Go to http://127.0.0.1:4001/drupal/ (or http://127.0.0.1:4001/whatever-you-called-the-folder-you-unzipped-drupal...

) and you should see the Drupal set-up page.

a. After you've selected which language you are installing Drupal in, you will be asked to fill in the database details. In our case the database name is 'drupal'; the database username is 'admin'; and the password is whatever password you chose.

b. Click on the 'Advanced options'. In 'Database host' put: 127.0.0.1 and in 'Database port' put 7188, the settings we noted earlier.

c. Save and continue.

d. Follow all the rest of the stuff as in the Drupal Handbook.

e. As you're installing on a local site, you'll probably get this message: warning: mail() [function.mail]: Failed to connect to mailserver at "localhost" port 25, verify your "SMTP" and

"smtp_port" setting in php.ini

Try this: http://drupal.org/project/smtp

11. To check everything works, add some test content to your site and then close the browser. Restart Server2Go.exe once the server has shut down. If your content is there, bingo! It works!

Settings for burning site to a CD

If you want to run some tests without wasting loads of CDs you can create an ISO of your files (you should be burning all the files INSIDE

'Drupal_S2G' and not just copying the 'Drupal_S2G' folder itself onto CD, otherwise the autorun will not work) by using software such as

PowerISO (the free version will create ISOs up to 300MB in size, which should be enough for testing).

There are lots of nice settings to change, including the splash screen (

Drupal_S2G > splash.png

more info. The following settings MUST be changed to make your site work on CD

) which you could replace with any graphic you like and you can even change the name of the server i.e. replace 'Server2Go' with 'My Drupal Site on CD'. See the Server2Go website for

1. In the pms_config.ini file in the ( a. [line 21] StartLocal=0

Drupal_S2G

) folder: b. [line 39] DefaultFile=drupal/ (or whatever the folder is called where you have your drupal files. Don't forget the trailing slash) c. [line 69] LocalMirror=1

If you are using Firefox portable, you will also have to change the following. Annoyingly, you can't be running firefox already when you start the CD and closing the browser will not shut down the server, this has to be done from the tray icon instead.

2. In the pms_config.ini file in the (

3. In the FirefoxPortable.ini in (

Drupal_S2G

) folder.

a. [line 14] KeepRunningAfterBrowserClose=1 b. [line 17] ShowTrayIcon=1 (you need this to be able to shut down the server once you've finished with the CD).

Drupal_S2G > FirefoxPortable

a. AllowMultipleInstances=false b. RunLocally=true

Comments welcome on this as the method has only been tested briefly.

Creating multiple sites on the same domain without using symlinks with Apache

We were searching for a way to support multi-site installations (subsites) on the same domain, that is, to have: www.example.com/ www.example.com/sitea www.example.com/siteb www.example.com/sitec etc.

with different content/themes/modules etc. but on the same Drupal 5.x installation. The normal way to do this is to create the appropriate

/sites/www.example.com.sitea/settings.php

etc...

files and then to create recursive symlinks for each subsite, eg.

ln -s drupal/. drupal/sitea etc..

The problem with this approach is that for multiple sites, it permits for recursive urls

87 of 183

2010-05-10

( http://www.example.com/sitea/siteb/sitea/siteb/content ) which can play havoc with Google PageRank. For us a secondary problem was that is caused our IDE (eclipse) to loose it frequently, presumably since it wasn't able to distinguish the symlinks from real directories and so was recursively parsing the entire drupal directory until it eventually ran out of memory. And finally symlinks don't often seem to translate well in our versioning system, which means we needed to create a script to build the symlinks across different dev environments.

What we wanted to do was achieve mutlisites on the same domain, but without using recursive symlinks. Instead our solution was to use an

Apache RewriteRule for each site. eg.

RewriteRule ^sitea(.*)$ $1 [PT]

This sits neatly in the .htaccess file (before the final 'RewriteRule ^(.*)$ index.php?q=$1 [L,QSA,PT]'), and can be versioned easily.

The problem with this approach is that Drupal uses the SCRIPT_NAME environment variable (normally /index.php) from the server to figure out which site config file to use. With symlinks the server is 'tricked' into thinking it's actually accessing index.php at a different location

(/sitea/index.php) than it actually is, so the SCRIPT_NAME is valid and the correct site file is found.

RewriteRules don't affect SCRIPT_NAME though. In fact we weren't able to find any way to reliably modify SCRIPT_NAME just through

Apache, so instead we patched bootstrap.inc to look at REQUEST_URI instead of SCRIPT_NAME (see attached patch file). This seems to work quite well, assuming you've set $base_url correctly for each site in it's settings.php file. (Editor's note: mod_rewrite has an 'env|E=VAR:VAL'

(set environment variable) flag, add that to [L,QSA,PT] as appropriate)

This solution is easilly versionable, requires no symlinks and doesn't lead to recursive URLS.

Before you use this be aware of some known caveats of this approach:

We've tried it this morning, it's hardly a tried and tested approach. There may well be issues we haven't uncovered.

There are doubtless more elegant ways of doing this, and we'd love to hear from anyone who has done so. Solutions from the community seems rather sparse on this issue right now though, hence this post.

This will only work on servers that set REQUEST_URI, as far as I know only Apache actually does this

You'll need to make sure all links in your subsites add the appropriate $base_path to them.

Attachment Size

bootstrap.inc_.patch

1.3 KB

File and directory management

These are general guidelines.

1. For Drupal 5.x and later: a new feature/best practice. For a normal (single site) installation, you should put all non-core modules or themes in the sites/all/modules

or sites/all/themes

folders. For a multi-site installation, put modules or themes in sites/all

that you wish to have available for all sites.

2. Multisite setups allow you to have a modules directory specific to the site in the sites/www.example.com/modules directory. You can still put modules in directories under sites/all/modules if you want them available to all sites. The most specific module or version found is the one that gets used. If you have different versions of image.module stored in both sites/thatsite/modules/image and sites/all/modules/image, then 'thatsite' will use the version found in 'thatsite' directory, while the others will use the other one.

3. Leave the CHANGELOG.txt file in your root directory as it has the Drupal version information in it. If you manage more than one site, consider putting a version.txt file in the root of your drupal directory with the Drupal version, date and modules you are using. If you only manage a few sites you will probably remember them all, but if you set them up for other people, these reminders can help you if you are asked back to do additional work. Also, it can help the next site admin if you move on.

4. Rename update.php if you want. There are protections for it in the update script in that you have to be logged in with UID1. As of 4.7

update.php is now required for various module installations and other tasks so if you move/rename it for whatever reason do not forget to put it back to it's original state before module installs/updates.

5. Remove install.php if you want. This file is only needed during installation.

Other Tips

Modules that are not part of core may or may not be supported by their contributor for a Drupal version upgrade.

Avoid spaces in any directory name.

Installing Drupal 7 on an OLPC laptop

This post has been moved to the Drupal for OLPC group on http://groups.drupal.org

http://groups.drupal.org/node/24188

Run Drupal on multiple web servers behind a load balancer

When running large Drupal installations, you may find yourself with a web server cluster that lives behind a load balancer. The pages here contain tips for configuring Drupal in this setup, as well as example configurations for various load balancers.

In addition to a large selection of commercial options, various open source load balancers exist: Pound , Varnish , ffproxy , tinyproxy , etc.

88 of 183

2010-05-10

Apache can also be configured as a reverse proxy.

The basic layout you can expect in most high-availability environments will look something like this:

Browser --→ HTTP Reverse Proxy

+-→

--+-

→

+-→

Web server 1

Web server 2

Web server 3

By way of explanation:

Browsers will connect to a reverse proxy using HTTP or HTTPS. The proxy will in turn connect to web servers via HTTP.

Web servers will likely be on private IP addresses. Use of a private network allows web servers to share a database and/or NFS server that need not be exposed to the Internet on a public IP address.

If HTTPS is required, it is configured on the proxy, not the web server.

Most HTTP reverse proxies will also "clean" requests in some way. For example, they'll require that a browser include a valid User-Agent string, or that the requested URL contain standard characters.

In the case of Drupal, it is highly recommended that all web servers share identical copies of the Drupal DocumentRoot in use, to insure version consistency between themes and modules. The best way to achieve this is to use an NFS mount to hold your Drupal files.

Note:

If you plan to install Drupal on a web server that is accessible from the outside via HTTPS, there's an outstanding issue you'll want to check ( #313145: Support X-Forwarded-Proto HTTP header ). At this time, Drupal's AJAX callbacks use URLs based on the protocol used at the web server, regardless of the protocol used at the proxy. Your workaround is either this patch, or to avoid relying on AJAX on your site. Unfortunately, the Drupal installer relies on AJAX, so you'll either need to install the patch at the issue above, or install via

HTTP instead of HTTPS.

Virtual sites: Create multiple sites based on one Drupal installation without using Drupal's multi-site feature

Virtual sites offers almost the same (and more) functionality as the Drupal multi-site feature without the need for FTP or SSH. Depending on conditions (e.g. requested url or user role) handeld by the Condition(s) module, you can override theme, site information, menu's and more to virtually present the visitor with a different website.

What it can do

Create virtual sites with different theme, site information, menu's etcetera.

No need for FTP or SSH, like with Drupal's multi-site feature .

Determine when to show what site based on (sub)domain, path, user role, taxonomy or any other condition .

Add custom conditions by writing a plug-in for the condition module.

Add custom virtual site features by writing a plug-in .

Features a virtual site can have

Each virtual site can override (of your default Drupal site) the following settings:

Set the source for the primary links

Set the source for the secondary links

Set the default site language

Force a base URL (e.g. domain)

Add HTML, JS and CSS to the page template

Set all site information settings (

Set theme

Set all theme-specific settings (

admin/settings/site-information

) like name, slogan and front-page

admin/build/themes/settings/theme

Any Drupal variable, using the easy INI syntax .

) like logo and even settings offered by the theme itself

What it cannot do

For the following settings you'd still need Drupal's multi-site feature :

Database URL (DSN).

Table prefix(es).

PHP configuration and cookie_domain.

String overrides.

Adding a virtual site feature

It's really easy to add new settings (features) than can be applied to any virtual site you create. For this you can create a new module, just

89 of 183

2010-05-10 like the included virtual_site_common.module

we will use here as an example. Like with any hook, replace virtual_site_common

with the name of your module.

Hook in to the virtual sites module

This can be achieved by writing an implementation of hook_feature_info()

<?php

function virtual_site_common_feature_info () {

return array(

// The name of the method that will apply the settings.

'virtual_site_common_feature' => array(

// The name for the settings as the title of the settings form.

'name' => t ( 'Common' ),

// A description as it will be displayed on top of the settings form.

'description' => t ( 'Set common settings for a virtual site.' ),

);

}

As you might note, one module can offer multiples features. Just add another one to the returned array.

Return the form to set the feature settings

Virtual sites will expect a method begins with the name of the specified 'apply method', but then postfixed with

_form

. This method receives an array just like the one it will return in the following paragraph and is expected to return a form array that will be displayed to set the feature settings.

<?php

function virtual_site_common_feature_form ( $context ) {

// ... (took out some code to make it more simple and clear)

$menu_options = menu_get_menus ();

$primary = isset( $context [ 'menu_primary_links_source' ]) ? $context [ 'menu_primary_links_source' ] : variable_get ( 'menu_primary_links_source' , 'primary-links' );

$primary_options = array_merge ( $menu_options , array( '' => t ( 'No primary links' )));

$form [ 'menu_primary_links_source' ] = array(

'#type' => 'select' ,

'#title' => t ( 'Source for the primary links' ),

'#default_value' => $primary ,

'#options' => $primary_options ,

'#description' => t ( 'Select what should be displayed as the primary links.' ),

);

// .. return $form ;

}

Return the settings to be saved for the virtual site

Virtual sites will expect a method begins with the name of the specified 'apply method', but then postfixed with receives the en

$form_state

_submit

. This method

&$form

variables like any form and is expected return the variable (mostly an array) to be saved with the virtual site to be used in the following paragraph.

<?php

function virtual_site_common_feature_submit ( $form , & $form_state ) {

return $form_state [ 'values' ];

}

Appliying the feature to the virtual site

The 'apply method' specified in the global variable.

hook_feature_info()

method will be called if a virtual site is due. The method receives the same variable it returned one paragraph earlier and is expected to apply it's feature. Most of the time, this means overriding a setting in Drupal's

$conf

<?php

function virtual_site_common_feature ( $context ) {

global $conf ;

if ( is_array ( $context )) {

$conf [ 'menu_primary_links_source' ] = $context [ 'menu_primary_links_source' ];

}

Setting up a virtual site

Understanding the Virtual Site module

What the Virtual Site module does is basicly overriding Drupal settings. This is also what Drupal's multi-site feature does at core-level

(

bootstrap

), but than at run-time level ( hook_init()

). This difference is why Virtual Site cannot change database settings, because these

90 of 183

2010-05-10 are already initialized when Virtual Site comes in.

Understanding a single Virtual Site

Each Virtual Site you create can be seen as a group of settings to override Drupal settings with. To determine when which Virtual Site settings are applied, the module depends on the Condition module. A condition can be seen as a group of requirements. When all requirements are met, the condition is

TRUE

A real-life example

Let's say I want to have a different theme and site title for all pages that have a path alias starting with subsite/

Install both the Virtual Site and the Condition module.

Go to

Expand

Press

Set admin/settings/condition/add

Requirement: Pages

Save settings

, set

and choose a name.

Validate

Only...

Go to admin/build/sites/add

and choose a name.

Criteria

Check the newly created condition and press

Find the newly created virtual site in the list and click the

Go to the

When ANY selected condition is met

Information

Theme

tab, select a theme and press

Save settings

Optionally, change any theme settings and press

and enter

Save settings

Create or go to a page having an alias starting with

edit

subsite/

subsite/*

link.

tab, change the default site name and press

Save settings

Handling multiple (sub)domains with Virtual Sites

Just like with Drupal's multi-site feature, the key is to point all the (sub)domains to the main public HTML directory. You can ask your host to point all domains to the same public HTML directory or use symbolic links. Once set, you can create a new condition for every domain and use the hostname requirement to enter the domain you want the condition to be valid for.

Using CVS to maintain a Drupal website

Why maintain a site from CVS?

Maintaining a site from CVS helps in two main areas:

1. Upgrades: Normally, when it comes time to upgrade Drupal to a new version, there's a long list of upgrade steps that you need to follow. New tarballs need to be downloaded and extracted not only for Drupal core, but for all contributed modules as well. Repeat for each Drupal site you maintain. With CVS, this is just a single command.

2. Access to bug fixes: New releases of Drupal are only made after major bugs (generally security issues) are fixed. These bugs (along with dozens of smaller bugs) are always fixed in CVS first.

How to maintain a site using CVS

Assuming you've already grabbed the core code and your favorite contrib modules using the instructions on the checking out core from CVS and checking out contrib modules from CVS pages, you can update your files at any time using a couple of CVS commands.

Checking for updates to core and contribs

cvs -nq update -dP

If updates are available, this will display output similar to:

U modules/taxonomy/taxonomy.module

U modules/upload/upload.module

The 'U' means that the listed file is newer, or "updated" from the one you have in your local copy.

Updating the site

To pull in the changes from CVS that will update your site to the latest Drupal "HEAD" version and dev versions for contributed modules:

1. Enter the command: cvs update -dP

This will update your site to the latest development versions of Drupal core and contributed modules.

2. While logged in as user/1, navigate to example.com/update.php to launch the database update utility to pick up any database changes.

Upgrading to a specific version of Drupal

91 of 183

2010-05-10

Your installation must have been installed via CVS in order to upgrade it via CVS. Let's say you'd like to upgrade from Drupal 6.6 to 6.8.

(This will only update Drupal core, not contributed modules):

1. Enter the command: cvs update -r DRUPAL-6-8 -dP

2. While logged in as user/1, navigate to example.com/update.php to launch the database update utility to pick up any database changes.

Note that if you are doing a major release upgrade (e.g. from Drupal 4.7 to 5.x or from Drupal 5.x to Drupal 6.x) you need to check on your contributed modules to make sure they have been ported for that major version of Drupal.

Upgrading to a specific version of a Drupal contributed module

You can upgrade contributed modules to a specific version if those modules were installed via CVS:

1. Navigate to the directory at the root level of the contributed module.

2. enter the command: cvs update -r DRUPAL-5--1-4 -dP where

DRUPAL-5--1-4

is the "CVS Tag" as listed on the release notes for the module.

3. While logged in as user/1, navigate to example.com/update.php to launch the database update utility to pick up any database changes.

Note: Core tags differ slightly from contribution tags. See Overview of core branches and tags and Overview of contribution branches and tags

Tips

Having a test site is highly recommended; new changes from CVS could potentially bring in additional bugs or changes which break your site (particularly with contributed modules). Testing these updates on a copy of your live server before moving them over is a great idea.

Using a version control system for your Drupal code such as CVS or Subversion is also a good idea; this way, you can keep track of what changes were made and when.

The CVS deploy module is useful for printing more user-friendly version strings on the system modules page, and for interacting with the Update status module (included in core in 6.x and beyond, and via a contributed module for 5.x).

Apt-drup - Preserves original CVS keywords

Preserving cvs keywords from Drupal (like $Id: drupal.js,v 1.29 2006/10/14 02:39:48 unconed Exp$) are essential to track down versions of files you originally used and to be able to patch your local copy of drupal in case you found a suitable patch on drupal.org. To be able to patch, you need to know which version of files we want to patch.

These keywords might get lost when we import this to your own CVS and replaced with your keywords substitution: $Id: drupal.js, v 1.1

2007/01/15 11:30:00 owahab Exp$.

This script does a "cvs export" from Drupal CVS for a version you can specify to a folder you can specify then it adds CVS keywords making the folder ready for a "cvs import" to your CVS, yet preserving Drupal's original CVS keywords.

The script also can be used to download Drupal modules the same way.

1. Download the attached file.

2. $ chmod +x apt-drup.sh

3. $ ./apt-drup.sh folder 5.1

You can substitute: folder with any folder name and 5.1 with any version of drupal.

Note: you can directly request downloading a module a folder that doesn't exist and in this case drupal will be downloaded too.

$ ./apt-drup.sh folder 5.1 event or

$ ./apt-drup.sh folder 5.1 buddylist 1.0

http://cvs.drupal.org/viewcvs/drupal/contributions/sandbox/owahab/apt-dr...

cvsdrupal - checkout and maintain a local CVS repository

This sophisticated script will check out Drupal and any number of contrib modules into a multisite (optionally) directory tree.

It does check out the most recent files for tag selected in $REL, so if you do not want this, you'll have to cvs up

to the tag you want.

The file is attached for download - just change it from a .txt to a .sh file.

#!/bin/sh

# cvsdrupal v0.0.3 20071101 [email protected]

# Multisite CVS Drupal Manager

# Initializes and maintains a multisite Drupal installation

# from the CVS codebase. Additionally, this script manages

# global and per-site modules and themes in the same manner.

92 of 183

# Run this daily or weekly with cron to keep your checkouts

# up to date with all bug fixes and security patches

# applied to your release in CVS.

# You define your site configurations in newline-delineated

# string arrays. There are three classes of such configuration

# arrays used in this script: SITES, _MODULES, _THEMES.

# For instance, you want to host two websites with shared

# modules, example.net and www.example.com:

# SITES="

# all

# example.net

# www.example.com

# "

# The pseudo-site 'all' creates an 'all' subdirectory of 'sites'

# in your Drupal installation. This is the parent of all shared

# modules, themes, profiles, etc.

# Thus, you can create shared resources

# all_MODULES="

# subversion

# svn

# "

# all_THEMES="

# meta

# "

# Each website you define (in SITES) is allowed its own modules

# and themes independent of the other sites in your installation,

# or it may use shared resources, or both. The decision is left

# to you.

# Or, to continue our example, you can create per-site resources

# example_net_MODULES="

# image

# img_assist

# "

# example_net_THEMES="

# dichotomy

# "

# www_example_com_MODULES="

# diff

# pathauto

# "

# www_example_com_THEMES="

# combustion

# "

# Be sure to replace the dots with underscores in the names of the

# per-site configurations. Also, note that any or all of these

# configurations can be blank or left out altogether.

# The configuration above has been included as a skeleton for your

# own website(s). See these included examples for further usage

# details in context of the code.

# License: http://www.gnu.org/licenses/gpl.txt

# Change these settings to suit your environment:

# REL the CVS codebase version you want to checkout,

# leave as is for a stable release or change to

# HEAD for the very latest developments

# BASE root path in which the "drupal" folder resides

# UGID the local user:group file permissions,

# set empty to ignore

# CHANGELOG:

# 2007-11-01 Cody Ray <[email protected]>

# * adapted for multisite usage

# * with more sensible defaults

# 2006-06-28 Mark Constable <[email protected]>

# * initial implementation

REL=DRUPAL-5

BASE=/var/www

UGID=www-data:www-data

# Add your sites

SITES="

all

example.net

www.example.com

# Add shared modules all_MODULES="

subversion

svn

# Add site-specific modules example_net_MODULES="

image

img_assist

" www_example_com_MODULES="

diff

pathauto

# Add shared themes

93 of 183

2010-05-10

2010-05-10 all_THEMES="

Advanced: Using a repository to track local changes to Drupal code

Note: many people use subversion (SVN) as their local repository even though drupal.org uses CVS. Hopefully someone will writeup the process here

Note: The following assumes you have both basic knowledge of CVS and your own local repository set up and working.

If you've been modifying the Drupal source code for your own purposes (or developing a module or theme) and manually applying your changes to the Drupal source every time it updates, you may be glad to learn that CVS can help make this easier.

This is usually referred to as 'tracking third-party sources' and requires knowledge of the CVS concepts branching, release tags, and the vendor tag. We'll work through an example here and explain these concepts as we go.

Example

Lets assume we'd like to track current Drupal CVS HEAD, and start by downloading the source. In this case we'll export using anonymous

CVS (we could also just download a tarball).

Begin by logging in to the anonymous CVS server, the required password is 'anonymous':

94 of 183

2010-05-10 cvs -d:pserver:[email protected]:/cvs/drupal login

Then export the newest development version of drupal using the HEAD release tag: cvs -d:pserver:[email protected]:/cvs/drupal export -r HEAD drupal

Now that we have a local copy of the drupal source we can import it into our own CVS repository. In this example we import with a log message including the date ' ', a module location/name of ' sites/drupal a vendor tag of ' drupal

-m "message text"

' and a release tag of '

CVS $ Id $ tags used on drupal.org):

HEAD20040110

' (customize that to suit your own CVS repository),

'. We also use the -ko option to prevent keyword expansion (this preserves the cd drupal cvs import -ko -m "Import CVS HEAD on Jan 10th 2004" sites/drupal drupal HEAD20040110

Before we can customize we need to checkout into a working directory. Then we can modify a file or files and commit: cvs checkout drupal cd drupal

...modify a file or files...

cvs commit

We now have a drupal module with a special 'vendor branch' (identified by the vendor tag), which contains the drupal source files we imported, and a main trunk with our modified files. Any files modified at this point are now HEAD on the main trunk of the module, whilst the unmodified files remain HEAD on the vendor branch (HEAD being what is produced by cvs update

). For an individual file (fileone.php) the version history now looks like something like this:

HEAD

+-----+

[Main trunk] fileone.php *------------+ 1.2 +

\ +-----+

+---------+

[Vendor Branch] + 1.1.1.1 +

+---------+

(tag:HEAD20040110)

Windows CVSNT

On Windows using CVSNT, if you're having problems with binary files being imported as text (so that e.g. your *.png image files end up corrupted when you check them out), try cvs import -k+o ...

instead of cvs import -ko ...

Some experimentation (in CVSNT 2.5.03 on Vista) suggests that specifying "-ko" on the command line may override the default "-k 'b'" flag specified for *.png files in $CVSROOT/cvswrappers, while "-k+o" works OK.

See also: http://www.cvsnt.org/manual/html/Wrappers.html

. (Note that this will not change flags for files you have already imported into a repository, see http://www.cvsnt.org/manual/html/Binary-howto.html

for information on how to fix these individually).

Additional resources

Article by Nick Patavalis : The mechanics and a methodology for tracking 3rd party sources with CVS

The section “Tracking third-party sources” in the CVS manual

The section “Tracking third-party sources” in a book on CVS

Managing contributions

Now I've been thinking about the best way to extend this method to incorporate contributions (eg, modules from the separate drupal.org

contributions CVS repository or any other non-drupal-core code). I would welcome comments/suggestions on a good model.

The model I'm currently using:

1. Maintain updated working copies of drupal HEAD and contributions HEAD from drupal.org locally, something like:

[HOST:~/drupal]$ ls -1 contributions drupal imports

2. Import drupal into my local CVS repository with vendor/release tags as per method outlined above .

3. Maintain customized versions of drupal using CVS branches which can be diff'd/updated against the latest drupal I've imported into my local CVS repository as suggested at the end of the method above .

4. Make a temporary copy of the complete, updated directory of whatever contribution I want to add to drupal's core in a different and otherwise empty local directory so I can import it to my local CVS repository alone. For example, say I want to include the event module:

[MP:~/drupal/contributions/modules]$ cp -r event ../../imports

[MP:~/drupal/contributions/modules]$ cd ../../imports/

[MP:~/drupal/imports]$ ls -1a

event

5. Import the contribution with its own vendor/release tags into the proper place in the HEAD branch of drupal I already have in my local

CVS repository. In this example, I import the entire event module from the temporary directory that contains the event module directory and only that directory. Note how the event module is imported into the proper directory (ie, "drupal/modules") of the drupal project in my local CVS repository:

[MP:~/drupal/imports]$ cvs import -ko -m "Import module event HEAD on 04 OCT 2004" drupal/modules module_event

MODULE_EVENT_20041004

95 of 183

2010-05-10 cvs import: Importing /home/mediaped/repos/drupal/modules/event

I drupal/modules/event/CVS

N drupal/modules/event/CHANGELOG

N drupal/modules/event/CREDITS

N drupal/modules/event/INSTALL

N drupal/modules/event/LICENSE

N drupal/modules/event/README

N drupal/modules/event/TODO

N drupal/modules/event/event.css

N drupal/modules/event/event.module

N drupal/modules/event/event.mysql

N drupal/modules/event/event.pgsql

N drupal/modules/event/fields.inc

cvs import: Importing /home/mediaped/repos/drupal/modules/event/po

I drupal/modules/event/po/CVS

N drupal/modules/event/po/event.pot

N drupal/modules/event/po/de.po

N drupal/modules/event/po/es.po

N drupal/modules/event/po/he.po

N drupal/modules/event/po/hu.po

No conflicts created by this import

6. Now the contribution is included in the HEAD of the drupal project in my local CVS repository, so if I update a working copy of that local drupal project (using the update -d option to ensure I get any new contribution directories) or checkout a new HEAD working copy, the newly added contribution will be in that working copy.

7. And, if I would like to add the contribution to one of the branches I have to maintain customized, separate versions of drupal, I just need to update a working copy of that branch with the release tag I established when importing the contribution into my local CVS repository. For example, to get the event module in a working copy of a branch tagged "drupalcustomA":

[MP:~/projects/drupalcustomA]$ cvs -q up -d -j MODULE_EVENT_20041004

U modules/event/CHANGELOG

U modules/event/CREDITS

U modules/event/INSTALL

U modules/event/LICENSE

U modules/event/README

U modules/event/TODO

U modules/event/event.css

U modules/event/event.module

U modules/event/event.mysql

U modules/event/event.pgsql

U modules/event/fields.inc

U modules/event/po/de.po

U modules/event/po/es.po

U modules/event/po/event.pot

U modules/event/po/he.po

U modules/event/po/hu.po

Note: if you try an update using your new tag and cvs complains that the tag doesn't exist, apparently you have to keep trying different cvs commands using that tag until cvs updates CVSROOT/val-tags. Once you get the tag to work once, it will work from then on. See the section here on error "cvs [checkout aborted]: no such tag".

8. This adds the event module files to that working copy, but I still have to commit them to that branch in my local CVS repository:

[MP:~/projects/drupalcustomA]$ cvs -q ci -m "adding event module"

Checking in modules/event/...

...

done

9. Then I can see that the event module is now a part of that branch by checking the status -v of one of the event module files:

[MP:~/projects/drupalcustomA]$ cvs st -v modules/event/INSTALL

===================================================================

File: INSTALL Status: Up-to-date

Working revision: 1.1.2.1 Tue Oct 5 06:46:30 2004

Repository revision: 1.1.2.1 /repos/drupal/modules/event/INSTALL,v

Sticky Tag: drupalcustomA (branch: 1.1.2)

Sticky Date: (none)

Sticky Options: -ko

Existing Tags:

drupalcustomA (branch: 1.1.2)

MODULE_EVENT_20041004 (revision: 1.1.1.1)

module_event (branch: 1.1.1)

10. Later, if there are significant changes to the event module, I'll update it using the same vendor tag, but a different release tag, just as it is demonstrated in the method above for drupal itself. My local drupal head will get the latest event module and I can get it in my customized branches by updating them with the new release tag I make when importing the new event module.

11. I will import every contribution I wish to include in my local CVS repository this way, giving unique vendor/release tags to each. That way I can pick and choose which contributions are included in any of my customized branches of drupal by updating each branch with the release tags of only the contributions I want in that branch.

Updating the vendor branch

At some later point the drupal source code will have been updated and we'll want to add the updated version to our repository. We do this by repeating the process described above, we get a fresh copy of the source from drupal.org, and import using the same vendor tag but change the release tag from '

HEAD20040110

' to reflect the newer version: cvs import -ko -m "Import CVS HEAD on Jan 11th 2004" sites/drupal drupal HEAD20040111

This updates the vendor branch, a single files revision history can now appear four different ways, depending on whether it has been modified by us, by the vendor (drupal.org), by both, or not at all.

If the file was modified only by us, our modified version remains the head revision:

HEAD

+-----+

[Main trunk] fileone.php *------------+ 1.2 +

\ +-----+

96 of 183

2010-05-10

+---------+

[Vendor Branch] + 1.1.1.1 +

+---------+

(tag:HEAD20040110)

If the file was modified only by the vendor, the new version becomes the HEAD revision:

[Main trunk] filetwo.php *

\ HEAD

+---------+ +---------+

[Vendor Branch] + 1.1.1.1 +----------+ 1.1.1.2 +

+---------+ +---------+

(tag:HEAD20040110) (tag:HEAD20040111)

And if the file was modified by both us and the vendor:

HEAD

+-----+

[Main trunk] filethree.php *------------+ 1.2 +

\ +-----+

+---------+ +---------+

[Vendor Branch] + 1.1.1.1 +----------+ 1.1.1.2 +

+---------+ +---------+

(tag:HEAD20040110) (tag:HEAD20040111)

Our version of filethree.php remains the HEAD revision, but this is clearly not desirable since it doesn't carry the latest changes. In fact, during our import of the latest source CVS would have warned us of conflicts between the two versions of filethree.php, we need to merge the changes to remove this conflict: cvs checkout -jHEAD20040110 -jHEAD20040111 drupal

Examine the merged file to ensure the changes CVS made were sane and then ‘ cvs commit

’ the changes back to the main trunk. Leaving us with a new revision which becomes HEAD:

HEAD

+-----+ +-----+

[Main trunk] filethree.php *------------+ 1.2 +-------+ 1.3 +

\ +-----+ +-----+

+---------+ +---------+

[Vendor Branch] + 1.1.1.1 +----------+ 1.1.1.2 +

+---------+ +---------+

(tag:HEAD20040110) (tag:HEAD20040111)

Summary

It should now be clear that using the CVS vendor tag to create a vendor branch in your own drupal module you can track changes to the drupal source code whilst also maintaining and developing your own customizations and new features for drupal. This example has been kept very simple for the purposes of explanation, but the basic process can be used to achieve many different things, some examples:

Track a specific release of Drupal (e.g. 4.3, or 4.2), instead of the development (CVS HEAD) version.

Maintain your customized sites with modules, themes, static pages, images etc all added to your CVS repository, whilst still tracking and importing updates to the drupal core.

Branch your module to maintain several customized web sites off a single tracked branch of the drupal core.

Reading the following additional resources is highly recommended.

Configuring Apache and PHP for Drupal in a Shared

Environment

These are some simple guidlines for setting up Drupal on a classic Linux-Apache-MySQL-PHP (LAMP) stack that provides a fair amount of security for the rest of your system.

PHP Configuration

To start, some common PHP configuration options can be optimized. On some systems, these settings may already be set, but it never hurts to add them yourself just in case.

PHP settings can be controlled in a number of ways. If you have access to the best place to do so is in your Drupal installation's settings.php

file.

php.ini

configuration file (usually found at

/etc/php.ini

), you can simply edit this file to cause system-wide changes. If you'd prefer to make these changes just for your Drupal installation, however, the

1. First, increase PHP's memory limit to avoid getting out-of-memory errors when you begin to add a few modules. These errors may look something like this:

Fatal error: Allowed memory size of 8388608 bytes exhausted (tried to allocate 30720 bytes) in

/path/to/drupal/modules/system/system.module on line 1022

2. In your php.ini

file, include a line that reads: memory_limit = 16M

. Or…

97 of 183

2010-05-10

3. …in your settings.php

file, include a line that reads:

<?php

ini_set ( 'memory_limit' , '16M' );

Apache Virtual Host Configuration

If you have access to your system's Apache configuration files (typically

/etc/httpd/httpd.conf

also make some simple changes to simplify Drupal's multisite configuration for subdomains.

/etc/apache2/httpd.conf

), you can

ServerName example.com

# Including a wildcard ServerAlias will direct all traffic to your end

# users site and simplifies using Drupal's multisite configuration for

# subdomains.

ServerAlias *.example.com

# This path will vary depending on your system. If you are using debian

# make sure you drop the default images alias. Leaving it can be very

# annoying to users on shared servers.

DocumentRoot /var/www/example.com/public_html

# Place the log where your end users can see them, and make sure they

# are at the least readable to an end user.

# Performance option:

# You can move the Apache logs to another partition or drive to

# get some small increases in disk i/o on heavily loaded servers.

# You can symlink the log files to /var/www/example.com/logs/

# to keep the persistent user interface, however it doesn't work in

# chroot environments.

ErrorLog /srv/www/example.com/logs/error.log

CustomLog /srv/www/example.com/logs/access.log combined

# Allow end users to manipulate their virtual hosts to their

# hearts' content by enabling .htaccess files for them.

AllowOverride All

# Since mod_php doesn't like you to respect su_exec, and safe_mode is just

# too paranoid to be usable, restrict php to the proper vhost but to a level

# above the DocumentRoot so users have some private file space for

# .htpasswd, Drupal files, backups, etc.

php_admin_value open_basedir /var/www/example.com

# Move PHP's temporary files into the open_basedir restricted space.

php_admin_value upload_tmp_dir /var/www/example.com/tmp

# session.save path isn't really necessary for drupal since it

# stores sessions in the database, but for general php enabled

#vhosts it keeps session data tied to each vhost.

php_admin_value session.save_path /var/www/example.com/tmp

MySQL Performance Optimization

Tweaking the configurations for your MySQL database server can give you a boost in performance. The MySQL configuration file is typically

/etc/my.cnf

# big ol mysql.querycache(128M) (be aware of your systems memory limitations) query_cache_size = 134217728

# boost mysql max connections (min = (20*number of drupal sites)) set-variable=max_connections=512 eacclerator

ModSecurity Considerations

ModSecurity is an Apache module that applies a set of rules to the activities of software run on Apache. It is used by some hosting environments to assure security, but some rules can interfere with the normal operation of Drupal. Because each ModSecurity administrator can write their own rules it is impossible to be certain that Drupal does not get caught up in these rules.

It is possible for Drupal to get caught correctly. Before implementing the solutions below to turn of part or all of ModSecurity, be sure that Drupal is being caught improperly. Be certain that the activity being stopped is not due to some malicious or potentially dangerous activity and that the security of your site will not be compromised.

It is possible, given the right permission or cooperation from your hosting company, to either turn off specific rules for your site or turn

ModSecurity off entirely for your VirtualHost.

Turning off a Rule

If you can find the errors put in the logs when your Drupal installation fails, you can identify the Rule ID and the location. Using this information you can disable a rule based on a path. Here is an example based on a rule ID of 990011 that interferes with the Drupal update script at /update.php. In many environments, these log entries are not available to the hostee and must be examined by the hoster.

98 of 183

2010-05-10

Here is an example of a what will appear in the logs. You'll note the Rule ID and path are bold.

[Wed Jan 20 11:43:01 2010] [error] [client 2.1.6.1] ModSecurity: Access denied with code 501 (phase 2). Match of "rx (?

:^(?:application\\\\/x-www-form-urlencoded(?:;(?:\\\\s?charset\\\\s?=\\\\s?[\\\\w\\\\d\\\\-]{1,18})?)??$|multipart/formdata;)|text/xml)" against "REQUEST_HEADERS:Content-Type" required. [file

"/etc/apache2/modsecurity_crs/modsecurity_crs_30_http_policy.conf"] [line "69"] [id "960011"] [msg "Request content type is not allowed by policy"] [severity "WARNING"] [tag "POLICY/ENCODING_NOT_ALLOWED"] [hostname

"d6test.domain.com"] [uri "/update.php"] [unique_id "R5esoc-ASakAAHGeOqAAAAAI"]

SecRuleRemoveById 990011

</LocationMatch>

Turning ModSecurity Off

If you can change the VirtualHost record, this may be used to turn off ModSecurity for a specific VirtualHost.

SecRuleEngine off

</ifModule>

Enable hosting of multiple sites from a single installation

If you are running more than one Drupal site, you can simplify management and upgrading of your sites by using the multi-site feature.

Multi-site allows you to share a single Drupal installation (including contributed modules and themes) among several sites. This is particularly useful for managing the code since each upgrade only needs to be done once.

Each site would continue to have its own database and its own configuration settings so each site would have entirely different content and you can still specify the theme, modules and other settings for each site.

Configure a new site

To create a new site using a shared code base you must complete the following steps:

1. Create a new database for the site.

2. Create a new subdirectory of the 'sites' directory with the name of your new site.

3. Copy the file sites/default/default.settings.php

into the folder you created in the previous step. Rename the new file to settings.php

4. Adjust the permissions of the new site directory, and grant write permissions on the configuration file

5. In a web browser, navigate to the URL of the new site and continue with the standard Drupal installation procedure.

It may also be necessary to modify your Web server's configuration file (often named httpd.conf

for Apache) to allow Drupal to override

Apache's settings. This is true for all installations of Drupal and is not specific to the multi-site install. Additional information is available in the

Best Practices: Configuring Apache and PHP for Drupal in a Shared Environment section of the Installation Guide.

Domains and URLs

The new directory name is constructed from the site's URL. The configuration for sites/example.com/settings.php

www.example.com

. You do not need to include 'www' as part of the directory name.

would be in

Any sub-domain of example.com

, including www, is served from that directory's settings unless there is an alternative, matching sub-domain sites directory. Installing a separate site in a sub-folder is also possible. For example, example.com, sub.example.com, and sub.example.com/site3 can all be defined as independent Drupal sites using the following directory setup: sites/example.com/settings.php

sites/sub.example.com/settings.php

sites/sub.example.com/site3/settings.php

Installing Drupal in a sub-folder is accomplished by adding a slash after the domain name and then the name of the sub-folder, as in the site3 example above.

If you are installing on a non-standard port, the port number is treated as the deepest sub-domain. For example: http://www.example.com:8080 could be loaded from sites/8080.example.com

if no port-specific configuration is found, just like a real sub-domain.

. The port number will be removed according to the pattern above

Domain-specific modules and themes

Each site configuration can have its own site-specific modules and themes in addition to those installed in the standard 'modules' and

sites/sub.example.com/themes/custom_theme sites/sub.example.com/modules/custom_module

99 of 183

2010-05-10

Document root

One area of frequent confusion is that in a Drupal multisite installation the webserver document root is the same for all sites. For example with the following three sites: example.com, sub.example.com and example.com/site3 there will be a single Drupal folder and all sites will be calling the same index.php file.

Some webhosts automatically create a folder (i.e. example.com) when creating a new domain. In this case it is necessary to create a symbolic link to the main Drupal folder.

Localhost

Domain name changes

Once a site is in production under the folder sites, it should not be renamed, even if the Web site URL changes. This is because several database tables (for example: system, and files) include references to "sites/www.mydomain.com." Of course, instead of renaming the sites directory, you can create a symlink to the new URL from the old one. Navigate to the sites directory and then use the following command:

$ ln -s /path/to/drupal/sites/old.domainname.com new.domainname.com

Comprehensive Multi-site Video

Running a successful multi-site install requires knowledge of how Drupal handles multiple sites and how various features of Apache can be leveraged to make the multi-site much easier to manage.

The video at this link provides a great deal of detail and comprehensive conf files for an Apache multi-site install of Drupal

Video about Multisites vs. Multiple Sites at GotDrupal.com

Multi-site how-tos

Do I need to copy each of these pages over to d7 or just reference them?

Do we need to prune or rearrange them?

Some of it seems redundant to other pages already created.

http://drupal.org/node/43816

Multi-site on Linux

Software installed:

Drupal 7

Apache 1.3

Red Hat 6.1 (Although other distributions will work)

PHP5

PostgreSQL 7.4

The process:

1. Install the Drupal core download from Drupal.org.

2. Install default Drupal site. I created mine with a "dummyUSER" user and "dummyDB" database with Drupal code in apache/htdocs/drupal

3. Once you have this working then create a new dir "example1.com" directly under "sites" dir.

mkdir sites/example1.com

cp -R sites/default/* sites/example1.com/

4. Create a new database "example1DB" and new user "example1USER" in database.

5. Edit the

sites/example1.com/settings.php

and change the following:

$db_url = 'pgsql://dummyUSER:dummyPSSWDl@localhost/dummyDB'; to

$db_url = 'pgsql://example1USER:example1PSSWDl@localhost/example1DB';

(this step is optional, normally Drupal will recognise the base url automatically):

# $base_url = 'http://www.example.com'; to

$base_url = 'http://www.example1.com';

(Remove the '#' [comment])

6. cp apache/htdocs/drupal/install.php to apache/htdocs/drupal/sites/example1.com/

7. Point your browser to www.example1.com

. Drupal will show you lot of errors.

8. Once it shows you errors you are all good. Just point your browser to www.example1.com/install.php

and it will present you the installation screen. Install from there on.

9. Repeat the above process for www.example2.com

100 of 183

2010-05-10

Note

If it says the site is offline then your database information in settings.php is not correct. If it says site not found then your base url in settings.php is not correct.

Multi-site on Mac

To get multi-sites working on apache on a Mac, see "HowTo: Configure your local workstation to serve multiple sites using Drupal's multisite configurations and Apache's VirtualHost" .

Multi-site on Windows-Apache

Software

This guide assumes you have installed WAMPServer, which you can download below:

WampServer - includes Apache, PHP, and MySQL.

Alternatively, you can install another WAMP package, but you will need to adjust the paths as necessary.

Process

1. Set up Drupal as usual

1. Install WampServer (or another 'WAMP' package) and make sure that Apache and MySQL services are running.

2. open phpMyAdmin in your browser

3. Create a new database -- we'll call it

drupal6 drupal6

installation, but then leave it alone.

2. Prepare the files for your new multi-sites

because this will be our base installation which we will leave untouched. While you're here create a second and third database, which we'll call

database and user settings ( contributed modules together in the

2. Use a text editor to open the database, and the database user name and password, eg:

(or it can be launched via the WampServer icon in your system tray.)

site1

1. Find Drupal's simple, we'll make it the same as the first test site database: within this new folder. The can create a

and but to keep things simple here, we'll stick with the default user

4. Download Drupal 6 into WampServer's

wamp/www

a tool like 7-zip to unpack the Drupal tar.gz file).

folder (or the

htdocs

folder in Xampp and some other packages). (You'll need

5. Do your first Drupal installation by pointing your browser to your Drupal folder, which should be something like http://localhost/drupal-6.x

. Enter the

sites localhost/phpmyadmin

folder, make a copy of the

modules themes root site2

. You can also change the database privileges if you want,

and no password.

root

and no password in this example). Complete the

sub-folder will be used for any custom theme you create specifically for this site. Similarly, you

sub-folder for any module you use only with this site. However, generally, I find it easier to keep all

sites/all/modules settings.php

default

folder and rename it to the URL you want for your first test site. To keep it

site1

. While you're here, create

files, tmp

folder so I can use them with all my test sites.

file in your new

site1

folder and change

$db_url

and

themes

sub-folders

line to reflect your first test site mysql://username:password@localhost/site1

Also, change the $base_url to the above site URL, eg:

$base_url = 'http://site1';

// NO trailing slash!

3. Repeat the above 2 steps for the other test site (

site2

)

3. Adjust windows so it can find the new site at a new made-up name

Find the Windows

hosts

file, which should be in Windows'

System32/drivers/etc

folder, make a backup of that file and then open the

hosts

file in a text editor. Here, add new lines mapping your localhost IP address to match the URLs of your test sites and your original

Drupal site. In our example, it would look like this:

127.0.0.1 localhost

127.0.0.1 site1

127.0.0.1 site2

127.0.0.1 drupal6

This is telling Windows Networking that http://site1/

is

a name for this machine.

4. Adjust Apache so it responds to requests for the new names

1. Find the Apache

httpd.conf

version number). Sorry, I can't remember where Xampp installs this, but it will be in the Apache folder. Anyway, all you need to do with this file is make sure the "Virtual hosts" line is active by removing the

2. Make a backup of that editor and add these lines:

file which, in WampServer, should be in the

httpd-vhosts.conf

file (which is in Apache's

wamp/bin/ApacheX.X/conf conf/extra

before

Include conf/extra/httpd-vhosts.conf

folder), then open

folder (where X.X is the Apache

httpd-vhosts.conf

with a text

DocumentRoot C:/wamp/www/drupal-6.x

ServerName site1

</VirtualHost> where

C:/wamp/www/drupal-6.x

is the path to the Drupal installation folder and localhost URL (if you want to keep this active), eg:

site1

is the URL for your first test site. Add another entry for your other test site, another entry for your original Drupal installation and another entry for WampServer's

DocumentRoot C:/wamp/www/drupal-6.x

ServerName site2

</VirtualHost>

101 of 183

2010-05-10

DocumentRoot C:/wamp/www/drupal-6.x

ServerName drupal6

</VirtualHost>

DocumentRoot C:/wamp/www

ServerName localhost

</VirtualHost>

3. Restart Apache for the changes to take effect. With WampServer, this is done by selecting the WampServer icon in the system tray and then "Restart all services".

5. Now you're ready to install each Drupal test site using your browser, eg: http://site1/install.php

http://site2/install.php

And that's it. You can access your two test sites anytime WampServer is running by using the http://site1 and http://site1 URLs.

As I said, it's not exactly simple, but it is well worth the effort. Now you can do whatever you like with your test sites. If you mess up with, say, site1, just delete the

site1

folder, the

site1

database in phpMyAdmin and the site1 entries in the Windows

hosts

and Apache

httpdvhosts.conf

files and start again. Alternatively, if a site works out and you want to go live with it, the multi-site approach makes this easier

(in my opinion).

Multi-site on Windows-IIS

Prerequisites

This guide assumes you have the following installed and running:

Microsoft's Internet Information Services web server 6 or 7

PhP 5.2 or higher with PDO dlls enabled .

The IIS FastCGI Module ( IIS6 version here - in IIS7 it's an integrated module that needs to be enabled).

MySQL

If you want clean urls, you'll also need the URL Rewrite module (IIS7) or a third-party url-rewrite module set up at some point, though you can do this afterward.

Process

1. Install a site. This will be the parent site, providing the code-base for all the child sites.

IIS7: be sure your parent site has a web.config file (see this for more info). Child sites will use the settings in the parent site's web.config file. To override these settings, put a web.config file with just the settings you want to override in the child site's folder (eg sites/site2.com/).

2. Create child site folders. Decide how you want people to navigate to your sub-site. In the parent site's /sites/ folder, create subfolders for each new site you wish to install.

Example 1: parentsite.com/subsite/ - in parent /sites/ folder, create /sites/parentsite.com.subsite

Example 2: subsite.parentsite.com - in parent /sites/ folder, create /sites/subsite.parentsite.com

Example 3: subsite.com - in parent /sites/ folder, create /sites/subsite.com

3. Copy the files & private subfolders. Go into the parent site's sites/default folder, and copy the /files and /private folders. Navigate to each new child site's folder (eg sites/parentsite.com/subsite/) and paste them.

4. Create child site settings.php file(s). Into each child site folder copy the parent's /sites/default/settings.php. Make each settings.php writable to IIS_WPG (IIS6) or IIS_IUSRS(IIS7).

5. Create IIS Site Mapping or Virtual Directory, depending on how you set up your site structure.

IIS7 - Start the IIS Manager.

Example 1: parentsite.com/subsite/ - Right-click on parentsite.com | Add virtual directory. Alias: [new site name, eg subsite].

Physical path: [parent site's physical path]. Click OK.

Example 2: subsite.parentsite.com - Right-click on Sites | Add web site. Site name: [new site name, eg site2]. Click to select the application pool, and select the parent site. Physical path: enter the parent site's physical path. Host name: [new site url, eg site2.localhost]. Click OK.

Example 3: subsite.com - add a web site as example 2, calling the host name subsite.com.

6. Set up the database(s).

Multiple databases - If you want each site to have it's own database, create them now.

For each child site, change settings.php to include each site's database name, username, and password:

$databases['default']['default'] = array(<br />

'driver' => 'mysql',<br />

'database' => 'databasename',<br />

'username' => 'username',<br />

'password' => 'password',<br />

'host' => 'localhost',<br />

);

Single database - See this tutorial.

102 of 183

2010-05-10

7. Run the setup script for each site, eg http://site2.localhost/install.php

Multi-site with single codebase, different content databases, shared user database, shared sign-on

IMPORTANT NEW INFORMATION - In light of this comment regarding the ability of Drupal to handle different databases this HOWTO has been re-written. You do not need to use MySQL views at all to achieve this functionality.