A new platform for documentation and tutorials is launching soon.
We are migrating Vagrant documentation into HashiCorp Developer, our new developer experience.
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.
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:
Vagrant.configure("2") do |config| config.vm.synced_folder ".", "/vagrant", type: "nfs" end
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
nfs_export(boolean) - If this is false, then Vagrant will not modify your
/etc/exportsautomatically 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
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_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:
config.vm.synced_folder ".", "/vagrant", type: "nfs", mount_options: ['actimeo=2']
This would result in the following
mount command being executed on the guest:
mount -o 'actimeo=2' 172.28.128.1:'/path/to/vagrantfile' /vagrant
You can also tweak the arguments specified in the
when the mount is added, by using the OS-specific
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:
config.vm.synced_folder ".", "/vagrant", type: "nfs", linux__nfs_options: ['rw','no_subtree_check','all_squash','async']
This would result in the following content in
/etc/exports on the host (note
# VAGRANT-BEGIN: 21171 5b8f0135-9e73-4166-9bfd-ac43d5f14261 "/path/to/vagrantfile" 172.28.128.5(rw,no_subtree_check,all_squash,async,anonuid=21171,anongid=660,fsid=3382034405) # VAGRANT-END: 21171 5b8f0135-9e73-4166-9bfd-ac43d5f14261
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
/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 macOS, sudoers should have this entry:
Cmnd_Alias VAGRANT_EXPORTS_ADD = /usr/bin/tee -a /etc/exports Cmnd_Alias VAGRANT_NFSD = /sbin/nfsd restart Cmnd_Alias VAGRANT_EXPORTS_REMOVE = /usr/bin/sed -E -e /*/ d -ibak /etc/exports %admin ALL=(root) NOPASSWD: VAGRANT_EXPORTS_ADD, VAGRANT_NFSD, VAGRANT_EXPORTS_REMOVE
For Linux , sudoers should look like this:
Cmnd_Alias VAGRANT_EXPORTS_CHOWN = /bin/chown 0\:0 /tmp/vagrant-exports Cmnd_Alias VAGRANT_EXPORTS_MV = /bin/mv -f /tmp/vagrant-exports /etc/exports Cmnd_Alias VAGRANT_NFSD_CHECK = /etc/init.d/nfs-kernel-server status Cmnd_Alias VAGRANT_NFSD_START = /etc/init.d/nfs-kernel-server start Cmnd_Alias VAGRANT_NFSD_APPLY = /usr/sbin/exportfs -ar %sudo ALL=(root) NOPASSWD: VAGRANT_EXPORTS_CHOWN, VAGRANT_EXPORTS_MV, VAGRANT_NFSD_CHECK, VAGRANT_NFSD_START, VAGRANT_NFSD_APPLY
For Fedora Linux, sudoers might look like this (given your user belongs to the vagrant group):
Cmnd_Alias VAGRANT_EXPORTS_CHOWN = /bin/chown 0\:0 /tmp/vagrant-exports Cmnd_Alias VAGRANT_EXPORTS_MV = /bin/mv -f /tmp/vagrant-exports /etc/exports Cmnd_Alias VAGRANT_NFSD_CHECK = /usr/bin/systemctl status --no-pager nfs-server.service Cmnd_Alias VAGRANT_NFSD_START = /usr/bin/systemctl start nfs-server.service Cmnd_Alias VAGRANT_NFSD_APPLY = /usr/sbin/exportfs -ar %vagrant ALL=(root) NOPASSWD: VAGRANT_EXPORTS_CHOWN, VAGRANT_EXPORTS_MV, VAGRANT_NFSD_CHECK, VAGRANT_NFSD_START, VAGRANT_NFSD_APPLY
For SUSE Linux, sudoers might look like this (given your user belongs to the vagrant group):
Cmnd_Alias VAGRANT_CHOWN = /usr/bin/chown 0\:0 /tmp/vagrant-exports Cmnd_Alias VAGRANT_MV = /usr/bin/mv -f /tmp/vagrant-exports /etc/exports Cmnd_Alias VAGRANT_START = /usr/bin/systemctl start --no-pager nfs-server Cmnd_Alias VAGRANT_STATUS = /usr/bin/systemctl status --no-pager nfs-server Cmnd_Alias VAGRANT_APPLY = /usr/sbin/exportfs -ar %vagrant ALL=(root) NOPASSWD: VAGRANT_CHOWN, VAGRANT_MV, VAGRANT_START, VAGRANT_STATUS, VAGRANT_APPLY
If you don't want to edit
/etc/sudoers directly, you can create
/etc/sudoers.d/vagrant-syncedfolders with the appropriate entries,
/etc/sudoers.d has been enabled.
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
<path> does not support NFS.
There is no workaround for this other than sharing a directory which is not
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:
mount.nfs: an incorrect mount option was specified
When using NFSv4, ensure the
nfs_udp option is set to false. For example:
config.vm.synced_folder ".", "/vagrant", type: "nfs", nfs_version: 4, nfs_udp: false
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-serverfor errors like
exportfs: Failed to stat /path : No such file or directory. Then create the missing directory or remove the line from
/etc/exportsand restart the nfs-kerne-server
sysctemctl start nfs-kernel-server
If using Mac, ensure that
/sbin/nfsdhas been given Full Disk Access.
Ensure the synced folder is present in the hosts
/etc/exportsfile. If the target folder is not listed in
/etc/exports, then ensure that the synced_folder option
nfs_exportis set to
true, or manually add the entry.
Ensure that the contents of
/etc/exportsis valid. For example, if running nfsd, this can be done by running
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
showmountcommands. For example
rpcinfo -u <ip> nfsor
showmount -e <ip>.
Ensure a firewall is not blocking NFS.
Try manually mounting the folder, enabling verbose output:
$ vagrant ssh $ mount -v -t nfs -o <mount options> <ip address>:<path to folder on host> <mountpoint>
If using a UDP connection: ensure UDP is enabled by the nfs server. This setting can likely be changed in config file
/etc/nfs.conf. Or, in Vagrant, set the
nfs_udpoption for the synced folder to