Mediawiki-extensions under Debian

Extensions for MediaWiki

Extensions are compilations of PHP code that add new features or enhance functionality of the main MediaWiki core. Extensions are one of the main advantages of MediaWiki. They give wiki administrators and wiki end-users the ability to adapt MediaWiki to their requirements.

Depending on your goals you can use extensions to:

extend the wiki markup used to write articles;
add new reporting and administrative capabilities;
change the look and feel of MediaWiki;
enhance security via custom authentication mechanisms.

The Debian mediawiki-extensions package

Under Debian 5.0 "Lenny", there exists a package named mediawiki-extensions that contains a number of useful extensions that you're quite likely to find useful. The included extensions are:

Cite -- add tags for citation purpose
GeSHi -- add tags for syntax highlighting
Inputbox -- add predefined HTML forms to wiki pages
NewestPages -- show the lsat pages added to the wiki
Poem -- add tags for poems
SpecialLastUserLogin -- special page to see a user last logins
ParserFunctions -- collection of parser functions
PageCSS -- parser hook to add per-page CSS
FootNote -- add footnote to your article
SpecialRenameuser -- special page to rename users
LdapAuthentication -- user authentication using LDAP
CategoryTree -- dynamic view of the wiki's category structure
ConfirmEdit -- very simple text Captcha
FancyCaptcha -- more comples image captchas (needs ConfirmEdit)

The installation of this package is, as usual, very straightforward. Run apt-get install mediawiki-extensions, or use aptitude to get this package installed.

After installation, the following directories get created:

/etc/mediawiki-extensions
     |-- extensions-available
     `-- extensions-enabled
/usr/share/mediawiki-extensions
           `-- maintenance
/var/lib/mediawiki/extensions/CategoryTree

Manually enabling or disabling Debian-packaged extensions

The way the package mediawiki-extensions is set up under Debian, means that all extensions themselves are installed in /usr/share/mediawiki-extensions. Furthermore, a symbolic link has been made to each individual extension in the directory /etc/mediawiki-extensions/extensions-available. However, the extensions are not yet "visible" to the Debian-configured MediaWiki. That's because the Debian-configured MediaWiki looks in /etc/mediawiki-extensions/extensions-enabled for all its extensions.

This means you can enable any one of them with just a little symbolic link in /etc/mediawiki-extensions/extensions-enabled, from which you only have to link back to /etc/mediawiki-extensions/extensions-available. Usually, this is accomplished by running a Debian-specific script:

mwenext <extension name>

In this call, the <extension name> is NOT how the extension is named in the MediaWiki special:version page, but the actual filename of the PHP-script, including its extension. E.g. mwenext NewestPages.php. Note that mwenext will not work when you've got WikiFarms, because per WikiFarm the extensions will be in another location. More on that however in the WikiFarm section.

Alternatively, you can manually create the symlink to the extension (i.e. from extensions-enabled to extensions-available):

cd /etc/mediawiki-extensions/extensions-enabled
ln -s ../extensions-available/<extension name>

Disabling is just as easy, with the dedicated script mwdisext <extension name> or by unlinking the corresponding symlink in /etc/mediawiki-extensions/extensions-enabled.

Manually adding non-Debian-packaged extensions

Now the advantage of the way the package mediawiki-extensions is set up under Debian, is that it has set up a structure for you to use, including population with some common extensions. Adding your own extensions (either the ones you wrote yourself, or the ones you download from the MediaWiki.org site) is pretty straightforward. Details however might differ if the extension needs its own configuration directories and what have you not. In the following, the simplest case is presented.

Install (unpack) all files of your new extension straight in /usr/share/mediawiki-extensions - note that you CANNOT put the files of the extension in a subdirectory, since under Debian MediaWiki will look for extensions only in this /usr/share/mediawiki-extensions directory. For security, make sure no-one can write the extension's files. Usually, we can make do by having all individual files of the extension owned by root:root, and setting the permissions to 644 (writable for user root, readable for everyone else).

If the extension needs to write data in some configuration directory, then we consider that data to be "configuration data", so the configuration directory should be somewhere under /etc/mediawiki-extensions. The directory should probably be writable by the web server daemon, so making www-data:www-data the owner, and modifying permissions to 755 would most probably be sufficient and safe. The extension itself will expect the configuration directory there where it sits itself, being /usr/share/mediawiki-extensions. If you create a symlink in that directory to your intended configuration directory, then all data the extension will write, will wind up in /etc as Debian custom has it. As an example: you could put the configuration files for Group Permissions Manager in /etc/mediawiki-extensions/GroupPermissionsManager/config and create the symlink /usr/share/mediawiki-extensions/config to point there.

Now to make the extension actually available, we need to create a symbolic link in /etc/mediawiki-extensions/extensions-available that points to the main PHP file of the extension over in /usr/share/mediawiki-extensions. As with the Debian-specific extensions, this makes them available, but not (yet) enabled. Enabling or disabling the extension is again just a matter of creating a symlink in /etc/mediawiki-extensions/extensions-enabled, just as with the Debian-specific extensions. Note that mwenext will take the name of any extension in /etc/mediawiki-extensions/extensions-available, not just the Debian-specific ones.

As a good example, see how we install MediaWiki Extension - GroupPermissionsManager

Cautions for adding non-Debian extensions

Note that multiple extensions can request the same directory, e.g. config. Thus they all expect /usr/share/mediawiki-extensions/config to be at their disposal. If this turns out to be the case, then the actual config directory might need to be (re)located in /etc/mediawiki-extensions/config. Extension-specific directories however can remain stored in their own little subtree off of /etc/mediawiki-extensions.

Another note is that if you have multiple extensions that need the same file in the same place (/usr/share/mediawiki-extensions), then things could get difficult. We haven't seen that yet, though....

Finally, you might wish to upgrade a Debian-included extension (e.g. ConfirmEdit.php) to a newer version. This will interfere with the Debian APT system, so care must be taken. Multiple courses of action can be taken:

You can see if you can put the mediawiki-extensions package on "hold" - this would prevent your newer extension from getting overwritten when an update to mediawiki-extensions is issued. But on the other hand, it would also prevent security updates to all the other extensions in the mediawiki-extensions package, something we would not recommend. Also, you have to remember NOT to remove the "hold" on the package, which could be tricky especially if your server is being administered by more than one person.
You can see if you can rename the files in the extension, so that they can coexist with the original Debian version of the extension. This however might make it necessary to inspect, and maybe even alter, the PHP code of the extension. Also, you'd have TWO extensions with almost similar names in the extensions-available directory, e.g. ConfirmEdit.php and NewerConfirmEdit.php - not ideal either.
You could locate the extension in a different place, e.g. /usr/share/mediawiki-extensions/<subdir>. This should work, but the problem of the symlink in extensions-available remains.