Python interface

While imount heavily utilizes the Python API of imagemounter, this API is also available for other classes.

Data structure

The basic structure of imagemounter is the imagemounter.ImageParser class, which provides access to underlying imagemounter.Disk and imagemounter.Volume objects. Each file name passed to a new imagemounter.ImageParser object results in one imagemounter.Disk object. imagemounter.Volume objects are created by analysis of the Disk object (each volume generates one object, even if it is not mountable), and each imagemounter.Volume can have one or more subvolumes.

For instance, a LUKS volume may contain a LVM system that contains a Ext volume. This would create a Disk with a Volume containing a Volume which contains the actual Ext Volume. Subvolumes are managed through imagemounter.VolumeSystem`s, which is used by both the :class:`Volume and Disk classes.

Most operations are managed on a Volume level, although individual disk file mounting (and volume detection) is performed on a Disk level and reconstruction is performed on a ImageParser level. This means the following main parts make up the Python package:

  • imagemounter.ImageParser, maintaining a list of Disks, providing several methods that are carried out on all disks (e.g. mount) and reconstruct.
  • imagemounter.Disk, which represents a single disk iamge and can be mounted, and maintain volumes. It is also responsible for maintaining the write cache. Although a Disk is able to detect volumes, a Volume has similar capabilities.
  • imagemounter.Volume, which can detect its own type and fill its stats, can be mounted, and maintain subvolumes.
  • imagemounter.VolumeSystem, which is used to manage subvolumes and can detect volumes from a volume system.

All three classes maintain an init() method that yields the volumes below it. You should call clean() on the parser as soon as you are done; you may also call unmount() on separate volumes or disks, which will also unmount all volumes below it. Warning: unmounting one of the RAID volumes in a RAID array, causes the entire array to be unmounted.

Reference

If you utilize the API, you typically only require the ImageParser object, e.g.:

parser = ImageParser(['/path/to/disk'])
for v in parser.init():
    print v.size
root = parser.reconstruct()
print root.mountpoint
parser.clean()

The best example of the use of the Python interface is the imount command. The entirety of all methods and attributes is documented below.

ImageParser

class imagemounter.ImageParser(paths=(), force_disk_indexes=False, casename=None, read_write=False, disk_mounter=u'auto', volume_detector=u'auto', vstypes=None, fstypes=None, keys=None, mountdir=None, pretty=False, **args)

Root object of the imagemounter Python interface. This class should be sufficient allowing access to the underlying functions of this module.

Instantiation of this class does not automatically mount, detect or analyse Disk s, though it initialises each provided path as a new Disk object.

Parameters:
  • paths (iterable) – list of paths to base images that should be mounted
  • force_disk_indexes – if True, a Disk index is always included. If False, will only use Disk indexes if more than 1 Disk is provided to the paths
  • casename – the name of the case, used when prettifying names
  • read_write (bool) – indicates whether disks should be mounted with a read-write cache enabled
  • disk_mounter (str) – the method to mount the base images with
  • fstypes (dict) – dict mapping volume indices to file system types to use; use * and ? as volume indexes for additional control. Only when ?=none, unknown will not be used as fallback.
  • keys (dict) – dict mapping volume indices to key material
  • mountdir (str) – location where mountpoints are created, defaulting to a temporary location
  • pretty (bool) – indicates whether pretty names should be used for the mountpoints
  • args – ignored
add_disk(path, force_disk_indexes=True, **args)

Adds a disk specified by the path to the ImageParser.

Parameters:
  • path – The path to the disk volume
  • force_disk_indexes – If true, always uses disk indexes. If False, only uses disk indexes if this is the second volume you add. If you plan on using this method, always leave this True. If you add a second disk when the previous disk has no index, an error is raised.
  • args – Arguments to pass to the constructor of the Disk.
init(single=None, swallow_exceptions=True)

Handles all important disk-mounting tasks, i.e. calls the Disk.init() function on all underlying disks. It yields every volume that is encountered, including volumes that have not been mounted.

Parameters:
  • single (bool|None) – indicates whether the Disk should be mounted as a single disk, not as a single disk or whether it should try both (defaults to None)
  • swallow_exceptions – specify whether you want the init calls to swallow exceptions
