"Fossies" - the Fresh Open Source Software Archive
Member "vagrant-2.2.14/website/pages/docs/synced-folders/nfs.mdx" (20 Nov 2020, 11602 Bytes) of package /linux/misc/vagrant-2.2.14.tar.gz:
As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard
) with prefixed line numbers.
Alternatively you can here view
the uninterpreted source code file.
See also the latest Fossies "Diffs"
side-by-side code changes report for "nfs.mdx": 2.2.13_vs_2.2.14
2 layout: docs
3 page_title: NFS - Synced Folders
4 sidebar_title: NFS
5 description: >-
6 In some cases the default shared folder implementations such as VirtualBox
8 shared folders have high performance penalties. If you are seeing less than
10 ideal performance with synced folders, NFS can offer a solution. Vagrant has
12 built-in support to orchestrate the configuration of the NFS server on the
15 and guest for you.
18 # NFS
20 In some cases the default shared folder implementations (such as VirtualBox
21 shared folders) have high performance penalties. If you are seeing less
22 than ideal performance with synced folders, [NFS](https://en.wikipedia.org/wiki/Network_File_System_%28protocol%29)
23 can offer a solution. Vagrant has built-in support to orchestrate the
24 configuration of the NFS server on the host and guest for you.
26 ~> **Windows users:** NFS folders do not work on Windows hosts. Vagrant will
27 ignore your request for NFS synced folders on Windows.
29 ## Prerequisites
31 Before using synced folders backed by NFS, the host machine must have
32 `nfsd` installed, the NFS server daemon. This comes pre-installed on Mac
33 OS X, and is typically a simple package install on Linux.
35 Additionally, the guest machine must have NFS support installed. This is
36 also usually a simple package installation away.
38 If you are using the VirtualBox provider, you will also need to make sure you
39 have a
40 [private network set up](/docs/networking/private_network). This is due to a limitation of VirtualBox's built-in networking. With
41 VMware, you do not need this.
43 ## Enabling NFS Synced Folders
45 To enable NFS, just add the `type: "nfs"` flag onto your synced folder:
48 Vagrant.configure("2") do |config|
49 config.vm.synced_folder ".", "/vagrant", type: "nfs"
53 If you add this to an existing Vagrantfile that has a running guest machine,
54 be sure to `vagrant reload` to see your changes.
56 ## NFS Synced Folder Options
58 NFS synced folders have a set of options that can be specified that are
59 unique to NFS. These are listed below. These options can be specified in
60 the final part of the `config.vm.synced_folder` definition, along with the
61 `type` option.
63 - `nfs_export` (boolean) - If this is false, then Vagrant will not modify
64 your `/etc/exports` automatically and assumes you've done so already.
66 - `nfs_udp` (boolean) - Whether or not to use UDP as the transport. UDP
67 is faster but has some limitations (see the NFS documentation for more
68 details). This defaults to true.
70 - `nfs_version` (string | integer) - The NFS protocol version to use when
71 mounting the folder on the guest. This defaults to 3.
73 ## NFS Global Options
75 There are also more global NFS options you can set with `config.nfs` in
76 the Vagrantfile. These are documented below:
78 - `functional` (bool) - Defaults to true. If false, then NFS will not be used
79 as a synced folder type. If a synced folder specifically requests NFS,
80 it will error.
82 - `map_uid` and `map_gid` (int) - The UID/GID, respectively, to map all
83 read/write requests too. This will not affect the owner/group within the
84 guest machine itself, but any writes will behave as if they were written
85 as this UID/GID on the host. This defaults to the current user running
88 - `verify_installed` (bool) - Defaults to true. If this is false, then
89 Vagrant will skip checking if NFS is installed.
91 ## Specifying NFS Arguments
93 In addition to the options specified above, it is possible for Vagrant to
94 specify alternate NFS arguments when mounting the NFS share by using the
95 `mount_options` key. For example, to use the `actimeo=2` client mount option:
98 config.vm.synced_folder ".", "/vagrant",
99 type: "nfs",
100 mount_options: ['actimeo=2']
103 This would result in the following `mount` command being executed on the guest:
106 mount -o 'actimeo=2' 172.28.128.1:'/path/to/vagrantfile' /vagrant
109 You can also tweak the arguments specified in the `/etc/exports` template
110 when the mount is added, by using the OS-specific `linux__nfs_options` or
111 `bsd__nfs_options` keys. Note that these options completely override the default
112 arguments that are added by Vagrant automatically. For example, to make the
113 NFS share asynchronous:
116 config.vm.synced_folder ".", "/vagrant",
117 type: "nfs",
118 linux__nfs_options: ['rw','no_subtree_check','all_squash','async']
121 This would result in the following content in `/etc/exports` on the host (note
122 the added `async` flag):
125 # VAGRANT-BEGIN: 21171 5b8f0135-9e73-4166-9bfd-ac43d5f14261
126 "/path/to/vagrantfile" 172.28.128.5(rw,no_subtree_check,all_squash,async,anonuid=21171,anongid=660,fsid=3382034405)
127 # VAGRANT-END: 21171 5b8f0135-9e73-4166-9bfd-ac43d5f14261
130 ## Root Privilege Requirement
132 To configure NFS, Vagrant must modify system files on the host. Therefore,
133 at some point during the `vagrant up` sequence, you may be prompted for
134 administrative privileges (via the typical `sudo` program). These
135 privileges are used to modify `/etc/exports` as well as to start and
136 stop the NFS server daemon.
138 If you do not want to type your password on every `vagrant up`, Vagrant
139 uses thoughtfully crafted commands to make fine-grained sudoers modifications
140 possible to avoid entering your password.
142 Below, we have a couple example sudoers entries. Note that you may
143 have to modify them _slightly_ on certain hosts because the way Vagrant
144 modifies `/etc/exports` changes a bit from OS to OS. If the commands below
145 are located in non-standard paths, modify them as appropriate.
147 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)."
149 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.
151 All of the snippets below require Vagrant version 1.7.3 or higher.
153 ~> **Use the appropriate group for your user** Depending on how your machine is
154 configured, you might need to use a different group than the ones listed in the examples below.
156 For OS X, sudoers should have this entry:
159 Cmnd_Alias VAGRANT_EXPORTS_ADD = /usr/bin/tee -a /etc/exports
160 Cmnd_Alias VAGRANT_NFSD = /sbin/nfsd restart
161 Cmnd_Alias VAGRANT_EXPORTS_REMOVE = /usr/bin/sed -E -e /*/ d -ibak /etc/exports
162 %admin ALL=(root) NOPASSWD: VAGRANT_EXPORTS_ADD, VAGRANT_NFSD, VAGRANT_EXPORTS_REMOVE
165 For Ubuntu Linux , sudoers should look like this:
168 Cmnd_Alias VAGRANT_EXPORTS_CHOWN = /bin/chown 0\:0 /tmp/*
169 Cmnd_Alias VAGRANT_EXPORTS_MV = /bin/mv -f /tmp/* /etc/exports
170 Cmnd_Alias VAGRANT_NFSD_CHECK = /etc/init.d/nfs-kernel-server status
171 Cmnd_Alias VAGRANT_NFSD_START = /etc/init.d/nfs-kernel-server start
172 Cmnd_Alias VAGRANT_NFSD_APPLY = /usr/sbin/exportfs -ar
173 %sudo ALL=(root) NOPASSWD: VAGRANT_EXPORTS_CHOWN, VAGRANT_EXPORTS_MV, VAGRANT_NFSD_CHECK, VAGRANT_NFSD_START, VAGRANT_NFSD_APPLY
176 For Fedora Linux, sudoers might look like this (given your user
177 belongs to the vagrant group):
180 Cmnd_Alias VAGRANT_EXPORTS_CHOWN = /bin/chown 0\:0 /tmp/*
181 Cmnd_Alias VAGRANT_EXPORTS_MV = /bin/mv -f /tmp/* /etc/exports
182 Cmnd_Alias VAGRANT_NFSD_CHECK = /usr/bin/systemctl status --no-pager nfs-server.service
183 Cmnd_Alias VAGRANT_NFSD_START = /usr/bin/systemctl start nfs-server.service
184 Cmnd_Alias VAGRANT_NFSD_APPLY = /usr/sbin/exportfs -ar
185 %vagrant ALL=(root) NOPASSWD: VAGRANT_EXPORTS_CHOWN, VAGRANT_EXPORTS_MV, VAGRANT_NFSD_CHECK, VAGRANT_NFSD_START, VAGRANT_NFSD_APPLY
188 For SUSE Linux, sudoers might look like this (given your user
189 belongs to the vagrant group):
192 Cmnd_Alias VAGRANT_CHOWN = /usr/bin/chown 0\:0 /tmp/vagrant[a-z0-9-]*
193 Cmnd_Alias VAGRANT_MV = /usr/bin/mv -f /tmp/vagrant[a-z0-9-]* /etc/exports
194 Cmnd_Alias VAGRANT_START = /usr/bin/systemctl start --no-pager nfs-server
195 Cmnd_Alias VAGRANT_STATUS = /usr/bin/systemctl status --no-pager nfs-server
196 Cmnd_Alias VAGRANT_APPLY = /usr/sbin/exportfs -ar
197 %vagrant ALL=(root) NOPASSWD: VAGRANT_CHOWN, VAGRANT_MV, VAGRANT_START, VAGRANT_STATUS, VAGRANT_APPLY
200 If you don't want to edit `/etc/sudoers` directly, you can create
201 `/etc/sudoers.d/vagrant-syncedfolders` with the appropriate entries,
202 assuming `/etc/sudoers.d` has been enabled.
204 ## Other Notes
206 **Encrypted folders:** If you have an encrypted disk, then NFS very often
207 will refuse to export the filesystem. The error message given by NFS is
208 often not clear. One error message seen is `<path> does not support NFS`.
209 There is no workaround for this other than sharing a directory which is not
212 **Version 4:** UDP is generally not a valid transport protocol for NFSv4.
213 Early implementations of NFS 4.0 still allowed UDP which allows the UDP
214 transport protocol to be used in rare cases. RFC5661 explicitly states
215 UDP alone should not be used for the transport protocol in NFS 4.1. Errors
216 due to unsupported transport protocols for specific versions of NFS are
217 not always clear. A common error message when attempting to use UDP with
221 mount.nfs: an incorrect mount option was specified
224 When using NFSv4, ensure the `nfs_udp` option is set to false. For example:
227 config.vm.synced_folder ".", "/vagrant",
228 type: "nfs",
229 nfs_version: 4,
230 nfs_udp: false
233 For more information about transport protocols and NFS version 4 see:
235 - NFSv4.0 - [RFC7530](https://tools.ietf.org/html/rfc7530#section-3.1)
236 - NFSv4.1 - [RFC5661](https://tools.ietf.org/html/rfc5661#section-2.9.1)
238 ## Troubleshooting NFS Issues
240 NFS issues may arise for a variety of reasons. The following list
241 describes how to possibly identify the root of the issue.
243 * Ensure nfs server is running on the host. Check if it is running using
244 the command `ps aux | grep nfsd`. If the nfs service is not running,
245 then it may require a manual restart.
247 * Check status of nfs-kernel-server `systemctl status nfs-kernel-server` for
248 errors like `exportfs: Failed to stat /path : No such file or directory`.
249 Then create the missing directory or remove the line from `/etc/exports`
250 and restart the nfs-kerne-server `sysctemctl start nfs-kernel-server`
252 * If using Mac, ensure that `/sbin/nfsd` has been given Full Disk Access.
254 * Ensure the synced folder is present in the hosts `/etc/exports` file.
255 If the target folder is not listed in `/etc/exports`, then ensure that
256 the synced_folder option `nfs_export` is set to `true`, or manually add
257 the entry.
259 * Ensure that the contents of `/etc/exports` is valid. For example, if running
260 nfsd, this can be done by running `nfsd checkexports`.
262 * Ensure guest machine has a nfs client installed. The client may differ
263 depending on the OS. If no nfs client is installed on the guest, then it may
264 need to be installed.
266 * Ensure the guest has access to the mounts. This can be done using something
267 like the `rpcinfo` or `showmount` commands. For example `rpcinfo -u <ip> nfs`
268 or `showmount -e <ip>`.
270 * Ensure a firewall is not blocking NFS.
272 * Try manually mounting the folder, enabling verbose output:
274 $ vagrant ssh
275 $ mount -v -t nfs -o <mount options> <ip address>:<path to folder on host> <mountpoint>
278 * If using a UDP connection: ensure UDP is enabled by the nfs server. This setting
279 can likely be changed in config file `/etc/nfs.conf`. Or, in Vagrant, set the
280 `nfs_udp` option for the synced folder to `false`.