You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
424 lines
18 KiB
424 lines
18 KiB
|
|
### Libburnia Frequently Asked Questions |
|
|
|
Please post your questions to |
|
[GNU xorriso mailing list](https://lists.gnu.org/mailman/listinfo/bug-xorriso). |
|
|
|
---------------------------------------------------------------------------- |
|
### Content: |
|
|
|
Google favorites: |
|
|
|
[xorriso not found](FAQ#xorriso_not_found) |
|
|
|
[xorriso tutorial](FAQ#xorriso_tutorial) |
|
|
|
[xorriso create ISO image](FAQ#xorriso_create_iso) |
|
|
|
Burning: |
|
|
|
[What is the difference between cdrskin and xorriso ?](FAQ#diff_cdrskin_xorriso) |
|
|
|
[What does that SCSI error message mean ?](FAQ#scsi_error) |
|
|
|
[Why is simultaneous burning with multiple drives so slow ?](FAQ#concurrent_burn) |
|
|
|
Imaging: |
|
|
|
[Is there a way to edit files inside the ISO image ?](FAQ#edit_files) |
|
|
|
[For which architectures xorriso is able to create bootable images ?](FAQ#boot_arch) |
|
|
|
[How to enable booting from USB stick ?](FAQ#isohybrid) |
|
|
|
[What is partition offset feature all about?](FAQ#partition_offset) |
|
|
|
[Partition offset bad on Apple ?](FAQ#partition_offset_apple) |
|
|
|
Development: |
|
|
|
[Where are the APIs of libburnia libraries described ?](FAQ#api_specs) |
|
|
|
[I want to write a GUI on the top of libburnia libraries. Any pointers or recommendations ?](FAQ#gui_advise) |
|
|
|
Miscellaneous: |
|
|
|
[Where to see examples ?](FAQ#example_links) |
|
|
|
[What personalities are supported by xorriso ?](FAQ#xorriso_aliases) |
|
|
|
[What is xorriso dialog mode useful for ?](FAQ#xorriso_dialog_mode) |
|
|
|
[Why is every second release missing ?](FAQ#version_numbers) |
|
|
|
|
|
------------------------------------------------------------------------ |
|
### Google favorites |
|
------------------------------------------------------------------------ |
|
|
|
##### xorriso not found <A NAME="xorriso_not_found"> |
|
|
|
This message is issued by programs which use [xorriso](Xorriso) for |
|
producing ISO 9660 filesystem images. E.g. by GRUB2's grub-mkrescue. |
|
|
|
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](http://www.gnu.org/software/xorriso#download) |
|
source tarball. For instructions read in its |
|
[README file](http://www.gnu.org/software/xorriso/README_xorriso) |
|
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 <A NAME="xorriso_tutorial"> |
|
|
|
There is not much more than the |
|
[man xorriso examples](http://www.gnu.org/software/xorriso/man_1_xorriso.html#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](https://dev.lovelyhq.com/libburnia/libisoburn/raw/branch/master/frontend/README-tcltk) |
|
[(screenshot)](http://www.gnu.org/software/xorriso/xorriso-tcltk-screen.gif) |
|
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](http://www.gnu.org/software/xorriso/man_1_xorriso.html) |
|
ready to learn what the particular commands mean. |
|
|
|
|
|
##### xorriso create ISO image <A NAME="xorriso_create_iso"> |
|
|
|
``` |
|
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](http://www.gnu.org/software/xorriso/man_1_xorriso.html) |
|
for xorriso native commands. |
|
|
|
See [man xorrisofs](http://www.gnu.org/software/xorriso/man_1_xorrisofs.html) |
|
for its mkisofs emulation. |
|
|
|
|
|
|
|
---------------------------------------------------------------------------- |
|
### Burning |
|
---------------------------------------------------------------------------- |
|
|
|
##### What is the difference between cdrskin and xorriso ? <A NAME="diff_cdrskin_xorriso"> |
|
|
|
[cdrskin](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](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 ? <A NAME="scsi_error"> |
|
|
|
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](https://lists.gnu.org/mailman/listinfo/bug-xorriso). |
|
|
|
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 ? <A NAME="concurrent_burn"> |
|
|
|
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](ConcurrentLinuxSr) 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 ? <A NAME="edit_files"> |
|
|
|
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 ? <A NAME="boot_arch"> |
|
|
|
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](https://dev.lovelyhq.com/libburnia/libisofs/raw/branch/master/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](ReportSystemArea). |
|
|
|
##### How to enable booting from USB stick ? <A NAME="isohybrid"> |
|
|
|
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](http://www.gnu.org/software/xorriso/man_1_xorriso.html) |
|
option `-boot_image` with arguments `isolinux system_area=`, |
|
and `-as mkisofs` option `-isohybrid-mbr`. |
|
|
|
See [Wikipedia on MBR](http://en.wikipedia.org/wiki/Master_boot_record) for |
|
general information about PC-DOS Master Boot Records, and |
|
[ISOLINUX wiki](http://syslinux.zytor.com/wiki/index.php/ISOLINUX) 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](http://www.gnu.org/software/grub/) |
|
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](https://en.wikipedia.org/wiki/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? <A NAME="partition_offset"> |
|
|
|
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](PartitionOffset) |
|
for examples.) |
|
|
|
There are reports of machines which will not boot from USB stick if |
|
partition offset is 0. |
|
|
|
##### Partition offset bad on Apple ? <A NAME="partition_offset_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 ? <A NAME="api_specs"> |
|
|
|
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](https://dev.lovelyhq.com/libburnia/libburn/raw/branch/master/libburn/libburn.h) , |
|
[libisofs/libisofs.h](https://dev.lovelyhq.com/libburnia/libisofs/raw/branch/master/libisofs/libisofs.h) , |
|
[libisoburn/libisoburn.h](https://dev.lovelyhq.com/libburnia/libisoburn/raw/branch/master/libisoburn/libisoburn.h) , |
|
[libisoburn/xorriso.h](https://dev.lovelyhq.com/libburnia/libisoburn/raw/branch/master/xorriso/xorriso.h) |
|
|
|
##### I want to write a GUI on the top of libburnia libraries. Any pointers or recommendations ? <A NAME="gui_advise"> |
|
|
|
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](http://www.gnu.org/software/xorriso/man_1_xorriso.html) |
|
can be performed by a corresponding C function that is defined in |
|
[xorriso.h](https://dev.lovelyhq.com/libburnia/libisoburn/raw/branch/master/xorriso/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](FAQ#xorriso_dialog_mode). |
|
The script |
|
[xorriso-tcltk](https://dev.lovelyhq.com/libburnia/libisoburn/raw/branch/master/frontend/xorriso-tcltk) |
|
demonstrates this approach. It is part of the |
|
libisoburn release tarball and of the GNU xorriso tarball. |
|
|
|
The known existing GUIs |
|
[Xfburn](http://goodies.xfce.org/projects/applications/xfburn), |
|
[Brasero](http://projects.gnome.org/brasero/), |
|
[FlBurn](http://flburn.sourceforge.net/) |
|
rather use libisofs and libburn directly. |
|
(Please submit an URI if you want your libburnia GUI application mentioned |
|
here.) |
|
|
|
---------------------------------------------------------------------------- |
|
### Miscellaneous |
|
---------------------------------------------------------------------------- |
|
|
|
##### Where to see examples ? <A NAME="example_links"> |
|
|
|
[xorriso examples](http://www.gnu.org/software/xorriso/man_1_xorriso.html#EXAMPLES) , |
|
[cdrskin examples](http://scdbackup.sourceforge.net/man_1_cdrskin_devel.html#EXAMPLES) , |
|
[libburner.c a minimal but complete burn program](https://dev.lovelyhq.com/libburnia/libburn/raw/branch/master/test/libburner.c). |
|
|
|
|
|
##### What personalities are supported by xorriso ? <A NAME="xorriso_aliases"> |
|
|
|
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 ? <A NAME="xorriso_dialog_mode"> |
|
|
|
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](https://dev.lovelyhq.com/libburnia/libisoburn/raw/branch/master/frontend/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 ? <A NAME="version_numbers"> |
|
|
|
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. |
|
|
|
|