XORRISOFS(1)

📦
version 1.5.8.2 · 3 versions
, in alpine 3.24, arch rolling, fedora 43, fedora 44, nixpkgs unstable

✨ XORRISOFS(1) ✨

General Commands Manual vibes, bestie. This is the xorrisofs page and it's long, so we're doing it in parts. Part 1 starts now. 💅

🌸 NAME 🌸

xorrisofs — emulation of ISO 9660 program mkisofs by program xorriso.

🦋 SYNOPSIS 🦋

xorrisofs [ options ] [-o filename ] pathspec [pathspecs ...]

💖 DESCRIPTION 💖

okay so xorrisofs produces Rock Ridge enhanced ISO 9660 filesystems and add-on sessions to such filesystems. Optionally it can produce Joliet directory trees too. No cap.

xorrisofs understands options of program mkisofs from cdrtools by Joerg Schilling. Its implementation is part of program xorriso which shares no source code with cdrtools. Iconic.

🌀 ISO 9660, Rock Ridge, Joliet, HFS+: 🌀

ISO 9660 (aka ECMA-119) is a read-only filesystem that is mainly used for optical media CD, DVD, BD, but may also reside on other storage devices like disk files, USB sticks or disk partitions. It is widely readable by many operating systems and by boot facilities of personal computers.

ISO 9660 describes directories and data files by very restricted filenames with no distinction of upper case and lower case. Its metadata do not comply to fundamental POSIX specifications.

Rock Ridge is the name of a set of additional information which enhance an ISO 9660 filesystem so that it can represent a POSIX compliant filesystem with ownership, access permissions, symbolic links, and other attributes. Rock Ridge allows filenames of up to 255 bytes and paths of up to 1024 bytes.

xorrisofs produces Rock Ridge information by default. It is strongly discouraged to disable this feature. Periodt.

Joliet is the name of an additional directory tree which provides filenames up to 64 characters encoded as UTF-16. A Joliet tree is mainly interesting for reading the ISO image by operating systems of Microsoft Corporation. Production of this directory tree may be enabled by option -J.

ISO 9660:1999 is the folkloric name of an additional directory tree which provides longer filenames. It allows single file names to have up to 207 characters. Its starting point is specified officially as Enhanced Volume Descriptor in ECMA-119 4th Edition.

It might be of use with some older computer system boot facilities which read neither Rock Ridge nor Joliet but need longer filenames nevertheless. Production of this directory tree may be enabled by option -iso-level 4.

HFS+ is the name of a filesystem which is normally used for writing and reading on hard disks and similar devices. It is possible to embed a HFS+ partition into the emerging ISO 9660 image and to mark it by Apple Partition Map entries. This interferes with options which copy data into the first 32 KiB of the ISO image, like -G or -isohybrid-mbr. See option -hfsplus.

The main purpose for having an embedded HFS+ partition is booting of certain models of Apple computers.

🎀 Inserting files into the ISO image: 🎀

xorrisofs deals with two kinds of file addresses:

  • disk_path is a path to an object in the local filesystem tree.
  • iso_rr_path is the Rock Ridge address of a file object in the ISO image.

If no Rock Ridge information shall be stored in an emerging ISO, then the names will get mapped to ISO 9660 names of limited length and character set.

A program argument is handled as a pathspec, if it is not recognized as original mkisofs option or additional xorrisofs option. A pathspec depicts an input file object by a disk_path. If option -graft-points is not present, then the behavior depends on the file type of disk_path. Directories get merged with the /-directory of the ISO image. Files of other types get copied into the /-directory.

If -graft-points is present then each pathspec gets split at the first occurrence of the =-character. The part before the = is taken as target, i.e. the iso_rr_path for the file object in the ISO image. The part after the first = is taken as source, i.e. the disk_path of the input object.

It is possible to make =-characters part of the iso_rr_path by preceding them with a \-character. The same must be done for \-characters which shall be part of the iso_rr_path.

If the source part of the pathspec leads to a directory, then all files underneath this directory get inserted into the image, too. It is possible to exclude particular files from being inserted by help of option -m.

In case that target already exists, the following rules apply:

  • Directories and other files may overwrite existing non-directories.
  • Directories get merged with existing directories.
  • Non-directories may not overwrite existing directories.

🧚 Relation to program xorriso: 🧚

xorrisofs is actually a command mode of program xorriso, which gets entered either by xorriso command "-as mkisofs" or by starting the program by one of the names "xorrisofs", "mkisofs", "genisoimage", or "genisofs".

This command mode can be left by argument "--" which leads to generic xorriso command mode. See man xorriso for its description.

xorriso performs image reading and writing by help of libburn, which is mainly intended for optical drives, but also operates on all POSIX file types except directories.

The program messages call any image file a "drive". File types which are not supported for reading are reported as "blank". The reported free media space may be quite fictional.

Nevertheless xorrisofs does not operate directly on optical drives, but rather forces libburn to regard them as general device files. So for writing of sequential optical media (CD, DVD-R, DVD+R, BD-R) one will have to use a burn program. E.g the cdrecord emulation of xorriso. See EXAMPLES.

💅 OPTIONS 💅

🍓 Image loading: 🍓

The following options control loading of an existing ISO image for the purpose of preparing a suitable add-on session. If they are missing then a new image is composed from scratch.

  • -M disk_path — Set the path from which to load the existing ISO image directory tree on which to base the upcoming directory tree as add-on session. The path must lead to a random-access readable file object. On GNU/Linux: regular data files or block device files. A special kind of pseudo disk_path has the form "/dev/fd/"number. It depicts the open file descriptor with the given number, regardless whether the operating system supports this feature by file nodes in /dev/fd or not. E.g. /dev/fd/3 is file descriptor 3 which was opened by the program that later started xorrisofs.
  • -prev-session disk_path — Alias of -M.
  • -dev disk_path — Alias of -M.
  • -C last_session_start,next_writeable_address — Set the 2 KiB block address last_session_start from where to read the ISO image out of the file given by option -M. Separated by a comma, set the next_writeable_address to which the add-on session will finally be written. Decisive is actually the block address which the intended readers will have to use as superblock address on the intended medium. Both values can be inquired from optical media by help of burn programs and cdrecord option -msinfo. xorriso itself can obtain it in its cdrecord emulation.
values=$(xorriso -as cdrecord dev=/dev/... -msinfo)
echo $values

Option -C may be used without option -M to create an ISO image from scratch and prepare it for being finally written to a block address other than 0. Parameter last_session_start must then be set to 0.

  • -cdrecord-params last_session_start,next_writeable_address — Alias of -C.

🌈 Settings for file insertion: 🌈

  • -path-list disk_path — Read pathspecs line-by-line from disk_file and insert the depicted file objects into the ISO image. If disk_path is - then read the pathspecs from standard input.
  • --quoted_path_list disk_path — Like option -path-list but reading quoted words rather than plain lines. Whitespace outside of quotes will be discarded. On the other hand it is possible to represent pathspecs which contain newline characters. The double quotation mark " and the single quotation mark ' can be used to enclose whitespace and make it part of pathspecs. Each mark type can enclose the marks of the other type. A trailing backslash \ outside quotations or an open quotation cause the next input line to be appended.
  • -cut_out disk_path byte_offset byte_count iso_rr_path — Map a byte interval of a regular disk file or of a device file into a regular file in the ISO image. The file depicted by disk_path has to support random read access. byte_offset and byte_count may be plain numbers counting bytes, or numbers with appended letter "d", "s", "k", "m", "g" to count disk blocks (512 bytes), disc sectors (2048 bytes), KiB (1024 bytes), MiB (1024 KiB), or GiB (1024 MiB). E.g:
-cut_out bootable.iso 562s 18s /formerly_hidden_boot_image
  • -f — Resolve symbolic links on disk rather than storing them as symbolic links in the ISO image.
  • -follow-links — Alias of -f.
  • -graft-points — Enable interpretation of input file pathspecs as combination of iso_rr_path and disk_path, separated by a =-character.
  • -m disk_pattern — Exclude files from being inserted into the image. Silently ignored are those files of which the disk_path matches the given shell parser pattern. If no /-character is part of the pattern, then it gets matched against the leaf name of the disk file. It is possible to give more than one -m option.
  • -exclude — Alias of -m.
  • -x — Alias of -m.
  • -old-exclude — Alias of -m.
  • -exclude-list disk_path — Perform -m using each line out of file disk_path as argument disk_pattern.
  • -z — Enable recognition and proper processing of zisofs compressed files as produced by program mkzftree. These files will get equipped with the necessary meta data so that a Linux kernel will recognize them and deliver their content in uncompressed form.
  • -transparent-compression — Alias of -z.
  • --zisofs-version-2 — Enable the recognition and proper processing of experimental zisofs version 2 compressed files. The Linux kernel (as of 5.9) does not yet know this format and will complain like
isofs: Unknown ZF compression algorithm: PZ

This complaint can be prevented by option --zisofs2-susp-z2. The files will be shown by unaware kernels as they were submitted to xorrisofs, i.e. with zisofs2 header, block pointer list, and compressed data. --zisofs-version-2 also enables -z.

  • --zisofs2-susp-z2 — ok so this one flips on the making of SUSP entries called "Z2" instead of "ZF" when you're doing zisofs2 compressed files 💖. Why tho? Because Linux kernels that don't know about it will just silently ignore "Z2" entries. Quiet. Peaceful. No drama ✨.
  • --zisofs2-susp-zf — and this flips it the other way: make SUSP entries "ZF" instead of "Z2" for zisofs2 compressed files. Warning tho bestie: kernels that don't understand zisofs2 will complain about a zisofs2 "ZF" with "Unknown ZF compression algorithm" and like... leave a little receipt in the system log 😭. So it's giving messy.
  • -root iso_rr_path — insert every single file that lives under the given iso_rr_path 🫶. And if -graft-points is also on the scene, then iso_rr_path gets prepended to each target part of a pathspec. The default for -root? That's "/" 💅.
  • -old-root iso_rr_path — this one enables incremental insertion of files into the loaded image, iykyk. What it does: it compares the effective target and source addresses of the pathspecs you gave it, checking whether the target already exists in the ISO image and is still identical to the source on disk. If the metadata in the ISO image doesn't match what's on disk, it gets adjusted 🎀. Brand-new files and files whose content changed get newly added ✨. And target files that don't exist in any of the according pathspec sources? They get removed from the ISO directory tree, periodt. Oh and also — if the effective setting of -root differs from the iso_rr_path you gave with -old-root, then the files underneath the -old-root directory get cloned underneath the -root directory 🌸. Cloning happens before file comparison, no cap.
  • --old-root-no-ino — disables recording and use of disk inode numbers. And like, if no disk inode numbers are recorded, then -old-root has to actually read the disk file content and compare it against the MD5 checksum recorded in the ISO image 😮‍💨. With recorded disk inode numbers plus credible ctime and mtime, you can spot potential content changes without actually reading it — slay. But there's a loophole: if multiple different filesystems can get mounted at the same directory, like the whole /mnt habit 🫠, then you gotta use --old-root-devno or just kill the inode number shortcut with --old-root-no-ino.
  • --old-root-devno — turns on comparison of recorded device numbers together with recorded inode numbers 🔥. Small problem tho: this only works with good old stable device numbers, which are getting out of fashion, regrettably 💀. If your hard disk gets a different device number after each reboot, then this comparison will see all files as changed and therefore prevent any incremental size saving. Not it.
  • --old-root-no-md5 — disables recording and use of MD5 checksums for data file content. And if neither checksums nor disk inode numbers are recorded, then -old-root has to read the ISO image file content when comparing it with disk file content 😭. Full read, bestie. No shortcuts.

