1BMAPTOOL(1) User Commands BMAPTOOL(1)
2
6 bmaptool - create block map (bmap) for a file or copy a file using bmap
7
10 bmaptool [--help] [--version] [--quiet] [--debug] <command> [<options>]
11 <args>
12
15 Bmaptool is a generic tool for creating the block map (bmap) for a file
16 and copying files using the block map. The idea is that large files,
17 like raw system image files, can be copied or flashed a lot faster with
18 bmaptool than with traditional tools, like "dd" or "cp".
19 Bmaptool supports 2 commands:
22 1. copy - copy a file to another file using bmap or flash an image to
23 a block device
24 2. create - create a bmap for a file
25 Please, find full documentation for the project online.
28
31 --version
32 Print bmaptool version and exit.
33 -h, --help
36 Print short help text and exit.
37 -q, --quiet
40 Be quiet, do not print extra information.
41 -d, --debug
44 Print debugging messages.
45
48 copy [options] IMAGE DEST
49 Copy file IMAGE to the destination regular file or block device DEST
50 using bmap. IMAGE may either be a local path or an URL. DEST may ei‐
51 ther be a regular file or a block device (only local).
52 Unless the bmap file is explicitly specified with the "--bmap" op‐
55 tion, bmaptool automatically discovers it by looking for a file with
56 the same basename as IMAGE but with the ".bmap" extension. The bmap
57 file is only looked for in IMAGE's directory (or base URL, in case
58 IMAGE was specified as an URL). If the bmap file is not found, bmap‐
59 tool fails. To copy without bmap, use the "--nobmap" option.
60 Both IMAGE and the bmap file may be specified as an URL (http://,
63 ftp://, https://, file://, ssh://). In order to make bmaptool use a
64 proxy server, please, specify the proxy using the standard
65 "$http_proxy", "$https_proxy", "$ftp_proxy" or "$no_proxy" environ‐
66 ment variables.
67 If the server requires authentication, user name and password may be
70 specified in the URL, for example "https://user:pass‐
71 word@my.server.org/image.raw.bz2", or "ssh://user:pass‐
72 word@host:path/to/image.raw".
73 IMAGE may be compressed, in which case bmaptool decompresses it on-
76 the-fly. The compression type is detected by the file extension and
77 the following extensions are supported:
78 1. ".gz", ".gzip", ".tar.gz" and ".tgz" for files and tar ar‐
80 chives compressed with "gzip" program
81 2. ".bz2", "tar.bz2", ".tbz2", ".tbz", and ".tb2" for files and
82 tar archives compressed with "bzip2" program
83 3. ".xz", ".tar.xz", ".txz" for files and tar archives compressed
84 with "xz" program
85 4. ".lzo", "tar.lzo", ".tzo" for files and tar archives com‐
86 pressed with "lzo" program
87 5. ".lz4", "tar.lz4", ".tlz4" for files and tar archives com‐
88 pressed with "lz4" program
89 6. ".zst", "tar.zst", ".tzst" for files and tar archives com‐
90 pressed with "zstd" program
91 IMAGE files with other extensions are assumed to be uncompressed.
94 Note, bmaptool uses "pbzip2" and "pigz" programs for decompressing
95 bzip2 and gzip archives faster, unless they are not available, in
96 which case if falls-back to using "bzip2" and "gzip".
97 If DEST is a block device node (e.g., "/dev/sdg"), bmaptool opens it
100 in exclusive mode. This means that it will fail if any other process
101 has IMAGE block device node opened. This also means that no other
102 processes will be able to open IMAGE until bmaptool finishes the
103 copying. Please, see semantics of the "O_EXCL" flag of the "open()"
104 syscall.
105 The bmap file typically contains SHA-256 checksum for itself as well
108 as SHA-256 checksum for all the mapped data regions, which makes it
109 possible to guarantee data integrity. bmaptool verifies the checksums
110 and exits with an error in case of a mismatch. Checksum verification
111 can be disabled using the "--no-verify" option. bmaptool does not
112 verify that unampped areas contain only zeroes, because these areas
113 are anyway dropped and are not used for anything.
114 The bmap file may be signed with OpenPGP (gpg). The signature may be
117 either detached (a separate file) or "built into" the bmap file (so
118 called "clearsign" signature).
119 The detached signature can be specified with the "--bmap-sig" option,
122 otherwise bmaptool tries to automatically discover it by looking for
123 a file with the same basename as the bmap file but with the ".asc" or
124 ".sig" extension. This is very similar to the bmap file auto-discov‐
125 ery. So if a ".asc" or ".sig" file exists, bmaptool will verify the
126 signature.
127 The clearsign signature is part of the bmap file and bmaptool auto‐
130 matically detected and verifies it.
131 If the signature is bad, bmaptool exits with an error. Bmap file sig‐
134 nature verification can be disabled using the "--no-sig-verify" op‐
135 tion.
136 OPTIONS
138 -h, --help
139 Print short help text about the "copy" command and exit.
140 --bmap BMAP
143 Use bmap file "BMAP" for copying. If this option is not speci‐
144 fied, bmaptool tries to automatically discover the bmap file.
145 --bmap-sig SIG
148 Use a detached OpenPGP signature file "SIG" for verifying the
149 bmap file integrity and publisher. If this option is not speci‐
150 fied, bmaptool tries to automatically discover the signature
151 file.
152 --nobmap
155 Disable automatic bmap file discovery and force flashing entire
156 IMAGE without bmap.
157 --no-sig-verify
160 Do not verify the OpenPGP bmap file signature (not recommended).
161 --no-verify
164 Do not verify data checksums when copying (not recommended). The
165 checksums are stored in the bmap file, and normally bmaptool veri‐
166 fies that the data in IMAGE matches the checksums.
167 --no-sig-verify
170 Write progress to a psplash pipe.
171 EXAMPLES
173 bmaptool copy image.raw.bz2 /dev/sdg
174 Copy bz2-compressed local file "image.raw.bz2" to block device
175 "/dev/sdg". The image file is uncompressed on-the-fly. The bmap
176 file is discovered automatically. The OpenPGP signature is de‐
177 tected/discovered automatically too.
178 bmaptool copy http://my-server.com/files/image.raw.bz2
180 $HOME/tmp/file
181 Copy bz2-compressed remote "image.raw.bz2" to regular file
182 "$HOME/tmp/file". The image file is uncompressed on-the-fly. The
183 bmap file is discovered automatically. The OpenPGP signature is
184 detected/discovered automatically too.
185 bmaptool copy --bmap image.bmap --bmap-sig image.bmap.asc image.raw
187 /dev/sdg
188 Copy non-compressed local file "image.raw" to block device
189 "/dev/sdg" using bmap file "image.bmap". Verify the bmap file
190 signature using a detached OpenPGP signature from
191 "imag.bmap.asc".
192 create [options] IMAGE
195 Generate bmap for a regular file IMAGE. Internally, this command uses
196 the Linux "FIEMAP" ioctl to find out which IMAGE blocks are mapped.
197 However, if "FIEMAP" is not supported, the "SEEK_HOLE" feature of the
198 "lseek" system call is used instead. By default, the resulting bmap
199 file is printed to stdout, unless the "--output" option is used.
200 The IMAGE file is always synchronized before the block map is gener‐
203 ated. And it is important to make sure that the IMAGE file is not modi‐
204 fied when the bmap file is being generated, and after the bmap file has
205 been generated. Otherwise the bmap file becomes invalid and checksum
206 verification will fail.
207 The image file can further be signed using OpenPGP.
210 OPTIONS
212 -h, --help
213 Print short help text about the "create" command and exit.
214 -o, --output OUTPUT
217 Save the generated bmap in the OUTPUT file (by default the bmap
218 is printed to stdout).
219 --no-checksum
222 Generate a bmap file without SHA1 checksums (not recommended).
223 EXAMPLES
225 bmaptool create image.raw
226 Generate bmap for the "image.raw" file and print it to stdout.
227 bmaptool create -o image.bmap image.raw
229 Generate bmap for the "image.raw" file and save it in "im‐
230 age.bmap".
231
234 Artem Bityutskiy <artem.bityutskiy@linux.intel.com>.
235
238 Please, report bugs to Artem Bityutskiy <artem.bityutskiy@linux.in‐
239 tel.com> or to the bmap-tools mailing list <bmap-tools@lists.in‐
240 fradead.org>.
241bmap-tools 3.2 February 2014 BMAPTOOL(1)