Annotation of wikisrc/puffs/kernel_file_systems_as_userspace_servers.mdwn, revision 1.1
1.1 ! jdf 1: **Contents**
! 3: [[!toc levels=2]]
! 5: # Kernel File Systems as Userspace Servers
! 7: This chapter describes the symbiosis of background knowledge on them, see the
! 8: respective web pages.
! 10: ## On Kernel File System Servers
! 12: The integration of the [[puffs]] and [[rump]] technologies enables mounting
! 13: kernel file systems as userspace servers. Equivalent functionality to the
! 14: in-kernel option is maintained, and an application accessing files is unable to
! 15: tell the difference between the two.
! 17: A useful scenario for mounting a kernel file system as a userspace server is
! 18: accessing untrusted media. As file system code is generally authored assuming a
! 19: trusted and correct file system image, a corrupt or deliberately modified image
! 20: can easily cause a kernel crash or security compromise. By using a userspace
! 21: server, the compromise is limited to the userspace server program, not the whole
! 22: system.
! 24: It also enables the mounting of kernel file systems which are not included as
! 25: part of the kernel and loading a module is not desired. Additionally, using
! 26: kernel file systems from different operating system versions is possible, since
! 27: interfacing with the kernel is done through the puffs protocol, not the kernel
! 28: binary interface. This is desired for example when wanting to take advantage of
! 29: new functionality without upgrading the operating system or wanting to do a
! 30: partial rollback to avoid a regression in a newer version.
! 32: ![puffs/rump.png](File System Access Comparison)
! 33: **File System Access Comparison**
! 35: ## Mounting and Use
! 37: The use of kernel file systems as userspace servers requires the support for
! 38: [[puffs]] in the kernel.
! 40: To mount the file system, the relevant `rump_fs` command must be run. These
! 41: commands share the same suffix as the normal in-kernel `mount_fs` commands. For
! 42: instance, the equivalent of `mount_msdos` is `rump_msdos`. The usage is also
! 43: equal, so the manual page of the mount equivalent should be consulted. The only
! 44: exception is that rump file systems do not require the use of
! 45: [vnconfig(8)](http://netbsd.gw.com/cgi-bin/man-cgi?vnconfig+8+NetBSD-current+i386)
! 46: to mount regular files. Rather, such images can be mounted directly by using the
! 47: image as the device file path.
! 49: To unmount, `umount` should be run as normal. While it is possible to violently
! 50: kill the server process, this does not give the file system an opportunity to
! 51: flush its caches and cleanly unmount and may result in data loss. In case the
! 52: server process is violently killed, puffs automatically performs a forced
! 53: unmount and no further action is necessary.
! 55: ### Examples
! 57: To mount a file system image as a read-only mount:
! 59: # rump_ffs -o ro ~/img/ffs.img /mnt
! 61: or
! 63: # mount -t ffs -o ro,rump ~/img/ffs.img /mnt
! 65: If you want to mount a disk device instead, the procedure is the same. This
! 66: example also instructs the file system to use journalling. Note: for reasons
! 67: beyond the scope of this document, it is highly recommended you use the raw
! 68: device instead of the usual block device.
! 70: # rump_ffs -o log /dev/rwd0e /mnt2
! 72: Mounting nfs works in a similar fashion. The command line flag `-p` makes sure a
! 73: non-root mount is succesful if the server allows them:
! 75: # rump_nfs -p host:/export /mnt3
! 77: Finally, the option `rump` in fstab signals that the file system should be
! 78: mounted using rump instead of the kernel file service. The following example is
! 79: for specifying an nfs share mount from a laptop over wireless:
! 81: server:/m/server /m/server nfs rw,noauto,-r=8192,-w=8192,rump
! 83: After this the file system will show up on the mountlist and you can access it
! 84: through the mountpath like any other mounted file system.
! 86: ## Internals
! 88: Internally, kernel file systems are implemented against the kernel virtual file
! 89: system layer. This layer defines a protocol which kernel file systems convert to
! 90: their backend storage protocol to satisfy the operation. The result is then
! 91: converted back to a format the virtual file system layer understands and passed
! 92: back to caller (most likely an application, although it can be for example the
! 93: NFS server).
! 95: Analogously, puffs file systems must interpret and convert the puffs file system
! 96: interface protocol. While the puffs interface is very similar to the kernel
! 97: virtual file system interface, there are differences in some parameters. For
! 98: example, the virtual file system passes information about I/O as a reference to
! 99: `struct uiomove`. In contrast, puffs passes this as explicit parameters.
! 101: Since a userspace kernel file system server attaches itself as a puffs file
! 102: system, protocol conversion from puffs to the kernel virtual file system must
! 103: happen, if the whole protocol stack is to work. This conversion of protocols is
! 104: done by the p2k, or puffs-to-kernel, component. It is installed as `libp2k` and
! 105: linked with all kernel file system servers.
CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb