Libburnia Frequently Asked Questions
Please post your questions to GNU xorriso mailing list.
Executable xorriso binaries are normally contained in software packages named "libisoburn" or "xorriso".
If your operating system does not offer such a package, then consider
to get the GNU xorriso
source tarball. For instructions read in its
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
grub-mkrescue --xorriso=$HOME/xorriso-1.3.8/xorriso/xorriso -o output.iso
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.
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
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 -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
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 xorrisofs for its mkisofs emulation.
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.
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
libburn translates known error codes into text messages. They consist of two statements: the overall classification and the error description.
[3 0C 00] Medium error. Write error.
The classification allows a guess where the problem cause might sit:
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.
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.
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
Workaround: Check cables. If possible, try the drive at a different bus controller.
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.
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.
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.
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.
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.
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.
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
-boot_image with arguments
-as mkisofs option
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.
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.
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.
/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
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
There are reports of machines which will not boot from USB stick if partition offset is 0.
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".
The decisive references are the inclusion headers of the libraries
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.
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 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
xorrecord starts up in cdrecord emulation mode, which is normally entered by
-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
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.
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
libisoburn/doc/faq.wiki. When done, paste it into the wiki editor.