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.

export ENV=[env]
# Usually dev, test, or live
export SITE=[uuid]
# 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.

export ENV=[env]
# Usually dev, test, or live
export 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 -rvlz --copy-unsafe-links --size-only --ipv4 --progress -e 'ssh -p 2222' $ENV.$SITE@appserver.$ENV.$SITE.drush.in:files/ ~/files


# -r: Recurse into subdirectories
# -v: Verbose output
# -l: copies symlinks as symlinks
# -L: transforms symlinks into files.
# -z: Compress during transfer
# --copy-unsafe-links: transforms symlinks into files when the symlink target is outside of the tree being copied
# Other rsync flags may or may not be supported
# (-a, -p, -o, -g, -D, etc are not).

Rsync is highly customizable. See the man page to learn more.

Examples

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:

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:

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:

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:

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:

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.

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

Empty a Folder Recursively Using rsync

Since the rm -r command is not available over SFTP on Pantheon, an alternative way to recursively empty a folder is to use the rsync --delete flag. This example shows how to empty the remote folder files/remote_folder_to_empty (change this to match the remote directory you want to empty).

In your local machine, you must first create an empty folder with mkdir empty_folder.

rsync -rLvz --size-only --ipv4 --progress -a --delete -e 'ssh -p 2222' empty_folder/ --temp-dir=~/tmp/ $ENV.$SITE@appserver.$ENV.$SITE.drush.in:files/remote_folder_to_empty

Now you can use rmdir over SFTP to remove the empty directory itself.

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.