[FAQ Index] [To Section 1 - Introduction to OpenBSD] [To Section 3 - Getting started with OpenBSD]

2 - Getting to know OpenBSD

2.1 - Web Pages
2.2 - Mailing Lists
2.3 - Manual Pages
2.4 - Reporting Bugs

2.1 - Web Pages of Interest

The official website for the OpenBSD project is located at: http://www.OpenBSD.org.

A lot of valuable information can be found here regarding all aspects of the OpenBSD project.

The OpenBSD Journal is an OpenBSD-focused news and opinion site.

OpenBSDsupport.org is a site collecting "user maintained" documentation of varying quality, but often covering topics not in this FAQ or other official documentation.

Many users have set up sites and pages with OpenBSD specific information. As with everything on the Internet, a good search engine is going to make your life easier, as will a healthy dose of skepticism. As always, do not blindly enter commands you do not understand into your computer.

2.2 - 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 e-mail message to majordomo@openbsd.org. 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 e-mail. 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 majordomo@openbsd.org. 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 mail 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 e-mail message to majordomo@openbsd.org. 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 e-mail message to majordomo@openbsd.org with a message body of "help".

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

Some of the more popular OpenBSD mailing lists are:

announce - Important announcements. This is a low-volume list.
security-announce - Announcements of security issues. This is a low volume list.
misc - General user questions and answers. This is the most active list, and should be the "default" for most questions.
bugs - Bugs received via sendbug(1) and discussions about them.
source-changes - Automated mailing of CVS source tree changes. Every time a developer commits a change to the OpenBSD source tree, CVS will send out a copy of the (usually brief) commit message via this list.
ports - Discussion of the OpenBSD Ports Tree.
ports-changes - Automated mailing of ports-specific CVS source tree changes.
advocacy - Discussion on advocating OpenBSD, and topics that are just too off-topic for misc.

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.

2.3 - 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 man54.tgz file set.

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

Getting Started

afterboot(8) - things to check after the first complete boot.
help(1) - help for new users and administrators.
hier(7) - layout of filesystems.
man(1) - display the on-line manual pages.
intro(1) - introduction to general commands, also see the intros to the other sections of the manual: intro(2), intro(3), intro(4) (note: intro(4) is platform specific), intro(5), intro(6), intro(7), intro(8), and intro(9).
adduser(8) - command for adding new users.
vipw(8) - edit the master password file.
disklabel(8) - read and write disk pack label.
reboot, halt(8) - stop and restart the system.
shutdown(8) - close down the system at a given time.
dmesg(8) - redisplay the kernel boot messages.
sudo(8) - don't log in as root, but run commands as root.
mg(1) - emacs-like text editor.

For more advanced users

boot(8) - system bootstrapping procedures.
boot_config(8) - how to change kernel configuration at boot.
gcc-local(1) - OpenBSD-specific modifications to gcc(1).
ifconfig(8) - configure network interface parameters.
login.conf(5) - format of the login class configuration file.
netstat(1) - show network status.
release(8) - build an OpenBSD release.
sendbug(1) - send a problem report (PR) about OpenBSD to a central support site.
style(9) - OpenBSD kernel source code style guide.
sysctl(8) - get or set kernel state.

You can find all the OpenBSD man pages on the web at http://www.openbsd.org/cgi-bin/man.cgi as well as on your computer if you install the man54.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

For many, 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. The man pages are found in the tree unformatted, and many times, through the use of CVS, they will be updated. To view these pages, simply:

# mandoc <file> | more

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.
Example:

# man <command> | col -b

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

Note that <file> must be the man page source file (probably a file that ends in a number e.g. tcpdump.8). 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

How do I generate compressed copies of the man pages?

For people who build their system from source, there are a number of options relating to the way in which man pages are built. These options can be placed in /etc/mk.conf (it may be necessary to create this file) and are included during system builds. One especially useful option is to generate compressed man pages in order to save disk space. These can be viewed in the normal way, using the man command. In order to set this, add the following to /etc/mk.conf:

