1XORRISO-DD-TARGET(1) General Commands Manual XORRISO-DD-TARGET(1)
2
6 xorriso-dd-target - Device evaluator and disk image copier for
7 GNU/Linux
8
10 xorriso-dd-target [ options ] [ device_names ]
11
13 xorriso-dd-target evaluates block devices of the Linux kernel whether
14 they are suitable targets for a disk image file and optionally copies
15 the image file to one of them.
16 It is specialized on the device names of the Linux kernel and uses the
17 capabilities of util-linux program lsblk. Therefore it refuses to run
18 on non-Linux kernels.
19 The main purpose of xorriso-dd-target is to inspect the device files of
21 disk-like storage media and to judge whether they look like removable
22 devices with disposable content.
23 If a single plausible candidate is detected, then the program is
24 willing to copy a disk image file onto it. This will overwrite or make
25 inaccessible the previous partition table and all previous data content
26 of the target device.
27 Superuser power is often needed for filesystem type identification, for
28 possible unmounting, and for possible image writing. Option -with_sudo
29 offers a way to gain this power only for those tasks and to run the
30 program elsewise with a normal user's power.
31 If a particular disk image file is intended as copy source, then its
32 path should be given by option -image_file, so that its size can be
33 used as decision criterion.
34 Following are use case descriptions with examples:
36 - List plain device names
37 - List all devices with reasoning
38 - Evaluate particular given devices
39 - Detect intended device by plugging
40 - Write image to an advised device
41 - Show commands for writing to a not advised device
42 List plain device names:
44 The most simple and most boring use case is a program run without
45 device names and without options -list_all, -plug_test, -DO_WRITE,
46 -dummy_force. It prints on standard output (stdout) only the names of
47 advisable devices without "/dev/" prefix. One name per line and without
48 any reasoning text.
49 The possible sudo password prompt, the message line about sudo, and the
50 empty line after it do not go to stdout.
51 Example:
52 $ xorriso-dd-target -with_sudo
53 Testing sudo to possibly get password prompting done now:
54 [sudo] password for thomas:
55 sudo /bin/lsblk seems ok.
56 sde
58 List all devices with reasoning:
60 For the more curious user, there is option -list_all which prints the
61 evaluation of each disk-like device that is listed by program lsblk.
62 Optical drives, floppy disks, RAM block devices, loop devices are
63 excluded, though.
64 Each device is shown by one line of the form
65 name : advice : reasoning : info
66 name is the device name without "/dev/" prefix.
67 advice is either "YES" or "NO". "YES" indicates that the device appears
68 to be pluggable disk-like, not used as system disk or sincere data
69 storage, and - if tested - of sufficient or plausible size.
70 reasoning is a blank separated list of words with either suffix '+' for
71 an inviting device property or '-' for a prohibitive property. Normally
72 a single '-' reason disqualifies the device from being advisable. Only
73 if option -look_for_iso is given, a reason "has_XYZ-" can be overridden
74 by the presence of an ISO 9660 filesystem on the device.
75 info is composed from VENDOR and MODEL as told by lsblk.
76 Option -list_long causes with each line an additional listing of the
77 information provided by lsblk which led to the shown reasons.
78 Example:
79 $ xorriso-dd-target -with_sudo -list_all
80 ...
81 sda : NO : not_usb- has_vfat+ has_ext4- : ATA Samsung SSD 850
82 sdb : NO : not_usb- has_swap- has_ext4- : ATA WDC WD20EFRX-68A
83 sdc : YES : usb+ has_iso9660+ has_vfat+ : Intenso Ultra Line
84 sdd : NO : usb+ has_iso9660+ has_vfat+ has_ext2- : SanDisk Cruzer
85 Evaluate particular given devices:
87 If device names are given instead of option -list_all, then only these
88 devices are inspected. Their result gets listed without the ": info"
89 part, unless option -with_vendor_model is given.
90 Device names must not begin by '-' and must be single words composed of
91 the characters [A-za-z0-9_/-]. They should not contain '/'. E.g. 'sdc'
92 is valid, '/dev/sdc' is not valid.
93 If one of the given device names gets not advised, the exit value is 1.
94 It makes few sense to give device names which are not listed by
95 -list_all.
96 Examples:
97 $ xorriso-dd-target -with_sudo sdc
98 ...
99 sdc : YES : usb+ has_iso9660+ has_vfat+
100 $ xorriso-dd-target -with_sudo -with_vendor_model sdc
101 ...
102 sdc : YES : usb+ has_iso9660+ has_vfat+ : Intenso Ultra Line
103 $ xorriso-dd-target sdc
104 sdc : NO : usb+ no_fs_while_not_su-
105 Detect intended device by plugging:
107 Option -plug_test triggers an interactive method to unambiguously
108 determine the intended target device candidate. It consists of 2 or 3
109 steps.
110 Step 1 is to have the intended storage device unplugged and to confirm
111 this by pressing the Enter key at the program's prompt. The program
112 will then assess the list of not wanted devices.
113 Step 2 is to plug in the intended storage device and to confirm this by
114 pressing the Enter key a second time. The program will wait up to 10
115 seconds for a disk-like storage device which is not in the list of not
116 wanted devices. The user may wait with key pressing until the device
117 blinking looks like it is ready.
118 Only if a single new device is found, the program will go on as if a
119 single device name was given. Option -list_all and any device names
120 given as arguments will be ignored.
121 Step 3 happens only if options -DO_WRITE or -dummy_force are given.
122 The program asks for a final input of the word 'yes' before real or
123 simulated writing begins.
124 Example:
125 $ xorriso-dd-target -with_sudo -plug_test
126 ...
127 Caused by option -plug_test: Attempt to find the desired device by
128 watching it appear after being plugged in.
129 Step 1:
130 Please make sure that the desired target device is plugged _out_ now.
131 If it is currently plugged in, make sure to unmount all its fileystems
132 and then unplug it.
133 Press the Enter key when ready.
134 Found and noted as _not_ desired: sda sdb sdc
136 Step 2:
137 Please plug in the desired target device and then press the Enter key.
138 Waiting up to 10 seconds for a new device to be listed ... found: sdd
140 Now waiting 5 seconds to let it settle .........
141 Found and noted as desired device: sdd
142 sdd : NO : usb+ has_iso9660+ has_vfat+ has_ext2- : SanDisk Cruzer
144 Write image to an advised device:
146 Only if option -DO_WRITE is given and -list_all is not, and if exactly
147 one advisable device is listed, it really gets overwritten by the file
148 content of the given -image_file. In this case the exit value is zero
149 if writing succeeded, non-zero else.
150 Option -dummy prevents this kind of real action and rather shows the
151 planned umount and dd commands on stdout.
152 Example:
153 $ xorriso-dd-target -with_sudo -plug_test -DO_WRITE \
154 -image_file debian-live-10.0.0-amd64-xfce.iso
155 ... sudo messages and above plug test steps 1 and 2 ...
156 sde : YES : usb+ has_iso9660+ has_vfat+
158 Step 3:
159 Last chance to abort. Enter the word 'yes' to start REAL WRITING.
160 yes
161 Looking for mount points of sde:
162 /dev/sde1 on /mnt/iso type iso9660 (ro,relatime)
163 /dev/sde2 on /mnt/fat type vfat (rw,...,errors=remount-ro)
164 Unmounted: /dev/sde1
165 Unmounted: /dev/sde2
166 Performing:
167 sudo /bin/dd if=/dev/zero of=/dev/'sde' bs=512 seek='245759999'
168 count=1 status=none
169 sudo /bin/dd if='debian-live-10.0.0-amd64-xfce.iso' of=/dev/'sde'
170 bs=1M status=progress oflag=dsync ; sync
171 ... dd messages ...
172 The first dd run shall erase a possible GPT backup header. It is
173 performed only if the local program "expr" can deal with the byte size
174 of the device.
175 Show commands for writing to a not advised device:
177 There should be no way to convince xorriso-dd-target of writing to a
178 target device which it does not deem advisable. Please report any set
179 of arguments that can be misused for that.
180 The outmost complicity to potentially unwise actions is offered by
181 option -dummy_force. If given together with a single device name or
182 with option -plug_test it will act like -dummy -DO_WRITE with this
183 device, even if it looks not advisable. I.e. it will show the shell
184 commands which the program does not dare to perform.
185 Example:
186 $ xorriso-dd-target -with_sudo -list_long -dummy_force sdd \
187 -image_file debian-live-10.0.0-amd64-xfce.iso
188 ...
189 sdd : NO : usb+ has_iso9660+ has_vfat+ has_ext2-
190 NAME SIZE FSTYPE TRAN LABEL
191 sdd 3.8G iso9660 usb d-live 9.5.0 xf i386
192 |-sdd1 1.9G iso9660 d-live 9.5.0 xf i386
193 |-sdd2 320K vfat
194 `-sdd3 512M ext2
195 Overriding any advice because of -dummy_force
197 Looking for mount points of sdd:
198 /dev/sdd1 on /mnt/iso type iso9660 (ro,relatime)
199 /dev/sdd2 on /mnt/fat type vfat (rw,...,errors=remount-ro)
200 /dev/sdd3 on /mnt/ext type ext2 (rw,relatime)
201 AGAINST THE ADVICE BY THIS PROGRAM, a daring user could do:
202 sudo /bin/umount /dev/sdd1
203 sudo /bin/umount /dev/sdd2
204 sudo /bin/umount /dev/sdd3
205 sudo /bin/dd if=/dev/zero of=/dev/'sdd' bs=512 seek='7864318'
206 count=1 status=none
207 sudo /bin/dd if='debian-live-10.0.0-amd64-xfce.iso' of=/dev/sdd
208 bs=1M status=progress oflag=dsync ; sync
209 BE SMART. BE CAUTIOUS. BEWARE.
210 Alphabetical List of positive and negative reasons:
212 As stated with use case "List all devices", reasons are words with
213 either suffix '+' for an inviting device property or '-' for a
214 prohibitive property.
215 Normally a single '-' reason disqualifies the device from being
216 advisable.
217 has_XYZ-
219 A filesystem of type XYZ is detected on base device or partition and is
220 spoiling the impression of a device with disposable content.
221 has_iso9660+
222 An ISO 9660 filesystem is detected.
223 has_vfat+
224 A FAT (MS-DOS-like) filesystem is detected.
225 look_for_iso++
226 Option -look_for_iso is given and an ISO 9660 filesystem is detected.
227 This reason overrides any "has_XYZ-" reason.
228 looks_like_cd_drive-
229 A given device name looks like the name of an optical drive: sr[0-9]*.
230 Use program xorrecord for this kind of devices.
231 looks_like_disk_partition-
232 A given device name looks like the name of a partition. Expected are
233 names of base devices, like "sde", not of their partitions, like
234 "sde1".
235 looks_like_floppy-
236 A given device name looks like the name of a floppy disk drive:
237 fd[0-9]*.
238 looks_like_loopdev-
239 A given device name looks like the name of a loop device: loop[0-9]*.
240 looks_like_ramdev-
241 A given device name looks like the name of a RAM block device:
242 zram[0-9]*.
243 lsblk_no_size-
244 A size test is given by -max_size, -min_size, or -image_file but the
245 size of the device cannot be inquired by lsblk. This is supposed to
246 happen only with given inappropriate device names.
247 mmcblk+
248 The device name looks like a directly connected memory card.
249 name_with_slash-
250 A given device name contains '/' characters.
251 no_bus_info-
252 The device is not a memory card and lsblk reports nothing about the way
253 how it is connected to the computer.
254 no_fs_while_not_su-
255 No filesystem is reported by lsblk and the program does not believe to
256 have run it with superuser powers. There is the risk that lsblk
257 silently failed to detect existing filesystems.
258 no_iso9660-
259 Option -look_for_iso is given but no ISO 9660 filesystem is detected.
260 not_usb-
261 The device is not a memory card and lsblk reports that it is connected
262 by something other than USB.
263 size_too_large-
264 Option -max_size is given with a size smaller than the size of the
265 device.
266 size_too_small-
267 Option -min_size or -image_file is given with size or file size larger
268 than the size of the device.
269 usb+
270 The device is reported by lsblk to be connected via USB.
271
274 -plug_test
275 Find the target device by asking the user to press the Enter key
276 when the desired target is _not_ plugged in, to then plug it in,
277 and to press Enter again.
278 This overrides device names and option -list_all. The found
279 device is then shown with advice, vendor, and model.
280 Option -DO_WRITE is obeyed if given. In this case, the word
281 'yes' has to be entered to let unmounting and writing begin.
282 -list_all
284 Print list of all found devices with advice, vendor and model.
285 One per line. Ignore any device names. Ignore -DO_WRITE.
286 -list_long
288 After each result line, which shows reasons, add an additional
289 listing of the information provided by lsblk which led to the
290 reasons and add an empty line.
291 -with_vendor_model
293 Print vendor and model with each submitted device name.
294 -max_size n[M|G|T]
296 Set the upper byte size limit for advisable devices. Plain
297 numbers get rounded down to full millions. As suffix are
298 recognized: M = million, G = billion, T = trillion.
299 Be generous to avoid problems with GB < GiB.
300 -min_size n[M|G|T]
302 Set the lower byte size limit for advisable devices. After
303 processing like with -max_size, one million gets added to the
304 size limit.
305 -look_for_iso
307 Demand presence of an ISO 9660 filesystem. If so, then any
308 further filesystem type is acceptable on that device.
309 If this option is missing, only ISO 9660 and VFAT filesystems
310 are accepted.
311 -with_sudo
313 Run 'lsblk -o FSTYPE' by sudo. If no filesystems are detected on
314 a device while the program has no superuser power, then the
315 device is not advised. Option -with_sudo avoids this refusal
316 without the need to run the whole program as superuser.
317 If -DO_WRITE -with_sudo is given, then the programs umount and
318 dd will be run by sudo, too.
319 -trust_lsblk_udev
321 Suppress the reason no_fs_while_not_su- if lsblk is linked with
322 libudev.so. In this case it is likely that lsblk can retrieve
323 FSTYPE even if run by a non-priviledged user.
324 This option is intended for use by frontend programs which are
325 certain that they do not encounter a udev-using version of lsblk
326 which nevertheless fails to detect existing filesystems. Human
327 users should better acquire superuser powers if reason
328 no_fs_while_not_su- is reported.
329 -image_file PATH
331 Set the path of the image file which shall be written to a
332 device. Its size will be set as -min_size.
333 -DO_WRITE
335 Write the given -image_file to the one advisable device that is
336 found. If more than one such device is found, then they get
337 listed but no writing happens.
338 In this case, to get a real write run, consider unplugging
339 unneeded devices, or using option -plug_test, or a re-run with
340 one of the advised device names as additional argument.
341 -no_pacifier
343 Do not use dd options to print progress messages and to perform
344 synchronized output. These options are used by default if
345 program dd offers progress messages.
346 -dummy Report the -DO_WRITE actions but do not perform them.
348 -dummy_force
350 If a single device name is given, do a run of -dummy -DO_WRITE
351 even against the advice of this program. This probably shows you
352 ways to shoot your own foot.
353 -version
355 Print the program name, version text, and timestamp to stdout
356 and then end the program.
357 -help Print the help text to stdout and then end the program.
359
361 Examples are given in the above description of use cases.
362
364 For now, no files are defined for configuration.
365
367 lsblk(8), umount(8), dd(1), xorrecord(1)
368
370 To report bugs, request help, or suggest enhancements for
371 xorriso-dd-target, please send electronic mail to the public list
372 <bug-xorriso@gnu.org>. If more privacy is desired, mail to
373 <scdbackup@gmx.net>.
374 Please describe what you expect the program to do, the program
375 arguments which you used, the messages of xorriso-dd-target, and the
376 undesirable outcome of your program run.
377 Expect to get asked more questions before solutions can be proposed.
378
380 Thomas Schmitt <scdbackup@gmx.net>
381 for libburnia-project.org
382
384 Copyright (c) 2019 - 2021 Thomas Schmitt
385 Permission is granted to distribute this text freely. It shall only be
386 modified in sync with the technical properties of xorriso-dd-target.
387 If you make use of the license to derive modified versions of
388 xorriso-dd-target then you are entitled to modify this text under that
389 same license.
390
392 xorriso-dd-target is developed in cooperation with Nio Wiklund alias
393 sudodus.
394 Version 1.5.4, Jan 30, 2021 XORRISO-DD-TARGET(1)