Revision [17354]

This is an old revision of RelocatingWikka made by JavaWoman on 2007-08-07 13:15:07.

 

Relocating or Sharing a Wikka installation


A bit of history

From the Wikka archeology department.

From the earliest point in its history, WakkaWiki Wakka version 0.1 (dated 2002-09-04, going by the README signed by Hendrik Mans), WakkaWiki Wakka has supported a mechanism to locate its configuration file somewhere else than in the installation directory. That mechanism was to look for an environment variable called WAKKA_CONFIG, using the PHP call getenv(). If that variable is set and the file it points to exists, that is loaded as the configuration file, otherwise the default location in the installation directory is used.

I have not been able (yet?) to trace any documentation of why this was done, but my guess would be it was intended to be able to store the configuration file outside the webroot for security reasons: the configuration includes all data necessary to access the database the wiki uses, which is a security risk.

From the earliest incarnation of its successor WikkaWiki Wikka (version 1.0.0) right through version 1.1.6.2, that mechanism has remained in place. Unfortunately, getenv() (AKA GetEnv()) itself constitutes a security risk, as pointed out by several Wikka users on this site and on one of the mailing lists. Not sure who got there first, but a likely candidate is DotMG, who's original post on WikkaBugs now lives on as #98: GetEnv is not a good idea. In effect, we had an insecure method to enhance security...

Meanwhile I was looking at security aspects for several areas of Wikka, and came up with a possible solution for a secure configuration in WikkaSecureConfig Securing the configuration, its first incarnation dated 2004-12-16. My primary concern was the presence of such sensitive data as database access parameters in the installation directory, but I did refer to the security risk posed by using getenv(). The last edit on that page was 2005-05-29... nothing much came of it, it seems. Until several people independently discovered that getenv() itself was a security risk, and started mentioning it to us here and there.

Security: getting rid of GetEnv() first

A preliminary solution

In February it came to our attention that a "highly critical" bug in PHP had been fixed in version 5.2 but not in any 4.x version. After a bit of research, it seemed we could devise a workaround - important since many hosters still provide PHP 4.x and not any 5.x version, and many Wikka installations run on such servers. We decided to create a special "security release" (which became 1.1.6.3) with a workaround for this PHP security problem, and then put in all other security fixes we had already in place in the trunk, as well as every other security fix we could come up with. So... trawling through old emails, I stumbled over good old GetEnv() again. No time for any architectural work, but GetEnv() had to go.

I opted for a very simple solution, replacing the optional environment variable WAKKA_CONFIG with the equally optional constant WAKKA_CONFIG. Unfortunately, the release notes for 1.1.6.3 originally only mentioned that GetEnv() had been "dropped", while in fact it had been replaced (now amended). But one has to edit the core wikka.php file to get the functionality back: clumsy, though functional.

Of course this clumsy (but secure) solution was never meant to be more than a preliminary solution, so for upcoming version 1.1.7 the brief was to come up with a more structural solution.

Getting back to relocating files

A more structured approach.

A single file relocatable?

A more structured approach? Well, it's obvious that we still need to be able to relocate the site configuration file. It's also obvious that having admins edit the code wikka.php file isn't really a good idea - that was a crutch. But the idea of using a constant (rather than GetEnv()) to point to a file's real location instead of the default location as assumed in the default Wikka installation is fine.

It's also an extensible idea. If you can relocate one file, you can relocate other files. And if you can relocate files by pointing to another location, you can also share files.

All code relocatable and shareable!

For instance, we bundle several third-party libraries that people may actually already have installed. Why install them twice? It would be far more sensible and economic to just point Wikka to where it's already installed. Upgrading such a third-party library or class would then also need to be done only once, with all packages using it (including Wikka) automatically inheriting the newer version.

Or, you may have adapted or even translated the language files that come with Wikka. If you then install a second wiki using Wikka, it would be nice if you could just share the language libraries instead of copying it all over to your new install.

If you added a number of new home-grown or third-party actions or handlers, you might want to share those with a second installation of Wikka running on the same server as well.

Files, code...

All of these can be relocated or shared using the same simple mechanism already used for the site configuration file: using an optional constant defining an alternative path, and having the core wikka.php look for these and use them as override for an internal constant if found.

A single file to do it all

Wikka now (in the current trunk version) comes with a file called override.config.php which is the key to this mechanism. As installed, it consists of nothing but comments, but if you want to relocate or share any of the relocatable components, just open the file, uncomment the appropriate define() statement, and edit it so it points to where the file or directory lives, or where you want the site configuration to be created on install. However, you really should do this before embarking on a (new) installation: doing it afterwards is not impossible but takes more manual work.

The override file override.config.php is not just "nothing but comments", it has actually extensive documentation for how it works and for each of the overridable paths. Naming of the definable constants also gives a clue to what they are for. The main phpDocumentor block:
/**
 * Override control: relocate or share Wikka components between installations.
 *
 * This file allows the administrator to override standard or default paths used
 * by Wikka. This makes it possible to:
 * - locate the site configuration file outside the webroot for security
 * - share Wikka code between several Wikka sites running on the same server
 * - share Wikka language files between several Wikka sites running on the same
 *   server: useful if you make adaptations to the texts or add a new translation
 * - use an already-installed 3rd-party component from its own location instead
 *   of the one bundled with Wikka
 *
 * To use an override, uncomment the corresponding define and adapt the path
 * to reflect your situation.
 *
 * There are two types of overrides:
 * - Direct overrides will be used directly by Wikka
 * - Configuration overrides define a <b>default</b> value for the configuration,
 *   which may be changed during installation or later by modifying the site
 *   configuration file. By using the overrides here you can provide consistent
 *   setup values for a collection of Wikka installations
 *
 * Naming indicates purpose:
 * - All constants have a prefix "LOCAL": 'LOCAL' in this context means applicable
 *   to this particular instance of Wikka, although it these constants can
 *   actually be used to share system files between different installations, by
 *   pointing this all at the same location in all instances.
 * - Constant names ending in "_PATH" define a <b>filesystem directory</b>; they
 *   should not end in a (back)slash
 * - Constant names ending in "_CONFIGFILE" define a <b>filesystem path</b> for a
 *   configuration file; LOCAL_SITE_CONFIGFILE is for the site configuration file
 *   and does not need to exist before installation.
 * - Constant names ending in "_URIPATH" define a <b>URI path component</b> to
 *   be used by Wikka to build a fully-qualified URL; they should not end in
 *   a slash.
 *
 * Tip 1:
 * When defining <b>filesystem paths</b>, you can use relative, absolute, or
 * fully_qualified paths (with a drive letter on Windows).
 * You may also use a (normal) slash instead of a backslash on a Windows server:
 * Wikka canonicalizes the paths, which automatically provides the slash type
 * appropriate for the system it's running on.
 *
 * Tip 2:
 * When defining <b>URI path components</b>, you can use the little "Compatibility"
 * function <b>filesys2uri()</b> to convert any backslashes in an already-built
 * or default filesystem path into forward slashes to use as a URI path.
 */


Finally, when wikka.php finds one or more overrides active, it does some "sanity checks" on the to be reasonably sure they are actually usable for their purpose - if not, the internal default path is used.

What this can do for you

A few example use cases.
(stub)

 

CategoryDevelopmentArchitecture CategoryDevelopmentSecurity
There is one comment on this page. [Display comment]
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki