Sources of Information
OpenBSD provides information through three primary channels: manual (man) pages, websites, and mailing lists. To understand why your system behaves in a particular way in your environment, you might need to check all three.
Man Pages
Man pages are the original format for presenting documentation on Unix-like systems. While man pages have a reputation for being obtuse, difficult to read, or incomplete, the OpenBSD team expects its man pages to be readable, correct, and complete.
When man pages were first created, the average system administrator was a C programmer. As a result, man pages were written by programmers for programmers. The OpenBSD developers are programmers and consider man pages the final word in OpenBSD documentation. Even documentation errors are considered serious bugs and are dealt with as quickly as possible. Man pages should be your first line of attack in learning how OpenBSD works.
That said, a man page is not a tutorial. The manual explains how things work, not what to type to achieve particular effects. You must be able to assemble the knowledge offered by the man page into the tool that you need. If you want tutorials, read articles on third-party websites, the FAQ, and this book. If you find a tutorial that tells you how to do exactly what you want, read the relevant man pages along with the tutorial. Just remember that anyone can write a tutorial, and there’s no guarantee of any particular tutorial’s effectiveness or security.
Manual Sections
The OpenBSD manual has nine sections, and each man page appears in only one section. These sections are sometimes called volumes, a name from the days when the manual was small enough to print and distribute. Each section covers a single topic. The sections are as follows:
-
1: General commands
-
2: System calls and error numbers
-
3: C libraries
-
3p: Perl libraries
-
4: Device drivers
-
5: File formats
-
6: Games
-
7: Miscellaneous
-
8: System maintenance and management commands
-
9: Kernel internals
Man pages often appear with the section number in parentheses after the command, such as ping(8) or ed(1). This gives you the name of the command (ping) and the section where the command is documented (8, on system maintenance). Almost every part of OpenBSD has a man page.
Viewing Man Pages
View man pages with man(1). If you know the section number, enter it before the program name, but the section number isn’t mandatory. For example, to see the man page for the standard network utility ping(8), enter this:
$ man ping
You’ll get something like this in response.
PING(8) OpenBSD System Manager's Manual PING(8)
NAME
ping - send ICMP ECHO_REQUEST packets to network hosts
SYNOPSIS
ping [-DdEefLnqRrv] [-c count] [-I ifaddr] [-i wait] [-l preload]
[-p pattern] [-s packetsize] [-T tos] [-t ttl] [-V rtable]
[-w maxwait] host
DESCRIPTION
ping uses the ICMP protocol's mandatory ECHO_REQUEST datagram to elicit
an ICMP ECHO_REPLY from a host or gateway. ECHO_REQUEST datagrams
(``pings'') have an IP and ICMP header, followed by a "struct timeval"
and then an arbitrary number of "pad" bytes used to fill out the
packet. The options are as follows:
-c count
Stop sending after count ECHO_REQUEST packets have been sent. If
count is 0, send an unlimited number of packets.
-D Set the Don't Fragment bit.
…
You can learn more than you ever wanted to know about the lowly troubleshooting tool ping just by reading this document. If you need more information, look at the other man pages referenced by ping(8). Read enough pages, and you’ll develop an in-depth understanding of OpenBSD.
Once you’re in a man page, pressing the spacebar or PGDN takes you forward one full screen. If you don’t want to go that far, press ENTER or the down arrow to scroll down one line. Typing B or pressing PGUP takes you back one screen. To search within a man page, type / followed by the word you’re searching for, and then press ENTER. You’ll jump to the first appearance of the search term. Subsequently, typing N takes you to the next occurrence of the word.
Note
The man page navigation discussed here assumes that you’re using the default BSD pager, more(1). If you’re using a different pager, use that pager’s syntax. If you know enough about Unix-like systems that you’ve already set your preferred default pager, you can probably skip this part of the book.
Finding Man Pages
New users often say that they would be happy to read the man pages, if they could find the right ones. You can perform basic keyword searches on the manual with apropos(1) and whatis(1). The command apropos searches for any man page name or description that includes the word you specify. The command whatis does the same search, but matches only whole words. For example, if you’re interested in the vi text editor, you might try the following:
$ apropos vi
…
vmware (4) - VMware SVGA video driver
voodoo (4) - Voodoo video driver
wsudl (4) - video driver for DisplayLink USB display devices
xcmsdb (1) - Device Color Characterization utility for X Color Management System
…
On my system, this generates 686 entries, most of which have nothing to do with vi(1). The random selection of entries shown here includes device drivers and user utilities, but no text editors. If you examine them closely, you’ll see that the letters vi appear in each of them, encapsulated within words like video or de
vice. Depending on what you’re looking for, apropos can offer you far too much information.
Try a similar search with whatis:
$ whatis vi
ex, vi, view (1) - text editors
Matching only whole words can be more useful. Experiment with apropos and whatis until you’re comfortable with them, and you should be able to find just about any topic you like.
Overlapping Man Page Names
Some man pages have a name in common with a man page in another section. For example, suppose someone mentions sysctl and you want to learn about it, so you search the man pages.
$ whatis sysctl
sysctl (3) - get or set system information
sysctl (8) - get or set kernel state
sysctl.conf (5) - sysctl variables to set at system startup
We have a sysctl.conf file and two different man pages called sysctl. Manual section 3 is for C libraries. If you’re just learning about sysctl, you might find this man page intimidating.
By default, man displays the first matching page it finds. It searches commands first, then games, then programming libraries, then add-on programs such as Perl. You can change this search order in /etc/man.conf (see Chapter 14).
In this situation, manual section 3 is before manual section 8. Without specifying a section number, you’ll read about the programming interface. To see the man page for the system administrator command sysctl, you must run man 8 sysctl.
Man Page Contents
Manual authors try to arrange their content meaningfully, although meaningful varies depending on what it documents. A man page for a common user command will probably be much easier to understand than a man page for a kernel-programming interface. Even so, most man pages are divided into sections. Some of the common sections include the following:
-
NAME tells you the names of a program or utility. Some programs have multiple names; for example, the
vi(1)text editor is also available asview(1)orex(1). The man page lists all of these names. -
SYNOPSIS lists the possible command-line options and their arguments, or gives examples for how programmers can call a library or interface. Once you’ve read the man page and used the command a few times, the synopsis might be enough to remind you of what you need.
-
DESCRIPTION contains a brief synopsis of the program or feature. You’ll also find detailed discussions of the command-line options.
-
BUGS describes known failure conditions and weird behavior, and generally discusses when a feature doesn’t work as you might expect. Always look at the BUGS section; it can save you a lot of time. I’ve frequently had a problem with a command only to find that the behavior, and sometimes a work-around, is listed here. Honesty is a wonderful thing in computing products.
-
SEE ALSO is traditionally the last section in a man page. OpenBSD is an interrelated whole, and every command has ties to other commands. In an ideal world, you would read every man page and be able to hold an integrated image of the system in your head. Because most of us can’t do this, this section directs you to related man pages.
Man Pages on the Web
The man pages are also available on http://www.OpenBSD.org/ and its various online mirrors. One of the interesting things about the web-based man pages is that you can look at them for both previous releases and for other architectures. Do you want to know if there’s a difference between the sysctl command for i386 and Loongson hardware? The web versions will let you compare two different man pages. (You can also do this with the integrated manual, but the web version makes it easier.)
The OpenBSD Website
The OpenBSD website (http://www.OpenBSD.org/) contains a lot of information—from administration, installation, and management to where to find hardware. The front page links you to a general discussion about OpenBSD’s goals and support, where you can get OpenBSD, available resources, and ways you can support OpenBSD. Project members keep the website updated. If you have an OpenBSD problem or question, check this website first.
Mirrors
Many people across the world mirror the OpenBSD website. The main website is quite heavily accessed, and mirrors will often respond more quickly. You’ll see links at the bottom of the main website. I recommend you pick and bookmark an official mirror that responds quickly for you. The mirror sites are generally underused and hence faster than the official site.
The OpenBSD FAQ
The OpenBSD FAQ is OpenBSD’s repository of answers to frequently asked questions. While much of the information in the FAQ duplicates the man pages, the FAQ presents this information in a question-and-answer format that’s often easier to understand.
Unlike many other FAQs, the OpenBSD FAQ includes extensive tutorials. For example, Chapter 4 of the FAQ contains the full, detailed installation process. If you’re having a problem, or want to know how some major part of OpenBSD works, check the FAQ first!
Non-Project Websites
Many people maintain websites dedicated to OpenBSD content, related to OpenBSD, or generally useful to OpenBSD users. Any time you have a problem or are trying to understand something, your search engine might lead you to articles on these sites. Read third-party documentation carefully and skeptically, however. Tutorials and articles outside the OpenBSD Project might contain erroneous information, violate OpenBSD’s best practices, or work only in the author’s particular environment.[4]
The only third-party website I can unconditionally recommend is http://www.undeadly.org/, an OpenBSD news aggregator. When a website posts worthwhile OpenBSD-related content, the undeadly.org maintainers link to it.
If you want a web forum to discuss OpenBSD, you might try DaemonForums (http://www.daemonforums.org/). DaemonForums has discussion groups for all of the major BSD variants, including OpenBSD.
OpenBSD Mailing Lists
The OpenBSD Project primarily communicates through mailing lists. All mailing lists are accessible to the public, but some welcome new users more than others. Many hardware platforms have dedicated mailing lists, but they welcome only platform-specific discussions and specifically reject problem reports. The OpenBSD website contains a complete list of mailing lists. Here, I’ll cover only the mailing lists useful to average users.
This low-volume, moderated list includes only important OpenBSD news. This list receives at least one message every six months, when a new version of OpenBSD comes out.
When the OpenBSD team learns of an OpenBSD security flaw, it posts a bulletin to this list. If you are running an OpenBSD machine on the Internet, you must subscribe to this list. I’ll say more about security-announce in Chapter 10.
This list contains general OpenBSD discussions. While this is the “miscellaneous” list, it still has strict rules, and the community firmly enforces its etiquette. I’ll cover how to usefully post to an OpenBSD mailing list in Using Mailing Lists.
This list is for in-depth technical discussions, such as code reviews and protocol analysis. If you want to know what the OpenBSD folks are working on, read this list. It’s not for support requests. As a good rule of thumb, if your email doesn’t include a code diff, don’t send it to this list.
This list is for promoting OpenBSD. If you want to talk about OpenBSD’s inherent awesomeness in a nontechnical manner, use this list.
You’ll find other lists that might interest you, such as www@ (discussions about the website) and ports@ (discussing the OpenBSD ports system, which we’ll cover in Chapter 13), but those lists require more OpenBSD expertise than most beginners have.
The easiest way to access the mailing lists is the web interface at http://lists.OpenBSD.org/. The OpenBSD team manages its mailing lists with Majordomo (http://www.greatcircle.com/majordomo/). If you’re familiar with that package, you can access the mailing lists at [email protected].
Unofficial Mailing Lists
You can find a fairly complete list of all OpenBSD-related mailing lists hosted by third parties at http://www.OpenBSD.org/mail.html. This includes lists in languages other than English.
One unofficial list, run by an OpenBSD developer, is the PF mailing list, for users of the OpenBSD packet filter. This list is for all PF packet filter users, not only OpenBSD, but OpenBSD users dominate the list. If you want to learn more about PF, subscribe to this list. You can find more at http://www.benzedrine.cx/.
Read-Only Mailing Lists
So [email protected] looks like the mailing list for you, and you subscribe. If you race ahead and ask all your questions, you’ll immediately accomplish a couple things: You’ll alienate the community, and you’ll be told to shut up and go away; you certainly won’t make friends. That’s mainly because the mailing lists exist to be read more than posted to.
Unless you’re in a truly unique situation or really on the bleeding edge of OpenBSD development, more likely than not, someone has struggled with your problem previously. That person probably got an answer, and that answer probably hasn’t changed. The quickest and least intrusive way to answer your question is to find that previous message. That’s where the mailing list archives come in.
Your favorite search engine has already indexed the OpenBSD mailing list. Always ask the search engine your question before going anywhere near the mailing lists. If you’ve looked around and found that your question is truly unique, send a message to the mailing list. But when you’re first starting out, you’re better off treating the OpenBSD mailing lists as read-only.