How to RTFM (Read the *#&@ Manual)

By: Luke Rawlins Jul 3, 2017 | 9 minutes read
Share this:

Tags: documentation, Linux, troubleshooting, rtfm

If you hang out in enough Linux forums asking questions sooner or later someone will tell you to read the manual (presumably they think this will help you). Fortunately, over the last few years “rtfm” has ceased being the default answer to most questions from new users. All things considered, the Linux world has become more user friendly even if the man pages haven’t.

Learning to read and understand man pages will allow you to separate yourself from new and even some intermediate users. Plus, if you plan to take any Linux exams you will need to know how to find and read man pages. There is simply no way that most of us can memorize all of the command and configuration options you need to pass a Red Hat or Linux Foundation exam.

Nearly every command you use at the command line has a “help” option. I like to use “help” when I am fairly comfortable with a command but need a quick reference to see specific options. In many cases “–help” will get the information you are looking for.

Let’s look at a good example, the lvextend command.

lvextend --help

 WARNING: Running as a non-root user. Functionality may be unavailable.
/run/lvm/lvmetad.socket: connect failed: Permission denied
  WARNING: Failed to connect to lvmetad. Falling back to internal scanning.
lvextend: Add space to a logical volume
[-A|--autobackup y|n]
[--alloc AllocationPolicy]
[--commandprofile ProfileName]
[-i|--stripes Stripes [-I|--stripesize StripeSize]]
 {-l|--extents [+]LogicalExtentsNumber[%{VG|LV|PVS|FREE|ORIGIN}] |
-L|--size [+]LogicalVolumeSize[bBsSkKmMgGtTpPeE]}         --poolmetadatasize [+]MetadataVolumeSize[bBsSkKmMgG]}
 [-m|--mirrors Mirrors]
[--type VolumeType]
 LogicalVolume[Path] [ PhysicalVolumePath... ]

The first thing we see might be exactly what we needed to know. “WARNING: Running as a non-root user. Functionality may be unavailable." There probably isn’t much you can do with this command if you don’t have root access. As you can see, the help gives us a great summary of the command options. For example: does lvextend use -l or -L to specify size? Who can remember such things? And why should you have to when the computer will remember them for you? This illustrates exactly why you might want to consider getting comfortable with the –help option. I use the lvextend command all the time, but occasionally I can’t remember if I want -l or -L to extend a volume by 1 gigabyte. It’s far more time consuming to search the web for an answer to this type of question than it is to append –help to the end of the command.

What if you needed to extend a logical volume but you didn’t know about the lvextend command? This is where “apropos” comes in handy. Let’s say all you know is that you need to make a volume bigger but have no idea how to do that. If you know that you can search man pages with apropos, then you should be able to solve this problem on your own, albeit with a bit of extra effort.

$apropos logical volume

alarm (2)            - set an alarm clock for delivery of a signal
cryptsetup (8)       - manage plain dm-crypt and LUKS encrypted volumes
dmsetup (8)          - low level logical volume management
lvchange (8)         - change attributes of a logical volume
lvconvert (8)        - convert a logical volume from linear to mirror or snapshot
lvcreate (8)         - create a logical volume in an existing volume group
lvdisplay (8)        - display attributes of a logical volume
lvextend (8)         - extend the size of a logical volume
lvm-lvpoll (8)       - Internal command used by lvmpolld to complete some Logical Volume operations.
lvm2-activation-generator (8) - generator for systemd units to activate LVM2 volumes on boot
lvmchange (8)        - change attributes of the logical volume manager
lvreduce (8)         - reduce the size of a logical volume
lvremove (8)         - remove a logical volume
lvrename (8)         - rename a logical volume
lvresize (8)         - resize a logical volume

I cut off some of the output for the sake of brevity, however, as you can see searching for “logical volume” with apropos will return a lot of results. What you are seeing in the first column of this output is the name of a man page that will contain the information you need in order use a command. The second column is a short description of what you will find in the man page. As you scan the results hopefully “lvextend” will catch your eye along with the many other lvm commands, so that you can learn all you need to learn about managing logical volumes.

Another thing to notice is that I ran apropos with two keywords “logical” and “volume”. How did I know that I could pass two keywords into apropos? I read the man page… and now so will you.

Knowing how to read a man page is just as important as knowing how to find a man page. In the last example I knew that apropos could take more than one keyword as input because I can read and understand the man page. Let’s look at the man page for apropos and see if we can demystify some of the archaic documentation.

$ man apropos