MANZ=yes

Another useful option is to have the system build generate man pages in PostScript format, as well as ASCII text. This is done by setting the option MANPS=yes in /etc/mk.conf. See mk.conf(5) for further details.

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 /etc/X11/app-defaults/XTerm-color to your home directory, and rename it ".Xdefaults". Be careful not to overwrite any current settings in ".Xdefaults". This file contains all the settings you need to enable color in XTerm. However, three lines need to be uncommented before this can work:

!*VT100*colorULMode: on
!*VT100*underLine: off
!*VT100*colorBDMode: on

The rest of this 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).

2.4 - Reporting Bugs

Before crying "Bug!", please make sure that is really what you are dealing with. If instead, you are not understanding how something is done in OpenBSD or how it works, and can't find out how to resolve the problem using the manual pages or the OpenBSD website, use the mail lists (usually misc@openbsd.org) to request help. If this is your first OpenBSD experience, be realistic: you probably did not discover an unknown bug. Also note that faulty hardware can mimic a software bug, please verify the current condition of your hardware before deciding you have found a "bug".

Finally, before submitting any bug report, please read http://www.openbsd.org/report.html.

Proper bug reporting is one of the most important responsibilities of end users. Very detailed information is required to diagnose most serious bugs. Developers frequently get bugs reports via e-mail such as this:

From: joeuser@example.com To: bugs@openbsd.org Subject: HELP!!! I have a PC and it won't boot!!!!! It's a 486!!!!!