Return type:

generator

init_volumes(single=None, only_mount=None, swallow_exceptions=True)

Detects volumes (as volume system or as single volume) in all disks and yields the volumes. This calls Disk.init_volumes() on all disks and should be called after mount_disks().

Return type:generator
reconstruct()

Reconstructs the filesystem of all volumes mounted by the parser by inspecting the last mount point and bind mounting everything.

Raises:NoRootFoundError if no root could be found
Returns:the root Volume
clean(remove_rw=False, allow_lazy=False)

Cleans all volumes of all disks (Volume.unmount()) and all disks (Disk.unmount()). Volume errors are ignored, but returns immediately on disk unmount error.

Parameters:
  • remove_rw (bool) – indicates whether a read-write cache should be removed
  • allow_lazy (bool) – indicates whether lazy unmounting is allowed
Raises:
  • SubsystemError – when one of the underlying commands fails. Some are swallowed.
  • CleanupError – when actual cleanup fails. Some are swallowed.
force_clean(remove_rw=False, allow_lazy=False, retries=5, sleep_interval=0.5)

Attempts to call the clean method, but will retry automatically if an error is raised. When the attempts run out, it will raise the last error.

Note that the method will only catch ImageMounterError exceptions.

Parameters:
  • remove_rw (bool) – indicates whether a read-write cache should be removed
  • allow_lazy (bool) – indicates whether lazy unmounting is allowed
  • retries – Maximum amount of retries while unmounting
  • sleep_interval – The sleep interval between attempts.
Raises:
  • SubsystemError – when one of the underlying commands fails. Some are swallowed.
  • CleanupError – when actual cleanup fails. Some are swallowed.

Most methods above, especially init(), handle most complicated tasks. However, you may need some more fine-grained control over the mount process, which may require you to use the following methods. Each of these methods passes their activities down to all disks in the parser and return whether it succeeded.

rw_active()

Indicates whether a read-write cache is active in any of the disks.

Return type:bool
get_volumes()

Gets a list of all volumes of all disks, concatenating Disk.get_volumes() of all disks.

Return type:list
get_by_index(index)

Returns a Volume or Disk by its index.

mount_disks()

Mounts all disks in the parser, i.e. calling Disk.mount() on all underlying disks. You probably want to use init() instead.

Returns:whether all mounts have succeeded
Return type:bool

For completeness, this is a list of all attributes of ImageParser:

disks

List of all Disk objects.

paths
casename
fstypes
keys
vstypes
mountdir
pretty

See the constructor of ImageParser.

Disk

class imagemounter.Disk(parser, path, index=None, offset=0, block_size=512, read_write=False, vstype=u'', disk_mounter=u'auto', volume_detector=u'auto')

Representation of a disk, image file or anything else that can be considered a disk.

Instantiation of this class does not automatically mount, detect or analyse the disk. You will need the init() method for this.

Only use arguments offset and further as keyword arguments.

Parameters:
  • parser (ImageParser) – the parent parser
  • path (str) – the path of the Disk
  • index (str) – the base index of this Disk
  • offset (int) – offset of the disk where the volume (system) resides
  • block_size (int) –
  • read_write (bool) – indicates whether the disk should be mounted with a read-write cache enabled
  • vstype (str) – the volume system type to use.
  • disk_mounter (str) – the method to mount the base image with
  • volume_detector (str) – the volume system detection method to use
init(single=None, only_mount=None, swallow_exceptions=True)

Calls several methods required to perform a full initialisation: mount(), and mount_volumes() and yields all detected volumes.

Parameters:single (bool|None) – indicates whether the disk should be mounted as a single disk, not as a single disk or whether it should try both (defaults to None)
Return type:generator
mount()

Mounts the base image on a temporary location using the mount method stored in method. If mounting was successful, mountpoint is set to the temporary mountpoint.

If read_write is enabled, a temporary read-write cache is also created and stored in rwpath.

Returns:whether the mounting was successful
Return type:bool
detect_volumes(single=None)

Generator that detects the volumes from the Disk, using one of two methods:

  • Single volume: the entire Disk is a single volume
  • Multiple volumes: the Disk is a volume system
