ServerUpgrading

Introduction
Server version upgrade from PennMush 1.7.4p18, which has been in use on ChampsMush for many years, to PennMush 1.8.1p4. The destination version is not the latest available. It is however the version that has been used to create and test the code developed on the CM2 test server and has proved to be reliable.

We cannot go straight to the destination version. The format of the database files changed in version 1.7.6. PennMush 1.7.6 can read files from earlier versions. Versions after 1.7.6 cannot read database files from versions before 1.7.6. Therefore we must first convert the database files from 1.7.4 to the newer format by loading them into a 1.7.6 version, which can read them, and then dumping a set of database files from 1.7.6, which will be written in the newer format.

There is plenty of space left in CM's disk allocation so we can add all the required files in advance of doing any changes impacting on the live server. The complete upgrade process can be partitioned into three stages: preparation, upgrading, and fixup.

Preparation
We can tackle most of the known potential problems upfront before making the actual upgrade. The move from 1.7.4 to 1.7.6 should proceed flawlessly. There are issues to resolve in moving from 1.7.6 to 1.8.0 onwards however.

Wizards (other than God) and Royalty are no longer treated as No_Pay in 1.8.0+ unless the No_Pay power is explicitly set on them. The same is true of admin objects that use functions with an associated cost such as @search, etc. Wizards and Royalty have been given the No_Pay power, as have all objects with Wizard or Royalty flags set on them.

Cafe Expresso and Limbo must be given Royalty flags. Permissions in version 1.8.1p4 have been tightened up and these rooms need the extra power conferred by Royalty flags to continue to act as they do in the existing server. This has been done. No change has been noticed in the current version and the rooms are now setup ready for the upgrade.

@adisconnect is triggered on every disconnection in 1.8.1, partial or full. We can't do anything about this until the server is upgraded. See the Fixup section for details.

Upgrading
The new code can no longer read databases created by versions of Penn before 1.7.5p0. So we have to load the 1.7.4 database in 1.7.6, shutdown, and use the 1.76 generated database for 1.8.1. This is discussed in the introduction above. It simply makes upgrading more laborious.

Source tarball files for the PennMush versions required, that is the intermediate 1.7.6 and the target 1.8.1p4 have been obtained from the pennmush http repository. We have ftp'ed the source tarballs to ChampsMush, for eventual use, and CM2, for testing and dry-run.

To ensure we can always restore the work that has been done on CM2 when testing the upgrade in that account we want to ftp the CM2 database files off site. A copy will be kept on Ayesha's PC. We will also store a copy on the CM2 host outside the pennmush directory. The backups have been done and the on-site database backups for CM2 are in ~/bak291106. The original CM2 server and data pennmush directory has been renamed to pm181cm2.

The new server versions, the intermediate 1.7.6 and target 1.8.1 have been unpacked and compiled in both accounts, testing on CM2 first. They are able to be run with minimal databases. We can now restart the 1.7.4 server and leave that running live while setting up the required configuration options for the 1.8.1 server and moving the text files over.

The text files in the ~/pm181/game and ~/pm181/game/txt/** directories have been copied in from the existing 1.7.4 server version where needed. Makefile in ~/pm181/game/txt has been edited to load and index both the existing additonal 'help' files like NEWS and EVENTS, and also the intended new file categories RULES and THEME.

To execute the upgrade:
 * Log in as a wizard and do an @dump in the existing Mush
 * Delete any existing files in ~/pm176/game/data. Be careful!
 * Copy the outdb, mail and chat data files from ~/pennmush/game/data to ~/pm176/game/data
 * Shutdown the 1.7.4 server by issuing @shutdown as a Wizard
 * Rename ~/pennmush to ~/pm174
 * Rename ~/pm176 to ~/pennmush
 * Navigate to the new ~/pennmush/game directory and start 1.7.6 with ./restart
 * Log into Mush as a Wizard and perform an @dump to create 1.7.6+ format output files
 * Delete any existing files in ~/pm181/game/data. Be careful!
 * Copy the outdb, mail and chat data files from ~/pennmush/game/data to ~/pm181/game/data
 * Shutdown the 1.7.6 server by issuing @shutdown as a Wizard
 * Rename ~/pennmush to ~/pm176
 * Rename ~/pm181 to ~/pennmush
 * Navigate to the new ~/pennmush/game directory and start 1.8.1 with ./restart
 * Pray
 * Log in and check that it all looks good
 * Proceed with any needed fixup OR revert to 1.7.4 if the Mush breaks badly.

Backing Out
If the upgrade does not go smoothly this is how to backout of the change and revert to the original 1.7.4 server version. Note: this is not a fully reversible process. Any changes made to the database in the new version will be lost. Restoring the original version also means restoring the database to the state it was in prior to the server being upgraded. This process requires shell access to the Mush host account.

First close down the new server if it is running. This can be done by issuing an @shutdown from within the Mush from a Wizard flagged login (preferred method) or by killing the server process from the shell. (use ps to get the pid and then kill pid)

rename the ~/pennmush directory to ~/pm181. Check this has been done before continuing. Rename the ~/pm174 directory to ~/pennmush. Check this has been done before continuing. Enter the game sub-directory of the renamed directory with cd ~/pennmush/game. Start the old 1.7.4 server version with ./restart

Fixup
@adisconnect is triggered on every disconnection, partial or full in 1.8.1. This mirrors the behavior of @aconnect. We can use %1 (the number of remaining connections) to distinguish between partial and full disconnects in @adisconnect code.

We are limited in what we can do about this until after the server upgrade as the %1 parameter mentioned isn't implemented in the earlier version of PennMush. What will be affected? The player's online_time attribute will be updated (#22). When players partially disconnect from a Place in a room they will be expelled from the Place (#29). Guests will be returned to the Guest Room by the @adisconnet attributes set on the Guest logins. Six players have set @ADISCONNECTS on their characters. None of these will have any significant effect and if a player knows enough to set up the attribute he or she ought to be able to amend it. After the upgrade is implemented we should look at amending the Places and Guest @disconnect's.