4.3. Shared Folders

With the shared folders feature of Oracle VM VirtualBox, you can access files of your host system from within the guest system. This is similar to how you would use network shares in Windows networks, except that shared folders do not require networking, only the Guest Additions. Shared folders are supported with Windows 2000 or later, Linux, and Oracle Solaris guests. Oracle VM VirtualBox includes experimental support for Mac OS X and OS/2 guests.

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

To share a host folder with a virtual machine in Oracle VM VirtualBox, you must specify the path of the folder and choose a share name that the guest can use to access the shared folder. This happens on the host. In the guest you can then use the share name to connect to it and access files.

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

In the window of a running VM, you 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 the 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 7.31, “VBoxManage sharedfolder add/remove”.

There are two types of shares:

Permanent shares, that are saved with the VM settings.
Transient shares, that are added at runtime and disappear when the VM is powered off. These can be created using a checkbox in the VirtualBox Manager, or by using the --transient option of the VBoxManage sharedfolder add command.

Shared folders can either be read-write or read-only. This means that the guest is either allowed to both read and write, or just read files on the host. By default, shared folders are read-write. Read-only folders can be created using a checkbox in the VirtualBox Manager, or with the --readonly option of the VBoxManage sharedfolder add command.

Oracle VM VirtualBox shared folders also support symbolic links, also called symlinks, under the following conditions:

The host operating system must support symlinks. For example, a Mac OS X, Linux, or Oracle Solaris host is required.
Currently only Linux and Oracle 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 a shared folder as follows:
```
VBoxManage setextradata "VM name" VBoxInternal2/SharedFoldersEnableSymlinksCreate/sharename 1
```

4.3.1. Manual Mounting

You can mount the shared folder from inside a VM, in 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. To attach the host's shared folder to your Windows guest, open Windows Explorer and look for the folder in My Networking Places, Entire Network, Oracle VM 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 command:
```
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 Oracle Solaris guest, use the following command:
```
mount -F vboxfs [-o OPTIONS] sharename mountpoint
```
Replace sharename, use a lowercase string, with the share name specified with VBoxManage or the VirtualBox Manager. Replace mountpoint with the path where you want the share to be mounted on the guest, such as /mnt/share. The usual mount rules apply. For example, create this directory first if it does not exist yet.
Here is an example of mounting the shared folder for the user jack on Oracle 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
```
This option sets 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 is used.
```
convertcp CHARSET
```
This option specifies the character set used for the shared folder name. This is UTF-8 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 can allow access by normal users in read/write mode, depending on the settings, even if root has mounted the filesystem.
In an OS/2 guest, use the VBoxControl command to manage shared folders. For example:
```
VBoxControl sharedfolder use D: MyShareName
VBoxControl sharedfolder unuse D:
VBoxControl sharedfolder list
```
As with Windows guests, shared folders can also be accessed via UNC using \\VBoxSF\, \\VBoxSvr\ or \\VBoxSrv\ as the server name and the shared folder name as sharename.

4.3.2. Automatic Mounting

Oracle VM VirtualBox provides the option to mount shared folders automatically. When automatic mounting is enabled for a shared folder, the Guest Additions service will mount it for you automatically. For Windows or OS/2, a preferred drive letter can also be specified. For Linux or Oracle Solaris, a mount point directory can also be specified.

If a drive letter or mount point is not specified, or is in use already, an alternative location is found by the Guest Additions service. The service searches for an alternative location depending on the guest OS, as follows:

Windows and OS/2 guests. Search for a free drive letter, starting at Z:. If all drive letters are assigned, the folder is not mounted.
Linux and Oracle Solaris guests. Folders are mounted under the /media directory. The folder name is normalized (no spaces, slashes or colons) and is prefixed with sf_.
For example, if you have a shared folder called myfiles, it will appear as /media/sf_myfiles in the guest.
The guest properties /VirtualBox/GuestAdd/SharedFolders/MountDir and the more generic /VirtualBox/GuestAdd/SharedFolders/MountPrefix can be used to override the automatic mount directory and prefix. See Section 4.7, “Guest Properties”.

Access to an automatically mounted shared folder is granted to everyone in a Windows guest, including the guest user. For Linux and Oracle Solaris guests, access is restricted to members of the group vboxsf and the root user.