OpenBSD FAQ - Getting to Know OpenBSD [FAQ Index]



Mailing lists

The OpenBSD project maintains several popular mailing lists which users should subscribe to and follow. To subscribe to a mailing list, send an email to [email protected]. That address is an automated subscription service. In the body of your message, on a single line, you should include a subscribe command for the list you wish to join. For example:
subscribe announce

The list processor will reply to you, asking for confirmation of your intent to join the list, so that others can not subscribe you to a flood of unwanted email. The message will include instructions for several different ways to confirm, including a list server web page link, responding to the confirmation message or responding to [email protected]. Use whatever method is convenient to you. You will note that all three techniques involve a unique and time limited identifying number, such as A56D-70D4-52C3, again to make sure you are really the person who requested this mailing list subscription (this is real "opt-in").

Once you have confirmed your intent to join, you will be immediately added to the list, and the list processor will notify you that you were successfully added.

To unsubscribe from a list, you will again send an email to [email protected]. It might look like this:

unsubscribe announce

If you have any difficulties with the mailing list system, please first read the help file which can be obtained by sending an email to [email protected] with a message body of "help".

Your subscription to the OpenBSD lists can also be maintained through the web interface at lists.openbsd.org.

Some of the more popular OpenBSD mailing lists are:

Before posting a question on misc or any other 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 dmesg(8)!

You can find several archives, other mailing list guidelines and more information on the mailing lists page.

An unofficial mailing list that may be of interest to new users of OpenBSD and Unix is the OpenBSD Newbies list.

Manual pages

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

To access the manual pages, be sure that you installed the correct file set.

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 install 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. For example:

$ 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 display a man page source file (i.e. one whose filename ends in a number, like tcpdump.8)?

These are found throughout the src tree and are installed to man page directories like /usr/share/man/man1 in their unformatted state. To view these pages, simply:
$ mandoc -a <file>

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

This is helpful to get the man page straight, with no non-printable characters.
$ man <command> | col -b

How can I get a PostScript copy of a man page that's print-ready?

The PostScript versions of the man pages look very nice. They can be printed or viewed on-screen with a program like gv (GhostView). GhostView can be found in our packages collection. Use the following mandoc(1) command options for getting a PostScript version from an OpenBSD system man page:
$ mandoc -Tps <file> > outfile.ps
Note that <file> must be the man page source file (probably a file that ends in a number, e.g. tcpdump.8).

What are info files?

Some of the documentation for OpenBSD comes in the form of info files, typically contained in /usr/share/info. This is an alternative form of documentation provided by GNU. Many of these files are more up to date than the manual pages provided by GNU, and can be accessed with the info(1) command. 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 "!" before this can work:
!*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, so customize as necessary: may we suggest red for "colorUL" and magenta for "colorBD"? There is also a man page viewer for X11 available, xman(1), which provides an alternative (graphical) interface to the manual pages. See the manual pages for xterm and xman for more information.

How do I write my own manual page?

If you wish to write your own man page for an application you have written, there is a handy reference guide provided in 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: [email protected]
To: [email protected]
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 can not 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 electronic mail successfully on the Internet. Note that the mail server uses spamd(8) based 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 [email protected] 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.