TWiki Reference Manual (04 Sep 2004 $Rev: 1742 $)

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

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

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

Related Topics: TWikiSite, TWikiHistory^?, TWikiPlannedFeatures^?, TWikiEnhancementRequests^?

TWiki Installation Guide

Installation instructions for the TWiki 01-Sep-2004 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.

• For Unix or Linux, check TWiki:Codev/TWikiOnUnix (install your own RCS, diff and grep tools if in doubt!) and TWiki:Codev/TWikiOnLinux.
• For Windows, check the WindowsInstallCookbook^?.
• For MacOS X, check TWiki:Codev/TWikiOnMacOSX.
• To install TWiki on SourceForge, for use on a software development project, read TWiki:Codev/TWikiOnSourceForge
• For other platforms, see TWiki:Codev/TWikiOn, and search the TWiki:Codev and TWiki:Support webs for other installation notes.
• If you need help, ask a question in the TWiki:Support web

Standard Installation

Download the TWiki 01-Sep-2004 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

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 .
  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 service httpd restart (or as appropriate to your flavor of UNIX or Linux).
• 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.

• Go directly to Step 2...

Aletrnative Step 1: Create & Configure the Directories 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

Note: Don't worry if you are not able to put 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 configure the /twiki/bin/setlib.cfg file (done in Step 3)

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.
    • Alternatively, you might try creating a file twiki/bin/.htaccess that contains the single line SetHandler cgi-script, which tells Apache to treat all files in this directory as CGI scripts.
• 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.
• 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).
    • 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 permissions manually.
  • 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.
  • 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. You have two options to change ownership of the RCS lock user:
    • Run the testenv script from your browser; in the Fix line you can relock all the rcs files (recommended)
    • Alternatively, run this in your shell:
      cd twiki/data
find . -name *,v -exec perl -pi~ -e '$. <= 10 && s/nobody:/www-data:/ ' {} \;
      This will create *,v~ backup files which you should remove after verification:
      find . -name *,v~ -exec rm -f {} \;

Step 3: Edit the Configuration Files

• Edit the file /twiki/bin/setlib.cfg
  • Set $twikiLibPath to the absolute file path of your /twiki/lib as seen by the web server.
  • Attention: Do not leave it as a relative "../lib" path or Plugins might fail to initialize properly
  • You can also edit $localPerlLibPath 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.
  • Attention: If you are running TWiki on Apache 2.0 on Unix you might experience cgi scripts to hang forever. This is a known Apache 2.0 bug. See details and woraround in the setlib.cfg 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: Internationalisation Setup (Optional)

By default, TWiki is configured to support US ASCII letters (no accents) in WikiWords, and ISO-8859-1 (Western European) characters in page contents. If that's OK for you, skip this step.

If your Wiki will be used by non-English speakers, TWiki can be configured for Internationalisation ('I' followed by 18 letters, then 'N', or I18N). Specifically, TWiki will support suitable accented characters in WikiWords (as well as languages such as Japanese or Chinese in which WikiWords do not apply), and will support virtually any character set in the contents of pages. NOTE: TWiki does not currently support UTF-8, so you are advised not to use this - however, improved UTF-8 support is under development, see TWiki:Codev/ProposedUTF8SupportForI18N.

To configure internationalisation suppport:

1. Edit the TWiki.cfg file's Internationalisation section to set the $useLocale parameter to 1. TWiki will now use the I18N parameters set in the rest of this section.
2. Type the Unix/Linux command locale -a to find a suitable 'locale' for your use of TWiki. A locale that includes a dot followed by a character set is recommended, e.g. pl_PL.ISO-8859-2 for Poland. Consult your system administrator if you are not sure which locale to use.
3. In TWiki.cfg, set the $siteLocale parameter to your chosen locale, e.g. pl_PL.ISO-8859-2 for Poland.
4. Check your setup using testenv (download the latest testenv from TWiki:Support/SupportGuidelines if possible) - this provides some diagnostics for I18N setup, and in particular checks that your locale can be used successfully.
5. (For upgrade of TWiki I18N sites only:) If you were using TWiki:Codev.TWikiRelease01Feb2003 support for I18N, and are using Internet Explorer or Opera, you should re-configure your browser so that it sends URLs encoded with UTF-8 (supported since TWiki:Codev.TWikiRelease01Sep2004). If you are doing a new installation of TWiki, you can ignore this step - no browser reconfiguration is needed for TWiki Release 01-Sep-2004).
   • Internet Explorer 5.0 or higher: in Tools | Options | Advanced, check 'always send URLs as UTF-8', then close all IE windows and restart IE.
   • Opera 6.x or higher: in Preferences | Network | International Web Addresses, check 'encode all addresses with UTF-8'.
   • NOTE: This does not mean that TWiki supports UTF-8 as a site character set.
6. Try out your TWiki by creating pages in the Sandbox web that use international characters in WikiWords and checking that searching, WebIndex, Ref-By and other features are working OK.

Trouble with I18N?

If international characters in WikiWords do not seem to work, and you are on Perl 5.6 or higher, you may need to set the TWiki.cfg parameter $localeRegexes to 0 - this disables some features but enables TWiki to work even if your system has locales that do not work. Then, set the $upperNational and $lowerNational parameters to the valid upper and lower case accented letters for your locale.

