Annotation of htdocs/docs/puffs/rump.html, Revision 1.42
1.17 jym 1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
1.1 pooka 2: <html>
3: <head>
4: <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
5: <meta name="generator" content="Website XSL Stylesheet V2.6.0">
1.2 kano 6: <link rel="home" href="../../." title="Welcome to The NetBSD Project: Of course it runs NetBSD.">
7: <link rel="up" href="../../docs/puffs/." title="Filesystems in userspace: puffs, refuse, FUSE, and more">
8: <link rel="previous" href="../../docs/puffs/." title="Filesystems in userspace: puffs, refuse, FUSE, and more">
9: <link rel="next" href="../../docs/research/." title="NetBSD Documentation: Research of interest to NetBSD">
1.4 dsieger 10: <link rel="stylesheet" href="../../global.css" type="text/css">
1.1 pooka 11:
1.8 pooka 12: <title>Kernel File Systems as Userspace Servers</title>
1.1 pooka 13: </head>
14: <body class="website"><div class="webpage">
1.40 maya 15: <a name="docs-puffs-rump"></a><div id="top"><a href="#mainContent" id="skiplink" tabindex="1">Skip to main content.</a></div>
1.28 maya 16: <div id="centralHeader"><div id="logo">
1.21 jym 17: <a href="../../"><img alt="[NetBSD Logo]" src="../../images/NetBSD-smaller.png"></a><div id="name"><a href="../../">
1.19 jym 18: The NetBSD Project
1.21 jym 19: </a></div>
20: <div id="slogan"><a href="../../">
1.19 jym 21: “Of course it runs NetBSD”
1.21 jym 22: </a></div>
1.28 maya 23: </div></div>
1.29 maya 24: <input id="hamburger" type="checkbox"><label class="menuicon" for="hamburger"><span></span></label><div id="navBar" role="navigation">
1.1 pooka 25: <span class="doNotDisplay">
26: Navigation:
1.17 jym 27: </span><ul>
28: <li><a href="../../">
29: Home</a></li>
30: <li>
31: <a href="../../">
1.20 wiz 32: News & Media</a><ul>
1.17 jym 33: <li><a href="../../changes/">
34: Recent changes</a></li>
1.31 maya 35: <li><a href="//blog.NetBSD.org/">
1.17 jym 36: NetBSD blog</a></li>
37: <li><a href="../../gallery/events.html">
38: Events</a></li>
39: </ul>
40: </li>
41: <li>
42: <a href="../../about/">
43: About</a><ul>
44: <li><a href="../../about/">
45: NetBSD</a></li>
1.36 maya 46: <li><a href="../../people/developers.html">
47: NetBSD developers</a></li>
1.17 jym 48: <li><a href="../../gallery/">
1.42 ! leot 49: Gallery</a></li>
1.17 jym 50: </ul>
51: </li>
52: <li>
53: <a href="../../docs/">
54: Documentation</a><ul>
55: <li><a href="../../docs/misc/index.html">
56: FAQ & HOWTOs</a></li>
57: <li><a href="../../docs/guide/en/">
58: The Guide</a></li>
1.32 maya 59: <li><a href="http://man.NetBSD.org/">
1.17 jym 60: Manual pages</a></li>
1.31 maya 61: <li><a href="//wiki.NetBSD.org/">
1.17 jym 62: Wiki</a></li>
63: </ul>
64: </li>
65: <li>
66: <a href="../../support/">
67: Support</a><ul>
68: <li><a href="../../support/send-pr.html">
69: Problem report guide</a></li>
70: <li><a href="../../cgi-bin/sendpr.cgi?gndb=netbsd">
71: Report a bug</a></li>
72: <li><a href="../../support/query-pr.html">
73: Query bug database</a></li>
74: <li><a href="../../support/security/">
75: Security</a></li>
76: </ul>
77: </li>
78: <li>
79: <a href="../../community/">
80: Community</a><ul>
81: <li><a href="../../mailinglists/">
82: Mailing lists</a></li>
1.31 maya 83: <li><a href="//mail-index.NetBSD.org/">
1.17 jym 84: List archives</a></li>
85: </ul>
86: </li>
87: <li>
88: <a href="../../developers/">
89: Developers</a><ul>
1.33 maya 90: <li><a href="http://cvsweb.NetBSD.org/">
1.17 jym 91: Browse source</a></li>
1.31 maya 92: <li><a href="//nxr.NetBSD.org/">
1.17 jym 93: Cross-reference</a></li>
1.31 maya 94: <li><a href="//releng.NetBSD.org/">
1.17 jym 95: Release engineering</a></li>
1.31 maya 96: <li><a href="//wiki.NetBSD.org/projects/">
1.17 jym 97: Projects list</a></li>
98: </ul>
99: </li>
100: <li>
101: <a href="../../ports/">
102: Ports</a><ul>
103: <li><a href="../../ports/history.html">
104: History</a></li>
105: <li><a href="../../ports/emulators.html">
106: Emulators</a></li>
107: </ul>
108: </li>
109: <li>
1.31 maya 110: <a href="//www.pkgsrc.org/">
1.17 jym 111: Packages</a><ul>
1.32 maya 112: <li><a href="http://www.pkgsrc.se/">
1.17 jym 113: Browse packages</a></li>
1.31 maya 114: <li><a href="//releng.NetBSD.org/index-pkgsrc.html">
1.17 jym 115: Release engineering</a></li>
116: </ul>
117: </li>
118: </ul>
1.1 pooka 119: </div>
1.39 maya 120: <div id="content"><div id="mainContent" class="fullWidth"><div class="rowOfBoxes">
1.8 pooka 121: <h1>Kernel File Systems as Userspace Servers</h1>
1.13 pooka 122: <div class="sect1">
1.1 pooka 123: <div class="titlepage"></div>
124: </div>
1.8 pooka 125: <h3 class="title"><a name="kernfs-server"></a></h3>
1.1 pooka 126: <ul>
1.8 pooka 127: <li><a href="#about">On Kernel File System Servers</a></li>
128: <li><a href="#use">Mounting and Use</a></li>
129: <li><a href="#internals">Internals</a></li>
1.1 pooka 130: </ul>
131: <hr>
132: <h3 class="title"></h3>
1.15 reed 133: <p>
134: This chapter describes the symbiosis of
135: background knowledge on them, see the respective web pages.
136: </p>
1.1 pooka 137: <h4 class="title">
1.37 maya 138: <a name="about"></a>On Kernel File System Servers</h4>
1.1 pooka 139:
140: <p>
1.8 pooka 141: The integration of the <a class="ulink" href="index.html" target="_top">puffs</a> and
142: <a class="ulink" href="../rump/index.html" target="_top">rump</a> technologies
143: enables mounting kernel file systems as userspace servers.
144: Equivalent functionality to the in-kernel option is maintained,
145: and an application accessing files is unable to tell the
146: difference between the two.
1.1 pooka 147: </p>
148:
149: <p>
1.8 pooka 150: A useful scenario for mounting a kernel file system as a userspace
151: server is accessing untrusted media. As file system code is
152: generally authored assuming a trusted and correct file system
153: image, a corrupt or deliberately modified image can easily cause a
154: kernel crash or security compromise. By using a userspace server,
155: the compromise is limited to the userspace server program, not the
156: whole system.
1.1 pooka 157: </p>
158:
159: <p>
1.8 pooka 160: It also enables the mounting of kernel file systems which are not
161: included as part of the kernel and loading a module is not
162: desired. Additionally, using kernel file systems from different
163: operating system versions is possible, since interfacing with
164: the kernel is done through the puffs protocol, not the
165: kernel binary interface. This is desired for example when
166: wanting to take advantage of new functionality without upgrading
167: the operating system or wanting to do a partial rollback to avoid
168: a regression in a newer version.
1.1 pooka 169: </p>
170:
171: <div class="figure">
1.8 pooka 172: <a name="rump-filesystem"></a><p class="title"><b>Figure 1. File System Access Comparison</b></p>
1.1 pooka 173: <div class="figure-contents">
1.8 pooka 174:
175: <div class="mediaobject"><img src="rump.png" alt="File System Access Comparison"></div>
176: </div>
1.1 pooka 177: </div>
178: <br class="figure-break">
179:
1.8 pooka 180:
181: <h4 class="title">
1.37 maya 182: <a name="use"></a>Mounting and Use</h4>
1.8 pooka 183:
184: <p>
185: The use of kernel file systems as userspace servers requires
186: the support for <a class="ulink" href="index.html" target="_top">puffs</a> in the
187: kernel.
188: </p>
1.1 pooka 189:
1.8 pooka 190: <p>
191: To mount the file system, the relevant <span class="command"><strong>rump_fs</strong></span>
192: command must be run. These commands share the same suffix as the
193: normal in-kernel <span class="command"><strong>mount_fs</strong></span> commands. For
194: instance, the equivalent of <span class="command"><strong>mount_msdos</strong></span> is
195: <span class="command"><strong>rump_msdos</strong></span>. The usage is also equal, so the
196: manual page of the mount equivalent should be consulted. The only
197: exception is that rump file systems do not require the use of
198: <span class="command"><strong>vnconfig</strong></span> to mount regular files. Rather, such
199: images can be mounted directly by using the image as the
200: device file path.
201: </p>
1.1 pooka 202:
203: <p>
1.8 pooka 204: To unmount, <span class="command"><strong>umount</strong></span> should be run as normal.
205: While it is possible to violently kill the server process, this
206: does not give the file system an opportunity to flush its caches
207: and cleanly unmount and may result in data loss. In case the
208: server process is violently killed, puffs automatically performs a
209: forced unmount and no further action is necessary.
1.1 pooka 210: </p>
211:
1.22 tron 212: <div class="sect4">
1.1 pooka 213: <div class="titlepage"><div><div><h5 class="title">
1.8 pooka 214: <a name="examples"></a>Examples</h5></div></div></div>
1.1 pooka 215:
216:
217: <p>
1.8 pooka 218: To mount a file system image as a read-only mount:
1.1 pooka 219:
220: </p>
221: <pre class="programlisting">
1.8 pooka 222: pain-rustique> rump_ffs -o ro ~/img/ffs.img /mnt
1.10 pooka 223: OR
224: pain-rustique> mount -t ffs -o ro,rump ~/img/ffs.img /mnt
1.1 pooka 225: </pre>
226: <p>
227:
1.13 pooka 228: If you want to mount a disk device instead, the procedure
229: is the same. This example also instructs the file system
230: to use journalling. Note: for reasons beyond the scope of
231: this document, it is highly recommended you use the raw
232: device instead of the usual block device.
1.1 pooka 233:
234: </p>
235: <pre class="programlisting">
1.13 pooka 236: pain-rustique> rump_ffs -o log /dev/rwd0e /mnt2
1.1 pooka 237: </pre>
238: <p>
239:
1.8 pooka 240: Mounting nfs works in a similar fashion. The command line flag
241: <code class="code">-p</code> makes sure a non-root mount is succesful if the
242: server allows them:
1.1 pooka 243:
244: </p>
245: <pre class="programlisting">
1.8 pooka 246: pain-rustique> rump_nfs -p host:/export /mnt3
1.1 pooka 247: </pre>
248: <p>
1.10 pooka 249:
250: Finally, the option <code class="option">rump</code> in fstab signals that
251: the file system should be mounted using rump instead of the
252: kernel file service. The following example is for specifying an
253: nfs share mount from a laptop over wireless:
254: </p>
255: <pre class="programlisting">
256: server:/m/server /m/server nfs rw,noauto,-r=8192,-w=8192,rump
257: </pre>
258: <p>
1.1 pooka 259: </p>
260:
261: <p>
1.8 pooka 262: After this the file system will show up on the mountlist and you
263: can access it through the mountpath like any other mounted file
264: system.
1.1 pooka 265: </p>
1.8 pooka 266:
1.1 pooka 267: </div>
268:
269: <h4 class="title">
1.37 maya 270: <a name="internals"></a>Internals</h4>
1.8 pooka 271:
1.1 pooka 272: <p>
1.8 pooka 273: Internally, kernel file systems are implemented against the
274: kernel virtual file system layer. This layer defines a protocol
275: which kernel file systems convert to their backend storage
276: protocol to satisfy the operation. The result is then converted
277: back to a format the virtual file system layer understands and
278: passed back to caller (most likely an application, although it can
279: be for example the NFS server).
1.1 pooka 280: </p>
281:
282: <p>
1.8 pooka 283: Analogously, puffs file systems must interpret and convert the
284: puffs file system interface protocol. While the puffs interface
285: is very similar to the kernel virtual file system interface,
286: there are differences in some parameters. For example, the
287: virtual file system passes information about I/O as a
288: reference to <code class="code">struct uiomove</code>. In contrast, puffs
289: passes this as explicit parameters.
1.1 pooka 290: </p>
291:
292: <p>
1.8 pooka 293: Since a userspace kernel file system server attaches itself
294: as a puffs file system, protocol conversion from puffs to the
295: kernel virtual file system must happen, if the whole protocol
296: stack is to work. This conversion of protocols is done by
297: the p2k, or puffs-to-kernel, component. It is installed
298: as <code class="filename">libp2k</code> and linked with all kernel
299: file system servers.
1.1 pooka 300: </p>
301: </div></div></div>
302: <div class="navfoot"></div>
1.11 mishka 303: <div id="footer"><div id="footerContent"><center>
1.31 maya 304: <span class="footfeed"><a href="//www.NetBSD.org/cgi-bin/feedback.cgi">
1.1 pooka 305: Contact</a> |
1.3 kano 306: </span><span class="footcopy"><a href="../../about/disclaimer.html">
1.1 pooka 307: Disclaimer</a> |
308:
1.41 maya 309: <span class="copyright">Copyright © 1994-2019 The NetBSD Foundation, Inc. </span>ALL RIGHTS RESERVED.<br>NetBSD<sup>®</sup> is a registered trademark of The NetBSD
1.1 pooka 310: Foundation, Inc.</span>
1.11 mishka 311: </center></div></div>
1.1 pooka 312: </div></body>
313: </html>
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to rump.html CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / htdocs / docs / puffs