550 lines
17 KiB
Groff
550 lines
17 KiB
Groff
.\" Hey, EMACS: -*- nroff -*-
|
|
.\"
|
|
.\" IMPORTANT NOTE:
|
|
.\"
|
|
.\" The original of this file is kept in xorriso/xorriso-dd-target.texi
|
|
.\" This here was generated by program xorriso/make_xorriso_1
|
|
.\"
|
|
.\"
|
|
.\" First parameter, NAME, should be all caps
|
|
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
|
|
.\" other parameters are allowed: see man(7), man(1)
|
|
.TH XORRISO-DD-TARGET 1 "Version 1.5.3, Jan 6, 2020"
|
|
.\" Please adjust this date whenever revising the manpage.
|
|
.\"
|
|
.\" Some roff macros, for reference:
|
|
.\" .nh disable hyphenation
|
|
.\" .hy enable hyphenation
|
|
.\" .ad l left justify
|
|
.\" .ad b justify to both left and right margins
|
|
.\" .nf disable filling
|
|
.\" .fi enable filling
|
|
.\" .br insert line break
|
|
.\" .sp <n> insert n+1 empty lines
|
|
.\" for manpage-specific macros, see man(7)
|
|
.nh
|
|
.SH NAME
|
|
xorriso\-dd\-target \- Device evaluator and disk image copier for GNU/Linux
|
|
.SH SYNOPSIS
|
|
.B xorriso-dd-target
|
|
[ options ] [ device_names ]
|
|
.br
|
|
.SH DESCRIPTION
|
|
.PP
|
|
\fBxorriso\-dd\-target\fR
|
|
evaluates block devices of the Linux kernel whether they are suitable targets
|
|
for a disk image file and optionally copies the image file to one of them.
|
|
.br
|
|
It is specialized on the device names of the \fBLinux kernel\fR and uses the
|
|
capabilities of util\-linux program \fBlsblk\fR.
|
|
Therefore it refuses to run on non\-Linux kernels.
|
|
.br
|
|
.PP
|
|
The main purpose of xorriso\-dd\-target is to inspect the device files
|
|
of disk\-like storage media and to judge whether they look like removable
|
|
devices with disposable content.
|
|
.br
|
|
If a single plausible candidate is detected, then the program is willing to
|
|
copy a disk image file onto it. This will overwrite or make inaccessible the
|
|
previous partition table and all previous data content of the target device.
|
|
.br
|
|
\fBSuperuser power\fR is normally needed for filesystem type identification,
|
|
for possible unmounting, and for possible image writing.
|
|
Option \fB\-with_sudo\fR offers a way to gain this power only for those
|
|
tasks and to run the program elsewise with a normal user's power.
|
|
.br
|
|
If a particular disk image file is intended as copy source, then
|
|
its path should be given by option \-image_file, so that its size can be used
|
|
as decision criterion.
|
|
.PP
|
|
Following are use case descriptions with examples:
|
|
.br
|
|
- List plain device names
|
|
.br
|
|
- List all devices with reasoning
|
|
.br
|
|
- Evaluate particular given devices
|
|
.br
|
|
- Detect intended device by plugging
|
|
.br
|
|
- Write image to an advised device
|
|
.br
|
|
- Show commands for writing to a not advised device
|
|
.br
|
|
.SS
|
|
\fBList plain device names:\fR
|
|
.br
|
|
The most simple and most boring use case is a program run without device names
|
|
and without options \-list_all, \-plug_test, \-DO_WRITE, \-dummy_force.
|
|
It prints on standard output (stdout) only the names of advisable devices
|
|
without "/dev/" prefix. One name per line and without any reasoning text.
|
|
.br
|
|
The possible sudo password prompt, the message line about sudo, and the
|
|
empty line after it do not go to stdout.
|
|
.br
|
|
Example:
|
|
.br
|
|
$ xorriso\-dd\-target \-with_sudo
|
|
.br
|
|
Testing sudo to possibly get password prompting done now:
|
|
.br
|
|
[sudo] password for thomas:
|
|
.br
|
|
sudo /bin/lsblk seems ok.
|
|
|
|
sde
|
|
.SS
|
|
\fBList all devices with reasoning:\fR
|
|
.br
|
|
For the more curious user, there is option \fB\-list_all\fR which prints
|
|
the evaluation of each disk\-like device that is listed by program lsblk.
|
|
Optical drives, floppy disks, RAM block devices, loop devices are excluded,
|
|
though.
|
|
.br
|
|
Each device is shown by one line of the form
|
|
.br
|
|
name : advice : reasoning : info
|
|
.br
|
|
\fBname\fR is the device name without "/dev/" prefix.
|
|
.br
|
|
\fBadvice\fR is either "YES" or "NO". "YES" indicates that the device
|
|
appears to be pluggable disk\-like, not used as system disk or sincere data
|
|
storage, and \- if tested \- of sufficient or plausible size.
|
|
.br
|
|
\fBreasoning\fR is a blank separated list of words with either suffix '+'
|
|
for an inviting device property or '\-' for a prohibitive property. Normally
|
|
a single '\-' reason disqualifies the device from being advisable. Only if
|
|
option \-look_for_iso is given, a reason "has_XYZ\-" can be overridden by
|
|
the presence of an ISO 9660 filesystem on the device.
|
|
.br
|
|
\fBinfo\fR is composed from VENDOR and MODEL as told by lsblk.
|
|
.br
|
|
Option \fB\-list_long\fR causes with each line an additional listing of
|
|
the information provided by lsblk which led to the shown reasons.
|
|
.br
|
|
Example:
|
|
.br
|
|
$ xorriso\-dd\-target \-with_sudo \-list_all
|
|
.br
|
|
...
|
|
.br
|
|
sda : NO : not_usb\- has_vfat+ has_ext4\- : ATA Samsung SSD 850
|
|
.br
|
|
sdb : NO : not_usb\- has_swap\- has_ext4\- : ATA WDC WD20EFRX\-68A
|
|
.br
|
|
sdc : YES : usb+ has_iso9660+ has_vfat+ : Intenso Ultra Line
|
|
.br
|
|
sdd : NO : usb+ has_iso9660+ has_vfat+ has_ext2\- : SanDisk Cruzer
|
|
.SS
|
|
\fBEvaluate particular given devices:\fR
|
|
.br
|
|
If \fBdevice names\fR are given instead of option \-list_all, then only
|
|
these devices are inspected. Their result gets listed without the ": info"
|
|
part, unless option \fB\-with_vendor_model\fR is given.
|
|
.br
|
|
Device names must not begin by '\-' and must be single words composed of
|
|
the characters [A\-za\-z0\-9_/\-]. They should not contain '/'. E.g. 'sdc' is
|
|
valid, '/dev/sdc' is not valid.
|
|
.br
|
|
If one of the given device names gets not advised, the exit value is 1.
|
|
.br
|
|
It makes few sense to give device names which are not listed by \-list_all.
|
|
.br
|
|
Examples:
|
|
.br
|
|
$ xorriso\-dd\-target \-with_sudo sdc
|
|
.br
|
|
...
|
|
.br
|
|
sdc : YES : usb+ has_iso9660+ has_vfat+
|
|
.br
|
|
$ xorriso\-dd\-target \-with_sudo \-with_vendor_model sdc
|
|
.br
|
|
...
|
|
.br
|
|
sdc : YES : usb+ has_iso9660+ has_vfat+ : Intenso Ultra Line
|
|
.br
|
|
$ xorriso\-dd\-target sdc
|
|
.br
|
|
sdc : NO : usb+ no_fs_while_not_su\-
|
|
.SS
|
|
\fBDetect intended device by plugging:\fR
|
|
.br
|
|
Option \fB\-plug_test\fR triggers an interactive method to unambiguously
|
|
determine the intended target device candidate. It consists of 2 or 3 steps.
|
|
.br
|
|
\fBStep 1\fR is to have the intended storage device unplugged and
|
|
to confirm this by pressing the Enter key at the program's prompt. The program
|
|
will then assess the list of not wanted devices.
|
|
.br
|
|
\fBStep 2\fR is to plug in the intended storage device and to confirm this
|
|
by pressing the Enter key a second time. The program will wait up to 10 seconds
|
|
for a disk\-like storage device which is not in the list of not wanted devices.
|
|
The user may wait with key pressing until the device blinking looks like it
|
|
is ready.
|
|
.br
|
|
Only if a single new device is found, the program will go on as if a single
|
|
device name was given. Option \-list_all and any device names given as arguments
|
|
will be ignored.
|
|
.br
|
|
\fBStep 3\fR happens only if options \-DO_WRITE or \-dummy_force are given.
|
|
The program asks for a final input of the word 'yes' before real or simulated
|
|
writing begins.
|
|
.br
|
|
Example:
|
|
.br
|
|
$ xorriso\-dd\-target \-with_sudo \-plug_test
|
|
.br
|
|
...
|
|
.br
|
|
Caused by option \-plug_test: Attempt to find the desired device
|
|
by watching it appear after being plugged in.
|
|
.br
|
|
Step 1:
|
|
.br
|
|
Please make sure that the desired target device is plugged _out_ now.
|
|
.br
|
|
If it is currently plugged in, make sure to unmount all its fileystems
|
|
.br
|
|
and then unplug it.
|
|
.br
|
|
Press the Enter key when ready.
|
|
.br
|
|
|
|
.br
|
|
Found and noted as _not_ desired: sda sdb sdc
|
|
.br
|
|
Step 2:
|
|
.br
|
|
Please plug in the desired target device and then press the Enter key.
|
|
.br
|
|
|
|
.br
|
|
Waiting up to 10 seconds for a new device to be listed ... found: sdd
|
|
.br
|
|
Now waiting 5 seconds to let it settle .........
|
|
.br
|
|
Found and noted as desired device: sdd
|
|
.br
|
|
|
|
.br
|
|
sdd : NO : usb+ has_iso9660+ has_vfat+ has_ext2\- : SanDisk Cruzer
|
|
.SS
|
|
\fBWrite image to an advised device:\fR
|
|
.br
|
|
Only if option \fB\-DO_WRITE\fR is given and \-list_all is not, and if exactly
|
|
one advisable device is listed, it really gets overwritten by the file content
|
|
of the given \-image_file. In this case the exit value is zero if writing
|
|
succeeded, non\-zero else.
|
|
.br
|
|
Option \fB\-dummy\fR prevents this kind of real action and rather shows the
|
|
planned umount and dd commands on stdout.
|
|
.br
|
|
Example:
|
|
.br
|
|
$ xorriso\-dd\-target \-with_sudo \-plug_test \-DO_WRITE \\
|
|
.br
|
|
\-image_file debian\-live\-10.0.0\-amd64\-xfce.iso
|
|
.br
|
|
... sudo messages and above plug test steps 1 and 2 ...
|
|
.br
|
|
|
|
.br
|
|
sde : YES : usb+ has_iso9660+ has_vfat+
|
|
.br
|
|
Step 3:
|
|
.br
|
|
Last chance to abort. Enter the word 'yes' to start REAL WRITING.
|
|
.br
|
|
yes
|
|
.br
|
|
Looking for mount points of sde:
|
|
.br
|
|
/dev/sde1 on /mnt/iso type iso9660 (ro,relatime)
|
|
.br
|
|
/dev/sde2 on /mnt/fat type vfat (rw,...,errors=remount\-ro)
|
|
.br
|
|
Unmounted: /dev/sde1
|
|
.br
|
|
Unmounted: /dev/sde2
|
|
.br
|
|
Performing:
|
|
.br
|
|
sudo /bin/dd if='debian\-live\-10.0.0\-amd64\-xfce.iso' of=/dev/sde bs=1M status=progress oflag=dsync ; sync
|
|
.br
|
|
... dd messages ...
|
|
.SS
|
|
\fBShow commands for writing to a not advised device:\fR
|
|
.br
|
|
There should be no way to convince xorriso\-dd\-target of writing to a target
|
|
device which it does not deem advisable. Please report any set of arguments
|
|
that can be misused for that.
|
|
.br
|
|
The outmost complicity to potentially unwise actions is offered by
|
|
option \fB\-dummy_force\fR. If given together with a single device name or
|
|
with option \-plug_test it will act like \-dummy \-DO_WRITE with this device,
|
|
even if it looks not advisable. I.e. it will show the shell commands which the
|
|
program does not dare to perform.
|
|
.br
|
|
Example:
|
|
.br
|
|
$ xorriso\-dd\-target \-with_sudo \-list_long \-dummy_force sdd \\
|
|
.br
|
|
\-image_file debian\-live\-10.0.0\-amd64\-xfce.iso
|
|
.br
|
|
...
|
|
.br
|
|
sdd : NO : usb+ has_iso9660+ has_vfat+ has_ext2\-
|
|
.br
|
|
NAME SIZE FSTYPE TRAN LABEL
|
|
.br
|
|
sdd 3.8G iso9660 usb d\-live 9.5.0 xf i386
|
|
.br
|
|
|\-sdd1 1.9G iso9660 d\-live 9.5.0 xf i386
|
|
.br
|
|
|\-sdd2 320K vfat
|
|
.br
|
|
`\-sdd3 512M ext2
|
|
.br
|
|
|
|
.br
|
|
Overriding any advice because of \-dummy_force
|
|
.br
|
|
Looking for mount points of sdd:
|
|
.br
|
|
/dev/sdd1 on /mnt/iso type iso9660 (ro,relatime)
|
|
.br
|
|
/dev/sdd2 on /mnt/fat type vfat (rw,...,errors=remount\-ro)
|
|
.br
|
|
/dev/sdd3 on /mnt/ext type ext2 (rw,relatime)
|
|
.br
|
|
AGAINST THE ADVICE BY THIS PROGRAM, a daring user could do:
|
|
.br
|
|
sudo /bin/umount /dev/sdd1
|
|
.br
|
|
sudo /bin/umount /dev/sdd2
|
|
.br
|
|
sudo /bin/umount /dev/sdd3
|
|
.br
|
|
sudo /bin/dd if='debian\-live\-10.0.0\-amd64\-xfce.iso' of=/dev/sdd bs=1M status=progress oflag=dsync ; sync
|
|
.br
|
|
BE SMART. BE CAUTIOUS. BEWARE.
|
|
.SS
|
|
\fBAlphabetical List of positive and negative reasons:\fR
|
|
.br
|
|
As stated with use case "List all devices", \fBreasons\fR are words with
|
|
either suffix '+' for an inviting device property or '\-' for a prohibitive
|
|
property.
|
|
.br
|
|
Normally a single '\-' reason disqualifies the device from being advisable.
|
|
.br
|
|
.PP
|
|
\fBhas_XYZ\-\fR
|
|
.br
|
|
A filesystem of type XYZ is detected on base device or partition and is
|
|
spoiling the impression of a device with disposable content.
|
|
.br
|
|
\fBhas_iso9660+\fR
|
|
.br
|
|
An ISO 9660 filesystem is detected.
|
|
.br
|
|
\fBhas_vfat+\fR
|
|
.br
|
|
A FAT (MS\-DOS\-like) filesystem is detected.
|
|
.br
|
|
\fBlook_for_iso++\fR
|
|
.br
|
|
Option \-look_for_iso is given and an ISO 9660 filesystem is detected.
|
|
This reason overrides any "has_XYZ\-" reason.
|
|
.br
|
|
\fBlooks_like_cd_drive\-\fR
|
|
.br
|
|
A given device name looks like the name of an optical drive: sr[0\-9]*.
|
|
Use program \fBxorrecord\fR for this kind of devices.
|
|
.br
|
|
\fBlooks_like_disk_partition\-\fR
|
|
.br
|
|
A given device name looks like the name of a partition. Expected are names
|
|
of base devices, like "sde", not of their partitions, like "sde1".
|
|
.br
|
|
\fBlooks_like_floppy\-\fR
|
|
.br
|
|
A given device name looks like the name of a floppy disk drive: fd[0\-9]*.
|
|
.br
|
|
\fBlooks_like_loopdev\-\fR
|
|
.br
|
|
A given device name looks like the name of a loop device: loop[0\-9]*.
|
|
.br
|
|
\fBlooks_like_ramdev\-\fR
|
|
.br
|
|
A given device name looks like the name of a RAM block device: zram[0\-9]*.
|
|
.br
|
|
\fBlsblk_no_size\-\fR
|
|
.br
|
|
A size test is given by \-max_size, \-min_size, or \-image_file but the size of
|
|
the device cannot be inquired by lsblk. This is supposed to happen only with
|
|
given inappropriate device names.
|
|
.br
|
|
\fBmmcblk+\fR
|
|
.br
|
|
The device name looks like a directly connected memory card.
|
|
.br
|
|
\fBname_with_slash\-\fR
|
|
.br
|
|
A given device name contains '/' characters.
|
|
.br
|
|
\fBno_bus_info\-\fR
|
|
.br
|
|
The device is not a memory card and lsblk reports nothing about the way how
|
|
it is connected to the computer.
|
|
.br
|
|
\fBno_fs_while_not_su\-\fR
|
|
.br
|
|
No filesystem is reported by lsblk and the program does not believe to have
|
|
run it with superuser powers. There is the risk that lsblk silently failed
|
|
to detect existing filesystems.
|
|
.br
|
|
\fBno_iso9660\-\fR
|
|
.br
|
|
Option \-look_for_iso is given but no ISO 9660 filesystem is detected.
|
|
.br
|
|
\fBnot_usb\-\fR
|
|
.br
|
|
The device is not a memory card and lsblk reports that it is connected by
|
|
something other than USB.
|
|
.br
|
|
\fBsize_too_large\-\fR
|
|
.br
|
|
Option \-max_size is given with a size smaller than the size of the device.
|
|
.br
|
|
\fBsize_too_small\-\fR
|
|
.br
|
|
Option \-min_size or \-image_file is given with size or file size larger than
|
|
the size of the device.
|
|
.br
|
|
\fBusb+\fR
|
|
.br
|
|
The device is reported by lsblk to be connected via USB.
|
|
.br
|
|
.SS
|
|
.br
|
|
.SH OPTIONS
|
|
.br
|
|
.PP
|
|
.TP
|
|
\fB\-plug_test\fR
|
|
Find the target device by asking the user to press the Enter key when the
|
|
desired target is _not_ plugged in, to then plug it in, and to press Enter
|
|
again.
|
|
.br
|
|
This overrides device names and option \-list_all.
|
|
The found device is then shown with advice, vendor, and model.
|
|
.br
|
|
Option \-DO_WRITE is obeyed if given.
|
|
In this case, the word 'yes' has to be entered to let unmounting and writing
|
|
begin.
|
|
.TP
|
|
\fB\-list_all\fR
|
|
Print list of all found devices with advice, vendor and model. One per line.
|
|
Ignore any device names. Ignore \-DO_WRITE.
|
|
.TP
|
|
\fB\-list_long\fR
|
|
After each result line, which shows reasons, add an additional listing of
|
|
the information provided by lsblk which led to the reasons and add an empty
|
|
line.
|
|
.TP
|
|
\fB\-with_vendor_model\fR
|
|
Print vendor and model with each submitted device name.
|
|
.TP
|
|
\fB\-max_size\fR n[M|G|T]
|
|
Set the upper byte size limit for advisable devices. Plain numbers get rounded
|
|
down to full millions. As suffix are recognized: M = million, G = billion,
|
|
T = trillion.
|
|
.br
|
|
Be generous to avoid problems with GB < GiB.
|
|
.TP
|
|
\fB\-min_size\fR n[M|G|T]
|
|
Set the lower byte size limit for advisable devices. After processing like
|
|
with \-max_size, one million gets added to the size limit.
|
|
.TP
|
|
\fB\-look_for_iso\fR
|
|
Demand presence of an ISO 9660 filesystem. If so, then any further filesystem
|
|
type is acceptable on that device.
|
|
.br
|
|
If this option is missing, only ISO 9660 and VFAT filesystems are accepted.
|
|
.TP
|
|
\fB\-with_sudo\fR
|
|
Run 'lsblk \-o FSTYPE' by sudo. If no filesystems are detected on a device while
|
|
the program has no superuser power, then the device is not advised. Option
|
|
\-with_sudo avoids this refusal without the need to run the whole
|
|
program as superuser.
|
|
.br
|
|
If \-DO_WRITE \-with_sudo is given, then the programs umount and dd will be run
|
|
by sudo, too.
|
|
.TP
|
|
\fB\-image_file\fR PATH
|
|
Set the path of the image file which shall be written to a device. Its size
|
|
will be set as \-min_size.
|
|
.TP
|
|
\fB\-DO_WRITE\fR
|
|
Write the given \-image_file to the one advisable device that is found. If more
|
|
than one such device is found, then they get listed but no writing happens.
|
|
.br
|
|
In this case, to get a real write run, consider unplugging unneeded devices,
|
|
or using option \-plug_test, or a re\-run with one of the advised device names
|
|
as additional argument.
|
|
.TP
|
|
\fB\-no_pacifier\fR
|
|
Do not use dd options to print progress messages and to perform synchronized
|
|
output. These options are used by default if program dd offers progress
|
|
messages.
|
|
.TP
|
|
\fB\-dummy\fR
|
|
Report the \-DO_WRITE actions but do not perform them.
|
|
.TP
|
|
\fB\-dummy_force\fR
|
|
If a single device name is given, do a run of \-dummy \-DO_WRITE even against
|
|
the advice of this program. This probably shows you ways to shoot your own
|
|
foot.
|
|
.TP
|
|
\fB\-version\fR
|
|
Print the program name, version text, and timestamp to stdout and then end
|
|
the program.
|
|
.TP
|
|
\fB\-help\fR
|
|
Print the help text to stdout and then end the program.
|
|
.SH EXAMPLES
|
|
Examples are given in the above description of use cases.
|
|
.SH FILES
|
|
For now, no files are defined for configuration.
|
|
.SH SEE ALSO
|
|
.BR lsblk(8),
|
|
.BR umount(8),
|
|
.BR dd(1),
|
|
.BR xorrecord(1)
|
|
.SH BUGS
|
|
To report bugs, request help, or suggest enhancements for
|
|
\fBxorriso\-dd\-target\fR,
|
|
please send electronic mail to the public list <bug\-xorriso@gnu.org>.
|
|
If more privacy is desired, mail to <scdbackup@gmx.net>.
|
|
.br
|
|
Please describe what you expect the program to do, the program arguments
|
|
which you used, the messages of \fBxorriso\-dd\-target\fR, and the
|
|
undesirable outcome of your program run.
|
|
.br
|
|
Expect to get asked more questions before solutions can be proposed.
|
|
.SH AUTHOR
|
|
Thomas Schmitt <scdbackup@gmx.net>
|
|
.br
|
|
for libburnia\-project.org
|
|
.SH COPYRIGHT
|
|
Copyright (c) 2019 Thomas Schmitt
|
|
.br
|
|
Permission is granted to distribute this text freely. It shall only be
|
|
modified in sync with the technical properties of xorriso\-dd\-target.
|
|
If you make use of the license to derive modified versions of xorriso\-dd\-target
|
|
then you are entitled to modify this text under that same license.
|
|
.SH CREDITS
|
|
\fBxorriso\-dd\-target\fR is developed in cooperation with Nio Wiklund alias
|
|
sudodus.
|