FAQ - web - Gitea

If your operating system does not offer such a package, then consider to get the GNU xorriso source tarball. For instructions read in its README file the paragraph "Compilation, First Glimpse, Installation". With grub-mkrescue it is possible to use the resulting binary without further installation. Just submit its absolute path with option --xorriso=. E.g.:

  grub-mkrescue --xorriso=$HOME/xorriso-1.3.8/xorriso/xorriso -o output.iso

xorriso tutorial

There is not much more than the man xorriso examples

Volunteers are wanted who make a collection of use cases, ask at bug-xorriso for xorriso instructions to fulfill the needs, and describe both in a user-readable manner.

Up to then, the GUI demo xorriso-tcltk (screenshot) may serve as interactive exploration tool. It needs xorriso >= 1.2.6, Tcl, Tk >= 8.4, optionally Tcl / Tk package BWidget.

  xorriso-tcltk --script_log_file -

starts the GUI and will log the essential xorriso commands in the start terminal. I.e. click on "Scan for drives" and learn that this operation is triggered by xorriso command -devices.

Click the rightmost mouse button while being over any of the GUI elements in order to get the particular help text for that element. Have man xorriso ready to learn what the particular commands mean.

xorriso create ISO image

  xorriso -outdev $HOME/result.iso \
          -map /home/me/sounds /sounds \
          -map /home/me/pictures /pictures

This points the output to file $HOME/result.iso, which should not yet exist. Then it maps disk directory /home/me/sounds to ISO directory /sounds, and /home/me/pictures to /pictures. At program end, the ISO image gets produced and the contents of the two directory trees gets copied into the ISO.

If you have experience with program mkisofs, you may also use its emulation by xorriso:

  xorriso -as mkisofs \
          -o $HOME/result.iso \
          -graft-points \
          /sounds=/home/me/sounds \
          /pictures=/home/me/pictures

See man xorriso for xorriso native commands.

See man xorrisofs for its mkisofs emulation.

Burning

What is the difference between cdrskin and xorriso ?

cdrskin is a dedicated emulator of program cdrecord, based on libburn. It tries to be as similar to cdrecord as is possible under that premise.

xorriso is an integrated tool which creates, loads, manipulates, and writes ISO 9660 filesystem images with Rock Ridge extensions. It is based on libburn, libisofs, and libisoburn. One of its features is the emulation of the corresponding tasks as done by mkisofs and cdrecord.

What does that SCSI error message mean ?

Error messages labled as "SCSI" stem from the drive. They are codes of three hexadecimal numbers, like [3 0C 00]. The first number gives an overall classification of the problem. The other two numbers give the particular error description.

libburn translates known error codes into text messages. They consist of two statements: the overall classification and the error description.

E.g. [3 0C 00] Medium error. Write error.

The classification allows a guess where the problem cause might sit:

2 Drive not ready : This is a well normal drive state and should be handled by libburn. If you see this outside of DEBUG messages then it happened at an unexpected occasion. Either libburn did its job wrong, or the hardware suffers from blackouts. Hardware can be: drive, cable, bus controller.

Workaround: Check cables. If possible, try the drive at a different bus controller.

3 Medium error : This indicates a problem between drive and medium. libburn cannot directly cause such an error by any mistake. If drive and medium are balancing on the edge of defect, it is possible that optional settings can cause or prevent such errors. But in many cases of drive-medium conflicts it is mere incident whether a burn run succeeds or not.

Workaround: Try other media or another drive.

4 Drive error : The drive or the bus controller accuse themselves of doing it wrong. As with "Medium error" this might be aggravated or eased by optional settings.

Workaround: Check cables. If possible, try the drive at a different bus controller.

5 Illegal request : The drive did not like a command sent by libburn. This may be normal. But if you see this outside of DEBUG messages, then either the drive does not comply to MMC or libburn does not do its job right.

Workaround: Submit an error report to GNU xorriso mailing list.

