BOOTISO(1)

NAME
bootiso - create a bootable USB drive from an image file

SYNOPSIS
Each line depicts an action, with the exception of the first three lines which describe install action modes. Respectively, “Automatic,” “Image-Copy” and “Mount-Rsync” modes. In the last two, INSTALLMODS refers to an option enumerated in the first “Automatic” synopsis line. When both short and long options exist, only one is printed.

bootiso [-aJMy] [-d device] [ --no-hash-check | [--hash-file hashfile] [--force-hash-check]] [--no-size-check] [--no-usb-check] [--assume-image-is image-type] [--] imagefile
bootiso --icopy [INSTALLMODS ...] [--dd-bs blocksize] [ -D [--data-part-fs fstype]] [--] imagefile
bootiso --mrsync [INSTALLMODS ...] [-L label] [-F fstype] [--gpt] [--no-wimsplit] [--part-type typeid] [--local-bootloader | --remote-bootloader version] [--] imagefile
bootiso -f [-ay] [-d device] [-L label] [-F fstype] [--gpt] [--no-usb-check] [--part-type typeid]
bootiso -i [-M] [ --no-hash-check | [--hash-file hashfile] [--force-hash-check]] [--] imagefile
bootiso -l [--no-usb-check]
bootiso -p [-M] [ --no-hash-check | [--hash-file hashfile] [--force-hash-check]] [--no-usb-check] [--] imagefile
bootiso -h
bootiso -v

DESCRIPTION
bootiso is a command-line utility aimed at simplifying the task of “burning” a USB storage device with a bootable disk image. The program can be safely called with no options. Read EXAMPLES section for a quick summary of typical invocations.

  Features
One can use dd(1) utility for hybrid images, but not all images are hybrid and the operation is error-prone, especially for amateur UNIX users, thus its “disk destroyer” nickname. In addition to offering a safety layer (see GUARDRAILS section), bootiso will handle hybrid and non-hybrid SYSLINUX or UEFI compliant images such as any GNU-Linux, Windows or rescue live-cds like UltimateBootCD images. This program also offers additional features, such as quickly format a USB drive, inspecting an image file or listing USB-connected drives. Supported images format are plain disk images (img) and ISO 9660 files.

bootiso can be invoked with two types of options: actions and modifiers. Actions determine the goal of the program execution, and modifiers define the specifics to reach that goal. At most one action flag can be set. In the absence of action flag, bootiso assumes install action in “Automatic” mode: inspect imagefile boot capabilities and find the best way to make a bootable USB drive (see INSTALL MODES bellow).

  Actions

-f, --format
    Wipe and format the selected USB device. Default Behavior: If no device were explicitly selected with --device modifier, bootiso will prompt for selection. With no further notice, bootiso will write a MBR partition table and format a FAT32 partition. These defaults can be overridden with --gpt and --fs modifiers.

-h, --help
    Display a concise list of options then exits.

-i, --inspect
    Inspect imagefile boot capabilities and how bootiso can handle it. In addition, validate this file against a hash file if one is found, then exit.

-l, --list-usb-drives
    List USB drives then exits. Diverse information will be printed such as model, vendor, size and device file name which can be later used with -d, --device modifier.

-p, --probe
    Probe is equivalent to inspect followed by list USB drives actions.

-v, --version
    Displays bootiso version then exits.

  Generic Modifiers
Use generic modifiers knowingly as some might override default safe behaviors.

--assume-image-is image-type
    Override bootiso assessment of imagefile hybridness. Use “hybrid” to force bootiso regard imagefile as hybrid, and “non-hybrid” to force bootiso regard imagefile as non hybrid.

-a, --autoselect
    Enable “autoselect” behavior in combination with --assume-yes modifier. It will automatically select a USB drive device if there is exactly one connected to the system.

    Notice: The “autoselect” behavior is the default behavior when “assume yes” is not enabled, unless either --device or --no-usb-check modifiers are set.

-d device, --device device
    Select device block file as the action target. When device is not connected through a USB bus, bootiso will fail and exit, unless --no-usb-check is set.

    Notice: Device block files are located in /dev/. The /dev/ prefix can be omitted. You will be prompted to select a device when not using this modifier. Also, this option is not compatible with loop devices.

-D, --data-part
    Add a supplementary data partition after installation. Requires --icopy or --dd install modifier.

    Notice: This will only work with imagefiles containing MBR or GPT partition schemes.

--data-part-fs fstype
    Change filesystem type for the supplementary data partition. Default is FAT32. Requires --icopy or --dd install modifier.

--dd-bs blocksize
    Specify the maximum block-size used by dd(1) utility in “Image-Copy” mode. See bs option of dd(1) utility. Default is 4M. Requires --icopy or --dd install modifier.

    Notice: values bellow 50k can sensibly slow down the installation.

