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

1.1     ! jdf         1: **Contents**
        !             2: 
        !             3: [[!toc levels=2]]
        !             4: 
        !             5: # Kernel File Systems as Userspace Servers
        !             6: 
        !             7: This chapter describes the symbiosis of background knowledge on them, see the 
        !             8: respective web pages.
        !             9: 
        !            10: ## On Kernel File System Servers
        !            11: 
        !            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.
        !            16: 
        !            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.
        !            23: 
        !            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.
        !            31: 
        !            32: ![puffs/rump.png](File System Access Comparison)  
        !            33: **File System Access Comparison**
        !            34: 
        !            35: ## Mounting and Use
        !            36: 
        !            37: The use of kernel file systems as userspace servers requires the support for 
        !            38: [[puffs]] in the kernel.
        !            39: 
        !            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.
        !            48: 
        !            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.
        !            54: 
        !            55: ### Examples
        !            56: 
        !            57: To mount a file system image as a read-only mount:
        !            58: 
        !            59:     # rump_ffs -o ro ~/img/ffs.img /mnt
        !            60: 
        !            61: or
        !            62: 
        !            63:     # mount -t ffs -o ro,rump ~/img/ffs.img /mnt
        !            64: 
        !            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.
        !            69: 
        !            70:     # rump_ffs -o log /dev/rwd0e /mnt2
        !            71: 
        !            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:
        !            74: 
        !            75:     # rump_nfs -p host:/export /mnt3
        !            76: 
        !            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:
        !            80: 
        !            81:     server:/m/server    /m/server    nfs    rw,noauto,-r=8192,-w=8192,rump
        !            82: 
        !            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.
        !            85: 
        !            86: ## Internals
        !            87: 
        !            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).
        !            94: 
        !            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.
        !           100: 
        !           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.
        !           106: 

CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb