Using Debian From Scratch

John Goerzen

   PLEASE NOTE: THIS DOCUMENTATION IS NOT YET ANYWHERE NEAR
   FINISHED.

   FIXME: add copyright here
     __________________________________________________________

   Table of Contents
   1. Introduction to DFS

        1.1. DFS Features
        1.2. Getting DFS
        1.3. History of DFS

   2. Booting DFS

        2.1. Booting on i386 (PC)
        2.2. Booting on Alpha
        2.3. Booting on PowerPC
        2.4. Booting a Kernel
        2.5. Selecting CD-ROM device
        2.6. Detecting Hardware
        2.7. Enabling Ethernet

              2.7.1. Wireless Networking

        2.8. Dialup with PPP

   3. Installation
   A. Command Reference

        dfsbuild -- Generate custom Debian From Scratch CD images

   B. Links to Related Resources
     __________________________________________________________

Chapter 1. Introduction to DFS

   Welcome to Debian From Scratch (DFS). DFS is really two
   systems: 1) a bootable CD for repairing Linux systems or
   installing Debian; and 2) the program that generates the CDs
   that are used for #1. Most of this manual focuses on #1. A wide
   variety of DFS CDs can be made using the DFS build tools. This
   manual will refer to CDs made using the default configuration.
     __________________________________________________________

1.1. DFS Features

   You can expect the following from your DFS CD:

     * Bootable CD featuring the GNU Grub bootloader. Can be used
       to boot hard disk partitions even if no hard disk
       bootloader is present.
     * Kernel and userland support for all major filesystems,
       including ext2, ext3, JFS, XFS, ReiserFS, FAT, VFAT, NTFS,
       ISO9660, CramFS, tmpfs, and more. Userland support for
       Reiser4.
     * Kernel and userland support for different disk layout
       schemes including standard partitioning, Logical Volume
       Manager 2 (LVM2), software RAID, etc.
     * Full recovery tools runnable directly from CD, including:
          + Filesystem utilities for all major filesystems,
            including undeletion tools for ext2
          + Partition editors (fdisk, cfdisk, parted)
          + Text editors (nano, joe, vim, emacs)
          + C, Perl, Python, and OCaml development environments.
            Enough to configure and compile a new kernel and build
            basic .debs. Kernel 2.6.6 sources included on CD.
          + Full networking support, including PPP and various
            Ethernet cards and DHCP
          + Network tools including FTP clients, Web client, ssh,
            telnet, NFS, smbclient, tcpdump, netcat, etc.
          + Backup restoration tools such as rdiff-backup,
            dump/restore, tar, cpio, amanda client, afbackup
            client, etc.
          + CD and DVD burning tools
          + Basic printing tools (cat for local printers, rlpr for
            remote ones, and netcat for Jetdirect, plus unix2dos
            for text files and Ghostscript for emergency
            conversions)
          + Mail reader (mutt)
     * Base systems for multiple versions of Debian installable
       directly from CD, including: sarge, etch, and sid (stable,
       testing, and unstable).
     * Hybrid amd64 support: A single i386/amd64 hybrid CD
       provides enough to install or fix either an i386 or an
       AMD64 system. Includes 64-bit kernel with 32-bit emulation
       (to run the 32-bit userland on the CD). Also includes
       64-bit packages for bootstrapping a new AMD64 support. In
       short, you can boot a 64-bit kernel and be treated as a
       first-class citizen in almost all respects.
     * Easy porting to other architectures. Existing ports to
       Alpha and PowerPC.
     * i386 or x86_64 (amd64) kernels bootable directly from
       initial boot menu.
     * DFS generation scripts support custom kernels, packages,
       mirrors, compressed ISO images, and a high degree of
       flexibility.
     __________________________________________________________

1.2. Getting DFS

   You may download ISO images for DFS from John Goerzen's DFS
   site. The dfsbuild program is available from within Debian
   itself, or you may find it on the Debian package page.

   For more resources, please visit Appendix B>.
     __________________________________________________________

1.3. History of DFS

   DFS begain as the first installer for the amd64 port of Debian.
   I also wanted to have a handy rescue disk for systems that use
   LVM, Reiser4, etc. At the time, the Debian installers didn't
   support any of this.
     __________________________________________________________

Chapter 2. Booting DFS

   Booting procedures vary by architecture. Here are some basics:
     __________________________________________________________

2.1. Booting on i386 (PC)

   Booting DFS usually is as simple as inserting a CD into the
   drive. DFS can boot from an IDE or SCSI CD-ROM. On some
   systems, you may need to access your BIOS to enable booting
   from CD. When you have successfully booted DFS the CD, you'll
   see a blue Grub selection screen.
     __________________________________________________________

