When you want to configure an unknown package, you must proceed in stages. First, you should read what the package maintainer has documented. Reading /usr/share/doc/package/README.Debian will indeed allow you to learn of specific provisions made to simplify the use of the software. It is sometimes essential in order to understand the differences from the original behavior of the program, as described in the general documentation, such as howtos. Sometimes this file also details the most common errors in order for you to avoid wasting time on common problems.

Then, you should look at the software's official documentation — refer to the previous section to identify the various existing documentation sources. The command dpkg -L package gives a list of files included in the package; you can therefore quickly identify the available documentation (as well as the configuration files, located in /etc/). dpkg -s package produces the package headers and shows any possible recommended or suggested packages; in there, you can find documentation or a utility that will ease the configuration of the software.

Finally, the configuration files are often self-documented by many explanatory comments detailing the various possible values for each configuration setting. So much so that it is sometimes enough to just choose a line to activate from among those available. In some cases, examples of configuration files are provided in the /usr/share/doc/package/examples/ directory. They may serve as a basis for your own configuration file.

A daemon somewhat complicates one's understanding of a situation, since it does not interact directly with the administrator. To check that a daemon is actually working, you need to test it. For example, to check the Apache (web server) daemon, test it with an HTTP request.

To allow such tests, each daemon generally records everything that it does, as well as any errors that it encounters, in what are called “log files” or “system logs”. Logs are stored in /var/log/ or one of its subdirectories. To know the precise name of a log file for each daemon, see its documentation. Note: a single test is not always sufficient if it does not cover all the possible usage cases; some problems only occur in particular circumstances.

Any preventive operation begins by regularly consulting the most relevant server logs. You can thus diagnose problems before they are even reported by disgruntled users. Indeed users may sometimes wait for a problem to reoccur over several days before reporting it. You can use a specific tool to analyze the content of the larger log files. You can find such utilities for web servers (such as analog, awstats, webalizer for Apache), for FTP servers, for proxy/cache servers, for firewalls, for e-mail servers, for DNS servers, and even for print servers. Some of these utilities operate in a modular manner and allow analysis of several types of log files. This is the case of lire or also modlogan. Other tools, such as logcheck (a software discussed in Chapter 14, Security), scan these files to search for alerts to be dealt with.

If your various searches haven't helped you to get to the root of a problem, it is possible to get help from other, perhaps more experienced people. This is indeed the purpose of the debian-user@lists.debian.org mailing list. As with any community, it has rules that need to be followed. Before asking any question, you should check that your problem isn't already covered by recent discussions on the list or by any official documentation.

Once you have met those two conditions, you can think of describing your problem to the mailing list. Include as much relevant information as possible: various tests conducted, documentation consulted, how you attempted to diagnose the problem, the packages concerned or those that may be involved, etc. Check the Debian Bug Tracking System (BTS, described in sidebar TOOL Bug tracking system) for similar problems, and mention the results of that search, providing links to bugs found. BTS starts on:

The more courteous and precise you have been, the greater your chances are of getting an answer, or, at least, some elements of response. If you receive relevant information by private e-mail, think of summarizing this information publicly so that others can benefit. Allow the list's archives, searched through various search engines, to show the resolution for others who may have the same question.

If all of your efforts to resolve a problem fail, it is possible that a resolution is not your responsibility, and that the problem is due to a bug in the program. In this case, the proper procedure is to report the bug to Debian or directly to the upstream developers. To do this, isolate the problem as much as possible and create a minimal test situation in which it can be reproduced. If you know which program is the apparent cause of the problem, you can find its corresponding package using the command, dpkg -S file_in_question. Check the Bug Tracking System (http://bugs.debian.org/package) to ensure that the bug has not already been reported. You can then send your own bug report, using the reportbug command, including as much information as possible, especially a complete description of those minimal test cases that will allow anyone to recreate the bug.

The elements of this chapter are a means of effectively resolving issues that the following chapters may bring about. Use them as often as necessary!