Using OpenBSD Problem-Solving Resources
Let’s pick a common question and use the OpenBSD resources to solve it, without resorting to sending mail. One of the things OpenBSD is known for is its support for cryptography in hardware. How does that work, and what does OpenBSD do to support it? Here’s how I would search for information on this topic from each information source the OpenBSD Project provides.
Using the OpenBSD Website
Look at http://www.OpenBSD.org/ and you’ll see a link to Crypto. This takes you to the Cryptography page, which covers OpenBSD’s cryptography support. It includes algorithms and discusses how the team has integrated OpenSSL into hardware cryptographic accelerators. Read, learn, and enjoy.
Using Man Pages
Let’s try running apropos cryptography:
$ apropos cryptography
RSA_public_encrypt, RSA_private_decrypt (3) - RSA public key cryptography
This man page isn’t terribly useful as a general overview, and whatis cryptography doesn’t return anything.
Cryptography is often referred to as crypto. apropos crypto gives too many results. whatis crypto gives more reasonable results:
$ whatis crypto
crypto (3) - OpenSSL cryptographic library
crypto (4) - hardware crypto access driver
crypto (9) - API for cryptographic services in the kernel
This is a fairly short list, and all the entries look promising. Manual section 3 is for programmer interfaces, section 4 is for device drivers, and section 9 is for the kernel. If you’re specifically looking for hardware cryptographic accelerators, section 4 should jump out at you, but start wherever you feel most comfortable.
Using Internet Searches
Go to your favorite search engine and search for “OpenBSD crypto hardware support.” On the day I wrote this, the first result led me to the official page on the OpenBSD website. The second hit was a paper on the OpenBSD cryptographic framework. You’ll find old articles, archived mailing list discussions, man pages, tutorials, and innumerable blog posts. You’ll probably need to add the model number of a particular cryptographic accelerator card to reduce the results to a manageable number.
Using Mailing Lists
If the mailing list archives, a web search, the OpenBSD FAQ, the OpenBSD website, the integrated manual, and other assorted resources do not answer your question, you can ask for help. A variety of highly knowledgeable and very skilled computing professionals read the OpenBSD mailing lists. Many of these people enjoy working with OpenBSD and want to help intelligent new users. In their minds, “intelligent” equates to “not asking a question that has been asked before.”
Have another look at all the ways we gathered information on OpenBSD’s cryptographic hardware accelerator support in the previous section. Information about most other topics is just as readily available. People who take the time to read and answer questions on the OpenBSD mailing lists have already spent considerable time and energy creating this content and ensuring its accuracy. Now imagine their reaction when someone asks about cryptographic accelerator support on the public mailing list. Most OpenBSD experts will assume any of the following:
-
The person wants their hand held.
-
The person is unwilling to read the documentation.
-
The person has nothing but contempt for the OpenBSD developers.
-
The person has the intelligence of a brick.
Most OpenBSD experts would conclude that the person asking the question simply isn’t ready to run OpenBSD. At best, the questioner will be ignored. At worst, some experienced OpenBSD person who wrote all this documentation will take offense at his hard work being so thoroughly discounted and flame the questioner badly enough that his monitor will need three months in the Mayo Clinic burn unit.
Keep this in mind before you send an email. Have you really checked everywhere for an answer? Are there any other search terms you haven’t tried? Performing a few extra searches with different keywords is much faster than composing a useful email, and there’s an excellent chance you’ll find the answer to your question.
If you’re familiar with other free Unix-like operating systems, OpenBSD’s mailing lists might give you a bit of a culture shock. OpenBSD users are advanced computer users almost by definition. If an experienced systems administrator tries to debug a piece of software, that administrator is expected to know enough to ask the responsible party. If you go to a Linux forum, you’ll find people discussing server and client programs, desktop environments, and dang near any other piece of software that runs on that platform. Those forums are manned by volunteers dedicated to providing around-the-clock support and extreme efforts to help their operating system conquer the world.
The OpenBSD folks don’t care if they take over the world or not. They don’t really care if you use their software. If other people can get use out of it, that’s great. If not, oh well. They will happily assist you with OpenBSD-specific problems, but they don’t really care about your database issues or your website. If you’re having trouble porting your preferred window manager to OpenBSD because of some subtle bug in OpenBSD’s libc, the OpenBSD people would love to talk to you. If you can’t configure your window manager the way you like, then you should talk to the window manager support group instead.
Creating a Good Help Request
Before you send an email, think carefully about the problem you’re trying to solve. What question should you actually be asking? Define the issue as narrowly as possible. Suppose you cannot connect to a virtual private network (VPN) server with OpenBSD’s IPsec client. Is the problem that you can’t actually reach the IPsec server? Does the connection work when you turn off your OpenBSD firewall, but return when you re-enable filtering? Does isakmpd(8) crash and leave a core file every time you try to start the VPN? Each of these is a very different problem. Including the precise problem in your email will get you a better reception.
The first paragraph of your email should state your problem briefly and succinctly. If your first paragraph doesn’t contain enough to interest people, they’ll probably delete the email before getting to anything relevant.
After that important first paragraph, gather any and all information related to the problem. Include this information in your email. This should include the following:
-
The version of OpenBSD you are running
-
Your hardware platform
-
Any error output (be sure to check /var/log/messages as well as your terminal)
-
The contents of /var/run/dmesg.boot
-
A complete but narrow problem description
Give your email message an appropriate subject. A subject like “Problem with OpenBSD” will get ignored. A subject like “Reproducible isakmpd crash on newest OpenBSD snapshot” will immediately attract attention. Many OpenBSD people decide which messages to read based entirely on the subject line. Moderately advanced email-reading programs allow the recipient to delete an entire thread of discussion based on the subject line or message headers.
How to Be Ignored
Many senior OpenBSD users use a text-based email reader such as Mutt (although quite a few do use more graphic email readers, mind you.) Text-based email programs are very powerful programs for handling thousands of emails a day, but they show only text, and they do not display HTML messages well. If you are using a graphic mail client such as Mozilla Thunderbird or Microsoft Outlook, wrap your text at 72 columns. Sending mail in pure HTML or without readable line wrapping invites experienced recipients to discard it unread.
This might seem harsh, and it’s definitely different from mailing lists run by other open source operating systems. But most email clients are not suited to handle thousands of messages in a day, scattered across dozens of mailing lists, with several parallel discussion threads each, in a manner accessible to the human mind. I receive thousands of email messages a day, and I know many OpenBSD developers get—and process—even more. We simply cannot cope without mail tools that address our problems. HTML support is not nearly as necessary as the ability to manage, present, and process a large number of messages in a sensible manner.
On a similar note, most email attachments are unnecessary (and several of the OpenBSD mailing lists will unceremoniously strip them from incoming messages). You do not need to PGP sign your email, and those business card attachments just demonstrate that you really shouldn’t be running OpenBSD. If you include a signature in your email, it should be no longer than four lines. Long ASCII art signatures, even really nifty ones featuring the OpenBSD blowfish, are right out.
It’s easy to let frustration turn a simple request into a rabid demand for immediate assistance. Remember to be polite; the people who receive your message might decide to help you, but they’re under no obligation to do so. If you want someone to be obliged to help you, buy a support contract.
Sending Your Email
Before sending your email, double-check your search engine. Are you sure this hasn’t been asked before?
Send all of your information and your narrow, specific, documented question about the OpenBSD core system to [email protected]. Yes, OpenBSD has many other mailing lists, and some of them might look more appropriate for your problem, but people who post to them are almost always told to go ask on misc@ instead. People on misc@ might refer you to another mailing list, but it’s much better to post a message to a specific list if that message starts with “So-and-so on misc@ recommended that I ask this here.” If you have a narrow, specific, well-documented question about a piece of add-on software (or package, as discussed in Chapter 13), you can send it to [email protected] instead.
Responding to Email
The response you receive might be a brief note with a URL, or even just the words “man such-and-such.” If that’s what you get, that’s where you need to go. Remember that you’re asking because you don’t understand something, and these responses tell you where to learn the answer to your question. Don’t just email back asking someone to hold your hand.
If you don’t understand the reference you’re given, treat that as another problem. Narrow down the source of your confusion. Man pages and tutorials are not perfect, and some parts might seem mutually exclusive or contradictory if you don’t fully comprehend them.
Finally, follow through. If you’re asked for more information, provide it. If you don’t know how to provide it, treat that as another problem. Go back to the beginning of this chapter and try to figure it out. 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.
Now let’s get ready to actually install OpenBSD.