Skip to topic | Skip to bottom
Powered by TWiki

TWiki

Log In

You are here: TWiki > TWikiDocumentation
r0 - 27 Mar 2005 - 13:14 - TWikiContributor


TMPL:P{"i18n:start_of_topic"}% | TMPL:P{"i18n:skip_to_actions"}%

TWiki Reference Manual (Mon, 29 Aug 2005 build 6193)

This page contains all documentation topics as one long, complete reference sheet.
Doubleclick anywhere to return to the top of the page.

Note - if you are reading this at twiki.org, then you are reading about the most recent code under development.
If you want to read about the features on your local TWiki, then you should read the documentation there!

Note: Read the most up to date version of this document at http://TWiki.org/cgi-bin/view/TWiki/TWikiDocumentation

Related Topics: TWikiSite, TWikiHistory, TWikiPlannedFeatures, TWikiEnhancementRequests, UserDocumentationCategory, AdminDocumentationCategory

TWiki System Requirements

Server and client requirements for TWiki 01-Sep-2004

Low client and server requirements are core features that keep TWiki widely deployable, particularly across a range of browser platforms and versions.

Server Requirements

TWiki is written in Perl 5, uses a number of shell commands, and requires RCS (Revision Control System), a GNU Free Software package. TWiki is developed in a basic Linux/Apache environment. It also works with Microsoft Windows, and should have no problem on any other platform that meets the requirements.

ResourceRequired Server Environment *
Perl 5.005_03 or higher (5.6.1 recommended, 5.8.x does work in most cases, but see TWiki:Codev.IssuesWithPerl5dot8)
Non-standard Perl modules • Unix: Net::SMTP (or sendmail)
• Windows: Net::SMTP, MIME::Base64, Digest::SHA1
• Internationalisation: Unicode::MapUTF8   (only for non-ISO-8859-1 sites using TWiki:Codev.EncodeURLsWithUTF8 with Perl 5.6 or lower)
RCS 5.7 or higher (including GNU diff)
Optional, but the all-Perl RCS replacement is not currently recommended for live sites - see TWiki:Codev.RcsLite
GNU diff GNU diff 2.7 or higher is required when not using the all-Perl RcsLite.
Install on PATH if not included with RCS (check version with diff -v)
Must be the version used by RCS, to avoid problems with binary attachments - RCS may have hard-coded path to diff
Other external programs fgrep, egrep
Cron/scheduler • Unix: cron
• Windows: cron equivalents
Web server Apache 1.3 is well supported; Apache 2.0 is not recommended yet (see TWiki:Codev.IssuesWithApache2dot0).
For other servers, CGI support, authentication, extended path info required; also, the register script is likely to need significant changes

warning * Current documentation mainly covers Linux and Apache installations. See WindowsInstallCookbook for a Windows installation guide. See TWiki:Codev.TWikiOn for help with installation on various platforms including Unix, MacOS X, Apache mod_perl, web hosts, etc.

Client Requirements

The TWiki standard installation has extremely low browser requirements:

  • HTML 3.2 compliant
  • generates XHTML 1.0 pages that are compatible with HTML 3.2
  • minimal use of JavaScript in the user interface (degrades gracefully)
  • no cookies
  • no CSS (if the ClassicSkin is used)

You can easily add functionality, by customizing TWikiTemplates, for one, while tailoring the browser requirements to your situation.

Important note about TWikiPlugins

  • The TWikiPlugins feature currently does not have compatibility guidelines for developers. Plugins can require just about anything - browser-specific functions, stylesheets (CSS), Java applets, cookies, specific Perl modules,... - check the individual Plugin specs.
    • help Plugins included in the TWiki distribution do not add requirements.

Related Topics: AdminDocumentationCategory

TWiki Installation Guide

Installation instructions for the TWiki Dakar production release

Please review the AdminSkillsAssumptions before you install TWiki.

TWiki should be fine with any web server and OS that meet the system requirements. Please check the topics listed below for any important news or tips for your platform.

  • For Unix or Linux, check TWiki:Codev/TWikiOnUnix and TWiki:Codev/TWikiOnLinux.
  • For Windows, check the WindowsInstallCookbook.
  • For MacOS X, check TWiki:Codev/TWikiOnMacOSX.
  • To install TWiki on SourceForge, for use on a software development project, read TWiki:Codev/TWikiOnSourceForge
  • For other platforms, see TWiki:Codev/TWikiOn, and search the TWiki:Codev and TWiki:Support webs for other installation notes.

