document a FreeBSD system

D

da1

Hi guys,

I'm on the verge of creating some kind of word/OO writer document which will contain all the hardware, software and changes that happened to a system from day 1 but soon after the quick idea, I realized that this could be nice to have for some other machines (3 more) and it quick became a challenging task.

How do you guys go about documenting a unix machine ?
Is there some tools you use ?
What do you prefer and why ? paper, electronic, word-style document, db, something else ?
 
To be honest with you I keep a excel spread sheet of each individual system with all the relevant data, there are management systems out there but they tend to be a little bit lacking or a little over complex for whats needed.
 
@da1

Documentation after creating the system for some task is very important, information how the system is configured, what services (and how) it runs, how to stop/start/debug them, that 'data' can go to SYSTEM_NAME.odf file, but I would also recommend using /etc/changelog for every machine (also put that information into SYSTEM_NAME_errata.odf file with some more in depth info) for all the changes that have been applied after the 'official 1.0'.

Using /etc/motd for the things that You need to remember for that system also helps (only if there are admin(s)/root on the system), if there are users, use other file then /etc/motd file for obvious reasons.
 
I agree vermaden but for some reason I would prefer a hard copy of a potential document (odf, doc, etc) or at least, a digital version of the document.

The only thing I'm wondering right now is if there is a tool that would help me in this quest because it would take me quite some time to design the template and then populate it with data.

For the moment, considering I'm the only admin on these 4 servers in question, I use /etc/motd for all changes that I make.
 
This post exists only to get space for underline note.
-------------------------------------------------------
[size=-2](LaTeX for WYSIWYG people is known under cryptic name print/lyx)[/size]
 
1. Plain text files to document any "exotic" configurations or complicated/boring procedures to get some things to work.
2. Copies of configuration files.

I keep these in a directory dedicated to anything FreeBSD that I often backup along with virtually everything in my /home/<user> directory.
 
@Beastie: I will have a hardcopy because we need it but besides that, I'm curious if I can use some application.

Came across these:
1) i-doit (made in DE)
2) Comodo's iTop

For the moment, testing ...
 
I have recently studied cfengine (sysutils/cfengine3). Currently I use cfengine configuration: promises and classes to document hosts. For example class service_ssh_openssh indicates that a host has SSH configured. However cfengine's main purpose is to easily reconfigure and rebuild hosts.

My cfengine configuration doesn't document network settings, filesystems or hardware and they need to be documented some other way. I also use changelogs to document manual changes (for example hardware changes).

Once I used a wiki to store short descriptions of every host and changelogs.

I think that the documentation is interesting subject and I haven't seen the best solution yet.
 
At work we use a very simple system based on CVS. Configuration files are stored in there so we have version history and can roll-back changes. Each machine simply runs a script periodically that checks out the relevant files and copies them to the right location. This works reasonably well.

As for documentation, you ideally want a document that describes exactly how the machine is setup. The document should contain enough information for someone else to make an exact working copy of the machine in question.
 
@SirDice: exactly.

After playing around a bit with the 2 aforementioned apps, I came to the conclusion that for our company, i-doit might be a possible choice while for personal use (non DC-driven), iTop might be more suited.

I'm still opened to suggestions.
 
I just noticed a port that was added not too long ago, www/rt40. But that might be a bit overkill for your situation. At first glance it looks very impressive, it pretty much has everything I'd expect a ticketing system to have.
 
da1 said:
How do you guys go about documenting a unix machine ?
Is there some tools you use ?
What do you prefer and why ? paper, electronic, word-style document, db, something else ?
Click to expand...

I keep formal documentation (serial numbers, inventory numbers, hostnames, IP addresses, VLANs, install checklists, significant configuration changes) on a www/dokuwiki install. Local revision control is handled by rcs(1).
 
You must log in or register to reply here.
Back
Top