Adding flexibility to your server structure using symlinks

    See more
    • Updated

    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 website 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 website operation on Acquia Cloud.

    If you have a Drupal website 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 websites on your server that use different versions of Drupal, you can point each website to its appropriate Drupal docroot using a symlink, allowing you to 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 /sitesdirectory.

      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

    Note that Windows will convert symlinks to flat files. See https://github.com/git-for-windows/git/wiki/Symbolic-Links for instructions on how to successfully create symlinks in Windows.

    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 website to ensure it is functioning as expected.
    6. Delete the /backup-sites directory if your website 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 7.x you could use d7_docroot. 
      ln -s path/to/drupal-7-codebase d7_docroot
    2. If you're hosting your own website, 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 website’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.

     

    Related articles