diff --git a/website/docs/source/layouts/layout.erb b/website/docs/source/layouts/layout.erb index 1ef236752..2bbfc7f2b 100644 --- a/website/docs/source/layouts/layout.erb +++ b/website/docs/source/layouts/layout.erb @@ -177,6 +177,7 @@ >Basic Usage >NFS >RSync + >SMB >VirtualBox <% end %> diff --git a/website/docs/source/v2/synced-folders/smb.html.md b/website/docs/source/v2/synced-folders/smb.html.md new file mode 100644 index 000000000..130a7dabf --- /dev/null +++ b/website/docs/source/v2/synced-folders/smb.html.md @@ -0,0 +1,75 @@ +--- +page_title: "SMB - Synced Folders" +sidebar_current: "syncedfolder-smb" +--- + +# SMB + +**Synced folder type:** `smb` + +Vagrant can use [SMB](http://en.wikipedia.org/wiki/Server_Message_Block) +as a mechanism to create a bi-directional synced folder between the host +machine and the Vagrant machine. + +SMB is built-in to Windows machines and provides a higher performance +alternative to some other mechanisms such as VirtualBox shared folders. + +
+

+ Windows only! SMB is currently only supported + when the host machine is Windows. The guest machine can be Windows + or Linux. +

+
+ +## Prerequisites + +To use the SMB synced folder type, the machine running Vagrant must be +a Windows machine. In addition to this, the command prompt executing Vagrant +must have administrative privileges. Vagrant requires these privileges in +order to create new network folder shares. + +The destination machine must be able to mount SMB filesystems. On Linux +the package to do this is usually called `smbfs` or `cifs`. Vagrant knows +how to automatically install this for some operating systems. + +## Options + +The SMB synced folder type has a variety of options it accepts: + +* `smb_host` (string) - The host IP where the SMB mount is located. If this + isn't specified, Vagrant will attempt to determine this automatically. + +* `smb_password` (string) - The password used for authentication to mount + the SMB mount. This is the password for the username specified by + `smb_username`. If this is not specified, Vagrant will prompt you for it. + It is highly recommended that you do not set this, since it would expose + your password directly in your Vagrantfile. + +* `smb_username` (string) - The username used for authentication to mount + the SMB mount. This is the username to access the mount, _not_ the username + of the account where the folder is being mounted to. This is usually your + Windows username. If this isn't specified, Vagrant will prompt you for + it. + +## Example + +The following is an example of using SMB to sync a folder: + +
+Vagrant.configure("2") do |config|
+  config.vm.synced_folder ".", "/vagrant", type: "smb"
+end
+
+ +## Limitations + +Because SMB is a relatively new synced folder type in Vagrant, it still +has some rough edges. Hopefully, future versions of Vagrant will address +these. + +The primary limitation of SMB synced folders at the moment is that they are +never pruned or cleaned up. Once the folder share is defined, Vagrant never +removes it. To clean up SMB synced folder shares, periodically run +`net share` in a command prompt, find the shares you don't want, then +run `net share NAME /delete` for each, where NAME is the name of the share.