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