X-Git-Url: http://git.jankratochvil.net/?a=blobdiff_plain;f=README;h=fcdcaeab36c371338707adf80ba6ad57f4a2f6da;hb=75b78d8bda10b9f46d7ecd034831541f43831546;hp=732c1f67c635f23b7bba5d1b759eaec777228e9f;hpb=e4302c2a1ce9bb31973795d12285c21280e61a59;p=captive.git diff --git a/README b/README index 732c1f6..fcdcaea 100644 --- a/README +++ b/README @@ -1,24 +1,242 @@ $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/captivecmdline path/to/some/driver.sys +./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