The software that has been packaged for Debian is available in one of several directory trees on each Debian mirror site through FTP or HTTP.

The following directories can be found on each Debian mirror site under the debian directory:

dists/:

This directory contains the "distributions", and this used to be the canonical way to access the currently available packages in Debian releases and pre-releases. Some old packages, the Contents-*.gz and Packages.gz files are still in here.

pool/:

The new physical location for all packages of Debian releases and pre-releases.

tools/:

DOS utilities for creating boot disks, partitioning your disk drive, compressing/decompressing files, and booting Linux.

doc/:

The basic Debian documentation, such as the FAQ, the bug reporting system instructions, etc.

indices/:

The Maintainers file and the override files.

project/:

mostly developer-only materials, such as:

project/experimental/:

This directory contains packages and tools which are still being developed, and are still in the alpha testing stage. Users shouldn't be using packages from here, because they can be dangerous and harmful even for the most experienced.

project/orphaned/:

Packages that have been orphaned by their old maintainers, and withdrawn from the distribution.

Normally there are three Debian distributions in the dists directory. They are named the stable distribution, the testing distribution, and the unstable distribution. Sometimes there was also a frozen distribution (currently it is just a development stage of the testing distribution). Each distribution is defined as a symlink to the actual directory with a codename in the dists directory.

Package entries for the stable distribution, Debian Etch (4.0), are recorded into the stable (symlink to etch/) directory:

• stable/main/: This directory contains the package versions belonging to the most recent official release of the Debian system.

  These packages are all free; that is, they all comply with the Debian Free Software Guidelines (DFSG) (also available as file:///usr/share/doc/debian/social-contract.txt installed by debian-doc).

• stable/non-free/: This directory contains packages that fail to qualify as free according to the DFSG.

  For example, some packages have licenses that prohibit commercial distribution. Others can be redistributed but are shareware.

• stable/contrib/: Each package in this directory is itself DFSG-free but somehow Depends on a package that is not DFSG-free.

Now, in addition to the above locations, nowadays physical packages are located under the pool directory (The pool directory, Section 2.1.10).

The current status of stable distribution bugs is reported on the Stable Problems web page.

Package entries for the testing distribution, Debian Lenny, are recorded into the testing (symlink to lenny/) directory after they have undergone some degree of testing in unstable. Nowadays physical packages are located under the pool directory (The pool directory, Section 2.1.10). There are also main, contrib, and non-free subdirectories in testing/, which serve the same functions as in stable/.

These packages must be in sync on all architectures where they have been built and must be installable; they must also have fewer release-critical bugs than the versions currently in unstable. This way, we hope that testing is always close to being a release candidate. More details of the testing mechanism are at http://www.debian.org/devel/testing.

The latest status of the testing distribution is reported at these sites:

• update excuses

• testing problems

• release-critical bugs

• base system bugs

• bugs in standard and task packages

• other bugs and bug-squashing party notes

Package entries for the unstable distribution, always codenamed "Sid", are recorded into the unstable (symlink to sid/) directory after they are uploaded to the Debian archive and stay here until they are moved to testing/. Nowadays physical packages are located under the pool directory (The pool directory, Section 2.1.10). There are also main, contrib, and non-free subdirectories in unstable/, which serve the same functions as in stable/.

The unstable distribution contains a snapshot of the most current development system. Users are welcome to use and test these packages, but are warned about their state of readiness. The advantage of using the unstable distribution is that you are always up-to-date with the latest in the Debian software project—but if it breaks, you get to keep both parts. :-)

The current status of unstable distribution bugs is reported on the Unstable Problems web page.

When the testing distribution is mature enough, it becomes frozen, meaning no new code is accepted anymore, just bugfixes, if necessary. Also, a new testing tree is created in the dists directory, assigned a new codename. The frozen distribution passes through a few months of testing, with intermittent updates and deep freezes called "test cycles".

We keep a record of bugs in the frozen distribution that can delay a package from being released or bugs that can hold back the whole release. Once that bug count lowers to maximum acceptable values, the frozen distribution becomes stable, it is released, and the previous stable distribution becomes obsolete (and moves to the archive).

