diff --git a/_layouts/documentation.html b/_layouts/documentation.html index 0f665ac07..55abd090d 100644 --- a/_layouts/documentation.html +++ b/_layouts/documentation.html @@ -15,6 +15,7 @@
  • Boxes
  • Multi-VM Environments
  • Host-Only Networking
    • +
  • NFS Shared Folders
  • Base Boxes
  • Systems
  • Rake Integration
    • diff --git a/docs/nfs.md b/docs/nfs.md new file mode 100644 index 000000000..5da7fe3a7 --- /dev/null +++ b/docs/nfs.md @@ -0,0 +1,91 @@ +--- +layout: documentation +title: Documentation - NFS Shared Folders +--- +# NFS Shared Folders + +Its been a long known issue that VirtualBox shared folder performance +degrades quickly as the number of files in the shared folder increases. +As a project reaches 1000+ files, doing simple things like running unit +tests or even just running an app server can be many orders of magnitude +slow (e.g. from 5 seconds to over 5 minutes). + +If you're seeing this sort of performance drop-off in your shared folders, +NFS shared +folders can offer a solution. Vagrant will orchestrate the configuration +of the NFS server on the host and will mount of the folder on the guest +for you. + +## Performance Benchmarks + +[John](http://nickelcode.com) and [I](http://github.com/mitchellh) did extensive +benchmarks using various solutions for the VirtualBox shared folder performance +issue. These benchmarks were run on a real-world rails project with a test +suite of over 6000 tests. We ran a _single_ unit test file and timed the average +of several runs: + +
    +VirtualBox Shared Folders:         5m 14s
+Host File System:                     10s
+Native VM File System:                13s
+NFS Shared Folders:                   22s
+NFS Shared Folders (warm cache):      14s
+
    + +As you can see, while there is a small performance hit compared to having +the files natively on the VM, it is perfectly reasonable versus true +VirtualBox shared folders. + +Notice the last line marked with "(warm cache)." During our daily usage +testing, we noticed that NFS really shines when many inodes of the host +filesystem are cached on the VM. Since in real world applications, only a +few files change at a time, we found that we were able to experience nearly +native VM file system performance throughout the day. + +## Prerequisites + +Before enabling NFS shared folders, there are two main requirements: + +* The host machine must have `nfsd` installed, the NFS server + daemon. This comes pre-installed on Mac OS X 10.5+ (Leopard and higher), + and is typically a simple package install away on Linux systems. +* The VM must have NFS support installed. Almost all distributions of linux/bsd + operating systems have this available through their respective package manager. + +
    +

    Disclaimer / Warning

    +

    + Vagrant must edit system files on the host in order to configure NFS. + Therefore, at some point during the vagrant up sequence, + you will be prompted by your system for administrator priveleges (via + the typical sudo command). +

    +

    + Vagrant modifies the /etc/exports file. Any previously + set exported folders will be preserved. While Vagrant is heavily tested, + the maintainers take no responsibility in any lost data in these files. +

    +
    + +## Enabling NFS Shared Folders + +NFS shared folders are very easily enabled through the Vagrantfile +configuration by setting a flag on the `config.vm.share_folder` method. +The example below uses NFS shared folders for the main project +directory: + +{% highlight ruby %} +Vagrant::Config.run do |config| + config.vm.share_folder("v-root", "/vagrant", ".", :nfs => true) +end +{% endhighlight %} + +Setting the `:nfs` flag causes that folder to be mounted via +NFS. + +## NFS customization + +[NFS exports](http://linux.die.net/man/5/exports) have quite a few configurable +options. Some of these are exposed via the [Vagrantfile](/docs/vagrantfile.html). +If you find an option you'd like exposed, please report a GitHub issue and +we'll try to add it ASAP. diff --git a/docs/vagrantfile.md b/docs/vagrantfile.md index 15696ad43..c6a0dc041 100644 --- a/docs/vagrantfile.md +++ b/docs/vagrantfile.md @@ -152,11 +152,14 @@ config.vm.provisioner = MyCustomProvisioner `config.vm.share_folder` is a function that will share a folder on the host machine with the guest machine, allowing the guest machine to read and write to a folder on the host machine. -This function takes three parameters, in the same way as `config.vm.forward_port`, with the +This function takes three mandatory parameters, in the same way as `config.vm.forward_port`, with the first parameter being a key used internally to reference the folder, the second parameter being the path on the guest machine, and the third parameter being the path to the folder to share on the host machine. If the third parameter is a _relative path_, then it is relative to where the root Vagrantfile is. +The method also takes a fourth, optional, parameter which is a has of options. This hash +can be used to enable things such as [NFS shared folders](/docs/nfs.html). + {% highlight ruby %} config.vm.share_folder("my-folder", "/folder", "/path/to/real/folder") config.vm.share_folder("another-folder", "/other", "../other") @@ -167,6 +170,17 @@ config.vm.share_folder("another-folder", "/other", "../other") These setting determine the defaults for the file name, `config.package.name`, and file extension, `config.package.extension`, used when [packaging](/docs/getting-started/packaging.html) a vm for distribution. +## config.nfs + +These settings configure [NFS shared folders](/docs/nfs.html), if they are used. + +`config.nfs.map_uid` is the UID which any remote file accesses map to on the +host machine. By default this is set to `:auto`, which tells Vagrant to match +the UID of any NFS shared folders on the host machine. + +`config.nfs.map_gid` is the same `config.nfs.map_uid` but for the GID of the +shared folder. + ## config.chef Vagrant can use [chef solo](/docs/provisioners/chef_solo.html) or [chef server](/docs/provisioners/chef_server.html)