upgrade3Add my vote for this tag create new tag
, view all tags
Get Involved!
TWiki is an open source project with 10+ years of history, built by a team of volunteers from around the world, and used by millions of people in over 100 countries. The community is focusing on building the best collaboration platform for the workplace. We invite you to get involved!

ALERT! NOTE: This is a DistributionDocument. Please help maintain high quality documentation: This is a wiki, please fix the documentation if you find errors or incomplete content. Put questions and suggestions concerning the documentation of this topic in the comments section below. Use the Support web for problems you are having using TWiki.

TWiki Upgrade Guide

This guide covers upgrading from a previous version of TWiki (such as TWiki-5.1) to TWiki-6.0


TWiki-6.0.0 is a major release that has a shiny new dashboard look. It brings many usability enhancements, strengthens TWiki as an application platform, and scales to very large deployments with thousands of webs and a million pages. Use this guide to upgrade a previous TWiki release to TWiki-6.0. Use the TWikiInstallationGuide if you do not have data to carry forward.

Upgrade Requirements

  • Please review the AdminSkillsAssumptions before you upgrade TWiki
  • Review supplemental document TWiki:TWiki.TWikiUpgradeTo06x00 for latest information and experience notes.
  • To upgrade from a release prior to TWiki Release 01-Sep-2004, start with TWiki:TWiki.UpgradingTWiki on TWiki.org
  • To upgrade from a standard TWiki Release 01-Sep-2004 to the latest TWiki-6.0 Production Release, follow the instructions below
  • 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. Make sure you take a backup!

Major Changes Compared to Earlier TWiki Releases

See TWikiReleaseNotes04x00, TWikiReleaseNotes04x00x00, TWikiReleaseNotes04x01, TWikiReleaseNotes04x02, TWikiReleaseNotes04x03, TWikiReleaseNotes05x00, TWikiReleaseNotes05x01, TWikiReleaseNotes06x00

New Upgrade Option with BackupRestorePlugin

TWiki now has a new solution to backup, restore and upgrade TWiki sites. It can be used via browser and on the command line. The BackupRestorePlugin is pre-installed in TWiki-5.1 and later releases; it can be installed in older TWiki releases as low as TWiki-2001-09-01 (Athens Release) to easily create a backup that can be restored on a new TWiki release. This offers an easy upgrade path for TWiki. The plugin is currently in Beta, check TWiki:Plugins.BackupRestorePlugin for updates.

Upgrade Procedure

The following steps are a rough guide to upgrading only. It is impossible to give detailed instructions, as what you have to do may depend on whether you can configure the webserver or not, and how much you have changed distributed files in your current TWiki release.

The main steps are:

  1. Install the new TWiki version, configure it, and get it to work similar to the old version
  2. Install additional extensions (plugins) -- make sure to use the latest versions
  3. Copy all the non-default webs from the old installation to the new
  4. Copy the users from old installation to the new including all their topics from Main
  5. Apply customizations to your skin (logos, menu bars etc)
  6. Apply preferences from old installation
  7. Switch-over

TIP After the extensions are installed (or upgraded) in step 2, take a "golden" backup. That will come in handy for your next patch or upgrade: By checking the differences between the golden copy and your production copy, you will be able to identify all the modifications that you have applied to the core or extensions.


  • Follow the installation instructions at TWiki:TWiki.TWikiInstallationGuide. Install the new release in a new directory. Do not install on top of the old release.
  • Use the configure script to configure TWiki.
    • If you are upgrading from a 4.x.x release, you can carry over the configure settings from the old release.
    • You need to run configure and save the configuration once when you upgrade as this will update the altered and added settings.
    • You can also choose to start with a fresh configuration and walk through all the settings using your old twiki/lib/LocalSite.cfg as a reference. This way you will not have old obsolete settings in the new LocalSite.cfg.
    • If at any time during the installation you want to start over from fresh, delete the LocalSite.cfg file and re-run configure.
  • Additional resources
  • Make sure you have a working basic TWiki before you continue

