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