<<O>>  Difference Topic TWikiDocumentation (r1.43 - 31 Jan 2003 - PeterThoeny)
Line: 1 to 1
Changed:
<
<
META TOPICINFO PeterThoeny date="1042701668" format="1.0" version="1.42"
>
>
META TOPICINFO PeterThoeny date="1043997325" format="1.0" version="1.43"

TWiki Reference Manual (07 May 2004)


TWiki Reference Manual (07 May 2004)

>
>
document.ondblclick=dblclick; -->

Changed:
<
<
This page contains all documentation topics as one long, complete reference sheet.
>
>
This page contains all documentation topics as one long, complete reference sheet.

Doubleclick anywhere to return to the top of the page.

TOC: No TOC in "TWiki.TWikiDocumentation"

Line: 22 to 25

TWiki Installation Guide

Installation instructions for the TWiki 01-Feb-2003 production release.

If you are reading this on your own TWiki installation, please get the latest installation guide (TWiki:TWiki.TWikiInstallationGuide), as this often has important updates to resolve installation issues.

These installation steps are based on the Apache web server on Linux. TWiki runs on other web servers and Unix systems, and should be fine with any web server and OS that meet the system requirements. Official documentation for platforms other than Linux is somewhat limited, so please check the topics listed below, they include some important tips for HP-UX, Solaris, OS/390, and many other platforms.

Standard Installation

Request and download the TWiki 01-Feb-2003 distribution in Unix ZIP format from http://TWiki.org/download.html. Please review the AdminSkillsAssumptions before you install TWiki.

Step 1: Create & Configure the Directories

ALERT! NOTE: If you don't have access to your Web server configuration files - for example, if you're installing on an ISP-hosted account, or you don't have administrator privileges on your intranet server - use the alternative Step 1 instead.

  • Create directory /home/httpd/twiki and unzip the TWiki distribution into this directory.
  • The twiki/bin directory of TWiki must be set as a cgi-bin directory. Add /home/httpd/twiki/bin to file httpd.conf (typcially located in /etc/httpd/) with only ExecCGI option.
  • The twiki/pub directory of TWiki must be set so that it is visible as a URL. Add /home/httpd/twiki to file httpd.conf with normal access options (copy from /home/httpd/html ).
  • Now add ScriptAlias for /twiki/bin and Alias for /twiki to file httpd.conf .
    ALERT! NOTE: The ScriptAlias must come before the Alias, otherwise, Apache will fail to correctly set up /twiki/bin/, by treating it as just another subdirectory of the /twiki/ alias.
  • The twiki/data and twiki/templates directories should be set so that they are not visible as URLs. Add them to httpd.conf with deny from all.

Example httpd.conf entries:
 ScriptAlias /twiki/bin/ "/home/httpd/twiki/bin/"
 Alias /twiki/ "/home/httpd/twiki/"
 <Directory "/home/httpd/twiki/bin">
    Options +ExecCGI
    SetHandler cgi-script
    Allow from all
 </Directory>
 <Directory "/home/httpd/twiki/pub">
    Options FollowSymLinks +Includes
    AllowOverride None
    Allow from all
 </Directory>
 <Directory "/home/httpd/twiki/data">
    deny from all
 </Directory>
 <Directory "/home/httpd/twiki/templates">
    deny from all
 </Directory>

  • Restart Apache by /etc/rc.d/rc5.d/S85httpd restart .
  • Test that the twiki/bin directory is CGI-enabled by trying visiting it in your browser:
    • Enter the URL for the bin directory, http://yourdomain.com/twiki/bin/.
    • Your settings are OK if you get a message like "Forbidden. You don't have permission to access /twiki/bin/ on this server".
    • Settings are NOT correct if you get something like "Index of /twiki/bin" - recheck your httpd.conf file.

Step 1 for Non-Root Accounts

To install TWiki on a system where you don't have Unix/Linux root (administrator) privileges, for example, on a hosted Web account or an intranet server administered by someone else:

  • Download and unzip TWiki on your local PC
  • Using the table below, create a directory structure on your host server
  • Upload the TWiki files by FTP (transfer as text except for the image files in pub)
TWiki dir: What it is: Where to copy: Example:
twiki start-up pages root TWiki dir /home/smith/twiki/
twiki/bin CGI bin CGI-enabled dir /home/smith/twiki/bin
twiki/lib library files same level as twiki/bin /home/smith/twiki/lib
twiki/pub public files htdoc enabled dir /home/smith/twiki/pub
twiki/data topic data dir secure from public access /home/smith/twiki/data
twiki/templates web templates dir secure from public access /home/smith/twiki/templates

If you are not able to create the twiki/lib directory at the same level as the twiki/bin directory (e.g. because CGI bin directories can't be under your home directory and you don't have root access), you can create this directory elsewhere and edit the setlib.cfg file in the bin directory:

    # -------------- Change these settings if required

    $twikiLibPath = '/some/other/path/lib';   # Path to lib directory containing TWiki.pm

You can also edit $localPerlLibPath in the setlib.cfg file if you are not root and need to install additional CPAN modules, but can't update the main Perl installation files on the server. Just set this variable to the full pathname to your local lib directory, typically under your home directory.

Step 2: Set File Permissions

  • 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 elsewhere, change the path to Perl in the first line of each script in the twiki/bin directory, or create a symbolic link from /usr/bin/perl.
    • IMPORTANT: On ISP-hosted accounts (and some intranet servers), Perl CGI scripts may require a .cgi extension to run. Some systems need .pl, the regular Perl extension. Rename all twiki/bin scripts if necessary.
  • Set the file permission of all Perl scripts in the twiki/bin directory as executable to -rwxr-xr-x (755).
  • To be able to edit the Perl scripts and .tmpl files it is necessary to chown and chgrp -R twiki so all the files have the owner you want.
  • HELP This Guide assumes user nobody ownership for all files manipulated by the CGI scripts (executed by the Web server), and user twiki for all other files. You can:
    • replace nobody with another user if your server executes scripts under a different name (ex: default for Debian is www-data).
      • TIP HINT: Run the testenv script from your browser: http://yourdomain.com/twiki/bin/testenv. It will show you the user name of the CGI scripts, a table listing all CGI environment variables, and a test of your twiki/lib/TWiki.cfg configuration file (you'll configure that in a minute).
    • replace user twiki with your own username
  • Set the permission of all files below twiki/data so that they are writable by user nobody. A simple way is to chmod them to -rw-rw-r-- (664) and to chown them to nobody.
  • Set the permission of the twiki/data directory and its subdirectories so that files in there are writable by user nobody. A simple way is to chmod them to drwxrwxr-x (775) and to chown them to nobody.
  • Set the permission of the twiki/pub directory and all its subdirectories so that files in there are writable by user nobody. A simple way is to chmod them to drwxrwxr-x (775) and to chown them to nobody.
  • HELP The twiki/data/*/*.txt,v RCS repository files in the installation package are locked by user nobody. If your CGI scripts are not running as user nobody, it's not possible to check in files (you'll see that the revision number won't increase after saving a topic). In this case, you need to unlock all repository files (check the RCS man pages) and lock them with a different user, such as www-data, or delete them all - new files will be automatically created the first time each topic is edited. A simple way to change ownership is with a search-and-replace in all files; for example, using Perl (type this carefully!):
cd twiki/data
perl -pi~ -e 'NR <= 10 && s/nobody:/www-data:/ ' */*,v

Step 3: Set the Main Configuration File

  • Edit the file twiki/lib/TWiki.cfg, setting the variables to your needs.
    • Set the file extension in the $scriptSuffix variable to cgi or pl if required.
    • RCS - revision control system to store revision of topics and attachments. You can use RCS executables or a version of RCS written in Perl, note that as the time of writing (Apr 2002) the Perl version has not been widely tested, so if you want to put up a live site the RCS executables are recommended.
      • Set $storeTopicImpl = "RcsWrap"; for the RCS executables and make sure RCS is installed. Set $rcsDir in twiki/lib/TWiki.cfg to match the location of your RCS binaries. You can check this by issuing the command rcs at the prompt, it should result in something like "rcs: no input file".
        • Check that you have GNU diff, by typing diff -v - an error indicates you have a non-GNU diff, so install the GNU diffutils package and make sure that diff is on the PATH used by TWiki (see $safeEnvPath in the TWiki.cfg file).
      • Set $storeTopicImpl = "RcsLite"; for the Perl based RCS
  • Security issue: Directories twiki/data , twiki/templates and all their subdirectories should be set so that they are not visible through URLs. (Alternatively, move the directories to a place where they are not visible, and change the variables in twiki/lib/TWiki.cfg accordingly)
  • Test your settings by running the testenv script from your browser: http://yourdomain.com/twiki/bin/testenv. Check if your twiki/lib/TWiki.cfg configuration file settings are correct.

