Meta-FAQ
RTFM!
by Ben Goren
If somebody referred you to this page, it’s for a reason. You have asked a question about OpenBSD that you should have answered yourself, for the simple reason that the best answer you can get has already been written and can be found in the links on this page. Do not persist in pressing your question until you have read the documentation referenced by this page.
Let’s set one thing straight, right off the bat: the documentation for OpenBSD absolutely rocks. The answers are (almost) all there. And this document is in no way intended to be a replacement for the real thing.
Spend any time on the OpenBSD mailing lists, and you’ll find that, despite all the amazing hard work the development team has done in creating outstanding documentation, people still have a tendency to ask the same well-answered questions over and over and over and over and over and over again.
And that’s the reason for this document. The next time you see somebody ask a question whose answer is pointed to here, feel free to use the link in a “RTFM” response.
I’ve started the list by gathering up some of the more obnoxious queries over a few weeks of traffic. I’ll add to this as time goes by, and probably eventually build a database to hold it all together. If you want to add an entry, simply mail it to me in the same HTML source format as you see here.
Where to start
afterboot
If you haven’t already done so—no matter what your question is—start with with the afterboot manual page. Read it all. Now.
FAQ
The OpenBSD FAQ doesn’t just answer those questions that get asked frequently; it’s also a serious piece of documentation, more akin to the FreeBSD Handbook than most other FAQs. It’s got lots of great stuff.
Manual Pages
If you’re used to the sorry state of manual pages on some other Unices and Unix-like operating systems, you’re in for a treat. Everything in OpenBSD has a manual page, and every manual page is both thorough and authoritative. It’s part of the OpenBSD way that software isn’t complete until the documentation is, and the documentation should be in the form of a manual page unless there’s a darn good reason for it to be otherwise.
If you really want to get an incredibly impressive amount of knowledge about OpenBSD, do the following (and be prepared to spend a lot of time doing it) on an OpenBSD system: man ‘ls /bin /usr/bin /sbin /usr/sbin /etc‘. Or, just get real friendly with xman.
The search engine, Google, is astounding. Try to find what you’re looking for there, and you’ll almost certainly be pleasantly surprised. All the major OpenBSD documentation sources and probably all of the minor ones are regularly re-indexed by Google. This includes the archives for the mailing lists such as the one that you probably posted your question to. It even includes this very document that you’re reading right now!
Mailing List Archives
At the bottom of the offical page devoted to OpenBSD Mailing Lists are links to the various archives of the lists. I personally happen to prefer what the primates at monkey.org have done, but that shouldn’t stop you from using one of the others.
My site
If I may be so bold as to..ah…blow my own horn, I’ve created a fair amount of relevant content on this very site. If you don’t know how the Internet works, read my paper on Internet protocols. In a similar vein, many people use OpenBSD to secure their networks. I’ve committed some of my ideas for network design to pap—er, electrons. OpenBSD makes extensive use of cryptography; it’s a good idea to understand the fundamental concepts involved. Some of the worst flame wars on the lists have revolved around questions about or failure to follow proper netiquette. There’s more, too—you might want to start at the top or with the site map.
The Questions
For now, these are in no particular order. Use the fragment link in references.
Help me!
We’d like to—we really would—but you didn’t do much more than shout a plea into the ether. Before we are humanly capable of helping you, you must send the following in your request for help:
- exactly what you’re having trouble with;
- a detailed description of the problem itself;
- what triggers the problem;
- when in doubt, a dmesg;
- the complete contents of relevant configuration files (sanitized for sensitive information if need be, but be darn carful when you make your edits);
- what you’ve done to try to fix it yourself (“He” is said to help those who help themselves; on the OpenBSD lists, you at least have to try to help yourself to get interest in your problem);
- what documentation you’ve searched for your answer.
That last deserves a bit of explanation. First, it shows that you’re not just looking for somebody to re-type in an email what he or she has already typed in a manual page (yes, code and documentation authors read and post to the lists). Next, if your problem is or should be in the documentation you read yet it didn’t help, the authors will consider revising the documentation. Finally, most of the time, if you search the documentation, you’ll almost always answer your question, yourself—as well as the next three questions you would have had but didn’t know you were going to have.
I discuss this topic further in my rant about netiquette.
Please reply to foo@bar.com since I’m not subscribed.
Don’t expect a lot of help, then. Many of the most active list members consider this behaviour rude, likening it to sticking your head in the door at a local user’s group meeting, shouting your problem, and ending with, “I gotta run. The keys are under the doormat; fix it for me by six, okay?”
The OpenBSD lists are not there to give you free tech support nearly so much as they’re there to discuss interesting problems. Free tech support for OpenBSD exists, in the form of the excellent and copious documentation detailed elsewhere in this document. If your question is simple and uninteresting, you’ll probably be told, “RTFM!” but you’ll probably also be told which FM to R. If your question is hard and interesting, the answer probably won’t come out without some discussion, all of which you’ll miss if you’re not on the list.
There are exceptions, certainly. “I’m having trouble with my mail, so please copy foo@bar.com,” is a different beast entirely. This and similar problems are much more likely to elicit sympathy and direct responses.
If you’re doing a survey—and you shouldn’t be doing a survey unless you’ve been on the list for a long time—it may well be appropriate to ask for off-list replies that you’ll summarize later, but none of the OpenBSD lists really run like that.
So, in short, if your question is worth getting the list involved, it’s certainly worth you getting involved with the list. And, you just might learn something new! I sure have….
Why does everybody hate me?
“We” don’t. Many of us, however, have a low tolerance for those who don’t make due dilligence to help themselves. If you want hand-holding, it’s already been done in all the sources referrenced here. When a toddler wants somebody to read a story out loud, it’s cute and healthy. When an adult wants somebody to re-type a technical manual, it’s obnoxious. If you feel you’ve been maligned, chances are you violated proper netiquette in one form or another. Oh—STFW while you’re at it.
Please help me with the attached file.
How do I activate PPP on startup?
STFA.
Does OpenBSD support encrypted filesystems?
RTFM. Also search the archives for caveats.
How can I calculate netmasks / specify ranges of IPs?
How do I install an RPM under OpenBSD?
First, see if there isn’t a native OpenBSD port or package (RPM is a Linuxism). Otherwise, STFA.
Help me tweak my kernel.
Use the GENERIC kernel unless it really, truly won’t do for you. Unless yours is a truly exceptional case (and, if it is, you don’t need to ask), you won’t get any performance or other benefits from a custom kernel. You won’t learn anything inspirational. It’s not a rite of passage and won’t confer Alpha Geek status upon you.
If you still want to proceed, dmassage is a nifty project. RTFAQ. RTFMs: options (4), config (8), release (8), and those referenced therein.
Do be aware: nobody’ll be much interested in helping you if you have problems and you’re using a custom kernel. The developers have gone to great pains to create a very versatile and high-performance kernel and tend to get ticked when people try to second-guess them, fail, and blame OpenBSD.
How do I tell what processes have open which files and network sockets?
RTFM.
How do I change my NIC’s Ethernet (MAC) address?
Officially, you don’t. Unofficially, there’s sea.c; STFW. Because it’s unsupported, it’s not guaranteed to work, though lots of people have reported success.
How do I make OpenBSD and VMware work together?
For OpenBSD as a guest running under VMware, STFW. If you’re having trouble with X and VMware, see Matt Rickard’s guide. VMware will not run with OpenBSD as the host operating system until somebody reates a port of it (but see Jason Ish’s port for a possibility). Use another operating system for the host (FreeBSD is an excellent choice here if you don’t like Linux) or use one of the programs that already exists under /usr/ports/emul.
Why does locate find / not find files that do / don’t exist?
RTFM.
I’m trying to upgrade a system and things aren’t working.
99.95% of the time this is because of a failure to precisely follow the instructions in the Upgrading Mini-FAQ or release (8). Start over again—regardless of what’s going on, it’s always best to start over at the beginning when things go worng unless you’re qualifed to fix the problems, yourself—and follow those two documents most religiously. Really.
If you’re trying to upgrade to -current and you can’t figure it out, then -current isn’t for you. The developers work hard to make sure -stable is something that works flawlessly for everybody; -current is where they’re playing around with things, occasionally breaking them in the process. It’s fun to experiment with -current, but it’s rarely fun to live with a -current system. If you really want -current and can’t get it to build from sources, you really don’t want -current, but you should be able to install from a snapshot.
Or, in other words, if you can’t handle open wounds, stay away from the cutting edge. (But do feel free to experiment, on your own on a non-critical system, if you’re curious.)
How do I create / edit manual pages?
RTFM. Sheesh!
What’s the proper way to administer my computer?
With sudo. This means not logging in as root and not using su. Both have their places, but, if you have to ask, you really should be using sudo.
ps, top, and other programs have stopped working.
You’re using a kernel from one system and userland (the rest of the binaries) from another. Most commonly, this happens when somebody builds a -current kernel on a -release or -stable system. Don’t do that then! This is now addressed in the upgrading mini-FAQ in section 1.14. If you’re guilty of this sin, then you should use the patch branch, only the patch branch, and nothing but the patch branch. The development releases are not for you, not by a long shot.
I can’t send mail to my computer.
Since 3.0, sendmail doesn’t listen on the network by default. Change it in /etc/rc.conf.
OpenBSD should do foo!
Perhaps it should, but don’t expect your argument to get much attention unless it’s obviously brilliant to everybody else, too, or unless you’re already well-known and respected by the OpenBSD team. If you think the developers are too dense or too slow to do what you want them to, fork the code. It’s yours, free for the taking. If the developers like what you do and it meets the necessary requirements, you can be sure they’ll merge it back into OpenBSD—but do note that those are two really big “if”s. Quoth Theo: “We develop what we need, for fun, in our own time.” This also applies to things other than code: the document you’re reading exists because I think it should—as best I know, the developers don’t have any special interest in it.
How do I optimize performance of my pf ruleset?
STFA. Should be lots more information elsewhere.
Is this $PATH (in)secure?
STFA.
…but if I reboot, that’ll wipe out all my uptime.
Uptime has nothing to do with the size of your anatomy, but you might want to STFA anyway.
I don’t get IPSEC.
IPSEC is hard. Personally, I’m starting to think that the protocol is poorly designed, being more complex than is truly necessary. The best help out there is in the FAQ and at allard.nu. Do be sure to do your homework, though, before asking questions.
Is anybody working on…?
Lots of people are working on lots of things for OpenBSD. infomatrix.ca has great information on who’s doing what, with an emphasis on the “unofficial” work.
I need to upgrade my computer, but it’s on the other side of the galaxy.
If you have to ask, it might not be a good idea to attempt this on a critical system. Do lots of research before you do anything. Start with something like Pintday’s howto.
I can’t restart sshd.
STFA.
I want to install OpenBSD on a RAIDFrame (software RAID) array
STFA.
How can I edit a crontab from within a script?
STFA.
I want to build from sources but don’t want to install everything.
STFA.
How does https work with virtual hosts?
What hardware works best under OpenBSD?
STFA. For example Theo’s preferences or Nick on ISA NICs.
How fast is pf?
How can I make my system faster?
RTFAQ and STFA. Note that there are lots and lots of things that will make certain aspects of a system perform better, but almost always at some expense. For most people, if a system with default configurations isn’t getting the job done, you either need to do your homework or throw money at the situation (and very likely both). Some people—Henning Brauer and Diana Eichert spring to mind—stress their systems to the limit and do amazing things squeezing enough extra oomph out of a high-end system to make the difference between high responsiveness and a helpdesk flooded with complaints. If you’re a mere mortal, it really doesn’t make any difference if your word processor launches in eleven seconds or nine. The experts on the list can give you great advice on how to build a hotter fire. Follow that advice, by all means—but only after you’ve taken precautions against getting burned. Such precautions always include reading lots and lots of manual pages, good backups, and the willingness to let well enough alone.
Does OpenBSD work with multisession CDs?
No. STFA.
Where can I get an OpenBSD ISO?
RTFAQ. There’s a very nice ISO image already burned onto CD for you that you can get from the OpenBSD Web Site. If you just want to try out OpenBSD, do an FTP install using floppies. If you want to make your own customized CD-ROM, STFA.
How do I use Unix?
If you’re absolutely brand new to Unix, some of the OpenBSD documentation could be a bit intimidating. Basic information on Unix is available.
I can’t get Mozilla to work!
First, it’s worth noting that there have been great advancements recently. -CURRENT as of this writing has a fully-functional port and package. If you’re using something older, read on for my original notes….
Neither, it would seem, can anybody else—though there are regular tantalizing reports of partial success. Search the archives and see what I mean. In the mean time, Konqueror is in the ports tree, is every bit as good a broswer and as standards-compliant as Mozilla, and can be run without KDE. You’ve also got Netscape 4, Opera, and other browsers in the ports tree. Dillo has a following. There was recently a lengthy thread on the topic. Use something other than Mozilla and wait—or, prefereably, help make Mozilla work. The same goes for {Open,Star}Office.
Those who have been following the news very recently know that there have been recent breakthroughs with Mozilla. It can be made to work but the solution as of this writing is less than ideal. STFA and stay tuned….
I want to use Java on OpenBSD
There are JDKs and other toolkits in the ports tree. Christian Gruber maintains the Java on OpenBSD page, and there’s a list devoted to J2SE on OpenBSD.
How can I do LDAP authentication?
Peter Werner has an authentication module to do the trick. Additionally, be sure to STFW.
These strange things are happening…
It would seem likely that you’ve got some bad hardware. The Sig11 FAQ is a good place to start. Yes, it says, “Linux” all over the place, but you can safely overlook that bit of jingoism. STFA to read about what I do. Note: Kyle R. Hofmann was sufficiently upset at my suggestion that zero and one might be prime that he wrote me privately. He’s given me permission to use his words to set the record straight.
I can’t boot so I can’t get a dmesg!
Make and boot from an install floppy. At the prompt, select the [S]hell. Remove the install floppy and insert a DOS-formatted floppy in its place. Type mount -t msdos /dev/fd0c /mnt followed by df to mount the disk and make sure it got mounted and has at least some free space. Type dmesg > /mnt/dmesg to create a file on the floppy with the output of the dmesg command. Take the floppy to a working computer. Note, all those commands should be followed by pressing the “Enter” key.
How can I restrict users to their home directory with {,s}ftp?
For plain ’ol FTP, RTFAQ and RTFM. For sftp, you can’t; STFA (though you might have some success with CHRSH, which creates a chroot environment with a login shell).
The documentation says, “foo,” but does it really mean what it says?
I’m glad you asked! No, there is not one word of truth whatsoever anywhere in the OpenBSD documentation. It’s all lies, lies I tell you! The developers are so diabolical that they write deceptive documentation designed solely to lead you straight to perdition. Run away while you can!
Help me with IPF.
IPF is no longer a part of OpenBSD. It hasn’t been a part for quite some time. The last version which did ship with IPF, 2.9, is over a year old and is therefore no longer supported. There also happens to be a lot of bad blood between the OpenBSD developers and Darren Reed, the person responsible for IPF. So, in short, if you’re having trouble with your system and IPF is in the mix, don’t ask misc@ for help. Instead, ask the IPF mailing list or Darren himself. If you want my biased opinion, dump IPF. OpenBSD’s pf is far superior.
I want to permit anonymous uploads with FTP.
You really, really don’t want to do this. There are many better solutions and lots of potenial traps. If you insist on proceeding, be sure to set the -u flag in ftpd to 666 to ensure all files that get uploaded are unreadable. STFA for details.
How can I monitor the official Web site for changes?
There are many kludges out there that check /errata.html and other files for changes; people do this to stay on top of patches, etc. There’s a better way: STFA.
Will a fix for foo make it into -STABLE?
Only if it’s significant. The developers won’t leave everybody high and dry, but their attention goes into making the next release better.
If there’s something you really, really need that isn’t in stable, you have three choices: run -CURRENT until it becomes -STABLE; back-port the change, yourself; or pay somebody to do something for you.
Running -CURRENT carries its own risks. Doing so in a production environment means really staying on top of things, because -CURRENT is where things get broken. Take this route if you religiously follow the development process and you can tolerate occasional periods of brokenness. A workstation may be a good candidate computer for this choice.
If what you need has been fixed in -CURRENT but not -STABLE, it’s time to learn CVS. You can generate a diff that encompases the changes and use that as a starting point for your own fixes to the code. This could be as simple as applying the diff and re-compiling…but, it might not be. Bugs can be subtle, and, if you don’t know the scope of the changes, there may be peculiar logical dependencies. Take this route if the computer must be stable and you’re a competent programmer.
If neither of the above work for you, hire somebody to do them for you. Either hire a sysadmin who’ll keep your computer working as best as possible with -CURRENT or hire a good programmer to back-port the fixes you need. The core members of the development team generally don’t have a lot of time available, but might be willing to do the fix if they’ll be paid proper consulting rates. There are lots of good programmers who use OpenBSD and who are not core developers; chances are excellent that a programmer-for-hire will be happy to take you on for a client.
There is, of course, one other option: shut up and live with it.
Who can do what with this document?
This document is copyright © 2002 by Ben Goren. All rights reserved. A non-exclusive, irrevocable, perpetual, transferable, unrestricted license is granted to anybody with an official “@openbsd.org” email address. All others must limit their use to what’s permitted by copyright law.