XMOUNT README FILE                                                        v1.0.x

Table of contents
  0.0 Author and license stuff
  0.1 Used external libraries
  1.0 What is xmount? - A short description
  2.0 Input image support
    2.1 libxmount_input_raw
    2.2 libxmount_input_ewf
    2.3 libxmount_input_aewf
    2.4 libxmount_input_aff
    2.5 libxmount_input_aff4
    2.6 libxmount_input_aaff
    2.7 libxmount_input_qcow
    2.8 libxmount_input_vdi
  3.0 Morphing support
    3.1 libxmount_morphing_combine
    3.2 libxmount_morphing_raid
    3.3 libxmount_morphing_unallocated
  4.0 Output image
    4.1 Emulated RAW file
    4.2 Emulated DMG file
    4.3 Emulated VDI file
    4.4 Emulated VMDK file
    4.5 Emulated VHD file
  5.0 Virtual write access
  6.0 Installation instructions
    6.1 Install from a prebuild package
    6.2 Install from source
      6.2.1 General prerequisits
      6.2.2 Shared vs static builds
      6.2.3 Installing prerequisits on Debian based systems
      6.2.4 Installing prerequisits on OSx
      6.2.5 Compilation / Installation
  7.0 xmount usage examples

0.0 Author and license stuff
  xmount Copyright (c) 2024 by SITS Sarl

  Author(s):
    Gillen Daniel <development@sits.lu>

  This program is free software: you can redistribute it and/or modify it under
  the terms of the GNU General Public License as published by the Free Software
  Foundation, either version 3 of the License, or (at your option) any later
  version.

  This program is distributed in the hope that it will be useful, but WITHOUT
  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

  You should have received a copy of the GNU General Public License along with
  this program. If not, see <http://www.gnu.org/licenses/>.

0.1 Used external libraries
  xmount's input libraries rely on various other external open source libraries:

  --- libewf

  Copyright (C) 2006-2024, Joachim Metz <joachim.metz@gmail.com>

  --- afflib v3

  Copyright (C) 2005-2006 Basis Technology, Inc.
  Copyright (C) 2005-2013 Simson L. Garfinkel <simsong@acm.org>
  Copyright (C) 2014-2022 Phillip Hellewell <sshock@gmail.com>

  This product includes software developed by Simson L. Garfinkel and Basis
  Technology Corp.

  --- aff4-cpp-lite

  Copyright Schatz Forensic Pty Ltd, 2017-2018

  --- snappy

  Copyright 2005 Google Inc. <opensource@google.com>

  --- raptor2

  Copyright (C) 2000-2023 Dave Beckett
  Copyright (C) 2000-2005 University of Bristol. All Rights Reserved.

  --- liblz4

  Copyright (C) 2011-2023, Yann Collet.

  --- zlib

  Copyright (C) 1995-2024 Jean-loup Gailly and Mark Adler

  --- libxml2

  Copyright (C) 1998-2012 Daniel Veillard. All Rights Reserved.

1.0 What is xmount? - A short description
  xmount allows you to convert on-the-fly between multiple input and output
  harddisk image formats. xmount creates a virtual file system using FUSE
  (Filesystem in Userspace) that contains a virtual representation of the input
  image.

  The virtual representation can be in raw DD, Apple's Disk Image format (DMG),
  VirtualBox's virtual disk file format (VDI), Microsoft's Virtual Hard Disk
  Image format (VHD) or in VmWare's VMDK file format.

  Input images can be raw DD, EWF (Expert Witness Compression Format), AFF
  (Advanced Forensic Format), VDI (VirtualBox Virtual Disk Image) or QCOW
  (QEMU Copy On Write) files.

  In addition, xmount also supports virtual write access to the output files
  that is redirected to a cache file. This makes it for example possible to boot
  acquired harddisk images using QEMU, KVM, VirtualBox, VmWare or alike.

