"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 or download 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.

    1 ---
    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
    7 
    8   shared folders have high performance penalties. If you are seeing less than
    9 
   10   ideal performance with synced folders, NFS can offer a solution. Vagrant has
   11 
   12   built-in support to orchestrate the configuration of the NFS server on the
   13   host
   14 
   15   and guest for you.
   16 ---
   17 
   18 # NFS
   19 
   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.
   25 
   26 ~> **Windows users:** NFS folders do not work on Windows hosts. Vagrant will
   27 ignore your request for NFS synced folders on Windows.
   28 
   29 ## Prerequisites
   30 
   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.
   34 
   35 Additionally, the guest machine must have NFS support installed. This is
   36 also usually a simple package installation away.
   37 
   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.
   42 
   43 ## Enabling NFS Synced Folders
   44 
   45 To enable NFS, just add the `type: "nfs"` flag onto your synced folder:
   46 
   47 ```ruby
   48 Vagrant.configure("2") do |config|
   49   config.vm.synced_folder ".", "/vagrant", type: "nfs"
   50 end
   51 ```
   52 
   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.
   55 
   56 ## NFS Synced Folder Options
   57 
   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.
   62 
   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.
   65 
   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.
   69 
   70 - `nfs_version` (string | integer) - The NFS protocol version to use when
   71   mounting the folder on the guest. This defaults to 3.
   72 
   73 ## NFS Global Options
   74 
   75 There are also more global NFS options you can set with `config.nfs` in
   76 the Vagrantfile. These are documented below:
   77 
   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.
   81 
   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
   86   Vagrant.
   87 
   88 - `verify_installed` (bool) - Defaults to true. If this is false, then
   89   Vagrant will skip checking if NFS is installed.
   90 
   91 ## Specifying NFS Arguments
   92 
   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:
   96 
   97 ```ruby
   98 config.vm.synced_folder ".", "/vagrant",
   99   type: "nfs",
  100   mount_options: ['actimeo=2']
  101 ```
  102 
  103 This would result in the following `mount` command being executed on the guest:
  104 
  105 ```
  106 mount -o 'actimeo=2' 172.28.128.1:'/path/to/vagrantfile' /vagrant
  107 ```
  108 
  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:
  114 
  115 ```ruby
  116 config.vm.synced_folder ".", "/vagrant",
  117   type: "nfs",
  118   linux__nfs_options: ['rw','no_subtree_check','all_squash','async']
  119 ```
  120 
  121 This would result in the following content in `/etc/exports` on the host (note
  122 the added `async` flag):
  123 
  124 ```
  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
  128 ```
  129 
  130 ## Root Privilege Requirement
  131 
  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.
  137 
  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.
  141 
  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.
  146 
  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)."
  148 
  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.
  150 
  151 All of the snippets below require Vagrant version 1.7.3 or higher.
  152 
  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.
  155 
  156 For OS X, sudoers should have this entry:
  157 
  158 ```
  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
  163 ```
  164 
  165 For Ubuntu Linux , sudoers should look like this:
  166 
  167 ```
  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
  174 ```
  175 
  176 For Fedora Linux, sudoers might look like this (given your user
  177 belongs to the vagrant group):
  178 
  179 ```
  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
  186 ```
  187 
  188 For SUSE Linux, sudoers might look like this (given your user
  189 belongs to the vagrant group):
  190 
  191 ```
  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
  198 ```
  199 
  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.
  203 
  204 ## Other Notes
  205 
  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
  210 encrypted.
  211 
  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
  218 NFSv4:
  219 
  220 ```
  221 mount.nfs: an incorrect mount option was specified
  222 ```
  223 
  224 When using NFSv4, ensure the `nfs_udp` option is set to false. For example:
  225 
  226 ```ruby
  227 config.vm.synced_folder ".", "/vagrant",
  228   type: "nfs",
  229   nfs_version: 4,
  230   nfs_udp: false
  231 ```
  232 
  233 For more information about transport protocols and NFS version 4 see:
  234 
  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)
  237 
  238 ## Troubleshooting NFS Issues
  239 
  240 NFS issues may arise for a variety of reasons. The  following list
  241 describes how to possibly identify the root of the issue.
  242 
  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.
  246 
  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`
  251 
  252 * If using Mac, ensure that `/sbin/nfsd` has been given Full Disk Access.
  253 
  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.
  258 
  259 * Ensure that the contents of `/etc/exports` is valid. For example, if running
  260   nfsd, this can be done by running `nfsd checkexports`.
  261 
  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.
  265 
  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>`.
  269 
  270 * Ensure a firewall is not blocking NFS.
  271 
  272 * Try manually mounting the folder, enabling verbose output:
  273     ```
  274     $ vagrant ssh
  275     $ mount -v -t nfs -o <mount options> <ip address>:<path to folder on host> <mountpoint>
  276     ```
  277 
  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`.