dman has written some excellent documentation on the site alias feature.

@dman: I have some specific feedback on a few points.

You made a comment that site aliases in a drushrc.php file in a site folder was not supported, but this limitation was in fact fixed. One thing to note, though, is that drush only loads the drushrc.php file in a site folder during the drupal site bootstrap, so only one of these will ever be loaded, and it doesn't really do any good to put an alias to a site in its own site folder, because drush will see it too late. So, your comment is correct, but the actual reasoning is a little different.

Regarding authentication keys, drush requires these to be set up. The commend in says that password access is okay, but the code says "ssh -o PasswordAuthentication=no", so drush will refuse to contact a remote machine unless you have set up the authentication keypair. I use the script "pushkey" to set these up; I have attached it to this incident for your general amusement. (Please always review scripts such as these carefully before using them, to insure that no one has inserted code to push your private keys out to some nefarious location...)

You recommend setting up an alias to the site folder on the target location. This is a fine idea, but if you go this route, you will need to set up symmetrical symlinks -- that is, each drupal instance should have a symlink to the other's site folder. This is important because drupal sometimes writes the path to the sites folder into certain fields of the database; if you do some operation on the target site (e.g. configure the color module) and then push the database back to the original site, then your database may contain references to both of the site folders, so you will need aliases in both locations to make sure things always work. I hear that this will not be necessary with D7, though. In the meantime, another solution is to insure that the sites folder is has the same name on both sites. If you originally set up a site "" and push it to a remote site "", then you can configure your web server to serve "" from a drupal root folder dedicated to that site, and drupal will still serve up content from the "sites/" folder due to the way drupal searches for the settings.php file. This explanation is a little brief; perhaps I should draw a diagram. Creating aliases is perhaps easier to understand.

You mentioned that '!drush-script' used to be '!drush', but this was changed before the site alias feature was committed, so few people will have seen this older version of the code. I'd recommend documenting it as it is now: !drush-script is the path to the script, and !drush is the path to the drush installation folder.

In the same general area you mention that drush must be installed on the target machine. This is the case only if drush needs to look up the database specifications for you. If you define 'database' or 'db-url' in your site alias, then the remote call is not done, and drush only needs to be installed on the local machine. If you pass '--database' or '--db-url' to the site alias command, it will include the database specification in the site alias record to make this more convenient for you. If you do this, you may have troubles if someone changes the database specifications on the remote machine, though.

Regarding the !dump specification, just fyi, there is a pending issue that will address this. sql sync will someday allow you to specify a folder instead of a file (e.g. in $options['dump']), then the filename will be composed from elements of the site alias (e.g. remote-host, root and uri). Perhaps there will be a separate option, 'dump-dir', or perhaps it will key off of whether or not the final character of !dump is a '/'. Please comment in #634720: Buglets with sql sync and sitealias if interested.

Finally, I always like to do a drush sitename cc all after pushing a site, just to insure that theme and block changes are picked up on the target. I also do a watchdog delete all, but I can't quite remember if this is superstition, or if it actually clears up a problem. Perhaps the former, since I include --skip-tables-key=common when I sync the database so as to avoid transmitting the watchdog table.

Thanks again for the documentation -- it's great!

Members fund testing for the Drupal project. Drupal Association Learn more


greg.1.anderson’s picture

2.68 KB

Here is the pushkey script I referred to above.

dman’s picture

Category: bug » task
Status: Active » Needs review

Thanks for the review. It is enlightening for me to see some of the details in the corners.
The walkthrough is a little bit stream-of-consciousness style, and is written as a first-time user taking one of many possible paths, so there are probably plenty of assumptions made.

RE sitename/bashrc.php
I understood the reasoning for that not triggering, and did try to test it first to see if my preferred approach would work first. I'd still like a way for a site to just define information locally about its default preferred peer, but it wasn't too much of an issue. I've softened that comment and demoted it to an aside.

RE authentication
Setting up ssh keys is now second nature to me, but I'd assumed other folk may get prompted for their pass a few times. I've updated the comment from 'tip' to 'requirement' to reflect this.
This is a little frustrating to know, as I have had some cases where due to limited permissions on the server, I could get shell but not ssh keys working :-/.
I didn't want to get into documenting that too much there, as this practice is a tip that should be covered elsewhere.
FWIW, my less-cute personal version of 'pushkey' is a one-liner that looks like:

