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.

Most operations are managed on a Volume level, although RAIDs (and volume detection) are managed 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, added to RAID, and detect and maintain volumes. It is also responsible for maintaining the write cache.
imagemounter.Volume, which can detect its own type and fill its stats, can be mounted, and detect LVM (sub)volumes.

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.

class imagemounter.ImageParser(paths, casename=None, **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 casename – the name of the case, used when prettifying names args – arguments that should be passed down to `Disk` and `Volume` objects

init(single=None, raid=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`) raid (bool) – indicates whether RAID detection is enabled
Return type:	generator

reconstruct()¶

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

Returns:	None on failure, or the root `Volume` on success

clean(remove_rw=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
Returns:	whether the command completed successfully
Return type:	boolean

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

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

mount_raid()¶

Creates a RAID device and adds all devices to the RAID array, i.e. calling Disk.add_to_raid() on all underlying disks. Should be called before mount_disks().

Returns:	whether all disks were successfully added
Return type:	bool

mount_single_volume()¶

Detects the full disk as a single volume and yields the volume. This calls Disk.mount_single_volume() on all disks and should be called after mount_disks()

Return type:	generator

mount_multiple_volumes()¶

Detects volumes in all disks (all mounted as a volume system) and yields the volumes. This calls Disk.mount_multiple_volumes() on all disks and should be called after mount_disks().

Return type:	generator

mount_volumes(single=None)¶

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

Return type:	generator

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

disks¶: List of all Disk objects.

paths¶
casename¶
args¶: See the constructor of ImageParser.

class imagemounter.Disk(parser, path, offset=0, vstype=u'detect', read_write=False, method=u'auto', detection=u'auto', multifile=True, index=None, mount_directories=True, **args)¶

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.

Parameters:

parser (ImageParser) – the parent parser
offset (int) – offset of the disk where the volume (system) resides
vstype (str) – the volume system type
read_write (bool) – indicates whether the disk should be mounted with a read-write cache enabled
method (str) – the method to mount the base image with
detection (str) – the method to detect volumes in the volume system with
multifile (bool) – indicates whether mount() should attempt to call the underlying mount method with all files of a split file when passing a single file does not work
index (str) – the base index of this Disk
mount_directories (bool) – indicates whether directories should also be ‘mounted’
args – arguments that should be passed down to Volume objects

init(single=None, raid=True, disktype=True)¶

Calls several methods required to perform a full initialisation: mount(), add_to_raid() 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`) raid (bool) – indicates whether RAID detection is enabled disktype (bool) – indicates whether disktype data should be loaded and used
Return type:	generator

unmount(remove_rw=False)¶: Removes all ties of this disk to the filesystem, so the image can be unmounted successfully. Warning: this method will destruct the entire RAID array in which this disk takes part.

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

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.

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

mount_volumes(single=None)¶

Generator that detects and mounts all volumes in the disk.

If single is True, this method will call mount_single_volumes(). If single is False, only mount_multiple_volumes() is called. If single is None, mount_multiple_volumes() is always called, being followed by mount_single_volume() if no volumes were detected.

mount_multiple_volumes()¶: Generator that will detect volumes in the disk file, generate Volume objects based on this information and call init() on these.

mount_single_volume()¶

Mounts a volume assuming that the mounted image does not contain a full disk image, but only a single volume.

A new Volume object is created based on the disk file and init() is called on this object.

This function will typically yield one volume, although if the volume contains other volumes, multiple volumes may be returned.

is_raid()¶: Tests whether this image (was) part of a RAID array. Requires mdadm to be installed.

add_to_raid()¶

Adds the disk to a central RAID volume.

This function will first test whether it is actually a RAID volume by using is_raid() and, if so, will add the disk to the array via a loopback device.

Returns:	whether the addition succeeded

The following attributes are also available:

name¶: Pretty name of the disk.

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¶: List of all direct child volumes of this disk, excluding all subvolumes. See get_volumes().

volume_source¶: The source of the volumes of this disk, either single or multi, filled after a call to mount_volumes().

loopback¶
md_device¶: Used for RAID support.

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¶
path¶
offset¶
vstype¶
read_write¶
detection¶
multifile¶
args¶: See the constructor of Disk.

class imagemounter.Volume(disk=None, stats=True, fsforce=False, fsfallback=u'unknown', fstypes=None, pretty=False, mountdir=None, **args)¶

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.

Parameters:

disk (Disk) – the parent disk
stats (bool) – indicates whether init() should try to fill statistics
fsforce (bool) – indicates whether the file system type in fsfallback should be used for all file systems
fsfallback (str) – the file system type to use when automatic detection fails
fstypes (dict) – dict mapping volume indices to file system types to (forcibly) use
pretty (bool) – indicates whether pretty names should be used for the mountpoints
mountdir (str) – location where mountpoints are created, defaulting to a temporary location
args – additional arguments

init(no_stats=False)¶

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

More specifically, this function will call fill_stats() (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

unmount()¶: Unounts the volume from the filesystem.

The following methods offer some more information about the volume:

get_description(with_size=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_size_gib()¶: 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.

get_raw_base_path()¶: 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.

mount()¶

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, open_luks_container() is called only. If it is a LVM volume, find_lvm_volumes() is called after the LVM has been mounted. Both methods will add subvolumes to volumes

Returns:	boolean indicating whether the mount succeeded

bindmount(mountpoint)¶

Bind mounts the volume to another mountpoint. Only works if the volume is already mounted. Note that only the last bindmountpoint is remembered and cleaned.

Returns:	bool indicating whether the bindmount succeeded

fill_stats()¶: Using fsstat, adds some additional information of the volume to the Volume.

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

find_lvm_volumes(force=False)¶

Performs post-mount actions on a LVM. Scans for active volume groups from the loopback device, activates it and fills volumes with the logical volumes.

If force is true, the LVM detection is ran even when the LVM is not mounted on a loopback device.

open_luks_container()¶

Command that is an alternative to the mount() command that opens a LUKS container. The opened volume is added to the subvolume set of this volume. Requires the user to enter the key manually.

Returns:	the Volume contained in the LUKS container, or None on failure.

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.

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

fsdescription¶: A description of the file system type.

lastmountpoint¶: The last mountpoint of this volume. Set by fill_stats() or detect_mountpoint() and only available for UFS and Ext volumes.

label¶: The volume label as detected by fill_stats().

version¶: The volume version as detected by fill_stats().

statfstype¶: The volume file system type as detected by fill_stats().

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

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

bindmountpoint¶: The mountpoint of the volume after bindmount() has been called.

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

exception¶: Contains an exception that occurred during a call to mount().

was_mounted¶: Boolean indicating that the volume has successfully been mounted during its lifetime.

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

volume_group¶
lv_path¶: Attributes used for LVM support

luks_path¶: Attribute used for LUKS support

disk¶
stats¶
fsforce¶
fsfallback¶
fstypes¶
pretty¶
mountdir¶
args¶: See the constructor of Volume.

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_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()

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.