BOOTISO(1)

📦 version 4.2.0, in nixos 26.05, nixpkgs unstable, opensuse-leap 16.0

💿 BOOTISO(1) 💿 — General Commands Manual

okay bestie, welcome to BOOTISO(1) from the General Commands Manual — the utility that makes “burn a bootable USB” not feel like a dare 💅✨

🎀 NAME 🎀

bootiso — create a bootable USB drive from an image file

🌸 SYNOPSIS 🌸

Each line shows an action, except for the first three lines — those describe install action modes. In order, they’re “Automatic,” “Image-Copy,” and “Mount-Rsync” modes. In the last two, INSTALLMODS means an option listed in the first “Automatic” synopsis line. When both a short and long option 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 that exists to simplify the task of “burning” a USB storage device with a bootable disk image. The program can be safely called with no options at all — yes, literally just run it. Read the “EXAMPLES” section for a quick summary of typical invocations.

🔥 Features 🔥

You can use dd(1) for hybrid images, but bestie… not all images are hybrid, and the operation is error-prone, especially for amateur UNIX users. That’s why dd has that “disk destroyer” nickname 😭. In addition to offering a safety layer (see the “GUARDRAILS” section), bootiso handles hybrid and non-hybrid SYSLINUX or UEFI compliant images — like any GNU-Linux, Windows, or rescue live-cds such as UltimateBootCD images.

This program also offers extra features, like quickly formatting a USB drive, inspecting an image file, or listing USB-connected drives. Supported image formats are plain disk images (img) and ISO 9660 files. Slay.

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 for reaching that goal. At most one action flag can be set. If no action flag is present, bootiso assumes the install action in “Automatic” mode: it inspects imagefile boot capabilities and finds the best way to make a bootable USB drive (see “INSTALL MODES” below).

💅 Actions 💅

  • -f, --format — Wipe and format the selected USB device. Default Behavior: if no device was explicitly selected with the --device modifier, bootiso will prompt for selection. With no further notice, bootiso will write an MBR partition table and format a FAT32 partition. These defaults can be overridden with the --gpt and --fs modifiers.
  • -h, --help — Display a concise list of options, then exit.
  • -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 exit. Diverse information will be printed, such as model, vendor, size, and device file name — which can later be used with the -d, --device modifier.
  • -p, --probe — Probe is equivalent to the inspect action followed by the list USB drives action.
  • -v, --version — Displays bootiso version, then exits.

✨ Generic Modifiers ✨

Use generic modifiers knowingly, bestie — some might override default safe behaviors 👀.

  • --assume-image-is image-type — Override bootiso’s assessment of imagefile hybridness. Use hybrid to force bootiso to regard imagefile as hybrid, and non-hybrid to force bootiso to regard imagefile as non-hybrid.
  • -a, --autoselect — Enable “autoselect” behavior in combination with the --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 the --device or --no-usb-check modifiers are set.
  • -d device, --device device — Select the 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 the --icopy or --dd install modifier.
Notice: This will only work with imagefiles containing MBR or GPT partition schemes.
  • --data-part-fs fstype — Change the filesystem type for the supplementary data partition. Default is FAT32. Requires the --icopy or --dd install modifier.
  • --dd-bs blocksize — Specify the maximum block-size used by the dd(1) utility in “Image-Copy” mode. See the bs option of the dd(1) utility. Default is 4M. Requires the --icopy or --dd install modifier.
Notice: Values below 50k can sensibly slow down the installation.
  • -F fstype, --fs fstype — Format to fstype instead of the default FAT32 (vfat). Supported types: vfat, exfat, ntfs, ext2, ext3, ext4, and f2fs. Requires the --mrsync install modifier or the format action.
Important Notice: Usage with the 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 the user when hash check fails.
  • --gpt — Enforce the GPT partition scheme over the default MBR. Requires the --mrsync install modifier or the 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 the --part-type modifier when enforcing GPT. This is however not required for Windows images, which have special handling by bootiso.
  • -H, --no-hash-check — Skip the lookup for hash sum-files in the same folder as imagefile. See the --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 these 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 the device after unmount. This is the default behavior with the format action.
  • --local-bootloader — Prevent download of the 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 the --mrsync install modifier.
  • -M, --no-mime-check — Don’t assert that imagefile has the right mime-type.
  • --no-size-check — Don’t assert that the selected device size is larger than imagefile.
  • --no-usb-check — Don’t assert that the selected device is connected through the USB bus.
  • --no-wimsplit — Prevent splitting the /sources/install.wim file in Windows ISOs. Requires the --mrsync install modifier.
  • --part-type typeid — Set a specific MBR partition type, or GPT partition type when the --gpt modifier is set. Not to be confused with the filesystem modifier --fs. Requires the --mrsync install modifier or the 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 the 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 the --mrsync install modifier.
  • -t fstype, --type fstype — Deprecated because of potential confusion with --part-type. Use -F, --fs instead.
  • -L label, --label label — Set the partition label as label instead of inferring it. bootiso will cut labels which are too long regarding the selected filesystem limitations. Requires the --mrsync install modifier or the format action.
  • -y, --assume-yes — Don’t prompt for confirmation before erasing and partitioning the USB device.
  • -- — Posix end of options. bootiso will not process any option after this flag and will treat the upcoming item as imagefile.

