Adding flexibility to your server structure using symlinks

A symbolic link, commonly called a symlink, is a file that contains the absolute or relative path to another file or directory on your server, and you can use them to help streamline your server maintenance and Drupal file structures. Your server and Drupal site read and write to the symlink’s target files or directories directly, as though they were present in the symlink’s location. In some cases, symlinks may be required for proper site operation on Acquia Cloud.

If you have a Drupal site with a large amount of uploaded content, you can keep the /sites or /files directories outside of your Drupal codebase, and then link to them. If you need to run multiple versions of Drupal, you can use this to share when you need to. On Acquia Cloud, symlinks to the /files directory are made automatically.

  • Run and maintain multiple Drupal versions

    If you have several sites on your server that use different versions of Drupal, you can point each site to its appropriate Drupal docroot using a symlink, allowing you to a point to the docroot of a newer core version of Drupal when you upgrade.

  • Faster updates

    When you update to a newer version of Drupal, instead of having to copy the whole /files directory to the new Drupal codebase, you can simply add a symlink to the external /sites directory.

  • Enhanced data security

    Since you don't need to move the contents of the /sites directory, you don't risk loss or corruption of your data while moving it to a new location.

  • Safer core upgrades

    If you are using the Acquia Drupal code repository, it will respect the symlink to /sites in your docroot directory and continue to use the symlink. Note that during updates you’ll still have to manually update the themes and modules not included in Acquia Drupal that you install within your external /sites directory.

    If there are upgrade issues during a core upgrade, you can revert to an older, backed up version of your database by changing the symlink to link to the older codebase, and then reimporting the backed-up database.

How to create symlinks

The basic command to create a symlink is:

ln -s [path/to/link/target] [link_name]

where:

  • [path/to/link/target] - The link’s target.
  • [link_name] - The link’s name. It can also be a path to place the symlink in any location. The last part of the second link is the link’s name. For example:

    ln -s [path/to/link/target] [path/to/symlink/location/link_name]

Examples

Here are some examples for creating symlinks in general, and symlink to /sites or /files, or your docroot

Creating a symlink for /sites

  1. Log in to your server, and then navigate to your Drupal docroot directory.

    ssh -l username example.com

    cd path/to/docroot

  2. Copy and rename /sites to new location outside of the Drupal docroot directory. Renaming /sites helps you to avoid potential naming conflicts, and you have the chance to aid your own memory in the future. Choices could include “my_Drupal5_sites” or “client_sites” and so on. Note that this command should begin with at least one “../” - meaning “move up one level in the directory hierarchy” - if you don’t, you’ll be renaming the directory where it is, not moving it to a new location.

    cp -r sites ../path/to/new-location/new-name

  3. Rename the old copy of /sites and keep it until you are sure the new copy is working as expected.

    mv sites backup-sites

  4. Create a symlink to the new /sites directory. We must call the symlink /sites so that Drupal continues to function.

    ln -s path/to/new-sites-directory sites

  5. Test your site to ensure it is functioning as expected.
  6. Delete the /backup-sites directory if your site is functioning as expected.

    rm -r backup-sites

Creating a symlink for docroot

  1. For each version of Drupal that you use, create a symlink that links to the current Drupal installation. For example, for Drupal 6.x you could use d6_docroot.

    ln -s path/to/drupal-6-codebase d6_docroot

  2. If you're hosting your own site, you can configure Apache to use that symlink as the docroot for any request to your Drupal website running that version of Drupal. The exact configuration method varies depending on your server's operating system.
  3. Make backups of your site’s files and database.
  4. When you upgrade to a new core Drupal version, perform all upgrade steps as usual, but instead of renaming the old and new docroot directories, delete the docroot symlink and make a new one that points at the new docroot directory.

    For more information about upgrading Drupal, see either Upgrading from previous versions on drupal.org or Upgrading Acquia Drupal.