🎀 Settings for image production 🎀

  • -o disk_path — sets the output file address for the emerging ISO image 🌟. If that address already exists as a regular file, it gets truncated to length 0 when image production begins. It may not already exist as a directory 🚫. And if it doesn't exist yet, then its parent directory must exist and a regular file will get created ✨. There's also a special kind of pseudo disk_path that looks like "/dev/fd/"number — it depicts the open file descriptor with that given number, regardless of whether your operating system supports this feature via file nodes in /dev/fd or not. E.g. /dev/fd/4 is file descriptor 4, which was opened by the program that later started xorriso 👑. Default is standard output (/dev/fd/1), which you can also set with the disk_path "-" 💅.
  • -output disk_path — literally just an alias of -o. Same energy 🫶.
  • --stdio_sync "on"|"off"|"end"|number — sets the number of bytes after which output gets forced to disk, so your memory doesn't get clogged with a ton of pending data for slow devices 😮‍💨. "on" is the same as "16m". You can disable forced output with "off", or delay it with "end" until all data are produced. And if you pick a number, it must be at least 64k ⚠️. Default with xorriso mkisofs emulation is --stdio_sync "off". Also, xorriso uses an inner fifo buffer with default size 4 MiB, so forcing the operating system i/o cache to disk does not necessarily block the simultaneous production of more image content ✨.
  • --emul-toc — writes a second superblock with the first session into random-access files 🦋. So if further sessions get appended and the first superblock gets updated, that second superblock will not get overwritten. Which means it's still possible to mount the first session and find the start blocks of the further sessions, iconic 💖. The price? 64 KiB extra space consumption. And if -partition_offset is non-zero, then it's 128 KiB plus twice the partition offset 💸.
  • --no-emul-toc — do not write a second superblock with the first session into random-access files. This is the default, bestie 🎀.
  • --sort-weight weight_number iso_rr_path — attributes an LBA weight number to regular files 💅. If iso_rr_path leads to a directory, then all regular files underneath it will get the weight_number. The weight_number may range from -2147483648 to 2147483647. The higher it is, the lower will be the block address of the file data in the emerging ISO image 📉. Currently the El Torito boot catalog has a hardcoded weight of 1 billion 👑. Normally it should occupy the block with the lowest possible address. Data files get added or loaded with initial weight 0, and boot image files have a default weight of 2 ⭐.
  • --sort-weight-list disk_path — reads pairs of weight number and iso_rr_path from a file on the local filesystem, then applies each pair like with --sort-weight 🫶. Only the last --sort-weight-list or --sort-weight-patterns of a xorrisofs run gets into effect — so, last one wins, periodt. The weight number is read from the start of the line 📝. The iso_rr_path part of an input line begins immediately after the first blank or tab character of the line. Notes for the case that this feature is used within a sequence of generic xorriso commands (not an issue with a pure mkisofs emulation run): the addressed files must already be in the ISO image model when you execute
-as mkisofs --sort-weight-list disk_path --

Several such commands may be used to apply more than one weight file ✨. And data files which are loaded by -indev or -dev get a weight between 1 and 2 exp 28 = 268,435,456, depending on their block address. This shall keep them roughly in the same order if the write method of modifying is applied 🌸.

  • --sort-weight-patterns disk_path — like --sort-weight-list, but it expands the iso_rr_paths as shell parser patterns and applies --sort-weight to each matching file 🦋. Globbing but make it weight.
  • -uid number|name — use the given number or locally existing user name as the owner id of all files and directories in the emerging filesystem 👑. Empty name or the name "-" revoke this feature.
  • -gid number|name — same vibe as above but for the group id 💜. Use the given number or locally existing group name as the group id of all files and directories in the emerging filesystem. Empty name or the name "-" revoke this feature.
  • -dir-mode mode — sets the access permissions for all directories in the image to the given mode, which is either an octal number beginning with "0" or a comma separated list of statements of the form [ugoa]*[+-=][rwxst]* 💅. E.g. ug=rx,a-rwx.
  • -file-mode mode — like -dir-mode but for all regular data files in the image 🎀.
  • -pad — adds 300 KiB to the end of the produced ISO image ✨. This circumvents possible read errors from ISO images which have been written to CD media in TAO mode 🫠. The additional bytes are claimed as part of the ISO image if not --emul-toc is given. Option -pad is the default 👑.
  • -no-pad — disables padding of 300 KiB to the end of the produced ISO image. This is safe if the image is not meant to be written on CD, or if it gets written to CD as only track in write mode SAO 🫶.
  • --old-empty — use the old way of giving block addresses in the range of [0,31] to files with no own data content 💀. The new way is to have a dedicated block to which all such files will point.

🌈 Settings for standards compliance 🌈

  • -iso-level number — specifies the ISO 9660 version, which defines the limitations of file naming and data file size 📏. Note: the naming restrictions do not apply to the Rock Ridge names, only to the low-level ISO 9660 names ✨. There are three conformance levels:
    • Level 1 allows ISO names of the form 8.3 and file size up to 4 GiB - 1.
    • Level 2 allows ISO names with up to 32 characters and file size up to 4 GiB - 1.
    • Level 3 allows ISO names with up to 32 characters and file size of up to 400 GiB - 200 KiB. (This size limitation is set by the xorriso implementation and not by ISO 9660, which would allow nearly 8 TiB 👀.)

Pseudo-level 4 enables production of an additional directory tree beginning at an Enhanced Volume Descriptor (aka ISO 9660:1999) as of ECMA-119 4th Edition 🦋.

  • -disallow_dir_id_ext — do not follow a bad habit of mkisofs which allows dots in the ISO names of directories 🚫. On the other hand, some bootable GNU/Linux images depend on this bad habit 😭. So like... choose wisely.
  • -U — this option allows ISO file names without a dot and up to 37 characters, ISO file paths longer than 255 characters, and all ASCII characters in file names 🔥. Further, it omits the semicolon and the version numbers at the end of ISO names. This all violates ISO 9660 specs ⚠️. Living dangerously, we love that.
  • -untranslated-filenames — alias of -U 💅.
  • -untranslated_name_len number — allow ISO file names up to the given number of characters without any character conversion. The maximum number is 96 📏. If a file name has more characters than that, then image production will fail deliberately 💀. This violates ISO 9660 specs ⚠️.
  • -allow-lowercase — allow lowercase characters in ISO file names. This violates ISO 9660 specs ⚠️. Rebel behaviour, honestly 💅.
  • -relaxed-filenames — okay so this one lets ISO file names use basically every 7-bit character 💅. The only two that are NOT allowed: 0x0 and /. And if you haven't also passed -allow-lowercase, then all your lowercase letters get yanked up to uppercase. Heads up bestie, this violates ISO 9660 specs 🙈.
  • -d — don't tack a trailing dot onto ISO file names that don't have a dot. That's it. And yeah, this violates ISO 9660 specs.
  • -omit-period — just an alias of -d, same energy 🫶.
  • -l — ISO file names can go up to 31 characters. That's the whole vibe ✨.
  • -full-iso9660-filenames — alias of -l. Twins fr fr.
  • -max-iso9660-filenames — now we're allowing up to 37 characters in ISO file names 👑. And yes, this violates ISO 9660 specs.
  • -N — drop the semicolon and the version numbers hanging off the end of ISO names. Cute? Yes. Spec-legal? Absolutely not, this violates ISO 9660 specs 💀.
  • -omit-version-number — alias of -N. Same thing, different name, iykyk.

🎀 Settings for standards extensions 🎀

  • -R — with mkisofs this option turns on Rock Ridge extensions. But here's the tea: xorrisofs produces them by default 🌸. So it is strongly discouraged to turn them off with --norock.
  • -rock — alias of -R. periodt.
  • -r — enable Rock Ridge and set the user and group id of every single file in the ISO image to 0. Grant r-permissions to all. Deny all w-permissions. If any x-permission is set, grant x-permission to all. Remove s-bit and t-bit 🔥.

These attribute changes stay delayed until mkisofs emulation ends. And within that same -as mkisofs emulation command, they can be revoked by a subsequent option --norock. For compatibility reasons, option -R does not revoke the changes ordered by -r.

  • -rational-rock — alias of -r. iconic.
  • --norock — this one disables the production of Rock Ridge extensions for the ISO 9660 file objects 😭. Real talk: the multi-session capabilities of xorrisofs depend much on the naming fidelity of Rock Ridge, so it is strongly discouraged to disable it with this option — except for the special use case of revoking the effect of -r by doing:
--norock -R
  • --set_all_file_dates timestring — sets mtime, atime, and ctime of all files and directories to the time you give it 🕰️.

Valid timestring formats are: 'Nov 8 14:51:13 CET 2007', 110814512007.13, 2007110814511300. Also see --modification-date= and man xorriso, Examples of input timestrings.

If the timestring is "set_to_mtime", then the atime and ctime of each file and directory get set to the value found in their mtime.

These actions stay delayed until actual ISO production begins. Up to then they can be revoked by --set_all_file_dates with an empty timestring or timestring "default".

The timestamps of the El Torito boot catalog file get refreshed when the ISO is produced. They can be influenced by --modification-date=.

  • -file_name_limit number — sets the maximum permissible length for file names in the range of 64 to 255. Path components longer than the given number get truncated, and their last 33 bytes get overwritten by a colon ':' plus the hex representation of the MD5 of the first 4095 bytes of the whole oversized name. Any potential incomplete UTF-8 characters get their leading bytes replaced by '_' 🦋.

Big warning bestie: Linux kernels up to at least 4.1 misrepresent names of length 254 and 255 😭. So if you expect such names in or under disk_paths and you plan to mount the ISO with such Linux kernels, consider setting -file_name_limit 253.

  • -D — the standard ECMA-119 demands that no path in the image shall have more than 8 name components or 255 characters. So normally it'd be necessary to move deeper directory trees to a higher directory. Rock Ridge offers an opportunity to let these relocated directories appear at their original deep position, but this feature might not be implemented properly by operating systems which mount the image 🙈.

Option -D disables this deep directory relocation, and thus violates ISO 9660 specs.

xorrisofs has -D set by default. If given explicitly, then it overrides the options -rr_reloc_dir and -hide-rr-moved.

  • -disable-deep-relocation — alias of -D.
  • -rr_reloc_dir name — enables the relocation of deep directories, which avoids ECMA-119 file paths of more than 8 name components or 255 characters ✨. Directories that lead to such file paths get moved to a directory in the root directory of the image, and its name gets set by this option. It is permissible to use the root directory itself.

