[FAQ Index] [To Section 1 - Introduction to OpenBSD] [To Section 3 - Obtaining OpenBSD]
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.
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 email@example.com. 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:
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 firstname.lastname@example.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 email@example.com. It might look like this:
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 firstname.lastname@example.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:
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.
OpenBSD comes with extensive documentation in the form of manual pages, as well as longer documents relating to specific applications. 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 and other documentation, be sure that you installed the man42.tgz and misc42.tgz file sets.
Here is a list of some of the most useful manual pages for new users:
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 man42.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
In addition to the UNIX manual pages, there is a typesettable document set (included in the misc42.tgz file set). It lives in the /usr/share/doc directory. You can format each document set with a "make" in the appropriate subdirectory. The psd subdirectory is the Programmer's Supplementary Documents distribution. The smm subdirectory is the System Manager's Manual. The usd subdirectory is the UNIX User's Supplementary Documents distribution. You can perform your "make" in the three distribution subdirectories, or you can select a specific section of a distribution and do a `make' in its subdirectory.
Some of the subdirectories are empty. By default, formatting the documents will result in PostScript output, suitable for printing. The PostScript output can be quite large -- you should assume a 250-300% increase in volume. If you do not have access to a PostScript printer or display, you may also format the documents for reading on a terminal display. Each document subdirectory has a target for building ASCII copies of these papers (called `paper.txt') which can be generated with make(1). For example:
# cd /usr/share/doc/usd/04.csh # make paper.txt # more paper.txt
Note that superuser privileges may be required to build documents in these directories, and that issuing make clean will remove any papers generated by a previous make. See /usr/share/doc/README for more details about the documents in /usr/share/doc/.
The UNIX manual pages are generally more current and trustworthy than the typesettable documents. The typesettable documents sometimes explain complicated applications in more detail than the manual pages do.
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.
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:
# nroff -Tascii -mandoc <file> | more
This is helpful to get the man page straight, with no non-printable
# man <command> | col -b
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 nroff(1) command options for getting a PostScript version from an OpenBSD system man page:
# nroff -Tps -mandoc <file> > outfile.ps
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:
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.
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:
After using info, you will really appreciate our man pages!
# info gcc
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:
The rest of this file allows you to choose colors for various settings. The relevant ones to the man pages are:
!*VT100*colorULMode: on !*VT100*underLine: off !*VT100*colorBDMode: on
That produces rather hellish looking man pages, so customise 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.
*VT100*colorUL: yellow *VT100*colorBD: white
If you wish to write your own man page for an application you have written, a tutorial is provided in mdoc.samples(7). There is also a handy reference guide provided in mdoc(7).
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:
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:
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 will be notified by e-mail about the status of the report. You may be contacted by developers for additional information or with patches that need testing. You can also monitor the archives of the email@example.com mailing list, details on the mailing list page, or query the bug report database status at the on-line Bug Tracking System.
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:
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:
Repeat the "machine ddb x" followed by "trace" for each processor in your machine.
[FAQ Index] [To Section 1 - Introduction to OpenBSD] [To Section 3 - Obtaining OpenBSD]