$Id$
-Operation Captive, codename "captive"
--------------------------------------
+Operation Captive
+-----------------
-Provides opensource interface to W32 filesystems. Some proprietary filesystem
-datastructures can be realiably accessed by this project.
+Existing binary Microsoft Windows file system drivers were exploited
+for accessing drives with possibly proprietary file system data structures.
+Open file system API is provided to access these file system drivers.
+Microsoft Windows system components required by these drivers
+were analyzed and successfuly emulated in the GNU/Linux operating system.
+The implementation allows applications running under the GNU/Linux operating
+system to access NTFS drives. File system driver compatibility with VFAT,
+ISO9660 and EXT2 is also provided.
-Bleeding Edge
+
+Project Home
+------------
+
+http://www.jankratochvil.net/
+
+
+Overview
+--------
+
+Any errors from 'captive-lufs' are written to '/var/log/messages'.
+
+Needed drivers (at least ntoskrnl.exe+ntfs.sys) must be in '/var/lib/captive'.
+
+'captive' package creates 'captive' user and 'captive' group on your system.
+
+
+Drivers Availability
+--------------------
+
+All the source packages involved in this project are GNU General Public License
+2.0 (GPL-2.0) compatible (see the file "AUTHORS" for details). The purpose of
+this project is to run the original Microsoft Windows drivers to get the best
+filesystem compatibility and safety ever reachable. This is the method known
+most by the Wine http://www.winehq.com/ project. Required driver files:
+
+ ntoskrnl.exe - Windows NT kernel; required for ANY use of this project.
+ ntfs.sys - NTFS filesystem driver; required to access NTFS disk drives.
+
+Run captive-install-acquire(1) installer for proper guided steps.
+
+
+Packaged Installations
+----------------------
+
+Required W32 drivers were automatically found if Microsoft Windows XP is
+installed on any NTFS or FAT partitions. FAT partitions must be already
+mounted. You may want to run captive-install-acquire(1) to check the drivers
+state and possibly update them. Installer uses X Windows or console
+automatically.
+
+Any NTFS disk partitions were automatically added to /etc/fstab.
+These partitions are now available for mount by
+ mount /mnt/captive-DISK_LABEL
+
+NTFS disk drives can be also mounted by
+ mkdir /mnt/drive-c
+ mount -t captive-ntfs /dev/hda1 /mnt/drive-c
+
+
+If you do not use the captive-install-acquire(1) installer you may also
+copy the drivers yourself - at least "ntoskrnl.exe" and "ntfs.sys".
+They should be stored in '/var/lib/captive' directory (lowercased filenames).
+These driver must be from Microsoft Windows XP while
+Service Pack 1 Check Build U.S. is their preferred version:
+ http://www.microsoft.com/WindowsXP/pro/downloads/servicepacks/sp1/checkedbuild.asp
+
+
+Command-line client access only:
+
+NTFS disk drives can be also accessed without Linux kernel support by:
+ captive-cmdline \
+ --load-module=/var/lib/captive/ntoskrnl.exe \
+ --filesystem=/var/lib/captive/ntfs.sys \
+ --sandbox-server=/usr/sbin/captive-sandbox-server \
+ --bug-pathname=/tmp/captive-bug-%FT%T.captivebug.xml.gz \
+ --disk --rw /dev/hda1
+ (Backslash end-of-line characters '\' to be omitted for line continuation.)
+
+In the case of 'sandbox' invocation error it can be also run directly but
+read/write (--rw) mode is definitely discouraged in such case:
+ captive-cmdline \
+ --load-module=/var/lib/captive/ntoskrnl.exe \
+ --filesystem=/var/lib/captive/ntfs.sys \
+ --disk --rw /dev/hda1
+ (Backslash end-of-line characters '\' to be omitted for line continuation.)
+
+
+Gnome-VFS aware applications can access NTFS disk drives by:
+ gnomevfs-info file:///dev/hda1#captive-ntfs:/config.sys
+ gnomevfs-copy file:///dev/hda1#captive-ntfs:/config.sys /tmp/
+You can replace 'captive-ntfs' by other supported methods, see:
+ /etc/gnome-vfs-2.0/modules/captive.conf
+
+(Gnome-VFS client is not contained in 'captive-static' package.)
+
+
+
+Source Installations
+--------------------
+
+Case #1 - All packages installed:
+ ./configure --enable-lufs --enable-install-pkg
+Case #2 - Packages without installer:
+ ./configure --enable-lufs
+Case #3 - Command-line client (or Gnome-VFS) access only:
+ ./configure
+'configure' will compile 'Case #1' or 'Case #2' automatically if possible
+when run with no arguments. For generic instructions see the file 'INSTALL'
+otherwise run:
+ ./configure --help
+
+Compile by:
+ make
+
+Now you have './src/client/cmdline/captive-cmdline' available for testing.
+
+Manual addition of user and group 'captive' is required for '--sandbox-server'.
+User 'captive' should have its group 'captive'. Login should be forbidden.
+Commands may vary on your system, please consult groupadd(8) and useradd(8):
+ groupadd captive
+ useradd -g captive -r -s /sbin/nologin captive
+
+Later you may invoke standard:
+ make install
+
+Both these steps will be suggested during 'make install' if appropriate:
+You may need to add '/usr/local/lib' line (without quotes) to your
+'/etc/ld.so.conf' file. You may also need to run as 'root' user:
+ ldconfig
+
+
+Bug Reporting
-------------
+Captive produces its bugreports automatically in '/var/lib/captive' directory
+named by 'bug-yyyy-mm-ddThh:mm:ss.captivebug.xml.gz' template. Microsoft
+Windows subsystem emulation failures should be reproducible from this snapshot
+file. You should attempt to minimize the number of operations from the mount
+operation till the expected crash to minimize the snapshot file size.
+
+ !!! Be aware '.captivebug.xml.gz' will contain data from your disk drive !!!
+
+
+CVS Bleeding Edge
+-----------------
+
cvs -d :pserver:pserver@cvs.jankratochvil.net:/cvs login
- Just hit ENTER (empty password)
-cvs -d :pserver:pserver@cvs.jankratochvil.net:/cvs -z3 checkout -d captive priv/captive
+ Just hit ENTER (empty password)
+cvs -d :pserver:pserver@cvs.jankratochvil.net:/cvs -z3 checkout captive
cd captive
-cvs -d :pserver:pserver@cvs.jankratochvil.net:/cvs -z3 checkout -d reactos -r captive -kk priv/reactos
+cvs -d :pserver:pserver@cvs.jankratochvil.net:/cvs -z3 checkout -r captive -kk reactos
./autogen.pl
make
-./src/client/cmdline/captive-cmdline --load-module=/path/to/ntoskrnl.exe --filesystem=/path/to/cdfs.sys --cdrom --ro /path/to/image.bin
- or
-./src/client/cmdline/captive-cmdline --load-module=/path/to/ntoskrnl.exe --filesystem=/path/to/fastfat.sys --disk --blind /path/to/image.bin
+./src/client/cmdline/captive-cmdline --load-module=/var/lib/captive/ntoskrnl.exe --filesystem=/var/lib/captive/ntfs.sys --disk --blind /dev/hda1
+
+
+Files Overview
+--------------
+
+User:
+src/client/lufs - Linux Userland File System module to access NTFS filesystem.
+src/client/sandbox-server - Security+safety wrapper of emulated W32 environment.
+ Disable during debugging sessions.
+src/client/cmdline - Simple ftp(1)-like client.
+ Fallback if LUFS client not usable; also useful during debugging.
+src/install - 'captive-install' package contents
+src/install/fstab - Search and add/remove 'captive-ntfs' /etc/fstab entries.
+src/install/acquire - Search/download needed MS Windows XP driver files.
+src/install/acquire/w32-mod-id.captivemodid.xml - List of supported W32 drivers.
+
+Developer:
+src/client/gnomevfs - gnomevfs-copy(1) file:///dev/hda1#captive-ntfs:/config.sys
+src/client/bug-replay - Debugging engine for files by --bug-pathname.
+src/libcaptive/ke/exports.captivesym - List of implemented W32 API functions.
+src/libcaptive/cc - Windows NT Cache Manager.
+src/TraceFS - TraceFS W32 Cache Manager debug tracer utilities.
+src/TraceFS/TraceFS-W32 - TraceFS native W32 Cache Manager debug tracer.
+src/libcaptive/sandbox - CORBA/ORBit security+safety sandbox-server separation.
+src/libcaptive/client - Code for interfacing libcaptive to its clients.
+src/libcaptive/halcaptive - W32 hal.dll of captive.
+src/libcaptive/include/captive - Include files for future 3rd party clients.
+src/libcaptive/include/reactos - ReactOS include wrappers for UNIX gcc(1).
+src/libcaptive/reactos - Build skeleton for gcc(1) compilation of ReactOS.
+src/libcaptive/reactos/ntoskrnl - Compatible parts of ReactOS ntoskrnl.exe.
+src/libcaptive/reactos/hal - Compatible parts of ReactOS hal.dll.
+src/libcaptive/rtl/unicode.c - Interface UNIX UCS4/UTF8 vs. W32 UCS2 unicode.
+src/libcaptive/storage - HDD/CD-ROM virtual block device UNIX<->W32 drivers.
+src/libcaptive/se - Void security manager granting everything to everyone.
+src/install/acquire/cabextract - Modified cabextract(1) for 'acquire'.
+src/w32-mod - Supplied W32 driver module files.
+macros - Generic AutoGen framework used by './autogen.pl' CVS bootstrapper.
+captive.spec.in - Red Hat Linux packaging.
+debian - Debian GNU/Linux packaging.
+
+
+Linux-NTFS Project
+------------------
+
+http://linux-ntfs.sourceforge.net/ is the most serious competitive NTFS driver
+implementation. It is fully GPL-2.0 licensed and it needs no proprietary
+drivers requirements. It should be now fully reliable for read/only operations.
+Read/write operations are supported only for rewriting existing data blocks of
+existing files - no file/directory create/delete operations possible.
+
+'captive-install' package of this project uses 'Linux-NTFS' driver to obtain
+the original drivers from Microsoft Windows XP already installed on existing
+NTFS disk partition by 'ntfsprogs' NTFS read/only access. 'ntfsprogs' are no
+longer used afterwards.
+
+Although Linux-NTFS Project contains a lot of valuable reverse-engineering work
+it is completely separated effort from Captive project, no knowledge can be
+shared. Linux-NTFS revere-engineers on-disk data structures while Captive
+reverse-engineers internal Windows NT kernel API.
+
+
+Drivers Availability Details
+----------------------------
+
+Microsoft Windows driver files are copyrighted by Microsoft corporation and
+therefore they were not supplied along with this project. It is expected you
+already have valid Microsoft Windows license if you need NTFS disk drive access
+at all. Currently this project supports only driver files of Microsoft Windows
+XP; other versions (such as NT-4.0, 2000 or 2003 Server) are currently not yet
+supported. You still may safely access your NTFS disk drive of a different
+MS-Windows version although depending on your country you may not have legal
+rights to download the needed Microsoft Windows XP drivers if not owning
+exactly the XP version license.
+
+These drivers have only debugging meaning as such disks are well supported:
+ ext2fsd.sys - GNU/Linux EXT2 filesystem driver; supplied in: src/w32-mod/
+ fastfat.sys - FAT filesystem driver; required for (V)FAT-12/16/32 drives.
+ cdfs.sys - CDFS/ISO-9660 filesystem driver; required for CD-ROM media.
Installation
git://git.jankratochvil.net / captive.git / blobdiff