OpenBSD FAQ - Introduction to OpenBSD [FAQ Index]



Tell me about OpenBSD

The OpenBSD project produces a freely available, multi-platform 4.4BSD-based UNIX-like operating system. Our goals place emphasis on correctness, security, standardization, and portability.

Why might I want to use it?

Some reasons why we think OpenBSD is a useful operating system:

When is the next release?

The OpenBSD team makes a new release every six months, with target release dates in May and November. More information on the development cycle can be found here.

Hardware support

OpenBSD runs on the following platforms:

alpha Available on CD
amd64 Available on CD
armish Download only
hppa Available on CD
i386 Available on CD
landisk Download only
loongson Download only
luna88k Download only
macppc Available on CD
octeon Download only
sgi Download only
socppc Download only
sparc Available on CD
sparc64 Available on CD
zaurus Download only

Available on CD means the official CD set includes that platform and a small selection of useful packages. CD ISO images can be downloaded for most other platforms. These are not the same as the official CD sets, however. Some platforms also have USB disk images available.

People sometimes ask why we support so many odd machines. The short answer is "because we want to." If enough skilled people (and sometimes "enough" is only one really skilled person!) wish to maintain support for a platform, it will be supported. The OpenBSD platforms include 32 bit and 64 bit processors, little and big endian machines and many different designs. Supporting unusual platforms has helped produce a higher-quality code base.

Selecting hardware

Selecting appropriate hardware to run your OpenBSD system on is important, as it can mean the difference between success and failure of a project.

Is OpenBSD really free?

OpenBSD is all free. The binaries are free. The source is free. All parts of OpenBSD have reasonable copyright terms permitting free redistribution. This includes the ability to reuse most parts of the OpenBSD source tree, either for personal or commercial purposes. OpenBSD includes no further restrictions other than those implied by the original BSD license. Software which is written under stricter licenses cannot be included in the regular distribution of OpenBSD. This is intended to safeguard the free use of OpenBSD. For example, OpenBSD can be freely used for personal use, for academic use, by government institutions, by non-profit making organizations and by commercial organizations. OpenBSD, or parts of it, can also be freely incorporated into commercial products.

This isn't to say we would object to financial or hardware support in thanks. In fact, it is stunning how little support of any kind comes from companies that depend upon OpenBSD or OpenSSH for their products.

For further reading on other popular licenses, read the OpenBSD copyright policy.

The maintainers of OpenBSD support the project largely from their own pockets. This includes the time spent programming for the project, equipment used to support the many ports, the network resources used to distribute OpenBSD to you, and the time spent answering questions and investigating users' bug reports. The OpenBSD developers are not independently wealthy, and even small contributions of time, equipment and resources make a big difference.

What's included with OpenBSD?

OpenBSD is distributed with a number of third-party software products, including: The OpenBSD team often patches third party products, typically to improve the security or quality of the code. Much home-grown software is also included. Additional applications are available as packages.

Why is/isn't ProductX included?

People often ask why a particular product is or isn't included with OpenBSD. The answer is based on two things: the wishes of the developers and compatibility with the goals of the project. Licensing is often the biggest problem: we want OpenBSD to remain usable by any person anywhere in the world for any purpose.

Supporting the project

We are greatly indebted to the people and organizations that have contributed to the OpenBSD project.

OpenBSD has a constant need for several types of support from the user community. If you find OpenBSD useful, you are strongly encouraged to find a way to contribute. If none of the suggestions below are right for you, feel free to propose an alternative by sending email to donations@openbsd.org.

Mailing lists

The OpenBSD project maintains several mailing lists that users should subscribe to and follow. Some of the more popular lists are: Before posting a question on any mailing list, please check the archives for most common questions have been asked repeatedly. While it might be the first time you have encountered the problem or question, others on the mailing lists may have seen the same question several times in the last week, and may not appreciate seeing it again. If asking a question possibly related to hardware, always include a full dmesg(8).

You can find several archives, other guidelines and more information on the mailing list page. Subscriptions can be easily managed via the web interface.

Manual pages

OpenBSD comes with extensive documentation in the form of man pages. Considerable effort is made to make sure the man pages are up-to-date and accurate. The man pages are the authoritative source of information for OpenBSD.

Here is a list of some useful manual pages for new users:

You can find all the OpenBSD man pages on the web at http://man.openbsd.org as well as on your computer if you installed the manXX.tgz file set.

In general, if you know the name of a command or a manual page, you can read it by executing man command. For example: man vi to read about the vi editor. If you don't know the name of the command, or if man command doesn't find the manual page, you can search the manual page database by executing apropos something or man -k something, where "something" is a likely word that might appear in the title of the manual page you're looking for.

