kpartx Command Linux: Create and Manage Partition Maps with Complete Examples

The kpartx command is a powerful Linux utility that creates device maps from partition tables, enabling you to access partitions within disk images or block devices. This essential tool is particularly useful for system administrators working with virtual machines, disk images, or complex storage configurations.

What is kpartx Command?

The kpartx command creates device mappings for partitions found in partition tables. It works by reading partition information from a device or image file and creating corresponding device nodes in /dev/mapper/ that represent each partition. This functionality is crucial when working with:

• Virtual machine disk images
• Loop devices with multiple partitions
• Complex RAID configurations
• Disk forensics and recovery operations

Installation and Requirements

The kpartx command is part of the multipath-tools package. Install it using your distribution’s package manager:

# Ubuntu/Debian
sudo apt update
sudo apt install kpartx

# RHEL/CentOS/Fedora
sudo yum install kpartx
# or
sudo dnf install kpartx

# Arch Linux
sudo pacman -S multipath-tools

Basic Syntax and Options

The basic syntax of the kpartx command is:

kpartx [OPTIONS] DEVICE

Essential Options

Practical Examples

Example 1: Basic Partition Mapping

Let’s start with a simple example of mapping partitions from a disk image:

# Create a loop device for a disk image
sudo losetup /dev/loop0 /path/to/disk.img

# List partitions in the image
sudo kpartx -l /dev/loop0

Expected Output:

loop0p1 : 0 2097152 /dev/loop0 2048
loop0p2 : 0 20971520 /dev/loop0 2099200

This output shows two partitions: loop0p1 and loop0p2 with their respective sizes and offsets.

Example 2: Adding Partition Mappings

To create device mappings for the partitions:

# Add partition mappings
sudo kpartx -av /dev/loop0

Expected Output:

add map loop0p1 (253:0): 0 2097152 linear /dev/loop0 2048
add map loop0p2 (253:1): 0 20971520 linear /dev/loop0 2099200

After this command, you’ll find the partition devices in /dev/mapper/:

ls -la /dev/mapper/loop0p*

Output:

lrwxrwxrwx 1 root root 7 Aug 25 10:30 /dev/mapper/loop0p1 -> ../dm-0
lrwxrwxrwx 1 root root 7 Aug 25 10:30 /dev/mapper/loop0p2 -> ../dm-1

Example 3: Working with Disk Images

Here’s a complete workflow for mounting a partition from a disk image:

# Step 1: Set up loop device
sudo losetup -P /dev/loop0 /path/to/disk.img

# Step 2: Create partition mappings
sudo kpartx -av /dev/loop0

# Step 3: Check available partitions
ls /dev/mapper/loop0p*

# Step 4: Mount a specific partition
sudo mkdir /mnt/partition1
sudo mount /dev/mapper/loop0p1 /mnt/partition1

# Step 5: Access the mounted filesystem
ls /mnt/partition1

Example 4: Custom Partition Prefix

You can specify a custom prefix for partition names:

# Use custom prefix 'mydisk'
sudo kpartx -av -p mydisk /dev/loop0

Expected Output:

add map mydisk1 (253:0): 0 2097152 linear /dev/loop0 2048
add map mydisk2 (253:1): 0 20971520 linear /dev/loop0 2099200

Example 5: Removing Partition Mappings

When you’re done working with the partitions, clean up the mappings:

# Unmount any mounted filesystems first
sudo umount /mnt/partition1

# Remove partition mappings
sudo kpartx -dv /dev/loop0

Expected Output:

del devmap : loop0p2
del devmap : loop0p1

Advanced Usage Scenarios

Working with RAID Arrays

The kpartx command is particularly useful when dealing with software RAID arrays that contain partition tables:

# List partitions on a RAID device
sudo kpartx -l /dev/md0

# Add mappings for RAID partitions
sudo kpartx -av /dev/md0

Forensic Analysis

For digital forensics, kpartx allows you to examine disk images without modifying them:

# Mount image read-only
sudo losetup -r /dev/loop0 /evidence/disk.img

# Create read-only partition mappings
sudo kpartx -ar /dev/loop0

# Mount partitions read-only for analysis
sudo mount -o ro /dev/mapper/loop0p1 /mnt/evidence

Troubleshooting Common Issues

Permission Denied Errors

If you encounter permission errors, ensure you’re running commands with proper privileges:

# Check if you have necessary permissions
sudo kpartx -l /dev/loop0

# If still failing, check device ownership
ls -la /dev/loop0

Device Busy Errors

When getting “device busy” errors during removal:

# Check what's using the device
sudo lsof /dev/mapper/loop0p1
sudo fuser -v /dev/mapper/loop0p1

# Kill processes using the device (if safe)
sudo fuser -k /dev/mapper/loop0p1

Missing Partition Mappings

If partition mappings aren’t created, check the partition table:

# Verify partition table exists
sudo fdisk -l /dev/loop0

# Force partition detection
sudo partprobe /dev/loop0
sudo kpartx -av /dev/loop0

Integration with Other Tools

Using with losetup

Modern versions of losetup can automatically create partition devices:

# losetup with -P flag automatically creates partitions
sudo losetup -P /dev/loop0 /path/to/disk.img

# This is equivalent to:
sudo losetup /dev/loop0 /path/to/disk.img
sudo kpartx -av /dev/loop0

Scripting with kpartx

Here’s a bash script example for automated partition handling:

#!/bin/bash

IMAGE_FILE="$1"
MOUNT_BASE="/mnt/partitions"

# Setup loop device
LOOP_DEV=$(sudo losetup -f --show "$IMAGE_FILE")
echo "Created loop device: $LOOP_DEV"

# Create partition mappings
sudo kpartx -av "$LOOP_DEV"

# List available partitions
PARTITIONS=$(ls /dev/mapper/$(basename $LOOP_DEV)p* 2>/dev/null)

for partition in $PARTITIONS; do
    PART_NAME=$(basename $partition)
    MOUNT_POINT="$MOUNT_BASE/$PART_NAME"
    
    sudo mkdir -p "$MOUNT_POINT"
    
    if sudo mount "$partition" "$MOUNT_POINT" 2>/dev/null; then
        echo "Mounted $partition at $MOUNT_POINT"
    else
        echo "Failed to mount $partition"
        sudo rmdir "$MOUNT_POINT"
    fi
done

Security Considerations

When using kpartx, keep these security aspects in mind:

• Root Privileges: Most kpartx operations require root access
• Device Exposure: Mapped partitions become accessible system-wide
• Read-Only Mode: Use read-only mounting for sensitive data examination
• Cleanup: Always remove mappings when done to prevent security leaks

Performance Tips

To optimize kpartx performance:

• Use the -f flag sparingly as it can bypass safety checks
• Clean up unused mappings to free system resources
• Consider using losetup -P for simpler use cases
• Monitor /dev/mapper/ space usage in high-volume environments

Conclusion

The kpartx command is an indispensable tool for Linux system administrators and power users working with complex storage configurations. Its ability to create device mappings from partition tables makes it essential for virtual machine management, disk image analysis, and advanced storage operations.

By mastering kpartx, you gain the ability to work flexibly with partitioned devices and images, whether for routine system administration, forensic analysis, or complex storage management tasks. Remember to always clean up your mappings and follow security best practices when working with sensitive data.

The examples and techniques covered in this guide provide a solid foundation for using kpartx effectively in various scenarios. As you become more comfortable with the command, you’ll discover additional use cases that can streamline your workflow and enhance your system administration capabilities.