2.0 Input image support
  Starting with version 0.7.0, input image support has been moved into external
  libraries. The following chapters list the officially supported ones. They
  might not all be available on your system though.

  2.1 libxmount_input_raw
    Supports raw DD images ("--in raw" or "--in dd").

  2.2 libxmount_input_ewf
    Supports EWF (Expert Witness Compression Format) images ("--in ewf") using
    Joachim Metz's libewf (https://code.google.com/p/libewf/).

  2.3 libxmount_input_aewf
    Supports EWF (Expert Witness Compression Format) images ("--in aewf")
    generated with Guymager (http://guymager.sourceforge.net/). This library
    uses an EWF implementation written by Guy Voncken. It consumes much less
    memory than libewf when mounting big (>1TB) images.

  2.4 libxmount_input_aff
    Supports AFFv3 (Advanced Forensic Format v3) images ("--in aff") using
    Simson Garfinkel's afflib (https://github.com/simsong/AFFLIBv3).

  2.5 libxmount_input_aff4
    Supports AFFv4 (Advanced Forensic Format v4) images ("--in aff4") using
    Schatz Forensic's aff4-cpp library (https://github.com/aff4/aff4-cpp-lite)

  2.6 libxmount_input_aaff
    Supports AFF (Advanced Forensic Format) images ("--in aaff") using an AFF
    implementation written by Guy Voncken. In essence, it is a lot faster than
    afflib.

  2.7 libxmount_input_qcow
    Supports QCOW (QEMU Copy On Write) files ("--in qcow") using an
    implementation written by Guy Voncken.

  2.8 libxmount_input_vdi
    Supports VDI (VirtualBox's Virtual Disk Image) files ("--in vdi") using
    an implementation written by Guy Voncken.

3.0 Morphing support
  Also starting with xmount version 0.7.0, a new concept of input image morphing
  has been added. Morphing is a process which is applied to the data of all
  specified input images and produces a single virtual image which can then be
  converted into an output image. The following chapters list the currently
  officially supported morphing libraries. As with the input image libs, not all
  might be available on your system.

  3.1 libxmount_morphing_combine
    Using "--morph combine", data from all input images is concatenated into
    a single image. Images are appended in the same order they are specified on
    the command line. This morphing type is also the default if no "--morph"
    option is specified.

  3.2 libxmount_morphing_raid
    This morphing library supports emulation of hardware / software raid.
    Currently, only RAID0 ("--morph raid0") is supported. The used chunk /
    stripe size in bytes can be specified with "--morphopts raid_chunksize=XXX".
    All input images are treated as member disks of the original raid.

  3.3 libxmount_morphing_unallocated
    Using "--morph unallocated" it is possible to extract unallocated sectors
    from a filesystem. For this to work, your input image must start with the
    volume you want to extract unallocated sectors from. If you have an image of
    a whole disk, you might need to use xmounts "--offset" parameter to move the
    start of the data to the start of the volume. Currently, unallocated
    sectors from HFS and FAT can be extracted.

4.0 Output image
  4.1 Emulated RAW file
    This is the standard data representation used by xmount. It is a file
    containing the raw data contained in the input image file. Except for OSx
    (see 4.2) this is the default output format when no --out option is
    specified.

  4.2 Emulated DMG file
    This is also a file containing the raw data contained in the input image
    file but with a .dmg file extension. On OSx, this is the default output
    format when no --out option is specified.

  4.3 Emulated VDI file
    When using the "--out vdi" command line parameter, a VirtualBox disk file
    is emulated. This means that xmount builds a virtual VDI header and prepends
    it to the raw data contained in the input image. The VDI file can be used in
    VirtualBox as a virtual disk file.

  4.4 Emulated VMDK file
    When using the "--out vmdk(s)" command line paramter, a VMWare virtual disk
    file will be emulated. This mainly consists in building a VMDK descriptor
    file that will access an emulated RAW file. You can use this VMDK file to
    add your input image as virtual disk to a VMWare virtual machine. "vmdk" is
    a VMWare disk attached to the IDE bus and "vmdks" is attached to the SCSI
    bus.

    When emulating VMDK files to be used in VMWare, you have to enable
    "user_allow_other" in /etc/fuse.conf or run xmount and VmWare as root.

    WARNING: VMDK support should be considered experimental and currently the
             VMDK descriptor file isn't cached.

  4.5 Emulated VHD file
    When using the "--out vhd" command line parameter, a Virtual Hard Disk Image
    file is emulated by appending to the raw data a valid VHD footer. Valid here
    means as described in Microsoft's Virtual Hard Disk Image Format specs v1.

5.0 Virtual write access
    By using the "--cache <cache_file>" command line parameter, xmount allows
    you to change data in the emulated image files. All changes are written to a
    separate cache file. No data will ever be written to the original input
    image files! Write access is limited to change existing data. It isn't
    possible to change the emulated image's file size (no append or truncate)!
    The same cache file can be used with different output image formats without
    loosing changed data.

6.0 Installation instructions
  To install xmount, you can use a prebuild package for your distribution or
  you can build xmount from source. The two methods are described in the
  following sections.

  6.1 Install from a prebuild package
    Chances are I provide prebuild binary packages for Debian / Ubuntu and OSx.
    In this case, you only have to fire up your distribution's package manager
    and install xmount.

  6.2 Install from source
    6.2.1 General prerequisits
      SYSTEM:
        - Linux: Some sort of Linux with a recent kernel (2.6.x or above).
        - OSx: OSx 10.6 or above

      FUSE:
        Your OS must support FUSE and have the appropriate libraries installed.
        (See https://github.com/libfuse/libfuse for more informations). On OSx,
        you can use MacFuse (https://osxfuse.github.io/) as replacement. To be
        able to install from source, you also need the FUSE header files.

      LIBEWF:
        To enable EWF input image support. Get it from
        https://github.com/libyal/libewf or use the version that is part of the
        xmount source tree.

      LIBAFF3:
        To enable AFFv3 input image support. Get it from
        https://github.com/sshock/AFFLIBv3 or use the version that is part of
        the xmount source tree.

      LIBAFF4:
        To enable AFFv4 input image support. Get it from
        https://github.com/aff4/aff4-cpp-lite or use the version that is part
        of the xmount source tree.

    6.2.2 Shared vs static builds
      Shared xmount builds will rely on the libraries installed on your system
      during build to also be available during execution. This is generally the
      preferred method to build software on Linux.

      Static xmount builds will incorporate **some** "problematic" libraries
      into the final binary so they don't have to be present on your system
      during execution. These libraries generally lack pre-packaged builds or a
      very specific version is needed. All other used libraries will still be
      dynamically linked.

      Statically linked xmount builds are for example used to be able to support
      multiple Debian versions with the same binary, support input image formats
      for which no libraries exist under Debian, or to support OSx at all.

      Packages released trough the official Debian / Ubuntu package repositories
      always include dynamically linked builds and might therefore lack some
      functionality.

      Packages released trough our own repository will always include statically
      linked builds and therefore include all available functionality.

    6.2.3 Installing prerequisits on Debian based systems
      For shared builds:

      $ sudo apt install build-essential cmake pkg-config libfuse-dev \
        zlib1g-dev libewf-dev libafflib-dev

      For static builds:

      $ sudo apt install build-essential cmake pkg-config autoconf automake \
        libfuse-dev zlib1g-dev libssl-dev libexpat1-dev liblz4-dev \
        libcppunit-dev liblzma-dev libtool bison flex

    6.2.4 Installing prerequisits on OSx
      After installing OSXFuse and MacPorts (https://www.macports.org) issue the
      following command in a terminal:

      $ sudo port install autoconf automake cmake libtool pkgconfig readline \
        cppunit openssl zlib expat ncurses readline lz4

      I recommend building xmount statically under OSx using the ewf and aff
      libraries that are part of the xmount source tree. They can be compiled
      using the following command:

      $ ./BuildLibs.sh

      Once they hav been compiled successfully, replace the cmake command below
      with the following one:

      $ cmake -DCMAKE_BUILD_TYPE=Release -DSTATIC=1 ..

    6.2.5 Compilation / Installation
      After having installed the prerequisits, you should be able to compile and
      install xmount by simply issuing the following commands:

      $ mkdir build
      $ cd build
      $ cmake -DCMAKE_BUILD_TYPE=Release ..
      $ make
      $ sudo make install

7.0 xmount usage examples
  To xmount an EWF harddisk image from your acquired disk as a raw DD image
  under /mnt, use the following command:

    xmount --in aewf ./acquired_disk.E?? /mnt

  To xmount the same ewf image as vdi file, you would use a command like this:

    xmount --in aewf ./acquired_disk.E?? --out vdi /mnt

  And to enable virtual write support on a raw DD input image xmounted as VDI
  file:

    xmount --in raw ./acquired_disk.dd --out vdi --cache ./disk.cache /mnt

EOF