-F fstype, --fs fstype
    Format to fstype instead of default FAT32 (vfat). Supported types: vfat, exfat, ntfs, ext2, ext3, ext4, and f2fs. Requires --mrsync install modifier or format action.

    Important Notice: usage with install action is discouraged: it will be rejected in “Automatic” and “Image-Copy” modes, and could prevent UEFI boot in “Mount-Rsync” mode since the UEFI standard mandates a FAT32 partition.

--force-hash-check
    Fail and exit when no valid hash is found. The default behavior is to prompt user when hash check fails.

--gpt
    Enforce GPT partition scheme over default MBR. Requires --mrsync install modifier or format action.

    Important Notice: Booting systems are generally more sensible to GPT partition types compared to MBR partition types. It is thus advised that you explicitly set the partition type with --part-type modifier when enforcing GPT. This is however not required for Windows images which have a special handling by bootiso.

-H, --no-hash-check
    Skip the lookup for hash sum-files in the same folder as imagefile. See --hash-file definition for a description of the lookup mechanism.

--hash-file hashfile
    Explicitly set the hashfile containing the ISO hash. The default behavior is to look for files matching those conditions:

    1.  Located in the same folder as imagefile.

    2.  Which name is the concatenation of imagefile, “.” and the hash function name suffixed with “sum”.

    Supported hash functions are md5, sha1, sha256 and sha512.

-J, --no-eject
    Do not eject device after unmount. This is the default behavior with format action.

--local-bootloader
    Prevent download of remote bootloader and force local syslinux during installation. This might work, but could also lower the chances of successful legacy BIOS boot, especially when the major versions mismatch. Requires --mrsync install modifier.

-M, --no-mime-check
    Don't assert that imagefile has the right mime-type.

--no-size-check
    Don't assert that selected device size is larger than imagefile.

--no-usb-check
    Don't assert that selected device is connected through USB bus.

--no-wimsplit
    Prevent splitting /sources/install.wim file in Windows ISOs. Requires --mrsync install modifier.

--part-type typeid
    Set a specific MBR partition type, or GPT partition type when --gpt modifier is set. Not to be confused with filesystem modifier --fs. Requires --mrsync install modifier or format action.

    List available types for GPT or MBR with the following commands:

        sfdisk --list-types --label gpt
        sfdisk --list-types --label mbr

--remote-bootloader version
    Force download of syslinux remote bootloader at version version. Version must follow the pattern MAJOR.MINOR. Examples: 4.10, 6.04. That will only work with x64 system architecture. Requires --mrsync install modifier.

-t fstype, --type fstype
    Deprecated because of potential confusion with --part-type. Use -F, --fs instead.

-L label, --label label
    Set partition label as label instead of inferring. bootiso will cut labels which are too long regarding the selected filesystem limitations. Requires --mrsync install modifier or format action.

-y, --assume-yes
    Don't prompt for confirmation before erasing and partitioning USB device.

--  Posix end of options. bootiso will not process any option after this flag and treat the upcoming item as imagefile.

  Install mode modifiers
These modifiers only apply to default install action (see INSTALL MODES bellow).

--icopy, --dd
    Assert “Image-Copy” mode and enable specific options for this mode. bootiso will fail if the imagefile is not hybrid.

--mrsync
    Assert “Mount-Rsync” mode and enable specific options for this mode. bootiso will fail if the imagefile is not an ISO 9660 filesystem.

INSTALL MODES

bootiso has three operating modes for install action. When you assert a specific mode, it allows you to provide advanced options for this mode.

Automatic
    In the default “Automatic” mode, bootiso will inspect imagefile and choose the best strategy to end up with a bootable USB stick. These strategies are described in the below two modes. Invoke --inspect action flag to print identified boot capabilities and the compatible strategy.

Image-Copy
    In “Image-Copy” mode enforceable with --icopy install modifier, bootiso uses dd(1) utility to make a raw copy of imagefile. This is perfectly appropriate when the image file contains a builtin boot capability. It requires to have a partition table, which can be directly copied to the target device along with the data partitions. ISOs with this feature are called “hybrid”, and a vast majority of GNU-Linux images are shipped that way. See isohybrid(1) for more information on this topic.