The overall directory tree will appear originally deep when interpreted as a Rock Ridge tree. It will appear as re-arranged if only ECMA-119 information is considered.

If the given relocation target directory doesn't already exist when image production begins, then it gets created and marked for Rock Ridge as a relocation artefact. At least on GNU/Linux it will not be displayed in mounted Rock Ridge images.

The name must not contain a '/' character after its first character, and it must not be longer than 255 bytes.

This option has no effect if option -D is present.

  • -hide-rr-moved — alias of -rr_reloc_dir "/.rr_moved" 💜.
  • -long-rr-time — force use of the long form of RockRidge timestamps. This form is not understood by Linux kernels older than 6.16, but it can represent times after the end of year 2155 up to year 9999 and down to year 0 (= 1 BC) 🌈.

Without this option, xorriso will use this form only with individual files or directories whose atime, ctime, or mtime is after 01 Jan 2150 UTC or before 01 Jan 1900 UTC. (The six years up to 2156 may serve as last opportunity to enhance readers after libisofs was changed to continue using the short form.)

  • -short-rr-time — re-enables the default behavior of using the long form of RockRidge timestamps only for files with timestamps after 01 Jan 2150 UTC or before 01 Jan 1900 UTC.
  • -no-long-rr-time — alias of -short-rr-time.
  • -rr-time-y1900 — restrict Rock Ridge timestamps to at least Jan 1 1900 UTC 🕰️. This may be desirable because the Linux kernel up to at least version 6.16 misrepresents times before year 1900 as Jan 1 1970 00:00:00 UTC.

Without this option, timestamps down to year 0 (= 1 BC) may be written as long form Rock Ridge timestamps.

  • --for_backup — turns on all the options that improve backup fidelity: --acl, --xattr-any, --md5, --hardlinks, --projid, and possibly --lfa_flags 👑.

If you later restore a backup with xattr from non-user namespaces, then make sure that the target operating system and filesystem know what these attributes mean. Possibly you'll need administrator privileges to record or restore such attributes. At recording time, xorriso will try to tolerate missing privileges and just record what is readable.

Option --xattr after option --for_backup excludes non-user attributes from being recorded.

Option --for_backup enables --lfa_flags only if the underlying libisofs was compiled with support for Linux file attributes — which is typically not the case on non-Linux systems 💀.

  • --acl — enable recording and loading of ACLs from GNU/Linux or FreeBSD (see man getfacl, man acl). They will not be in effect with mounted ISO images. But xorriso can restore them on the same systems when extracting files from the ISO image 🫶.
  • --xattr — enable recording and loading of GNU/Linux or FreeBSD extended attributes in the user namespace (see man getfattr and man attr, man getextattr and man 9 extattr, respectively). They will not be in effect with mounted ISO images. But xorriso can restore them on the same systems when extracting files from the ISO image ✨.
  • --xattr-any — enable recording and loading of GNU/Linux or FreeBSD extended attributes in all namespaces. This might need administrator privileges, even if the owner of the disk file tries to read the attributes 😭.
  • --lfa_flags — enable recording and loading of Linux file attributes as described in man 1 chattr.

Disable restoring of such attributes just in case the mkisofs emulation gets ended and files get restored to disk. If restoring of the attributes is desired in this case, execute the xorriso command -lfa_flags "restore" with possibly appended mode texts like :restore_mask=aAcdDijmPsStTux.

  • --projid — enable recording and loading of XFS-style project ids as described in man 5 xfs_quota or man 5 ext4 🦋.
  • --md5 — enable recording of MD5 checksums for the overall ISO image and for each single data file in the image. xorriso can check the content of an ISO image with these sums and raise an alert on mismatch. See man xorriso, options -check_media, check_md5_r.

xorriso can also print recorded MD5 checksums, e.g. by:

-find / -exec get_md5
  • --hardlinks — enable loading and recording of hardlink relations 🔗. Search for families of iso_rr files which stem from the same disk file, have identical content filtering and have identical properties. The members of each family get the same inode number in the ISO image.

Whether these numbers are respected at mount time depends on the operating system. xorriso can create hardlink families when extracting files from the ISO image.

  • --scdbackup_tag disk_path record_name — append a scdbackup checksum record to the image. This works only if the parameter next_writeable_address of option -C is 0 and --md5 is enabled 💅. If disk_path is not an empty string, then append a scdbackup checksum record to the end of this file. record_name is a word that gets part of tag and record. Program scdbackup_verify will recognize and verify tag and file record.

An empty record_name disables this feature.

  • -J — enable the production of an additional Joliet directory tree along with the ISO 9660 Rock Ridge tree 🌈.
  • -joliet — alias of -J. iconic.
  • -joliet-long — okay so Joliet file names normally cap at 64 characters, right? This lets them go all the way to 103 characters, which is way more than the spec says is allowed. It also lets Joliet paths blow past the prescribed limit of 240 characters. The way this works: oversized names just get truncated. And if you don't turn this on? Oversized paths get straight up excluded from the Joliet tree. gone. not invited. 🫶
  • -joliet-utf16 — encode Joliet file names in UTF-16BE instead of UCS-2. The difference only shows up with characters that aren't in UCS-2, which then get encoded in UTF-16 by 2 words of 16 bit each. Both of those words then come from a reserved subset of UCS-2. it's giving "technically still valid" energy 💅
  • -hfsplus — turn on production of an additional HFS+ filesystem inside the ISO 9660 image, and mark it with Apple Partition Map (APM) entries in the System Area — that's the first 32 KiB of the image.

Heads up bestie, this can collide with options like -G or -isohybrid-mbr that submit user data for inclusion in that same address range. The first 8 bytes of the System Area get overwritten by { 0x45, 0x52, 0x08 0x00, 0xeb, 0x02, 0xff, 0xff } — which, fun fact, can be executed as x86 machine code without negative effects. So if an MBR gets combined with this feature, its first 8 bytes should contain no essential commands. 👑

The next blocks of 2 KiB in the System Area get occupied by APM entries. The first one covers the part of the ISO image before the HFS+ filesystem metadata. The second one marks the range from HFS+ metadata to the end of file content data. And if more ISO image data follows? Boom, a third partition entry gets produced. Other features of xorriso might cause the need for even more APM entries. it just keeps going 😭

Be aware that HFS+ is case-insensitive even though it can record file names with upper-case and lower-case letters. So file names from the iso_rr name tree may collide in the HFS+ name tree. When that happens they get changed by adding underscore characters and counting numbers. And in the case of very long names, it might be necessary to map them to "MANGLED_...". so dramatic 💀

WARNING: The HFS+ implementation in libisofs has a limit of 125,829,120 bytes for the size of the overall directory tree. That suffices for about 300,000 files of normal name length. If the limit gets exceeded, a FAILURE event will be issued and the ISO production will not happen. no image for you, bestie. periodt.
  • -hfsplus-serial-no — set a string of 16 digits "0" to "9" and letters "a" to "f", which gets used as the unique serial number of an emerging HFS+ filesystem. 🔢
  • -hfsplus-block-size number — set the allocation block size used when producing HFS+ filesystems. Permissible values are 512, 2048, or 0. The 0 lets the program decide. (letting the program decide is lowkey the move ngl)
  • -apm-block-size number — set the block size used when describing partitions by an Apple Partition Map. Permissible are 512, 2048, or 0, and again the 0 lets the program decide.

Note that size 512 is not compatible with production of GPT, and size 2048 will not be mountable -t hfsplus — at least by older Linux kernels. so pick your fighter wisely 🌸

  • -hfsplus-file-creator-type creator type iso_rr_path — set the HFS+ creator and type attributes of a file in the emerging image. These are two codes of 4 characters each. cute little tags for your file 🎀
  • -hfs-bless-by blessing iso_rr_path — issue a HFS+ blessing. Blessings are roles which can be attributed to up to four directories and a data file:
    • "ppc_bootdir"
    • "intel_bootfile"
    • "show_folder"
    • "os9_folder"
    • "osx_folder"

They may be abbreviated as "p", "i", "s", "9", and "x". Each such role can be attributed to at most one file object. "intel_bootfile" is the one that would apply to a data file; all the others apply to directories. And no file object can bear more than one blessing. one blessing per file, no greediness 🙅‍♀️

  • -hfs-bless disk_path — issue HFS+ blessing "ppc_bootdir" to the directory which stems from the directory disk_path in the local filesystem tree. This works only if there's at least one data file underneath the directory.

Heads up: disk_path can become ambiguous if files from different local filesystem sub-trees are put into the same sub-tree of the ISO image. Consider using -hfs-bless-by "p" for unambiguous addressing via iso_rr_path. much cleaner, trust ✨

✨ Settings for file hiding ✨

  • -hide disk_path_pattern — make files invisible in the directory tree of ISO 9660 and Rock Ridge if their disk_path matches the given shell parser pattern.

The data content of such hidden files will still be included in the resulting image, even if they don't show up in any directory. But bestie, you'll need your own means to find nameless data in the image. it's a ghost with a body 💀

This command does not apply to the boot catalog.

  • -hide-list disk_path — perform -hide using each line out of file disk_path as argument disk_path_pattern. bulk hiding, we love efficiency 🦋
  • -hide-joliet disk_path_pattern — like option -hide but making files invisible in the directory tree of Joliet, if their disk_path matches the given shell parser pattern.
  • -hide-joliet-list disk_path — perform -hide-joliet using each line out of file disk_path as argument disk_path_pattern.
  • -hide-hfsplus disk_path_pattern — like option -hide but making files invisible in the directory tree of HFS+, if their disk_path matches the given shell parser pattern.
  • -hide-hfsplus-list disk_path — perform -hide-hfsplus using each line out of file disk_path as argument disk_path_pattern.
  • -hide_iso_path hide_state iso_rr_path — prevent the name of the given file from showing up in the directory trees of ISO 9660 and/or Joliet and/or HFS+ when the image gets written. Other than the above hide options, this one takes the path of a file in the emerging ISO filesystem, not the path of a file on hard disk. 👀

Possible values of hide_state are: "iso_rr" for hiding from the ISO 9660 tree, "joliet" for the Joliet tree, "hfsplus" for HFS+, "on" for them all. And "off" means visibility in all directory trees.

These values may be combined. E.g.: joliet:hfsplus

This command does not apply to the boot catalog. Rather use: --boot-catalog-hide

✨ ISO image ID strings ✨

The following strings and file addresses get stored in the Volume Descriptors of the ISO 9660 image. The file addresses are ISO 9660 paths. These files should have iso_rr_paths which consist only of the characters [A-Z0-9_] and exactly one dot which separates at most 8 characters from at most 3 characters.

It depends on the setting of -relaxed_pvd_atts whether the strict rules for the character sets of these strings and file addresses are enforced when written to the Primary Volume Descriptor. so yes, the vibes of your strings are being policed 🌈

  • -relaxed_pvd_atts mode — control whether to enforce the strict rules for the character sets which are permissible in text fields of the ISO 9660 Primary Volume Descriptor. Default is mode "vol".

The fields Volume Id and Volume Set Id are restricted by the specs to "d-characters", i.e. the set [0-9A-Z_]. This restriction is lifted by the modes "vol" or "on", but not by "nonvol".

