6.1. Documentation Sources
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. One of the best ways to do this is to review the program's documentation. Let's begin by discussing where, exactly, you can find documentation since it is often scattered.
How to Avoid RTFM Answers
This acronym stands for "read the f***ing manual," but can also be expanded in a friendlier variant, "read the fine manual." This phrase is sometimes used in (terse) responses to questions from newbies. It is rather abrupt, and betrays a certain annoyance at a question asked by someone who has not even bothered to read the documentation. Some say that this classic response is better than no response at all since this at least hints that the answer lies within the documentation.
When you are posting questions, don't necessarily be offended by the occasional RTFM response, but do what you can to at least show that you have taken the time to do some research before posting the question; mention the sources that you have consulted and describe the various steps that you have personally taken to find information. This will go a long way to show that you are not lazy and are truly seeking knowledge. Following Eric Raymond's guidelines is a good way to avoid the most common mistakes and get useful answers.
6.1.1. Manual Pages
Manual pages, while relatively terse in style, contain a great deal of essential information. To view a manual page, simply type man manual-page. The manual page usually coincides with the command name. For example, to learn about the possible options for the cp command, you would type man cp at the command prompt.
Man pages not only document programs accessible from the command line, but also configuration files, system calls, C 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 the following numbered sections:
- Commands that can be executed from the command line
- System calls (functions provided by the kernel)
- Library functions (provided by system libraries)
- Devices (on Unix-like systems, these are special files, usually placed in the /dev/ directory)
- Configuration files (formats and conventions)
- Games
- Sets of macros and standards
- System administration commands
- Kernel routines
You can 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–4.
Of course, if you do not know the names of the commands, the manual is not going to be of much use to you. Enter the apropos command, which searches manual pages (or more specifically their short descriptions) for any keywords that you provide. The apropos command then returns a list of manual pages whose summary mentions the requested keywords along with the one-line summary from the manual page. If you choose your keywords well, you will find the name of the command that you need.
Example 6.1. Finding cp with apropos
$ apropos "copy file"
cp (1) - copy files and directories
cpio (1) - copy files to and from archives
gvfs-copy (1) - Copy files
gvfs-move (1) - Copy files
hcopy (1) - copy files from or to an HFS volume
install (1) - copy files and set attributes
ntfscp (8) - copy file to an NTFS volume.Browsing Documentation by Following Links
Many manual pages have a "See Also" section, usually near the end of the document, which refers to other manual pages relevant to similar commands, or to external documentation. You can use this section to find relevant documentation even when the first choice is not optimal.
In addition to man, you can use konqueror (in KDE) and yelp (in GNOME) to search man pages as well.
6.1.2. Info Documents
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 (also called info) is slightly more complex. You would be well advised to use pinfo instead (from the pinfo package). To install it, simply run apt update followed by apt install pinfo (see Section 8.2.2.2, "Installing Packages with APT").
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.
You can use the arrow keys to navigate between nodes. Alternatively, you could also use a graphical browser (which is a lot more user-friendly) such as konqueror or yelp.
As far as language translations are concerned, the info system is always in English and is not suitable for translation, unlike the man page system. 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.
6.1.3. Package-Specific Documentation
Each package includes its own documentation and even the least 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.
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 that documents the major changes in the program that may directly concern the administrator.
6.1.4. Websites
In many cases, you can find websites that are used to distribute free software programs and to bring together the community of its developers and users. These sites are loaded with relevant information in various forms such as official documentation, frequently asked questions (FAQ), and mailing list archives. In most cases, the FAQ or mailing list archives address problems that you have encountered. As you search for information online, it is immensely valuable to master search syntax. One quick tip: try restricting a search to a specific domain, like the one dedicated to the program that is giving you trouble. If the search returns too many pages or if the results do not match what you seek, you can add the keyword kali or debian to limit results and target relevant information.
From the Error to a Solution
If the software returns a very specific error message, enter it into a search engine (between double quotes, ", in order to search for the complete phrase, rather than the individual keywords). In most cases, the first links returned will contain the answer that you need.
In other cases, you will get very general errors, such as "Permission denied". In this case, it is best to check the permissions of the elements involved (files, user ID, groups, etc.). In short, don't get in the habit of always using a search engine to find a solution to your problem. You will find it is much too easy to forget to use common sense.
If you do not know the address of the software's website, there are various means of locating it. First, look for a Homepage field in the package's meta-information (apt show package). Alternatively, the package description may contain a link to the program's official website. If no URL is indicated, the package maintainer may have included a URL in the /usr/share/doc/package/copyright file. Finally, you may be able to use a Internet search engine (such as Google, Bing, DuckDuckGo, etc.) to find the software's website.
6.1.5. Kali Documentation at docs.kali.org
The Kali project maintains a collection of useful documentation at https://www.kali.org/docs/. While this book covers a large part of what you should know about Kali Linux, the documentation there might still be useful as it contains step-by-step instructions (much like how-tos) on many topics.
Let's review the various topics covered there:
- Introduction: documentation describing what Kali Linux is and all of its features
- Installation: various documents describing Kali Linux installation, including how to install it side-by-side with other operating systems
- Virtualization: various documents describing how to create Kali Linux virtual machines through various software
- USB: documentation describing how to create a Kali Linux bootable live USB
- Kali Linux on ARM: many recipes about running Kali Linux on various ARM-based devices
- Containers: documentation describing how to use Kali Linux in containers such as Docker or LXC
- WSL: various documents containing information on potential ways to use Kali Linux through the Windows Subsystem for Linux
- Cloud: documentation describing how to create cloud instances of Kali Linux
- Kali NetHunter: documentation on everything involving the mobile port of Kali
- General Use: various documents on the typical use cases of Kali Linux and answers to various questions that may be asked
- Tools: documentation on the tools contained within Kali Linux
- Troubleshooting: various documents that contain information that may be beneficial when troubleshooting issues
- Development: documentation describing many aspects of the Kali Linux creation process
- Community: documentation describing how to get involved in the Kali Linux community
- Policy: explanations about what makes Kali Linux special when compared to other Linux distributions
