Using Wikis and Blogs to Ease Administration

This tutorial on TWiki and WordPress shows how wikis and blogs can be useful for system administration and documentation.

System administration can be like sailing a ship. You must keep your engines running smoothly, keep your crew and the harbors notified and up to date and also maintain your Captain's log. You must keep your eye on the horizon for what is coming next. Two technologies have emerged over the past few years that could help keep you on course, wikis and blogs.

Maintaining Good Documentation

I find that one of the most difficult aspects of system administration is keeping documentation accurate and up to date. Documenting how you fixed a pesky problem today will help you remember how to fix it months later when it occurs again. If you ever have worked with others, you realize how critical good documentation is. Even if you are the only system administrator, you still will reap the benefits of good documentation, even more so if another sysadmin is ever brought on board.

Some goals of a good documentation system should be:

  • Make it easy for you and your coworkers to find relevant information.

  • Make it easy for new employees to come up to speed quickly.

  • Make it easy to create, edit and retire documentation.

  • Keep revisions of changes and who made them.

  • Limit who sees or edits the documentation with an authentication system.

Unfortunately, keeping your documentation up to date can be a full-time job in itself. Documenting, though not a very glamorous task, certainly will pay off in the long run.

Why a Wiki?

This is where a wiki comes in. From Wikipedia: “a wiki is a type of Web site that allows users to add and edit content and is especially suited for constructive collaborative authoring.”

What this means is a wiki allows you to keep and edit your documentation in a central location. You can access and edit that documentation regardless of the platform you are using. All you need is a Web browser. Some wikis have the ability to keep track of each revision of a changed document, so you can revert to a previous version if some errant changes are made to a document. The only obstacle a new user must overcome is learning the particular markup language of your wiki, and sometimes even this is not completely necessary.

One of a wiki's features is also one of its drawbacks. Wikis are pretty free flowing, and although this allows you to concentrate on getting the documentation written quickly, it can make organization of your wiki rapidly spiral out of control. Thought needs to be put into how the wiki is organized, so that topics do not get stranded or lost. I have found that making the front page a table of contents of all the topics is very handy. However you decide to organize your wiki, make sure it is well understood by everyone else. In fact, a good first document might be the policy describing the organization of the wiki!

TWiki

There are several open-source wikis available, such as MediaWiki [see Reuven M. Lerner's article on page 62 for more information on MediaWiki] and MoinMoin, each with its own philosophy on markup and layout, but here we concentrate on TWiki. Some of TWiki's benefits are:

  • A notion of webs that allows the wiki administrator to segregate areas of collaboration into their own areas, each with its own set of authorization rules and topics.

  • A modular plugin and skin system that allows you to customize easily.

  • A well-established base of users and developers.

  • Revision control based on RCS.

  • It is Perl-based and mod_perl or FastCGI can be used.

  • Authentication is handled outside the wiki by mechanisms such as Apache htpasswd.

The most current stable release at this time is Cairo, or TWiki20040904. It was released, as the name suggests, on September 4, 2004, and it has been proven to be very stable. However, it does lack some of the features of the current beta release, Dakar, that I find to be very useful. The Dakar release we use here is TWikiRelease2005x12x17x7873beta.

Installing TWiki is relatively easy, but still needs work. I hope, as the beta progresses, we will see improvements in ease of installation and upgrading along with clearer documentation.

First, you must create the directory where you want to install TWiki, say /var/www/wiki. Next, untar the TWiki distribution in that directory. Then you must make sure that the user with rights to run CGI scripts (usually apache or www-data), owns all of the files and is able to write to all files:

# install -d -o apache /var/www/wiki
# cd /var/www/wiki
# tar zxf /path/to/TWikiRelease2005x12x17x7873beta.tgz
# cp bin/LocalLib.cfg.txt bin/LocalLib.cfg
# vi bin/LocalLib.cfg lib/LocalSite.cfg
# chown -R apache *
# chmod -R u+w *

Now copy bin/LocalLib.cfg.txt to bin/LocalLib.cfg, and edit it. You need to edit the $twikiLibPath variable to point to the absolute path of your TWiki lib directory, /var/www/wiki/lib in our case. You also must create lib/LocalSite.cfg to reflect your specific site information. Here is a sample of what might go into LocalSite.cfg:

# This is LocalSite.cfg. It contains all the setups for your local
# TWiki site.
$cfg{DefaultUrlHost} = "http://www.example.com";
$cfg{ScriptUrlPath} = "/wiki/bin";

$cfg{PubUrlPath} = "/wiki/pub";
$cfg{DataDir} = "/var/www/wiki/data";
$cfg{PubDir} = "/var/www/wiki/pub";
$cfg{TemplateDir} = "/var/www/wiki/templates";
$TWiki::cfg{LocalesDir} = '/var/www/wiki/locale';

Here is a sample section for your Apache configuration file that allows this wiki to run:


ScriptAlias /wiki/bin/ "/var/www/wiki/bin/"
Alias /wiki "/var/www/localhost/wiki"
<Directory "/var/www/wiki/bin">
    Options +ExecCGI -Indexes
    SetHandler cgi-script
    AllowOverride All
    Allow from all
</Directory>
<Directory "/var/www/wiki/pub">
    Options FollowSymLinks +Includes
    AllowOverride None
    Allow from all
</Directory>
<Directory "/var/www/wiki/data">
    deny from all
</Directory>
<Directory "/var/www/wiki/lib">
    deny from all
</Directory>
<Directory "/var/www/wiki/templates">
    deny from all
</Directory>

TWiki comes with a configure script that you run to set up TWiki. This script is used not only on initial install but also when you want to enable plugins later. At this point, you are ready to configure TWiki, so point your browser to your TWiki configure script, http://www.example.com/wiki/bin/configure. You might be particularly interested in the Security section, but we will visit this shortly. Until you have registered your first user, you should leave all settings as they are. If the configure script gives any warnings or errors, you should fix those first and re-run the script. Once you click Next, you are prompted to enter a password. This password is used whenever the configure script is run in the future to help ensure no improper access.

Once you have completed the configuration successfully, it is time to enter the wiki. Point your browser to http://www.example.com/wiki/bin/view, and you are presented with the Main web. In the middle of the page is a link for registration. Register yourself as a user. Be sure to provide a valid e-mail address as the software uses it to validate your account. Once you have verified your user account, you need to add yourself to the TWikiAdminGroup. Return to the Main web and click on the Groups link at the left, and then choose the TWikiAdminGroup. Edit this page, and change the GROUP variable to include your new user name:

   Set GROUP = %MAINWEB%.TiLeggett
   Set ALLOWTOPICCHANGE = %MAINWEB%.TWikiAdminGroup

______________________

Comments

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

I would like to appreciate

backgammon's picture

I would like to appreciate your efforts in for writing this useful article. I am sure it will make the difference You are truly my inspiration. You, see when i first log in to google to i did not think that i could find such a interesting direction, which would really help me in a positive manner. May God bless you that you will keep doing the nice work always.

Thanks

CSS Forum's picture

very informative

The company I work for uses

Anonymous's picture

The company I work for uses MediaWiki as an internal know-how database.

http.conf problems

tony.cureington's picture

I had problems with graphics showing up using NatSkin, but I suspect it would be in all ather skins as well.

Long story short:
I looked in /var/log/httpd/ssl_error_log and found errors

Edited /etc/httpd/conf/httpd.conf and changed
Alias /wiki "/var/www/localhost/wiki"
to
Alias /wiki "/var/www/wiki"

Restarted httpd and it worked....

The "localhost" seems to cause things not to work, at least for me.

Cheers,
Tc

Article on Performance Tuning of Twiki

Anonymous's picture

There is an article on twiki performance tuning in the April 2006 issue of Sysadmin Magazine: http://www.samag.com/current/

The author is able to boost twiki installations by factor 20 for read access.

The method presented can be used for other wikis too.

Wrong title for the article

WhyofcourseMe's picture

The article title suggests that it will discuss using Wiki's and Blog's for documentation. It does start out with a short "why" on Wiki's, it does not addresses "why blogs" at all. I would have liked more information on why and how. Examples are key for me, personally.
My companies documentation is a bit of a mess. We are using a UML tool to document everything which means:
1) It was a lot of work work to put togther and just as much work to maintain (which means that a week later, it was already out of date).
2) Impossible to get a report out of it. I'm no expert in the tool, but I should not have to be to extract information I put in.
3) As pointed out above, too much overhead to learn. I spend enough of my free time reading articles and books on subjects that I am paid to do (and enjoy doing). I'm not going to spend an evening reading the manual of a tool I don't think fits the job.

Sorry - a little off track but I got a little frustrated reading an article on how to install software when I expected to read why I would want to.

Correction to permissions above & SpeedyCGI help

Marcus's picture

Those examples above won't work. Instead of
(space)(space)(space)Set BLAHBLAH = something
you need a TWiki bullet point:
(space)(space)(space)*(space)Set BLAHBLAH = something.

URL for help with SpeedyCGI:
http://twiki.org/cgi-bin/view/Codev/SpeedyCGI

Cheers.

More about using blogs as administration document tool

daFool's picture

I have two blogs at work. One is called "The life of the machines" where each machine has it's own category. All entries are short descriptions about things that I or someone else inside the company have done to the machines.

Another one is called "The laboratory" and it is personal but mostly open to anybody inside our company. I use it to document things I have experimented with, things I have done during the day and things that are still open for the next day or for the near future. It also serves as a store for ideas to experiment with etc. I have categories for several projects and also use the blog to track time spent in projects with a plugin I have written for the task. I even use tracked time as basis of intra corporation billing. I have also integrated my blog as a datasource for the company reporting system. I can run reports against my blog and see where my time has gone in a nice pie chart.

Of course I write official documentation based on my blog entries to the company wiki. ;-)

My company uses wiki, too

mangoo's picture

The company I work for uses MediaWiki as an internal know-how database.

It's working like a charm.

A friend of me is also using

Steff's picture

A friend of me is also using MediaWiki as an external database. I think it's a great idea and hope to have the time to test it on my own soon.

Latest stable TWiki release

Michael Daum's picture

Actually, TWiki-4.0 (codename dakar) has been released on 1 Feb 2006 already. There's even a first maintenance release, TWiki-4.0.1 available. The patch described above isn't necessary anymore.

The previous release (TWiki20040904) was available on 28 Feb 2005.

I recommend to run TWiki by using SpeedyCGI, not FastCGI or mod_perl.

Michael, any tips on

Anonymous's picture

Michael, any tips on setting it up with SpeedyCGI?

easiest speedy setup is to

Anonymous's picture

easiest speedy setup is to use the cgi, not the apache mod, and just replace the perl shebang line with the path to speedy e.g. "#!/path/to/speedy". Don't accelerate all the scripts, just bin/view is sufficient. more at http://twiki.org/cgi-bin/view/Codev/SpeedyCGI

Webinar
One Click, Universal Protection: Implementing Centralized Security Policies on Linux Systems

As Linux continues to play an ever increasing role in corporate data centers and institutions, ensuring the integrity and protection of these systems must be a priority. With 60% of the world's websites and an increasing share of organization's mission-critical workloads running on Linux, failing to stop malware and other advanced threats on Linux can increasingly impact an organization's reputation and bottom line.

Learn More

Sponsored by Bit9

Webinar
Linux Backup and Recovery Webinar

Most companies incorporate backup procedures for critical data, which can be restored quickly if a loss occurs. However, fewer companies are prepared for catastrophic system failures, in which they lose all data, the entire operating system, applications, settings, patches and more, reducing their system(s) to “bare metal.” After all, before data can be restored to a system, there must be a system to restore it to.

In this one hour webinar, learn how to enhance your existing backup strategies for better disaster recovery preparedness using Storix System Backup Administrator (SBAdmin), a highly flexible bare-metal recovery solution for UNIX and Linux systems.

Learn More

Sponsored by Storix