Install Extensions

  • From TWiki-4.1.0 and on, the configure script which you ran during installation supports installation of additional plugins.
  • Manual installation is possible. Follow the instruction on the plugin page at twiki.org.
  • Check the plugin topics from your old TWiki installation. There may be plugin settings that you want to transfer to the new TWiki installation.
    HELP Hint: For an easier upgrade later on, set the plugin preferences settings in the Main.TWikiPreferences topic, not in the plugin topic. To identify the plugin, prefix the name of the setting with the capitalized name of the plugin. For example, to change the DEFAULT_TYPE setting of the CommentPlugin, create a COMMENTPLUGIN_DEFAULT_TYPE setting in Main.TWikiPreferences.
  • Typical plugin settings you may have altered.
    • CommentPlugin - Set DEFAULT_TYPE
    • EditTablePlugin - Set CHANGEROWS, Set QUIETSAVE, and Set EDITBUTTON
    • InterwikiPlugin - Set RULESTOPIC
    • InterWikis - If you added your own rules you should save this topic and not overwrite it.
    • SlideShowPlugin - Make sure you did not change the embedded 'Default Slide Template' If you did you should save it. It is a bad idea to do. It is better to define your own slide show templates as separate topics that do not get overwritten when you upgrade.
    • SmiliesPlugin - Did you add your own smileys?
    • TablePlugin - Set TABLEATTRIBUTES.
  • Remember that a plugin must be activated in configure.
  • To avoid having to re-apply plugin settings each time you upgrade a plugin or TWiki itself, define the altered plugin settings in Main.TWikiPreferences instead.

Copy your old webs to new TWiki

  • Webs come in pairs, such as twiki/data/Engineering (for page content) and twiki/pub/Engineering (for attachments).
  • When upgrading from 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 '{}' \;
  • Copy your local webs over to the data and pub directories of the new install. Do not copy the default webs: TWiki, Main, Trash, Sandbox, _default, and _empty.
  • Make sure all data and pub files and directories are owned by the webserver user.
  • Note: TWiki's WebChanges topics depend on the file timestamp. If you touch the .txt files make sure to preserve the timestamp, or to change them in the sequence of old file timestamps.

Copy Users And Their Topics From Main Web

  • Copy all the topics from the Main web and corresponding pub/Main directories from the old TWiki to the new TWiki but do not overwrite any of the new topics already inside the new Main directory!
  • Manually merge all the users from the old Main.TWikiUsers topic to the new TWiki. If you upgrade from Cairo you can simply use the old file and add the missing new system users to the list of users. If you upgrade from TWiki-4.0.x simply use the old topic. Starting from 4.2.0 TWiki no longer ships with a Main.TWikiUsers topic. When you register the first user TWiki now checks for an existing Main.TWikiUsers and if it does not exist it gets created.
    • If you want users to be able to use a login ID other than their WikiName, such as when using LDAP or SSO authentication, set the configure setting {Register}{AllowLoginName} to 1.
  • If you use data/.htpasswd for authentication copy this file from the old TWiki to the new.
    • If you upgrade from Cairo and you are using the Htpasswd login manager, then note that email addresses for users have moved out of user topics and into the password file. There is a script that performs this extra upgrade step for you - see tools/upgrade_emails.pl.
  • The old Sandbox web may have a lot of useful topic and users may use it actively for drafts. Manually select the topics (remember the corresponding pub directories) from the old Sandbox web and copy them to the one of the new TWiki. Decide if you want to overwrite the sandbox homepage and left menu bar or keep the new.
  • If you added or removed fields from the user topic form you may also have tailored TWiki.TWikiRegistration. Make sure you either reuse the registration topic from the old installation or apply the same field changes to the new TWiki.TWikiRegistration topic.
  • Starting from 4.2.0 TWiki ships with NewUserTemplate and UserForm in the TWiki web. If you choose to tailor anything you are strongly advised to copy NewUserTemplate and UserForm to the Main web and tailor the Main web copies. TWiki will look for the NewUserTemplate in the Main web first and if it does not exist it uses the default from the TWiki web. By creating a Main.NewUserTemplate and its Main.UserForm you will not loose your tailorings next time you upgrade TWiki.
  • Make sure all data and pub files and directories are owned by the webserver user.

Apply Customizations To The Skin

