appearance of that word in the page. Typing n subsequently will jump you to the next occurrence of that word.
[1]It's called "honesty" as opposed to the "marketing" included in many other software products.
The FreeBSD Documentation
If you installed the FreeBSD documentation, you'll find it under/usr/share/doc. You'll find several directories there, including one for each language that FreeBSD's documentation has been translated to. If your language of choice is English, you'll probably want the "en" directory.
The FreeBSD documentation is divided into articles and books. The difference between the two is highly arbitrary: As a rule, books are longer than articles, and cover broader topics; articles are short and focus on one topic. The two books that should most interest new users are the Handbook and the FAQ, both of which are available online at http://www.freebsd.org/.
The Handbook is the FreeBSD Project's continually changing guidebook. It describes how to perform basic system tasks and is a good reference when you're starting on a project. The FAQ (Frequently Asked Questions), like the Handbook, is divided by topics, but also contains answers to mailing list questions. Some of the FAQ's information is duplicated in the Handbook, but most is not.
If you think you know what you're doing and have a particular question about an error you're encountering, check the FAQ. If you don't have a clue about what you're doing, check the Handbook. If the Handbook doesn't help, search for an article about what you're trying to accomplish . (You can search the entirety of the FreeBSD documentation set at http://www.FreeBSD.org/search/. If that doesn't help, you can use that same page to check the mailing list archives.)
The Mailing List Archives
Unless you're really on the bleeding edge, someone has probably struggled with your problem before, and likely posted to the mailing lists about it. After all, the archives go back to 1994 and contain about a million messages. Of course, the challenge of having a million messages is finding what you want.
When you're stumped, take your error message and copy it into the mailing list archive search box at http://www.FreeBSD.org/search/. Remove common words such as "and," "or," "but," and so on, and hit the search button. (This page defaults to searching the FreeBSD−questions mailing list.) If you don't get a result right away, try entering another message or phrase the computer is giving you during your troubleshooting. I usually get an answer within two or three searches.
If you can't find anything useful in the FreeBSD−questions archives, try another mailing list that seems appropriate. Some good ones include FreeBSD−hackers, FreeBSD−stable, and FreeBSD−current. If you're having a problem with a particular subsystem, check for a mailing list devoted to it.
Note The entry fields for searching the documentation and the mailing list archives are on the same page! More than once, I've searched the documentation when meaning to search the mailing list archives.
42
Other Web Sites
If you haven't found your answer by this point, there are a variety of other Web sites you might try.
∙FreeBSD Diary (http://www.freebsddiary.org/) This site details users' experiences with FreeBSD. The articles include detailed descriptions of how they make everything work.
∙Google (http://www.google.com/) This site archives Usenet news on many topics, including FreeBSD. Try a power search on mailing.FreeBSD.* or comp.unix.bsd.FreeBSD.*, which will give you both the mailing lists and the newsgroups. (Google also hosts a BSD−specific search engine at http://www.google.com/bsd.)
∙Daemonnews (http://www.daemonnews.org/) This is a popular BSD news site. Their monthly issue contains a variety of articles on various BSD topics.
∙The FreeBSD 'zine (http://www.freebsdzine.org/) This is a bimonthly FreeBSD article site, and includes many useful articles.
∙Defcon1 (http://www.defcon1.org/) Another FreeBSD article site.
∙BSD Today (http://www.bsdtoday.com/) This http://internet.com/ site hosts BSD articles and news links.
∙O'Reilly Network BSD Developer Center (http://www.onlamp.com/bsd) This site hosts a variety of BSD articles, including the column "Big Scary Daemons" by yours truly.
Using FreeBSD Problem−Solving Resources
Okay, now let's pick a common problem and use the FreeBSD resources to solve it. We'll use several different methods to find an answer . Take this typical message sent to FreeBSD−questions@FreeBSD.org.
"I've just installed FreeBSD and my network isn't working. When I try to ping, the console shows the message ed0: device timeout. What's wrong?"
Checking the Handbook/FAQ
A scan of the handbook shows nothing related to the problem. In the FAQ, however, there's an entry under Troubleshooting:
...............................................................................................
I keep seeing messages like ed1: device timeout
...............................................................................................
That's close enough. Read that entry, and try the solution presented.
Checking the Man Pages
As we go on, you'll learn that the numbers after device names are simply instances of a particular device. ed0 is simply device ed, unit number 0. So, type man ed. You will see the following:
43
...............................................................................................
ED(1) FreeBSD General Commands Manual ED(1)
NAME
ed, red − text editor
SYNOPSIS
ed [−] [−sx] [−p string] [file]
DESCRIPTION
Ed is a line−oriented text editor. It is used to create, display, modify and otherwise manipulate text files.
If invoked with a file argument, then a copy of file is read into the editor's buffer. Changes are made to this copy and not directly to file itself. Upon quitting ed, any changes not explicitly saved with a w command are lost.
Editing is done in two distinct modes: command and input. When first invoked, ed is in command mode. In this mode commands are read from the standard input and executed to manipulate the contents of the editor buffer. A typical command might look like:
,s/old/new/g
:
...............................................................................................
What the heck? Something's obviously amiss here. Every device driver has a man page. Run man −k ed to get a complete list of all the man pages related to ed. You'll get a whole list of functions, in slightly skewed alphabetical order. (Capital letters come before lowercase ones.) Scroll down to the e's, and you'll see this:
...............................................................................................
... |
|
|
ed(1), −(1) |
− |
ed text editor |
ed(4) |
− |
high performance ethernet device driver |
... |
|
|
...............................................................................................
Aha! There are two different eds, in different sections, each with their own man page. Type man 4 ed and you'll see what you want:
...............................................................................................
ED(4) FreeBSD Kernel Interfaces Manual ED(4)
NAME
ed − ethernet device driver
SYNOPSIS device ed
DESCRIPTION
The ed driver provides support for 8 and 16bit ethernet cards that are based on the National Semiconductor DS8390 and similar NICs manufactured by other companies.
It supports all 80x3 series ethernet cards manufactured by Western Digi− tal and SMC, the SMC Ultra, the 3Com 3c503, the Novell NE1000/NE2000 and compatible cards, and the HP PC Lan+. ISA, PCI and PC Card devices are supported.
44
The ed driver uses a unique multi−buffering mechanism to achieve high transmit performance. When using 16bit ISA cards, as high as 97% of the theoretical maximum performance of the IEEE 802.3 CSMA ethernet is possi− ble.
:
...............................................................................................
This is what you're looking for. Looking at the error message, you can guess that timeout is a good keyword. Type /timeout and press ENTER.
...............................................................................................
ed%d: device timeout Indicates that an expected transmitter interrupt
didn't occur. Usually caused by an interrupt conflict with another card
on the ISA bus.
...............................................................................................
Voila! Here we have a terse explanation of the problem, and a probable cause (interrupt conflict). We have a good old−fashioned IRQ problem.
Checking the Mailing List Archives
Searching for "ed0: device timeout" spit out quite a few results from the mailing list archives. On the day I did the search, the first response gave the solution.
Using Your Answer
Any answer you get for our "ed0 timeout" example assumes that you know what an IRQ is, and how to adjust one on your hardware. This is fairly typical of the level of expertise required for basic problems. If you get an answer that is beyond your comprehension, you need to do the research to understand it.
While an experienced developer or systems administrator is probably not going to be interested in explaining IRQs to you, he or she might be willing to point you to a Web page that explains IRQs.
Mailing for Help
If the archives, FAQ, Handbook, tutorials, and other assorted resources cannot help you, ask for help. When you do, be sure that you include all the information you have at your disposal, as discussed shortly. There's a lot of suggested information to include, and you can choose to skip it all. But if you do, one of two things will happen:
∙Your question will be ignored.
∙You will receive a barrage of email asking you to gather this information.
If, on the other hand, you actually want help to solve your problem, include the following in your message:
45
∙A complete problem description. A message like "How do I make my modem work?" is going to generate a multitude of questions, like what do you want your modem to do? What kind of modem is it? What are the symptoms?
∙It's much better to start with a message like, "My modem isn't dialing my ISP. The modem is a BleahCorp v.90 model 6789. My OS is version 4.6−stable, on a dual Athlon motherboard. There are no error log messages in /var/log/ppp.log." You'll shortcut a whole round of email by doing so. While I have never seen anyone flamed for offering too much information on the FreeBSD−questions mailing list, the converse is not true.
∙The output from uname −a. This gives the operating system version and platform.
∙If you run CVSup and "make world", give the date of the last CVSup, if you have it.
The CVSup date, in seconds from the epoch, is the third field in the first line of your log file. (Of course, if you have upgraded your source without building "world", this is moot.) For example, on m y s y s t e m , C V S u p r e c o r d s i t s d a t a i n / u s r / s u p . T h e f i r s t l i n e o f /usr/src/src−all/checkouts.cvs:RELENG_3/ is:
...............................................................................................
F 5 939160270
...............................................................................................
Running date −r 939160270 spits out the following:
...............................................................................................
Tue Oct 5 21:51:10 GMT 1999
...............................................................................................
∙Any error output. Be as complete as possible, and include any messages from your logs, particularly /var/log/messages.
Finally, here are some tips for getting your best results out of a FreeBSD mailing list:
∙Be polite. Remember, this list is staffed by volunteers who are answering your message out
of sheer kindness. Before you hit that send key, ask yourself, "Would I be late for my date with the hot twins down the hall to answer a message from someone like this?"[2]
∙Use plain text. Many FreeBSD developers read their email in a command−line environment, and find reading raw HTML quite annoying. (To see for yourself, install/usr/ports/mail/mutt and read some HTML email with it.)
∙State up front exactly what you have done to solve this problem or answer this question. Make it clear that you have done your homework.
∙Be on topic. If you are having a problem with XFree86, check the XFree86 site. If your window manager isn't working, ask the people who maintain it. Asking the FreeBSD folks to
46
help you with your Java Application Server configuration is like complaining to hardware salespeople about your fast−food lunch. They might have an extra ketchup packet, but it's not really their problem. On the other hand, if your FreeBSD system starts sendmail on every boot, and you want to turn it off, check the online resources and then ask.
∙Send your message to FreeBSD−questions@FreeBSD.org. Yes, there are other FreeBSD mailing lists, some of which are probably dedicated to what you're having trouble with. As a new user, however, your question is almost certainly best suited for FreeBSD−questions. I've lurked FreeBSD−stable, −current, and −hackers for years now, and have yet to see a new user ask a question there that wouldn't have been better served in FreeBSD−questions. Generally, the questioner is referred back to −questions.
Sending a message to FreeBSD−hackers asking how to fix your dial−up connection is only going to annoy them. You might get an answer, but you won't make any friends. Conversely, the people on FreeBSD−questions are there because they are volunteering to answer questions. These people want to hear from you. Quite a few are FreeBSD developers, and some are even core members. Many of them are very skilled, and many are new users who have already dealt with your problem.
If those folks can't help you, they'll probably refer you to another mailing list. It's much better to go to −hackers and say, "The folks on −questions suggested I ask you about this" than to just jump straight to −hackers. If you respect the FreeBSD community, they'll respect you.
∙Follow through. If you're asked for more information, provide it. If you don't know how to provide it, treat it as another problem. Go back to the beginning of this chapter and try to figure it out. If someone asks you for a debugging dump, go look at Chapter 16 and set your system up for it. The bottom line is, if you develop a reputation as someone who doesn't follow up on requests for more information, you won't even get a first reply.
∙Lastly, "how can I learn this" questions are more likely to be answered than "what do I do" ones. It doesn't matter if the question is about obscure system functions or simple troubleshooting; being willing to work for your answer is a necessary part of running FreeBSD. The upside is, when you're done, you will actually understand more about your computer than you did before.
Now that you understand where to go when this book doesn't quite go far enough, let's look at how you can protect yourself from your own mistakes.
[2]Quite a few developers would accept the phone number for said twins in lieu of politeness. This isn't guaranteed, and is only supported in the bleeding−edge−current.
47