TWiki > TWiki > TWikiDocumentation	TWiki webs: Main | TWiki | Plugins | Sandbox | Patterns
	TWiki . { Home | Welcome | Register | Changes | Topics | Index | Search | Go }

TWiki Reference Manual (30 Dec 2002)

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

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 System Requirements

Server and client requirements for TWiki 01-Dec-2001

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

Server Requirements

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

* Current documentation covers Linux/Apache only. See TWiki:Codev/TWikiOnWindows for work-to-date on a Windows installation guide.

Client Requirements

The TWiki standard installation has extremely low browser requirements:

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

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

Known Issues

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

-- MikeMannix? - 12 Jan 2002

TWiki Installation Guide

Installation instructions for the TWiki 01-Dec-2001 production release. Update notes for the new RCS configuration are marked Dataframework.

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. Documentation for other platforms is somewhat limited:

• For Unix or Linux, check TWiki:Codev/TWikiOnUnix and TWiki:Codev/TWikiOnLinux.
• For Windows, check the WindowsInstallCookbook?.
• For MacOS X, check TWiki:Codev/TWikiOnMacOSX.
• For other platforms, see TWiki:Codev/TWikiOn, and search the TWiki:Codev and TWiki:Support webs for other installation notes.

Standard Installation

Request and download the TWiki 01-Dec-2001 distribution in Unix ZIP format from http://TWiki.org/download.html. (To install TWiki on SourceForge, for use on a software development project, read TWiki:Codev/SourceForgeHowTo .)

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 /etc/httpd/httpd.conf 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 /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.

• Go directly to Step 2...

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, Perl CGI scripts usually require a .cgi extension to run. Some systems need .pl, the regular Perl extension. Modify all twiki/bin script filenames 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.
• 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 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, ex 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:

cd twiki/data
perl -pi~ -e '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

• From your web browser, edit the TWikiPreferences topic in the TWiki:TWiki web 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.

Step 5: 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 Mail notification topic in all webs and add the users you want to notify.
• Add the TWiki:Main/PoweredByTWikiLogo to your WebHome? 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
     • 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. 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.
  • 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.

Adding a New Web

To create a new web:

1. Create a new web data directory under twiki/data and check the file permission of the directory.
   • Use a name consisting of characters A..Z , a..z but not in WikiNotation. (The name should start with one (or more) uppercase letters, but have no uppercase letters after the first group -- if it starts with a lowercase letter or is a WikiWord, some features of TWiki will not work as expected.)
2. Copy all files from the twiki/data/_default directory to the new data directory, preserving the original files' owner, group and permissions (on Unix, use cp -p). The data files must be writable by the owner the CGI scripts are running on (usually, nobody).
   • HINT: You can set permissions of .txt and .txt,v files to -rw-rw-rw- (666) and then edit the topic using your browser; RCS will restore the file permissions correctly when saving the topic.
3. Add the new web to the web list (visible in the upper right corner of each topic) by editing the site-level preferences, TWikiPreferences:
   • Add the new web to the %WIKIWEBLIST% variable.
4. Update the web settings by editing the WebPreferences topic of the new web:
   • Customize the %WEBTOPICLIST% variable to contain the web-specific links you prefer.
   • Set the WEBBGCOLOR variable to a color. The number represents the unique color for the web.
   • Set Plugins, access privileges, custom variables, other web-level options (ex: %WEBCOPYRIGHT% can be set for an individual web).
5. Test the new web: view pages, create a new page.

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.

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-2001 distribution.

-- PeterThoeny - 28 Dec 2002
-- MikeMannix - 16 May 2002

TWiki Upgrade Guide

Upgrade from TWiki 01-Dec-2001 to TWiki 01-Jan-2003 (previous to new full release)

Overview

This guide describes how to upgrade from TWiki 01-Dec-2001 to TWiki 01-Jan-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-Jan-2003 TWiki Production Release, follow the instructions below.

• NOTE: To upgrade from a pre-01-Dec-2001 TWiki, start with TWikiUpgradeTo01Dec2001.

• 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

• AND Search - With regular expression enabled, use ";" as the AND operator in FormattedSearch and WebSearch
• (to be completed)

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

The following steps describe the upgrade assuming that $TWIKIROOT is the root of your current 01-Dec-2001 release.

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.

1. Back up and prepare:
   • Back up all existing TWiki directories $TWIKIROOT/bin, $TWIKIROOT/pub, $TWIKIROOT/data, $TWIKIROOT/templates.
   • 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.
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, ex: .cgi
   • Edit $TWIKIROOT/bin/setlib.cfg and point $twikiLibPath to the absolute file path of $TWIKIROOT/lib
   • Pay attention to the file and directory permissions, the scripts need to be executable, e.g. 775.
