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

The Help Option

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
    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, 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 using --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’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.

Apropos

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.

How To Read 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. ([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.

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

Let’s take a look at what each piece of this line means.

• 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 [] 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 optional 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 without a keyword the command will output an error. Anything that does not appear inside [] brackets is a required value.

• I discovered that you can use multiple keywords because of the ... (three dots) that comes immediately after keyword. 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 labeled 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 type q .

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.