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 Releases

Foswiki 1.0.1, 1.0.2 and 1.0.3 were released internally in the development community, but were never publicly released.

Foswiki 1.0.4 was built 19 Mar 2009. It is a patch release with more than 120 bug fixes relative to 1.0.0 and only very few minor enhancements.

Foswiki 1.0.5 was built 25 Apr 2009. It is a patch release with more than 150 bug fixes relative to 1.0.0 and a few enhancements. This patch release further enhances the robustness and the security of the Foswiki software.

Foswiki 1.0.6 was built 21 Jun 2009. It is a patch release with more than 200 bug fixes relative to 1.0.0 and some enhancements. This version introduces a major enhancement in security against Cross-Site Request Forgery. Further more a central translation framework got introduced which ease the translation process and enables all users to contribute to translations.

Foswiki 1.0.7 was built 20 Sep 2009. It is a patch release with more than 240 bug fixes relative to 1.0.0 and some enhancements. This release fixes some serious issues introduced by the CSRF fix and the redirect cache fix in 1.0.6. Major enhancement that also fixes many annoying editor bugs is the upgrade of the Tiny MCE editor to version 3.2.2.

Foswiki 1.0.8 was built 29 Nov 2009. It is a patch release with more than 280 bug fixes relative to 1.0.0 and some enhancements. This release fixes a short list of quite annoying old bugs incl a bug that prevented efficient use of MailerContrib for producing newsletters. The Wysiwyg editor has been upgraded with the latest Tiny MCE editor release 3.2.7.

Foswiki 1.0.9 was built 17 Jan 2010. It is a patch release with more than 320 bug fixes relative to 1.0.0 and several enhancements. This release fixes many bugs in the Wysiwyg editor, bugs related to more advanced wiki applications and bugs in the Plugin API. It contains several bug fixes and enhancements related to security and spam fighting.

Foswiki 1.0.10 was built 08 Sep 2010 as a patch release with more than 410 bug fixes relative to 1.0.0. It is assumed to be the last 1.0.X release.

Foswiki 1.1.0 was built 04 Oct 2010. It is a release with more than 270 bug fixes relative to 1.0.10 and more than 680 bug fixes relative to 1.0.0. And the release adds more than 100 enhancements. Foswiki 1.1.0 introduces jQuery Javascript user interface framework, improved topic history display, new QUERY and FORMAT macros, better user interfaces for groups, much improved WYSIWYG editor, facelift of the default skin, much improved configure tool, and many more enhancements.

Foswiki 1.1.1 was built 25 Oct 2010. It is a release that fixes some important bugs that were introduced in 1.1.0. It is highly recommended that all running 1.1.0 upgrade to 1.1.1.

Foswiki 1.1.2 was built 09 Nov 2010. It is a release that fixes some very important bugs incl. a security related bug. Installations running 1.1.0 and 1.1.1 should be upgraded to 1.1.2

Foswiki 1.1.3 was built 16 Apr 2011. It is a release that fixes more than 150 bugs. jQuery has been updated to 1.4.3. The default PatternSkin has some usability improvements.

Foswiki 1.1.4 was built 20 Dec 2011. It is a release that fixes some very important including some security related issues. It contains 143 fixes and 27 enhancements. jQuery has been updated to 1.7.1.

Foswiki 1.1.5 was built 10 Apr 2012. It is a release that fixes some very important issues including some security related issues. It contains 100 fixes and 20 enhancements.

Foswiki 1.1.6 was built 02 Dec 2012. It is a release that fixes some important issues including some minor security related issues. It contains 94 fixes and 27 enhancements.

Foswiki 1.1.7 was built 01 Feb 2013. It is a release that fixes CVE-2012-6329 and CVE-2012-6330. It contains 20 fixes and 4 enhancements.

Foswiki 1.1.8 was built 28 Feb 2013. It is a release that fixes CVE-2013-1666. It contains 4 fixes.

Foswiki 1.1.9 was built 18 Nov 2013. It is a release that contains 44 fixes and 4 enhancements..

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.

Known issues

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.

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

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.

Perl 5.8.8 is the minimum perl version. The newer the better. There are know issues with international characters and Perl 5.16.x See Item13424. For international character set support, Perl 5.18+ is recommended.

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 [[http://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:

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:

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
http://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.

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

Foswiki is now able to run without a configuration (LocalSite.cfg) After initial installation, just point your browser at the default URL for Foswiki. Foswiki will "bootstrap" itself and provide a link to configure to establish the initial configuration.

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.

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:

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.