Step 4: Configure Site-Wide Email Preferences

  • Edit the TWikiPreferences topic in the TWiki web (by pointing your browser to http://yourdomain.com/twiki/bin/view/TWiki/TWikiPreferences) to set the WIKIWEBMASTER email address, and other email settings required for registration and WebChangesAlert to work:
    • WIKIWEBMASTER should be set to the email address of the TWiki administrator
    • SMTPMAILHOST is typically set on Windows or other non-Unix/Linux systems, where sendmail or similar is not available. When this is set and the Perl module Net::SMTP is installed, TWiki will connect to this SMTP server (e.g. mail.yourdomain.com) to send email for user registration and WebChangesAlerts. If you do have a sendmail-type program, leave SMTPMAILHOST unset so that the external sendmail program is used instead (defined by $mailProgram in TWiki.cfg).
    • SMTPSENDERHOST is optional, and set to the domain name sending the email (e.g. twiki.yourdomain.com). For use where the SMTP server requires that you identify the TWiki server sending mail. If not set, Net::SMTP will guess it for you.
  • You may want to set up other TWikiPreferences later on.
  • To enable the WebChangesAlerts (email notifications) you need to read about cron in the topic TWikiSiteTools.

Step 5: Finish Up from Your Browser

  • Point your Web browser at http://yourdomain.com/twiki/bin/view and start TWiki-ing away!
    • TIP Or, point to http://yourdomain.com/twiki/ to get the pre-TWiki index.html page, with a link to the view script. Customize this page if you want a public intro screen with a login link, instead of immediately calling up the .htaccess login dialog by going directly to view.
  • Edit the WebPreferences topic in each web, if necessary: set individual WEBCOPYRIGHT messages, and other preferences.
  • Enable email notification of topic changes, TWikiSiteTools has more.
  • Edit the WebNotify topic in all webs and add the users you want to notify.
  • Add the TWiki:Main/PoweredByTWikiLogo to your Main.Home topic.
  • You can add new %VARIABLES%. Define site-level variables in the TWikiPreferences topic. See also: TWikiVariables.

That's it for the standard virgin installation of TWiki. Read on for server-level customization options.

Additional Server-Level Options

With your new TWiki installation up and running, you can manage most aspects of your site from the browser interface. Only a few functions require access to the server file system, via Telnet or FTP. You can make these server-level changes during installation, and at any time afterwards.

Enabling Authentication of Users

  • If TWiki is installed on a non-authenticated server - not using SSL - and you'd like to authenticate users:
    1. Rename file .htaccess.txt in the twiki/bin directory to .htaccess and change it to your needs. For details, consult the HTTP server documentation (for Apache server: [1], [2]). In particular, the following red part needs to be configured correctly:
      Redirect /urlpathto/twiki/index.html http://yourdomain.com/urlpathto/twiki/bin/view
      AuthUserFile /filepathto/twiki/data/.htpasswd
      ErrorDocument 401 /urlpathto/twiki/bin/oops/TWiki/TWikiRegistration?template=oopsauth
      • ALERT! NOTE: If you had to add a .cgi or .pl file extension to the bin scripts, make sure to do the same for edit, view, preview, and all the other script names in .htaccess.
      • HELP The browser should ask for login name and password when you click on the Edit link. In case .htaccess does not have the desired effect, you need to enable it: Add "AllowOverride All" to the Directory [3] section of access.conf for your twiki/bin directory.
        • This applies only if you have root access: on hosted accounts, you shouldn't have this problem - otherwise, email tech support.
      • ALERT! NOTE: In the TWiki distribution package, the twiki/data/.htpasswd.txt file contains several TWiki core team user accounts and a guest user account. You probably want to remove those accounts by deleting the entries in .htpasswd. Do not remove the guest user if you want to allow guest logins.
    2. Copy the TWikiRegistrationPub topic to TWikiRegistration, overwriting old version of TWikiRegistration. Do that by either editing the topics in theTWiki web, or by renaming the .txt and .txt,v files in the twiki/data/TWiki directory.
  • Customization:
    • 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.
  • Register yourself in the TWikiRegistration topic.
    • ALERT! NOTE: When a user registers, a new line with the username and encrypted password is added to the data/.htpasswd file. The .htpasswd file that comes with the TWiki installation includes user accounts for TWiki core team members that are used for testing on TWiki.org. You can edit the file and delete those lines.
  • Create a new topic to check if authentication works.
  • Edit the TWikiAdminGroup topic in the TWiki:Main web to include users with system administrator status.
  • Edit the TWikiPreferences topic in the TWiki:TWiki web to set access privileges.
  • Edit the WebPreferences topic in each web, if necessary: set access priviliges.

That's it for a basic new web set-up!

Optionally, you can also:

  • Create custom web-specific templates in a new twiki/templates/Someweb directory (otherwise, templates are inherited from twiki/templates).
  • Add TWikiForms for form-based page input that's stored separately from the main free-form topic text.

ALERT! NOTE: User home topics are located in the Galeon.Main web - don't try to move them or create them in other webs. From any other web, user signatures have to point to Galeon.Main web, using a Main.UserName or %MAINWEB%.UserName format. (The %MAINWEB% variable is an advantage if you ever change the Main web name, but the standard Main.UserName is easier for users to enter, which is the bottom line!

TWiki File System Info

See Appendix A: TWiki File System for an installed system snapshot and descriptions of all files in the TWiki 01-Sep-2001 distribution.

-- PeterThoeny - 03 Jun 2003
-- MikeMannix? - 16 May 2002


Added:
>
>

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. Please read TWiki:Codev.WindowsModPerlInstallCookbook in case you use mod_perl.

There is a huge volume of existing material on TWiki about installing on Windows, and I'm indebted to the many contributors for this - the aim of this cookbook is to synthesise the many tips into a recipe that works.

  • NOTE: This cookbook is probably incomplete (e.g. it doesn't cover authentication setup), but it has now been successfully tried out by a few people - it is quite accurate and should get you started if you follow the instructions. Please consider it beta quality, and 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.

-- RichardDonkin? - 24 Feb 2002

Recent updates

  • 30 Nov 2002 - added binutils to list of Cygwin packages, and added warning not to use Apache 2.0
  • 20 Nov 2002 - update to avoid TWiki:Support.InstallDigestSHA1Fails when installing Digest::SHA1 on Windows 2000
  • 12 Nov 2002 - setting SMTPMAILHOST for user registration and notification
  • 03 Sep 2002 - linked to TWiki:Codev.WindowsModPerlInstallCookbook
  • 20 Jul 2002 - added flags to grep commands in TWiki.cfg
  • 27 Jun 2002 - more updates to list of required Cygwin packages
  • 20 Jun 2002 - added creation of c:/twiki directory
  • 17 Jun 2002 - updates to list of required Cygwin packages
  • 15 Jun 2002 - various notes on Cygwin installation and troubleshooting: use of 'Unix' as default text file type (i.e. for mounting c:/cygwin directories) is essential for binary attachment uploads to work properly
  • 27 Apr 2002 - update to settings for egrep and fgrep on some Cygwin versions (fix from TWiki:Main.DavidLeBlanc)
  • 21 Apr 2002 - updates on download sizes and free disk space requirements, improved post-installation testing, and brief coverage of TWiki:Codev.WindowsInstallModNTLM to avoid TWiki:Codev.ForgettingPasswords
  • 18 Apr 2002 - updates on Apache installation, setting TZ variable, and creation of c:\temp, based on comments by TWiki:Main.MaryDeMarco
  • 3 Apr 2002 - added pcre to list of Cygwin packages (required by grep), fixed bug in Apache config (Apache doesn't allow '#' comments on same line as config)
  • 19 Mar 2002 - comment about Windows 98
  • 18 Mar 2002 - fix for register script committed to TWiki:Codev.TWikiAlphaRelease - most users can ignore this for now, but the edits in step 5 will eventually go away
  • 14 Mar 2002 - minor fix to section on Apache environment
  • 13 Mar 2002 - added a link to another Windows text editor
  • 4 Mar 2002 - changed status to beta, notes about using spaces in file names, pointer on TWiki authentication setup, overview of Cygwin permissions and security issues
  • 3 Mar 2002 - minor update to include uname -a command to check Cygwin DLL version, and delete Apache config's PassEnv line
  • 27 Feb 2002 - various improvements to Cygwin and Perl Net::SMTP installation sections, based on comments in TWiki:Codev.WindowsInstallCookbookComments by TWiki:Main.MartinWittmann. Also linked to a Windows editor that understands Unix/Cygwin file formats.
  • 25 Feb 2002 - clarified changes required to register, fixed minor typo in Cygwin binary mode section, after beta testing by TWiki:Main.JerryWard (thanks!)

Scope

This document covers installation of the TWiki 01-Feb-2003 production release (TWiki:Codev/TWikiRelease01Feb2003) in the following environment - if you want to use a different environment, feel free to use this as a guideline only. (It has been mainly tested with the TWiki 01-Dec-2001 release but should work fine with Feb 2003.)

Component Name, version Comment
Operating System Windows 2000 Should also work for Windows NT
Web Server Apache 1.3.26 Windows-specific security holes fixed in this build
(check latest version at http://httpd.apache.org, but don't use Apache 2.0 yet)
Unix tools Cygwin 1.3.9 Simplest way to get a whole set of required tools
Perl Cygwin perl-5.6.1-2 Comes with Cygwin
RCS Cygwin rcs-5.7-2 Comes with Cygwin, includes a file corruption bugfix

Why this choice of packages? Because I'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, with a recent TWiki-relevant bug fix in Feb 2002. 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 and Perl 5.8, are very likely to cause problems - for example, Apache 2.0 is unable to authenticate (see TWiki:Support.FailedAuthenticationWithApache2OnWinNT) users created by the current TWiki user registration script (due to a feature being removed in 2.0), and Perl 5.8 may introduce issues due to its Unicode features. Even though the Apache group says that Apache 2.0 is the best version, that's not true for TWiki.

Alternatives

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

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

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.3.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 to 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 is best done with an editor that can handle Unix file format (see the Cygwin binary mode section below) - the installation process includes nano, a non-GUI editor, but if you prefer to use a GUI editor, you should first 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 Win2000 cmd.exe 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 RCS tools that it (typically) launches with the bash shell.

If you need to use spaces in file names (not recommended), you may be able to put double quotes around the file name in the TWiki.cfg file - however, it's not clear whether all the TWiki code would work with this.

Installing Components

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

TWiki (part 1)

Head to http://twiki.org, click the download link, and fill in the form to request a URL for download. You'll get an automated email, which should arrive by the time you need it.

Apache

1. 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) - this is supported by Windows 2000.

  • 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.

2. 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.
  • You can choose to run Apache as a Win2000 service or as a normal program - see the Apache docs for details.

3. Test Apache

  • If necessary, start apache, either as a Win2000 service (using Admin Tools | Computer Management, or by typing apache -k start -n apache) or standalone (by typing apache -k start)
  • 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.

Cygwin, Unix tools, Perl and RCS

4. Install Cygwin

Head to http://cygwin.com, and click the Install Cygwin 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
    • ncftp
    • pcre
    • perl (5.6.1-2 or higher)
    • rcs (5.7-2 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. Something like 20 to 30 MB of free disk space should be enough for Cygwin, but I didn't test this (try a du -k / after a new install and let me know the last figure).
    • 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

5. 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.

6. 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').
  • 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.

TWiki (part 2)

7. Download TWiki

Download the latest TWiki release from the URL that PeterThoeny sent you, and save it in the c:/twiki directory.

8. Install TWiki

Unzip the ZIP file under c:/twiki using WinZip, or by going into Cygwin and doing the following - you can hit the TAB key to complete filenames after you've typed the first part:

   $ cd /twiki
   $ unzip TWiki20011201.zip

Configuring components

Now that all the components are installed, you need to configure them.

Configuring 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.

  • NOTE: This needs reviewing for security holes and to ensure nothing is missed, though this config does work.

1. Configure Apache (part 1)

Using a suitable text editor (e.g. Cygwin's 'nano', or the Windows PFE editor, unless you already know 'vi'), edit c:/apache/conf/httpd.conf as follows - this tells Apache where TWiki lives, and removes the need to tinker with the Windows 2000 environment settings.

  • If you are using nano, always launch it with nano -w filename - this turns off wrapping of long lines.
  • 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:

# Change this to point to the Apache administrator (e.g. you)
ServerAdmin you@yourdomain.com

# Replaces DocumentRoot "C:/apache/htdocs"
DocumentRoot "C:/twiki"

# Replaces <Directory "C:/apache/htdocs">
<Directory "C:/twiki">

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

# Alias /twiki/ "C:/twiki/"
# ScriptAlias /twiki/bin/ "C:/twiki/bin/"
<Directory  "C:/twiki/bin/">
    # RD: Changed None to All in next line, to enable .htaccess
    AllowOverride All
    Allow From All
    Options  ExecCGI
    SetHandler cgi-script
</Directory>

# Environment setup required to run Apache as service or as a
# standalone process.
<IfModule mod_env.c>
   # Adjust TZ for your server timezone, e.g. EST5EDT - put the non-daylight-savings
   # timezone code first (e.g. EST or GMT), followed by the number of hours that it's behind GMT 
   # during non-daylight-savings time (use '-5' for timezones in advance of GMT).
   SetEnv TZ GMT0BST
   SetEnv RCSINIT -x,v/
   # Adjust TEMP and TMP for your server and create directories if necessary
   SetEnv TEMP c:/temp
   SetEnv TMP c:/temp
   SetEnv LOGNAME system
   SetEnv HOME c:/twiki
</IfModule>

2. Configure Apache (part 2)

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.
#
# Document types
#
<IfModule mod_mime.c>
    # TWiki setup - avoid renaming scripts
    AddHandler cgi-script .
</IfModule>

Configuring TWiki

3. Configure TWiki

Edit the TWiki config file, c:/twiki/lib/TWiki.cfg (or in Cygwin terms, /twiki/lib/TWiki.cfg) as follows:

  • NOTE: It should be possible to use c:/twiki format pathnames for Cygwin, given the above binmode setup, but I have not tested this fully - a Cygwin Perl test script does generate binary mode files in this configuration, so it should work with RCS as well (really need a small RCS file corruption test case). Watch out for RCS file corruption carefully if you do try c:/twiki pathnames with Cygwin, and do report your experiences...
  • NOTE: Some recent versions of Cygwin (e.g. 1.3.10) seem to create 'symbolic links' from fgrep and egrep to grep, requiring the settings for these commands to point directly to grep (with suitable flags to provide fgrep and egrep behaviour).

# variables that need to be changed when installing on a new server:
# ==================================================================
#                   http://galeon.sourceforge.net/Main : link of TWiki icon in upper left corner :
$wikiHomeUrl      = "http://yourdomain.com/bin/view";
#                   Host of TWiki URL :    (Example "http://myhost.com:123")
$defaultUrlHost   = "http://yourdomain.com";
#                    : cgi-bin path of TWiki URL:
$scriptUrlPath    = "/bin";
#                   /twiki/pub : Public data path of TWiki URL (root of attachments) :
$pubUrlPath       = "/pub";

# NOTE: Next three settings should be valid absolute pathnames using Cygwin; if using
# TWiki:Codev.ActiveState Perl, use z:/twiki format pathnames if your TWiki directory is not on C:.

#                   Public data directory, must match $pubUrlPath :
$pubDir           = "/twiki/pub";
#                   Template directory :
$templateDir      = "/twiki/templates";
#                   Data (topic files) root directory :
$dataDir          = "/twiki/data";

....

#                   Set ENV{'PATH'} explicitly for taint checks ( #!perl -T option ) :
#                   (Note: PATH environment variable is not changed if set to "")

# On Windows, $safeEnvPath needs only one component, the directory where RCS is installed
# - used by 'rcsdiff' to run 'co' program, so PATH must be correct.

# Unix/Linux setting:
# $safeEnvPath      = "/bin:/usr/bin";

# Using Cygwin perl, so can use Unix-like paths, with ':' as separator.
# Note that /usr/bin and /bin are identical due to default /usr/bin mount
# in Cygwin.  Must NOT use 'c:/foo' type paths, as ':' is taken as separator
# meaning that 'c' is interpreted as a pathname, giving Perl taint error.
$safeEnvPath      = "/bin";

# If using ActiveState perl, use Windows paths instead
# $safeEnvPath      = "c:/cygwin/bin";

...

#                   RCS directory (find out by 'which rcs') :
$rcsDir           = "c:/cygwin/bin";

...

#                   Unix egrep command :
$egrepCmd         = "/bin/grep -E";
#                   Unix fgrep command :
$fgrepCmd         = "/bin/grep -F";

For the cookbook install using Cygwin Perl, there's no more TWiki.cfg editing to be done, so you can get onto the next section.

#                   NOTE: When using ActiveState Perl, you must specify
#                   a full Windows-style pathname, using '\\' for backslashes,
#                   for the ls, egrep and fgrep commands, because Cygwin's shell
#                   is not used - forward slashes are OK in Windows everywhere
#                   except in the cmd.exe shell. Drive letters are OK - e.g.
#                   'c:\\foo\\ls' will work.  When using Cygwin perl, just
#                   use the default '/bin/ls' type settings.
#
#                   Unix ls command :
$lsCmd            = "c:\\cygwin\\bin\\ls";
#                   Unix egrep command :
$egrepCmd         = "c:\\cygwin\\bin\\grep";
#                   Unix fgrep command :
$fgrepCmd         = "c:\\cygwin\\bin\\grep";

Editing the CGI scripts

4. Editing the Shebang lines

Now to edit the curiously named 'shebang lines' at the top of the TWiki CGI 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
    • If you do mis-type the perl line, you can restore from the .backup directory and re-run the command, as it will only edit the original files, not the backups with '~' suffixes.

$ 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

If for some reason the edit goes wrong, just type cp .backup/* . (while within the bin directory) to restore the original distribution files. Use ls -a to see the .backup directory, and ls -a .backup to view its contents.

Optional step: you can do 'rm *~' to clean out the backups made by Perl, but that's not essential as all the original files cannot be executed. If you do this, type the command very carefully, as a space after the '*' will wipe out all files in this directory!

5. Minor changes to TWiki scripts

TWiki Dec 2001 release only - fixed in Feb 2003 release

If using the Dec 2001 release, you now need to make some minor edits to files in the c:/twiki/bin directory, using a suitable editor (remember to use nano -w filename if you prefer nano to vi - or just use the Windows PFE editor).

  • Edit the register script in /twiki/bin - change line 200 to read as follows (insert the MIME::Base64:: part):

         return $user . ':{SHA}' . MIME::Base64::encode_base64(Digest::SHA1::sha1($passwd));

Perl module installation

6. Installing required Perl modules

Some additional Perl modules are needed for the register script to work properly. 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. Here's what you need to do:

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 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 tool'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.

Re-locking RCS files

7. Re-locking files

First, some testing: in your browser, go to http://yourdomain.com/bin/testenv - this provides a lot of detail, including warnings. Write down the Apache server's userid that is given by this script - typically either 'system' or 'administrator' - I'll assume 'system' from now on.

  • If the testenv script doesn't work, go back and check the configuration of the Apache httpd.conf file, and TWiki.cfg. Have a look at the Apache error log, c:/apache/logs/error_log, and the TWiki error log, /twiki/data/log*.txt.

This 'system' user must own the locks on the RCS files, which are shipped with the lock held by 'nobody'. The reason this matters is that no revisions will be tracked by RCS unless the Apache userid matches that of the RCS file locks.

You can re-lock files using rcs -u and rcs -l, but it's a painfully manual process. Instead, just use Perl again to mass-edit all the RCS files, as follows:

  • NOTE: The 'NR <= 10' part of the Perl command ensures that it only operates on the first 10 lines, to avoid editing the body of RCS files for topics that happen to include the text 'nobody:' (like this one...)

$ cd /twiki/data

$ : Make a backup of all files
$ tar czvf all-files.tar.gz */*

$ : Test edit a single file to check your typing
$ perl -pi~~~ -e 'NR <= 10 && s/nobody:/system:/ ' Main/WebIndex.txt,v

$ diff Main/WebIndex.txt,v Main/WebIndex.txt,v~~~
5c5
<       system:1.2; strict;
---
>       nobody:1.2; strict;

$ : Now edit all the RCS files at once - use cursor-up to recall previous command
$ perl -pi~~~ -e 'NR <= 10 && s/nobody:/system:/ ' */*,v

$ : Check for any remaining files not edited
$ grep 'strict;$' */*,v | grep -v system

$ : Clean up - type this very carefully 
$ rm */*~~~

  • If something goes wrong: to restore your existing files from the backup, just type tar xzvf all-files.tar.gz and all your files, both .txt and .txt,v, will be back as they were before the edits.

You have now re-locked all the RCS files and are almost ready to start using TWiki!

Email setup

8. Email setup for notification and registration

You need to set the SMTPMAILHOST in TWikiPreferences to an SMTP email host that is reachable and currently working. Otherwise you'll get a confusing message from TWiki when registering new users or running mailnotify (for WebNotify), along the lines of:

   Software Error: Can't call method "mail" on an undefined value at ../lib/TWiki/Net.pm line 187.

There are other settings to be made in TWikiPreferences, e.g. the WIKIWEBMASTER and (probably) the SMTPSENDERHOST (normally your mail server or TWiki server). See the TWikiInstallationGuide for more details, what's listed here is just enough to let you run the basic tests.

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:

  • testenv - use http://yourdomain.com/bin/testenv and check for warnings
  • 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 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 TWiki.cfg. 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.

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.

Format of filenames

In your TWiki on Windows installation, it's worth remembering that:

  • Apache configuration files (e.g. the .htaccess file and c:/apache/conf/httpd.conf) always use Windows format paths, with forward slashes, e.g. c:/twiki
  • The same is true for the first line of the TWiki Perl scripts (since this line is interpreted by Apache), e.g. c:/cygwin/bin/perl
  • All other lines in the Perl scripts use Unix format paths, e.g. /twiki (using Cygwin Perl as per this cookbook)
  • Depending on the Perl version used (Cygwin or TWiki:Codev.ActivePerl), the TWiki.cfg file uses a mixture of Unix and Cygwin format paths - stick to the format used in the installation step for TWiki.cfg
  • RCS always uses Unix format paths, e.g. /twiki

Credits

Material in this cookbook is heavily based on the enormous number of contributions in TWiki:Codev.TWikiOnWindowsArchive and related topics - too many people to thank, but have a look at the contributor list to TWiki:Codev.TWikiOnWindowsArchive to get an idea!

People who've tested or reviewed this document and provided valuable feedback include:


ALERT! Comments welcome at TWiki:Codev.WindowsInstallCookbookComments

-- PeterThoeny - 30 Jan 2003



TWiki Upgrade Guide

Upgrade from the previous TWiki 01-Dec-2001 production release to TWiki 01-Feb-2003

Overview

This guide describes how to upgrade from TWiki 01-Dec-2001 to TWiki 01-Feb-2003. The new version involves several new features and numerous enhancements to the previous version.

Upgrade Requirements

  • To upgrade from a 01-Dec-2001 standard installation to the latest 01-Feb-2003 TWiki Production Release, follow the instructions below.

  • 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 from TWiki 01-Dec-2001

  • Form and script to create new webs
  • Enhanced Plugin API to manipulate topic data with new functions in TWikiFuncModule: readTopicText, saveTopicText, setTopicEditLock, checkTopicEditLock
  • New Plugin hooks registrationHandler, beforeEditHandler, afterEditHandler, beforeSaveHandler, writeHeaderHandler, redirectCgiQueryHandler, getSessionValueHandler, setSessionValueHandler
  • Internationalization ('I18N') support 8-bit character sets in WikiWords, such as ISO-8859-15, KOI8-R
  • Possible to omit e-mail address in WebNotify, in which case the e-mail is taken from the user's home page; if the WikiName is a group name, a notification is sent to all members of the group
  • New data storage framework that lets you use external RCS commands for revision control, or a new native Perl implementation that does not depend on the external RCS commands (not recommended yet for production use, see TWiki:Codev/RcsLite)
  • New AND search; with regular expression enabled, use the semicolon ";" as the AND operator in %SEARCH{}% variable, FormattedSearch and WebSearch
  • Many more enhancements, see the complete change log at TWikiHistory

Upgrade Procedure from 01-Dec-2001 to 01-Feb-2003 Release

The following steps describe the upgrade assuming that $TWIKIROOT is the root of your current 01-Dec-2001 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 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.
    • Specific changes to templates and skins:
      • Replace %WIKIHOMEURL% with %WIKILOGOURL%
      • Replace img tag's src=%PUBURLPATH%/wikiHome.gif with src=%WIKILOGOIMG%
      • Replace img tag's alt="TWiki Home" with alt="%WIKILOGOALT%"
      • Replace meta tag's charset=iso-8859-1" with charset=%CHARSET%"
      • Add %TOPIC% to form action of GoBox
      • For internationalized sites, URL encode webs and topics in all form actions, e.g. replace .../view%SCRIPTSUFFIX%/%WEB%/%TOPIC%" with .../view%SCRIPTSUFFIX%/%INTURLENCODE{"%WEB%/%TOPIC%"}%
  4. Update script files:
    • Overwrite all script files in $TWIKIROOT/bin with the new ones.
      • If necessary, change the script names 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 $TWIKIROOT/bin/.htaccess to include a directive for the new manage script:
      <Files "manage">
          require valid-user
      </Files>
    • Pay attention to the file and directory permissions, the scripts need to be executable, e.g. chmod 775 $TWIKIROOT/bin/*
    • If on Non-Unix host, make sure the correct path to the perl interpreter is changed in the first line of every script file. See also WindowsInstallCookbook.
  5. Update library files:
    • Overwrite the TWiki.cfg configuration file in $TWIKIROOT/lib with the new one.
    • Restore the configuration values from the backup. You typically need to configure just the ones in the section "variables that need to be changed when installing on a new server".
    • 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
    • Pay attention to the file and directory permissions, the library files should not be executable, e.g. chmod -R 664 $TWIKIROOT/lib/*
  6. Update data files:
    • Run the bin/testenv script from the browser (e.g. http://localhost/bin/testenv) to verify if the cgi-scripts are running as user nobody.
      • In case not: The *,v RCS repository files delivered with the installation package are locked by user nobody and need to be changed to the user of your cgi-scripts, e.g. www-data:
      • Change the lock user in the temporary twiki/data/* directories where you unzipped the installation package: A simple way to switch the locker of the RCS files is to use sed in the :
        for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done
    • 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.*, WebNotify.*, 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.
    • Move the data/_default directory from the temporary location to your $TWIKIROOT/data directory.
    • Move the data/Sandbox directory from the temporary location to your $TWIKIROOT/data directory
      (The Test web has been renamed to Sandbox in this release.)
      • There are now two webs in parallel (Test and Sandbox) for the purpose of testing (experimenting) TWiki.
        Move all relevant topics from Test web to Sandbox web, or motivate the users to do.
    • Make sure that the directories and files below $TWIKIROOT/data are writable by your cgi-script user.
  7. Adapt the other webs (all other than TWiki and _default):
    • Merge the new files WebHome.txt and WebPreferences.txt of your other webs to make sure, you have the improvements applied also in your other webs.
  8. 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.
  9. Update TWikiPreferences to authorize users to create webs:
    • Add ALLOWWEBMANAGE to the FINALPREFERENCES list so that nobody can overwrite the setting:
      • Set FINALPREFERENCES = WIKIWEBMASTER, PREVIEWBGIMAGE, SMTPMAILHOST, SMTPSENDERHOST, ALLOWWEBMANAGE
    • Set users or groups allowed to create new webs:
  10. Verify installation:
    • Execute the $TWIKIROOT/bin/testenv script from your browser (e.g. http://localhost/bin/testenv) to see if it reports any issues; fix 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 TextFormattingRules.

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 TWiki.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/TWiki.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

-- PeterThoeny - 01 Feb 2002
-- MartinRaabe? - 15 Jan 2003



 <<O>>  Difference Topic TWikiDocumentation (r1.42 - 16 Jan 2003 - PeterThoeny)
Line: 1 to 1
Changed:
<
<
META TOPICINFO PeterThoeny date="1039329680" format="1.0" version="1.41"
>
>
META TOPICINFO PeterThoeny date="1042701668" format="1.0" version="1.42"

Changed:
<
<
TWiki Reference Manual (01-Dec-2001)
>
>
TWiki Reference Manual (07 May 2004)

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


 <<O>>  Difference Topic TWikiDocumentation (r1.39 - 03 Dec 2001 - MikeMannix?)
Line: 1 to 1
Changed:
<
<
META TOPICINFO MikeMannix? date="1007361807" format="1.0" version="1.38"
>
>
META TOPICINFO MikeMannix? date="1007383132" format="1.0" version="1.39"

Changed:
<
<
TWiki Reference Manual (01-Sep-2001)
>
>
TWiki Reference Manual (01-Dec-2001)

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

Line: 15 to 15

Related Topics: TWikiSite, TWikiHistory, TWikiPlannedFeatures, TWikiEnhancementRequests

Changed:
<
<

>
>


Note: Included topic TWikiImplementationNotes? does not exist yet
Changed:
<
<

>
>


TWiki Installation Guide

Installation instructions for the TWiki 01-Feb-2003 production release.

If you are reading this on your own TWiki installation, please get the latest installation guide (TWiki:TWiki.TWikiInstallationGuide), as this often has important updates to resolve installation issues.

These installation steps are based on the Apache web server on Linux. TWiki runs on other web servers and Unix systems, and should be fine with any web server and OS that meet the system requirements. Official documentation for platforms other than Linux is somewhat limited, so please check the topics listed below, they include some important tips for HP-UX, Solaris, OS/390, and many other platforms.

Standard Installation

Request and download the TWiki 01-Feb-2003 distribution in Unix ZIP format from http://TWiki.org/download.html. Please review the AdminSkillsAssumptions before you install TWiki.

Step 1: Create & Configure the Directories

ALERT! NOTE: If you don't have access to your Web server configuration files - for example, if you're installing on an ISP-hosted account, or you don't have administrator privileges on your intranet server - use the alternative Step 1 instead.

  • Create directory /home/httpd/twiki and unzip the TWiki distribution into this directory.
  • The twiki/bin directory of TWiki must be set as a cgi-bin directory. Add /home/httpd/twiki/bin to file httpd.conf (typcially located in /etc/httpd/) with only ExecCGI option.
  • The twiki/pub directory of TWiki must be set so that it is visible as a URL. Add /home/httpd/twiki to file httpd.conf with normal access options (copy from /home/httpd/html ).
  • Now add ScriptAlias for /twiki/bin and Alias for /twiki to file httpd.conf .
    ALERT! NOTE: The ScriptAlias must come before the Alias, otherwise, Apache will fail to correctly set up /twiki/bin/, by treating it as just another subdirectory of the /twiki/ alias.
  • The twiki/data and twiki/templates directories should be set so that they are not visible as URLs. Add them to httpd.conf with deny from all.

Example httpd.conf entries:
 ScriptAlias /twiki/bin/ "/home/httpd/twiki/bin/"
 Alias /twiki/ "/home/httpd/twiki/"
 <Directory "/home/httpd/twiki/bin">
    Options +ExecCGI
    SetHandler cgi-script
    Allow from all
 </Directory>
 <Directory "/home/httpd/twiki/pub">
    Options FollowSymLinks +Includes
    AllowOverride None
    Allow from all
 </Directory>
 <Directory "/home/httpd/twiki/data">
    deny from all
 </Directory>
 <Directory "/home/httpd/twiki/templates">
    deny from all
 </Directory>

  • Restart Apache by /etc/rc.d/rc5.d/S85httpd restart .
  • Test that the twiki/bin directory is CGI-enabled by trying visiting it in your browser:
    • Enter the URL for the bin directory, http://yourdomain.com/twiki/bin/.
    • Your settings are OK if you get a message like "Forbidden. You don't have permission to access /twiki/bin/ on this server".
    • Settings are NOT correct if you get something like "Index of /twiki/bin" - recheck your httpd.conf file.

Step 1 for Non-Root Accounts

To install TWiki on a system where you don't have Unix/Linux root (administrator) privileges, for example, on a hosted Web account or an intranet server administered by someone else:

  • Download and unzip TWiki on your local PC
  • Using the table below, create a directory structure on your host server
  • Upload the TWiki files by FTP (transfer as text except for the image files in pub)
TWiki dir: What it is: Where to copy: Example:
twiki start-up pages root TWiki dir /home/smith/twiki/
twiki/bin CGI bin CGI-enabled dir /home/smith/twiki/bin
twiki/lib library files same level as twiki/bin /home/smith/twiki/lib
twiki/pub public files htdoc enabled dir /home/smith/twiki/pub
twiki/data topic data dir secure from public access /home/smith/twiki/data
twiki/templates web templates dir secure from public access /home/smith/twiki/templates

If you are not able to create the twiki/lib directory at the same level as the twiki/bin directory (e.g. because CGI bin directories can't be under your home directory and you don't have root access), you can create this directory elsewhere and edit the setlib.cfg file in the bin directory:

    # -------------- Change these settings if required

    $twikiLibPath = '/some/other/path/lib';   # Path to lib directory containing TWiki.pm

You can also edit $localPerlLibPath in the setlib.cfg file if you are not root and need to install additional CPAN modules, but can't update the main Perl installation files on the server. Just set this variable to the full pathname to your local lib directory, typically under your home directory.

Step 2: Set File Permissions

  • 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 elsewhere, change the path to Perl in the first line of each script in the twiki/bin directory, or create a symbolic link from /usr/bin/perl.
    • IMPORTANT: On ISP-hosted accounts (and some intranet servers), Perl CGI scripts may require a .cgi extension to run. Some systems need .pl, the regular Perl extension. Rename all twiki/bin scripts if necessary.
  • Set the file permission of all Perl scripts in the twiki/bin directory as executable to -rwxr-xr-x (755).
  • To be able to edit the Perl scripts and .tmpl files it is necessary to chown and chgrp -R twiki so all the files have the owner you want.
  • HELP This Guide assumes user nobody ownership for all files manipulated by the CGI scripts (executed by the Web server), and user twiki for all other files. You can:
    • replace nobody with another user if your server executes scripts under a different name (ex: default for Debian is www-data).
      • TIP HINT: Run the testenv script from your browser: http://yourdomain.com/twiki/bin/testenv. It will show you the user name of the CGI scripts, a table listing all CGI environment variables, and a test of your twiki/lib/TWiki.cfg configuration file (you'll configure that in a minute).
    • replace user twiki with your own username
  • Set the permission of all files below twiki/data so that they are writable by user nobody. A simple way is to chmod them to -rw-rw-r-- (664) and to chown them to nobody.
  • Set the permission of the twiki/data directory and its subdirectories so that files in there are writable by user nobody. A simple way is to chmod them to drwxrwxr-x (775) and to chown them to nobody.
  • Set the permission of the twiki/pub directory and all its subdirectories so that files in there are writable by user nobody. A simple way is to chmod them to drwxrwxr-x (775) and to chown them to nobody.
  • HELP The twiki/data/*/*.txt,v RCS repository files in the installation package are locked by user nobody. If your CGI scripts are not running as user nobody, it's not possible to check in files (you'll see that the revision number won't increase after saving a topic). In this case, you need to unlock all repository files (check the RCS man pages) and lock them with a different user, such as www-data, or delete them all - new files will be automatically created the first time each topic is edited. A simple way to change ownership is with a search-and-replace in all files; for example, using Perl (type this carefully!):
cd twiki/data
perl -pi~ -e 'NR <= 10 && s/nobody:/www-data:/ ' */*,v

Step 3: Set the Main Configuration File

  • Edit the file twiki/lib/TWiki.cfg, setting the variables to your needs.
    • Set the file extension in the $scriptSuffix variable to cgi or pl if required.
    • RCS - revision control system to store revision of topics and attachments. You can use RCS executables or a version of RCS written in Perl, note that as the time of writing (Apr 2002) the Perl version has not been widely tested, so if you want to put up a live site the RCS executables are recommended.
      • Set $storeTopicImpl = "RcsWrap"; for the RCS executables and make sure RCS is installed. Set $rcsDir in twiki/lib/TWiki.cfg to match the location of your RCS binaries. You can check this by issuing the command rcs at the prompt, it should result in something like "rcs: no input file".
        • Check that you have GNU diff, by typing diff -v - an error indicates you have a non-GNU diff, so install the GNU diffutils package and make sure that diff is on the PATH used by TWiki (see $safeEnvPath in the TWiki.cfg file).
      • Set $storeTopicImpl = "RcsLite"; for the Perl based RCS
  • Security issue: Directories twiki/data , twiki/templates and all their subdirectories should be set so that they are not visible through URLs. (Alternatively, move the directories to a place where they are not visible, and change the variables in twiki/lib/TWiki.cfg accordingly)
  • Test your settings by running the testenv script from your browser: http://yourdomain.com/twiki/bin/testenv. Check if your twiki/lib/TWiki.cfg configuration file settings are correct.

Step 4: Configure Site-Wide Email Preferences

  • Edit the TWikiPreferences topic in the TWiki web (by pointing your browser to http://yourdomain.com/twiki/bin/view/TWiki/TWikiPreferences) to set the WIKIWEBMASTER email address, and other email settings required for registration and WebChangesAlert to work:
    • WIKIWEBMASTER should be set to the email address of the TWiki administrator
    • SMTPMAILHOST is typically set on Windows or other non-Unix/Linux systems, where sendmail or similar is not available. When this is set and the Perl module Net::SMTP is installed, TWiki will connect to this SMTP server (e.g. mail.yourdomain.com) to send email for user registration and WebChangesAlerts. If you do have a sendmail-type program, leave SMTPMAILHOST unset so that the external sendmail program is used instead (defined by $mailProgram in TWiki.cfg).
    • SMTPSENDERHOST is optional, and set to the domain name sending the email (e.g. twiki.yourdomain.com). For use where the SMTP server requires that you identify the TWiki server sending mail. If not set, Net::SMTP will guess it for you.
  • You may want to set up other TWikiPreferences later on.
  • To enable the WebChangesAlerts (email notifications) you need to read about cron in the topic TWikiSiteTools.

Step 5: Finish Up from Your Browser

  • Point your Web browser at http://yourdomain.com/twiki/bin/view and start TWiki-ing away!
    • TIP Or, point to http://yourdomain.com/twiki/ to get the pre-TWiki index.html page, with a link to the view script. Customize this page if you want a public intro screen with a login link, instead of immediately calling up the .htaccess login dialog by going directly to view.
  • Edit the WebPreferences topic in each web, if necessary: set individual WEBCOPYRIGHT messages, and other preferences.
  • Enable email notification of topic changes, TWikiSiteTools has more.
  • Edit the WebNotify topic in all webs and add the users you want to notify.
  • Add the TWiki:Main/PoweredByTWikiLogo to your Main.Home topic.
  • You can add new %VARIABLES%. Define site-level variables in the TWikiPreferences topic. See also: TWikiVariables.

That's it for the standard virgin installation of TWiki. Read on for server-level customization options.

Additional Server-Level Options

With your new TWiki installation up and running, you can manage most aspects of your site from the browser interface. Only a few functions require access to the server file system, via Telnet or FTP. You can make these server-level changes during installation, and at any time afterwards.

Enabling Authentication of Users

  • If TWiki is installed on a non-authenticated server - not using SSL - and you'd like to authenticate users:
    1. Rename file .htaccess.txt in the twiki/bin directory to .htaccess and change it to your needs. For details, consult the HTTP server documentation (for Apache server: [1], [2]). In particular, the following red part needs to be configured correctly:
      Redirect /urlpathto/twiki/index.html http://yourdomain.com/urlpathto/twiki/bin/view
      AuthUserFile /filepathto/twiki/data/.htpasswd
      ErrorDocument 401 /urlpathto/twiki/bin/oops/TWiki/TWikiRegistration?template=oopsauth
      • ALERT! NOTE: If you had to add a .cgi or .pl file extension to the bin scripts, make sure to do the same for edit, view, preview, and all the other script names in .htaccess.
      • HELP The browser should ask for login name and password when you click on the Edit link. In case .htaccess does not have the desired effect, you need to enable it: Add "AllowOverride All" to the Directory [3] section of access.conf for your twiki/bin directory.
        • This applies only if you have root access: on hosted accounts, you shouldn't have this problem - otherwise, email tech support.
      • ALERT! NOTE: In the TWiki distribution package, the twiki/data/.htpasswd.txt file contains several TWiki core team user accounts and a guest user account. You probably want to remove those accounts by deleting the entries in .htpasswd. Do not remove the guest user if you want to allow guest logins.
    2. Copy the TWikiRegistrationPub topic to TWikiRegistration, overwriting old version of TWikiRegistration. Do that by either editing the topics in theTWiki web, or by renaming the .txt and .txt,v files in the twiki/data/TWiki directory.
  • Customization:
    • 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.
  • Register yourself in the TWikiRegistration topic.
    • ALERT! NOTE: When a user registers, a new line with the username and encrypted password is added to the data/.htpasswd file. The .htpasswd file that comes with the TWiki installation includes user accounts for TWiki core team members that are used for testing on TWiki.org. You can edit the file and delete those lines.
  • Create a new topic to check if authentication works.
  • Edit the TWikiAdminGroup topic in the TWiki:Main web to include users with system administrator status.
  • Edit the TWikiPreferences topic in the TWiki:TWiki web to set access privileges.
  • Edit the WebPreferences topic in each web, if necessary: set access priviliges.

That's it for a basic new web set-up!

Optionally, you can also:

  • Create custom web-specific templates in a new twiki/templates/Someweb directory (otherwise, templates are inherited from twiki/templates).
  • Add TWikiForms for form-based page input that's stored separately from the main free-form topic text.

ALERT! NOTE: User home topics are located in the Galeon.Main web - don't try to move them or create them in other webs. From any other web, user signatures have to point to Galeon.Main web, using a Main.UserName or %MAINWEB%.UserName format. (The %MAINWEB% variable is an advantage if you ever change the Main web name, but the standard Main.UserName is easier for users to enter, which is the bottom line!

TWiki File System Info

See Appendix A: TWiki File System for an installed system snapshot and descriptions of all files in the TWiki 01-Sep-2001 distribution.

-- PeterThoeny - 03 Jun 2003
-- MikeMannix? - 16 May 2002

Changed:
<
<

>
>


TWiki Upgrade Guide

Upgrade from the previous TWiki 01-Dec-2001 production release to TWiki 01-Feb-2003

Overview

This guide describes how to upgrade from TWiki 01-Dec-2001 to TWiki 01-Feb-2003. The new version involves several new features and numerous enhancements to the previous version.

Upgrade Requirements

  • To upgrade from a 01-Dec-2001 standard installation to the latest 01-Feb-2003 TWiki Production Release, follow the instructions below.

  • 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 from TWiki 01-Dec-2001

  • Form and script to create new webs
  • Enhanced Plugin API to manipulate topic data with new functions in TWikiFuncModule: readTopicText, saveTopicText, setTopicEditLock, checkTopicEditLock
  • New Plugin hooks registrationHandler, beforeEditHandler, afterEditHandler, beforeSaveHandler, writeHeaderHandler, redirectCgiQueryHandler, getSessionValueHandler, setSessionValueHandler
  • Internationalization ('I18N') support 8-bit character sets in WikiWords, such as ISO-8859-15, KOI8-R
  • Possible to omit e-mail address in WebNotify, in which case the e-mail is taken from the user's home page; if the WikiName is a group name, a notification is sent to all members of the group
  • New data storage framework that lets you use external RCS commands for revision control, or a new native Perl implementation that does not depend on the external RCS commands (not recommended yet for production use, see TWiki:Codev/RcsLite)
  • New AND search; with regular expression enabled, use the semicolon ";" as the AND operator in %SEARCH{}% variable, FormattedSearch and WebSearch
  • Many more enhancements, see the complete change log at TWikiHistory

Upgrade Procedure from 01-Dec-2001 to 01-Feb-2003 Release

The following steps describe the upgrade assuming that $TWIKIROOT is the root of your current 01-Dec-2001 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 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.
    • Specific changes to templates and skins:
      • Replace %WIKIHOMEURL% with %WIKILOGOURL%
      • Replace img tag's src=%PUBURLPATH%/wikiHome.gif with src=%WIKILOGOIMG%
      • Replace img tag's alt="TWiki Home" with alt="%WIKILOGOALT%"
      • Replace meta tag's charset=iso-8859-1" with charset=%CHARSET%"
      • Add %TOPIC% to form action of GoBox
      • For internationalized sites, URL encode webs and topics in all form actions, e.g. replace .../view%SCRIPTSUFFIX%/%WEB%/%TOPIC%" with .../view%SCRIPTSUFFIX%/%INTURLENCODE{"%WEB%/%TOPIC%"}%
  4. Update script files:
    • Overwrite all script files in $TWIKIROOT/bin with the new ones.
      • If necessary, change the script names 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 $TWIKIROOT/bin/.htaccess to include a directive for the new manage script:
      <Files "manage">
          require valid-user
      </Files>
    • Pay attention to the file and directory permissions, the scripts need to be executable, e.g. chmod 775 $TWIKIROOT/bin/*
    • If on Non-Unix host, make sure the correct path to the perl interpreter is changed in the first line of every script file. See also WindowsInstallCookbook.
  5. Update library files:
    • Overwrite the TWiki.cfg configuration file in $TWIKIROOT/lib with the new one.
    • Restore the configuration values from the backup. You typically need to configure just the ones in the section "variables that need to be changed when installing on a new server".
    • 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
    • Pay attention to the file and directory permissions, the library files should not be executable, e.g. chmod -R 664 $TWIKIROOT/lib/*
  6. Update data files:
    • Run the bin/testenv script from the browser (e.g. http://localhost/bin/testenv) to verify if the cgi-scripts are running as user nobody.
      • In case not: The *,v RCS repository files delivered with the installation package are locked by user nobody and need to be changed to the user of your cgi-scripts, e.g. www-data:
      • Change the lock user in the temporary twiki/data/* directories where you unzipped the installation package: A simple way to switch the locker of the RCS files is to use sed in the :
        for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done
    • 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.*, WebNotify.*, 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.
    • Move the data/_default directory from the temporary location to your $TWIKIROOT/data directory.
    • Move the data/Sandbox directory from the temporary location to your $TWIKIROOT/data directory
      (The Test web has been renamed to Sandbox in this release.)
      • There are now two webs in parallel (Test and Sandbox) for the purpose of testing (experimenting) TWiki.
        Move all relevant topics from Test web to Sandbox web, or motivate the users to do.
    • Make sure that the directories and files below $TWIKIROOT/data are writable by your cgi-script user.
  7. Adapt the other webs (all other than TWiki and _default):
    • Merge the new files WebHome.txt and WebPreferences.txt of your other webs to make sure, you have the improvements applied also in your other webs.
  8. 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.
  9. Update TWikiPreferences to authorize users to create webs:
    • Add ALLOWWEBMANAGE to the FINALPREFERENCES list so that nobody can overwrite the setting:
      • Set FINALPREFERENCES = WIKIWEBMASTER, PREVIEWBGIMAGE, SMTPMAILHOST, SMTPSENDERHOST, ALLOWWEBMANAGE
    • Set users or groups allowed to create new webs:
  10. Verify installation:
    • Execute the $TWIKIROOT/bin/testenv script from your browser (e.g. http://localhost/bin/testenv) to see if it reports any issues; fix 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 TextFormattingRules.

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 TWiki.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/TWiki.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

-- PeterThoeny - 01 Feb 2002
-- MartinRaabe? - 15 Jan 2003

Changed:
<
<

>
>


TWiki User Authentication

TWiki site access control and user activity tracking options

TWiki does not authenticate users internally, it depends on the REMOTE_USER environment variable. This variable is set when you enable Basic Authentication (.htaccess) or SSL "secure server" authentication (https protocol).

TWiki uses visitor identification to keep track of who made changes to topics at what time and to manage a wide range of personal site settings. This gives a complete audit trail of changes and activity.

Authentication Options

No special installation steps are required if the server is already authenticated. If it isn't, you have these options for controlling user access:

  1. No login at all: Forget about authentication to make your site completely public - anyone can browse and edit freely, in classic Wiki mode. All visitors are assigned the TWikiGuest default identity, so you can't track individual user activity.
    • How: Default, no web server configuration necessary
  2. No login to view; require login to edit: Keeping track of who changed what and when, while keeping view access unrestricted is desirable in most TWiki deployments. This option is not suitable if you need TWikiAccessControl for view restricted content since TWiki does not know who a user is when looking at content.
    • How: Use Basic Authentication (.htaccess) to control access by protecting key scripts: attach, edit, installpasswd, manage, preview, rename, save, upload using the .htaccess file. The TWikiInstallationGuide has step-by-step instructions.
  3. No login to view unless necessary; require login to edit: You prefer not to bother the user with login for unrestricted content, but you need TWikiAccessControl for view restricted content. There are two ways to accomplish this:
    • How 1: Use Basic Authentication with Partial Authentication (described below)
    • How 2: Use one of the Session TWiki:Plugins where you give the user the option to login and logout.
  4. Require login to view and edit: Most restrictive, but TWiki knows who the user is at all times. There are two ways to accomplish this:
    • How 1: Use Basic Authentication to authenticate the whole twiki/bin directory. Consult your web server documentation.
    • How 1: Use SSL (Secure Sockets Layer; HTTPS) to authenticate and secure the whole server. Consult your web server documentation.

Partial Authentication

Tracking by IP address is an experimental feature, enabled in lib/TWiki.cfg. It lets you combine open access to some functions, with authentication on others, with full user activity tracking:

  • Normally, the REMOTE_USER environment variable is set for the scripts that are under authentication. If, for example, the edit, save and preview scripts are authenticated, but not view, you would get your WikiName in preview for the %WIKIUSERNAME% variable, but view will show TWikiGuest instead of your WikiName.
  • TWiki can be configured to remember the IP address/username pair whenever an authentication happens (edit topic, attach file). Once remembered, the non-authenticated scripts, like view, will show the correct username instead of TWikiGuest.
  • Enable this feature by setting the $doRememberRemoteUser flag in TWiki.cfg. TWiki then persistently stores the IP address/username pairs in the file, $remoteUserFilename, which is "$dataDir/remoteusers.txt" by default.
  • Copy the view script to viewauth (or better, create a symbolic link)
  • Add viewauth to the list of authenticated scripts in the twiki/bin/.htaccess file. The view script should not be listed in the .htaccess file.
  • ALERT! This approach can fail if the IP address changes due to dynamically assigned IP addresses or proxy servers.

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

TWiki Username vs. Login Username

This section applies only if your TWiki site is installed on a server that is both authenticated and on an intranet.

Galeon 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 Main 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.

  • ALERT! 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 Main web name in front of the Wiki username, followed by a period, and no spaces. Ex:
Main.WikiUsername or %MAINWEB%.WikiUsername
This points WikiUser to the Galeon.Main 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 Main web.

Changing Passwords

Change and reset passwords using forms on regular pages. Use TWikiAccessControl to restrict use as required.

Forgot your old password? Then use ResetPassword instead. Please only use ResetPassword in case you really forgot your password. Thank you.

Your WikiName: **
Old password: **
New password: **
Retype new password: **
     (Fields marked ** are required)

After submitting this form your password will be changed.

If you have questions please contact the TWiki webmaster tko@users.sourceforge.net.

Please only use this ResetPassword form in case you really forgot your password. Otherwise just change it using ChangePassword. Thank you.

Your WikiName: **
New password: **
Retype new password: **
     (Fields marked ** are required)

After submitting this form you will see a page with your new password appearing encrypted.

You will have to e-mail this information to the Wiki webmaster, tko@users.sourceforge.net, who will set your account to use the new password.

-- TWiki.Main.MikeMannix - 19 May 2002
-- TWiki.Main.PeterThoeny - 25 Apr 2004

Changed:
<
<

>
>


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:

  • WikiName and encrypted password are recorded in .htpasswd if authentication is enabled.
  • A confirmation e-mail is sent to the user.
  • A user home page with the WikiName of the user is created in the Main web.
  • The user is added to the TWikiUsers topic.

Users can be authenticated using Basic Authentication (htaccess) or SSL (secure server). In either case, TWikiUserAuthentication is required in order to track user identities, and use User and Group access control.

The default visitor name is TWikiGuest. This is the non-authenticated user.

Managing Groups

Groups are defined by group topics created in the Main web, like the TWikiAdminGroup. To create a new group:

  1. Edit TWikiGroups by entering a new topic with a name that ends in Group. Example:
    • SomeGroup
  2. Set Preferences for two Variables in the new group topic:
    • Set GROUP = < list of Users and/or Groups >
    • Set ALLOWTOPICCHANGE = < list of Users and/or Groups >
    • The GROUP variable is a comma-separated list of Users and/or other Groups. Example:
      • Set GROUP = Main.SomeUser, Main.OtherUser, Main.SomeGroup
    • ALLOWTOPICCHANGE defines who is allowed to change the group topic; it is a comma delimited list of Users and Groups. You typically want to restrict that to the members of the group itself, so it should contain the name of the topic. (This prevents Users not in the Group from editing the topic to give themselves or others access. For example, for the TWikiAdminGroup topic write:
    • Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup

Restricting Write Access

You can define who is allowed to make changes to a web or a topic.

Deny Editing by Topic

Denying editing of a topic also restricts file attachment; both privileges are assigned together.

  • Define one or both of these variables in a topic, preferably at the end of the page:
    • Set DENYTOPICCHANGE = < list of Users and Groups >
    • Set ALLOWTOPICCHANGE = < list of Users and Groups >

  • DENYTOPICCHANGE defines Users or Groups that are not allowed to make changes to the topic, with a comma-delimited list. Example:
    • Set DENYTOPICCHANGE = Main.SomeBadBoy, Main.SomeBadGirl, Main.SomeHackerGroup

  • ALLOWTOPICCHANGE defines Users or Groups that are allowed to make changes to the topic. It is a comma delimited list of Users and Groups. Example:
    • Set ALLOWTOPICCHANGE = Main.SomeGoodGuy, Main.SomeGoodGirl, Main.TWikiAdminGroup

  • DENYTOPICCHANGE is evaluated before ALLOWTOPICCHANGE. Access is denied if the authenticated person is in the DENYTOPICCHANGE list, or not in the ALLOWTOPICCHANGE list. Access is granted in case DENYTOPICCHANGE and ALLOWTOPICCHANGE is not defined.

Deny Editing by Web

Restricting web-level editing blocks creating new topics, changing topics or attaching files.

  • Define one or both of these variable in the WebPreferences topic:
    • Set DENYWEBCHANGE = < list of Users and Groups >
    • Set ALLOWWEBCHANGE = < list of Users and Groups >

The same rules apply as for restricting topics, with these additions:

  • DENYTOPICCHANGE (in topic) overrides DENYWEBCHANGE (in WebPreferences)
  • ALLOWTOPICCHANGE (in topic) overrides ALLOWWEBCHANGE (in WebPreferences)

Restricting Rename Access

You can define who is allowed to rename, move or delete a topic, or rename a web.

Deny Renaming by Topic

To allow a user to rename, move or delete a topic, they also need write (editing) permission. They also need write access to change references in referring topics.

  • Define one or both of these variables in a topic, preferably at the end of the topic:
    • Set DENYTOPICRENAME = < list of Users and Groups >
    • Set ALLOWTOPICRENAME = < list of Users and Groups >

  • DENYTOPICCRENAME defines Users or Groups that are not allowed to rename the topic. It is a comma delimited list of Users and Groups. Example:
    • Set DENYTOPICRENAME = Main.SomeBadBoy, Main.SomeBadGirl, Main.SomeHackerGroup

  • ALLOWTOPICRENAME defines Users or Groups that are allowed to rename the topic. It is a comma delimited list of Users and Groups. Example:
    • Set ALLOWTOPICRENAME = Main.SomeGoodGuy, Main.SomeGoodGirl, Main.TWikiAdminGroup

  • DENYTOPICRENAME is evaluated before ALLOWTOPICRENAME. Access is denied if the authenticated person is in the DENYTOPICRENAME list, or not in the ALLOWTOPICRENAME list. Access is granted in case DENYTOPICRENAME and ALLOWTOPICRENAME is not defined.

Deny Renaming by Web

You can define restrictions of who is allowed to rename a Galeon web.

  • Define one or both of these variable in the WebPreferences topic:
    • Set DENYWEBRENAME = < list of Users and Groups >
    • Set ALLOWWEBRENAME = < list of Users and Groups >

The same rules apply as for topics, with these additions:

  • DENYTOPICRENAME (in topic) overrides DENYWEBRENAME (in WebPreferences)
  • ALLOWTOPICRENAME (in topic) overrides ALLOWWEBRENAME (in WebPreferences)

Restricting Read Access

You can define who is allowed to see a web.

Deny Viewing by Topic

ALERT! Technically it is possible to restrict read access to an individual topic based on DENYTOPICVIEW / ALLOWTOPICVIEW preferences variables, provided that the view script is authenticated. However this setup is not recommended since all content is searchable within a web - a search will turn up view restricted topics.

Deny Viewing by Web

You can define restrictions of who is allowed to view a Galeon web. You can restrict access to certain webs to selected Users and Groups, by:

  • obfuscating webs: Insecure but handy method to hide new webs until content is ready for deployment.
  • authenticating all webs and restricting selected webs: Topic access in all webs is authenticated, and selected webs have restricted access.
  • authenticating and restricting selected webs only: Provide unrestricted viewing access to open webs, with authentication and restriction only on selected webs.

Obfuscate Webs

The idea is to keep a web hidden by not publishing its URL and by preventing the all webs search option from accessing obfuscated webs. Do so by enabling the NOSEARCHALL variable in WebPreferences:

  • Set NOSEARCHALL = on

This setup can be useful to hide a new web until content its ready for deployment.

ALERT! Obfuscating webs is insecure, as anyone who knows the URL can access the web.

Authenticate all Webs and Restrict Selected Webs

Use the following setup to authenticate users for topic viewing in all webs and to restrict access to selected webs:

  1. Restrict view access to selected Users and Groups. Set one or both of these variables in its WebPreferences topic:
    • Set DENYWEBVIEW = < list of Users and Groups >
    • Set ALLOWWEBVIEW = < list of Users and Groups >
    • Note: DENYWEBVIEW is evaluated before ALLOWWEBVIEW. Access is denied if the authenticated person is in the DENYWEBVIEW list, or not in the ALLOWWEBVIEW list. Access is granted in case DENYWEBVIEW and ALLOWWEBVIEW is not defined.
  2. Hide the web from an "all webs" search. Enable this restriction with the NOSEARCHALL variable in its WebPreferences topic:
    • Set NOSEARCHALL = on
  3. Add view to the list of authenticated scripts in the .htaccess file.

HELP This method only works if the view script is authenticated, which means that all Users have to login, even for read-only access. (An open guest account, like TWikiGuest, can get around this, allowing anyone to login to a common account with, for example, view-only access for public webs.) TWikiInstallationGuide has more on Basic Authentication, using the .htaccess file.

Authenticate and Restricting Selected Webs Only

Use the following setup to provide unrestricted viewing access to open webs, with authentication only on selected webs:

  1. Restrict view access to selected Users and Groups. Set one or both of these variables in its WebPreferences topic:
    • Set DENYWEBVIEW = < list of Users and Groups >
    • Set ALLOWWEBVIEW = < list of Users and Groups >
    • Note: DENYWEBVIEW is evaluated before ALLOWWEBVIEW. Access is denied if the authenticated person is in the DENYWEBVIEW list, or not in the ALLOWWEBVIEW list. Access is granted in case DENYWEBVIEW and ALLOWWEBVIEW is not defined.
  2. Hide the web from an "all webs" search. Enable this restriction with the NOSEARCHALL variable in its WebPreferences topic:
    • Set NOSEARCHALL = on
  3. Enable the $doRememberRemoteUser flag in lib/TWiki.cfg as described in TWikiUserAuthentication. Galeon will now remember the IP address of an authenticated user.
  4. Copy the view script to viewauth (or better, create a symbolic link)
  5. Add viewauth to the list of authenticated scripts in the .htaccess file. The view script should not be listed in the .htaccess file.

When a user accesses a web where you enabled view restriction, Galeon will redirect from the view script to the viewauth script once (this happens only if the user has never edited a topic). Doing so will ask for authentication. The viewauth script shows the requested topic if the user could log on and if the user is authorized to see that web.

ALERT! Authenticating webs is not very secure, as there is a way to circumvent the read access restriction. It can be useful in certain situations - for example, to simplify site organization and clutter, by hiding low traffic webs - but is not recommended for securing sensitive content.

Hiding Control Settings

TIP To hide access control settings from normal browser viewing, place them in comment markers.

<!--
   * Set DENYTOPICCHANGE = Main.SomeGroup
-->

The SuperAdminGroup

By mistyping a user or group name in the ALLOWTOPICCHANGE setting, it's possible to lock a topic so that no-one can edit it from a browser. To avoid this, you can create Web-based superusers:

  • Set the $superAdminGroup variable in lib/TWiki.cfg to the name of a group of Users who are always allowed to edit/view topics.
$superAdminGroup = "TWikiAdminGroup";
  • The default setting is not to have superusers.

-- PeterThoeny - 04 May 2002
-- MikeMannix? - 12 May 2002

Changed:
<
<

TWiki Templates

Definition of the templates used to render all HTML pages displayed in TWiki

Overview

The new modular template system offers flexible, easy control over the layout of all TWiki pages. The master template approach groups parts that are shared by several templates - like headers and footers - in a common file. Special variables allow individual layouts to include parts from a master template - variables are mixed with regular HTML markup for template-specific content. Templates are used to define page layout, and also to supply default content for new pages.

Major changes from the previous template system

Where the old templates were each complete HTML documents, the new templates are defined using variables to include template parts from a master file. You can now change one instance of a common element to update all occurrences; previously, every affected template had to be updated. This simplifies the conversion of templates into XHTML format, and provides a more versatile solution for templates and for TWikiSkins. The new system:

  • separates a set of common template parts into a base template that is included by all of the related templates;
  • defines common variables, like a standard separator (ex: "|"), in the base template;
  • defines variable text in the individual templates and passes it back to the base template.

How Template Variables Work

  • Special template directives (or preprocessor commands) are embedded in normal templates.
  • All template preprocessing is done in &TWiki::Store::readTemplate() so that the caller simply gets an expanded template file (the same as before).
  • Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
  • Directives:
    • %TMPL:INCLUDE{"file"}%: Includes a template file. The template directory of the current web is searched first, then the templates root (twiki/templates).
    • %TMPL:DEF{"var"}%: Define a variable. Text between this and the END directive is not returned, but put into a hash for later use.
    • %TMPL:END%: Ends variable definition.
    • %TMPL:P{"var"}%: Prints a previously defined variable.
  • Variables live in a global name space: there is no parameter passing.
  • Two-pass processing lets you use a variable before or after declaring it.
  • Templates and TWikiSkins work transparently and interchangeably. For example, you can create a skin that overloads only the twiki.tmpl master template, like twiki.print.tmpl, that redefines the header and footer.
  • HELP Use of template directives is optional: templates work without them.
  • ALERT! NOTE: Template directives work only for templates: they do not get processed in topic text.

Types of Template

There are three types of template:

  • Master Template: Stores common parts; included by other templates
  • HTML Page Templates: Defines the layout of Galeon pages
  • Template Topics: Defines default text when you create a new topic

Master Templates

Common parts, appearing in two or more templates, can be defined in a master template and then shared by others: twiki.tmpl is the default master template.

Template variable: Defines:
%TMPL:DEF{"sep"}% "|" separator
%TMPL:DEF{"htmldoctype"}% Start of all HTML pages
%TMPL:DEF{"standardheader"}% Standard header (ex: view, index, search)
%TMPL:DEF{"simpleheader"}% Simple header with reduced links (ex: edit, attach, oops)
%TMPL:DEF{"standardfooter"}% Footer, excluding revision and copyright parts
%TMPL:DEF{"oops"}% Skeleton of oops dialog

HTML Page Templates

Galeon uses HTML template files for all actions, like topic view, edit, and preview. This allows you to change the look and feel of all pages by editing just a few template files.

Templates are in the twiki/templates directory. As an example, twiki/templates/view.tmpl is the template file for the twiki/bin/view script. Templates can be overloaded by individual webs. The following search order applies:

  1. twiki/templates/$webName/$scriptName.tmpl
  2. twiki/templates/$scriptName.tmpl
    • $webName is the name of the web (ex: Main)
    • $scriptName is the script (ex: view).

HELP NOTE: TWikiSkins can be defined to overload the standard templates.

Special variables are used in templates, especially in view, to display meta data.

Template Topics

Template topics define the default text for new topics. There are three types of template topic:

Topic Name: What it is:
WebTopicViewTemplate Error page shown when you try to view a nonexistent topic
WebTopicNonWikiTemplate Alert page shown when you try to view a nonexistent topic with a non-WikiName
WebTopicEditTemplate Default text shown when you create a new topic.
All template topics are located in the TWiki web. The WebTopicEditTemplate can be overloaded. When you create a new topic, TWiki locates a topic to use as a content template according to the following search order:

  1. A topic name specified by the templatetopic CGI parameter.
  2. WebTopicEditTemplate in the current web
  3. WebTopicEditTemplate in the TWiki web

Edit Template Topics and Variable Expansion

The following variables get expanded when a user creates a new topic based on a template topic:

Variable: Description:
%DATE% Current date, e.g. 20 Nov 2017
%USERNAME% Login name, e.g. jsmith
%WIKINAME% WikiName of user, e.g. JohnSmith
%WIKIUSERNAME% User name, e.g. Main.JohnSmith
%URLPARAM{"name"}% Value of a named URL parameter
%NOP% A no-operation variable that gets removed. Useful to prevent a SEARCH from hitting an edit template topic; also useful to escape a variable like %URLPARAM%NOP%{...}%
%NOP{ ... }% A no-operation text that gets removed. Useful to write-protect an edit template topic, but not the topics based this template topic. See notes below. Example:
%NOP{
   * Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup
}%

Notes:

  • Unlike other variables, %NOP{ ... }% can span multiple lines.
  • The scan for the closing }% pattern is "non-greedy", that is, it stops at the first occurance. That means, you need to escape variables with parameters located inside %NOP{ ... }%: Insert a %NOP% between } and %. Silly example: %NOP{ %GMTIME{"$year"}%NOP%% }%.

All other variables are unchanged, e.g. are carried over "as is" into the new topic.

Template Topics in Action

Here is an example for creating new topics based on a specific template topic:

  • New example topic: (date format is YYYYxMMxDD)

The above form asks for a topic name. A hidden input tag named templatetopic specifies ExampleTopicTemplate as the template topic to use. Here is the HTML source of the form:

<form name="new" action="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%INTURLENCODE{"%WEB%"}%/">
   * New example topic: 
     <input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="23" />
     <input type="hidden" name="templatetopic" value="ExampleTopicTemplate" />
     <input type="hidden" name="topicparent" value="%TOPIC%" />
     <input type="hidden" name="onlywikiname" value="on" />
     <input type="hidden" name="onlynewtopic" value="on" />
     <input type="submit" value="Create" />
     (date format is <nop>YYYYxMMxDD)
</form>

The edit scipt understands the following parameters, typically supplied by HTML input fields:

Parameter: Description:
topic Name of topic to create. Can be set in a text field, or is set programmatically (e.g. with a sequential number)
onlywikiname If set, TWiki will complain if the topic name is not a WikiWord
onlynewtopic If set, TWiki will complain if a topic of the same name already exists
templatetopic The name of the template topic, e.g. topic used to copy the initial content
topicparent Sets the parent topic
TopicClassification Assuming the template topic has a form with a field called "TopicClassification", it will set the value of the field
anyname Any parameter can passed to the new topic; if the template topic contains %URLPARAM{"anyname"}%, it will be replaced by its value

TIP TIP: You can use the %WIKIUSERNAME% and %DATE% variables in your topic templates to include the signature of the person creating a new topic. The variables are expanded into fixed text when a new topic is created. The standard signature is:
-- %WIKIUSERNAME% - %DATE%

Templates by Example

Attached is an example of an oops based template oopsbase.tmpl and an example oops dialog oopstest.tmpl based on the base template. %A% NOTE: This isn't the release version, just a quick, simple demo.

Base template oopsbase.tmpl

The first line declares a delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing %TMPL:P{"sep"}%

%TMPL:DEF{"sep"}% | %TMPL:END%
<html>
<head>
  <title> %WIKITOOLNAME% . %WEB% . %TOPIC% %.TMPL:P{"titleaction"}%</title>
  <base href="%SCRIPTURL%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%">
  <meta name="robots" content="noindex">
</head>
<body bgcolor="#FFFFFF">
<table width="100%" border="0" cellpadding="3" cellspacing="0">
  <tr>
    <td bgcolor="%WEBBGCOLOR%" rowspan="2" valign="top" width="1%">
      <a href="%WIKIHOMEURL%">
      <img src="%PUBURLPATH%/wikiHome.gif" border="0"></a>
    </td>
    <td>
      <b>%WIKITOOLNAME% . %WEB% . </b><font size="+2">
      <B>%TOPIC%</b> %TMPL:P{"titleaction"}%</font>
    </td>
  </tr>
  <tr bgcolor="%WEBBGCOLOR%">
    <td colspan="2">
      %TMPL:P{"webaction"}%
    </td>
  </tr>
</table>
--- ++ %TMPL:P{"heading"}%
%TMPL:P{"message"}%
<table width="100%" border="0" cellpadding="3" cellspacing="0">
  <tr bgcolor="%WEBBGCOLOR%">
    <td valign="top">
      Topic <b>%TOPIC%</b> . {
        %TMPL:P{"topicaction"}%
      }
    </td>
  </tr>
</table>
</body>

Test template oopstest.tmpl

Each oops template basically just defines some variables and includes the base template that does the layout work.

%TMPL:DEF{"titleaction"}% (test =titleaction=) %TMPL:END%
%TMPL:DEF{"webaction"}% test =webaction= %TMPL:END%
%TMPL:DEF{"heading"}%
Test heading %TMPL:END%
%TMPL:DEF{"message"}%
Test =message=. Blah blah blah blah blah blah blah blah blah blah blah...

   * Some more blah blah blah blah blah blah blah blah blah blah...
   * Param1: %PARAM1%
   * Param2: %PARAM2%
   * Param3: %PARAM3%
   * Param4: %PARAM4%
%TMPL:END%
%TMPL:DEF{"topicaction"}%
Test =topicaction=:
[[%WEB%.%TOPIC%][OK]] %TMPL:P{"sep"}%
[[%TWIKIWEB%.TWikiRegistration][Register]] %TMPL:END%
%TMPL:INCLUDE{"oopsbase"}%

Sample screen shot of oopstest.tmpl

With URL: .../bin/oops/Sandbox/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify

testscreen.gif

Known Issues

  • A drawback of referring to a master template is that you can only test a template from within TWiki, where the include variables are resolved. In the previous system, each template was a structurally complete HTML document with a .tmpl filename extension - it contained unresolved %VARIABLES%, but could still be previewed directly in a browser.

-- TWiki:Main.PeterThoeny - 25 Apr 2004
-- TWiki:Main.MikeMannix - 14 Sep 2001
-- TWiki:Main.DavidLeBlanc - 11 Mar 2002


TWiki Skins

Skins overlay regular templates with alternate header/footer layouts; topic text is not affected

Overview

Skins are customized TWikiTemplates files. You can use skins to change the look of a Galeon topic, for example, the layout of the header and footer. Rendered text between header and footer does not change. You can also use skins to define an alternate view, like a view optimized for printing.

Defining Skins

Skin files are located in the twiki/templates directory and are named with the syntax: <scriptname>.<skin>.tmpl. For example, the Printable skin for the view template is view.print.tmpl.

Use the existing TWikiTemplates (like view.tmpl) or skin files as a base for your own skin, name it for example view.myskin.tmpl.

Variables in Skins

You can use template variables, TWikiVariables, and other predefined variables to compose your skins. Some commonly used variables in skins:

Variable: Expanded to:
%WIKILOGOURL% Link of page logo
%WIKILOGOIMG% Image URL of page logo
%WIKILOGOALT% Alt text of page logo
%WEBBGCOLOR% Web specific background color, defined in the WebPreferences
%WIKITOOLNAME% The name of your TWiki site
%SCRIPTURL% The script URL of TWiki
%SCRIPTSUFFIX% The script suffix, ex: .pl, .cgi
%WEB% The name of the current web. Note: It is recommended to URL-encode the variable in form actions with %INTURLENCODE{"%WEB%"}% for proper handling in an internationalized environment
%TOPIC% The name of the current topic. Note: It is recommended to URL-encode the variable in form actions with %INTURLENCODE{"%TOPIC%"}% for proper handling in an internationalized environment
%WEBTOPICLIST% Common links of current web, defined in the WebPreferences. It includes a #GoBox
%TEXT% The topic text, e.g. the content that can be edited
%META{"form"}% TWikiForm, if any
%META{"attachments"}% FileAttachment table
%META{"parent"}% The topic parent
%EDITTOPIC% Edit link
%REVTITLE% The revision title, if any, ex: (r1.6)
%REVINFO% Revision info, ex: r1.6 - 24 Dec 2002 - 08:12 GMT - TWikiGuest
%WEBCOPYRIGHT% Copyright notice, defined in the WebPreferences
%BROADCASTMESSAGE% Broadcast message at the beginning of your view template, can be used to alert users of scheduled downtimes; is set in TWikiPreferences

The "Go" Box and Navigation Box

The %WEBTOPICLIST% includes a "Go" box to jump to a topic. The box also understand URLs, e.g. you can type http://www.google.com/ to jump to an external web site. The feature is handy if you build a skin that has a select box of frequently used links, like Intranet home, employee database, sales database and such. A little JavaScript gets into action on the onSelect method of the select tag to fill the selected URL into the "Go" box field, then submits the form.

Here is an example form that has a select box and the "Go" box for illustration purposes. You need to have JavaScript enabled for this to work:

Bare bones header for demo only
Welcome | Register | Topics | Search | Go

Using Cascading Style Sheets

The regular templates files currently do not use style sheets. Many skin developers choose to use them, it helps in separating style from content.

Example: To use a style sheet for the broadcast message, add this to view.myskin.tmpl:

<style type="text/css">
.broadcastmessage {
    background: yellow; display:block;
    border-style:solid;border-width: 2px;border-color:red;
}
.broadcastmessage strong {color: red}
</style>

Then add a div tag to the %BROADCASTMESSAGE% variable located after the #PageTop anchor or after the opening form tag:

<div class="broadcastmessage"> %BROADCASTMESSAGE% </div>

Packaging and Publishing Skins

See TWiki:Plugins/SkinPackagingHowTo and TWiki:Plugins/SkinDeveloperFAQ

Activating Skins

A skin can be activated in two ways:

The ?skin=name URL parameter overrides the SKIN Preference value.

-- PeterThoeny - 05 Jan 2003

>
>

TWiki Text Formatting

http://naked-girls.chiki-piki.com/index.html http://rape-pics.chiki-piki.com/index.html http://shemale.chiki-piki.com/index.html http://paris-hilton.chiki-piki.com/index.html http://incest.chiki-piki.com/index.html http://hentai.chiki-piki.com/index.html http://mature-women.chiki-piki.com/index.html http://britney-spears.chiki-piki.com/index.html http://nude-celebrities.chiki-piki.com/index.html http://hustler.chiki-piki.com/index.html http://gay-sex.chiki-piki.com/index.html http://lesbian-sex.chiki-piki.com/index.html http://beastiality.chiki-piki.com/index.html

http://beastiality.horse.dyn.agat.net

Working in TWiki is as easy as typing in text - exactly like email. You don't need to know HTML, though you can use it if you prefer. Links to topics are created automatically when you enter WikiWords. And TWiki shorthand gives you all the power of HTML with a simple coding system that takes no time to learn. It's all laid out below - refer back to this page in a pop-up window from the Edit screen.

TWiki Editing Shorthand

Formatting Command: Example: You write: You get:
Paragraphs:
Blank lines will create new paragraphs.
1st paragraph

2nd paragraph
1st paragraph

2nd paragraph

Headings:
At least three dashes at the beginning of a line, followed by plus signs and the heading text. One plus creates a level 1 heading (most important), two pluses a level 2 heading; the maximum is level 6. Note: A Table of Content can be created automatically with the %TOC% variable, see TWikiVariables. Any heading text after !! is excluded from the TOC; for example, write ---+!! text if you do not want to list a header in the TOC.
---++ Sushi

---+++ Maguro

Sushi

Maguro

Bold Text:
Words get bold by enclosing them in * asterisks.
*Bold*
Bold
Italic Text:
Words get italic by enclosing them in _ underscores.
_Italic_
Italic
Bold Italic:
Words get _bold italic by enclosing them in _ double-underscores.
__Bold italic__
Bold italic
Fixed Font:
Words get shown in fixed font by enclosing them in = equal signs.
=Fixed font=
Fixed font

Bold Fixed Font:
Words get shown in bold fixed font by enclosing them in double equal signs.
==Bold fixed==
Bold fixed
Note: Make sure there is no space between the text and the bold, italic, or other indicators (* _ __ = ==).
_This works_,
_this not _
This works,
_this not _
Verbatim Mode:
Surround code excerpts and other formatted text with <verbatim> and </verbatim> tags.
Note: Use <pre> and </pre> tags instead if you want that HTML code is interpreted.
Note: Each tag must be on a line by itself.
<verbatim>
class CatAnimal {
  void purr() {
    <code here>
  }
}
</verbatim>
class CatAnimal {
  void purr() {
    <code here>
  }
}
Separator:
At least three dashes at the beginning of a line.
-------

List Item:
Three spaces, an asterisk, and another space.
   * bullet item
  • bullet item
Nested List Item:
Six, nine, ... spaces, an asterisk, and another space.
   * level 1
      * level 2
  • level 1
    • level 2
Ordered List:
Three spaces, a number, a dot, and another space. Several types are available besides a number:
Type Generated Style Sample Sequence
1. Arabic numerals 1, 2, 3, 4...
A. Uppercase letters A, B, C, D...
a. Lowercase letters a, b, c, d...
I. Uppercase Roman Numerals I, II, III, IV...
i. Lowercase Roman Numerals i, ii, iii, iv...

   1. Sushi
   1. Dim Sum

   A. Sushi
   A. Dim Sum

   i. Sushi
   i. Dim Sum
  1. Sushi
  2. Dim Sum

  1. Sushi
  2. Dim Sum

  1. Sushi
  2. Dim Sum
Definition List:
Three spaces, a dollar sign, the term, a colon, a space, followed by the definition.
   $ Sushi: Japan
   $ Dim Sum: S.F.
Sushi
Japan
Dim Sum
S.F.
Table:
Any number of lines of text. Each line is one row of the table consisting of one or more cells. Each cell starts and ends with a vertical bar '|'. Any spaces at the beginning of a line are ignored.
Notes:
| *bold* | cells are displayed as table headers.
|   center-spaced   | cells are displayed center aligned.
|     right-spaced | cells are displayed right aligned.
| 2 colspan || cells are displayed as multi-span columns (i.e., a cell with no text spans a column).
|^| cells with a caret indicate follow-up rows of multi-span rows (this functionality is provided by TablePlugin).
• If a row contains a large amount of text, and you want it to be more readable while editing the table, split the row into multiple text lines by ending each line with a backslash character '\'.
• Table cells wrap automatically as determined by the browser.
| *L* | *C* | *R* |
| A2 |  2  |  2 |
| A3 |  3  |  3 |
| multi span |||
| A4-6 | four | four |
|^| five | five |



|^| six | six |
L C R
A2 2 2
A3 3 3
multi span
A4-6 four four
five five
six six
WikiWord Links:
CapitalizedWordsStuckTogether (or WikiWords) will produce a link automatically.
Note: In case you want to link to a topic in a different Galeon web write Webname.TopicName.
WebNotify

Know.ReadmeFirst
WebNotify

ReadmeFirst?

Forced Links:
You can create a forced internal link by enclosing words in double square brackets.
Note: Text within the brackets may contain optional spaces; the topic name is formed by capitalizing the initial letter and by removing the spaces; for example, [[text formatting FAQ]] links to topic TextFormattingFAQ. You can also refer to a different web and use anchors.
Note: To "escape" double square brackets that would otherwise be a correct link, prefix the leading left square brackets with an exclamation point, that is, begin with ![[....
[[wiki syntax]]

[[Main.TWiki users]]

escaped:
![[wiki syntax]]
wiki syntax

Main.TWiki users

escaped: [[wiki syntax]]

Specific Links:
Create a link where you can specify the link text and the link reference separately, using nested square brackets like [[reference][text]]. Internal link references (e.g. WikiSyntax) and external link references (e.g. http://TWiki.org/) are supported.
Note: The same Forced Links rules apply for internal link references.
Note: For external link references, you can simply use a space instead of ][ to separate the link URL from the descriptive text.
Note: Anchor names can be added as well, like [[Home#MyAnchor][go home]] and [[http://gnu.org/#Action][GNU Action]].
[[WikiSyntax][syntax]]

[[http://gnu.org][GNU]]

[[http://xml.org XML]]
syntax

GNU

XML

Anchors:
You can define a link reference inside a Galeon topic (called an anchor name) and link to that. To define an anchor write #AnchorName at the beginning of a line. The anchor name must be a WikiWord. To link to an anchor name use the [[MyTopic#MyAnchor]] syntax. You can omit the topic name if you want to link within the same topic.
[[WikiWord#NotThere]]

[[#MyAnchor][Jump]]

#MyAnchor To here
WikiWord#NotThere

Jump

To here

Prevent a Link:
Prevent a WikiWord from being linked by prepending it with an exclamation point.
!SunOS
SunOS
Disable Links:
You can disable automatic linking of WikiWords by surrounding text with <noautolink> and </noautolink> tags.
Note: Each tag must be on a line by itself.
Note: This also works for TWiki tables, but only if you add a blank line between the end of the table and the closing </noautolink> tag (known issue of the TablePlugin).
 <noautolink>
 RedHat &
 SuSE
 </noautolink>
RedHat & SuSE
Mailto: Links:
To create 'mailto:' links that have more descriptive link text, specify subject lines or message bodies, or omit the email address, you can write [[mailto:user@domain descriptive text]].
[[mailto:a@z.com Mail]]

[[mailto:?subject=Hi Hi]]
Mail

Hi

Using HTML

You can use just about any HTML tag without a problem - however, there are a few usability and technical considerations to keep in mind.

HTML and TWiki Usability

  • On collaboration pages, it's preferable NOT to use HTML, and to use TWiki shorthand instead - this keeps the text uncluttered and easy to edit.
  • ALERT! NOTE: TWiki is designed to work with a wide range of browsers and computer platforms, holding to HTML 3.2 compatibility in the standard installation - adding raw HTML, particularly browser-specific tags (or any other mark-up that doesn't degrade well) will reduce compatibility.

TWiki HTML Rendering

  • TWiki converts shorthand notation to XHTML 1.0 for display. To copy a fully marked-up page, simply view source in your browser and save the contents.
    • TIP If you need to save HTML frequently, you may want to check out TWiki:Plugins/GenHTMLAddon - it will "generate a directory containing rendered versions of a set of TWiki pages together with any attached files."
  • ALERT! NOTE: The opening and closing angle brackets - <...> - of an HTML tag must be on the same line, or the tag will be broken.
    • This feature allows you to enter an unclosed angle bracket - as a greater than or less than symbol - and have it automatically rendered as if you had entered its HTML character, &lt;, ex: a < b
    • TIP If you're pasting in preformatted HTML text and notice problems, check the file in a text processor with no text wrap. Also, save without hard line breaks on text wrap, in your HTML editing program.

TWiki and JavaScript

You can use JavaScript for your TWiki applications. Since TWiki rendering might interfere with JavaScript code you need to escape it with HTML comments and <pre> tags:

<script language="JavaScript">
<!-- Hide JavaScript and <pre> escape TWiki rendering
... put your JavaScript code here...
// Stop hiding and stop </pre> escaping TWiki rendering -->
</script>

Hyperlinks

Being able to create links without any formatting required is a core TWiki feature, made possible with WikiWords. New TWiki linking rules are a simple extension of the syntax that provide a new set of flexible options.

Internal Links

  • GoodStyle is a WikiWord that links to the GoodStyle topic located in the current Galeon web.

  • NotExistingYet? is a topic waiting to be written. Create the topic by clicking on the ?. (Try clicking, but then, Cancel - creating the topic would wreck this example!)

External Links

  • http://..., https://..., ftp://..., gopher://..., news://..., file://..., telnet://... and mailto:...@... are linked automatically.

  • Email addresses like name@domain.com are linked automatically.

  • [[Square bracket rules]] let you easily create non-WikiWord links.
    • You can also write [[http://www.website.com website]] as an easier way of doing external links with descriptive text for the link, such as website.

TWiki Variables

Variables are names that are enclosed in percent signs % that are expanded on the fly.

  • %TOC% : Automatically generates a table of contents based on headings in a topic - see the top of this page for an example.

  • %WEB% : The current web, is TWiki.

  • %TOPIC% : The current topic name, is TextFormattingRules.

  • %ATTACHURL% : The attachment URL of the current topic. Example usage: If you attach a file to a topic you can refer to it as %ATTACHURL%/image.gif to show the URL of the file or the image in your text.

  • %INCLUDE{"SomeTopic"}% : Server side include, includes another topic. The current Galeon web is the default web. Example: %INCLUDE{"TWiki.SiteMap"}%

  • %SEARCH{"sushi"}% : Inline search showing the search result embedded in a topic. FormattedSearch gives you control over formatting, used to create web-based applications.

  • TWikiPreferences defines site-wide variables. Among others:
    • Line break: Write %BR% to start a new line.
    • Colored text: Write: %RED% Red %ENDCOLOR% and %BLUE% blue %ENDCOLOR% colors to get: Red and blue colors.
    • Documentation Graphics: Write: %H% Help, %T% Tip, %X% Alert to get: HELP Help, TIP Tip, ALERT! Alert. For more info see TWikiDocGraphics.

  • To "escape" a variable, prefix it with an exclamation point. Write: !%SOMEVARIABLE% to get: %SOMEVARIABLE%.

TWikiPlugin Formatting Extensions

Plugins provide additional text formatting capabilities and can extend the functionality of Galeon into many other areas. For example, the optional SpreadSheetPlugin lets you create a spreadsheet with the same basic notation used in TWiki tables.

Available Plugins are located in the Plugins web on TWiki.org. Currently enabled plugins on this TWiki installation, as listed by %PLUGINDESCRIPTIONS%:

  • DefaultPlugin: This plugin can be used to specify some simple custom rendering rules. It also renders depreciated *_text_* as bold italic text.
  • SpreadSheetPlugin: Add spreadsheet calculation like "$SUM( $ABOVE() )" to tables located in Galeon topics.
  • EditTablePlugin: Edit TWiki tables using edit fields, date pickers and drop down boxes
  • InterwikiPlugin: Link ExternalSite:Page text to external sites based on aliases defined in the InterWikis topic
  • RenderListPlugin: Render bullet lists in a variety of formats
  • SlideShowPlugin: Create web based presentations based on topics with headings.
  • SmiliesPlugin: Render smilies as icons, like  :-) for smile or  :cool: for cool!
  • TablePlugin: Control attributes of tables and sorting of table columns

Check on current Plugin status and settings for this site in TWikiPreferences.

Common Editing Errors

TWiki formatting rules are fairly simple to use and quick to type. However, there are some things to watch out for, taken from the TextFormattingFAQ:

  • Q: Text enclosed in angle brackets like <filename> is not displayed. How can I show it as it is?
    • A: The '<' and '>' characters have a special meaning in HTML, they define HTML tags. You need to escape them, so write '&lt;' instead of '<', and '&gt;' instead of '>'.
      Example: Type 'prog &lt;filename&gt;' to get 'prog <filename>'.

  • Q: Why is the '&' character sometimes not displayed?
    • A: The '&' character has a special meaning in HTML, it starts a so called character entity, i.e. '&copy;' is the © copyright character. You need to escape '&' to see it as it is, so write '&amp;' instead of '&'.
      Example: Type 'This &amp; that' to get 'This & that'.

-- TWiki:Main.MikeMannix - 02 Dec 2001
-- TWiki:Main.PeterThoeny - 25 Apr 2004


Changed:
<
<

>
>


TWiki Variables

Special text strings expand on the fly to display user data or system info

TWikiVariables are text strings - %VARIABLE% - that expand into content whenever a page is opened. When a topic is rendered for viewing, VARIABLES are replaced by data, either user-entered, or info automatically generated by TWiki (like the date, or the current username). There are predefined variables, and Preference variables that you configure. You can also define custom variables, with new names and values.

Note: To leave a variable unexpanded, preceed it with an exclamation point, e.g. type !%TOPIC% to get %TOPIC%.

Predefined Variables

Most predefined variables return values that were either set in the lib/twiki.cfg file, when TWiki was installed, or taken from server info (like current username, or date and time). Many of the variables let you format the appearance of the display results.

  • TIP Take the time to thoroughly read through ALL preference variables. If you actively configure your site, review variables periodically. They cover a wide range of functions, and it can be easy to miss the one perfect variable for something you have in mind. For example, see %INCLUDINGTOPIC%, %INCLUDE%, and the mighty %SEARCH%.

This version of TWiki - 07 May 2004 - expands the following variables (enclosed in % percent signs):

ATTACHURL -- attachment URL of the current topic

ATTACHURLPATH -- path of the attachment URL of the current topic

BASETOPIC -- base topic where an INCLUDE started

  • The name of the topic where a single or nested INCLUDE started - same as %TOPIC% if there is no INCLUDE
  • Syntax: %BASETOPIC%
  • Related: BASEWEB, INCLUDINGTOPIC, INCLUDE, TOPIC

BASEWEB -- base web where an INCLUDE started

  • The web name where the includes started, e.g. the web of the first topic of nested includes. Same as %WEB% in case there is no include.
  • Syntax: %BASEWEB%
  • Related: BASETOPIC, INCLUDINGWEB, INCLUDE, WEB

DISPLAYTIME -- display time

DISPLAYTIME{"format"} -- formatted display time

  • Formatted time - either GMT or Local server time, depending on setting in TWiki.cfg. Same format qualifiers as %GMTIME%
  • Syntax: %DISPLAYTIME{"format"}%
  • Example: %DISPLAYTIME{"$hou:$min"}% expands to 11:34
  • Related: DISPLAYTIME, GMTIME, SERVERTIME

ENCODE{"string"} -- encodes a string

  • Syntax: %ENCODE{"string"}%
  • Supported parameters:
    Parameter: Description: Default:
    "string" String to encode required (can be empty)
    type="entity" Encode special characters into HTML entities, like a double quote into &#034; URL encoding
    type="url" Encode special characters for URL parameter use, like a double quote into %22 (this is the default)
  • Example: %ENCODE{"spaced name"}% expands to spaced%20name
  • Related: URLPARAM

GMTIME -- GM time

GMTIME{"format"} -- formatted GM time

  • Syntax: %GMTIME{"format"}%
  • Supported variables:
    Variable: Unit: Example
    $seconds seconds 59
    $minutes minutes 59
    $hours hours 23
    $day day of month 31
    $wday day of the Week (Sun, Mon, Tue, Wed, Thu, Fri, Sat) Thu
    $month month in ISO format Dec
    $mo 2 digit month 12
    $year 4 digit year 1999
    $ye 2 digit year 99
    $tz either "GMT" (if set to gmtime), or "Local" (if set to servertime) GMT
    $iso ISO format timestamp 2017-11-20T11:34Z
    $rcs RCS format timestamp 2017/11/20 11:34:20
    $http E-mail & http format timestamp Mon, 20 Nov 2017 11:34:20 GMT
  • Variables can be shortened to 3 characters
  • Example: %GMTIME{"$day $month, $year - $hour:$min:$sec"}% expands to 20 Nov, 2017 - 11:34:20
  • Related: DISPLAYTIME, GMTIME, SERVERTIME

HOMETOPIC -- home topic in each web

HTTP_HOST -- environment variable

ICON{"type"} -- small icon of common attachment types

  • Small 16x16 pixel icon of common attachment types. Specify file type only, file name, or full path name
  • Syntax: %ICON{"type"}%
  • Samples: bmp, doc, gif, hlp, html, mp3, pdf, ppt, txt, xls, xml, zip
  • Example: %ICON{"pdf"}% expands to
  • Related: TWikiPreferences, FileAttachments, TWikiDocGraphics

INCLUDE{"page"} -- include other topics or web pages

  • Syntax: %INCLUDE{"page" ...}%
  • Supported parameters:
    Parameter: Description: Default:
    "SomeTopic" The name of a topic located in the current web, i.e. %INCLUDE{"WebNotify"}%  
    "Web.Topic" A topic in another web, i.e. %INCLUDE{"TWiki.SiteMap"}%  
    "http://..." A full qualified URL, i.e. %INCLUDE{"http://twiki.org/"}%  
    pattern="..." A RegularExpression pattern to include a subset of a topic or page none
    rev="1.2" Include a previous topic revision; N/A for URLs top revision
    warn="off" Warn if topic include fails: Fail silently (if off); output default warning (if set to on); else, output specific text (use $topic for topic name) %INCLUDE- WARNING% preferences setting
  • Related: BASETOPIC, BASEWEB, INCLUDINGTOPIC, INCLUDINGWEB, IncludeTopicsAndWebPages

INCLUDINGTOPIC -- name of topic that includes current topic

  • The name of the topic that includes the current topic - same as %TOPIC% in case there is no include
  • Syntax: %INCLUDINGTOPIC%
  • Related: BASETOPIC, INCLUDINGWEB, INCLUDE, TOPIC

INCLUDINGWEB -- web that includes current topic

  • The web name of the topic that includes the current topic - same as %WEB% if there is no INCLUDE.
  • Syntax: %INCLUDINGWEB%
  • Related: BASEWEB, INCLUDINGTOPIC, INCLUDE, WEB

MAINWEB -- name of Main web

METASEARCH -- special search of meta data

  • Syntax: %METASEARCH{...}%
  • Supported parameters:
    Parameter: Description: Default:
    type="topicmoved" What sort of search is required?
    "topicmoved" if search for a topic that may have been moved
    "parent" if searching for topics that have a specific parent i.e. its children
    required
    web="%WEB%" Wiki web to search: A web, a list of webs separated by whitespace, or all webs. required
    topic="%TOPIC%" The topic the search relates to required
    title="Title" Text that is prepended to any search results required
  • Example: %METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%" title="This topic used to exist and was moved to: "}%
  • Example: You may want to use this in WebTopicViewTemplate and WebTopicNonWikiTemplate:
    %METASEARCH{type="parent" web="%WEB%" topic="%TOPIC%" title="Children: "}%
  • Related: SEARCH

NOTIFYTOPIC -- name of the notify topic

PUBURL -- the base URL of attachments

  • Syntax: %PUBURL%
  • Expands to: http://galeon.sourceforge.net/twiki/pub
  • Example: You can refer to a file attached to another topic with %PUBURL%/%WEB%/OtherTopic/image.gif
  • Related: ATTACHURL, PUBURLPATH, SCRIPTURL, FileAttachments

PUBURLPATH -- the base URL path of attachments

REMOTE_ADDR -- environment variable

REMOTE_PORT -- environment variable

REMOTE_USER -- environment variable

SCRIPTURL -- script URL of Galeon

  • Syntax: %SCRIPTURL%
  • Expands to: http://galeon.sourceforge.net
  • Example: To get the authenticated version of current topic write %SCRIPTURL%/viewauth%SCRIPTSUFFIX%/%WEB%/%TOPIC% which expands to http://galeon.sourceforge.net/viewauth/TWiki/TWikiVariables
  • Related: PUBURL, SCRIPTSUFFIX, SCRIPTURLPATH

SCRIPTURLPATH -- script URL path of Galeon

SCRIPTSUFFIX -- script suffix

  • Some Galeon installations require a file extension for CGI scripts like .pl or .cgi
  • Syntax: %SCRIPTSUFFIX%
  • Expands to:
  • Related: SCRIPTURL

SEARCH{"text"} -- search content

  • Inline search, shows a search result embedded in a topic
  • Syntax: %SEARCH{"text" ...}%
  • Supported parameters: [1]
    Parameter: Description: Default:
    "text" Search term. Is a keyword search, literal search or regular expression search, depending on the type parameter. SearchHelp has more required
    search="text" (Alternative to above) N/A
    web="Name"
    web="Main, Know"
    web="all"
    Wiki web to search: A web, a list of webs separated by comma, or all webs. [2] Current web
    topic="WebPreferences"
    topic="*Bug"
    Limit search to topics: A topic, a topic with asterisk wildcards, or a list of topics separated by comma. All topics in a web
    excludetopic="Web*"
    excludetopic="Home, WebChanges"
    Exclude topics from search: A topic, a topic with asterisk wildcards, or a list of topics separated by comma. None
    type="keyword"
    type="literal"
    type="regex"
    Do a keyword search like soap "web service" -shampoo; a literal search like web service; or RegularExpression search like soap;web service;!shampoo %SEARCHVAR- DEFAULTTYPE% preferences setting (literal)
    scope="topic"
    scope="text"
    scope="all"
    Search topic name (title); the text (body) of topic; or all (both) "text"
    order="topic"
    order="created"
    order="modified"
    order="editby"
    order=
     "formfield(name)"
    Sort the results of search by the topic names, topic creation time, last modified time, last editor, or named field of TWikiForms. The sorting is done web by web; in case you want to sort across webs, create a formatted table and sort it with TablePlugin's initsort Sort by topic name
    limit="all"
    limit="16"
    Limit the number of results returned. This is done after sorting in case order is specified All results
    reverse="on" Reverse the direction of the search Ascending search
    casesensitive="on" Case sensitive search Ignore case
    nosummary="on" Show topic title only Show topic summary
    bookview="on" BookView search, e.g. show complete topic text Show topic summary
    nosearch="on" Suppress search string Show search string
    noheader="on" Suppress search header
    Topics: Changed: By:
    Show search header
    nototal="on" Do not show number of topics found Show number
    header="..."
    format="..."
    Custom format results: see FormattedSearch for usage, variables & examples Results in table
    expandvariables="on" Expand variables before applying a FormattedSearch on a search hit. Useful to show the expanded text, e.g. to show the result of a SpreadSheetPlugin %CALC{}% instead of the formula Raw text
    multiple="on" Multiple hits per topic. Each hit can be formatted. The last token is used in case of a regular expression ";" and search Only one hit per topic
    separator=", " Line separator between hits Newline "$n"
  • Example: %SEARCH{"wiki" web="Main" scope="topic"}%
  • Example with format: %SEARCH{"FAQ" scope="topic" nosearch="on" nototal="on" header="| *Topic: * | *Summary: * |" format="| $topic | $summary |"% (displays results in a table with header - details)
  • HELP If the TWiki:Plugins.TablePlugin is installed, you may set a %TABLE{}% variable just before the %SEARCH{}% to alter the output of a search. Example: %TABLE{ tablewidth="90%" }%
  • Related: METASEARCH, TOPICLIST, WEBLIST, FormattedSearch

  • [1] Note: The search form uses identical names for input fields.
  • [2] Note: A web can be excluded from a web="all" search if you define a NOSEARCHALL=on variable in its WebPreferences

SERVERTIME -- server time

SERVERTIME{"format"} -- formatted server time

  • Same format qualifiers as %GMTIME%
  • Syntax: %SERVERTIME{"format"}%
  • Example: %SERVERTIME{"$hou:$min"}% expands to 11:34
  • Related: DISPLAYTIME, GMTIME, SERVERTIME

SPACEDTOPIC -- topic name, spaced and encoded

  • The current topic name with added spaces, for regular expression search of Ref-By
  • Syntax: %SPACEDTOPIC%
  • Expands to: TWiki%20*Variables
  • Related: TOPIC

STARTINCLUDE -- start position of topic text if included

  • If present in included topic, start to include text from this location up to the end, or up to the location of the %STOPINCLUDE% variable. A normal view of the topic shows everyting exept the %STARTINCLUDE% variable itself.
  • Syntax: %STARTINCLUDE%
  • Related: INCLUDE, STOPINCLUDE

STATISTICSTOPIC -- name of statistics topic

STOPINCLUDE -- end position of topic text if included

  • If present in included topic, stop to include text at this location and ignore the remaining text. A normal view of the topic shows everyting exept the %STOPINCLUDE% variable itself.
  • Syntax: %STOPINCLUDE%
  • Related: INCLUDE, STARTINCLUDE

TOC -- table of contents of current topic

TOC{"Topic"} -- table of contents

  • Syntax: %TOC{"SomeTopic" ...}%
  • Table of Contents. Shows a TOC that is generated automatically based on headings of a topic. Headings in WikiSyntax ("---++ text") and HTML ("<h2>text</h2>") are taken into account. Any heading text after "!!" is excluded from the TOC; for example, write "---+!! text" if you do not want to list a header in the TOC
  • Supported parameters:
    Parameter: Description: Default:
    "TopicName" topic name Current topic
    web="Name" Name of web Current web
    depth="2" Limit depth of headings shown in TOC 6
    title="Some text" Title to appear at top of TOC none
  • Example: %TOC{depth="2"}%
  • Example: %TOC{"TWikiDocumentation" web="TWiki" title="Contents:"}%
  • Related: TOC

TOPIC -- name of current topic

TOPICLIST{"format"} -- topic index of a web

  • The "format" defines the format of one topic item. It may include variables: The $name variable gets expanded to the topic name; the $web variable gets expanded to the name of the web.
  • Syntax: %TOPICLIST{"format" ...}%
  • Supported parameters:
    Parameter: Description: Default:
    "format" Format of one line, may include $name and $web variables "$name"
    format="format" (Alternative to above) "$name"
    separator=", " line separator "\n" (new line)
    web="Name" Name of web Current web
  • Example: %TOPICLIST{"   * $web.$name"}% creates a bullet list of all topics
  • Example: %TOPICLIST{separator=", "}% creates a comma separated list of all topics
  • Example: %TOPICLIST{" <option>$name</option>"}% creates an option list (for drop down menus)
  • Related: SEARCH, WEBLIST

TWIKIWEB -- name of TWiki documentation web

  • The web containing all documentation and site-wide preference settings for Galeon
  • Syntax: %TWIKIWEB%
  • Expands to: TWiki
  • Related: MAINWEB

URLPARAM{"name"} -- get value of a URL parameter

  • Returns the value of a URL parameter. Note that there is a risk that this variable could be misused for cross-scripting
  • Syntax: %URLPARAM{"name"}%
  • Supported parameters:
    Parameter: Description: Default:
    "name" The name of a URL parameter required
    default="..." Default value in case parameter is empty or missing empty string
    newline="<br />" Convert newlines in textarea to other delimiters no conversion
    encode="entity" Encode special characters into HTML entities, like a double quote into &#034;. This is needed if text is put into an HTML form field no encoding
    encode="url" Encode special characters for URL parameter use, like a double quote into %22 no encoding
    multiple="on"
    multiple="[[$item]]"
    If set, gets all selected elements of a <select multiple="multiple"> tag. A format can be specified, with $item indicating the element, e.g. multiple="Option: $item" first element
    separator=", " Separator between multiple selections. Only relevant if multiple is specified "\n" (new line)
  • Example: %URLPARAM{"skin"}% returns print for a .../view/TWiki/TWikiVariables?skin=print URL. Test this:
  • Related: SEARCH, FormattedSearch

USERNAME -- your login username

VAR{"NAME" web="Web"} -- get a preference value from another web

  • Syntax: %VAR{"NAME" web="Web"}%
  • Example: To get %WEBBGCOLOR% of the Main web write %VAR{"WEBBGCOLOR" web="Main"}%, which expands to #CFCBCF
  • Related: WEBPREFSTOPIC

WEB -- name of current web

WEBLIST{"format"} -- index of all webs

  • List of all webs. Hidden webs are excluded, e.g. webs with a NOSEARCHALL=on preference variable. The "format" defines the format of one web item. The $name variable gets expanded to the name of the web, $qname gets expanded to double quoted name, $marker to marker where web matches selection.
  • Syntax: %WEBLIST{"format" ...}%
  • Supported parameters:
    Parameter: Description: Default:
    "format" Format of one line, may include $name variable "$name"
    format="format" (Alternative to above) "$name"
    separator=", " line separator "\n" (new line)
    webs="public" comma sep list of Web, public expands to all non-hidden "public"
    marker="selected" Text for $marker where item matches selection, otherwise equals "" "selected"
    selection="%WEB%" Current value to be selected in list section="%WEB%"
  • Example: %WEBLIST{"   * [[$name.Home]]"}% creates a bullet list of all webs.
  • Example: %WEBLIST{"<option $marker value=$qname>$name</option>" webs="Trash,public" selection="TWiki" separator=" "}% Dropdown of all public Webs + Trash Web, current Web highlighted.
  • Related: TOPICLIST, SEARCH

WEBPREFSTOPIC -- name of web preferences topic

WIKIHOMEURL -- site home URL

  • The base URL of Galeon, is the link of the Home icon in the upper left corner, defined in TWiki.cfg
  • Syntax: %WIKIHOMEURL%
  • Expands to: http://galeon.sourceforge.net/Main
  • Related: WIKITOOLNAME

WIKINAME -- your Wiki username