
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
