rsync and SFTP

Transfer large files using an SFTP client or rsync using Drupal 6, Drupal 7, or WordPress for Pantheon.


If you have more than 500 MB of content to be transferred to your /files directory (sites/default/files for Drupal and wp-content/uploads for WordPress), you won't be able to use your Pantheon Dashboard to import. Instead, you'll need to use a SFTP client or rsync to transfer.

This allows you to transfer unlimited data "server-to-server", which is much faster than transferring from your workstation. Files can be transferred to and from any Pantheon site environment (Dev, Test, and Live).

There are two mechanisms for transferring files: SFTP and rsync.

Authenticating

SSH Keys

To take full advantage of Pantheon, you should load your public SSH key into your account. SSH keys are a best practice for authentication, allowing you more security than a simple password. You will only need to do this once, no matter how many sites you work on. For more details, see Generate and Add SSH Keys.

Dashboard Credentials

If you are prompted for a password when connecting to the platform, use your Pantheon Dashboard login password to gain access.

Note

If you login via social login (Connect with Google) or Single-Sign On (SSO) and you'd like to authenticate using a password, logout and visit https://dashboard.pantheon.io/reset-password to add a password to your account.

Larger agencies with multiple developers using password authentication who login frequently may see access issues across the organization. To avoid potential authentication failures, we strongly recommend using SSH keys. For details, see Pantheon Organizations FAQs.

SFTP

There are a number of GUI SFTP clients available, such as FileZilla, WinSCP, and Cyberduck. In your SFTP client, be sure to limit the number of simultaneous connections to one.

Connection information for SFTP is available in each site environment. From your Pantheon Dashboard, click Connection Info to see your credentials.

Here's an example of using a command-line SFTP client to connect to a site environment's file directory. Substitute your target environment and site UUID to connect; copy/pasting this example exactly as is will not work.

export ENV=dev
# Usually dev, test, or live
export SITE=c9beeb22-63f9-498a-942b-6ac0edcd4c29
# Site UUID from dashboard URL: https://dashboard.pantheon.io/sites/<UUID>


sftp -oPort=2222 $ENV.$SITE@appserver.$ENV.$SITE.drush.in
Connected to appserver.$ENV.$SITE.drush.in
sftp> cd files
sftp> put [your file or files]

rsync

rsync is also available, but it is a more advanced tool that requires experience with the command line.

Substitute your target environment and site UUID to connect; copying/pasting this example exactly as is will not work.

export ENV=dev
# Usually dev, test, or live
export SITE=[YOUR SITE UUID]
# Site UUID from dashboard URL: https://dashboard.pantheon.io/sites/<UUID>

# To Upload/Import
rsync -rLvz --size-only --ipv4 --progress -e 'ssh -p 2222' ./files/. --temp-dir=~/tmp/ $ENV.$SITE@appserver.$ENV.$SITE.drush.in:files/

# To Download
rsync -rLvz --size-only --ipv4 --progress -e 'ssh -p 2222' $ENV.$SITE@appserver.$ENV.$SITE.drush.in:files/ ~/files


# -r: Recurse into subdirectories
# -l: Check links
# -v: Verbose output
# -z: Compress during transfer
# Other rsync flags may or may not be supported
# (-a, -p, -o, -g, -D, etc are not).

Examples

Before you begin, make sure you have the following information:

Site URL: https://dashboard.pantheon.io/sites/3ef6264e-51d9-43b9-a60b-6cc22c3129308as83
Environment (ENV): Dev
Site (SITE): 3ef6264e-51d9-43b9-a60b-6cc22c3129308as83

Download a Drupal Directory from Pantheon

Download the contents of the sites/default/files directory into a folder on your local environment in the files home folder:

$: export ENV=dev
$: export SITE=3ef6264e-51d9-43b9-a60b-6cc22c3129308as83
$: rsync -rLvz --size-only --ipv4 --progress -e 'ssh -p 2222' $ENV.$SITE@appserver.$ENV.$SITE.drush.in:code/sites/default/files/ ~/files

Download a WordPress Directory from Pantheon

Download the contents of the wp-content/uploads directory into a folder on your local environment in the files home folder:

$: export ENV=dev
$: export SITE=3ef6264e-51d9-43b9-a60b-6cc22c3129308as83
$: rsync -rLvz --size-only --ipv4 --progress -e 'ssh -p 2222' $ENV.$SITE@appserver.$ENV.$SITE.drush.in:code/wp-content/uploads ~/files

Download a Drupal File from Pantheon

Download the sites/default/settings.php file into a Drupal installation called Foo on your local environment in a sites/default/files folder:

$: export ENV=dev
$: export SITE=3ef6264e-51d9-43b9-a60b-6cc22c3129308as83
$: rsync -rLvz --size-only --ipv4 --progress -e 'ssh -p 2222' $ENV.$SITE@appserver.$ENV.$SITE.drush.in:code/sites/default/settings.php ~/Foo/sites/default

Download a WordPress File from Pantheon

Download the index.php file into a WordPress installation called Foo on your local environment in a wp-content/uploads folder:

$: export ENV=dev
$: export SITE=3ef6264e-51d9-43b9-a60b-6cc22c3129308as83
$: rsync -rLvz --size-only --ipv4 --progress -e 'ssh -p 2222' $ENV.$SITE@appserver.$ENV.$SITE.drush.in:code/wp-content/uploads/index.php ~/Foo/sites/wp-content/uploads

Upload a Directory to Pantheon

If you need to upload the files directory from a local installation called Foo in your home directory to a Pantheon site's Test environment sites/default/files directory, use the following commands:

$: export ENV=test
$: export SITE=3ef6264e-51d9-43b9-a60b-6cc22c3129308as83
$: rsync -rLvz --size-only --ipv4 --progress -e 'ssh -p 2222' ~/files/. --temp-dir=~/tmp/ $ENV.$SITE@appserver.$ENV.$SITE.drush.in:files/

Upload a Single File to Pantheon

This example shows how to upload the logo.png file into a Pantheon site's theme folder.

$: export ENV=dev
$: export SITE=3ef6264e-51d9-43b9-a60b-6cc22c3129308as83
$: rsync -rLvz --size-only --ipv4 --progress -e 'ssh -p 2222' ~/Foo/sites/all/themes/foo/logo.png --temp-dir=~/tmp/ $ENV.$SITE@appserver.$ENV.$SITE.drush.in:code/sites/all/themes/foo

Known Issues

If you're uploading many files, and your Live environment has multiple application containers, upload to an environment other than Live (e.g. Dev), then use the clone operation in the Dashboard or Terminus to move the files to Live. Uploading a large amount of files into a multi-container Live environment may fail silently.