1. Manuals
  2. Tumbleweed
  3. bootiso
  4. bootiso(1)

Scroll to navigation

BOOTISO(1) General Commands Manual 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

--format
Wipe and format the selected USB device. 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.
--help
Display a concise list of options then exits.
--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.
--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.
--probe
Probe is equivalent to followed by actions.
--version
Displays bootiso version then exits.

Generic Modifiers

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

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

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.

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

fstype
Change filesystem type for the supplementary data partition. Default is FAT32. Requires --icopy or --dd install modifier.
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.

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.

Fail and exit when no valid hash is found. The default behavior is to prompt user when hash check fails.
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.

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

--no-eject
Do not eject device after unmount. This is the default behavior with format action.
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.
--no-mime-check
Don't assert that imagefile has the right mime-type.
Don't assert that selected device size is larger than imagefile.
Don't assert that selected device is connected through USB bus.
Prevent splitting /sources/install.wim file in Windows ISOs. Requires --mrsync install modifier.
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
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.
fstype, --type fstype
Deprecated because of potential confusion with --part-type. Use -F, --fs instead.
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.
--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).

, --dd
Assert “Image-Copy” mode and enable specific options for this mode. bootiso will fail if the imagefile is not hybrid.
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.

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

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

.
: a safety check has not passed. See GUARDRAILS.
: program invocation does not match any known combination of options and operands.
: imagefile does not have boot capabilities bootiso knows of.
: a file provided as option argument or operand does not exist.
: a file provided as option argument or operand exist, but is not of the expected format.
: a device provided as option argument does not exist.
: a device provided as option argument exists in filesystem, but is not a device node.
: there are no drives in selection.
: bootiso is missing a program.
: an operation involving network access could not be performed with host.
: the action was canceled by user.
: you need to run this command as root.
: an assumption about system state turned out false.
: a read/write command has unexpectedly failed.
: the program reached an unexpected state. This is a bug.
: a command has unexpectedly failed.

EXAMPLES

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.

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

    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:

  • IEEE Std 1003.1-2008 (“POSIX.1”), Ch. 12, “Utility Conventions”;
  • Filesystem Hierarchy Standard, version 3.0.

AUTHORS

Jules Sam. Randolph ⟨jules.sam.randolph@gmail.com⟩

May 22, 2020 bootiso 4.2.0