table of contents
BMAPTOOL(1) | User Commands | BMAPTOOL(1) |
NAME¶
bmaptool - create block map (bmap) for a file or copy a file using bmap
SYNOPSIS¶
bmaptool [--help] [--version] [--quiet] [--debug] <command> [<options>] <args>
DESCRIPTION¶
bmaptool is a generic tool for creating the block map (bmap) for a file and copying files using the block map. The idea is that large files, like raw system image files, can be copied or flashed a lot faster with bmaptool than with traditional tools, like "dd" or "cp".
bmaptool supports 2 commands:
Please, find full documentation for the project online.
OPTIONS¶
--version
-h, --help
-q, --quiet
-d, --debug
COMMANDS¶
copy [options] IMAGE DEST¶
Unless the bmap file is explicitly specified with the "--bmap" option, bmaptool automatically discovers it by looking for a file with the same basename as IMAGE but with the ".bmap" extension. 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:
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 basename as the bmap file but with the ".asc" or ".sig" extension. 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.
--bmap BMAP
--bmap-sig SIG
--nobmap
--no-sig-verify
--no-verify
--psplash-pipe PATH
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.
The image file can further be signed using OpenPGP.
-o, --output OUTPUT
--no-checksum
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
March 2024 | bmaptool 3.8.0 |