Upgrading from older TWiki releases.

This guide covers upgrading from a previous version of TWiki (such as Cairo or TWiki4.0) to Foswiki 2.0 (References to Cairo are for TWiki versions older than TWiki 4.0, such as TWikiRelease04Sep2004)

TWiki^® is a registered trademark of Peter Thoeny.

Overview

Foswiki is a fork from TWiki 4.2.3. Upgrades from all TWiki versions and earlier Foswiki versions are supported. Foswiki was originally designed to be 100% compatible with the content of TWiki sites, using the same markup language and supporting the same plugin API (through the use of a TWikiCompatibilityPlugin), thereby enabling a smooth transition from TWiki to Foswiki. Note however that newer versions of Foswiki have not directly tracked newer versions of TWiki, and some divergence has occurred.

This document provides supplemental information for upgrade from TWiki. You should follow the same process as defined by the UpgradeGuide, referring to additional information documented here.

Upgrade requirements

• Please review the Foswiki:System.AdminSkillsAssumptions before you upgrade your site.
• Carefully review Foswiki:System.SystemRequirements. Foswiki no longer ships with CPAN libraries. CPAN dependencies must be installed prior to upgrade.
• Before upgrading, making a backup of your topics is strongly recommended.
• Once the upgrade has been applied, an existing earlier installation will still be able to read all the topics, but should not be used to write.
• Some TWiki plugins are not compatible with Foswiki (usually ones that use a private API or execute helper scripts); you may need to migrate to the equivalent extension in the Foswiki:Extensions repository.

Upgrading from TWiki to Foswiki

You are strongly advised to read the Foswiki:System.ReleaseNotes01x00 which contains a list of changes from TWiki 4.2.3 to Foswiki 1.0. A number of system topics and macros (formerly known as TWiki variables) have been renamed, to better describe their purpose and, where appropriate, to re-brand to the Foswiki name. Also review changes documented in Foswiki:System.ReleaseNotes01x01 and Foswiki:System.ReleaseNotes01x02 (the latter also available in an HTML file in the root of your installation),

Upgrade procedure: upgrading to a new major or minor version, or upgrading from TWiki

The following is a high level view of the upgrade procedure:

1. Prepare for all upgrade steps.
2. Install the new Foswiki version and configure it with the same settings as the old version.
   
   • Windows server users: Don't forget to rerun tools/rewriteshebang.pl to fix up the Perl locations
3. Install any additional extensions (Plugins) used by your old installation. Make sure to use the latest Foswiki versions.
4. Copy all the non-default webs from the old installation to the new one.
5. Copy the users, groups, and site customizations from the old installation to the Main web in the new installation, including all user topics.
6. Apply preferences from the old installation.
7. Apply your site customizations: skin, logos, menu bars, forms for personal information, and so forth.
8. Validate your Wiki applications and other key functionality.
9. Switch your production site from the old installation to the new installation.
   Managing caches of static .js, .css files: some parts of Foswiki use URI versioning to help web browsers obtain a current version of these files when they change, but currently other parts do not. You may need to get your users to clear their browser's cache after upgrading your site to a new major or minor release (usually not necessary for patch upgrades). An alternative approach is to manage your web server configuration to strategically set appropriate expiry times for static files (see performance supplement)

More details for each step appear in the following sections. The steps may need to be modified or otherwise tailored with specifics for your installation. In particular, you must take care to preserve any special configuration or customizations you have made, especially if you have modified any of the default software files or system topics that are contained within the installation package.

For purposes of discussion, the following conventions are used:

• <oldwiki> refers to the directory in which the old installation is located
• <newwiki> refers to the directory in which the new installation is located; it is assumed to be immediately below the root directory of your web server
• <old_users_web> refers to the web in which the user topics are located in the old installation. The default value is the Main web. The web is specified in the Store settings pane of the configure page, in the {UsersWebName} setting (visible when Expert mode is enabled).
• <old_system_web> refers to the web used for documentation and default preferences in the old installation. In Foswiki, the default value is the System web; in TWiki, the default value is the TWiki web. The web is specified in the Store settings pane of the configure page, in the {SystemWebName} setting (visible when Expert mode is enabled).

After the upgrade, in the new installation, the Main web is used for user topics and site preferences, and the System web is used to hold documentation and default preferences.

The configure page mentioned in this document is accessible via your web browser at http://yourdomain/<newwiki>/bin/configure

 

.

Prepare for all upgrade steps

Download the Foswiki distribution from the following location: http://foswiki.org/Download — if you are installing your extensions manually, also download them from the repository where they are stored. (Default extensions are included in the Foswiki distribution).

Review Foswiki:SystemRequirements and Install missing Perl modules using your local package manager or CPAN. Foswiki 2.0 no longer ships with CPAN modules. If you have access to the command line on the server, you can test for missing dependencies by running: perl tools/dependencies

Read the Foswiki:System.ReleaseNotes01x02 and learn about the differences between your old installation and the new release to which you are upgrading. Take note of any areas that affect your site and what special steps you may need to take.

