table of contents
BMAPTOOL(1) | User Commands | BMAPTOOL(1) |
NAME¶
bmaptool - create block map (bmap) for a file or copy a file using bmapSYNOPSIS¶
bmaptool [--help] [--version] [--quiet] [--debug] <subcommand> [<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 subcommands: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 at
https://source.tizen.org/documentation/reference/bmaptool
OPTIONS¶
--versionPrint 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
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:
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
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".
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.OPTIONS
-h, --help
Print short help text about the "copy"
subcommand 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.
--nobmap
Disable automatic bmap file discovery and force flashing
entire IMAGE without bmap.
--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.
--no-sig-verify
Do not verify the OpenPGP bmap file signature (not
recommended).
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".
create [options] IMAGE¶
Generate bmap for a regular file IMAGE. Internally, this subcommand 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"
subcommand 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>.REPORTING BUGS¶
Please, report bugs to Artem Bityutskiy <artem.bityutskiy@linux.intel.com> or to the bmap-tools mailing list <bmap-tools@lists.infradead.org>.February 2014 | bmap-tools 3.2 |