mkinitrd-magellan/isolinux/isolinux.txt

                               ISOLINUX

       A bootloader for Linux using ISO 9660/El Torito CD-ROMs

       Copyright 1994-2008 H. Peter Anvin - All Rights Reserved

This program is provided under the terms of the GNU General Public
License, version 2 or, at your option, any later version.  There is no
warranty, neither expressed nor implied, to the function of this
program.  Please see the included file COPYING for details.

----------------------------------------------------------------------

ISOLINUX is a boot loader for Linux/i386 that operates off ISO 9660/El
Torito CD-ROMs in "no emulation" mode.  This avoids the need to create
an "emulation disk image" with limited space (for "floppy emulation")
or compatibility problems (for "hard disk emulation".)

This documentation isn't here yet, but here is enough that you should
be able to test it out:

Make sure you have a recent enough version of mkisofs.  I recommend
mkisofs 1.13 (distributed with cdrecord 1.9), but 1.12 might work as
well (not tested.)

To create an image, create a directory called "isolinux" (or, if you
prefer, "boot/isolinux") underneath the root directory of your ISO
image master file tree.  Copy isolinux.bin, a config file called
"isolinux.cfg" (see syslinux.txt for details on the configuration
file), and all necessary files (kernels, initrd, display files, etc.)
into this directory, then use the following command to create your ISO
image (add additional options as appropriate, such as -J or -R):

	mkisofs -o <isoimage> \
		-b isolinux/isolinux.bin -c isolinux/boot.cat \
		-no-emul-boot -boot-load-size 4 -boot-info-table \
		<root-of-iso-tree>

(If you named the directory boot/isolinux that should of course be
-b boot/isolinux/isolinux.bin -c boot/isolinux/boot.cat.)

ISOLINUX resolves pathnames the following way:

