Online Troubleshooting Resources: HOWTO

Jean-Philippe Guérard

Version 1.7


2006-05-25
Revision History                                                             
Revision 1.7           2006-05-25            Revised by: JPG                 
Two updates following suggestions of Oguz Yarimtepe (the Basic Unix Tutorial 
of Idaho State University is not available anymore, update of the link to the
Why use Google page). Added a section listing translations of this document. 
Revision 1.6           2005-08-06            Revised by: JPG                 
Added FOLDOC (thanks to Howard Mann for suggesting this). General document   
update and cleanup. Added the text of the Open Publication Licence at the end
of the document.                                                             
Revision 1.5           2002-10-20            Revised by: JPG                 
More dead links removal & URL updates. Author and copyright updated as per   
Horward Mann request.                                                        
Revision 1.4           2002-03-04            Revised by: JPG                 
Dead links removal. Outdated links update. Revision of the HOWTOs and FAQs   
sections.                                                                    
Revision 1.3           2000-07-24            Revised by: HM                  
Update.                                                                      
Revision 1.2           1999-11-20            Revised by: HM                  
Added "Introduction to Unix" to Unix section.                                
Revision 1.1           1999-11-08            Revised by: HM                  
Added Geocrawler.com to Mailing List Section. Convert to DocBook.            
Revision 0.5           1999-09-18            Revised by: HM                  
Initial release.                                                             


  Troubleshooting a Linux-related issue is often perceived as a difficult
task. But, often, the solution is just a few clicks away on the internet.
This document will direct Linux users to resources available on the Internet
that provide access to a vast amount of Linux-related information useful in
the troubleshooting problems.

-----------------------------------------------------------------------------
Table of Contents
1. Introduction
    1.1. Document Updates
    1.2. Copyright and License
    1.3. Feedback and Corrections
    1.4. Translations
    1.5. Document history
   
   
2. Frequently-Asked-Questions (FAQs)
3. Online Support Sections
4. Internet Search Engines
    4.1. Google.com
   
   
5. Usenet Newsgroup Archives
6. Mailing List Archives
7. HOWTOs
8. Online User's Manuals
9. Online Unix References and Tutorials
10. Miscellaneous Resources
    10.1. Release Notes and Available Documentation related to the X Window
        Server
    10.2. GNU Software and Manuals
    10.3. The Free On-line Dictionary of Computing
    10.4. An online dictionary of computer and technology terms
   
   
11. Concluding Comments
A. Open Publication License
    A.1. Requirements on both unmodified and modified versions
    A.2. Copyright
    A.3. Scope of license
    A.4. Requirements on modified works
    A.5. Good-practice recommendations
    A.6. License options
   
   

1. Introduction

  The traditional means of troubleshooting computer-related problems involves
consulting user's manuals, books, friends - probably enticed with goodies -
and, when all the former do not yield a solution, calling the technical
support service of the vendor of the product in question. And, we all know
pleasant and reliably efficacious the latter stratagem is. Unfortunately,
this is the norm in the sphere of commercial proprietary products.

  In contradistinction, Linux, and related distributions, utilities and