• NOTE: You will need to do the above workaround for Windows based servers (whether using Cygwin or ActiveState Perl), since Perl locales are not working on Windows as of Feb 2004.

If international characters in WikiWords aren't working, and you are on Perl 5.005 with working locales, keep $useLocale set to 1 and set $localeRegexes to 0, then set $upperNational and $lowerNational - if testenv generates the lists of characters for you, your locales are working so there is no need to set $localeRegexes to 0 in this case. See the comments in TWiki.cfg for more information.

Step 5: 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 6: Finish Up from Your Browser

• Point your Web browser at http://yourdomain.com/twiki/bin/view and start TWiki-ing away!
  • 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.WebHome topic.
• You can add new %VARIABLES%. Define site-level variables in the TWikiPreferences topic. See also: TWikiVariables.

That's it for the standard 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. The comment at the top of the file explains what need to be done, basically replace !FILE_path_to_TWiki! and !URL_path_to_TWiki! with paths specific to your installation. For the details of how this file works, consult the HTTP server documentation (for Apache server: [1], [2]).
     • 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.
     • 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.
     • 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. TWiki now supports several Password file format/encoding methods for Apache. Once you know what method is used by your Appache server, you can configure TWiki to create compatible .htpasswd entries by editing the $htpasswdFormatFamily, $htpasswdEncoding and $htpasswdFilename in the TWiki.cfg file. The supported options are htpasswd:plain, htpasswd:crypt, htpasswd:sha1, htdigest:md5
  3. 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. The same variables get expanded as in the template topics
• Register yourself in the TWikiRegistration topic.
  • 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.

WYSIWYG Editor

At this time, TWiki does not ship with an "what you see is what you get" editor. TWiki:Codev/IntegrateHtmlAreaEditor describes how to integrate an HTML editor.

NOTE: User home topics are located in the TWiki.Main web - don't try to move them or create them in other webs. From any other web, user signatures have to point to TWiki.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-2004 distribution.

-- TWiki:Main/PeterThoeny - 29 Aug 2004
-- TWiki:Main/MikeMannix - 16 May 2002

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 to control access by protecting key scripts: attach, edit, installpasswd, manage, preview, rename, save, upload. 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.
• 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:

• You are Main.guest

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.

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

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

• TWiki Username: Your name in WikiNotation, ex: PeterThoeny, is recorded when you register using TWikiRegistration; doing so also generates a personal home page in the 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.

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

• The ChangePassword form ( TWiki/ChangePassword ):

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 webmaster@kitchentablemath.net.

• The ResetPassword form ( TWiki/ResetPassword ):

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, webmaster@kitchentablemath.net, who will set your account to use the new password.

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

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

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

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.

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

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

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.

-- TWiki:Main.PeterThoeny - 04 May 2002
-- TWiki:Main.MikeMannix - 12 May 2002

TWiki Text Formatting

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

1st paragraph

2nd paragraph

---++ Sushi

---+++ Maguro

*Bold*

_Italic_

__Bold italic__

=Fixed font=

==Bold fixed==

_This works_,
_this not _

<verbatim>
class CatAnimal {
  void purr() {
    <code here>
  }
}
</verbatim>

class CatAnimal {
  void purr() {
    <code here>
  }
}

-------

   * bullet item

   * level 1
      * level 2

   1. Sushi
   1. Dim Sum

   A. Sushi
   A. Dim Sum

   i. Sushi
   i. Dim Sum

   $ Sushi: Japan
   $ Dim Sum: S.F.

| *L* | *C* | *R* |
| A2 |  2  |  2 |
| A3 |  3  |  3 |
| multi span |||
| A4-6 | four | four |
|^| five | five |



|^| six | six |

WebNotify

Main.TWikiUsers

[[wiki syntax]]

[[Main.TWiki users]]

escaped:
![[wiki syntax]]

[[WikiSyntax][syntax]]

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

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

[[WikiWord#NotThere]]

[[#MyAnchor][Jump]]

#MyAnchor To here

!SunOS

 <noautolink>
 RedHat &
 SuSE
 </noautolink>

[[mailto:a@z.com Mail]]

[[mailto:?subject=Hi 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

• TIP: 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.
• NOTE: TWiki is designed to work with a wide range of browsers and computer platforms, holding to HTML 4.0 and XHTML 1.0 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.
• Recommondations when using HTML:
  • Use XHTML 1.0 Transitional syntax
  • Do not span a tag over more then one line
  • Remove all empty lines. TWiki inserts <p /> paragraph tags on empty lines, which causes problems if done between tags that do not allow paragraph tags, like for example between table tags.

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.
  • 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."
• 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, <, ex: a < b
  • 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 type="text/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 TWiki 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://yahoo.com Yahoo home page]] as an easier way of doing external links with descriptive text for the link, such as Yahoo home page.

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 TWiki 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, Tip, Alert. For more info see TWikiDocGraphics.

• There are many more variables, see TWikiVariables.

• 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 TWiki 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 TWiki topics.
• CommentPlugin: Allows users to quickly post comments to a page without an edit/preview/save cycle.
• ContributorsPlugin: This plugin gives a variable %CONTRIBUTORS% which gives information on all revisions of a given topic.
• 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.
• 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