» 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) .

Symbolic links and synced folders in Vagrant

I want to use Vagrant to provide a common development environment to my team. The hosts are completely different:

• Some use OS X, some Linux, and some Windows.
• Some use VMware, some use VirtualBox.

Inside of the VM we want to run Linux.

So far, everything is fine.

Now our idea was that each developer shall be able use the IDE of their choice, and hence we have introduced a synced folder that shares the source code between the host and the VM. This basically, works as well … except for symbolic links.

Inside of our source code we actually do have a few symbolic links, which is not a problem within the Linux inside the VM, but on Windows as host this causes problems. The only thing that we can not do is get rid of the symbolic links, so we need another way to deal with this.

So far, we have tried a number of options:

• There is a workaround mentioned in an issue of Vagrant, unfortunately this is VirtualBox-only and does not help those who run VMware. So far, we haven’t found a way of running code in the Vagrantfile depending on the provider used.
• Instead of using a standard shared folder we now have tried using the rsync type. This works on Windows, but crashes on OS X with a number of errors telling us that the symlink has no referent (one error per symbolic link).
• We thought about NFS, but that only works if you do not use Windows as host.
• We also though about SMB, but this again only works on Windows as host.

I can not imagine that we are the only or the first persons on this planet to experience problems with multi-platform hosts and symbolic links within the shared folder.

How can you solve this issue, so that we can keep symbolic links, but still use different host operating systems?

Vagrant sync folder windows

Synced folder type: smb

Vagrant can use SMB as a mechanism to create a bi-directional synced folder between the host machine and the Vagrant machine.

SMB is built-in to Windows machines and provides a higher performance alternative to some other mechanisms such as VirtualBox shared folders.

SMB is currently only supported when the host machine is Windows or macOS. The guest machine can be Windows, Linux, or macOS.

» Prerequisites

» Windows Host

To use the SMB synced folder type on a Windows host, the machine must have PowerShell version 3 or later installed. In addition, when Vagrant attempts to create new SMB shares, or remove existing SMB shares, Administrator privileges will be required. Vagrant will request these privileges using UAC.

» macOS Host

To use the SMB synced folder type on a macOS host, file sharing must be enabled for the local account. Enable SMB file sharing by following the instructions below:

• Open «System Preferences»
• Click «Sharing»
• Check the «On» checkbox next to «File Sharing»
• Click «Options»
• Check «Share files and folders using SMB»
• Check the «On» checkbox next to your username within «Windows File Sharing»
• Click «Done»

When Vagrant attempts to create new SMB shares, or remove existing SMB shares, root access will be required. Vagrant will request these privileges using sudo to run the /usr/sbin/sharing command. Adding the following to the system’s sudoers configuration will allow Vagrant to manage SMB shares without requiring a password each time:

» Guests

The destination machine must be able to mount SMB filesystems. On Linux the package to do this is usually called smbfs or cifs . Vagrant knows how to automatically install this for some operating systems.

» Options

The SMB synced folder type has a variety of options it accepts:

smb_host (string) — The host IP where the SMB mount is located. If this is not specified, Vagrant will attempt to determine this automatically.

smb_password (string) — The password used for authentication to mount the SMB mount. This is the password for the username specified by smb_username . If this is not specified, Vagrant will prompt you for it. It is highly recommended that you do not set this, since it would expose your password directly in your Vagrantfile.

smb_username (string) — The username used for authentication to mount the SMB mount. This is the username to access the mount, not the username of the account where the folder is being mounted to. This is usually your Windows username. If you sign into a domain, specify it as user@domain . If this option is not specified, Vagrant will prompt you for it.

» Example

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

» Preventing Idle Disconnects

On Windows, if a file is not accessed for some period of time, it may disconnect from the guest and prevent the guest from accessing the SMB-mounted share. To prevent this, the following command can be used in a superuser shell. Note that you should research if this is the right option for you.

» Common Issues

» «wrong fs type» Error

If during mounting on Linux you are seeing an error message that includes the words «wrong fs type,» this is because the SMB kernel extension needs to be updated in the OS.

If updating the kernel extension is not an option, you can workaround the issue by specifying the following options on your synced folder:

Replace «USERNAME» and «PASSWORD» with your SMB username and password.

Vagrant 1.8 changed SMB mounting to use the more secure credential file mechanism. However, many operating systems ship with an outdated filesystem type for SMB out of the box which does not support this. The above workaround reverts Vagrant to the insecure before, but causes it work.

Synchronize Local and Guest Files

2 min
Products Used vagrant

Virtual machines are convenient for developing in, but not many people want to edit files using a plain terminal-based editor over SSH. Vagrant automatically syncs files to and from the guest machine. This way you can edit files locally and run them in your virtual development environment.

By default, Vagrant shares your project directory (the one containing the Vagrantfile) to the /vagrant directory in your guest machine.

Create and configure a guest machine, as specified by your Vagrantfile.

SSH into your virtual machine to see the synched file.

» Explore the synced folder

On the virtual machine, list the files in the vagrant directory.

Tip: When you vagrant ssh into your machine, you’re in /home/vagrant , which is a different directory from the synced /vagrant directory.

Believe it or not, the Vagrantfile that you see inside the virtual machine is actually the same Vagrantfile that is on your actual host machine.

If your terminal displays an error about incompatible guest additions (or no guest additions), you may need to update your box or choose a different one. Some users have also had success with the vagrant-vbguest plugin, but it is not officially supported by the Vagrant core team.

» Test the synced folder

To see the files sync between the guest machine and yours add a new folder in your virtual machine’s vagrant directory.

End your SSH session.

List the contents of your local vagrant directory, and notice that the new directory you created on your virtual machine is reflected there.

The folder «foo» is now on your host machine; Vagrant kept the folders in sync.

» Next Steps

With synced folders, you can continue to use your own editor on your host machine and have the files sync into the guest machine.

You have successfully interacted with your host machine via synced folders on the guest machine. In the next tutorial, learn about installing packages, users, and more with provisioning.