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