$ apropos "time zone"
tzfile (5) - time zone information
zdump (8) - time zone dumper
zic (8) - time zone compiler
The parenthetical numbers indicate the section of the manual in which that page can be found. In some cases, you may find manual pages with identical names living in separate sections of the manual. For example, assume that you want to know the format of the configuration files for the cron daemon. Once you know the section of the manual for the page you want, you would execute man n command, where n is the manual section number.
$ man -k cron
cron (8) - clock daemon
crontab (1) - maintain crontab files for individual users
crontab (5) - tables for driving cron
$ man 5 crontab
Occasionally, having a hardcopy of the man page can be useful. Here are the guidelines to making a printable copy of a man page.

How do I get a man page with no control characters?

If you pipe the output of the man command to your editor, you will see that it contains a lot of control characters. To remove them, issue
$ man <command> | col -b

How can I get a print-ready copy of a man page?

If you wish to print out a man page, the printer-friendly formats .ps or .pdf are available.
$ man -Tps <command> > outfile.ps
Replace ps with pdf if you prefer the latter.

What are info files?

Some of the documentation for OpenBSD comes in the form of info(1) files. This is an alternative form of documentation provided by GNU. For example, to view information about the GNU compiler, gcc(1), type:
$ info gcc
After using info, you will really appreciate our man pages!

How do I get color man pages on XTerm?

The default configuration file for xterm(1) does not display color man pages. In order to get color output, copy the file /usr/X11R6/share/X11/app-defaults/XTerm-color to your home directory, and rename it .Xdefaults-XTerm-color. The color XTerm defaults file can now be activated by adding the following line to .Xdefaults in your home directory:
#include ".Xdefaults-XTerm-color"
This file contains all the settings you need to enable color in XTerm. However, three lines need to be uncommented by removing the leading "!":
!*VT100*colorULMode: on
!*VT100*underLine: off
!*VT100*colorBDMode: on
The rest of the included file allows you to choose colors for various settings. The relevant ones to the man pages are:
*VT100*colorUL: yellow
*VT100*colorBD: white
That produces rather hellish looking man pages. We suggest red for colorUL and magenta for colorBD.

X11 also provides the xman(1) graphical interface to the manual pages.

How do I write my own manual page?

Consult mdoc(7).

Reporting bugs

Reporting bugs is one of the most important responsibilities of end users. However, if this is your first OpenBSD experience, be realistic: you probably did not discover an unknown problem. Sometimes faulty hardware can mimic a software bug, so verify the current condition of your hardware before deciding you have found a bug.

Very detailed information is required to diagnose most serious issues. For example, the following would be an appropriate bug report:

From: smartuser@example.com
To: bugs@openbsd.org
Subject: 3.3-beta panics on a SPARCStation2

OpenBSD 3.2 installed from an official CD-ROM installed and ran fine
on this machine.

After doing a clean install of 3.3-beta from a mirror, I find the
system randomly panics after a period of use, and predictably and
quickly when starting X.

This is the dmesg output:

[...]

This is the panic I got when attempting to start X:

panic: pool_get(mclpl): free list modified: magic=78746572; page 0xfaa93000;
 item addr 0xfaa93000
Stopped at      Debugger+0x4:   jmpl            [%o7 + 0x8], %g0
http://www.openbsd.org/ddb.html describes the minimum info required in bug
reports. Insufficient info makes it difficult to find and fix bugs.
ddb> trace
[...]

Thank you!
See report.html for more information on creating and submitting bug reports. Detailed information about your hardware is necessary if you think the bug could be in any way related to your hardware or hardware configuration. Usually, dmesg(8) output is sufficient in this respect. A detailed description of your problem is necessary. You will note that the dmesg described the hardware, the text explained why Smart User thought the system was not broken (ran 3.2 properly), how this crash was caused (starting X), and the output of the debugger's ps and trace commands. In this case, Smart User provided output captured on a serial console. If you cannot do that, take a picture of the screen and attach it to your bug report. (This was a real problem, and the information in the above report helped lead to a repair of this issue which impacted Sun4c systems.)

If Smart User had a working OpenBSD system, they would have used the sendbug(1) utility to submit his bug report. Obviously, you can't use sendbug(1) when your system won't boot, but you should use it whenever possible. You will still need to include detailed information about what happened, the exact configuration of your system, and how to reproduce the problem. The sendbug(1) command requires that your system be able to send email. The OpenBSD mail server uses spamd(8) for greylisting, so it may take half an hour or so before the mail server accepts your bug report. Please be patient.

After submitting a bug report via sendbug(1), you may be contacted by developers for additional information or with patches that need testing. You can also monitor the archives of the bugs@openbsd.org mailing list - details on the mailing list page.

How do I get more useful info for developers?

Here are a few additional tips:

Lost the "panic" message?

Under some circumstances, you may lose the very first message of a panic, stating the reason for the panic. This is a very important message, so you want to report it as well. You can get this back by using the "show panic" command in ddb> like this:

ddb> show panic
0:      kernel: page fault trap, code=0
ddb>
In this case, the panic string was "Kernel: page fault trap, code=0".

Note for SMP systems

You should get a trace from each processor as part of your report:

ddb{0}> trace
pool_get(d05e7c20,0,dab19ef8,d0169414,80) at pool_get+0x226
fxp_add_rfabuf(d0a62000,d3c12b00,dab19f10,dab19f10) at fxp_add_rfabuf+0xa5
fxp_intr(d0a62000) at fxp_intr+0x1e7
Xintr_ioapic0() at Xintr_ioapic0+0x6d
--- interrupt ---
idle_loop+0x21:
ddb{0}> machine ddbcpu 1
Stopped at      Debugger+0x4:   leave
ddb{1}> trace
Debugger(d0319e28,d05ff5a0,dab1bee8,d031cc6e,d0a61800) at Debugger+0x4
i386_ipi_db(d0a61800,d05ff5a0,dab1bef8,d01eb997) at i386_ipi_db+0xb
i386_ipi_handler(b0,d05f0058,dab10010,d01d0010,dab10010) at i386_ipi_handler+0x
4a
Xintripi() at Xintripi+0x47
--- interrupt ---
i386_softintlock(0,58,dab10010,dab10010,d01e0010) at i386_softintlock+0x37
Xintrltimer() at Xintrltimer+0x47
--- interrupt ---
idle_loop+0x21:
ddb{1}>
Repeat the machine ddbcpu x followed by trace for each processor in your machine.

How do I gather further information from a kernel crash?

A typical kernel crash on OpenBSD might look like this: (things to watch for are marked with bold font)

kernel: page fault trap, code=0
Stopped at    _pf_route+0x263:        mov     0x40(%edi),%edx
ddb>
The first command to run from the ddb> prompt is "trace" (see ddb(4) for details):
ddb> trace
_pf_route(e28cb7e4,e28bc978,2,1fad,d0b8b120) at _pf_route+0x263
_pf_test(2,1f4ad,e28cb7e4,b4c1) at _pf_test+0x706
_pf_route(e28cbb00,e28bc978,2,d0a65440,d0b8b120) at _pf_route+0x207
_pf_test(2,d0a65440,e28cbb00,d023c282) at _pf_test+0x706
_ip_output(d0b6a200,0,0,0,0) at _ip_output+0xb67
_icmp_send(d0b6a200,0,1,a012) at _icmp_send+0x57
_icmp_reflect(d0b6a200,0,1,0,3) at _icmp_reflect+0x26b
_icmp_input(d0b6a200,14,0,0,d0b6a200) at _icmp_input+0x42c
_ipv4_input(d0b6a200,e289f140,d0a489e0,e289f140) at _ipv4_input+0x6eb
_ipintr(10,10,e289f140,e289f140,e28cbd38) at _ipintr+0x8d
Bad frame pointer: 0xe28cbcac
ddb>
This tells us what function calls lead to the crash.

To find out the particular line of C code that caused the crash, you can do the following:

Find the source file where the crashing function is defined in. In this example, that would be pf_route() in sys/net/pf.c. Recompile that source file with debug information:

# cd /usr/src/sys/arch/$(uname -m)/compile/GENERIC
# rm pf.o
# DEBUG=-g make pf.o
Then use objdump(1) to get the disassembly:
# objdump --line --disassemble --reloc pf.o >pf.dis
In the output, grep for the function name (pf_route in our example):
# grep "<_pf_route>:" pf.dis
00007d88 <_pf_route>:
Take this first hex number and add the offset from the 'Stopped at' line: 0x7d88 + 0x263 == 0x7feb.

Scroll down to that line (the assembler instruction should match the one quoted in the 'Stopped at' line), then up to the nearest C line number:

# more pf.dis
/usr/src/sys/arch/i386/compile/GENERIC/../../../../net/pf.c:3872
    7fe7:       0f b7 43 02             movzwl 0x2(%ebx),%eax
    7feb:       8b 57 40                mov    0x40(%edi),%edx
    7fee:       39 d0                   cmp    %edx,%eax
    7ff0:       0f 87 92 00 00 00       ja     8088 <_pf_route+0x300>
So, it's precisely line 3872 of pf.c that crashes:
# cat -n pf.c | head -n 3872 | tail -n 1
3872          if ((u_int16_t)ip->ip_len <= ifp->if_mtu) {
Note that the kernel that produced the crash output and the object file for objdump must be compiled from the exact same source file, otherwise the offsets won't match.

If you provide both the ddb trace output and the relevant objdump section, that's very helpful.

Migrating to OpenBSD

If you learned Unix from any of the good books on general Unix, understanding the Unix philosophy and then extending your knowledge to a particular platform, you will find OpenBSD to be familiar.

One important difference between OpenBSD and many other operating systems is the documentation. OpenBSD developers take great pride in the system man pages. The man pages are the authoritative OpenBSD documentation. Developers making a change to the system are expected to update the man pages along with their change to the system code. It is expected that a user will check the man pages before asking for help on the mailing lists.

Here are some of the commonly encountered differences between OpenBSD and other Unix variants.