Foswiki Release 2.0.3

Foswiki - The Free and Open Source Wiki

Foswiki is an enterprise collaboration and information sharing tool targeted for professional use in many types of organizations: from small businesses to multi-nationals, from one-product open source groups, to worldwide research networks.

Foswiki is a wiki: fundamentally, a website with editable web pages. It looks like a normal web site but it encourages contributions, edits, updates, questions, and answers from its users. It's a powerful way of enabling a community to communicate asynchronously using intranet and public Internet websites. Foswiki is simple to learn and use. It aims to provide a transparent way for you to publish and exchange your ideas with others over the web and eliminates the one-webmaster syndrome of outdated intranet content.

Foswiki is a structured wiki with tools that enable users without programming skills to build powerful yet simple applications to process information and support workflows. Developers can extend the functionality of Foswiki with plugins.

Foswiki is backwards compatible with content generated on all previous Foswiki versions, and even content and many plugins from TWiki installations (Foswiki ships with a TWikiCompatibilityPlugin, thus enabling most extensions made for TWiki to work in Foswiki. TWiki^® is a registered trademark of Peter Thoeny.)

Foswiki is released under the GNU General Public License.

Foswiki Releases

• Foswiki 2.0.0 was built on 04 Jul 2015. It is a release that contains 312 fixes and 157 enhancements, and closes 59 Feature Requests.
• Foswiki 2.0.1 was built on 03 Aug 2015. It is a release that contains 28 fixes and 3 enhancements.
• Foswiki 2.0.2 was built on 01 Oct 2015. It is a release that contains 65 fixes and 5 enhancements.
• Foswiki 2.0.3 was built on 15 Nov 2015. It is a release that contains 17 fixes and 1 enhancement.

Pre-installed Extensions

Foswiki 2.0 is shipped with the following: ( New to Foswiki 2.0 )

• Plugins: AutoViewTemplatePlugin, CommentPlugin, ConfigurePlugin, EditRowPlugin, EmptyPlugin, HistoryPlugin, HomePagePlugin, InterwikiPlugin, JQueryPlugin, NatEditPlugin, PreferencesPlugin, PubLinkFixupPlugin, RenderListPlugin, SlideShowPlugin, SmiliesPlugin, SpreadSheetPlugin, SubscribePlugin, TablePlugin, TinyMCEPlugin, TwistyPlugin, UpdatesPlugin, WysiwygPlugin
• Contribs: CompareRevisionsAddOn, FamFamFamContrib, FastCGIEngineContrib, JEditableContrib, JSCalendarContrib, JsonRpcContrib, MailerContrib, ModPerlEngineContrib, PlainFileStoreContrib, RCSStoreContrib, TipsContrib, TopicUserMappingContrib
• Skins: PatternSkin
• Compatibility support - TWikiCompatibilityPlugin

Known issues

For up-to-date information, see Known issues of Foswiki 2.0

Use of non-default {Store}{Encoding}

WARNING About {Store}{Encoding}: If you intend to use high-bit characters in attachment filenames (such as umlauts and accents), then links to these attachments on Foswiki pages will not work on a non-utf-8 Store without modification. This is because Foswiki works internally using UNICODE, but the store saves files to disk using your chosen {Store}{Encoding}. Running the Store with other than utf-8 encoding is considered a transitional step and not recommended for long-term operation. The strongly recommended solution is to convert your store to UTF8 at the earliest opportunity.

A partial workaround is implemented in the PubLinkFixupPlugin This Plugin will attempt to rewrite broken links. This generally gets linked images and other attachments working. However the TinyMCEPlugin is still unable to render image links while editing a topic.

See Item13696 for up-to-date details.

Store bulk_copy.pl utility

A significant issue was discovered in prior versions of tools/bulk_copy.pl. If data was migrated from Foswiki 1.x, and the 2.0 system was configured to use the RcsWrap store, it's possible that the WebPreferences files were reset back to the default settings, and other topics may have been skipped. Migrated WebPreferences should be validated, especially access control settings.

Important changes in 2.0.3