If you need help, ask a question in the TWiki:Support web or on TWiki:Codev.TWikiIRC (irc.freenode.net, channel #twiki)

Basic Installation

  1. Download the TWiki distribution from http://TWiki.org/download.html.
  2. Unpack the distribution where you want to install it.
  3. Make sure the user that runs CGI scripts on your system can read and write all files in the distribution.
  4. Make sure Perl 5 and the Perl CGI library are installed on your system.
    The default location of Perl is /usr/bin/perl. If it's somewhere else, change the path to Perl in the first line of each script in the twiki/bin directory.
    help Some systems require a special extension on perl scripts (e.g. .cgi or .pl). If necessary, rename all files in twiki/bin (i.e. rename view to view.pl etc). If you do this, make sure you set the ScriptSuffix option in configure (Step 6).
  5. Create the file /twiki/bin/LocalLib.cfg.
    There is a template for this file in /twiki/bin/LocalLib.cfg.txt.
    The file must contain a setting for $twikiLibPath, which must point to the absolute file path of your twiki/lib e.g. /home/httpd/twiki/lib.
    help If you need to install additional CPAN modules, but can't update the main Perl installation files on the server, you can set $CPANBASE to point to your personal CPAN install. Don't forget that the webserver user has to be able to read those files as well.
  6. Configure the webserver so you can execute the bin/configure script from your browser.
    Run the configure script from your browser, and resolve any errors or warnings it tells you about.
You now have a basic, unauthenticated installation running. At this point you can just point your Web browser at http://yourdomain.com/twiki/bin/view and start TWiki-ing away!

Next Steps (optional)

Once you have your TWiki running, you can move on to customise it for your users.
  • Edit the TWikiPreferences topic in the TWiki web. Read through it and set any additional settings you think you might need (you can click the 'Edit' button near the top to edit the settings in place)
  • Enable authentication, if required. Read TWikiUserAuthentication..
  • Enable email notification (WebChangesAlerts). Read TWikiSiteTools.
  • Install Plugins. TWiki:Plugins is an extensive library of Plugins for TWiki, that enhance functionality in a huge number of ways. A few plugins are pre-installed in the TWiki distribution. Installation instructions for the other plugins can be found in the plugin topics on TWiki.org.

Troubleshooting

The first step is to re-run the configure script and make sure you have resolved all errors, and are happy that you understand any warnings.

Faliing that, please check the topics listed below, they include some important tips for HP-UX, Solaris, OS/390, and many other platforms.

  • For Unix or Linux, check TWiki:Codev/TWikiOnUnix and TWiki:Codev/TWikiOnLinux.
  • For Windows, check the WindowsInstallCookbook.
  • For MacOS X, check TWiki:Codev/TWikiOnMacOSX.
  • To install TWiki on SourceForge, for use on a software development project, read TWiki:Codev/TWikiOnSourceForge
  • For other platforms, see TWiki:Codev/TWikiOn, and search the TWiki:Codev and TWiki:Support webs for other installation notes.

If you need help, ask a question in the TWiki:Support web or on IRC (irc.freenode.net, channel #twiki)

Windows Install Cookbook

Introduction

This cookbook is intended to get you up and running with TWiki on Windows quickly, with as few problems as possible. The 'cookbook' approach is simply to restrict the many choices that someone installing TWiki must make, so that a reasonably well-defined procedure can be followed - new users can simply follow the steps, while experts can use this as more of a guideline.

  • NOTE: This cookbook is not 100% complete (e.g. it doesn't cover authentication setup described by existing documentation), but it has been used successfully for several years - it is quite accurate and should get you started if you follow the instructions. Please provide feedback in TWiki:Codev.WindowsInstallCookbookComments.
  • NOTE: You will get the best results from following this cookbook exactly, using the same directories, etc - however, if you really do need to vary things, it should be fairly obvious what to do.

Summary

new - See WindowsInstallSummary for a concise summary of the whole cookbook.

Scope

This document covers installation of the TWiki Dakar production release on the following environment - if you want to use a different environment, feel free to use this as a guideline only.

ComponentName, versionComment
Operating System Windows 2000 or XP Should also work for Windows NT
Web Server Apache 1.3.33 Check latest version at http://httpd.apache.org, but don't use Apache 2.0 yet
Unix tools Cygwin 1.5.12-1 Simplest way to get a whole set of required tools - later versions should be fine
Perl Cygwin perl-5.8.5-3 Comes with Cygwin, Perl 5.8 is now fine
RCS Cygwin rcs-5.7-3 Comes with Cygwin

Why this choice of packages? Because we've tried them, and they work well, without requiring a complicated setup... In particular, Apache is the commonest choice for TWiki on Unix/Linux, Cygwin Perl is very close to Unix Perl, and the Cygwin RCS is regularly updated. Cygwin also lets you install the Unix tools, Perl and RCS in a single step, saving quite a lot of time.

More recent minor versions should be OK, but they can introduce bugs.

new Major version upgrades, such as Apache 2.0, are very likely to cause problems - for example, Apache 2.0 is unable to authenticate users created by the current TWiki user registration script (due to a feature being removed in 2.0, see TWiki:Support.FailedAuthenticationWithApache2OnWinNT). Even though the Apache group says that Apache 2.0 is the best version, that's not true for TWiki on Windows at present (and particularly not true for sites using internationalisation - see TWiki:Codev.ApacheTwoBreaksNonUTF8EncodedURLsOnWindows). Perl 5.8 may also cause minor issues though it's generally OK. For more information, see TWiki:Codev.IssuesWithApache2dot0 and TWiki:Codev.IssuesWithPerl5dot8.

Alternatives

The following Windows operating systems have been tested following the instructions given here:
  • Windows NT, 98 and ME all work fine with minor tweaks
  • Windows XP works but please report any XP installations on TWiki:Codev.TWikiOnWindowsKnownConfigurations, and comment at TWiki:Codev.WindowsInstallCookbookComments.

There are doubtless other combinations of components that may work - in particular:

  • TWiki:Codev.ActiveState Perl involves only minor changes in http://www.socialscience-ed.org/pages/bin/configure, and is probably a simpler choice if you need an easy way to install mod_perl (see TWiki:Codev.ModPerl)..
  • Using a different web server is certainly possible, but the setup required for each webserver varies greatly (see TWiki:Codev.TWikiOnWindows for pages about specific web servers). You may find it easiest to get a working system with Apache and then switch over to another web server.

Covering the whole range of additional possibilities, particularly web servers, would make this cookbook too complex, and is best handled as a separate activity.

For improved performance on Windows through using mod_perl, you may want to try TWiki:Codev.WindowsModPerlInstallCookbook.

Checking versions

If you already have some of these add-ons installed, here's how to check the versions - this assumes you have TWiki:Codev.CygWin already installed: 

   $ : Cygwin DLL version is the number in 1.5.x format
   $ uname -r
   $ less c:/your-apache-dir/Announcement
   $ perl -v
   $ rcs -V

If you have an older version of any component, do yourself a favour and upgrade it as part of the install process.

Pre-requisites and upgrades

You will need to have local administrator rights and be comfortable with Windows administration.

This cookbook is intended for a clean install, i.e. none of these components are already installed. However, since Cygwin and Apache's installation process is fairly upgrade-friendly, upgrades should work as well - take backups of all your data and config files first, though!

Text editing

Editing Cygwin files should be done with an editor that can handle Unix file format (see the Cygwin binary mode section below). The installation process suggests:
  • nano, a very simple text editor, installed optionally during Cygwin installation. Always launch nano with the -w command-line option to turn off wrapping of long lines.
  • vim, a more sophisticated vi compatible editor that should be familiar to most Unix users
These both non-GUI editors, but if you prefer to use a GUI editor you can install PFE, a freeware editor that supports Unix format files. PFE is available on download.com and Simtel.

Another good TWiki:Codev.OpenSource editor is SciTE (aka WSciTE), available at http://www.scintilla.org/SciTE.html.

The Unix/Windows Environment

It's a little known fact that you can use pathnames such as c:/apache almost everywhere in Windows - try it in a File Open dialogue box. The main exception is the Windows "DOS" command line shell - here, you must use double quotes around forward slashes, e.g. dir "c:/apache" will work fine.

The reason this matters is that '\' is a special character to Perl and other tools, so it's much easier to use '/' everywhere.

The Cygwin environment

TWiki:Codev.CygWin is a Unix-like environment for Windows - many of its tools support the c:/apache format, but it also provides a more Unixlike syntax, e.g. /usr/bin/rcs.exe, because some Unix tools ported onto Cygwin only support the Unix format.

When you launch a Cygwin shell, your existing PATH variable is translated from the Windows format to the Unix format, and the ';' separators in the Windows PATH are changed into ':' separators as required by Unix. A Cygwin tool (e.g. Cygwin Perl or Cygwin RCS) will always use the Unix PATH format, and will accept Unix format pathnames.

The Apache environment

Apache runs as a native Windows process and has nothing to do with Cygwin (at least the version used in this cookbook doesn't). Hence it supports c:/ pathnames in its config files and the first line of Perl CGI scripts.

If you need to use spaces in file names (not recommended), put double quotes around the file name in the httpd.conf file. There have been some security-related bugs in Apache with long pathnames, which are a bit more likely if you use spaces, so it's best to just avoid long names and using spaces.

The Perl environment

Once Perl has been launched by Apache, it is in Cygwin mode, and so is everything it launches, including ls, egrep, and the RCS tools that it (typically) launches with the bash shell.

You cannot use spaces in file names.

Installing Components

Enough background, let's get on with the installation.

Before we start, it's worth highlighting that:

  • When working with Apache, Cygwin and Cygwin Perl, you should use UNIX format paths i.e. forward slashes. For example, c:/twiki/pub
  • Other perl implementations, such as Active State Perl, may have other requirements, though in most cases forward slashes are likely to work best.

Install Apache

Apache 1.3.x is recommended. Apache 2 really doesn't work very well on the Windows platform.

The first couple of steps can be shortcut by opening the self-installing executable on the Apache website that installs Apache 1.3.x. The painful details below are mainly helpful when detecting where things are going wrong.

Download Apache

  • Check at http://httpd.apache.org/ for any security announcements
  • Check the latest 1.3.x version number on this page
  • Find a local mirror using http://www.apache.org/dyn/closer.cgi - choose httpd, then binaries, then win32
  • The file to download is apache_1.3.X-win32-x86-no_src.msi where 'X' is 20 or higher
    • Note that this is a Microsoft Installer format file (.MSI)

  • NOTE: If you are using Windows NT, download the .MSI installer (instmsi.exe) from the Apache Win32 download page - this enables you to install .MSI files. You may need to update the .MSI Installer if you have an old version under NT.
  • NOTE: The Apache package itself requires a download of around 2 MB, and up to 10 MB of free disk space once installed

Install Apache

  • Double-click the .MSI file to run the installer
  • Specify c:\ as the installation directory - this actually installs Apache into c:\apache (if you specify c:\apache, it installs into c:\apache\Apache). Putting Apache into c:\Program Files is not recommended for easy editing of Apache config files from Cygwin.
  • On Windows NT/2000/XP you can choose to run Apache as a service or as a normal program - see the Apache docs for details.

Test Apache

  • If necessary, start apache, by selecting 'Start' from the 'Start->Programs->Apache...->Control Apache Server' menu.
  • Point your browser at http://yourdomain.com/ to see the Apache intro page.

Congratulations, you now have a working web server!

To restart Apache after changing its config, type:

  • apache -k restart for standalone Apache process running in another window
  • apache -k restart -n apache for Apache running as a Win2000 service (-n gives name of service)

Another useful command is apache -k stop.

Install Cygwin

Head to http://cygwin.com, and click the cygwin-icon.gif Install or update now! link. Save the setup.exe in a directory, e.g. c:\download\cygwin-dist.

Now run the Cygwin setup.exe file - this will also install Perl and RCS in one fell swoop.

  • Choose Internet install
  • On first page, accept the defaults (be sure that the default text file type is Unix to avoid problems with attachment uploads, and specify 'install for all users')
  • Select c:\download\cygwin-dist as the local package directory, and suitable proxy settings, then pick a local mirror site
  • In the package list screen, hit the View button until you get an alphabetical list that says Full to the right of the button.
  • Leave the radio button on Curr (Current)
    • The Current column shows what's installed on your system (if anything)
  • For each package, make sure the New column in the installer has a version number under it. If it says 'Skip' or 'Keep' (meaning it's already installed), single-click that word until a version number is shown.
  • Make sure you select the following packages - :
    • bash
    • binutils
    • diffutils
    • gcc
    • grep
    • gzip
    • make
    • nano (or vim if you prefer the vi editor)
    • ncftp
    • pcre
    • perl (5.8.5-3 or higher)
    • rcs (5.7-3 or higher)
    • tar
    • textutils
    • unzip
    • w32api
    • wget (optional, useful for Perl install and TWiki:Codev.ReadWriteOfflineWiki)
    • NOTE: Do not include lynx if you are upgrading from an older Cygwin installation (to avoid annoying DLL messages) - if you want Lynx, read the Cygwin FAQ entry and upgrade libncurses5.
  • Hit Next to do the installation.
    • NOTE: The mandatory packages require a download of about 12 MB - about half of this is Perl, which would be necessary even without Cygwin, and most of the rest is gcc, which is required for simple installation of Perl modules that use the C language. A default installation of Cygwin 1.5.10, plus required packages, needs around 150 MB of free disk space - if you are tight on disk space or Internet bandwidth, de-select all but the mandatory packages, but if not, there is no harm in downloading more.
    • NOTE: The installer keeps a local copy of downloaded files, so it's easy to re-install without re-downloading.
  • Let the installer create the shortcuts suggested
  • You can always come back and re-run the installer again later if you missed anything.

Environment setup:

  • Set the HOME environment variable to c:\cygwin\home\YOURUSER, where YOURUSER is your userid, e.g. jsmith or administrator.
    • On Windows NT, XP and 2000: Go into Control Panel, double-click the System icon, and select Advanced, then click Environment Variables. Under User Variables, click New.... Now type HOME (must be upper case) as the variable name, and c:\cygwin\home\YOURUSER as the value, and hit OK.
    • On Windows 98 and ME - add to BAT and reboot
  • You can also set TEMP to c:\temp at this point, if you prefer this to editing the Cygwin ~/.profile file. (HOME can't be set in the ~/.profile file.)
  • Create the c:\cygwin\home\YOURUSER directory

Test Cygwin

  • Launch the desktop icon - this runs the bash shell, which has command line editing features
    • Use the cursor up key to recall previous commands - normal PC editing keys can then be used to edit a command
    • TIP: When typing a directory or file name, hit the TAB key after the first few letters of the name - bash will 'complete' the name. If bash beeps at you, hit TAB again to see the files/directories that match the name so far, and type a bit more before hitting TAB. This saves a lot of time!
  • Type rcs -V - you should see the RCS version, 5.7
  • Type perl -v - you should see cygwin mentioned in the first line, and the Perl version, 5.6.1
  • Type grep home /etc/passwd - you should see some output.

The Cygwin User Guide is well worth reading for some background on how Cygwin works.

Configure Cygwin for binary mode

  • This is very important - omitting this step leads to a partially working system that corrupts RCS files - without this, Cygwin tools (including Perl and RCS) will add unwanted carriage returns (Ctrl/M, '\r') to files in an attempt to translate between the Windows and Unix text file formats (Unix text files only use line feeds ('\n').
    • This has been a great time sink, causing numerous subtle problems - see TWiki:Codev.CookbookLineEndingProblems
  • Stay in the Cygwin (bash) shell, and type the following (use only forward slashes, i.e. '/'): 
   $ mkdir /twiki /c c:/twiki
   $ mount -b -s c:/twiki /twiki
   $ mount -b -s c:/ /c
   $ mount -b -c /cygdrive
   $ mount
   Device              Directory           Type         Flags
   C:\cygwin\bin       /usr/bin            system       binmode
   C:\cygwin\lib       /usr/lib            system       binmode
   C:\cygwin           /                   system       binmode
   c:\twiki            /twiki              system       binmode
   c:                  /c                  system       binmode
  • This configures /twiki (known as a 'mount point') to map onto c:/twiki and for that directory tree to always be in binary mode, and does the same for /c, mapping it onto c:/. The last-but-one command sets binary as the default for any unmounted drives (e.g. z:/, aka /cygdrive/z).
  • It is very important that all lines in the output of mount say 'binmode' under Flags
    • If the lines for C:\cygwin directories do not, you should uninstall and then re-install Cygwin to ensure that binary attachment uploads will work.
  • You can now refer to files using Unix paths, e.g. /twiki/bin/view or /c/apache/Announcement - see the Cygwin documentation for more details on this.
  • Now test this, still using the Cygwin shell:
    • Type cd /twiki
    • Type echo hi >t
    • Type cat -v t - you should see hi as the output
    • If you see filename errors, your mounts did not work for some reason - check your typing
    • If you see hi^M as output, your /twiki directory is not in binary mode
    • Clean up by doing rm t

This setup is written to the Windows registry, so there's no need to put these commands into a .profile file. For more information on binary vs text mode, see this User Guide section and this FAQ entry.

Configure Apache

The setup given here is fairly simple, in that it allows only TWiki to be served by the web server. For more complex setups, you can investigate the Alias and ScriptAlias commands that are left commented out in this configuration.

Using a suitable text editor (see #TextEditing, above) edit c:/apache/conf/httpd.conf as follows - this tells Apache where TWiki lives, and removes the need to tinker with the Windows environment settings.

  • Note the trailing '/' characters in various places - they are important!

  • Create the c:\temp directory, by typing mkdir c:\temp in a DOS command line window
  • Edit the following lines, some of which already exist in the file:

  • Add the following lines - the Alias and ScriptAlias lines can be omitted in this setup

Add an AddHandler line to the <IfModule mod_mime.c> section of httpd.conf - this removes the need to rename all the TWiki CGI scripts later in the installation.

  • Note the trailing '.' on the AddHandler line.

Configure Cygwin

Open the windows explorer, right click your cygwin directory (c:/path/to/cygwin) and choose "Properties". Select the "Security" flag and set the permissions as follows:

  1. uncheck 'inherit permissions', slap the 'copy existing' button when prompted
  2. for the 'Everyone' group, uncheck Write access and Full Control
  3. Add the groups CREATOR OWNER, SYSTEM and give them Full Control
  4. Add the users Administrator, Your_Name and give them Full Control

Install Perl modules

Some additional Perl modules are needed, above and beyond the standard modules installed with Cygwin. Fortunately, there is an automated tool that makes it easy to do this - it's called cpan, and goes to the Perl module archive site, http://www.cpan.org/, to download all required modules, and then build and install them.

Note: if you are unable to get cpan working in your environment, don't panic; you can still install the modules manually. In this case, follow the instructions in CPAN: The Manual Way.

First of all, you need to get the cpan tool configured and working - this is only necessary once. From the Cygwin shell, type the following (putting the export command in ~/.profile is recommended to make this setting persistent). Without the TEMP variable, some modules may fail to install on Windows 2000 or XP and higher. 

$ export TEMP=/c/temp
$ cpan
Lots of questions about configuration and preferences - just hit Enter until you get to the questions about mirror sites, but answer the questions about FTP proxies etc if you are behind a proxy-based firewall. The CPAN tool will fetch a series of files, some quite large, as part of this setup process, so be patient...

NOTE: If you are behind a non-proxy-based firewall that requires the use of passive FTP, the initial downloads of files using Net::FTP may appear to hang - just wait 5 or more minutes, however, and the CPAN tool should eventually hit on ncftpget, which is part of Cygwin and does work OK. If this doesn't work and you are behind a typical NAT-based firewall, try doing the following at the Cygwin shell before running cpan - this forces Net::FTP to use passive FTP, letting it get through such firewalls: 

$ export FTP_PASSIVE=1
If this works, add this line to your ~/.profile file for future use.

Once some initial files are downloaded, you are asked to select your continent and country, and then mirror sites - just type the number of the mirror sites you want to use (pick a few in case one is down): 

...
(28) Turkey
(29) Ukraine
(30) United Kingdom

Select your country (or several nearby countries) [] 30

(1) ftp://cpan.teleglobe.net/pub/CPAN
(2) ftp://ftp.clockerz.net/pub/CPAN/
(3) ftp://ftp.demon.co.uk/pub/CPAN/
(4) ftp://ftp.flirble.org/pub/languages/perl/CPAN/
(5) ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
(6) ftp://ftp.plig.org/pub/CPAN/
(7) ftp://mirror.uklinux.net/pub/CPAN/
(8) ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
(9) ftp://usit.shef.ac.uk/pub/packages/CPAN/
Select as many URLs as you like,
put them on one line, separated by blanks [] 4 7 8

Enter another URL or RETURN to quit: []
New set of picks:
  ftp://ftp.flirble.org/pub/languages/perl/CPAN/
  ftp://mirror.uklinux.net/pub/CPAN/
  ftp://sunsite.doc.ic.ac.uk/packages/CPAN/

Eventually, you'll get to the cpan installer's shell prompt, where you need to install a few modules - the tool will do all the work for you.

  • NOTE: You will need to have previously installed the Cygwin make and gcc packages, which are required by the CPAN installer (gcc is required for modules that include C language code) - you can install them now by launching Cygwin's setup.exe from c:/download/cygwin-dist (no need to exit the CPAN installer). 

cpan shell -- CPAN exploration and modules installation (v1.59_54)
cpan> install Net::SMTP
May already be installed - if it is, try 'force install', since it's useful to be able to set
firewall and passive FTP configuration when using Net::FTP.  Make sure you answer 'Y' to the question 
about whether you want to configure this package.
cpan> install Digest::SHA1
Lots of output about how CPAN finds, builds and installs the module - watch for 
any errors, though it should work fine if you have installed the Cygwin packages listed above (particularly 'gcc' and 'make').
cpan> install MIME::Base64
May already be installed.

CPAN: The Manual Way

If you find that cpan doesn't work for you, perhaps because you are behind an uncooperative corporate firewall, you may have to fall back on installing modules manually. In this case, you need to read the CPAN INSTALL page and visit the CPAN search site to search for each module you require. Usually installation simply involves downloading the module distribution into a temporary directory and unpacking it (a .tar.gz or .tgz file is unpacked using tar zxvf file). Then do the following: The make test step should not be skipped - for example, one known problem is with the Digest::SHA1 module on Windows NT, which does not pass its tests and does not work. This causes problems with password encoding. In this event you can use another encoding scheme or switch to unencoded passwords. There may be other problems on the various Windows configurations, and you can save yourself a lot of time by running the tests.

Install TWiki

Finally you are ready to install TWiki! Do this by following the instructions in TWikiInstallationGuide. The webserver should already be configured to run configure, but before you do so you will have to edit the "shebang" lines in the scripts in bin. This is required so the Apache server knows what interpreter (perl) to use with the scripts.
  • You must use the Cygwin shell to do this (unless you are a Perl expert) - don't use the Windows command shell, cmd.exe (aka DOS Prompt)
  • Then do the following, which quickly edits the 19 or so files, using Perl - the important lines are in bold.
  • Type the Perl line very carefully 

$ cd /twiki/bin

$ ls
attach   geturl         oops     rdiff     save        testenv  viewfile
changes  installpasswd  passwd   register  search      upload
edit     mailnotify     preview  rename    statistics  view

$ mkdir .backup 
$ cp * .backup

$ head -1 view
#!/usr/bin/perl -wT

$ perl -pi~ -e 's;#!/usr/bin/perl;#!c:/cygwin/bin/perl;' *[a-z]

$ head -1 view
#!c:/cygwin/bin/perl -wT

$ ls
attach    geturl          oops      rdiff      save         testenv   viewfile~
attach~   geturl~         oops~     rdiff~     save~        testenv~  view~
changes   installpasswd   passwd    register   search       upload
changes~  installpasswd~  passwd~   register~  search~      upload~
edit      mailnotify      preview   rename     statistics   view
edit~     mailnotify~     preview~  rename~    statistics~  viewfile
Note also that to set file permissions you have to use the cygwin 'chmod' command; for example,

Testing your TWiki installation

It is important to test your TWiki installation before you release it to other users or put any significant data into it.

Here are the main things to test:

  • Page viewing (view script) - click around a few pages and make sure the links are OK
  • RCS diffs (rdiff script) - click on the Diffs link and on the '>' links at bottom of page
  • Edit a page, and register as a new user - tests page creation, use of register script to create a new user entry in /twiki/data/.htpasswd (the Apache password file), ability to send email via Net::SMTP, and whether SMTPMAILHOST was set correctly in TWikiPreferences (if it is unset it will not use Net::SMTP and will almost inevitably fail silently).
    • If you get a failure to register or send email, check the Apache error log, and that all CPAN modules were installed correctly in Step 6, Installing required Perl modules.
    • Try typing tail -30 /c/apache/logs/error_log to see last 30 errors from Apache
  • Edit a page - check revision increased and set to current date/time
  • Edit the same page using another browser or PC, logging in as a different user - check there's a lock message (which you can override) and no double lines
  • Check the Apache error_log file to see if there are any RCS errors so far
  • Index - tests whether ls and grep are working
  • Search - more tests for whether ls and grep are working
  • Attachments - tests access to /twiki/pub directory.
    • Try a binary attachment upload and check the number of bytes in the file has not changed - if it has, see the Install Cygwin section's note on the default text file type.
  • Check the Apache error_log file again

Troubleshooting

If anything doesn't work, go back and check the configuration of the Apache httpd.conf file, and configure. Have a look at the Apache error log, c:/apache/logs/error_log, and the TWiki error log, /twiki/data/log*.txt, and if necessary enable debugging on selected scripts (the commands are right at the top of each script) - the results go into /twiki/data/debug.txt. There is also a /twiki/data/warning.txt file that contains less serious messages.

See TWiki:Codev.TWikiPatches in case there are patches (i.e. specific code changes) for particular problems that may affect you (e.g. TWiki:Codev.ChangePasswordOnWin2K).

If you find that the Index feature doesn't work, or topic name searches fail, you should check you have set $egrepCmd and $fgrepCmd correctly, as mentioned above.

Permissions

TWiki:Codev.CygWin has several models for how it does security:

  • By default, it only implements the Unix 'write' and 'execute' permissions bits - the former is controlled by the Windows Read-Only attribute, while the latter is automatically assigned to files named *.exe or *.com, and to files whose first line is a shebang (i.e. #!/bin/something). This is what has been used for this cookbook.
  • You can enable the 'ntea' or 'ntsec' models, which will increase security but are also likely to introduce permission problems.

I have not had any problems with TWiki permissions on Windows, unlike Linux/Unix, which is probably because I'm using the default security model for Cygwin. If you use the other models, you may still be OK if you have local admin rights, and Apache is running as the SYSTEM user (which it uses if started as a service). If you do have trouble in this area, see the TWikiInstallationGuide's advice, some of which will apply to TWiki:Codev.CygWin, and log any issues in TWiki:Codev.WindowsInstallCookbookComments.

Next Steps

See the TWikiInstallationGuide for other setup. In particular, you'll probably want to refer to the section on basic authentication - remember to use c:/twiki type filenames (i.e. Windows format) since you are using Apache for Windows.

Improved authentication

You may want to investigate TWiki:Codev.WindowsInstallModNTLM, which describes how to add an Apache module so that TWiki:Codev.InternetExplorer users are automatically authenticated based on their Windows domain login - this avoids TWiki:Codev.GettingTheUsernameWrong and TWiki:Codev.ForgettingPasswords, which are usually very common among TWiki users.

As of the TWiki:Codev.TWikiRelease01Sep2004, there is built in support for several apache based authentication modes. The TWikiInstallationGuide has step-by-step instructions.

Improved performance

See TWiki:Codev.WindowsModPerlInstallCookbook and TWiki:Codev.ModPerl for information on installing TWiki under Apache's mod_perl - this is somewhat more complex and follows a different model, so it's best to get some experience with TWiki, Apache and Perl first.

TWiki Upgrade Guide

Upgrade from the previous TWiki 01-Feb-2003 production release to TWiki 01-Sep-2004

Overview

This guide describes how to upgrade from TWiki 01-Feb-2003 to TWiki 01-Sep-2004. This is a major new release. You can chose between an automated upgrade using a script or a manual update.

Upgrade Requirements

  • Please review the AdminSkillsAssumptions before you upgrade TWiki
  • To upgrade from a 01-Feb-2003 standard installation to the latest 01-Sep-2004 TWiki Production Release, follow the instructions below
  • NOTE: To upgrade from a pre-01-Feb-2003 TWiki, start with TWikiUpgradeTo01Feb2003
  • To upgrade from a Beta of the new release, or if you made custom modifications to the application, read through all new reference documentation, then use the procedure below as a guideline

Major Changes Compared to TWiki 01-Feb-2003

  • Automatic upgrade script, and easier first-time installation
  • Attractive new skins, using a standard set of CSS classes, and a TWikiSkinBrowser to help you choose
  • New easier-to-use save options
  • Many improvements to SEARCH
  • Improved support for internationalisation
  • Better topic management screens
  • More pre-installed Plugins: CommentPlugin, EditTablePlugin? , RenderListPlugin? , SlideShowPlugin? , SmiliesPlugin? , SpreadSheetPlugin? , TablePlugin?
  • Improved Plugins API and more Plugin callbacks
  • Better support for different authentication methods
  • Many user interface and usability improvements
  • And many more enhancements, see the complete change log at TWikiHistory

Automated Upgrade Procedure from 01-Feb-2003 to 01-Sep-2004 Release

With the 01-Sep-2004 Release, for the first time, comes a helper script for upgrading from a previous version. This feature is currently at beta stage, it has only been sanity tested under Unix. It should be worth giving it a try, it won't mess up your existing TWiki installation because it leaves that untouched.

If you would prefer to do things manually than trust a beta script, skip to the manual upgrade procedure below.

The upgrade script is called "UpgradeTwiki", and is found in the root of the distribution.

It will:

  • Create a new TWiki installation, placing the files from the distribution there as appropriate
  • Where possible, merge the changes you've made in your existing topics into the new twiki
  • Where not possible, it will tell you, and you can inspect those differences manually
  • Create new configuration files for the new TWiki based on your existing configuation information
  • Set the permissions in the new TWiki so that it should work straight away
  • Attempt to setup authentication for your new TWiki, if you are using .htaccess in the old one
  • Tell you what else you need to do

To perform the upgrade, you need to:

  • Check first if there is a newer UpgradeTwiki script available, see TWiki:Codev.UpgradeTwiki
  • Create a new directory for your new installation: Let's call this distro/
  • Put the distribution zip file in distro/
  • Unzip it
  • Choose a directory for the new installation. I will call this new_twiki. This directory must not already exist.
  • Change directory to distro/ and run:
    ./UpgradeTwiki <full path to new_twiki>

Assuming all goes well, UpgradeTwiki will give you the final instructions.

There are a few points worth noting:

  • UpgradeTwiki may not be able to merge all the changes you made in your existing TWiki into the new installation, but it will tell you which ones it couldn't deal with
  • UpgradeTwiki creates the new installation in a new directory tree. It makes a complete copy of all your existing data, so:
    • Clearly you need to point it to a location where there is enough space
    • If you have symlinks under your data/ directory in your existing installation, these are reproduced as actual directories in the new structure. It is up to you to pull these sub-directories out again and re-symlink as needed
  • UpgradeTwiki doesn't deal with custom templates or Plugins, you will have to reinstall these in the new installation.

If you use it, and would be kind enough to add your experiences to TWiki:Codev.UpgradeTwiki, it would be much appreciated. The report of your experience will help to make UpgradeTwiki more robust.

Manual Upgrade Procedure from 01-Feb-2003 to 01-Sep-2004 Release

The following steps describe the upgrade assuming that $TWIKIROOT is the root of your current 01-Feb-2003 release. As written this will require some downtime. A process for switching over without downtime is described at the end of this section.

  1. Back up and prepare:
    • Back up all existing TWiki directories $TWIKIROOT/bin, $TWIKIROOT/pub, $TWIKIROOT/data, $TWIKIROOT/templates, $TWIKIROOT/lib
    • Create a temporary directory and unpack the ZIP file there
  2. Update files in TWiki root:
    • Overwrite all *.html and *.txt files in $TWIKIROOT with the new ones
  3. Update template files:
    • Overwrite all template files in $TWIKIROOT/templates with the new ones
      • If you have customized your templates, make sure to merge those changes back to the new files
    • If you have customized skins or loaded new skins, make sure to merge or apply those changes to the new files
    • Change to view templates and skins:
      • Add %BROADCASTMESSAGE% somewhere on the top of the rendered HTML page (see the new view.tmpl for reference)
    • Changes to edit templates and skins:
      • Change the form action from preview to save:
        <form name="main" action="%SCRIPTURLPATH%/save%SCRIPTSUFFIX%/%WEB%/%TOPIC%" method="post">
      • Change the topic action to the following:
        %TMPL:DEF{"topicaction"}%
<input type="submit" class="twikiSubmit" name="action" value="Cancel" id="cancel" />
<input type="submit" class="twikiSubmit" name="action" value="Preview" id="preview" />
<input type="submit" class="twikiSubmit" name="action" value="Checkpoint" id="checkpoint" />
<input type="submit" class="twikiSubmit" name="action" value="QuietSave" id="quietsave" />
<input type="submit" class="twikiSubmit" name="action" value="Save" id="save" />%TMPL:END%
  1. Update script files:
    • Overwrite all script files in $TWIKIROOT/bin with the new ones.
      • If necessary, rename the scrips to include the required extension, e.g. .cgi
    • Edit $TWIKIROOT/bin/setlib.cfg and point $twikiLibPath to the absolute file path of $TWIKIROOT/lib
    • Edit your existing $TWIKIROOT/bin/.htaccess file to include a directive for the new rdiffauth script:
      <Files "rdiffauth">
          require valid-user
      </Files>
    • Pay attention to the file and directory permissions, the scripts need to be executable, e.g. chmod 775 $TWIKIROOT/bin/*
      • Certain hosted environments require a 755 (do so if you get a "Premature end of script headers" messages in the Apache error log)
    • For Windows hosts, make sure the correct path to the perl interpreter is changed in the first line of every script file. See also WindowsInstallCookbook
  2. Update library files:
    • Overwrite the TWiki.cfg configuration file in $TWIKIROOT/lib with the new one
    • Add the unique local configuration values from the backup. You can do this manually if you have to, but you are highly recommended to use the http://www.socialscience-ed.org/pages/bin/configure interface. If you choose to do it manually, add the local settings to LocalSite.cfg and not to TWiki.cfg. Do not edit the new TWiki.cfg.
    • Overwrite the TWiki.pm library in $TWIKIROOT/lib with the new one
    • Copy and overwrite all subdirectories below $TWIKIROOT/lib with the new ones. Make sure to preserve any extra Plugins you might have in $TWIKIROOT/lib/TWiki/Plugins
  3. Update data files:
    • In the temporary twiki/data/TWiki directory where you unzipped the installation package:
      • Remove the files you do not want to upgrade: InterWikis.*, TWikiRegistration.*, TWikiRegistrationPub.*, WebPreferences.*, WebStatistics.* and all WebTopic* files
    • Rename in the temporary directory the file $TWIKIROOT/data/TWiki/TWikiPreferences.* to TWikiPreferencesSave.*.
    • Move all remaining *.txt and *.txt,v files from the temporary data/TWiki directory to your $TWIKIROOT/data/TWiki directory, overwriting the existing ones
    • Merge your original TWikiPreferencesSave.txt settings into $TWIKIROOT/data/TWiki/TWikiPreferences.txt. Notable changes are:
      • New WIKIWEBMASTERNAME setting to avoid notifications being trapped by spam filters
      • New ATTACHFILESIZELIMIT setting for maximum size of FileAttachments in KB, 0 for no limit
      • New READTOPICPREFS and TOPICOVERRIDESUSER settings to allow override Preference settings in topics
      • Changed FINALPREFERENCES:
        • Set FINALPREFERENCES = PREVIEWBGIMAGE, WIKITOOLNAME, WIKIWEBMASTER, SMTPMAILHOST, SMTPSENDERHOST, ALLOWWEBMANAGE, READTOPICPREFS, TOPICOVERRIDESUSER
    • Move the data/_default directory from the temporary location to your $TWIKIROOT/data directory
    • Make sure that the directories and files below $TWIKIROOT/data are writable by your cgi-script user
  4. Adapt the other webs (all other than TWiki and _default):
    • Add WebLeftBar topic. See WebLeftBarExample for a clean example, and WebLeftBarCookbook for more information. (WebLeftBar is used by the PatternSkin skin)
    • Add WebSearchAdvanced topic, which has this one line:
      %INCLUDE{"%TWIKIWEB%.WebSearchAdvanced"}%
    • Consider changing WebPreferences settings:
      • New NOAUTOLINK setting to prevent automatic linking of WikiWords and acronyms
      • Changed FINALPREFERENCES:
        • Set FINALPREFERENCES = NOSEARCHALL, ATTACHFILESIZELIMIT, WIKIWEBMASTER, WEBCOPYRIGHT, WEBTOPICLIST, DENYWEBVIEW, ALLOWWEBVIEW, DENYWEBCHANGE, ALLOWWEBCHANGE, DENYWEBRENAME, ALLOWWEBRENAME
  5. Update pub files:
    • Move all subdirectories below pub/TWiki from your temporary directory into your $TWIKIROOT/pub/TWiki directory
    • Make sure that the directories and files below $TWIKIROOT/pub/TWiki are writable by your cgi-script user
    • Move all files in pub/icn directory from the temporary location to your $TWIKIROOT/pub/icn directory
  6. Verify installation:
    • Execute the $TWIKIROOT/bin/configure script from your browser (e.g. http://localhost/bin/configure) to see if it reports any issues; address any potential problems
    • Test your updated TWiki installation to see if you can view, create, edit and rename topics; upload and move attachments; register users
    • Test if the installed Plugins work as expected. You should see the list of installed Plugins in TWiki.WebHome

Note: These steps assume a downtime during the time of upgrade. You could install the new version in parallel to the existing one and switch over in an instant without affecting the users. As a guideline, install the new version into $TWIKIROOT/bin1, $TWIKIROOT/lib1, $TWIKIROOT/templates1, $TWIKIROOT/data/TWiki1 (from data/TWiki), $TWIKIROOT/pub/TWiki1 (from pub/TWiki), and configure LocalSite.cfg to point to the same data and pub directory like the existing installation. Once tested and ready to go, reconfigure $TWIKIROOT/bin1/setlib.cfg and $TWIKIROOT/lib1/LocalSite.cfg, then rename $TWIKIROOT/bin to $TWIKIROOT/bin2, $TWIKIROOT/bin1 to $TWIKIROOT/bin. Do the same with the lib, templates and data/TWiki directories.

Known Issues

  • Check TWiki:Codev/KnownIssuesOfTWiki01Sep2004 for known issues of TWiki 01-Sep-2004 production release

TWiki User Authentication

TWiki site access control and user activity tracking options

Authentication, or "login", is the process by which a user lets TWiki know who they are.

Authentication isn't just to do with access control. TWiki uses authentication to identify users, and uses those identities to keep track of who made changes, and manage a wide range of personal settings. With authentication enabled, users can personalise their environment and contribute as recognised individuals, instead of anonymous shadows.

TWiki authentication is extremely flexible, and can either stand alone or integrate with existing authentication schemes. You can set up TWiki to require authentication for every access, or set it up to require authentication only for changes. Authentication is also essential for effective access control.

Quick Authentication Test - Use the %WIKIUSERNAME% variable to return your current identity:

TWiki supports three default authentication schemes: no authentication, Template Login, and Apache Login. You can select your chosen authentication option through the Security Settings pane in the configure interface.

If you want users to log in, Template Login is the recommended way. Apache Login isn't as flexible, but historically it's been an option so it's still provided in case you want to use it.

No Login

Does exactly what it says on the tin. Forget about authentication to make your site completely public - anyone can browse and edit freely, in classic Wiki style. All visitors are given the TWikiGuest default identity, so you can't track individual user activity.

Template Login

If a user tries to access protected content (either views a topic with access restrictions, or attempts a protected operation such as edit) they are redirected to a "login" page.

Template Login uses a TWiki template to ask for a username and password in a web page, and process them using whatever Password Manager you choose (also in the security section of the configuration page).

Enabling Template Login

  1. Use the configure interface to enable the TemplateLogin login manager (on the Security Settings pane).
  2. Select the appropriate password manager for your system, or provide your own.
  3. In TWiki, edit the TWikiRegistrationPub topic, copy the contents, then edit TWikiRegistration and paste, deleting the old contents and replacing them with the contents of TWikiRegistrationPub.
    You can customize the registration form by deleting or adding input tags. The name="" parameter of the input tags must start with: "Twk0..." (if this is an optional entry), or "Twk1..." (if this is a required entry). This ensures that the fields are carried over into the user home page correctly.
    You can customize the default user home page in NewUserTemplate. The same variables get expanded as in the template topics
  4. Register yourself in the TWikiRegistration topic.
    help Check that a new line with the username and encrypted password is added to the .htpasswd file. If not, you may have got a path wrong, or the permissions may not allow the webserver user to write to that file.
  5. Create a new topic to check if authentication works.
  6. Edit the TWikiAdminGroup topic in the TWiki:SSECHome web to include users with system administrator status.
    warning This is a very important step, as users in this group can access all topics, independent of TWiki access controls.
TWikiAccessControl has more information on setting up access controls.

warning At this time TWikiAccessControls cannot control access to files in the pub area, unless they are only accessed through the viewfile script. If your pub directory is set up in the webserver to allow open access you may want to add .htaccess files in there to restrict access.

Apache Login

Using this method TWiki does not authenticate users internally. Instead it depends on the REMOTE_USER environment variable, which is set when you enable authentication in the webserver.

The advantage of this scheme is that if you have an existing website authentication scheme using Apache modules such as mod_auth_ldap or mod_auth_mysql you can just plug in directly to them.

TWiki maps the REMOTE_USER that was used to log in to the webserver to a WikiName using the table in TWikiUsers. This table is updated whenever a user registers, so users can choose not to register (in which case their webserver login name is used for their signature) or register (in which case that login name is mapped to their WikiName).

The same private .htpasswd file used in TWiki Template Login can be used to authenticate Apache users, using the Apache Basic Authentication support. This allows the TWiki registration support to maintain usernames and passwords.

Enabling Apache Login using mod_auth

You can also use any other Apache authentication module that sets REMOTE_USER
  1. Use configure to select the ApacheLogin login manager.
  2. Use configure to set up TWiki to create the right kind of .htpasswd entries.
  3. Create a .htaccess file in the twiki/bin directory.
    help There is an template for this file in twiki/bin/.htaccess.txt that you can copy and change. The comments in the file explain what need to be done.
    help If you got it right, the browser should now ask for login name and password when you click on the Edit. If .htaccess does not have the desired effect, you may need to "AllowOverride All" for the directory in httpd.conf (if you have root access; otherwise, email web server support)
    warning At this time TWikiAccessControls do not control access to files in the pub area, unless they are only accessed through the viewfile script. If your pub directory is set up to allow open access you may want to add .htaccess files in there as well to restrict access
  4. In TWiki, edit the TWikiRegistrationPub topic, copy the contents, then edit TWikiRegistration and paste, deleting the old contents and replacing them with the contents of TWikiRegistrationPub.
    You can customize the registration form by deleting or adding input tags. The name="" parameter of the input tags must start with: "Twk0..." (if this is an optional entry), or "Twk1..." (if this is a required entry). This ensures that the fields are carried over into the user home page correctly.
    You can customize the default user home page in NewUserTemplate. The same variables get expanded as in the template topics
  5. Register yourself in the TWikiRegistration topic.
    help Check that a new line with the username and encrypted password is added to the .htpasswd file. If not, you may have got a path wrong, or the permissions may not allow the webserver user to write to that file.
  6. Create a new topic to check if authentication works.
  7. Edit the TWikiAdminGroup topic in the TWiki:SSECHome web to include users with system administrator status.
    warning This is a very important step, as users in this group can access all topics, independent of TWiki access controls.
TWikiAccessControl has more information on setting up access controls.

Logons via bin/logon

Any time a user enters a page that needs authentication, they will be forced to log on. However, if you're using Apache Login, then if a user never has a need to authenticate, they may never log on and never retrieve their personal settings. It may be convenient to force then to log on.

The bin/logon script accomplishes this. The bin/logon script must be setup in the bin/.htaccess file to be a script which requires a valid user to authenticate. However, once authenticated, it will simply redirect the user to the view URL for the page from which logon was linked.

Sessions

TWiki uses the CPAN:CGI::Session and CPAN:CGI::Cookie modules to track sessions using cookies. These modules are de facto standards for session management among Perl programmers. If you can't use Cookies for any reason, CPAN:CGI::Session also supports session tracking using IP matching. However this is inherently insecure and you are strongly advised against it.

There are a number of TWikiVariables available that you can use to interrogate your current session. You can even add your own session variables to the TWiki cookie. Session variables are referred to as "sticky" variables.

Getting, Setting, and Clearing Session Variables

You can get, set, and clear session variables from within TWiki web pages or by using script parameters. This allows you to use the session as a personal "persistent memory space" that is not lost until the web browser is closed. Also note that if a session variable has the same name as a TWiki preference, the session variables value takes precedence over the TWiki preference. This allows for per-session preferences.

To make use of these features, use the tags:

The session variables can also be set and cleared via CGI variables (include more than one in the string if necessary, separated by commas, as demonstrated here):

set_session_variable=" varName = varValue , varName = varValue , ... "
clear_session_variable=" varName , varName , ..."

That is, to set the session variable SKIN equal to "gnu" while clearing the session variable TEST, adding this to the end of a TWiki URL should work:

Cookies and Transparent Session IDs

TWiki normally uses cookies to store session information on a client computer. Cookies are a common way to pass session information from client to server. TWiki cookies simply hold a unique session identifier that is used to look up a database of session information on the TWiki server.

For a number of reasons, it may not be possible to use cookies. In this case, TWiki has a fallback mechanism; it will automatically rewrite every internal URL it sees on pages being generated to one that also passes session information.

TWiki Username vs. Login Username

This section applies only if you are using authentication with existing login names (i.e. mapping from login names to WikiNames).

TWiki internally manages two usernames: Login Username and TWiki Username.

  • Login Username: When you login to the intranet, you use your existing login username, ex: pthoeny. This name is normally passed to TWiki by the REMOTE_USER environment variable, and used internally. Login Usernames are maintained by your system administrator.

  • TWiki Username: Your name in WikiNotation, ex: PeterThoeny, is recorded when you register using TWikiRegistration; doing so also generates a personal home page in the SSECHome web.

TWiki can automatically map an Intranet (Login) Username to a TWiki Username, provided that the username pair exists in the TWikiUsers topic. This is also handled automatically when you register.

  • warning In the original TWiki distribution, in twiki/data, there are two registration form topics, TWikiRegistration and TWikiRegistrationPub. The original form includes an intranet Login Username field. For Basic Authentication, the original form is replaced by the Pub version. If you started using TWiki on Basic Authentication and want to change, you have to switch back forms for future use, and manually correct the existing entries, by editing TWikiUsers, adding the Login Username for each member - PeterThoeny - pthoeny - 01 Jan 1999 - and also in the .htpasswd file, where you can either replace the WikiNames or duplicate the entries and have both, so both usernames will work.

NOTE: To correctly enter a WikiName - your own or someone else's - be sure to include the SSECHome web name in front of the Wiki username, followed by a period, and no spaces. Ex:
SSECHome.WikiUsername or %MAINWEB%.WikiUsername
This points WikiUser to the SSECHome web, where user registration pages are stored, no matter which web it's entered in. Without the web prefix, the name appears as a NewTopic? everywhere but in the SSECHome web.

Changing Passwords

If your authentication method supports password changing, you can change and reset passwords using forms on regular pages.

TWiki Access Control

Restricting read and write access to topics and webs, by Users and groups

TWikiAccessControl allows you restrict access to single topics and entire webs, by individual user and by user Groups, in three areas: view; edit & attach; and rename/move/delete. Access control, combined with TWikiUserAuthentication, lets you easily create and manage an extremely flexible, fine-grained privilege system.

An Important Control Consideration

Open, freeform editing is the essence of WikiCulture - what makes TWiki different and often more effective than other collaboration tools. For that reason, it is strongly recommended that decisions to restrict read or write access to a web or a topic are made with care - the more restrictions, the less Wiki in the mix. Experience shows that unrestricted write access works very well because:

  • Peer influence is enough to ensure that only relevant content is posted.

  • Peer editing - the ability for anyone to rearrange all content on a page - keeps topics focussed.

  • In TWiki, content is transparently preserved under revision control:
    • Edits can be undone by the TWikiAdminGroup (the default administrators group; see #ManagingGroups).
    • Users are encouraged to edit and refactor (condense a long topic), since there's a safety net.

As a collaboration guideline:

  • Create broad-based Groups (for more and varied input), and...
  • Avoid creating view-only Users (if you can read it, you should be able to contribute to it).

Authentication vs. Access Control

Authentication: Identifies who a user is based on a login procedure. See TWikiUserAuthentication.

Access control: Restrict access to content based on users and groups once a user is identified.

Users and Groups

Access control is based on the familiar concept of Users and Groups. Users are defined by their WikiNames. They can then be organized in unlimited combinations by inclusion in one or more user Groups. For convenience, Groups can also be included in other Groups.

Managing Users

A user can create an account in TWikiRegistration. The following actions are performed: