BMAPTOOL(1)

🎀 NAME 🎀

bmaptool — bestie, it makes a block map (bmap) for a file, or it copies a file using a bmap. That's it, that's the whole job, and it does it beautifully. ✨

---

🦋 SYNOPSIS 🦋

bmaptool [--help] [--version] [--quiet] [--debug] <command> [<options>] <args>

---

💖 DESCRIPTION 💖

okay so bmaptool is a generic tool with two whole moods: it can create the block map (bmap) for a file, and it can copy files using that block map. the ✨vision✨ is that big files — think raw system image files, the chunky ones — can be copied or flashed so much faster with bmaptool than with the old-school tools like dd or cp. like, no contest, it's giving speed. 🏎️💨

bmaptool supports 2 commands:

1. copy — copy a file to another file using bmap, or flash an image to a block device
2. create — create a bmap for a file

please, find full documentation for the project online. 👑

---

✨ OPTIONS ✨

• --version — print the bmaptool version and dip. bye! 💅
• -h, --help — print the short help text and exit.
• -q, --quiet — be quiet, do not print extra information. (the introvert option 🫶)
• -d, --debug — print debugging messages. for when you need to see everything. 🔍

---

👑 COMMANDS 👑

💫 copy [options] IMAGE DEST 💫

copy the file IMAGE to the destination regular file or block device DEST, using bmap. IMAGE may either be a local path or an URL. DEST may either be a regular file or a block device (only local).

unless the bmap file is explicitly specified with the --bmap option, bmaptool automatically discovers it by looking for a file with the same name as IMAGE but with the .bmap extension. if it was unable to find it that way, it will try filenames with each extension of IMAGE removed and .bmap added to it. so if your IMAGE is named disk.img.gz, it will first try disk.img.gz.bmap, then disk.img.bmap and finally disk.bmap. the bmap file is only looked for in IMAGE's directory (or base URL, in case IMAGE was specified as an URL). if the bmap file is not found, bmaptool fails. to copy without bmap, use the --nobmap option.