The fields Copyright File, Abstract File, and Biblio File are restricted to [0-9A-Z_.;] ("d-characters") plus at most one . and at most one ; which must not come before the dot.

The fields Publisher Id, Application Id, System Id, and Data Preparer Id are restricted to "a-characters", i.e. the set [ !"%&'()*+,./0-9:;<=>?A-Z_-]. These restrictions are lifted by the modes "nonvol" or "on", but not by "vol".

Mode "off" enforces the rules for both mentioned groups of fields. Enforcement with "off", "vol", or "nonvol" is done by mapping the letters [a-z] to [A-Z] and other disallowed characters to _.

Note: The characters '[' and ']' are not part of the permitted sets but rather used here as set delimiters like with regular expressions. iykyk 💅
  • -volid_for fs_types text — set the Volume Id for one or more filesystem types of the ISO image.

A xorriso made ISO 9660 image may offer four different filesystems for mounting: ISO 9660 aka ECMA-119 (normally with Rock Ridge), Joliet, ISO 9660:1999, and HFS+. The parameter fs_types chooses the types for which the Volume ID shall be set by the -volid_for command. It's a comma separated list of keywords out of "ecma119", "joliet", "iso_9660_1999", "hfsplus". Keyword "all" chooses all four types. Example:

  -volid_for joliet "Joliet Volume Id"
  -volid_for ecma119,iso_9660_1999 "LONGER_ISO_VOLUME_ID"

xorriso accepts any text up to 32 characters, but according to rarely obeyed specs stricter rules apply:

  • Conformant are ASCII characters out of [A-Z0-9_]. Like: "IMAGE_23"
  • xorriso warns if the submitted text does not comply. If -relaxed_pvd_atts is set to "off" or "nonvol", then the text is mapped to specs compliant characters.
  • Joliet allows 16 UCS-2 characters. Longer texts cause a warning and get truncated.
  • ISO 9660:1999 allows arbitrary characters of the output character set.
  • HFS+ allows UTF-16BE characters which have to be suitable for a file name.

Be aware that the volume id might get used automatically as name of the mount point when the medium is inserted into a playful computer system. main character moment for your volume id 🫶

  • -V text — specify the volume ID for all filesystem types. I.e. perform -volid_for "all" with the given parameter text.
  • -volid text — alias of -V. same vibe, shorter name ✨
  • -volset text — set the Volume Set Id of the ISO image. Permissible are up to 128 d-characters (see -relaxed_pvd_atts).
  • -P text — set the Publisher Id of the ISO image. This may identify the person or organisation who specified what shall be recorded. Permissible are up to 128 a-characters (see -relaxed_pvd_atts).
  • -publisher text — alias of -P.
  • -A text — set the Application Id of the ISO image. This may identify the specification of how the data are recorded. Permissible are up to 128 a-characters (see -relaxed_pvd_atts).

The special text "@xorriso@" gets converted to the id string of xorriso, which is normally written as Preparer Id. It is a wrong tradition to write the program id as Application Id. ngl, we've all done it 🙈

  • -appid text — alias of -A.
  • -sysid text — sets the System Id of the ISO image. Bestie, this may identify the system which can recognize and act upon the content of the System Area in image blocks 0 to 15. Permissible are up to 32 a-characters (see -relaxed_pvd_atts). ✨
  • -p text — sets the Preparer Id of the ISO image. This may identify the person or other entity which controls the preparation of the data which shall be recorded. Normally this should be the id of xorriso and not of the person or program which operates xorriso. Please avoid to change it. Permissible are up to 128 a-characters (see -relaxed_pvd_atts). The special text "@xorriso@" gets converted to the id string of xorriso which is default at program startup. 💅
  • -preparer text — Alias of -p. 🎀
  • -abstract iso_path — sets the address of the Abstract File of the ISO image. This should be the ISO 9660 path of a file in the image which contains an abstract statement about the image content. Permissible are up to 37 d-characters plus '.' and ';' (see -relaxed_pvd_atts). 🦋
  • -biblio iso_path — sets the address of the Biblio File of the ISO image. This should be the ISO 9660 path of a file in the image which contains bibliographic records. Permissible are up to 37 d-characters plus '.' and ';' (see -relaxed_pvd_atts). 🌸
  • -copyright iso_path — sets the address of the Copyright File of the ISO image. This should be the ISO 9660 path of a file in the image which contains a copyright statement. Permissible are up to 37 d-characters plus '.' and ';' (see -relaxed_pvd_atts). 💖
  • --modification-date=YYYYMMDDhhmmsscc — sets a timestring that overrides ISO image creation and modification timestamps literally. It must consist of 16 decimal digits which form YYYYMMDDhhmmsscc, with YYYY between 0000 and 9999. Time zone is GMT. It is supposed to match this GRUB line:
search --fs-uuid --set YYYY-MM-DD-hh-mm-ss-cc

E.g. 2010040711405800 is 7 Apr 2010 11:40:58 (+0 centiseconds). Among the influenced timestamps are: isohybrid MBR id, El Torito boot catalog file, HFS+ superblock. 🔥

  • --application_use character|0xXY|disk_path — specifies the content of the Application Use field which can take at most 512 bytes. If the parameter of this command is empty, then the field is filled with 512 0-bytes. If it is a single character, then it gets repeated 512 times. If it begins by "0x" followed by two hex digits [0-9a-fA-F], then the digits are read as byte value which gets repeated 512 times. Any other parameter text is used as disk_path to open a data file and to read up to 512 bytes from it. If the file is smaller than 512 bytes, then the remaining bytes in the field get set to binary 0. 🌈

✨ El Torito Bootable ISO images: ✨

Okay so the precondition for a bootable ISO image is to have in the ISO image the files of a boot loader. The boot facilities of computers get directed to such files, which usually execute further program files from the ISO image. xorrisofs can produce several kinds of boot block or boot record, which become part of the ISO image, and get interpreted by the according boot facility. No cap. 🫶

An El Torito boot record points the bootstrapping facility to a boot catalog with one or more boot images, which are binary program files stored in the ISO image. The content of the boot image files is not in the scope of El Torito. xorriso composes the boot catalog according to the boot image files given and structured by options -b, -e, -eltorito-alt-boot, and --efi-boot. Often it contains only one entry. Normally the boot images are data files inside the ISO filesystem. By special path "--interval:appended_partition_NNN:all::" it is possible to refer to an appended partition. The number NNN gives the partition number as used with the corresponding option -append_partition. E.g.:

-append_partition 2 0xef /tmp/efi.img
-e --interval:appended_partition_2:all::

El Torito gets interpreted by boot facilities PC-BIOS and EFI. Most bootable GNU/Linux CDs are equipped with ISOLINUX or GRUB boot images for PC-BIOS. xorrisofs supports the example options out of the ISOLINUX wiki, the options used in GRUB script grub-mkrescue, and the example in the FreeBSD AvgLiveCD wiki. 💅

For CD booting via boot facilities other than PC-BIOS and EFI, and for booting from USB sticks or hard disks, see the next section about the System Area. 👑

  • -b iso_rr_path — specifies the boot image file which shall be mentioned in the current entry of the El Torito boot catalog. It will be marked as suitable for PC-BIOS. With boot images from ISOLINUX and GRUB this option should be accompanied by options -c, -no-emul-boot, -boot-load-size 4, -boot-info-table. 🔥
  • -eltorito-boot iso_rr_path — Alias of -b. 🎀
  • -eltorito-alt-boot — finalizes the current El Torito boot catalog entry and begins a new one. A boot image file and all its necessary options shall be specified before option -eltorito-alt-boot. All further El Torito boot options apply to the new catalog entry. Up to 32 catalog entries are possible. 🌟
  • -e iso_rr_path — specifies the boot image file which shall be mentioned in the current entry of the El Torito boot catalog. It will be marked as suitable for EFI. Option -e should be followed by option -no-emul-boot and no other El Torito options before an eventual -eltorito-alt-boot. 💜
  • --efi-boot iso_rr_path — performs -eltorito-alt-boot, option -e with the given iso_rr_path, -no-emul-boot, and again -eltorito-alt-boot. This gesture is used for achieving EFI-bootability of the GRUB2 rescue CD. ✨
  • -eltorito-platform "x86"|"PPC"|"Mac"|"efi"|0xnn|nnn — sets the Platform Id number for the next option -b or -eltorito-boot. The number may be chosen by a platform name or by a number between 0 and 255 (0x00 and 0xFF). "x86" = 0 is for PC-BIOS, "PPC" = 1 for some PowerPC systems, "Mac" = 2 for some MacIntosh systems, "efi" = 0xEF for EFI on modern PCs with x86 compatible CPUs or others. If the new platform id differs from the previous one, -eltorito-alt-boot gets performed. 🦋
  • -boot-load-size number|"full" — sets the number of 512-byte blocks to be loaded at boot time from the boot image in the current catalog entry. Non-emulating BIOS bootimages usually need a load size of 4. Nevertheless the default setting of mkisofs is to use the full size of the boot image rounded up to a multiple of 4 512-byte blocks. This default may be explicitly enforced by the word "full" instead of a number. EFI boot images always get set the number of blocks occupied by the boot image file. El Torito cannot represent load sizes higher than 65535. EFI images which exceed the maximum size get size 0 or 1, which means "up to the end of the device" according to the UEFI specification. 😭
  • -hard-disk-boot — marks the boot image in the current catalog entry as emulated hard disk. (Not suitable for any known boot loader.) 💀
  • -no-emul-boot — marks the boot image in the current catalog entry as not emulating floppy or hard disk. (This is to be used with all known boot loaders.) If neither -hard-disk-boot nor -no-emul-boot is given, then the boot image will be marked as emulating a floppy. (Not suitable for any known boot loader.) 🫶
  • -eltorito-id text|56_hexdigits — defines the ID string of the boot catalog section where the boot image will be listed. If the value consists of 56 characters [0-9A-Fa-f] then it is converted into 28 bytes, else the first 28 characters become the ID string. The ID string of the first boot image becomes the overall catalog ID. It is limited to 24 characters. Other id_strings become section IDs. 🌈
  • -eltorito-selcrit hexdigits — defines the Selection Criteria of the boot image. Up to 20 bytes get read from the given characters [0-9A-Fa-f]. They get attributed to the boot image entry in the catalog. ⭐
  • -boot-info-table — overwrites bytes 8 to 63 in the current boot image. The information will be supplied by xorriso in the course of image production: Block address of the Primary Volume Descriptor, block address of the boot image file, size of the boot image file. 💅
  • --grub2-boot-info — overwrites bytes 2548 to 2555 in the current boot image by the address of that boot image. The address is written as 64 bit little-endian number. It is the 2KB block address of the boot image content, multiplied by 4, and then incremented by 5. 🔥
  • -c iso_rr_path — sets the address of the El Torito boot catalog file within the image. This file address is not significant for the booting PC-BIOS or EFI, but it may later be read by other programs in order to learn about the available boot images. 👑
  • -eltorito-catalog iso_rr_path — Alias of -c. 🎀
  • --boot-catalog-hide — prevents the El Torito boot catalog from appearing as file in the directory trees of the image. 🙈

🌸 System Area, MBR, GPT, APM, other boot blocks: 🌸

The first 16 blocks of an ISO image are the System Area. It is reserved for system dependent boot software. This may be the boot facilities and partition tables of various hardware architectures. A MBR (Master Boot Record) contains boot code and a partition table. It is read by PC-BIOS when booting from USB stick or hard disk, and by PowerPC CHRP or PReP when booting. An MBR partition with type 0xee indicates the presence of GPT. A GPT (GUID Partition Table) marks partitions in a more modern way. It is read by EFI when booting from USB stick or hard disk, and may be used for finding and mounting a HFS+ partition inside the ISO image. An APM (Apple Partition Map) marks the HFS+ partition. It is read by Macs for booting and for mounting. MBR, GPT and APM are combinable. APM occupies the first 8 bytes of MBR boot code. All three do not hamper El Torito booting from CDROM. xorrisofs supports further boot facilities: MIPS Big Endian (SGI), MIPS Little Endian (DEC), SUN SPARC, HP-PA, DEC Alpha. Those are mutually not combinable and also not combinable with MBR, GPT, or APM. 💖

okay so bestie, some of the next options are like “gimme a disk path” but they’re also lowkey flexible and will accept description strings for the libisofs interval reader. That reader can cut data out of disk files or -indev and zeroize chunks of the content. The options that play this game are: -G, -generic-boot, --embedded-boot, --grub2-mbr, -isohybrid-mbr, -efi-boot-part, -prep-boot-part, -B, -sparc-boot, -append_partition.

The description string is built from these components, separated by a colon : 🎀

"--interval:"Flags":"Interval":"Zeroizers":"Source

The "--interval" component is literally saying “bestie, this is not a plain disk path, it’s an interval reader description string.”

The Flags component changes how everything else gets read:

  • "local_fs" — read from a file shown by the path in Source.
  • "imported_iso" — read from -indev. This only works if -outdev is not the same as -indev. The Source component is ignored.
  • "appended_partition_NNN" — with a decimal number NNN, works only for options that announce El Torito boot image paths: -b, -e, --efi-boot. That number is the partition number used with the matching -append_partition option.

The Interval component is two byte address numbers separated by a - character. Like "0-429" means read bytes 0 to 429.

The Zeroizers component is zero or more comma-separated strings. They say which part of the read data to zeroize. Byte number 0 means the byte read from the Interval start address. Each string can be one of:

  • "zero_mbrpt" — zeroize the MBR partition table if bytes 510 and 511 carry the MBR signature 0x55 0xaa.
  • "zero_gpt" — check for a GPT header in bytes 512 to 1023, then zeroize it and its partition table blocks.
  • "zero_apm" — check for an APM block 0 and zeroize its partition table blocks.
  • Start_byte"-"End_byte — zeroize the read-in bytes starting at Start_byte and ending after End_byte.

The Source component is the file path when the flag is "local_fs", and it’s ignored when the flag is "imported_iso".

Byte numbers can be scaled by a suffix from {k,m,g,t,s,d}, which means multiply by {1024, 1024k, 1024m, 1024g, 2048, 512}. A scaled value end number means the last byte of the scaled range. E.g. "0d-0d" is "0-511".

Examples:

"local_fs:0-32767:zero_mbrpt,zero_gpt,440-443:/tmp/template.iso"
"imported_iso:45056d-47103d::"
  • -G disk_path — Copy at most 32768 bytes from the given disk file to the very start of the ISO image. Unlike an El Torito boot image, disk_path doesn’t need to be added to the ISO image. It will not show up as a file in the directory trees. In multi-session situations, the special disk_path . prevents reading a disk file but still causes the adjustments in the existing MBR that other options ordered. 👑
  • -generic-boot disk_path — Alias of -G.
  • --embedded-boot disk_path — Alias of -G.
  • --grub2-mbr disk_path — Install disk_path in the System Area and treat it as a modern GRUB2 MBR. The content start address of the first boot image is converted to a count of 512 byte blocks, and an offset of 4 is added. The result is written as a 64 bit little-endian number to byte address 0x1b0.
  • -isohybrid-mbr disk_path — Install disk_path as ISOLINUX isohybrid MBR, which makes the boot image given by option -b bootable from USB sticks and hard disks via PC-BIOS. This preparation is normally done by ISOLINUX program isohybrid on the already produced ISO image. The disk path should lead to one of the Syslinux files isohdp[fp]x*.bin. The MBR gets patched according to isohybrid needs. The first partition describes the range of the ISO image. Its start is at block 0 by default, but may be set to 64 disk blocks by option -partition_offset 16. For the meaning of special disk_path ., see option -G.
  • -isohybrid-gpt-basdat — Mark the current El Torito boot image (see options -b and -e) in an actually invalid GPT as partition of type Basic Data. This works only with -isohybrid-mbr and has the same impact on the system area as -efi-boot-part. It cannot be combined with -efi-boot-part or -hfsplus. The first three boot images which are marked by GPT will also show up as partition entries in MBR. The MBR partition of type 0xEF is what actually is used by EFI firmware for booting from USB stick. The MBR partition for PC-BIOS gets type 0x00 rather than 0x17 in this case. Often the further MBR entries are the ones which actually get used by EFI.
  • -isohybrid-gpt-hfsplus — Mark the current El Torito boot image (see options -b and -e) in GPT as partition of type HFS+. Impact and restrictions are like with -isohybrid-gpt-basdat.
  • -isohybrid-apm-hfsplus — Mark the current El Torito boot image (see options -b and -e) in Apple Partition Map as partition of type HFS+. This works only with -isohybrid-mbr and has a similar impact on the system area as -hfsplus. It cannot be combined with -efi-boot-part or -hfsplus. The ISOLINUX isohybrid MBR file must begin by a known pattern of 32 bytes of x86 machine code which essentially does nothing. It will get overwritten by 32 bytes of APM header mock-up.
  • -part_like_isohybrid — Control whether -isohybrid-gpt-basdat, -isohybrid-gpt-hfsplus, and -isohybrid-apm-hfsplus apply even if not -isohybrid-mbr is present. No MBR partition of type 0xee emerges, even if GPT gets produced. Gaps between GPT and APM partitions will not be filled by more partitions. Appended partitions get mentioned in APM if other APM partitions emerge.
  • -iso_mbr_part_type "default"|number|type_guid — Set the partition type of the MBR or GPT partition which represents the ISO or at least protects it. Number may be 0x00 to 0xff. The text "default" re-enables the default types of the various occasions to create an ISO MBR partition. This is without effect if no such partition emerges by other settings or if the partition type is prescribed mandatorily like 0xee for GPT protective MBR or 0x96 for CHRP. If instead a type_guid is given by a 32-digit hex string like a2a0d0ebe5b9334487c068b6b72699c7 or by a structured text like EBD0A0A2-B9E5-4433-87C0-68B6B72699C7, then it will be used as partition type if the ISO filesystem appears as partition in GPT. In MBR, C12A7328-F81F-11D2-BA4B-00A0C93EC93B will be mapped to 0xef. Any other GUID will be mapped to 0x83.
  • --protective-msdos-label — Patch the System Area by a simple PC-DOS partition table where partition 1 claims the range of the ISO image but leaves the first block unclaimed. This is mutually exclusive to option -isohybrid-mbr.
  • --mbr-force-bootable — Enforce an MBR partition with "bootable/active" flag if options like --protective-msdos-label or --grub2-mbr are given. These options normally cause the flag to be set if there is an MBR partition of type other than 0xee or 0xef. If no such partition exists, then no bootflag is set, unless --mbr-force-bootable forces creation of a dummy partition of type 0x00 which covers only the first block of the ISO image. If no bootable MBR is indicated by other options and a partition gets created by -append_partition, then --mbr-force-bootable causes a bootflag like it would do with e.g. --protective-msdos-label.
  • --gpt-iso-bootable — Set bit 2 of the GPT partition flags for the ISO 9660 partition if such a GPT partition emerges. This bit is specified as "Legacy BIOS bootable" but its true significance is unclear. Some GPT-aware BIOS might want to see it in some partition.
  • --gpt-iso-not-ro — Do not set bit 60 of the GPT partition flags for the ISO 9660 partition if such a GPT partition emerges. This bit is specified as "Read-only" and thus appropriate. But it is unusual in GPT disk partitions.
  • -partition_offset 2kb_block_adr — Cause a partition table with a single partition that begins at the given block address. This is counted in 2048 byte blocks, not in 512 byte blocks. If the block address is non-zero then it must be at least 16. Values larger than 16 are hardly of use. A non-zero partition offset causes two superblocks to be generated and two sets of directory trees. The image is then mountable from its absolute start as well as from the partition start. The offset value of an ISO image gets preserved when a new session is added to a loaded image. So the value defined here is only in effect if a new ISO image gets written.
  • -partition_hd_cyl number — Set the number of heads per cylinder for the MBR partition table. 0 chooses a default value. Maximum is 255.
  • -partition_sec_hd number — Set the number of sectors per head for the MBR partition table. 0 chooses a default value. Maximum is 63. The product partition_sec_hd * partition_hd_cyl * 512 is the cylinder size. It should be divisible by 2048 in order to make exact alignment possible. With appended partitions and -appended_part_as_gpt there is no limit for the number of cylinders. Else there may be at most 1024 of them. If the cylinder size is too small to stay below the limit, then appropriate values of partition_hd_cyl are chosen with partition_sec_hd 32 or 63. If the image is larger than 8,422,686,720 bytes, then the cylinder size constraints cannot be fulfilled for MBR. They seem not overly important anyway. Flat block addresses in partition tables are good for 1 TiB.
  • -partition_cyl_align mode — Control image size alignment to an integer number of cylinders. It is prescribed by isohybrid specs and it seems to please program fdisk. Cylinder size must be divisible by 2048. Images larger than 8,323,596,288 bytes cannot be aligned in MBR partition table. Mode "auto" is default. Alignment by padding happens only if option -isohybrid-mbr is given. Mode "on" causes alignment by padding with option --protective-msdos-label too. Mode "all" is like "on" but also pads up partitions from -append_partition to an aligned size. Mode "off" disables alignment unconditionally.
  • -append_partition partition_number type_code disk_path — okay bestie, this one is the "attach a whole prepared filesystem image to my ISO" move. ✨ It takes a filesystem image you already made, appends it to the ISO image, and then writes a partition table entry describing it into a boot block at the very start of the emerging ISO image.
    • That partition entry carries the size of the file you submitted, rounded up to the next multiple of 2048 bytes — or to the next multiple of the cylinder size. your choice of rounding, basically.
    • > ⚠️ Beware of subsequent multi-session runs, fr. The appended partition will get overwritten. not "might". will. 💀
    • With MBR: partition_number may be 1 to 4. Number 1 will put the whole ISO image into the unclaimed space before partition 1. So together with most xorriso MBR or GPT features, number 2 would be the most natural choice. 🫶
    • The type_code may be "FAT12", "FAT16", "Linux", or a hexadecimal number between 0x00 and 0xff. Not all those numbers will yield usable results. For a list of codes search the Internet for "Partition Types" or run fdisk command "L". If the partition appears in GPT then type_code 0xef is mapped to the EFI System Partition Type GUID. All others get mapped to Basic Data Type GUID.
    • type_code may also be a type GUID as plain hex string like a2a0d0ebe5b9334487c068b6b72699c7 or as structured text like EBD0A0A2-B9E5-4433-87C0-68B6B72699C7. It will be used if the partition is mentioned in GPT. In MBR, C12A7328-F81F-11D2-BA4B-00A0C93EC93B will be mapped to 0xef. Any other GUID will be mapped to 0x83. In APM, 48465300-0000-11AA-AA11-00306543ECAC will be mapped to partition type "Apple_HFS", any other to "Data".
    • If some other command causes the production of GPT, then the appended partitions will be mentioned there too, even if -appended_part_as_gpt is not given.
    • GPT can be forced by option -appended_part_as_gpt.
    • GPT time: partition_number may be 1 to 8. But other than with MBR partitions it is not guaranteed that the resulting GPT partition will have this number, because it might get occupied by a partition entry which fills a gap in the coverage of the whole emerging image. 🙈
    • The chance to get the desired partition number is increased much by option -appended_gpt_with_gaps.
    • The type_code may be the same as described with MBR. Given GUIDs are used unchanged. Given MBR partition types get translated. 0xef becomes C12A7328-F81F-11D2-BA4B-00A0C93EC93B, others become EBD0A0A2-B9E5-4433-87C0-68B6B72699C7.
  • -appended_part_as_gpt — tells the partitions from -append_partition to get marked in GPT rather than in MBR. 💅 In this case the MBR shows a single partition of type 0xee which covers the whole output data.
    • By default, appended partitions get marked in GPT only if GPT is produced because of other options.
    • This option raises the maximum number of appended partitions from 4 to 8. But it is not guaranteed that the resulting GPT partition will have the given partition_number. Other GPT partitions may emerge. The final sorting by start block address may put one of them in the partition entry with the desired number, so that the appended partition will get a higher number. the audacity tbh 😭
    • Given MBR partition types get translated. 0xef becomes C12A7328-F81F-11D2-BA4B-00A0C93EC93B, others become EBD0A0A2-B9E5-4433-87C0-68B6B72699C7.
  • -appended_part_as_apm — marks partitions from -append_partition in the Apple Partition Map, too. 🍓 The partition number in APM will not be influenced by -append_partition parameter partition_number. (APM said "I do what I want.")
    • By default, appended partitions get marked in APM only if APM is produced because of other options and -part_like_isohybrid is enabled.
  • -appended_gpt_with_gaps — possibly leaves some parts of the resulting image unclaimed by partitions in the emerging GPT, so that there's a bigger chance to actually get in GPT the partition numbers you gave with option -append_partition. ✨ manifesting those numbers, basically.
    • The ISO 9660 filesystem gets marked by a GPT partition only if none of the appended partitions has partition number 1, and if no other command causes a partition inside the emerging ISO 9660 filesystem, and if -partition_offset is 16. three whole conditions, bestie, it's giving picky 💀
    • If this option is not given, then gap filling partitions will be inserted so that no part of the emerging image after block 16 is unclaimed by GPT partitions. This happens only if partitions get appended and a valid GPT emerges, e.g. by option -appended_part_as_gpt. Commands which produce isohybrid-style invalid GPT disable gap filling.
  • -efi-boot-part disk_path — copies a file from disk into the emerging ISO image and marks it with a GPT entry as an EFI System Partition. 🦋 EFI boot firmware is supposed to use a FAT filesystem image in such a partition for booting from a USB stick or hard disk.
    • Instead of a disk_path, the word --efi-boot-image may be given. It exposes in GPT the content of the first El Torito EFI boot image as EFI system partition. EFI boot images are introduced by options -e or --efi-boot. The affected EFI boot image cannot show up in HFS+ because it is stored outside the HFS+ partition. 🙈
  • --gpt_disk_guid value — controls whether an emerging GPT gets a randomly generated disk GUID or whether the GUID is supplied by you. ✨ Value "random" is the default. Value "modification-date" produces a low quality GUID from the value set by option --modification-date=. A string of 32 hex digits, or a RFC 4122 compliant GUID string, may be used to set the disk GUID directly. UEFI prescribes the first three components of a RFC 4122 GUID string to be byte-swapped in the binary representation — for example:
--gpt_disk_guid 2303cd2a-73c7-424a-a298-25632da7f446

equals

--gpt_disk_guid 2acd0323c7734a42a29825632da7f446

The partition GUIDs get generated by minimally varying the disk GUID. cute little family of GUIDs, obsessed 🎀

  • -chrp-boot-part — marks the block range of the whole emerging ISO image as MBR partition of type 0x96. This is not compatible with any other feature that produces MBR partition entries. It makes GPT unrecognizable. 💀 so like, choose wisely.
    • CHRP is often used in conjunction with HFS. It is not yet tested whether HFS+ filesystems produced with option -hfsplus would boot on any CHRP capable machine which does not boot pure ISO 9660 as well.
  • -chrp-boot — alias of -chrp-boot-part. same girl, different name 🫶
  • -prep-boot-part disk_path — copies a file from disk into the emerging ISO image and marks it with an MBR partition entry of type 0x41. PReP boot firmware is supposed to read the content of the partition as a single ELF executable file. This option is compatible with other MBR partitions and with GPT. 🌈 we love a low-conflict queen.
  • -mips-boot iso_rr_path — declares a data file in the image to be a MIPS Big Endian boot file and causes production of a MIPS Big Endian Volume Header. This is mutually exclusive with production of other boot blocks like MBR. It will overwrite the first 512 bytes of any data provided by -G. Up to 15 boot files can be declared by multiple -mips-boot options. ⭐
  • -mipsel-boot iso_rr_path — declares a data file in the image to be the MIPS Little Endian boot file. This is mutually exclusive with other boot blocks. It will overwrite the first 512 bytes of any data provided by -G. Only a single boot file can be declared by -mipsel-boot. one and done 💅
  • -B disk_path[,disk_path ...] — causes one or more data files on disk to be written after the end of the ISO image. A SUN Disk Label will be written into the first 512 bytes of the ISO image, listing this image as partition 1 and the given disk_paths as partition 2 up to 8.
    • The disk files should contain suitable boot images for SUN SPARC systems.
    • The pseudo disk_path "..." causes all empty partition entries to become copies of the last non-empty entry. If no other disk_path is given before "..." then all partitions describe the ISO image. In this case, the boot loader code has to be imported by option -G.
  • -sparc-boot disk_path[,disk_path ...] — alias of -B. 💖
  • -sparc-label text — sets the ASCII label text of a SUN Disk Label. 🏷️
  • --grub2-sparc-core iso_rr_path — causes the content address and size of the given data file in the image to be written after the SUN Disk Label. Both numbers are counted in bytes. The address is written as a 64 bit big-endian number to byte 0x228. The size is written as a 32 bit big-endian number to byte 0x230. precision, bestie ✨
  • -hppa-cmdline text — sets the PALO command line for HP-PA. Up to 1023 characters are permitted by default. With -hppa-hdrversion 4 the limit is 127. Note that the first five -hppa options are mandatory, if any of the -hppa options is given. Only option -hppa-hdrversion is allowed to be missing. so like, almost all-or-nothing 🙈
  • -hppa-bootloader iso_rr_path — designates the given path as HP-PA bootloader file.
  • -hppa-kernel-32 iso_rr_path — designates the given path as HP-PA 32 bit kernel file.
  • -hppa-kernel-64 iso_rr_path — designates the given path as HP-PA 64 bit kernel file.
  • -hppa-ramdisk iso_rr_path — designates the given path as HP-PA RAM disk file. 🍓
  • -hppa-hdrversion number — chooses between PALO header version 5 (default) and version 4. For the appropriate value, see in PALO source code: PALOHDRVERSION. iykyk 💅
  • -alpha-boot iso_rr_path — declares a data file in the image to be the DEC Alpha SRM Secondary Bootstrap Loader and causes production of a boot sector which points to it. This is mutually exclusive with production of other boot blocks like MBR. ⭐

🎀 Character sets 🎀

Character sets should not matter as long as only english alphanumeric characters are used for file names, or as long as all writers and readers of the medium use the same character set. Outside these constraints it may be necessary to let xorriso convert byte codes. 🌸

A conversion from the input character set to the output character set is performed when an ISO image gets written. Vice versa, there is a conversion from the output character set to the input character set when an ISO image gets loaded. The sets can be defined by options -input-charset and -output-charset, if needed. 🦋

  • -input-charset character_set_name — tells xorrisofs which character set your disk file names are coming from, so it can convert them on the way into the ISO image. 💅
  • -output-charset character_set_name — same energy but the other direction: sets the character set it converts from when it's loading names out of existing ISO images, and the one it converts to when writing ISO images. ✨

Jigdo Template Extraction:

Straight from man genisoimage, bestie, and I'm quoting: "Jigdo is a tool to help in the distribution of large files like CD and DVD images; see http://atterer.net/jigdo/ for more details. Debian CDs and DVD ISO images are published on the web in jigdo format to allow end users to download them more efficiently." 🦋

So here's the tea: if libjte was enabled when xorriso got compiled, then xorrisofs can spit out a .jigdo file and a .template file alongside a single-session ISO image. If it was not enabled, then any Jigdo option you pass will cause a FAILURE event, which normally means the program just aborts. 💀

Wanna know if you even have the ability? Run this:

$ xorrisofs -version 2>&1 | grep '^libjte' && echo YES

The .jigdo file holds checksums and symbolic file addresses. The .template file holds the compressed ISO image, but with reference tags where the content bytes of the listed files would be. 👑

Your input for this whole process is: the normal arguments for a xorrisofs session with no image loaded, plus a checksum file that lists those data files which may be listed in the .jigdo file and externally referenced in the .template file. Each designated file gets represented in the checksum file by a single text line:

Checksum as hex digits, 2 blanks, size as 12 decimal digits or blanks, 2 blanks, symbolic file address

Which checksum kind you get is chosen by -jigdo "checksum_algorithm", with values "md5" (32 hex digits) or "sha256" (64 hex digits). That same choice also gets used for the file address lines in the .jigdo file. The default is "md5". 🌸

Now — the file address in a checksum file line has to bear the same basename as the disk_path of the file it's supposed to match. The directory path of the file address is decisive for To=From mapping, not for file recognition. After To=From mapping, the file address gets written into the .jigdo file. Jigdo restore tools will convert these addresses into actually reachable data source addresses from which they can read. 🧚

If the list of jigdo parameters is not empty, then padding gets counted as part of the ISO image.

  • -jigdo-checksum-algorithm "md5"|"sha256" — sets the checksum algorithm used for the data file entries in the .jigdo file, and the one expected in the checksum file. Default is "md5".
  • -jigdo-jigdo disk_path — sets the disk_path for the .jigdo file, which carries the checksums and download addresses for filling the holes in .template.
  • -jigdo-template disk_path — sets the disk_path for the .template file, the holed-and-compressed copy of the ISO image.
  • -jigdo-min-file-size size — sets the minimum size for a data file to be listed in the .jigdo file and to be a hole in the .template file. size may be a plain number counting bytes, or a number with the appended letter "k", "m", "g" to count KiB (1024 bytes), MiB (1024 KiB), or GiB (1024 MiB).
  • -jigdo-force-checksum disk_path_pattern — adds a regular expression pattern that gets compared against the absolute disk_path of any data file that was not found in the checksum file. A match causes a MISHAP event, which normally does not abort the program run but finally causes a non-zero exit value of the program. 😭
  • -jigdo-force-md5 disk_path_pattern — outdated alias of -jigdo-force-checksum. (yes bestie, it's giving legacy 💅)
  • -jigdo-exclude disk_path_pattern — adds a regular expression pattern that gets compared against the absolute disk_path of any data file. A match causes the file to stay in .template in any case.
  • -jigdo-map To=From — adds a string pair of the form To=From to the parameter list. If a data file gets listed in the .jigdo file, then it's referred to by the file address from its line in the checksum file. That file address gets checked whether it begins with the From string. If so, then this string gets replaced by the To string and a ':' character, before it goes into the .jigdo file. The From string should end with a '/' character. ✨
  • -checksum-list disk_path — sets the disk_path where to find the checksum file with symbolic file addresses and checksums according to -jigdo-checksum-algorithm.
  • -md5-list disk_path — outdated alias of -checksum-list. 🫶
  • -jigdo-template-compress "gzip"|"bzip2" — picks one of "bzip2" or "gzip" for compressing the template file. The jigdo file is put out uncompressed.
  • -checksum_algorithm_iso list_of_names — picks one or more of "md5", "sha1", "sha256", "sha512" for the auxiliary "# Image Hex" checksums in the .jigdo file. list_of_names may e.g. look like "md5,sha1,sha512". The value "all" chooses all available algorithms. Note that MD5 stays always enabled. 🔥
  • -checksum_algorithm_template list_of_names — picks the algorithms for the "# Template Hex" checksums in the .jigdo file. The rules for list_of_names are the same as with -checksum_algorithm_iso.

Miscellaneous options:

  • -genisoimage_completion — matches unrecognized option arguments that begin with a dash '-' against the known genisoimage options, exactly like program genisoimage does unconditionally (and undocumentedly). If the given argument matches the beginning of exactly one genisoimage option, then it gets replaced by that option. Options which are genuine to mkisofs or xorriso's mkisofs emulation are not matched that way. Option arguments that consist entirely of a leading dash and letters out of "dDfJlNRrTUvz" are not matched but rather interpreted as usual, i.e. as multiple options with leading dash and each single letter. If no genisoimage option is found, or more than one is found, then a SORRY message is issued and the argument stays as is. 🥲 To enable this mode by default, write the xorriso command
-genisoimage_completion on

into one of the xorriso start files. See section FILES.

  • -print-size — prints to standard output the foreseeable number of 2048 byte blocks in the emerging ISO image. Does not produce this image. The result depends on several settings. If option --emul-toc is given, then padding (see -pad) is not counted as part of the image size. In this case either use -no-pad or add 150 (= 300 KiB) to the resulting number. If mkisofs emulation ends after option -print-size, then the properties of the most recently specified boot image file cannot be edited by subsequent xorriso commands.
  • --no_rc — only if used as first argument, this option prevents reading and interpretation of startup files. See section FILES below. ⭐
  • -help — lists supported options to stderr. Original mkisofs options bear their original mkisofs description texts.
  • -quiet — suppresses most messages of the program run, except those which indicate problems or errors.
  • -gui — increases the frequency of pacifier messages while writing an ISO image.
  • -log-file disk_path — truncates file disk_path to 0 size and redirects to it all messages which would normally appear on stderr. -log-file with empty text as disk_path re-enables output to stderr.
  • -v — enables the output of informational program messages.
  • -verbose — alias of -v.
  • -version — prints to standard output a text that begins with
"mkisofs 2.01-Emulation Copyright (C)"

and to standard error the version information of xorriso.

Reproducibility considerations:

Stable versions of xorriso are prepared to produce, in repeated runs from the same input files with the same file metadata and the same xorrisofs options, the same ISO 9660 filesystem bytes. The only exception is bytes that depend on the current time of the xorriso run. 🕰️

Those time dependent values can be set to fixed values by the options --modification-date=, --gpt_disk_guid, and --set_all_file_dates. And instead of setting each of them one by one, you can influence them all by the environment variable SOURCE_DATE_EPOCH. ✨

SOURCE_DATE_EPOCH belongs to the specification of reproducible-builds.org. It's supposed to be either undefined, or to contain a decimal number telling the seconds since january 1st 1970. If it contains a number, then that number is used as the time value to set the default of --modification-date=. --gpt_disk_guid defaults to "modification-date". The default of --set_all_file_dates is then "set_to_mtime". Further, the "now" time for ISO nodes without a disk source is set to the SOURCE_DATE_EPOCH value. 🌈

Startup files and xorrisofs options can override the effect of SOURCE_DATE_EPOCH.

Different versions of xorriso may or may not produce the same result from the same input and options. Reproducibility may be prevented by bug fixes or feature enhancements between versions. 😬

xorriso puts its version information into the Preparer Id field of the ISO 9660 Primary Volume Descriptor by default. This may be desired in order to clearly define which xorriso version has to be used for reproduction. But it may also be undesired, because a wider range of xorriso versions shall not be excluded from an attempt of reproduction. Use option -p with a text other than "@xorriso@" if you want to override the default at first production time. This option may also be used to explicitly set the preparer id as found in an ISO 9660 filesystem which shall be reproduced by a different version of xorriso. The preparer id can be inquired by xorriso command -pvd_info. 💜

If reproducibility of xorrisofs results is desired, then the precautions — like setting SOURCE_DATE_EPOCH — should be done already with the original xorrisofs run. All input files, the used xorrisofs options in exact sequence, the version of xorriso, and the possibly set SOURCE_DATE_EPOCH value should then be kept or recorded for later re-use. no cap. 🫶

✨ EXAMPLES ✨

Overview of examples:

  • A simple image production run
  • Set ISO image paths by -graft-points
  • Perform multi-session runs
  • Let xorrisofs work underneath growisofs
  • Incremental backup of a few directory trees
  • Incremental backup with accumulated trees
  • Create bootable images for PC-BIOS and EFI

🎀 A simple image production run 🎀

So you've got a file tree all prepped in ./for_iso and you want it in your ISO? Bestie, it gets copied straight into the root directory of the ISO image. File permissions get set to read-only for everybody (everybody, periodt 🔒), and Joliet attributes for Microsoft systems get added. Then the resulting image gets written as the data file ./image.iso on disk. Obsessed, honestly.

$ xorrisofs -r -J -o ./image.iso ./for_iso

🦋 Set ISO image paths by -graft-points 🦋

Okay so without option -graft-points, every disk file you hand over gets copied into the root directory of the ISO image, keeping its own name. And if you give it a directory? Then its files and sub-directories get copied into the root directory, names maintained, no drama.

$ xorrisofs ... /home/me/datafile /tmp/directory

which yields in the ISO image root directory:

/datafile
/file_1_from_directory
...
/file_N_from_directory

With option -graft-points tho? Now you can put files and directories at arbitrary paths in the ISO image. Main character energy fr fr.

$ xorrisofs ... -graft-points /home/me/datafile /dir=/tmp/directory

yields in the ISO image root directory:

/datafile
/dir

And any parent directories you eventually need in the image? They get created automatically:

/datafiles/file1=/home/me/datafile

yields in the ISO image:

/datafiles/file1

The attributes of directory /datafiles get copied from /home/me on disk. Cute, right? 🫶

Normally one should avoid = and \ characters in the ISO part of a pathspec. But if it must be, one may escape them:

/with_\=_and_\\/file=/tmp/directory/file

yields in the ISO image:

/with_=_and_\/file

✨ Perform multi-session runs ✨

This example works for multi-session media only: CD-R[W], DVD-R[W], DVD+R, BD-R. Add cdrskin option --grow_overwriteable_iso to all -as cdrecord runs in order to enable multi-session emulation on overwritable media. Not optional, bestie 💅

The first session is written like this:

$ xorrisofs -graft-points \
            /tree1=prepared_for_iso/tree1 \
  | xorriso -as cdrecord -v dev=/dev/sr0 blank=fast -multi -eject -

Follow-up sessions are written like this (the run of dd is only to give demons a chance to spoil it 😭):

$ m=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo)
$ dd if=/dev/sr0 count=1 >/dev/null 2>&1
$ xorrisofs -M /dev/sr0 -C $m -graft-points \
            /tree2=prepared_for_iso/tree2 \
  | xorriso -as cdrecord -v dev=/dev/sr0 -waiti -multi -eject -
Always eject the drive tray between sessions. Non-negotiable. 🚨

The run of xorriso -as mkisofs will read old sessions via the CD-ROM driver of /dev/sr0. This driver might not be aware of the changed content as long as the medium is not loaded again. In this case the previous session would not be properly assessed by xorriso and the new session would contain only the newly added files. The way that would be a whole mess 💀

Some systems have not enough patience with automatic tray loading and some demons may interfere with a first CD-ROM driver read attempt from a freshly loaded medium.

When loading the tray manually, wait 10 seconds after the drive has stopped blinking. Ten. Seconds. Count them.

A safe automatic way seems to be a separate run of xorriso for loading the tray with proper waiting, and a subsequent run of dd which shall offer itself to any problems caused by demons assessing the changed drive status. If this does not help, insert a run of sleep 10 between xorriso and dd. Slay.

🌸 Let xorrisofs work underneath growisofs 🌸

growisofs expects an ISO formatter program which understands options -C and -M. A variable is defined to override the hardcoded default name.

$ export MKISOFS="xorrisofs"
$ growisofs -Z /dev/dvd /some/files
$ growisofs -M /dev/dvd /more/files

If no "xorrisofs" is available on your system, then you will have to create a link pointing to the xorriso binary and tell growisofs to use it. E.g. by:

$ ln -s $(which xorriso) "$HOME/xorrisofs"
$ export MKISOFS="$HOME/xorrisofs"

One may quit mkisofs emulation by argument "--" and make use of all xorriso commands. growisofs dislikes options which start with "-o" but -outdev must be set to "-". So use "outdev" instead:

$ growisofs -Z /dev/dvd --for_backup -- \
            outdev - -update_r /my/files /files
$ growisofs -M /dev/dvd --for_backup -- \
            outdev - -update_r /my/files /files

Note that --for_backup is given in the mkisofs emulation. To preserve the recorded extra data it must already be in effect, when the emulation loads the image. Timing matters, iykyk ⏰

💖 Incremental backup of a few directory trees 💖

This changes the directory trees /open_source_project and /personal_mail in the ISO image so that they become exact copies of their disk counterparts. ISO file objects get created, deleted or get their attributes adjusted accordingly. Glow-up for your backups ✨

ACL, xattr, hard links and MD5 checksums will be recorded. It is expected that inode numbers in the disk filesystem are persistent over cycles of mounting and booting. Files with names matching *.o or *.swp get excluded explicitly.

To be used several times on the same medium, whenever an update of the two disk trees to the medium is desired. Begin with a blank medium and update it until the run fails gracefully due to lack of remaining space on the old one.

Always eject the drive tray between sessions. A run of dd shall give demons a chance to spoil the first read on freshly loaded media. 😈
$ msinfo=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo)
$ dd if=/dev/sr0 count=1 >/dev/null 2>&1
$ load_opts=
$ test -n "$msinfo" && load_opts="-M /dev/sr0 -C $msinfo"
$ xorrisofs $load_opts -o - --for_backup -m '*.o' -m '*.swp' \
  -V PROJ_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" -graft-points \
  -old-root / \
  /projects=/home/thomas/projects \
  /personal_mail=/home/thomas/personal_mail \
  | xorriso -as cdrecord dev=/dev/sr0 -v -multi -waiti -eject -

