Product SiteDocumentation Site

Chapitre 7. Résolution de problèmes et sources d'informations

7.1. Les sources de documentation
7.1.1. Les pages de manuel
7.1.2. Documentation au format info
7.1.3. La documentation spécifique
7.1.4. Les sites web
7.1.5. Les tutoriels (HOWTO)
7.2. Procédures types
7.2.1. Configuration d'un logiciel
7.2.2. Surveiller l'activité des démons
7.2.3. Demander de l'aide sur une liste de diffusion
7.2.4. Signaler un bogue en cas de problème incompréhensible
Pour un administrateur, le plus important est d'être capable de faire face à toute situation, connue ou inconnue. Nous proposons dans ce chapitre un ensemble de méthodes qui vous permettront — nous l'espérons — d'isoler la cause des problèmes que vous ne manquerez pas de rencontrer, pour mieux les résoudre ensuite.

7.1. Les sources de documentation

Avant de pouvoir comprendre ce qui se passe réellement en cas de problème, il faut connaître le rôle théorique de chaque programme impliqué. Pour cela, rien de tel que de consulter leurs documentations ; mais celles-ci étant multiples et dispersées, il convient de les connaître toutes.

7.1.1. Les pages de manuel

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 B.A.-BA Interpréteur de commandes).
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
commandes exécutables depuis l'interpréteur ;
2
appels système (fonctions fournies par le noyau) ;
3
fonctions de bibliothèques (fournies par les bibliothèques système) ;
4
périphériques (sous les systèmes dérivés d'Unix, ce sont des fichiers spéciaux, habituellement placés sous /dev/) ;
5
fichiers de configuration (formats et conventions) ;
6
jeux ;
7
ensemble de macros et de standards ;
8
commandes d'administration système ;
9
routines du noyau.
Il est possible de préciser la section de la page de manuel recherchée : pour consulter la documentation de l'appel système read, on tapera donc man 2 read. En l'absence d'une section explicite, c'est la première section abritant une page du nom demandé qui sera utilisée. Ainsi, man shadow renvoie shadow(5) parce qu'il n'y a pas de pages de manuel shadow dans les sections 1 à 4.
Évidemment, si vous ne connaissez pas les noms des commandes, le manuel ne vous sera pas d'un grand secours. C'est l'objet de la commande apropos, qui permet de mener une recherche dans les pages de manuel, ou plus précisément dans leurs descriptions courtes : chaque page de manuel commence en effet par un résumé en une ligne des fonctions documentées plus en détail par la suite. apropos renvoie donc une liste des pages de manuel dont la description mentionne le ou les mots-clés demandés. En choisissant bien ceux-ci, on trouvera le nom de la commande recherchée.

Exemple 7.1. Retrouver cp avec apropos

$ apropos "copy file"
cp (1)               - copy files and directories
cpio (1)             - copy files to and from archives
hpcopy (1)           - copy files from an HFS+ volume
install (1)          - copy files and set attributes
ntfscp (8)           - copy file to an NTFS volume.
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:
Cet utilitaire a donc besoin d'un serveur web. C'est pourquoi vous choisirez d'installer ce paquet sur l'un de vos serveurs : tous les utilisateurs du réseau local bénéficieront du service (y compris les postes non Linux) et vous éviterez de devoir mettre en place un serveur HTTP sur chaque poste. Par ailleurs, si votre serveur est accessible depuis l'extérieur, il peut être souhaitable de restreindre l'accès à ce service aux seuls utilisateurs du réseau local.
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.

7.1.2. Documentation au format info

Le projet GNU a rédigé les manuels de la plupart de ses programmes au format info ; c'est pourquoi de nombreuses pages de manuel renvoient vers la documentation info correspondante. Ce format offre quelques avantages mais le programme qui permet de consulter ces documentations est également un peu plus complexe. Il est recommandé d'utiliser pinfo à la place (dans le paquet pinfo).
La documentation info a une structure hiérarchique et pinfo invoqué sans paramètres affichera la liste des nœuds disponibles au premier niveau. Habituellement, un nœud porte le nom de la commande correspondante.
With pinfo navigating between these nodes is easy to achieve with the arrow keys. Alternatively, you could also use a graphical browser, which is a lot more user-friendly. Again, konqueror and yelp work; the info2www package also provides a web interface.
On notera que le système info ne permet pas de traduction, contrairement au système de pages man. Ses pages sont donc presque systématiquement en anglais. Cependant, lorsqu'on demande au programme pinfo d'afficher une page info inexistante, il se rabattra sur la page man du même nom, si celle-ci existe ; cette dernière pourra donc éventuellement exister en français.

7.1.3. La documentation spécifique

Chaque paquet intègre sa documentation spécifique : même les logiciels les moins bien documentés disposent en général au moins d'un fichier README (« lisez-moi ») contenant quelques informations intéressantes et/ou importantes. Cette documentation est installée dans le répertoire /usr/share/doc/paquet/ (où paquet représente le nom du paquet). Si elle est très volumineuse, elle peut ne pas être intégrée au paquet du programme mais constituer son propre paquet, alors intitulé paquet-doc. Le paquet du programme recommande en général le paquet de documentation pour le mettre en exergue.
The /usr/share/doc/package/ directory also contains some files provided by Debian which complete the documentation by specifying the package's particularities or improvements compared to a traditional installation of the software. The README.Debian file also indicates all of the adaptations that were made to comply with the Debian Policy. The changelog.Debian.gz file allows the user to follow the modifications made to the package over time: it is very useful to try to understand what has changed between two installed versions that do not have the same behavior. Finally, there is sometimes a NEWS.Debian.gz file which documents the major changes in the program that may directly concern the administrator (see Section 6.7.2, « Gérer les problèmes consécutifs à une mise à jour »).

7.1.4. Les sites web

Dans la majorité des cas, un logiciel libre dispose d'un site web pour le diffuser et fédérer la communauté de ses développeurs et utilisateurs. Ces sites regorgent souvent d'informations pertinentes sous différentes formes : les documentations officielles, les foires aux questions (FAQ), les archives des listes de diffusion relatives au logiciel, etc. Fréquemment, un problème rencontré aura déjà fait l'objet de nombreuses questions ; la FAQ ou les archives de l'une des listes de diffusion en abriteront alors la solution. Une bonne maîtrise d'un moteur de recherche s'avérera précieuse pour trouver rapidement les pages pertinentes (en restreignant éventuellement la recherche au domaine ou sous-domaine Internet dédié au logiciel). Si le moteur renvoie trop de pages ou si les réponses ne correspondent pas à ce qui est attendu, l'ajout du mot-clé debian permet de restreindre les réponses en ciblant les informations concernant les utilisateurs de ce système.
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.
You might also want to check the Debian wiki, a collaborative website where anybody, even simple 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.

7.1.5. Les tutoriels (HOWTO)

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:
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 own 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…