Bug 70952

Summary:	Handbook section 16.6.2 has bad example
Product:	Documentation	Reporter:	Jon Wallace <jon>
Component:	Books & Articles	Assignee:	freebsd-doc (Nobody) <doc>
Status:	Closed FIXED
Severity:	Affects Only Me
Priority:	Normal
Version:	Latest
Hardware:	Any
OS:	Any

Description Jon Wallace 2004-08-25 20:10:22 UTC

The example provided in Handbook Section 16.6.2 contains an example that results in an error on the OS. The example is:
# mkisofs -U -R -b boot/cdboot -o /tmp/bootable.iso /tmp/myboot

Running this command however, produces the following error:
# mkisofs -U -R -b boot/cdboot -o ../test.iso .
Warning: creating filesystem that does not conform to ISO-9660.
Size of boot image is 4 sectors -> mkisofs: Error - boot image './boot/cdboot' is not the an allowable size.

The mkisofs command stops and no image is created. There appear to be two problems with the example. First, the cdboot file is not a standard floppy boot size so using the -b flag without a corresponding -no-emul-boot flag. The mkisofs(8) manpage describes this. Second, the -U flag does not appear to work with FreeBSD. Booting a CDrom created with -U produces the following boot error:
Looking up /BOOT/LOADER...file not found
and the boot procedure hangs.

Fix:

1) Create a bootable cdrom with:
mkisofs -L -D -R -b boot/cdboot -no-emul-boot -o ../test.iso .
How-To-Repeat: 1)Try to create a bootable cdrom with
# mkisofs -U -R -b boot/cdboot -o /tmp/bootable.iso /tmp/myboot
2) You should see an error:
Size of boot image is 4 sectors -> mkisofs: Error - boot image './boot/cdboot' is not the an allowable size.

1) Try to build a bootable cdrom with the command
mkisofs -U -R -b boot/cdboot -no-emul-boot -o ../test.iso .
2) Burn a cdrom with the test image
3) Boot the cdrom
4) The bootup will fail to find /boot/loader and stop

Comment 1 Sebastian Schulze Struchtrup 2004-10-11 18:17:44 UTC

doc/70952:
> There appear to be two problems with the example
> First, the cdboot file is not a standard floppy boot size so using
> the -b flag without a corresponding -no-emul-boot flag.  
> The mkisofs(8) manpage describes this.Second, the -U flag does not
> appear to work with FreeBSD.  Booting a CDrom created with -U
> produces the following boot error: 
> Looking up /BOOT/LOADER...file not found
> and the boot procedure hangs.


I discoved the same problem regarding the missing -no-emul-boot 
parameter to mkisofs.
But booting the created CDROM (with -U) works fine for me.
The boot code looks for /BOOT/LOADER and /boot/loader.

A patch to correct the documentation is attached below.
I have added the -no-emul-boot flag and added another sentence 
describing the reason for adding this.


Index: chapter.sgml
===================================================================
RCS file: /usr/home/cvs/freebsd/doc/en_US.ISO8859-1/books/handbook/disks/chapter.sgml,v
retrieving revision 1.222
diff -U2 -r1.222 chapter.sgml
--- chapter.sgml	26 Sep 2004 20:08:31 -0000	1.222
+++ chapter.sgml	8 Oct 2004 16:01:55 -0000
@@ -1032,5 +1032,9 @@
 	<quote>El Torito</quote> bootable CD. This option takes an
 	argument which is the path to a boot image from the top of the
-	tree being written to the CD. So, given that
+	tree being written to the CD. The default for mkisofs is to use
+	floopy disc emulation with an image sizes of exactly 1200, 1440 or
+	2880 KB. The FreeBSD cdrom boot loader <filename>/boot/cdboot</filename>
+	does not use any emulation. Hence, we have to add the
+	<option>-no-emul-boot</option>. So, given that 
 	<filename>/tmp/myboot</filename> holds a bootable FreeBSD system
 	with the boot image in
@@ -1039,5 +1043,5 @@
 	<filename>/tmp/bootable.iso</filename> like so:</para>
 
-      <screen>&prompt.root; <userinput>mkisofs -U -R -b boot/cdboot -o /tmp/bootable.iso /tmp/myboot</userinput></screen>
+      <screen>&prompt.root; <userinput>mkisofs -U -R -no-emul-boot -b boot/cdboot -o /tmp/bootable.iso /tmp/myboot</userinput></screen>
 
       <para>Having done that, if you have <devicename>vn</devicename>

Comment 2 Peter Pentchev freebsd_committer

2004-11-05 19:11:25 UTC

State Changed
From-To: open->closed

I committed a patch loosely based on the one provided by Sebastian. 
Thanks for the problem report!