Here are some key points for package configuration on the Debian system:

	Warning
	Do not install packages from random mixture of suites. It will likely break the package consistency which requires deep system management knowledge, such as compiler ABI, library version, interpreter features, etc.

The newbie Debian system administrator should stay with the stable release of Debian while applying only security updates. I mean that some of the valid actions are better avoided, as a precaution, until you understand the Debian system very well:

The non-compatible effects caused by above actions to the Debian package management system may leave your system unusable.

The serious Debian system administrator who runs mission critical servers, should use extra precautions:

Despite my warnings above, I know many readers of this document wish to run the "testing" or "unstable" suites of Debian as their main Desktop system since they work very well for self-administered Desktop environments. Because they are updated frequently, they offer the latest features.

	Caution
	For your production server, the "stable" suite with the security updates is recommended. The same can be said for desktop PCs on which you can spend limited administration efforts, e.g. for your mother's PC.

It takes no more than simply setting the distribution string in the /etc/apt/sources.list to the suite: "testing" or "unstable"; or the codename: "lenny" or "sid". This will let you live the life of eternal upgrades.

The use of "testing" or "unstable" is a lot of fun but comes with some risks. Even though the "unstable" suite of Debian system looks very stable for most of the times, there have been some package problems on the "testing" and "unstable" suite of Debian system and a few of them were not so trivial to resolve. It may be quite painful for you. Sometimes, you may have a broken package or missing functionality for a few weeks.

Here are some ideas to ensure quick and easy recovery from bugs in Debian packages:

(If you can not do any one of these precautionary actions, you are probably not ready for the "testing" and "unstable" suites.)

Enlightenment with the following will save a person from the eternal karmic struggle of upgrade hell and let him reach Debian nirvana.

Let's look into the Debian archive from a system user's perspective. For the typical HTTP access, the archive is specified in the /etc/apt/sources.list file as, e.g. for the current "stable" == "etch" system:

deb http://ftp.us.debian.org/debian/ etch main contrib non-free
deb-src http://ftp.us.debian.org/debian/ etch main contrib non-free

deb http://security.debian.org/ etch/updates main contrib
deb-src http://security.debian.org/ etch/updates main contrib

Here, I tend to use codename "etch" instead of suite name "stable" to avoid surprises when the next "stable" is released.

The meaning of this is described in "man 5 sources.list" and key points are:

The "deb-src" lines can safely be omitted (or commented out by placing "#" at the start of the line) if it is just for aptitude which does not access source related meta data. It will speed up the updates of the archive meta data. The URL can be "http://", "ftp://", "file://", ....

	Tip
	If "sid" is used in the above example instead of "etch", the "deb: http://security.debian.org/ ..." line for security updates in the /etc/apt/sources.list is not required. Security updates are only available for "stable" and "testing" (i.e., "etch" and "lenny").

Here are the lists of URL of the Debian archive sites and suite or codename used in the configuration file:

	Tip
	For the Debian system with the "stable" and "testing" suites, it is a good idea to include lines with http://security.debian.org/ in the /etc/apt/sources.list to enable access to the archive for security updates as in the example above.

Caution

Only pure stable release with security updates provides the best stability. Running mostly stable release mixed with some packages from testing or unstable release is riskier than running pure unstable release. If you really need the latest version of some programs under stable release, please use packages from the debian-volatile project and http://backports.org/ (see: Section 3.4.4, “Volatile and Backports.org”) services. These services must be used with extra care.

Caution

You should basically list only one of "stable", "testing", or "stable" suites in the "deb" line. If you list any combination of "stable", "testing", and "stable" suites in the "deb" line, APT programs slow down while only the latest archive is effective. Multiple listing makes sense for these when the /etc/apt/preferences file is used with clear objectives (see: Section 3.4.3, “Tweaking candidate version”).

Each Debian archive consists of 3 components. Components are alternatively called categories in "Debian Policy" or areas in "Debian Social Contract". The component is grouped by the compliance to "The Debian Free Software Guidelines " (DFSG):

Here the number of packages in the above is for the amd64 architecture. Strictly speaking, only the main component archive shall be considered the Debian system.

The Debian archive organization can be studied best by pointing your browser to the each archive URL appended with dists or pool.

The distribution is referred by two ways, the suite or codename. The word distribution is alternatively used as the synonym to the suite in many documentation. The relationship between the suite and the codename can be summarized as:

The history of codenames are described in Debian FAQ: 6.3.1 Which other codenames have been used in the past?

In the stricter Debian archive terminology, the word "section" is specifically used for the categorization of packages by the application area. (Although, the word "main section" may sometimes be used to describe the Debian archive section which provides the main component.)

Every time a new upload is done by the Debian developer (DD) to the "unstable" archive (via incoming processing), DD is required to ensure uploaded packages to be compatible with the latest set of packages in the latest "unstable" archive.

If DD breaks this compatibility intentionally for important library upgrade etc, there is usually announcement to the debian-devel mailing list etc.

Before a set of packages are moved by the Debian archive maintenance script from the "unstable" archive to the "testing" archive, the archive maintenance script not only checks the maturity (about 10 days old) and the status of the RC bug reports for the packages but also tries to ensure them to be compatible with the latest set of packages in the "testing" archive. This process makes the "testing" archive very current and usable.

Through the gradual archive freeze process led by the release team, the "testing" archive will be matured to make it completely consistent and bug free with some manual interventions. Then the new "stable" release is created by assigning the codename for the old "testing" archive to the new "stable" archive and creating the new codename for the new "testing" archive. The initial contents of the new "testing" archive is exactly the same as that of the newly released "stable" archive.

Both the "unstable" and the "testing" archives may suffer temporary glitches due to:

So if you ever decide to use these archives, you should be able to fix or work around these kinds of glitches.

	Tip
	When tracking the "testing" archive, problem caused by a removed package is usually worked around by installing corresponding package from the "unstable" archive which is uploaded for bug fix.

See Debian Policy Manual for definition of:

The Debian system offers a consistent set binary packages through its versioned binary dependency declaration mechanism through the control file fields. Here is a bit over simplified definition for them.

	Note
	Please note that defining, Provides, Conflicts and Replaces simultaneously to an virtual package is the sane configuration. This ensures that only one real package providing this virtual package can be installed at any one time.

The official definition including source dependency can be found in the Policy Manual: Chapter 7 - Declaring relationships between packages.

The simplified event flow of the upgrade and the install are:

The package removal process has 2 distinct stages and the simplified event flow of them are:

Here, I intentionally skipped technical details for the sake of big picture.

Aptitude is the current preferred package management tool for the Debian system. It can be used as the commandline alternative to apt-get/apt-cache and also as the full screen menu-driven tool alternative to dselect.

The selection of a package in aptitude not only pulls in packages which are defined in its "Depends:" list but also defined in the "Recommends:" list if the menu "F10 -> Options -> Dependency handling" is set accordingly. These auto installed packages are removed automatically if they are no longer needed under aptitude.

	Note
	Before the "lenny" release, apt-get and other standard APT tools did not offer the autoremove functionality.

For the package management, you start aptitude interactive mode from the console shell prompt as:

$ sudo aptitude -u
Password:

This will update the local copy of the archive information and display the package list in the full screen with menu. Aptitude places its configuration at $HOME/.aptitude/config.

	Tip
	If you want to use root's configuration instead of user's one, use "sudo -H aptitude ..." instead of "sudo aptitude ..." in the above expression.

3.1.7.1. Key bindings of aptitude

Notable key strokes to browse status of packages and to set "planned action" on them in this full screen mode are:

Table 3.6.  List of key bindings for aptitude.

key	key binding
F10 or in a terminal window Ctrl-t	Menu
?	Display help for keystroke (more complete listing)
F10 -> Help -> User's Manual	Display User's Manual
u	Update package archive information
+	Mark the package for the upgrade or the install
-	Mark the package for the remove (keep conffiles)
_	Mark the package for the purge (remove conffiles)
=	Place the package on hold
U	Mark all upgradable packages (function as dist-upgrade)
g	Start downloading and installing selected packages
q	Quit current screen and save changes
x	Quit current screen and discard changes
Enter	View information about a package
C	View a package's changelog
l	Change the limit for the displayed packages
/	Search for the first match
\	Repeat the last search

The file name specification of the command line and the menu prompt after pressing "l" and "/" take the aptitude regex as described below. For the input to the menu prompt and argument to "aptitude search" command, "~n" is prepended to match the package name with the pattern if the input does not start with "~" character.

	Tip
	You need to press "U" to get all the installed packages upgraded to the candidate version in the visual interface. Otherwise only the selected packages and certain packages with versioned dependency to them are upgraded to the candidate version.

3.1.7.2. Package views under aptitude

In the interactive full screen mode of aptitude(8), packages in the package list are displayed like this by default:

idA   libsmbclient                             -2220kB 3.0.25a-1  3.0.25a-2

Here, this line means from the left as:

• The "current state" flag (the first letter)

• The "planned action" flag (the second letter)

• The "automatic" flag (the third letter)

• The package name

• The change in disk space usage attributed to "planned action".

• The current version of the package.

• The candidate version of the package.

	Tip
	The full list of flags are given at the bottom of Help screen shown by pressing "?".

The candidate version is chosen according to the current local policy and preferences (see apt_preferences(5)).

Several types of package views are available under the menu "Views":

Table 3.7.  Views for aptitude.

view	categorization	status
Package View	See Table 3.8, “The categorization of standard aptitude views. ”. (default)	Good
Audit Recommendations	Packages which are recommended by some installed packages but not yet installed are listed.	Good.
Flat Package List	Packages are listed without categorization (for use with regex).	Good
Debtags Browser	Packages are categorized according to their debtags entries.	Very usable
Categorical Browser	Packages are categorized according to their category.	Deprecated (Use debtags!)

	Note
	Please help us improving tagging packages with debtags!

The standard "Package View" categorizes packages somewhat like dselect with few extra features. For switching distribution to a newer one can be achieved basically by

Table 3.8. The categorization of standard aptitude views.

category	organization
"Upgradable Packages"	Organized as section --> component --> package
"New Packages"	, ,
"Installed Packages"	, ,
"Not Installed Packages"	, ,
"Obsolete and Locally Created Packages"	, ,
"Virtual Packages"	You can pick a particular package from a set of packages with the same function.
"Tasks"	You can cherry pick particular packages from a set of packages of a task.

3.1.7.4. The aptitude regex formula

The aptitude regex formula is mutt-like extended ERE (see: Section 2.6.2, “Regular expressions”) and the meanings of the aptitude specific special match rule extensions are as below:

Table 3.11.  List of the aptitude regex formula.

