Install TWiki on the OpenSUSE Linux Development Server

When you’re working in a small engineering team, one of the best tools for collaboration is a wiki. After looking at TikiWiki, MediaWiki, and TWiki, I decided to use TWiki. TWiki had the most sophisticated syntax for formatting a page. TWiki’s syntax trumped the downsides of using Perl and files, instead of PHP and MySQL which are used by TikiWiki and MediaWiki.

Below are notes I took when installing and securing TWiki on our OpenSUSE Linux development server.

Perl 5.12 comes pre-installed with OpenSUSE 11.3. Double-check that it is installed properly by running:
perl -version
Browse to http://twiki.org/. Click on the “Download TWiki-5.0.1” button to the right. Input the info requested in the download form on the right half and click on the Download button. You will download a zip archive named “TWiki-5.0.1.zip”.
Put the archive file onto your Linux server. As root user, unzip it to a “twiki” directory under the secure web rot directory “htdocs-ssl” and adjust the permissions so the Apache user can access it:
unzip TWiki-5.0.1.zip -d /srv/www/htdocs-ssl/twiki
chown -R wwwrun:www /srv/www/htdocs-ssl/twiki
Start configuring TWiki by creating a “LocalLib.cfg” file:
cd /srv/www/htdocs-ssl/twiki/bin
cp LocalLib.cfg.txt LocalLib.cfg

Edit the resulting “LocalLib.cfg” file and update the variable “$twikiLibPath” to be the correct path:

$twikiLibPath = "/srv/www/htdocs-ssl/twiki/lib"
Configure Apache by creating a “/etc/apache2/twiki.conf” file with the content below. I generated it using TWiki:TWiki.ApacheConfigGenerator and cleaned it up. (For security reasons, we are putting twiki.conf under “/etc/apache2” instead of “/etc/apache2/conf” to prevent the TWiki Directory directives from being applicable to non-secure HTTP access.)
# Prevent TWiki from including its own topics as URLs (used by DOS attacks).
BrowserMatchNoCase ^$ blockAccess

# ScriptAlias defines bin as a directory where CGI scripts are allowed.
ScriptAlias /twiki/bin "/srv/www/htdocs-ssl/twiki/bin"

# Alias defines pub directory as the root of file attachments.
Alias /twiki/pub "/srv/www/htdocs-ssl/twiki/pub"

# Secure file attachments by using viewfile which enforces permission
RewriteEngine on
RewriteCond %{REQUEST_URI} !^/+twiki/+pub/+(TWiki|Sandbox)/+.+
RewriteRule ^/+twiki/+pub/+(.*)$ /twiki/bin/viewfile/$1 [L,PT]

# Block access to typical spam related attachments
SetEnvIf Request_URI "twiki/pub/.*\.[hH][tT][mM][lL]?$" blockAccess
SetEnvIf Request_URI "twiki/pub/TWiki/.*\.[hH][tT][mM][lL]?$" !blockAccess

# Allow everyone to run perl scripts from the bin directory.
<Directory "/srv/www/htdocs-ssl/twiki/bin">
AllowOverride None
Order Allow,Deny
Allow from all
Deny from env=blockAccess

Options ExecCGI FollowSymLinks
SetHandler cgi-script

# Password file for TWiki users
AuthUserFile /srv/www/htdocs-ssl/twiki/data/.htpasswd
AuthName 'Enter your login name:'
AuthType Basic

# File to return on access control error (e.g. wrong password)
ErrorDocument 401 /twiki/bin/view/TWiki/TWikiRegistration

# Limit access to configure script to localhost since it contains sensitive info.
<FilesMatch "^(configure)$">
SetHandler cgi-script
Order Deny,Allow
Deny from all
Allow from localhost
</FilesMatch>
</Directory>

# Allow access to the pub directory for attachments, CSS stylesheets and icons.
<Directory "/srv/www/htdocs-ssl/twiki/pub">
Options None
AllowOverride None
Order Allow,Deny
Allow from all
Deny from env=blockAccess

# Disable execusion of PHP scripts
php_admin_flag engine off

# This line will redefine the mime type for the most common types of scripts
AddType text/plain .shtml .php .php3 .phtml .phtm .pl .py .cgi
</Directory>

# With exception of bin and pub directories, prevent access to everything else.
<Directory "/srv/www/htdocs-ssl/twiki/">
Deny from all
</Directory>