ssh $login "echo '`cat ~/.ssh/`' >> ~/.ssh/authorized_keys"


RE site folder aliases.
I know exactly what you are saying. In the real world, I do in fact do it a little differently. For a while now, I've been creating:

sites/shortname/{real files}
sites/ -> shortname
sites/ -> shortname

And do indeed create both aliases in both places. And change the filesystem setting to 'shortname/files' asap. There are still some places where the system can potential get a little out of kilter, but symlinks hold it together.
But again, this is advice is just one possibility with its own set of considerations that should be documented or written about off-topic separate from drush. If that doc exists, I'd link to it.

RE !drush-script
I just had to note that to myself at the time because the example.drushrc.php internal documentation was not quite obvious.
'!drush' => '/drush/path/drush',
... I'll rewrite my comment, as it is indeed redundant if I actually read the comments nearby in the file :-)

RE drush not entirely required.
Noted. Very Cool, did not know that, and it is going to be simpler for me, I prefer to have a copy of remote details stored locally. I added an update about skipping that step.
I got the impression that there was an intention to make the remote drush instance do lots more work, like an RPC endpoint (and was a bit sceptical about that approach) but if it remains working as a local set of instructions sent to a remote machine, I'm very happy with that.
... I guess I can remove one of the cogs from my illustration :-B. Damn. I made it a cog just so I could plug them together!

RE !dump.
commented on-issue there.

RE caches.
In my experience, it makes more sense to flush caches and watchdog immediately before taking a dump, because that makes the SQL several times smaller. I've noted the 'cc' action (which I didn't know of) at the bottom of my write-up anyway.
Would it be good practice for sql sync to do that itself? does it already?

