From c9e4a400f2cf8a5c03a98613fab01e6df38b5d4f Mon Sep 17 00:00:00 2001 From: Chris Roberts Date: Thu, 21 Dec 2017 12:51:13 -0800 Subject: [PATCH] Update SMB synced folder documentation --- .../source/docs/synced-folders/smb.html.md | 55 ++++++++++++------- 1 file changed, 36 insertions(+), 19 deletions(-) diff --git a/website/source/docs/synced-folders/smb.html.md b/website/source/docs/synced-folders/smb.html.md index 6b88857e4..a927f3207 100644 --- a/website/source/docs/synced-folders/smb.html.md +++ b/website/source/docs/synced-folders/smb.html.md @@ -19,17 +19,46 @@ 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. + SMB is currently only supported when the host machine is Windows or + macOS. The guest machine can be Windows, Linux, or macOS.
## Prerequisites -To use the SMB synced folder type, the machine running Vagrant must be -a Windows machine with PowerShell version 3 or later installed. 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. +### Windows Host + +To use the SMB synced folder type on a Windows host, the machine must have +PowerShell version 3 or later installed. In addition, when Vagrant attempts +to create new SMB shares, or remove existing SMB shares, Administrator +privileges will be required. Vagrant will request these privileges using UAC. + +### macOS Host + +To use the SMB synced folder type on a macOS host, file sharing must be enabled +for the local account. Enable SMB file sharing by following the instructions +below: + +* Open "System Preferences" +* Click "Sharing" +* Check the "On" checkbox next to "File Sharing" +* Click "Options" +* Check "Share files and folders using SMB" +* Check the "On" checkbox next to your username within "Windows File Sharing" +* Click "Done" + +When Vagrant attempts to create new SMB shares, or remove existing SMB shares, +root access will be required. Vagrant will request these privileges using +`sudo` to run the `/usr/sbin/sharing` command. Adding the following to +the system's `sudoers` configuration will allow Vagrant to manage SMB shares +without requiring a password each time: + +``` +Cmnd_Alias VAGRANT_SMB_ADD = /usr/sbin/sharing -a * -S * -s * -g * -n * +Cmnd_Alias VAGRANT_SMB_REMOVE = /usr/sbin/sharing -r * +%admin ALL=(root) NOPASSWD: VAGRANT_SMB_ADD, VAGRANT_SMB_REMOVE +``` + +### Guests 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 @@ -75,18 +104,6 @@ shell. Note that you should research if this is the right option for you. net config server /autodisconnect:-1 ``` -## 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 do not want, then -run `net share NAME /delete` for each, where NAME is the name of the share. - ## Common Issues ### "wrong fs type" Error