Vagrant 1.5 Feature Preview: Rsync Synced Folders

Vagrant 1.5 is going to be the biggest release of Vagrant since 1.1, with dozens of new features and improvements coming in. Don't worry, we've also obsessed over stability, so we expect it'll be one of the most stable upgrades, too.

Because Vagrant 1.5 will be so feature-packed, we're doing a series of blog posts that highlight the upcoming features so you know what to look forward to and how to use them. These posts will be weekly on Wednesdays, so keep an eye out for them!

We're going to kick off the series by introducing rsync synced folders. These synced folders offer incredible I/O performance at the expense of a little bit of latency. Read on to learn more.

»Introducing Rsync Synced Folders

Rsync synced folders use rsync to sync files to the guest machine. They are configured just as easily as any other synced folder, by just specifying the "rsync" type:

config.vm.synced\_folder ".", "/vagrant", type: "rsync"

As long as rsync is installed in both the host and the guest, this will just work. Since rsync is a standard utility for Mac and most Linux distributions, this just works most of the time! For Windows users, msysgit, MinGW, and Cygwin all provide rsync.

As an added benefit, Vagrant 1.5 knows how to install rsync for most major operating systems, and will do this automatically for you by default within the guest machine if rsync cannot be found.

When you execute vagrant up or vagrant reload, Vagrant will sync the data to the guest machine. In addition to these commands, Vagrant has a new command vagrant rsync that will only sync rsync folders that are defined.

Unlike VM shared folders and NFS, rsync is a one-time sync from the host machine to the guest machine. Changes to the folder after the sync is complete won't be visible in the guest machine until you force another sync with a command such as vagrant rsync. Luckily, Vagrant 1.5 will provide a way to auto-sync rsync synced folders.

»Auto-Syncing

By default, the folder syncing only happens when you manually execute a vagrant up, vagrant reload, or vagrant rsync. Part of the magic of Vagrant, though, has always been for changes to just appear in the guest machine.

Rsync synced folders don't have this magic property by default because unlike VM shared folders or NFS, rsync doesn't continue to run in the background to propagate any changes. And Vagrant itself doesn't keep any background processes running after it finishes executing, so by default changes won't be seen.

But because this is such a useful feature of Vagrant, Vagrant 1.5 has avagrant rsync-auto command. This command runs forever (until you Ctrl-C), watches any defined rsync synced folders, and automatically syncs changes as you make them.

$ vagrant rsync-auto 
==> default: Watching: /home/mitchellh/work/frontend
    default: Changes! Syncing /vagrant ...

This command uses system-specific APIs to detect file changes, rather than polling the file system. Therefore, this command sits idle most of the time and consumes only a small amount of RAM.

Changes are usually picked up in less than a second, and Vagrant only syncs changes over a compressed connection to use as little bandwidth as possible. As a result, changes appear in the guest machine quite fast.

We realize this workflow is a bit different than what you're used to with Vagrant, but it is a minor change necessitated by the technical differences of rsync versus other available synced folder mechanisms.

»Performance and Benefits

Because rsync copies the files directly onto the remote filesystem, performance is fantastic. For a comparison to NFS or VM shared folders, see my personal blog post comparing filesystem performance in virtual machines. With rsync, you'll see the "VirtualBox native" performance numbers.

Unlike NFS and VM shared folders, filesystem notifications work in the guest machine with rsync synced folders. So, if you use Guard or something like it, it will now work with Vagrant!

Also unlike NFS or VM shared folders, filesystem permissions are not tampered with in the guest machine. NFS and VM shared folders both change the way file permissions work that is fine most of the time, but can be really disruptive for some workflows. With rsync, because files are just copied onto the guest machine, permissions work as you would expect.

Rsync synced folders only requires rsync to be available in the guest machine, so it works on virtual machines that don't have guest additions installed. This is great for specialized operating systems where guest additions that require invasive kernel modules won't compile, but a relatively standard C program such as rsync will.

For Windows users, rsync finally provides a cross-platform alternative to VM shared folders that works out of the box with Vagrant. While NFS is available for Windows, Vagrant doesn't currently work with it, so Vagrant would fall back to VM shared folders.

»Choices, choices, choices!

With the introduction of rsync synced folders, users of Vagrant now have three choices out of the box for synced folders: VM shared folders, NFS, or rsync.

NFS and VM shared folders are not deprecated in any way and will be fully supported and improved for the foreseeable future. Vagrant has always been about choice and working with the technologies that work best for you and your team and rsync is now another really great choice Vagrant offers you.

»What's Next?

Rsync synced folders will be available out of the box with Vagrant 1.5. They are also fully documented already, so the documentation will cover all aspects of rsync synced folders immediately when 1.5 is released.

And that is only one of dozens of features of equal or greater caliber coming to Vagrant 1.5. Stay tuned next week when we cover another feature! Vagrant 1.5 will have quite a few surprises, we're sure, that should make both new and experienced Vagrant users very happy.