Knowledge Base

How to configure Drush site aliases for Drupal

This article describes how to configure Drush site aliases that work with Drupal sites hosted on A2 Hosting accounts.

About Drush site aliases

Drush site aliases enable you to set up SSH-based connections from a local computer to a remote Drupal site. (You can also configure site aliases for use with local Drupal sites, but this article focuses on remote Drupal sites only.) With correctly configured Drush site aliases, you can invoke Drush commands on your local computer that run on remote Drupal sites.

The command-line environment used by Drush opens up many possibilities for Drupal site management. For example, you could use Drush site aliases in a Bash script to update multiple remote Drupal sites all at once.

Configuring Drush site aliases

To define a Drush site alias, follow these steps:

  1. On your local computer, go to your home directory:
    • On Linux, this is usually the /home/username directory.
    • On Apple Mac OS X, this is usually the /Users/username directory.
    • On Microsoft Windows, this is usually the \Users\username directory.
  2. Open the .drush subdirectory in your home directory.
  3. In the .drush subdirectory, create a file named sitename.aliases.drushrc.php. Replace sitename with a descriptive name for your site. (Then if you define multiple site aliases, you will be able to remember which alias is associated with which site.)
  4. Copy and paste the following sample configuration into the sitename.aliases.drushrc.php file. Replace sitename with the site name you used in the filename, replace username with your own A2 Hosting account username, and replace example.com with the domain name where the Drupal site is hosted. If you installed Drupal in a subdirectory beneath the public_html directory, add it to the root path value as well:

    <?php
        $aliases['sitename'] = array(
            'root' => '/home/username/public_html',
            'remote-host' => 'example.com',
            'remote-user' => 'username',
            'ssh-options' => '-p 7822'
        );
    ?>
    

    This configuration shows only the essential settings for connecting to a remote Drupal site. There are many other options available for site alias configuration files. For a complete list and examples, please visit https://github.com/drush-ops/drush/blob/master/examples/example.aliases.drushrc.php.

    One notable exception to available site alias options is SSH passwords. You cannot specify an SSH password in the alias configuration. Therefore, if you do not want to type the SSH password every time you use a remote site alias, you must set up SSH keys for your A2 Hosting account. For information about how to set up SSH keys, please see this article.
  5. Save your changes to the sitename.aliases.drushrc.php file.

Using Drush site aliases

After you configure a remote site alias, you can use it to manage Drupal sites on your A2 Hosting account. For example, to view the status of a remote Drupal site, type the following command. Replace sitename with the site name that you used to name the sitename.aliases.drushrc.php file:

drush @sitename status

Similarly, to update the remote site, type the following command:

drush @sitename up

You can run any drush command by prefixing it with @ and the site alias name.

To list the site alias files on your local computer, type the following command:

drush status

The site aliases are listed under the Drush alias files heading.