- A pathname consists of names separated by slashes, Unix-style.
- A leading / means it searches from the root directory; otherwise the
  search is from the isolinux directory (think of this as the "current
  directory".)
- . and .. in pathname searches are not supported.
- The maximum length of any pathname is 255 characters.

Note that ISOLINUX only uses the "plain" ISO 9660 filenames, i.e. it
does not support Rock Ridge or Joliet filenames.  It can still be used
on a disk which uses Rock Ridge and/or Joliet extensions, of course.
Under Linux, you can verify the plain filenames by mounting with the
"-o norock,nojoliet" option to the mount command.  Note, however, that
ISOLINUX does support "long" (level 2) ISO 9660 plain filenames, so if
compatibility with short-names-only operating systems like MS-DOS is
not an issue, you can use the "-l" or "-iso-level 2" option to mkisofs
to generate long (up to 31 characters) plain filenames.

ISOLINUX does not support discontiguous files, interleaved mode, or
logical block and sector sizes other than 2048.  This should normally
not be a problem.

ISOLINUX is by default built in two versions, one version with extra
debugging messages enabled.  If you are having problems with ISOLINUX,
I would greatly appreciate if you could try out the debugging version
(isolinux-debug.bin) and let me know what it reports.  The debugging
version does not include hybrid mode support (see below.)


      ++++ NOTE ON THE CONFIG FILE DIRECTORY ++++

ISOLINUX will search for the config file directory in the order
/boot/isolinux, /isolinux, /.  The first directory that exists is
used, even if it contains no files.  Therefore, please make sure that
these directories don't exist if you don't want ISOLINUX to use them.


      ++++ HYBRID CD-ROM/HARD DISK MODE ++++

Starting in version 3.72, ISOLINUX supports a "hybrid mode" which can
be booted from either CD-ROM or from a device which BIOS considers a
hard disk or ZIP disk, e.g. a USB key or similar.

To enable this mode, the .iso image should be postprocessed with the
"isohybrid" script from the utils directory:

	isohybrid filename.iso

This script creates the necessary additional information to be able to
boot in hybrid mode.  It also pads out the image to an even multiple
of 1 MB.

This image can then be copied using any raw disk writing tool (on Unix
systems, typically "dd" or "cat") to a USB disk, or written to a
CD-ROM using standard CD burning tools.

The ISO 9660 filesystem is encapsulated in a partition (which starts
at offset zero, which may confuse some systems.)  This makes it
possible for the operating system, once booted, to use the remainder
of the device for persistent storage by creating a second partition.


      ++++ BOOTING DOS (OR OTHER SIMILAR OPERATING SYSTEMS) ++++

WARNING: This feature depends on BIOS functionality which is
apparently broken in a very large number of BIOSes.  Therefore, this
may not work on any particular system.  No workaround is possible; if
you find that it doesn't work please complain to your vendor and
indicate that "BIOS INT 13h AX=4C00h fails."

To boot DOS, or other real-mode operating systems (protected-mode
operating systems may or may not work correctly), using ISOLINUX, you
need to prepare a disk image (usually a floppy image, but a hard disk
image can be used on *most* systems) with the relevant operating
system.  This file should be included on the CD-ROM in the /isolinux
directory, and have a .img extension.  The ".img" extension does not
have to be specified on the command line, but has to be explicitly
specified if used in a "kernel" statement in isolinux.cfg.

For a floppy image, the size of the image should be exactly one of the
following:

	1,228,800 bytes		- For a 1200K floppy image
	1,474,560 bytes		- For a 1440K floppy image
	2,949,120 bytes		- For a 2880K floppy image

Any other size is assumed to be a hard disk image.  In order to work
on as many systems as possible, a hard disk image should have exactly
one partition, marked active, that covers the entire size of the disk
image file.  Even so, hard disk images are not supported on all
BIOSes.
1	niro	1133	ISOLINUX
2
3			A bootloader for Linux using ISO 9660/El Torito CD-ROMs
4
5			Copyright 1994-2008 H. Peter Anvin - All Rights Reserved
6
7			This program is provided under the terms of the GNU General Public
8			License, version 2 or, at your option, any later version. There is no
9			warranty, neither expressed nor implied, to the function of this
10			program. Please see the included file COPYING for details.
11
12			----------------------------------------------------------------------
13
14			ISOLINUX is a boot loader for Linux/i386 that operates off ISO 9660/El
15			Torito CD-ROMs in "no emulation" mode. This avoids the need to create
16			an "emulation disk image" with limited space (for "floppy emulation")
17			or compatibility problems (for "hard disk emulation".)
18
19			This documentation isn't here yet, but here is enough that you should
20			be able to test it out:
21
22			Make sure you have a recent enough version of mkisofs. I recommend
23			mkisofs 1.13 (distributed with cdrecord 1.9), but 1.12 might work as
24			well (not tested.)
25
26			To create an image, create a directory called "isolinux" (or, if you
27			prefer, "boot/isolinux") underneath the root directory of your ISO
28			image master file tree. Copy isolinux.bin, a config file called
29			"isolinux.cfg" (see syslinux.txt for details on the configuration
30			file), and all necessary files (kernels, initrd, display files, etc.)
31			into this directory, then use the following command to create your ISO
32			image (add additional options as appropriate, such as -J or -R):
33
34			mkisofs -o <isoimage> \
35			-b isolinux/isolinux.bin -c isolinux/boot.cat \
36			-no-emul-boot -boot-load-size 4 -boot-info-table \
37			<root-of-iso-tree>
38
39			(If you named the directory boot/isolinux that should of course be
40			-b boot/isolinux/isolinux.bin -c boot/isolinux/boot.cat.)
41
42			ISOLINUX resolves pathnames the following way:
43
44			- A pathname consists of names separated by slashes, Unix-style.
45			- A leading / means it searches from the root directory; otherwise the
46			search is from the isolinux directory (think of this as the "current
47			directory".)
48			- . and .. in pathname searches are not supported.
49			- The maximum length of any pathname is 255 characters.
50
51			Note that ISOLINUX only uses the "plain" ISO 9660 filenames, i.e. it
52			does not support Rock Ridge or Joliet filenames. It can still be used
53			on a disk which uses Rock Ridge and/or Joliet extensions, of course.
54			Under Linux, you can verify the plain filenames by mounting with the
55			"-o norock,nojoliet" option to the mount command. Note, however, that
56			ISOLINUX does support "long" (level 2) ISO 9660 plain filenames, so if
57			compatibility with short-names-only operating systems like MS-DOS is
58			not an issue, you can use the "-l" or "-iso-level 2" option to mkisofs
59			to generate long (up to 31 characters) plain filenames.
60
61			ISOLINUX does not support discontiguous files, interleaved mode, or
62			logical block and sector sizes other than 2048. This should normally
63			not be a problem.
64
65			ISOLINUX is by default built in two versions, one version with extra
66			debugging messages enabled. If you are having problems with ISOLINUX,
67			I would greatly appreciate if you could try out the debugging version
68			(isolinux-debug.bin) and let me know what it reports. The debugging
69			version does not include hybrid mode support (see below.)
70
71
72			++++ NOTE ON THE CONFIG FILE DIRECTORY ++++
73
74			ISOLINUX will search for the config file directory in the order
75			/boot/isolinux, /isolinux, /. The first directory that exists is
76			used, even if it contains no files. Therefore, please make sure that
77			these directories don't exist if you don't want ISOLINUX to use them.
78
79
80			++++ HYBRID CD-ROM/HARD DISK MODE ++++
81
82			Starting in version 3.72, ISOLINUX supports a "hybrid mode" which can
83			be booted from either CD-ROM or from a device which BIOS considers a
84			hard disk or ZIP disk, e.g. a USB key or similar.
85
86			To enable this mode, the .iso image should be postprocessed with the
87			"isohybrid" script from the utils directory:
88
89			isohybrid filename.iso
90
91			This script creates the necessary additional information to be able to
92			boot in hybrid mode. It also pads out the image to an even multiple
93			of 1 MB.
94
95			This image can then be copied using any raw disk writing tool (on Unix
96			systems, typically "dd" or "cat") to a USB disk, or written to a
97			CD-ROM using standard CD burning tools.
98
99			The ISO 9660 filesystem is encapsulated in a partition (which starts
100			at offset zero, which may confuse some systems.) This makes it
101			possible for the operating system, once booted, to use the remainder
102			of the device for persistent storage by creating a second partition.
103
104
105			++++ BOOTING DOS (OR OTHER SIMILAR OPERATING SYSTEMS) ++++
106
107			WARNING: This feature depends on BIOS functionality which is
108			apparently broken in a very large number of BIOSes. Therefore, this
109			may not work on any particular system. No workaround is possible; if
110			you find that it doesn't work please complain to your vendor and
111			indicate that "BIOS INT 13h AX=4C00h fails."
112
113			To boot DOS, or other real-mode operating systems (protected-mode
114			operating systems may or may not work correctly), using ISOLINUX, you
115			need to prepare a disk image (usually a floppy image, but a hard disk
116			image can be used on most systems) with the relevant operating
117			system. This file should be included on the CD-ROM in the /isolinux
118			directory, and have a .img extension. The ".img" extension does not
119			have to be specified on the command line, but has to be explicitly
120			specified if used in a "kernel" statement in isolinux.cfg.
121
122			For a floppy image, the size of the image should be exactly one of the
123			following:
124
125			1,228,800 bytes - For a 1200K floppy image
126			1,474,560 bytes - For a 1440K floppy image
127			2,949,120 bytes - For a 2880K floppy image
128
129			Any other size is assumed to be a hard disk image. In order to work
130			on as many systems as possible, a hard disk image should have exactly
131			one partition, marked active, that covers the entire size of the disk
132			image file. Even so, hard disk images are not supported on all
133			BIOSes.