NAME

CGI::pWiki - Perl Wiki Environment

SYNOPSIS

#!/usr/bin/perl
use CGI::pWiki;
use strict;
my $pWiki = new CGI::pWiki()->server();
0;

DESCRIPTION

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

USAGE

Installation

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/mod_mime.so
LoadModule dir_module /usr/lib/apache/1.3/mod_dir.so
LoadModule cgi_module /usr/lib/apache/1.3/mod_cgi.so
LoadModule alias_module /usr/lib/apache/1.3/mod_alias.so
LoadModule access_module /usr/lib/apache/1.3/mod_access.so
LoadModule auth_module /usr/lib/apache/1.3/mod_auth.so
LoadModule setenvif_module /usr/lib/apache/1.3/mod_setenvif.so
LoadModule action_module /usr/lib/apache/1.3/mod_actions.so

Add a virtual host directive :

NameVirtualHost *
<VirtualHost *>
    ServerName test.copyleft.de
    DocumentRoot /var/www/test.copyleft.de
    DirectoryIndex index.wiki 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 127.0.0.1 virtual hosts, only !
  # AddHandler wiki-script .xsl
</VirtualHost>

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 127.0.0.1 environment.

Security

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/test.copyleft.de
echo "=location /open/index.wiki" /var/www/test.copyleft.de/index.wiki
mkdir /var/www/test.copyleft.de/open
touch /var/www/test.copyleft.de/open/index.wiki
chmod a+w /var/www/test.copyleft.de/open
chmod a+w /var/www/test.copyleft.de/open/index.wiki

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/test.copyleft.de/ -print | xargs sudo chown kraehe.www-data
find /var/www/test.copyleft.de/ -type d -print | xargs chmod 6775
find /var/www/test.copyleft.de/ ! -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/test.copyleft.de>
    AuthUserFile /usr/local/etc/test.copyleft.de.htpasswd
    AuthName "For Test Only"
    AuthType Basic
    <Limit POST>
        require valid-user
    </Limit>
</Directory>

Or leave this as an option for .htaccess :

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

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/test.copyleft.de/pWiki
mkdir -p /var/lib/pWiki/test.copyleft.de/pWiki
chmod a+w /var/lib/pWiki/test.copyleft.de/pWiki

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

http://test.copyleft.de/pWiki/index.wiki

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/test.copyleft.de/pWiki/

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.

METHODS

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.

AUTHOR

(c) 2002 GNU/GPL+Perl/Artistic Michael Koehne kraehe@copyleft.de

SEE ALSO

CGI

cpanm CGI::pWiki

perl -MCPAN -e shell
install CGI::pWiki