Parameters:single – If single is True, this method will call init_single_volumes(). If single is False, only init_multiple_volumes() is called. If single is None, init_multiple_volumes() is always called, being followed by init_single_volume() if no volumes were detected.
init_volumes(single=None, only_mount=None, swallow_exceptions=True)

Generator that detects and mounts all volumes in the disk.

Parameters:
  • single – If single is True, this method will call init_single_volumes(). If single is False, only init_multiple_volumes() is called. If single is None, init_multiple_volumes() is always called, being followed by init_single_volume() if no volumes were detected.
  • only_mount (list) – If set, must be a list of volume indexes that are only mounted.
  • swallow_exceptions (bool) – If True, Exceptions are not raised but rather set on the instance.
unmount(remove_rw=False, allow_lazy=False)

Removes all ties of this disk to the filesystem, so the image can be unmounted successfully.

Raises:
  • SubsystemError – when one of the underlying commands fails. Some are swallowed.
  • CleanupError – when actual cleanup fails. Some are swallowed.

The following methods are only required if you want some fine-grained control, typically if you are not using init().

get_disk_type()
rw_active()

Indicates whether anything has been written to a read-write cache.

get_fs_path()

Returns the path to the filesystem. Most of the times this is the image file, but may instead also return the MD device or loopback device the filesystem is mounted to.

Return type:str
get_raw_path()

Returns the raw path to the mounted disk image, i.e. the raw .dd, .raw or ewf1 file.

Return type:str
get_volumes()

Gets a list of all volumes in this disk, including volumes that are contained in other volumes.

The following attributes are also available:

index

Disk index. May be None if it is the only disk of this type.

mountpoint

The mountpoint of the disk, after a call to mount().

rwpath

The path to the read-write cache, filled after a call to mount().

volumes

VolumeSystem of all direct child volumes of this disk, excluding all subvolumes. See get_volumes().

method

Used to store the base mount method. If it is set to auto, this value will be overwritten with the actually used mount method after calling mount().

See also the constructor of Disk.

parser
paths
offset
read_write
disk_mounter

See the constructor of Disk.

Volume

class imagemounter.Volume(disk, parent=None, index=u'0', size=0, offset=0, flag=u'alloc', slot=0, fstype=u'', key=u'', vstype=u'', volume_detector=u'auto')

Information about a volume. Note that every detected volume gets their own Volume object, though it may or may not be mounted. This can be seen through the mountpoint attribute – if it is not set, perhaps the exception attribute is set with an exception.

Creates a Volume object that is not mounted yet.

Only use arguments as keyword arguments.

Parameters:
  • disk (Disk) – the parent disk
  • parent – the parent volume or disk.
  • index (str) – the volume index within its volume system, see the attribute documentation.
  • size (int) – the volume size, see the attribute documentation.
  • offset (int) – the volume offset, see the attribute documentation.
  • flag (str) – the volume flag, see the attribute documentation.
  • slot (int) – the volume slot, see the attribute documentation.
  • fstype (str) – the fstype you wish to use for this Volume. May be ?<fstype> as a fallback value. If not specified, will be retrieved from the ImageParser instance instead.
  • key (str) – the key to use for this Volume.
  • vstype (str) – the volume system type to use.
  • volume_detector (str) – the volume system detection method to use
init(only_mount=None, swallow_exceptions=True)

Generator that mounts this volume and either yields itself or recursively generates its subvolumes.

More specifically, this function will call load_fsstat_data() (iff no_stats is False), followed by mount(), followed by a call to detect_mountpoint(), after which self is yielded, or the result of the init() call on each subvolume is yielded

Parameters:
  • only_mount – if specified, only volume indexes in this list are mounted. Volume indexes are strings.
  • swallow_exceptions – if True, any error occuring when mounting the volume is swallowed and added as an exception attribute to the yielded objects.
init_volume(fstype=None)

Initializes a single volume. You should use this method instead of mount() if you want some sane checks before mounting.

unmount(allow_lazy=False)

Unounts the volume from the filesystem.

Raises:
  • SubsystemError – if one of the underlying processes fails
  • CleanupError – if the cleanup fails

The following methods offer some more information about the volume:

get_description(with_size=True, with_index=True)

