The manual pages, usually called “man pages” because they are read with the man command, constitute the traditional “on-line” documentation. (Of course, these days all documentation is on-line in some form or another.) Program-specific man pages come along for the ride when you install new software packages. Even in the age of Google, we continue to consult man pages as an authoritative resource because they are accessible from the command line, typically include complete details on a program’s options, and show helpful examples and related commands.
Man pages are concise descriptions of individual commands, drivers, file formats, or library routines. They do not address more general topics such as “How do I install a new device?” or “Why is this system so damn slow?”
Organization of the man pages
FreeBSD and Linux divide the man pages into sections. Table 1.3 shows the basic schema. Other UNIX variants sometimes define the sections slightly differently.
The exact structure of the sections isn’t important for most topics because man finds the appropriate page wherever it is stored. Just be aware of the section definitions when a topic with the same name appears in multiple sections. For example, passwd is both a command and a configuration file, so it has entries in both section 1 and section 5.
man: read man pages
man title formats a specific manual page and sends it to your terminal through more, less, or whatever program is specified in your PAGER environment variable. title is usually a command, device, filename, or name of a library routine. The sections of the manual are searched in roughly numeric order, although sections that describe commands (sections 1 and 8) are usually searched first.
See this page to learn about environment variables.
The form man section title gets you a man page from a particular section. Thus, on most systems, man sync gets you the man page for the sync command, and man 2 sync gets you the man page for the sync system call.
man -k keyword or apropos keyword prints a list of man pages that have keyword in their one-line synopses. For example:
The keywords database can become outdated. If you add additional man pages to your system, you may need to rebuild this file with makewhatis (Red Hat and FreeBSD) or mandb (Ubuntu).
Storage of man pages
nroff input for man pages (i.e., the man page source code) is stored in directories under /usr/share/man and compressed with gzip to save space. The man command knows how to decompress them on the fly.
man maintains a cache of formatted pages in /var/cache/man or /usr/share/man if the appropriate directories are writable; however, this is a security risk. Most systems preformat the man pages once at installation time (see catman) or not at all.
The man command can search several man page repositories to find the manual pages you request. On Linux systems, you can find out the current default search path with the manpath command. This path (from Ubuntu) is typical:
If necessary, you can set your MANPATH environment variable to override the default path:
Some systems let you set a custom system-wide default search path for man pages, which can be useful if you need to maintain a parallel tree of man pages such as those generated by OpenPKG. To distribute local documentation in the form of man pages, however, it is simpler to use your system’s standard packaging mechanism and to put man pages in the standard man directories. See Chapter 6, Software Installation and Management, for more details.
Other authoritative documentation
Man pages are just a small part of the official documentation. Most of the rest, unfortunately, is scattered about on the web.
System-specific guides
Major vendors have their own dedicated documentation projects. Many continue to produce useful book-length manuals, including administration and installation guides. These are generally available on-line and as downloadable PDF files. Table 1.4 shows where to look.
Although this documentation is helpful, it’s not the sort of thing you keep next to your bed for light evening reading (though some vendors’ versions would make useful sleep aids). We generally Google for answers before turning to vendor docs.
Package-specific documentation
Most of the important software packages in the UNIX and Linux world are maintained by individuals or by third parties such as the Internet Systems Consortium and the Apache Software Foundation. These groups write their own documentation. The quality runs the gamut from embarrassing to spectacular, but jewels such as Pro Git from git-scm.com/book make the hunt worthwhile.
Supplemental documents include white papers (technical reports), design rationales, and book- or pamphlet-length treatments of particular topics. These supplemental materials are not limited to describing just one command, so they can adopt a tutorial or procedural approach. Many pieces of software have both a man page and a long-form article. For example, the man page for vim tells you about the command-line arguments that vim understands, but you have to turn to an in-depth treatment to learn how to actually edit a file.
Most software projects have user and developer mailing lists and IRC channels. This is the first place to visit if you have questions about a specific configuration issue or if you encounter a bug.
Books
The O’Reilly books are favorites in the technology industry. The business began with UNIX in a Nutshell and now includes a separate volume on just about every important UNIX and Linux subsystem and command. O’Reilly also publishes books on network protocols, programming languages, Microsoft Windows, and other non-UNIX tech topics. All the books are reasonably priced, timely, and focused.
Many readers turn to O’Reilly’s Safari Books Online, a subscription service that offers unlimited electronic access to books, videos, and other learning resources. Content from many publishers is included—not just O’Reilly—and you can choose from an immense library of material.
RFC publications
Request for Comments documents describe the protocols and procedures used on the Internet. Most of these are relatively detailed and technical, but some are written as overviews. The phrase “reference implementation” applied to software usually translates to “implemented by a trusted source according to the RFC specification.”
RFCs are absolutely authoritative, and many are quite useful for system administrators. See this page for a more complete description of these documents. We refer to various RFCs throughout this book.
Other sources of information
The sources discussed in the previous section are peer reviewed and written by authoritative sources, but they’re hardly the last word in UNIX and Linux administration. Countless blogs, discussion forums, and news feeds are available on the Internet.
It should go without saying, but Google is a system administrator’s best friend. Unless you’re looking up the details of a specific command or file format, Google or an equivalent search engine should be the first resource you consult for any sysadmin question. Make it a habit; if nothing else, you’ll avoid the delay and humiliation of having your questions in an on-line forum answered with a link to Google (or worse yet, a link to Google through lmgtfy.com). When stuck, search the web.
Keeping current
Operating systems and the tools and techniques that support them change rapidly. Read the sites in Table 1.5 with your morning coffee to keep abreast of industry trends.
Social media are also useful. Twitter and reddit in particular have strong, engaged communities with a lot to offer, though the signal-to-noise ratio can sometimes be quite bad. On reddit, join the sysadmin, linux, linuxadmin, and netsec subreddits.
HowTos and reference sites
The sites listed in Table 1.6 contain guides, tutorials, and articles about how to accomplish specific tasks on UNIX and Linux.
Stack Overflow and Server Fault, both listed in Table 1.6 (and both members of the Stack Exchange group of sites), warrant a closer look. If you’re having a problem, chances are that somebody else has already seen it and asked for help on one of these sites. The reputation-based Q&A format used by the Stack Exchange sites has proved well suited to the kinds of problems that sysadmins and programmers encounter. It’s worth creating an account and joining this large community.
Conferences
Industry conferences are a great way to network with other professionals, keep tabs on technology trends, take training classes, gain certifications, and learn about the latest services and products. The number of conferences pertinent to administration has exploded in recent years. Table 1.7 highlights some of the most prominent ones.
Meetups (meetup.com) are another way to network and engage with like-minded people. Most urban areas in the United States and around the world have a Linux user group or DevOps meetup that sponsors speakers, discussions, and hack days.
