Contributed by grey on from the providing more resources dept.
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)
By Anthony (68.145.111.152) on
Comments
By Nate (24.112.240.105) on
Comments
By Anthony (68.145.111.152) on
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.
Comments
By Nate (24.112.240.105) on
By Clint (24.131.187.140) on
Many of these openbsdsupport.org 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.
Comments
By Noryungi (82.230.182.114) on
Hmmm... Sorry, but have you even looked at the home page of OpenBSDsupport.org?
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).
By The Feature Creep (68.142.8.147) on
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 Misc@obsd.org
Comments
By Anonymous Coward (142.109.90.79) on
By Sean Brown (204.209.209.129) on
By kroty (200.114.169.113) kroty@gawab.com 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.
Comments
By John Ferguson (24.175.86.167) 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.
John
By Simon (80.171.58.211) on
as me to contribute, CVS is a requirement (better patching, maybe more commiters).
Regards,
Simon
By Anonymous Coward (81.193.92.109) on
Comments
By jvp (200.254.144.62) on
By kami petersen (217.215.10.111) on
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 =)
Comments
By Anonymous Coward (134.58.253.114) on
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.
Comments
By kami petersen (217.215.10.111) on
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.
By James (129.10.211.148) on
Comments
By Johan Berg (193.11.233.19) on http://k.jb.nu
Comments
By Nate (24.112.240.105) on
By DavidH (198.207.223.237) on
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.
By Iain (142.179.199.27) on
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.
By Anonymous Coward (68.188.68.77) on
Comments
By Anonymous Coward (216.252.76.248) on
By Anonymous Coward (68.188.68.77) on
Comments
By steven mestdagh (213.224.83.138) 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:
http://marc.theaimsgroup.com/?l=openbsd-ports&m=109734097722707&w=2
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.
By empty (69.132.141.94) on