Support Development Made Easy Using Drush Aliases

Odds are most Drupal Support Developers have found Drush to be an extremely useful command line tool for routine maintenance tasks such as generating one-time logins (drush uli), clearing caches (drush cc all or drush cr), or updating modules (drush up). And many more advanced commandline tasks!

But, executing Drush on remote environments requires some legwork. Every client's situation can be unique. Some client sites might be hosted on Acquia. Others on Pantheon. And still others on self-managed hosting by Rackspace, Amazon Web Services, etc. Databases might be hosted on separate scalable servers, and a database may only allow queries from the web server that is meant to utilize it.

SSH access to the site's remote server is a must for all things Drush, as is finding the web docroot location on that remote server. Finding and using server information - and keeping that information up to date - can be a chore. In the ever-increasing world of scalable computing, server addresses can change any time. So, keeping server information in sync with fellow teammates can be cumbersome.

Enter Drush Aliases

Drush aliases provide a means to not only track each client's unique server settings, but also these alias files can be tracked in version control (i.e. Git) right with your client's codebase.

Beginning with Drush 5.x, Drush will find alias files located in pre-defined locations when the developer is working on the command line within the site's docroot. Tracking alias files with a project's repository is then as secure as one's access to the repository. Drush Alias files are not meant to store any critical passwords, and SSH access to a remote environment is still required to perform any tasks on that remote environment.

Inspire yourself: Review the Drush Aliases example file

The Drush Aliases example file, available with the Drush project and viewable over on Github, is a great place to start when considering what information to track in a Drush Aliases file as well as where to track it (be it in a site repository or simply in a local machine's .drush directory.

Drush Aliases file naming convention

Aliases may be broken into multiple files called ALIASNAME.alias.rushrc.php, or they can be managed in one singular file using the convention GROUPNAME.aliases.drushrc.php.

Standardizing the Drush Aliases file location

As explained in the example file, the following locations are examined for alias files:

1. 1. In any path set in $options['alias-path'] in drushrc.php, or (equivalently) any path passed in via --alias-path=... on the command line.
2. 2. In one of the default locations:
   1.   a. /etc/drush
   2.   b. $HOME/.drush
3. 3. In one of the site-specific locations:
   1.   a. The /sites/all/drush folder for the current Drupal site  ← Drush 5.x & later
   2.   b. The /drush folder for the current Drupal site ← Drush 6.x & later
   3.   c. The /drush folder in the directory above the current Drupal site ← Drush 7.x & later

Of particular interest to my support workflow are the site-specific locations in bold above: /sites/all/drush for the current Drupal site, and /drush in the directory above the current Drupal site.

For Composer-based Drupal 8 sites, /drush in the directory above the current Drupal site is a fantastic place to store drush alias files. This location may also work well for newer Drupal 7 sites, but developers may find that their Drupal 6-7 servers are commonly running versions of Drush older than 7.x, which eliminates /drush as an option. For legacy verisons of Drush, /sites/all/drush is a great place to track alias files.

Make-up of a Drush Aliases file

The following is a sample of what information a Drush Aliases file might contain, as well as comments that explain the purpose of each line in the alias definition file:

/**
* Drush aliases for an Example Site
*/

/* Local environment: */
$aliases['local'] = array (
  // Define a URI for generating 1-time logins with "drush @local uli":
  'uri' => 'example.local',
  'path-aliases' => array(
    '%files' => 'sites/default/files' // Used for "drush rsync" commands.
  ),
  /* Allow sql overwrites in non-prod environments: */
  'command-specific' => array (
    'sql-sync' => array (
      // Negate the simulation defined below under the Prod section, for non-Prod environments:
      'simulate' => '0',
    ),
  ),
);

/* Vagrant environment: */
// This section is useful if locally hosting a site inside a Vagrant box.
$aliases['vagrant'] = array (
  // Define a URI for generating 1-time logins with "drush @vagrant uli":
  'uri' => 'example.local',
  // SSH hostname, for quickly entering the Vagrant host:
  'remote-host' => 'example.local',
  // SSH user, for quickly entering the Vagrant host.
  'remote-user' => 'vagrant',
  // Docroot location inside Vagrant, for bootstrapping Drush remotely from the host terminal:
  'root' => '/var/www/sites/example.local/www',
  'ssh-options' => '-o "StrictHostKeyChecking no" -o "UserKnownHostsFile=/dev/null" -o "LogLevel FATAL" -i "~/example/.vagrant/machines/default/virtualbox/private_key"',  
  // The private_key location above should be set to match the location of your Vagrant project.
  'path-aliases' => array(
    '%files' => 'sites/default/files', // Used for "drush rsync" commands.
  ),
);

/* Development environment: */
$aliases['dev'] = array (
  // Define a URI for generating 1-time logins with "drush @dev uli":
  'uri' => 'dev.example.com',
  // SSH hostname, for quickly entering the development server:
  'remote-host' => 'dev.example.com',
  // Docroot location, for bootstrapping Drush remotely:
  'root' => '/var/www/sites/dev.example.com/www',
  'ssh-options' => '-o "LogLevel FATAL"',
  'path-aliases' => array(
    '%files' => 'sites/default/files',
  ),
);

/* Staging environment: */
$aliases['test'] = array (
  'uri' => 'test.example.com',
  'remote-host' => 'test.example.com',
  'root' => '/var/www/sites/test.example.com/www',
  'ssh-options' => '-o "LogLevel FATAL"',
  'path-aliases' => array(
    '%files' => 'sites/default/files',
  ),
);

/* Live Production environment: */
$aliases['prod'] = array (
  'uri' => 'www.example.com',
  'remote-host' => '123.456.78.9',
  'root' => '/var/www/sites/example.com/www',
  'ssh-options' => '-o "LogLevel FATAL"',
  'path-aliases' => array(
    '%files' => 'sites/default/files',
  ),
  // Prevent accidental sql-sync and rsync overwrites in Prod:
  'command-specific' => array (
    'sql-sync' => array (
      'simulate' => '1',
    ),
    'sql-drop' => array (
      'simulate' => '1',
    ),
    'sql-create' => array (
      'simulate' => '1',
    ),
  ),
);

You may notice that in the example above, I have excluded 'remote-user' from the Dev, Staging, and Production environment alias definitions. In many cases, the SSH login for each developer may be unique to that developer and therefore should not be tracked in the Drush Aliases file. Instead, this information can be tracked in your SSH configuration file. For *nix systems, this file is located at ~/.ssh/config, and the Host defition for the example site above might look like this:

# Example.com Dev/Staging
Host example.com *.example.com
  User myusername