» NFS

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

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

» Prerequisites

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

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

If you are using the VirtualBox provider, you will also need to make sure youhave aprivate network set up. This is due to a limitation of VirtualBox's built-in networking. WithVMware, you do not need this.

» Enabling NFS Synced Folders

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

  1. Vagrant.configure("2") do |config|
  2.   config.vm.synced_folder ".", "/vagrant", type: "nfs"
  3. 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 areunique to NFS. These are listed below. These options can be specified inthe final part of the config.vm.synced_folder definition, along with thetype option.

  • nfs_export (boolean) - If this is false, then Vagrant will not modifyyour /etc/exports automatically and assumes you've done so already.

  • nfs_udp (boolean) - Whether or not to use UDP as the transport. UDPis faster but has some limitations (see the NFS documentation for moredetails). This defaults to true.

  • nfs_version (string | integer) - The NFS protocol version to use whenmounting 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 inthe Vagrantfile. These are documented below:

  • functional (bool) - Defaults to true. If false, then NFS will not be usedas 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 allread/write requests too. This will not affect the owner/group within theguest machine itself, but any writes will behave as if they were writtenas this UID/GID on the host. This defaults to the current user runningVagrant.

  • verify_installed (bool) - Defaults to true. If this is false, thenVagrant will skip checking if NFS is installed.

» Specifying NFS Arguments

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

  1. config.vm.synced_folder ".", "/vagrant",
  2.   type: "nfs",
  3.   mount_options: ['actimeo=2']

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

  1. mount -o 'actimeo=2' 172.28.128.1:'/path/to/vagrantfile' /vagrant

You can also tweak the arguments specified in the /etc/exports templatewhen the mount is added, by using the OS-specific linuxnfs_options orbsdnfs_options keys. Note that these options completely override the defaultarguments that are added by Vagrant automatically. For example, to make theNFS share asynchronous:

  1. config.vm.synced_folder ".", "/vagrant",
  2.   type: "nfs",
  3.   linux__nfs_options: ['rw','no_subtree_check','all_squash','async']

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

  1. # VAGRANT-BEGIN: 21171 5b8f0135-9e73-4166-9bfd-ac43d5f14261
  2. "/path/to/vagrantfile" 172.28.128.5(rw,no_subtree_check,all_squash,async,anonuid=21171,anongid=660,fsid=3382034405)
  3. # 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 foradministrative privileges (via the typical sudo program). Theseprivileges are used to modify /etc/exports as well as to start andstop the NFS server daemon.

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

Below, we have a couple example sudoers entries. Note that you mayhave to modify them slightly on certain hosts because the way Vagrantmodifies /etc/exports changes a bit from OS to OS. If the commands beloware 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:

  1. Cmnd_Alias VAGRANT_EXPORTS_ADD = /usr/bin/tee -a /etc/exports
  2. Cmnd_Alias VAGRANT_NFSD = /sbin/nfsd restart
  3. Cmnd_Alias VAGRANT_EXPORTS_REMOVE = /usr/bin/sed -E -e /*/ d -ibak /etc/exports
  4. %admin ALL=(root) NOPASSWD: VAGRANT_EXPORTS_ADD, VAGRANT_NFSD, VAGRANT_EXPORTS_REMOVE

For Ubuntu Linux , sudoers should look like this:

  1. Cmnd_Alias VAGRANT_EXPORTS_CHOWN = /bin/chown 0\:0 /tmp/*
  2. Cmnd_Alias VAGRANT_EXPORTS_MV = /bin/mv -f /tmp/* /etc/exports
  3. Cmnd_Alias VAGRANT_NFSD_CHECK = /etc/init.d/nfs-kernel-server status
  4. Cmnd_Alias VAGRANT_NFSD_START = /etc/init.d/nfs-kernel-server start
  5. Cmnd_Alias VAGRANT_NFSD_APPLY = /usr/sbin/exportfs -ar
  6. %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 userbelongs to the vagrant group):

  1. Cmnd_Alias VAGRANT_EXPORTS_CHOWN = /bin/chown 0\:0 /tmp/*
  2. Cmnd_Alias VAGRANT_EXPORTS_MV = /bin/mv -f /tmp/* /etc/exports
  3. Cmnd_Alias VAGRANT_NFSD_CHECK = /usr/bin/systemctl status --no-pager nfs-server.service
  4. Cmnd_Alias VAGRANT_NFSD_START = /usr/bin/systemctl start nfs-server.service
  5. Cmnd_Alias VAGRANT_NFSD_APPLY = /usr/sbin/exportfs -ar
  6. %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 userbelongs to the vagrant group):

  1. Cmnd_Alias VAGRANT_CHOWN = /usr/bin/chown 0\:0 /tmp/vagrant[a-z0-9-]*
  2. Cmnd_Alias VAGRANT_MV = /usr/bin/mv -f /tmp/vagrant[a-z0-9-]* /etc/exports
  3. Cmnd_Alias VAGRANT_START = /sbin/service nfsserver start
  4. Cmnd_Alias VAGRANT_STATUS = /sbin/service nfsserver status
  5. Cmnd_Alias VAGRANT_APPLY = /usr/sbin/exportfs -ar
  6. %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,assuming /etc/sudoers.d has been enabled.

» Other Notes

Encrypted folders: If you have an encrypted disk, then NFS very oftenwill refuse to export the filesystem. The error message given by NFS isoften 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 notencrypted.

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

  1. mount.nfs: an incorrect mount option was specified

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

  1. config.vm.synced_folder ".", "/vagrant",
  2.   type: "nfs",
  3.   nfs_version: 4,
  4.   nfs_udp: false

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