## Plan 9

The Plan 9 (9p) file system is used to share files with Linux guests. OpenVMM includes a 9p server
that implements the 9P2000.L protocol. This server can run on both Linux and Windows hosts through
the use of [LxUtil](lxutil.md).

The 9p server uses the [virtio](../infra/virtio.md) transport, which allows it to communicate with the
guest by using shared memory.

### Usage

Plan 9 file systems are added to the VM by specifying the `--virtio-9p` command line option when
running OpenVMM. This argument takes a value of the format `tag:root`, where `tag` is the mount tag
used to identify the virtio device in the VM, and `root` is the root path of the file system share
on the host.

For example, the argument `--virtio-9p=myfs:C:\` creates a 9p file system that exposes the host's
entire C: drive using the mount tag `myfs`.

To use the file system in the guest, it must be mounted, which is done by running the following
command as root:

```
mount -t 9p tag /mnt/point -o trans=virtio
```

Where `tag` matches the mount tag provided in the `--virtio-9p` argument, and `/mnt/point` is the
directory where you want to mount the file system.

You can create multiple 9p file systems by specifying the `--virtio-9p` option more than once, with
different mount tags (you can actually reuse the same mount tag more than once, but there is no
way to determine in which order they will be used when mounting).

### Details

For each occurrence of the `--virtio-9p` option, OpenVMM will open the root of the share, and create
a `Plan9FileSystem` instance. This instance is associated with a `VirtioPlan9Device` which creates
a virtio PCI device which is added to the guest.

The `VirtioPlan9Device` will receive 9p protocol messages on a single virtio queue, and hand them
off to the `Plan9FileSystem`, which implements the protocol and accesses the host's file system.

Currently, the 9p server only implements a small subset of the 9P2000.L protocol. It only supports
reading and writing files, creating new files, listing directories, and retrieving file attributes.
This is sufficient if you just want to copy files back and forth between the host and the guest, but
doesn't support any advanced scenarios such as symbolic links, chmod/chown, extended attributes, or
anything else.

### Debugging

You can specify the `--virtio-9p-debug` option to enable debug output for the 9p server. This will
cause it to log every request and reply, so this is very verbose.

### See also

- [Bell Labs documentation of the original Plan 9 File Protocol](http://9p.io/magic/man2html/5/0intro)
- [9P2000.L protocol documentation](https://github.com/chaos/diod/blob/master/protocol.md)
- [Kernel documentation of the Linux 9p client](https://www.kernel.org/doc/html/latest/filesystems/9p.html)
