Warning message

Documentation is currently being migrated into the new system. Some pages might be temporarily missing, and some guides might appear empty. Thank you for your patience while we are improving Drupal.org documentation.

Multi-site - Sharing the same code base

Last updated on
August 30, 2016 - 13:47

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 with multiple administrators. (See section"Security Concerns" 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 (if there is already an existing database you can also use this by defining a prefix in the installation procedure).
  2. Create a new subdirectory of the 'sites' directory with the name of your new site. See below or the comments in the default.settings.php file for information on how to name the subdirectory.
  3. Copy the file sites/default/default.settings.php into the subdirectory you created in the previous step. Rename the new file to settings.php.
  4. For Drupal 8 only: Activate the multi-site feature by copying (and renaming) the file sites/example.sites.php to sites/sites.php. There is no need to edit the file unless you need site aliases. The normal site selection rules applies.
  5. Adjust the permissions of the new site directory, and grant write permissions on the configuration file (settings.php).
  6. If you are using a subdirectory such as example.com/subdir and not a subdomain such as subd.example.com you probably have to create a symbolic link for each site. See the subdirectory multi-site section below for details.
  7. In a Web browser, navigate to the URL of the new site and continue with the standard Drupal installation procedure (if you get an infinite redirection loop, check if the file install.php exists the document root).

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.

           Back to Contents

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.

           Back to Contents

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:


           Back to Contents

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.

           Back to Contents

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 ...

To make it work read the subdirectory specific multi-site documentation - also if it happened to work for you.

           Back to Contents

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:

ln -s drupaldir subdir

and name your site folder localhost.subdir.

           Back to Contents

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

           Back to Contents

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.


Occasionally, Drupal is subject to security vulnerabilities, bugs which allow an unauthorised user access to Drupal core code. Once a hacker has access to your core code, they have access to all your multisites through one attack. Non-multisites require separate attacks, which may offer sufficient time for the vulnerability to be secured.

           Back to Contents

When to multisite

As a general rule on whether to use multisite installs or not you can say:

  • If the sites are similar in functionality (use same modules or use the same drupal distribution) do it.
  • If the functionality is different don't use multisite.

The Drupalcon Austin conversation/debate on multisite where the pros, cons, and some suggestions are discussed is available on youtube

This is because you want your sites to stay as up-to-date as possible regarding drupal module security updates and when you have different functionalities this is more difficult to do because it takes a little more time since you need to test each site independently. If you are doing multisite, then the update needs to be run at the same time for all the sites which is not always possible.

So sites with different functionality usually end up being upgraded at different times because each needs to be tested and backed up. Site updates and backups are also pretty easy to do and can be automated with drush, but drush has little support for multisite install.

           Back to Contents