Mount-Rsync
    In “Mount-Rsync” mode enforceable with --mrsync install modifier, bootiso creates a MBR partition table and format one partition in the USB drive and copy files from mounted ISO. The behavior will change depending on the presence of special files to identify whether legacy BIOS boot or UEFI boot should be preferred. bootiso will check conditions to figure out which ones to choose:

    1.  If /efi/boot/* boot files exist, choose UEFI boot and FAT32 filesystem mandated by the standard. In which case, if a Windows /sources/install.wim file is found, wimlib-imagex(1) will be used to circumvent FAT32 filesystem size limitations. You can prevent this behavior with --no-wimsplit modifier flag.

    2.  If syslinux(1) configuration files are found, it will install the syslinux bootloader to allow legacy BIOS boot and select MBR partition table. When the local version of syslinux doesn't match ISO version, it will attempt to download the closest version available in kernel.org: https://www.kernel.org unless --local-bootloader flag is set. When invoked with --remote-bootloader version modifier, bootiso will ignore local version check and forces download of the kernel.org version at version.

    3.  If none of the above conditions are met, bootiso will fail and exit.

GUARDRAILS
bootiso performs a set of tests with user safety and confidence in mind:

•   Checks imagefile hash sum against a hash file if one found. Supported hash algorithms are md5, sha1, sha256 and sha512.

•   Checks imagefile mime-type with file(1) utility.

•   Asserts selected device is connected through USB preventing system damages and exit if it doesn't, with lsblk(8) utility.

•   Asserts that selected image is not larger than selected device.

•   Prompts for confirmation before erasing and partitioning USB device.

ENVIRONMENT

BOOTISO_IMAGES_COMPLETIONS_PATH
    This variable is interpreted by shell completion scripts as a path pointing to a directory to look up for image and hashsum files and suggest those files when no files are matched in current working directory. When not set, either XDG_DOWNLOAD_DIR if defined or ~/Downloads otherwise are used instead. See xdg-user-dir(1).

BOOTISO_SYSLINUX_LIB_ROOT
    Used in “Mount-Rsync” mode when imagefile has syslinux boot capability. In which case, bootiso will need to install a MBR boot program which it needs to locate. This variable sets syslinux assets root, from which MBR program file will be searched. Defaults to /usr/lib/syslinux.

EXIT STATUS
The bootiso utility exits 0 on success, >0 on error. Error exit status < 64 depict unfavorable conditions external to the program such as a missing file. On the other hand, exit status superior or equal to 64 depict an execution failure.

0   Success.

1   Assertion failed: a safety check has not passed. See GUARDRAILS.

2   Synopsis noncompliance: program invocation does not match any known combination of options and operands.

3   Missing boot capabilities: imagefile does not have boot capabilities bootiso knows of.

4   File doesn't exists: a file provided as option argument or operand does not exist.

5   Bad file: a file provided as option argument or operand exist, but is not of the expected format.

6   Device doesn't exists: a device provided as option argument does not exist.

7   Bad device: a device provided as option argument exists in filesystem, but is not a device node.

8   No devices: there are no drives in selection.

9   Missing dependency: bootiso is missing a program.

10  Host unreachable: an operation involving network access could not be performed with host.

11  User aborted: the action was canceled by user.

12  Missing privilege: you need to run this command as root.

13  Failed postulate: an assumption about system state turned out false.

64  I/O error: a read/write command has unexpectedly failed.

65  Program state error: the program reached an unexpected state. This is a bug.

66  Third party error: a command has unexpectedly failed.

EXAMPLES

Probe
    To have a quick feedback, probe around to check bootiso capabilities with given “file.iso” and list USB drives candidates:

        bootiso -p file.iso

    Alternatively, you can use -i action flag to solely inspect “file.iso” or -l action flag to solely list USB drives.

Install
    With the default install action in “Automatic” mode, give “file.iso” as sole argument and you'll be prompted to select from available USB drives. If there is only one USB device connected, bootiso will automatically select it:

        bootiso file.iso

    You can also explicitly set the target USB device:

        bootiso -d /dev/sdX file.iso

    Avoid being prompted before writing to USB drive and autoselect device when there is exactly one connected:

        bootiso -ay file.iso

    Add a FAT32 data partition in “Image-Copy” mode (only works with hybrid images):

        bootiso --icopy -D file.iso

Format
    Format the USB drive to NTFS and label it “SONY JOE”. Be careful with the label name, which size and character set is limited by the target filesystem:

        bootiso -ft ntfs -L 'SONY JOE'

TROUBLESHOOTING

•   Some live-CD systems are not shipped with USB-3 drivers or are known to work poorly with USB-3 ports. Always try a USB-2 port, or if you don't have one, use a USB-2 stick, before considering the boot a failure. As of 2020, Windows 10 (UEFI) is among those systems.

•   If legacy BIOS boot doesn't work, be advised that UEFI-compliant boot systems have a Compatibility Support Module (CSM) option to enable legacy BIOS boot.

•   If bootiso does not detect your USB device, you can try running

        udevadm settle

    and try again.

•   If the imagefile has UEFI support and the boot fails on a UEFI-compatible machine, one can try different partition types with --part-type modifier, because some systems will assume specific types and refuse to load data otherwise. This is especially prevalent with GPT partition tables.

COPYRIGHT
Copyright Jules Sam. Randolph.

GPLv3 License: https://www.gnu.org/licenses/gpl-3.0 This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

SEE ALSO
dd(1), isohybrid(1), syslinux(1), wimlib-imagex(1)

COMPATIBILITY
bootiso should work with any terminal emulator and the Linux console. More specifically, the output device should support the following features:

•   ASCII character set;

•   ECMA-48 SGR sequences to feature color, bold and underline text attributes as documented in console_codes(4).

STANDARDS
bootiso is compliant with:

•   p1003.1-2008, Ch. 12, “Utility Conventions”;

•   Filesystem Hierarchy Standard, version 3.0.

AUTHORS
Jules Sam. Randolph <jules.sam.randolph@gmail.com>