# Either of this will redirect root / to twiki/bin/view
#RewriteRule ^/$ /twiki/bin/view
#RedirectMatch ^/$ /twiki/bin/view

If you can’t run a browser under localhost, then make sure to comment out the “<FilesMatch “^(configure)$”>” block above so you can run the configure script remotely. If you want to redirect from the root URL to TWiki, just uncomment either “RewriteRule” or “RedirectMatch” at the end; don’t uncomment both because I’m not sure what would happen.
To allow access to the TWiki only from SSL/HTTPS, we will include the twiki.conf into the SSL virtual host configuration. Edit the “/etc/apache2/vhost.d/your_vhost-ssl.conf” file (which you created in this post) and add the following Include directive anywhere inside the “<VirtualHost>” block:
<VirtualHost _default_:443>
...
Include /etc/apache2/twiki.conf
...
</VirtualHost>
The twiki.conf uses the mod_redirect module which we will need to configure Apache to load on startup. Good thing we have to restart Apache for the Twiki.conf to take effect also.
a2enmod redirect
rcapache2 restart
Run the Twiki configure script by browsing to “https://localhost/twiki/bin/configure” or equivalent. Ignore the warning about the missing “/srv/www/htdocs-ssl/twiki/lib/LocalSite.cfg” configuration file. You will create it by running the configure script this first time.
- Input your new administrative password and click Configure button.
- Click on “General path settings” to expand it:
  - Change the “{DefaultUrlHost}” to match your website’s domain URL.
  - Input “https://localhost” into “{PermittedRedirectHostUrls}” so you can access Twiki from a local browser.
  - Verify that the rest are correct (they should be) and click on Next.
  - Click on Save button, click on “Return to configuration” link, and enter your admin password again.
- You will see three sections with warnings. We’ll address a couple of those warnings below, but not all. It’s okay to run TWiki with some warnings.
- Click on “Security setup”.
  - Check “{Register}{AllowLoginName}” if you wish to allow the use of a login ID instead of WikiName.
  - I left the “{Register}{NeedVerification}” unchecked because I haven’t set up SMTP yet. This is okay because once we complete securing the TWiki, only logged-in users will be able to register new users.
  - You might want to increase the “{MinPasswordLength}” to 4 from the default 1 character.
  - You will definitely want to uncheck the “{CryptToken}{Enable}” option because it will cause a browser back action to prevent all Edits and Previews from succeeding in that session. While, I applaud the intent, this feature is flawed. When you preview a page, to re-edit it, you have to hit the Back browser button, and then if you attempt to save, CryptToken will prevent you from doing so. And once this happens, any page you attempt to edit and save will fail. (If you plan never to use Preview or use the browser back button, then you can leave this option on.)
- Click on “Mail and Proxies”.
  - Uncheck the “{EnableEmail}” option since SMTP wouldn’t work anyhow.
  - Click Next and Save.
Browse to the main TWiki page at https://localhost/twiki/bin/view. You will see a nice congratulations message.
Click on the Registration link under “Main Web Utilities” to register a new user.
- Just fill in the required info. Once you click Submit, your user will be created and logged into Twiki automatically.
- Click on the TwikiUsers link on the resulting page.
- If you want to create another user, click on the TWikiRegistration link and repeat as necessary.
- Once you are done and back on the TWikiUsers page, log out by clicking on the “Account” menu to the top-right and selecting “Log out”.
For the following, you will need to log in as the administrator.
- Go to the “Account” menu and select “Log in”. Input “admin” as the username and your administrative password.
- Click on TWikiUsers and then TWikiGroups after “Related topics”.
- Creating a new non-admin user group by inputting “TWikiUserGroup” into the “New Group” field and clicking on Add button. Add the WikiNames for non-administrative users to the “Set GROUP =” property. Click on the Save button.
- Go back to TWikiGroups and click on TWikiAdminGroup to add your user as an administrator. Edit, add your WikiName to “Set GROUP =”, and Save.
- At the bottom of the resulting page, click on TWikiAdminGroup to add your new user to the administrator group.
- Now that we have groups and users configured, let’s restrict access to the TWiki.
  - Click on the TWikiAccessControl at the bottom.
  - Scroll down to the “Permissions settings of the webs on this TWiki site” section.
  - Click on the wrench icon before “Main” to edit the Main page permissions.
  - Edit the page and set the following to restrict access to the admin group and our user group.
    Set ALLOWWEBVIEW = %USERSWEB%.TWikiAdminGroup, %USERSWEB%.TWikiUserGroup
    Set ALLOWWEBCHANGE = %USERSWEB%.TWikiAdminGroup, %USERSWEB%.TWikiUserGroup,
    TWikiRegistrationAgent
    Set ALLOWWEBRENAME = %USERSWEB%.TWikiAdminGroup, %USERSWEB%.TWikiUserGroup
    
    Note: TWikiRegistrationAgent belongs on the same line as %USERSWEB%.TWikiUserGroup.
    
    It is necessary to allow the TWikiRegistrationAgent to change Main.TWikiUsers to enable new user registration.
  - Save the page.
  - Go back to TWikiAccessControl (link at bottom) and repeat the above access restrictions (without TWikiRegistrationAgent) by clicking on the wrench icon before the “TWiki” link right under “Main” and changing the following:
    Set ALLOWWEBVIEW = %USERSWEB%.TWikiAdminGroup, %USERSWEB%.TWikiUserGroup
    Set ALLOWWEBCHANGE = %USERSWEB%.TWikiAdminGroup, %USERSWEB%.TWikiUserGroup
    Set ALLOWWEBRENAME = %USERSWEB%.TWikiAdminGroup, %USERSWEB%.TWikiUserGroup
  - I disable the “SandBox” instead of setting permissions on it. You can do otherwise.
    Set SITEMAPLIST = off
