Online Troubleshooting Resources : HOWTO

Jean-Philippe Guérard

         jean-philippe.guerard@laposte.net
      
Revision History                                                             
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.                                                             


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
troubleshooting problems

-----------------------------------------------------------------------------
Table of Contents
1. Introduction
2. Document Updates
    2.1. Copyright and License
    2.2. Feedback and Corrections
    2.3. Document history
   
   
3. HOWTOs and mini-HOWTOs
4. Frequently-Asked-Questions (FAQs)
5. Online Support Sections
6. Usenet Newsgroup Archives
7. Internet Search Engines
    7.1. Google.com
   
   
8. Mailing List Archives
9. Online User's Manuals
10. Online Unix References and Tutorials
11. Miscellaneous Resources
    11.1. Release Notes and Available Documentation related to the XFree86 X
        Window Server
    11.2. GNU Software and Manuals
    11.3. A detailed Guide to Personal Computers
    11.4. An online dictionary of computer and technology terms
   
   
12. Concluding Comments

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, has 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
publically-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.
-----------------------------------------------------------------------------

2. Document Updates

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

2.1. Copyright and License

Copyright (c) 1999-2002 , 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 (the latest version is presently available
at [http://www.opencontent.org/openpub/] http://www.opencontent.org/openpub
/).
-----------------------------------------------------------------------------

2.2. Feedback and Corrections

I always welcome feedback and constructive criticism. You can reach me at
[mailto:jean-philippe.guerard@laposte.net] jean-philippe.guerard@laposte.net.
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.
-----------------------------------------------------------------------------

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

3. HOWTOs and mini-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. For example, I found Linux
Network Drivers, an interesting site for information about Network Interface
Card drivers, in the Ethernet HOWTO.

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
using an Internet search engine as I describe in a subsequent section.
-----------------------------------------------------------------------------

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

  * The Linux FAQ
   
  * The Linux Kernel mailing list FAQ
   

-----------------------------------------------------------------------------
5. 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. Look for sections with one or more of the following
titles:

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

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

6. 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] 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 (I do have an
ADSL connection to the 'net !).
-----------------------------------------------------------------------------

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

Of course, there are a large number of available Search Engines, and I
suggest you try several before giving up on a particular quest. Research has
shown that any one of them catalogues but a small portion of existent web
pages. 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.
-----------------------------------------------------------------------------

7.1. Google.com

This [http://www.google.com] engine has several novel features that are
described in its Why use Google.com 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 (TM) feature, activated by clicking on the "similar
pages" links, that provides additional relevant links with each item
returned.

In addition, it has a specialized [http://www.google.com/linux] Linux Search
Engine that I use as my primary Internet search tool. It searches the
database of linux-related pages at Google.com further promoting search
efficiency. Try it - I am confident you will bookmark it immediately.
-----------------------------------------------------------------------------

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

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.

For a listing of linux-related Mailing Lists, peruse websites such as the 
Linux Resource Exchange and the Linux Online Mailing Lists

A relatively new, excellent Mailing List resource is [http://
www.geocrawler.com] Geocrawler (The Knowledge Archive). This is a
continuously updated, searchable archive of a large number of Lists that also
allows one to register and subsequently post to any particular Mailing List.
Its user interface is simple and its search function delivers messages very
quickly. I highly recommend this site.

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

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

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

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

  * [http://www.tru64unix.compaq.com/docs/base_doc/DOCUMENTATION/V40D_HTML/
    APS2HDTE/TITLETXT.HTM] 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://unixhelp.ed.ac.uk/] 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.
   

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

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

This documentation accompanies each version of XFree86, and is available at
the [http://www.xfree86.org/] XFree86 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 theXF86Config file that governs X.
-----------------------------------------------------------------------------

11.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 GNU.org website
where many [http://www.gnu.org/manual/manual.html] 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.
-----------------------------------------------------------------------------

11.3. A detailed Guide to Personal Computers

The Topic Index to the voluminous hardware guide at [http://www.PCguide.com/
topic.html] PC guide.com will give you a great idea of the contents of this
website. I used it quite frequently when first installing Linux and
configuring the X Window System. I learnt a lot about videocards and
monitors, including the concepts of screen resolution, color depth etc.,
useful when troubleshooting X display problems.
-----------------------------------------------------------------------------

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

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