File:  [DragonFly] / doc / en / books / usersguide / installation / chapter.sgml
Revision 1.2: download - view: text, annotated - select for diffs
Tue Jun 1 20:00:04 2004 UTC (10 years, 1 month ago) by justin
Branches: MAIN
CVS tags: HEAD
Completed conversion of Markus Schatzl's installation notes, plus
additions from me.  Also, some changes suggested by Matt Dillon.

This section is now complete enough that it will take a user from
end to end of the install process, in most cases.  It does not touch
upon the new installer work.

<!--
$DragonFly: doc/en/books/usersguide/installation/chapter.sgml,v 1.2 2004/06/01 20:00:04 justin Exp $
-->
<chapter id="installation-cd">
  <chapterinfo>
    <authorgroup>
      <author>
        <firstname>Markus</firstname>
        <surname>Schatzl</surname>
        <contrib>Written by </contrib>
      </author> <!-- lists@neuronenwerk.de  05 May 2004 -->
      <author>
        <firstname>Justin</firstname>
        <surname>Sherrill</surname>
      </author> <!-- justin@dragonflybsd.org  05 May 2004 -->
    </authorgroup>
  </chapterinfo>
  <title>Installation from CD</title>

  <sect1 id="installation-cd-synopsis">
    <title>CD Installation Overview</title>
      <para>This document describes the installation of DragonFly BSD on a plain i386
      machine. This process uses a bootable DragonFly CD, usually referred to as a
      'live CD'.</para>

      <para>This CD is available at one of the current mirrors, which distribute the images
      by various protocols. The authorative list can be found at the
      <ulink url="http://www.dragonflybsd.org/main/download.cgi">DragonFly website</ulink>.</para>

      <para>This document may be superseded by the /README file located on the live CD, 
      which may reflect changes made after this document was last updated.  Check that 
      README for any last-minute changes and for an abbreviated version of this installation 
      process.</para>

      <para>The DragonFly development team is working on an automatic installation
      tool, which simplifies the partitioning and installation processes. Until this
      tool is in place, the manual process here is required.  Some experience with
      BSD-style tools is recommended.</para>

      <caution>
        <para>While this guide covers installing to
        a computer with an existing non-DragonFly operating system, take no chances!  Back up
        any data on your disk drives that you want to save.</para>
      </caution>

      <para>When installing to an old machine, it may not be possible to boot from
      a CD. Use a bootmanager on a floppy in those cases, such as
      <ulink url="http://btmgr.sourceforge.net/">Smart Bootmanager</ulink>.</para>

      <caution>
        <para>Always be sure of the target disk for any command.  Unless otherwise 
        specified, each command here assumes the first disk in the IDE chain is 
        the target.  (ad0)  Adjust commands as needed.</para>
      </caution>
  
  </sect1>

  <sect1 id="installation-cd-preinstall">
    <title>CD Installation - Making room</title>

      <sect2>
        <title>DragonFly as the only operating system</title>
        <para>If DragonFly is to be the only operating system on the target computer, preparing
        the disk is a short and simple process.  Boot with the live CD, and log in as root
        to reach a command prompt.</para>

        <para>First, the master boot record (MBR) must be cleared of any old information.  This
        command clears all old data off your disk by writing zeros (if=/dev/zero) onto the
        system's master ata drive (of=/dev/ad0).</para>

        <!-- put in big fat note about disk naming -->

        <screen>
        &prompt.root; <userinput>dd if=/dev/zero of=/dev/<replaceable>ad0</replaceable> bs=32k count=16</userinput>
        </screen>

        <para>The now-empty disk must be formatted.  </para>
        
        <important>
          <para>This will destroy any existing data on a disk.  Do this only if 
          you plan to dedicate this disk to DragonFly.</para>
        </important>

        <screen>
        &prompt.root; <userinput>fdisk -I <replaceable>ad0</replaceable></userinput>
        &prompt.root; <userinput>fdisk -B <replaceable>ad0</replaceable></userinput>
        </screen>
      
      </sect2>

      <sect2>
        <title>Multiple operating systems on one hard disk</title>
        <para>This example assumes that the target computer for installation has at least
        one operating system installed that needs to survive the installation process.
        A new partition for DragonFly needs to be created from the existing
        partition(s) that otherwise fill the disk.  There must be unused space within
        the existing partition in order to resize it.</para>

        <important>
          <para>The new partition is created from empty space in an existing partition.
          For example, an 18 gigabyte disk that has 17 gigabytes of existing data in the existing
          partition will only have 1 gigabyte available for the new partition.</para>
        </important>

        <para>Partition resizing needs to be accomplished with a third-party tool.  Commercial
        programs such as <ulink url="http://www.symantec.com/partitionmagic/">Partition Magic</ulink>
        can accomplish these tasks.  Free tools exist that can be adapted to this task, such as
        'GNU parted', found on the
        <ulink url="http://www.knopper.net/knoppix-mirrors/index-en.html">Knoppix CD</ulink>,
        or <ulink url="http://paud.sourceforge.net">PAUD</ulink>.
        </para>

        <para>Create a new partition of at least 5-6 gigabytes.  It is possible to
        install within a smaller amount of disk space, but this will create 
        problems not covered by this document.  The newly created partition
        does not need to be formatted; the rest of the
        installation process treats that new partiton as a new disk.</para>
      </sect2>

      <sect2>
        <title>Multiple operating systems, multiple hard disks</title>
        <para>Installing DragonFly to a separate disk removes the need
        for partition resizing, and is generally safer when trying to preserve
        an existing operating system installation.</para>

        <para>This type of installation is very similar to installing DragonFly
        as the only operating system.  The only difference is the disk named
        in each command.</para>

      </sect2>
  </sect1>

  <sect1 id="installation-cd-disk">
    <title>CD Installation - Disk setup</title>

      <sect2>
        <title>Disk formatting</title>
        <para>The slice layout on the newly formatted disk or partition needs 
	to be set up, using this command.  </para>
      
          <screen>
          &prompt.root; <userinput>fdisk -u</userinput>
          </screen>

        <!-- reword -->
        <para>If there are multiple operating systems on the disk, pick the correct 
        partition judging by what partitions were created earlier with a resizing tool.</para>
      </sect2>

      <sect2>
        <title>Boot block installation</title>
          <para>The 'ad0' here refers to the first disk on the first IDE bus of a computer.  
          Increment the number if the target disk is farther down the chain.  For example, 
          the master disk on the second IDE controller would be 'ad2'.</para>
 
          <!-- write list here of adx to drive mapping, and scsi too -->
  
          <screen>
          &prompt.root; <userinput>boot0cfg -B <replaceable>ad0</replaceable></userinput>
          &prompt.root; <userinput>boot0cfg -v <replaceable>ad0</replaceable></userinput>
          </screen>

          <para><userinput>-s SLICE</userinput>, where SLICE is a number, controls which 
          slice on disk is used by boot0cfg to start from.  By default, this number is 1, and 
          will only need modification if a different slice contains DragonFly.</para>
  
          <para>Use <userinput>-o packet</userinput> as an option to boot0cfg if the DragonFly 
          partition is located beyond cylinder 1023 on the disk.  This location problem usually 
          only happens when another operating system is taking up more than the 
          first 8 gigabytes of disk space.  This problem cannot happen if DragonFly is 
          installed to a dedicated disk </para>
  
       </sect2>

      <sect2>
        <title>Disklabel</title>
          <para>If DragonFly is installed anywhere but the first partition of the disk, 
          the device entry for that partition will have to be created.  Otherwise, the 
          device entry is automatically created.  Refer to this different partition 
          instead of the 'ad0s1a' used in later examples.</para>

          <screen>
          &prompt.root; <userinput>cd /dev; ./MAKEDEV <replaceable>ad0s2</replaceable></userinput>
          </screen>

          <para>The partition needs to be created on the DragonFly disk.</para>

          <screen>
          &prompt.root; <userinput>disklabel -B -r -w <replaceable>ad0s1</replaceable> auto</userinput>
          </screen>

          <para>Using /etc/disklabel.ad0s1 as an example, issue the following command to 
          edit the disklabel for the just-created partition.</para>

          <screen>
          &prompt.root; <userinput>disklabel -e <replaceable>ad0s1</replaceable></userinput>
          </screen>

  
          <informaltable>
            <tgroup cols="3">
              <thead>
                <row>
                  <entry>Partition</entry>
                  <entry>Size</entry>
                  <entry>Mountpoint</entry>
                </row>
              </thead>

              <tbody>

                 <row>
                  <entry>ad0s2a
                  <entry>256m
                  <entry>/
                </row>
          
                 <row>
                  <entry>ad0s2b
                  <entry>1024m
                  <entry>swap
                </row>
          
                 <row>
                  <entry>ad0s2c
                  <entry>leave alone
                  <entry>This represents the whole slice.
                </row>
          
                 <row>
                  <entry>ad0s2d
                  <entry>256m
                  <entry>/var
                </row>
          
                 <row>
                  <entry>ad0s2e
                  <entry>256m
                  <entry>/tmp !
                </row>
          
                 <row>
                  <entry>ad0s2f
                  <entry>8192m
                  <entry>/usr - This should be at least 4096m
                </row>
          
                 <row>
                  <entry>ad0s2g
                  <entry>*
                  <entry>/home - This holds 'everything else'
                </row>

              </tbody>
            </tgroup>
          </informaltable>

      </sect2>
      
      <sect2>
        <title>Partition Format</title>
          <para>newfs will format each individual partition.  </para>

          <screen>
          &prompt.root; <userinput>newfs /dev/<replaceable>ad0s1a</replaceable></userinput>
          &prompt.root; <userinput>newfs -U /dev/<replaceable>ad0s1d</replaceable></userinput>
          &prompt.root; <userinput>newfs -U /dev/<replaceable>ad0s1e</replaceable></userinput>
          &prompt.root; <userinput>newfs -U /dev/<replaceable>ad0s1f</replaceable></userinput>
          &prompt.root; <userinput>newfs -U /dev/<replaceable>ad0s1g</replaceable></userinput>
          </screen>

          <note>
            <para>The -U option is not used for the root partition, 
            since / is usually relatively small.  Softupdates can cause it to
            run out of space while under a lot of disk activity, such as a buildworld.</para>
          </note>

          <note>
            <para>The command listing skips directly from ad0s1a to ad0s1d.  This is 
            because /dev/ad0s1b is used as swap and does not require formatting; 
            ad0s1c refers to the entire disk and should not be formatted.</para>
          </note>
      </sect2>
  </sect1>

  <sect1 id="installation-cd-to-disk">
    <title>Installing to Disk</title>
      <para>Since the Live CD contains all needed data to create a running DragonFly system, 
      the simplest installation possible is to copy the Live CD data to the newly formatted 
      disk/partition created in previous steps.
      </para>

      <para>These commands mount the newly created disk space and create the 
      appropriate directories on it.</para>

      <screen>
      &prompt.root; <userinput>mount /dev/<replaceable>ad0s1a</replaceable> /mnt</userinput>
      &prompt.root; <userinput>mkdir /mnt/var</userinput>
      &prompt.root; <userinput>mkdir /mnt/tmp</userinput>
      &prompt.root; <userinput>mkdir /mnt/usr</userinput>
      &prompt.root; <userinput>mkdir /mnt/home</userinput>
      &prompt.root; <userinput>mount /dev/<replaceable>ad0s1d</replaceable> /mnt/var</userinput>
      &prompt.root; <userinput>mount /dev/<replaceable>ad0s1e</replaceable> /mnt/tmp</userinput>
      &prompt.root; <userinput>mount /dev/<replaceable>ad0s1f</replaceable> /mnt/usr</userinput>
      &prompt.root; <userinput>mount /dev/<replaceable>ad0s1g</replaceable> /mnt/home</userinput>
      </screen>

      <para>cpdup duplicates data from one volume to another.  These commands copy 
      data from the Live CD to the newly created directories on the mounted disk.
      Each step can take some time, depending on disk speed.</para>
      
      <screen>
      &prompt.root; <userinput>cpdup / /mnt</userinput>
      &prompt.root; <userinput>cpdup /var /mnt/var</userinput>
      &prompt.root; <userinput>cpdup /etc /mnt/etc</userinput>
      &prompt.root; <userinput>cpdup /dev /mnt/dev</userinput>
      &prompt.root; <userinput>cpdup /usr /mnt/usr</userinput>
      </screen>

        <note>
          <para>Nothing is copied to the /tmp directory that was created 
          in the previous step.  This is not an error, since /tmp is intended only 
          for temporary storage.</para>
        </note>
            
  </sect1>

  <sect1 id="installation-cd-postinstall">
    <title>CD Installation - Post-install cleanup</title>
      
      <para>/tmp and /var/tmp are both often used as temporary directories.  Since 
      use is not consistent from application to application, it is worthwhile to 
      create /tmp as a link to /var/tmp so space is not wasted in duplication.
      </para>
    
      <screen>
      &prompt.root; <userinput>chmod 1777 /mnt/tmp</userinput>
      &prompt.root; <userinput>rm -fr /mnt/var/tmp</userinput>
      &prompt.root; <userinput>ln -s /tmp /mnt/var/tmp</userinput>
      </screen>

      <note>
        <para>/tmp will not work until the computer is rebooted.</para>
      </note>
      
      <para>The file /etc/fstab describes the disk partition layout.  However, 
      the version copied to the target disk only reflects the Live CD layout.  
      The installed /mnt/fstab.example can be used as a starting point for 
      creating a new /etc/fstab.</para>
      
      <screen>
      &prompt.root; <userinput>vi /mnt/etc/fstab.example</userinput>
      &prompt.root; <userinput>mv /mnt/etc/fstab.example /mnt/etc/fstab</userinput>
      </screen>
      
      <para>A corrupted disklabel will render a disk useless.  While this is 
      thankfully very rare, having a backup of the new install's disklabel may 
      stave off disaster at some point in the future.  This is optional.  
      (Adjust the slice name to reflect the actual installation.)</para>
      
      <screen>
      &prompt.root; <userinput>disklabel <replaceable>ad0s1</replaceable> > /mnt/etc/disklabel.backup</userinput>
      </screen>

      <note>
        <para>Nothing is copied to the /tmp directory that was created 
        in the previous step.  This is not an error, since /tmp is intended only 
        for temporary storage.</para>
      </note>      
      
      <para>Remove some unnecessary files copied over from the Live CD.</para>

      <screen>
      &prompt.root; <userinput>rm /mnt/boot/loader.conf</userinput>
      &prompt.root; <userinput>rm /mnt/boot.catalog</userinput>
      &prompt.root; <userinput>rm -r /mnt/rr_moved</userinput>
      </screen>

      <para>The system can now be rebooted.  Be sure to remove the Live CD from the 
      CDROM drive so that the computer can boot from the newly-installed disk.</para>

      <screen>
      &prompt.root; <userinput>reboot</userinput>
      </screen>

      <note>
        <para>Use the reboot command so that the disk can be unmounted cleanly.  
	Hitting the power or reset buttons, while it won't hurt the Live CD, 
	can leave the mounted disk in a inconsistent state.  </para>
      </note>
      
      <para>If the system refuses to boot, there are several options to try:</para>

      <itemizedlist>
        <listitem>
          
          <para>Old bootblocks can interfere with the initialization-process.  To 
          avoid this, zero-out the MBR.  "of" should be changed to the correct disk 
          entry if ad0 is not the targeted installation disk.</para> 

          <screen>
          &prompt.root; <userinput>dd if=/dev/zero of=/dev/<replaceable>ad0</replaceable> bs=32 count=16</userinput>
          </screen>
        
        </listitem>
        <listitem>
  
          <para>It is possible that the DragonFly slice is beyond cylinder 1023 on the 
          hard disk, and can't be detected.  Packet mode can fix this problem.</para>
          
          <screen>
          &prompt.root; <userinput>boot0cfg -o packet <replaceable>ad0</replaceable></userinput>
          </screen>
        
        </listitem>
        <listitem>
        
          <para>If you can select CHS or LBA mode in your BIOS, try changing 
          the mode to LBA.</para>
        
        </listitem>
      </itemizedlist>
      
      <para>After a successful boot from the newly installed hard drive, the timezone 
      should be set.  Use the command <command>tzsetup</command> to set the appropriate 
      time zone.
      </para>

      <screen>
      &prompt.root; <userinput>tzsetup</userinput>
      </screen>