2.2. Booting on Alpha

   The DFS images for Alpha support the SRM console only at this
   time. If your system uses AlphaBIOS or some other BIOS, you may
   need to convert to SRM. If you need the SRM firmware, you may
   be able to find it on the Alpha firmware updates page.

   Details about SRM can be found at the SRM HOWTO. If you are
   reading this manual directly from the DFS CD-ROM, you can find
   the HOWTO at
   file:///usr/share/doc/aboot-base/SRM-HOWTO/index.html. If you
   are reading this on the Web, the SRM HOWTO can be found at
   http://www.tldp.org/HOWTO/SRM-HOWTO/ or
   http://www.alphalinux.org/faq/srm.html.

   Booting the DFS CD generally involves these steps:

    1. Boot to an SRM prompt. If your system is set to
       automatically boot an operating system, Ctrl-C at the
       appropriate time may accomplish this.
    2. Set the operating system type with: set os_type Unix.
    3. Find the device that represents your CD-ROM drive. Typing
       show dev will help you out. IDE users may often find dqa2
       as their CD-ROM device. Please consult show dev to discover
       the proper value for your system.
    4. Boot the aboot bootloader. Run: boot device -fl i. Replace
       device with your particular CD-ROM device.
    5. You should now see an aboot prompt. You can press "l"
       (lower-case "L") to see a list of available kernels. Press
       zero through 9 to boot one of them; the default should be
       set to 0. If you don't know what to do, just press 0.
    6. Linux should now start.
     __________________________________________________________

2.3. Booting on PowerPC

   The DFS images for PowerPC support booting from OpenFirmware
   (OF) into yaboot.

   Booting the DFS CD generally involves these steps:

    1. Boot into yaboot. On newer PowerPC (NewWorld) you can press
       "c" (or "Command-Option-Shift-Delete") during boot until
       you reach the yaboot bootprompt. If this does not work, you
       have to boot into OpenFirmware first. This can be done by
       pressing "Option-Command-o-f" (all four at the same time)
       during boot. The Option key might also be labeled "Alt" and
       the Command key with the Apple sign on your keyboard. Once
       you have reached the OpenFirmware prompt, type boot
       cd:,\boot\yaboot to boot into yaboot.
    2. You should now see an yaboot prompt. You can press "TAB" to
       see a list of available kernels. Enter the kernel's name to
       boot it. The *-safe options use "video=ofonly" which is
       needed if your machine has a framebuffer that is not well
       supported and booting would give flickering lines on the
       screen. "ofonly" relies on the OpenFirmware console.
    3. Linux should now start.
     __________________________________________________________

2.4. Booting a Kernel

   Depending on how your CD was built, you'll see options for one
   or more different kernel images. Select one appropriate for
   your system. If a given image says "amd64", this should only be
   used on amd64 systems such as Opteron or Athlon64 system. Note:
   if you intend to install a 64-bit amd64 system, you MUST boot
   from the 64-bit amd64 kernel.
     __________________________________________________________

2.5. Selecting CD-ROM device

   In most cases, DFS can automatically detect which drive holds
   your DFS CD. However, if that check is time-consuming or fails,
   you can manually specify your CD with the dfscd parameter. To
   use it, select the kernel you wish, press e to edit the command
   and edit the "kernel" line. Insert something such as
   dfscd=/dev/hdc, press Enter, then b to boot.
     __________________________________________________________

2.6. Detecting Hardware

   Some hardware will automatically be configured. You can attempt
   to autodetect more hardware by running /etc/init.d/discover
   start. If you want to use USB devices, try /etc/init.d/hotplug
   start. Otherwise, you will likely need to manually load kernel
   modules. You can find them under /lib/modules/kernelversion.
   Tools such as lspci can help you find out what hardware you
   have that needs to be loaded.

   If you have PCMCIA devices, run /etc/init.d/pcmcia start.
     __________________________________________________________

2.7. Enabling Ethernet

   If your network hardware was detected and your LAN uses DHCP,
   you can simply say ifup eth0. Your network will be activated.

   If your LAN does not use DHCP, you will need to edit
   /etc/networking/interfaces. You should delete the eth0 line and
   replace it with something along these lines:
iface eth0 inet static
    address 192.168.0.4
    netmask 255.255.255.0
    gateway 192.168.0.1

   Then run ifup eth0. You'll also need to edit /etc/resolv.conf
   and add a line such as nameserver 192.168.0.1 to specify your
   nameserver. (If you run DHCP, this is usually taken care of for
   you, but you may occasionally need to do it anyway.)
     __________________________________________________________

2.7.1. Wireless Networking

   If you are using wireless networking, first make sure that your
   hardware is detected. Sometimes the device name is not eth0; if
   so, figure out what your device is called. If your network is
   open -- has no encryption -- you should be able to enable your
   wireless device the same as a wired device. Otherwise, you will
   need to modify /etc/network/interfaces as described in the file
   /usr/share/doc/wireless-tools/README.Debian on the live DFS
   system.
     __________________________________________________________

2.8. Dialup with PPP

   To dial-up with ppp, first run pppconfig to set up your access.
   Name your connection "provider". Now, you can use pon to
   connect and poff to disconnect.
     __________________________________________________________

