4.3. Shared folders

Oracle VM VirtualBox

4.3. Shared folders

With the "shared folders" feature of VirtualBox, you can access files of your host system from within the guest system. This is similar how you would use network shares in Windows networks -- except that shared folders do not need require networking, only the Guest Additions. Shared Folders are supported with Windows (2000 or newer), Linux and Solaris guests.

Shared folders must physically reside on the host and are then shared with the guest, which uses a special file system driver in the Guest Addition to talk to the host. For Windows guests, shared folders are implemented as a pseudo-network redirector; for Linux and Solaris guests, the Guest Additions provide a virtual file system.

To share a host folder with a virtual machine in VirtualBox, you must specify the path of that folder and choose for it a "share name" that the guest can use to access it. Hence, first create the shared folder on the host; then, within the guest, connect to it.

There are several ways in which shared folders can be set up for a particular virtual machine:

In the window of a running VM, you can select "Shared folders" from the "Devices" menu, or click on the folder icon on the status bar in the bottom right corner.
If a VM is not currently running, you can configure shared folders in each virtual machine's "Settings" dialog.
From the command line, you can create shared folders using VBoxManage, as follows:
```
VBoxManage sharedfolder add "VM name" --name "sharename" --hostpath "C:\test"
```
See Section 8.32, “VBoxManage sharedfolder add/remove” for details.

There are two types of shares:

VM shares which are only available to the VM for which they have been defined;
transient VM shares, which can be added and removed at runtime and do not persist after a VM has stopped; for these, add the --transient option to the above command line.

Shared folders have read/write access to the files at the host path by default. To restrict the guest to have read-only access, create a read-only shared folder. This can either be achieved using the GUI or by appending the parameter --readonly when creating the shared folder with VBoxManage.

Starting with version 4.0, VirtualBox shared folders also support symbolic links (symlinks), under the following conditions:

The host operating system must support symlinks (i.e. a Mac, Linux or Solaris host is required).
Currently only Linux and Solaris Guest Additions support symlinks.
For security reasons the guest OS is not allowed to create symlinks by default. If you trust the guest OS to not abuse the functionality, you can enable creation of symlinks for "sharename" with:
```
VBoxManage setextradata "VM name" VBoxInternal2/SharedFoldersEnableSymlinksCreate/sharename 1
```

4.3.1. Manual mounting

You can mount the shared folder from inside a VM the same way as you would mount an ordinary network share:

In a Windows guest, shared folders are browseable and therefore visible in Windows Explorer. So, to attach the host's shared folder to your Windows guest, open Windows Explorer and look for it under "My Networking Places" → "Entire Network" → "VirtualBox Shared Folders". By right-clicking on a shared folder and selecting "Map network drive" from the menu that pops up, you can assign a drive letter to that shared folder.

Alternatively, on the Windows command line, use the following:
```
net use x: \\vboxsvr\sharename
```
While vboxsvr is a fixed name (note that vboxsrv would also work), replace "x:" with the drive letter that you want to use for the share, and sharename with the share name specified with VBoxManage.
In a Linux guest, use the following command:
```
mount -t vboxsf [-o OPTIONS] sharename mountpoint
```
To mount a shared folder during boot, add the following entry to /etc/fstab:
```
sharename   mountpoint   vboxsf   defaults  0   0
```
In a Solaris guest, use the following command:
```
mount -F vboxfs [-o OPTIONS] sharename mountpoint
```
Replace sharename (use lowercase) with the share name specified with VBoxManage or the GUI, and mountpoint with the path where you want the share to be mounted on the guest (e.g. /mnt/share). The usual mount rules apply, that is, create this directory first if it does not exist yet.

Here is an example of mounting the shared folder for the user "jack" on Solaris:
```
$ id
uid=5000(jack) gid=1(other)
$ mkdir /export/home/jack/mount
$ pfexec mount -F vboxfs -o uid=5000,gid=1 jackshare /export/home/jack/mount
$ cd ~/mount
$ ls
sharedfile1.mp3 sharedfile2.txt
$
```
Beyond the standard options supplied by the mount command, the following are available:
```
iocharset CHARSET
```
to set the character set used for I/O operations. Note that on Linux guests, if the "iocharset" option is not specified then the Guest Additions driver will attempt to use the character set specified by the CONFIG_NLS_DEFAULT kernel option. If this option is not set either then UTF-8 will be used. Also,
```
convertcp CHARSET
```
is available in order to specify the character set used for the shared folder name (utf8 by default).

The generic mount options (documented in the mount manual page) apply also. Especially useful are the options uid, gid and mode, as they allow access by normal users (in read/write mode, depending on the settings) even if root has mounted the filesystem.

4.3.2. Automatic mounting

Starting with version 4.0, VirtualBox can mount shared folders automatically, at your option. If automatic mounting is enabled for a specific shared folder, the Guest Additions will automatically mount that folder as soon as a user logs into the guest OS. The details depend on the guest OS type:

With Windows guests, any auto-mounted shared folder will receive its own drive letter (e.g. E:) depending on the free drive letters remaining in the guest.

If there no free drive letters left, auto-mounting will fail; as a result, the number of auto-mounted shared folders is typically limited to 22 or less with Windows guests.
With Linux guests, auto-mounted shared folders are mounted into the /media directory, along with the prefix sf_. For example, the shared folder myfiles would be mounted to /media/sf_myfiles on Linux and /mnt/sf_myfiles on Solaris.

The guest property /VirtualBox/GuestAdd/SharedFolders/MountPrefix determines the prefix that is used. Change that guest property to a value other than "sf" to change that prefix; see Section 4.7, “Guest properties” for details.

Note

Access to auto-mounted shared folders is only granted to the user group vboxsf, which is created by the VirtualBox Guest Additions installer. Hence guest users have to be member of that group to have read/write access or to have read-only access in case the folder is not mapped writable.

To change the mount directory to something other than /media, you can set the guest property /VirtualBox/GuestAdd/SharedFolders/MountDir.
Solaris guests behave like Linux guests except that /mnt is used as the default mount directory instead of /media.

To have any changes to auto-mounted shared folders applied while a VM is running, the guest OS needs to be rebooted. (This applies only to auto-mounted shared folders, not the ones which are mounted manually.)

previous page start next page

4.3. Shared folders

Oracle VM VirtualBox