This makes sense if the full backup leaves substantial remaining capacity on media and if the expected changes are much smaller than the full backup.

Better do not use your youngest backup for -old-root. Have at least two media which you use alternatingly. So only older backups get endangered by the new write operation, while the newest backup is stored safely on a different medium. Protect the baby 🍼

Always have a blank medium ready to perform a full backup in case the update attempt fails due to insufficient remaining capacity. This failure will not spoil the old medium, of course. Phew.

If inode numbers on disk are not persistent, then use option --old-root-no-ino . In this case an update run will compare recorded MD5 sums against the current file content on hard disk.

With mount option -o "sbsector=" on GNU/Linux or -s on FreeBSD or NetBSD it is possible to access the session trees which represent the older backup versions. With CD media, GNU/Linux mount accepts session numbers directly by its option "session=".

Multi-session media and most overwritable media written by xorriso can tell the sbsectors of their sessions by xorriso option -toc:

$ xorriso -dev /dev/sr0 -toc

xorriso can print the matching mount command for a session number:

$ xorriso -mount_cmd /dev/sr0 session 12 /mnt

or for a volume id that matches a search expression:

$ xorriso -mount_cmd /dev/sr0 volid '*2008_12_05*' /mnt

Both yield on standard output something like:

mount -t iso9660 -o nodev,noexec,nosuid,ro,sbsector=1460256 '/dev/sr0'
'/mnt'

