Debian Codegraph @

docs/man1/bmaptool.1

raw
1 .TH BMAPTOOL "1" "March 2025" "bmaptool 3.9.0" "User Commands"
2
3 .SH NAME
4
5 .PP
6 bmaptool - create block map (bmap) for a file or copy a file using bmap
7
8 .SH SYNOPSIS
9
10 .PP
11 .B bmaptool
12 [\-\-help] [\-\-version] [\-\-quiet] [\-\-debug] <command> [<options>] <args>
13
14 .SH DESCRIPTION
15
16 .PP
17 \fIbmaptool\fR is a generic tool for creating the block map (bmap) for a file and
18 copying files using the block map. The idea is that large files, like raw
19 system image files, can be copied or flashed a lot faster with \fIbmaptool\fR than
20 with traditional tools, like "dd" or "cp".
21
22 .PP
23 \fIbmaptool\fR supports 2 commands:
24 .RS 2
25 1. \fBcopy\fR - copy a file to another file using bmap or flash an image to a block device
26 .RE
27 .RS 2
28 2. \fBcreate\fR - create a bmap for a file
29 .RE
30
31 .PP
32 Please, find full documentation for the project online.
33
34 .\" ===========================================================================
35 .\" Global options
36 .\" ===========================================================================
37 .SH OPTIONS
38
39 .PP
40 \-\-version
41 .RS 2
42 Print \fIbmaptool\fR version and exit.
43 .RE
44
45 .PP
46 \-h, \-\-help
47 .RS 2
48 Print short help text and exit.
49 .RE
50
51 .PP
52 \-q, \-\-quiet
53 .RS 2
54 Be quiet, do not print extra information.
55 .RE
56
57 .PP
58 \-d, \-\-debug
59 .RS 2
60 Print debugging messages.
61 .RE
62
63 .\" ===========================================================================
64 .\" Commands descriptions
65 .\" ===========================================================================
66 .SH COMMANDS
67
68 .\"
69 .\" The "copy" command description
70 .\"
71 .SS \fBcopy\fR [options] IMAGE DEST
72
73 .RS 2
74 Copy file IMAGE to the destination regular file or block device DEST
75 using bmap. IMAGE may either be a local path or an URL. DEST may either
76 be a regular file or a block device (only local).
77
78 .PP
79 Unless the bmap file is explicitly specified with the "--bmap" option, \fIbmaptool\fR
80 automatically discovers it by looking for a file with the same name as IMAGE
81 but with the ".bmap" extension. If it was unable to find it that way, it will
82 try filenames with each extension of IMAGE removed and ".bmap" added to it. So
83 if your IMAGE is named \fIdisk.img.gz\fR, it will first try
84 \fIdisk.img.gz.bmap\fR, then \fIdisk.img.bmap\fR and finally \fIdisk.bmap\fR.
85 The bmap file is only looked for in
86 IMAGE's directory (or base URL, in case IMAGE was specified as an URL). If the
87 bmap file is not found, \fIbmaptool\fR fails. To copy without bmap, use
88 the "--nobmap" option.
89
90 .PP
91 Both IMAGE and the bmap file may be specified as an URL (http://, ftp://,
92 https://, file://, ssh://). In order to make \fIbmaptool\fR use a proxy server,
93 please, specify the proxy using the standard "$http_proxy", "$https_proxy",
94 "$ftp_proxy" or "$no_proxy" environment variables.
95
96 .PP
97 If the server requires authentication, user name and password may be specified
98 in the URL, for example "https://user:[email protected]/image.raw.bz2", or
99 "ssh://user:password@host:path/to/image.raw".
100
101 .PP
102 IMAGE may be compressed, in which case \fIbmaptool\fR decompresses it on-the-fly.
103 The compression type is detected by the file extension and the following
104 extensions are supported:
105
106 .RS 4
107 1. ".gz", ".gzip", ".tar.gz" and ".tgz" for files and tar archives compressed with "\fIgzip\fR" program
108 .RE
109 .RS 4
110 2. ".bz2", "tar.bz2", ".tbz2", ".tbz", and ".tb2" for files and tar archives compressed with "\fIbzip2\fR" program
111 .RE
112 .RS 4
113 3. ".xz", ".tar.xz", ".txz" for files and tar archives compressed with "\fIxz\fR" program
114 .RE
115 .RS 4
116 4. ".lzo", "tar.lzo", ".tzo" for files and tar archives compressed with "\fIlzo\fR" program
117 .RE
118 .RS 4
119 5. ".lz4", "tar.lz4", ".tlz4" for files and tar archives compressed with "\fIlz4\fR" program
120 .RE
121 .RS 4
122 6. ".zst", "tar.zst", ".tzst" for files and tar archives compressed with "\fIzstd\fR" program
123 .RE
124
125 .PP
126 IMAGE files with other extensions are assumed to be uncompressed. Note,
127 \fIbmaptool\fR uses "\fIpbzip2\fR" and "\fIpigz\fR" programs for decompressing
128 bzip2 and gzip archives faster, unless they are not available, in which case if
129 falls-back to using "\fIbzip2\fR" and "\fIgzip\fR". Furthermore, uncompressed
130 IMAGE files can be piped to the standard input using "-".
131
132 .PP
133 If DEST is a block device node (e.g., "/dev/sdg"), \fIbmaptool\fR opens it in
134 exclusive mode. This means that it will fail if any other process has IMAGE
135 block device node opened. This also means that no other processes will be able
136 to open IMAGE until \fIbmaptool\fR finishes the copying. Please, see semantics
137 of the "O_EXCL" flag of the "open()" syscall.
138
139 .PP
140 The bmap file typically contains SHA-256 checksum for itself as well as SHA-256
141 checksum for all the mapped data regions, which makes it possible to guarantee
142 data integrity. \fIbmaptool\fR verifies the checksums and exits with an error
143 in case of a mismatch. Checksum verification can be disabled using the
144 "--no-verify" option. \fIbmaptool\fR does not verify that unampped areas
145 contain only zeroes, because these areas are anyway dropped and are not used for
146 anything.
147
148 .PP
149 The bmap file may be signed with OpenPGP (gpg). The signature may be either
150 detached (a separate file) or "built into" the bmap file (so called "clearsign"
151 signature).
152
153 .PP
154 The detached signature can be specified with the "--bmap-sig" option, otherwise
155 \fIbmaptool\fR tries to automatically discover it by looking for a file with
156 the same name as the bmap file but with the ".asc" or ".sig" extension.
157 If it was unable to find it that way, it will try filenames with each extension
158 of IMAGE removed and ".asc" or ".sig" added to it.
159 This is very similar to the bmap file auto-discovery. So if a ".asc" or ".sig"
160 file exists, \fIbmaptool\fR will verify the signature.
161
162 .PP
163 The clearsign signature is part of the bmap file and \fIbmaptool\fR
164 automatically detected and verifies it.
165
166 .PP
167 If the signature is bad, \fIbmaptool\fR exits with an error. Bmap file
168 signature verification can be disabled using the "--no-sig-verify" option.
169 .RE
170
171 .\"
172 .\" The "copy" command's options
173 .\"
174 .RS 2
175 \fBOPTIONS\fR
176 .RS 2
177 \-h, \-\-help
178 .RS 2
179 Print short help text about the "copy" command and exit.
180 .RE
181
182 .PP
183 \-\-bmap BMAP
184 .RS 2
185 Use bmap file "BMAP" for copying. If this option is not specified, \fIbmaptool\fR
186 tries to automatically discover the bmap file.
187 .RE
188
189 .PP
190 \-\-bmap-sig SIG
191 .RS 2
192 Use a detached OpenPGP signature file "SIG" for verifying the bmap file
193 integrity and publisher. If this option is not specified, \fIbmaptool\fR
194 tries to automatically discover the signature file.
195 .RE
196
197 .PP
198 \-\-fingerprint FINGERPRINT
199 .RS 2
200 The GPG fingerprint which you expect to have signed the bmap file.
201 .RE
202
203 .PP
204 \-\-keyring KEYRING
205 .RS 2
206 Path to the GPG keyring that will be used when verifying GPG signatures.
207 .RE
208
209 .PP
210 \-\-nobmap
211 .RS 2
212 Disable automatic bmap file discovery and force flashing entire IMAGE without bmap.
213 .RE
214
215 .PP
216 \-\-no-sig-verify
217 .RS 2
218 Do not verify the OpenPGP bmap file signature (not recommended).
219 .RE
220
221 .PP
222 \-\-no-verify
223 .RS 2
224 Do not verify data checksums when copying (not recommended). The checksums are
225 stored in the bmap file, and normally \fIbmaptool\fR verifies that the data in
226 IMAGE matches the checksums.
227 .RE
228
229 .PP
230 \-\-psplash\-pipe PATH
231 .RS 2
232 Write periodic machine-readable progress reports to a fifo in the format
233 used by \fBpsplash\fR. Each progress report consists of "PROGRESS" followed
234 by a space, an integer percentage and a newline.
235 .RE
236
237 .PP
238 \-\-removable\-device
239 .RS 2
240 Copy to destination only if it is a removable block device. This option is
241 recommended when writing on SD Card or USB key to avoid involuntary
242 destructive operations on non-removable disks. The copy command fails when the
243 destination file does not exist, is not a block device or is not removable.
244 .RE
245
246 .RE
247 .RE
248
249 .\"
250 .\" The "copy" command's examples
251 .\"
252 .RS 2
253 \fBEXAMPLES\fR
254 .RS 2
255 \fIbmaptool\fR copy image.raw.bz2 /dev/sdg
256 .RS 2
257 Copy bz2-compressed local file "image.raw.bz2" to block device "/dev/sdg". The
258 image file is uncompressed on-the-fly. The bmap file is discovered
259 automatically. The OpenPGP signature is detected/discovered automatically
260 too.
261 .RE
262 .RE
263
264 .RS 2
265 \fIbmaptool\fR copy http://my-server.com/files/image.raw.bz2 $HOME/tmp/file
266 .RS 2
267 Copy bz2-compressed remote "image.raw.bz2" to regular file "$HOME/tmp/file".
268 The image file is uncompressed on-the-fly. The bmap file is discovered
269 automatically. The OpenPGP signature is detected/discovered automatically
270 too.
271 .RE
272 .RE
273
274 .RS 2
275 \fIbmaptool\fR copy --bmap image.bmap --bmap-sig image.bmap.asc image.raw /dev/sdg
276 .RS 2
277 Copy non-compressed local file "image.raw" to block device "/dev/sdg" using bmap file
278 "image.bmap". Verify the bmap file signature using a detached OpenPGP signature
279 from "imag.bmap.asc".
280 .RE
281 .RE
282
283 .RS 2
284 cat image.raw | \fIbmaptool\fR copy --bmap image.bmap - /dev/sdg
285 .RS 2
286 Copy non-compressed image from standard input to block device "/dev/sdg" using bmap file
287 "image.bmap".
288 .RE
289 .RE
290
291 .\"
292 .\" The "create" command description
293 .\"
294 .SS \fBcreate\fR [options] IMAGE
295
296 .PP
297 Generate bmap for a regular file IMAGE. Internally, this command uses the
298 Linux "FIEMAP" ioctl to find out which IMAGE blocks are mapped. However, if
299 "FIEMAP" is not supported, the "SEEK_HOLE" feature of the "lseek" system call
300 is used instead. By default, the resulting bmap file is printed to stdout,
301 unless the "--output" option is used.
302
303 .PP
304 The IMAGE file is always synchronized before the block map is generated. And it
305 is important to make sure that the IMAGE file is not modified when the bmap
306 file is being generated, and after the bmap file has been generated. Otherwise
307 the bmap file becomes invalid and checksum verification will fail.
308
309 .PP
310 The image file can further be signed using OpenPGP.
311
312 .\"
313 .\" The "create" command's options
314 .\"
315 .RS 2
316 \fBOPTIONS\fR
317 .RS 2
318 \-h, \-\-help
319 .RS 2
320 Print short help text about the "create" command and exit.
321 .RE
322
323 .PP
324 \-o, \-\-output OUTPUT
325 .RS 2
326 Save the generated bmap in the OUTPUT file (by default the bmap is printed to
327 stdout).
328 .RE
329
330 .PP
331 \-\-no-checksum
332 .RS 2
333 Generate a bmap file without SHA1 checksums (not recommended).
334 .RE
335 .RE
336 .RE
337
338 .\"
339 .\" The "create" command's examples
340 .\"
341 .RS 2
342 \fBEXAMPLES\fR
343 .RS 2
344 \fIbmaptool\fR create image.raw
345 .RS 2
346 Generate bmap for the "image.raw" file and print it to stdout.
347 .RE
348 .RE
349
350 .RS 2
351 \fIbmaptool\fR create -o image.bmap image.raw
352 .RS 2
353 Generate bmap for the "image.raw" file and save it in "image.bmap".
354 .RE
355 .RE
356
357 .SH AUTHOR
358
359 Artem Bityutskiy <[email protected]>.
360
361 .SH Maintainers
362
363 Trevor Woerner <[email protected]>
364 Joshua Watt <[email protected]>
365 Tim Orling <[email protected]>
366
367 .SH REPORTING BUGS
368
369 This project is hosted on github; please use it to report any issues or
370 post any patches: https://github.com/yoctoproject/bmaptool