[BACK]Return to rump.html CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / htdocs / docs / puffs

File: [cvs.NetBSD.org] / htdocs / docs / puffs / rump.html (download) (as text)

Revision 1.55, Mon Apr 19 07:19:31 2021 UTC (15 months, 3 weeks ago) by nia
Branch: MAIN
Changes since 1.54: +1 -1 lines


<!DOCTYPE html>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<meta name="generator" content="Website XSL Stylesheet V2.6.0">
<link rel="home" href="../../." title="Welcome to The NetBSD Project: Of course it runs NetBSD.">
<link rel="up" href="../../docs/puffs/." title="Filesystems in userspace: puffs, refuse, FUSE, and more">
<link rel="previous" href="../../docs/puffs/." title="Filesystems in userspace: puffs, refuse, FUSE, and more">
<link rel="next" href="../../docs/research/." title="NetBSD Documentation: Research of interest to NetBSD">
<link rel="stylesheet" href="../../global.css" type="text/css">
<link rel="stylesheet" href="../../donations/thermo/fundraiser.css" type="text/css">

<title>Kernel File Systems as Userspace Servers</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
<body class="website"><div class="webpage">
<a name="docs-puffs-rump"></a><div id="top"><a href="#mainContent" id="skiplink" tabindex="1">Skip to main content.</a></div>
<input id="hamburger" type="checkbox"><label class="menuicon" for="hamburger"><span></span><span></span><span></span></label><div id="navBar" role="navigation">
<div id="centralHeader"><div id="logo">
<a href="../../"><img id="projectLogo" alt="" height="120" src="../../images/NetBSD-smaller-tb.png"></a><a href="/"><div id="fundraiser">
<br><div id="fundraiser-amount"><div id="fundraiser-raised"></div></div>
<span class="doNotDisplay">
<a href="../../">
<li><a href="../../changes/">
	    Recent changes</a></li>
<li><a href="//blog.NetBSD.org/">
	    NetBSD blog</a></li>
<li><a href="../../gallery/presentations/">
<a href="../../about/">
<li><a href="../../people/developers.html">
<li><a href="../../gallery/">
<li><a href="//wiki.NetBSD.org/ports/">
<li><a href="//www.pkgsrc.org/">
<a href="../../docs/">
<li><a href="../../docs/misc/index.html">
	    FAQ &amp; HOWTOs</a></li>
<li><a href="../../docs/guide/en/">
	    The Guide</a></li>
<li><a href="//man.NetBSD.org/">
	    Manual pages</a></li>
<li><a href="//wiki.NetBSD.org/">
<a href="../../support/">
<li><a href="/community/">
<li><a href="/mailinglists/">
	    Mailing lists</a></li>
<li><a href="../../support/send-pr.html">
	    Bug reports</a></li>
<li><a href="../../support/security/">
<a href="../../developers/">
<li><a href="http://cvsweb.NetBSD.org/">
<li><a href="//anonhg.NetBSD.org/">
<li><a href="//nxr.NetBSD.org/">
<li><a href="//releng.NetBSD.org/">
	    Release engineering</a></li>
<li><a href="//wiki.NetBSD.org/projects/">
	    Projects list</a></li>
<div id="content"><div id="mainContent" class="fullWidth"><div class="rowOfBoxes">
<h1>Kernel File Systems as Userspace Servers</h1>
<div class="sect1">
<div class="titlepage"></div>
<h3 class="title"><a name="kernfs-server"></a></h3>
<li><a href="#about">On Kernel File System Servers</a></li>
<li><a href="#use">Mounting and Use</a></li>
<li><a href="#internals">Internals</a></li>
<h3 class="title"></h3>
    This chapter describes the symbiosis of
    background knowledge on them, see the respective web pages.
    <h4 class="title">
<a name="about"></a>On Kernel File System Servers</h4>

      The integration of the <a class="ulink" href="index.html" target="_top">puffs</a> and
      <a class="ulink" href="../rump/index.html" target="_top">rump</a> technologies
      enables mounting kernel file systems as userspace servers.
      Equivalent functionality to the in-kernel option is maintained,
      and an application accessing files is unable to tell the
      difference between the two.

      A useful scenario for mounting a kernel file system as a userspace
      server is accessing untrusted media.  As file system code is
      generally authored assuming a trusted and correct file system
      image, a corrupt or deliberately modified image can easily cause a
      kernel crash or security compromise.  By using a userspace server,
      the compromise is limited to the userspace server program, not the
      whole system.

      It also enables the mounting of kernel file systems which are not
      included as part of the kernel and loading a module is not
      desired.  Additionally, using kernel file systems from different
      operating system versions is possible, since interfacing with
      the kernel is done through the puffs protocol, not the
      kernel binary interface.  This is desired for example when
      wanting to take advantage of new functionality without upgrading
      the operating system or wanting to do a partial rollback to avoid
      a regression in a newer version.

    <div class="figure">