both IMAGE and the bmap file may be specified as an URL (http://, ftp://, https://, file://, ssh://). in order to make bmaptool use a proxy server, please, specify the proxy using the standard $http_proxy, $https_proxy, $ftp_proxy or $no_proxy environment variables.

if the server requires authentication, user name and password may be specified in the URL, for example https://user:password@my.server.org/image.raw.bz2, or ssh://user:password@host:path/to/image.raw.

IMAGE may be compressed, in which case bmaptool decompresses it on-the-fly. 🪄 the compression type is detected by the file extension and the following extensions are supported:

1. .gz, .gzip, .tar.gz and .tgz for files and tar archives compressed with gzip program
2. .bz2, tar.bz2, .tbz2, .tbz, and .tb2 for files and tar archives compressed with bzip2 program
3. .xz, .tar.xz, .txz for files and tar archives compressed with xz program
4. .lzo, tar.lzo, .tzo for files and tar archives compressed with lzo program
5. .lz4, tar.lz4, .tlz4 for files and tar archives compressed with lz4 program
6. .zst, tar.zst, .tzst for files and tar archives compressed with zstd program

IMAGE files with other extensions are assumed to be uncompressed. note, bmaptool uses pbzip2 and pigz programs for decompressing bzip2 and gzip archives faster, unless they are not available, in which case if falls-back to using bzip2 and gzip. furthermore, uncompressed IMAGE files can be piped to the standard input using -.

if DEST is a block device node (e.g., /dev/sdg), bmaptool opens it in exclusive mode. this means that it will fail if any other process has IMAGE block device node opened. this also means that no other processes will be able to open IMAGE until bmaptool finishes the copying. please, see semantics of the O_EXCL flag of the open() syscall.

the bmap file typically contains SHA-256 checksum for itself as well as SHA-256 checksum for all the mapped data regions, which makes it possible to guarantee data integrity. bmaptool verifies the checksums and exits with an error in case of a mismatch. checksum verification can be disabled using the --no-verify option. bmaptool does not verify that unampped areas contain only zeroes, because these areas are anyway dropped and are not used for anything.

the bmap file may be signed with OpenPGP (gpg). the signature may be either detached (a separate file) or "built into" the bmap file (so called "clearsign" signature).

the detached signature can be specified with the --bmap-sig option, otherwise bmaptool tries to automatically discover it by looking for a file with the same name as the bmap file but with the .asc or .sig extension. if it was unable to find it that way, it will try filenames with each extension of IMAGE removed and .asc or .sig added to it. this is very similar to the bmap file auto-discovery. so if a .asc or .sig file exists, bmaptool will verify the signature.

the clearsign signature is part of the bmap file and bmaptool automatically detected and verifies it.

if the signature is bad, bmaptool exits with an error. bmap file signature verification can be disabled using the --no-sig-verify option.

🌸 OPTIONS 🌸

• -h, --help — print short help text about the copy command and exit.
• --bmap BMAP — use bmap file BMAP for copying. if this option is not specified, bmaptool tries to automatically discover the bmap file.
• --bmap-sig SIG — use a detached OpenPGP signature file SIG for verifying the bmap file integrity and publisher. if this option is not specified, bmaptool tries to automatically discover the signature file.
• --fingerprint FINGERPRINT — the GPG fingerprint which you expect to have signed the bmap file.
• --keyring KEYRING — path to the GPG keyring that will be used when verifying GPG signatures.
• --nobmap — disable automatic bmap file discovery and force flashing entire IMAGE without bmap.
• --no-sig-verify — do not verify the OpenPGP bmap file signature (not recommended). 🚩
• --no-verify — do not verify data checksums when copying (not recommended). the checksums are stored in the bmap file, and normally bmaptool verifies that the data in IMAGE matches the checksums. 🚩
• --psplash-pipe PATH — write periodic machine-readable progress reports to a fifo in the format used by psplash. each progress report consists of PROGRESS followed by a space, an integer percentage and a newline.
• --removable-device — copy to destination only if it is a removable block device. this option is recommended when writing on SD Card or USB key to avoid involuntary destructive operations on non-removable disks. the copy command fails when the destination file does not exist, is not a block device or is not removable.

🎀 EXAMPLES 🎀

bmaptool copy image.raw.bz2 /dev/sdg

copy bz2-compressed local file image.raw.bz2 to block device /dev/sdg. the image file is uncompressed on-the-fly. the bmap file is discovered automatically. the OpenPGP signature is detected/discovered automatically too. ✨

bmaptool copy http://my-server.com/files/image.raw.bz2 $HOME/tmp/file

copy bz2-compressed remote image.raw.bz2 to regular file $HOME/tmp/file. the image file is uncompressed on-the-fly. the bmap file is discovered automatically. the OpenPGP signature is detected/discovered automatically too.

bmaptool copy --bmap image.bmap --bmap-sig image.bmap.asc image.raw /dev/sdg

copy non-compressed local file image.raw to block device /dev/sdg using bmap file image.bmap. verify the bmap file signature using a detached OpenPGP signature from imag.bmap.asc.

cat image.raw | bmaptool copy --bmap image.bmap - /dev/sdg

copy non-compressed image from standard input to block device /dev/sdg using bmap file image.bmap. 🫶

---

💜 create [options] IMAGE 💜

generate bmap for a regular file IMAGE. internally, this command uses the Linux FIEMAP ioctl to find out which IMAGE blocks are mapped. however, if FIEMAP is not supported, the SEEK_HOLE feature of the lseek system call is used instead. by default, the resulting bmap file is printed to stdout, unless the --output option is used.

the IMAGE file is always synchronized before the block map is generated. and it is important to make sure that the IMAGE file is not modified when the bmap file is being generated, and after the bmap file has been generated. otherwise the bmap file becomes invalid and checksum verification will fail. 😭

okay this one matters bestie: do not touch the IMAGE file while the bmap is being generated, and do not touch it after either. if you do, the bmap file becomes invalid and checksum verification will fail. periodt. 💀

the image file can further be signed using OpenPGP.

🌈 OPTIONS 🌈

• -h, --help — print short help text about the create command and exit.
• -o, --output OUTPUT — save the generated bmap in the OUTPUT file (by default the bmap is printed to stdout).
• --no-checksum — generate a bmap file without SHA1 checksums (not recommended). 🚩

🍓 EXAMPLES 🍓

bmaptool create image.raw

generate bmap for the image.raw file and print it to stdout.

bmaptool create -o image.bmap image.raw

generate bmap for the image.raw file and save it in image.bmap.

---

🧚 AUTHOR 🧚

Artem Bityutskiy <artem.bityutskiy@linux.intel.com>.

Maintainers

Trevor Woerner <twoerner@gmail.com> Joshua Watt <JPEWhacker@gmail.com> Tim Orling <ticotimo@gmail.com>

---

🔥 REPORTING BUGS 🔥

this project is hosted on github; please use it to report any issues or post any patches: https://github.com/yoctoproject/bmaptool

---

and that's the whole page, bestie 🫶 this was bmaptool version 3.9.0, from March 2025, living its best life in section 1, User Commands. go flash something responsibly. 💅✨🎀