The superuser may let xorriso execute the mount command directly:

# osirrox -mount /dev/sr0 "volid" '*2008_12_05*' /mnt

🧚 Incremental backup with accumulated trees 🧚

Solaris does not offer the option to mount older sessions. In order to keep them accessible, one may map all files to a file tree under a session directory and accumulate those directories from session to session. The -root tree is cloned from the -old-root tree before it gets compared with the appropriate trees on disk.

This demands to know the previously used session directory name.

With the first session:

$ xorrisofs -root /session1 \
  -o - --for_backup -m '*.o' -m '*.swp' \
  -V PROJ_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" -graft-points \
  /projects=/home/thomas/projects \
  /personal_mail=/home/thomas/personal_mail \
  | xorriso -as cdrecord dev=/dev/sr0 -v blank=as_needed \
            -multi -waiti -eject -

With the second session, option -old-root refers to /session1 and the new -root is /session2.

Always eject the drive tray between sessions. A run of dd shall give demons a chance to spoil the first read on freshly loaded media. 😤
$ msinfo=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo)
$ dd if=/dev/sr0 count=1 >/dev/null 2>&1
$ load_opts=
$ test -n "$msinfo" && load_opts="-M /dev/sr0 -C $msinfo"
$ xorrisofs $load_opts -root /session2 -old-root /session1 \
  -o - --for_backup -m '*.o' -m '*.swp' \
  -V PROJ_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" -graft-points \
  /projects=/home/thomas/projects \
  /personal_mail=/home/thomas/personal_mail \
  | xorriso -as cdrecord dev=/dev/sr0 -v -multi -waiti -eject -

