OpenBSD Journal

OpenBSD User documentation project started

Contributed by grey on from the providing more resources dept.

Thanks to Jason Crawford and others for writing in with the following:

It appears as though an OpenBSD Users documentation project has begun. This offers a chance for users to document anything relating to their favorite operating system (and mine) that, say, core developers may not feel is right to put into the official FAQ. This includes setting up PHP+MySQL on OpenBSD's chrooted apache and xdsl firewalling with PPPoE. This thread on misc@ seemed to start it all, and even if the original message didn't seem to have much real thought put into it, it appears something constructive has come out of it.

(Comments are closed)

  1. By Anthony ( on

    This is dangerously close to the Linux HOWTOs that we've all come to know and love.

    1. By Nate ( on

      Very true. However some things that can be tossed up here to help would be very nice for the helpless; like usage of a dhcp server, setting up a vpn using isakmpd, using netcat or such stuff could be nice for the poor people out there that have not done it once or twice before.

      1. By Anthony ( on

        Well, I don't know what the depth of help you're referring to is... but I think that's a dangerous road.

        Take netfilter as an example. It's so complicated that no one can configure it properly except for the developers. Everyone else has a tweaked version of something they got from a HOWTO. Nobody makes really good docs because nobody could understand them if they did.

        This is a good example of the majority of docs on Linux, and it's a dangerous attitude. The philosphy behind HOWTOs is "This is too hard for anyone else, we'll just tell them how to get it to a minimum working state and if they're interested they can tweak it from there.".

        The OpenBSD docs require that people learn a bit more before they get to a working configuration, so they're not for everyone, but the people that can use them are better off.

        I wholeheartedly agree that there aren't enough docs for intermediate levels for people that are willing to learn but don't want to become experts. bind configuration is a good example. There's no intermediate stage between the man page and the bloody BIND 9 Administrator Reference Manual (or at least there wasn't when I had to become an expert). If this new thing can provide that... it'll be a good thing. If it ends up becoming a database of .conf files, it'll be negative.

        1. By Nate ( on

          Well, the things I mentioned in my post were not as complecated as doing anything with iptables or netfilter. Anyways, as I said, touching on the easy to do things that new people don't know where to look for information on would be nice. Many people that try OpenBSD at first have less than a clue how to use a BSD, they're usually used to the hogepoge crap of info files that come in Linux or the really bad Help in Windows.

    2. By Clint ( on

      Actually, as much as I hate "HOWTO's", they are sometimes better than the stuff that seems to be on in that at least most of the Linux HOWTO's bother to tell you what version of the OS they used to create the steps.

      Many of these articles dont' bother to tell you this vital step. OpenBSD 3.6? 3.5? 2.9? -STABLE? -RELEASE? -CURRENT as of some date? no clue.

      So now we'll have a bunch of google archived docs for users to find to set themselves up for problems when they assume that whatever version or configuration they have matches what the author of that article.

      I would start the "teach a man how to fish.." speach but it just seems to obvious.

      1. By Noryungi ( on

        Hmmm... Sorry, but have you even looked at the home page of

        Here is what I was able to find just by looking at this home page:

        1. OpenBSD 3.5 and PPPoE

        2. OpenBSD 3.6 Gateway Mail Filter

        Several other documents do not give an OpenBSD version, that's true, but they seem so generic that not having a version number should not be too much of a problem (for instance: 'Quick Steps to an OpenBSD Desktop' should be mostly the same under 3.4, 3.5, and 3.6).

    3. By The Feature Creep ( on

      HowTos: Geek Ego Gone Wild or Wrong

      OBSD is the "WhatToDo" OS. It's the real world, not what is sexy or cool ("DUDE why didn't you write this app in DILDONICS++?" ). Give me out-of-the-box configuration and "cut and paste examples" from MAN pages.

      "Ben, I have one word for you: PACKAGES."
      Someone smart and experienced has done the work -- including "flavors."

      However, on some of the more 'involved' apps (i.e postfix, apache ) the MANs are a litle turgid. And getting Apache CHROOTED with MySQL, PERL and user directories is no stroll in the park.

      I would hope "User Pages" provides the 90-10 solution like OpenNTPD: KISS. (Love that OpenNTPD config file. SANTA, please bring me OpenSMTPD and OpenHTTPD!!)

      For most of us, the simpler, the better. Then, if there is a real need, one can drill down into separate MANs or post to

      1. By Anonymous Coward ( on

        "And getting Apache CHROOTED with MySQL, PERL and user directories is no stroll in the park. " -- The Feature Creep its not?

    4. By Sean Brown ( on

      Everyone needs somewhere to start, and the howtos often provide a better starting point then the man pages. While the OpenBSD documentation and man pages are excellently done, they often require or assume you already know what your doing. A howto will have a series of steps from biggening to end that you can then begin to understand what the man pages are saying. Howtos are not documentation, they are starting points to get you going.

    5. By kroty ( on

      Damn!! This is nothing but crap!! HOWTOs are for stupid and lazy
      people that can't understand what are they doing and are not even
      interested on learning it.
      That kind of people is good for linux but is not for OpenBSD.
      OpenBSD community is cultured, smart and skilled or at least
      skilled wanna be.
      The official OpenBSD documentation is excelent if you want to learn,
      but if you don't, use linux and read HOWTOs.

      1. By John Ferguson ( on

        kroty says "not even interested on learning it" and "That kind of people is good for linux but is not for OpenBSD. OpenBSD community is cultured, smart and skilled or at least skilled wanna be."

        Fascinating. In three sentences kroty has argued against HOWTOs while at the same time he has provided real life examples of why they can be useful. Without a HOWTO he so argues against, kroty would never have reached the substandard level of english usage he displays... Yet the HOWTO has made it possible for him to advance to a level of communication at which he is able to make his point. Is this a bad thing? Maybe, but I won't argue that kroty should never have been taught to write!

        The fact is that you can't protect yourselves by keeping your field dense and intractable. The recipe for Coca-Cola is probably the only real secret out there these days. But only two guys know it, and they can't travel on the same plane.

        If you really are proud of your work, put it out there and let it be tested in the real world. Like the majors do.


  2. By Simon ( on

    I see many places where things could be enhanced. But to get someone
    as me to contribute, CVS is a requirement (better patching, maybe more commiters).


  3. By Anonymous Coward ( on

    Lets wait and see...

    1. By jvp ( on

      Instead of wait and see, contribute ...

  4. By kami petersen ( on

    one thing i've been wanting for a long time i an archive of select pf configurations. this might be an excellent spot for it.

    i've been thinking that each entry should be moderated and have the following components:

    * brief title
    * plain language policy description
    * indexing keywords (from a predefined set, e.g. DMZ, QoS, Transparent Bridge etc.)
    * what version of openbsd it's sync'ed to
    * actual ruleset
    * moderated feedback

    actually, this kind of format could probably be a good way to organise the whole site =)

    1. By Anonymous Coward ( on

      A firewall needs a very specific configuration in most cases. I don't really see the use of such an archive. It would tempt people into blindly copying pieces of rulesets and omit thinking about a good network setup. The result will be the opposite of a secure situation, no?
      IMO the authors of PF have written very good documentation already, along with examples enabling anyone with a will to properly set up their firewall to do so.

      1. By kami petersen ( on

        well, your knee-jerk statement is totally non-sequitur. first you say that providing reference configuration files equals bad security, and then you say that the two examples in the faq are good enough for anyone.

        anyway, i beg to differ. examples are never bad. the idiots that would just mindlessly copy an example setup would probably do even worse without one. and as i stated, the examples should be carefully selected.

  5. By James ( on

    Gotta get a spell checker on there! Typos be everywhere, yo!

    1. By Johan Berg ( on

      I really like this idea about a documentation project. I am searching for a good howto for setting up Heimdal on OpenBSD and getting it to work with for example telnet, ssh or ftp.

      1. By Nate ( on

        Did you just use the T word? Good Lord man, that is blasphemous! ssh is your only friend.

  6. By DavidH ( on

    ...And that's a superb operating system with inherent security that no other can offer. For myself, I'd like to see many more people running well-configured and secure implementations of OpenBSD rather than the mass of bot-fodder that is infesting the 'net, squandering our bandwidth and polluting our mail.
    So- if we have a set of high-quality, well researched, well QA'd and up-to-date documents, with well-documented configuration examples, perhaps we will all benefit from an increased adoption of OpenBSD.
    Of course, the Catch-22 is effort and dedication required to continue the research, update and QA all that doc as OpenBSD continues to deliver more feature/function. That effort and dedication would have to come close to that of Theo and the team, and that's one heck of a tall order.
    For the moment, I'll continue to use the books by Jacek Artymiak, Michael Lucas and the Brandon Palmer/Jose Nazario team (not forgetting the errata for those books!) as supplements to the outstanding OpenBSD man pages.
    In the mean time, good luck to UDP: you have a lot to live up to, folks.

  7. By Iain ( on

    I am happy to see we are getting more User Documentation but I also see we have issues with what the documents should be and what they should contain. I have put some thought into it and have come to my classification of Documentation into the following categories:

    Man Pages -- Quick reminder pages about using a specific tool, library, or code. Very simple but covers all flags but concentrates on the specific tool. This is very formal in how they are written.

    Howto's -- Focus on complex subjects where more then one set of Tools are needed else more complex usage then a Man Page can cover. Some example topics could be:
    Howto create an OpenBSD Windows Domain Controler
    Creating a DHCP Server for Multiple Domains and Multiple Interfaces
    OpenBSD as a Windows/Unix Fileserver -- Samba + NFS
    Debugging in OpenBSD how to debug your code with the OpenBSD -- Do not expect to find your code in the same place
    Setting up a OpenBSD VPN to communicate to Commercial VPN's
    Making an OpenBSD Proxy Server
    Patching Third Party Source Code for Security then compile native
    Writing for the OBSD Kernel -- New Devices, New Kernel Security, and Porting to a new Architecture.

    In addition it would be nice to setup a Secure and Open Wikie Documentation writing interface. This is where the community can post there experiences which then can help with documentation.

    Lastly with enough Howto's we can get more publishing done there-fore more converts which equals more support.

  8. By Anonymous Coward ( on

    They've taken the 'official' look and feel of the OpenBSD site and copied it. It makes it look like it's a truly sanctioned project. I really do not feel that is fair to the project at all. The project is known for the quality of the documentation. I know there are disclaimers there. But it was tacky to take the feel if it's not the real deal.

    1. By Anonymous Coward ( on

      Yeah, I agree. They can keep the design but change the blue scheme to an orange one perchance.

  9. By Anonymous Coward ( on

    As a newbie to OpenBSD, since java is such an important dev platform, I'd like to see something on creating good java development envs in OpenBSD especially since Sun hasn't exactly ported their stuff. What are our options? What compilers get us to the point of being the most up to date with java standards? Is jikes the best for OpenBSD or gcj or is a linux compat mode with official jdk the best and how to do it? What kind of compatibility problems do we have with those? What IDEs can we develop in? What other tools can we bring in from the Linux world for java development to make our lives better if they don't exist in ports? What are our known limits and what could we do about them? So not just a man page but a real faq on the ins and outs of java on openbsd. Just an idea.

    1. By steven mestdagh ( on

      Well, I'm certainly no experienced java developer, but recently there has been a significant effort porting the JDK to OpenBSD. Read about it in this post:

      This includes a link to a website with instructions on how to build it on your system. You still need linux emulation to build it, but you can use it natively.

      Note: you need to follow the -current branch of src and ports to be able to work with this port, as it is still in a development phase.

  10. By empty ( on

    I would like to see how to get running on OpenBSD 3.6. The instructions in an earlier undeadly post did not work for me at all. Got random memory core faults or something, and at other times missing libgtk-x11 or something like that. Meanwhile if anyone has successfully tried (Linux version) on OpenBSD 3.6, I would like to hear from you.


Copyright © - Daniel Hartmeier. All rights reserved. Articles and comments are copyright their respective authors, submission implies license to publish on this web site. Contents of the archive prior to as well as images and HTML templates were copied from the fabulous original with Jose's and Jim's kind permission. This journal runs as CGI with httpd(8) on OpenBSD, the source code is BSD licensed. undeadly \Un*dead"ly\, a. Not subject to death; immortal. [Obs.]