Foswiki 2.0.3 contains some important security related change to avoid certain XSS posibilites.

SpreadSheetPlugin changes

The CALC and CALCULATE macros now encode < and > as entities, which prevents some paths used to insert script tags. If your user's topics require CALC or CALCULATE to generate HTML, then you must enable the following setting:

• Set SPREADSHEETPLUGIN_ALLOWHTML=1

This setting can be set in the topic, web, user or site perferences.

Performance

Foswiki 2.0.3 includes several performance improvements. Note however that the best performance will be achiveved by using Perl 5.20 or newer. There are kknow performance issues using regular expressions against UNICODE strings in perl 5.18.x and older.

Important changes in 2.0.2

API Change in Foswiki::Func

Attention plugin authors: The default behaviour of Foswiki::Func::saveFile() and Foswiki::Func::readFile() has been reverted to Foswiki 1.x behavior. Data is written and read as raw bytes. utf-8 encoding is not applied. A new optional flag can be set which will tell the API to add the utf-8 encoding layer. See Foswiki::Func file handling documentation for more details.

Query search performance

A major performance issue was discovered and resolved. Some query searches can see as much as a 350% improvement in performance.

EditTablePlugin has been restored as an optional extension

Foswiki now includes both the EditRowPlugin and the older EditTablePlugin. New sites will automatically get the new EditRowPlugin. Sites who prefer the older extension can enable the EditTablePlugin and disable the EditRowPlugin. Caution: Both extensions should not be enabled at the same time. Note that the EditTablePlugin is deprecated and receives minimal maintenance.

New configuration wizard

This patch release adds a new Configuration wizard. If an extension is installed from outside of the configure tool, you must run this wizard in order to merge in any Config.spec changes and save the default values for new configuration settings. Run the wizard using tools/configure and include the -save option to save any required changes.

$ tools/configure -wizard Plugins
WARNING: The Config.spec for CommentPlugin is more recent than the latest configuration. 'save of extension settings' is required.
WARNING: Configuration changes are required.
WARNING: If you did not include the -save option, you should rerun this wizard, specifying -save.

You can also now check the configuration from the CLI

$ tools/configure -check

Checking:Extensions -> Extension operation and maintenance -> Install, Update or Remove extensions:  {ExtensionsRepositories}
WARNING:    The Config.spec for CommentPlugin is more recent than the latest configuration.
WARNING:    You should run 'tools/configure -wizard Plugins -save'.

Checking:Extensions -> PlainFileStoreContrib: {Extensions}{PlainFileStoreContrib}{CheckForRCS}
WARNING:    This setting can be disabled for slightly improved performance once you can ensure that no RCS history exists within your Store.

Important changes in 2.0.1

Foswiki 2.0.1 has changed how the working/tmp/cgisess_* files are stored. This is needed to better accommodate user names with international characters. If old files exist and users still have a matching session cookie, then their access attempts will fail with a 500 internal server error.

ACTION REQUIRED: After applying the changes in Foswiki 2.0.1, you must delete all cgisess_* files from the working/tmp directory.

If you are unable to access the server to do this, users will have to clear their cookies to gain access to Foswiki.

This change addresses Item13563

Changes in requirements

API Change

The Foswiki API version is incremented to version 2.3 in Foswiki 2.0.0 for the following changes:

• A new validateRegistrationHandler can be registered by Extensions to process incoming regisrations.
• The old registrationHandler has been deprecated and will be removed from a future release.

Deprecation and removals

Setting HIDE_NON_WIKI_WORD_WARNINGS has been removed

This setting was used to hide the checkbox for controlling whether or not non-WikiWord topic names are permitted. The checkbox is now always visible. The recommended replacement is to use a SKIN setting to override foswiki.tmpl.

Space delimited square bracket links have been removed.

The long-deprecated [[https://foswiki.org Spaced title]] link format has been removed. Links must be written as [[url][title]] format if a title is desired.

Deprecated AllowInlineScript configuration setting removed

The $Foswiki::cfg{AllowInlineScript} setting has been removed. Inline scripts are always allowed. Extensions like the SafeWikiPlugin can be optionally used to control JavaScript within topics.

Deprecation of empty DENY rules

The intention to deprecate the use of an empty DENYTOPIC<action> rule to act as an "ALLOW all" has been completed. This has been a pending change predating Foswiki 1.0.0.

ACTION REQUIRED Any topics in the system that allow access by supplying an empty DENYTOPIC rule need to be updated. A utility has been provided to find and convert existing empty DENY rules to the new ALLOW format. You can choose to defer this action by enabling $Foswiki::cfg{AccessControlACL}{EnableDeprecatedEmptyDeny} in the Security and Authentication section under the Access control tab.

With release 2.0 of Foswiki, a new ACL rule, the asterisk, is used as a wildcard to match any user, including the guest user, WikiGuest. Prior to Foswiki 2.0, a topic could be made accessible to everyone by coding an empty DENYTOPIC<action> rule. This rule is no longer active by default.

A conversion tool is available in the tools directory. tools/convertTopicSettings.pl It can perform the following actions:

• Convert empty DENYTOPIC<action> rules to the corresponding ALLOWTOPIC<action> *=
• Optionally convert inline ACLs into META settings. This is recommended for Foswiki 2.0
• Optionally convert all inline settings into META settings.

For additional information run perl tools/convertTopicSettings.pl -help

Removal of PasswordManager Foswiki::Users::ApacheHtpasswdUser

This password manager was included primarily as demonstration code and was not fully functional. The default Foswiki::Users::HtPasswdUser provides better functionality and it works. The modules are compatible and no changes are needed. The decision was made to completely remove this module because it was no longer compatible with the new Foswiki utf-8 & unicode support.

Deprecation of jQuery plugins

A number of jQuery plugins have been deprecated and should be disabled in the configuration. Recommended replacements:

• jquery.corner, direct use of CSS recommended.
• jquery.gradient, direct use of CSS recommended.
• jquery.rating replaced by jquery.stars
• jquery.shake, is now part of jQuery-ui
• jquery.simplemodal, replaced by ui::dialog, the jQuery ui-dialog widget.
• jquery.supersubs, superseded by jQuery.superfish
• jquery.tmpl, replaced with jsrender
• jquery.tooltip, replaced with the tooltip component of jQuery-ui

Deprecation of EDITBOXSTYLE and EDITBOXWIDTH settings

These settings are not used with the new NatEditPlugin editor.

With the old wikitext editor, these settings are used only until the user drags the corner of the edit window. Once the window size has been changed with a drag event, the settings are remembered in a cookie and the preference settings are ignored.

Deprecation of Meta::get/setEmbeddedStoreForm API

These Meta APIs will be removed in Foswiki 2.0. They are retained for compatibility only, should not be used in new code, and should be replaced in existing code.

• for Foswiki::Meta::getEmbeddedStoreForm(), use Foswiki::Serialise::serialise($meta, 'Embedded').
• for Foswiki::Meta::setEmbeddedStoreForm(), use Foswiki::Serialise::deserialise($text, 'Embedded', $meta)

The EditTablePlugin has been deprecated and removed from the release

The EditTablePlugin has been replaced by the EditRowPlugin. If installed, the EditTablePlugin should be disabled in the configuration. The old EditTablePlugin is still available for installation from https://foswiki.org/Extensions/EditTablePlugin, but is not being maintained.

The EditRowPlugin has significant advantages over the old EditTablePlugin. Most features of the EditTablePlugin are supported, with the exception of the editbutton parameter, and plugin preferences.

The EditRowPlugin also enhances features previously provided by the TablePlugin. The EditRowPlugin adds client side JavaScript based sorting of tables, which has significant performance advantages. (Client-side sorting is provided only for tables on pages with an active %EDIT table or row macro. The JQTablePlugin is able to completely eliminate server side table sorting.)

The TablePlugin and EditRowPlugin can be used together, with one exception. A table statement with the initsort parameter e.g. %TABLE{ initsort="... " ]% will cause confusion as the table will be resorted every time a row is opened for edit, as well as when the whole table is opened for edit.

The SpreadSheetPlugin $BITXOR(string) has been remove.

The $BITXOR(string) function in SpreadSheetPlugin is not compatible with the implementation of utf-8 and unicode. It opereates at the "byte" level assuming that each character is represented by a single byte. With utf-8 and unicode, characters can be represented by 1, 2, or 3 or more bytes. The concept of obfuscating string data by flipping the bits is not compatible.

$BITXOR(string) is treated as $BITXOR() and returns zero.

Important changes in Foswiki 2.0

Installation process has changed significantly!

You should not visit 'bin/configure' as your first access. After extracting the Foswiki code and preparing your web server:

• Visit your desired default URL. If using Short URLs, use the short form: http://yoursite.com/Main/WebHome or http://yoursite.com/foswik/Main/WebHome, ...
• Follow the link in the banner of that initial page to access configure.
• After saving the configuration, return to your wiki pages, register your initial user and add them to the AdminGroup.

Improvements in International Character Set support

Foswiki 2.0 has improved support for utf-8 based character sets. Topics and data forms can use utf-8 characters. They will be properly rendered and preserved during edit. The Foswiki core has been fully converted to utf-8 and unicode. All encoding / decoding is done "at the edge", when reading from / writing to the Foswiki store.

• New sites will use utf-8 by default. Internationalizaiton should just work.
• Sites migrating data from a previous installation have two choices:
  • Set {Store}{Encoding} to match the previous ={Site}{CharSet}. (Default was iso-8859-1)
  • Migrate the data to utf-8 by using the tools/bulk_copy.pl script. This is the recommended solution.
• Support for Locales is still known to have issues. {UseLocales} should not be enabled in the configuration.

ACTION REQUIRED If you are upgrading an existing system, you should review the existing data and determine if migration to utf-8 should be performed. See the UpgradeGuide for more details. Note that the topic and attachment name filters no longer filter international characters, so migration to utf-8 is strongly recommended.

Due to the extensive internal changes, extensions may require changes for compatibility with this release.

• See Utf8MigrationConsiderations for guidance on upgrading local extensions
• See Item13483 for known extensions compatibility issues.

Perl libraries and paths

Foswiki no longer ships Perl CPAN libraries for use as a last resort. If it is not possible or convenient to install perl libraries, then install the CpanContrib to get pre-built libraries for Foswiki to use.

The setup of the perl @INC path has been simplified, and the foswiki/bin/LocalLib.cfg setting for $CPANBASE has been completely eliminated. A simple method of adding libraries to the top of the @INC path is provided in the new example foswiki/bin/LocalLib.cfg.txt shipped with foswiki.

ACTION REQUIRED If you are upgrading an existing system and have created a custom foswiki/bin/LocalLib.cfg, you should tailor a new copy using the updated foswiki/bin/LocalLib.cfg.txt   (Note that on most systems, foswiki/bin/LocalLib.cfg is not required.)

Authentication, Authorization and Security

Users now have the option to authenticate via 'TemplateLogin' using their email address. This feature is optional, and is enabled in the Security and Authentication section, Login tab of configure. Enable {TemplateLogin}{AllowLoginUsingEmailAddress}. If more than one user shares an email address, the user with the matching password will be selected during login.

REST Script default security has changed:

Foswiki 2.0 has removed the rest script from the list of {AuthScripts}. Instead of providing blanket security for rest, each handler is now responsible to set its individual requirements for 3 options: authentication, validation and http_allowed methods (POST vs. GET). The defaults for these 3 options have been changed to default to be secure, and handlers can exempt these checks based upon their specific requirements.

A new configuration option has been added to the Security and Authentication section, Login tab: {LegacyRESTSecurity}. Enable this setting to restore the old insecure defaults for REST handlers. If enabled, and rest is not listed in {AuthScripts}, a warning will be displayed.

New Pluggable Access Control implementations.

Foswiki has made the Access Control implementation "Pluggable". New ACL methods may be more easily implemented in the future. The default method is $Foswiki::cfg{AccessControl} = 'Foswiki::Access::TopicACLAccess';.

Two additional methods are now included which may be of help to the Administrator:

AdminOnlyAccess

When selected, all requests for access are denied except when requested by users in the AdminGroup.

TopicACLReadOnlyAccess

The topic ACLs are applied as usual, but any access other than VIEW access is denied, except for users in the AdminGroup

Caution: These controls are enforced at the ACL Level. Extensions have the ability to ignore access controls. If an extension fails to check for access permission, then these new methods will not block access.

CGI Related changes

Session ID Security improvements.

In Foswiki 2.0, sessions ID's will be changed whenever the user identity changes. This improves the resistance to certain session hijack attacks. This is not believed to have any negative impact, however there is a race condition if the user uses multiple browser tabs, and authenticates in one tab while the other tabs are interacting with the server (for ex. a long running attachment upload in one tab, followed by a internal admin login in another tab. The session ID in use for the upload will be deleted because of the internal admin login and results are unpredictable.

This change is important for security purposes and cannot be disabled.

Sessions and Roaming or Mobile Users

In Foswiki 2.0, $Foswiki::cfg{Sessions}{UseIPMatching} has been enabled by default. This change can improve security by reducing the exposure to certain session hijack attacks. However it can be disruptive to mobile users. It is also of limited use when users access the wiki through a proxy or other devices that might cause multiple users to share the same IP address.

With UseIPMatching enabled, CGI::Session code will compare the current user's IP Address to the address that was used when the session was initially created. If the IP address has changed, then the session is invalidated and the user is required to re-authenticate. There is further information about this option in the configure Security And Authentication tab interface.

ACTION REQUIRED If you have roaming users who need to keep their Foswiki Sessions across IP Address changes, then you need to disable the {Sessions}{UseIPMatching} option in your configuration.

Optional Sessions for Guest users

EXPERIMENTAL feature: In Foswiki version 2.0, sessions can be suppressed for guest users. This is believed safe if guests have no ability to update. However if guests are permitted to update, for example by using the CommentPlugin, or if any wiki applications make use Session Variables, then guest sessions should be enabled. See the configure Security and Authentication tab interface for more information.

Other CGI related changes

ACTION REQUIRED If you have {Store}{Encoding} set to utf-8, you must not use CGI versions 4.11-4.13. With those CGI releases, topic and form data can be corrupted during save. CGI version 4.14 released 1 April 2015 is recommended.

Also note that with CGI 4.14, there have been come internal changes that might impact non-default or locally written extensions. If you have locally written extensions and use the CGI:: HTML generation functions, you should review the CGI Release Notes.

Configure has been given a major restructuring

• Configure is now a conventional "Foswiki Engine" based script. This means that to use configure you must either:
  • be running in bootstrap mode, or
  • be logged in to Foswiki and be in the admin group, or have appropriate permissions granted.
• Configure now requires JavaScript.
  • Configuration parameters are checked and saved through AJAX.
• Performance
  • Configure only transmits changed settings, greatly reducing the required bandwidth and improving performance.

Changes to configure Authentication

• Configure requires that the user has logged in to Foswiki and either be in the AdminGroup, or be identified as an authorized configure user.
• The "admin" superuser password is now optional:
  • If not set, configure depends solely upon the session authentication
  • By not setting, or by clearing the admin password, sites can disable the internal admin login, eliminating sharing of admin passwords, which is considered poor security practice.
• Configure can be restricted to individual users in or out of the AdminGroup.
  • If {FeatureAccess}{Configure} is NOT configured, then the current user must be in the AdminGroup in order to view or save the configuration.
  • If {FeatureAccess}{Configure} user list is configured, then the current user must be in the list to be allowed access to configure, regardless of whether or not they are in the AdminGroup.

The Configure access restrictions are also applied to control potentially sensitive information, such as the new information topics:

• System.PerlDependencyReport
• System.FoswikiServerInformation

Configure command line interface

Configure can now be run from the command line using the foswiki/tools/configure script. It can be run interactively using tools/configure -save and will prompt for the required minimum configuration options. It can also be run without prompting. Here is an example of a complete Foswiki configuration from the shell, configured for short URLs:

tools/configure -save -noprompt
tools/configure -save -set {Password}='mypassword' -set {DefaultUrlHost}='http://your.site.com' -set {PubUrlPath}='/pub' -set {ScriptUrlPath}='/bin' -set {ScriptUrlPaths}{view}=''  -set {FeatureAccess}{Configure}='JoeUser, FredAdmin' -set {WebMasterEmail}='webmaster@your.site.com

If any of your variables contain international characters, you need to run configure with the perl -CA option.

perl -CA tools/configure -save set ...

Full help on the available options can be viewed using tools/configure --help

CLI Extensions installer

The command line Extensions installer has been rewritten to use the foswiki/tools/configure script. This version will automatically enable new extensions and save the configuration. If you want to install an extension without enabling it, include the --noenable switch.

Execute tools/extensions_installer usage for more information.

Query Search

The undocumented shortcut notation to reference to a form name is no longer available. Previously you could write:

%SEARCH{
   type="query"
   "BlogPostForm"
}%

Because this could lead to indeterminate behaviour, the syntax is now more controlled. You now have to refer to the form name:

%SEARCH{
   type="query"
   "form.name='BlogPostForm'"
}%

Major change to ICON macro and templates

HtmlAttributesShouldUseSingleQuotes has changed the ICON macro to generate singe quotes by default. This has no impact unless the %ICON macro is being expanded inside a single-quote delimited macro.

In order to simplify migration, a new quote= parameter has been added to the ICON macro. %ICON{"pdf" quote="\""}% generates the html using double quotes delimiters. See System.VarICON for more details.

Major changes to the Foswiki Store subsystem.

The Foswiki Store has been restructured into separate pluggable store implementations. Foswiki 2.0 ships with two store backends:

• RCSStoreContrib: This implements the RCSWrap and RCSLite "Revision Control System" based stores, compatible with prior versions of Foswiki and TWiki.
• PlainFileStoreContrib: A new plain file store that saves topic and attachment as time-stamped copies instead of the "diff" based RCS store. This implementation can use more disk space but is expected to be much higher performing than the RCS store. Existing topics can be migrated to the new store. Store formats may not be mixed. One store must be selected.

The utility to migrate between stores is tools/bulk_copy.pl. Be sure to backup everything before running the conversion. For information on how to run the tool, run:

cd foswiki/tools
perl -I ../lib bulk_copy.pl --help

Caution: There are known limitations to bulk_copy.pl. See the Upgrade Guide for details. Hidden files (filenames with underscore (_) or dot (.) prefix) will not be copied. If your installation contains these types of files, then bulk_copy.pl should not be used!

New "Natural Editor", NatEditPlugin replaces the old WikiText editor

The NatEditPlugin, a component of the optional NatSkin, is now the default WikiText editor. It is enabled with the new default skin setting:

• #Set SKIN = natedit,pattern

The NatEditPlugin is a Topic Markup Language (TML) editor, and provides a GUI "assist" to the user to aid in learning and using TML. This editor relies heavily on JavaScript and jQuery. Users that must edit without the use of JavaScript can override the SKIN setting and remove natedit.

Translation Status

As of this release,

• Czech, Danish, French, German and Italian are >99% complete.
• Dutch, Norwegian, and Portuguese (Brazil) are 70-88% complete.
• Other languages are 60% complete or lower.
• A new translation has been added: Klingon, 94% translated.

For more details on translation status, see TranslationTeam and Foswiki's Weblate translation server. Foswiki thanks the Translators for their efforts. If you are interesting in helping with the translation, please contact foswiki-translations@lists.sourceforge.net.

Foswiki Release 2.0 Details

New Features

(This list was updated with more complete information in Release 2.0.2)

Fixes

Enhancements

Foswiki Release 2.0.1 Details

Fixes

Enhancements

Foswiki Release 2.0.2 Details

Fixes

Enhancements

Foswiki Release 2.0.3 Details

Fixes

| Item13852 | CommentPlugin should warn about COMMENT permissions in configure.

Enhancements

Related Topic: ReleaseHistory