meaning of the extended match rule	regex formula
match on package name	~n<regex_name>
match on description	~d<regex_description>
match on task name	~t<regex_task>
match on debtag	~G<regex_debtag>
match on maintainer	~m<regex_maintainer>
match on package section	~s<regex_section>
match on package version	~V<regex_version>
match archive	~A{sarge,etch,sid}
match origin	~O{debian,...}
match priority	~p{extra,important,optional,required,standard}
match essential packages	~E
match virtual packages	~v
match new packages	~N
match with pending action	~a{install,upgrade,downgrade,remove,purge,hold,keep}
match installed packages	~i
match installed packages with A-mark (auto installed package)	~M
match installed packages without A-mark (administrator selected package)	~i!~M
match installed and upgradable packages	~U
match removed but not purged packages	~c
match removed, purged or can-be-removed packages	~g
match with broken relation	~B<type>
match broken depends/predepends/conflict packages	~b
match packages whose control files define relation <type> to the <term> package	~D[<type>:]<term>
match packages whose control files define broken relation <type> to the <term> package	~DB[<type>:]<term>
match packages to which the <term> package defines relation <type>	~R[[<type>:]<term>
match packages to which the <term> package defines broken relation <type>	~RB[<type>:]<term>
match packages to which some other installed packages depend on	~R~i
match packages to which no other installed packages depend on	!~R~i
match packages to which some other installed packages depend or recommend on	~R~i|~Rrecommends:~i
match <term> package with filtered version	~S filter <term>
match all packages (true)	~T
match no packages (false)	~F

Here,

• regex part is the same ERE as the one used in typical Unix-like text tools using "^", ".*", "$" etc. as in egrep, awk and perl.

• relation <type> is one of (depends, predepends, recommends, suggests, conflicts, replaces, provides).

• the default relation type is "depends".

	Tip
	When <regex_pattern> is a null string, place "~T" immediately after the command.

Short cuts:

• "~P<term>" == "~Dprovides:<term>"

• "~C<term>" == "~Dconflicts:<term>"

• "...~W term" == "(...|term)"

Users familiar with mutt will pick up quickly, as mutt was the inspiration for the expression syntax. See "SEARCHING, LIMITING, AND EXPRESSIONS" in the "User's Manual" /usr/share/doc/aptitude/README.

Here are few examples of using aptitude.

$ aptitude search '~n(pam|nss).*ldap'
p libnss-ldap - NSS module for using LDAP as a naming service
p libpam-ldap - Pluggable Authentication Module allowing LDAP interfaces

# aptitude search '~c'

# aptitude purge '~c'

You can perform system wide upgrade to a newer release by changing contents of the /etc/apt/sources.list file pointing to a new release and running the "aptitude update; aptitude dist-upgrade" command.

To upgrade from "stable" to "testing" or "unstable", you replace "etch" in the /etc/apt/sources.list example of Section 3.1.4, “Debian archive basics” with "lenny" or "sid".

In reality, you may face some complications due to some package transition issues, mostly due to package dependencies. The larger the difference of the upgrade, the more likely you face larger troubles. For the transition from the old "stable" archive to the new "stable" after its release, you can read its new Release Notes and follow the exact procedure described in it to minimize troubles.

When you decide to move from "stable" to "testing" before its formal release, there are no Release Notes to help you. The difference between "stable" and "testing" could have grown quite large after the previous "stable" release and makes upgrade situation complicated.

You should make some precautionary moves while gathering latest information from mailing list and using common senses:

	Caution
	It is not wise to skip major Debian release when upgrading between "stable" releases.

	Caution
	In previous "Release Notes", GCC, Linux Kernel, initrd-tools, Glibc, Perl, APT tool chain, etc. have required some special attention for system wide upgrade.

For daily upgrade in "unstable", see Section 3.1.16, “Safeguard for package problems”.

Aptitude has advantages over other APT based packaging systems (apt-get, apt-cache, synaptic, ...):

For the old etch release version, synaptic also gives you the history log; apt-get did not but you can rely on the log of dpkg.

Anyway, aptitude is nice for interactive console use.

You can check package activity history in the log files.

Here are list of low-level package maintenance tasks for which aptitude is too high-level, plus the suggested tool.

Please note:

The grep-dctrl(1), grep-status(1), and grep-available(1) commands can be used to search any file which has the general format of a Debian package control file.

The "dpkg -S <file_name_pattern>" can be used search package names which contain files with the matching name installed by dpkg. But this overlooks files created by the maintainer scripts.

If you need to make more elaborate search on the dpkg meta data, you need to run "grep -e regex_pattern *" command in the /var/lib/dpkg/info/ directory. This will let you identify:

If you wish to look up package dependency recursively, you should use apt-rdepends(8).

Here are list of tasks for the advanced system maintenance such as creating and installing the backported and customized packages on the target system itself. For this kind of tasks, aptitude is not much of help and other lower level package and porting tools should be carefully used by the expert.

Please note:

	Tip
	See Section 13.9, “Making Debian package” for general packaging.

The installation of debsums package enables verification of installed package files against MD5sum values in the Packages file with debsums(1) command. See: Section 11.3.5, “The MD5 sum” for how MD5sum works.

Many user prefer to follow the unstable release of the Debian system for its new features and packages. This makes the system more prone to be hit by the critical package bugs.

The installation of the apt-listbugs package will provide safeguard to the critical bugs by checking Debian BTS automatically for critical bugs when upgrading with APT system.

The installation of the apt-listchanges package will provide important news in NEWS.Debian when upgrading with APT system.

You should read the fine official documentation. The first document to read is the Debian specific /usr/share/doc/<package_name>/README.Debian. Other documentation in /usr/share/doc/<package_name>/ should be consulted too. If you set shell as previously discussed, type:

$ cd <package_name>
$ pager README.Debian
$ mc

You may need to install the corresponding documentation package named with "-doc" suffix for detailed information.

If you are experiencing problems with a specific package, make sure to check out these sites first:

Search Google with search words including "site:debian.org".

When you file a bug report, please use reportbug command.

Downgrading from a later release of a package to an earlier one is not officially supported in Debian (see: Section 3.4.3, “Tweaking candidate version”). However, you may find that you have to downgrade a specific package in order to re-install a version of a package that works when a new version malfunctions. You may find these previous package files locally in /var/cache/apt/archives/ or remotely at http://snapshot.debian.net/. You need to make sure the consistency are kept.

The meta data files are stored under the dist/ on each Debian mirror sites, e.g., ftp://ftp.us.debian.org/debian/. Its archive structure can be browsed by the web browser. There are 6 types of key meta data:

In the recent archive, these meta data are stored as the compressed and differential files to reduce network traffic.

Each suites of the Debian archive has a top level Release file, e.g., ftp://ftp.us.debian.org/debian/dists/unstable/Release:

Origin: Debian
Label: Debian
Suite: unstable
Codename: sid
Date: Sat, 26 Jan 2008 20:13:58 UTC
Architectures: alpha amd64 arm hppa hurd-i386 i386 ia64 m68k mips mipsel powerpc s390 sparc
Components: main contrib non-free
Description: Debian x.y Unstable - Not Released
MD5Sum:
 e9f11bc50b12af7927d6583de0a3bd06 22788722 main/binary-alpha/Packages
 43524d07f7fa21b10f472c426db66168  6561398 main/binary-alpha/Packages.gz
...

	Note
	Here, you can find my rationale to use the "suite", "codeneme", and "components" in Section 3.1.4, “Debian archive basics”. The "distribution" is used when referring to both "suite" and "codeneme".

The integrity of the top level Release file is verified by cryptographic infrastructure called the secure apt.

The integrity of all the Packages and Sources files are verified by using MD5sum values in its top level Release file. The integrity of all package files are verified by using MD5sum values in the Packages and Sources files. See debsums(1) and Section 3.1.15, “Verify installed package files”.

Since the cryptographic signature verification is very CPU intensive process than the MD5sum value calculation, use of MD5sum value for each package while using cryptographic signature for the top level Release file provides the good security with the performance (see: Section 11.3, “Data security infrastructure”).

	Tip
	The archive level Release files are used for the rule of apt_preferences(5).

There are archive level Release files for all archive locations specified by "deb:" line in /etc/apt/sources.list, such as "ftp://ftp.us.debian.org/debian/dists/unstable/main/binary-amd64/Release" or "ftp://ftp.us.debian.org/debian/dists/sid/main/binary-amd64/Release":

Archive: unstable
Component: main
Origin: Debian
Label: Debian
Architecture: amd64

	Caution
	For Archive stanza, suite names ("stable", "testing", "unstable", ...) are used in the Debian archive while codenames ("dapper", "feisty", "gutsy", "hardy", "intrepid", ...) are used in the Ubuntu archive.

For some archives, such as "experimental", "volatile-sloppy", and "etch-backports", which contain packages which should not be installed automatically, there is an extra line, e.g., "ftp://ftp.us.debian.org/debian/dists/experimental/main/binary-amd64/Release":

Archive: experimental
Component: main
Origin: Debian
Label: Debian
NotAutomatic: yes
Architecture: amd64

Please note that for normal archives without "NotAutomatic: yes", the default Pin-Priority value is 500, while for special archives with "NotAutomatic: yes", the default Pin-Priority value is 1 (see apt_preferences(5) and Section 3.4.3, “Tweaking candidate version”).

When APT tools, such as aptitude, apt-get, synaptic, apt-file, auto-apt..., are used, we need to update the local copies of the meta data containing the Debian archive information. These local copies have file names corresponding to the specified distribution component and architecture names in the /etc/apt/sources.list (see: Section 3.1.4, “Debian archive basics”) under the /var/lib/apt/lists directory as: