UpgradeToSiteAdmin

For PmWiki 2.2.0 a new SiteAdmin group has been created to hold various administrative pages, such as AuthUser, ApprovedUrls, Blocklist, NotifyList, and others. This page explains the reason for the change, and various methods for managing the migration to the new scheme.

This page is still a first draft, so if anything seems unclear or confusing, please let us know on the pmwiki-users mailing list so that we can make it easier for others to follow. Or, feel free to improve this page directly.

Why this change is being made

Over time, we've discovered that the existing Site group is attempting to serve too many purposes. Some pages in Site need to be public, such as Site.Search, Site.PageListTemplates, and Site.EditQuickReference while others are better left "hidden" from the casual visitor, such as Site.AuthUser and Site.Blocklist. Instead of trying to manage permissions on these pages individually, we've decided to create a new SiteAdmin group that will hold configuration pages that should generally be hidden. The new page locations are:

• SiteAdmin.AuthUser
• SiteAdmin.Blocklist?
• SiteAdmin.ApprovedUrls?
• SiteAdmin.NotifyList?

For new installations, PmWiki starts off with everything configured in the SiteAdmin group, and just works out-of-the-box. The rest of this page provides assistance for people migrating from pre-2.2.0 versions to 2.2.0 .

How to make the switch to SiteAdmin, or not

Because the pages that are being moved are at the very core of PmWiki's security, we're trying to be extra-cautious in managing this conversion. Of course, we highly recommend making a backup of the entire installation before performing an upgrade.

Starting in 2.2.0, when PmWiki detects that the installation is being upgraded from a previous installation that was using pages in the Site group, it halts all processing to allow the administrator to reconfigure things to match the new upgrade. Administrators can basically choose to either move existing pages to their new locations, or to configure PmWiki to continue using the existing Site group.

Option 1: Let PmWiki fix things

One option is to let PmWiki attempt to migrate things for you. In the upgrade notice, PmWiki also presents a link to have PmWiki automatically copy existing Site pages into their new locations. If this link is activated (and the browser has 'admin' privileges), then PmWiki will attempt to copy things automatically. If successful, then the upgrade will be complete and everything will work with the pages in their new locations. After you have verified that things appear to be working properly, it might be a good idea to delete the old copies from the Site group, to avoid confusion.

Option 2: Migrate pages manually

In some situations PmWiki may not be able to migrate the pages automatically (especially if admin authentication depends on Site.AuthUser). In these cases, it's possible to manually copy or rename the pages from their old locations to their new ones. This can generally be done from within an FTP client or using a command line interface.

The pages that may need to be renamed or copied are:

• Site.AuthUser -> SiteAdmin.AuthUser
• Site.ApprovedUrls -> SiteAdmin.ApprovedUrls
• Site.Blocklist -> SiteAdmin.Blocklist
• Site.NotifyList -> SiteAdmin.NotifyList

Your site may not be using some of these features or pages, in which case you don't need to do anything for those pages. Once copies of the pages are in their new locations, PmWiki will detect that it's safe to continue and will skip over the upgrade warning.

Option 3: Continue using the existing Site group

Some sites may prefer to keep the pre-2.2.0 locations of site administrative pages. This can be easily done in local/config.php by setting:

    $SiteAdminGroup = $SiteGroup;

This tells PmWiki that the site administrative pages are to be found in Site (or whatever $SiteGroup is set to use), and will bypass any further checking.

Notes

If you have previously defined a custom $GroupPattern variable to limit WikiGroups, you need to update this variable to include the SiteAdmin group. See for more information Limit WikiGroups.

For more information, contact pmwiki-users@pmichaud.com or pmichaud@pobox.com .