With the third session, option -old-root refers to /session2. The new -root is /session3. And so on. Forever and ever, bestie 🔁

👑 Create bootable images for PC-BIOS and EFI 👑

The SYSLINUX/ISOLINUX boot loader suite is popular for booting PC-BIOS. The ISOLINUX wiki prescribes to create on disk a directory ./CD_root and to copy all desired files underneath that directory. Especially file isolinux.bin shall be copied to ./CD_root/isolinux/isolinux.bin . This is the boot image file. It's giving bootable. 🔥

The prescribed mkisofs options can be used unchanged with xorrisofs:

$ xorrisofs -o output.iso \
    -b isolinux/isolinux.bin -c isolinux/boot.cat \
    -no-emul-boot -boot-load-size 4 -boot-info-table \
    ./CD_root

Put it on CD by a burn program. E.g.:

$ xorriso -as cdrecord -v dev=/dev/sr0 blank=as_needed output.iso

The image from above example will boot from CD, DVD or BD, but not from USB stick or other hard-disk-like devices. Bestie, you can fix that with an isohybrid MBR. Syslinux ships matching template files named isohdp[fp]x*.bin, e.g. /usr/lib/syslinux/isohdpfx.bin.

If a few hundred KB of size do not matter, then option -partition_offset can be used to create a partition table where partition 1 starts not at block 0. This facilitates later manipulations of the USB stick by tools for partitioning and formatting.