Apply Preferences From Old Installation

  • Transfer any customized and local settings from TWiki06x00.TWikiPreferences to the topic pointed at by {LocalSitePreferences} (Main.TWikiPreferences). Per default this is Main.TWikiPreferences. This avoids having to write over files in the distribution on a later upgrade.
  • If you changed any of the topics in the original TWiki distribution, you will have to transfer your changes to the new install manually. There is no simple way to do this, though a suggestion is to use 'diff' to find changed files in the data/TWiki of the old and new TWiki installation, and transfer the changes into the new TWiki install. If you can run a GUI on your server, you may find that using a visual diff tool like WinMerge, meld, kdiff3, xxdiff, etc. is helpful.
  • Compare the WebPreferences topics in the old TWiki Installation with the default from the new TWiki installation and add any new Preferences that may be relevant.
  • Compare the WebLeftBar topics in the old TWiki Installation with the default from the new TWiki installation and add any new feature that you desire.


Once you have tested the new TWiki you can switch over to the new site.

If the same domain and URL is used:

  • Update the DNS settings of the TWiki domain with the IP address of the new TWiki server.
  • Keep in mind that the updated DNS is not seen immediately by all users at the same time. The DNS propagation can take several hours and depends on the time to live (TTL) setting. Because of this it is recommended to disable content update on the old server. You could simply rename or move all scripts in twiki/bin that allow content update, such as attach, edit, manage, rename, save, upload, rest. Alternatively, if you have a recent TWiki version on the old server you can set a READONLYSKINMODE = 1 setting in Main.TWikiPreferences to turn the skin into read-only mode.

If the domain or URL changes:

  • Add a DNS setting for the new TWiki domain if needed.
  • Redirect users visiting the old TWiki to the new TWiki. The TWiki:Plugins.MovedSkin has been designed for that task. Install it on your old TWiki, and configure it with the proper URL of the new TWiki. After that, users on the old TWiki will see a yellow box informing them of the move, with a link to the new URL of the page visited.

Customization of Special Pages

Some pages in the TWiki web are meant to be customized after choice of authentication. If you do not use the internal TWiki password manager the topics that contains the features for changing and resetting passwords and changing the email address should be changed to a note describing how to perform these tasks in your organization. If you have made such customizations remember to replace these topics in the TWiki web with the tailored versions from your old installation. The topics are:

  • TWiki.ChangePassword
  • TWiki.ResetPassword
  • TWiki.ChangeEmailAddress

Upgrading from Cairo to TWiki-4 (additional advice)


TWiki-4's PatternSkin introduces the use of the favicon feature which most browsers use to show a small icon in front of the URL and for bookmarks.

In TWiki-4 it is assumed that each web has a favicon.ico file attached to the WebPreferences topic. When you upgrade from Cairo to TWiki-4 you do not have this file and you will get flooded with errors the error log of your web server. There are two solutions to this.

  • Attach a favicon.ico file to WebPreferences in each web.
  • Preferred: Change the setting of the location of favicon.ico in TWikiPreferences so all webs use the favicon.ico from the TWiki web. This is the fastest and easiest solution.

To change the location of favicon.ico in TWikiPreferences to the TWiki web add the following setting to Main.TWikiPreferences:


TWikiUsers topic in Main web

Your old Main.TWikiUsers topic will work in the new TWiki but you will need to ensure that the following four users from the TWikiUsersTemplate topic are copied to the existing TWikiUsers topic in proper alphabetical order:

   * TWikiContributor - 2005-01-01
   * TWikiGuest - guest - 1999-02-10
   * TWikiRegistrationAgent - 2005-01-01
   * UnknownUser - 2005-01-01

What these users are:

  • TWikiContributor - placeholder for a TWiki developer, and is used in TWiki documentation
  • TWikiGuest - guest user, used as a fallback if the user can't be identified
  • TWikiRegistrationAgent - 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

You additionally need to ensure that TWikiUsers has the Set ALLOWTOPICCHANGE = TWikiAdminGroup, TWikiRegistrationAgent access control setting. Otherwise people will not be able to register.

Important Changes since TWiki-4.0.5

Supported Perl version