Obtains a generic description of the volume, containing the file system type, index, label and NTFS version. If with_size is provided, the volume size is also included.

get_safe_label()

Returns a label that is safe to add to a path in the mountpoint for this volume.

get_formatted_size()

Obtains the size of the volume in a human-readable format (i.e. in TiBs, GiBs or MiBs).

get_volumes()

Recursively gets a list of all subvolumes and the current volume.

These functions offer access to some internals:

determine_fs_type()

Determines the FS type for this partition. This function is used internally to determine which mount system to use, based on the file system description. Return values include ext, ufs, ntfs, lvm and luks.

Note: does not do anything if fstype is already set to something sensible.

get_raw_path(include_self=False)

Retrieves the base mount path of the volume. Typically equals to Disk.get_fs_path() but may also be the path to a logical volume. This is used to determine the source path for a mount call.

The value returned is normally based on the parent’s paths, e.g. if this volume is mounted to a more specific path, only its children return the more specific path, this volume itself will keep returning the same path. This makes for consistent use of the offset attribute. If you do not need this behaviour, you can override this with the include_self argument.

This behavior, however, is not retained for paths that directly affect the volume itself, not the child volumes. This includes VSS stores and LV volumes.

mount(fstype=None)

Based on the file system type as determined by determine_fs_type(), the proper mount command is executed for this volume. The volume is mounted in a temporary path (or a pretty path if pretty is enabled) in the mountpoint as specified by mountpoint.

If the file system type is a LUKS container or LVM, additional methods may be called, adding subvolumes to volumes

Raises:
  • NotMountedError – if the parent volume/disk is not mounted
  • NoMountpointAvailableError – if no mountpoint was found
  • NoLoopbackAvailableError – if no loopback device was found
  • UnsupportedFilesystemError – if the fstype is not supported for mounting
  • SubsystemError – if one of the underlying commands failed
bindmount(mountpoint)

Bind mounts the volume to another mountpoint. Only works if the volume is already mounted.

Raises:
  • NotMountedError – when the volume is not yet mounted
  • SubsystemError – when the underlying command failed
carve(freespace=True)

Call this method to carve the free space of the volume for (deleted) files. Note that photorec has its own interface that temporarily takes over the shell.

Parameters:

freespace (bool) – indicates whether the entire volume should be carved (False) or only the free space (True)

Returns:

string to the path where carved data is available

Raises:
  • CommandNotFoundError – if the underlying command does not exist
  • SubsystemError – if the underlying command fails
  • NoMountpointAvailableError – if there is no mountpoint available
  • NoLoopbackAvailableError – if there is no loopback available (only when volume has no slot number)
detect_volume_shadow_copies()

Method to call vshadowmount and mount NTFS volume shadow copies.

Returns:

iterable with the Volume objects of the VSS

Raises:
  • CommandNotFoundError – if the underlying command does not exist
  • SubSystemError – if the underlying command fails
  • NoMountpointAvailableError – if there is no mountpoint available
detect_mountpoint()

Attempts to detect the previous mountpoint if this was not done through load_fsstat_data(). This detection does some heuristic method on the mounted volume.

The following details may also be available as attributes:

size

The size of the volume in bytes.

offset

The offset of the volume in the disk in bytes.

index

The index of the volume in the disk. If there are subvolumes, the index is separated by periods, though the exact format depends on the detection method and its format.

slot

Internal slot number of the volume.

flag

Indicates whether this volume is allocated (alloc), unallocated (unalloc) or a meta volume (meta).

block_size

The block size of this volume.

fstype

The volume file system type used internally as determined by determine_fs_type().

key

The key used by some crypto methods.

info

A dict containing information about the volume. Not all keys are always available. Some common keys include:

  • fsdescription – A description of the file system type, usually set by the detection method
  • lastmountpoint – The last mountpoint of this volume. Set by load_fsstat_data() or detect_mountpoint() and only available for UFS and Ext volumes
  • label – The volume label as detected by load_fsstat_data()
  • version – The volume version as detected by load_fsstat_data()
  • statfstype – The volume file system type as detected by load_fsstat_data()
  • guid – The volume GUID
  • volume_group – Used for LVM support

The contents of the info dict are not considered part of a stable API and are subject to change in the future.