5. Update library files:
   • Make a backup copy of $TWIKIROOT/lib/TWiki.cfg to TWiki.cfg.save
   • 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, but set to e.g. 664.
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.*, Mail_notification.*, WebPreferences.*, WebStatistics.* and all WebTopic* files.
   • Rename $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.
   • Merge your original TWikiPreferencesSave.txt settings into $TWIKIROOT/data/TWiki/TWikiPreferences.txt.
   • Move all *.txt and *.txt,v files from the temporary data/_default directory to your $TWIKIROOT/data/_default directory.
   • Move the data/Sandbox directory from the temporary location to your $TWIKIROOT/data directory.
   • Make sure that the directories and files below $TWIKIROOT/data are writable by your cgi-script user.
7. Update pub/TWiki 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.
8. 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.

General Format Changes

• (to be written)

Known Issues

• Check TWiki:Codev/KnownIssuesOfTWiki01Jan2003 for known issues of TWiki 01 Jan 2003 (production release)

-- PeterThoeny - 17 Dec 2002

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

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.

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

TWiki Text Formatting

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 to "stick" the * _ = == signs to the words, e.g. take away spaces.	_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 and an asterisk.	* bullet item	bullet item
Nested List Item: Six, nine, ... spaces and an asterisk.	* nested stuff	nested stuff
Ordered List: Three spaces and a number.	1 Sushi 1 Dim Sum	Sushi Dim Sum
Definition List: Three spaces, the term, a colon, a space, followed by the definition. Note: Terms with spaces are not supported. In case you do have a term with more then one word, separate the words with dashes or with the &nbsp; non-breaking-space entity.	Sushi: Japan Dim&nbsp;Sum: S.F.	Sushi Japan Dim Sum S.F.
Table: Optional spaces followed by the cells enclosed in vertical bars. Note: | *bold* | cells are rendered as table headers. Note: |   spaced   | cells are rendered center aligned. Note: |     spaced | cells are rendered right aligned. Note: | 2 colspan || cells are rendered as multi-span columns. Note: In case you have a long row and you want it to be more readable when you edit the table you can split the row into lines that end with a '\' backslash character.	| *L* | *C* | *R* | | A2 | 2 | 2 | | A3 | 3 | 3 | | multi span ||| | A4 \ | next \ | next |	L C R A2 2 2 A3 3 3 multi span A4 next next
WikiWord Links: CapitalizedWordsStuckTogether (or WikiWords) will produce a link automatically. Note: In case you want to link to a topic in a different TWiki web write Webname.TopicName.	WebNotify Know.ReadmeFirst	Mail notification 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; i.e. [[text formatting FAQ]] links to topic TextFormattingFAQ. You can also refer to a different web and use anchors.	[[wiki syntax]] [[Main.TWiki users]]	wiki syntax? Main.TWiki users
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 (i.e. WikiSyntax) and external link references (i.e. http://TWiki.org/) are supported. The same Forced Links rules apply for internal link references. Anchor names can be added as well, like [[Home_#MyAnchor][go home]] and [[http://www.yahoo.com/#somewhere][Yahoo!]].	[[WikiSyntax][syntax]] [[http://gnu.org][GNU]]	syntax GNU
Easier External Links: An easier syntax for external links is now available: [[externalURL text]] - just hit the spacebar to separate the link URL from the descriptive text, e.g. [[http://gnu.org/ GNU]]. This also supports anchors, e.g. [[http://www.yahoo.com/#somewhere Yahoo!]].	[[http://gnu.org GNU]]	GNU
Anchors: You can define a link reference inside a TWiki 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.	[[WebHome#NotThere]] [[#MyAnchor][Jump]] #MyAnchor To here	Home #NotThere Jump To here
Prevent a Link: Prevent a WikiWord from being linked by prepending it with the <nop> tag.	<nop>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

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

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://... 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"}%

• There are many more variables, see TWikiVariables.

• TWikiPreferences defines site-wide variables like colors. For example, write: %RED% Red %ENDCOLOR% and %BLUE% blue %ENDCOLOR% colors to get: Red and blue colors.

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 deprecated *_text_* as bold italic text.
• TreePlugin: Dynamic generation of TWiki topic trees
• SpacedWikiWordPlugin: Causes wiki words to be displayed with spaces between capitals.
• ImageGalleryPlugin: Displays image gallery with auto-generated thumbnails for attachments.
• EditTablePlugin: Edit TWiki tables using edit fields and drop down boxes.
• EmbedFlashPlugin: Embeds a Macromedia Flash file
• InterwikiPlugin: Link ExternalSite:Page text to external sites based on aliases defined in the InterWikis topic.
• 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 '<' instead of '<', and '>' instead of '>'.
    Example: Type 'prog <filename>' 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. '©' is the © copyright character. You need to escape '&' to see it as it is, so write '&' instead of '&'.
    Example: Type 'This & that' to get 'This & that'.

-- MikeMannix - 02 Dec 2001
-- PeterThoeny - 02 May 2002

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.

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.

• 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 - 30 Dec 2002 - expands the following variables (enclosed in % percent signs):