Bug 25890

No single document describes how to create a CD on FreeBSD.

Fix: 

I wrote up a handbook chapter covering this. I'm not sure where it
should go, though.

<!--
     The FreeBSD Documentation Project
-->

<chapter id="creating-cds">
  <title>Creating CDs</title>

  <para><emphasis>Written by mwm@mired.org</emphasis></para>

  <sect1>
    <title>Introduction</title>

    <para>When CDs have a number of features that differentiate them
    from convential disks. Initially, they weren't writable by the
    user. They are designed so they can be read continuously without
    delays to move the head between tracks. They are also much easier
    to transport between system than similar sized media was at the
    time.</para>
    
    <para>CDs do have tracks, but by this they mean a section of data
    to be read continuously, not a physical property of the disk. To
    produce a CD on FreeBSD, you prepare the data files that are going
    to make up the tracks on the CD, then write the tracks to the CD.</para>
    
    <para>The ISO 9660 file system was designed to deal with these
    differences. It unfortunately codifies file system limits that
    were common then. Fortunately, it provides an extension mechanism
    that allows properly written CDs to exceed those limits while
    still working with systems that do not support those extensions.</para>

    <para>The <command><link
    linkend="mkisofs">mkisofs</link></command> program is used to
    produce a data file containing an ISO 9660 file system. It has
    options that support various extensions, and is described
    below. You can install it with the <filename>
    /usr/ports/sysutils/mkisofs</filename> port.</para>
    
    <para>The tool to use to burn the CD depend on whether your CD
    burner is ATAPI or something else. ATAPI CD burners use the
    <command><link linkend="burncd">burncd</link></command> program
    that is part of the base system. SCSI and USB CD burners should
    use the <command><link
    linkend="cdrecord">cdrecord</link></command> from the <filename>
    /usr/ports/sysutils/cdrecord</filename> port.</para>

  </sect1>
  
  <sect1 id="mkisofs">
    <title>mkisofs</title>

    <para><command>mkisofs</command> produces an ISO 9660 file system
    that is an image of a directory tree in the Unix file system name
    space. The simplest usage is:</para>
    
    <screen>&prompt.root; <userinput>mkisofs <option>-o</option> <replaceable>imagefile.iso</replaceable> <replaceable>/path/to/tree</replaceable></userinput></screen>

    <para>This command will create a
    <replaceable>imagefile</replaceable> containing an ISO 9660 file
    system that is a copy of the tree at
    <replaceable>/path/to/tree</replaceable>. In the process, it will
    map the file names to names that fit the limitations of the
    standard ISO 9660 file system, and will exclude files that have
    names uncharacteristic of ISO file systems. Read &man.mkisofs.8;
    for details of this process, and options that can be used to
    control it.</para>
    
    <para>A number of options are available to overcome those
    restrictions. In particular, <option>-R</option> will enable the
    Rock Ridge extensions common to Unix systems, <option>-J</option>
    causes Joliet extenions used by MicroSoft systems, and
    <option>-hfs</option> can be used to create HFS file systems used
    by Macs. Read &mak.mkisofs.8; for more information on the last
    two.</para>
    
    <para>For CD's that are going to be used only on FreeBSD systems,
    <option>-U</option> can be used to disable all filename
    restrictions. When used with <option>-R</option>, it produced a
    file system image that is identical to the FreeBSD tree you
    started from, though it may violate the ISO 9660 standard in a
    number of ways.</para>
    
    <para>The last option of general use is <option>-b</option>. This
    is used to specify the location of the boot image in producing a
    <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
    <filename>/tmp/myboot</filename> holds a bootable FreeBSD system
    with the boot image in
    <filename>/tmp/myboot/boot/cdboot</filename>, you could produce
    the image of an ISO 9660 file system in
    <filename>/tmp/bootable.iso</filename> like so:</para>
    
    <screen>&prompt.root; <userinput>mkisofs <option>-U</option> <option>-R</option> <option>-b</option> <filename>boot/cdboot</filename> <option>-o</option> <filename>/tmp/bootable.iso</filename> <filename>/tmp/myboot</filename></userinput></screen>

      <para>Having done that, if you have vn configured in your
      kernel, you can mount the file system by doing:</para>

      <screen>&prompt.root; <userinput>vnconfig <option>-e</option> <filename>vn0c</filename> <filename>/tmp/bootable.iso</filename></userinput>