</sect1>




  <sect1 id="installation-system-setup">
    <title>CD Installation - New system setup</title>

      <para>Once the new DragonFly system is booting from disk, there are a number of 
      steps that may be useful before working further.  The file /etc/rc.conf controls a 
      number of options for booting the system.
      </para>

      <sect2>
        <title>Setting up rc.conf</title>
          <para>Depending on location, a different keyboard map may be needed.  This is 
          only necessary for computers outside of North America.</para>

          <screen> 
          &prompt.root; <userinput>kbdmap</userinput>
          </screen>

          <para>Pick the appropriate keyboard map and remember the name.  Place this 
          name in /etc/rc.conf.  For example:</para>

          <screen>
          <userinput>keymap="german.iso.kbd"</userinput>
          </screen>

          <para>The file /etc/rc.conf matches the one on the Live CD.  Since it is now 
          on an installed system are no longer running in a read-only environment, some 
          changes should be made.  Changes to this file will take effect after the 
          next boot of the machine.</para>

          <para>These lines can be removed.</para>

          <programlisting>syslogd_enable="NO"
xntpd_enable="NO"
cron_enable="NO"</programlisting>

          <para>For a system which uses USB, this line will need to be modified to 
	  a value of "YES":</para>
	  
	  <programlisting>usbd_enable="NO"</programlisting>

          <!-- link to man pages for this-->
	  
	  <para>inetd controls various small servers like telnet or ftp.  By default, 
          all servers are off, and must be individually uncommented in /etc/inetd.conf 
	  to start them.  This is optional.</para>

          <programlisting>inetd_enable="YES"              # Run the network daemon dispatcher (YES/NO).
inetd_program="/usr/sbin/inetd" # path to inetd, if you want a different one.
inetd_flags="-wW"               # Optional flags to inetd</programlisting>

      </sect2>
      
      <sect2>  
        <title>Network Setup</title>
          <para>For acquiring an IP address through DHCP, place this entry in /etc/rc.conf, 
          using the appropriate card name.  (ep0 is used as an example here.)</para>
           
          <screen>
          <userinput>ifconfig_<replaceable>ep0</replaceable>="DHCP"</userinput>
          </screen>

          <para>For a fixed IP, /etc/rc.conf requires a few more lines of data.
          (Again, ep0 is used as an example here.)  Supply the correct local values 
	  for IP, netmask, and default router.  The hostname should reflect what is 
	  entered in DNS for this computer.</para>
          
          <screen>
          <userinput>ifconfig_<replaceable>ep0</replaceable>="inet <replaceable>123.234.345.456</replaceable> netmask <replaceable>255.255.255.0</replaceable>"</userinput>
          <userinput>hostname="<replaceable>myhostname</replaceable>"</userinput>
          <userinput>defaultrouter="<replaceable>654.543.432.321</replaceable>"</userinput>
          </screen>
      </sect2>
  </sect1>

</chapter>