» RSync

Synced folder type: rsync

Vagrant can use rsync as a mechanismto sync a folder to the guest machine. This synced folder type is usefulprimarily in situations where other synced folder mechanisms are not available,such as when NFS or VirtualBox shared folders are not available in the guestmachine.

The rsync synced folder does a one-time one-way sync from the machine runningto the machine being started by Vagrant.

The rsync and rsync-autocommands can be used to force a resync and to automatically resync whenchanges occur in the filesystem. Without running these commands, Vagrantonly syncs the folders on vagrant up or vagrant reload.

» Prerequisites

To use the rsync synced folder type, the machine running Vagrant must haversync (or rsync.exe) on the path. This executable is expected to behavelike the standard rsync tool.

On Windows, rsync installed with Cygwin or MinGW will be detected byVagrant and works well.

The destination machine must also have rsync installed, but Vagrantcan automatically install rsync into many operating systems. If Vagrantis unable to automatically install rsync for your operating system,it will tell you.

The destination folder will be created as the user initiating the connection,this is vagrant by default. This user requires the appropriate permissions onthe destination folder.

» Options

The rsync synced folder type accepts the following options:

  • rsync__args (array of strings) - A list of arguments to supplyto rsync. By default this is ["—verbose", "—archive", "—delete", "-z", "—copy-links"].

  • rsync__auto (boolean) - If false, then rsync-auto will notwatch and automatically sync this folder. By default, this is true. Note: Thisoption will not automatically invoke the rsync-auto subcommand.

  • rsync__chown (boolean) - If false, then theowner and groupoptions for the synced folder are ignored and Vagrant will not executea recursive chown. This defaults to true. This option exists becausethe chown causes issues for some development environments. Note thatany rsyncargs options for ownership will be overridden byrsyncchown.

  • rsync__exclude (string or array of strings) - A list of files or directoriesto exclude from the sync. The values can be any acceptable rsync excludepattern. By default, the ".vagrant/" directory is excluded. We recommendexcluding revision control directories such as ".git/" as well.

  • rsync__rsync_ownership (boolean) - If true, and rsync executables in useare >= 3.1.0, then rsync will be used to set the owner and group insteadof a separate call to modify ownership. By default, this is false.

  • rsync__rsync_path (string) - The path on the remote host where rsyncis and how it is executed. This is platform specific but defaults to"sudo rsync" for many guests.

  • rsync__verbose (boolean) - If true, then the output from the rsyncprocess will be echoed to the console. The output of rsync is subjectto rsync__args of course. By default, this is false.

» Example

The following is an example of using RSync to sync a folder:

  1. Vagrant.configure("2") do |config|
  2.   config.vm.synced_folder ".", "/vagrant", type: "rsync",
  3.     rsync__exclude: ".git/"
  4. end

» Rsync to a restricted folder

If required to copy to a destination where vagrant user does not havepermissions, use "—rsync-path='sudo rsync'" to run rsync with sudo on the guest

  1. Vagrant.configure("2") do |config|
  2.   config.vm.synced_folder "bin", "/usr/local/bin", type: "rsync",
  3.     rsync__exclude: ".git/",
  4.     rsync__args: ["--verbose", "--rsync-path='sudo rsync'", "--archive", "--delete", "-z"]
  5. end