» RSync

Synced folder type: rsync

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

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

The rsync and rsync-auto commands can be used to force a resync and to automatically resync when changes occur in the filesystem. Without running these commands, Vagrant only syncs the folders on vagrant up or vagrant reload .

» Prerequisites

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

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

The destination machine must also have rsync installed, but Vagrant can automatically install rsync into many operating systems. If Vagrant is 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 on the destination folder.

» Options

The rsync synced folder type accepts the following options:

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

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

rsync__chown (boolean) — If false, then the owner and group options for the synced folder are ignored and Vagrant will not execute a recursive chown . This defaults to true. This option exists because the chown causes issues for some development environments. Note that any rsync__args options for ownership will be overridden by rsync__chown .

rsync__exclude (string or array of strings) — A list of files or directories to exclude from the sync. The values can be any acceptable rsync exclude pattern. By default, the «.vagrant/» directory is excluded. We recommend excluding revision control directories such as «.git/» as well.

rsync__rsync_ownership (boolean) — If true, and rsync executables in use are >= 3.1.0, then rsync will be used to set the owner and group instead of a separate call to modify ownership. By default, this is false.

rsync__rsync_path (string) — The path on the remote host where rsync is 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 rsync process will be echoed to the console. The output of rsync is subject to rsync__args of course. By default, this is false.

» Example

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

» Rsync to a restricted folder

If required to copy to a destination where vagrant user does not have permissions, use «—rsync-path=’sudo rsync'» to run rsync with sudo on the guest

» Basic Usage

» Configuration

Synced folders are configured within your Vagrantfile using the config.vm.synced_folder method. Usage of the configuration directive is very simple:

The first parameter is a path to a directory on the host machine. If the path is relative, it is relative to the project root. The second parameter must be an absolute path of where to share the folder within the guest machine. This folder will be created (recursively, if it must) if it does not exist. By default, Vagrant mounts the synced folders with the owner/group set to the SSH user and any parent folders set to root.

» Options

You may also specify additional optional parameters when configuring synced folders. These options are listed below. More detailed examples of using some of these options are shown below this section, note the owner/group example supplies two additional options separated by commas.

In addition to these options, the specific synced folder type might allow more options. See the documentation for your specific synced folder type for more details. The built-in synced folder types are documented in other pages available in the navigation for these docs.

create (boolean) — If true, the host path will be created if it does not exist. Defaults to false.

disabled (boolean) — If true, this synced folder will be disabled and will not be setup. This can be used to disable a previously defined synced folder or to conditionally disable a definition based on some external factor.

group (string) — The group that will own the synced folder. By default this will be the SSH user. Some synced folder types do not support modifying the group.

mount_options (array) — A list of additional mount options to pass to the mount command.

owner (string) — The user who should be the owner of this synced folder. By default this will be the SSH user. Some synced folder types do not support modifying the owner.

type (string) — The type of synced folder. If this is not specified, Vagrant will automatically choose the best synced folder option for your environment. Otherwise, you can specify a specific type such as «nfs».

id (string) — The name for the mount point of this synced folder in the guest machine. This shows up when you run mount in the guest machine.

» Enabling

Synced folders are automatically setup during vagrant up and vagrant reload .

» Disabling

Synced folders can be disabled by adding the disabled option to any definition:

Disabling the default /vagrant share can be done as follows:

» Modifying the Owner/Group

Sometimes it is preferable to mount folders with a different owner/group than the default SSH user. Keep in mind that these options will only affect the synced folder itself. If you want to modify the owner/group of the synced folder’s parent folders use a script. It is possible to set these options:

NOTE: Owner and group IDs defined within mount_options will have precedence over the owner and group options.

For example, given the following configuration:

the mounted synced folder will be owned by the user with ID 1234 and the group with ID 1234 . The owner and group options will be ignored.

» Symbolic Links

Support for symbolic links across synced folder implementations and host/guest combinations is not consistent. Vagrant does its best to make sure symbolic links work by configuring various hypervisors (such as VirtualBox), but some host/guest combinations still do not work properly. This can affect some development environments that rely on symbolic links.

