Drush Aliases

This section provides information on how to use Drush aliases.

Download Drush Aliases Locally

Downloading the Pantheon aliases to your local Drush aliases file allows you to run Drush calls against your Pantheon site environments.

1. Use Terminus to download your Drush aliases.

2. Authenticate Terminus with machine tokens, then update your local aliases file in a single step:

   terminus aliases

   This command will write both Drush 8 and Drush 9 aliases into the directory $HOME/.drush for your sites that you are a direct member of.

3. Run the command below to create aliases for all sites that you can use, including sites that you have access to via team membership:

   terminus aliases --all

You must download a new copy of your Drush aliases if you add a site to your account. You do not need to update your Drush aliases when you add new Mulitdev environments to your sites.

Structure of Site Aliases

The form Pantheon Drush aliases take depends on the version of Drush you use. Drush 8 aliases are all written to a single file, $HOME/.drush/pantheon.aliases.drushrc.php. A single alias record looks something like the example below:

$aliases['example.*'] = array(
  'uri' => '${env-name}-example.pantheonsite.io',
  'remote-host' => 'appserver.${env-name}.3eb7b5dd-8b90-4272-8a80-5474015c37f1.drush.in',
  'remote-user' => '${env-name}.3eb7b5dd-8b90-4272-8a80-5474015c37f1',
  'ssh-options' => '-p 2222 -o "AddressFamily inet"',
  'path-aliases' => array(
    '%files' => 'files',
   ),
);

Drush 9 aliases are written one file per site to the directory $HOME/.drush/sites/pantheon. The site name is used to generate the filename, e.g. example.site.yml. The contents of a Drush 9 alias file looks something like the example below:

'*':
  host: appserver.${env-name}.3eb7b5dd-8b90-4272-8a80-5474015c37f1.drush.in
  paths:
    files: files
  uri: ${env-name}-example.pantheonsite.io
  user: ${env-name}.3eb7b5dd-8b90-4272-8a80-5474015c37f1
  ssh:
    options: '-p 2222 -o "AddressFamily inet"'
    tty: false

Note that these are both "wildcard" aliases. The same wildcard alias is used for every environment available for a given site. The variable ${env-name} is replaced with the appropriate environment name when used.

Policy Files

Pantheon uses policy files to validate aliases before they are used. Policy files are written by the terminus aliases command.

• The Drush 8 policy file is written to $HOME/.drush/pantheon/drush8/pantheon_policy.drush.inc. Do not delete this file.

• The Drush 9 policy file is written to $HOME/.drush/pantheon/Commands/PantheonAliasPolicyCommands.php. Do not delete this file.

Manage Available Site Aliases

You can verify that your site aliases are available by listing every site alias known to Drush after the Pantheon Drush aliases have been copied. Note that Drush does not read alias files from global locations. You must set valid alias locations in your drush.yml file if you want to opt-in for this behavior.

List Site Aliases

Run the command below to view every site alias known to Drush:

drush sa

Add Site Aliases Locations

Drush does not read alias files from global locations. You can add alias locations in your drush.yml file. Files stored in one of the search path locations can be used to create aliases to local and remote Drupal installations. These aliases can be used in place of a site specification on the command line, and can also be used in arguments to certain commands such as:

• drush rsync
• drush sql:sync

1. Navigate to your ~/.drush/drush.yml configuration file.

2. Add the new alias search path location. The example below re-adds the default user alias path from Drush 8.

   drush:
     paths:
      alias-path:
         - '${env.home}/.drush/site-aliases'
        - /etc/drush

Drush Alias Strict Control

You can create strict control policies for your Drush aliases.

1. Create a file called policy.drush.inc, and place it in the .drush folder of your home directory. You can create a new file or use the example policy file in Drush’s examples folder to get started.

   Pantheon will select an arbitrary domain to include in the alias file that you download with Terminus if your live site is associated with multiple domains. In some instances, it can cause problems in Drupal if the wrong URI is used, and Drush will not allow you to override the URI value in the alias with a command line --uri option.

2. Use a hook_drush_sitealias_alter function in policy.drush.inc to change the URI for your specific Pantheon site to avoid editing the generated Pantheon aliases file every time it is downloaded:

   policy.drush.inc

   function policy_drush_sitealias_alter(&$alias_record) {
     // Provide the correct 'uri' for a specific site
     if ($alias_record['#name'] == 'pantheon.SITENAME.live') {
       $alias_record['uri'] = 'example.com';
     }:title=settings.php
   }

3. Replace SITENAME with your Pantheon site name, and example.com with the correct URI for that site.

More Resources

• Terminus Guide
• Pantheon YAML Configuration Files