Solving Problems and Finding Relevant Information
For an administrator, the most important skill is to be able to cope with any situation, known or unknown. This chapter gives a number of methods that will — hopefully — allow you to isolate the cause of any problem that you will encounter, so that you may be able to resolve them.
Documentation Sources
documentation
Before you can understand what is really going on when there is a problem, you need to know the theoretical role played by each program involved in the problem. To do this, the best reflex to have is consult their documentation; but since these documentations are many and can be scattered far and wide, you should know all the places where they can be found.
Manual Pages
man
man-db
manual pages
manual pages
man
documentation
manual pages
documentation
/usr
Manual pages, while relatively terse in style, contain a great deal of essential information. We will quickly go over the command for viewing them, provided by the man-db package. Simply type man manual-page — the manual page usually goes by the same name as the command whose documentation is sought. For example, to learn about the possible options for the cp command, you would type the man cp command at the shell prompt (see sidebar sidebar_title).
Man pages not only document commands and programs accessible from the command line, but also configuration files, system calls, library functions, and so forth. Sometimes names can collide. For example, the shell's read command has the same name as the read system call. This is why manual pages are organized in numbered sections:
1
commands that can be executed from the command line;
2
system calls (functions provided by the kernel);
3
library functions (provided by system libraries);
4
devices (on Unix-like systems, these are special files, usually placed in the /dev/ directory);
5
configuration files (formats and conventions);
configuration
configuration files
documentation
6
games;
7
sets of macros and standards;
8
system administration commands;
9
kernel routines.
It is possible to specify the section of the manual page that you are looking for: to view the documentation for the read system call, you would type man 2 read. When no section is explicitly specified, the first section that has a manual page with the requested name will be shown. Thus, man shadow returns shadow(5) because there are no manual pages for shadow in sections 1 to 4.
apropos
manual pages
apropos
Of course, if you do not know the names of the commands, the manual is not going to be of much use to you. This is the purpose of the apropos command, which helps you conduct a search in the manual pages, or more specifically in their short descriptions. Each manual page begins essentially with a one line summary. apropos returns a list of manual pages whose summary mentions the requested keyword(s). If you choose them well, you will find the name of the command that you need.
Finding cp with apropos
$ apropos "copy file"
cp (1) - copy files and directories
cpio (1) - copy files to and from archives
git-checkout-index (1) - Copy files from the index to the working tree
install (1) - copy files and set attributes
ntfscp (8) - copy file to an NTFS volume.
manual pages
khelpcenter
manual pages
konqueror
manual pages
yelp
manual pages
man2html
The man command is not the only means of consulting the manual pages, since khelpcenter and konqueror (by KDE) and yelp (under GNOME) programs also offer this possibility. There is also a web interface, provided by the man2html package, which allows you to view manual pages in a web browser. On a computer where this package is installed, use this URL after following the instructions in /usr/share/doc/man2html/README.Debian:
This utility requires a web server. This is why you should choose to install this package on one of your servers: all users of the local network could benefit from this service (including non-Linux machines), and this will allow you not to set up an HTTP server on each workstation. If your server is also accessible from other networks, it may be desirable to restrict access to this service only to users of the local network.
man2html
manpages.debian.org
Last but not least, you can view all manual pages available in Debian (even those that are not installed on your machine) on the manpages.debian.org service. It offers each manual page in multiple versions, one for each Debian release.
info Documents
info
GNU
Info
documentation
info documents
documentation
/usr
The GNU project has written manuals for most of its programs in the info format; this is why many manual pages refer to the corresponding info documentation. This format offers some advantages, but the default program to view these documents (it is called info) is also slightly more complex. You would be well advised to use pinfo instead (from the pinfo package).
pinfo
The info documentation has a hierarchical structure, and if you invoke pinfo without parameters, it will display a list of the nodes available at the first level. Usually, nodes bear the name of the corresponding commands.
info2www
Note that the info system is not suitable for translation, unlike the man page system. info documents are thus almost always in English. However, when you ask the pinfo program to display a non-existing info page, it will fall back on the man page by the same name (if it exists), which might be translated.
Specific Documentation
documentation
documentation
package documentation
documentation
documentation package
documentation
package
/
/usr
documentation
package
-doc
documentation
README
package
documentation
package
package
-doc
package
package
/
Each package includes its own documentation. Even the least well documented programs generally have a README file containing some interesting and/or important information. This documentation is installed in the /usr/share/doc/package/ directory (where <package> represents the name of the package). If the documentation is particularly large, it may not be included in the program's main package, but might be offloaded to a dedicated package which is usually named package-doc. The main package generally recommends the documentation package so that you can easily find it.
README.Debian
changelog.Debian.gz
NEWS.Debian.gz
documentation
README.Debian
documentation
changelog.Debian.gz
documentation
NEWS.Debian.gz
package
README.Debian
package
changelog.Debian.gz
package
NEWS.Debian.gz
Websites
documentation
websites
documentation
mailing list archive
documentation
FAQ
Frequently Asked Questions
FAQ
Frequently Asked Questions
In most cases, free software programs have websites that are used to distribute it and to bring together the community of its developers and users. These sites are frequently loaded with relevant information in various forms: official documentation, FAQ (Frequently Asked Questions), mailing list archives, etc. Problems that you may encounter have often already been the subject of many questions; the FAQ or mailing list archives may have a solution for it. A good mastery of search engines will prove immensely valuable to find relevant pages quickly (by restricting the search to the Internet domain or sub-domain dedicated to the program). If the search returns too many pages or if the results do not match what you seek, you can add the keyword debian to limit results and target relevant information.
control
Homepage
, header field
apt
show
package
package
/copyright
/usr
package
source code
If you do not know the address for the software's website, there are various means of getting it. First, check if there is a Homepage field in the package's meta-information (apt show package). Alternately, the package description may contain a link to the program's official website. If no URL is indicated, look at /usr/share/doc/package/copyright. The Debian maintainer generally indicates in this file where they got the program's source code, and this is likely to be the website that you need to find. If at this stage your search is still unfruitful, consult a free software directory, such as FSF's Free Software Directory, or search directly with a search engine, such as Google, DuckDuckGo, Yahoo, etc.
copyright
package
copyright
Free Software Directory
You might also want to check the Debian wiki, a collaborative website where anybody, even new visitors, can make suggestions directly from their browsers. It is used equally by developers who design and specify their projects, and by users who share their knowledge by writing documents collaboratively.
wiki.debian.org
documentation
wiki.debian.org
Tutorials (HOWTO)
HOWTO
documentation
HOWTO
documentation
tutorials
A HOWTO is a document that describes, in concrete terms and step by step, “how to” reach a predefined goal. The covered goals are relatively varied, but often technical in nature: for example, setting up IP Masquerading, configuring software RAID, installing a Samba server, etc. These documents often attempt to cover all of the potential problems likely to occur during the implementation of a given technology.
Many such tutorials are managed by the Linux Documentation Project (LDP), whose website hosts all of these documents:
LDP
Linux Documentation Project
Linux Documentation Project
Debian also provides tutorials for its users:
All these documents should be taken with a grain of salt. They are often several years old; the information they contain is sometimes obsolete. This phenomenon is even more frequent for their translations, since updates are neither systematic nor instant after the publication of a new version of the original documents. Further many tutorials nowadays are provided by bloggers, sharing their individual solution with the interested reader. They often lack important information, i.e. the reason why some configuration has been chosen over another, or why some option has been enabled or disabled. Because blogging and creating personal websites made it so easy to share, many of these often short tutorials exist, but only a few are actively maintained and well-kept. This can make it hard to find the "right" one for you. This is all part of the joys of working in a volunteer environment and without constraints…
Common Procedures
standard procedure
The purpose of this section is to present some general tips on certain operations that an administrator will frequently have to perform. These procedures will of course not cover every possible case in an exhaustive way, but they may serve as starting points for the more difficult cases.
Configuring a Program
configuration
program configuration
program
configuration
README.Debian
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 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.
dpkg
--listfiles
dpkg
--status
Then, you should look at the software's official documentation — refer to Documentation Sources to identify the various existing documentation sources. The dpkg -L package command 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 displays the package meta-data 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.
configuration
configuration files
documentation
configuration
configuration files
examples
package
package
/examples/
/usr
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.
Monitoring What Daemons Are Doing
Understanding what a daemon does is somewhat more complicated, 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.
/var
/var/log/
log files
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.
As a preventive operation, the administrator should regularly read the most relevant server logs. They can thus diagnose problems before they are even reported by disgruntled users. Indeed users may sometimes wait for a problem to occur repeatedly over several days before reporting it. In many cases, there are specific tools to analyze the contents of the larger log files. In particular, such utilities exist for web servers (such as analog, awstats, awffull for Apache), FTP servers, proxy/cache servers, firewalls, e-mail servers, DNS servers, and even for print servers. Other tools, such as logcheck (a software discussed in ???), scan these files in search of alerts to be dealt with.
analyzer, of log files
log files
analyzer
analog
awstats
webalizer
awffull
awffull
logcheck
Asking for Help on a Mailing List
mailing lists
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 exactly the purpose of the debian-user@lists.debian.org mailing list and its language specific siblings debian-user-@lists.debian.org. 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.
debian-user@lists.debian.org
mailing lists
debian-user@lists.debian.org
mailing lists
debian-user-
lang
@lists.debian.org
bugs.debian.org
Once those two conditions are met, 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 ???) 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. This also allows the list's archives, searched through various search engines, to show the resolution for others who may have the same question.
Reporting a Bug When a Problem Is Too Difficult
report a bug
bug
report
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 (https://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.
reportbug
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!
谢谢你的反馈！