mountpoint

The mountpoint of the volume after mount() has been called.

loopback

The loopback device used by the volume after mount() (or related methods) has been called.

was_mounted
is_mounted

Booleans indicating that the volume has successfully been mounted during its lifetime, and is currently mounted

volumes
parent

volumes contains a VolumeSystem of all subvolumes of this volume; parent contains the parent volume (if any).

disk
stats
fstypes
pretty
mountdir
args

See the constructor of Volume.

VolumeSystem

class imagemounter.VolumeSystem(parent, vstype=u'', volume_detector=u'')

A VolumeSystem is a collection of volumes. Every Disk contains exactly one VolumeSystem. Each system contains several Volumes, which, in turn, may contain additional volume systems.

Creates a VolumeSystem.

Parameters:
  • parent – the parent may either be a Disk or a Volume that contains this VolumeSystem.
  • vstype (str) – the volume system type to use.
  • volume_detector (str) – the volume system detection method to use
detect_volumes(vstype=None, method=None, force=False)

Iterator for detecting volumes within this volume system.

Parameters:
  • vstype (str) – The volume system type to use. If None, uses vstype
  • method (str) – The detection method to use. If None, uses detection
  • force (bool) – Specify if you wnat to force running the detection if has_Detected is True.
preload_volume_data()

Preloads volume data. It is used to call internal methods that contain information about a volume.

__iter__()
__getitem__(item)
volumes

The list of all volumes in this system.

volume_source

The source of the volumes of this system, either single or multi.

has_detected

Boolean indicating whether this volume already ran its detection.

vstype
detection
args

See the constructor of VolumeSystem.

Unmounter

class imagemounter.Unmounter(casename=None, pretty=False, mountdir=None, allow_greedy=True, *args, **kwargs)

Allows easy unmounting of left-overs of ImageParser calls.

Instantiation of this class automatically indexes the mountpoints and loopbacks currently on the system. However, in the time between calling any find function and actually unmounting anything, the system may change. This can be especially painful when using preview_unmount().

Parameters:
  • casename (str) – The casename to be unmounted, see ImageParser
  • pretty (bool) – Whether the volumes were mounted using pretty mount, see Volume
  • mountdir (str) – The mountdir wheret he volumes were mounted, see Volume
  • allow_greedy (bool) – When none of the parameters are specified, by default, a greedy method will try to find as much possible mount points as possible.
preview_unmount()

Returns a list of all commands that would be executed if the unmount() method would be called.

Note: any system changes between calling this method and calling unmount() aren’t listed by this command.

unmount()

Calls all unmount methods in the correct order.

find_bindmounts()

Finds all bind mountpoints that are inside mounts that match the re_pattern

find_mounts()

Finds all mountpoints that are mounted to a directory matching re_pattern or originate from a directory matching orig_re_pattern.

find_base_images()

Finds all mountpoints that are mounted to a directory matching orig_re_pattern.

find_volume_groups()

Finds all volume groups that are mounted through a loopback originating from orig_re_pattern.

Generator yields tuples of vgname, pvname

find_loopbacks()

Finds all loopbacks originating from orig_re_pattern.

Generator yields device names

find_clean_dirs()

Finds all (temporary) directories according to the glob and re patterns that should be cleaned.

unmount_bindmounts()

Unmounts all bind mounts identified by find_bindmounts()

unmount_mounts()

Unmounts all mounts identified by find_mounts()

unmount_base_images()

Unmounts all mounts identified by find_base_images()

unmount_volume_groups()

Unmounts all volume groups and related loopback devices as identified by find_volume_groups()

unmount_loopbacks()

Unmounts all loopback devices as identified by find_loopbacks()

clean_dirs()

Does a final cleaning of the (temporary) directories according to find_clean_dirs().

re_pattern

The regex pattern used to look for volume mountpoints.

glob_pattern

The glob pattern used to look for volume mountpoints. Always used in conjunction with the re_pattern.

orig_re_pattern

The regex pattern used to look for base mountpoints.

orig_glob_pattern

The glob pattern used to look for base mountpoints. Always used in conjunction with the orig_re_pattern.

be_greedy

If set, some more volumes and mountpoints may be found.