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:
         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 bmaptool version and exit.

       -h, --help
         Print short help text and exit.

       -q, --quiet
         Be quiet, do not print extra information.

       -d, --debug
         Print debugging messages.

COMMANDS

   copy [options] IMAGE DEST
         Copy 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.

       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

bmaptool 3.9.0                                     March 2025                                        BMAPTOOL(1)