XORRISO(1)
okay so this is xorriso(1), bestie — straight out of the General Commands Manual, and it is giving main character energy for real. 💅
🌸 NAME 🌸
xorriso — creates, loads, manipulates and writes ISO 9660 filesystem images with Rock Ridge extensions. 💖
✨ SYNOPSIS ✨
xorriso [settings|actions]🦋 DESCRIPTION 🦋
okay so xorriso is that girl. She copies file objects from POSIX compliant filesystems into Rock Ridge enhanced ISO 9660 filesystems, and she does session-wise manipulation of those filesystems. She can load the management information of ISO images that already exist, and she writes the session results to optical media or to filesystem objects. 🎀
And vice versa, bestie — xorriso is able to copy file objects out of ISO 9660 filesystems. 💫
A special property of xorriso — like, her whole thing — is that she needs neither an external ISO 9660 formatter program nor an external burn program for CD, DVD or BD. She just incorporates the libraries of libburnia-project.org . No middleman. Iconic. 👑
🌈 Overview of features:
- Operates on an existing ISO image or creates a new one.
- Copies files from disk filesystem into the ISO image.
- Copies files from ISO image to disk filesystem (see
osirrox). - Renames or deletes file objects in the ISO image.
- Changes file properties in the ISO image.
- Updates ISO subtrees incrementally to match given disk subtrees.
- Writes result either as completely new image or as add-on session to optical media or filesystem objects.
- Can activate ISOLINUX and GRUB boot images via El Torito and MBR.
- Can perform multi-session tasks as emulation of
mkisofsandcdrecord. - Can record and restore hard links and ACL.
- Content may get zisofs compressed or filtered by external processes.
- Can issue commands to mount older sessions on GNU/Linux or FreeBSD.
- Can check media for damages and copy readable blocks to disk.
- Can attach MD5 checksums to each data file and the whole session.
- Scans for optical drives, blanks re-usable optical media.
- Reads its instructions from command line arguments, dialog, and files.
- Provides navigation commands for interactive ISO image manipulation.
- Adjustable thresholds for abort, exit value, and problem reporting.
heads up though: note that xorriso does not write audio CDs, and she does not produce UDF filesystems which are specified for official video DVD or BD. So like, don't ask her for that. She said no. 🙈
🧚 General information paragraphs:
- Session model
- Media types and states
- Creating, Growing, Modifying, Blind Growing
- Libburn drives
- Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr
- Command processing
- Dialog, Readline, Result pager
Maybe you first want to have a look at section EXAMPLES near the end of this text before reading the next few hundred lines of background information. fr fr, it's a lot. 😭
💜 Session model:
Unlike other filesystems, ISO 9660 (aka ECMA-119) is not intended for read-write operation but rather for being generated in a single sweep and being written to media as a session. The data content of the session is called filesystem image.
The written image in its session can then be mounted by the operating system for being used read-only. GNU/Linux is able to mount ISO images from block devices, which may represent optical media, other media or via a loop device even from regular disk files. FreeBSD mounts ISO images from devices that represent arbitrary media or from regular disk files.
This session usage model has been extended on CD media by the concept of multi-session, which adds information to the CD and gives the mount programs of the operating systems the addresses of the entry points of each session. The mount programs recognize block devices which represent CD media and will by default mount the image in the last session. This session usually contains an updated directory tree for the whole medium which governs the data contents in all recorded sessions. So in the view of the mount program all sessions of a particular medium together form a single filesystem image.
Adding a session to an existing ISO image is in this text referred as growing.
The multi-session model of the MMC standard does not apply to all media types. But program growisofs by Andy Polyakov showed how to extend this functionality to overwritable media or disk files which carry valid ISO 9660 filesystems.
xorriso provides growing as well as an own method named modifying which produces a completely new ISO image from the old one and the modifications. See paragraph Creating, Growing, Modifying, Blind Growing below.
xorriso adopts the concept of multi-session by loading an image directory tree if present, by offering to manipulate it by several actions, and by writing the new image to the target medium. The first session of a xorriso run begins by the definition of the input drive with the ISO image or by the definition of an output drive. The session ends by command -commit which triggers writing. A -commit is done automatically when the program ends regularly.
After -commit a new session begins with the freshly written one as input. A new input drive can only be chosen as long as the loaded ISO image was not altered. Pending alteration can be revoked by command -rollback.
Writing a session to the target is supposed to be very expensive in terms of time and of consumed space on appendable or write-once media. Therefore all intended manipulations of a particular ISO image should be done in a single session. But in principle it is possible to store intermediate states and to continue with image manipulations. 💸
🎀 Media types and states:
There are two families of media in the MMC standard:
Multi-session media are CD-R, CD-RW, DVD-R, DVD+R, DVD+R/DL, BD-R, and unformatted DVD-RW. These media provide a table of content which describes their existing sessions. See command -toc.
Similar to multi-session media are DVD-R DL and minimally blanked DVD-RW. They record only a single session of which the size must be known in advance. xorriso will write onto them only if command -close is set to "on".
Overwritable media are DVD-RAM, DVD+RW, BD-RE, and formatted DVD-RW. They offer random write access but do not provide information about their session history. If they contain one or more ISO 9660 sessions and if the first session was written by xorriso, then a table of content can be emulated. Else only a single overall session will be visible.
DVD-RW media can be formatted by -format "full". They can be made unformatted by -blank "deformat".
Regular files and block devices are handled as overwritable media.
Pipes and other writeable file types are handled as blank multi-session media.
The program growisofs formats by default BD-R to be pseudo-overwritable (POW). xorriso will classify them as
Media current: is unsuitable , is POW formattedand will refuse to write to them or to obtain multi-session information from them. nope, not doing it. 💀
These media can assume several states in which they offer different capabilities.
Blank media can be written from scratch. They contain no ISO image suitable for xorriso.
Blank is the state of newly purchased optical media. With used CD-RW and DVD-RW it can be achieved by action -blank "as_needed".
Overwritable media are considered blank if they are new or if they have been marked as blank by xorriso. Action -blank "as_needed" can be used to do this marking on overwritable media, or to apply mandatory formatting to new media if necessary.
Appendable media accept further sessions. Either they are MMC multi-session media in appendable state, or they are overwritable media which contain an ISO image suitable for xorriso.
Appendable is the state after writing a session with command -close off.
Closed media cannot be written. They may contain an ISO image suitable for xorriso.
Closed is the state of DVD-ROM media and of multi-session media which were written with command -close on. If the drive is read-only hardware then it will probably show any media as closed CD-ROM or DVD-ROM.
Overwritable media assume this state in such read-only drives or if they contain unrecognizable data in the first 32 data blocks.
Read-only drives may or may not show session histories of multi-session media. Often only the first and the last session are visible. Sometimes not even that. Command -rom_toc_scan might or might not help in such cases. 🤷
🫶 Creating, Growing, Modifying, Blind Growing:
A new empty ISO image gets created if there is no input drive with a valid ISO 9660 image when the first time an output drive is defined. This is achieved by command -dev on blank media or by command -outdev on media in any state.
The new empty image can be populated with directories and files. Before it can be written, the medium in the output drive must get into blank state if it was not blank already.
If there is a input drive with a valid ISO image, then this image gets loaded as foundation for manipulations and extension. The constellation of input and output drive determines which write method will be used. They have quite different capabilities and constraints.
The method of growing adds new data to the existing data on the medium. These data comprise of new file content and they override the existing ISO 9660 + Rock Ridge directory tree. It is possible to hide files from previous sessions but they still exist on the medium and with many types of optical media it is quite easy to recover them by mounting older sessions. 👀
Growing is achieved by command -dev.
The write method of modifying produces compact filesystem images with no outdated files or directory trees. Modifying can write its images to target media which are completely unsuitable for multi-session operations. E.g. DVD-RW which were treated with -blank deformat_quickest, DVD-R DL, named pipes, character devices, sockets. On the other hand modified sessions cannot be written to appendable media but to blank media only.
So for this method one needs either two optical drives or has to work with filesystem objects as source and/or target medium.
Modifying takes place if input drive and output drive are not the same and if command -grow_blindly is set to its default "off". This is achieved by commands -indev and -outdev.
If command -grow_blindly is set to a non-negative number and if -indev and -outdev are both set to different drives, then blind growing is performed. It produces an add-on session which is ready for being written to the given block address. This is the usage model of
mkisofs -M $indev -C $msc1,$msc2 -o $outdevwhich gives much room for wrong parameter combinations and should thus only be employed if a strict distinction between ISO formatter xorriso and the burn program is desired. -C $msc1,$msc2 is equivalent to:
-load sbsector $msc1 -grow_blindly $msc2💿 Libburn drives 💿
okay so first things first, bestie — there are two flavors of drive here and you need to keep them straight or you will absolutely get your wires crossed.
- Input drive — this is the source, aka where your existing or empty ISO image lives. It can be any random access readable libburn drive: optical media that already has readable data on it, blank optical media, regular files, or block devices. Basically if it can be read and seeked, it's fair game.
- Output drive — this is the target you're writing to, and it can be any libburn drive too. lowkey important: some drive types don't support the method of growing at all, only the methods of modifying and blind growing. But literally all of them are suitable for newly created images. ✨
Now, here's the vibe check on permissions: all drive file objects have to offer rw-permission to the user of xorriso. yes, even the ones that won't ever be used for reading an ISO image. no exceptions, bestie, the whole object needs read-write. 🙈
With any type of drive object, the data are considered to be organized in blocks of 2 KiB. Access happens in terms of Logical Block Address (LBA), which is just the number of a particular data block. cute and simple. 🎀
MMC compliant (i.e. optical) drives on GNU/Linux usually get addressed by the path of their block device or of their generic character device. like so:
-dev /dev/sr0
-dev /dev/hdc
-dev /dev/sg2By default xorriso will try to map the given address to /dev/hd* and /dev/sr*. The command -scsi_dev_family can redirect the mapping from sr to scd or sg. The latter does not suffer from the concurrency problems which plagued /dev/sr of Linux kernels since version 2.6 up to 5.5. But it does not yield the same addresses which are used by mount(8) or by open(2) for read(2). so like, tradeoffs, iykyk. 💅
On FreeBSD the device files have names like
-dev /dev/cd0On NetBSD:
-dev /dev/rcd0dOn OpenSolaris:
-dev /dev/rdsk/c4t0d0s2Wanna get a list of accessible drives? run
-device_linksngl it might be necessary to do this as superuser in order to see all drives, and then allow rw-access for the intended users. Consider bundling the authorized users in a group like the old "floppy" group. retro but it works. 🦋
Filesystem objects of nearly any type can be addressed by prefixing stdio: and their path in the filesystem. E.g.:
-dev stdio:/dev/sdcThe default setting of -drive_class allows the user to address files outside the /dev tree without that prefix. E.g.:
-dev /tmp/pseudo_driveIf path leads to a regular file or to a block device, then the emulated drive is random access readable and can be used for the method of growing if it already contains a valid ISO 9660 image. Any other file type is not readable via "stdio:" and can only be used as target for the method of modifying or blind growing. Non-existing paths in existing directories are handled as empty regular files. iconic behavior honestly. ✨
A very special kind of pseudo drive are open file descriptors. They are depicted by "stdio:/dev/fd/" plus the descriptor number (see man 2 open). Addresses "-" or "stdio:/dev/fd/1" depict standard output, which normally is the output channel for result texts. To prevent a fatal intermingling of ISO image and text messages, all result texts get redirected to stderr if -*dev "-" or "stdio:/dev/fd/1" is among the start arguments of the program.
Standard output is currently suitable for creating one session per program run without dialog. Use in other situations is discouraged and several restrictions apply:
🚨 It is not allowed to use standard output as pseudo drive if it was not among the start arguments. Do not try to fool this ban via backdoor addresses to stdout. If stdout is used as drive, then -use_readline is permanently disabled. Use of backdoors can cause severe memory and/or tty corruption. 💀
Be aware that especially the superuser can write into any accessible file or device by using its path with the "stdio:" prefix. By default any address in the /dev tree without prefix "stdio:" will work only if it leads to a MMC drive.
- One may use command
-ban_stdio_writeto surely prevent this risk and to restrict drive usage to MMC drives. - One may prepend
"mmc:"to a path to surely disallow any automatic"stdio:". - By command
-drive_classone may ban certain paths or allow access without prefix"stdio:"to other paths.
🧚 Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr 🧚
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. This is what xorriso uses for a decent representation of the disk files within the ISO image. xorriso produces Rock Ridge information by default. It is strongly discouraged to disable this feature. don't do it bestie. 🫶
xorriso is not named "porriso" because POSIX only guarantees 14 characters of filename length. It is the X/Open System Interface standard XSI which demands a file name length of up to 255 characters and paths of up to 1024 characters. Rock Ridge fulfills this demand. periodt. 💅
An El Torito boot record points the BIOS bootstrapping facility to 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. Most bootable GNU/Linux CDs are equipped with ISOLINUX or GRUB boot images. xorriso is able to create or maintain an El Torito object which makes such an image bootable. For details see command -boot_image. 🔥
It is possible to make ISO images bootable from USB stick or other hard-disk-like media. Several options install a MBR (Master Boot Record). It may get adjusted according to the needs of the intended boot firmware and the involved boot loaders, e.g. GRUB2 or ISOLINUX. A MBR contains boot code and a partition table. The new MBR of a follow-up session can get in effect only on overwritable media. 💀
MBR 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.
Emulation -as mkisofs 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. slay, it speaks everyone's language. ✨
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. cute, they all get along. 🎀
There is support for further facilities: MIPS Big Endian (SGI), MIPS Little Endian (DEC), SUN SPARC, HP-PA. Those are mutually not combinable and also not combinable with MBR, GPT, or APM. pick a lane bestie. 🚨
ACL are an advanced way of controlling access permissions to file objects. Neither ISO 9660 nor Rock Ridge specify a way to record ACLs. So libisofs has introduced a standard conformant extension named AAIP for that purpose. It uses this extension if enabled by command -acl.
AAIP enhanced images are supposed to be mountable normally, but one cannot expect that the mounted filesystem will show and respect the ACLs. For now, only xorriso is able to retrieve those ACLs. It can bring them into effect when files get restored to an ACL enabled file system, or it can print them in a format suitable for tool setfacl.
Files with ACL show as group permissions the setting of entry "mask::" if that entry exists. Nevertheless the non-listed group members get handled according to entry "group::". When removing ACL from a file, xorriso brings "group::" into effect.
Recording and restoring of ACLs from and to local files works currently only on GNU/Linux and FreeBSD.
<xattr> — wait, no, xattr (aka EA, or extattr) are pairs of name and value which can be attached to file objects. AAIP is able to represent them and xorriso can record and restore them.
But be aware that pairs with names of non-user namespaces are not necessarily portable between operating systems and not even between filesystems. Only those which begin with "user.", like "user.x" or "user.whatever", can unconditionally be expected to be appropriate on other machines and disks. Processing of other xattr may need administrator privileges. 😭
Name has to be a 0 terminated string. Value may be any array of bytes which does not exceed the size of 4095 bytes. xattr processing happens only if it is enabled by command -xattr.
As with ACL, currently only xorriso is able to retrieve xattr from AAIP enhanced images, to restore them to xattr capable file systems, or to print them.
Recording and restoring of xattr from and to local files works currently only on GNU/Linux and FreeBSD, where they are known as extattr.
Linux file attributes are binary flags which can be set by program chattr(1) and listed by program lsattr(1). See their man pages and the definitions FS_*_FL in Linux header file <linux/fs.h>. Not all defined flags get reported by lsattr and accepted by chattr, but their number grew over the years. glow-up honestly. 📈
xorriso records the flags of disk files if enabled by command -lfa_flags. Its command -lsattr lists 22 flags the same way as the program lsattr does. They can be set by xorriso command -chattr and can be enabled by -lfa_flags for restoring when their files get restored to disk. ✨
XFS-style project ids are numbers which define the members of file object groups, called projects. They can be set by programs chattr(1) and xfs_quota(8) and reported by programs lsattr(1) and xfs_quota(8). The files of a project can share quotas which limit their usage of filesystem resources. This is possible in XFS and in specially prepared and mounted ext4 filesystems. Project id 0 means that the file is not member of any project.
xorriso records non-zero project ids of disk files if enabled by command -projid. Command -get_projid lists the project ids of files. They can be set by command -set_projid and get restored to disk if enabled by -projid. Usually project id 0 is not set to restored disk files, so that they may get the project id of their parent disk directory. 🎀
🫶 Command processing 🫶
Commands are either actions which happen immediately or settings which influence following actions. So their sequence does matter, unless they are given as program arguments and command -x is among them. order matters, bestie, this is not a buffet. 🍓
The list of all current settings can be inquired by command -status "long". Command -status "short" lists a handful of fundamental settings and all settings which are not default at program start. lowkey the short one is the vibe check. 💅
Commands consist of a command word, followed by zero or more parameter words. If the list of parameter words is of variable length (indicated by "[...]" or "[***]") then it must be terminated by either the list delimiter, occur at the end of the argument list, or occur at the end of an input line. ✨
Okay so at program start, the list delimiter is the string "--". You can change it with the -list_delimiter command if you wanna sneak "--" in as an actual parameter inside a variable length list — but bestie, the moment you're done, reset that delimiter straight back to "--". Like, immediately. 🫶
For brevity, this whole text just calls the list delimiter "--".
Also, heads up: the list delimiter gets silently ignored if it shows up after the parameters of a command that has a fixed list length. And if it appears among the parameters of one of those commands, it's handled as normal text. No drama, no error, it just vibes. ✨
Pattern expansion is the glow-up that turns a list of pattern words into a list of existing file addresses. Any pattern word that doesn't match anything? It just shows up unaltered in the result list. It stays in the group chat, fr fr. 🙈
Pattern matching supports the usual shell parser wildcards '*', '?', '[xyz]' and it respects / as the path separator — which can only be matched literally.
Pattern expansion is a property of some particular commands, not a general feature, okay? It's controlled by the commands -iso_rr_pattern and -disk_pattern. Every command that uses pattern expansion has a variable parameter list, which this text writes as "[***]" instead of "[...]". Note the difference. 👑
And some other commands do pattern matching unconditionally. Iconic. 💅
Command and parameter words are read either from the program arguments — where one argument is one word — or from quoted input lines, where words are recognized kind of like the quotation rules of a shell parser.
But xorriso is not a shell, even though it absolutely gives shell at first glimpse. Be aware that the way quotation marks and pattern symbols like "*" interact here is different from your usual shell parsers. In xorriso, a quotation mark does not make a pattern symbol literal. That's the tea. ☕
Quoted input converts whitespace-separated text into words. The double quotation mark " and the single quotation mark ' can be used to enclose whitespace and make it part of words (e.g. of file names). Each mark type can enclose the marks of the other type. A trailing backslash \ outside quotations, or an open quotation, causes the next input line to be appended.
Quoted input accepts any 8-bit character except NUL (0) as the content of the quotes. But ngl, it can be cumbersome for the user to produce those characters directly. So quoted input and program arguments both offer optional Backslash Interpretation, which can represent all 8-bit characters except NUL (0) via backslash codes, just like $'...' in bash.
This is not enabled by default. See command -backslash_codes.
When the program starts, it first looks for the argument -no_rc. If that's not there, it looks for its startup files and reads their content as command input lines. Then it interprets the program arguments as commands and parameters. Finally it enters dialog mode — but only if the command -dialog "on" has been executed by that point.
The program ends either by command -end, or by the end of program arguments if dialog mode has not been enabled at that point, or by a problem event which triggers the threshold of command -abort_on. 🎬
Dialog, Readline, Result pager 🎀
Dialog mode prompts you for a quoted input line, parses it into words, and performs them as commands with their parameters. It also provides assisting services to make dialog more comfy. 🦋
Readline is an enhancement for the input line. You probably already know it from the bash shell. Whether it's available in xorriso depends on whether the package readline-dev was around at the time xorriso was built from its sourcecode.
Readline lets you move the cursor over the text in the line with the Left and Right arrow keys. Text may be inserted at the cursor position. The Delete key removes the character under the cursor. Up and Down arrow keys navigate through the history of previous input lines. Main character energy, honestly. 👑
See man readline for more info about libreadline.
Command -page activates a built-in result text pager, which is lowkey convenient in dialog mode. After an action has output the given number of terminal lines, the pager prompts you for a line of input.
- An empty line lets xorriso resume work until the next page is output. ⭐
- The single character
"@"disables paging for the current action. "@@@","x","q","X", or"Q"request that the current action aborts and suppress further result output. 💀- Any other line input will be interpreted as a new dialog line. The current action is requested to abort. Afterwards, the input line is executed.
Some actions apply paging to their info output, too. And real talk: the request to abort may or may not be obeyed by the current action. All actions try to abort as soon as possible, though. 🏃♀️💨
✨ OPTIONS ✨
All command words are shown with a leading dash, although this dash is not mandatory for the command to be recognized. Nevertheless, within command -as, the dashes of the emulated commands are mandatory.
Normally any number of leading dashes is ignored with command words, and inner dashes are interpreted as underscores.
🔥 Execution order of program arguments
By default, the program arguments of a xorriso run are interpreted as a sequence of commands which get performed exactly in the given order. This means you have to write the commands for your desired settings before the commands that shall be influenced by those settings. Order matters, bestie.
Many other programs support program arguments in an arbitrary ordering and perform settings and actions in a sequence at their own discretion. xorriso provides an option to enable such a behavior — but at the cost of loss of expressivity. Trade-offs, always trade-offs. 💅
-x— Enable automatic sorting of program arguments into a sequence that (most likely) is sensible. This command may be given at any position among the commands which are handed over as program arguments.
Note: It works only if it is given as a program argument and with a single dash (i.e."-x"). It will not work in startup files, nor with-options_from_file, nor in dialog mode, nor as"x", and finally not as"--x". It affects only the commands given as program arguments.
-list_arg_sorting— List all xorriso commands in the order which applies if command-xis in effect. This list may also be helpful without-xfor a user who ponders over the sequence in which to put commands. Deviations from the listed sorting order may well make sense, though. 👑
🌈 Acquiring source and target drive
The effect of acquiring a drive may depend on several commands in the next paragraph "Influencing the behavior of image loading". If desired, their enabling commands have to be performed before the commands which acquire the drive. Order. Again. Always. 😭
-devaddress — Set input and output drive to the same address and load an ISO image if it is present. If there is no ISO image, then create a blank one. Set the image expansion method to growing.
This is only allowed as long as no changes are pending in the currently loaded ISO image. If changes are pending, then you have to perform -commit or -rollback first. No skipping that step. 🚫
Special address string "-" means standard output, to which several restrictions apply. See above paragraph "Libburn drives".
An empty address string "" gives up the current device without acquiring a new one. 🚪
-indevaddress — Set input drive and load an ISO image if present. If the new input drive differs from-outdev, then switch from growing to modifying or to blind growing. It depends on the setting of-grow_blindlywhich of both gets activated. The same rules and restrictions apply as with-dev.-outdevaddress — Set output drive and, if it differs from the input drive, switch from growing to modifying or to blind growing. Unlike-devand-indev, this action does not load a new ISO image. So it can be performed even if there are pending changes. 🎉
-outdev can be performed without a previous -dev or -indev. In that case an empty ISO image with no changes pending is created. It can either be populated by help of -map, -add et.al. or it can be discarded silently if -dev or -indev are performed afterwards.
Special address string "-" means standard output, to which several restrictions apply. See above paragraph "Libburn drives".
An empty address string "" gives up the current output drive without acquiring a new one. And remember: no writing is possible without an output drive. Periodt. 💅
-drive_class"harmless"|"banned"|"caution"|"clear_list"disk_pattern — Add a drive path pattern to one of the safety lists, or make those lists empty.
There are three lists defined, and they get tested in this sequence:
- If a drive address path matches the
"harmless"list, then the drive will be accepted. If it is not a MMC device, then the prefix"stdio:"will be prepended automatically. This list is empty by default. - Else if the path matches the
"banned"list, then the drive will not be accepted by xorriso but rather lead to a FAILURE event. This list is empty by default. - Else if the path matches the
"caution"list and if it is not a MMC device, then its address must have the prefix"stdio:"or it will be rejected. This list has by default one entry:"/dev".
If a drive path matches no list, then it is considered "harmless". By default these are all paths which do not begin with directory "/dev".
A path matches a list if one of its parent paths or itself matches a list entry. Address prefix "stdio:" or "mmc:" will be ignored when testing for matches.
By pseudo-class "clear_list" and pseudo-patterns "banned", "caution", "harmless", or "all", the lists may be made empty. E.g.:
-drive_class clear_list bannedOne will normally define the -drive_class lists in one of the xorriso Startup Files.
Note: This is not a security feature but rather a bumper for the superuser to prevent inadvertent mishaps. For reliably blocking access to a device file you have to deny its rw-permissions in the filesystem. 🛑
-drive_access "exclusive"|"shared":"unrestricted"|"readonly"— okay so this one is the ✨vibe check✨ for how xorriso grabs a drive: should device file locking mechanisms be used when acquiring it, and is it allowed to touch the medium's status or content? The most useful and most harmless settings are"shared:readonly"and the default"exclusive:unrestricted". 🫶
"exclusive" turns on tests and locks while acquiring the drive. Which locking mechanisms actually get applied (if any!) depends on your operating system. On GNU/Linux it's open(O_EXCL). On FreeBSD it's flock(LOCK_EX).
"shared" disables those mechanisms, which is what lets you acquire drives that are mounted, or opened by some process, or guarded by /dev/pktcdvd*.
"unrestricted" enables all technically appropriate operations on an acquired drive. But lowkey watch out: "shared:unrestricted" risks getting your own burn runs spoiled by other processes, or you vice versa spoiling the activities of such processes. Mutual sabotage, not the cute kind 💀. So use "exclusive:unrestricted" unless you know for sure that "shared" is safe.
"readonly" disables operations which might surprise a co-user of the drive. For -outdev these are formatting, blanking, writing, ejecting. For -indev this is ejecting. And be aware that even reading and drive status inquiries can disturb an ongoing burn run on CD-R[W] and DVD-R[W]. 😭
-scsi_dev_family "default"|"sr"|"scd"|"sg"— GNU/Linux specific, bestie:
By default, xorriso tries to map Linux drive addresses to /dev/sr* before they get opened for operating the drive. This coordinates well with other use cases of optical drives, like mount(8). But between year 2010 and 2020 all /dev/sr* shared a global lock which allowed only one drive to process an SCSI command while all others had to wait for its completion. This yielded awful throughput if more than one drive was writing or reading simultaneously. The global lock was never applied to device files /dev/sg* and also not if the xorriso drive address is prepended by "stdio:".
So for simultaneous burn runs on GNU/Linux 2.6 to 5.5 it is advisable to perform -scsi_dev_family "sg" before any -dev, -indev, or -outdev. The drive addresses may then well be given as /dev/sr*, but will nevertheless get used as the matching /dev/sg*.
If you decide so, consider to put the command into a global startup file like /etc/opt/xorriso/rc. 🎀
-grow_blindly "off"|predicted_nwa— ifpredicted_nwais a non-negative number then perform blind growing rather than modifying, when-indevand-outdevare set to different drives."off"or"-1"switch to modifying, which is the default.
predicted_nwa is the block address where the add-on session of blind growing will finally end up. And this part is on YOU, bestie: it is the responsibility of the user to ensure this final position and the presence of the older sessions. Else the overall ISO image will not be mountable or will produce read errors when accessing file content. xorriso will write the session to the address as obtained from examining -outdev and not necessarily to predicted_nwa. 👑
During a run of blind growing, the input drive is given up before output begins. The output drive is given up when writing is done.
✨ Influencing the behavior of image loading ✨
The following commands should normally be performed before loading an image by acquiring an input drive. In rare cases it is desirable to activate them only after image loading.
-read_speed code|number[k|m|c|d|b]— sets the speed for reading. Default is"none", which avoids sending a speed setting command to the drive before reading begins.
Further special speed codes are:
"max"(or"0") selects maximum speed as announced by the drive."min"(or"-1") selects minimum speed as announced by the drive.
Speed can be given in media dependent numbers or as a desired throughput per second in MMC compliant kB (= 1000) or MB (= 1000 kB). Media x-speed factor can be set explicitly by "c" for CD, "d" for DVD, "b" for BD, "x" is optional.
Example speeds:
706k = 706kB/s = 4c = 4xCD
5540k = 5540kB/s = 4d = 4xDVD
17983k = 17983kB/s ~= 4b = 4xBDIf there is no hint about the speed unit attached, then the medium in the -indev will decide. Default unit is CD = 176.4k. Depending on the drive, the reported read speeds can be deceivingly low or high. Therefore "min" cannot become higher than 1x speed of the involved medium type. Read speed "max" cannot become lower than 52xCD, 24xDVD, or 20xBD, depending on the medium type.
MMC drives usually activate their own idea of speed and take the speed value given by the burn program only as hint for their own decision. Friendly drives adjust their constant angular velocity so that the desired speed is reached at the outer rim of the medium. But often there is only the choice between very slow and very loud. 🙈
Sometimes no speed setting is obeyed at all, but speed is adjusted to the demand frequency of the reading program. So xorriso offers to set an additional software enforced limit by prefix "soft_force:". The program will take care not to read faster than the soft_force: speed. This may be combined with setting the drive speed to a higher value. Setting "soft_force:0" disables this feature.
"soft_force:" tries to correct in subsequent waiting periods lost or surplus time of up to 0.25 seconds. This smoothens the overall data stream but also enables short times of higher speed to compensate short times of low speed. Prefix "soft_corr:" sets this hindsight span by giving a number of microseconds. Not more than 1 billion = 1000 seconds. Very short times can cause speed deviations, because systematic inaccuracies of the waiting function cannot be compensated.
Examples (combinable):
-read_speed 6xBD
-read_speed soft_force:4xBD -read_speed soft_corr:100000-load entity id— loads a particular (possibly outdated) ISO session from-devor-indev. Usually all available sessions are shown with command-toc.
entity depicts the kind of addressing. id depicts the particular address. The following entities are defined:
"auto"with anyidaddresses the last session in-toc. This is the default."session"withidbeing a number as of a line"ISO session", column"Idx"."track"withidbeing a number as of a line"ISO track", column"Idx"."lba"or"sbsector"with a number as of a line"ISO ...", column"sbsector"."volid"with a search pattern for a text as in the column"Volume Id"of a-tocline"ISO ..."."at_time"with a time string as described with command-alter_datechooses the last session or track where the modification timestamp matches the given time within the same second."before"with a time string chooses the last session or track of which the timestamp is older than the given time. But it does not match an entity with exactly the given time."not_after"is like"before"but also matches an entity with exactly the given time."after"with a time string chooses the first session or track of which the timestamp is younger than the given time. But it does not match an entity with exactly the given time."not_before"is like"after"but also matches an entity with exactly the given time.
Comparison of time entities is done with an accuracy of one second. I.e. the centiseconds of ISO 9660 timestamps are ignored. If -toc_info_type is set to "creation_time", then the comparison is done against the creation timestamp of track or session rather than the modification timestamp. The output of -pvd_info shows both timestamps as "Creation Time:" and "Modif. Time :".
The time comparisons pick first and last matching sessions. If the sequence of timestamps on a drive is not chronologically ascending, the picks might not be the best choice. In this case look at the output of -toc_info_type "mtime" -toc and choose the desired entity by "session", "track", or "sbsector".
Addressing a non-existing entity or one which does not represent an ISO image will either abandon -indev or at least lead to a blank image.
If an input drive is set at the moment when -load is executed, then the addressed ISO image is loaded immediately. Else, the setting will be pending until the next -dev or -indev. After the image has been loaded once, the setting is valid for -rollback until next -dev or -indev, where it will be reset to "auto". 🦋
-displacement [-]lba— compensates a displacement of the image versus the start address for which the image was prepared. This affects only loading of ISO images and reading of their files. The multi-session method of growing is not allowed as long as-displacementis non-zero. I.e.-indevand-outdevmust be different. The displacement gets reset to 0 before the drive gets re-acquired after writing.
Examples: If a track of a CD starts at block 123456 and gets copied to a disk file where it begins at block 0, then this copy can be loaded with
-displacement -123456If an ISO image was written onto a partition with offset of 640000 blocks of 512 bytes, then it can be loaded from the base device by
-load sbsector 160000 -displacement 160000(If the partition start address is not divisible by 4, then you will have to employ a loop device instead.)
In both cases, the ISO sessions should be self contained, i.e. not add-on sessions to an ISO image outside their track or partition. 🌸
-read_fs "any"|"norock"|"nojoliet"|"ecma119"— okay so when you're loading an image, this tells xorriso which kind of filesystem tree to grab if it's even there. And if your lil wish can't be granted? No stress, it just loads ECMA-119 names and converts them following-ecma119_map."any"— tries Rock Ridge first, bestie. Not there? Then Joliet gets a turn."norock"— does not try Rock Ridge. Nope."nojoliet"— does not try Joliet. Nope nope."ecma119"— tries neither Rock Ridge nor Joliet. Just ECMA-119, periodt.
-assert_volid pattern severity— this one is giving bouncer-at-the-club energy 💅. It refuses to load ISO images whose volume IDs don't match the given search pattern. When it refuses an image, it gives up the input drive and fires off an event with the severity you gave it (likeFAILURE, peep-abort_on). An empty search pattern accepts any image, so it's chill like that.
Heads up though: this command does not hamper the creation of an empty image from blank input media, and it does not discard an image that's already loaded. It's not gonna snatch anything back from you. 🫶
-in_charset character_set_name— sets the character set that file names get converted from when you're loading an image. Go read the "Character sets" paragraph for the deets, iykyk. Fun fact: when you load the written image after-commit, whatever you set in-out_charsetgets copied over into-in_charset. ✨-auto_charset "on"|"off"— turns on or off the recording and interpreting of the output character set name inside an xattr attribute of the image root directory. If it's enabled and a recorded character set name is found, that name becomes the name of the input character set when reading an image. So convenient, honestly.
⚠️ Real talk: the default output charset is the local character set of the terminal where xorriso runs. Before you go attributing that local charset to the ISO image you produced, check that your terminal properly displays all intended filenames, especially the exotic national characters. Don't let your terminal lie to you bestie 😭
-hardlinks mode[:mode...]— enables or disables loading and recording of hardlink relations. Let's break this all the way down:- Default mode
"off":iso_rrfiles lose their inode numbers</bad> at image load time. Everyiso_rrfile object with no inode number at image generation time gets a fresh unique inode number if-complianceis set tonew_rr. - Mode
"on"preserves inode numbers from the loaded image, if such numbers were actually recorded. - When committing a session, it goes looking for families of
iso_rrfiles that stem from the same disk file, have identical content filtering, and have identical properties. The whole family gets the same inode number. 🫂 Whether those numbers are respected at mount time is between you and your operating system, so don't @ me. - Command
-lsldisplays hardlink counts if"lsl_count"is enabled. Warning: that can slow the command down substantially after changes to the ISO image have been made. That's why the default is"no_lsl_count". - Commands
-updateand-update_rtrack splits and fusions of hard links in filesystems that have stable device and inode numbers. This can cause automatic last minute changes right before the session gets written. Command-hardlinks "perform_update"lets you do those changes earlier — say, if you need to apply filters to all updated files. Foresight is main character energy. - Mode
"without_update"avoids hardlink processing during update commands. Use this if your filesystem situation does not allow-disk_dev_ino "on". - xorriso commands that extract files from an ISO image try to hardlink files with identical inode number. The normal scope of this operation runs from image load to image load. You can give up the accumulated hard link addresses with
-hardlinks "discard_extract". - A large number of hardlink families may exhaust
-temp_mem_limitif not both-osirrox "sort_lba_on"and-hardlinks "cheap_sorted_extract"are in effect. That combo restricts hard linking to other files restored by the same single extract command.-hardlinks "normal_extract"re-enables wide and expensive hardlink accumulation, if you're feeling bougie.
- Default mode
-acl "on"|"off"— enables or disables processing of ACLs. When it's enabled, xorriso will: obtain ACLs from disk file objects, store ACLs in the ISO image using the libisofs specific AAIP format, load AAIP data from ISO images, test ACL during file comparison, and restore ACLs to disk files when extracting them from ISO images. She does it all 💅. Peep-getfacland-setfacltoo.-xattr "on"|"user"|"any"|"off"— enables or disables processing of xattr attributes. When enabled, xorriso handles xattr similar to ACL (yes, they're siblings fr fr). Check out-getfattr,-setfattr, and that paragraph above about xattr.- Modes
"on"and"user"read and write only attributes from namespace"user". - Mode
"any"processes attributes of all namespaces. This might need administrator privileges, even if the owner of the disk file is the one trying to read or write the attributes. Rude, but that's the vibe. - > 🚫 Note that it is not possible to set xattr of namespace
"isofs."by xorriso xattr manipulation commands. Just not a thing, bestie.
- Modes
-lfa_flags mode[:mode...]— enables, disables, or influences processing of Linux file attributes, as described inman 1 chattr. Grab a snack, this one's a whole buffet 🍓:- Mode
"on"enables actual processing of the attributes. - Mode
"off"disables it. - Mode
"auto_on"enables it only if the underlying libisofs was compiled with support for Linux file attributes — which is typically not the case on non-Linux systems. Enabled processing without libisofs support would cause failure events when reading disk files. 😬
- Mode
The other modes define the behavior in case of "on":
- Mode
"read"enables obtaining of these attributes from disk files, storing them in the emerging ISO 9660 filesystem as AAIP data, importing them when an ISO filesystem gets loaded and bears such stored attributes, and comparing them during comparisons between files on disk and in ISO. - Mode
"no_read"disables reading of the attributes from disk files and importing them when an ISO filesystem gets loaded. But if other settings like-acl "on"or-xattr "on"require storing of AAIP data, then file attributes might still get stored in the emerging ISO. To surely exclude any file attributes, run this before-commit:
-chattr_r --remove-lfa-flags / --- Mode
"import_non_settable"enables obtaining of non-settable attributes from disk and attaching of attributes to files in the emerging ISO image even if all attribute flags are zero. - Mode
"import_only_settable"causes non-settable attributes ("eEhINVZ") to be ignored when file objects get read from disk. If the remaining attribute flags are all zero, then no attribute information gets attached to the file in the ISO. This saves storage and eases finding of non-trivial attributes in the ISO image. Efficiency slay. - Mode
"restore"enables restoring of attributes when their file gets restored, and comparing them during comparisons between files on disk and in ISO. Several modes below modify the behavior during restoring of attributes. - Mode
"no_restore"disables restoring of attributes. - Mode
"restore_su"enables restoring of the attributes"aij", which are only changeable by the bearer of superuser capabilities."no_restore_su"disables restoring of these attributes."restore_su_auto"enables it only if the effective user id is0. - The attribute
"i"(for"immutable") gets restored to directories only if they have been created freshly by the same file restoring xorriso command. A directory which already existed on disk will not be made immutable. No retroactive freezing, sorry. - Mode
"restore_only_known"restricts restoring to the known settable attribute flags"aAcCdDFijmPsStTux"."restore_unknown"enables the attempt to restore unknown flags or even those which are known to be unchangeable, if they are not disabled by other modes. Living dangerously, love that for you. - Mode
"restore_mask=..."enables particular attributes for restoring; all others will not be restored. The list of desired attribute letters follows the'='character. An empty list enables all attributes, if they are not disabled by other modes. The single character"-"bans all attributes from restoring, like"off"does. Example:
-lfa_flags restore_mask=SdCiaj- Mode
"restore_error="sets the behavior for the event that restoring of attribute flags to the local filesystem fails. Available are the keyword"silent"and the severities from"all"to"fatal"."silent"and severity"all"suppress any error messages and abort considerations caused by restore attempts of attribute flags. Otherwise the error message is issued with the given severity — and then it depends on the setting of command-abort_onwhether restoring goes on or gets aborted. The plot twist is yours to pick. - Mode
"restore_single"tries to set the attribute flags of a file one-by-one if the attempt to set them all at once fails. This happens only if the"restore_error="severity and the setting of command-abort_ondo not demand to abort the program run. Note that some flags in some situations get ignored silently by some kernels. Not our fault, the kernel's just like that 💀. - Mode
"no_restore_single"disables this attempt to get at least some of the attribute flags into effect. - Mode
"default"reinstates the default settings:
-lfa_flags off:read:restore:restore_su_auto:restore_only_known
-lfa_flags restore_mask=:restore_error=sorry:restore_singleUse "default:on" to get default settings with enabled processing. Best of both worlds ✨
-projid mode[:mode...]— turn XFS-style project ids on, off, or influence the way they get processed. 👑
Mode on says yes, record and restore those project ids. Mode off says nope, we're not doing that.
Mode restore_0 means: when files get extracted to disk, actually restore project id 0. The default is no_restore_0, which leaves the decision about the project id to the local filesystem — but only if the file has project id 0 in the ISO filesystem. 🫶
Mode map+ is where it gets ✨spicy✨ — it defines mappings of project id intervals in the ISO to project id intervals on disk, for when files get restored. The form is:
map+low_in_iso,high_in_iso=low_on_disk[,[high_on_disk]]low_in_iso and high_in_iso define the number interval from which the mapping happens at restore time. low_on_disk is the mapping result of low_in_iso. Project id numbers up to high_in_iso get mapped to
low_on_disk + (project_id - low_in_iso)If the resulting number is higher than high_on_disk, then it gets mapped to high_on_disk. A low_on_disk with no following comma means low_on_disk,low_on_disk, which maps the whole _in_iso interval to the single number low_on_disk. And low_on_disk, with no following number means low_on_disk,4294967295. 🎯
You can hand over multiple map+ modes with one or more -projid commands. Like:
-projid on:map+1,1=11,11:map+1000,1999=2000,The first match in the list of mappings defines the mapping of a given project id in the ISO. Fr fr, order matters. 💅
Pseudo-mode map_test= lets you peek at the current mapping of the given project number. It immediately reports the mapping result on result channel and does not change the current -projid settings. For example:
-projid map_test=1001Mode default throws away all defined mappings and sets -projid to off:no_restore_0. Clean slate energy. 🧚
-md5 "on"|"all"|"off"|"load_check_off"— enable or disable processing of MD5 checksums for the overall session and for each single data file. 🔥
If it's enabled, then images with checksum tags get loaded only if the tags of superblock and directory tree match properly. The MD5 checksums of data files and whole session get loaded from the image if there are any.
With the commands -compare and -update, the recorded MD5 of a file will be used to avoid content reading from the image. Only the disk file content will be read and compared with that MD5. This can save much time if -disk_dev_ino "on" is not suitable.
Commands which copy whole data files from ISO to hard disk will verify the copied data stream by the recorded MD5 — if -osirrox "check_md5_on" is set.
At image generation time, checksums are computed for each file which gets its data written into the new session. The checksums of files which have their data in older sessions get copied into the new session. Superblock, tree and whole session get a checksum tag each. 🏷️
Mode all will additionally check, during image generation, whether the checksum of a data file changed between the time when its reading began and the time when it ended. Heads up: this implies reading every file twice. 😭
Mode load_check_off together with on or all will load recorded MD5 sums but not test the recorded checksum tags of superblock and directory tree. This is necessary if growisofs was used as burn program, because it does not overwrite the superblock checksum tag of the first session. Therefore load_check_off is in effect when xorriso -as mkisofs option -M is performed.
The test can be re-enabled by mode load_check_on. 🔁
Checksums can be exploited via commands -check_md5, -check_md5_r, via find actions get_md5, check_md5, and via -check_media. ✨
-for_backup— turn on all the extra features that help you produce or restore backups with the highest fidelity of file properties. 💖 Currently this is a shortcut for:
-hardlinks on -acl on -xattr any -md5 on -projid onand possibly:
-lfa_flags default:on:import_only_settable
-lfa_flags restore_mask=aAcdDijmPsStTuxIf you 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 will 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. But at restore time, missing privileges or preconditions will cause failure events. 💀
Command -xattr "user" after command -for_backup will exclude non-user attributes from being recorded or restored.
The command -lfa_flags is executed by -for_backup only if the underlying libisofs was compiled with support for Linux file attributes — which is typically not the case on non-Linux systems. 🐧
If -lfa_flags is executed by -for_backup, then the restore mask enables all known settable attributes, except "C" and "F" which have special constraints which xorriso cannot yet detect at restore time. Command -lfa_flags "restore_mask=" after -for_backup will enable all known settable attributes.
-ecma119_map "stripped"|"unmapped"|"lowercase"|"uppercase"— pick how file names get converted when a session gets loaded, if they stem neither from a Rock Ridge name nor from a Joliet name. 🦋
Mode stripped is the default. It shows the names as found in the ISO but removes trailing ;1 or .;1 if present.
Mode unmapped shows names as found, without removing characters.
Warning: Multi-session convertsxyz;1toxyz_1and maybe adds new;1. ⚠️
Mode lowercase is like stripped but also maps uppercase letters to lowercase letters. This is compatible to default GNU/Linux mount behavior. 🌸
Mode uppercase is like stripped but maps lowercase letters to uppercase, if any occur despite the prescriptions of ECMA-119.
-joliet_map "stripped"|"unmapped"— pick how file names get converted when a session gets loaded from a Joliet tree. 🌈
Mode stripped is the default. It removes trailing ;1 or .;1 if present.
Mode unmapped shows names as found, without removing characters.
Warning: Multi-session convertsxyz;1toxyz_1and maybe adds new;1. ⚠️
-iso_nowtime "dynamic"|timestring— choose whether to use the current time ("dynamic") or a fixed time point for timestamps of ISO 9660 nodes that have no disk source file, and as the default for superblock timestamps. ⏰
If a timestring is given, then it is used for such timestamps. For the formats of timestrings see command -alter_date.
-disk_dev_ino "on"|"ino_only"|"off"— enable or disable processing of recorded file identification numbers (dev_tandino_t). 💾
If enabled, they are stored as xattr and can substantially accelerate file comparison. The root node gets a global start timestamp. If during comparison a file with younger timestamps is found in the ISO image, then it is suspected to have inconsistent content. 👀
If device numbers and inode numbers of the disk filesystems are persistent, and if no irregular alterations of timestamps or system clock happen, then potential content changes can be detected without reading that content. File content change is assumed if any of mtime, ctime, device number or inode number have changed.
Mode ino_only replaces the precondition that device numbers are stable by the precondition that mount points in the compared tree always lead to the same filesystems. Use this if mode on always sees all files changed. 🙈
The speed advantage appears only if the loaded session was produced with -disk_dev_ino "on" too.
Note that-disk_dev_ino "off"is totally in effect only if-hardlinksis"off", too. 💅
-file_name_limit [+]number— set the maximum permissible length for file names, in the range of 64 to 255. ✂️
Path components which are longer than the given number will get truncated and have their last 33 bytes overwritten by a colon ':' and the hex representation of the MD5 of the first 4095 bytes of the whole oversized name. Potential incomplete UTF-8 characters will get their leading bytes replaced by '_'.
iso_rr_paths with the long components will still be able to access the file paths with truncated components. 🫶
If -file_name_limit is executed while an ISO tree is present, the file names in the ISO tree get checked for existing truncated file names of the current limit, and for name collisions between newly truncated files and existing files. In both cases, the setting will be refused with a SORRY event. 😭
One may lift this ban by prepending the character "+" to the argument of -file_name_limit. Truncated filenames may then get truncated again, invalidating their MD5 part. Colliding truncated names are made unique, consuming at least 9 more bytes of the remaining name part.
If writing of xattr is enabled, then the length will be stored in "isofs.nt" of the root directory. If reading of xattr is enabled and "isofs.nt" is found, then the found length will get into effect if it is smaller than the current setting of -file_name_limit.
File name patterns will only work if they match the truncated name. This might change in future.
Files with truncated names get deleted and re-added unconditionally during -update and -update_r. This might change in future.
Linux kernels up to at least 4.1 misrepresent names of length 254 and 255. If you expect such names in or underdisk_pathsand plan to mount the ISO by such Linux kernels, consider to set-file_name_limit 253. Else just avoid names longer than 253 characters. 🐧
-rom_toc_scan"on"|"force"|"off"[:"emul_off"][:"emul_wide"]— bestie, read-only drives are lowkey liars. They don't tell you the actual media type, they just show any media as ROM (like DVD-ROM). And the session history of MMC multi-session media might get truncated to just first and last session, or honestly be completely false fr. (The emulated history of overwritable media is not affected by this tho, so breathe.) So like, to have a chance of getting the session history — especially the address of the last session — in case things fail, there's a scan for ISO 9660 filesystem headers. It might help. It also might give you worse results than the drive's own table of content 😭. At its end it can cause read attempts to invalid addresses, which means ugly drive behavior. Setting"on"enables that scan for alleged read-only media. Some operating systems literally can't mount the most recent session of a multi-session DVD or BD. If on such a system xorriso has no own MMC capabilities, it may still find that session from a scanned table of content. Setting"force"handles any media like a ROM medium with setting"on"✨. Flip side: the emulation of session history on overwritable media can hamper reading of partly damaged media 🙈. Setting"off:emul_off"disables the otherwise trustworthy table-of-content scan for those media. The table-of-content scan on overwritable media normally searches only up to the end of the session pointed to by the superblock at block 0. Setting"on:emul_wide"lets the scan continue all the way to the end of the medium 💅. This may be useful after copying a medium with-check_media patch_lba0=onwhen not the last session was loaded.-calm_drive"in"|"out"|"all"|"revoke"|"on"|"off"|"never"— controls reduction of drive noise until it's actually used again. Some drives stay alert for a substantial time after they've been used for reading or writing. That reduces the startup time for the next drive operation, but it can be loud and waste energy if no i/o with the drive is expected to happen soon 🔋. Modes"in","out","all"immediately calm down-indev,-outdev, or both, respectively. Mode"revoke"immediately alerts both drives ⚡. Mode"on"causes calming to be performed automatically after each-dev,-indev, and-outdev. Mode"off"disables this but still automatically calms a drive when it is given up without ejecting. Mode"leave"disables all automatic drive calming so that the drives might stay alert even after the end of the xorriso program run 😳. Drives will slow down on their own after some time of inactivity. This usually happens in several steps, no cap.-ban_stdio_write— allows for writing only the usage of MMC optical drives 🎀. Disallows writing the result into files of nearly arbitrary type. Once set, this command cannot be revoked. Periodt.-early_stdio_test"on"|"appendable_wo"|"off"— if enabled by"on", then regular files and block devices get tested for effective access permissions. This implies trying to open those files for writing, which otherwise will happen only later and only if actual writing is desired 👀. The test result is used for classifying the pseudo drives as overwritable, read-only, write-only, or uselessly empty. This may lead to earlier detection of severe problems, and may avoid some less severe error events ✨. Mode"appendable_wo"is like"on"with the additional property that non-empty write-only files are regarded as appendable rather than blank.-data_cache_sizenumber_of_tilesblocks_per_tile— sets the size and granularity of the data cache used when ISO images are loaded and when file content is read from ISO images. The cache consists of several tiles, which each consists of several blocks 🧱. A larger cache reduces the need for tiles being read multiple times. Larger tiles might additionally improve the data throughput from the drive, but can be wasteful if the data are scattered over the medium. Larger cache sizes help best with image loading from MMC drives 💖. They are an inferior alternative to-osirroxoption"sort_lba_on".blocks_per_tilemust be a power of 2. E.g.16,32, or64. The overall cache size must not exceed1 GiB. The default values can be restored by parameter"default"instead of one or both of the numbers. Currently the default is32tiles of32blocks =2 MiB🌸.
🦋 Inserting files into ISO image: 🦋
The following commands expect file addresses of two kinds:
disk_pathis a path to an object in the local filesystem tree.iso_rr_pathis the Rock Ridge name of a file object in the ISO image.
If no Rock Ridge information is recorded in the loaded ISO image, then you will see ISO 9660 names, which are of limited length and character set 😬. If no Rock Ridge information shall be stored in an emerging ISO image, then their names will get mapped to such restricted ISO 9660 (aka ECMA-119) names.
Note that in the ISO image you are as powerful as the superuser 👑. Access permissions of the existing files in the image do not apply to your write operations. They are intended to be in effect with the read-only mounted image.
If the iso_rr_path of a newly inserted file leads to an existing file object in the ISO image, then the following collision handling happens: if both objects are directories then they get merged by recursively inserting the subobjects from filesystem into ISO image 🫶. If other file types collide then the setting of command -overwrite decides. Renaming of files has similar collision handling, but directories can only be replaced, not merged. Note that if the target directory exists, then -mv inserts the source objects into this directory rather than attempting to replace it. Command -move, on the other hand, would attempt to replace it 👀.
The commands in this section alter the ISO image and not the local filesystem. Do not get it twisted.
-disk_pattern"on"|"ls"|"off"— sets the pattern expansion mode for thedisk_pathparameters of several commands which support this feature. Setting"off"disables this feature for all commands which are marked in this man page by"disk_path [***]"or"disk_pattern [***]". Setting"on"enables it for all those commands. Setting"ls"enables it only for those which are marked by"disk_pattern [***]". Default is"ls"✨.-addpathspec [...]|disk_path [***]— insert the given files or directory trees from filesystem into the ISO image 💖. If-pathspecsis set to"on"or"as_mkisofs"then pattern expansion is always disabled and character'='has a special meaning. It separates the ISO image path from the disk path:
iso_rr_path=disk_pathCharacter '=' in the iso_rr_path must be escaped by '\' (i.e. as "\="). With -pathspecs "on", the character '\' must not be escaped. The character '=' in the disk_path must not be escaped. With -pathspecs "as_mkisofs", all characters '\' must be escaped in both, iso_rr_path and disk_path. The character '=' may or may not be escaped in the disk_path. If iso_rr_path does not begin with '/' then -cd is prepended. If disk_path does not begin with '/' then -cdx is prepended. If no '=' is given then the word is used as both, iso_rr_path and disk path. If in this case the word does not begin with '/' then -cdx is prepended to the disk_path and -cd is prepended to the iso_rr_path. If -pathspecs is set to "off" then -disk_pattern expansion applies, if enabled. The resulting words are used as both, iso_rr_path and disk path. Relative path words get prepended the setting of -cdx to disk_path and the setting of -cd to iso_rr_path 🎀.
-add_plainlymode— if set to mode"unknown"then any command word that does not begin with"-"and is not recognized as known command will be subject to a virtual-addcommand. I.e. it will be used aspathspecor asdisk_pathand added to the image ✨. If enabled,-disk_patternexpansion applies todisk_paths. Mode"dashed"is similar to"unknown"but also adds unrecognized command words even if they begin with"-". Mode"any"announces that all further words are to be added aspathspecsordisk_paths. This does not work in dialog mode 😭. Mode"none"is the default. It prevents any words from being understood as files to add, if they are not parameters to appropriate commands.-path_listdisk_path— like-addbut reads the parameter words from filedisk_pathor standard input ifdisk_pathis"-". The list must contain exactly onepathspecordisk_pathpattern per line 💅.-quoted_path_listdisk_path— like-path_listbut with quoted input reading rules. Lines get split into parameter words for-add. Whitespace outside quotes is discarded 🦋.-mapdisk_pathiso_rr_path— insert file objectdisk_pathinto the ISO image asiso_rr_path. Ifdisk_pathis a directory then its whole sub tree is inserted into the ISO image 🌸.-map_singledisk_pathiso_rr_path— like-map, but ifdisk_pathis a directory then its sub tree is not inserted 🙈.-map_ldisk_prefixiso_rr_prefixdisk_path [***]— performs-mapwith each of thedisk_pathparameters.iso_rr_pathwill be composed fromdisk_pathby replacingdisk_prefixbyiso_rr_prefix✨.-updatedisk_pathiso_rr_path— compares file objectdisk_pathwith file objectiso_rr_path. If they do not match, then performs the necessary image manipulations to makeiso_rr_patha matching copy ofdisk_path💖. By default this comparison will imply lengthy content reading before a decision is made. Commands-disk_dev_inoor-md5may accelerate comparison if they were already in effect when the loaded session was recorded. Ifdisk_pathis a directory andiso_rr_pathdoes not exist yet, then the whole subtree will be inserted. Else only directory attributes will be updated 🎀.-update_rdisk_path iso_rr_path — bestie this is-updatebut make it recursive. ✨ Like, every file object below both addresses gets compared: do they have counterparts below the other address, and do both counterparts match? If there's a mismatch, the necessary update manipulation gets done. Simple as that. 💅
Heads up though: the comparison result may depend on command -follow. Its setting should always be the same as with the first adding of disk_path as iso_rr_path. Consistency is the vibe, don't switch up mid-run. 🫶
If iso_rr_path doesn't exist yet, then it gets added. If disk_path doesn't exist, then iso_rr_path gets deleted. No cap.
-update_ldisk_prefix iso_rr_prefix disk_path []* — performs-update_rwith each of the disk_path parameters. The iso_rr_path gets composed from disk_path by replacing disk_prefix by iso_rr_prefix. 🎀-update_liiso_rr_prefix disk_prefix iso_rr_path []* — performs-update_rwith each of the iso_rr_path parameters. The disk_path gets composed from iso_rr_path by replacing iso_rr_prefix by disk_prefix. 🦋-update_lxidisk_prefix iso_rr_prefix disk_path []* — performs-update_rwith each of the disk_path parameters and with iso_rr_paths in the ISO filesystem which are derived from the disk_path parameters after exchanging disk_prefix by iso_rr_prefix. So, other than-update_l, this one detects missing matches of disk_path and deletes the corresponding iso_rr_path. 👑
Note that relative disk_paths and disk_path patterns are interpreted as sub paths of the current disk working directory -cdx. The corresponding iso_rr_paths are derived by exchanging disk_prefix by iso_rr_prefix before pattern expansion happens. The current -cdi directory has no influence. periodt.
-cut_outdisk_path byte_offset byte_count iso_rr_path — maps 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. A symbolic link will only work if enabled by-follow "link"or"param". 🌸
Cutting out a byte interval may be necessary if the disk file is larger than a single medium, or if it exceeds the traditional limit of 2 GiB - 1 for old operating systems, or the limit of 4 GiB - 1 for newer ones. Contemporary Linux kernels are able to read properly files >= 4 GiB - 1. 💀
A clumsy remedy for such limits is to backup file pieces and to concatenate them at restore time. A well tested chopping size is 2047m. It is permissible to request a higher byte_count than available. The resulting file will be truncated to the correct size of a final piece. To request a byte_offset higher than available yields no file in the ISO image but a SORRY event. 😭
E.g:
-cut_out /my/disk/file 0 2047m \
/file/part_1_of_3_at_0_with_2047m_of_5753194821 \
-cut_out /my/disk/file 2047m 2047m \
/file/part_2_of_3_at_2047m_with_2047m_of_5753194821 \
-cut_out /my/disk/file 4094m 2047m \
/file/part_3_of_3_at_4094m_with_2047m_of_5753194821If the directory /file does no yet exist, then its permissions are not taken from directory /my/disk but rather from /my/disk/file with additional x-permission for those who have r-permission. 👀
While command -split_size is set larger than 0, and if all pieces of a file reside in the same ISO directory with no other files, and if the names look like above, then their ISO directory will be recognized and handled like a regular file. This affects commands -compare*, -update*, and overwrite situations. See command -split_size for details. 🧚
Another use case is copying the content of a device file as interval or as a whole into the emerging ISO filesystem. The fact that the byte_count is allowed to be unreasonably high enables copying of a whole device:
-cut_out /dev/sdd3 0 1000g /content_of_sdd3-cprdisk_path [] *iso_rr_path** — insert the given files or directory trees from filesystem into the ISO image. 🌈
The rules for generating the ISO addresses are similar as with shell command cp -r. Nevertheless, directories of the iso_rr_path are created if necessary. Especially a not yet existing iso_rr_path will be handled as directory if multiple *disk_path*s are present. The leafnames of the multiple *disk_path*s will be grafted under that directory as would be done with an existing directory. 💅
If a single disk_path is present then a non-existing iso_rr_path will get the same type as the disk_path.
If a disk_path does not begin with / then -cdx is prepended. If the iso_rr_path does not begin with / then -cd is prepended. ⭐
-mkdiriso_rr_path [...] — create empty directories if they do not exist yet. Existence as directory generates a WARNING event, existence as other file causes a FAILURE event. 😬-lnstarget_text iso_rr_path — create a symbolic link with address iso_rr_path which points to target_text. iso_rr_path may not exist yet. 🔗
Hint: Command -clone produces the ISO equivalent of a hard link.
-cloneiso_rr_path_original iso_rr_path_copy — create a copy of the ISO file object iso_rr_path_original with the new address iso_rr_path_copy. If the original is a directory then copy all files and directories underneath. If iso_rr_path_original is a boot catalog file, then it gets not copied but is silently ignored. 🙈
The copied ISO file objects have the same attributes. Copied data files refer to the same content source as their originals. The copies may then be manipulated independendly of their originals. 💫
This command will refuse execution if the address iso_rr_path_copy already exists in the ISO tree. (No overwriting, bestie, it's not that kind of party. 💀)
-cp_cloneiso_rr_path_original [] *iso_rr_path_dest — create copies of one or more ISO file objects as with command-clone. In case of collision merge directories with existing ones, but do **not overwrite existing ISO file objects. 🎀
The rules for generating the copy addresses are the same as with command -cpr (see above) or shell command cp -r. Other than with -cpr, relative iso_rr_path_original will get prepended the -cd path and not the -cdx path. Consider to -mkdir iso_rr_path_dest before -cp_clone so the copy address does not depend on the number of iso_rr_path_original parameters. iykyk 🫶
⚙️ Settings for file insertion ✨
-file_size_limitvalue [value [...]]--— set the maximum permissible size for a single data file. The values get summed up for the actual limit. If the only value is"off"then the file size is not limited by xorriso. Default is a limit of100extents,4g -2keach:
-file_size_limit 400g -200k --When mounting ISO 9660 filesystems, old operating systems can handle only files up to 2g -1 --. Newer ones are good up to 4g -1 --. You need quite a new Linux kernel to read correctly the final bytes of a file >= 4g if its size is not aligned to 2048 byte blocks. 😭
xorriso's own data read capabilities are not affected by operating system size limits. Such limits apply to mounting only. Nevertheless, the target filesystem of an -extract must be able to take the file size. (fr fr, disk full is a real thing. 💀)
Note: Running -compliance "iso_9660_level=1" or "iso_9660_level=2" sets the file size limit to 4g -1. Running -compliance "default" enlarges the limit to the default size if it was smaller. ⭐
-not_mgtcode[:code[...]] — control the behavior of the exclusion lists. 🚫
Exclusion processing happens before *disk_path*s get mapped to the ISO image, before disk files get compared with image files, and before image files get extracted to disk files.
The absolute disk paths involved in such an action are matched against the -not_paths list. The leafnames of disk paths are matched against the patterns in the -not_leaf list. If a match is detected then the disk path will not be regarded as an existing file and not be added to the ISO image.
Several codes are defined. The _on/_off settings persist until they are revoked by their _off/_on counterparts. 👑
"erase"empties the lists which were accumulated by-not_pathsand-not_leaf."reset"is like"erase"but also re-installs default behavior."off"disables exclusion processing temporarily without invalidating the lists and settings."on"re-enables exclusion processing."param_off"applies exclusion processing only to paths below disk_path parameter of commands. I.e. explicitly given *disk_path*s are exempted from exclusion processing."param_on"applies exclusion processing to command parameters as well as to files below such parameters."subtree_off"with"param_on"excludes parameter paths only if they match a-not_pathsitem exactly."subtree_on"additionally excludes parameter paths which lead to a file address below any-not_pathsitem."ignore_off"treats excluded disk files as if they were missing. I.e. they get reported with-compareand deleted from the image with-update."ignore_on"keeps excluded files out of-compareor-updateactivities. 💅
-not_pathsdisk_path [*]** — add the given paths to the list of excluded absolute disk paths. If a given path is relative, then the current-cdxis prepended to form an absolute path. Pattern matching, if enabled, happens at definition time and not when exclusion checks are made. 🦋
Keep in mind that there may be alternative paths to the same disk file. The exclusion tests are done literally, so that they do not keep files from getting into the ISO filesystem by other paths. Accordingly an exclusion does not prevent a disk file from being overwritten by file extraction via an alternative not excluded path. So the exclusions need to be coordinated with the actual disk_path parameters given with commands. 😬
(Do not forget to end the list of *disk_path*s by "--")
-not_leafpattern — add a single shell parser style pattern to the list of exclusions for disk leafnames. These patterns are evaluated when the exclusion checks are made. 🍓-not_listdisk_path — bestie, this one reads lines straight out of disk_path and then decides what each line is gonna be. If a line has a/in it? Boom, it becomes a-not_pathsparameter. No slash? Then it's a-not_leafpattern instead. ✨-quoted_not_listdisk_path — literally-not_listbut it reads its input with quoted input reading rules. Every single word gets handled as one parameter for-not_pathsor-not_leaf. 💅-followoccasion[:occasion[...]] — this turns resolution of symbolic links and mountpoints on or off under disk_paths. It applies to the actions-add,-cut_out,-du*x,-ls*x,-findx,-concat, and to-disk_patternexpansion. 🦋
There are three main kinds of follow decision to be made, and they're giving very different energy:
- link — the hop from a symbolic link to its target file object for the purpose of reading. (Not for command
-concat, ok?) If it's enabled, symbolic links get handled as their target file objects; if not, they get handled as themselves. 🙈 - mount — the hop from one filesystem to another subordinate filesystem. Enabled means mountpoint directories are handled like any other directory. Disabled means mountpoints get handled as empty directories if they show up during directory tree traversals. 🏔️
- concat — the hop from a symbolic link to its target file object for the purpose of writing. (So, for command
-concat.) Heads up: this is a security risk ! 😭
Now the less general occasions, for the girlies who need finer control:
- pattern — is mount and link hopping, but only during
-disk_patternexpansion. - param — is link hopping for parameter words (after eventual pattern expansion). If enabled then
-ls*xwill show the link targets rather than the links themselves.-du*x,-findx, and-addwill process the link targets but not follow links in an eventual directory tree below the targets (unless"link"is enabled).-cut_outwill process link targets.
Occasions can be combined in a colon separated list. Every occasion you mention in that list leads to a positive follow decision. 💖
- off — prevents any positive follow decision. Use it if no other occasion applies.
- default — a shortcut, equivalent to
"pattern:mount:limit=100". - on — always decides positive. Equivalent to
"link:mount:concat".
Not an occasion, but an optional setting, is:
- limit= <number> — sets the maximum number of link hops. A link hop is a sequence of symbolic links plus a final target of a different type. And ngl, those hops can loop. Example:
$ ln -s .. uploopLink hopping has a built-in loop detection that stops hopping at the first repetition of a link target. When that happens, the repeated link gets handled as itself and not as its target. 😵💫 Regrettably, one can construct link networks which cause exponential workload before their loops get detected. The number you give with "limit=" can curb this workload, at the risk of truncating an intentional sequence of link hops. So like… pick your poison, bestie.
-pathspecs"on"|"off"|"as_mkisofs"— controls parameter interpretation with the xorriso actions-addand-path_list. ✨- Mode
"as_mkisofs"enables pathspecs of the form
- Mode
iso_rr_path=disk_pathlike with program mkisofs -graft-points. All characters \ must be escaped in both, iso_rr_path and disk_path. The character = must be escaped in the iso_rr_path and may or may not be escaped in the disk_path. This mode temporarily disables -disk_pattern expansion for command -add. 🎀
- Mode
"on"does nearly the same. But=must only be escaped in the iso_rr_path and\must not be escaped at all. This has the disadvantage that one cannot express an iso_rr_path which ends by\. 🥲 - Mode
"off"disables pathspecs of the formtarget=sourceand re-enables-disk_patternexpansion.
-overwrite"on"|"nondir"|"off"— allow or disallow overwriting of existing files in the ISO image or in the local filesystem by files with the same name. 👑- With setting
"off", name collisions with at least one non-directory file cause FAILURE events. Collisions of two directories lead to merging of their file lists. - With setting
"nondir", only directories are protected by such events; other existing file types get treated with-rmbefore the new file gets added. - Setting
"on"enables automatic-rm_r. I.e. a non-directory can replace an existing directory and all its subordinates. 💀
- With setting
If restoring of files to the disk filesystem is enabled by -osirrox, then the overwrite rule applies to the target file objects on disk as well, but "on" is downgraded to "nondir".
-split_sizenumber["k"|"m"]— sets the threshold for automatic splitting of regular files. Such splitting maps a large disk file onto a ISO directory with several part files in it. This is necessary if the size of the disk file exceeds-file_size_limit. Older operating systems can handle files in mounted ISO 9660 filesystems only if they are smaller than 2 GiB or in other cases 4 GiB. 🫶
Default is 0, which will exclude files larger than -file_size_limit by a FAILURE event. A well tested -split_size is 2047m. Sizes above -file_size_limit are not permissible. ⚠️
The newly created ISO directory inherits its permissions from the data file with additional x-permission for those who have r-permission.
While command -split_size is set larger than 0, such a directory with split file pieces will be recognized and handled like a regular file by commands -compare*, -update*, and in overwrite situations. There are -osirrox parameters "concat_split_on" and "concat_split_off" which control the handling when files get restored to disk. 💾
In order to be recognizable, the names of the part files have to describe the splitting by 5 numbers:
part_number,total_parts,byte_offset,byte_count,disk_file_sizewhich are embedded in the following text form:
part_#_of_#_at_#_with_#_of_#Scaling characters like "m" or "k" are taken into respect. All digits are interpreted as decimal, even if leading zeros are present.
E.g: /file/part_1_of_3_at_0_with_2047m_of_5753194821
No other files are allowed in the directory. All parts have to be present and their numbers have to be plausible. E.g. byte_count must be valid as -cut_out parameter and their contents may not overlap. 🧚
💖 File manipulations: 💖
The following commands manipulate files in the ISO image, regardless whether they stem from the loaded image or were newly inserted. It's giving ✨renovation era✨.
-iso_rr_pattern"on"|"ls"|"off"— sets the pattern expansion mode for the iso_rr_path parameters of several commands which support this feature.- Setting
"off"disables pattern expansion for all commands which are marked in this man page by"iso_rr_path [***]"or"iso_rr_pattern [***]". - Setting
"on"enables it for all those commands. - Setting
"ls"enables it only for those which are marked by"iso_rr_pattern [***]".
- Setting
Default is "on". 🌈
-rmiso_rr_path[***]— delete the given files from the ISO image. 🗑️
Note: This does not free any space on the -indev medium, even if the deletion is committed to that same medium. The image size will shrink if the image is written to a different medium in modification mode.
-rm_riso_rr_path[***]— delete the given files or directory trees from the ISO image. See also the note with command-rm. 🌳💥-rmdiriso_rr_path[***]— delete empty directories. Only the empty ones, bestie, don't get cute.-moveiso_rr_path iso_rr_path — rename the file given by the first (origin) iso_rr_path to the second (destination) iso_rr_path. Deviate from rules of shell commandmvby not moving the origin file underneath an existing destination directory. The origin file will rather replace such a directory, if this is allowed by command-overwrite. 😳-mviso_rr_path[***]iso_rr_path — rename the given file objects in the ISO tree to the last parameter in the list. Use the same rules as with shell commandmv. If pattern expansion is enabled and if the last parameter contains wildcard characters then it must match exactly one existing file address, or else the command fails with a FAILURE event. 🔥-chownuid iso_rr_path[***]— set ownership of file objects in the ISO image. uid may either be a decimal number or the name of a user known to the operating system. 👑-chown_ruid iso_rr_path[***]— like-chownbut affecting all files below eventual directories. So it's the recursive version, she's thorough. 💜-chgrpgid iso_rr_path[***]— set group attribute of file objects in the ISO image. gid may either be a decimal number or the name of a group known to the operating system. 🫶-chgrp_rgid iso_rr_path[***]— like-chgrpbut affecting all files below eventual directories.-chmodmode iso_rr_path[***]— equivalent to shell commandchmodin the ISO image. mode is either an octal number beginning with"0"or a comma separated list of statements of the form[ugoa]*[+-=][rwxst]*. Like:go-rwx,u+rwx. 💅
Personalities: u=user, g=group, o=others, a=all
Operators: + adds given permissions, - revokes given permissions, = revokes all old permissions and then adds the given ones.
Permissions: r=read, w=write, x=execute|inspect, s=setuid|setgid, t=sticky bit
For octal numbers see man 2 stat.
-chmod_rmode iso_rr_path[***]— like-chmodbut affecting all files below eventual directories. Recursion, she ate. 🎀-setfaclacl_text iso_rr_path[***]— bestie, this one slaps ACLs (access control lists) onto the iso_rr_paths you name. Heads up though: if those files already had ACLs, the old ones get yeeted before the new ones kick in. If acl_text is empty, or literally just saysclearor--remove-all, then the existing ACLs get removed and nothing new gets attached — clean slate energy. Anything else in acl_text gets read as a list of ACL entries, and it can come in the long multi-line format that-getfaclspits out, or you can do the abbreviated thing. Here's the breakdown:- Entries are separated by comma or newline. Empty entries, or ones starting with
#, get ignored — not me ghosting them, they just don't count. - A valid entry has to start with a letter from
{ugom}— that's"user","group","other","mask"💅 - It has to have two colons
":". The non-empty text between them is the user id or group id. - After that second
":"you can have letters from{rwx- #}. The first three are read, write, execute. The letters"-"," "and TAB get ignored. A"#"makes the rest of that entry get ignored. - Letter
"X"or literally any other letter? Not supported. Sorry babes. - Examples, iconic as always:
- Entries are separated by comma or newline. Empty entries, or ones starting with
g:toolies:rw,u:lisa:rw,u:1001:rw,u::wr,g::r,o::r,m::rw
group:toolies:rw-,user::rw-,group::r--,other::r--,mask::rw-- Oh and a valid entry can be prefixed by
"d", some characters after it, and":"— that means the entry goes to the "default" ACL instead of the "access" ACL. Example:
u::rwx,g::rx,o::,d:u::rwx,d:g::rx,d:o::,d:u:lisa:rwx,d:m::rwx-setfacl_racl_text iso_rr_path[***]— same vibe as-setfaclbut it hits all the files below the given directories. Recursive queen 👑-setfacl_listdisk_path — reads the output of-getfacl_ror the shell commandgetfacl -Rand applies it to the iso_rr_paths as given in lines starting with"# file:". This will change ownership, group and ACL of the given files. If disk_path is"-"then lines get read from standard input. Line"@"ends the list, and"@@@"aborts without changing the pending iso_rr_path. Since-getfaclandgetfacl -Rstrip the leading"/"off file paths, the setting of-cdalways matters here, fr fr.
-setfattr[-]name value iso_rr_path[***]— attaches that given xattr pair of name and value to the given iso_rr_paths. If name is prefixed with"-", then the pair with that name gets removed from the xattr list. If name is"--remove-all"then all user namespace xattr of the given iso_rr_paths get deleted. And for deletion? value must be empty text, no exceptions.
Which names are even allowed depends on the setting of command -xattr. "on" or "user" restricts them to namespace "user" — so a name has to look like "user.x" or "user.whatever". Setting -xattr to "any" enables names from all namespaces except "isofs".
Values and names go through xorriso's normal input processing, so peep command -backslash_codes for that. And unlike -setfattr_list, the byte value 0 cannot be expressed via -setfattr. Rude but true.
-setfattr_r[-]name value iso_rr_path[***]— like-setfattrbut it also hits all files below the given directories 🦋-setfattr_listdisk_path — reads the output format of-getfattr_ror shell commandgetfattr -Rdand applies it to the iso_rr_paths as given in lines starting with"# file:". Every previously existing xattr of the acceptable namespaces gets deleted before the new xattr get attached. Which names are acceptable depends on the setting of command-xattr. If disk_path is"-"then lines get read from standard input. Since-getfattrandgetfattr -Rdstrip the leading"/"off file paths, the setting of-cdalways matters here too.
Empty input lines and lines starting with "#" get ignored — except "# file:", she's special. Line "@" ends the list, "@@@" aborts without changing the pending iso_rr_path. Every other input line has to be in this form:
name="value"The separator "=" is not allowed in names. value can contain literally any kind of bytes and must be in quotes. Trailing whitespace after the closing quote gets ignored. Non-printable bytes and quotes have to be written as \XYZ using their octal 8-bit code XYZ. Use code \000 for 0-bytes. Periodt.
-chattrmode iso_rr_path[***]— sets or unsets Linux file attributes, exactly like programchattr(1)would do to disk files. Applying this to files that are neither a directory nor a regular data file will give you a SORRY event 😭 — unless the mode is"--remove-lfa-flags". The first letter of the mode string decides what goes down. The other letters are symbolic attribute flag letters from the set"aAcCdDeEFhiIjNmPsStTuVxZ"as described inman 1 chattr. There's no restriction on which attributes can be set or unset, but bestie listen — at restore time, unusual or unsuitable attributes may cause problems. You've been warned.- First letter
'+'sets the given attribute flags. All other attributes stay exactly as they are. - First letter
'-'unsets the given attribute flags. All other attributes stay as they are. (Also note'-'is accepted as a symbolic attribute letter that has no effect. She's just there.) - Special case: mode string
"--remove-lfa-flags"causes the Linux file attribute information to be removed from the file entirely. The-findtest-has_lfa_flags"-"will then not match the file any more. - First letter
'.'causes all attribute flags except the given ones to be unset. The given ones stay as they are. And ngl, this is not a feature of programchattr(1)— xorriso is just extra like that. - First letter
'='sets the given attribute flags and unsets all the others. Mode"=-"leads to all attribute flags being unset, but-findtest-has_lfa_flags"-"will match the file afterwards. - Example, bookmark it:
- First letter
-chattr +sDu /my/file /my/other_file ---chattr_rmode iso_rr_path[***]— like-chattrbut it also affects all suitable files below the given directories. Except with mode"--remove-lfa-flags", the given iso_rr_path parameters need to be directories or regular data files or else a SORRY event happens. Files below the given directories get skipped silently if their type isn't suitable for-chattr🤫-set_projidnumber iso_rr_path[***]— sets the XFS-style project ids, like programsxfs_quota(8)orchattr(1)would do to disk files. The permissible number range is0to4294967295. A0means the file doesn't belong to any project. Solo era 💅-set_projid_rnumber iso_rr_path[***]— like-projidbut it also hits all files below the given directories.
-alter_datetype timestring iso_rr_path[***]— alters the date entries of files in the ISO image. type can be one of these:"a"sets access time, updates ctime."m"sets modification time, updates ctime."b"sets access time and modification time, updates ctime."a-c","m-c", and"b-c"set the times without updating ctime."c"sets the ctime.
Now timestring, and there are so many formats bestie, keep up (also see section EXAMPLES):
- As expected by program
date:
MMDDhhmm[[CC]YY][.ss]]- As produced by program
date:
[Day] MMM DD hh:mm:ss [TZON] YYYY- Relative times counted from the current clock time:
+|-Number["s"|"h"|"d"|"w"|"m"|"y"]where "s" means seconds, "h" hours, "d" days, "w" weeks, "m"=30d, "y"=365.25d plus 1d added to the multiplication result.
- Absolute seconds counted from Jan 1 1970 00:00 GMT:
=Number- xorriso's own timestamps:
YYYY.MM.DD[.hh[mm[ss]]]- scdbackup timestamps:
YYMMDD[.hhmm[ss]]where "A0" is year 2000, "B0" is 2010, etc.
- ECMA-119 volume timestamps:
YYYYMMDDhhmmssccThese are normally given as GMT. The suffix "LOC" causes local timezone conversion. E.g. 2013010720574700, 2013010720574700LOC. The last two digits cc (centiseconds) get ignored, but they must be present in order to make the format recognizable. Iconic lil quirk.
Example:
-alter_date m-c 2013.11.27.103951 /file1 /file2 --Heads up: this command does not persistently apply to the boot catalog, which gets fresh timestamps at-committime. Command-volume_date"uuid"can set this time value instead.
-alter_date_rtype timestring iso_rr_path[***]— like-alter_datebut it hits all files below eventual directories.
-hidehide_state iso_rr_path[***]— stops the names of the given files from showing up in the directory trees of ISO 9660 and/or Joliet and/or HFS+ when the image gets written. The data content of these hidden files still gets included in the resulting image, even if they don't show up in any directory — but you'll need your own means to find nameless data in the image. Sneaky ghost files 👻
⚠️ Warning bestie: data that's hidden from the ISO 9660 tree will not be copied by the write method of modifying. That's a big deal, don't sleep on it.
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. "off" means visibility in all directory trees.
These values can be combined. E.g.: joliet:hfsplus
This command does not apply to the boot catalog. Rather use:
-boot_image "any" "cat_hidden=on"Tree traversal command -find:
-find iso_rr_path [test [op] [test ...]] [-exec action [params]] --— ok so picture the shellfindcommand but make it a ✨restricted✨ little sibling that only lives inside the ISO image. It runs an action on matching file objects at or belowiso_rr_path. 🦋
If you're not using it as the last command on the line, bestie, you MUST terminate the parameter list with --. fr fr.
Tests are optional. Omit them and the action gets applied to all file objects. Give it tests and they all vibe together into one expression — the action only fires if that expression matches the file object. The default operator chilling between tests is -and, meaning the expression only matches when every single test matches. periodt. 👑
Available tests are:
-name pattern— matches if pattern matches the file leaf name. If pattern contains none of the characters*?[, it gets truncated according to-file_name_limitand thus matches the truncated name in the ISO filesystem.-wholename pattern— matches if pattern matches the file path as it would be printed by action"echo". The character/can be matched by wildcards. If the pattern pieces between/contain none of the characters*?[, they get truncated according to-file_name_limit.-disk_name pattern— like-namebut it tests the leaf name of the file source on disk. It can only match data files which do not stem from the loaded image, or for directories above such data files. With directories the result can change between-findruns if their content stems from multiple sources. 🙈-disk_path disk_path— matches if the given disk_path is equal to the path of the file source on disk. The same restrictions apply as with-disk_name.-type type_letter— matches files of the given type:"block","char","dir","pipe","file","link","socket","eltorito", and"Xotic"which matches whatever the other types don't. Only the first letter is interpreted. e.g.-find / -type d-size [+-][=]number[cwbdksmg]— matches files with a matching relation to the given size number. The prefix defines the relation you want:- no prefix or prefix
=— the file must have exactly the given size. - prefix
+— the file must be larger than the given size. - prefix
+=— the file must be larger than or equal to the given size limit. - prefix
-— the file must be smaller than the given size limit. - prefix
-=— the file must be smaller than or equal to the given size limit.
- no prefix or prefix
Suffixes are a lil peculiar so they stay compatible with the program find:
- no suffix — blocks of 512 bytes
c— single bytesw— 2 bytesb— 512 bytes
The suffixes k, M, and G mean 1024, 1024k, and 1024M respectively. And as usual with xorriso, the suffixes d and s mean 512 and 2048, and all suffixes get recognized as both uppercase and lowercase letters. e.g. match files of 4 GiB or larger: -size +=4g
-maxdepth number— matches only files which are at most at the given depth level relative to theiso_rr_pathwhere-findstarts. That path itself is at depth 0, its directory children are at 1, their directory children at 2, and so on. 🌸-mindepth number— matches only files which are at least at the given depth level.-damaged— matches files which use data blocks marked as damaged by a previous run of-check_media. The damage info vanishes when a new ISO image gets loaded.
⚠️ Heads up: an MD5 session mismatch marks all files of the session as damaged. If you want a finer distinction, run-md5 offbefore-check_media. 😭
-pending_data— matches files which get their content from outside the loaded ISO image.-lba_range start_lba block_count— matches files which use data blocks within the range of start_lba and start_lba+block_count-1.-has_acl— matches files which have a non-trivial ACL.-has_xattr— matches files which have xattr name-value pairs from the user namespace.-has_any_xattr— matches files which have any xattr other than ACL.-has_aaip— matches files which have ACL or any xattr.-has_lfa_flags flag_letters— matches files which have Linux file attributes attached and have all flags set which correspond to the characters in the string flag_letters. The characters may be zero or more out of the set"aAcCdDeEFhiIjNmPsStTuVxZ". The character-gets ignored. The flag_letters string-matches any attribute set, but not a file with no Linux file attributes attached. e.g. look for files with both flagsi(immutable) andd(no dump) set:-has_lfa_flags di-has_some_lfa_flags_of flag_letters— similar to-has_lfa_flagsbut matching files which have at least one of the flags set which correspond to the characters in the string flag_letters. The flag_letters string-never matches any file. e.g. look for files which haveioraor both of them set:-has_some_lfa_flags_of ia-has_projid number— matches files which bear the given XFS-style project id number.-has_md5— matches data files which have MD5 checksums.-has_hfs_crtp creator type— matches files which have the given HFS+ creator and type attached. These are codes of 4 characters which get stored if-hfsplusis enabled. Use a single dash-as a wildcard that matches any such code. e.g.:
-has_hfs_crtp YYDN TEXT
-has_hfs_crtp - --has_hfs_bless blessing— matches files which bear the given HFS+ blessing. It may be one of:"ppc_bootdir","intel_bootfile","show_folder","os9_folder","osx_folder","any". See also actionset_hfs_bless.-has_filter— matches files which are filtered by-set_filter.-hidden hide_state— matches files which are hidden in the"iso_rr"tree, in the"joliet"tree, in the"hfsplus"tree, in all trees ("on"), or not hidden in any tree ("off"). Those which are hidden in some tree match-not -hidden "off".-bad_outname namespace— matches files with names which change when converted forth and back between the local character set and one of the namespaces"rockridge","joliet","ecma119","hfsplus".
All applicable -compliance rules get taken into respect. Rule "omit_version" is always enabled, because otherwise the namespaces "joliet" and "ecma119" would cause changes with every non-directory name. Consider also enabling rules "no_force_dots" and "no_j_force_dots".
The namespaces use different character sets and apply further restrictions to name length, permissible characters, and mandatory name components. "rockridge" uses the character set defined by -out_charset, "joliet" uses UCS-2BE, "ecma119" uses ASCII, "hfsplus" uses UTF-16BE.
-name_limit_blocker length— matches file names which would prevent command-file_name_limitwith the given length. The command itself reports only the first problem file.-prune— if this test is reached and the tested file is a directory, then-findwill not dive into that directory. This test itself does always match. 💅-use_pattern "on"|"off"— this pseudo test controls the interpretation of wildcards with tests-name,-wholename, and-disk_name. Default is"on". If interpretation is disabled by"off", then the parameters of-name,-wholename, and-disk_namehave to match literally rather than as a search pattern. This test itself does always match.-or_use_pattern "on"|"off"— like-use_pattern, but it automatically appends the test by-orrather than by-and. Further, the test itself does never match. So a subsequent test-orwill cause its other operand to be performed.-decision "yes"|"no"— if this test is reached, then the evaluation ends immediately and the action is performed if the decision is"yes"or"true". See operator-if.-trueand-false— always match or match not, respectively. Evaluation goes on.-sort_lba— always match. This causes-findto perform its action in a sequence sorted by the ISO image block addresses of the files. It may improve throughput with actions which read data from optical drives. The action will always get the absolute path as parameter.
Available operators are:
-not— matches if the next test or sub expression does not match. Several tests do this specifically:-undamaged,-lba_rangewith negative start_lba,-has_no_acl,-has_no_xattr,-has_no_aaip,-has_no_filter.-and— matches if both neighboring tests or expressions match.-or— matches if at least one of both neighboring tests or expressions matches.-sub ... -subendor( ... )— enclose a sub expression which gets evaluated first before it is processed by neighboring operators.- Normal precedence is:
-not,-or,-and. -if ... -then ... -elseif ... -then ... -else ... -endif— enclose one or more sub expressions. If the-ifexpression matches, then the-thenexpression is evaluated as the result of the whole expression up to-endif. Else the next-elseifexpression is evaluated and if it matches, its-thenexpression. Finally, in case of no match, the-elseexpression is evaluated. There may be more than one-elseif. Neither-elsenor-elseifare mandatory. If-elseis missing and would be hit, then the result is a non-match.-if-expressionsare the main use case for the above test-decision.
echo— the default action, bestie 💅 it just prints the address of the file it found. The other actions below are actual xorriso commands that get performed on the found files, and some of them take their own specific parameters. Go read their individual descriptions too, fr fr.chown,chown_r— changes the ownership, and it takes a user id as its parameter. E.g.:-exec chown thomas --chgrp,chgrp_r— changes the group attribute, and it takes a group id as its parameter. E.g.:-exec chgrp_r staff --chmod,chmod_r— changes access permissions, and it takes a mode string as its parameter. E.g.:-exec chmod a-w,a+r --alter_date,alter_date_r— changes the timestamps. These take a type character and a timestring as parameters. E.g.:-exec alter_date "m" "Dec 30 19:34:12 2007" --set_to_mtime— sets the ctime and atime to whatever value it finds in mtime. cute little sync moment 🎀lsdl— prints file information just like the shell commandls -dl.show_time— prints the timestamp of the given type plus the file path. Unlikelsdl, the time here is always shown exact to the second. This action takes a type text as parameter, and that text has to start with one of the letters'a','c', or'm'to ask for atime, ctime, or mtime. Letters'u'or'U'may be appended to request UTC instead of local time. Letter's'may be appended to request sortable timestamps of the formYYYY.MM.DD.hhmmsslike2025.10.03.183911. Heads up though: for ASCII-alphabetic sortability, the year 10000 is represented as"999A"and the year -1 is represented as"-001". E.g.:-exec show_time mus --compare— performs command-comparewith the found file address as iso_rr_path and the corresponding file address below its parameter disk_path_start. For this, the iso_rr_path of the-findcommand gets replaced by the disk_path_start. E.g.:-find /thomas -exec compare /home/thomas --update— performs command-updatewith the found file address as iso_rr_path. The corresponding file address is determined the same way as with the actioncompareabove.update_merge— likeupdate, but it does not delete the found file if it's missing on disk. It may be run several times, and it records with all visited files whether their counterpart on disk has already been seen by one of theupdate_mergeruns. Then, finally, a-findrun with actionrm_mergemay remove all files that saw no counterpart on disk.- Up to the next
"rm_merge"or"clear_merge", all newly inserted files will get marked as having a disk counterpart. ✨ rm— removes the found iso_rr_path from the image, but only if it is not a directory with files in it. I.e. this"rm"includes"rmdir".rm_r— removes the found iso_rr_path from the image, including whole directory trees. yeah she's thorough 💅rm_merge— removes the found iso_rr_path if it was visited by one or more previous actions"update_merge"and saw no counterpart on disk in any of them. The marking from the update actions is removed in any case.clear_merge— removes an eventual marking from action"update_merge".report_damage— classifies files by whether they hit a data block that is marked as damaged. The result is printed together with the address of the first damaged byte, the maximum span of damages, file size, and the path of the file. 😭report_lba— prints files which are associated to image data blocks. It tells the logical block address, the block number, the byte size, and the path of each file. There may be more than one line reported per file if the file has more than one section. In that case each line has a different extent number in column"xt".report_sections— likereport_lba, but telling the byte sizes of the particular sections rather than the overall byte size of the file.getfacl— prints access permissions in ACL text form to the result channel.setfacl— attaches ACLs after removing the existing ones. The new ACL is given in text form as defined with command-setfacl. E.g.:-exec setfacl u:lisa:rw,u::rw,g::r,o::-,m::rw --getfattr— prints xattr name-value pairs to the result channel. The choice of namespaces depends on the setting of command-xattr:"off","on", or"user"restricts it to the namespace"user", while"any"only omits namespace"isofs".get_any_xattr— prints xattr name-value pairs from any namespace except ACL to the result channel. This is mostly for debugging of namespace"isofs".list_extattrmode — prints a script to the result channel which would use the FreeBSD commandsetextattrto set the file's xattr name-value pairs of user namespace. The parameter mode controls the form of the output of names and values. Default mode"e"prints harmless characters in shell quotation marks, but represents texts with octal001to037and0177to0377by an embeddedecho -ecommand. Mode"q"prints any characters in shell quotation marks — this might not be terminal-safe but should work in script files. Mode"r"uses no quotation marks. Not safe. Mode"b"prints backslash encoding. Not suitable for shell parsing. E.g.:-exec list_extattr e --- Command
-backslash_codesdoes not affect the output. (not me pointing that out 🙈) lsattrd— shows the Linux file attribute flags, like command-lsattrddoes.chattrmode — applies-chattrwith the given mode. Other than command-chattr, this silently skips any file which is not-type"dir"or"file". E.g.:-exec chattr +sDu --get_projid— shows the XFS-style project id number.get_projid_minmax— shows at the end of the-findrun the minimal and the maximal XFS-style project id numbers among the files which were matched by the find tests.set_projidnumber — applies-set_projidwith the given number. Number range is0to4294967295. E.g.:-exec set_projid 1001 --get_md5— prints the MD5 sum, if recorded, together with the file path.check_md5— compares the MD5 sum, if recorded and loaded, with the file content and reports if there's a mismatch. E.g.:-find / -not -pending_data -exec check_md5 FAILURE --make_md5— equips a data file with an MD5 sum of its content. Super useful for upgrading the files in the loaded image to full MD5 coverage by the next commit with-md5 "on". E.g.:-find / -type f -not -has_md5 -exec make_md5 --setfattr— sets or deletes xattr name value pairs. E.g.:-find / -has_xattr -exec setfattr --remove-all '' --set_hfs_crtp— adds, changes, or removes HFS+ creator and type attributes. E.g.:
-exec set_hfs_crtp YYDN TEXT-find /my/dir -prune -exec set_hfs_crtp --delete -get_hfs_crtp— prints the HFS+ creator and type attributes together with the iso_rr_path, if the file has such attributes at all. E.g.:-exec get_hfs_crtpset_hfs_bless— applies or removes HFS+ blessings. These 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. The-findrun will end as soon as the first blessing is issued — and the previous bearer of the blessing will lose it then. No file object can bear more than one blessing. E.g.:-find /my/blessed/directory -exec set_hfs_bless p - Further, there's blessing
"none"or"n"which revokes any blessing from the found files. This-findrun will not stop when the first match is reached. E.g.:-find / -has_hfs_bless any -exec set_hfs_bless none get_hfs_bless— prints the HFS+ blessing role and the iso_rr_path, if the file is blessed at all. E.g.:-exec get_hfs_blessset_filter— applies or removes filters. E.g.:-exec set_filter --zisofs --mkisofs_r— applies the rules ofmkisofs -rto the file object: user id and group id become0, all r-permissions get granted, all w denied. If there's any x-permission, then all three x get granted. s- and t-bits get removed.sort_weight— attributes an LBA weight number to regular files. The number may range from-2147483648to2147483647. The higher it is, the lower will be the block address of the file data in the emerging ISO image. Currently the boot catalog has a hardcoded weight of 1 billion. Normally it should occupy the block with the lowest possible address. 👑- Data files which are loaded by
-indevor-devget 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. - Data files which are added by other commands get an initial weight of
0. Boot image files have a default weight of2. E.g.:-exec sort_weight 3 -- show_stream— shows the content stream chain of a data file.show_stream_id— likeshow_stream, but also prints between stream type and first":"in square brackets libisofs id numbers:[fs_id,dev_id,ino_id].hide— brings the file into one of the hide states"on","iso_rr","joliet","hfsplus","off". They may be combined. E.g.:joliet:hfsplus- E.g.:
-find / -disk_name *_secret -exec hide onprint_outname— prints in the first line the filename as registered by the program model, and in the second line the filename after conversion forth and back between local character set and one of the namespaces"rockridge","joliet","ecma119", or"hfsplus". The third output line is"--".- The name conversion does not take into respect the possibility of name collisions in the target namespace. Such collisions are most likely in
"joliet"and"ecma119", where they get resolved by automatic file name changes. - E.g.:
-find / -bad_outname joliet -exec print_outname jolietestimate_size— prints a lower and an upper estimation of the number of blocks which the found files together will occupy in the emerging ISO image. This does not account for the
superblock, for the directories in the -find path, or for image padding, bestie. ✨
find then does another whole run of -find on the matching file address. It takes the same params as -find, except iso_rr_path. Like, for example:
-find / -name '???' -type d -exec find -name '[abc]*' -exec
chmod a-w,a+r --🌈 Filters for data file content 🌈
Okay so this is the glow-up part. Filters can be installed between the data files in the ISO image and their content source outside the image. They can also be used the other way around — between data content in the image and target files on disk. 💅
Built-in filters are --zisofs and --zisofs-decode. The first one gets applied via -set_filter, and the second one is automatically applied if zisofs compressed content is detected with a file when loading the ISO image. No cap.
Another built-in filter pair is --gzip and --gunzip with suffix .gz. They behave about like external gzip and gunzip but they avoid forking a process for each single file. So they are much faster if there are many small files. periodt.
-external_filternameoption[:option]program_path[arguments] --— Register a content filter by associating a name with a program path, program arguments, and some behavioral options. Once registered it can be applied to multiple data files in the ISO image, regardless whether their content resides in the loaded ISO image or in the local filesystem. External filter processes may produce synthetic file content by reading the original content fromstdinand writing tostdoutwhatever they want. They must deliver the same output on the same input in repeated runs. 🙈 The options are:"default"means that no other option is intended."suffix=..."sets a file name suffix. If it is not empty then it will be appended to the file name or removed from it."remove_suffix"will remove a file name suffix rather than appending it."if_nonempty"will leave 0-sized files unfiltered."if_reduction"will try filtering and revoke it if the content size does not shrink."if_block_reduction"will revoke if the number of 2 kB blocks does not shrink."used=..."is ignored. Command-statusshows it with the number of files which currently have the filter applied.- Examples:
-external_filter bzip2 suffix=.bz2:if_block_reduction \
/usr/bin/bzip2 --
-external_filter bunzip2 suffix=.bz2:remove_suffix \
/usr/bin/bunzip2 ---unregister_filtername — Remove an-external_filterregistration. This is only possible if the filter is not applied to any file in the ISO image. 🫶-close_filter_list— Irrevocably ban commands-concat "pipe",-external_filter, and-unregister_filter, but not-set_filter. Use this to prevent external filtering in general, or when all intended filters are registered and-concatmode"pipe"shall be disallowed. External filters may also be banned totally at compile time of xorriso. By default they are banned if xorriso runs under setuid permission. 💀-set_filtername iso_rr_path[***]— Apply an-external_filteror a built-in filter to the given data files in the ISO image. If the filter suffix is not empty, then it will be applied to the file name. Renaming only happens if the filter really gets attached and is not revoked by its options. By default files which already bear the suffix will not get filtered. The others will get the suffix appended to their names. If the filter has option"remove_suffix", then the filter will only be applied if the suffix is present and can be removed. Name oversize or collision caused by suffix change will prevent filtering. 😭 With most filter types this command will immediately run the filter once for each file in order to determine the output size. Content reading operations like-extract,-compareand image generation will perform further filter runs and deliver filtered content. At image generation time the filter output must still be the same as the output from the first run. Filtering for image generation does not happen with files from the loaded ISO image if the write method of growing is in effect (i.e.-indevand-outdevare identical). The reserved filter name--remove-all-filtersrevokes filtering. This will revoke suffix renamings as well. Use--remove-all-filters+to prevent any suffix renaming. Attaching or detaching filters will not alter the state of-changes_pending. If the filter manipulations shall be the only changes in a write run, then explicitly execute-changes_pending "yes". ✨-set_filter_rname iso_rr_path[***]— Like-set_filterbut affecting all data files below eventual directories. 🦋
👑 Writing the result, drive control 👑
(see also paragraph about settings below)
-rollback— Discard the manipulated ISO image and reload it from-indev. (Use-rollback_endif immediate program end is desired.) 💅-changes_pending"no"|"yes"|"mkisofs_printed"|"show_status"— Write runs are performed only if a change of the image has been made since the image was loaded or created blank. Vice versa the program will start a write run for pending changes when it ends normally (i.e. not by abort and not by command-rollback_end). The command-changes_pendingcan be used to override the automatically determined state. This is mainly useful for setting state"yes"despite no real changes were made. The sequence-changes_pending "no" -endis equivalent to the command-rollback_end. State"mkisofs_printed"is caused by emulation command-as mkisofsif option-print-sizeis present. The pseudo-state"show_status"can be used to print the current state to result channel. Image loading or manipulations which happen after this command will again update automatically the change status of the image. 👑-commit— Perform the write operation. Afterwards, if-outdevis readable, make it the new-devand load the image from there. Switch to growing mode. (A subsequent-outdevwill activate modification mode or blind growing.)-commitis performed automatically at end of program if there are uncommitted manipulations pending. So, to perform a final write operation with no new-devand no new loading of image, rather execute command-end. If you want to go on without image loading, execute-commit_eject "none". To eject after write without image loading, use-commit_eject "all". To suppress a final write, execute-rollback_end. 🌸
Writing can last quite a while. It is not unnormal with several types of media that there is no progress visible for the first few minutes, or that the drive gnaws on the medium for a few minutes after all data have been transmitted. xorriso and the drives are in a client-server relationship. The drives have much freedom about what to do with the media. Some combinations of drives and media simply do not work, despite the promises by their vendors. If writing fails then try other media or another drive. The reason for such failure is hardly ever in the code of the various burn programs but you may well try some of those listed below under SEE ALSO. 💀
-eject"in"|"out"|"all"— Eject the medium in-indev,-outdev, or both drives, respectively. Note: It is not possible yet to effectively eject disk files. 🙈-commit_eject"in"|"out"|"all"|"none"— Combined-commitand-eject. When writing has finished do not make-outdevthe new-dev, and load no ISO image. Rather eject-indevand/or-outdev. Give up any non-ejected drive. 🫶-blankmode — Make media ready for writing from scratch (if not-dummyis activated). This affects only the-outdevnot the-indev. If both drives are the same and if the ISO image was altered then this command leads to a FAILURE event. Defined modes are:
as_needed, fast, all, deformat, deformat_quickest"as_needed" cares for used CD-RW, DVD-RW and for used overwritable media by applying -blank "fast". It applies -format "full" to yet unformatted DVD-RAM and BD-RE. Other media in blank state are gracefully ignored. Media which cannot be made ready for writing from scratch cause a FAILURE event. "fast" makes CD-RW and unformatted DVD-RW re-usable, or invalidates overwritable ISO images. "all" might work more thoroughly and need more time. "deformat" converts overwritable DVD-RW into unformatted ones. "deformat_quickest" is a faster way to deformat or blank DVD-RW but produces media which are only suitable for a single session. Some drives announce this state by not offering feature 21h, but some drives offer it anyway. If feature 21h is missing, then xorriso will refuse to write on DVD-RW if not command -close is set to "on". The progress reports issued by some drives while blanking are quite unrealistic. Do not conclude success or failure from the reported percentages. Blanking was successful if no SORRY event or worse occurred. ✨ Mode may be prepended by "force:" in order to override the evaluation of the medium state by libburn. E.g. "force:fast". Blanking will nevertheless only succeed if the drive is willing to do it. 💅
-formatmode — this is the glow-up command, bestie 💅 it turns unformatted DVD-RW into overwritable ones, "de-ices" DVD+RW, formats brand-new BD-RE or BD-R, and re-formats DVD-RAM or BD-RE. The modes you can pick are:as_needed,full,fast,by_index_<num>,fast_by_index_<num>,by_size_<num>,fast_by_size_<num>,without_spareas_needed— formats the ones that are still unformatted: DVD-RW, DVD-RAM, BD-RE, or a blank unformatted BD-R. Everything else? Left completely untouched, no notes 💖full— (re-)formats DVD-RW, DVD+RW, DVD-RAM, BD-RE, or a blank unformatted BD-R.fast— literally the same job asfull, but it tries to be quicker about it. main character energy, no time to waste ✨by_index_— picks a format out of the descriptor list that command-list_formatshands you. You stick the index number from that list onto the end of the mode word. For example:by_index_3.fast_by_index_— does the same thing asby_index_, just tries to be speedier 🦋by_size_— picks a format from the descriptor list that gives you at least the size you ask for. That size goes on the end of the mode word. Example:by_size_4100m. This one applies to media with Defect Management. And on BD-RE it will not choose format0x31, because that one offers no Defect Management.fast_by_size_— same asby_size_, but again, tries to be quicker.without_spare— grabs the biggest format from the descriptor list that provides no Spare Area for Defect Management. On BD-RE that's gonna be format0x31. BD-R will not be formatted by this mode at all. DVD-RAM and other media get formatted to the largest size offered.
The formatting action does absolutely nothing to your media if -dummy is activated, fyi.
Formatting is normally only needed once in a medium's whole lifetime — if ever, honestly. But here's when re-formatting is a legit reason:
- DVD-RW was deformatted by
-blank, - DVD+RW has read failures (re-format before the next write, bestie 😭),
- DVD-RAM or BD-RE shall change their amount of defect reserve.
BD-R can be written unformatted or formatted before its first use. Formatting activates Defect Management, which tries to catch and repair bad spots on the media during the write process — and the price for that is half speed, even on flawless media. it's giving insurance premium 🫶
The progress reports some drives spit out while formatting are wildly unrealistic. Do not conclude success or failure from the reported percentages, okay? Formatting was successful if no SORRY event or worse occurred. Be patient with apparently frozen progress. 🧘♀️
-list_formats— dumps a list of format descriptors as reported by the output drive for the current medium. The list gives you the index number afterFormat idx, a MMC format code, the announced size in blocks (like2236704s), and that same size in MiB. ✨
MMC format codes are manifold, like there are so many. The most important ones: 00h general formatting, 01h increases reserve space for DVD-RAM, 26h for DVD+RW, 30h for BD-RE with reserve space, 31h for BD-RE without reserve space, 32h for BD-R.
Smaller format size with DVD-RAM, BD-RE, or BD-R means more reserve space. iykyk 💜
-list_speeds— puts out a list of speed values as reported by the drives with the loaded media. The list tells you the read speeds of the input drive and of the output drive, and it also tells you the write speeds of the output drive.
Heads up: the list of write speeds does not necessarily mean the medium is writable, or that those speeds are actually achievable. Especially the lists reported with an empty drive or with ROM media — those obviously advertise speeds for other media. 🙈
You are not obligated to use speed values out of the listed range. The drive is supposed to choose a safe speed that's as near to the desired speed as possible.
At the end of the list, Write speed L and Write speed H are the best guesses for the lower and upper write speed limit. Write speed l and Write speed h may appear only with CD, and they might override the list of other speed offers.
Only if the drive reports contradicting speed information will Write speed 0 show up — that tells you the outcome of speed selection by command -speed 0, if it deviates from Write speed H.
Read speed L and Read speed H tell the minimum and maximum read speeds, as reported by the drive. They'd be chosen by -read_speed "min" or "max" if they undercut or surpass the built-in limits. And those built-in limits are 1x, 52xCD, 24xDVD, 20xBD. 🌈
-list_profiles "in"|"out"|"all"— puts out a list of media types supported by-indev,-outdev, or both, respectively. The type that's currently recognized gets marked with the text(current). 👑-truncate_overwritableentity id adjust — on overwritable medium, this copies the volume descriptors of an existing session to the overall descriptors at LBA0ff. The result? Every session younger than the activated one becomes inaccessible. A reason you'd wanna do this: read errors in the younger sessions, and you just want to re-write or skip them. 😤
This operation is only allowed if no changes to the loaded filesystem are pending. If an -indev is acquired, then it gets released before the write operation begins, and re-acquired only in case of success.
The parameters entity and id mean the same thing as with command -load. They choose the existing ISO session that shall become the youngest accessible session. Available entity names are session, track, lba, sbsector, volid. And auto makes few sense here, ngl. id is a number or search text as appropriate for the given entity.
Parameter adjust controls the claimed size of the activated session. Text new means the size of the newly activated session as it was before this command — i.e. the space of the then-inaccessible younger sessions will be re-used when you append more sessions.
old means the size up to the end of the previously youngest session. I.e. old will not free the space of the then-inaccessible younger sessions for re-use.
A number preceded by + gives the number of bytes to be added to new. A number without + gives the overall number of bytes. In any case, the result may not be smaller than new. Numbers may have a unit suffix: d=512, k=1024, s=2048, m=1024k, g=1024m.
Normally the volume descriptors at block 16 ff. have to be readable. Only with entity lba or sbsector and adjust mode new is it possible to address a session if block 16 ff. yields no valid volume descriptors.
Examples, bestie 💅 Activate session 4 and enable overwriting of the blocks of younger sessions:
-truncate_overwritable session 4 newActivate session 4 and claim the blocks of younger sessions as useless part of session 4:
-truncate_overwritable session 4 oldLet session 4 claim additional 500 MiB as useless data:
-truncate_overwritable session 4 +500m-close_damaged "as_needed"|"force"— tries to close the upcoming track and session if the drive reported the medium as damaged. This may apply to CD-R, CD-RW, DVD-R, DVD-RW, DVD+R, DVD+R DL, or BD-R media. You'll know it's happening from warning messages when the drive gets acquired, and from a remarkbut next track is damagedsitting next to the lineMedia status :of command-toc. 💀
The setting of command -close determines whether the medium stays appendable.
Mode as_needed gracefully refuses on media that aren't reported as damaged. Mode force attempts the close operation even with media that appear undamaged. 😭
No image changes are allowed to be pending before this command is performed. After closing was attempted, both drives are given up.
Settings for result writing: ✍️✨
Rock Ridge info will be generated by default. ACLs will be written according to the setting of command -acl.
-joliet "on"|"off"— if you enable it with"on", it generates a Joliet tree additional to the ISO 9660 + Rock Ridge tree. obsessed. 🌸-hfsplus"on" | "off" — okay so bestie, this one is giving Apple era 💖. Flip it to "on" and xorriso will build a whole HFS+ filesystem inside your ISO 9660 image, and then flag it with Apple Partition Map (APM) entries living in the System Area — that's the first 32 KiB of the image, jsyk 🎀.
Careful though, because this can collide with data you submitted via -boot_image system_area=. The first 8 bytes of the System Area get straight-up overwritten by { 0x45, 0x52, 0x08 0x00, 0xeb, 0x02, 0xff, 0xff }, which — iconic — can be executed as x86 machine code with no negative effects ✨. So if an MBR gets combined with this feature, its first 8 bytes should contain no essential commands, fr fr 💅.
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 follow, then a third partition entry gets produced. Other features of xorriso might cause the need for even more APM entries, so like, it can keep going 🙈.
Now for the tea ☕: the HFS+ filesystem is not suitable for add-on sessions produced by the multi-session method of growing. An existing ISO image may nevertheless be the base for a new image produced by the method of modifying, so that's your lane 🦋. If -hfsplus is enabled when -indev or -dev gets executed, then AAIP attributes get loaded from the input image and checked for info about HFS creator, filetype, or blessing. If found, they get enabled as settings for the next image production. Which is why it is advisable to perform -hfsplus "on" before -indev or -dev — order matters bestie, no cap 👑.
Info about HFS creator, type, and blessings gets stored by xorriso if -hfsplus is enabled at -commit time. It's stored as a copy outside the HFS+ partition, but rather along with the Rock Ridge information. And xorriso does not read any information from the HFS+ meta data. Periodt 💅.
Be aware that HFS+ is case-insensitive although it can record file names with upper-case and lower-case letters 😭. Therefore, file names from the iso_rr name tree may collide in the HFS+ name tree. In this case they get changed by adding underscore characters and counting numbers. And in case of very long names, it might be necessary to map them to "MANGLED_...". It's giving chaos but it's handled 🫶.
WARNING 🚨 The HFS+ implementation in libisofs has a limit of 125,829,120 bytes for the size of the overall directory tree. This 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. Not me crying over a byte limit 😭.
-rockridge"on" | "off" — mode "off" disables production of Rock Ridge information for the ISO 9660 file objects. And listen, the multi-session capabilities of xorriso depend much on the naming fidelity of Rock Ridge. So it is strongly discouraged to deviate from the default setting "on". Like, just leave it on bestie, trust the process ✨🌈.-compliance rule[:rule...]— ok bestie, this one is the ✨compliance dial✨. It tweaks how strictly xorriso follows the specs of ISO 9660/ECMA-119 and its contemporary extensions. Sometimes you want to stray a lil bit — to dodge bugs in whatever reader system is gonna eat your disc, or to unlock unofficial extra features. 👑
There are several adjustable rules, each with its own keyword. Mention one with this command and its rule gets added to the relaxation list. You can wipe that whole list with the rules "strict" or "clear". You can reset it back to its start setting with "default". And every relaxation rule can be revoked on its own by tacking "_off" on the end — but only if it doesn't take a parameter after a '=' character. Like "deep_paths_off". 💅
Rule keywords, incoming:
"iso_9660_level="number— picks your level. Level 1 = ECMA-119 names in the8.3form with-file_size_limit <= 4g - 1. Level 2 = ECMA-119 names up to length 32, same-file_size_limit. Level 3 = ECMA-119 names up to length 32 with-file_size_limit >= 400g -200k. If it needs to,-file_size_limitgets adjusted. And vice versa: the command-file_size_limitactivatesiso_9660_level=3if it sets the limit to4gor larger."allow_dir_id_ext"— lets ECMA-119 names of directories have a name extension like other file types do. It does not force dots and it omits the version number, though. This is a bad tradition ofmkisofswhich violates ECMA-119. 😬 Especially ISO level 1 only allows 8 characters in a directory name and not8.3."omit_version"— does not add versions (";1") to ECMA-119 and Joliet file names."only_iso_version"— does not add versions (";1") to Joliet file names."deep_paths"— allows ECMA-119 file paths deeper than 8 levels."long_paths"— allows ECMA-119 file paths longer than 255 characters."long_names"— allows up to 37 characters with ECMA-119 file names."no_force_dots"— does not add a dot to ECMA-119 file names which have none."no_j_force_dots"— does not add a dot to Joliet file names which have none."lowercase"— allows lowercase characters in ECMA-119 file names."7bit_ascii"— allows nearly all 7-bit characters in ECMA-119 file names. Not allowed are0x0and'/'. If"lowercase"is not enabled, then lowercase letters get converted to uppercase."full_ascii"— allows all 8-bit characters except0x0and'/'in ECMA-119 file names."untranslated_names"— ⚠️ might be dangerous for inadverted reader programs which rely on the restriction to at most 37 characters in ECMA-119 file names. This rule allows ECMA-119 file names up to 96 characters with no character conversion. If a file name has more characters, then image production will fail deliberately."untranslated_name_len="number— enablesuntranslated_nameswith a smaller limit for the length of file names.0disables this feature,-1chooses maximum length limit, numbers larger than 0 give the desired length limit."joliet_long_names"— allows Joliet leaf names up to 103 characters rather than 64."joliet_long_paths"— allows Joliet paths longer than 240 characters."joliet_utf16"— encodes Joliet names in UTF-16BE rather than UCS-2. The difference shows up with characters which are not present in UCS-2 and get encoded in UTF-16 by 2 words of 16 bit each. Both words then stem from a reserved subset of UCS-2. 🧚"relaxed_pvd_atts="mode— controls 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.
- The fields Volume Id and Volume Set Id are restricted by the specs to
"always_gmt"— stores timestamps in GMT representation with timezone 0."rrip_tf_long"— forces use of the long form of RockRidge timestamps. This form is not understood by Linux kernels older than6.16. 😭"rrip_tf_short"— this is the default. It enables use of the short form of RockRidge timestamps, which cannot express times after end of year 2155 but is understood by a wide range of operating systems. The short form is then used with all files or directories which have atime, ctime, and mtime before01 Jan 2150 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.)"rrip_tf_y1900"— restricts Rock Ridge timestamps to at leastJan 1 1900 UTC. This may be desirable because the Linux kernel up to at least version6.16misrepresents times before year 1900 asJan 1 1970 00:00:00 UTC."rrip_tf_year0"— this is the default. It enables writing of RockRidge timestamps before year 1900 AD down to year 0 (= 1 BC). Such timestamps will be written in long form."rec_mtime"— records with non-RockRidge directory entries the disk file's mtime and not the creation time of the image. This applies to the ECMA-119 tree (plain ISO 9660), to the Joliet tree, and to the tree of an Enhanced Volume Descriptor (aka ISO 9660:1999) as of ECMA-119 4th Edition."rec_mtime"is default. If disabled, it gets automatically re-enabled by-as mkisofsemulation when a pathspec is encountered."new_rr"— uses Rock Ridge version 1.12 (suitable for GNU/Linux but not for older FreeBSD or for Solaris). This implies"aaip_susp_1_10_off"which may be changed by subsequent"aaip_susp_1_10"."old_rr"— the default, which uses Rock Ridge version 1.10. This implies also"aaip_susp_1_10"which may be changed by subsequent"aaip_susp_1_10_off"."aaip_susp_1_10"— allows AAIP to be written as unofficial extension of RRIP rather than as official extension under SUSP-1.12."no_emul_toc"— saves 64 kB with the first session on overwritable media but makes the image incapable of displaying its session history."iso_9660_1999"— causes the production of an additional directory tree beginning at an Enhanced Volume Descriptor (aka ISO 9660:1999) as of ECMA-119 4th Edition. It can record long filenames for readers which do not understand Rock Ridge."old_empty"— uses 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."max_ce_entries="number— sets the maximum number of SUSP CE entries and thus continuation areas. Each continuation area can hold at most 2048 bytes of SUSP data (Rock Ridge or AAIP). The first area can be smaller. There might be some waste at the end of each area. When the maximum number is exceeded during ISO filesystem production then either xattr and ACL get dropped from the affected file or an error gets reported and image production is prevented.- Linux silently ignores a file when encountering its 32th CE entry. (Workaround is to mount the filesystem with option
"norock".) So the default setting is 31. Minimum is 1, maximum is 100000. If a limit higher than 31 is chosen and 31 gets surpassed, then a warning message gets reported.
- Linux silently ignores a file when encountering its 32th CE entry. (Workaround is to mount the filesystem with option
"max_ce_drop="mode— sets the behavior when the limit ofmax_ce_entries=is surpassed. Mode"off"causes an error message and prevents image production. Mode"xattr"and"xattr_acl"report a warning, delete from the affected file all xattr of namespaces other than"isofs", and then try again. If this still surpasses the limit, then mode"xattr_acl"deletes all ACL from the file and retries. If this still surpasses the limit, then an error message gets reported and image production is prevented.
The default setting is
"clear:iso_9660_level=3:only_iso_version:deep_paths:long_paths:no_j_force_dots:relaxed_pvd_atts=vol:always_gmt:rec_mtime:old_rr:max_ce_entries=31:max_ce_drop=xattr_acl"Note: The term "ECMA-119 name" means the plain ISO 9660 names and attributes which get visible if the reader ignores Rock Ridge. 💖
-rr_reloc_dir name— names the relocation directory where deep directory subtrees get parked if-complianceis set to"deep_paths_off"or"long_paths_off". A deep directory is one that has a chain of 8 parent directories (including root) above itself, or one that contains a file with an ECMA-119 path of more than 255 characters.
The overall directory tree will appear originally deep when interpreted as Rock Ridge tree. It will appear as re-arranged if only ECMA-119 information is considered. 🦋
The default relocation directory is the root directory. By giving a non-empty name with -rr_reloc_dir, a directory in the root directory may get this role. If that directory does not already exist at -commit time, then it will get created and marked for Rock Ridge as relocation artefact. At least on GNU/Linux it will not be displayed in mounted Rock Ridge images.
The name must not contain a '/' character and must not be longer than 255 bytes.
Okay so these next ones are all about identity — like who this disc says it is, what it's called, who made it. Very main character energy, very "this is my brand". 💅 Let's get into it.
-volid_for fs_types text— Sets the volume ID for one or more filesystem types. Here's the tea: a xorriso-made ISO 9660 image can offer four different filesystems for mounting — ISO 9660 aka ECMA-119 (normally with Rock Ridge), Joliet, ISO 9660:1999, and HFS+. Thefs_typesparameter picks which of those types get their volume ID set by this command. It's a comma-separated list of keywords out of"ecma119","joliet","iso_9660_1999","hfsplus". And the keyword"all"? That one chooses all four types, slay. Example bestie:
-volid_for joliet "Joliet Volume Id"
-volid_for ecma119,iso_9660_1999 "LONGER_ISO_VOLUME_ID"xorriso will accept any volume ID text up to 32 characters, but ngl, according to some rarely obeyed specs, stricter rules apply:
- ECMA-119 demands ASCII characters out of
[A-Z0-9_]. Like:"IMAGE_23" - xorriso warns if the text you submitted doesn't comply. And if
-complianceis set torelaxed_pvd_atts="off"or"nonvol", then the text gets 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 the name of the mount point when the medium is inserted into a playful computer system. 👀
Okay this part is important: if an ISO image gets loaded while the volume ID is set to default "ISOIMAGE" or to "", then the volume IDs of the loaded image will become the effective volume ids for the respective filesystem types for the next write run. But the second you run commands -volid_for or -volid afterwards, those pending IDs get overridden by the new settings. So consider this when setting volume ID "ISOIMAGE" before executing -dev, -indev, or -rollback. And if you insist on volume ID "ISOIMAGE", set it again after those commands. Periodt.
-volid text— Sets the volume ID for all filesystem types. I.e. it performs-volid_for "all"with the given parametertext. One and done. ✨-volset_id text— Sets the volume set ID string to be written with the next-commit. Permissible are up to 128 d-characters (see-compliancerule"relaxed_pvd_atts="). This setting gets overridden by image loading.-publisher text— Sets the publisher ID string to be written with the next-commit. This may identify the person or organisation who specified what shall be recorded. Permissible are up to 128 a-characters (see-compliancerule"relaxed_pvd_atts="). This setting gets overridden by image loading.-application_id text— Sets the application ID string to be written with the next-commit. This may identify the specification of how the data are recorded. Permissible are up to 128 a-characters (see-compliancerule"relaxed_pvd_atts="). This setting gets overridden by image loading. Also, the special text"@xorriso@"gets converted to the ID string of xorriso, which is normally written as-preparer_id. And lowkey it's a wrong tradition to write the program ID as-application_id, so don't do that bestie. 🙈-system_id text— Sets the system ID string to be written with the next-commit. 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-compliancerule"relaxed_pvd_atts="). This setting gets overridden by image loading.-volume_date type timestring— Sets one of the four overall timestamps for subsequent image writing. Available types are:"c"— time when the volume was created."m"— time when volume was last modified."x"— time when the information in the volume expires."f"— time since when the volume is effectively valid."all_file_dates"— sets mtime, atime, and ctime of all files and directories to the given time. 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"all_file_dates"with 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"uuid"."uuid"— sets a timestring that overrides"c"and"m"times literally and sets the time of the El Torito boot catalog. 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-ccE.g. 2010040711405800 is 7 Apr 2010 11:40:58 (+0 centiseconds).
Timestrings for the other types may be given as with command -alter_date. Some of them are prone to timezone computations. The timestrings "default" or "overridden" cause default settings: "c" and "m" will show the current time of image creation. "x" and "f" will be marked as insignificant. "uuid" will be deactivated. At -commit time, some timestamps get set to the maximum value of effectively written volume creation and modification time: El Torito boot catalog, HFS+ superblock, ECMA-119 file modification time if -compliance "no_rec_mtime". The isohybrid MBR id is computed from "uuid" if given, else from the effective volume modification date.
-copyright_file text— Sets the copyright file name to be written with the next-commit. 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-compliancerule"relaxed_pvd_atts="). This setting gets overridden by image loading.-abstract_file text— Sets the abstract file name to be written with the next-commit. 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-compliancerule"relaxed_pvd_atts="). This setting gets overridden by image loading.-biblio_file text— Sets the biblio file name to be written with the next-commit. 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-compliancerule"relaxed_pvd_atts="). This setting gets overridden by image loading.-preparer_id text— Sets the preparer ID string to be written with the next-commit. 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. So please avoid changing it, okay? 🥺 Permissible are up to 128 a-characters (see-compliancerule"relaxed_pvd_atts="). The special text"@xorriso@"gets converted to the ID string of xorriso, which is default at program startup. And unlike other ID strings, this setting is not influenced by image loading.-application_use character|0xXY|disk_path— Sets the content of the Application Use field, which can take at most 512 bytes. Here's how the parameter behaves:- If it's empty, then the field is filled with 512
0-bytes. - If it's a single character, then it gets repeated 512 times.
- If it begins by
0xfollowed 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_pathto 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 binary0.
- If it's empty, then the field is filled with 512
This setting is not influenced by image loading.
-out_charset character_set_name— Sets the character set to which file names get converted when writing an image. See paragraph"Character sets"for more explanations. When loading the written image after-commit, the setting of-out_charsetwill be copied to-in_charset.-uid uid— User id to be used for all files when the new ISO tree gets written to media.-gid gid— Group id to be used for all files when the new ISO tree gets written to media.-zisofs parameter[:parameters]— bestie, this sets the global params for zisofs compression. It's a data format that some Linux kernels recognize and transparently uncompressed on the fly, which is honestly iconic of them. You apply it via the command-set_filterwith the built-in filter--zisofs.
🫶 Heads up: this command is only permitted while no --zisofs filters are applied to any files. Like, none. Zero. Wait your turn.
Here are the parameters, all of them, no skips:
"level="[0-9]— zlib compression:0=none,1=fast,...,9=slow."block_size="32k|64k|128k— sets the size of version 1 compression blocks."by_magic=on"— enables an expensive test at image generation time which checks files from disk whether they already are zisofs compressed, e.g. by programmkzftree."by_magic=v2"enables processing of already zisofs2 compressed files additionally to those of zisofs version 1."by_magic=off"disables both."version_2="off|as_needed|on— controls compression by experimental version zisofs2 which can encode files of size 4 GiB or larger. The Linux kernel (as of 5.9) does not yet know this format and will complain like
isofs: Unknown ZF compression algorithm: PZThe files will then appear in their compressed form with zisofs2 header, block pointer list, and compressed data. zisofs2 is recognized by xorriso in files from loaded images and gets equipped with --zisofs-decode filters, unless restrictions on the number of block pointers prevent this. Mode "off" restricts compression to files smaller than 4 GiB uncompressed size. Mode "as_needed" uses zisofs2 for larger files. Mode "on" uses zisofs2 for all zisofs compressed files.
"susp_z2="off|on— controls production of SUSP entries"Z2"instead of"ZF"with zisofs2 compressed files. Unaware Linux kernels are supposed to silently ignore"Z2"entries. 💅"block_size_v2="32k|64k|128k|256k|512k|1m— sets the size of compression blocks for zisofs2."bpt_target="-1|>0— sets a number of block pointers per file, which is considered low enough to justify a reduction of block size. If this number is larger than 0, then block sizes smaller than the settings ofblock_size=orblock_size_v2=are tried whether they yield not more block pointers than the given number. If so, the smallest suitable block size is applied. The inavoidable final block pointer counts. E.g. a file of 55 KiB has 3 block pointers if block size is 32k, and 2 block pointers with block size 64k.bpt_target=-1disables this automatic block size adjustment."max_bpt="1k...128g— sets the limit for the overall allocated block pointer memory. Block pointers occupy virtual memory while a file gets uncompressed and while a file, which shall be compressed, waits for ISO filesystem creation. One pointer occupies 8 bytes of memory and governsblock_sizeorblock_size_v2uncompressed bytes. I.e. with block size 128k, 1m of block pointer memory suffices for at most 16g of uncompressed file size. Each file consumes one end block pointer, independently of the file size. Partially filled end blocks may further reduce the effective payload. In case of overflow of the max_bpt limit while adding compression filters the program tries to go on by discarding all buffered block pointers of previously added--zisofsfilters. From then on all newly added filters will discard their block pointers immediately after being added. Discarded block pointers cause an additional read and compression run of the input file during the production of the ISO filesystem. 😭"max_bpt_f="1k...128g— sets the limit for the memory size of the block pointer list of a single file.max_bpt_fis never larger thanmax_bpt. If either is set to violate this rule, the other gets set to the same value. If both values are the same before a change bymax_bpt=ormax_bpt_f=, then both limits stick together unless the limit is decreased bymax_bpt_f=."bpt_free_ratio="-1|0.0...1.0— sets a threshold for switching to block pointer discarding during compression. If less than the given fraction of themax_bpt_f=memory is free, then block pointers of compression filters get discarded immediately after being added. Value-1disables this feature."default"— is the same as"level=6:block_size=32k:by_magic=off:version_2=off:block_size_v2=128k:susp_z2=off:max_bpt=256m:max_bpt_f=256m:bpt_free_ratio=-1".
-speed code|number[k|m|c|d|b]— set the burn speed, bestie. Default is"max"(or"0") = maximum speed as announced by the drive. 🏎️
Further special speed codes:
"min"(or"-1") selects minimum speed as announced by the drive."none"avoids to send a speed setting command to the drive before burning begins.
Speed can be given in media dependent numbers or as a desired throughput per second in MMC compliant kB (= 1000) or MB (= 1000 kB). Media x-speed factor can be set explicitly by "c" for CD, "d" for DVD, "b" for BD, "x" is optional.
Example speeds:
706k = 706kB/s = 4c = 4xCD
5540k = 5540kB/s = 4d = 4xDVD
8992k = 8992kB/s ~= 2b = 2xBDIf there is no hint about the speed unit attached, then the medium in the -outdev will decide. Default unit is CD = 176.4k.
MMC drives usually activate their own idea of speed and take the speed value given by the burn program only as upper limit for their own decision. So like, it's giving suggestion, not decree. 🙈
-stream_recording "on"|"off"|"full"|"data"|number— setting"on"tries to circumvent the management of defects on DVD-RAM, BD-RE, or BD-R. Defect management keeps partly damaged media usable. But it reduces write speed to half nominal speed even if the medium is in perfect shape. For the case of flawless media, one may use-stream_recording "on"to get full speed. full speed!!"full"tries full speed with all write operations, whereas"on"does this only above byte address 32s. One may give a number of at least 16s in order to set an own address limit."data"causes full speed to start when superblock and directory entries are written and writing of file content blocks begins.
-dvd_obs "default"|"32k"|"64k"|"obs_pad"|"bdr_obs_exempt"— GNU/Linux specific, babe: set the number of bytes to be transmitted with each write operation to DVD or BD media. A number of 64 KB may improve throughput with bus systems which show latency problems. The default depends on media type, on command-stream_recording, and on compile time options.
On all systems: "obs_pad" pads the data of the last write operation of a DVD-R[W] DAO session or BD-R session up to the full size of an output chunk. This padding has to be applied automatically to the other DVD and BD media types, where it causes e.g. ISO images to have trailing unclaimed blocks. Whether it is applied automatically to BD-R depends on "bdr_obs_exempt". "obs_pad" can be disabled by "no_obs_pad".
"bdr_obs_exempt" exempts BD-R media from automatic unconditional transaction end padding, provided that this padding is not requested by "obs_pad" and that no stream_recording is requested. "bdr_obs_exempt" can be disabled by "no_obs_exempt".
This is a new feature introduced with version 1.5.6. It might become default in later versions. 👀
-modesty_on_drive parameter[:parameters]— control whether the drive buffer shall be kept from getting completely filled. Parameter"on"(or"1") keeps the program from trying to write to the burner drive while its buffer is in danger to be filled over a given limit. If this limit is exceeded then the program will wait until the filling reaches a given low percentage value.
This can ease the load on operating system and drive controller and thus help with achieving better input bandwidth if disk and burner are not on independent controllers (like hda and hdb). It may also help with throughput problems of simultaneous burns on different burners with Linux kernels like 3.16, if one has reason not to fix the problem by -scsi_dev_family "sg". On the other hand it increases the risk of buffer underflow and thus reduced write speed. 😬
Some burners are not suitable because they report buffer fill with granularity too coarse in size or time, or expect their buffer to be filled to the top before they go to full speed. Parameters "off" or "0" disable this feature.
The threshold for beginning to wait is given by parameter "max_percent=". Parameter "min_percent=" defines the threshold for resuming transmission. Percentages are permissible in the range of 25 to 100. Numbers in this range without a prepended name are interpreted as "on:min_percent=".
E.g.:
-modesty_on_drive 75The optimal values depend on the buffer behavior of the drive. Parameter "timeout_sec=" defines after which time of unsuccessful waiting the modesty shall be disabled because it does not work. Parameter "min_usec=" defines the initial sleeping period in microseconds. If the drive buffer appears to be too full for sending more data, the program will wait the given time and inquire the buffer fill state again. If repeated inquiry shows not enough free space, the sleep time will slowly be increased to what parameter "max_usec=" defines.
Parameters, which are not mentioned with a -modesty_on_drive command, stay unchanged. Default is:
-modesty_on_drive off:min_percent=90:max_percent=95:
timeout_sec=120:min_usec=5000:max_usec=25000-use_immed_bit "on"|"off"|"default"— ok so this one controls whether a bunch of long lasting SCSI commands get run with the Immed bit 💫, which makes the commands finish early while the drive is still actually doing the thing. After that, xorriso keeps asking for progress indication until the drive says it's ready again. If you turn this feature off, then blanking and formatting show no progress indication at all 😭. Whether-use_immed_bitis set to"off"by default may depend on your operating system. Command-statuswill tell you by appending"/on"or"/off"if a drive has already been acquired and-use_immed_bitis currently set to"default". And no worries — command-use_immed_bittolerates and ignores that appended text 🫶.-stdio_sync "on"|"off"|"end"|number— sets the number of bytes after which output to stdio gets forced: pseudo drives 🌀. This forcing is what keeps memory from getting clogged with tons of pending data for slow devices. The default"on"is the same as"16m". Forced output can be disabled with"off", or delayed until all data are produced with"end". If you pick a number, it has to be at least64k, periodt.-dummy "on"|"off"— if it's"on", then simulate burning, or refuse with aFAILUREevent if no simulation is possible, and do neither blank nor format 🙅♀️.-fs number["k"|"m"]— sets the size of the fifo buffer that smooths the data stream from ISO image generation to media burning ✨. Default is4 MiB, minimum64 kiB, maximum1 GiB. The number can be followed by the letter"k"or"m", which means the unit is kiB (= 1024) or MiB (= 1024 kiB).-close "on"|"off"|"as_needed"— if-closeis set to"on"then the written medium gets marked as not appendable anymore 🔒. This has no effect on overwritable media types. Setting"on"is the exact opposite of cdrecord option-multi, and it's one aspect of growisofs option-dvd-compat. If set to"off"then the medium stays writable for an appended session. If set to"as_needed"then it uses"on"only if"off"is predicted to fail with the given medium and its state. Heads up: not all drives correctly recognize fast-blanked DVD-RW, which need"on"👀. If there's well founded suspicion that a burn run failed because of-close "off", then-close "as_needed"causes a re-try with"on". Also note that emulation command-as "cdrecord"temporarily overrides the current setting of-closeby its own default-close "on"if its option-multiis missing.-write_type "auto"|"tao"|"sao/dao"— sets the write type for the next burn run 🔥."auto"will select SAO with blank CD media, DAO with blank DVD-R[W] if-closeis"on", and otherwise CD TAO or the equivalent write type of the particular DVD/BD media. Choosing TAO or SAO/DAO explicitly might cause the burn run to fail if the desired write type isn't possible with the given media state.-padding number["k"|"m"]|"included"|"appended"— appends the given number of extra bytes to the image stream. This is a traditional remedy for a traditional bug in block device read drivers 🩹. It's needed only for CD recordings in TAO mode. Since you can hardly predict what media an image might end up on, xorriso adds the traditional300kof padding by default to all images. For images that will never get to a CD, it's safe to use-padding 0. Normally padding isn't written as part of the ISO image but appended after the image end — that's-paddingmode"appended". Emulation command-as "mkisofs"and command-jigdocause padding to be written as part of the image. The same effect is achieved by-paddingmode"included".-perform_opc "on"|"off"|"as_growisofs"— controls whether to explicitly order the drive to perform Optimum Power Calibration (OPC) before writing begins ⚡. Lots of drives do their own power calibration even without such an order. Mode"off"leaves OPC to the discretion of the drive, and that's the default. Mode"on"orders the drive to do OPC on any medium. Mode"as_growisofs"orders the drive to do OPC only with DVD-R and unformatted DVD-RW, and only if the drive offers no OPC table entries — that's what growisofs does by default. Modes"on"and"as_growisofs"may or may not be beneficial. Use them only if you suspect burn failures have happened because of poor compatibility between drive and medium 🫠.
💿 Bootable ISO images 💿
Contrary to published specifications, many BIOSes will load an El Torito record from the first session on media and not from the last one, which is the one that gets mounted by default 😭. This makes no problems with overwritable media, because they appear to inadverted readers as one single session. But with multi-session media CD-R[W], DVD-R[W], DVD+R, it implies that the whole bootable system has to reside already in the first session, and that the last session still has to bear all files which the booted system expects after mounting the ISO image.
If a boot image from ISOLINUX or GRUB is known to be present on media, then it's advised to patch it when a follow-up session gets written 👑. But one should not rely on the capability to influence the bootability of the existing sessions, unless one can assume overwritable media.
Normally the boot images are data files inside the ISO filesystem. By special path "--interval:appended_partition_NNN:all::" it's possible to refer to an appended partition 🦋. The number NNN gives the partition number as used with the corresponding command -append_partition. E.g.:
-append_partition 2 0xef /tmp/efi.img
-boot_image any efi_path=--interval:appended_partition_2:all::There are booting mechanisms which don't use an El Torito record but rather start at the first bytes of the image 🌈: PC-BIOS MBR or EFI GPT for hard-disk-like devices, APM partition entries for Macs which expect HFS+ boot images, MIPS Volume Header for old SGI computers, DEC Boot Block for old MIPS DECstation, SUN Disk Label for SPARC machines, HP-PA boot sector for HP PA-RISC machines, DEC Alpha SRM boot sector for old DEC Alpha machines.
Several of the following commands expect disk paths as input but also accept description strings for the libisofs interval reader, which is able to cut out data from disk files or -indev and to zeroize parts of the content ✂️: command -append_partition, boot specs system_area=, grub2_mbr=, prep_boot_part=, efi_boot_part=.
The description string consists of the following components, separated by colon ':'
"--interval:"Flags":"Interval":"Zeroizers":"SourceThe component "--interval" states that this is not a plain disk path but rather an interval reader description string. The component Flags modifies the further interpretation:
"local_fs"demands to read from a file depicted by the path inSource."imported_iso"demands to read from the-indev. This works only if-outdevis not the same as-indev. TheSourcecomponent is ignored."appended_partition_NNN"with a decimal numberNNNworks only for-boot_imagebootspecs which announce El Torito boot image paths:bin_path=,efi_path=. The number gives the partition number as used with the corresponding command-append_partition.
The component Interval consists of two byte address numbers separated by a "-" character. E.g. "0-429" means to read bytes 0 to 429.
The component Zeroizers consists of zero or more comma separated strings. They define which part of the read data to zeroize. Byte number 0 means the byte read from the Interval start address. Each string may be one of:
"zero_mbrpt"demands to zeroize the MBR partition table if bytes 510 and 511 bear the MBR signature0x55 0xaa."zero_gpt"demands to check for a GPT header in bytes 512 to 1023, to zeroize it and its partition table blocks."zero_apm"demands to check for an APM block 0 and to zeroize its partition table blocks.Start_byte"-"End_bytedemands to zeroize the read-in bytes beginning with numberStart_byteand ending afterEnd_byte.
The component Source is the file path with flag "local_fs", and ignored with flag "imported_iso".
Byte numbers may be scaled by a suffix out of {k,m,g,t,s,d} meaning multiplication by {1024, 1024k, 1024m, 1024g, 2048, 512}. A scaled value end number depicts 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::"-boot_image "any"|"isolinux"|"grub" "discard"|"keep"|"patch"|"replay"|"show_status"| bootspec|"next"— defines the equipment of the emerging filesystem with boot entry points 👑.
With systems which boot via BIOS or EFI this is a set of El Torito boot images, possibly MBR boot code, and possibly partition tables of type MBR, GPT, or APM. Such file sets get produced by boot loader systems like ISOLINUX or GRUB.
Each -boot_image command has two parameters: type and setting. More than one -boot_image command may be used to define the handling of one or more boot images. Sequence matters, fr fr. Types isolinux and grub care for known peculiarities. Type any makes no assumptions about the origin of the boot images ✨.
okay so when an ISO filesystem gets loaded, the system area <emphasis>and</emphasis> the El Torito boot images get pulled in right along with it. default behavior, bestie: it does not write the loaded El Torito boot images, and it writes the loaded system area content without any alterations. That's just the vibe it ships with. 🫶
discard— this one gives up the El Torito boot catalog and its boot images, regardless of whether they came from a loaded ISO filesystem or were defined by your commands. Any BIOS- or EFI-related boot options get revoked, periodt. but the loaded system area data and the possibly defined appended partitions stay valid — they survive. If you actually want them gone, you have to erase them yourself with:
-boot_image any system_area=/dev/zero
-append_partition all revoke -keep— keeps or copies El Torito boot images unaltered and writes a new catalog. Iconic, no notes. ✨patch— applies patching to existing El Torito boot images if they seem to bear a boot info table.
so about that boot info table — it needs to be patched when the boot image gets newly introduced into the ISO image, or if an existing image gets relocated. This happens automatically if the type is "isolinux" or "grub", but not with "any". 🙈
If patching is enabled, then boot images from previous sessions get checked to see whether they seem to bear a boot info table. If they don't, they stay unpatched. heads up: this check is <emphasis>not infallible</emphasis>. So if you know your images need no patching, use "any" "keep". And "grub" "patch" will not patch EFI images (platform_id=0xef). 💅
replay is the glow-up version of "patch" — a more modern take. It doesn't just care for existing El Torito boot equipment, it also handles the recognizable boot provisions in the System Area. It discards any existing -boot_image setting including the system area, and executes the commands proposed by command -report_el_torito "cmd". 👑
special care alert 🚨 — be careful with manipulations of files in the emerging ISO filesystem that are mentioned by-report_el_torito "cmd". Their paths get memorized at ISO image load time. In general,-boot_image "any" "replay"should be applied after all file manipulations are done. All file paths from the-report_el_toritocommands must then still lead to data files which are suitable for their respective commands.
The effects of file path changes <emphasis>after</emphasis> -boot_image "any" "replay" can be surprising. E.g. removing or replacing a boot image with boot info table for legacy BIOS leads to a hidden boot image with the content as it was at "replay" time. Doing the same with a boot image for EFI leads to an error at -commit time, or to the new file content becoming the EFI boot image. 😭
out of historical reasons — and yeah, iykyk — replay does <emphasis>not</emphasis> revoke all possibly made -append_partition settings. It only overwrites those for which the loaded ISO image provides candidates. 🦋
show_status will print what is known about the loaded boot images and their designated fate. vibe check, printed to your terminal. 🌸
Examples 🎀
Drop El Torito:
-boot_image any discardDrop El Torito, system area, appended partitions:
-boot_image any discard
-boot_image any system_area=/dev/zero
-append_partition all revoke -Maintain recognizable stuff after revoking possibly made -append_partition settings, to surely get only the partitions from the loaded ISO:
-append_partition all revoke -
-boot_image any replayRe-adjust El Torito only for GRUB:
-boot_image grub patchRe-adjust El Torito only for ISOLINUX:
-boot_image isolinux patchA bootspec is just a lil word shaped like name=value 💖 it's how you describe the parameters of a boot feature. Simple as that.
The names "dir", "bin_path", "efi_path" all lead to El Torito bootable images. The name "system_area" activates a given file as MBR or other disk header. On all media types this is possible within the first session. In further sessions an existing boot image can get replaced by a new one, but — and this is the tea — depending on the media type this may have few effect at boot time. See above. 👀
El Torito boot images have to be added to the ISO image by normal means (image loading, -map, -add, ...). In case of ISOLINUX the files should reside either in ISO image directory /isolinux or in /boot/isolinux. In that case it suffices to use as bootspec the text "dir=/isolinux" or "dir=/boot/isolinux". E.g.:
-boot_image isolinux dir=/boot/isolinuxwhich bundles these individual settings:
-boot_image isolinux bin_path=/boot/isolinux/isolinux.bin
-boot_image isolinux cat_path=/boot/isolinux/boot.cat
-boot_image isolinux load_size=2048
-boot_image any boot_info_table=onAn El Torito boot catalog file gets inserted into the ISO image with address cat_path= with the first -boot_image "any" "next" or at -commit time. It is subject to normal -overwrite and -reassure processing if there is already a file with the same name. The catalog lists the boot images and is read by the boot facility to choose one of the boot images. But it is not necessary that it appears in the directory tree at all. One may hide it in all trees by cat_hidden=on. Other possible values are "iso_rr", "joliet", "hfsplus", and the default "off". The timestamps of the boot catalog file are refreshed at commit time. Command -volume_date "uuid" can be used to set their value. ✨
bin_path= depicts an El Torito boot image file, a binary program which is to be started by the hardware boot facility (e.g. the BIOS) at boot time. Default platform_id is 0x00 = legacy 80x86 BIOS.
efi_path= depicts an El Torito boot image file that is ready for EFI booting. This is normally a FAT filesystem image not larger than 65535 blocks of 512 bytes (= 32 MiB - 512). Its load_size is determined automatically, no boot info table gets written, no boot medium gets emulated, platform_id is 0xef.
emul_type= can be one of "no_emulation", "hard_disk", "diskette". It controls the boot medium emulation code of a boot image. The default "no_emulation" is suitable for ISOLINUX, GRUB, FreeBSD cdboot.
load_size= is a value which depends on the boot image. Default for legacy BIOS is 2048 which matches the expectations of most BIOS boot images. The special value "full" means the full size of the boot image file rounded up to a multiple of 2048 bytes. Maximum is 33,552,384 bytes. With EFI boot images the load size is always the full image size. 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. 😭
boot_info_table=on causes address patching to bytes 8 to 63 of the boot image which is given by "any" "bin_path=". "boot_info_table=off" disables this patching.
grub2_boot_info=on causes address patching to byte 2548 of the boot image which is given by "any" "bin_path=". 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. "grub2_boot_info=off" disables this patching.
platform_id= defines by a hexadecimal or decimal number the Platform ID of the boot image. "0x00" is 80x86 PC-BIOS, "0x01" is PowerPC, "0x02" is Mac, "0xef" is EFI (decimal "239").
id_string=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.
sel_crit=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.
next ends the definition of a boot image and starts a new one. Any following -bootimage bootspecs will affect the new image. The first "next" discards loaded boot images and their catalog.
system_area=disk_path copies at most 32768 bytes from the given disk file to the very start of the ISO image. This System Area is reserved for system dependent boot software, e.g. an MBR which can be used to boot from USB stick or hard disk. Other than an El Torito boot image, the file disk_path needs not to be added to the ISO image.
In multi-session situations the existing System Area is preserved by default. In in this case, the special disk_path "." prevents reading of a disk file but nevertheless causes adjustments in the loaded system area data. Such adjustments may get ordered by -boot_image commands. 👑
Special "system_area=/dev/zero" causes 32k of 0-bytes. Use this to e.g. discard partition tables which were loaded with the ISO image. 🧹
This setting is the default with the write method of Modifying, when -indev and -outdev are both used and not the same drive. If you indeed need to copy the unchanged system area from -indev to -outdev, use "system_area=--interval:imported_iso:0s-15s::" , which was the default in older versions of xorriso.
-boot_image isolinux system_area= implies "partition_table=on". In this case, the disk path should lead to one of the SYSLINUX files isohdp[fp]x*.bin or to a file which was derived from one of those files. E.g. to the first 512 bytes from an ISOLINUX isohybrid ISO image.
El Torito boot images (dir=, bin_path=, efi_path=) may then be augmented by isolinux partition_entry=gpt_basdat or isolinux partition_entry=gpt_hfsplus, and by isolinux partition_entry=apm_hfsplus. The boot image will then be mentioned in an invalid GPT as Basic Data or GPT HFS+ partition, and in a valid APM as HFS+ partition. The first three GPT partitions will also be marked by MBR partitions. The MBR partition of type 0xEF is what actually is used by EFI firmware for booting from USB stick.
-boot_image any gpt_disk_guid=value controls whether an emerging GPT shall get a randomly generated disk GUID or whether the GUID is supplied by the user. Value "random" is default. Value "volume_date_uuid" produces a low quality GUID from the value set by -volume_date "uuid".
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:
E.g. gpt_disk_guid=2303cd2a-73c7-424a-a298-25632da7f446 equals gpt_disk_guid=2acd0323c7734a42a29825632da7f446
The partition GUIDs get generated by minimally varying the disk GUID.
-boot_image any part_like_isohybrid=on enables -boot_image isolinux partition_entry= even if no -boot_image isolinux system_area= is given. 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.
-boot_image any iso_mbr_part_type=number sets the partition type of the MBR 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. 🦋
grub2_mbr=disk_path works like "any" system_area= with additional patching for modern GRUB MBRs. 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 64 bit little-endian number to byte address 0x1b0.
This feature can be revoked either by grub2_mbr= with empty disk path, or by submitting a disk_path via system_area=.
partition_table=on causes a simple partition table to be written into bytes 446 to 511 of the System Area.
With type "isolinux" it shows a partition that begins at byte 0 and it causes the LBA of the first boot image to be written into the MBR. For the first session this works only if also "system_area=" and "bin_path=" or "dir=" is given.
With types "any" and "grub" it shows a single partition which starts at byte 512 and ends where the ISO image ends. This works with or without system_area= or boot image.
Bootspecs chrp_boot_part=, prep_boot_part=, and efi_boot_part= overwrite this entry in the MBR partition table.
If types "isolinux" or "grub" are set to "patch", then "partition_table=on" is activated without new boot image. In this case the existing System Area gets checked whether it bears addresses and sizes as if it had been processed by "partition_table=on". If so, then those parameters get updated when the new System Area is written.
appended_part_as=gpt marks partitions from -append_partition in GPT rather than in MBR. In this case the MBR shows a single partition of type 0xee which covers the whole output data. The
ok bestie quick fact drop before we dive in: the number of appendable partitions with GPT is 8, rather than 4 with MBR. ✨
appended_part_as=mbr— this is the default, periodt. Appended partitions only get marked in GPT if GPT is produced because of other settings. If you give this one explicitly, it clears the settinggptandapm. That said,apmmay still be added tombr. 💅appended_part_as=apm— marks partitions from-append_partitionin APM in addition tombrorgpt. Heads up tho: the partition number in APM will not be influenced by the-append_partitionparameterpartition_number. By default, appended partitions get marked in APM only if APM is produced because of other options together withpart_like_isohybrid="on". 🎀
The next two settings only apply if partitions get appended by the command -append_partition and if GPT emerges at all — like, e.g., by appended_part_as=gpt. ✨
appended_gpt_with_gaps=on— increases the chance to get in GPT the partition numbers you gave with the command-append_partition. It may leave some parts of the resulting image unclaimed by partitions in the emerging GPT. The ISO 9660 filesystem gets marked by a GPT partition only if none of the appended partitions has partition number1, and if no other command causes a partition inside the emerging ISO 9660 filesystem, and ifpartition_offset=16. 🦋appended_gpt_with_gaps=off— causes the default behavior of inserting gap filling partitions 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. byappended_part_as=gpt. Commands which produce isohybrid-style invalid GPT disable gap filling. 💀chrp_boot_part=on— causes a single partition in MBR which covers the whole ISO image and has type0x96. This is not compatible with any other feature that produces MBR partition entries. It makes GPT unrecognizable. 😭prep_boot_part=disk_path— inserts the content of a data file into the image and marks it by an MBR partition of type0x41. The parts of the ISO image before and after this partition will be covered by further MBR partitions. The data file is supposed to contain ELF executable code. 🔥efi_boot_part=disk_path— inserts the content of a data file into the image and marks it by a GPT partition. If notchrp_boot_part=on, then the first partition in MBR will have type0xeeto announce the presence of GPT. The data file is supposed to contain a FAT filesystem. 🫶
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 bootspec efi_path=. The affected EFI boot image cannot show up in HFS+ because it is stored outside the HFS+ partition. 🙈
partition_offset=2kb_block_adr— causes 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 least16. 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. So the value defined here is only in effect if a new ISO image gets written.
partition_hd_cyl=number— gives the number of heads per cylinder for the partition table.0chooses a default value. Maximum is255. 🌀partition_sec_hd=number— gives the number of sectors per head for the partition table.0chooses a default value. Maximum is63. 🌸
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. 💀
partition_cyl_align=mode— controls image size alignment to an integer number of cylinders. It is prescribed by isohybrid specs and it seems to please programfdisk. Cylinder size must be divisible by2048. Images larger than8,323,596,288bytes cannot be aligned in MBR partition table. ✨
Mode "auto" is default. Alignment by padding happens only with "isolinux" "partition_table=on".
Mode "on" causes alignment by padding with "partition_table=on" for any type. Mode "all" is like "on" but also pads up partitions from -append_partition to an aligned size.
Mode "off" disables alignment for any type. 💅
mbr_force_bootable=mode— enforces an MBR partition with the"bootable/active"flag if options likepartition_table=orgrub2_mbr=indicate production of a bootable MBR. These options normally cause the flag to be set if there is an MBR partition of type other than0xeeor0xef. If no such partition exists, then no bootflag is set — unlessmbr_force_bootable="on"forces creation of a dummy partition of type0x00which covers only the first block of the ISO image. 🎀
If no bootable MBR is indicated and a partition gets created by -append_partition, then mbr_force_bootable="on" causes a bootflag like it would do with a bootable MBR.
gpt_iso_bootable=on— causes bit2of the GPT partition flags to be set 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. Mode"off"revokes this setting. 🦋gpt_iso_not_ro=on— causes bit60of the GPT partition flags to be not set 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. Mode"off"revokes this setting and causes the read-only bit to be set. 🌈mips_path=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 first512bytes of any data provided bysystem_area=. Up to15boot files can be declared bymips_path=. 🔥mipsel_path=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 first512bytes of any data provided bysystem_area=. Only a single boot file can be declared bymipsel_path=. 💜sparc_label=text— causes the production of a SUN Disk Label with the given text as ASCII label. Partitions2to8may be occupied by appended images. Partition1will always be the ISO image. See command-append_partition. The first512bytes of any data provided bysystem_area=will be overwritten. 🌸grub2_sparc_core=iso_rr_path— causes the content address and size of the given file to be written after the SUN Disk Label. Both numbers are counted in bytes. The address is written as 64 bit big-endian number to byte0x228. The size is written as 32 bit big-endian number to byte0x230. 🎀hppa_cmdline=text— sets the PALO command line for HP-PA. Up to1023characters are permitted by default. Withhppa_hdrversion=4the limit is127. 👑
Note that the first fivehppa_bootspecs are mandatory, if any of thehppa_bootspecs is used. Onlyhppa_hdrversion=is allowed to be missing. 🫶
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 version5(default) and version4. For the appropriate value see in PALO source code:PALOHDRVERSION. ✨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. 🔥mips_discard,mipsel_discard,sparc_discard,hppa_discard,alpha_discard— revoke any boot file declarations made for mips/mipsel, sparc, hppa, or alpha, respectively. This removes the ban on production of other boot blocks. 🦋hfsplus_serial=hexstring— sets a string of16digits"0"to"9"and letters"a"to"f", which will be used as unique serial number of an emerging HFS+ filesystem. 💜hfsplus_block_size=number— sets the allocation block size to be used when producing HFS+ filesystems. Permissible are512,2048, or0. The latter lets the program decide. 🎀apm_block_size=number— sets the block size to be used when describing partitions by an Apple Partition Map. Permissible are512,2048, or0. The latter lets the program decide. ✨
Note that size512is not compatible with production of GPT, and that size2048will not be mountable-t hfsplusat least by older Linux kernels. 😭
-append_partition partition_number type_code disk_path— okay so bestie, this one takes a filesystem image you already prepped and yeets it onto the end of the ISO image, and then it gets described by a partition table entry in a boot block at the start of the emerging ISO image. That entry is gonna bear the size of the submitted file, rounded up to the next multiple of 2048 bytes or to the next multiple of the cylinder size. 💅
Beware of subsequent multi-session runs. The appended partition will get overwritten. 💀 not a drill.
Partitions may be appended with partition table types MBR, GPT, and SUN Disk Label. And additionally to MBR and GPT, it is possible to have them marked in APM. ✨
With MBR:
partition_numbermay be1to4. Number1will put the whole ISO image into the unclaimed space before partition 1. So together with most xorriso MBR features, number2would be the most natural choice. 👑- The
type_codemay be"FAT12","FAT16","Linux", or a hexadecimal number between0x00and0xff. Not all those numbers will yield usable results. For a list of MBR partition type codes search the Internet for"Partition Types"or run fdisk command"L". type_codemay also be a type GUID as plain hex string likea2a0d0ebe5b9334487c068b6b72699c7or as structured text likeEBD0A0A2-B9E5-4433-87C0-68B6B72699C7. It will be used if the partition is mentioned in GPT. In MBR,C12A7328-F81F-11D2-BA4B-00A0C93EC93Bwill be mapped to0xef. Any other GUID will be mapped to0x83. In APM,48465300-0000-11AA-AA11-00306543ECACwill 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. 🫶
GPT can be forced by
-boot_image "any" "appended_part_as=gpt"partition_numbermay be1to8. But other than with MBR partitions, it is not guaranteed that the resulting GPT partition will have this number. 🙈- More important than the desired partition number will be that the resulting ISO filesystem is covered gaplessly with GPT table and its partitions, and that the partitions in the table are sorted by block address. If
partition_numberis higher than the number of preceding partitions, then the appropriate number of empty partition entries is inserted to achieve the desiredpartition_number. If the number of preceding partitions is too high, then a NOTE message informs about the inability to achievepartition_numberand about the actually assigned number. - The chance to get the desired partition number is increased much by command
-boot_image "any" "appended_gpt_with_gaps=on". - The
type_codemay be the same as described with MBR. Given GUIDs are used unchanged. Given MBR partition types get translated.0xefbecomesC12A7328-F81F-11D2-BA4B-00A0C93EC93B, others becomeEBD0A0A2-B9E5-4433-87C0-68B6B72699C7.
SUN Disk Label is chosen by -boot_image any sparc_label=. partition_number may be 2 to 8. Number 1 will always be the ISO image. Partition start addresses are aligned to 320 KiB. The type_code does not matter. Submit 0x0. 🧚
disk_path "." causes the partition to become a copy of the next lower valid one. lowkey iconic.
With MBR, GPT, and SUN alike:
- The
disk_pathmust provide the necessary data bytes at commit time. ⏰ - Issueing
-append_partitionwith a partition number that was already used in a previous-append_partitioncommand does not cause an error but silently overrides the previous setting. - The pseudo
type_code"revoke"or an emptydisk_pathprevent the partition from being appended. The pseudo partition number"all"may be used in this case to revoke all previous-append_partitionsettings.
🧃 Jigdo Template Extraction 🧃
From man genisoimage: "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."
xorriso can produce a .jigdo and a .template file together with a single-session ISO image. The .jigdo file contains checksums and symbolic file addresses. The .template file contains the compressed ISO image with reference tags instead of the content bytes of the listed files. it's giving compression queen 🎀
Input for this process are the normal arguments for a xorriso session on a blank -outdev, and a checksum file which lists those data files which may be listed in the .jigdo file and externally referenced in the .template file. Each designated file is 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 addressThe kind of checksum is chosen by -jigdo "checksum_algorithm" with values "md5" (32 hex digits) or "sha256" (64 hex digits). It will also be used for the file address lines in the .jigdo file. The default is "md5".
The file address in a checksum file line has to bear the same basename as the disk_path of the file which it shall 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 really reachable data source addresses from which they can read. ✨
If the list of jigdo parameters is not empty, then xorriso will refuse to write to non-blank targets, it will disable multi-session emulation, and padding will be counted as part of the ISO image. no cap.
-jigdo parameter_name value— Clear the Jigdo Template Extraction parameter list, or add a parameter to that list. The alias names are the corresponding genisoimage options. They are accepted as parameter names as well. Especially they are recognized by the-as mkisofsemulation command. 🦋- Parameter
clearwith any value empties the whole list. No.jigdoand.templatefile will be produced. checksum_algorithmchooses the checksum algorithm which shall be used for the data file entries in the.jigdofile and is expected in the checksum file. Permissible are"md5"or"sha256". Default is"md5".- Alias:
-jigdo-checksum-algorithm
- Alias:
template_pathsets thedisk_pathfor the.templatefile with the holed and compressed ISO image copy.- Alias:
-jigdo-template
- Alias:
jigdo_pathsets thedisk_pathfor the.jigdofile with the checksums and download addresses for filling the holes in.template.- Alias:
-jigdo-jigdo
- Alias:
checksum_pathsets thedisk_pathwhere to find the checksum file with symbolic file addresses and checksums according tochecksum_algorithm.- Alias:
md5_path - Alias:
-checksum-list - Alias:
-md5-list
- Alias:
min_sizesets the minimum size for a data file to be listed in the.jigdofile and being a hole in the.templatefile.- Alias:
-jigdo-min-file-size
- Alias:
excludeadds a regular expression pattern which will get compared with the absolutedisk_pathof any data file. A match causes the file to stay in.templatein any case.- Alias:
-jigdo-exclude
- Alias:
demand_checksumadds a regular expression pattern which will get compared with the absolutedisk_pathof any data file that was not found in the checksum list file as of"checksum_path". A match causes a MISHAP event. 😭- Alias:
demand_md5 - Alias:
-jigdo-force-checksum - Alias:
-jigdo-force-md5
- Alias:
mappingadds a string pair of the formTo=Fromto the parameter list. If a data file gets listed in the.jigdofile, then it is referred by the file address from its line in the checksum file. This file address gets checked whether it begins with theFromstring. If so, then this string will be replaced by theTostring and a':'character, before it goes into the.jigdofile. TheFromstring should end by a'/'character.- Alias:
-jigdo-map
- Alias:
compressionchooses one of"bzip2"or"gzip"for the compression of the template file. The jigdo file is put out uncompressed.- Alias:
-jigdo-template-compress
- Alias:
checksum_isochooses one or more of"md5","sha1","sha256","sha512"for the auxiliary"# Image Hex"checksums in the jigdo file. The value may e.g. look like"md5,sha1,sha512". Value"all"chooses all available algorithms. Note that MD5 stays always enabled. 💅- Alias:
-checksum_algorithm_iso
- Alias:
checksum_templateis likechecksum_isobut for"# Template Hex".- Alias:
-checksum_algorithm_template
- Alias:
- Parameter
🔤 Character sets: 🔤
File names are strings of non-zero bytes, 8 bits each. And here's the messy part bestie: that exact same byte string can show up as totally different quirky national characters on terminals that are nationalized differently. The meaning of byte codes lives in character sets, and character sets have names. Run shell command iconv -l and it'll list them for you. 💅
The file names on your hard disk are assumed to be encoded by the local character set, which is also what gets used for talking to the user. Byte codes 32 to 126 of the local character set must match the US-ASCII characters of the same code. ISO-8859 and UTF-8 both fulfill this demand, so they're chill like that. ✨
By default, xorriso uses whatever character set shell command "locale" tells it with argument "charmap". This may be influenced by environment variables LC_ALL, LC_CTYPE, or LANG, and it should match what your terminal expects. In some situations you may need to set it yourself by command -local_charset. 🎀
Local character sets should not matter as long as you only use english alphanumeric characters for file names, or as long as every writer and reader of the media uses the same local character set. Outside those constraints, you may need to let xorriso convert byte codes from and to other character sets. It's giving translator energy. 🌈
The Rock Ridge file names in ISO filesystems are assumed to be encoded by the input character set. The Rock Ridge file names that get written with ISO filesystems will be encoded by the output character set. The sets can be defined independently by commands -in_charset and -out_charset. Normally you'll have both identical, if you ever set them at all. Other than the local character set, these two character sets may deviate from US-ASCII. Lowkey flexible. 🦋
The output character sets for Joliet and HFS+ are not influenced by these commands. Joliet uses output character set UCS-2 or UTF-16. HFS+ uses UTF-16. Periodt.
The default output charset is the local character set of the terminal where xorriso runs. So by default no conversion happens between local filesystem names and emerging Rock Ridge names in the image. The situation stays ambiguous and the reader has to riddle out what character set was used. Not me leaving a mystery for the next person 😭.
By command -auto_charset it is possible to attribute the output charset name to the image. This makes the situation unambiguous. But if your terminal character set does not match the character set of the local file names, then this attribute can become plainly wrong and cause problems at read time. To prevent this you must check whether the terminal properly displays all intended filenames. Check especially the exotic national characters, bestie. 👀
To enforce recording of a particular character set name without any conversion at image generation time, set -charset and -local_charset to the desired name, and enable -backslash_codes to avoid evil character display on your terminal. 🫶
-charsetcharacter_set_name — Set the character set from which to convert file names when loading an image, and to which to convert when writing an image.-local_charsetcharacter_set_name — Override the system assumption of the local character set name. If this appears necessary, one should consider setting-backslash_codesto"on"in order to avoid dangerous binary codes being sent to the terminal.
🌸 Exception processing 🌸
Since the tasks of xorriso are manifold and prone to external influence, there may arise the need for xorriso to report and handle problem events. It's not being dramatic, it's just being prepared. 💅
Those events get classified when they are detected by one of the software modules and forwarded to reporting and evaluation modules which decide about reactions. Event classes are sorted by severity, from the top of the spectrum down:
"NEVER"— The upper end of the severity spectrum."ABORT"— The program is being aborted and on its way to end."FATAL"— The main purpose of the run failed or an important resource failed unexpectedly."FAILURE"— An important part of the job could not be performed."MISHAP"— AFAILUREwhich can be tolerated during ISO image generation."SORRY"— A less important part of the job could not be performed."WARNING"— A situation is suspicious of being not intended by the user."HINT"— A proposal to the user how to achieve better results."NOTE"— A harmless information about noteworthy circumstances."UPDATE"— A pacifier message during long running operations."DEBUG"— A message which would only interest the program developers."ERRFILE"— A filename for the-errfile_logif it is enabled."ALL"— The lower end of the severity spectrum.-abort_onseverity — Set the severity threshold for events to abort the program. Useful:"NEVER","ABORT","FATAL","FAILURE","MISHAP","SORRY". It may become necessary to abort the program anyway, despite the setting by this command. Expect not many"ABORT"events to be ignorable.
A special property of this command is that it works preemptive if given as program start argument. I.e. the first -abort_on setting among the start arguments is in effect already when the first operations of xorriso begin. Only "-abort_on" with dash - is recognized that way. 👑
-return_withseverity exit_value — Set the threshold and exit_value to be returned at program end if no abort has happened. This is to allow xorriso to go on after problems but to get a failure indicating exit value from the program, nevertheless. Useful is a value lower than the-abort_onthreshold, down to"WARNING".
exit_value may be either 0 (indicating success to the starter of the program) or a number between 32 and 63. Some other exit_values are used by xorriso if it decides to abort the program run:
1=abort due to external signal
2=no program arguments given
3=creation of xorriso main object failed
4=failure to start libburnia-project.org libraries
5=program abort during argument processing
6=program abort during dialog processing-report_aboutseverity — Set the threshold for events to be reported. Useful:"SORRY","WARNING","HINT","NOTE","UPDATE","DEBUG","ALL".
Regardless of what is set by -report_about, messages get always reported if they reach the severity threshold of -abort_on. Event messages are sent to the info channel "I" which is usually stderr but may be influenced by command -pkt_output. Info messages which belong to no event get attributed severity "NOTE".
A special property of this command is that the first -report_about setting among the start arguments is in effect already when the first operations of xorriso begin. Only "-report_about" with dash - is recognized that way. ✨
-signal_handlingmode — Control the installation of a signal handler which shall react on external signals (e.g. from program"kill"or from keys Ctrl+C) or on signals caused by severe program errors.
Mode "on" is the default. It uses the signal handler of libburn which produces ugly messages but puts much effort in releasing optical drives before xorriso ends.
Mode "off" as first -signal_handling among the start arguments prevents all own signal precautions of xorriso. Inherited signal handler settings stay as they are. It works like "sig_dfl" if given after other signal handling was already established at program start.
Mode "sig_dfl" uses the system provided default handling of signals, which is normally a sudden abort of the program. To prevent stuck drives, the libburn handler is used during burning, blanking, and formatting on MMC drives.
Mode "sig_ign" tries to ignore as many signal types as possible. This imposes the risk that xorriso refuses to end until externally kill -9 if performed. kill -9 then imposes the risk that the drive is left in unusable state and needs poweroff to be reset. So during burning, blanking, and formatting wait for at least their normal run time before killing externally. 💀
A special property of this command is that the first -signal_handling setting among the start arguments is in effect already when the first operations of xorriso begin. Only "-signal_handling" with dash - is recognized that way.
-error_behavioroccasion behavior — Control the program behavior at problem event occasions. For now this applies to occasions"image_loading"which is given while an image tree is read from the input device, and to"file_extraction"which is given with osirrox commands like-extract.
With "image_loading" there are three behaviors available:
"best_effort"goes on with reading after events with severity belowFAILUREif the threshold of command-abort_onallows this."failure"aborts image tree reading on first event of at leastSORRY. It issues an ownFAILUREevent. This is the default."fatal"acts like"failure"but issues the own event asFATAL.
With occasion "file_extraction" there are three behaviors:
"keep"maintains incompletely extracted files on disk. This is the default."delete"removes files which encountered errors during content extraction."best_effort"starts a revovery attempt by means of-extract_cutif the file content stems from the loaded ISO image and is not filtered.
🎀 Dialog mode control 🎀
-dialog"on"|"off"|"single_line"— Enable or disable to enter dialog mode after all program arguments are processed. In dialog mode input lines get prompted via readline or from stdin.
If no -abort_on severity was set when dialog starts, then "NEVER" is set to avoid abort in most cases of wrong input or other problems. Before dialog begins, the default is "FAILURE" which e.g. aborts on unknown commands.
Mode "on" supports input of newline characters within quotation marks and line continuation by trailing backslash outside quotation marks. Mode "single_line" does not.
-pagelength width — Describe terminal to the text pager. See also above, paragraph Result pager.
If parameter length is nonzero then the user gets prompted after that number of terminal lines. Zero length disables paging.
Parameter width is the number of characters per terminal line. It is used to compute the number of terminal lines which get occupied by an output line. A usual terminal width is 80.
-use_readline"on"|"off"— If"on"then use readline for dialog. Else use plain stdin. See also above, paragraph Dialog, Readline, Result pager. 🫶-reassure "on"|"tree"|"off"— okay bestie, this one is your safety blanket 🧸. If it's"on"then xorriso asks you for a "y" or "n" before it does literally any of these irreversible things:- before deleting or overwriting any file in the ISO image,
- before overwriting any disk file during restore operations,
- before rolling back pending image changes,
- before committing image changes to media,
- before changing the input drive,
- before blanking or formatting media,
- before ending the program.
With setting "tree" the reassuring prompt will appear for an eventual directory only once and not for each file in its whole subtree (so you're not getting spammed with a million prompts, we love that for you 💅).
Setting "off" silently kills any kind of image file object and performs above irrevocable actions. No take-backs, no warning, just vibes and consequences 💀
To really produce user prompts, command -dialog needs to be set to "on". Note that the prompt does not appear in situations where file removal is forbidden by command -overwrite. -reassure only imposes an additional curb for removing existing file objects.
Be aware that file objects get deleted from the ISO image immediately after confirmation. They are gone even if the running command gets aborted and its desired effect gets revoked. In case of severe mess-up, consider to use -rollback to revoke the whole session. 😭
🚗💨 Drive and media related inquiry actions:
-devices— shows you the list of available MMC drives with the addresses of their libburn standard device files. This is only possible when no ISO image changes are pending (so no half-finished glow-ups hanging around, got it?). After this command was executed, there is no drive current and no image loaded. In order to be visible, a device has to offer rw-permissions with its libburn standard device file. Thus it might be only the superuser who is able to see all drives. Drives which are occupied by other processes get not shown. They're busy, they can't come to the phone rn 🙈-device_links— like-devices, but presenting the drives with addresses of symbolic links which point to the actual device files. Modern GNU/Linux systems may shuffle drive addresses from boot to boot. Theudevdaemon is supposed to create links which always point to the same drive, regardless of its system address. The command-device_linksshows the addresses of such links if they begin by"/dev/dvd"or"/dev/cd". Precedence is:"dvdrw","cdrw","dvd","cdrom","cd". Consistent naming? We stan ✨-toc— show media specific tables of content. This is the session history of the medium, not the ISO image directory tree (important distinction bestie, don't get it twisted). In case of overwritable media holding a valid ISO image, it may happen that only a single session gets shown. But if the first session on the overwritable media was written byxorrisothen a complete session history can be emulated. A drive which is incapable of writing may show any media as CD-ROM or DVD-ROM with only one or two sessions on it. The last of these sessions is supposed to be the most recent real session then. Some read-only drives and media show no usable session history at all. Command-rom_toc_scanmight help. If input device and output device are both acquired and not the same, then both tables-of-content get shown.-toc_of "in"|"out"|"all"[":short"]— like command-tocbut explicitly choosing which drive's table-of-content to show."in"shows-indevor-dev,"out"shows-outdevor-dev,"all"shows the same as-toc. If":short"is appended to the drive choosing word, then only a short summary of drive state and medium content is printed. As further difference to-toc, this command does not emit FAILURE events if the desired drive is not acquired. No dramatic meltdown, just chill 🫶-toc_info_type typetext— choose which information to show in the rightmost column of-tocand-toc_of. Type"volid"is the default. It shows the Volume Ids of the listed ISO sessions. Type"creation_time"or"ctime"chooses the Creation Times. Type"modification_time"or"mtime"chooses the Modification Times. Appending"_gmt"to a time type text causes the time information to be shown in ECMA-119 formatYYYYMMDDhhmmssccin timezone GMT. Else it is shown as timestampsYYYY.MM.DD.hhmmssin the local timezone of the system.-assess_indev_features "plain"|"cmd"|"as_mkisofs"|"replay"— inspect the filesystem on-indevfor the presence of Rock Ridge, Joliet, or Enhanced Volume Descriptor (aka ISO 9660:1999) as of ECMA-119 4th Edition, and for traces of other write options which seem to have been used when the filesystem was created. Note that this command does not detect and report a possibly present HFS+ tree. HFS+ said "not today" 🧚
Mode "cmd" lists xorriso commands which would activate the detected settings.
Mode "as_mkisofs" lists options of the -as mkisofs emulation, which would activate those of the detected settings which are not default.
Mode "replay" performs the commands which get listed by mode "cmd".
Mode "plain" lists after a "Indev feature: " header name-value pairs as delivered by libisofs function iso_read_image_feature_named(). See libisofs.h. The other modes derive their output from this list. I.e. the sequence of commands from "cmd" follows the sequence of "plain".
Not leading to "cmd" lines are:
"size="tells the number of 2048 byte blocks of the filesystem."eltorito=1"tells that El Torito boot equipment was detected."tree_loaded="tells which tree was loaded by-indev:0 = ISO 9660 , 1 = Joliet ,2 = Enhanced Volume Descriptor (aka ISO 9660:1999) as of ECMA-119 4th Edition"tree_loaded_text="tells the same by name:"ISO9660","Joliet","ISO9660:1999""rr_loaded=1"tells that Rock Ridge information was loaded with the tree."aaip=1"tells that AAIP information was detected (ACL, xattr, MD5, ...)."rrip_1_10_px_ino=1"tells that with Rock Ridge 1.10 a PX entry was found which looks like from Rock Ridge 1.12.
-mount_cmd drive entity id path— emit an appropriate command line for mounting the ISO session indicated by drive, entity and id. The result will be different on GNU/Linux and on FreeBSD or NetBSD. drive can be"indev"or"outdev"to indicate already acquired drives, or it can be the path of a not yet acquired drive. Prefix"stdio:"for non-MMC drives is not mandatory. See command-loadfor the meaning of entity and id. Entities are:"auto","session","track","lba","sbsector","volid","at_time","before","not_after","after", and"not_before". Each is to be used with its appropriate kind of id string:"auto", session number, track number, block number, search expression for volume id, or time string. path will be used as mount point and must already exist as a directory on disk. The command gets printed to the result channel. See command-mountfor direct execution of this command. It's literally just printing the command for you, doing the homework but letting you hit submit 💅-mount_opts option[:option...]— set options which influence-mountand-mount_cmd. Currently there is only option"exclusive"which is default and its counterpart"shared". The latter causes xorriso not to give up the affected drive with command-mount. On GNU/Linux it adds mount option"loop"which may enable mounting of several sessions of the same block device at the same time. One should not write to a mounted optical medium, of course. Take care to umount all sessions before ejecting. 🚨-session_string drive entity id format— print to the result channel a text which gets composed according to format and the parameters of the addressed session. Formats"linux:"path or"freebsd:"path produce the output of-mount_cmdfor the given operating systems. In other texts xorriso will substitute the following parameter names. An optional prefix"string:"will be removed."%device%"will be substituted by the mountable device path of the drive address."%sbsector%"will be substituted by the session start sector."%track%","%session%","%volid%"will be substituted by track number, session number, or volume id of the depicted session.
-print_size— print the foreseeable consumption of 2048 byte blocks by next-commit. This can last a while as a-commitgets prepared and only in last moment is revoked by this command. So it does the whole thing and then goes "sike" 😭 The result depends on several settings and also on the kind of output device. If no-jigdooptions are set and not command-as "mkisofs"was used, then-padding(300 kB by default) is not counted as part of the image size. If an El Torito boot image file is already depicted, then command-print_sizeautomatically executes-boot_image "any" "next". This means that the properties of that boot image cannot be edited by subsequent commands.-tell_media_space— print available space on the output medium and the free space after subtracting already foreseeable consumption by next-commit. Note that the title of the prediction"After commit :"is misleading. It is rather the space that may still be filled in this session without making the next-commitfail from medium overflow. The free space after the next-commitmight be smaller by several MB. This depends on medium type, number of recorded sessions, and drive habits. Drive habits, like it's got a whole personality fr fr 🦋-pvd_info— print various ID strings and timestamps which can be found in loaded ISO images. Some of the IDs may be changed by commands like-volidor-publisher. For these IDs-pvd_inforeports what would be written with the next-commit. The timestamps get shown in ECMA-119 formatYYYYMMDDhhmmssccand timezone GMT. They do not get automatically propagated from loaded image to newly written image. The ones for new images may be set by command-volume_date. See there for the meaning of the particular timestamps. Go read that one, bestie, it's got the lore ✨-report_el_toritomode — okay so this one is the gossip columnist for your El Torito boot catalog 👀 it reads the boot catalog of the loaded ISO image and reports back.- With mode
plain— print a report about the information found in the El Torito boot catalog of the loaded ISO image. - With mode
help— print a text which explains the meaning of the lines put out by"plain". - mode
cmd— tries to print thexorrisocommands which are necessary to produce the found boot equipment: disk identifiers, El Torito boot images, and System Area. Disk identifiers are strings which the booting operating system might use to find the ISO filesystem from where it comes. Currently known is the use of volume id and modification date.
- With mode
The intended use case is modification of the filesystem by having -indev and -outdev pointing to different images or drives. The result might be insufficient, if the found equipment cannot be produced by xorriso. Various SORRY events may arise in this case, but it is not guaranteed that xorriso recognizes all its insufficiencies. 😭
mode as_mkisofs — tries to print the xorriso -as mkisofs options, which are necessary to produce the found equipment. The intended use case is to use the mounted filesystem as input tree together with the printed options.
If CHRP equipment is detected, then modes cmd and as_mkisofs issue some of the relaxation commands or options which get detected by command -assess_indev_features. This happens because CHRP firmware reads file paths from file /ppc/bootinfo.txt and tries to find them case-insensitively in the ECMA-119 tree without using Rock Ridge. If such a path has actually forbidden properties, like the name "powerpc-ieee1275", then the relaxations are needed to bring it unmangled into the ECMA-119 tree.
It is important to keep in mind that the file paths shown in the report lines and commands were registered directly after image loading. Possible filesystem manipulations which later remove these paths or replace their file content will not influence the report lines or commands. ✨
-report_system_areamode — the System Area's personal biographer 🫶- With mode
plain— print a report about the information found in the System Area of the loaded ISO image. The report consists of zero to many lines with a header text, a colon, and information text. - With mode
help— print a text which explains the meaning of the lines put out by"plain". You probably will have to look for more documentation which explains the technical details of the mentioned boot facilities. (iykyk 📚) - Modes
cmdandas_mkisofswork like with command-report_el_torito. See above.
- With mode
It is important to keep in mind that the file paths shown in the report lines and commands were registered directly after image loading. Possible filesystem manipulations which later remove these paths or replace their file content will not influence the report lines or commands. 💅
- With mode
gpt_disk_guid— print the GPT disk GUID of the loaded ISO in RFC 4122 text format to result channel. It is not considered an error if no GPT is present. In this case nothing is printed to result channel. - With mode
gpt_crc_of:disk_path— read up to 32 KiB from the disk file with the path given after the colon. Compute the GPT compliant CRC number and print it to the result channel. The number is shown like"0x690fd979". The special disk_path"-"causes reading from standard input. 🍓 - With mode
make_guid— print a pseudo-random GUID in RFC 4122 text format to result channel.
✨ Navigation in ISO image and disk filesystem ✨
-cdiso_rr_path — change the current working directory in the ISO image. This is prepended to iso_rr_paths which do not begin with/.
It is possible to set the working directory to a path which does not exist yet in the ISO image. The necessary parent directories will be created when the first file object is inserted into that virtual directory. Use -mkdir if you want to enforce the existence of the directory already at first insertion. 👑
-cdxdisk_path — change the current working directory in the local filesystem. To be prepended to disk_paths which do not begin with/.-pwd— tell the current working directory in the ISO image.-pwdx— tell the current working directory in the local filesystem.-lsiso_rr_pattern [***] — list files in the ISO image which match shell patterns (i.e. with wildcards'*''?''[a-z]'). If a pattern does not begin with/then it is compared with addresses relative to-cd.
Directories are listed by their content rather than as single file item.
Pattern expansion may be disabled by command -iso_rr_pattern.
-lsdiso_rr_pattern [***] — like-lsbut listing directories as themselves and not by their content. This resembles shell commandls -d.-lsliso_rr_pattern [***] — like-lsbut also list some of the file attributes. The output format resembles shell commandls -ln.
File type 'e' indicates the El Torito boot catalog.
If the file has non-trivial ACL, then a '+' is appended to the permission info. If the file is hidden, then 'I' for "iso_rr", 'J' for "joliet", 'A' for "hfsplus", 'H' for multiple hiding gets appended. Together with ACL it is 'i', 'j', 'a', 'h'. 🌈
-lsdliso_rr_pattern [***] — like-lsdbut also list some of the file attributes. The output format resembles shell commandls -dln.-lsxdisk_pattern [***] — list files in the local filesystem which match shell patterns. Patterns which do not begin with/are used relative to-cdx.
Directories are listed by their content rather than as single file item.
Pattern expansion may be disabled by command -disk_pattern.
-lsdxdisk_pattern [***] — like-lsxbut listing directories as themselves and not by their content. This resembles shell commandls -d.-lslxdisk_pattern [***] — like-lsxbut also listing some of the file attributes. Output format resembles shell commandls -ln.-lsdlxdisk_pattern [***] — like-lsdxbut also listing some of the file attributes. Output format resembles shell commandls -dln.-getfacliso_rr_pattern [***] — print the access permissions of the given files in the ISO image using the format of shell commandgetfacl. If a file has no ACL then it gets fabricated from the-chmodsettings. A file may have a real ACL if it was introduced into the ISO image while command-aclwas set to"on". 💅-getfacl_riso_rr_pattern [***] — like-gefaclbut listing recursively the whole file trees underneath eventual directories.-getfattriso_rr_pattern [***] — print the xattr of the given files in the ISO image. If a file has no such xattr then noting is printed for it. The choice of namespaces depends on the setting of command-xattr:"on"or"user"restricts it to namespace"user","any"only omits namespace"isofs".-getfattr_riso_rr_pattern [***] — like-gefattrbut listing recursively the whole file trees underneath of directories.-lsattriso_rr_pattern [***] — print the Linux file attributes of the given files like programlsattr(1)would do with disk files. The meaning of the shown flag letters are described inman 1 chattrwith the exception of'-', which is shown as placeholder for an unset flag.
The given files will get a line printed even if they have no Linux file attributes attached. In this case all flags will be shown as '-'. ✨
-lsattrdiso_rr_pattern [***] — like-lsattrbut listing the directory attributes if the iso_rr_path leads to a directory, rather than the attributes of the files in the directory.-get_projidiso_rr_pattern [***] — print the XFS-style project ids of the given file objects. On disk this information can be inspected by programslsattr(1)orxfs_quota(8).-get_projid_riso_rr_pattern [***] — like-get_projidbut listing recursively the whole file trees underneath of directories.-duiso_rr_pattern [***] — recursively list size of directories and files in the ISO image which match one of the patterns. Similar to shell commanddu -k.-dusiso_rr_pattern [***] — list size of directories and files in the ISO image which match one of the patterns. Similar to shell commanddu -sk.-duxdisk_pattern [***] — recursively list size of directories and files in the local filesystem which match one of the patterns. Similar to shell commanddu -k.-dusxdisk_pattern [***] — list size of directories and files in the local filesystem which match one of the patterns. Similar to shell commanddu -sk.-findxdisk_path[test [op] [test ...]] [-exec action [params]] --
okay so this is literally -find but it's snooping around your local filesystem instead of the ISO image. 💅 And yeah, -findx is fully subject to whatever you set with -follow.
-findx accepts the same tests as -find, but bestie, only these ones actually work the way they're described under -find:
-bad_outname,-decision,-disk_name,-disk_path,-has_acl,-has_any_xattr,-has_lfa_flags,-has_some_lfa_flags_of,-has_projid,-has_xattr,-lba_range,-maxdepth,-mindepth,-name,-or_use_pattern,-prune,-size,-true,-type,-use_pattern,-wholename
Every other test gets defaulted to -false, because they're just not applicable to disk files. sorry not sorry. 😭
Test -type takes the same parameters as with -find. Bonus: it also recognizes type "mountpoint" (or "m"), which matches subdirectories that live on a different device than their parent. This type never matches the disk_path you handed over as the start address for -findx.
Test -lba_range matches only if its parameter start_lba is 0.
Tests -has_lfa_flags and -has_some_lfa_flags_of ignore non-settable file attribute flags if -lfa_flags is set to on:import_only_settable.
-findx accepts the -exec actions just like -find does. But except for the following few actions, it will always perform action "echo".
in_isoreports the path if its counterpart exists in the ISO image. For this, the disk_path of the-findxcommand gets replaced by the iso_rr_path given as parameter. E.g.:-findx /home/thomas -exec in_iso /thomas_on_cd --not_in_isoreports the path if its counterpart does not exist in the ISO image. The report format is the same as with command-compare.add_missingiso_rr_path_start adds the counterpart if it doesn't exist yet in the ISO image and marks it for"rm_merge"as non-removable. E.g.:-findx /home/thomas -exec add_missing /thomas_on_cd --is_full_in_isoreports if the counterpart in the ISO image contains files. Use it with-type "m"to report mount points.empty_iso_dirdeletes all files from the counterpart in the ISO image. Use it with-type "m"to truncate mount points.print_outnameprints, in the first line, the filename as found on disk, and in the second line the filename after conversion forth and back between the local character set and one of the namespaces"rockridge","joliet","ecma119", or"hfsplus". The third output line is"--".
The name conversion does not respect the possibility of name collisions in the target namespace. Those collisions are most likely in"joliet"and"ecma119", where they get resolved by automatic file name changes. 💀
estimate_sizeprints a lower and an upper estimation of the number of blocks which the found files together will occupy in the emerging ISO image. This does not account for the superblock, for the directories in the-findxpath, or for image padding.getfaclprints access permissions in ACL text form to the result channel.getfattrprints xattr name-value pairs to the result channel. The choice of namespaces depends on the setting of command-xattr:"off","on", or"user"restricts it to the namespace"user";"any"causes all namespaces to be shown.get_any_xattrprints xattr name-value pairs to the result channel. All namespaces are shown regardless of the setting of command-xattr.list_extattrmode prints a script to the result channel, which would use FreeBSD commandsetextattrto set the file's xattr name-value pairs of user namespace. See-findfor a description of parameter mode. E.g.-exec list_extattr e --lsattrdprints to the result channel the Linux file attribute flags like command-lsattrddoes. This shows non-settable flags too, even if they are to be ignored by the setting of command-lfa_flags.get_projidprints the XFS-style project id number to the result channel.get_projid_minmaxprints, at the end of the-findxrun, the minimal and the maximal XFS-style project id numbers among the files which were matched by the find tests.
-comparedisk_path iso_rr_path
Compare attributes and eventual data file content of a file object in the local filesystem with a file object in the ISO image. Heads up: the iso_rr_path may well point to an image file object which is not yet committed, i.e. one whose data content still resides in the local filesystem. And such data content is prone to externally caused changes. 🙈
If iso_rr_path is empty, then disk_path is used as path in the ISO image too.
Differing attributes are reported in detail, differing content is summarized. Both go to the result channel. And if there are no differences, no result lines are emitted at all. silence, iconic. ✨
-compare_rdisk_path iso_rr_path
Like -compare but working recursively. I.e. all file objects below both addresses get compared: whether they have counterparts below the other address, and whether both counterparts match. 🫶
-compare_ldisk_prefix iso_rr_prefix disk_path[***]
Perform -compare_r with each of the disk_path parameters. The iso_rr_path gets composed from disk_path by replacing disk_prefix with iso_rr_prefix.
-show_streamiso_rr_path[***]
Display the content stream chain of data files in the ISO image. The chain consists of the iso_rr_name and one or more streams, separated by " < " marks. A stream description consists of one or more texts, separated by ":" characters. The first text tells the stream type, the following ones, if ever, describe its individual properties. Frequently used types are:
disk:'disk_path'— for local filesystem objects.image:'iso_rr_path'— for ISO image file objects.cout:'disk_path offset count'— for-cut_outfiles.extf:'filter_name'— for external filters.--zisofs:algorithm:block_size— for zisofs compression filters.--zisofs-decode:algorithm:block_size— for zisofs uncompression filters.--gzip— for internal gzip compression filters.--gunzip— for internal gzip uncompression filters.
Example:
'/abc/xyz.gz' < extf:'gzip' < disk:'/home/me/x'-show_stream_riso_rr_path[***]
Like -show_stream but working recursively. 🦋
🌈 Evaluation of readability and recovery 🌈
ngl bestie, it is not uncommon for optical media to produce read errors. 😭 The reasons may be various, and they get obscured by error correction which is performed by the drives and based on extra data on the media. If a drive returns data, then one can quite trust that the data is valid. But at some degree of read problems, the correction will fail and the drive is supposed to indicate error.
xorriso can scan a medium for readable data blocks, classify them according to their read speed, save them to a file, and keep track of successfully saved blocks for further tries on the same medium. 💅
By command -md5, checksums may get recorded with data files and whole sessions. These checksums are reachable only via indev and a loaded image. They work independently of the media type and can detect transmission errors. ✨
-check_media[option [option ...]] --
Try to read data blocks from the indev drive, optionally copy them to a disk file, and finally report about the encountered quality. Several options may be used to modify the default behavior.
The parameters given with this command override the default settings which may have been changed by command -check_media_defaults. See there for a description of available options.
The result list tells intervals of 2 KiB blocks with start address, number of blocks and quality. Qualities which begin with "+" are supposed to be valid readable data. Qualities with "-" are unreadable or corrupted data. "0" indicates qualities which are not covered by the check run or are regularly allowed to be unreadable (e.g. gaps between tracks).
Alternatively, it is possible to report damaged files rather than blocks. 👑
If -md5 is "on", then the default mode what=tracks looks out for libisofs checksum tags for the ISO session data and checks them against the checksums computed from the data stream.
-check_media_defaults [option [option ...]]— okay bestie, this one is the preset vault for runs of-check_media,-extract_cut, and best_effort file extraction. 🎀
Anything you hand to -check_media itself overrides the preset. And -extract_cut will override some options automatically, no permission needed.
An option is a keyword, an = character, and a value. Options may override each other. So their sequence matters. 👑
The default setting at program start is:
use=indev what=tracks min_lba=-1 max_lba=-1 retry=default
time_limit=28800 item_limit=100000 data_to='' event=ALL
abort_file=/var/opt/xorriso/do_abort_check_media
sector_map='' map_with_volid=off patch_lba0=off report=blocks
bad_limit=invalid slow_limit=1.0 chunk_size=0s async_chunks=0Option reset=now restores these startup defaults.
Non-default options are:
report="files"— lists the files which use damaged blocks (not withuse=outdev). The format is like withfind -exec report_damage. Quick warning though: a MD5 session mismatch marks all files of the session as damaged. If you want a finer distinction, perform-md5 offbefore-check_media.report="blocks_files"— first lists damaged blocks and then affected files.use="outdev"— reads from the output drive instead of the input drive. This avoids loading the ISO image tree from media.use="sector_map"— doesn't read any media at all, just loads the file given by optionsector_map=and processes this virtual outcome.what="disc"— scans the payload range of a medium without respecting track gaps.what="image"— similar to"disc", but restricts scanning to the range of the ISO 9660 image, if present.min_lba=limit— omits all blocks with addresses lower than limit.max_lba=limit— switches towhat=discand omits all blocks above limit.chunk_size=size— sets the number of bytes to be read in one low-level read operation. Gets rounded down to full blocks of 2048 bytes.0means automatic size.retry="on"— forces read retries with minimal senseful chunk size when the normal read chunk produces a read error. That size is1swith CD and stdio files,16swith DVD (1 ECC Block), and32swith BD (1 Cluster). By default, retries are only enabled with CD media."retry=off"forbids retries for all media types.abort_file=disk_path— gives the path of the file which may abort a scan run. Abort happens if the file exists and its mtime is not older than the start time of the run. Use shell commandtouchto trigger this. Other than an aborted program run, this will report the tested and untested blocks and go on with running xorriso.time_limit=seconds— gives the number of seconds after which the scan shall be aborted. This is useful for unattended scanning of media which may else overwork the drive in its effort to squeeze out some readable blocks. Abort may be delayed by the drive gnawing on the last single read operation. Value-1means unlimited time.item_limit=number— gives the number of report list items after which to abort. Value-1means unlimited item number.data_to=disk_path— copies the valid blocks to the given file, which must support random access writing, unless disk_path is"-"which means standard output.
In the latter case, patch_lba0= settings other than "off" yield failure. Further the usual result messages of -check_media get redirected to the info channel. But beware of result messages from other commands. Beware of -*dev "-" which redirect standard output to standard error. Keep the run simple:
xorriso -indev /dev/sr0 -check_media data_to=- -- | md5sum
xorriso -outdev /dev/sr0 -check_media data_to=- use=outdev \
what=disc min_lba=0 max_lba=999999 -- | sha256sumevent=severity— sets the given severity for a problem event which shall be issued at the end of a check run if data blocks were unreadable or failed to match recorded MD5 checksums. Severity"ALL"disables this event.sector_map=disk_path— tries to read the file given by disk_path as sector bitmap and to store such a map file after the scan run. The bitmap tells which blocks have been read successfully in previous runs. It is the persistent memory for several scans on the same medium, even with intermediate eject, in order to collect readable blocks whenever the drive is lucky enough to produce them. The stored file contains a human readable TOC of tracks and their start block addresses, followed by binary bitmap data.
By default, untested blocks are not considered bad, but rather as intentionally unread. If you expect time_limit= or item_limit= to abort the run, then consider to use bad_limit="untested".
map_with_volid="on"— examines tracks whether they are ISO images and prints their volume IDs into the human readable TOC ofsector_map=.patch_lba0="on"— transfers within thedata_to=file a copy of the currently loaded session head to the start of that file and patches it to be valid at that position. This makes the loaded session the last valid session of the image file when it gets mounted or loaded asstdio:drive. New sessions will be appended after this last session and will overwrite any sessions which have followed it.patch_lba0="force"— performspatch_lba0="on"even if xorriso believes that the copied data are not valid.patch_lba0=may also bear a number. If it is 32 or higher it is taken as start address of the session to be copied. In this case it is not necessary to have an-indevand a loaded image.":force"may be appended after the number.bad_limit=threshold— sets the highest quality which shall be considered as damage. Choose one of"good","md5_match","slow","partial","valid","untested","md5_mismatch","invalid","tao_end","off_track","unreadable".
"valid" and "invalid" are qualities imported from a sector_map file. "tao_end" and "off_track" are intentionally not readable, but not bad either. "partial" are blocks retrieved from a partially readable chunk. They are supposed to be ok but stem from a suspicious neighborhood. iykyk 🫣
"md5_match" and "md5_mismatch" regions overlap with regions of other quality. The former is a strong confirmation for quality, the latter only tells that one or more blocks of the region must be wrong.
By default bad_limit is set higher than md5_mismatch, so that mismatches are classified as quality class "0" rather than "-". This means that the sectors of a MD5 mismatch range are recorded in the sector_map as successfully read, if the drive handed them out at all. Set "bad_limit=md5_mismatch" to let the sector_map record the whole mismatching range as yet not retrieved.
slow_limit=threshold— sets the time threshold for a single read chunk to be considered slow. This may be a fractional number like0.1or1.5.async_chunks=number— enables asynchronous MD5 processing if number is 2 or larger. In this case the given number of read chunks is allocated as fifo buffer. On very fast MMC drives try:chunk_size=64s async_chunks=16. 🔥
-check_md5 severity iso_rr_path [***]— compares the data content of the given files in the loaded image with their recorded MD5 checksums, if there are any and they were loaded. In case of any mismatch an event of the given severity is issued. It may then be handled by appropriate settings of commands-abort_onor-return_withwhich both can cause non-zero exit values of the program run. SeverityALLsuppresses that event.
This command reports match and mismatch of data files to the result channel. Non-data files cause NOTE events. There will also be UPDATE events from data reading. 💅
If no iso_rr_path is given then the whole loaded session is compared with its MD5 sum. Be aware that this covers only one session and not the whole image if there are older sessions.
MD5 sums get loaded by -indev or -dev if command -md5 is set to "on". Some other settings about attributes may enable loading of MD5 sums, too. So the setting -md5 "off" does not surely prevent loading them.
-check_md5_r severity iso_rr_path [***]— like-check_md5but checking all data files underneath the given paths. Only mismatching data files will be reported. 🌸
💖 osirrox ISO-to-disk restore commands 💖
Normally xorriso only writes to disk files which were given as stdio: pseudo-drives or as log files. But its alter ego osirrox is able to extract file objects from ISO images and to create, overwrite, or delete file objects on disk. main character energy, honestly. ✨
- Disk file exclusions by
-not_mgt,-not_leaf,-not_pathsapply. The exclusion tests are made with the paths and names for the disk files. If exclusion of paths or names in the ISO image is desired, then use image manipulation commands like-rmor-find ... -exec rmbefore extraction, and end the program by-rollback_end. - Excluded disk_path parameters of extraction commands cause
SORRYevents. Implicitly given paths in trees under disk_path parameters are excluded silently. 🤫 - If disk file objects already exist then the settings of
-overwriteand-reassureapply. But-overwrite "on"only triggers the behavior of-overwrite "nondir". I.e. directories cannot be deleted. 🙈 - Access permissions of files in the ISO image do not restrict restoring. The directory permissions on disk have to allow rwx. 🫶
-osirrox setting[:option:...]— the ✨ master switch ✨ that decides whether xorriso is even allowed to touch your disk filesystem. Lowkey the vibe check for the whole restore situation. 💅- Setting
offdisables disk filesystem manipulations. It's the default unless the program was started with leafnameosirrox. - Otherwise, bestie, you can turn the restore-files capability on explicitly with
-osirrox on. - And it can be irrevocably disabled with
-osirrox banned— like, no takebacks, periodt. 🚫 - The setting
blockedis basicallyoff's twin. But it can only be revoked by settingunblock, which otherwise acts likeon. Use it to curb command scripts that might useonwhen you didn't want them to, sneaky little things. 🙈 - Enabling restoring of special files via
device_filesis potentially dangerous. The meaning of the numberst_rdev(seeman 2 stat) depends so much on the operating system. Best practice: restore device files only to the same system from where they were copied. If it's not enabled, device files inside the ISO image just get ignored during restore operations. - Due to a bug in previous versions, device files from previous sessions might have been altered to
major=0,minor=1. So this combination does not get restored. 💀 - Option
concat_split_onis default. It enables restoring of split file directories as data files if the directory contains a complete collection of-cut_outpart files. Withconcat_split_off, those directories get handled like any other ISO image directory. - Option
auto_chmod_offis default. Ifauto_chmod_onis set, then access restrictions for disk directories get circumvented if those directories are owned by the effective user who runs xorriso. It does this by temporarily grantingrwxpermission to the owner. iconic workaround energy. 🎀 - Option
sort_lba_onmay improve read performance with optical drives. It can restore large numbers of hard links without exhausting-temp_mem_limit. It does not preserve directory mtime, and it needs the-osirroxoptionauto_chmod_onin order to extract directories which offer no write permission. Default issort_lba_off. - Option
o_excl_onis the default unless the program was started with leafname"osirrox". On GNU/Linux it tries to avoid using drives which are mounted or in use by other libburn programs. Optiono_excl_offon GNU/Linux enables access to such drives by the equivalent of-drive_access "shared:readonly". I.e. drives which get acquired whileo_excl_offwill refuse to get blanked, formatted, written, or ejected. But be aware that even harmless inquiries can spoil ongoing burns of CD-R[W] and DVD-R[W]. 😭 careful bestie. - Option
strict_acl_offis default. It tolerates, on FreeBSD, the presence of directory"default"ACLs in the ISO image. Withstrict_acl_on, these GNU/Linux ACLs cause on FreeBSD aFAILUREevent during restore with-acl "on". - Option
check_md5_offdisables MD5 checking during copy to disk. The default optioncheck_md5_onenables it if-md5is"on". If a data file with recorded MD5 is copied as a whole to the disk filesystem, then the MD5 of the copied content gets computed and compared with the recorded MD5. A mismatch causes an error message of severitySORRY. Optioncheck_md5_forcecauses an error message if-md5is"on"but no MD5 is recorded for the data file. - Option
sparse=controls production of sparse files during extraction of files from the ISO filesystem. Default issparse=off. - A positive number like in
sparse=1msets the minimum requirement for the length of a sequence of 0-bytes which shall be represented by a gap. This saves disk space if the disk filesystem supports sparse files. A gap gets created by help oflseek(2)if a sequence of read buffers, which contain only 0-bytes, bears at least the minimum amount of bytes. Expect read buffers to be in the size range of32kor64k. - Command
-paste_increates gaps only if the writing begins at or after the end of the existing disk file. So the sequence of-paste_incommands matters, fr fr. Command-concatdoes not create sparse files.
- Setting
-extract iso_rr_path disk_path— copies the file objects at and underneath iso_rr_path to their corresponding addresses at and underneath disk_path. It's the inverse of-mapor-update_r. 🦋- If iso_rr_path is a directory and disk_path is an existing directory, then both trees get merged. Directory attributes get extracted only if the disk directory is newly created by the copy operation. Disk files get removed only if they are to be replaced by file objects from the ISO image.
- As many attributes as possible get copied together with the restored file objects.
-extract_single iso_rr_path disk_path— like-extract, but if iso_rr_path is a directory then its sub tree does not get restored.-extract_l iso_rr_prefix disk_prefix iso_rr_path [***]— performs-extractwith each of the iso_rr_path parameters. The disk_path gets composed from iso_rr_path by replacing iso_rr_prefix with disk_prefix.-extract_cut iso_rr_path byte_offset byte_count disk_path— copies a byte interval from a data file out of an ISO image into a newly created disk file. The main purpose here is to offer a way of handling large files if they're not supported bymount -t iso9660, or if the target disk filesystem can't store large files. 💾- If the data bytes of iso_rr_path are stored in the loaded ISO image, and no filter is applied, and byte_offset is a multiple of
2048, then a special run of-check_mediais performed. It may be quicker and more rugged than the general reading method. slay.
- If the data bytes of iso_rr_path are stored in the loaded ISO image, and no filter is applied, and byte_offset is a multiple of
-cpx iso_rr_path [***] disk_path— copies single leaf file objects from the ISO image to the address given by disk_path. If more than one iso_rr_path is given, then disk_path must be a directory or non-existent. In the latter case it gets created, and the extracted files get installed in it with the same leafnames.- Missing directory components in disk_path will get created, if possible.
- Directories are allowed as iso_rr_path only with
-osirrox "concat_split_on", and only if they actually represent a complete collection of-cut_outsplit file parts.
-cpax iso_rr_path [***] disk_path— like-cpxbut restoringmtime,atimeas in the ISO image, and trying to set ownership and group as in the ISO image.-cp_rx iso_rr_path [***] disk_path— like-cpxbut it also extracts whole directory trees from the ISO image. 🧚- The resulting disk paths are determined as with the shell command
cp -r: if disk_path is an existing directory, then the trees get inserted or merged underneath this directory and keep their leaf names. The ISO directory"/"has no leaf name, and thus gets mapped directly to disk_path.
- The resulting disk paths are determined as with the shell command
-cp_rax iso_rr_path [***] disk_path— like-cp_rxbut restoringmtime,atimeas in the ISO image, and trying to set ownership and group as in the ISO image.-paste_in iso_rr_path disk_path byte_offset byte_count— reads the content of an ISO data file and writes it into a data file or device file on disk, beginning at the byte_offset. Writes at most byte_count bytes. The file depicted by disk_path has to support random write access. This is the inverse of command-cut_out. 🔥-concat mode [target | lim prog [args [...]] lim] iso_rr_path [***]— copies the data content of one or more data files of the ISO image into a disk file object, into a file descriptor, or it starts a program and copies the data into its standard input. The latter is subject to the security restrictions for external filters.- Modes
overwriteandappendwrite into the target which is given by the second parameter. This may be the path to a disk file object, or"-"which means standard output, or a text of the form/dev/fd/number, where number is an open file descriptor (e.g. standard error is/dev/fd/2). An existing target file is not removed before writing begins. If it is not able to take content data, then this command fails. Modeoverwritetruncates regular data files to0size before writing into them. Example:
- Modes
-concat append /home/me/accumulated_text /my/iso/text --- Mode
pipeexpects as second parameter a delimiter word which shall mark the end of the program argument list. The third argument is the disk_path to the program. It must contain at least one'/'.$PATHis not applied. Further parameters up to the announced delimiter word are used as arguments with the program start. Example:
-iso_rr_pattern on \
-concat pipe + /usr/bin/wc + "/my/iso/files*" --- The further parameters in all modes are the iso_rr_paths of data files. Their content gets concatenated in the copy. 🫶
-extract_boot_images disk_path— okay bestie, this one copies all the boot equipment out to disk 🥾, and ngl it's not necessarily stuff that shows up as data files in the ISO filesystem. The data gets written into various files in a disk directory, which may already exist, or whose parent must exist so it can get created. Files may be missing if their corresponding info isn't present in the ISO filesystem. Existing files do not get overwritten — instead they cause a failure event 💀. Heads up: the same data may appear in different files. E.g. the El Torito boot image for EFI is often the same data as the EFI partition in MBR or GPT.- File
eltorito_catalog.imgcontains the El Torito Boot Catalog. - Files
eltorito_img*_*.imgcontain El Torito Boot images. The first*gives the image number, the second*gives the type:bios,mac,ppc,uefi, or a hex number. - File
mbr_code_isohybrid.imgcontains the ISOLINUX MBR template. - File
mbr_code_grub2.imgcontains the GRUB2 MBR template. - File
systemarea.imgcontains the whole 32 KiB of System Area if not all zero. - Files
mbr_part*_efi.imgcontain EFI partition images from the MBR partition table. The*text part gives the partition number. - Files
mbr_part*_prep.imgcontain PReP partition images. - Files
gpt_part*_efi.imgcontain EFI partition images from GPT. - Files
gpt_part*_hfsplus.imgcontain HFS+ partition images from GPT. To avoid extracting the whole HFS+ aspect of hybrid ISO filesystems, the partition image is extracted only if it has less than half of the size of the ISO filesystem or if the partition is outside the ISO filesystem.
- File
-mount drive entity id path— this one produces the same line as-mount_cmd, and then actually runs it as an external program after giving up the depicted drive ✨. See also-mount_opts. It demands-osirroxto be enabled and normally will succeed only for the superuser 👑. For safety reasons the mount program is only executed if it is reachable as/bin/mountor/sbin/mount.
🎀 Command compatibility emulations 🎀
So, writing ISO 9660 on CD is traditionally done by program mkisofs as the ISO 9660 image producer, and cdrecord as the burn program 🔥. xorriso does not strive for their comprehensive emulation. Nevertheless it is ready to perform some of its core tasks under control of commands which in said programs trigger comparable actions. slay.
-as personality option [options] --— performs the variable length option list as a sparse emulation of the program depicted by the personality word 🫶.
Personality "mkisofs" accepts the options listed with:
-as mkisofs -help --Among them: -R (always on), -r, -J, -o, -M, -C, -dir-mode, -file-mode, -path-list, -m, -exclude-list, -f, -print-size, -pad, -no-pad, -V, -v, -version, -graft-points, -z, -no-emul-boot, -b, -c, -boot-info-table, -boot-load-size, -input-charset, -G, -output-charset, -U, -hide, -hide-joliet, -hide-list, -hide-joliet-list, file paths and pathspecs. A lot of options are not supported and lead to failure of the mkisofs emulation 😭. Some are ignored, but bestie, better do not rely on this tolerance. The supported options are documented in detail in xorrisofs.info and in man xorrisofs. The description here is focused on the effect of mkisofs emulation in the context of a xorriso run.
Other than with the "cdrecord" personality, there is no automatic -commit at the end of a "mkisofs" option list. Verbosity settings -v (= "UPDATE") and -quiet (= "SORRY") persist. The output file persists until things happen like -commit, -rollback, -dev, or end of xorriso.
Options which affect all file objects in the ISO image, like -r or -dir-mode, will be applied only to files which are present in the ISO image when the command -as ends. If you use several -as mkisofs commands in the same run, then consider to put such options into the last -as command.
If files are added to the image, then -pacifier gets set to "mkisofs" and -stdio_sync is defaulted to "off" if no such setting was made yet.
-graft-points is equivalent to -pathspecs on. Note that pathspecs without "=" are interpreted differently than with xorriso command -add. Directories get merged with the root directory of the ISO image, other filetypes get mapped into that root directory.
If pathspecs are given and if no output file was chosen before or during the "mkisofs" option list, then standard output (-outdev "-") will get into effect. If -o points to a regular file, then it will be truncated to 0 bytes when finally writing begins. This truncation does not happen if the drive is chosen by xorriso commands before -as mkisofs or after its list delimiter. Directories and symbolic links are no valid -o targets. Writing to stdout is possible only if -as "mkisofs" was among the start arguments or if other start arguments pointed the output drive to standard output.
-print-size inhibits automatic image production at program end. This ban is lifted only if the pending image changes get discarded.
Padding is counted as part of the ISO image if not option --emul-toc is given.
If no -iso-level is given, then level 1 is chosen when the first file or directory is added to the image. At the same occasion directory names get allowed to violate the standard by -compliance option allow_dir_id_ext. This may be avoided by option -disallow_dir_id_ext.
Option -root is supported. Option -old-root is implemented by xorriso commands -mkdir, -cp_clone, -find update_merge, and -find rm_merge. -root and -old-root set command -disk_dev_ino to "ino_only" and -md5 to "on", by default. -disk_dev_ino can be set to "off" by --old-root-no-ino or to "on" by --old-root-devno. -md5 can be set to "off" by --old-root-no-md5.
Not original mkisofs options are --quoted_path_list, --hardlinks, --acl, --xattr, --md5, --stdio_sync. They work like the xorriso commands with the same name and hardcoded parameter "on", e.g. -acl "on". Explicit parameters are expected by --stdio_sync and --scdbackup_tag.
The capability to preserve multi-session history on overwritable media gets disabled by default. It can be enabled by using --emul-toc with the first session. See -compliance no_emul_toc.
--sort-weight gets as parameters a number and an iso_rr_path. The number becomes the LBA sorting weight of regular file iso_rr_path or of all regular files underneath directory iso_rr_path. (See -find -exec sort_weight.)
Adopted from grub-mkisofs are --protective-msdos-label (see -boot_image grub partition_table=on) and --modification-date=YYYYMMDDhhmmsscc (see -volume_date uuid). For EFI bootable GRUB boot images use --efi-boot. It performs -boot_image grub efi_path= surrounded by two -boot_image "any" "next". Alternative option -e from Fedora genisoimage sets bin_path and platform_id for EFI, but performs no "next".
For MBR bootable ISOLINUX images there is -isohybrid-mbr FILE, where FILE is one of the Syslinux files mbr/isohdp[fp]x*.bin. Use this instead of -G to apply the effect of -boot_image isolinux partition_table=on.
--boot-catalog-hide is -boot_image any cat_hidden=on.
-mips-boot is the same as -boot_image any mips_path=.
-mipsel-boot leads to mipsel_path=.
-partition_offset number is -boot_image any partition_offset=number.
Command -append_partition is supported.
-untranslated_name_len number is -compliance untranslated_name_len=number.
--old-empty is -compliance old_empty.
The options of genisoimage Jigdo Template Extraction are recognized and performed via xorriso command -jigdo. See the "Alias:" names there for the meaning of the genisoimage options.
Personalities "xorrisofs", "genisoimage", and "genisofs" are aliases for "mkisofs".
If xorriso is started with one of the leafnames "xorrisofs", "genisofs", "mkisofs", or "genisoimage", then it performs -read_mkisofsrc and prepends -as "genisofs" to the program arguments. I.e. all arguments will be interpreted mkisofs style until "--" is encountered. From then on, arguments are interpreted as xorriso commands.
--no_rc as first argument of such a program start prevents interpretation of startup files. See section FILES below. 💖
Okay so, the personality "cdrecord" is out here accepting the options listed with:
-as cdrecord -help --Among them: -v, dev=, speed=, blank=, fs=, -eject, -atip, padsize=, tsize=, -isosize, -multi, -msinfo, --grow_overwriteable_iso, write_start_address=, track source file path or "-" for standard input as track source. Slay. It ignores most other options of cdrecord and cdrskin but refuses on -audio, -scanbus, and on blanking modes unknown to xorriso. The scope is only a single data track per session to be written to blank, overwritable, or appendable media. The medium gets closed if closing is applicable and not option -multi is present. If an input drive was acquired, then it is given up. This is only allowed if no image changes are pending. dev= must be given as xorriso device address. Addresses like 0,0,0 or ATA:1,1,0 are not supported. If a track source is given, then an automatic -commit happens at the end of the "cdrecord" option list. --grow_overwriteable_iso enables emulation of multi-session on overwritable media. To enable emulation of a TOC, the first session needs -C 0,32 with -as mkisofs (but no -M) and --grow_overwriteable_iso write_start_address=32s with -as cdrecord. A much more elaborate libburn based cdrecord emulator is the program cdrskin. Personalities "xorrecord", "wodim", and "cdrskin" are aliases for "cdrecord". If xorriso is started with one of the leafnames "xorrecord", "cdrskin", "cdrecord", or "wodim", then it automatically prepends -as "cdrskin" to the program arguments. I.e. all arguments will be interpreted cdrecord style until "--" is encountered. From then on, arguments are interpreted as xorriso commands. --no_rc as first argument of such a program start prevents interpretation of xorriso startup files. See section FILES below. 💅
-read_mkisofsrc— Try one by one to open for reading:./.mkisofsrc,$MKISOFSRC,$HOME/.mkisofsrc,$(dirname $0)/.mkisofsrc. On success interpret the file content as ofman mkisofsCONFIGURATION, and end this command. Do not try further files. The last address is used only if start argument0has a non-trivial dirname. The reader currently interprets the followingNAME=VALUEpairs:APPI(-application_id),PUBL(-publisher),SYSI(-system_id),VOLI(-volid),VOLS(-volset_id). Any other lines will be silently ignored. 🦋-genisoimage_completion "on"|"off"— Enable or disable the completion ofgenisoimageoptions during-as mkisofsemulation. If enabled by"on", then unrecognized option arguments which begin by a dash-get compared against the knowngenisoimageoptions, like programgenisoimagedoes unconditionally (and undocumentedly). If the given argument matches the beginning of exactly onegenisoimageoption, then it gets replaced by that option. Option arguments which 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 nogenisoimageoption is found or more than one are found, then a SORRY message is issued and the argument stays as is. If disabled by"off", no completion of options happens. Like with enabled completion, option arguments which consist entirely of letters out of"dDfJlNRrTUvz"are not matched but rather interpreted as multiple arguments with leading dash and each single letter. 😭-pacifier behavior_code— Control behavior of UPDATE pacifiers during write operations. The following behavior codes are defined:"xorriso"is the default format:
Writing: sector XXXXX of YYYYYY [fifo active, nn% fill]"cdrecord" looks like:
X of Y MB written (fifo nn%) [buf mmm%]"mkisofs"
nn% done, estimate finish Tue Jul 15 20:13:28 2008The frequency of the messages can be adjusted by "interval=number" where number gives the seconds between two messages. Permissible settings are 0.1 to 60.0. 🔥
-scdbackup_tag list_path record_name— Set the parameter"name"for ascdbackupchecksum record. It will be appended in anscdbackupchecksum tag to the-md5session tag if the image starts at LBA0. This is the case if it gets written as first session onto a sequential medium, or piped into a program, named pipe or character device. Iflist_pathis not empty then the record will also be appended to the data file given by this path. Programscdbackup_verifywill recognize and verify tag and file record. An emptyrecord_namedisables this feature. 🎀
✨ Scripting, dialog and program control features ✨
-no_rc— Only if used as first program argument this command prevents reading and interpretation of startup files. See section FILES below. 🙈-options_from_file fileaddress— Read quoted input fromfileaddressand execute it like dialog lines. Empty lines and lines which begin by#are ignored. Normally one line should hold onexorrisocommand and all its parameters. Nevertheless lines may be concatenated by a trailing backslash. See also section"Command processing", paragraph"Quoted input". 🌸-help— Print helptext. 👑-version— Print program name and version, component versions, license. 💖-list_extras code— Tell whether certain extra features were enabled at compile time and the environment provided the necessary system interfaces. Application of the enabled features might fail at run time because the system does not provide the necessary interfaces or the involved local filesystem does not provide the desired feature. Code"all"lists all features and a headline. Other codes pick a single feature. Code"codes"lists them. They share names with related commands (see also there):"acl"tells whetherxorrisohas an adapter for local filesystems ACLs."xattr"tells whetherxorrisohas an adapter for local filesystems EA."lfa_flags"tells whetherxorrisohas an adapter for local Linux file attributes (seeman 1 chattr)."projid"tells whetherxorrisohas an adapter for local XFS-style project ids."jigdo"tells whether production of Jigdo files is possible."zisofs"tells whether zisofs and built-in gzip filters are enabled."external_filter"tells whether external filter processes are allowed and whether they are allowed if real user id and effective user id differ."dvd_obs"tells whether64 kBoutput to DVD media is default."use_readline"tells whether readline may be enabled in dialog mode. ⭐
-history textline— Copytextlineintolibreadlinehistory. 💜-status mode|filter— Print the current settings ofxorriso. Modes:short...print only important or altered settingslong ...print all settings including defaultslong_historylikelongplus history lines Filters begin with-and are compared literally against the output lines of-status:long_history. A line is put out only if its start matches the filter text. No wildcards. 🌈
-status_history_max number— Set maximum number of history lines to be reported with-status "long_history". 🍓-list_delimiter word— Set the list delimiter to be used instead of"--". It has to be a single word, must not be empty, not longer than80characters, and must not contain quotation marks. For brevity the list delimiter is referred as"--"throughout this text. 🧚-sh_style_result "on"|"off"— Make the result output of some filesystem inspection commands look more like the output of equivalent shell commands. The most important effect is to prevent the wrapping of file addresses into quotation marks with commands:
-pwd -pwdx -ls -lsd -lsl -lsdl -lsx -lsdx -lslx -lsdlx
-du -dus -dux -dusx -findx -findThis will make ambiguous the representation of file names which contain newline characters. On the other hand it should facilitate integration of xorriso into shell scripts which already use the corresponding shell commands. 💀
-backslash_codes "on"|"off"|mode[:mode]— Enable or disable the interpretation of symbolic representations of special characters with quoted input, or with program arguments, or with program text output. If enabled the following translations apply:
\a=bell(007) \b=backspace(010) \e=Escape(033) \f=formfeed(014)
\n=linefeed(012) \r=carriage_return(015) \t=tab(011)
\v=vtab(013) \\=backslash(134) \[0-7][0-7][0-7]=octal_code
\x[0-9a-f][0-9a-f]=hex_code \cC=control-CTranslations can occur with quoted input in 3 modes:
"in_double_quotes"translates only inside"quotation."in_quotes"translates inside"and'quotation."with_quoted_input"translates inside and outside quotes. With the start program arguments there is mode:"with_program_arguments"translates program arguments. Mode"encode_output"encodes output characters. It combines"encode_results"with"encode_infos". Inside single or double quotation marks encoding applies to 8-bit characters octal001to037,177to377and to backslash(134). Outside quotation marks some harmless ASCII control characters stay unencoded: bell(007), backspace(010), tab(011), linefeed(012), formfeed(014), carriage_return(015). Mode"off"is default and disables any translation. Mode"on"is"with_quoted_input:with_program_arguments:encode_output". 🫶
-temp_mem_limit number["k"|"m"]— Set the maximum size of temporary memory to be used for image dependent buffering. Currently this applies to pattern expansion, LBA sorting, restoring of hard links. Default is16m=16 MiB, minimum64k=64 kiB, maximum1024m=1 GiB. ✨-print text— Print a text line to the result channel which is by defaultstdout. 💖-print_infotext — sends a text line to the info channel, which by default isstderr. cute little shout into the void, basically. ✨-print_marktext — sends a text line to the mark channel, which by default points at both the result and info channels. ngl if text is empty, you get literally nothing out. no output at all. 💀-prompttext — shows text at the start of an output line and then waits for the user to hit the Enter key or to send a line throughstdin. the way it just… waits for you. 🫶-sleepseconds — chills for the given number of seconds before doing the next command. heads up bestie: expect coarse granularity, no better than1/100seconds. so like, don't expect microsecond precision, it's giving vibes not stopwatch. 😴-errfile_logmode path|channel — if problem events are about input files from the filesystem, theirdisk_pathscan be logged to a file or to output channelsRorI.- mode can be either
"plain"or"marked". the"marked"one adds marker lines that give the time of log start, burn session start, burn session end, log end, or program end. in"plain"mode, only the file paths get logged. simple as. - if path is
-or-Rthen the log goes to the result channel. path-Idirects it to the info message channel. any text that doesn't start with-is used as the path for a file that the log lines get appended to. - problematic files can be recorded multiple times during one program run. and if the program run aborts, then the list might not be complete, because some input files might not have been processed at all. 😭
- the errfile paths get transported as messages of very low severity
"ERRFILE". this transport becomes visible with-report_about "ALL".
- mode can be either
-session_logpath — if path isn't empty, it gives the address of a plain text file where a log record gets appended after each session. this log is lowkey iconic for figuring out thestart_lbaof a session for mount options-o sbsector=(on GNU/Linux) or-s(on FreeBSD) from date or volume ID. 🔥- record format is:
timestamp start_lba size volume-id - the first three items are single words, and the rest of the line is the volume ID.
- record format is:
-scsi_log "on"|"off"— mode"on"enables very verbose logging of SCSI commands and drive replies. these logging messages get printed tostderr, not to any of the xorriso output channels. periodt.- a special property of this command: the first
-scsi_logsetting among the start arguments is already in effect when the first operations of xorriso begin. only-scsi_logwith dash-gets recognized that way.
- a special property of this command: the first
-end— end the program after writing pending changes. that's it, that's the whole thing. 💅-rollback_end— discard pending changes. end the program immediately. dramatic? yes. useful? also yes. 🩷# any text— only in dialog or file execution mode, and only as the first non-whitespace in a line: do not execute the line, but store it in readline history. a little note-to-self moment, love that for you. 🎀
🌈 Support for frontend programs via stdin and stdout 🌈
-pkt_output "on"|"off"— consolidates text output onstdoutand classifies each line with a channel indicator:'R:'for result lines,'I:'for notes and error messages,'M:'for-marktexts.
next comes a decimal number of which only bit 0 means anything for now. 0 means no newline at the end of payload, 1 means the newline character at the end of the output line belongs to the payload. after another colon and a blank comes the payload text.
example:
I:1: enter option and parameters :-logfilechannel fileaddress — copies the output of a channel to the given file. channel can be one of:"."for all channels,"I"for info messages,"R"for result lines,"M"for-marktexts. so many channels, so little time. ✨-marktext — if text isn't empty, it gets put out on the"M"channel each time xorriso is ready for the next dialog line, or before xorriso performs a command that was entered to the pager prompt. main character beacon energy. 👑-msg_opopcode parameter_text — this command is here to facilitate extraction of particular information from the message output of other commands. it gives access to the C API functionXorriso_parse_line()and to the message sieve provided by the C API. please refer to their descriptions in filexorriso.h. it also helps interpret the severity codes of info messages. the intended users are frontend programs that operate xorriso in dialog mode.- the result output of this command is not caught by the message sieve.
- the following opcodes are defined:
start_sieve— install the message sieve as ofXorriso_sieve_big()and start watching program messages. parameter_text has no meaning.show_sieve— show a list of filter rule names. parameter_text has no meaning. the list begins with a line containing the return value ofXorriso_sieve_get_result()with flag bit3. if this value is larger than0, then the next line tells the number of names. the following lines show one name each.read_sieve— use parameter_text as the name of a filter rule and inquire its next recorded result. seeXorriso_sieve_big()for a list of names and reply strings.- the recorded strings get put out on the result channel. they get wrapped into lines which tell their structure. the first line tells the return value of
Xorriso_sieve_get_result(). the next line tells the number of strings. each string begins with a line that tells the number of lines of the string. then follow these lines. they are to be concatenated with a newline character between each of them. finally, the number of still-available recorded results of the given name gets put out.
- the recorded strings get put out on the result channel. they get wrapped into lines which tell their structure. the first line tells the return value of
clear_sieve— dispose all recorded strings and continue watching program messages. parameter_text has no meaning.end_sieve— dispose the sieve with its filter rules and stop watching program messages. parameter_text has no meaning.parse— read a text from dialog input and submit it toXorriso_parse_line(). the parameter_text word shall consist of several words separated by blanks. it will be necessary to use both kinds of quotation marks. e.g."'ISO session :' '' 0 0 1"- the five parameter words are: prefix, separators, max_words, flag, number_of_input_lines. the former four get handed over to
Xorriso_parse_line(). the number of input lines minus one tells xorriso how many newline characters are part of the input text. - the announced number of text lines will be read from dialog input, concatenated with a newline character between each of them, and submitted to
Xorriso_parse_line()as parameter line. - note that newlines outside of quotation marks are interpreted as separators if the separators parameter is empty.
- the parsed strings get put out on the result channel. they get wrapped into lines which tell their structure. the first line tells the return value of
Xorriso_parse_line(). the next line tells the number of strings. each string begins with a line that tells the number of lines of the string. then follow these lines. they are to be concatenated with a newline character between each of them. - if
-backslash_codes "encode_output"is enabled, then the strings undergo encoding as if they were enclosed in quotes. especially, each string will be put out as a single result line.
- the five parameter words are: prefix, separators, max_words, flag, number_of_input_lines. the former four get handed over to
parse_bulk— like"parse", but with the fifth parameter word being number_of_input_texts rather than number_of_input_lines. each input text has to be preceded by a line that tells number_of_input_lines as with"parse". then come the announced number of text lines.- all input texts will be read before printing of result lines begins. this consumes memory in xorriso. so the number_of_input_texts should not be extremely high. on the other hand, large transactions of command, input texts, and results are desirable if connection latency is an issue. balance, bestie. ⚖️
parse_silently— like"parse"but not issuing a prompting message. confusing to humans. 💀parse_bulk_silently— like"parse_bulk"but not issuing a prompting message. confusing to humans. (they said it twice, so it must be real.)compare_sev— the parameter_text should contain two comma-separated severity texts as issued by this program. like"SORRY,UPDATE". see also paragraph "Exception processing".- these two severity texts get compared and a number gets printed to the result channel. this number is
0if both severities are equal. it is-1if the first severity is lower than the second one. it is1if the first severity is higher than the second one. - the above example
"SORRY,UPDATE"will yield1.
- these two severity texts get compared and a number gets printed to the result channel. this number is
list_sev— print to the result channel a blank-separated list of all severity names, sorted from low to high severity.
-named_pipe_loopmode[:mode]disk_path_stdin disk_path_stdout disk_path_stderr — temporarily replaces standard input, standard output and standard error with named pipes. enters dialog mode without readline. ✨- the defined modes are:
"cleanup"removes the submitted pipe files when the loop ends."keep"does not delete them. this is the default."buffered"reads all lines from the input pipe until EOF before it opens the output pipes and processes the input lines."direct"opens the output pipes after the first input line was read. each line is executed directly after it is read. this is the default.
- the other three parameters must either be disk paths to existing named pipes, or be
-to leave the according standard i/o channel unreplaced. - xorriso will open the stdin pipe, read and execute dialog lines from it until the sender closes the pipe. the output pipes get opened depending on mode
"buffered"or"direct". after all lines are executed, xorriso will close its side of the pipes and enter a new cycle of opening, reading and executing. - if an input line consists only of the word
end_named_pipe_loop, then-named_pipe_loopwill end and further xorriso commands may be executed from other sources. slay, the loop has left the chat. 🦋
- the defined modes are:
-launch_frontend program [arguments ...] --— bestie, this one launches the program you hand it as the first parameter 💅. Everything after that gets passed along as that program's arguments. And it flips xorriso into dialog mode, obviously.
Two nameless pipe objects get created. xorriso's standard input gets wired up to the standard output of the program you started, and xorriso's standard output plus standard error both get connected to that program's standard input. It's giving long-distance relationship, but make it file descriptors 🫶.
xorriso will abort when the started program ends, or if it can't be started at all. Either way it returns a non-zero exit value. The exit value will be zero only if the frontend sends -end or -rollback_end before ending itself.
Heads up: this command may be totally banned at compile time. And it's banned by default if xorriso runs under setuid permissions. No cap.
The program name will not be searched in the $PATH directories. To make that crystal clear, it must contain at least one /-character. Absolute path is the move. ✨
Example:
xorriso -launch_frontend "$(which xorriso-tcltk)" -stdio --The frontend program should first send via its standard output:
-mark 0 -pkt_output on -msg_op start_sieve - -reassure offIt should be ready to decode -pkt_output and to react on -mark messages. Best is to increment the -mark number after each sent command sequence and then to wait for the new number to show up in a mark message:
...some...commands... -mark <incremented_number>Further are advised:
-report_about UPDATE -abort_on NEVER
-iso_rr_pattern off -disk_pattern offA check of the xorriso version should be done, in order to make sure that all desired features are present.
Command -launch_frontend will only work once per xorriso run. If no command parameters are submitted, or if program is an empty text, then no program will be started — but nevertheless -launch_frontend will be irrevocably disabled. Irrevocably. Periodt. 💀
-prog text— use text as the name of this program in subsequent messages 🎀-prog_help text— use text as the name of this program and perform-help. Two birds, one stone, iconic behavior.
🌈 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 xorriso commands, the same ISO 9660 filesystem bytes. The only exception are bytes which depend on the current time of the xorriso run.
These time dependent values can be set to fixed values by the commands -volume_date "uuid", -boot_image "any" "gpt_disk_guid=", -volume_date "all_file_dates", and -iso_nowtime. Instead of setting each of them, it is possible to influence them all by the environment variable SOURCE_DATE_EPOCH.
SOURCE_DATE_EPOCH belongs to the specification of reproducible-builds.org. It is supposed to be either undefined or to contain a decimal number which tells the seconds since january 1st 1970. If it contains a number, then it is used as time value to set the default of -volume date "uuid", sets -boot_image "any" "gpt_disk_guid=" to "volume_date_uuid", -volume_date "all_file_dates" to "set_to_mtime", and -iso_nowtime.
Startup files and xorriso commands can override the effect of SOURCE_DATE_EPOCH. So like, the environment variable sets the vibe, but your commands can absolutely overrule it 💅
Different versions of xorriso may or may not produce the same result from the same input and commands. Reproducibility may be prevented by bug fixes or feature enhancements between versions. (Not me being a different girl every release 😭)
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 command -preparer_id with a text other than "@xorriso@" if you want to override the default at first production time. This command 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 command -pvd_info.
If reproducibility of xorriso results is desired, then the precautions — like setting SOURCE_DATE_EPOCH — should be done already with the original xorriso run. All input files, the used xorriso commands 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. Write it down bestie, future you will be so grateful 🫶
✨ EXAMPLES ✨
🌸 Overview of examples: 🌸
- As superuser learn about available drives
- Blank medium and compose a new ISO image as batch run
- A dialog session doing about the same
- Manipulate an existing ISO image on the same medium
- Copy modified ISO image from one medium to another
- Bring a prepared ISOLINUX tree onto medium and make it bootable
- Change existing file name tree from ISO-8859-1 to UTF-8
- Operate on storage facilities other than optical drives
- Burn an existing ISO image file to medium
- Perform multi-session runs as of cdrtools traditions
- Let xorriso work underneath growisofs
- Adjust thresholds for verbosity, exit value and program abort
- Examples of input timestrings
- Incremental backup of a few directory trees
- Restore directory trees from a particular ISO session to disk
- Try to retrieve blocks from a damaged medium
👑 As superuser learn about available drives
On Linux, FreeBSD or NetBSD consider to give rw-permissions to those users or groups which shall be able to use the drives with xorriso. On Solaris use pfexec. Consider to restrict privileges of xorriso to "base,sys_devices" and to give r-permission to user or group.
$ xorriso -device_links
1 -dev '/dev/cdrom1' rwrw-- : 'TSSTcorp' 'DVD-ROM SH-D162C
1 -dev '/dev/cdrw' rwrw-- : 'TSSTcorp' 'CDDVDW SH-S223B'
2 -dev '/dev/cdrw3' rwrw-- : 'HL-DT-ST' 'BDDVDRW_GGC-H20L'🔥 Blank medium and compose a new ISO image as batch run
Acquire drive /dev/sr2, make medium ready for writing a new image, fill the image with the files from hard disk directories /home/me/sounds and /home/me/pictures.
Because no -dialog "on" is given, the program will then end by writing the session to the medium.
$ xorriso -outdev /dev/sr2 \
-blank as_needed \
-map /home/me/sounds /sounds \
-map /home/me/pictures /picturesThe ISO image may be shaped in a more elaborate way like the following: Omit some unwanted stuff by removing it from the image directory tree. Reintroduce some wanted stuff.
$ cd /home/me
$ xorriso -outdev /dev/sr2 \
-blank as_needed \
-map /home/me/sounds /sounds \
-map /home/me/pictures /pictures \
-rm_r \
/sounds/indecent \
'/pictures/*private*' \
/pictures/confidential \
-- \
-cd / \
-add pictures/confidential/work* --Note that /pictures/*private* is a pattern for iso_rr_paths while pictures/confidential/work* gets expanded by the shell with addresses from the hard disk. Commands -add and -map have different parameter rules but finally the same effect: they put files into the image. Same destination, different routes, both slay 💅
🦋 A dialog session doing about the same
Some settings are already given as start argument. The other activities are done as dialog input. The pager gets set to 20 lines of 80 characters.
The drive is acquired by command -dev rather than -outdev in order to see the message about its current content. By command -blank this content is made ready for being overwritten and the loaded ISO image is made empty.
In order to be able to eject the medium, the session needs to be committed explicitly.
$ xorriso -dialog on -page 20 80 -disk_pattern on
enter option and arguments :
-dev /dev/sr2
enter option and arguments :
-blank as_needed
enter option and arguments :
-map /home/me/sounds /sounds -map /home/me/pictures /pictures
enter option and arguments :
-rm_r /sounds/indecent /pictures/*private* /pictures/confidential
enter option and arguments :
-cdx /home/me/pictures -cd /pictures
enter option and arguments :
-add confidential/office confidential/factory
enter option and arguments :
-du /
enter option and arguments :
-commit_eject all -end🎀 Manipulate an existing ISO image on the same medium
Load image from drive. Remove (i.e. hide) directory /sounds and its subordinates. Rename directory /pictures/confidential to /pictures/restricted. Change access permissions of directory /pictures/restricted. Add new directory trees /sounds and /movies. Burn to the same medium, check whether the tree can be loaded, and eject.
$ xorriso -dev /dev/sr2 \
-rm_r /sounds -- \
-mv \
/pictures/confidential \
/pictures/restricted \
-- \
-chmod go-rwx /pictures/restricted -- \
-map /home/me/prepared_for_dvd/sounds_dummy /sounds \
-map /home/me/prepared_for_dvd/movies /movies \
-commit -eject all💜 Copy modified ISO image from one medium to another
Load image from input drive. Do the same manipulations as in the previous example. Acquire output drive and blank it. Burn the modified image as first and only session to the output drive.
$ xorriso -indev /dev/sr2 \
-rm_r /sounds -- \
...
-outdev /dev/sr0 -blank as_needed \
-commit -eject all⭐ Bring a prepared ISOLINUX tree onto medium and make it bootable
The user has already created a suitable file tree on disk and copied the ISOLINUX files into subdirectory ./boot/isolinux of that tree. Now xorriso can burn an El Torito bootable medium:
$ xorriso -outdev /dev/sr0 -blank as_needed \
-map /home/me/ISOLINUX_prepared_tree / \
-boot_image isolinux dir=/boot/isolinux🌈 Change existing file name tree from ISO-8859-1 to UTF-8
This example assumes that the existing ISO image was written with character set ISO-8859-1 but that the readers expected UTF-8. Now a new session gets added with converted file names. Command -changes_pending "yes" enables writing despite the lack of any manipulation command.
In order to avoid any weaknesses of the local character set, this command pretends that it uses already the final target set UTF-8. Therefore strange file names may appear in messages, which will be made terminal-safe by command -backslash_codes.
$ xorriso -in_charset ISO-8859-1 -local_charset UTF-8 \
-out_charset UTF-8 -backslash_codes on -dev /dev/sr0 \
-changes_pending yes -commit -eject all🗂️ Operate on storage facilities other than optical drives ✨
Bestie, your optical drive is NOT the only place xorriso can play. You can do a full read-write thing with regular files and block devices:
$ xorriso -dev /tmp/regular_file ...Paths underneath /dev normally need the prefix "stdio:":
$ xorriso -dev stdio:/dev/sdb ...If /dev/sdb is something you use constantly and /dev/sda is your system disk, then lowkey consider dropping these lines into a xorriso Startup File. They let you use /dev/sdb with no prefix at all, and they protect /dev/sda from xorriso:
-drive_class banned /dev/sda*
-drive_class harmless /dev/sdbOther writeable file types are supported write-only:
$ xorriso -outdev /tmp/named_pipe ...And among the write-only drives? Standard output, bestie.
$ xorriso -outdev - \
...
| gzip >image.iso.gz🔥 Burn an existing ISO image file to medium 🎀
Okay so actually this works with any kind of data, not just ISO images:
$ xorriso -as cdrecord -v dev=/dev/sr0 blank=as_needed image.iso💿 Perform multi-session runs as of cdrtools traditions 👑
Between both processes you can do literally any transportation or filtering you want.
The first session gets written like this:
$ xorriso -as mkisofs prepared_for_iso/tree1 | \
xorriso -as cdrecord -v dev=/dev/sr0 blank=fast -multi -eject -Follow-up sessions get written like this (the dd run is only there 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
$ xorriso -as mkisofs -M /dev/sr0 -C $m prepared_for_iso/tree2 | \
xorriso -as cdrecord -v dev=/dev/sr0 -waiti -multi -eject -Always eject the drive tray between sessions. No cap.
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. 💀
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. ✨
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.
This example works for multi-session media only. Add cdrskin option --grow_overwriteable_iso to all -as cdrecord runs in order to enable multi-session emulation on overwritable media.
🌈 Let xorriso work underneath growisofs 🦋
growisofs expects an ISO formatter program which understands options -C and -M. If xorriso gets started by name "xorrisofs" then it is suitable for that. Slay.
$ export MKISOFS="xorrisofs"
$ growisofs -Z /dev/dvd /some/files
$ growisofs -M /dev/dvd /more/filesIf 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 -- outdev - -update_r /my/files /files
$ growisofs -M /dev/dvd -- outdev - -update_r /my/files /filesgrowisofs has excellent burn capabilities with DVD and BD. It does not emulate session history on overwritable media, though.
⚙️ Adjust thresholds for verbosity, exit value and program abort 🎚️
Be quite verbose, exit 32 if severity "FAILURE" was encountered, do not abort prematurely but forcibly go on until the end of commands.
$ xorriso ... \
-report_about UPDATE \
-return_with FAILURE 32 \
-abort_on NEVER \
...⏰ Examples of input timestrings ⭐
- As printed by program
date:'Thu Nov 8 14:51:13 CET 2007' - The same without ignored parts:
'Nov 8 14:51:13 2007' - The same as expected by
date:110814512007.13 - Four weeks in the future:
+4w - The current time:
+0 - Three hours ago:
-3h - Seconds since Jan 1 1970:
=1194531416
💾 Incremental backup of a few directory trees 🌸
This changes the directory trees /projects 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.
ACL, xattr, hard links and MD5 checksums will be recorded. Accelerated comparison is enabled at the expense of potentially larger backup size. Only media with the expected volume ID or blank media are accepted. Files with names matching *.o or *.swp get excluded explicitly. When done with writing, the new session gets checked by its recorded MD5.
$ xorriso \
-abort_on FATAL \
-for_backup -disk_dev_ino on \
-assert_volid 'PROJECTS_MAIL_*' FATAL \
-dev /dev/sr0 \
-volid PROJECTS_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" \
-not_leaf '*.o' -not_leaf '*.swp' \
-update_r /home/thomas/projects /projects \
-update_r /home/thomas/personal_mail /personal_mail \
-commit -toc -check_md5 FAILURE -- -eject allTo 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. 😭
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. To apply zisofs compression to those data files which get newly copied from the local filesystem, insert these commands immediately before -commit:
-hardlinks perform_update \
-find / -type f -pending_data -exec set_filter --zisofs -- \Commands -disk_dev_ino and -for_backup depend on stable device and inode numbers on disk. Without them, an update run may use -md5 "on" to match recorded MD5 sums against the current file content on hard disk. This is usually much faster than the default which compares both contents directly.
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 command -toc. Used after -commit the following command prints the matching mount command for the newly written session (here for mount point /mnt):
-mount_cmd "indev" "auto" "auto" /mntCommands -mount_cmd and -mount are also able to produce the mount commands for older sessions in the table-of-content. E.g. as superuser:
# osirrox -mount /dev/sr0 "volid" '*2008_12_05*' /mntAbove example produces a result similar to -root / -old-root / with mkisofs. For getting the session trees accumulated in the new sessions, let all -update commands use a common parent directory and clone it after updating is done:
-update_r /home/thomas/projects /current/projects \
-update_r /home/thomas/personal_mail /current/personal_mail \
-clone /current /"$(date '+%Y_%m_%d_%H%M%S')" \The cloned tree will have a name like /2011_02_12_155700.
Sessions on multi-session media are separated by several MB of unused blocks. So with small sessions the payload capacity can become substantially lower than the overall media capacity. If the remaining space on a medium does not suffice for the next gap, the drive is supposed to close the medium automatically.
Better do not use your youngest backup for -update_r. 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.
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. 🫶
🧚 Restore directory trees from a particular ISO session to disk 🍓
This is an alternative to mounting the medium and using normal file operations.
First check which backup sessions are on the medium:
$ xorriso -outdev /dev/sr0 -tocThen enable restoring of ACL, xattr and hard links. Load the desired session and copy the file trees to disk. Avoid to create /home/thomas/restored without rwx-permission.
$ xorriso -for_backup \
-load volid 'PROJECTS_MAIL_2008_06_19*' \
-indev /dev/sr0 \
-osirrox on:auto_chmod_on \
-chmod u+rwx / -- \
-extract /projects /home/thomas/restored/projects \
-extract /personal_mail /home/thomas/restored/personal_mail \
-rollback_endThe final command -rollback_end prevents an error message about the altered image being discarded. 💅
🩹 Try to retrieve blocks from a damaged medium 💀
$ xorriso -abort_on NEVER -indev /dev/sr0 \
-check_media time_limit=1800 report=blocks_files \
data_to="$HOME"/dvd_copy sector_map="$HOME"/dvd_copy.map --This can be repeated several times, if necessary with -eject or with other -indev drives. See the human readable part of "$HOME"/dvd_copy.map for addresses which can be used on "$HOME"/dvd_copy with mount option -o sbsector= or -s.
🎀 FILES 🎀
🔗 Program alias names:
Normal installation of xorriso creates three links or copies which by their program name pre-select certain settings:
xorrisofsstarts xorriso with-as mkisofsemulation.xorrecordstarts xorriso with-as cdrecordemulation.osirroxstarts with-osirrox "on:o_excl_off"which allows further commands to copy files from ISO image to disk and to apply command-mountto one or more of the existing ISO sessions.
📜 Startup files:
If not -no_rc is given as the first argument then xorriso attempts on startup to read and execute lines from the following files:
/etc/default/xorriso
/etc/opt/xorriso/rc
/etc/xorriso/xorriso.conf
$HOME/.xorrisorcThe files are read in the sequence given above, but none of them is required to exist. The line format is described with command -options_from_file.
If mkisofs emulation was enabled by program name "xorrisofs", "mkisofs", "genisoimage", or "genisofs", then afterwards -read_mkisofsrc is performed, which reads .mkisofsrc files. See there. ✨
🛑 Runtime control files:
The default setting of -check_media abort_file= is:
/var/opt/xorriso/do_abort_check_media🌍 ENVIRONMENT 🌍
Bestie, these are the env vars that lowkey run the vibe check on how xorriso behaves:
HOME— used to find the startup files ofxorrisoandmkisofs. It's giving "where's my config at" energy. 🏠SOURCE_DATE_EPOCH— belongs to the specs of reproducible-builds.org. Peep the paragraph "Reproducibility considerations" up above for the whole tea. 🕰️
👀 SEE ALSO 👀
okay so here's the whole friend group, grouped by what they do:
For the mkisofs emulation of xorriso:
For the cdrecord emulation of xorriso:
For mounting xorriso generated ISO 9660 images (-t iso9660):
Libreadline, a comfortable input line facility:
Other programs which produce ISO 9660 images:
Other 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 🐛
Found a bug? Need help? Got a ✨genius✨ idea for an enhancement? Do not suffer in silence, bestie. 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. Basically: spill all the details, we need the receipts. 🧾
Expect to get asked more questions before solutions can be proposed. Yes, fr fr — there will be a follow-up conversation, that's just how this works. 😭
👑 AUTHOR 👑
Thomas Schmitt <scdbackup@gmx.net> for libburnia-project.org
The main character. Periodt. 💅
📜 COPYRIGHT 📜
Copyright (c) 2007 - 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.
(Read the fine print, bestie — it's short and it's fair. 🫶)
🌟 CREDITS 🌟
No one builds an icon alone, and xorriso 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. An absolute legend. 👑
Thanks to Andy Polyakov who invented emulated growing, and to Derek Foreman and Ben Jansens who once founded libburn. 🙌
Compliments towards Joerg Schilling whose cdrtools served me for ten years. A whole decade of service, that's not a phase, that's devotion. 💜
okay bestie that's the WHOLE page, start to finish, no cap 🎀
You just read the entirety of XORRISO(1) — Version 1.5.8, Apr 01, 2026 — and honestly? You ate that. Go make some ISO images, you're iconic now. ✨💖🦋🌸💅🌈⭐💀🙈🍓🧚💜🫶
📦 where this page comes from
- alpine 3.24: libisoburn-doc 1.5.8-r0 · GPL-2.0-or-later
- arch rolling: libisoburn 1.5.8.2-1 · GPL-2.0-or-later
- fedora 43: xorriso 1.5.8-2.fc43 · GPL-2.0-or-later
- fedora 44: xorriso 1.5.8-2.fc44 · GPL-2.0-or-later
- nixpkgs unstable: libisoburn 1.5.8.pl02
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms