|
OpenBSD General Other questions regarding OpenBSD which do not fit in any of the categories below. |
|
Thread Tools | Display Modes |
|
|||
Documentation on OpenBSD
What package or method do you use to document your research? Do you use a text editor, a local wiki web server, a database or what?
Last edited by jjstorm; 17th November 2014 at 02:02 PM. |
|
|||
What kind of research do you mean?
__________________
You don't need to be a genius to debug a pf.conf firewall ruleset, you just need the guts to run tcpdump |
|
|||
Say, I wanted to document the instructions locally on how to install OpenBSD or information about the most popular commands? I should have probably said documentation instead of research.
|
|
||||
I don't write my own "howto" docs. As you will find when you do study someone's published third party "howto", they have short lifespans, and can go out-of-date relatively quickly.
I document local configurations as comments within each configuration file, which are more "why" than "how". When I want to know how to do something, I start first with the FAQ, then I review man pages, then I look to the OpenBSD Journal. The "howtos" published there were juried by the editors, and were accurate at the time of publication. Last edited by jggimi; 17th November 2014 at 02:53 PM. Reason: clarity |
|
|||
Please use the FAQ for things like this. If you don't get your questions answered there try a mailing list.
|
|
|||
Are these documents to be used as instructions for someone else? Or are they just notes to yourself for future reference?
For the former, FAQs and man pages are best in the long run. For the latter, FAQs and man pages are best in the long run with maybe a few sparse reminders in a text file. Usually, once I find the information, it's easier to find it again, than to find notes that may now be out of date or too specific. Tim. |
|
|||
got it, thanks, I will check it out. I also appreciate everyone else's valid points too.
|
|
|||
My $0.02
Mediawiki works best for me if the documentation has to be shared across users. For security - 1) Webserver is bound to the local LAN only 2) No one has view permissions without entering a login and password in mediawiki Advantage - Searchable - Multiple users at the same time - Versioning - ability to upload files |
|
|||
Quote:
|
|
|||
Quote:
Yes, the user needs to learn how to use a wiki but the language between all of them is very similar if not identical. It's easier than using raw HTML. Of course, if the notes are just for yourself, you could use anything - text files, OneNote, Evernote, etc. I keep extensive documentation myself, because the faq/man pages are generic. I don't write down what the flags for some command are - that's man page stuff. Anything that would work the same on any server I don't keep my own notes on. But what I tend to keep in my notebook are: (1) Local config stuff. i.e., what the IPs for interfaces should be, Visios showing relationships of servers, RAID configs, etc. Much of it could be determined by system inspection but it's good to have it written down as it should be. Note that some things like which packages are installed on which servers, contents of /etc files, etc. are not things I document because I capture that in backups. (2) Procedures. For example, adding a new host to backups requires several steps on both the new host and the backup server. I've documented some emergency procedures - e.g., if the root disk fails, how to recover. In many cases, things can be scripted, but not always - or rather, they don't happen often enough that the investment in scripting is worthwhile. Or I haven't had time :-) (3) Docs on my own sysadmin scripts. Yes, the scripts have comments, etc. but for example, some of them interact with a database and it's nice to have the schema in one place to look at, etc. (4) Links to faqs/questions/answers. If I have an issue and research and find a solution, I usually document it in case it happens again or I run into it again. I should emphasize that this is all internal - not stuff published on the Internet. |
|
||||
Blackbox is good for a system that documents itself as well. There's a little overhead, but it's not worse than html.
The default menu is a great example of a living config file. http://blackboxwm.sourceforge.net/Bl...ainMenuExample as an example, last night I installed espeak, for text to speech and saved an example to my blackbox menu as such: Code:
[exec] (espeak) {urxvt -e sudo -H espeak -a 200 -g 10 -k15 -p 70 -s 165 -v f4 Hello} Code:
grep espeak /usr/local/share/blackbox/menu Code:
[exec] (espeak) {urxvt -e sudo -H espeak -a 200 -g 10 -k15 -p 70 -s 165 -v f4 Hello} # [exec] (fortune) {/usr/games/fortune | espeak} |
|
|||
Quote:
Am checking out docuwiki and blackbox both, as suggested by @raindog308 and @vanGrimoire |
|
|
Similar Threads | ||||
Thread | Thread Starter | Forum | Replies | Last Post |
Security Popular WordPress Plug-ins Vulnerable to Attack: Checkmarx Research | J65nko | News | 0 | 19th June 2013 08:55 PM |
New Research Suggests That Governments May Fake SSL Certificates | Carpetsmoker | News | 0 | 25th March 2010 09:28 PM |