Hopefully most people understand why such reports get summarily deleted. All bug reports should contain detailed information. If Joe User had really expected someone to help find this bug, he or she would have supplied more information... something like this:

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 an FTP mirror, I find the system randomly panics after a period of use, and predictably and quickly when starting X. This is the dmesg output: OpenBSD 3.3-beta (GENERIC) #9: Mon Mar 17 12:37:18 MST 2003 deraadt@sparc.openbsd.org:/usr/src/sys/arch/sparc/compile/GENERIC real mem = 67002368 avail mem = 59125760 using 200 buffers containing 3346432 bytes of memory bootpath: /sbus@1,f8000000/esp@0,800000/sd@1,0 mainbus0 (root): SUNW,Sun 4/75 cpu0 at mainbus0: CY7C601 @ 40 MHz, TMS390C602A FPU; cache chip bug - trap page uncached cpu0: 64K byte write-through, 32 bytes/line, hw flush cache enabled memreg0 at mainbus0 ioaddr 0xf4000000 clock0 at mainbus0 ioaddr 0xf2000000: mk48t02 (eeprom) timer0 at mainbus0 ioaddr 0xf3000000 delay constant 17 auxreg0 at mainbus0 ioaddr 0xf7400003 zs0 at mainbus0 ioaddr 0xf1000000 pri 12, softpri 6 zstty0 at zs0 channel 0 (console i/o) zstty1 at zs0 channel 1 zs1 at mainbus0 ioaddr 0xf0000000 pri 12, softpri 6 zskbd0 at zs1 channel 0: reset timeout zskbd0: no keyboard zstty2 at zs1 channel 1: mouse audioamd0 at mainbus0 ioaddr 0xf7201000 pri 13, softpri 4 audio0 at audioamd0 sbus0 at mainbus0 ioaddr 0xf8000000: clock = 20 MHz dma0 at sbus0 slot 0 offset 0x400000: rev 1+ esp0 at sbus0 slot 0 offset 0x800000 pri 3: ESP100A, 25MHz, SCSI ID 7 scsibus0 at esp0: 8 targets sd0 at scsibus0 targ 1 lun 0: <SEAGATE, ST1480 SUN0424, 8628> SCSI2 0/direct fixed sd0: 411MB, 1476 cyl, 9 head, 63 sec, 512 bytes/sec, 843284 sec total sd1 at scsibus0 targ 3 lun 0: <COMPAQPC, DCAS-32160, S65A> SCSI2 0/direct fixed sd1: 2006MB, 8188 cyl, 3 head, 167 sec, 512 bytes/sec, 4110000 sec total le0 at sbus0 slot 0 offset 0xc00000 pri 5: address 08:00:20:13:10:b9 le0: 16 receive buffers, 4 transmit buffers cgsix0 at sbus0 slot 1 offset 0x0: SUNW,501-2325, 1152x900, rev 11 wsdisplay0 at cgsix0 wsdisplay0: screen 0 added (std, sun emulation) fdc0 at mainbus0 ioaddr 0xf7200000 pri 11, softpri 4: chip 82072 fd0 at fdc0 drive 0: 1.44MB 80 cyl, 2 head, 18 sec root on sd0a rootdev=0x700 rrootdev=0x1100 rawdev=0x1102 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 RUN AT LEAST 'trace' AND 'ps' AND INCLUDE OUTPUT WHEN REPORTING THIS PANIC! DO NOT EVEN BOTHER REPORTING THIS WITHOUT INCLUDING THAT INFORMATION! ddb> trace pool_get(0xfaa93000, 0x22, 0x0, 0x1000, 0x102, 0x0) at pool_get+0x2c0 sosend(0x16, 0xf828d800, 0x0, 0xf83b0900, 0x0, 0x0) at sosend+0x608 soo_write(0xfac0bf50, 0xfac0bf70, 0xfac9be28, 0xfab93190, 0xf8078f24, 0x0) at soo_write+0x18 dofilewritev(0x0, 0xc, 0xfac0bf50, 0xf7fff198, 0x1, 0xfac0bf70) at dofilewritev+0x12c sys_writev(0xfac87508, 0xfac9bf28, 0xfac9bf20, 0xf80765c8, 0x1000, 0xfac0bf70) at sys_writev+0x50 syscall(0x79, 0xfac9bfb0, 0x0, 0x154, 0xfcffffff, 0xf829dea0) at syscall+0x220 slowtrap(0xc, 0xf7fff198, 0x1, 0x154, 0x1, 0xfac87508) at slowtrap+0x1d8 ddb> ps PID PPID PGRP UID S FLAGS WAIT COMMAND 27765 8819 29550 0 3 0x86 netio xconsole 1668 29550 29550 0 3 0x4086 poll fvwm 15447 29550 29550 0 3 0x44186 poll xterm 8819 29550 29550 35 3 0x4186 poll xconsole 1238 29550 29550 0 3 0x4086 poll xclock 29550 25616 29550 0 3 0x4086 pause sh 1024 25523 25523 0 3 0x40184 netio XFree86 *25523 25616 25523 35 2 0x44104 XFree86 25616 30876 30876 0 3 0x4086 wait xinit 30876 16977 30876 0 3 0x4086 pause sh 16977 1 16977 0 3 0x4086 ttyin csh 5360 1 5360 0 3 0x84 select cron 14701 1 14701 0 3 0x40184 select sendmail 12617 1 12617 0 3 0x84 select sshd 27515 1 27515 0 3 0x184 select inetd 1904 1 1904 0 2 0x84 syslogd 9125 1 9125 0 3 0x84 poll dhclient 7 0 0 0 3 0x100204 crypto_wa crypto 6 0 0 0 3 0x100204 aiodoned aiodoned 5 0 0 0 3 0x100204 syncer update 4 0 0 0 3 0x100204 cleaner cleaner 3 0 0 0 3 0x100204 reaper reaper 2 0 0 0 3 0x100204 pgdaemon pagedaemon 1 0 1 0 3 0x4084 wait init 0 -1 0 0 3 0x80204 scheduler swapper 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, you will have to use paper and pencil to record the crash. (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 from which he wanted to submit a bug report, he would have used the sendbug(1) utility to submit his bug report to the GNATS problem tracking system. 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, so 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"

Special 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.