<a name="rump-filesystem"></a><p class="title"><b>Figure. Ĉile System Access Comparison</b></p>
<div class="figure-contents">
     <div class="mediaobject"><img src="rump.png" alt="File System Access Comparison"></div>
<br class="figure-break">

    <h4 class="title">
<a name="use"></a>Mounting and Use</h4>
      The use of kernel file systems as userspace servers requires
      the support for <a class="ulink" href="index.html" target="_top">puffs</a> in the

      To mount the file system, the relevant <span class="command"><strong>rump_fs</strong></span>
      command must be run.  These commands share the same suffix as the
      normal in-kernel <span class="command"><strong>mount_fs</strong></span> commands.  For
      instance, the equivalent of <span class="command"><strong>mount_msdos</strong></span> is
      <span class="command"><strong>rump_msdos</strong></span>.  The usage is also equal, so the
      manual page of the mount equivalent should be consulted.  The only
      exception is that rump file systems do not require the use of
      <span class="command"><strong>vnconfig</strong></span> to mount regular files.  Rather, such
      images can be mounted directly by using the image as the
      device file path.

      To unmount, <span class="command"><strong>umount</strong></span> should be run as normal.
      While it is possible to violently kill the server process, this
      does not give the file system an opportunity to flush its caches
      and cleanly unmount and may result in data loss.  In case the
      server process is violently killed, puffs automatically performs a
      forced unmount and no further action is necessary.

    <div class="sect4">
<div class="titlepage"><div><div><h5 class="title">
<a name="examples"></a>Examples</h5></div></div></div>

        To mount a file system image as a read-only mount:

<pre class="programlisting">
pain-rustique&gt; rump_ffs -o ro ~/img/ffs.img /mnt
pain-rustique&gt; mount -t ffs -o ro,rump ~/img/ffs.img /mnt

	If you want to mount a disk device instead, the procedure
	is the same.  This example also instructs the file system
	to use journalling.  Note: for reasons beyond the scope of
	this document, it is highly recommended you use the raw
	device instead of the usual block device.

<pre class="programlisting">
pain-rustique&gt; rump_ffs -o log /dev/rwd0e /mnt2

        Mounting nfs works in a similar fashion.  The command line flag
        <code class="code">-p</code> makes sure a non-root mount is succesful if the
        server allows them:

<pre class="programlisting">
pain-rustique&gt; rump_nfs -p host:/export /mnt3

        Finally, the option <code class="option">rump</code> in fstab signals that
	the file system should be mounted using rump instead of the
	kernel file service.  The following example is for specifying an
	nfs share mount from a laptop over wireless:
<pre class="programlisting">
server:/m/server    /m/server    nfs    rw,noauto,-r=8192,-w=8192,rump

        After this the file system will show up on the mountlist and you
        can access it through the mountpath like any other mounted file

    <h4 class="title">
<a name="internals"></a>Internals</h4>

      Internally, kernel file systems are implemented against the
      kernel virtual file system layer.  This layer defines a protocol
      which kernel file systems convert to their backend storage
      protocol to satisfy the operation.  The result is then converted
      back to a format the virtual file system layer understands and
      passed back to caller (most likely an application, although it can
      be for example the NFS server).

      Analogously, puffs file systems must interpret and convert the
      puffs file system interface protocol.  While the puffs interface
      is very similar to the kernel virtual file system interface,
      there are differences in some parameters.  For example, the
      virtual file system passes information about I/O as a
      reference to <code class="code">struct uiomove</code>.  In contrast, puffs
      passes this as explicit parameters.

      Since a userspace kernel file system server attaches itself
      as a puffs file system, protocol conversion from puffs to the
      kernel virtual file system must happen, if the whole protocol
      stack is to work.  This conversion of protocols is done by
      the p2k, or puffs-to-kernel, component.  It is installed
      as <code class="filename">libp2k</code> and linked with all kernel
      file system servers.
<div class="navfoot"></div>
<div id="footer"><div id="footerContent"><center>
<span class="footfeed"><a href="//www.NetBSD.org/cgi-bin/feedback.cgi">
	  Contact</a> |
      </span><span class="footcopy"><a href="../../about/disclaimer.html">
      Disclaimer</a> |

      <span class="copyright">Copyright 1994-2021 The NetBSD Foundation, Inc. </span>ALL RIGHTS RESERVED.<br>NetBSD<sup>/sup> is a registered trademark of The NetBSD
	Foundation, Inc.</span>