Physical directory names in the dists directory, such as etch/ and lenny/, are just "codenames". When a Debian distribution is in the development stage, it has no version number, but a codename instead. The purpose of these codenames is to make the mirroring of the Debian distributions easier. (If unstable would be a real directory and it's name would suddenly change to stable/, a lot of stuff would have to be needlessly downloaded again).

Currently, stable/ is a symbolic link to etch/, and testing/ is a symbolic link to lenny/. This means that Etch is the current stable distribution and Lenny is the current testing distribution.

unstable/ is a permanent symbolic link to sid/, as Sid is always the unstable distribution.

Codenames that have already been used are: "Buzz" for release 1.1, "Rex" for release 1.2, "Bo" for releases 1.3.x, "Hamm" for release 2.0, "Slink" for release 2.1, "Potato" for release 2.2, "Woody" for release 3.0, and "Sarge" for release 3.1.

So far they have been characters taken from the movie Toy Story by Pixar.

• Buzz (Buzz Lightyear) was the spaceman,

• Rex was the tyrannosaurus,

• Bo (Bo Peep) was the girl who took care of the sheep,

• Hamm was the piggy bank,

• Slink (Slinky Dog) was the toy dog,

• Potato was, of course, Mr. Potato Head,

• Woody was the cowboy,

• Sarge was a leader of the Green Plastic Army Men,

• Etch (Etch-a-Sketch) was the blackboard,

• Sid was a boy next door who destroyed toys.

Historically, packages were kept in the subdirectory of dists corresponding to the distribution that contained them. This turned out to cause various problems, such as large bandwidth consumption on mirrors when major changes were made.

Packages are now kept in a large "pool", structured according to the name of the source package. To make this manageable, the pool is subdivided by section (main, contrib, and non-free) and by the first letter of the source package name. These directories contain several files: the binary packages for each architecture, and the source packages from which the binary packages were generated.

You can find out where each package is placed by executing a command like apt-cache showsrc mypackagename and looking at the "Directory:" line. For example, the apache packages are stored in pool/main/a/apache/. Since there are so many lib* packages, these are treated specially: for instance, libpaper packages are stored in pool/main/libp/libpaper/.

The dists directories are still used for the index files used by programs like apt.

Normally, you won't have to worry about any of this, as new apt and probably older dpkg-ftp will handle it seamlessly. If you want more information, see the RFC: implementation of package pools.

When the present-day Sid did not exist, the Debian archive site organization had one major flaw: there was an assumption that when an architecture was created in the current unstable/, it would be released when that distribution became the new stable. For many architectures that wasn't the case, with the result that those directories had to be moved at release time. This was impractical because the move would chew up lots of bandwidth.

The archive administrators worked around this problem for several years by placing binaries for unreleased architectures in a special directory called sid. When an architecture was released the first time there was a link from the current stable/ to sid/, and from then on they were created inside the unstable/ tree as usual. This layout was somewhat confusing to users.

With the advent of package pools (see The pool directory, Section 2.1.10) during the Woody distribution development, binary packages began to be stored in a canonical location in the pool, regardless of the distribution, so releasing a distribution no longer causes large bandwidth consumption on the mirrors (there is, however, a lot of gradual bandwidth consumption throughout the development process).

Uploaded packages are first located at http://incoming.debian.org/ after being checked to insure that they really come from a Debian developer (and are put in the DELAYED subdirectory in the case of a Non-Maintainer Upload (NMU)). Once a day, they are moved out of incoming/ to unstable/.

In an emergency, you may want to install packages from incoming/ before they reach unstable/.

While the most recent Debian distributions are kept under the debian directory on each Debian mirror site, archives for older Debian distributions such as Slink are kept on http://archive.debian.org/ or under the debian-archive directory on each Debian mirror site.

Older testing and unstable packages can be located at http://snapshot.debian.net/.

Within each of the major directory trees (dists/stable/main, dists/stable/contrib, dists/stable/non-free, dists/unstable/main, etc.), the binary package entries reside in subdirectories whose names indicate the chip architecture for which they were compiled.

• binary-all/, for packages which are architecture-independent. These include, for example, Perl scripts, or pure documentation.

• binary-platform/, for packages which execute on a particular binary platform.

Please note that the actual binary packages no longer reside in these directories, but in the top-level pool directory. The index files (Packages and Packages.gz) have been kept, though, for backwards compatibility.

For the actual binary architectures supported, see the Release Notes for each distribution. They can be located at the Release Notes sites for stable and testing.

Source code is included for everything in the Debian system. Moreover, the license terms of most programs in the system require that source code be distributed along with the programs, or that an offer to provide the source code accompany the programs.

Normally the source code is distributed in the source directories, which are parallel to all the architecture-specific binary directories, or more recently in the pool directory (see The pool directory, Section 2.1.10). To retrieve the source code without having to be familiar with the structure of the Debian archive, try a command like apt-get source mypackagename.

Some packages, notably pine, are only available in a source package due to their licensing limitations. (Recently the pine-tracker package has been provided to facilitate Pine installation.) The procedures described in Port a package to the stable system, Section 6.4.10 and Packaging, Section 13.10 provide ways to build a package manually.

Source code may or may not be available for packages in the contrib and non-free directories, which are not formally part of the Debian system.

Packages generally contain all of the files necessary to implement a set of related commands or features. There are two types of Debian packages:

• Binary packages, which contain executables, configuration files, man/info pages, copyright information, and other documentation. These packages are distributed in a Debian-specific archive format (see Debian package format, Section 2.2.2); they are usually distinguished by having a .deb file extension. Binary packages can be unpacked using the Debian utility dpkg; details are given in its manual page.

• Source packages, which consist of a .dsc file describing the source package (including the names of the following files), a .orig.tar.gz file that contains the original unmodified source in gzip-compressed tar format, and usually a .diff.gz file that contains the Debian-specific changes to the original source. The utility dpkg-source packs and unpacks Debian source archives; details are provided in its manual page.

Installation of software by the package system uses "dependencies" which are declared by the package maintainers. These dependencies are documented in the control file associated with each package. For example, the package containing the GNU C compiler (gcc) Depends on the package binutils which includes the linker and assembler. If a user attempts to install gcc without having first installed binutils, the package management system (dpkg) will print an error message that it also needs binutils, and stop installing gcc. (However, this facility can be overridden by the insistent user; see dpkg(8).) For additional details, see Package dependencies, Section 2.2.8 below.

Debian's packaging tools can be used to:

• manipulate and manage packages or parts of packages,

• aid the user in the splitting of packages that must be transmitted through a limited-size medium such as floppy disks,

• aid developers in the construction of package archives, and

• aid users in the installation of packages which reside on a remote Debian archive site.

A Debian "package", or a Debian archive file, contains the executable files, libraries, and documentation associated with a particular program suite or set of related programs. Normally, a Debian archive file has a filename that ends in .deb. [1]

The internals of this Debian binary package format are described in the deb(5) manual page. Because this internal format is subject to change (between major releases of Debian), always use dpkg-deb(1) for manipulating .deb files.

Through at least the Sarge distribution, all Debian archive files have been manipulable by the standard Unix commands ar and tar, even when dpkg commands are not available.

The Debian package filenames conform to the following convention:

     foo_ver-rev_arch.deb

where, usually, foo is the package name, ver is the upstream version number, rev is the Debian revision number, and arch is the target architecture. Files are easily renamed, of course. You can find out what package is really contained in any given file of name filename by running the following command:

     dpkg --info filename

The Debian revision number is specified by the Debian developer or by whoever built the package. A change in revision number usually indicates that some aspect of the packaging has changed.

Files that are intended to be changeable by the local administrator are kept in /etc/. Debian policy dictates that all changes to locally configurable files be preserved across package upgrades.

If a default version of a locally configurable file is shipped in the package itself then the file is listed as a "conffile". The package management system does not upgrade conffiles that have been changed by the administrator since the package was last installed without getting the administrator's permission. On the other hand, if the conffile has not been changed by the administrator then the conffile will be upgraded along with the rest of the package. This is almost always desirable and so it is advantageous to minimize changes to conffiles.

To list the conffiles belonging to a package run the following command:

     dpkg --status package

The list follows the "Conffiles:" line.

For more information about conffiles you can read the section of the Debian Policy Manual entitled "Configuration files". (See References, Section 15.1).

Debian maintenance scripts are executable scripts which are automatically run before or after a package is installed. Along with a file named control, all of these files are part of the "control" section of a Debian archive file.

The individual files are:

preinst

This script executes before its package is unpacked from its Debian archive (.deb) file. Many "preinst" scripts stop services for packages which are being upgraded until their installation or upgrade is completed (following the successful execution of the "postinst" script).

postinst

This script typically completes any required configuration of a package once it has been unpacked from its Debian archive (.deb) file. Often, "postinst" scripts ask the user for input, and/or warn the user that if he accepts default values, he should remember to go back and reconfigure the package as the situation warrants. Many "postinst" scripts then execute any commands necessary to start or restart a service once a new package has been installed or upgraded.

prerm

This script typically stops any daemons which are associated with a package. It is executed before the removal of files associated with the package.

postrm

This script typically modifies links or other files associated with a package, and/or removes files created by it. (Also see Virtual packages, Section 2.2.7.)

Currently all of the control files can be found in the directory /var/lib/dpkg/info. The files relevant to package foo begin with the name "foo" and have file extensions of "preinst", "postinst", etc., as appropriate. The file foo.list in that directory lists all of the files that were installed with the package foo. (Note that the location of these files is a dpkg internal, and may be subject to change.)

Each Debian package is assigned a priority by the distribution maintainers, as an aid to the package management system. The priorities are:

• Required packages are necessary for the proper functioning of the system.

  This includes all tools that are necessary to repair system defects. You must not remove these packages or your system may become totally broken and you may not even be able to use dpkg to restore things. Systems with only the Required packages are probably inadequate for most purposes, but they do have enough functionality to allow the sysadmin to boot and install more software.

• Important packages should be found on any Unix-like system.

  Other packages without which the system will not run well or be usable will carry this priority. This does not include Emacs or X11 or TeX or any other large applications. These packages only constitute the bare infrastructure.

• Standard packages are standard on any Linux system, including a reasonably small but not too limited character-mode system.

  This is what will install by default if users do not select anything else. "Standard" does not include many large applications, but it does include Emacs (this is more a piece of infrastructure than an application) and a reasonable subset of TeX and LaTeX (if this turns out to be possible without X).

• Optional packages include all those that you might reasonably want to install even if you are unfamiliar with them, and if you don't have specialized requirements.

  This includes X11, a full TeX distribution, and lots of applications.

• Extra packages either conflict with others with higher priorities, have little use to users who are unfamiliar with them, or have specialized requirements that make them unsuitable for "Optional".

Please note the differences among "Priority: required", "Section: base" and "Essential: yes" in the package description. "Section: base" means that this package is installed before everything else on a new system. Most of the packages in "Section: base" have the "Priority: required" or at least "Priority: important", and many of them are tagged with "Essential: yes". "Essential: yes" means that this package requires to specify an extra force option to the package management system such as dpkg when removing from the system. For example, libc6, mawk, and makedev are "Priority: required" and "Section: base" but are not "Essential: yes".

A virtual package is a generic name that applies to any one of a group of packages, all of which provide similar basic functionality. For example, both the tin and trn programs are news readers, and either one should therefore satisfy the need of a program that requires a news reader on the system in order to be useful. They are therefore both said to Provide the "virtual package" called news-reader.

Similarly, many packages such as exim, exim4, sendmail, and postfix, provide the functionality of a mail transport agent. They are therefore said to Provide the virtual package mail-transport-agent. If either one is installed, then any program that Depends on the installation of a mail transport agent will be satisfied by the existence of this virtual package.

Debian has a mechanism such that, if more than one package which Provides the same virtual package is installed on a system, the system administrator can set one as the preferred package. The relevant command is update-alternatives, and is described further in Alternative commands, Section 6.5.3.

The Debian packaging system handles dependency declarations which are used to express the fact that one package requires another package to be installed in order to work or in order to work better.

• Package A Depends on Package B if B absolutely must be installed in order to use A. In some cases, A Depends not only on B, but on a specific version of B. In this case, the version dependency is usually a lower limit, in the sense that A Depends on any version of B more recent than some specified version.

• Package A Recommends Package B if the package maintainer judges that most users would not want A without also having the functionality provided by B.

• Package A Suggests Package B if B contains files that are related to and enhance the functionality of A. The same relationship is expressed by declaring that Package B Enhances Package A.

• Package A Conflicts with Package B when A will not operate properly if B is installed on the system. "Conflicts" status is often combined with "Replaces".

• Package A Replaces Package B when files installed by B are removed or overwritten by files in A.

• Package A Provides Package B when all of the files and functionality of B are incorporated into A.

More detailed information on the use of each these terms can be found in the Packaging Manual and the Policy Manual.

Note that aptitude and dselect have more fine-grained control over packages specified by Recommends and Suggests than apt-get, which simply pulls all the packages specified by Depends and leaves all the packages specified by Recommends and Suggests. Both programs in modern form use APT as their back end.

dpkg always configures a package upon which another package Depends before it configures the package that Depends on it. However, dpkg normally unpacks archive files in arbitrary order, independently of dependencies. (Unpacking consists of extracting files from the archive file and putting them in the right place.) If, however, a package Pre-Depends on another then the other package is unpacked and configured before the one that Pre-Depends is even unpacked. [2] The use of this dependency is kept to a minimum.

Package status can be "unknown", "install", "remove", "purge", or "hold". These "want" flags indicate what the user wanted to do with a package (either by making choices in the "Select" section of dselect, or by directly invoking dpkg).

Their meanings are:

• unknown - the user has never indicated whether he wants the package.

• install - the user wants the package installed or upgraded.

• remove - the user wants the package removed, but does not want to remove any existing configuration files.

• purge - the user wants the package to be removed completely, including its configuration files.

• hold - the user wants this package not to be processed, i.e., he wants to keep the current version with the current status, whatever that is.

There are two mechanisms for holding back packages from an upgrade, through dpkg, or, beginning with Woody, through APT.

With dpkg, first export the list of package selections:

     dpkg --get-selections \* > selections.txt

Then edit the resulting file selections.txt, changing the line containing the package you wish to hold, e.g. libc6, from this:

     libc6                       install

to this:

     libc6                       hold

Save the file, and reload it into dpkg database with:

     dpkg --set-selections < selections.txt

Or, if you know the package name to hold, simply run:

     echo libc6 hold | dpkg --set-selections

This procedure holds packages at the install process of each package file.

The same effect can be obtained through dselect. Simply enter the [S]elect screen, find the package you wish to hold in its present state, and press the `=' key (or `H'). The changes will take effect immediately after you exit the [S]elect screen.

The APT system in the Woody distribution has a new alternative mechanism for holding packages during the archive retrieval process using Pin-Priority. See the manual page apt_preferences(5), along with http://www.debian.org/doc/manuals/apt-howto/ or the apt-howto package.

Source packages are distributed in a directory called source, and you can either download them manually, or use

     apt-get source foo

to fetch them (see the apt-get(8) manual page on how to set up APT for doing that).

For a package foo, you will need all of foo_*.dsc, foo_*.tar.gz, and foo_*.diff.gz to compile the source (note: there is no .diff.gz for a Debian native package).

Once you have them, if you have the dpkg-dev package installed, the command

     $ dpkg-source -x foo_version-revision.dsc

will extract the package into a directory called foo-version.

Issue the following command to build the binary package:

     $ cd foo-version
     $ su -c "apt-get update ; apt-get install fakeroot"
     $ dpkg-buildpackage -rfakeroot -us -uc

Then,

     # su -c "dpkg -i ../foo_version-revision_arch.deb"

to install the newly built package. See Port a package to the stable system, Section 6.4.10.

For detailed information on creating new packages, read the New Maintainers' Guide, available in the maint-guide package, or at http://www.debian.org/doc/manuals/maint-guide/.

This is the main program for manipulating package files; read dpkg(8) for a full description.

dpkg comes with several primitive supplemental programs.

• dpkg-deb: Manipulate .deb files. dpkg-deb(1)

• dpkg-ftp: An older package file retrieval command. dpkg-ftp(1)

• dpkg-mountable: An older package file retrieval command. dpkg-mountable(1)

• dpkg-split: Splits a large package into smaller files. dpkg-split(1)

dpkg-ftp and dpkg-mountable have been superseded by the introduction of the APT system.

APT (the Advanced Packaging Tool) is an advanced interface to the Debian packaging system consisting of several programs whose names typically begin with "apt-". apt-get, apt-cache, and apt-cdrom are the command-line tools for handling packages. These also function as the user's "back end" programs to other tools, such as dselect and aptitude. Currently aptitude is the preferred tool for system maintenance.

For more information, install packages apt and aptitude and read aptitude(8), apt-get(8), apt-cache(8), apt-cdrom(8), apt.conf(5), sources.list(5), and apt_preferences(5).

An alternative source of information is the APT HOWTO. This can be installed by apt-howto at file:///usr/share/doc/Debian/apt-howto/.

apt-get upgrade and apt-get dist-upgrade pull only the packages listed under "Depends:" and overlook all the packages listed under "Recommends:" and "Suggests:". To avoid this, use dselect.

This program is a menu-driven user interface to the Debian package management system. It is particularly useful for first-time installations and large-scale upgrades. See dselect, Section 6.2.4.

For more information, read dselect Documentation for Beginners.

The kernel (filesystem) in Debian systems supports replacing files even while they're being used. When packages are upgraded any services provided by those packages are restarted if they are configured to run in the current runlevel. The Debian system does not require use of the single-user mode to upgrade a running system.

If you have manually downloaded package files to your disk (which is not absolutely necessary, see above for the description of dpkg-ftp or APT), then after you have installed the packages, you can remove the .deb files from your system.

If APT is used, these files are cached in the /var/cache/apt/archives directory. You may erase them after installation (apt-get clean) or copy them to another machine's /var/cache/apt/archives directory to save downloading during subsequent installations.

dpkg keeps a record of the packages that have been unpacked, configured, removed, and/or purged, but does not (currently) keep a log of terminal activity that occurred while a package was being so manipulated.

The simplest way to work around this is to run your dpkg, dselect, apt-get, etc., sessions within the script(1) program.

Like all Unixes, Debian boots up by executing the program init. The configuration file for init (which is /etc/inittab) specifies that the first script to be executed should be /etc/init.d/rcS.

What happens next depends on whether the sysv-rc package or the file-rc package is installed. The following assumes that the sysv-rc package is installed. (file-rc contains its own /etc/init.d/rcS script and uses a file instead of symlinks in rc directories to control which services are started in which runlevels.)

The /etc/init.d/rcS file from the sysv-rc package runs all of the scripts in /etc/rcS.d/ in order to perform initialization such as checking and mounting file systems, loading modules, starting the network services, setting the clock, and so on. Then, for compatibility, it also runs all the files (except those with a `.' in the filename) in /etc/rc.boot/. The latter directory is reserved for system administrator use, and using it is deprecated. See System initialization, Section 9.1 and System run levels and init.d scripts in the Debian Policy Manual for more info.

Debian does not use a BSD-style rc.local directory.

After completing the boot process, init starts all services that are configured to run in the default runlevel. The default runlevel is given by the entry for id in /etc/inittab. Debian ships with id=2.

Debian uses the following runlevels:

• 1 (single-user mode),

• 2 through 5 (multiuser modes), and

• 0 (halt the system),

• 6 (reboot the system).

Runlevels 7, 8, and 9 can also be used but their rc directories are not populated when packages are installed.

Switch runlevels using the telinit command.

When entering a runlevel all scripts in /etc/rcrunlevel.d/ are executed. The first letter in the name of the script determines the way in which the script is run: scripts whose names begin with K are run with the argument stop. Scripts beginning with S are run with the argument start. The scripts are run in the alphabetical order of their names; thus "stop" scripts are run before "start" scripts and the two-digit numbers following the K or S determine the order in which the scripts are run.

The scripts in /etc/rcrunlevel.d are in fact just symbolic links back to scripts in /etc/init.d/. These scripts also accept "restart" and "force-reload" as argument; the latter methods can be used after a system has been booted in order to restart services or force them to reload their configuration files.

For example:

     # /etc/init.d/exim4 force-reload

Customizing runlevels is an advanced system administration task. The following advice holds for most services.

To enable service service in runlevel R create the symbolic link /etc/rcR.d/Sxyservice with target ../init.d/service. The sequence number xy should be the sequence number that was assigned to the service when the package was installed.

To disable the service, rename the symbolic link so that its name begins with a K instead of with an S and its sequence number is 100 minus xy.

It is convenient to use a runlevel editor such as sysv-rc-conf or ksysv for these purposes.

It is possible to delete the S symlink for a service in a particular runlevel directory instead of renaming it. This does not disable the service but leaves it in a "floating" state as far as the sysv-rc init system is concerned: on runlevel changes the service will be neither started nor stopped but will be left as it was, whether running or not running. Note, however, that a service left in such a floating state will be started if its package is upgraded whether or not it was running before the upgrade. This is a known shortcoming of the current Debian system. Note also that you should retain a service's K symlinks in runlevels 0 and 6. If you delete all the symlinks for a service then on upgrade the service's package will restore the symlinks to their factory default state.

It is not advisable to make any changes to symlinks in /etc/rcS.d/.

One has to understand the Debian policy with respect to headers.

The Debian C libraries are built with the most recent stable releases of the kernel headers.

For example, the Debian-1.2 release used version 5.4.13 of the headers. This practice contrasts with the Linux kernel source packages distributed at all Linux FTP archive sites, which use even more recent versions of the headers. The kernel headers distributed with the kernel source are located in /usr/include/linux/include/.

If you need to compile a program with kernel headers that are newer than those provided by libc6-dev, then you must add -I/usr/src/linux/include/ to your command line when compiling. This came up at one point, for example, with the packaging of the automounter daemon (amd). When new kernels changed some internals dealing with NFS, amd needed to know about them. This required the inclusion of the latest kernel headers.

Users who wish to (or must) build a custom kernel are encouraged to download the package kernel-package. This package contains the script to build the kernel package, and provides the capability to create a Debian kernel-image package just by running the command

     # make-kpkg kernel_image

in the top-level kernel source directory. Help is available by executing the command

     # make-kpkg --help

and through the manual page make-kpkg(1) and The Linux kernel under Debian, Chapter 7.

Users must separately download the source code for the most recent kernel (or the kernel of their choice) from their favorite Linux archive site, unless a kernel-source-version package is available (where version stands for the kernel version). The Debian initrd boot script requires a special kernel patch called initrd; see http://bugs.debian.org/149236.

Detailed instructions for using the kernel-package package are given in the file /usr/share/doc/kernel-package/README.gz.

Debian's modconf package provides a shell script (/usr/sbin/modconf) which can be used to customize the configuration of modules. This script presents a menu-based interface, prompting the user for particulars on the loadable device drivers in his system. The responses are used to customize the file /etc/modules.conf (which lists aliases, and other arguments that must be used in conjunction with various modules) through files in /etc/modutils/, and /etc/modules (which lists the modules that must be loaded at boot time).

Like the (new) Configure.help files that are now available to support the construction of custom kernels, the modconf package comes with a series of help files (in /usr/share/modconf/) which provide detailed information on appropriate arguments for each of the modules.

The kernel-image-NNN.prerm script checks to see whether the kernel you are currently running is the same as the kernel you are trying to de-install. Therefore you can safely remove unwanted kernel image packages using this command:

     # dpkg --purge --force-remove-essential kernel-image-NNN

(Replace NNN with your kernel version and revision number, of course.)

Linux is compatible with most PC hardware and can be installed to almost any system. For me it was as easy as installing Windows 95/98/Me. The hardware compatibility list just seems to keep growing.

If you have a laptop PC, check Linux on Laptops for installation pointers by brand and model.

My recommendation for desktop PC hardware is "Just be conservative":

• SCSI rather than IDE for work, IDE/ATAPI HD for private use.

• IDE/ATAPI CD-ROM (or CD-RW).

• PCI rather than ISA, especially for the network card (NIC).

• Use a cheap NIC. Tulip for PCI, NE2000 for ISA are good.

• Avoid PCMCIA (notebook) as your first Linux install.

• No USB keyboard, mouse, ... unless you want a challenge.

If you have a slow machine, yanking out the hard drive and plugging it into another faster machine for installation is a good idea.

During installation, one will be asked to identify the hardware or chip set of the PC. Sometimes that information may not seem easy to find. Here is one method:

• Open your PC's case and look inside.
• Record the product ID codes on the large chips on the graphics card, network card, chip near serial ports, chip near IDE ports.
• Record card names printed on the back of the PCI and ISA cards.

The following commands on a Linux system should give some idea of actual hardware and configuration.

     $ pager /proc/pci
     $ pager /proc/interrupts
     $ pager /proc/ioports
     $ pager /proc/bus/usb/devices

These commands can be run during the install process from the console screen by pressing Alt-F2.

After the initial installation, with the installation of optional packages such as pciutils, usbutils, and lshw, you can obtain more extensive system information.

     $ lspci -v |pager
     $ lsusb -v |pager
     # lshw  |pager

Typical uses of interrupts:

• IRQ0: timer output (8254)

• IRQ1: keyboard controller

• IRQ2: cascade to IRQ8–IRQ15 on PC-AT

• IRQ3: secondary serial port (io-port=0x2F8) (/dev/ttyS1)

• IRQ4: primary serial port (io-port=0x3F8) (/dev/ttyS0)

• IRQ5: free [sound card (SB16: io-port=0x220, DMA-low=1, DMA-high=5)]

• IRQ6: floppy disk controller (io-port=0x3F0) (/dev/fd0, /dev/fd1)

• IRQ7: parport (io-port=0x378) (/dev/lp0)

• IRQ8: rtc

• IRQ9: software interrupt (int 0x0A), redirect to IRQ2

• IRQ10: free [network interface card (NE2000: io-port=0x300)]

• IRQ11: free [(SB16-SCSI: io-port=0x340, SB16-IDE: io-port=0x1E8,0x3EE)]

• IRQ12: PS/2 Mouse

• IRQ13: free (was 80287 math coprocessor)

• IRQ14: primary IDE controller (/dev/hda, /dev/hdb)

• IRQ15: secondary IDE controller (/dev/hdc, /dev/hdd)

For old non-PnP ISA cards, you may want to set IRQ5, IRQ10, and IRQ11 as non-PnP from the BIOS.

For USB devices, device classes are listed in /proc/bus/usb/devices as Cls=nn:

• Cls=00 : Unused

• Cls=01 : Audio (speaker etc.)

• Cls=02 : Communication (MODEM, NIC, ...)

• Cls=03 : HID (Human Interface Device: KB, mouse, joystick)

• Cls=07 : Printer

• Cls=08 : Mass storage (FDD, CD/DVD drive, HDD, Flash, ...)

• Cls=09 : Hub (USB hub)

• Cls=255 : Vendor specific

If the device class of a device is not 255, Linux supports the device.

Hardware information can also be obtained from other OSs:

Install another commercial Linux distribution. Hardware detection on those tends to be better than on Debian as of now. (This situation should even out once debian-installer is introduced with Sarge.)

Install Windows. Hardware configuration can be obtained by right-clicking "My Computer" to get to Properties / Device Manager. Record all resource information such as IRQ, I/O port address, and DMA. Some old ISA cards may need to be configured under DOS and used accordingly.

"Lilo is limited to 1024 cylinders." Wrong!

The newer lilo used after Debian Potato has lba32 support. If the BIOS of your motherboard is recent enough to support lba32, lilo should be able to load beyond the old 1024-cylinder limitation.

Just make sure to add a line reading "lba32" somewhere near the beginning of your lilo.conf file if you have kept an old lilo.conf. See file:///usr/share/doc/lilo/Manual.txt.gz.

The new boot loader grub from the GNU Hurd project can be installed on a Debian Woody system:

     # apt-get update
     # apt-get install grub-doc
     # mc file:///usr/share/doc/grub-doc/html/
     ... read contents
     # apt-get install grub
     # pager file:///usr/share/doc/grub/README.Debian.gz
     ... read it :)

To edit the GRUB menu, edit /boot/grub/menu.lst. See Setting GRUB boot parameters, Section 8.1.6 for how to set boot parameters during the boot process since it is slightly different from lilo configuration.

For Potato, I liked the IDEPCI disk set for normal install to a desktop. For Woody, I like the bf2.4 boot disk set. They both use a version of boot-floppies to create boot floppies.

If you have a PCMCIA network card, you need to use the standard boot disk set (largest number of floppies but all driver modules available) and configure the NIC in the PCMCIA setup; do not try to set up an NIC card in the standard network setup dialog.

For special systems, you may need to create a custom rescue disk. This can be done by replacing the kernel image named "linux" on the Debian rescue disk by overwriting it with another compressed kernel image compiled off-site for the machine. Details are documented in readme.txt on the rescue disk. The rescue floppy uses the MS-DOS filesystem, so you can use any system to read and edit it. This should make life easier for people with a special network card, etc.

For Sarge, debian-installer and/or pgi is expected to be used for creating boot floppies.

Follow the official instructions found in http://www.debian.org/releases/stable/installmanual or http://www.debian.org/releases/testing/installmanual (work in progress, sometimes this may not exist).

If you are installing a system using boot-floppies in the testing distribution, you may need to open a console terminal during the install process by pressing Alt-F2 and manually edit /etc/apt/sources.list entries, changing "stable" to "testing" to adjust APT sources.

I tend to install lilo into places like /dev/hda3, while installing mbr into /dev/hda. This minimizes the risk of overwriting boot information.

Here is what I choose during the install process.

• MD5 passwords "yes"

• shadow passwords "yes"

• Install "advanced" (dselect **) and select

  • Exclude emacs (if selected), nvi, tex, telnet, talk(d);

  • Include mc, vim, either one of nano-tiny or elvis-tiny.

    See dselect, Section 6.2.4. Even if you are an Emacs fan, avoid it now and be content with nano during install. Also avoid installing other large packages such as TeX (Potato used to do this) at this stage. See Rescue editors, Section 11.2 for the reason for installing nano-tiny or elvis-tiny here.

• All configuration questions = "y" (replace current) during each package install dialog.

• exim: select 2 for machine since I send mail through my ISP's SMTP server.

For more information on dselect, see dselect, Section 6.2.4.

Example of LAN configuration (C subnet: 192.168.1.0/24):

     Internet
        |
        +--- External ISP provides POP service (accessed by fetchmail)
        | 
       Access point ISP provides DHCP service and SMTP relay service
        |                     :
       Cable modem         (Dialup)
        |                     :
     LAN Gateway machine external port: eth0 (IP given by ISP's DHCP)
      use old notebook PC (IBM Thinkpad, 486 DX2 50MHz, 20MB RAM)
      run Linux 2.4 kernel with ext3 filesystem.
      run "ipmasq" package (with stronger patch, NAT, and firewall)
      run "dhcp-client" package configured for eth0 (override DNS setting)
      run "dhcp" package configured for eth1
      run "exim" as the smarthost (mode 2)
      run "fetchmail" with a long interval (fallback)
      run "bind" as the cache nameserver for Internet from LAN
                 as authoritative nameserver for LAN domain from LAN
      run "ssh" on port 22 and 8080 (connect from anywhere)
      run "squid" as the cache server for the Debian archive (for APT)
     LAN Gateway machine internal port: eth1 (IP = 192.168.1.1, fixed)
                              |
              +--- LAN Switch (100base T) ---+
              |                              |
     Some fixed IP clients on LAN     Some DHCP clients on LAN
     (IP = 192.168.1.2-127, fixed)    (IP = 192.168.1.128-200, dynamic)

See Network configuration, Chapter 10 for the details of configuring the network. See Building a gateway router, Section 10.12 for the details of configuring the LAN gateway server.

In order to have a consistent feel across machines, the first few accounts are always the same in my system.

I always create a first user account with a name like "admin" (uid=1000). I forward all root email there. This account is given membership in the adm group (see "Why GNU su does not support the wheel group", Section 9.2.2), which can be given a good amount of root privilege through su using PAM or the sudo command. See Add a user account, Section 4.1.3 for details.

Following are rough guidelines for DRAM.

       4MB:  Bare minimum for Linux kernel to function.
      16MB:  Minimum for reasonable console system.
      32MB:  Minimum for simple X system.
      64MB:  Minimum for X system with GNOME/KDE.
     128MB:  Comfortable for X system with GNOME/KDE.
     256MB (or more): Why not if you can afford it?  DRAM is cheap.

Using the boot option mem=4m (or lilo append="mem=4m") will show how the system would perform with 4MB of memory installed. A lilo boot parameter is needed for a system containing more than 64MB of memory with an old BIOS.

I use the following guidelines for swap space:

• Each swap partition is < 128MB (if using an old 2.0 kernel), < 2GB (with recent kernels)

• Total = either (1 to 2 times installed RAM) or (128MB to 2GB) as a guideline

• Spread them on different drives and mount all of them with sw,pri=1 options in /etc/fstab. This ensures that the kernel does a striping RAID of the swap partitions and offers the maximum swap performance.

• Use a central portion of the hard disk when possible.

Even if you never need it, some swap space (128MB) is desirable so the system will slow down before it crashes hard with a program which leaks memory.

Make sure you have all required kernel functions activated through kernel compile time configuration or modules:

• Under "Input core support":

  • "Input core support" (CONFIG_INPUT, input.o),

  • "Mouse support" (CONFIG_INPUT_MOUSEDEV, mousedev.o),

• Under "USB support":

  • "Support for USB" (CONFIG_USB, usbcore.o),

  • "Preliminary USB device filesystem" (CONFIG_USB_DEVICEFS),

  • "UHCI" or "OHCI" (CONFIG_USB_UHCI || CONFIG_USB_UHCI_ALT || CONFIG_USB_OHCI, usb-uhci.o || uhci.o || usb-ohci.o),

  • "USB Human Interface Device (full HID) support" (CONFIG_USB_HID, hid.o), and

  • "HID input layer support" (CONFIG_USB_HIDINPUT)

Here, lower case names are module names.

If you're not using devfs, create a device node /dev/input/mice with major 13 and minor 63 as follows:

     # cd /dev
     # mkdir input
     # mknod input/mice c 13 63

For typical scroll USB mice, configuration combinations should be:

     /etc/gpm.conf            | /etc/X11/XF86Config-4
     =========================+======================================
     device=/dev/input/mice   | Section "InputDevice"
     responsiveness=          |  Identifier "Generic Mouse"
     repeat_type=raw          |  Driver     "mouse"
     type=autops2             |  Option     "SendCoreEvents" "true"
     append=""                |  Option     "Device"   "/dev/input/mice"
     sample_rate=             |  Option     "Protocol" "IMPS/2"
                              |  Option     "Buttons" "5"
                              |  Option  "ZAxisMapping" "4 5"
                              | EndSection

See the Linux USB Project for more information.

Although the touchpad on a laptop computer emulates a 2-button PS/2 mouse as the default behavior, the tpconfig package enables full control of the device. For example, setting OPTIONS="--tapmode=0" in /etc/default/tpconfig will disable pesky "click by tap" behavior. Set /etc/gpm.conf as follows to use both touchpad and USB external mouse on the console:

     device=/dev/psaux
     responsiveness=
     repeat_type=ms3
     type=autops2
     append="-M -m /dev/input/mice -t autops2"
     sample_rate=