TWiki 4.0.5 worked on Perl version 5.6.X. Reports from users has shown that unfortunately TWiki 4.1.0 does not support Perl versions older then 5.8.0. It is the goal that TWiki should work on at least Perl version 5.6.X but none of the developers have had access to Perl installations older than 5.8.0.

Since TWiki 4.1.0 has some urgent bugs the development team decided to release TWiki 4.1.1 without resolving the issue with Perl 5.6.X. We will however address this and try and resolve it for a planned 4.1.2 release. The TWiki community is very interested in contributions from users that have fixes for the code which will enable TWiki to run on older versions of Perl.

See the WhatVersionsOfPerlAreSupported topic to keep up to date with the discussion how to get back support for earlier Perl versions.

Template spec changed

Until TWiki 4.0.5 TWikiTemplates the text inside template definition blocks (anything between %TMPL:DEF{"block"}% and %TMPL:END% was stripped of leading and trailing white space incl new lines.

This caused a lot of problems for skin developers when you wanted a newline before or after the block text.

From TWiki 4.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. But if you use an older skin or have written your own you will most likely need to make some adjustments.

It is not difficult. The general rule is - if you get mysterious blank lines in your skin, the newline after the %TMPL:DEF{"block"}% needs to be removed. Ie. the content of the block must follow on the same line as the TMPL:DEF.

The spec change have the same impact on CommentPlugin templates where you may have to remove the first line break after the TMPL:DEF. See the CommentPluginTemplate for examples of how comment template definitions should look like in TWiki-4.1.X

An example: A CommentPlugin template that adds a comment as appending a row to a table. Before the spec change this would work.

|%URLPARAM{"comment"}%| -- %WIKIUSERNAME% - %DATE% |

From Twiki 4.1.0 the old template definition will add an empty line before the new table row. To fix it simply remove the new line before the table.

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

The advantage of the spec change is that now you can add leading and trailing white space including new lines. This was not possible before.

Important Changes since TWiki-4.1.0

New location for session and other temporary files

An upgrader upgrading to 4.1.1 should note the following important change

The directory for passthrough files and session files have been replaced by a common directory for temporary files used by TWiki. Previously the two configure settings {PassthroughDir} and {Sessions}{Dir} were by default set to /tmp. These config settings have been replaced by {TempfileDir} with the default setting value /tmp/twiki. If the twiki directory does not exist twiki will create it first time it needs it.

It is highly recommended no longer to use the tmp directory common to other web applications and the new default will work fine for most. You may want to delete all the old session files in /tmp after the upgrade to 4.1.1. They all start with cgisess_. It is additionally highly recommended to limit write access to the {TempfileDir} for security reasons if you have non-admin users with login access to the webserver just like you would do with the other webserver directories.

Important Changes since TWiki-4.1.2

New WYSIWYG Editor

TWiki now ships with a new WYSIWYG editor based on TinyMCE which replaces the Kupu based editor. TinyMCE is not a perfect Wysiwyg editor but it is magnitudes better than the previously used Kupu editor.

The WysiwygPlugin that drives the engine behind both TinyMCE has additionally been heavily improved so that fewer TWiki Applications are negatively affected by editing in WYSIWYG mode.

When TinyMCEPlugin is enabled, the Edit button by default becomes WYSIWYG editing mode. A new Raw Edit link has been added to enable application developers to edit the good old way.

The WYSIWYG button has been removed.


The NEWTOPICLINKSYMBOL preference which was deprecated in 4.1 has now been removed from the code. If you want to control the appearance of new links, you can use NEWLINKFORMAT.

UserForm and NewUserTemplate Customization

When a new user registers on TWiki his user topic is created based on the NewUserTemplate and UserForm.

The NewUserTemplate was located in the TWiki web and the UserForm in the Main web. When upgrading TWiki these were some of the topics you had to take care not to overwrite.

From 4.2.0 the UserForm and NewUserTemplate are distributed in the TWiki web. If you create the two in the Main web the Main web version will be used instead. So if you tailor the user topic format or the form then you should always copy the two files to the Main web and modify the ones in the Main web. When you later upgrade TWiki your tailored template and form will not be overwritten.

TWikiUsers no longer distributed

The Main.TWikiUsers topic contains all the registered users. It is a topic you do not want to overwrite when you upgrade TWiki.

From 4.2.0 this file is no longer included in the TWiki distribution. When you register the first time TWiki creates the Main.TWikiUsers topic in the Main web if it does not exist already. This means that you can now upgrade TWiki without risk of overwriting the important TWikiUsers topic.

  • For new installers this makes no difference at all
  • For upgraders this is one less problem to worry about as your important Main.TWikiUsers topic now no longer gets overwritten when upgrading.

New working directory

A new working directory which by default is located in the twiki root, has been introduced which contains:

  • registration_approvals - with 4.2.0 it is moved to here from the data directory.
  • tmp - so we now avoid having to fight with special access rights and /tmp directory that gets cleaned out when booting.
  • work_areas - with 4.2.0 it is moved to here from the pub directory. Configure automatically moved the directory when you upgrade.

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

The configure setting {WorkingDir} defines the container directory for temporary files, extensions' work areas, and intermediate registration data. The default is working under your installation root.

Take care for that change if you run your own routine to delete obsolete session files, which will now be found under working/tmp/cgisess*.

New Internal Admin Login

TWiki 4.2 introduces a new Internal Admin Login feature which uses "admin" (configurable) as username and the password used for configure to become temporary administrator. When you do a new installation you need to use this feature as Main.TWikiAdminGroup is now access restricted by default to avoid security attacks during the hours an installation may take. From configure there is a link to the TWikiAdminGroup topic and on TWikiAdminGroup the step by step instructions are written in a yellow box. Our advice is not to remove this help text in case you need it later.

Important Changes since TWiki-5.0.0

New TopMenuSkin

The TopMenuSkin adds pulldown menus for better usability and corporate/modern look&feel. This skin is based on the PatternSkin, which used the WebLeftBar in each web for navigation. The TopMenuSkin has a new WebTopBar that defines the menu structure in each web. A default menu is shown in case WebTopBar is missing in a web, so you do not need to add a WebTopBar topic to all your existing webs. See TopMenuSkin#WebSpecific instructions in case you need a customized menu structure in a specific web.

Important Changes since TWiki-5.1.0

New Page Bookmarks Feature

A new bookmark feature has been introduced that replaces the personal left-bar links. Bookmarking a page is now a simple point and click operation: In the Account pulldown menu, select "Bookmark this page...". Existing bookmarks can be managed with an edit table in Main.<wikiname>Bookmarks topic, accessible via the "----- Bookmarks -----" pulldown menu of the Account pulldown.

The personal left-bar topics such as JohnSmithLeftBar are no longer used. Ask users to select the "----- Bookmarks -----" pulldown menu of the Account pulldown to initially create the bookmarks topic, then to either bookmark pages, or to manually copy & paste old left-bar links to the bookmarks topic.

User Profile Pages Tailored for Workplace

Previous user profile pages had a bare bones look and the form fields were more tailored for public TWiki sites. TWiki-5.1 brings a more visual/modern page layout with profile picture selector, as well as default form fields tailored for the workplace.

Changes to the TWiki06x00.UserForm:


  • FirstName to First Name (no change in %META:FIELD name)
  • LastName to Last Name (no change in %META:FIELD name)
  • OrganisationName to Organization
  • OrganisationURL to URL
  • Profession to Titles
  • VoIP to Skype ID
  • State to Region
  • Address
  • InstantMessaging (IM)
  • HomePage
  • Comment
  • Department
  • Status Update

When upgrading user profile pages pay attention to the renamed and removed fields.

Important Changes since TWiki-6.0.0

Spec Change for Empty DENYTOPICVIEW

From TWiki 4.0 and prior to 6.0, the syntax * Set DENYTOPICVIEW = (nothing) in a topic means deny nobody the topic view. The reason for this behavior is that it allows public access to a topic in a restricted web, e.g. having * Set ALLOWWEBVIEW = Main.VipGroup in WebPreferences. This is not symmetric with the fact that an empty DENYWEBVIEW is the same as an undefined DENYWEBVIEW, hence confusing.

From TWiki 6.0 on, an empty DENYTOPICVIEW means the same as not defined. To open up a topic in a restricted web, you need to use * Set ALLOWTOPICVIEW = Main.AllUsersGroup. The Main.AllUsersGroup is new. It is a pseudo group containing all authenticated and unauthenticated users. You can use Main.AllAuthUsersGroup if you want to specify all authenticated users.

To keep publicly accessible topics in restricted webs publicly accessible, the tools/eliminate_emptydenytopic script is provided, which replaces * Set DENYTOPIC<action> = with * Set ALLOWTOPIC<action> = Main.AllUsersGroup in all topics in all webs.

Note: See more changes since TWiki-6.0.0 in TWikiReleaseNotes06x00.

Related Topics: AdminDocumentationCategory, TWiki:TWiki.UpgradingTWiki, TWiki:TWiki.UpgradingTWiki04x00PatchReleases, TWiki:TWiki.InstallingTWiki#OtherPlatforms, TWiki:TWiki.ApacheConfigGenerator, TWiki:TWiki.SettingFileAccessRightsLinuxUnix

Contributors: TWiki:Main.PeterThoeny, TWiki:Main.KennethLavrsen, TWiki:Main.CrawfordCurrie, TWiki:Main.HaraldJoerg, TWiki:Main.BobBagwill

Comments & Questions about this Distribution Document Topic

-- PeterThoeny - 26 Feb 2006

The step-by-step instructions on topic upgrade we had in TWiki03.TWikiUpgradeGuide are lost. It would be helpful to review and update the docs with:

  • topics that need to be retained in TWiki web
  • topics that need to be updated in Main web
  • topics that need to be updated in all other webs
See confused user in Support.WillUpgradingTWikiDestroyDoco

-- PeterThoeny - 01 Jun 2006

I am trying to upgrade 02 sept 2004 to twiki 4.0.4. I have following the instuction on the site using UpgradeTwiki. All went well, only 10 rej file. I have made the changes to the new topic. The problem is that when I try to hit the site, the content are not displayed properly. Any suggestion?

-- DavidAguilera - 17 Aug 2006

Please ask support questions in the Support web, thanks.

-- PeterThoeny - 17 Aug 2006

Does this procedure apply to upgrading to beyond TWiki-4.0.0? Or is one supposed to upgrade to the 4.0.0 major release level, and then apply further updates on top of that to get to current?

-- DavidForrest - 01 Nov 2006

This applies to upgrading TWiki from a pre-TWiki 4.0 release to any TWiki 4.0.x release. For incremental TWiki.4.0.x upgrades refer to the relevant TWikiRelease04x00 topic.

-- PeterThoeny - 01 Nov 2006

How would I upgrade 5, 10, 100 TWiki's? The current upgrade procedure is labor-intensive and error-prone, IMHO.

-- BobBagwill - 23 Jan 2007

We are aware of the upgrade issues, with each release we make it a bit easier. Please ReadmeFirst if you would like to get involved. We look forward for ideas how to make an upgrade dead easy.

-- PeterThoeny - 24 Jan 2007

I'm attempting to upgrade from Beijing (01-Feb-2003) to Edinburg (4.1). Right now I have a the old working system on the Beijing release and a 4.1 installation on the new target system, and my task is to migrate over our web data. In addition to the info for Cairo migration, any other gotchas or advice? Thanks!

-- MarcHebert - 29 Oct 2007

Please ask support questions in the Support web (see migration topics)

-- PeterThoeny - 30 Oct 2007

I recently upgraded from a pre-4.0 version of TWiki and I found this upgrade guide very useful. However, I ran into a couple of problems caused by the following find commands in the Copy your old webs to new TWiki section of the guide:

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

On HP-UX these commands changed the ownership of the "*,v" files to that of the user running the commands. In my case, as I'm sure is the case for many administrators, I was performing the update while logged in as root. However, all the files in the TWiki hierarchy are supposed to be owned by the web server user (which is not root!). The result was that topics could not be edited due to a security violation. A simple chown command fixed all the files, but it did take a few minutes to track it down, and it would have been nice if the upgrade guide had included a warning.

The second problem was more insidious. We didn't discover it right away, and it took a lot of time to figure it out and fix it. As it turns out, those find commands also happened to update the modification dates of all my ",v" files! TWiki worked fine after that, as I could edit and save topics, and view their revision histories. But the WebChanges topic showed a completely incorrect and seemingly random list of topics, and none of the topics which I knew to have been changed recently showed up. This was apparently due to to the fact that TWiki generates the WebChanges on the fly by looking at the file modification dates.

I was able to fix the mod dates of all my ",v" files by using the following shell script (which also did the chmod part, too):

  cd twiki/data/Myweb
  for x in $(ls *,v) ; do
     y=$(echo $x | cut -d, -f1)
     touch -m -r $y $x
     chown apache:www $x

I don't know if anyone else has run into this, but from my perspective it sure would have been nice if I had been warned of this... it would have saved me several hours of research.

-- BarryLake - 10 Dec 2007

Thanks Barry. I added a note accordingly (and synched the changes from SVN.)

-- PeterThoeny - 11 Dec 2007

This is too complicated. Is it possible to stop developing additional functionality into the twiki and focus on making it maintainable? I'm sorry, I don't mean to be flip, but the biggest barrier to adoption of wikis is the perception from business people that it is something only to be used by geeks. The complexity and difficulty involved in working with twiki to install, upgrade, or implement plugins--followed by complicated training efforts to explain how to do things reinforces that perception and embarasses me as an advocate of the software.

-- DaveAtkins - 12 Dec 2007

Good feedback, thanks Dave. The TWikiCommunity and TWIKI.NET is working on usability enhancement, as well as on making install/upgrade easier. The upcoming TWiki 4.2 release has a much better WYSIWYG editor and many smaller usability enhancements.

We'd love to get more feedback from the user community, especially from the business side. If you want to get involved I invite you to participate in the Codev web, for example in UsabilityIdeas and TWikiMarketing. If you wish you can participate in our biweekly #twiki_marketing IRC meetings.

-- PeterThoeny - 13 Dec 2007

I would like to second DaveAtkins's point, and emphasize the pain that comes to admins in upgrading, not only to major versions but minor ones as well. It's true that TWiki is not simple to install (actually it seems that TWiki itself is, but it's its dependencies that become tedious), but upgrades require so much manual testing and munging that the task becomes near contemptible, to the point where a site with a good deal of content and a few customizations takes weeks or months to migrate.

TWiki is excellent software and very good at what it does, but the administration aspect is becoming increasingly difficult to manage and justify.

If there is a more succinct method that someone has used successfully to bring a 4.1.2 site to 4.2, I'd be grateful to see it, as well as glad to help "beautify" it for official documentation, if that would be of use.

-- JohnDeStefano - 23 Jan 2008

At "Note: TWiki's WebChanges topics depend on the file timestamp. If you touch the .txt files make sure to preserve the timestamp, or to change them in the sequence of old file timestamps" :

  • Maybe a lot easier (for the end-user trying to upgrade) using cp from the GNU tools :
    • cp -rupfv ./old-data/* ./data/
    • cp -rupfv ./old-pub/* ./pub/
-- AlexandreDulaunoy - 31 Jan 2008

> If there is a more succinct method that someone has used successfully to bring a 4.1.2 site to 4.2, I'd be grateful to see it

I don't think there are shortcuts there: it takes a new installation and migration of the content.

My current concern is to retain the customization that I've done since that upgrade. Even a minor patch requires most of those to be redone (unless it was a mod to fix a bug that happens to have been fixed in the patch). I found that to be nowhere near as easy as described in Upgrading TWiki 4.X and Maintaining Current Tailoring.

But with this rev, I have added a tip to help identify where all those mods are.

-- SeanCMorgan - 19 Aug 2008

Sean, your paragraph has not yet made it into svn. Someone needs to do it.

-- PeterThoeny - 30 Mar 2009

This topic is now up to date and synched with svn.

-- PeterThoeny - 2009-04-11

I recently upgraded to TWiki 4.3.2.Yes I know its old code, but I at least wanted the system patched before tackling a 5.0 migration.

The suggested upgrade path I read on another topic was to copy over files from the TWiki-4.3.2-upgrade.tgz file over an existing installation.

Please be aware that the file permissions in the TWiki-4.3.2-upgrade.tgz file containing the upgrade differ greatly from the TWiki-4.3.2.tgz file containing a full installation.

A simple example.

from TWiki-4.3.2.tgz:

-r-xr-xr-x apache/apache 1103 2009-09-02 15:29 bin/view

from TWiki-4.3.2-upgrade.tgz:

-rw-r--r-- apache/apache 1103 2009-09-23 16:32 bin/view

blindly untarring the upgrade tarball over a working installation on a UNIX system may render it useless. It looks like the permissions in the upgrade tarball are all over the place.

I used the following UNIX & perl commands to generate a repair_permissions script to be the same as the new installation tarball, which is then run as the apache user in the ~twiki home directory.

su apache

# change to the directory where twiki is installed

cd ~apache/twiki

# store the install tarball in the TWiki installation root from the web page

# tar out the manifest

tar tvfz TWiki-4.3.2.tgz > install-manifest

# extract the file permissions from the manifest

more install-manifest|perl -e 'while (<>) { @a=split(); print "$a[0] $a[5]\n";}' >install-manifest-permissions

# convert to numeric format

more install-manifest-permissions |perl -e 'while (<>) { s/-r--r--r--/444/;s/-r-xr-xr-x/555/;s/-rw-r--r--/644/;s/drwxr-xr-x/755/;s/-rw-rw----/660/;s/-r--r-----/440/;print}' > manifest-permissions

# autogenerate chmod commands

more manifest-permissions |perl -e 'while (<>) {split;print "chmod ".@_[0]." ".@_[1]."\n";}'>repair_permissions

# run the commands chmod u+x repair_permissions bash repair_permissions

Hope this helps someone else.

But really the file permissions should be set correctly in the original distro. Or there should be a script to repair them (like in bugzilla's installer)

The permissions topic at SettingFileAccessRightsLinuxUnix does not cover the 4.3 release yet.

I'm also not sure why the apache user needs 755 on the twiki/bin directory and subdirectories. Surely in an ideal world the directories would be 550? or 555?

Same for twiki/lib and subdirectories. Shouldn't any config files then be stored in twiki/cfg which is 750 or 755. Everything else that is maintained distributed code should be 550 or 555 by default to ease upgrades?

Of course we want the apache daemon user to be able to alter content (the whole point of web2.0) but I'm not sure why anyone would want to risk an apache daemon user being able to alter the code on the fly.

-- RayHunter - 2010-08-04

Thanks for the feedback. Good points, the upcoming upgrade tarball for 5.0.x needs to be packaged properly. We will not fix older packages.

As for twiki/bin and twiki/tools files, 555 seems a sensible way. 550 might fail on some hosted environments.

The twiki/lib files are supposed to be 444. For ease of plugin installation (using configure) all lib dirs need to be owned by the Apache user. Personally I prefer to have them owned by root, and I manually install plugins.

Please feel free to post an enhancement at TWikiFeatureProposals. If you commit to implementing the change you get a good likelihood that this will get accepted.

-- PeterThoeny - 2010-08-04

Thanks GuyKroizman for typo-fix. This is now in SVN trunk and TWiki-5.1 branch.

-- PeterThoeny - 2012-02-28

Thank you JonForrest for fixing the docs! I took the changes back into SVN trunk and 5.1 branch.

For future edits, you can make it easier for the person checking in if you edit the topic in raw mode. The WYSIWYG editor tends to change some content in undesirable ways, and it is difficult to see what you changed vs what the WYSIWYG editor did.

-- Peter Thoeny - 2013-06-28

Thanks TerjeAndersen for enhancing the docs - I synched it into SVN trunk and 5.1 branch.

-- Peter Thoeny - 2013-07-16

Please use the Support forum if you have questions about TWiki features. This comment section is about the documentation of this topic.
Edit | Attach | Watch | Print version | History: r54 < r53 < r52 < r51 < r50 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r54 - 2013-10-15 - PeterThoeny
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2015 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.