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 newDisk
object.Parameters: -
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 toNone
) - raid (bool) – indicates whether RAID detection is enabled
Return type: generator
- single (bool|None) – indicates whether the
-
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 useinit()
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 beforemount_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 aftermount_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 aftermount_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 aftermount_disks()
.Return type: generator
For completeness, this is a list of all attributes of
ImageParser
:-
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()
andmount_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
- 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
-
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
orewf1
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 inrwpath
.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 callmount_single_volumes()
. If single is False, onlymount_multiple_volumes()
is called. If single is None,mount_multiple_volumes()
is always called, being followed bymount_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 callinit()
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 andinit()
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.
-
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()
.
- parser (
-
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 theexception
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 bymount()
, followed by a call todetect_mountpoint()
, after whichself
is yielded, or the result of theinit()
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 ifpretty
is enabled) in the mountpoint as specified bymountpoint
.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 tovolumes
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()
ordetect_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()
.
-
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.
-
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).
-
luks_path
¶ Attribute used for LUKS support
- disk (
-
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 usingpreview_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 matchingorig_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.
- casename (str) – The casename to be unmounted, see