🧚 Install mode modifiers 🧚

These modifiers only apply to the default install action (see “INSTALL MODES” below).

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

okay so bootiso has like three whole operating modes for the install action, and when you actually pick one specifically, it unlocks the advanced options for that mode. very "choose your fighter" of it 💅

🌸 Automatic

In the default "Automatic" mode, bootiso will peek at imagefile and pick the best strategy so you end up with a bootable USB stick. Those strategies are literally the two modes below. Run the --inspect action flag to print out the boot capabilities it detected plus the compatible strategy — very "let me show you my work" energy.

🦋 Image-Copy

"Image-Copy" mode — you enforce it with the --icopy install modifier — and bootiso uses the dd(1) utility to make a raw copy of imagefile. This is perfectly appropriate when the image file has a builtin boot capability. It needs a partition table though, one that can be copied straight onto the target device along with the data partitions. ISOs with this feature are called "hybrid", and a vast majority of GNU-Linux images ship that way. Peep isohybrid(1) if you wanna know more about this topic 👀

🧚 Mount-Rsync

"Mount-Rsync" mode — enforced with the --mrsync install modifier — has bootiso create an MBR partition table, format one partition on the USB drive, and copy files from the mounted ISO. The behavior changes depending on whether those special files are there that tell it legacy BIOS boot or UEFI boot should be preferred. bootiso checks the conditions to figure out which one to choose:

  1. If /efi/boot/* boot files exist, it chooses UEFI boot and FAT32 filesystem, which the standard mandates. In that case, if a Windows /sources/install.wim file is found, wimlib-imagex(1) gets used to circumvent the FAT32 filesystem size limitations. You can prevent this behavior with the --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 the MBR partition table. When your local syslinux version doesn't match the ISO version, it attempts to download the closest version available on kernel.org: https://www.kernel.org — unless the --local-bootloader flag is set. And when invoked with the --remote-bootloader version modifier, bootiso ignores the local version check entirely and forces the download of the kernel.org version at version. no cap.
  3. If none of the above conditions are met, bootiso will fail and exit. 💀

👑 GUARDRAILS 👑

bootiso runs a whole set of tests with your safety and confidence in mind, bestie:

  • Checks imagefile hash sum against a hash file if one is found. Supported hash algorithms are md5, sha1, sha256 and sha512.
  • Checks imagefile mime-type with the file(1) utility.
  • Asserts the selected device is connected through USB — preventing system damage — and exits if it isn't, using the lsblk(8) utility.
  • Asserts that the selected image is not larger than the selected device.
  • Prompts for confirmation before erasing and partitioning the USB device.
like... it's giving "protective bestie" and honestly? we stan 🎀

🌈 ENVIRONMENT 🌈

  • BOOTISO_IMAGES_COMPLETIONS_PATH — this variable is interpreted by shell completion scripts as a path pointing to a directory to look up image and hashsum files, and to suggest those files when no files are matched in the current working directory. When it's not set, either XDG_DOWNLOAD_DIR (if defined) or ~/Downloads (otherwise) gets used instead. See xdg-user-dir(1) 💖
  • BOOTISO_SYSLINUX_LIB_ROOT — used in "Mount-Rsync" mode when imagefile has syslinux boot capability. In that case bootiso needs to install an MBR boot program, and it needs to locate it. This variable sets the syslinux assets root, from which the 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 depicts unfavorable conditions external to the program — like a missing file. On the other hand, exit status superior or equal to 64 depicts an execution failure.

  • 0 — Success. slay ✨
  • 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 a given file.iso and list USB drive candidates:

bootiso -p file.iso

Alternatively, you can use the -i action flag to solely inspect file.iso, or the -l action flag to solely list USB drives. options, options, options — we love a flexible icon 💅

Install

With the default install action in "Automatic" mode, give file.iso as the sole argument and you'll be prompted to select from available USB drives. If there's 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 the USB drive and autoselect the device when there's 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 — its size and character set are 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. not me learning that the hard way 😭
  • 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 imagefile has UEFI support and the boot fails on a UEFI-compatible machine, one can try different partition types with the --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 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>

and that's the whole page bestie, ily, go make a bootable USB and slay 💖✨ this was bootiso version 4.2.0, dated May 22, 2020 — iconic behavior, periodt 🎀

📦 where this page comes from