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
/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
docrootusing a symlink, allowing you to point to the
docrootof 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
/filesdirectory to the new Drupal codebase, you can simply add a symlink to the external
- Enhanced data security
Since you don't need to move the contents of the
/sitesdirectory, 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
docrootdirectory 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
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
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
Here are some examples for creating symlinks in general, and symlink to
/files, or your
Creating a symlink for /sites
- Log in to your server, and then navigate to your Drupal
ssh -l username example.com cd path/to/docroot
- Copy and rename
/sitesto new location outside of the Drupal
/siteshelps 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
/sitesand keep it until you are sure the new copy is working as expected.
mv sites backup-sites
- Create a symlink to the new
/sitesdirectory. We must call the symlink
/sitesso 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-sitesdirectory 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
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
docrootfor 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
docrootdirectories, delete the
docrootsymlink and make a new one that points at the new