Check that all the extensions (plugins, contribs, skins) used by your old installation are available with the new release. Familiarize yourself with any new behaviour that you will have to adapt to or any configuration changes you will have to perform.

• The EditTablePlugin has been deprecated and is not shipped with Foswiki 2.0 It is replaced by the EditRowPlugin. If you are upgrading an existing site, and have that plugin installed, only one of EditTablePlugin or EditRowPlugin should be enabled.
• Review the deprecated jQuery javascript plugins. The JQueryPlugin has several changes in available jQuery JavaScript plugins. Determine if any of these will impact your JavaScript enabled topics.

Choose the character encoding to be used in your site. Previous versions of Foswiki defaulted to iso-8859-1 encoding (The "Latin Alphabet 1, intended for US and Western European languages). Foswiki 2.0 defaults to UTF-8 encoding, which provides better support for international character sets. You must match the prior encoding if you intend to use topic created on an older version of Foswiki. If you change encoding of existing topics, you must use the non-default Foswiki:Extensions.CharsetConverterContrib to modify the character encoding. Changes in character encoding must be done using the RCS based store.

Choose your desired Store. Foswiki ships with two native stores.

• RcsStoreContrib is compatible with topics created in prior versions of Foswiki.
• PlainFileStoreContrib requires that topic history be converted to a new history format. perl -I lib tools/change_store.pl -help for more information on conversion.
• If you intend to change the topic character encoding, this must be done prior to conversion to the PlainFileStore.

If you are using authentication, prepare a test plan to verify that your authentication mechanism is working correctly. Make sure you are able to test logins by a sufficient sample of users to cover all categories of users of your site. For example, users of various groups may need to be tested. In particular, ensure you test that non-admin users cannot access topics restricted to admins.

• Empty DENYTOPICxxxx rules are deprecated They are disabled by default. We recommend converting any existing rules into  

    * Set ALLOWTOPICxxxx = * wildcard allow rules. Use perl tools/convertTopicSettings.pl -help for further information on the conversion process.

Identify all essential Wiki topics and Wiki applications that must be fully functional upon completion of the upgrade. Prepare a test plan to verify their functionality. If you are using access controls, ensure that the test plan will adequately test all categories and groups of users of your site.

If your testing will require a test environment to be set up, ensure that it is ready, with any required support infrastructure (for example, testbed authentication servers). If you need to be able to login with different users in different categories and groups, ensure that you have the required login information ready, or you have testers from those groups available to perform the required test cases.

Installation

Follow the installation instructions in INSTALL.html, located in the root of the new installation. Install the new release in a new directory. Do not install on top of the old release.

• For public or otherwise sensitive installations, ensure that your web server configuration is set to deny access to the new Foswiki installation for anyone except you.
• Configure Foswiki using the configure page.
  • (Not recommended!) If you are upgrading from an older Foswiki release, first copy your <oldwiki>/lib/LocalSite.cfg file to <newwiki>/lib/LocalSite.cfg in order to preserve your existing configuration settings (Not recommended). Alternatively, you can reconfigure the new installation from scratch (you can use your old LocalSite.cfg file as a reference).
  • If you are upgrading from a TWiki site, you must reconfigure your Foswiki installation from scratch. You cannot copy over your old LocalSite.cfg file (though you can use it as a reference). Run configure and set the configuration values in the new installation to match those of the old installation.
  • Verify all of the configuration settings on the configure page, including any new settings added in the new version. Save the configuration after you have completed your changes.
  • To wipe out all your settings and start configuring from a fresh installation, just delete the <newwiki>/lib/LocalSite.cfg file and visit your default view URL. From there follow the link to configure.
• Additional resources
  • Foswiki:System.InstallationGuide
  • Foswiki:Support.InstallingOnSpecificPlatforms
  • Foswiki:Support.ApacheConfigGenerator
  • Foswiki:Support.SettingFileAccessRightsLinuxUnix

Test your newly-installed Foswiki site and ensure that its basic functionality works: viewing and editing topics (you can try creating and editing a topic in the Sandbox web).

To make it easier to follow the subsequent steps, you can view this upgrade guide using your new Foswiki site by entering System.UpgradeGuide into the "Jump" text box on the top right of any topic. By doing this instead of using the UpgradeGuide.html file from the distribution, you will be able to use the embedded hyperlinks to jump directly to the referenced pages.

Install extensions

Install all of the extensions that were installed in your old site. In particular, start with any extensions required for the authentication and authorization methods you use (if any). You can use the Find more extensions button in the Extensions section of the configure page to install and configure extensions from the Foswiki:Extensions repository. You can also install extensions manually; see the instructions on the extension's web page from where you obtained the extension (for Foswiki extensions, on foswiki.org).

• Note: some TWiki extensions may not work with Foswiki. By default, the TWikiCompatibilityPlugin is installed to provide backwards compatible support for TWiki plugins. However if the TWiki plugin calls private APIs or invokes helper scripts, it may still not work correctly. Check for an upgraded Foswiki version of the extension in the Foswiki:Extensions repository and install it instead.

Check the plugin topics from your old TWiki/Foswiki installation and transfer the plugin settings to the Main.SitePreferences topic in your new Foswiki site, prefixing each setting with the name of the plugin in uppercase followed by an underscore. For example, to copy over the DEFAULT_TYPE setting from the CommentPlugin topic in the old site to the new site, copy the value to a COMMENTPLUGIN_DEFAULT_TYPE setting in the Main.SitePreferences topic in the new site.

Commonly-customized plugin settings include the following:

• CommentPlugin - DEFAULT_TYPE
• EditTablePlugin Deprecated! Replaced with EditRowPlugin - CHANGEROWS, QUIETSAVE, EDITBUTTON
• InterwikiPlugin - RULESTOPIC
• InterWikis - If you added your own rules, make sure you copy over the rules to the new installation. Use of a local rules topic is the preferred way to customize the links.
• SlideShowPlugin - If you changed the embedded 'Default Slide Template', then copy your customized template to the topic in the new installation. You should prefer creating your own slide show template in a separate topic, so you will not have to take special steps over upgrades to preserve your modifications to the default slide template.
• SmiliesPlugin - If you added your own smileys, make sure you copy over your customizations to the topic in the new installatin.
• TablePlugin - TABLEATTRIBUTES

Activate, and if required, configure the installed extensions in configure.

Copy content from non-default webs in old installation to the new installation

Be sure to select an "RCS Store" RcsWrap or RcsLite on the new installation. The PlainFile store is not compatible with topic history written on previous versions of Foswiki. If you have created or updated topics using PlainFileStore, you should either start over, or plan to to remove all ,pfv directories from the system so that there is no history in the PlainFileStore format.

If you are upgrading from TWiki Cairo or earlier, it may be necessary to unlock the rcs files in data and pub directories from the old installation using the following shell commands:

• find data -name '*,v' -exec rcs -u -M '{}' \;
• find pub -name '*,v' -exec rcs -u -M '{}' \;

If you intend to change character encoding to UTF-8, you should install and run the Foswiki:Extensions.CharsetConverterContrib on your existing data before migrating it to Foswiki 2.0. The CharsetConverterContrib only supports the RCS style Store. Once you have converted the characterset to UTF-8 then you can convert to PlainFileStore

Copy your local webs over to the data and pub directories of the new installation. Do not copy the default webs: <old_system_web> (by default, either System or TWiki), Main, Trash, Sandbox, _default, and _empty.

• Make sure the data and pub directories, as well as the files within them, are readable and writeable by the web server user.
• Note: Foswiki's WebChanges topics depend on the file timestamp. If you touch the .txt files make sure to preserve the timestamp, or change them in the same chronological order as the old file timestamps.

Verify that existing topics are operational and (if you converted to UTF-8) that any international characters have been properly converted and are displayed correctly.

Copy users, user topics, and site customizations to Main web

Copy all topics and attachments from <old_users_web>: copy all files from <oldwiki>/data/<old_users_web>/ to <newwiki>/data/Main/, and copy all files from <oldwiki>/pub/<old_users_web>/ to <newwiki>/pub/Main/ . Do not overwrite any topics already present in the <newwiki>/data/Main/ directory.

• In addition to all the user topics, if you have created <old_users_web>.NewUserTemplate in the old installation, this step will copy over your template for user topics to the new installation.
• Ensure that the topic defining the admin group in your old installation is copied over. The admin group is defined in the Security setup pane of the configure page, in the {SuperAdminGroup} setting (visible when Expert mode is enabled). You can do either of the following:
  • Set the {SuperAdminGroup} setting in your new installation to the old admin group.
  • Move the contents of the old admin group to the new admin group. To avoid having to change all references to the old admin group, you must still keep the old admin group defined: set it so its only member is the new admin group, and the new admin group is the only user who can change or rename the old admin group topic.
    • The default admin group with Foswiki is AdminGroup and the default admin group with TWiki is TWikiAdminGroup. So if you are upgrading from TWiki and are using the default admin groups, then in the new installation, you must copy all members from TWikiAdminGroup to AdminGroup, and change TWikiAdminGroup so its only member is AdminGroup and so it can only be modified or renamed by AdminGroup.
• If your old installation did not customize {LocalSitePreferences} on the configure page, or if you did customize {LocalSitePreferences} but kept your site preferences within the <old_users_web> web, then this step will also copy over your site preferences to the new installation.

For upgrades from an older Foswiki installation:

• Manually merge all users from the <old_users_web>.WikiUsers topic in the old installation to the Main.WikiUsers topic in the new installation. If the new installation does not yet have an initial Main.WikiUsers topic, then copy <oldwiki>/data/<old_users_web>/WikiUsers.txt to <newwiki>/data/Main/WikiUsers.txt.
• Verify that the following default users are present in the Main.WikiUsers topic:
  • ProjectContributor - the Foswiki documentation is attributed to this user
  • RegistrationAgent - special user used during the new user registration process
  • UnknownUser - used where the author of a previously stored piece of data can't be determined
  • WikiGuest - guest user; used as a fallback if the user can't be identified
• If any of the default users are missing, then add them in manually to Main.WikiUsers, using the corresponding entries in Foswiki:System.UsersTemplate as an example.
• If you use data/.htpasswd for authentication, copy this file from the old installation to the new one.
• If you have customized <old_system_web>.UserRegistration, then either copy over <oldwiki>/data/<old_system_web>/UserRegistration.txt and <oldwiki>/data/<old_system_web>/UserRegistration.txt,v to the <newwiki>/data/System/ directory, or modify System.UserRegistration in the new installation to contain your customizations.

For upgrades from a TWiki installation:

• Manually merge all users from the <old_users_web>.TWikiUsers topic in the old installation to the Main.WikiUsers topic in the new installation. If the new installation does not yet have an initial Main.WikiUsers topic, then copy <oldwiki>/data/<old_users_web>/TWikiUsers.txt to <newwiki>/data/Main/WikiUsers.txt, and manually add the required default users (see the next steps).
• Verify that the following default users are present in the Main.WikiUsers topic:
  • ProjectContributor - the Foswiki documentation is attributed to this user
  • RegistrationAgent - special user used during the new user registration process
  • UnknownUser - used where the author of a previously stored piece of data can't be determined
  • WikiGuest - guest user; used as a fallback if the user can't be identified
• If any of the default users are missing, then add them in manually to Main.WikiUsers, using the corresponding entries in Foswiki:System.UsersTemplate as an example.
• If you use data/.htpasswd for authentication, copy this file from the old installation to the new one.
• If you are upgrading from Cairo and are using the Htpasswd login manager, run the tools/upgrade_emails.pl script to move the user emails out of the user topics and into the password file.
• If you have customized <old_system_web>.TWikiRegistration, then modify System.UserRegistration in the new installation to contain your customizations.

Copy over any topics and attachments you want to preserve from the Sandbox web in the old installation: copy the desired files from <oldwiki>/data/Sandbox/ to <newwiki>/data/Sandbox and from <oldwiki>/pub/Sandbox/ to <newwiki>/pub/Sandbox . Some pages you may wish to preserve are the WebHome topic and the WebLeftBar topic (if you had created it in the old wiki installation). The Sandbox web often contains work-in-progress topics that users will want to keep.

Make sure the data and pub directories, as well as the files within them, are readable and writeable by the web server user.

Execute your test plans for authentication and authorization. Test that users that you have transferred from the old installation can login with any problems, and that access controls work appropriately: check that users are able to view and edit pages for which they have access, and are denied permission to view or edit pages for which they do not have access. Also check that pages restricted to the admin group are not accessible by non-admin users, and that administrators continue to have access.

Convert empty DENY ACLs to ALLOW * wildcards

By default, empty DENYTOPIC rules will be ignored by Foswiki 2.0. You must change them to the equivalent ALLOWTOPIC * rules. The tools/convertTopicSettings.pl utility will scan the Webs & Topics, and will perform several optional conversions on the topics.

Get help text for convertTopicSettings

perl tools/convertTopicSettings.pl -help

Scan all webs / topics, report any topics with empty DENY rules

perl tools/convertTopicSettings.pl

Replace all empty DENY rules with ALLOW * wildcards

perl tools/convertTopicSettings.pl -fixdeny -update

Same, but convert all ACLs into META settings from inline topic settings, for just the Sandbox web

perl tools/convertTopicSettings.pl -fixdeny -convert -update Sandbox

Convert ALL settings into META settings, not just ACLs, for the Sandbox and Customer webs

perl tools/convertTopicSettings.pl -fixdeny -convert -all -update Sandbox Customer

When convertTopicSettings saves the modified topics, they will be saved by user UnknownUser.

Convert to Plain File Store (optional)

The convertStore.pl utility will copy the data and pub directories into a new structure, with new revision data. It also will validate the contents of topics and verify that the revision history is consistent and complete. Subdirectories below topic directories within the pub directory are not copied! Because of this, it is not possible to completely convert the System directory. We recommend using the new System shipped with Foswiki 2.0. Normally the System does not contain any topic history, however if System topics have been edited, then conversion may be required. If you attempt to convert the System, you will need to copy critical pub subdirectories, found under pub/System/JQueryPlugin/.., pub/System/TinyMCEPlugin/.., and other key components.

Validate the store in-place

perl -I lib tools/change_store.pl -q -v RcsLite RcsLite

• Any topics with inconsistent revisions are reported
• Any pub files without Attachment metadata in the topic are reported.

Convert the store to PlainFile, creating directories under ./newstore

perl -I lib tools/change_store.pl -s . -t newstore -q RcsLite PlainFile

• Any "unattached" attachments will be listed, and can be piped to a command to copy separately
• The System will be copied but will be incomplete / unusable.

Apply preferences from old installation

If you have not already set your desired site-wide preferences, as described in the section " Set Foswiki Preferences" in the InstallationGuide, then set your preferences. The location of your site preferences is specified in the Miscellaneous settings pane of the configure page, in the {LocalSitePreferences} setting (visible when Expert mode is enabled) — the default location is Main.SitePreferences. Copy any customized preferences from the site preferences topic in your old installation to the site preferences topic in the new installation. (Note you may have already copied over your customized preferences when you transfered the contents of the <old_users_web> web.)

If, in your old installation, you customized the default preferences in <old_system_web>.DefaultPreferences, then transfer your customizations from this topic to the site preferences topic instead (i.e. the topic specified in your {LocalSitePreferences} setting), so that your customizations will not get overwritten on the next upgrade.

If you are upgrading from TWiki, note that the default location of the default preferences in TWiki is <old_system_web>.TWikiPreferences, and the default location of the site preferences is Main.TWikiPreferences. Transfer any customized preferences from these topics to the site preferences topic in your new installation.

Apply additional site customizations

Modify skin with customizations for your site

If you did not already customize the appearance of your new installation, as described in the section " Customize the appearance of your Foswiki site" in the InstallationGuide, then reapply the customizations from your old installation to the new one. Ensure you transfer over any skin templates — .tmpl files, or topics referred to using VIEW_TEMPLATE or EDIT_TEMPLATE preferences — you need. Also ensure you transfer any style sheets or Javascript files required.

If you are upgrading from the Cairo version of TWiki: note that the skins from this release do not work well with Foswiki. Starting from TWiki 4.0.2, the default PatternSkin has been fairly stable and so your customizations should continue to work.

Customize pages for managing personal information

In your new installation, default copies of the following topics were installed:

• System.ChangePassword
• System.ResetPassword
• System.ChangeEmailAddress

If you customized these topics in your old installation, transfer the changes to these topics in the new installation. Use the corresponding files in the <oldwiki>/<old_system_web>/ directory as a reference.

Validate your Wiki applications and other key functionality

Execute your test plan to validate the Wiki applications and other key functionality that need to be up and running after the upgrade.

Switch your production site from the old installation to the new installation

*If you are converting from RCS to PlainFile store, you must not repeat any copy step from the old to the new version once you've run the conversion.

If you had been running your old installation in parallel with the new one during a test phase, then disable your old installation, and repeat the step " Copy content from non-default webs in old installation to the new installation".

Change your web server configuration so that the new installation is accessible to all of your users, and so the old installation is no longer accessible.

Change your web server configuration so that the new installation is accessible using the same URL prefix as your old installation. For purposes of discussion, assume that your old installation is accessible from http://yourdomain/wiki/. You can use one of the following approaches to make the new installation accessible using the same URL prefix:

• You can rename your <newwiki>/ directory to wiki/ (renaming the directory of your old installation if necessary).
• If your operating system supports links to other directories and your web server is configured to follow links, then you can create a link called wiki/ that points to <newwiki>/ (renaming the directory of your old installation if necessary).
• You can configure your web server so that requests to /wiki/ are served from your <newwiki>/ directory.

Re-execute your test plan to verify that your newly-upgraded site is accessible to your users, and that all authentication and authorization mechanisms work as expected (including denying access to those who are not authorized).

Re-execute your test plan to verify that your Wiki applications and other key functionality work as intended.

General information about upgrading From TWiki

Foswiki is compatible with content generated using TWiki releases up to and including 4.3.1, as part of its design. This compatibility is at the disk file level, and means that upgrading from TWiki is easy and reliable.

As part of the creation of the Foswiki project, the Foswiki community is evaluating all of the hundreds of extensions that are available for TWiki. All that are working are ported over to the Foswiki name space. Many of them are being enhanced through the removal of bugs and security vulnerabilities, resulting in better, more functional plugins for Foswiki. The most popular plugins are already ported and more are added every day.

Terminology changes from TWiki

As part of the first Foswiki product release, various topics and terms were changed to avoid using the TWiki brand name and to more accurately reflect their purpose, including the following:

• The TWiki web is now called System, as it contains configuration information for the entire Foswiki installation. The TWikiCompatibilityPlugin provides backwards compatible support for references to the TWiki web, in order to facilitate migrations from TWiki to Foswiki.
• The %TWIKIWEB% and %MAINWEB% variables are now called %SYSTEMWEB% and %USERSWEB%
• Topics in the Foswiki distribution have been renamed to eliminate the TWiki word and to make the titles more readable (for example, Plugins, Skins, and so forth).
• All templates, CSS and Javascript names have been changed from twikiXxxxx to foswikiXxxxx
• Key terminology changes:

TWiki term	Foswiki term
TWiki variable	Macro
preference(s) variable	preference setting, or macro when referring to expansion of same
TWiki form	Data form
TWiki Plugin	Plugin
TWiki Template	Skin Template
Topic Template	Template Topic
TWiki Markup Language (TML)	Topic Markup Language (TML)
TWiki Application	Wiki Application

Topic names changed in System web (former TWiki web)

Old name	New name
ATasteOfTWiki	BeginnersStartHere
TWikiAccessControl	AccessControl
TWikiAddOns	ContributedAddOns
TWikiContribs	Contribs
TWikiContributor	ProjectContributor
TWikiCss	CascadingStyleSheets
TWikiDocGraphics	DocumentGraphics
TWikiDocumentation	CompleteDocumentation
TWikiDownload	DownloadSources
TWikiEditingShorthand	EditingShorthand
TWikiEnhancementRequests	EnhancementRequests
TWikiFaqTemplate	FaqTemplate
TWikiFAQ	FrequentlyAskedQuestions
TWikiForms	DataForms
TWikiGlossary	GlossaryOfTerms
TWikiHistory	ReleaseHistory
TWikiInstallationGuide	InstallationGuide
TWikiJavascripts	JavascriptFiles
TWikiLogos	ProjectLogos
TWikiMetaData	MetaData
TWikiPlugins	Plugins
TWikiPreferences	DefaultPreferences
TWikiReferenceManual	ReferenceManual
TWikiRegistration	UserRegistration
TWikiReleaseNotes04x02	ReleaseNotes01x00
TWikiRenderingShortcut	RenderingShortcut
TWikiScripts	CommandAndCGIScripts
TWikiShorthand	ShortHand
TWikiSiteTools	SiteTools
TWikiSkinBrowser	SkinBrowser
TWikiSkins	Skins
TWikiSystemRequirements	SystemRequirements
TWikiTemplates	SkinTemplates
TWikiTemplates	TemplateTopics
TWikiTopics	TopicsAndWebs
TWikiTutorial	TwentyMinuteTutorial
TWikiUpgradeGuide	UpgradeGuide
TWikiUserAuthentication	UserAuthentication
TWikiUsersGuide	UsersGuide
TWikiVariablesQuickStart	MacrosQuickStart
TWikiVariables	Macros
TWikiWebsTable	WebsTable
TWikiRegistrationAgent	RegistrationAgent

TWikiPlannedFeatures, TWikiReleaseNotes04x00, TWikiSite, and WhatDoesTWikiStandFor have been removed.

Topic names changed in Main web

Old name	New name
TWikiAdminGroup	AdminGroup
TWikiGroupTemplate	GroupTemplate
TWikiPreferences	SitePreferences
TWikiGroups	WikiGroups
TWikiContributor	ProjectContributor
TWikiUsers	WikiUsers
TWikiGuest	WikiGuest
TWikiRegistrationAgent	RegistrationAgent
TWikiAdminUser	AdminUser

These changes have the following consequences when upgrading from TWiki to Foswiki:

• You can either continue to use TWikiAdminGroup as your administrators group, or migrate your admin users to the Main.AdminGroup topic.
• The users in the TWikiUsers topic must be merged into the Main.WikiUsers topic.
• Your site preference settings from Main.TWikiPreferences must be copied to the Main.SitePreferences topic.

Please see UpgradeGuide#CopyUsersAndCustomizations for more information.

Favicon

The favicon is now configurable as a site preference or per-web preference. See System.DefaultPreferences for a description of the FAVICON preference. To set it for your site, add the FAVICON preference to your site preferences topic, Main.SitePreferences (or the topic you configured in your {LocalSitePreferences} setting in the Miscellaneous settings pane on the configure page). To set it for a web, add the FAVICON preference to the WebPreferences topic for that web.

Important changes since TWiki 4.0.5

Supported Perl version

To use Foswiki, you must use Perl 5.8.8 or higher. Foswiki no longer supports Perl version 5.6.x (the minimum version required for TWiki 4.0.5).

Template spec changed

Until TWiki 4.0.5, any text inside template definition blocks for SkinTemplates (formerly called TWikiTemplates) — that is, between %TMPL:DEF{"block"}% and %TMPL:END% — was stripped of leading and trailing white space, including newlines. This made it difficult for skin developers to include a newline before or after a block of text.

From TWiki 4.1.0 onwards, and in Foswiki 1.0, this has changed so that white space is no longer stripped. Skins like PatternSkin and NatSkin have been updated so that they work with the new behavior. If you use an older skin or have written your own you will most likely need to make some adjustments.

In general, if you get mysterious blank lines in your skin, the newline after the %TMPL:DEF{"block"}% needs to be removed: the content of the block must follow on the same line as the TMPL:DEF.

CommentPlugin templates also must be modified to remove extraneous newlines — in particular, any newline immediately after the TMPL:DEF. See the System.CommentPluginTemplate for examples of how comment template definitions should look like in TWiki 4.1.x.

Example: a CommentPlugin template that adds a row to a table. With versions of TWiki prior to 4.1, the following syntax can be used:

%TMPL:DEF{OUTPUT:tabletest}%%POS:BEFORE%
|%URLPARAM{"comment"}%| -- %WIKIUSERNAME% - %DATE% |
%TMPL:END%

Starting in TWiki 4.1 and continuing with Foswiki 1.0, the newline before the start of the table row must be removed:

%TMPL:DEF{OUTPUT:tabletest}%%POS:BEFORE%|%URLPARAM{"comment"}%| -- %WIKIUSERNAME% - %DATE% |
%TMPL:END%

Important changes for the upgrader - since TWiki 4.1.0

New location for session and other temporary files

The directory for passthrough and session files have been replaced by a common directory for temporary files used by Foswiki. Previously the two configure settings {PassthroughDir} and {Sessions}{Dir} were set by default to /tmp. These config settings have been eliminated: Foswiki creates a tmp directory and other temporary directories under the directory defined by the configure setting {WorkingDir}.

Important changes for the upgrader - since TWiki 4.1.2

New WYSIWYG editor

Foswiki now ships with a new WYSIWYG editor based on TinyMCE that replaces the Kupu-based editor. When TinyMCEPlugin is enabled, the Edit button will initiate WYSIWYG editing mode. A Raw Edit link has been added for users to edit the topic markup directly.

The WYSIWYG button has been removed.

NEWTOPICLINKSYMBOL removed

The NEWTOPICLINKSYMBOL preference that was deprecated in TWiki 4.1 is no longer supported. To control the appearance of new links, set the NEWLINKFORMAT preference in Main.SitePreferences (see System.DefaultPreferences for more information on NEWLINKFORMAT).

UserForm and NewUserTemplate customization

When a new user registers on Foswiki his user topic is created based on the NewUserTemplate and UserForm in the Main web, if they exist. If the topic does not exist in the Main web, then the default version from System is used. Thus on upgrades, any customizations you made to NewUserTemplate or UserForm in the Main web will be preserved.

In previous TWiki versions, only System.NewUserTemplate and System.UserForm are used; you cannot override them by creating your own version in the Main web.

WikiUsers no longer distributed

The Main.WikiUsers topic contains all the registered users. It is not included in the Foswiki distribution, so that your list of users will not be overwritten on upgrades. When the first user is registered in Foswiki, the Main.WikiUsers topic is created on demand.

New working directory

The configuration setting {WorkingDir} in the General path settings pane on the configure page defines the location of a working directory for various subdirectories for use by Foswiki. The default value for this setting is the working subdirectory within the installation root directory for the Foswiki installation.

The subdirectories within the working directory include the following:

• registration_approvals — previously located in the data/ directory
• tmp — avoids security issues with using the /tmp directory. (This is not a tmp directory for general use. working/tmp contains CGI Session files.
• work_areas — previously located in the pub/ directory.

Note: Remember to restrict access to this new directory when you upgrade.

If you have your own scheduled task to delete obsolete session files, note they are now located in the working/tmp/ subdirectory.

New internal admin login

Foswiki has a new internal admin login feature that lets you login as a temporary administrator, using "admin" as your user name and a password set in configure. It is an expert setting in the Security and Authentication tab, Passwords sub-tab. The internal admin username can be configured in the {AdminUserLogin} setting in the Security setup pane on the configure page.

Note that as of Foswiki 2.0, the internal admin login does not need to be configured. If necessary to add one later, the new shell configure command tools/configure can be used to set a new password.

In order to add an initial user to the default {SuperAdminGroup}, Main.AdminGroup, you should add the user while you are still running with the bootstrap credentials. Otherwise you must login as the internal admin user using the link on the Main.AdminGroup page.

Important changes for the upgrader - since Foswiki 1.0.4

An additional security feature has been added to Foswiki 1.0.5 so that saving data now requires the http method POST. This means that it is no longer possible to store data via an "<a href=..." link or img tag. It also means that if you have an application with an HTML form that creates new topics you must specify in the form tag method="post". This change is done to further tighten the security of Foswiki.

<form name="new" action="/bin/save/Sandbox/" method="post">
    ...
</form>

The template webs _default and _empty are frequent targets for spammers because these webs are normally not monitored very carefully by the community around a Foswiki installation. These webs are now write protected so on an administrator can edit topics in these webs. When an administrator creates a new web it is important to remember to remove the access restriction from the %WEBPREFSTOPIC% in the new web.

Important changes for the upgrader - since Foswiki 1.0.5

Foswiki 1.0.6 introduces a major security enhancement, protecting against Cross-Site Request Forgery. The extra safe "double submit" algorithm, as recommended by the Open Web Application Security Project (OWASP) project has been used. This is the same algorithm used by several major banks and other security-conscious institutions, and requires that users have Javascript enabled.

See Foswiki:Support.SecurityFeatures for more information on these, and other, Foswiki security features. This is recommended reading for all Foswiki administrators.

If these new countermeasures against CSRF creates problems for your users and your applications, you can alter the way the protection works or disable it. These are the configure parameters you need to visit (note that some are expert settings).

• {Validation}{Method} is by default "strikeone" which is the highest level of security and requires that users have Javascript enabled. You can lower this setting to "embedded" which uses a less safe validation method but does not require javascript. If you want to disable CSRF protection set it to "none". It is highly recommended to keep it at "strikeone".
• {Validation}{ValidForTime} is the time the validation key is valid. It is by default 1 hour. If your users often edit pages longer you can increase this time. Your users can still save pages with an expired validation key but they will be asked to confirm the saving.
• {Validation}{MaxKeysPerSession} is the maximum number of validation keys to store in a session. There is one key stored for each page rendered. If the number of keys exceeds this number, the oldest keys will be force-expired to bring the number down. If you have users that are very fast at editing pages and experience expired keys, you can increase this number. The default is 1000 and should be much higher than any normal person will experience.
• {Validation}{ExpireKeyOnUse} defines if validation keys expire when they are used for storing data. This prevents an attacker from evesdropping communication between server and browser and reuse keys. Unfortunately it also means that if a user edits a page, saves it, uses the back button of the browser, corrects his previous editing, and then saves again, he is asked to confirm that he intended to save the topic. Another use case is if you create an application with multiple forms and multiple submit buttons on a topic and you submit multiple times from this topic without navigating away from it, you will be asked to confirm the submission each time. If this is not acceptable to your use of Foswiki, you can turn off {Validation}{ExpireKeyOnUse}.

Important changes for the upgrader - since Foswiki 1.0.x

ADDTOZONE instead of ADDTOHEAD

Foswiki 1.1.0 introduces the concept of zones, realised by the ADDTOZONE and RENDERZONE macros. Although ADDTOHEAD will continue to work, there may be problems with Foswiki applications that use ADDTOHEAD to add <script>... markup to the page where dependencies have been required which are now added with %ADDTOZONE{"script"....

Foswiki treats the head and script zones of a page separately and won't be able to order these dependencies properly unless the {MergeHeadAndScriptZones} option is set in configure. This feature will be removed in a future version of Foswiki.

See also Foswiki:Development.UpdatingExtensionsScriptZone, VarADDTOZONE and Foswiki:Development.UsingADDTOZONE

JQueryPlugin

Foswiki 1.1.x ships with JQueryPlugin by default. If you are upgrading from a 1.0.x site that used previous versions of JQueryPlugin, care needs to be taken to ensure that your existing jQuery code is compatible with the new JQueryPlugin.

• The foswiki DOM object is no longer automatically populated from <meta .../> tags. See JQueryCodingStandards to learn about the new foswiki.getPreference('SOMETHING'); method.
• JQueryPlugin now uses the script zone to add <script>... markup. If your existing wiki applications used something like

  %JQREQUIRE{"cycle"}%%ADDTOHEAD{"MyApp" requires="JQUERYPLUGIN::CYCLE" text="<script..."}%

  then this code will no longer be guaranteed to be ordered after the JQUERYPLUGIN::CYCLE markup, unless {MergeHeadAndScriptZones} has been enabled in configure. It needs to be re-written as per the instructions at Foswiki:Development.UpdatingExtensionsScriptZone. See also VarADDTOZONE and Foswiki:Development.UsingADDTOZONE

JavascriptFiles and BehaviourContrib

If you have written wiki applications or plugins that assumed the presence of certain Foswiki JS libraries, such as behaviour (no longer shipped with Foswiki), System/JavascriptFiles/foswikilib.js, System/JavascriptFiles/foswikilib.js, System/JavascriptFiles/foswikilib.js etc. these should now be explicitly required into the page using

%TMPL:P{"JavascriptFiles/foswikiPref"}%

as instructed at Foswiki:Development.UsingADDTOZONE

TinyMCEPlugin TINYMCEPLUGIN_INIT changes

TinyMCEPlugin 's configuration scheme has been reorganised. If you had a customised TINYMCEPLUGIN_INIT preference variable on Foswiki 1.0.x, it will need to be removed, re-built, replaced with a dedicated topic section or replaced with newly introduced preference variables for Foswiki 1.1.x. See upgrade advice for more information.

Logging

Foswiki 1.1 uses a new configurable location for logs (a pluggable logging API has been introduced):

Old location	New location
data/warnYYYYMM	working/logs/error.log
data/logYYYYMM	working/logs/events.log
data/configure.log	working/logs/configure.log

The currently used log file is always the same name. They are renamed to somehthing resembling the old scheme on a monthly basis automatically.

Managing caches of static files during upgrade

Managing caches of static .js, .css files: some parts of Foswiki use URI versioning to help web browsers obtain a current version of these files when they change, but currently other parts do not. You may need to get your users to clear their browser's cache after upgrading your site to a new major or minor release (usually not necessary for patch upgrades). An alternative approach is to manage your web server configuration to strategically set appropriate expiry times for static files (see performance supplement)

Important changes for the upgrader - since Foswiki 1.1.4

Due to fixes to the authentication session cookies when using http and https, your users may need to login again. This applies to both TemplateLogin and ApacheLogin.

---

Related Topics: AdminDocumentationCategory, Foswiki:Support.InstallationGuide, Foswiki:Support.InstallingOnSpecificPlatforms, Foswiki:Support.ApacheConfigGenerator, Foswiki:Support.SettingFileAccessRightsLinuxUnix