- Log out.
Browse to the main TWiki page. You will see a mandatory login form.
Because email was not set up, none of the users have gotten an email containing their randomly generated passwords. To fix this, do the following:
- Edit the “/srv/www/htdocs-ssl/twiki/data/.htpasswd” file.
  - For each user line, blank out the password by deleting the random character string (encrypted password) between the first colon and second colon.
  - Save the file. Users that you have modified above will now have blank passwords.
- Ask the users to log in with blank passwords and set their new passwords by doing the following:
  - Click on their name under the top-right Accounts menu.
  - Click on the ChangePassword link at the bottom to set their passwords.
That’s it. Hope that you were able to get it working.

Ease of Use Items:

I don’t like the automatic CamelCase or WikiWord linking that TWiki has enabled by default. If I want a link, I will specify so using the square brackets. If you feel the same way, here is how you can disable this feature:
1. Log into TWiki as a user with administrative privileges or as the default “admin” user.
2. Click on the “Web Preferences” link on the right navigation table or at the bottom.
3. Edit the “Web Preferences” page and add the following under “Web settings” section:
  * Set NOAUTOLINK = on
  * Set HIDE_NON_WIKI_WORD_WARNINGS = on
The default way to go back to the parent page in TWiki is to hit the browser back button (which breaks CryptToken) or by clicking on the “Backlinks” link at the bottom (too many clicks). I love breadcrumbs and we can add a plugin to TWiki to support this function:
1. Run the TWiki configure script (https://localhost/twiki/bin/configure). Enter your admin password.
2. Click on “Extensions” and “Find More Extensions”. Enter your admin password.
3. Find BreadCrumbsPlugin and click on its “Install” link to the far right. Enter your admin password.
4. On my system, I got a weird Perl error. If you got the same, we have to install manually by doing the following:
  1. SSH into the linux server.
  2. Change directory to the TWiki installation root directory: “cd /srv/www/htdocs-ssl/twiki”
  3. There should be a script named “BreadCrumbsPlugin_installer” there. Execute it by running “Perl BreadCrumbsPlugin_installer”.
  4. Answer Yes to the re-install module prompt. The installation should complete successfully.
5. Re-run the TWiki configure script (https://localhost/twiki/bin/configure). Enter your admin password.
6. Go to “Plugins” and check the “{Plugins}{BreadcrumbsPlugin}{Enabled}” box. Save the change.
7. Log into the TWiki and edit the “Web Preferences” page to add the following under “Web settings” section:
  * Set BREADCRUMBSPLUGIN_RECORDTRAIL = on
8. In your wiki pages, add the following “%BREADCRUMBS%” variable at the top and when you view the page, it will be rendered as breadcrumb links.

Some info above derived from:

The official TwikiInstallationGuide.
If you decide to go with MediaWiki, check out Making MediaWiki secure (and fixing some config annoyances) for instructions on how to secure MediaWiki. I tried the instructions and they worked pretty well.