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.

The three blank spaces at the beginning of each of those lines are critical.

These two lines add your user to the TWikiAdminGroup and allow only members of the TWikiAdminGroup to modify the group. We are now ready to enable authentication for our wiki, so go back to http://www.example.com/wiki/bin/configure. Several options provided under the Security section are useful. You should make sure the options {UseClientSessions} and {Sessions}{UseIPMatching} are enabled. Also set the {LoginManager} option to TWiki::Client::TemplateLogin and {PasswordManager} to TWiki::Users::HtPasswdUser. If your server supports it, you should set {HtPasswd}{Encoding} to sha1. Save your changes and return to the wiki. If you are not logged in automatically, there is a link at the top left of the page that allows you to do so.

Now that you have authentication working, you may want to tighten down your wiki so that unauthorized people do not turn your documentation repository into an illicit data repository. TWiki has a pretty sophisticated authorization system that is tiered from the site-wide preferences all the way down to a specific topic. Before locking down the Main web, a few more tasks need to be done. Once only certain users can change the Main web, registering new users will fail. That is because part of the user registration process involves creating a topic for that user under the Main web. Dakar has a user, TWikiRegistrationAgent, that is used to do this. From the Main web, use the Jump box at the top left to jump to the WebPreferences topic. Edit the topic to include the following four lines and save your changes:

Set ALLOWTOPICRENAME = %MAINWEB%.TWikiAdminGroup
Set ALLOWTOPICCHANGE = %MAINWEB%.TWikiAdminGroup
Set ALLOWWEBRENAME = %MAINWEB%.TWikiAdminGroup
Set ALLOWWEBCHANGE = %MAINWEB%.TWikiAdminGroup,
 -->;%MAINWEB%.TWikiRegistrationAgent

This allows only members of the TWikiAdminGroup to make changes or rename the Main web or update the Main web's preferences. It also allows the TWikiRegistrationAgent user to create new users' home topics when new users register. I have included a patch that you must apply to lib/TWiki/UI/Register.pm as well. The patch follows, but you can also download the patch from the LJ FTP site (see the on-line Resources):

--- lib/TWiki/UI/Register.pm.orig	2006-01-04 01:34:48.968947681 -0600
+++ lib/TWiki/UI/Register.pm	2006-01-04 01:35:48.999652157 -0600
@@ -828,11 +828,12 @@

     my $userName = $data->{remoteUser} || $data->{WikiName};
     my $user = $session->{users}->findUser( $userName );
+    my $agent = $session->{users}->findUser( $twikiRegistrationAgent );
     $text = $session->expandVariablesOnTopicCreation( $text, $user );

     $meta->put( 'TOPICPARENT', { 'name' => $TWiki::cfg{UsersTopicName}} );

-    $session->{store}->saveTopic($user, $data->{webName},
+    $session->{store}->saveTopic($agent, $data->{webName},
                                  $data->{WikiName}, $text, $meta );
     return $log;
 }

Otherwise, new users' home directories will fail to be created and new user registration will fail. Once you have verified that the Main web is locked down, you should do the same for the TWiki and Sandbox webs.

When you are done configuring TWiki, you should secure the files' permissions:

# find /var/www/wiki/ -type d -exec chmod 0755 {} ';'
# find /var/www/wiki/ -type f -exec chmod 0400 {} ';'
# find /var/www/wiki/pub/ -type f -exec chmod 0600 {} ';'
# find /var/www/wiki/data/ -type f -exec chmod 0600 {} ';'
# find /var/www/wiki/lib/LocalSite.cfg -exec chmod 0600 {} ';'
# find /var/www/wiki/bin/ -type f -exec chmod 0700 {} ';'
# chown -R apache /var/www/wiki/*

As I mentioned before, TWiki has a plugin system that you can use. Many plugins are available from the TWiki Web site. Be sure the plugins you choose have been updated for Dakar before you use them.

Keeping Your Users in the Know

One important aspect of system administration that is sometimes overlooked is keeping users informed. Most users like to know when there is new functionality available or when resources are down or not available. Not only does it make users happier to be kept informed, but it also can make your life easier as well. The last thing you want to do when the central file server is down is reply to users' questions about why they cannot get to their files. If you have trained your users to look at a central location for status of the infrastructure first, all you have to do after notification of a problem is post to this central place that there is a problem. Mailing lists also are good for this, but what if the mail server is down? Some people, for instance your boss or VP of the company, might like to know what the status is of things as they happen. These updates might not be suitable to send out to everyone daily via e-mail. You could create yet another mailing list for these notifications, but you also might consider a blog.

If you are not familiar with a blog, let us refer back to Wikipedia: “a blog is a Web site in which journal entries are posted on a regular basis and displayed in reverse chronological order.”

The notion of a blog has been around for centuries in the form of diaries, but blogs recently have had an explosion on the Internet. Many times a blog is started as someone's personal journal or as a way to report news, but blogs can be extremely useful for the sysadmin.

Blogs can help a sysadmin give users an up-to-the-minute status of what they are doing and what the state of the infrastructure is. If you faithfully update your blog, you easily can look back on what you have accomplished so you can make your case for that raise you have been hoping for. It also will help you keep track of what your coworkers are doing. And, with many blog software packages providing RSS feeds, users can subscribe to the blog and be notified when there are new posts.

______________________

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

White Paper
Linux Management with Red Hat Satellite: Measuring Business Impact and ROI

Linux has become a key foundation for supporting today's rapidly growing IT environments. Linux is being used to deploy business applications and databases, trading on its reputation as a low-cost operating environment. For many IT organizations, Linux is a mainstay for deploying Web servers and has evolved from handling basic file, print, and utility workloads to running mission-critical applications and databases, physically, virtually, and in the cloud. As Linux grows in importance in terms of value to the business, managing Linux environments to high standards of service quality — availability, security, and performance — becomes an essential requirement for business success.

Learn More

Sponsored by Red Hat

White Paper
Private PaaS for the Agile Enterprise

If you already use virtualized infrastructure, you are well on your way to leveraging the power of the cloud. Virtualization offers the promise of limitless resources, but how do you manage that scalability when your DevOps team doesn’t scale? In today’s hypercompetitive markets, fast results can make a difference between leading the pack vs. obsolescence. Organizations need more benefits from cloud computing than just raw resources. They need agility, flexibility, convenience, ROI, and control.

Stackato private Platform-as-a-Service technology from ActiveState extends your private cloud infrastructure by creating a private PaaS to provide on-demand availability, flexibility, control, and ultimately, faster time-to-market for your enterprise.

Learn More

Sponsored by ActiveState