&prompt.root; <userinput>mount <option>-t</option> cd9660 <filename>/dev/vn0c</filename> <filename>/mnt</filename></userinput></screen>

      <para>At which point you can verify that
      <filename>/mnt</filename> and <filename>/tmp/myboot</filename>
      are identical.</para>

      <para>There are a large number of other options you can use with
      <command>mkisofs</command> to fine tune its behavior. See
      &man.mkisofs.8; for details.</para>

   </sect1>

   <sect1 id="burncd">
   <title>burncd</title>

      <para>If you have an ATAPI CD burner, you can use the
      <command>burncd</command> command to burn an ISO image onto a
      CD. <command>burncd</command> is part of the base system,
      installed as <filename>/usr/sbin/burncd</filename>.  Usage is
      very simple, as it does not have a lot of options:</para>
      
      <screen>&prompt.root; <userinput>burncd <option>-f</option> <replaceable>cddevice</replaceable> data <replaceable>imagefile.iso</replaceable> fixate</userinput></screen>

      <para>Will burn a copy of <replaceable>imagefile.iso</replaceable> on
      <replaceable>cddevice</replaceable>. The default device is
      <filename>/dev/acd0</filename>. See &man.burncd.8; for options
      like setting the write speed, ejecting the floppy, and writing
      audio data.</para>
      </sect1>

    <sect1 id="cdrecord">
    <title>cdrecord</title>

      <para>If you do not have an ATAPI CD burner, you will have to
      use <command>cdrecord</command> to burn your
      CDs. <command>cdrecord</command> is not part of the base system; you must
      install it from either the port at <filename>
      /usr/ports/sysutils/cdrecord</filename> or the appropriate
      package. Changes to the base system can cause binary versions of
      this program to fail, possibly resulting in a
      <quote>coaster</quote>. You should therefore either upgrade the
      port when you upgrade your system, or if you are <link
      linkend="stable">tracking -stable,</link> upgrade the port when
      a new version becomes available.</para>
      
      <para>While <command>cdrecord</command> has many options, basic
      usage is even simpler than <command>burncd</command>. Burning an
      ISO 9660 image is done by:</para>
      
      <screen>&prompt.root; <userinput>cdrecord <option>dev=</option><replaceable>device</replaceable> <replaceable>imagefile.iso</replaceable></userinput></screen>
      
      <para>The tricky part of using <command>cdrecord</command> is
      finding the <option>dev</option> to use. To find the proper
      setting, use the <option>-scanbus</option> flag of
      <command>cdrecord</command>, which might produce results like
      this:</para>
      
      <screen>&prompt.root; <userinput>cdrecord <option>-scanbus</option></userinput>
Cdrecord 1.9 (i386-unknown-freebsd4.2) Copyright (C) 1995-2000 Jörg Schilling
Using libscg version 'schily-0.1'
scsibus0:
        0,0,0     0) 'SEAGATE ' 'ST39236LW       ' '0004' Disk
        0,1,0     1) 'SEAGATE ' 'ST39173W        ' '5958' Disk
        0,2,0     2) *
        0,3,0     3) 'iomega  ' 'jaz 1GB         ' 'J.86' Removable Disk
        0,4,0     4) 'NEC     ' 'CD-ROM DRIVE:466' '1.26' Removable CD-ROM
        0,5,0     5) *
        0,6,0     6) *
        0,7,0     7) *
scsibus1:
        1,0,0   100) *
        1,1,0   101) *
        1,2,0   102) *
        1,3,0   103) *
        1,4,0   104) *
        1,5,0   105) 'YAMAHA  ' 'CRW4260         ' '1.0q' Removable CD-ROM
        1,6,0   106) 'ARTEC   ' 'AM12S           ' '1.06' Scanner
        1,7,0   107) *
</screen>

      <para>This lists the approriate <option>dev</option> value for
      the devices on the list. Locate your CD burner, and use the
      three numbers separated by commas as the value for
      <option>dev</option>. In this case, the CRW device is 1,5,0, so
      the appriate option would be
      <userinput><option>dev</option>=1,5,0</userinput>. There are
      easier ways to specify this value; see the &man.cdrecord.1; for
      details. That is also the place to look for information on
      writing audio tracks, controlling the speed, and other
      things.</para>
      </sect1>
      </chapter>
How-To-Repeat: 
Look for the document, and fail to find it.