Chapter 3. Installation

   Installation from DFS involves the following general steps:

    1. Partitioning
    2. Initialize and mount swap
    3. Formatting and Mounting Filesystems
    4. Installing Base System
       You can do this (assuming you have mounted your new
       partitions at /mnt) with: cdebootstrap sid /mnt
       file:///opt/packages. (amd64: add -a amd64 before "sid".
       Also, I recommend using the amd64 mirror directly, since
       things change frequently and the data available when the CD
       was made may or may not be usable for you.
    5. Configuring Base System
       You should copy your /etc/resolv.conf to the new system.
       Then, configure its /etc/apt/sources.list, /etc/fstab, and
       /etc/network/interfaces. Then, chroot /mnt and:
         a. apt-get update
         b. i386: apt-get install module-init-tools grub ppp
            alpha: apt-get install module-init-tools aboot ppp
            powerpc: apt-get install module-init-tools yaboot ppp
         c. apt-get install appropriate filesystem tools for your
            chosen filesystem
         d. i386: mkdir /boot/grub; cp /lib/grub/i386-pc/*
            /boot/grub
            If your /boot is its own partition, also run cd /boot;
            ln -s . boot.

      Note

           amd64 did not have a grub package as of the last check.
           However, you can simulate it; just mkdir /mnt/boot/grub and
           copy the files from /lib/grub/i386-pc on the live CD image to
           /boot/grub on your new system.
            alpha: see aboot docs
            powerpc: see yaboot docs
    6. Installing Kernel
       If you like the kernel on the DFS CD, you can do this: cd
       /mnt/root; dpkg-repack linunx-image-2.6.16.4. Then, chroot
       /mnt and dpkg -i /root/linux-image-*.
    7. Installing Grub
# grub
grub> root (hd0,0)
grub> setup (hd0)
grub> quit
# update-grub

       amd64 users: if this doesn't work, try rebooting the DFS
       cd. Press "c" when you see the blue Grub menu to get a
       command line. Then run the above.
    8. Rebooting into new system
     __________________________________________________________

Appendix A. Command Reference

dfsbuild

Name

   dfsbuild -- Generate custom Debian From Scratch CD images

Synopsis

   dfsbuild [-a arch] [-R] [-v | -V] -c config_file -w working_dir

Description

   dfsbuild is a program to generate Debian From Scratch (DFS) CD
   images. It is highly configurable and can generate images far
   different from the standard DFS image.

   The output from dfsbuild is an ISO image that is bootable on
   i386 and amd64, powerpc, or alpha systems. It uses Grub for the
   bootloader (on i386/amd64), and in the default configuration,
   generates DFS ISOs that are bootable and can be used to repair
   a Linux system or install a new one.

   dfsbuild requires about twice the eventual size of the ISO
   image to run. That is, if you are building a 600MB ISO image,
   you will need approximately 1.2GB free on the disk that holds
   working_dir.

   Configuration is accomplished through the config file given
   with -c. An example is available in /etc/dfsbuild/dfs.cfg. That
   example is commented and shows all the available options.

   dfsbuild must be run as root.

Options

   These are the command-line options for dfsbuild. Please note
   that you must always specify at least -c and -w.

   -a architecture
          Specify the Debian architecture of the destination
          image. Normally, this defaults to the architecture of
          the host system. This option may be useful to, for
          instance, build an i386 image from your amd64 host.

   -c configfile
          Specifies the path for the configuration file to use.

   -R
          Resume an existing build. If your build failed, you may
          be able to restart it from where it left off by using
          this option. Resuming is not supported from every point,
          so do not be surprised if this option doesn't work for
          you everywhere. This option is still experimental and
          may disappear in future versions of dfsbuild.

   -v
          Enable verbose mode for dfsbuild messages only.

   -V
          Enable verbose mode for both dfsbuild messages and
          messages from external programs when possible.

   -w directory
          Specifies a directory for dfsbuild to use as its "work"
          directory. It will create its temporary files, and place
          the resulting ISO9660 image, in this directory.

          It is an error if this directory already exists, unless
          -R is given, in which case it is an error if this
          directory does not exist.

Copyright

   dfsbuild, all associated scripts and programs, this manual, and
   all build scripts are Copyright  2004-2006 John Goerzen.

   This program is free software; you can redistribute it and/or
   modify it under the terms of the GNU General Public License as
   published by the Free Software Foundation; either version 2 of
   the License, or (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public
   License along with this program; if not, write to the Free
   Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
   MA 02111-1307 USA

Author

   dfsbuild, its modules, documentation, executables, and all
   included files, except where noted, was written by John Goerzen
   <jgoerzen@complete.org> and copyright is held as stated in the
   COPYRIGHT section.

See Also

   Other related references include: DFS Manual at
   /usr/share/doc/dfsbuild, mkisofs(1), cdebootstrap(1). Pre-build
   DFS ISOs for various architectures are available from John
   Goerzen's DFS page at http://people.debian.org/~jgoerzen/dfs/.
     __________________________________________________________

Appendix B. Links to Related Resources

   Here are some links to websites where you may find DFS-related
   resources:

     * DFS pre-built ISO images
     * NewsForge article: Installing Debian From Scratch
     * Article by Suramya Tomar: How to Install Debian From
       Scratch