The recommendation is to make sure to test symbolic links on all the host/guest combinations you sync folders on if this is important to you.

Vagrant shared and synced folders

I created a Vagrantfile with the following content:

After vagrant up or vagrant reload I get:

My questions are:

1. Why is Vagrant mounting the /vagrant shared folder? I read shared folders are deprecated in favour of synced folders, and I never defined any shared folder in my Vagrantfile.
2. Why is the synced folder not set up?

I’m using Vagrant version 1.2.7 on MacOX 10.8.4.

1 Answer 1

shared folders VS synced folders

Basically shared folders are renamed to synced folder from v1 to v2 (docs), under the bonnet it is still using vboxsf between host and guest (there is known performance issues if there are large numbers of files/directories).

Vagrantfile directory mounted as /vagrant in guest

Vagrant is mounting the current working directory (where Vagrantfile resides) as /vagrant in the guest, this is the default behaviour.

NOTE: By default, Vagrant will share your project directory (the directory with the Vagrantfile) to /vagrant.

You can disable this behaviour by adding cfg.vm.synced_folder «.», «/vagrant», disabled: true in your Vagrantfile .

Why synced folder is not working

Based on the output /tmp on host was NOT mounted during up time.

Use VAGRANT_INFO=debug vagrant up or VAGRANT_INFO=debug vagrant reload to start the VM for more output regarding why the synced folder is not mounted. Could be a permission issue (mode bits of /tmp on host should be drwxrwxrwt ).

I did a test quick test using the following and it worked (I used opscode bento raring vagrant base box)

config.vm.synced_folder «/tmp», «/tmp/src»

Within the VM, you can see the mount info /tmp/src on /tmp/src type vboxsf (uid=900,gid=900,rw) .

Vagrant synced folder windows

In some cases the default shared folder implementations (such as VirtualBox shared folders) have high performance penalties. If you are seeing less than ideal performance with synced folders, NFS can offer a solution. Vagrant has built-in support to orchestrate the configuration of the NFS server on the host and guest for you.

Windows users: NFS folders do not work on Windows hosts. Vagrant will ignore your request for NFS synced folders on Windows.

» Prerequisites

Before using synced folders backed by NFS, the host machine must have nfsd installed, the NFS server daemon. This comes pre-installed on Mac OS X, and is typically a simple package install on Linux.

Additionally, the guest machine must have NFS support installed. This is also usually a simple package installation away.

If you are using the VirtualBox provider, you will also need to make sure you have a private network set up. This is due to a limitation of VirtualBox’s built-in networking. With VMware, you do not need this.

» Enabling NFS Synced Folders

To enable NFS, just add the type: «nfs» flag onto your synced folder:

If you add this to an existing Vagrantfile that has a running guest machine, be sure to vagrant reload to see your changes.

» NFS Synced Folder Options

NFS synced folders have a set of options that can be specified that are unique to NFS. These are listed below. These options can be specified in the final part of the config.vm.synced_folder definition, along with the type option.

nfs_export (boolean) — If this is false, then Vagrant will not modify your /etc/exports automatically and assumes you’ve done so already.

nfs_udp (boolean) — Whether or not to use UDP as the transport. UDP is faster but has some limitations (see the NFS documentation for more details). This defaults to true.

nfs_version (string | integer) — The NFS protocol version to use when mounting the folder on the guest. This defaults to 3.

» NFS Global Options

There are also more global NFS options you can set with config.nfs in the Vagrantfile. These are documented below:

functional (bool) — Defaults to true. If false, then NFS will not be used as a synced folder type. If a synced folder specifically requests NFS, it will error.

map_uid and map_gid (int) — The UID/GID, respectively, to map all read/write requests too. This will not affect the owner/group within the guest machine itself, but any writes will behave as if they were written as this UID/GID on the host. This defaults to the current user running Vagrant.

verify_installed (bool) — Defaults to true. If this is false, then Vagrant will skip checking if NFS is installed.

» Specifying NFS Arguments

In addition to the options specified above, it is possible for Vagrant to specify alternate NFS arguments when mounting the NFS share by using the mount_options key. For example, to use the actimeo=2 client mount option:

