Configuring a shared file system

Configure a virtual file system for accessing a directory tree of the host file system.

Before you begin

The KVM host needs the virtiofsd daemon.

About this task

The KVM guest must use memory that can be shared with the virtiofsd daemon on the KVM host. To attain this sharing, the virtual server must configure shared file-backed memory or shared hugepage-backed memory.

For file-backed memory, you must use the memory_backing_dir= parameter in /etc/libvirt/qemu.conf to specify a directory that holds these files.
For more information about huge pages, see Configuring huge pages.

Procedure

Configure the memory backend of the virtual server as shared.
Use the memoryBacking element (see <memoryBacking>) with a nested access element. The memoryBacking element is a child of the domain element.

access mode attribute: shared
Configure the memory as backed by files or by huge pages.
- Optional: For file-backed memory, you can use a source element as a child of the memoryBacking element.
  
  source type attribute: file
- For hugepage-backed memory, you must add a hugepages element as a child of the memoryBacking element.
Use the filesystem element as a child of the devices element to configure a device that provides access to the file system.

filesystem type attribute: mount

filesystem accessmode attribute: passthrough

With these attribute settings, the device provides access to a branch on the host file system where a guest user has the same permission as the same user has on the host.
Use the driver element as a child of the filesystem element to specify virtiofs as the file system type.

driver type attribute: virtiofs
Use the source element as a child of the filesystem element to specify the path to the host file system branch to be shared.

source dir attribute: <path>
Use the target element as a child of the filesystem element to specify a tag for the file system. This tag is used in the mount command that mounts the file system on the KVM guest.

target dir attribute: <tag>
Use the target element as a child of the filesystem element to specify a unique device bus-ID of the following form.
```
fe.n.dddd
```
where n is the subchannel set-ID and dddd is the device number. The channel subsystem-ID 0xfe is reserved to the virtual channel.
The virtual server sees the channel subsystem-ID 0x0 instead.

Tip: Do not mix device specifications with and without device numbers.

address type attribute: ccw

address cssid attribute: 0xfe
(reserved channel subsystem-ID)

address ssid attribute: <subchannel-set-ID>

address devno attribute: <device-number>

(see <address> as child element of <controller>, <disk>, <filesystem>, and <memballoon>)

Example: KVM host device bus-ID fe.0.1a12 is seen by the virtual server as device bus-ID 0.0.1a12.

If you do not specify a device number, a device bus-ID is automatically generated by using the first available device bus-ID starting with subchannel set-ID 0x0 and device number 0x0000.

Example

<domain type="kvm">
    ...
    <memoryBacking>
       <access mode="shared"/>
       <source type="file"/>
    </memoryBacking>
    ...
    <devices>
       ...
       <filesystem type="mount" accessmode="passthrough">
          <driver type="virtiofs"/>
          <source dir="/share/vs01"/>
          <target dir="my_shared_fs"/>
          <address type="ccw" cssid="0xfe" ssid="0x0" devno="0x0003"/>
       </filesystem>
       ...
   </devices>
   ...
</domain>

On the KVM guest, the following command mounts the /share/vs01 branch of the host file system at /mnt/shared according to this configuration.

# mount --types virtiofs my_shared_fs /mnt/shared/

You can persistently mount the file system branch through the following entry in /etc/fstab.

my_shared_fs /mnt/shared defaults 0 0

The KVM guest has full uid/gid access to the mounted branch of the file system.