<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>captive - Microsoft Windows NT kernel emulation for NTFS disk access</title>
-<link rev="made" href="mailto:root@localhost" />
</head>
<body style="background-color: white">
<!-- INDEX BEGIN -->
<ul>
-
<li><a href="#name">NAME</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<li><a href="#options">OPTIONS</a></li>
<p>All programs using <strong>captive</strong>(7) library share the common set of configuration
options:</p>
<dl>
-<dt><strong><a name="item_%2d%2dfilesystem%3dpathname"><strong>--filesystem</strong>=<strong>pathname</strong></a></strong><br />
-</dt>
+<dt><strong><a name="item__2d_2dfilesystem_3dpathname"><strong>--filesystem</strong>=<strong>pathname</strong></a></strong></dt>
+
<dd>
-Pathname to <strong>.sys</strong> or <strong>.so</strong> filesystem module file. You will use exactly
+<p>Pathname to <strong>.sys</strong> or <strong>.so</strong> filesystem module file. You will use exactly
once this option. Possible choices are
-<strong>/var/lib/captive/ntfs.sys</strong>
-etc.
+<strong>/usr/local/var/lib/captive/ntfs.sys</strong>
+etc.</p>
</dd>
-<p></p>
-<dt><strong><a name="item_%2d%2dload%2dmodule%3dpathname"><strong>--load-module</strong>=<strong>pathname</strong></a></strong><br />
-</dt>
+<dt><strong><a name="item__2d_2dload_2dmodule_3dpathname"><strong>--load-module</strong>=<strong>pathname</strong></a></strong></dt>
+
<dd>
-Pathname to any W32 module to load w/o initialization. Multiple modules can be
+<p>Pathname to any W32 module to load w/o initialization. Multiple modules can be
loaded although in common case you will use just
-<strong>/var/lib/captive/ntoskrnl.exe</strong>
-here.
+<strong>/usr/local/var/lib/captive/ntoskrnl.exe</strong>
+here.</p>
</dd>
-<p></p>
-<dt><strong><a name="item_%2d%2dro"><strong>--ro</strong></a></strong><br />
-</dt>
+<dt><strong><a name="item__2d_2dmodid_2dpath_3dpathname"><strong>--modid-path</strong>=<strong>pathname</strong></a></strong></dt>
+
<dd>
-Read/write mode: Any write access will be forbidden. You should set this mode
+<p>Pathname to the <strong>.captivemodid.xml</strong> database of existing W32 module
+identifications. The default used one is:
+<strong>/usr/local/etc/w32-mod-id.captivemodid.xml</strong>
+You must have this database update for any W32 binary module you are using.
+If you miss such database you may also try to use <strong>--load-untested</strong> below.</p>
+</dd>
+<dt><strong><a name="item__2d_2dload_2duntested"><strong>--load-untested</strong></a></strong></dt>
+
+<dd>
+<p>Load tthe W32 modules despite they may not match the current <strong>--modid-path</strong>
+identifications database. If you use this option Captive may fail very easily
+as such module was never tested before the release and may need some
+compatibility updates. Still no data should be corrupted even if using this
+<strong>--load-untested</strong> option.</p>
+</dd>
+<dt><strong><a name="item__2d_2dro"><strong>--ro</strong></a></strong></dt>
+
+<dd>
+<p>Read/write mode: Any write access will be forbidden. You should set this mode
for <strong>cdfs.sys</strong> (<em>CD-ROM</em> filesystem). This option is mutually exclusive with
-<strong>--blind</strong> and <strong>--rw</strong>.
+<strong>--blind</strong> and <strong>--rw</strong>.</p>
</dd>
-<p></p>
-<dt><strong><a name="item_%2d%2dblind"><strong>--blind</strong></a></strong><br />
-</dt>
+<dt><strong><a name="item__2d_2dblind"><strong>--blind</strong></a></strong></dt>
+
<dd>
-Read/write mode: All writes are just simulated in memory (default). Microsoft
+<p>Read/write mode: All writes are just simulated in memory (default). Microsoft
Windows filesystem driver will see no difference between <strong>--blind</strong> and <strong>--rw</strong>
although the UNIX image file/device will be open read/only as for <strong>--ro</strong>.
All the changes get 'written' as long as <strong>captive</strong>(7) program runs - all the
changes will be lost afterwards. This mode is the most suitable for debugging.
-This option is mutually exclusive with <strong>--ro</strong> and <strong>--rw</strong>.
+This option is mutually exclusive with <strong>--ro</strong> and <strong>--rw</strong>.</p>
</dd>
-<p></p>
-<dt><strong><a name="item_%2d%2drw"><strong>--rw</strong></a></strong><br />
-</dt>
+<dt><strong><a name="item__2d_2drw"><strong>--rw</strong></a></strong></dt>
+
<dd>
-Read/write mode: Write directly to the image file/device. Standard read/write
+<p>Read/write mode: Write directly to the image file/device. Standard read/write
disk mode. You should use <strong>--sandbox-server</strong> option in this case to have the
disk protected against Microsoft Windows filesystem driver crashes. Modified
disk image blocks are in <strong>--sandbox-server</strong> <strong>--rw</strong> mode buffered in the
memory and they get reflected to the disk only after successful completion
of all filesystem operations including filesystem unmount.
-This option is mutually exclusive with <strong>--ro</strong> and <strong>--blind</strong>.
+This option is mutually exclusive with <strong>--ro</strong> and <strong>--blind</strong>.</p>
</dd>
-<p></p>
-<dt><strong><a name="item_%2d%2dcdrom"><strong>--cdrom</strong></a></strong><br />
-</dt>
+<dt><strong><a name="item__2d_2dcdrom"><strong>--cdrom</strong></a></strong></dt>
+
<dd>
-Media type: CD-ROM. You must set this media type for <strong>cdfs.sys</strong>.
+<p>Media type: CD-ROM. You must set this media type for <strong>cdfs.sys</strong>.
Virtual Microsoft Windows block device driver used by Captive maps to
-<strong>\Device\CdRom0</strong>. This option is mutually exclusive with <strong>--disk</strong>.
+<strong>\Device\CdRom0</strong>. This option is mutually exclusive with <strong>--disk</strong>.</p>
</dd>
-<p></p>
-<dt><strong><a name="item_%2d%2ddisk"><strong>--disk</strong></a></strong><br />
-</dt>
+<dt><strong><a name="item__2d_2ddisk"><strong>--disk</strong></a></strong></dt>
+
<dd>
-Media type: Disk (default). You must set this media type for all the Microsoft
+<p>Media type: Disk (default). You must set this media type for all the Microsoft
Windows filesystem drivers except <strong>cdfs.sys</strong>. Virtual Microsoft Windows block
device driver used by Captive maps to <strong>\Device\CaptiveHarddisk0</strong>.
-This option is mutually exclusive with <strong>--cdrom</strong>.
+This option is mutually exclusive with <strong>--cdrom</strong>.</p>
</dd>
-<p></p>
-<dt><strong><a name="item_%2d%2ddebug%2dmessages"><strong>--debug-messages</strong></a></strong><br />
-</dt>
+<dt><strong><a name="item__2d_2ddebug_2dmessages"><strong>--debug-messages</strong></a></strong></dt>
+
<dd>
-Turn on debugging messages. Be prepared for substation debug output.
-Use of <strong>--syslog</strong> feature is not recommended in this case.
+<p>Turn on debugging messages. Be prepared for substation debug output.
+Use of <strong>--syslog</strong> feature is not recommended in this case.</p>
</dd>
-<p></p>
-<dt><strong><a name="item_%2d%2dsandbox%2dserver%3dpathname"><strong>--sandbox-server</strong>=<strong>pathname</strong></a></strong><br />
-</dt>
+<dt><strong><a name="item__2d_2dsandbox_2dserver_3dpathname"><strong>--sandbox-server</strong>=<strong>pathname</strong></a></strong></dt>
+
<dd>
-Pathname to
-<strong>/usr/sbin/captive-sandbox-server</strong>
+<p>Pathname to
+<strong>/usr/local/sbin/captive-sandbox-server</strong>
program, turns on sandboxing.
You should always use this option in conjunction with <strong>--rw</strong>, see it for
details. Although this program is <em>setuid root</em> and it drops it privileges
-to <strong>@CAPTIVE_SANDBOX_SETUID@</strong> user. Your system gets protected by
+to <strong>captive</strong> user. Your system gets protected by
<strong>chroot</strong>(2), <strong>setuid</strong>(2), <strong>setgid</strong>(2) and <strong>setrlimit</strong>(2) UNIX security
features against malicious Microsoft Windows drivers. You should never use this
-option during debugging.
+option during debugging.</p>
</dd>
<dd>
<p>This option is turned on automatically during the mount operation by
<strong>mount.captive-ntfs</strong>(8).
Option needs to be used by hand for the <strong>captive-cmdline</strong>(2) client.</p>
</dd>
-<p></p>
-<dt><strong><a name="item_%2d%2dsandbox%2dserver%2dior%3dior"><strong>--sandbox-server-ior</strong>=<strong>IOR</strong></a></strong><br />
-</dt>
+<dt><strong><a name="item__2d_2dsandbox_2dserver_2dior_3dior"><strong>--sandbox-server-ior</strong>=<strong>IOR</strong></a></strong></dt>
+
<dd>
-Specify <em>CORBA IOR</em> of
-<strong>/usr/sbin/captive-sandbox-server</strong>
+<p>Specify <em>CORBA IOR</em> of
+<strong>/usr/local/sbin/captive-sandbox-server</strong>
program, turns on
sandboxing. Specified <em>CORBA IOR</em> should be the string starting by ``<strong>IOR:</strong>''
text. This option is useful only for debugging. No sandbox restarting is
-possible in this case.
+possible in this case.</p>
</dd>
-<p></p>
-<dt><strong><a name="item_%2d%2dno%2dsandbox"><strong>--no-sandbox</strong></a></strong><br />
-</dt>
+<dt><strong><a name="item__2d_2dno_2dsandbox"><strong>--no-sandbox</strong></a></strong></dt>
+
<dd>
-Turn off sandboxing feature (default). No
-<strong>/usr/sbin/captive-sandbox-server</strong>
+<p>Turn off sandboxing feature (default). No
+<strong>/usr/local/sbin/captive-sandbox-server</strong>
is run. Microsoft Windows filesystem driver is run in native UNIX environment
without any <em>CORBA</em> separation. This option is recommended only for debugging.
-It is dangerous to use <strong>--rw</strong> together, see its description for the details.
+It is dangerous to use <strong>--rw</strong> together, see its description for the details.</p>
</dd>
-<p></p>
-<dt><strong><a name="item_%2d%2dbug%2dpathname%3dpathname"><strong>--bug-pathname</strong>=<strong>pathname</strong></a></strong><br />
-</dt>
+<dt><strong><a name="item__2d_2dbug_2dpathname_3dpathname"><strong>--bug-pathname</strong>=<strong>pathname</strong></a></strong></dt>
+
<dd>
-Pathname to <strong>strftime</strong>(3) for <strong>.captivebug.xml.gz</strong> bugreports. Every crash of
+<p>Pathname to <strong>strftime</strong>(3) for <strong>.captivebug.xml.gz</strong> bugreports. Every crash of
sandbox child gets bugreported to the specified file. You should attempt to
minimize the number of operations from the mount operation till the expected
crash to minimize the snapshot file size. <strong>--sandbox-server</strong> option is
-required for <strong>--bug-pathname</strong>.
+required for <strong>--bug-pathname</strong>.</p>
</dd>
<dd>
<p><strong>!!! Be aware '.captivebug.xml.gz' will contain data from your disk drive !!!</strong></p>
</dd>
-<p></p>
-<dt><strong><a name="item_%2d%2dsyslog"><strong>--syslog</strong></a></strong><br />
-</dt>
+<dt><strong><a name="item__2d_2dsyslog"><strong>--syslog</strong></a></strong></dt>
+
<dd>
-Messages sent to <strong>syslog</strong>(3) instead of <em>stderr</em>. This option gets handy
+<p>Messages sent to <strong>syslog</strong>(3) instead of <em>stderr</em>. This option gets handy
for <strong>mount</strong>(8) operation as the messages would be lost otherway.
Watch our for possible ``<strong>Filesystem crash broke dirty object</strong>'' messages where
some written filesystem data got lost in the case of Microsoft Windows
-filesystem driver crash.
+filesystem driver crash.</p>
</dd>
-<p></p>
-<dt><strong><a name="item_%2d%2dsyslog%2dfacility%3dfacility"><strong>--syslog-facility</strong>=<strong>facility</strong></a></strong><br />
-</dt>
+<dt><strong><a name="item__2d_2dsyslog_2dfacility_3dfacility"><strong>--syslog-facility</strong>=<strong>facility</strong></a></strong></dt>
+
<dd>
-<strong>openlog</strong>(3) facility for <strong>--syslog</strong>. See <strong>facility</strong> section of
+<p><strong>openlog</strong>(3) facility for <strong>--syslog</strong>. See <strong>facility</strong> section of
<strong>openlog</strong>(3) man page for details. Lowercased values such as <strong>daemon</strong> or
-<strong>user</strong> are supported.
+<strong>user</strong> are supported.</p>
</dd>
-<p></p></dl>
+</dl>
<p>
</p>
<hr />