B Command aborted : Seems to be generated by some bus controllers or operating system SCSI drivers. The newest outbreak is said to be due to USB 3 and drivers which do not prevent power saving.

Workaround: Plug USB drives to USB 2 sockets or have a recent operating system kernel. If this does not help, contact [https://lists.gnu.org/mailman/listinfo/bug-xorriso GNU xorriso mailing list] and be ready for experiments.

Why is simultaneous burning with multiple drives so slow ?

It is a known regression of Linux since about 2010 that operating more than one drive at the same time via SCSI commands shows severe throughput problems. See the wiki page about this problem which offers two alternative workarounds in userspace, explanantions of the reason, and a link to a remedy proposal by courageous kernel modification.

Imaging

Is there a way to edit files inside the ISO image ?

File content cannot be altered. But files may be replaced by new copies from the disk filesystem.

The main method of manipulating an existing ISO image is to append a session with a new complete directory tree and the file content of the added or overwritten files. Depending on the media type you get gaps between sessions of up to 20 MB. So better try to do all foreseeable changes by one add-on session.

For which architectures xorriso is able to create bootable images ?

Currently it supports systems with PC-BIOS for booting from CD, DVD, or BD media, and from memory sticks or hard disks. The same feature range is supported for systems with EFI firmware with x86 or ARM processor.

Further it supports machines with MIPS processor from SGI (Big Endian) and DEC (Little Endian), and SUN SPARC machines. (See libisofs/doc/boot_sectors.txt for technical details.)

Examples how to get an impression of the boot equipment of existing ISO 9660 images are on the wiki page about xorriso commands -report_system_area and -report_el_torito.

How to enable booting from USB stick ?

In most cases, ISOs are prepared for PC-BIOS to boot the ISOLINUX boot loader. This boot loader is normally started from CD, DVD or BD media via an El Torito boot record. But if the ISO image resides on an USB stick or another hard-disk-like device, then PC-BIOS ignores El Torito and rather expects a Master Boot Record (MBR). Both boot record types can reside in the same ISO image. Therefore it is possible to create an MBR that starts the boot image file of ISOLINUX which is already target of the El Torito boot record. This kind of MBR is called isohybrid. ISOLINUX provides a program named isohybrid to patch existing images, but libisofs can create an MBR already when producing the ISO image. See in manual page of xorriso option -boot_image with arguments isolinux system_area=, and -as mkisofs option -isohybrid-mbr.

See Wikipedia on MBR for general information about PC-DOS Master Boot Records, and ISOLINUX wiki for special information about ISOLINUX. The wiki example with mkisofs can be performed as well by help of xorriso option -as mkisofs.

A similar combination of El Torito and MBR is created by GRUB2 tool grub-mkrescue. See homepage of GNU GRUB 2 for general information.

EFI firmware in its native mode boots by El Torito from CD, DVD or BD media, and by partition table from USB stick or hard disk. Both, El Torito and partition table, point to a FAT filesystem image, the EFI System Partition. The partiton table may be either a DOS-style MBR partition table or a GUID Partition Table. The x86 program program in the MBR is ignored by EFI, which rather starts a program from the FAT directory "\EFI\BOOT". The name of the program file depends on the processor architecture: BOOTX64.EFI, BOOTIA32.EFI, BOOTARM.EFI, BOOTAA64.EFI for x86 64 bit, x86 32 bit, ARM 32 bit, and ARM 64 bit, respectively.

The boot equipment for other systems may well work from USB stick too. But libburnia project has no tangible information about this.

What is partition offset feature all about?

If an MBR is present, then it contains a partition table with up to four entries. The MBR is located at the very start of the ISO image. By tradition the first partition should begin only after the range of MBR and eventual supporting data blocks. On hard disk one often sees partition 1 starting at byte 63*512. Further it is tradition that the payload filesystem is mountable via one of the partitions.

The isohybrid MBR has its only partition start at byte 0. Thus it is mountable but does not obey the tradition to begin only after the MBR. The grub-mkrescue MBR on the other hand has partition 1 start at byte 512,i which makes it unmountable. Only the unpartitioned base device can be mounted. (On GNU/Linux e.g. /dev/sdb is the base device whereas /dev/sdb1 is its partition 1.)

The compromise offered by libisofs is to create a second superblock at address 16*2048 and to let start partition 1 at this address. The second superblock leads to a second directory tree which takes into account the address difference between partition 1 and the base device. So the image gets mountable via both devices and reserves 32 kB for boot manager software where it may manipulate and augment the MBR. (See Partition Offset Wiki for examples.)

There are reports of machines which will not boot from USB stick if partition offset is 0.

Partition offset bad on Apple ?

Apple's "Snow Leopard" operating system refuses to mount Debian CD images with non-zero partition offset.

The issue is not yet fully understood. For now one has to choose between mountability on Apple "Snow Leopard" or bootability from USB stick on Kontron CG2100 "carrier grade server".

Developing

Where are the APIs of libburnia libraries described ?

The decisive references are the inclusion headers of the libraries <libburn/libburn.h>, <libisofs/libisofs.h>, <libisoburn/libisoburn.h>, and <libisoburn/xorriso.h>.

Current git versions of these files: libburn/libburn.h , libisofs/libisofs.h , libisoburn/libisoburn.h , libisoburn/xorriso.h

I want to write a GUI on the top of libburnia libraries. Any pointers or recommendations ?

Most appreciated would be a GUI for xorriso which allows to copy files from a view of the hard disk filesystem to a view of the ISO filesystem, and vice versa. The xorriso implementation is located inside libisoburn.

Each option that is described in man 1 xorriso can be performed by a corresponding C function that is defined in xorriso.h

Further there are calls for library startup and shutdown, for problem handling, and for the interpreters of xorriso's command line interface. The xorriso API encapsulates calls to libisofs, libburn, and libisoburn.

An alternative to the xorriso C API is xorriso dialog mode. See below. The script xorriso-tcltk demonstrates this approach. It is part of the libisoburn release tarball and of the GNU xorriso tarball.

The known existing GUIs Xfburn, Brasero, FlBurn rather use libisofs and libburn directly. (Please submit an URI if you want your libburnia GUI application mentioned here.)

Miscellaneous

Where to see examples ?

xorriso examples , cdrskin examples , libburner.c a minimal but complete burn program.

What personalities are supported by xorriso ?

The name by which xorriso is started may trigger certain features which normally would need to be enabled by program options.

xorrisofs starts up in mkisofs emulation mode, which otherwise would have to be entered by command -as mkisofs.

xorrecord starts up in cdrecord emulation mode, which is normally entered by command -as cdrecord. This emulation is only able to write a single data track as new session to blank or appendable media. No audio. No multiple tracks in one session.

osirrox can copy files from ISO image to disk and to apply option -mount to one or more of the existing ISO sessions. This is normally enabled by option -osirrox on:o_excl_off.

What is xorriso dialog mode useful for ?

Dialog mode is initiated if -dialog on is among the program arguments. It can be used to inspect and exploit existing ISO 9660 images or to explore xorriso's behavior in order to develop the command sequence for a batch run.

Frontend programmers may fork xorriso initiating a xorriso dialog session (-dialog on -use_readline off -pkt_output on -mark done), and interact with it from their own program via pipes connected to xorriso's stdin and stdout. This is more efficient than forking xorriso every now and then to perform various commands in order to complete complex tasks like image size prediction.

The script xorriso-tcltk demonstrates this approach. It is part of the libisoburn release tarball and of the GNU xorriso tarball.

Why is every second release missing ?

Releases have an even third version number. Like 0.5.6 or 1.0.4. During development the next higher odd number is used. E.g. 0.5.7 or 1.0.5.

The content of release tarballs does not get changed without changing their name. The development tarballs of xorriso and cdrskin may change their content without notice.

Site maintainer: Do not edit this wiki directly but rather the git version of libisoburn/doc/faq.wiki. When done, paste it into the wiki editor.