The image from the following example will be prepared for booting via MBR and its first partition will start at hard disk block 64. It will also boot from optical media.

$ xorrisofs -o output.iso \
    -b isolinux/isolinux.bin -c isolinux/boot.cat \
    -no-emul-boot -boot-load-size 4 -boot-info-table \
    -isohybrid-mbr /usr/lib/syslinux/isohdpfx.bin \
    -partition_offset 16 \
    ./CD_root

Become superuser and copy the image to the unpartitioned base device file of the USB stick. On GNU/Linux this is e.g. /dev/sdb, not /dev/sdb1.

CAUTION: This will overwrite any partitioning on the USB stick and make remaining data unaccessible. 💀 So first make sure you got the correct address of the intended device. E.g. by reading 100 MiB data from it and watching it blinking:
# dd bs=2K if=/dev/sdb count=50K >/dev/null

Now copy the image onto it

# dd bs=2K if=output.iso of=/dev/sdb

✨ Now for EFI ✨

The boot image file has to be the image of an EFI System Partition, i.e. a FAT filesystem with directory /EFI/BOOT and boot files with EFI prescribed names: BOOTIA32.EFI for 32 bit x86, BOOTx64.EFI for 64 bit AMD/x86 (in UEFI-2.4 there is indeed a lower case "x" 😭), BOOTAA64.EFI for 64 bit ARM. The software in the FAT filesystem should be able to find and inspect the ISO filesystem for boot loader configuration and start of operating system. GRUB2 program grub-mkimage can produce such a FAT filesystem with suitable content, which then uses further GRUB2 software from the ISO filesystem.

EFI boot equipment may be combined with above ISOLINUX isohybrid for PC-BIOS in a not really UEFI-2.4 compliant way, which obviously works well. It yields MBR and GPT partition tables, both with nested partitions. Assumed the EFI System Partition image is ready as ./CD_root/boot/grub/efi.img, add the following options before the directory address ./CD_root:

      -eltorito-alt-boot -e 'boot/grub/efi.img' -no-emul-boot \
      -isohybrid-gpt-basdat \

More compliant with UEFI-2.4 is to decide for either MBR or GPT and to append a copy of the EFI System Partition in order to avoid overlap of ISO partition and EFI partition. Here for MBR:

      -eltorito-alt-boot -e 'boot/grub/efi.img' -no-emul-boot \
      -append_partition 2 0xef ./CD_root/boot/grub/efi.img \

The resulting ISOs are supposed to boot from optical media and USB stick. One may omit option -eltorito-alt-boot if no option -b is used to make the ISO bootable via PC-BIOS.

For ISOs with pure GRUB2 boot equipment consider to use GRUB2 tool grub-mkrescue as frontend to xorrisofs.

If you have a bootable ISO filesystem and want to know its equipment plus a proposal how to reproduce it, try:

$ xorriso -hfsplus on -indev IMAGE.iso \
    -report_el_torito plain -report_system_area plain \
    -print "" -print "======= Proposal for xorrisofs options:" \
    -report_el_torito as_mkisofs

📂 FILES 📂

🎀 Startup files:

If not --no_rc is given as the first argument then xorrisofs attempts on startup to read and execute lines from the following files:

   /etc/default/xorriso
   /etc/opt/xorriso/rc
   /etc/xorriso/xorriso.conf
   $HOME/.xorrisorc

The files are read in the sequence given here, but none of them is required to exist. The lines are not interpreted as xorrisofs options but as generic xorriso commands. See man xorriso.

After the xorriso startup files, the program tries one by one to open for reading:

   ./.mkisofsrc
   $MKISOFSRC
   $HOME/.mkisofsrc
   $(dirname $0)/.mkisofsrc

On success it interprets the file content and does not try further files. The last address is used only if start argument 0 has a non-trivial dirname.

The reader currently interprets the following NAME=VALUE pairs:

APPI default for -A
PUBL default for -publisher
SYSI default for -sysid
VOLI default for -V
VOLS default for -volset

Any other lines will be silently ignored. 🙈

🌍 ENVIRONMENT 🌍

The following environment variables influence the program behavior:

  • HOME is used to find xorriso and mkisofs startup files.
  • MKISOFSRC may be used to point the program to a mkisofs startup file.
  • SOURCE_DATE_EPOCH belongs to the specs of reproducible-builds.org. See above paragraph "Reproducibility considerations".

👀 SEE ALSO 👀

For generic xorriso command mode

For the cdrecord emulation of xorriso

For mounting xorriso generated ISO 9660 images (-t iso9660)

Other programs which produce ISO 9660 images

Programs which burn sessions to optical media

ACL, xattr, Linux file attributes, project ids

MD5 checksums

On FreeBSD the commands for xattr and MD5 differ

🐛 BUGS 🐛

To report bugs, request help, or suggest enhancements for xorriso, 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 xorriso to do, the program arguments or dialog commands by which you tried to achieve it, the messages of xorriso, and the undesirable outcome of your program run. Expect to get asked more questions before solutions can be proposed. 😭 (they just wanna help fr fr)

👑 AUTHOR 👑

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

Copyright (c) 2011 - 2026 Thomas Schmitt

Permission is granted to distribute this text freely. It shall only be modified in sync with the technical properties of xorriso. If you make use of the license to derive modified versions of xorriso then you are entitled to modify this text under that same license.

💖 CREDITS 💖

xorrisofs is in part based on work by Vreixo Formoso who provides libisofs together with Mario Danic who also leads the libburnia team. Vladimir Serbinenko contributed the HFS+ filesystem code and related knowledge. Compliments towards Joerg Schilling whose cdrtools served me for ten years.

And that's a wrap bestie!! 🎀✨ This was Version 1.5.8, Apr 01, 2026 — yes, we're serving XORRISOFS(1) realness, and honestly? iconic. Go make some bootable ISOs, you absolute main character. 💅👑

📦 where this page comes from