Linux Cookbook | O'Reilly Media

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Documentation for Linux programs is abundant. Finding it can be a bit challenging, though. You're not going to find lots of sleek, glossy printed manuals, because most Linux software is distributed online, rather than in shiny boxed sets.

There's another difficulty, too: Linux follows the grand Unix tradition of small, specialized programs working cooperatively, so any Linux distribution contains a large number of individual programs. For example, Tom's Root Boot, "The most GNU/Linux on one floppy disk," contains over 230 separate, individual programs on a single 3.5" diskette. A general-purpose distribution such as Mandrake or SuSE contains several thousand programs and there are over 12,000 packages in the Debian repositories. While organizing and maintaining a printed library presents some difficulties, the good news is that all of these things are documented. Whatever you want to know, there is a way to find it.

Almost every program written for Linux has a man page. They're usually not the best teaching tool for newbies. Their purpose is to document the command syntax and every command option, and to be universally available. No matter what kind of strange desert-island scenario you may find yourself in, there will always be man pages. And because man pages are incorporated into the programs to which they belong, you'll find that only installed programs have man pages and that the versions of those pages are pertinent to your system.

info pages tend to be more verbose than man pages and are hyperlinked. The hyperlinks navigate to the various nodes, or chapters, inside the document and to cross-references in other info pages. Many info pages are simply reformatted man pages. But in some instances—primarily the GNU project programs—the info pages are more detailed, containing tutorials and extensive examples.

A large number of README, CHANGELOGS, RELEASE NOTES, COPYRIGHT, INSTALL, integrated Help systems, and HTML docs are going to be squirreled away in various locations on your system. Yes, it's a jumble. Don't worry, you'll learn easy ways to find all these things in this chapter, including a nice Python script to do the finding for you.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Documentation for Linux programs is abundant. Finding it can be a bit challenging, though. You're not going to find lots of sleek, glossy printed manuals, because most Linux software is distributed online, rather than in shiny boxed sets.

There's another difficulty, too: Linux follows the grand Unix tradition of small, specialized programs working cooperatively, so any Linux distribution contains a large number of individual programs. For example, Tom's Root Boot, "The most GNU/Linux on one floppy disk," contains over 230 separate, individual programs on a single 3.5" diskette. A general-purpose distribution such as Mandrake or SuSE contains several thousand programs and there are over 12,000 packages in the Debian repositories. While organizing and maintaining a printed library presents some difficulties, the good news is that all of these things are documented. Whatever you want to know, there is a way to find it.

Almost every program written for Linux has a man page. They're usually not the best teaching tool for newbies. Their purpose is to document the command syntax and every command option, and to be universally available. No matter what kind of strange desert-island scenario you may find yourself in, there will always be man pages. And because man pages are incorporated into the programs to which they belong, you'll find that only installed programs have man pages and that the versions of those pages are pertinent to your system.

info pages tend to be more verbose than man pages and are hyperlinked. The hyperlinks navigate to the various nodes, or chapters, inside the document and to cross-references in other info pages. Many info pages are simply reformatted man pages. But in some instances—primarily the GNU project programs—the info pages are more detailed, containing tutorials and extensive examples.

