Provided by: xorriso-dd-target_1.5.6-1.1ubuntu3_all bug

NAME

       xorriso-dd-target -  Device evaluator and disk image copier for GNU/Linux

SYNOPSIS

       xorriso-dd-target [ options ] [ device_names ]

DESCRIPTION

       xorriso-dd-target  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.
       It is specialized on the device names of the Linux kernel and  uses  the  capabilities  of
       util-linux program lsblk.  Therefore it refuses to run on non-Linux kernels.

       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.
       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.
       Superuser  power  is  often  needed  for  filesystem  type  identification,  for  possible
       unmounting,  and  for possible image writing.  Option -with_sudo offers a way to gain this
       power only for those tasks and to run the program elsewise with a normal user's power.
       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.

       Following are use case descriptions with examples:
       - List plain device names
       - List all devices with reasoning
       - Evaluate particular given devices
       - Detect intended device by plugging
       - Write image to an advised device
       - Show commands for writing to a not advised device

   List plain device names:
       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.
       The possible sudo password prompt, the message line about sudo, and the empty  line  after
       it do not go to stdout.
       Example:
       $ xorriso-dd-target -with_sudo
       Testing sudo to possibly get password prompting done now:
       [sudo] password for thomas:
       sudo /bin/lsblk seems ok.

       sde

   List all devices with reasoning:
       For  the  more curious user, there is option -list_all 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.
       Each device is shown by one line of the form
         name : advice : reasoning : info
       name is the device name without "/dev/" prefix.
       advice  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.
       reasoning 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.
       info is composed from VENDOR and MODEL as told by lsblk.
       Option -list_long causes with each line an additional listing of the information  provided
       by lsblk which led to the shown reasons.
       Example:
       $ xorriso-dd-target -with_sudo -list_all
        ...
       sda : NO  : not_usb- has_vfat+ has_ext4- : ATA Samsung SSD 850
       sdb : NO  : not_usb- has_swap- has_ext4- : ATA WDC WD20EFRX-68A
       sdc : YES : usb+ has_iso9660+ has_vfat+ : Intenso Ultra Line
       sdd : NO  : usb+ has_iso9660+ has_vfat+ has_ext2- : SanDisk Cruzer

   Evaluate particular given devices:
       If  device  names  are  given  instead  of  option  -list_all, then only these devices are
       inspected.  Their  result  gets  listed  without  the  ":  info"   part,   unless   option
       -with_vendor_model is given.
       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.
       If one of the given device names gets not advised, the exit value is 1.
       It makes few sense to give device names which are not listed by -list_all.
       Examples:
       $ xorriso-dd-target -with_sudo sdc
        ...
       sdc : YES : usb+ has_iso9660+ has_vfat+
       $ xorriso-dd-target -with_sudo -with_vendor_model sdc
        ...
       sdc : YES : usb+ has_iso9660+ has_vfat+ : Intenso Ultra Line
       $ xorriso-dd-target sdc

       sdc : NO  : usb+ no_fs_while_not_su-
   Detect intended device by plugging:
       Option -plug_test triggers an interactive method to unambiguously determine  the  intended
       target device candidate. It consists of 2 or 3 steps.
       Step  1  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.
       Step 2 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.
       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.
       Step  3 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.
       Example:
       $ xorriso-dd-target -with_sudo -plug_test
        ...
       Caused by option -plug_test: Attempt to find the desired  device  by  watching  it  appear
       after being plugged in.
       Step 1:
       Please make sure that the desired target device is plugged _out_ now.
       If it is currently plugged in, make sure to unmount all its filesystems
       and then unplug it.
       Press the Enter key when ready.

       Found and noted as _not_ desired:  sda sdb sdc
       Step 2:
       Please plug in the desired target device and then press the Enter key.

       Waiting up to 10 seconds for a new device to be listed ... found: sdd
       Now waiting 5 seconds to let it settle .........
       Found and noted as desired device:  sdd

       sdd : NO  : usb+ has_iso9660+ has_vfat+ has_ext2- : SanDisk Cruzer

   Write image to an advised device:
       Only  if  option  -DO_WRITE  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.
       Option -dummy prevents this kind of real action and rather shows the planned umount and dd
       commands on stdout.
       Example:
       $ xorriso-dd-target -with_sudo -plug_test -DO_WRITE \
           -image_file debian-live-10.0.0-amd64-xfce.iso
        ... sudo messages and above plug test steps 1 and 2 ...

       sde : YES : usb+ has_iso9660+ has_vfat+
       Step 3:
       Last chance to abort. Enter the word 'yes' to start REAL WRITING.
       yes
       Looking for mount points of sde:
         /dev/sde1 on /mnt/iso type iso9660 (ro,relatime)
         /dev/sde2 on /mnt/fat type vfat (rw,...,errors=remount-ro)
       Unmounted: /dev/sde1
       Unmounted: /dev/sde2
       Performing:
         sudo /bin/dd if=/dev/zero of=/dev/'sde' bs=512 seek='245759999'
                      count=1 status=none
         sudo /bin/dd if='debian-live-10.0.0-amd64-xfce.iso' of=/dev/'sde'
                      bs=1M status=progress oflag=dsync ; sync
        ... dd messages ...
       The first dd run shall erase a possible GPT backup header. It is  performed  only  if  the
       local program "expr" can deal with the byte size of the device.

   Show commands for writing to a not advised device:
       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.
       The outmost complicity to potentially unwise actions is offered by option -dummy_force. 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.
       Example:
       $ xorriso-dd-target -with_sudo -list_long -dummy_force sdd \
           -image_file debian-live-10.0.0-amd64-xfce.iso
        ...
       sdd : NO  : usb+ has_iso9660+ has_vfat+ has_ext2-
       NAME    SIZE FSTYPE  TRAN LABEL
       sdd     3.8G iso9660 usb  d-live 9.5.0 xf i386
       |-sdd1  1.9G iso9660      d-live 9.5.0 xf i386
       |-sdd2  320K vfat
       `-sdd3  512M ext2

       Overriding any advice because of -dummy_force
       Looking for mount points of sdd:
         /dev/sdd1 on /mnt/iso type iso9660 (ro,relatime)
         /dev/sdd2 on /mnt/fat type vfat (rw,...,errors=remount-ro)
         /dev/sdd3 on /mnt/ext type ext2 (rw,relatime)
       AGAINST THE ADVICE BY THIS PROGRAM, a daring user could do:
         sudo /bin/umount /dev/sdd1
         sudo /bin/umount /dev/sdd2
         sudo /bin/umount /dev/sdd3
         sudo /bin/dd if=/dev/zero of=/dev/'sdd' bs=512 seek='7864318'
                      count=1 status=none
         sudo /bin/dd if='debian-live-10.0.0-amd64-xfce.iso' of=/dev/sdd
                      bs=1M status=progress oflag=dsync ; sync
       BE SMART. BE CAUTIOUS. BEWARE.

   Alphabetical List of positive and negative reasons:
       As stated with use case "List all devices", reasons are words with either suffix  '+'  for
       an inviting device property or '-' for a prohibitive property.
       Normally a single '-' reason disqualifies the device from being advisable.

       has_XYZ-
       A  filesystem  of  type  XYZ  is  detected on base device or partition and is spoiling the
       impression of a device with disposable content.
       has_iso9660+
       An ISO 9660 filesystem is detected.
       has_vfat+
       A FAT (MS-DOS-like) filesystem is detected.
       look_for_iso++
       Option -look_for_iso is given and  an  ISO  9660  filesystem  is  detected.   This  reason
       overrides any "has_XYZ-" reason.
       looks_like_cd_drive-
       A  given  device  name  looks  like  the  name of an optical drive: sr[0-9]*.  Use program
       xorrecord for this kind of devices.
       looks_like_disk_partition-
       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".
       looks_like_floppy-
       A given device name looks like the name of a floppy disk drive: fd[0-9]*.
       looks_like_loopdev-
       A given device name looks like the name of a loop device: loop[0-9]*.
       looks_like_ramdev-
       A given device name looks like the name of a RAM block device: zram[0-9]*.
       lsblk_no_size-
       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.
       mmcblk+
       The device name looks like a directly connected memory card.
       name_with_slash-
       A given device name contains '/' characters.
       no_bus_info-
       The  device  is  not  a  memory  card  and  lsblk  reports nothing about the way how it is
       connected to the computer.
       no_fs_while_not_su-
       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.
       no_iso9660-
       Option -look_for_iso is given but no ISO 9660 filesystem is detected.
       not_usb-
       The device is not a memory card and lsblk reports that it is connected by something  other
       than USB.
       size_too_large-
       Option -max_size is given with a size smaller than the size of the device.
       size_too_small-
       Option  -min_size  or  -image_file is given with size or file size larger than the size of
       the device.
       usb+
       The device is reported by lsblk to be connected via USB.

OPTIONS

       -plug_test
              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.
              This  overrides  device names and option -list_all.  The found device is then shown
              with advice, vendor, and model.
              Option -DO_WRITE is obeyed if given.  In this  case,  the  word  'yes'  has  to  be
              entered to let unmounting and writing begin.

       -list_all
              Print  list  of  all  found  devices  with  advice, vendor and model. One per line.
              Ignore any device names. Ignore -DO_WRITE.

       -list_long
              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.

       -with_vendor_model
              Print vendor and model with each submitted device name.

       -max_size 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.
              Be generous to avoid problems with GB < GiB.

       -min_size 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.

       -look_for_iso
              Demand  presence of an ISO 9660 filesystem. If so, then any further filesystem type
              is acceptable on that device.
              If this option is missing, only ISO 9660 and VFAT filesystems are accepted.

       -with_sudo
              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.
              If -DO_WRITE -with_sudo is given, then the programs umount and dd will  be  run  by
              sudo, too.

       -trust_lsblk_udev
              Suppress  the  reason  no_fs_while_not_su-  if lsblk is linked with libudev.so.  In
              this case  it  is  likely  that  lsblk  can  retrieve  FSTYPE  even  if  run  by  a
              non-priviledged user.
              This option is intended for use by frontend programs which are certain that they do
              not encounter a udev-using version of lsblk  which  nevertheless  fails  to  detect
              existing  filesystems. Human users should better acquire superuser powers if reason
              no_fs_while_not_su- is reported.

       -image_file PATH
              Set the path of the image file which shall be written to a device. Its size will be
              set as -min_size.

       -DO_WRITE
              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.
              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.

       -no_pacifier
              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.

       -dummy Report the -DO_WRITE actions but do not perform them.

       -dummy_force
              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.

       -version
              Print the program name, version text, and timestamp to  stdout  and  then  end  the
              program.

       -help  Print the help text to stdout and then end the program.

EXAMPLES

       Examples are given in the above description of use cases.

FILES

       For now, no files are defined for configuration.

SEE ALSO

       lsblk(8), umount(8), dd(1), xorrecord(1)

BUGS

       To  report  bugs, request help, or suggest enhancements for xorriso-dd-target, please send
       electronic mail to the public list <bug-xorriso@gnu.org>.  If  more  privacy  is  desired,
       mail to <scdbackup@gmx.net>.
       Please  describe  what you expect the program to do, the program arguments which you used,
       the messages of xorriso-dd-target, and the undesirable outcome of your program run.
       Expect to get asked more questions before solutions can be proposed.

AUTHOR

       Thomas Schmitt <scdbackup@gmx.net>
       for libburnia-project.org

COPYRIGHT

       Copyright (c) 2019 - 2023 Thomas Schmitt
       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.

CREDITS

       xorriso-dd-target is developed in cooperation with Nio Wiklund alias sudodus.

                                   Version 1.5.6, Jun 07, 2023               XORRISO-DD-TARGET(1)