This would result in the following mount command being executed on the guest:

You can also tweak the arguments specified in the /etc/exports template when the mount is added, by using the OS-specific linux__nfs_options or bsd__nfs_options keys. Note that these options completely override the default arguments that are added by Vagrant automatically. For example, to make the NFS share asynchronous:

This would result in the following content in /etc/exports on the host (note the added async flag):

» Root Privilege Requirement

To configure NFS, Vagrant must modify system files on the host. Therefore, at some point during the vagrant up sequence, you may be prompted for administrative privileges (via the typical sudo program). These privileges are used to modify /etc/exports as well as to start and stop the NFS server daemon.

If you do not want to type your password on every vagrant up , Vagrant uses thoughtfully crafted commands to make fine-grained sudoers modifications possible to avoid entering your password.

Below, we have a couple example sudoers entries. Note that you may have to modify them slightly on certain hosts because the way Vagrant modifies /etc/exports changes a bit from OS to OS. If the commands below are located in non-standard paths, modify them as appropriate.

Also note that in the sudoer file format, entries are applied in order. If you’ve added the appropriate entries but still have to type in your password, make sure the entries aren’t inserted too early. From the sudoers man page: «When multiple entries match for a user, they are applied in order. Where there are multiple matches, the last match is used (which is not necessarily the most specific match).»

For * nix users, make sure to edit your /etc/sudoers file with visudo . It protects you against syntax errors which could leave you without the ability to gain elevated privileges.

All of the snippets below require Vagrant version 1.7.3 or higher.

Use the appropriate group for your user Depending on how your machine is configured, you might need to use a different group than the ones listed in the examples below.

For OS X, sudoers should have this entry:

For Ubuntu Linux , sudoers should look like this:

For Fedora Linux, sudoers might look like this (given your user belongs to the vagrant group):

For SUSE Linux, sudoers might look like this (given your user belongs to the vagrant group):

If you don’t want to edit /etc/sudoers directly, you can create /etc/sudoers.d/vagrant-syncedfolders with the appropriate entries, assuming /etc/sudoers.d has been enabled.

» Other Notes

Encrypted folders: If you have an encrypted disk, then NFS very often will refuse to export the filesystem. The error message given by NFS is often not clear. One error message seen is

does not support NFS . There is no workaround for this other than sharing a directory which is not encrypted.

Version 4: UDP is generally not a valid transport protocol for NFSv4. Early implementations of NFS 4.0 still allowed UDP which allows the UDP transport protocol to be used in rare cases. RFC5661 explicitly states UDP alone should not be used for the transport protocol in NFS 4.1. Errors due to unsupported transport protocols for specific versions of NFS are not always clear. A common error message when attempting to use UDP with NFSv4:

When using NFSv4, ensure the nfs_udp option is set to false. For example:

For more information about transport protocols and NFS version 4 see:

» Troubleshooting NFS Issues

NFS issues may arise for a variety of reasons. The following list describes how to possibly identify the root of the issue.

Ensure nfs server is running on the host. Check if it is running using the command ps aux | grep nfsd . If the nfs service is not running, then it may require a manual restart.

Check status of nfs-kernel-server systemctl status nfs-kernel-server for errors like exportfs: Failed to stat /path : No such file or directory . Then create the missing directory or remove the line from /etc/exports and restart the nfs-kerne-server sysctemctl start nfs-kernel-server

If using Mac, ensure that /sbin/nfsd has been given Full Disk Access.

Ensure the synced folder is present in the hosts /etc/exports file. If the target folder is not listed in /etc/exports , then ensure that the synced_folder option nfs_export is set to true , or manually add the entry.

Ensure that the contents of /etc/exports is valid. For example, if running nfsd, this can be done by running nfsd checkexports .

Ensure guest machine has a nfs client installed. The client may differ depending on the OS. If no nfs client is installed on the guest, then it may need to be installed.

Ensure the guest has access to the mounts. This can be done using something like the rpcinfo or showmount commands. For example rpcinfo -u nfs or showmount -e .

Ensure a firewall is not blocking NFS.

Try manually mounting the folder, enabling verbose output: