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 thedocroot
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 yourdocroot
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
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
- Log in to your server, and then navigate to your Drupal
docroot
directory.ssh -l username example.com cd path/to/docroot
- Copy and rename
/sites
to new location outside of the Drupaldocroot
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
- Rename the old copy of
/sites
and keep it until you are sure the new copy is working as expected.mv sites backup-sites
- 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
- Test your website to ensure it is functioning as expected.
- Delete the
/backup-sites
directory if your website is functioning as expected.rm -r backup-sites
Creating a symlink for docroot
- 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
- 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. - Make backups of your website’s files and database.
- 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 thedocroot
symlink and make a new one that points at the newdocroot
directory.For more information about upgrading Drupal, see either Upgrading from previous versions on drupal.org or Upgrading Acquia Drupal.