I may still get around to patching in the missing db prefix support for the project one day... I'm just stepping through an automated backup/testsuite setup so hitting (and documenting) things as I come across them. I had 20 multisites in one (dev/demo) DB, and it slowed the db export down with a lot of redundancy. Thought I'd get up to speed with drush sync as a replacement for my own scripts (so far it's pretty much the same as my hand-rolled versions - which is a good sign).

Glad I didn't make too many gross misunderstandings in my write-up there! I find making notes to be quite theraputic, especially when the system i'm documenting is more clever than me!

(PS, did my placing a purely decorative image in the HTML lock it from editing for you?)

greg.1.anderson’s picture

It was my intention to write up some documentation for site aliases, but probably wasn't going to have time until sometime in January. I'm very glad you stepped up and filled the need -- and the world got a cool drush icon to boot.

Regarding the "cogs", two drush installs can work together as you describe above. For example, drush my.drupalsite.remote cc will run drush cc on the remote site my.drupalsite.remote. Both sites must have drush installed for this remote execution feature to work.

Your point about the documentation in example.drushrc.php was well made; I adjusted the comments a bit to make it clearer.

Re caches: I clear the cache on the source site, tell sql sync not to transmit the cache tables, and then clear the cache on the target site. Overkill, but that works. (Better take off and nuke the site from orbit...) I don't think it is necessarily best practices to always clear the cache, so I wouldn't build that into sql sync itself. I'm planning a site sync command that will do a sql sync followed by a sync, with appropriate actions such as taking the target site offline atomicly, clearning caches, etc. as part of #628996: Concurrently execute a single drush command on multiple sites (but there will be a separate incident for the "site" commands).

Re table prefix support: You are a brave man. Personally I'm worried about issues such as the fact that the table prefixes might not be the same, there might be shared tables, and things can go horribly amiss if you try to sync from a table-prefix db to an exclusive-use db (or other permutations of "oh no, the settings.php file configurations for table prefixes are not quite the same in the two sites...). You could always make a drush command similar to sql conf that would pull out the table prefix settings, and fetch it the same way sql sync currently gets the database settings from a remote machine, but it would probably be easier to start off with a requirement that the settings match on the source and on the target. I don't use table prefixes myself, but I'd be glad to see someone make a stab at supporting them.

Re Locking: There is no "edit" tab for me on your page, whereas other documentation pages do have an edit tab. I do not know what the reason might be for that difference.

dman’s picture

Hm. Cache clearing is a fuzzy one. Different needs in different cases. In the past I've tried various methods, but what you are currently doing with the 'no-data' options is the best I can imagine at the moment.

I'd not yet encountered the remote invocation syntax, but knew it was in the pipeline. Good to know that drush my.drupalsite.remote cc is the magic word.

I guess there are some issues with multi-shared table prefixes, but I've not had to use them yet. I can start with simple per-site prefixes and just freak out if there is an array ... for now. It'll only happen as I find a need for it in real sites. If I have to imagine all possible futures, even ones that don't apply to me, nothing will happen.
Currently however the all-my-neighbours-tables behaviour is undesirable, so I'll want to detect and fix that. I'm setting up a bunch of rapid-development small sites that have most things in common, including the DB itself, as a host won't let me CREATE DATABASE on the fly.
I've also developed code that (so far seems to) handle prefix-rewriting on the fly, including prefixed-to-not and back (just a few regexps through sed) so I'd like to plug that in. I've found it useful/neccessary in some migrations. I work with many different companies that have different conventions about setting stuff up, and try to make my local dev mirrors as consistent+agnostic as possible, so I've seen plenty of variety.
I will not speculate about why someone would have entirely different structured schemas on two sites they intended to keep in synch!

RE edit locking
Yeah, I was afraid of that. In order to insert an image on d.o, the input format is slightly advanced, for the 'documentation' role. (I'm a d.o doc maintainer). However, this has the side effect of not letting other non-maintainers touch my code. I'll have to remove my pretty picture if I want to open up that page to public edits :-/

greg.1.anderson’s picture

Regarding table prefixes, see #625870: drush sql dump and table prefixes.

As for remote invocation, I will also mention that drush sitename site alias and drush site alias sitename are subtly different. I hope to make them less so, but the later will always execute locally, whereas the former might run on a remote machine.

moshe weitzman’s picture

Status: Needs review » Postponed (maintainer needs more info)

Anything left to do here? I added 'site maintainer' role to greg's account so he can tweak the documentation when inspiration enters the mind.

greg.1.anderson’s picture

Assigned: Unassigned » greg.1.anderson
Status: Postponed (maintainer needs more info) » Needs work

The documentation still uses ! instead of % in path aliases, and documents some limitations / bugs that have been fixed. I'll update it as I find the time to do so.

moshe weitzman’s picture

I added links to dman's doc from README.txt and includes/

greg.1.anderson’s picture

Substantial changes to alias handling were just committed, so this documentation needs substantial updating. I will do that soon.

greg.1.anderson’s picture

6.04 KB

I committed the attached improvements to the example.aliases.drushrc.php file.

greg.1.anderson’s picture

Status: Needs work » Needs review

I have updated the site alias documentation to reflect what is currently in drush-HEAD.

moshe weitzman’s picture

Status: Needs review » Fixed

Seems like we are done here. If not, please reopen.

soxofaan’s picture

Priority: Normal » Minor
Status: Fixed » Active
876 bytes

There is a minor issue in example.aliases.drushrc.php with a part of an old sentence that was not completely deleted:

 * Files stored in these locations can be used to create aliases
 * to local and remote Drupal installations.  These aliases can beTo create aliases to remote Drupal installations, add entries
 * used in place of a site specification on the command line, and
greg.1.anderson’s picture

Status: Active » Fixed

Committed; thanks.

Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for 2 weeks with no activity.

smoothoperatah’s picture

This is great. how do i install this command on osx? i downloaded the file and saved as in /bin then chmod +X. but still no dice.

greg.1.anderson’s picture

I don't know that the shell script will work on OSX; you might have better luck with the pushkey drush command in drush extras. It's not committed, but you can pull it from the issue queue: #754106: drush pushkey

P.S. It was only luck that I happened to see your note on this closed issue. It's better to open a new issue for new support requests, or re-open a closed issue if you find the bug is still happening. Comments on closed issues are often missed &/or ignored.

dman’s picture

Works fine on osx for me
If you saved it with the .sh extension, that's what you'll have to type

gateway69’s picture

i just tried this script on one of my clean CENTOS images and it spit this out

/bin/sh: /root/.ssh/ No such file or directory


dman’s picture

For future pushkey-type support, I recommend looking at ssh-copy-id which now comes with the ssh package (AFAIK) and just does this common task for you.