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
 124 Manual addition of user and group 'captive' is required for '--sandbox-server'.
 125 User 'captive' should have its group 'captive'. Login should be forbidden.
 126 Commands may vary on your system, please consult groupadd(8) and useradd(8):
 127   groupadd captive
 128   useradd -g captive -r -s /sbin/nologin captive
 129
 130 Later you may invoke standard:
 131   make install
 132
 133 Both these steps will be suggested during 'make install' if appropriate:
 134 You may need to add '/usr/local/lib' line (without quotes) to your
 135 '/etc/ld.so.conf' file. You may also need to run as 'root' user:
 136   ldconfig
 137
 138
 139 Bug Reporting
 140 -------------
 141
 142 Captive produces its bugreports automatically in '/var/lib/captive' directory
 143 named by 'bug-yyyy-mm-ddThh:mm:ss.captivebug.xml.gz' template. Microsoft
 144 Windows subsystem emulation failures should be reproducible from this snapshot
 145 file. You should attempt to minimize the number of operations from the mount
 146 operation till the expected crash to minimize the snapshot file size.
 147
 148   !!! Be aware '.captivebug.xml.gz' will contain data from your disk drive !!!
 149
 150
 151 CVS Bleeding Edge
 152 -----------------
 153
 154 cvs -d :pserver:pserver@cvs.jankratochvil.net:/cvs login
 155     Just hit ENTER (empty password)
 156 cvs -d :pserver:pserver@cvs.jankratochvil.net:/cvs -z3 checkout captive
 157 cd captive
 158 cvs -d :pserver:pserver@cvs.jankratochvil.net:/cvs -z3 checkout -r captive -kk reactos
 159 ./autogen.pl
 160 make
 161 ./src/client/cmdline/captive-cmdline --load-module=/var/lib/captive/ntoskrnl.exe --filesystem=/var/lib/captive/ntfs.sys --disk  --blind /dev/hda1
 162
 163
 164 Files Overview
 165 --------------
 166
 167 User:
 168 src/client/lufs - Linux Userland File System module to access NTFS filesystem.
 169 src/client/sandbox-server - Security+safety wrapper of emulated W32 environment.
 170     Disable during debugging sessions.
 171 src/client/cmdline - Simple ftp(1)-like client.
 172     Fallback if LUFS client not usable; also useful during debugging.
 173 src/install - 'captive-install' package contents
 174 src/install/fstab - Search and add/remove 'captive-ntfs' /etc/fstab entries.
 175 src/install/acquire - Search/download needed MS Windows XP driver files.
 176 src/install/acquire/w32-mod-id.captivemodid.xml - List of supported W32 drivers.
 177
 178 Developer:
 179 src/client/gnomevfs - gnomevfs-copy(1) file:///dev/hda1#captive-ntfs:/config.sys
 180 src/client/bug-replay - Debugging engine for files by --bug-pathname.
 181 src/libcaptive/ke/exports.captivesym - List of implemented W32 API functions.
 182 src/libcaptive/cc - Windows NT Cache Manager.
 183 src/TraceFS - TraceFS W32 Cache Manager debug tracer utilities.
 184 src/TraceFS/TraceFS-W32 - TraceFS native W32 Cache Manager debug tracer.
 185 src/libcaptive/sandbox - CORBA/ORBit security+safety sandbox-server separation.
 186 src/libcaptive/client - Code for interfacing libcaptive to its clients.
 187 src/libcaptive/halcaptive - W32 hal.dll of captive.
 188 src/libcaptive/include/captive - Include files for future 3rd party clients.
 189 src/libcaptive/include/reactos - ReactOS include wrappers for UNIX gcc(1).
 190 src/libcaptive/reactos - Build skeleton for gcc(1) compilation of ReactOS.
 191 src/libcaptive/reactos/ntoskrnl - Compatible parts of ReactOS ntoskrnl.exe.
 192 src/libcaptive/reactos/hal - Compatible parts of ReactOS hal.dll.
 193 src/libcaptive/rtl/unicode.c - Interface UNIX UCS4/UTF8 vs. W32 UCS2 unicode.
 194 src/libcaptive/storage - HDD/CD-ROM virtual block device UNIX<->W32 drivers.
 195 src/libcaptive/se - Void security manager granting everything to everyone.
 196 src/install/acquire/cabextract - Modified cabextract(1) for 'acquire'.
 197 src/w32-mod - Supplied W32 driver module files.
 198 macros - Generic AutoGen framework used by './autogen.pl' CVS bootstrapper.
 199 captive.spec.in - Red Hat Linux packaging.
 200 debian - Debian GNU/Linux packaging.
 201
 202
 203 Linux-NTFS Project
 204 ------------------
 205
 206 http://linux-ntfs.sourceforge.net/ is the most serious competitive NTFS driver
 207 implementation. It is fully GPL-2.0 licensed and it needs no proprietary
 208 drivers requirements. It should be now fully reliable for read/only operations.
 209 Read/write operations are supported only for rewriting existing data blocks of
 210 existing files - no file/directory create/delete operations possible.
 211
 212 'captive-install' package of this project uses 'Linux-NTFS' driver to obtain
 213 the original drivers from Microsoft Windows XP already installed on existing
 214 NTFS disk partition by 'ntfsprogs' NTFS read/only access. 'ntfsprogs' are no
 215 longer used afterwards.
 216
 217 Although Linux-NTFS Project contains a lot of valuable reverse-engineering work
 218 it is completely separated effort from Captive project, no knowledge can be
 219 shared. Linux-NTFS revere-engineers on-disk data structures while Captive
 220 reverse-engineers internal Windows NT kernel API.
 221
 222
 223 Drivers Availability Details
 224 ----------------------------
 225
 226 Microsoft Windows driver files are copyrighted by Microsoft corporation and
 227 therefore they were not supplied along with this project. It is expected you
 228 already have valid Microsoft Windows license if you need NTFS disk drive access
 229 at all. Currently this project supports only driver files of Microsoft Windows
 230 XP; other versions (such as NT-4.0, 2000 or 2003 Server) are currently not yet
 231 supported. You still may safely access your NTFS disk drive of a different
 232 MS-Windows version although depending on your country you may not have legal
 233 rights to download the needed Microsoft Windows XP drivers if not owning
 234 exactly the XP version license.
 235
 236 These drivers have only debugging meaning as such disks are well supported:
 237   ext2fsd.sys - GNU/Linux EXT2 filesystem driver; supplied in: src/w32-mod/
 238   fastfat.sys - FAT filesystem driver; required for (V)FAT-12/16/32 drives.
 239   cdfs.sys - CDFS/ISO-9660 filesystem driver; required for CD-ROM media.
 240
 241
 242 Installation
 243 ------------
 244
 245 See the file 'INSTALL'.
 246
 247
 248 Copyright
 249 ---------
 250
 251 See the file 'COPYING' and 'AUTHORS'.