kpartx

Add partition mappings

$ kpartx -a [whole_disk.img]

$ kpartx -d [whole_disk.img]

$ kpartx -l [whole_disk.img]

kpartx [-a | -d | -u | -l] [-f] [-r] [-p prefix] [-s] [-v] [-z] [-n] [-g] [--raw] [--bytes] device

-a
    Add partition device maps for the specified device. This is the default action if no explicit action is chosen.

-d
    Delete partition device maps for the specified device.

-u
    Update partition device maps for the specified device. This action effectively deletes existing maps and then recreates them based on the current partition table.

-l
    List partition device maps without performing any creation or deletion operations.

-f
    Force update. When adding or updating maps, this option ensures any existing maps for the partitions are flushed (removed from cache/kernel) before new ones are created.

-r
    Create read-only device maps for the partitions, preventing any write operations through the device mapper interfaces.

-p prefix
    Specify a custom prefix for the device mapper partition names. The default prefix is 'p', resulting in names like /dev/mapper/loop0p1. For example, using 'kpartx -p - /dev/sdb' would generate names such as /dev/mapper/sdb-1.

-s
    Synchronize map creation with disk. This option ensures that kpartx waits for the udev (device manager) event to complete before exiting, which can be useful in scripts where immediate device availability is critical.

-v
    Enable verbose output. This provides more detailed information about the operations being performed by kpartx.

-z
    This option is only applicable when deleting maps (used with -d). It prevents the deletion of device maps if any of the partitions are currently in use or busy.

-n
    Perform a dry run. kpartx will print the commands that would be executed but will not actually perform any operations on the system.

-g
    Attempt to guess the partition type. This is particularly useful for raw disk images where the partition table might not adhere strictly to standard formats.

--raw
    Output partition information in a raw format, which is highly suitable for scripting. It typically prints one line per partition in the format 'device_mapper_name start_sector num_sectors'.

--bytes
    When displaying information or raw output, print sizes and offsets in bytes rather than the default sectors.

device
    The path to the block device (e.g., /dev/sda, /dev/loop0, or a disk image file) for which partition maps are to be managed.

The kpartx command is a utility that reads the partition table on a specified block device and subsequently creates device mapper devices for each primary and logical partition found within it. This functionality is invaluable for scenarios involving disk images (e.g., .img or .iso files) by associating them with a loop device, or for managing partitions directly on physical block devices like hard drives or SSDs.

It's commonly used in conjunction with losetup to access file systems embedded within disk images without needing to write the image to physical media. kpartx dynamically populates the /dev/mapper/ directory with entries corresponding to the detected partitions, enabling them to be treated as independent block devices for mounting, file system checks, or other operations. The command supports adding, deleting, or merely listing these partition maps.

kpartx relies heavily on the kernel's device mapper and the udev subsystem. Problems with these underlying services can directly impact kpartx's functionality. It may not correctly interpret all types of partition tables, especially highly unusual or corrupted ones. When deleting maps, proceeding without the -z option on busy partitions could potentially lead to data corruption if not managed carefully.

One of the most frequent applications of kpartx is in conjunction with the losetup command to access partitions embedded within disk image files. The typical workflow involves:
1. Attaching the disk image to a loop device (e.g., /dev/loop0) using losetup.
2. Using kpartx -a /dev/loop0 to automatically create device mapper entries (e.g., /dev/mapper/loop0p1, /dev/mapper/loop0p2) for all detected partitions within that image.
These newly created device mapper entries can then be treated as standard block devices, allowing them to be mounted, checked for file system integrity, or otherwise manipulated.

By default, kpartx generates device mapper names by appending 'p' and the partition number to the base device name (e.g., /dev/sdb becomes /dev/mapper/sdbp1 for its first partition). The -p option offers flexibility in customizing this naming convention. For instance, employing -p - can result in names such as /dev/mapper/sdb-1, which some users or scripts might find more intuitive or easier to parse due to the clear hyphenated separation.

kpartx is a component of the multipath-tools package, which primarily provides the multipath command for configuring device mapper multipathing. Its development is closely tied to the Linux device-mapper infrastructure. Although often used in conjunction with multipath, kpartx carved out its own niche as a standalone utility for exposing partitions within block devices, particularly for handling disk images and complex storage setups, becoming an indispensable tool in Linux system administration and digital forensics.

losetup(8), dmsetup(8), multipath(8), fdisk(8), parted(8)