CGI::pWiki - Perl Wiki Environment


 use CGI::pWiki;
 use strict;
 my $pWiki = new CGI::pWiki()->server();


The CGI::pWiki class, is providing an environment for serving a WikiWikiWeb for virtual hosts and multiple databases.



At first install the CGI::pWiki module either on the CPAN, or the Debian or by hand as usual with :

 perl Makefile.PL &&
      make &&
      make test &&
      su -c "make install"

First check your /etc/apache/httpd.conf for the system wide ScriptAlias path and directory path.

 ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/

The pWiki distibution includes a pWiki.cgi to be symlinked from your install point to your system wide cgi-bin directory.

 ln -s /usr/local/bin/pWiki.cgi /usr/lib/cgi-bin/

Next check your /etc/apache/httpd.conf to contain at least those modules :

 LoadModule mime_module /usr/lib/apache/1.3/
 LoadModule dir_module /usr/lib/apache/1.3/
 LoadModule cgi_module /usr/lib/apache/1.3/
 LoadModule alias_module /usr/lib/apache/1.3/
 LoadModule access_module /usr/lib/apache/1.3/
 LoadModule auth_module /usr/lib/apache/1.3/
 LoadModule setenvif_module /usr/lib/apache/1.3/
 LoadModule action_module /usr/lib/apache/1.3/

Add a virtual host directive :

 NameVirtualHost *
 <VirtualHost *>
     DocumentRoot /var/www/
     DirectoryIndex index.xml index.html index.htm index.text
     Action wiki-script /cgi-bin/pWiki.cgi
   # Some Apaches need the next line, also.
   # ErrorDocument 404 /cgi-bin/pWiki.cgi
     AddHandler wiki-script .wiki
     AddHandler wiki-script .text
     AddHandler wiki-script .html
     AddHandler wiki-script .htm
     AddHandler wiki-script .pod
     AddHandler wiki-script .xml
   # The next line should be in virtual hosts, only !
   # AddHandler wiki-script .xsl

There is no need to add any handler besides .wiki and .text, if you dont want to manage the other files with pWiki. Handling .xsl files in fact opens a wide security hole, and should NOT be done outside a VirtualHost environment.


CGI::pWiki will offer users from outside to write files in the document root of your webserver. It is therefore a possible security hole. The minimal security is to constrain write access by using the Unix chmod command. e.g. :

 mkdir /var/www/
 echo "=location /open/" /var/www/
 mkdir /var/www/
 touch /var/www/
 chmod a+w /var/www/
 chmod a+w /var/www/

This will create a document root for the test site, installs a relocation of the index page, and creates an open area and its index page, and makes it world writeable, while other areas will stay read only.

A typical all public site for creating open content may want to allow every directory to be writeable. Adopt the following lines to migrate existing content.

 find /var/www/ -print | xargs sudo chown kraehe.www-data
 find /var/www/ -type d -print | xargs chmod 6775
 find /var/www/ ! -type d -print | xargs chmod 664

You may want to restrict edit access to the Wiki as a webmaster by defining a directory directive :

 <Directory /var/www/>
     AuthUserFile /usr/local/etc/
     AuthName "For Test Only"
     AuthType Basic
     <Limit POST>
         require valid-user

Or leave this as an option for .htaccess :

 AuthUserFile /usr/local/etc/
 AuthName "For Test Only"
 AuthType Basic
 <Limit POST>
     require valid-user

First Test

You can now test the pWiki by reloading Apache. Create a directories for your virtual host to contain a database called pWiki. The second directory needs to be writeable by the webserver, as it contains the shadow pages, if people change the content online.

 mkdir -p /var/www/
 mkdir -p /var/lib/pWiki/
 chmod a+w /var/lib/pWiki/

Browse at your fresh created test site and enter the URL :

This should show an edit window. Submit something like the following :

 This is a test for pWiki.

Click on the pWiki and submit the following :

 The CGI_pWiki Perl_Module is an Apache_Handler acting as a
 wrapper around a WikiWikiWeb for creating content in a
 [comunity] on the fly.

 Benefits : 

 * rapid content creation
 * easy formatting rules
 * multiple authors

 CGI_pWiki is able to handle the following extensions :

 | .html | normal hypertext pages |
 | .text | preformated text pages |
 | .wiki | pWiki formated hypertext pages |
 | .xml | XSL formated hypertext pages |
 | .pod | PlainOldDocumentation |

Ensure that there are no leading white space when cut and paste.

Adding Style

The CGI-pWiki distribution contains an example database. Copy it to your document root :

 cp htdocs/pWiki/* /var/www/

The style is defined in pairs of files with .lnx and .moz extension. Copy the pWiki/content.{lnx,moz}-exam files to your document root and define the main table of contents.


new proto HASH

Creates a new pWiki object. Default options are passed as key-value pairs or as a single hash. Options may be changed directly in the object.


 (c) 2002 GNU/GPL+Perl/Artistic Michael Koehne



1 POD Error

The following errors were encountered while parsing the POD:

Around line 200:

You forgot a '=back' before '=head1'