Annotation of wikisrc/puffs/kernel_file_systems_as_userspace_servers.mdwn, revision 1.2

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.
1.2     ! jdf        32: ![File System Access Comparison](/puffs/rump.png)  
1.1       jdf        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)](
                     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 <> software: FreeBSD-CVSweb