APROPOS(1)                                                  Manual pager utils                                                  APROPOS(1)
apropos - search the manual page names and descriptions
apropos [-dalv?V] [-e|-w|-r] [-s list] [-m system[,...]] [-M path] [-L locale] [-C file] keyword ...
A traditional global index database cache.
An FHS compliant global index database cache.
A traditional whatis text database.
man(1), whatis(1), mandb(8)
Wilf. ([email protected]).
Fabrizio Polacco ([email protected]).
Colin Watson ([email protected]).
2015-11-06                                                      APROPOS(1
man(1), whatis(1), mandb(8)

I have obviously redacted quite a bit of this document so if you are following along in your terminal don’t worry. There are just a few things I want to point out. First is the structure of the page.

The first section in every man page is the name of the program along with a short summary. The name and summary should look familiar if you found the page through an apropos search.

This is the point at which most people start to let their eyes glaze over, and begin imagining how much fun it would be to poke yourself in the eye with a fork. Don’t let this section intimidate you, this is where some of the best information can be found.

apropos [-dalv?V] [-e|-w|-r] [-s list] [-m system[,...]] [-M path] [-L locale] [-C file] keyword ...

  * First it shows the command to run "apropos" pretty straight forward.
  * Next, ignore the letters and symbols inside the [] brackets. What is important here is that they are inside the [] brackets, which means that they are optional. You can use them, but you don't have to.
  * Some of the commands have special options of there own. Typically options separated with a | (pipe) indicate "or". As in you can use [-e or -w or -r] but not all of them. In this case -s takes some kind of list, and -m system[ has some other optional stuff and things]. If you want to know what those things are you need to read about them in the options sections. Right now all we care about is that these commands have some special modifier and they are optional.
  * Next we come to "keyword" notice that this is not in brackets. Like apropos this value is required. If you just type apropos the command will output an error if you don't supply at least one keyword. Anything that does not appear inside [] brackets is a required value.
  * I discovered that you can use multiple keywords because of the "..." that comes immediately after that value. Whenever you see "..." in any man page it means that you can specify multiple values for that option.

This is the section that will explain what each option does. The options are those optional things in the [] brackets.

Just like it say’s, this section tells you what the possible exit codes will be after you run the command, and hopefully what they mean. Usually useful information if you are using the command in a script.

Details about the system environment that effect the operation of the command. Not all man pages will have this section.

Any relevant files that you may need or find useful will be listed here. Often times you will see the name and location for configuration files listed here.

Additionally, though not listed in this man page sometimes you will have a section labled “EXAMPLES” that will show practical examples of how a command can be used, and why you might specify particular options. The man page for lvextend has several examples listed that we would find useful.

Man pages are also searchable with vim commands. If you want to skip through the doc to find out what the “-C” option does you can do that by typing “/-C”. Slash “/” is shorthand for search and “-C” is what we want to find. You can also move the bottom of the page with SHIFT + G or to the top by typing “gg”. To exit the man page just type “q”. (editorial note: don’t include the quotation marks)

The /usr/share/doc directory contains all the documentation files that come with a particular package. Sometimes these files contain example configuration files. For instance the apache2 or httpd package (depending on disto) will put example configuration files in this directory. These examples might help you solve a problem on an exam or help you quickly set up a proof of concept without all the internet research.

There is an enormous amount of help available for Linux. Much of it is available directly on the system you are using. If you spend some time to get comfortable reading the documentation and playing with some of the options (in a safe environment not production) you will quickly find out that you don’t always need a search engine.

In my opinion the ability to find and use information in the man pages quickly is probably the biggest difference between a really good Linux Administrator and a great one. Now, the next time someone tells you to RTFM you will at least have a better idea of how to read the f…. friendly manual.

Related Posts

Linux Security

Linux is not a bulletproof operating system, no doubt flaws, vulnerabilities, and exploits exist at this very moment that are unidentified and unpatched. It’s also very likely that many Linux systems are running old unpatched kernels that are just waiting to be owned by some nefarious persons driven by who knows what motivations. Linux like Windows has a human flaw built into it, businesses don’t want downtime for updates, users want too many permissions, and sysadmins don’t want to risk breaking an application by running an OS update. Read more

openSUSE patch vs update

If you dig into the man pages for zypper, you will notice that zypper provides three distinct options for keeping your openSUSE system up-to-date; update (up), patch, and dist-upgrade (dup). If you aren’t familiar with zypper see my previous post managing packages with zypper for more information. In this post I will attempt to demonstrate the differences between each option and suggest when you may want to consider using each. In particular, I will try to explain the difference between a simple update and a patch, with emphasis on how to gather detailed information on particular patches. Read more

Working with files in Linux - File Attributes

In the previous two posts, we’ve looked at file permissions and access control lists. Today let’s take look at file attributes. Whereas, permissions and ACL’s deal with user and group access to a file, attributes are properties of a file that regulate how the operating system interacts with a given file. There are 15 file attributes: append only (a), no atime updates (A), compressed (c), no copy on write (C), no dump (d), synchronous directory updates (D), extent format (e), immutable (i), data journalling (j), project hierarchy (P), secure deletion (s), synchronous updates (S), no tail-merging (t), top of directory hierarchy (T), and undeletable (u). Read more


If you’d like to get in touch, contact with me via email - or follow on Twitter.

[email protected]