applications software, have largely been developed according to the [http://
www.opensource.org] Open Source model, wherein developers have used
electronic communication over the Internet - typically in the form of
publicly-accessible Mailing Lists - to collaborate with their peers in the
refinement of the associated source code. Such collaboration has also
traditionally involved the online publication of user's manuals, lists of
Frequently-Asked-Questions (FAQ's), knowledge bases, release notes, formal
guides such as this document (HOWTO's) and tutorials. In addition, users
often assist others through the forum of Usenet and other newsgroups and the
posted messages are readily accessible in the form of searchable archives.
These Linux-related newsgroups are renowned for their high level of user
participation. In significant measure, Linux may be considered a product of
the Internet.

  Considered together, these resources enable access to a large,
ever-expanding factual database, and my intent is to encourage and direct the
reader to utilize these repositories when faced with an issue not addressed
in the documentation that is included with each distribution of Linux. Linux
veterans who assist newcomers through the forum of Usenet soon become aware
of the frequency with which certain technical questions are repeatedly posted
- questions the answers to which are readily available in one or more of the
existent online repositories. So, to diminish the likelihood of being
"flamed" in response to your posted question on Usenet or irc, read further!

  Armed with a browser, Linux users may rapidly become adept at
troubleshooting their systems. The key is knowing how and where to look. My
objective is to guide the user - particularly the Linux newbie - in this
quest.
-----------------------------------------------------------------------------

1.1. Document Updates

  The [http://www.tldp.org/HOWTO/Online-Troubleshooting-HOWTO/] latest
version of this document will always be available at the Linux Documentation
Project. The document will also be available in SGML, PS, PDF, and other
formats at that website.
-----------------------------------------------------------------------------

1.2. Copyright and License

  Copyright © 1999-2005, by Jean-Philippe Guérard. This material may be
distributed only subject to the terms and conditions set forth in the Open
Publication Licence, v1.0 or later (see Appendix A).
-----------------------------------------------------------------------------

1.3. Feedback and Corrections

  I always welcome feedback and constructive criticism. You can reach me at <
jean DASH philippe DOT guerard AT tigreraye DOT org>. In particular, I wish
to be notified about any errors in this document and resources you believe
deserving of inclusion, but not presently covered herein. Because the
assessment of the value of a particular resource is inherently subjective, I
do not guarantee that I will include it, but I will certainly give any
suggestion thoughtful consideration. In anticipation, Thanks.
-----------------------------------------------------------------------------

1.4. Translations

  This document has already been translated in several languages. If you have
made a translation of this document, please e-mail me and I will add your
translation to this list.

  *   A French translation has been made by Benoît Sibaud, of the [http://
    www.traduc.org] Traduc.org project.
   
  *   A Turkish translation has been made by Oguz Yarimtepe, of the [http://
    docs.comu.edu.tr] docs.comu.edu.tr project.
   

-----------------------------------------------------------------------------
1.5. Document history

  Howard Mann conceived and formulated the first version of this HOWTO. He
kept managing and updating it until version 1.3. Maintainership was then
taken over by Jean-Philippe Guérard, who is now in charge of this document.
-----------------------------------------------------------------------------

2. Frequently-Asked-Questions (FAQs)

  Users of Internet Newsgroups and Mailing lists soon discovered that some
basic questions were being asked over and over again. To provide an answer to
these questions, and to avoid them being repeated continually, FAQs were
developed, listing the most classical questions and their agreed answers.

  A list of FAQs is also a traditional accompaniment to Linux-related
software. The FAQ is the first document to peruse when troubleshooting a
particular application. It provides answers to typical questions, and is a
good place to start troubleshooting a specific problem. In addition, FAQs
exist for Linux distributions, window managers, and the so-called desktop
environments (KDE and Gnome).

  A FAQ is typically provided online by the developers of the product in
question, and enterprising users sometimes host an "unofficial" FAQ as well.
Search for the latter with an Internet search engine.

  For Linux newbies, I provide links to two FAQs that collectively address 
many of the questions posted to the Usenet newsgroups:

  *   [http://www.tldp.org/FAQ/Linux-FAQ/] The Linux FAQ
   
  *   The Linux Kernel mailing list FAQ
   

-----------------------------------------------------------------------------
3. Online Support Sections

  These sections are typically found at the websites of Linux distributions,
and often contain a variety of helpful documents with information not easily
encompassed within a FAQ. This is the second place to go when troubleshooting
a problem. Look for sections with one or more of the following titles:

  *  Installation Support
   
  *  Knowledge or Solutions Databases
   
  *  Tips and Tricks
   
  *  Errata, Fixes and Updates
   
  *  Security Information
   
  *  Bug Tracking System
   
  *  Bug Database
   
  *  Hardware Guide or Compatibility List
   
  *  Technical Guides
   
  *  White Papers
   

  Some websites provide a site search engine that will facilitate your quest
for a solution.

  If you have a problem with a newly installed distribution, look here first
as bugs and their fixes are typically posted here. You may find a detailed
guide that will help you accomplish a task such as upgrading your kernel or
the version of the X Window System you are using.

  I have often been able to solve problems with my Linux distribution by
looking into the bug report database, and finding that another user already
has offered a solution to this issue.

  I recommend you spend some time at the website of the distribution you are
using, familiarizing yourself with what is available.
-----------------------------------------------------------------------------

4. Internet Search Engines

  I frequently use a Search Engine to retrieve helpful or necessary
information from the 'net. These engines catalogue pages from commercial,
personal and academic websites, as well as Mailing Lists and the like.

  There are several good search engine. It is worthwhile becoming very
familiar with the operational details of at least one non-directory engine to
maximize the efficiency and efficacy of your search efforts. You probably
already have a favorite - I like Google.com, and will discuss it in a little
more detail.

  The key to a successful search is to use a good set of keywords. If you're
getting a specific error message, you might search for its text. Otherwise,
you need to find a few relevant words describing your problem. Then, by trial
and error, you should be able to find some pertinent information.
-----------------------------------------------------------------------------

4.1. Google.com

  This [http://www.google.com] engine has several novel features that are
described in its [http://www.google.com/technology/] Google Technology page.
In particular, the engine often returns the most useful pages first; in fact,
I have often found that the first listed page contains the information I
need. Because it caches web pages, it is relatively fast at displaying
requested items. It has a so-called GoogleScout?? feature, activated by
clicking on the "similar pages" links, that provides additional relevant
links with each item returned.
-----------------------------------------------------------------------------

5. Usenet Newsgroup Archives

  The ability to search for and retrieve information from archived posts to
the Linux-related (Usenet) newsgroups represents a powerful means of
troubleshooting in Linux.

  Search engines permit one to search the archives by stipulating the forum,
keywords, authors, dates, language and combinations thereof. Because the
number of Linux-related newsgroups is large, the likelihood of finding useful
information is high.

  The main web site that currently provides access to Usenet archives using a
search engine is [http://groups.google.com] http://groups.google.com. The
most effective way to do a search is to use its Advanced Groups Search page.

  I would like to relate a brief anecdote to demonstrate the efficacy of this
approach. The first time I attempted to build a kernel, I was presented with
this error message when I invoked a "make" command:
make[1]: as86: Command not found                                             
make[1]: *** [bootsect.o] Error 127                                          
make[1]: Leaving directory `/usr/src/linux/arch/i386/boot'                   
make: *** [zImage]                                                           
Error 2                                                                      

  I had no idea what as86 was, but I entered it as the keyword in the Subject
field of the Advanced Groups Search page at groups.google.com, and was
presented with a large number of posts from folks who had encountered the
same problem. Respondents had provided the reason and solution: I did not
have an assembler/linker necessary to create machine code, and the bin86
package provided it. I downloaded and installed a RPM package of the latter
and was on my way. This entire process took about 10 minutes!
-----------------------------------------------------------------------------

6. Mailing List Archives

  As you might expect, there are a very large number of Linux-related Mailing
Lists that enable developers and users to communicate and collaborate on
projects. These Lists cover every conceivable aspect of Linux, from the
technical arcana of kernel development to the relatively unfocused discussion
of issues at the newbie level. Subscribers to a particular Mailing List are
generally very knowledgeable in the List's topic, and detailed and useful
information is often retrievable. The communications are publicly accessible
through Internet search engines and in the form of online Mailing List
Archives. You will typically see archived pages when you conduct a search
using an Internet search engine.

  Usually, you will not need to look directly in a Mailing List Archive. 
Search engines like Google.com include these archives in their databases. If
you can't find anything with a search engine, it might be worthwhile to
browse or search in an appropriate Mailing List.

  Also, not all Mailing Lists are associated with an online archive, but this
is increasingly the case. Similarly, not all archives have an associated
search engine.

  Initially, try locate the Mailing List Archive you are interested in by
typing keywords and "mailing list archive" in an Internet search engine.

  You may also find Mailing List archives at the following locations:

  *   The website of the distribution of Linux you use.
   
  *   The website of the Window Manager or Desktop Environment you use.
   
  *   The website dedicated to the application or project in question.
   
  *   The Mail Archive
   
  *   Mailing List Archives
   

  This is not a complete listing of archives and you may find additional
sites with an Internet search engine. But, this should certainly get you
going.
-----------------------------------------------------------------------------

7. HOWTOs

  HOWTOs are detailed reference documents on a specific subject, usually
following a step-by-step approach. A HOWTO is a good document to help you
discover a task or a topic you don't know. It will provide you with the basic
steps and the major references.

  These documents are particularly useful when you decide to provide or
access a new service with your Linux system, or when you embark on a
technically complex project. For example, you may have the option of
accessing the 'net with a DSL or Cable Modem service - excellent guides are
available in the form of HOWTOs.

  Authors of these documents often include references and links to sites that
they have found useful. You may find the information you need at one of these
hyperlinked sites rather than in the HOWTO itself.

  To find HOWTOs, the first place to go is the [http://www.tldp.org] Linux
Documentation Project (LDP). The LDP includes a HOWTO Index Page that I
suggest you bookmark in your browser.

  These HOWTOs are written by Linux users and are periodically updated by the
authors. Many authors provide the latest version at a personal website and a
hyperlink to the latter is typically provided in the document. This version
may be newer than the one available at the LDP website.

  Note also that other HOWTOs are available, the authors of which have not
submitted them to the LDP. It is definitely worthwhile trying to find these
with an Internet search engine, using the "howto" keyword.
-----------------------------------------------------------------------------

8. Online User's Manuals

  Some of the major Linux distributions, Window Managers and Desktop
Environments publish their user's manual online. If the entire manual is not
online, installation and configuration guides are typically found at the
relevant website. This also applies to major applications like the Gimp (GNU
Image Manipulation Program) or Apache.

  So, for those users who do not have the printed manual, a wealth of
installation and configuration guidance is generally available online.
-----------------------------------------------------------------------------

9. Online Unix References and Tutorials

  As Linux is a Unix-like operating system, a general familiarity with
fundamental Unix concepts such as the Unix directory hierarchy and file
permissions is essential. Fortunately, there are many Unix tutorials online
that collectively cover everything a user might need to know to use Linux. I
suggest you bookmark the following as an online reference library:

  *   The Wikipedia Unix article is a good place to start. It includes an
    Unix history, explains some Unix concepts and includes an explanation of
    basic commands and some relevant links.
   
  *   Eric S. Raymond's The Unix and Internet Fundamentals HOWTO is a good
    document to learn about the Unix concepts.
   
  *   The UNIX Tutorial for Beginners of the University of Surrey is a good
    step by step tutorial for beginners.
   
  *   The Command and Shell User's guide from Digital Equipment Corporation
    is an excellent guide to the Unix Operating System. Bookmark the Index
    Page linked there as an online reference.
   
  *   [http://star.pst.qub.ac.uk/help/unixhelp/] UNIXhelp is mirrored on many
    servers around the world. It is a useful resource for newbies.
   
  *   Introduction to Unix also contains a useful Unix Command Summary page
    with brief, but useful, explanations of commonly used Unix commands.
   
  *   Unix is a Four Letter Word... is another resource suitable for newbies.
   

-----------------------------------------------------------------------------
10. Miscellaneous Resources

  In this section, I provide a number of links to websites that I have found
useful while learning to use Linux. This is an eclectic collection, but keep
these handy.
-----------------------------------------------------------------------------

10.1. Release Notes and Available Documentation related to the X Window
Server

  Depending on the X Window Server your distribution is using, you will need
to look at either the XFree86 website or the X.Org Foundation website.
Whenever you have trouble with your X environment, peruse the notes
applicable to your videocard and chipset. These typically provide details
about the configuration of the X Window System relative to your card, and
will enumerate any "options" you have to include in the XF86Config file that
governs X.
-----------------------------------------------------------------------------

10.2. GNU Software and Manuals

  Many important programs that are frequently utilized by the Linux user are
GNU utilities - for example, the tar (archive) and gzip (compression)
programs. Descriptions of these programs are located at the [http://
directory.fsf.org/] FSF Free Software Directory where many Online Manuals may
also be found.

  These manuals typically provide a lot more information than is found in the
corresponding man page on your system. For example , compare the man page and
online manual for the tar utility.
-----------------------------------------------------------------------------

10.3. The Free On-line Dictionary of Computing

  The Free On-line Dictionary of Computing (FOLDOC) is a huge encyclopedia of
computing terms and concepts, maintained by Denis Howe. It has very detailed
articles, with a lot of cross references. It's a very good reference to
understand anything related to computing.
-----------------------------------------------------------------------------

10.4. An online dictionary of computer and technology terms

  The [http://www.pcwebopedia.com/] PC Webopedia consists of a large online
dictionary of computer-related terms and a search engine that provides links
to documents that discuss each item in more detail. For example, I used this
site to learn the differences between ISA and PCI buses.
-----------------------------------------------------------------------------

11. Concluding Comments

  If you are a Linux newbie, you may want to create a Troubleshooting folder
in your browser's bookmark list, into which you put the hyperlinks I have
included in this document, as well as those pertinent to the distribution of
Linux and the Window Manager or Desktop Environment you use.

  As you use these links, you will quickly become adept at troubleshooting
online.

Cheers and happy searching!
-----------------------------------------------------------------------------

A. Open Publication License

v1.0, 8 June 1999
-----------------------------------------------------------------------------

A.1. Requirements on both unmodified and modified versions

  The Open Publication works may be reproduced and distributed in whole or in
part, in any medium physical or electronic, provided that the terms of this
license are adhered to, and that this license or an incorporation of it by
reference (with any options elected by the author(s) and/or publisher) is
displayed in the reproduction.

  Proper form for an incorporation by reference is as follows:

   
      Copyright (c) <year> by <author's name or designee>. This material may
    be distributed only subject to the terms and conditions set forth in the
    Open Publication License, vX.Y or later (the latest version is presently
    available at [http://www.opencontent.org/openpub/] http://
    www.opencontent.org/openpub/).
   
  The reference must be immediately followed with any options elected by the
author(s) and/or publisher of the document (see section VI).

  Commercial redistribution of Open Publication-licensed material is
permitted.

  Any publication in standard (paper) book form shall require the citation of
the original publisher and author. The publisher and author's names shall
appear on all outer surfaces of the book. On all outer surfaces of the book
the original publisher's name shall be as large as the title of the work and
cited as possessive with respect to the title.
-----------------------------------------------------------------------------

A.2. Copyright

  The copyright to each Open Publication is owned by its author(s) or
designee.
-----------------------------------------------------------------------------

A.3. Scope of license

  The following license terms apply to all Open Publication works, unless
otherwise explicitly stated in the document.

  Mere aggregation of Open Publication works or a portion of an Open
Publication work with other works or programs on the same media shall not
cause this license to apply to those other works. The aggregate work shall
contain a notice specifying the inclusion of the Open Publication material
and appropriate copyright notice.

  SEVERABILITY. If any part of this license is found to be unenforceable in
any jurisdiction, the remaining portions of the license remain in force.

  NO WARRANTY. Open Publication works are licensed and provided "as is"
without warranty of any kind, express or implied, including, but not limited
to, the implied warranties of merchantability and fitness for a particular
purpose or a warranty of non-infringement.
-----------------------------------------------------------------------------

A.4. Requirements on modified works

  All modified versions of documents covered by this license, including
translations, anthologies, compilations and partial documents, must meet the
following requirements:

 1.   The modified version must be labeled as such.
   
 2.   The person making the modifications must be identified and the
    modifications dated.
   
 3.   Acknowledgement of the original author and publisher if applicable must
    be retained according to normal academic citation practices.
   
 4.   The location of the original unmodified document must be identified.
   
 5.   The original author's (or authors') name(s) may not be used to assert
    or imply endorsement of the resulting document without the original
    author's (or authors') permission.
   

-----------------------------------------------------------------------------
A.5. Good-practice recommendations

  In addition to the requirements of this license, it is requested from and
strongly recommended of redistributors that:

 1.   If you are distributing Open Publication works on hardcopy or CD-ROM,
    you provide email notification to the authors of your intent to
    redistribute at least thirty days before your manuscript or media freeze,
    to give the authors time to provide updated documents. This notification
    should describe modifications, if any, made to the document.
   
 2.   All substantive modifications (including deletions) be either clearly
    marked up in the document or else described in an attachment to the
    document.
   
 3.   Finally, while it is not mandatory under this license, it is considered
    good form to offer a free copy of any hardcopy and CD-ROM expression of
    an Open Publication-licensed work to its author(s).
   

-----------------------------------------------------------------------------
A.6. License options

  The author(s) and/or publisher of an Open Publication-licensed document may
elect certain options by appending language to the reference to or copy of
the license. These options are considered part of the license instance and
must be included with the license (or its incorporation by reference) in
derived works.

 A.   To prohibit distribution of substantively modified versions without the
    explicit permission of the author(s). "Substantive modification" is
    defined as a change to the semantic content of the document, and excludes
    mere changes in format or typographical corrections.
   
      To accomplish this, add the phrase `Distribution of substantively
    modified versions of this document is prohibited without the explicit
    permission of the copyright holder.' to the license reference or copy.
   
 B.   To prohibit any publication of this work or derivative works in whole
    or in part in standard (paper) book form for commercial purposes is
    prohibited unless prior permission is obtained from the copyright holder.
   
      To accomplish this, add the phrase 'Distribution of the work or
    derivative of the work in any standard (paper) book form is prohibited
    unless prior permission is obtained from the copyright holder.' to the
    license reference or copy.
   

