Documentation/9psetup

This section details the steps involved in setting up VirtFS (Plan 9 folder sharing over Virtio - I/O virtualization framework) between the guest and host operating systems. The instructions are followed by an example usage of the mentioned steps.

Preparation

1. Download the latest kernel code (2.6.36.rc4 or newer) from http://www.kernel.org to build the kernel image for the guest.

2. Ensure the following 9P options are enabled in the kernel configuration.

    CONFIG_NET_9P=y
    CONFIG_NET_9P_VIRTIO=y
    CONFIG_NET_9P_DEBUG=y (Optional)
    CONFIG_9P_FS=y
    CONFIG_9P_FS_POSIX_ACL=y

3. Get the latest git repository from http://git.qemu.org/ or http://repo.or.cz/w/qemu.git.

4. Configure QEMU for the desired target. Note that if the configuration step prompts ATTR/XATTR as 'no' then you need to install libattr & libattr-dev first.

For debian based systems install packages libattr1 & libattr1-dev and for rpm based systems install libattr & libattr-devel. Proceed to configure and build QEMU.

5. Setup the guest OS image and ensure kvm modules are loaded.

Starting the Guest

To start the guest add the following options to enable 9P sharing in QEMU

    -fsdev local,id=[id],path=[path to share],security_model=[mapped|passthrough|none] -device virtio-9p-pci,fsdev=[id],[mount tag]

You can instead use the following also, which is just a short-cut of the above command.

    -virtfs local,path=[path to share],security_model=[mapped|passthrough|none],mount_tag=[mount tag]

Options:

fstype: Type of the file system. Only "local" tag is supported for now. In future we plan on adding various types of network and cluster filesystems here.

id: Identifier used to refer to this fsdev.

path: The path on the host that is identified by this fsdev.

security_model: Valid options are mapped, passthrough & none.

mapped: Files are created with Qemu user credentials and the client-user's credentials are saved in extended attributes.
passthrough: Files on the filesystem are directly created with client-user's credentials.
none: It is equivalent to passthrough security model; the only exception is, failure of priviliged operation like chown are ignored. This makes a passthrough like security model usable for people who run kvm as non root.

mount_tag: A tag which acts as a hint to the guest OS and is used to mount this exported path.

Mounting the shared path

You can mount the shared folder using

    mount -t 9p -o trans=virtio [mount tag] [mount point] -oversion=9p2000.L

mount tag: As specified in Qemu commandline.
mount point: Path to mount point.
trans: Transport method (here virtio for using 9P over virtio)
version: Protocol version. By default it is 9p2000.u .

Other options that can be used include:

msize: Maximum packet size including any headers. By default it is 8KB.
access: Following are the access modes

access=user : If a user tries to access a file on v9fs filesystem for the first time, v9fs sends an attach command (Tattach) for that user. This is the default mode.
access=<uid> : It only allows the user with uid=<uid> to access the files on the mounted filesystem
access=any : v9fs does single attach and performs all operations as one user
access=client : Fetches access control list values from the server and does an access check on the client.

Example

An example usage of the above steps (tried on an Ubuntu Lucid Lynx system):

1. Download the latest kernel source from http://www.kernel.org

2. Build kernel image

Ensure relevant kernel configuration options are enabled pertaining to

Virtualization
KVM
Virtio
9P

Compile

3. Get the latest QEMU git repository in a fresh directory using

    git clone git://repo.or.cz/qemu.git

4. Configure QEMU

For example for i386-softmm with debugging support, use

    ./configure '--target-list=i386-softmmu' '--enable-debug' '--enable-kvm' '--prefix=/home/guest/9p_setup/qemu/'

If this step prompts ATTR/XATTR as 'no', install packages libattr1 and libattr1-dev on your system using:

    sudo apt-get install libattr1
    sudo apt-get install libattr1-dev

5. Compile QEMU

    make
    make install

6. Guest OS installation (Installing Ubuntu Lucid Lynx here)

Create Guest image (here of size 2 GB)

    dd if=/dev/zero of=/home/guest/9p_setup/ubuntu-lucid.img bs=1M count=2000

Burn a filesystem on the image file (ext4 here)

    mkfs.ext4 /home/guest/9p_setup/ubuntu-lucid.img

Mount the image file

    mount -o loop /home/guest/9p_setup/ubuntu-lucid.img /mnt/temp_mount

Install the Guest OS

For installing a Debain system you can use package debootstrap

    debootstrap lucid /mnt/temp_mount

Once the OS is installed, unmount the guest image.

    umount /mnt/temp_mount

7. Load the KVM modules on the host (for intel here)

    modprobe kvm
    modprobe kvm_intel

8. Start the Guest OS

   /home/guest/9p_setup/qemu/bin/qemu -drive file=/home/guest/9p_setup/ubuntu-lucid.img,if=virtio \ 
   -kernel /path/to/kernel/bzImage -append "console=ttyS0 root=/dev/vda" -m 512 -smp 1 \
   -fsdev local,id=test_dev,path=/home/guest/9p_setup/shared,security_model=none -device virtio-9p-pci,fsdev=test_dev,mount_tag=test_mount -enable-kvm

The above command runs a VNC server. To view the guest OS, install and use any VNC viewer (for instance xclientvncviewer).

9. Mounting shared folder

Mount the shared folder on guest using

    mount -t 9p -o trans=virtio test_mount /tmp/shared/ -oversion=9p2000.L

In the above example the folder /home/guest/9p_setup/shared of the host is shared with the folder /tmp/shared on the guest.