Linux administration

• Most Linux commands have an associated manual page
  • Often known as a manpage
• Viewed with the man command:

$ man ls

• Press q to quit and return to the shell prompt

• man uses the less viewer
• Use the cursor keys for scrolling
• Other common keystrokes:

• Help on all keystokes is available with h

• Manpages have a traditional format
• Manpages for user commands tend to have some or all of these sections:
  • NAME — name and single-line reason for the command
  • SYNOPSIS — possible arguments
  • DESCRIPTION — fuller explanation of the command
  • OPTIONS
  • FILES — any files the command needs
  • ENVIRONMENT — pertinent environment variables
  • BUGS
  • AUTHOR
  • SEE ALSO

• Each manpage is in a section of the manual
• User commands are in section 1
• Different sections can contain pages of the same name:
  • The 'passwd' page in section 1 describes the passwd command
  • The 'passwd' page in section 5 describes the /etc/passwd file
  • These are often referred to as “passwd(1)” and passwd(5)
• A page can be requested from a particular section by specifying its number:
  • man 1 passwd
  • man 5 passwd

• Most commands are documented in section 1
  • This is the first place man looks
  • So the passwd command's manpage can also be viewed with:

$ man passwd

• Other sections you may need:
  • Some system administration commands are in section 8
  • File formats are in section 5
  • Miscellany is in section 7
• A complete list of sections is in man(7)
• Each section has an introduction page called intro:

$ man 8 intro

• The whatis command lists manpages with the specified name:

$ whatis hostname
hostname    (1) - show or set the system's host name
hostname    (7) - host name resolution description

• show or set the system's host name
• host name resolution description
• Section number in brackets
• Single-line description from the NAME section
• Useful for quickly discovering what a command does, ex. "What is tac?"

$ whatis tac

• man -f is equivalent to whatis

• Manpages can be printed out in a nicely-formatted way:

$ man -t head > head.ps

• Formats the manpage for head as PostScript and writes it to head.ps in the current directory
  • Alternatively, send the PostScript directly to a printer:

$ man -t head | lpr

• To search for pages with a NAME section matching a particular keyword, use apropos:

$ apropos gif
gif2tiff    (1) create a TIFF file from a GIF87 format image file
giftopnm    (1) convert a GIF file into a portable anymap
ppmtogif    (1) convert a portable pixmap into a GIF file
Data::Dumper    (3) stringified perl data structures, suitable for both printing and eval

• Can't restrict the search to a particular section. But can grep the output:

$ apropos gif | grep '(1)'

• man -k is equivalent to apropos

• To display all pages which have a particular name, regardless of their section, use man -a:

$ man -a hostname

• Displays hostname(1)
• Waits for you to quit
• Displays hostname(8)

• It is possible to search through the textual content of the entire manual
• man -K (note upper-case) does this:

$ man -K printer

• Filename of each matching page is displayed in turn
• Prompt for choosing whether to display it
  • Not particularly useful
• Many false matches obscuring the data you want
• Slow to search so much text
• Tedious to respond to each prompt

• Sometimes commands' documentation are not quite where expected
• Related commands can be grouped together on one page:
  • These commands all display the same page:

$ man gzip
$ man gunzip
$ man zcat

• Can be misleading if you look up one command and start reading the description of another

• Shell built-in commands are documented in shells' manpages:
  • cd(1) refers the reader to bash(1)
  • echo(1) relates to /bin/echo, but in most shells echo is a separate built-in command
• The bash(1) manual page has details, but is too big
  • See the section 'SHELL BUILTIN COMMANDS'
• For brief explanations of builtin functions, use help:

$ help help
help: help [-s] [pattern ...]
Display helpful information about builtin commands. If PATTERN is
...

• Run help without arguments to get a list of builtin commands

• Manpages are stored in the filesystem
• You can use man to find the locations of a given manpage
  • Use the -a and -w options to show the locations of all manpages with a given name:

$ man -aw passwd
/usr/man/man1/passwd.1.gz
/usr/man/man5/passwd.5.gz

• Common locations for manpages include /usr/man and /usr/share/man
  • Locally-installed packages often put manpages under /usr/local/man

• GNU have a rival documentation system called info
  • GNU utilities have info pages
  • Often duplicating man pages
  • But some GNU utilities have half-hearted man pages
  • A few other programs use info too
• An info page is viewed with the info command:

$ info cat
$ info ls

• Use q to quit and return to the shell
• Emacs has a better info viewer built in, and there is an alternative, slicker viewer available, called pinfo

• Scroll with the cursor keys, PgUp and PgDn
• An info page may be split into nodes
  • For example, the ls page has separate nodes covering file selection, formatting, and sorting
  • Hyperlinks between nodes start with stars

• Node navigation keystrokes:

• The 'Next', 'Prev', and 'Up' destinations are shown at the top.

• Some programs' main (or only) documentation is not available as man or info pages
• /usr/share/doc/ contains other formats of documentation
  • Usually plain text
  • Sometimes HTML
  • Subdirectory per package, such as /usr/share/doc/grep-2.4/
• On many systems (particularly older ones) /usr/doc is used instead of /usr/share/doc
• On really awkward systems both directories exist, and contain different documentation!

• Documentation in /usr/share/doc is often information only relevant to system administration of a package, not users of it:
  • Installation instructions, licence, change log

• Sometimes more user-friendly documentation than elsewhere

  • For example /usr/share/doc/ImageMagick-4.2.9/ImageMagick.html
  • HTML help is more common for interactive applications, and very rare for traditional Unix commands
  • Programs ported from other platforms often have documentation in /usr/share/doc/ rather than man pages

• Some commands have no external documentation, but have an option to display some help:

$ netscape -help

• Others do have documentation elsewhere but have an option to display a usage summary:

$ vim -h

• GNU utilities all have a --help option for this:

$ grep --help

• Discovering which, if any, option does this can often only be found by trial and error

• Unfortunately some luck is required for finding documentation
• With time you pick up the hang of what is likely to be documented where
• The locate command can be useful for finding all files related to a particular command.
• Web search engines can sometimes be the fastest way of searching for documentation
  • Many places have the entire manual pages hosted on the web, which Google et al have conveniently indexed

• a. Use man man to open the man page which details how to use the man command itself
• b. Press the h (help) key to see a summary of commands and keystrokes
• c. Find out how to do the following things:
  • i. Move to the start and the end of the man page
  • ii. Move up and down the text one screen at a time
  • iii. Move up and down one line at a time
  • iv. Search for a pattern in the text
  • v. Repeat a previous search with a single keypress
  • vi. Move to a specific line, by number

• a. From the man page for man, find out what commands to type to do the following:
  • i. Get a list of manual pages about the 'whatis' database
  • ii. Get a list of manual pages from section 1 whose descriptions contain the word 'print'
  • iii. Search for man pages containing the string 'cdrom' (but why is this a problem?)
• b. Practice using man to find out about things which interest you, or try some of these examples:
  • i. Bitmap image formats like JPEG, GIF, XPM and PNG
  • ii. Communications concepts like modems, serial connections, telnet, PCMCIA and PPP
  • iii. Filesystems like NFS, ext2, FAT, vfat, msdos and Samba

• a. Take a quick look at the documentation for the tar command, in both the man page and the Info documentation. How are they different?
• b. What happens when you run info without specifying which document to view?