A large number of README, CHANGELOGS, RELEASE NOTES, COPYRIGHT, INSTALL, integrated Help systems, and HTML docs are going to be squirreled away in various locations on your system. Yes, it's a jumble. Don't worry, you'll learn easy ways to find all these things in this chapter, including a nice Python script to do the finding for you.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You're trying to use some programs (for example, everyone's favorite, grep; the name tells you so much) and you can't make them them do what you want. So, heeding the standard "RTFM" (read the fine man page) advice, you dig up the relevant man pages. But they don't make a lot of sense—now what?

Learn how man pages are organized, and familiarize yourself with their conventions for teaching command syntax and options, and you'll find that man pages really are helpful.

Linux sees all the man pages on a system as part of a single manual. This manual is divided into sections:

1 Executable programs or shell commands
2 System calls
3 Library calls
4 Special files (usually found in /dev)
5 File formats and conventions
6 Games
7 Miscellaneous
8 System administration commands
9 Nonstandard kernel routines
n New documentation, which may be moved later
l Local documentation, specific to your system

Each individual program, utility, or function has its own page in this manual, like a page in a book. Finding the man page for a program or command is usually as easy as typing man foo, where foo is the name of the program.

You've probably seen references to numbered man pages, like grep(1). This is referring to man grep in section 1. Call it up this way:

               $ man 1 grep

Some man pages are in more than one section. man foo will only display the first one. You can list all of them with the -f switch:

               $ man -f man
man (1)   an interface to the online reference manuals
man (7)   macros to format man pages

Each man page is divided into sections. The section names vary, but you'll usually see these: NAME, SYNOPSIS, DESCRIPTION, OPTIONS, FILES, EXAMPLES, SEE ALSO, BUGS, and AUTHOR.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You need a program or utility to perform a specific function—for example, counting the words in a file—but you don't know what to look for. If you knew what you were looking for, you wouldn't need to look for it, right? How do you get out of this dilemma?

Do keyword searches with apropos or man -k. For example, if you want a command to count the words in a file, use:

               $ apropos count words

or:

               $ man -k count words
american-english (5) - a list of english words
grpconv (8)          - convert to and from shadow passwords and groups.
grpunconv (8)        - convert to and from shadow passwords and groups.
kmessedwords (1)     - a letter order game for KDE
lppasswd (1)         - add, change, or delete digest passwords.
pwconv (8)           - convert to and from shadow passwords and groups.
pwunconv (8)         - convert to and from shadow passwords and groups.
shadowconfig (8)     - toggle shadow passwords on and off
wc (1)               - print the number of newlines, words, and bytes in files

It doesn't matter which you use; apropos and man -k are the same. There are a lot of options, but wc looks like the program you want.

Remember the -f switch, to find all versions of a man page:

               $ man -f manpath
manpath (1)      - determine search path for manual pages
manpath (5)      - format of the /etc/manpath.config file

These commands perform keyword searches in the Description sections of the man pages. You can use any number of search terms, but the more you use, the more results you'll get, because they search each keyword in sequence.

Because these are literal keyword searches, broad concepts like "bandwidth shaping" or "user management" do not carry the same meaning for apropos and man -k; they see "bandwidth shaping" as two unrelated search terms, so single-word searches usually work best.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You can't find a man page for an installed program, and you're certain it should be on the system.

Sometimes the man database gets corrupted, users make strange modifications, or programs install man pages incorrectly. First try searching with whereis -m :

               $ whereis -m cat
               cat:/usr/man/man1/cat.1.gz /usr/share/man/man1/cat.1.gz

Now you've found the page. Read it with man:

               $ man /usr/man/man1/cat.1.gz

If that doesn't work, try rebuilding the man database with mandb:

               # mandb

If that doesn't work, try a system-wide search with locate and egrep:

               $ locate / cat. | egrep -w 'cat\.[1-9][a-zA-Z]*[.gz]?'

This works for any man page—simply replace cat with whatever you're looking for.

If none of these approaches turn up the man page you are looking for, try the finddoc script in Recipe 1.11. If this doesn't find it, it's not on your system.

There are all kinds of man page repositories on the Web, so you can always try a Google search. However, some programs simply don't have man pages, so don't ruin your health searching for one that may not exist.

whereis(1), mandb(8)
grep comes in several flavors; see grep(1) for details

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You're working on a system that is seriously messed up, and you can't read man pages because the man viewer doesn't work.

Try reading the raw man page with zcat and nroff:

               $ zcat /usr/man/man1/cat.1.gz | nroff -man | less

As a last resort, read the raw page code with zless :

               $ zless /usr/man/man1/cat.1.gz
.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.32.
.TH CAT "1" "July 2003" "cat (coreutils) 5.0" "User Commands"
.SH NAME
cat \- concatenate files and print on the standard output
.SH SYNOPSIS
.B cat
[\fIOPTION\fR] [\fIFILE\fR]...

It's not pretty, but it works.

nroff is a wrapper for groff , for formatting man pages. groff is a document-formatting, or typesetting, program. It enables you to create many differently formatted documents from a single source file: HTML, .pdf, printed hard copies, info pages, and many more. See Chapter 9 of Running Linux for a good introduction.

mandb(8), locate(1), grep(1), nroff(1), groff(1), zless(1), zcat(1)
Recipe 1.6
Chapter 9 of Running Linux , by Matt Walsh, Matthias Dalheimer, Terry Dawson, and Lar Kaufman (O'Reilly)

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You're repeatedly having trouble finding man pages; using tools from Recipe 1.4, you find that most of the missing pages are in a directory that man doesn't seem to know about. Perhaps a newly-installed program put its man pages in a strange place, like /opt/man. Or perhaps you want to put some man pages in a nonstandard location. How do you configure man to find them?

Edit /etc/manpath.config.

Suppose the directory you want to add is /opt/man. Add /opt/man to /etc/manpath.config:

# every automatically generated MANPATH includes
# these fields
   
MANDATORY_MANPATH                   /usr/man
MANDATORY_MANPATH                   /usr/share/man
MANDATORY_MANPATH                   /usr/X11R6/man
MANDATORY_MANPATH                   /usr/local/man
MANDATORY_MANPATH                   /opt/man

And you're done. Now man will find the man pages in the new directory.

When you create a custom man page directory, be sure to include the section directories:

               $ ls /opt/man/local
man1  man2  man3  man4  man5  man6  man7  man8  man9

It's not necessary to include all the numbered sections, just the ones pertinent to the man pages you'll be storing there.

If you're going to have subdirectories—for example, /opt/man and /opt/man/local—be sure to list them in this order:

MANDATORY_MANPATH                   /opt/man/local
MANDATORY_MANPATH                   /opt/man

Subdirectories must be listed before parent directories, or they will be overlooked by the man viewer.

You can run manpath with no options to see your current manpaths:

               $ manpath
/usr/local/man:/usr/share/man:/usr/X11R6/man:/usr/man

manpath(1), manpath(5)

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You decide to give info pages a try, so you call up info tar (or any other info page of your choice). But you find that navigating info tar is confusing and difficult. What is the best way to learn your way around?

Use info's built-in tutorial. Type info at any command line, hit the letter h, then do what it says. It should take 15-30 minutes, and it is time well-spent.

Even though some folks think that info pages are unnecessarily complicated to navigate, it is worth getting acquainted with them. Even though they are more difficult to navigate than man pages, they are (usually) easier to understand. Once you get the hang of moving around in them, you can go very fast and find information quickly. Info pages often contain more information than man pages, and they sometimes include tutorials and extensive examples.

There are also a number of nice info viewers, such as pinfo, Konqueror, and Yelp. Pinfo runs in the console, and Konqueror and Yelp need X. Konqueror is especially easy to navigate and to use for printing selected pages.

info info

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to print a man page, nicely formatted and readable. You have tried man foo | lpr, but it doesn't look very good. The margins are too small, and all the formatting is lost.

One way to print a nicely formatted man page is to use the -t flag, which formats it especially for printing. man finger is good for practice, because it's only two pages long:

               $ man -t finger | lpr

To use a networked printer:

               $ man -t finger | lpr -P printername

To see your available printers:

               $ lpstat -p -d

Another option is to use the following command, which formats the page in HTML and sends it to the web browser of your choice:

               $ man -Hmozilla finger

Then use the browser's print command. Be sure there is no space between -H and the browser name.

All of the major Linux distributions ship with CUPS, the Common Unix Printing System. CUPS supports both the System V (lp) and Berkeley (lpr) commands. This recipe uses the Berkeley commands. Here is the System V equivalent.

               $ man -t finger | lp

To use a networked printer:

               $ man -t finger | lp -d printername

man(1), lpr(1), lp(1)
Chapter 14
CUPS Software Users Manual (http://localhost:631/documentation.html)

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to print some info pages, but there doesn't seem to be a built-in print command for info.

You can use lpr :

               $ info finger | lpr

However, this may result in too-small margins and odd line breaks, depending on your printer defaults. Use lpr options to format it:

               $ info finger | lpr -o cpi=12 -o page-left=54 -o page-right=54 -o page-top=54 \
               -o page-bottom=54

The numbered values are points, or 1/72". This example creates 3/4" margins all the way around. cpi=12 sets the number of characters to 12 per inch. All of these options are documented in the CUPS Software Users Manual, at http://localhost:631/documentation.html.

All of the major Linux distributions ship with CUPS, the Common Unix Printing System. CUPS supports both the System V (lp) and Berkeley (lpr) commands. This recipe uses the Berkeley commands. Here are the System V equivalents.

To print an info page use:

               $ info finger | lp

To print the info page using lp's formatting options use:

               $ info finger | lp -o cpi=12 -o page-left=54 -o page-right=54 -o page-top=54 \
               -o page-bottom=54

info info, lpr(1), lp(1)
Chapter 14
CUPS Software Users Manual (http://localhost:631/documentation.html)

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You would like to print selected man and info pages, because most man and info documents are quite long. For example, man bash consumes 33 printed pages. How can you print pages selectively?

Export the man or info page to a plain text file, using the col command. Then you can easily select the pages to print. To do this with man bash or info bash use:

               $ man bash | col -b > bash.txt
               $ info bash | col -b > bash.txt

If you just type man bash > bash.txt, the results will be unpleasant. col -b cleans things up considerably by removing reverse line feeds, or backspaces. This is especially suited for converting man pages to plain text, because man pages are full of reverse line feeds, which then appear in text files as either empty boxes or repeated characters.

col(1)

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to find all the relevant readmes, changelogs, howtos, guides, examples, samples, and other documentation that accompanies your installed programs.

Use finddoc, that wonderful Python script that comes to you courtesy of the excellent Akkana Peck.

You can call it anything you like. Remember to make it executable:

               $ chmod +x finddoc

Using it requires only the script name and the name of the program for which you need the documentation. For example:

               $ ./finddoc grep
/usr/share/doc/grep
/usr/share/doc/grep-dctrl
/usr/share/doc/grep-dctrl/changelog.gz
...

The output can be filtered through other commands, or redirected to a file:

               $ ./finddoc | grep -i examples | lpr
               $ ./finddoc | grep -i faq
               $ ./finddoc | grep -i examples > python-examples.txt

#!/usr/bin/env python
   
# Finddoc: A Script For Finding Linux Program Documentation
# When making your own copy of this script, be sure to
# preserve the leading spaces exactly as they are written
# here, because Python needs them. 
   
# Search for documentation related to the given strings;
# case-insensitive, and whole-word only.
# Relies on "locate" and assumes that the locate
# database is current.
#
# Copyright 2003 by Akkana Peck.
# You may use, distribute or modify this program
# under the terms of the GPL.
   
import sys, os, string, re
   
# This is the list of document-related filenames
# to search for. You may edit this list as needed.
# Be sure to add only lowercase names.
docfilenames = [ 
 "changelog", 
 "readme", 
 "install", 
 "howto", 
 "authors", 
 "news", 
 "todo", 
 "config", 
 "sample", 
 "samples", 
 "example", 
 "examples",
 "ref",
 "guide",
 "manual",
 "quickstart",
 "thanks",
 "notes",
 "features",
 "faq",
 "acknowledgement",
 "bugs",
 "problems"
]
   
def system_out (cmdstr) :
 retlist = [  ]
 fp = os.popen(cmdstr)
 while 1:
  s = fp.readline( )
  if not s : break
  retlist.append(s)
 fp.close( )
 return retlist
   
# main( )
for arg in sys.argv :
 #print string.split(arg, " \t./")
   
 files = system_out("locate " + arg + " | grep -w " + arg);
   
 for path in files :
  #print path
   
  # Special case for anything with "man", "doc", or "info" in the path:
  if (string.find(path, "/man") >= 0) \
   or (string.find(path, "/doc") >= 0) \
   or (string.find(path, "/info") >= 0) :
   print path,
)
   continue
   
  # Now see if it matches any of the docfilenames:
  base = os.path.basename(path)
  for nam in docfilenames :
   if base =  = "" : continue
   
   # Non full word search would use this:
:
   
   # Full-word-search:
   # Make a regexp to search for nam as full-word only
   pat = "^" + nam + "$"
   if (re.compile(nam).search(base, 1)) :
    print path,
    base = ""
    continue

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Installing a Linux distribution is quite easy these days. Pop in a CD-ROM, make a few configuration choices, then go enjoy a cup of tea while it finishes. Modern Linuxes have excellent hardware detection, install quickly (typically in 30 minutes or less), and require no more than a single reboot.

Maintaining a Linux system has also evolved tremendously. Packages and intelligent dependency resolvers mean that keeping a system updated and patched is now easier and less error-prone. Today's youngsters have it so easy. We didn't have CD-ROMs in the primitive olden days of computing—instead of broadband, we had a station wagon full of floppy disks. To get new programs, us old-timers had to unpack laboriously downloaded tarballs, or copy them off floppy disks, then compile the programs from source code. Dependency problems? Why, us old geeks handled all those things without help from any fancy-pants dependency resolvers. It went something like this:

               # tar -xvf someprogram.tar
               # ./configure
               # make

The make failed, because of unresolved dependencies. So the next step was to download a tarball containing the program with the required libraries, which took six hours over a 300-baud modem. You know, the kind with the rubber cup that fits over the phone. I passed the time by going outside and planting a garden. I came back inside when the download was finished, unpacked the new tarball, and tried again:

               # ./configure
               # make

Boy howdy, another long string of error messages indicating more unresolved dependencies. Download yet another tarball, do more garden work. By the time everything was installed and working, I had tomatoes the size of melons. It's a good thing we were so smart we hardly even needed computers.

Why was there all this dependency drama? Because Linux uses shared libraries that are dynamically linked at runtime. Many separate, unrelated programs can use the same libraries. This makes for a fast, efficient system. Less memory and storage resources are consumed, and programs are smaller and easier to distribute. But as Linux evolved and became more complex, managing source-built systems became more difficult. So programs were put into

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Installing a Linux distribution is quite easy these days. Pop in a CD-ROM, make a few configuration choices, then go enjoy a cup of tea while it finishes. Modern Linuxes have excellent hardware detection, install quickly (typically in 30 minutes or less), and require no more than a single reboot.

Maintaining a Linux system has also evolved tremendously. Packages and intelligent dependency resolvers mean that keeping a system updated and patched is now easier and less error-prone. Today's youngsters have it so easy. We didn't have CD-ROMs in the primitive olden days of computing—instead of broadband, we had a station wagon full of floppy disks. To get new programs, us old-timers had to unpack laboriously downloaded tarballs, or copy them off floppy disks, then compile the programs from source code. Dependency problems? Why, us old geeks handled all those things without help from any fancy-pants dependency resolvers. It went something like this:

               # tar -xvf someprogram.tar
               # ./configure
               # make

The make failed, because of unresolved dependencies. So the next step was to download a tarball containing the program with the required libraries, which took six hours over a 300-baud modem. You know, the kind with the rubber cup that fits over the phone. I passed the time by going outside and planting a garden. I came back inside when the download was finished, unpacked the new tarball, and tried again:

               # ./configure
               # make

Boy howdy, another long string of error messages indicating more unresolved dependencies. Download yet another tarball, do more garden work. By the time everything was installed and working, I had tomatoes the size of melons. It's a good thing we were so smart we hardly even needed computers.

Why was there all this dependency drama? Because Linux uses shared libraries that are dynamically linked at runtime. Many separate, unrelated programs can use the same libraries. This makes for a fast, efficient system. Less memory and storage resources are consumed, and programs are smaller and easier to distribute. But as Linux evolved and became more complex, managing source-built systems became more difficult. So programs were put into

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You need to know how to install software packages on Red Hat and Red Hat-type systems.

Use RPM, the Package Manager. Red Hat installation command syntax looks like this:

               # rpm -i 
               packagename

For example, the following command installs the drawing program Tuxpaint. -v adds verbose feedback, and -h draws progress hashmarks:

               # rpm -ivh tuxpaint-9.13-1.i386.rpm
Preparing...########################### [100%]
   1. tuxpaint ######################## [100%]

To test the installation first, without installing anything, use:

               # rpm -ivh —test tuxpaint-9.13-1.i386.rpm
Preparing...########################### [100%]
#

RPM hell, or getting caught in an endless chain of unresolved dependencies, is the most common RPM problem. Here are some ways to prevent it:

Do not let any dependencies remain unresolved. They don't fix themselves; they lurk and grow larger over time.
The quality of RPMs varies wildly. Anyone can throw one together and post it for distribution. As much as possible, stick with RPMs built for your distribution and architecture. Polished Linux Distribution (PLD) builds good-quality RPMs for all x86 systems.
Use CheckInstall when you need a source-built program. CheckInstall creates Red Hat, Debian, and Slackware packages, so you get the benefits of both a custom compilation and your package manager (see Recipe 4.5, Recipe 4.5).

rpm(8)

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You need to upgrade an installed RPM package: there's a new version of some program you like, with new features and important bug fixes.

Use the -U flag:

               # rpm -Uvh tuxpaint-9.13-1.i386.rpm

To test the command first, use:

               # rpm -Uvh —test tuxpaint-9.13-1.i386.rpm

-U can be used in place of -i, install. It doesn't matter if you're upgrading a package or installing a new one, it works in both cases. -U replaces the old package. If you want to have multiple versions of the same package, such as gcc, or install several different kernels, don't use -U, use -i.

rpm(8)
RPM.org (http://rpm.org/)
Maximum RPM (http://www.rpm.org/max-rpm/index.html)

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You've gotten tired of some program and want to get rid of it. Or you've just installed something you don't want. So, you want to remove an RPM package.

rpm -e does the job:

               # rpm -ev tuxpaint

You don't need the entire package name (e.g., tuxpaint-9.13-1.i386.rpm), just the label.

To uninstall several programs at once, use a space-delimited list:

               # rpm -ev tuxpaint SDL_ttf  SDL_ttf-devel SDL_images

If you don't want to check dependencies:

               # rpm -ev —nodeps tuxpaint

To test your command first, before executing it, use:

               # rpm -ev —test tuxpaint SDL_ttf  SDL_ttf-devel SDL_images

If RPM reports that it cannot remove a package because other packages depend on it, you either need to remove the other packages, or leave it alone. There are times when you need to break dependencies; for example, when replacing Sendmail. Your new MTA—Postfix, Exim, or qmail—will resolve Sendmail's dependencies, but you have to remove Sendmail first, which you can't do without breaking all kinds of dependencies.

rpm(8)
Maximum RPM (http://www.rpm.org/max-rpm/index.html)

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to know what packages are installed on your system, what files belong to a package, or what package a file belongs to. There are lots of reasons for wanting this information; you might want to know exactly what version of some program is on your system, or you may be asking, "what does this thingy belong to?" You might even change some file accidentally, and want to know what you've broken.

Use RPM's querying features. All queries start with rpm -q .

To query the RPM database to see if a program is already installed, use:

               $ rpm -q tuxpaint
tuxpaint-9.13-1

To do a case-insensitive search for an installed RPM, using a partial package name, use:

               $ rpm -qa | grep -i kde
lockdev-1.0.1-1.3
kdebase-3.1.4-6
kdeutils-3.1.4-1
kdegames-3.1.4-4

To list files in an installed package, use:

               $ rpm -ql kdegames
/usr/bin/atlantik
/usr/bin/kasteroids
/usr/bin/katomic
...

To list the documentation for an application, use:

               $ rpm -qd kdegames | grep katomic
/usr/share/doc/HTML/en/katomic/common
/usr/share/doc/HTML/en/katomic/index.docbook
...

To list the configuration files for a package, use:

               $ rpm -qc openssh
/etc/ssh/moduli

To list the configuration files for a command, use:

               $ rpm -qcf /usr/bin/ssh
/etc/ssh/ssh_config

To list all installed packages, use:

               $ rpm -qa
setup-2.5.27-1.1
tzdata-2003d-1
bzip2-libs-1.0.2-10
...

To save the list to a file, while viewing the output on the screen, use:

               $ rpm -qa | tee rpmlist.txt

To see what package a file belongs to, use:

               $ rpm -qf /usr/bin/tuxkart
tuxkart-0.2.0-3

RPM queries will not follow symlinks, and will report that the file is "not owned by any package." To find the file that a symlink points to, use:

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to know what dependencies a new RPM requires, what files are in it, or if a particular file is in it.

Add the -p switch to run queries on uninstalled RPMs.

To list the documentation files, use:

               $ rpm -qpd tuxpaint-9.13-1.i386.rpm
/usr/share/doc/tuxpaint-9.13-1/AUTHORS.txt
/usr/share/doc/tuxpaint-9.13-1/CHANGES.txt
/usr/share/doc/tuxpaint-9.13-1/COPYING.txt
...

To list all the files, use:

               $ rpm -qpl tuxpaint-9.13-1.i386.rpm
/etc/tuxpaint/tuxpaint.conf
/usr/bin/tuxpaint
...

To see what dependencies this package requires, use:

               $ rpm -qpR tuxpaint-9.13-1.i386.rpm
/bin/sh
SDL >= 1.2.4
SDL_image
...

To see what this package provides, use:

               $ rpm -qp —provides tuxpaint-9.13-1.i386.rpm
config (tuxpaint) = 9.13-1
tuxpaint-9.13-1
tuxpaint = 9.13-1

You can also get all this information on individual packages, before downloading them, from RPM repositories such as http://freshrpms.net, http://rpmfind.net, and http://rpm.pbone.net.

rpm(8)
Maximum RPM (http://www.rpm.org/max-rpm/index.html)
FreshRPMS (http://freshrpms.net/)
rpmfind (http://rpmfind.net)
rpm.pbone (http://rpm.pbone.net)

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You installed some new packages a few days ago, and you've forgotten what they are.

Use the —last option:

               # rpm -qa —last

This command lists all installed RPMs, with the newest first.

If the list is too long, pipe it into less or head: rpm -qa --last|head.

rpm(8)
Maximum RPM (http://www.rpm.org/max-rpm/index.html)

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You think your RPM database may be corrupted, or out-of-date, because it does not answer queries for RPMs you know are installed; or you've given your system a major overhaul and want to be sure the RPM database is up-to-date.

Try rebuilding the RPM database, as root:

               # rpm —rebuilddb

or completely re-create it:

               # rpm —initdb

It is uncommon for the RPM database to need rebuilding, but it doesn't hurt anything to try. Any time you make major changes to your system is a good time to rebuild the RPM database. If you compare the size of /var/lib/rpm/packages before and after running rpm —rebuilddb, you may notice some shrinkage, because it has removed unused portions of the database.

rpm(8)
Maximum RPM (http://www.rpm.org/max-rpm/index.html)
Chapter 16 of Linux in a Nutshell

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You want to run both source-built programs and RPMs on the same system. But RPM does not know about the source-built libraries, so it incorrectly reports dependency errors.

Use the rpm-orphan-find script. This script searches for all the libraries on your system, then compares the results with the contents of the RPM database. Any orphaned libraries are then rolled into a new, virtual .rpm. There are no files in this .rpm, just a list of provides. Run this like any Bash script:

               # chmod +x rpm-orphan-find
               # ./rpm-orphan-find

When the script is finished, install the shiny new .rpm,and your formerly orphaned libraries will be included in your RPM database.

Thank you to Paul Heinlein and Peter Samuelson for this great script.

#!/bin/bash
## rpm-orphan-find, a script that finds
## orphaned libs on an RPM-based system
## and rolls them into a virtual .rpm
## written by Paul Heinlein and Peter Samuelson
## Copyright 2003
## You may use, distribute or modify this
## program under the terms of the GPL.
OS=$(uname -s)
LIBS="/lib /usr/lib $(cat /etc/ld.so.conf)"
NAME=$(echo ${OS}-base-libs | tr '[A-Z]' '[a-z]')
VER=1.0; REL=1
TMPSPEC=$(mktemp /tmp/${NAME}.spec.XXXXXX)
   
exec 9>$TMPSPEC
   
cat <<_ _eof_ _ >&9
Summary: $OS Base Virtual Package
Name: $NAME
Version: $VER
Release: $REL
Group: System Environment/Base
License: None
_ _eof_ _
   
found=0; orphan=0;
echo "Scanning system libraries $NAME version $VER-$REL..."
find $LIBS -type f \( -name '*.so.*' -o -name '*.so' \) |
while read f
do
  ((found++))
  if ! rpm -qf $f >/dev/null 2>&1
  then
    ((orphan++))
    echo "Provides: $(basename $f)" >&9
  fi
  echo -ne "Orphans found: $orphan/$found...\r"
done
echo ''; echo ''
   
cat <<_ _eof_ _ >&9
   
%description
This is a virtual RPM package.  It contains no
actual files.  It uses the 'Provides' token from RPM 3.x and later to list many of the 
shared libraries that are part of the base operating system and associated subsets for 
this $OS environment.
   
%prep
# nothing to do
   
%build
# nothing to do
   
%install
# nothing to do
   
%clean
# nothing to do
   
%post
# nothing to do
   
%files
   
_ _eof_ _
   
exec 9>&-
rpmbuild -ba $TMPSPEC; rm $TMPSPEC

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You are trying to install an RPM, but the installation fails with " Error: Failed dependencies." Welcome to dependency hell.

Collect all of the RPMs needed to satisfy the dependencies, then install them all at once. For example:

               # rpm -ivh tuxpaint-0.9.13-1.i386.rpm
error: Failed dependencies
    SDL_image is needed by tuxpaint-0.9.13-1
    SDL_ttf is needed by tuxpaint-0.9.13-1
    libSDL_image-1.2.so.O is needed by tuxpaint-0.9.13-1
    libSDL_ttf-2.0.so.O is needed by tuxpaint-0.9.13-1
# rpm -ivh tuxpaint-0.9.13-1.i386.rpm  SDL_image-1.2.3-4.i386.rpm  SDL_ttf-2.0.6-1.i386.rpm

The installer will sort them out and install them in the correct order.

What if RPM complains about a missing file or package, and you are certain it is installed? Sometimes the RPM database contains errors, so try rebuilding it:

               # rpm -rebuilddb

If that doesn't help, reinstall the allegedly missing package with —replacepkgs:

               # rpm -ivh —replacepkgs SDL_ttf-2.0.6-1.i386.rpm

If you are certain the necessary libraries exist on your system, try either forcing the installation, ignoring errors:

               # rpm -ivh —force  tuxpaint-2002.10.20-1.i386.rpm

or don't check dependencies:

               # rpm -ivh —nodeps tuxpaint-2002.10.20-1.i386.rpm

If you find yourself stuck with unresolvable dependency conflicts, try installing your new program and all of its dependent packages from source RPMs (see Recipe Recipe 2.11).

Where do you find the packages you need? Your first stop should be the home page of the program you're trying to install. Be sure to read any available documentation.

RPM-based distributions are quite diverse these days, so be sure to get RPMs built for your system. These are some of largest public RPM archives:

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You can't install an RPM because of binary incompatibilities with your system, or you just prefer to compile applications on your system, or you want to edit the source code then build the package.

Build your new program from source RPMs.

Download the SRPM—in this example, tuxpaint-2002.10.20-1.src.rpm—into your directory of choice. Be sure to get the SRPM for your Linux distribution.

Then run the package installer:

               # rpm -ivh tuxpaint-2002.10.20-1.src.rpm

This will place sources in /usr/src/SOURCES and the spec file in /usr/src/SPECS:

               $ ls /usr/src/SOURCES
tuxpaint-2002.09.29.tar.gz ruxpaint-Makefile.patch tuxpaint-stamps-2002.09.29.tar.gz 
tuxpaint.desktop tuxpaint-opt.patch
$ ls /usr/src/SPECS
tuxpaint.spec

Build the spec file:

               # rpmbuild -bb tuxpaint.spec

This creates a new RPM in /usr/src/RPMS/i386:

               # ls /usr/src/RPMS/i386
tuxpaint-2002.10.20-1.i386.rpm

You now have a nice, new Tuxpaint RPM, compiled for your system.

The source directory on your particular distribution may be different. Fedora 1 uses /usr/src/redhat/RPMS/,as did some early versions of Mandrake. Other distributions use /usr/src/RPM/RPMS. Poke around and you'll find the right one.

This is not an escape from RPM hell. It simply lets you build an RPM from sources compiled on your system, so you have binary compatibility with system libraries and the RPM is optimized for your architecture. You still need to manually satisfy dependencies, which is not as much f

Table of Contents