[FAQ Index] [To Section 1 - Introduction to OpenBSD] [To Section 3 - Obtaining OpenBSD]

2 - Other OpenBSD Information Resources

Table of Contents

• 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, 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:

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.

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

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:

# nroff -Tascii -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 nroff(1) command options for getting a PostScript version from an OpenBSD system man page:

# nroff -Tps -mandoc <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

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

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

*VT100*colorUL: yellow *VT100*colorBD: white

How do I write my own manual page?

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

2.4 - Reporting Bugs

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 bugs@openbsd.org mailing list, details on the mailing list page, or query the bug report database status at the on-line Bug Tracking System.

More on getting useful info for developers

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]