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

Finding help with Linux

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 questions from new users. All things considered the Linux world has become more user friendly, even if the man pages haven’t.

One of the things that will allow you to separate yourself from new and even some intermediate users is knowing where to find the help you need on your own, knowing how to read the information you find, and then being able to apply that information. 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.

The Help Option

Nearly every command you will 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 what you are looking for.

Quick help options are usually retrievable with “–help”. Let’s look at a good example. With 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

lvextend
        [-A|--autobackup y|n]
        [--alloc AllocationPolicy]
        [--commandprofile ProfileName]
        [-d|--debug]
        [-f|--force]
        [-h|--help]
        [-i|--stripes Stripes [-I|--stripesize StripeSize]]
        {-l|--extents [+]LogicalExtentsNumber[%{VG|LV|PVS|FREE|ORIGIN}] |
         -L|--size [+]LogicalVolumeSize[bBsSkKmMgGtTpPeE]}
         --poolmetadatasize [+]MetadataVolumeSize[bBsSkKmMgG]}
        [-m|--mirrors Mirrors]
        [--nosync]
        [--use-policies]
        [-n|--nofsck]
        [--noudevsync]
        [-r|--resizefs]
        [-t|--test]
        [--type VolumeType]
        [-v|--verbose]
        [--version]
        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, this gives us a great summary of the command options. 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 for you? This illustrates exactly the way that you might want to consider getting comfortable with –help. 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 is 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.

Apropos

But what if you needed to extend a live 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 pr0blem on your own, albeit with a bit of extra effort.

apropos live 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 “live 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 much of 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 live volumes.

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

Man Pages

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)

NAME
       apropos - search the manual page names and descriptions

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

DESCRIPTION
       ...
...

OPTIONS
      ...
...
...

EXIT STATUS
       ...
...
...
ENVIRONMENT
...
...
...
FILES
       /usr/share/man/index.(bt|db|dir|pag)
              A traditional global index database cache.

       /var/cache/man/index.(bt|db|dir|pag)
              An FHS compliant global index database cache.

       /usr/share/man/.../whatis
              A traditional whatis text database.
SEE ALSO
       man(1), whatis(1), mandb(8)

AUTHOR
       Wilf. (G.Wilford@ee.surrey.ac.uk).
       Fabrizio Polacco (fpolacco@debian.org).
       Colin Watson (cjwatson@debian.org).

2.7.5                                                           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.

NAME

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.

SYNOPSIS

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.

OPTIONS

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

EXIT STATUS

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.

ENVIRONMENT

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

FILES

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)

Documentation

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.

Luke has an RHCSA for Red Hat Enterpirse Linux 7 and currently works as a Linux Systems Adminstrator in Ohio.

This post, re-published here with permission, was originally published on Luke’s site here.