README

   1 $Id$
   2
   3
   4 Operation Captive
   5 -----------------
   6
   7 Existing binary Microsoft Windows file system drivers were exploited
   8 for accessing drives with possibly proprietary file system data structures.
   9 Open file system API is provided to access these file system drivers.
  10 Microsoft Windows system components required by these drivers
  11 were analyzed and successfuly emulated in the GNU/Linux operating system.
  12
  13 The implementation allows applications running under the GNU/Linux operating
  14 system to access NTFS drives. File system driver compatibility with VFAT,
  15 ISO9660 and EXT2 is also provided.
  16
  17
  18 Project Home
  19 ------------
  20
  21 http://www.jankratochvil.net/
  22
  23
  24 Overview
  25 --------
  26
  27 'captive' is the base package. It contains debugging 'captive-cmdline' client.
  28 'captive-lufs' permits mounting NTFS as regular filesystem. It needs 'lufs'.
  29 'lufs' is a daemon to enable userland process to provide filesystem functions.
  30
  31 Any errors from 'captive-lufs' are written to '/var/log/messages'.
  32
  33 Needed drivers (at least ntoskrnl.exe+ntfs.sys) must be in '/var/lib/captive'.
  34
  35 'captive' package creates 'captive' user and 'captive' group on your system.
  36
  37
  38 Drivers Availability
  39 --------------------
  40
  41 All the source packages involved in this project are GNU General Public License
  42 2.0 (GPL-2.0) compatible (see the file "AUTHORS" for details). The purpose of
  43 this project is to run the original Microsoft Windows drivers to get the best
  44 filesystem compatibility and safety ever reachable. This is the method known
  45 most by the Wine http://www.winehq.com/ project. Required driver files:
  46
  47   ntoskrnl.exe - Windows NT kernel; required for ANY use of this project.
  48   ntfs.sys - NTFS filesystem driver; required to access NTFS disk drives.
  49
  50 Run captive-install-acquire(1) installer for proper guided steps.
  51
  52
  53 Packaged Installations
  54 ----------------------
  55
  56 Case #1 - All packages installed:
  57     captive-install - Acquire needed MS-Windows drivers and setup /etc/fstab.
  58     captive-lufs - Linux Userland File System module to be native filesystem.
  59     captive - Base package of this project.
  60     lufs >=0.9.6-1captive - Linux Userland File System engine for captive-lufs.
  61     gnome-vfs-httpcaptive - Gnome-VFS httpcaptive:// method for captive-install.
  62     ntfsprogs >=200309071734 - Readonly NTFS to get drivers by captive-install.
  63     ntfsprogs-gnomevfs - Gnome-VFS readonly NTFS access used by captive-install.
  64
  65   Required W32 drivers were automatically found if Microsoft Windows XP is
  66   installed on any (mounted or unmounted) NTFS or (mounted) FAT partition.
  67   You may want to run captive-install-acquire(1) to check the drivers state
  68   and possibly update them. Installer uses X Windows or console automatically.
  69
  70   Any NTFS disk partitions were automatically added to /etc/fstab.
  71   These partitions are now available for mount by
  72     mount /mnt/captive-DISK_LABEL
  73   such as (if the label is empty)
  74     mount /mnt/captive-
  75
  76 Case #2 - Packages without installer:
  77     captive-lufs - Linux Userland File System module to be native filesystem.
  78     captive - Base package of this project.
  79     lufs >=0.9.6-1captive - Linux Userland File System engine for captive-lufs.
  80
  81   You must obtain W32 drivers - at least "ntoskrnl.exe" and "ntfs.sys".
  82   They should be stored in '/var/lib/captive' directory (lowercased filenames).
  83   These driver must be from Microsoft Windows XP;
  84   Service Pack 1 Check Build U.S. preferred:
  85     http://www.microsoft.com/WindowsXP/pro/downloads/servicepacks/sp1/checkedbuild.asp
  86
  87   NTFS disk drives can be mounted by
  88     mkdir /mnt/drive-c
  89     mount -t captive-ntfs /dev/hda1 /mnt/drive-c
  90
  91 Case #3 - Command-line client (or Gnome-VFS) access only:
  92     captive - Base package of this project.
  93
  94   You must obtain W32 drivers - at least "ntoskrnl.exe" and "ntfs.sys".
  95   They should be stored in '/var/lib/captive' directory (lowercased filenames).
  96   These driver must be from Microsoft Windows XP;
  97   Service Pack 1 Check Build U.S. preferred.
  98     http://www.microsoft.com/WindowsXP/pro/downloads/servicepacks/sp1/checkedbuild.asp
  99
 100   NTFS disk drives can be accessed by:
 101     captive-cmdline --load-module=/tmp/ntoskrnl.exe --filesystem=/tmp/ntfs.sys \
 102             --sandbox-server=/usr/sbin/captive-sandbox-server \
 103             --bug-pathname=/tmp/captive-bug-%FT%T.captivebug.xml.gz \
 104             --disk --rw /dev/hda1
 105     (Backslash end-of-line characters '\' to be omitted for line continuation.)
 106
 107   In the case of 'sandbox' invocation error you can also run directly but
 108   read/write (--rw) mode is definitely discouraged in such case:
 109     captive-cmdline --load-module=/tmp/ntoskrnl.exe --filesystem=/tmp/ntfs.sys \
 110             --disk --rw /dev/hda1
 111     (Backslash end-of-line characters '\' to be omitted for line continuation.)
 112
 113   Gnome-VFS aware applications can access NTFS disk drives by:
 114     gnomevfs-info file:///dev/hda1#captive-ntfs:/config.sys
 115     gnomevfs-copy file:///dev/hda1#captive-ntfs:/config.sys /tmp/
 116   You can replace 'captive-ntfs' by other supported methods, see:
 117     /etc/gnome-vfs-2.0/modules/captive.conf
 118
 119
 120 Source Installations
 121 --------------------
 122
 123 Case #1 - All packages installed:
 124   ./configure --enable-lufs --enable-install-pkg
 125 Case #2 - Packages without installer:
 126   ./configure --enable-lufs
 127 Case #3 - Command-line client (or Gnome-VFS) access only:
 128   ./configure
 129 'configure' will compile 'Case #1' or 'Case #2' automatically if possible
 130 when run with no arguments. For generic instructions see the file 'INSTALL'
 131 otherwise run:
 132   ./configure --help
 133
 134 Compile by:
 135   make
 136
 137 Now you have './src/client/cmdline/captive-cmdline' available for testing.
 138 Later you may invoke standard:
 139   make install
 140
 141 Manual addition of user and group 'captive' is required for '--sandbox-server':
 142   useradd captive
 143
 144 Both these steps will be suggested during 'make install' if appropriate:
 145 You may need to add '/usr/local/lib' line (without quotes) to your
 146 '/etc/ld.so.conf' file. You may also need to run as 'root' user:
 147   ldconfig
 148
 149
 150 Bug Reporting
 151 -------------
 152
 153 Captive produces its bugreports automatically in '/var/lib/captive' directory
 154 named by 'bug-yyyy-mm-ddThh:mm:ss.captivebug.xml.gz' template. Microsoft
 155 Windows subsystem emulation failures should be reproducible from this snapshot
 156 file. You should attempt to minimize the number of operations from the mount
 157 operation till the expected crash to minimize the snapshot file size.
 158
 159   !!! Be aware '.captivebug.xml.gz' will contain data from your disk drive !!!
 160
 161
 162 CVS Bleeding Edge
 163 -----------------
 164
 165 cvs -d :pserver:pserver@cvs.jankratochvil.net:/cvs login
 166     Just hit ENTER (empty password)
 167 cvs -d :pserver:pserver@cvs.jankratochvil.net:/cvs -z3 checkout captive
 168 cd captive
 169 cvs -d :pserver:pserver@cvs.jankratochvil.net:/cvs -z3 checkout -r captive -kk reactos
 170 ./autogen.pl
 171 make
 172 ./src/client/cmdline/captive-cmdline --load-module=/var/lib/captive/ntoskrnl.exe --filesystem=/var/lib/captive/ntfs.sys --disk  --blind /dev/hda1
 173
 174
 175 Files Overview
 176 --------------
 177
 178 User:
 179 src/client/lufs - Linux Userland File System module to access NTFS filesystem.
 180 src/client/sandbox-server - Security+safety wrapper of emulated W32 environment.
 181     Disable during debugging sessions.
 182 src/client/cmdline - Simple ftp(1)-like client.
 183     Fallback if LUFS client not usable; also useful during debugging.
 184 src/install - 'captive-install' package contents
 185 src/install/fstab - Search and add/remove 'captive-ntfs' /etc/fstab entries.
 186 src/install/acquire - Search/download needed MS Windows XP driver files.
 187 src/install/acquire/w32-mod-id.captivemodid.xml - List of supported W32 drivers.
 188
 189 Developer:
 190 src/client/gnomevfs - gnomevfs-copy(1) file:///dev/hda1#captive-ntfs:/config.sys
 191 src/client/bug-replay - Debugging engine for files by --bug-pathname.
 192 src/libcaptive/ke/exports.captivesym - List of implemented W32 API functions.
 193 src/libcaptive/cc - Windows NT Cache Manager.
 194 src/TraceFS - TraceFS W32 Cache Manager debug tracer utilities.
 195 src/TraceFS/TraceFS-W32 - TraceFS native W32 Cache Manager debug tracer.
 196 src/libcaptive/sandbox - CORBA/ORBit security+safety sandbox-server separation.
 197 src/libcaptive/client - Code for interfacing libcaptive to its clients.
 198 src/libcaptive/halcaptive - W32 hal.dll of captive.
 199 src/libcaptive/include/captive - Include files for future 3rd party clients.
 200 src/libcaptive/include/reactos - ReactOS include wrappers for UNIX gcc(1).
 201 src/libcaptive/reactos - Build skeleton for gcc(1) compilation of ReactOS.
 202 src/libcaptive/reactos/ntoskrnl - Compatible parts of ReactOS ntoskrnl.exe.
 203 src/libcaptive/reactos/hal - Compatible parts of ReactOS hal.dll.
 204 src/libcaptive/rtl/unicode.c - Interface UNIX UCS4/UTF8 vs. W32 UCS2 unicode.
 205 src/libcaptive/storage - HDD/CD-ROM virtual block device UNIX<->W32 drivers.
 206 src/libcaptive/se - Void security manager granting everything to everyone.
 207 src/install/acquire/cabextract - Modified cabextract(1) for 'acquire'.
 208 src/w32-mod - Supplied W32 driver module files.
 209 macros - Generic AutoGen framework used by './autogen.pl' CVS bootstrapper.
 210 captive.spec.in - Red Hat Linux packaging.
 211 debian - Debian GNU/Linux packaging.
 212
 213
 214 Linux-NTFS Project
 215 ------------------
 216
 217 http://linux-ntfs.sourceforge.net/ is the most serious competitive NTFS driver
 218 implementation. It is fully GPL-2.0 licensed and it needs no proprietary
 219 drivers requirements. It should be now fully reliable for read/only operations.
 220 Read/write operations are supported only for rewriting existing data blocks of
 221 existing files - no file/directory create/delete operations possible.
 222
 223 'captive-install' package of this project 'ntfsprogs' package of Linux-NTFS
 224 Project. This driver is very useful to obtain the original drivers from
 225 Microsoft Windows XP already installed on existing NTFS disk partition by
 226 'ntfsprogs' NTFS read/only access. 'ntfsprogs' are no longer used afterwards.
 227
 228 Although Linux-NTFS Project contains a lot of valuable reverse-engineering work
 229 it is completely separated effort from Captive project, no knowledge can be
 230 shared. Linux-NTFS revere-engineers on-disk data structures while Captive
 231 reverse-engineers internal Windows NT kernel API.
 232
 233
 234 Drivers Availability Details
 235 ----------------------------
 236
 237 Microsoft Windows driver files are copyrighted by Microsoft corporation and
 238 therefore they were not supplied along with this project. It is expected you
 239 already have valid Microsoft Windows license if you need NTFS disk drive access
 240 at all. Currently this project supports only driver files of Microsoft Windows
 241 XP; other versions (such as NT-4.0, 2000 or 2003 Server) are currently not yet
 242 supported. You still may safely access your NTFS disk drive of a different
 243 MS-Windows version although depending on your country you may not have legal
 244 rights to download the needed Microsoft Windows XP drivers if not owning
 245 exactly the XP version license.
 246
 247 These drivers have only debugging meaning as such disks are well supported:
 248   ext2fsd.sys - GNU/Linux EXT2 filesystem driver; supplied in: src/w32-mod/
 249   fastfat.sys - FAT filesystem driver; required for (V)FAT-12/16/32 drives.
 250   cdfs.sys - CDFS/ISO-9660 filesystem driver; required for CD-ROM media.
 251
 252
 253 Installation
 254 ------------
 255
 256 See the file 'INSTALL'.
 257
 258
 259 Copyright
 260 ---------
 261
 262 See the file 'COPYING' and 'AUTHORS'.