Continued from part 1, which gives a general overview and some miscellaneous tips…

My Actual Upgrade Process:

•   As noted in part 1, before actually proceeding with any part of the upgrade, I make a complete backup copy of my BBS’s directory. If you’re running in a VM or a containerized copy of Mysitc and you want to be extra paranoid, you can go ahead and take a snapshot. In any case, if anything should go sideways with any part of the upgrade we can always return to where we started.

•   I also go ahead and shut down my MIS daemon. It’s possible that you could cause some odd errors or even corrupt some of your data files by making some of these changes while Mystic is actually running. I also have a script I use to automatically restart MIS if it stops running, a relic from back when MIS was fairly unstable, that I terminate while I’m at it.

•   I’ve decided to upgrade incrementally, going through the process for each version one at a time, assessing how to proceed with the subsequent upgrade as I complete the last one. The first step I need to complete is upgrading from A38 to A39. Two of our upgrades require using upgrade.exe to modify our binary data structures and I don’t want to risk corrupting my data files by skipping one of these (though I believe upgrade.exe is actually intelligent enough to deal with that these days!)

•   I’ve gone ahead and downloaded the Mystic v1.12 A39 archive. Once download, I extracted it to a temporary directory (“c:\mtemp112a39”) and then proceeded with the installation, installing it into second temporary directory (“C:\mystica39”.) Note that we’re not going to be running Mystic from here, just plucking the required files from this new installation.

•   Now, let’s consult our upgrade.txt instructions:

 .------------------------------------.
 | UPGRADING FROM 1.12 A37/A38 to A39 |-------------------------
 `------------------------------------'

 - Replace existing binaries with the new alpha binaries:

      mystic.exe
      mis.exe
      fidopoll.exe
      mutil.exe
      nodespy.exe
      qwkpoll.exe
      upgrade.exe
      mplc.exe (in scripts directory)
      mide.exe (in scripts directory)

 - Run upgrade.exe once to update your data files then you can
   delete it.

 - Add prompts #528-#537 to the prompt file for all themes you have
   on your BBS.  If you use the default prompts and have not customized,
   then you can simply replace default.txt in the DATA folder with that
   from the fresh installation.  These new prompts can be found below or
   in default.txt in the fresh installation.  See whatsnew for more
   information.

 - Copy over msgsearch.asc from the A39 installation to your TEXT directory
   if you use the default prommpts.

 - Replace "mis_events.ans" in your DATA folder with the newer one
   from the A39 installation
 
 - Replace "areafixhelp.txt" in your DATA folder with the newer one

 - Replace "filefixhelp.txt" in your DATA folder with the newer one

 - Replace "bulletin.mps" in your SCRIPTS folder with the newer one

 - Replace "onlyonce.mps" in your SCRIPTS folder with the newer one

 - Replace your msg_editor.ini from the text folder with the newer
   one from the A39 installation.  If you use a custom msg_editor.ini then
   you will need to modify "str7" to include the Draft option by adding a
   F at the end of the hotkey list and then adding "D-Save as Draft" into
   the list of options.  Use the default msg_editor.ini to guide you if
   you need help.

 - Recompile MPL programs (mplc -all in SCRIPTS directory)

•   So, wow, a lot of steps involved in the A38 to A39 upgrade. Let’s jump right in:

·   First, I’ll go ahead and skip down to adding the new strings to my default.txt language file. To do this I simply opened the new default.txt located in C:\mystica39\data, copy the new strings, #528-#537, and paste them into the appropriate place in my default.txt (which, for the record, is right at the end of the file.) You can do this using your text editor of choice. I’m using good old edit.com here strictly for extra street cred. 😉

Note that, if you’re planning on using the features related to these new strings, you’ll want to modify these to match the rest of your theme. This can obviously be an involved process, especially if you’ve heavily modified your theme. In the case of Distortion, I usually avoid using a lot of the cool new, modern user-facing features James keeps adding to Mystic, preferring to keep the system feeling more mid 90s era appropriate.

It’s clear from the prompts themselves that they all relate to the new draft message feature mentioned in the upgrade.txt file, which I’m not planning on using, so I’ll just leave these prompts as is. If some of them do end up appearing in my setup they’ll stick out like a sore thumb and I’ll modify them later.

·   The next step has us replacing our \text\msgsearch.asc with the updated version. The instructions specifically mention that you should do this if you use an unmodified default.txt file, which tells us that this isn’t a new required template, but an extra display file that is called from a string. Since Distortion’s strings are highly modified, I don’t call that display file, and can skip this step.

·   Next we’re asked to replace our \data\mis_events.ans with an updated version. Taking a quick look at the file confirms my suspicion that this is the template for one of MIS’s status screens. Mine are default, so I copy the file over, overwriting the original one.

·   The next two steps involve replacing two echomail related help files in our \data directory. These files will almost always be left stock, though if you’ve got a highly modded your system and you happen to be running an echomail network, you may want to confirm that you haven’t customized yours. If you haven’t, just copy the files over, overwriting the old ones. If you have, make the appropriate modifications to your old files to incorporate the new changes, or modify the new files to incorporate your customizations and copy away. In Distortion’s case, it’s the former, so I copy and overwrite.

·   The next two steps are to replace two of the stock MPL scripts. If you’re using these scripts in your setup and might have modified them, you’ll need to take a quick look at what has changed and make the appropriate modifications to your old files to incorporate the new changes, or modify the new files to incorporate your customizations and copy away. I’d recommend using some kind of text file compare (or “diff”) tool to speed up the process, though these kinds of changes are usually minor unless specifically noted. In Distortion’s case, I’m not using any of stock MPL scripts, so I skip this step entirely.

·   Finally, the last of the potentially tricky steps, replacing \text\msg_editor.ini. Well, I’ve completely customized my message editor, so I certainly don’t want to do that. The instructors tell me instead to simply modify str7 to include the new hotkey and key help. Again, I can tell from the string itself that it relates to the new draft message feature, so I don’t bother.

That said, I also notice that a new string, str18, has shown up. Hmph… it looks like James left that out of the upgrade instructions! Again, its related to drafts, so I don’t need it, but just for the sake of having a complete msg_editor.ini, I go ahead and copy the default str18 from the a39 msg_editor.ini into mine.

·   Next, we’re going to go back up to the very first step. We’re going to copy all of the executables from our C:\mystica39 directory (and \scripts subdirectory) to our Mystic installation, overwriting all of the old versions. I also like to copy any of the associated .ini files from the new version if I know my old ones are default. For example, I know my mide.ini is default, so I went ahead and copied it too, just in case there have been any changes to it.

·   Now we need to upgrade our data files by running “upgrade.exe”. If you run into any errors during these step you should immediately stop – something very bad has happened. You could try restoring your original directory and going back through the steps, or reverting and leaving your BBS as-is until you can do more troubleshooting. In case of Distortion, everything was successful.

I’d recommend you delete your upgrade.exe after you successfully complete this step. You won’t need it anymore.

·   Finally, I go to my \scripts subdirectory and run “mplc -all” to recompile all of my MPL scripts with the new version of MPLC. Again, look for any errors – if you do encounter any, most likely it’ll be due to a change in MPL which will require some (hopefully minor) updates to your scripts. You’ll want pair the error message the compiler gave you with a scan of whatsnew.txt at this point to try to figure out what has changed that could be causing you the error(s). In my case everything compiled without any errors.

·   Now that the upgrade is (apparently) complete, we should launch MIS, log on to the BBS, and take a look around. I briefly log into my system via local telnet and give everything a quick once over to make sure nothing looks amiss. I also test my echomail, which I’d highly recommended if you’re on any echomail networks, since that is one area where Mystic has been constantly developing in recent years. Distortion is the hub for a message network, so this is an important step for me.

•   At this point we’re done with this version. Distortion is on A39. Woot!?

Still, knowing we’re still several versions behind has to make you wonder if this new version introduced any bugs that subsequent released fixed. Maybe major ones, even. Well, let’s get moving on to A40…

•   I’ll start with downloading the Mystic v1.12 A40 archive. Once downloaded, I extract it to a temporary directory (“c:\mtemp112a40”) and then proceed with the installation, installing it into second temporary directory (“C:\mystica40”.) Sound familiar? You bet it does.

•   Again, we consult our guiding star, the upgrade.txt file:

.--------------------------------.
 | UPGRADING FROM 1.12 A39 to A40 |-------------------------
 `--------------------------------'

 - Replace existing binaries with the new alpha binaries:

      mystic.exe
      mis.exe
      fidopoll.exe
      mutil.exe
      nodespy.exe
      qwkpoll.exe
      upgrade.exe
      mplc.exe (in scripts directory)
      mide.exe (in scripts directory)

 - If you use default installation replace the default.txt from DATA with the
   newer one, otherwise the following prompts have been modified or changed
   and will need to be updated/added to your custom themes:

     Changed prompts: 18, 419, 420, 463, 486    
         New prompts: 538-552

 - Copy "msg_index.ini" from the TEXT folder into your TEXT folders
 - Copy "msg_index.ans" from the TEXT folder into your TEXT folders
 - Copy "msg_index_help.ans" from the TEXT folder into your TEXT folders

 - Copy "cfgroot4.ans" from the DATA folder into your DATA folder

 - Execute upgrade.exe

 - Recompile MPL programs

•   Some odd steps, but notably less than last time. Let’s dive right in!

·   Again, I’m going to skip copying the binaries for now and move to the next step, which seems to be copying more strings. Again, I simply open the default.txt located in C:\mystica40\data, copy the new strings, #538-#552, and paste them into the appropriate place in my default.txt. Good god, that’s a lot of new prompts. We better take a look at them and make sure we don’t need to spend a while customizing them to fit Distortion’s theme.

Ah, they all appear to relate to A40’s new reset password via email feature. This is a pretty neat feature, one I’d achieved in earlier setups with mods, but not something I intend on adding to Distortion quite yet. As with last time, I’ll leave the strings default and if they should appear somewhere I’ll spot them right away and come back and take care of them.

But wait… that’s not all! We also need to modify some existing strings. If you’re running a stock standard default.txt, you can just copy them over, but for the rest of us we need to roll up our sleeves and take a closer look.

I open default.txt from my Mystic installation and the one from my A40 temporary installation and compare each of the strings listed:

Prompt #18 in my installation is an error for when new users specify a password that is too short.
Prompt #419 is my user config editor password prompt.
Prompt #420 is an error for when the user specifies a short password in the user config editor.
Prompt #463 is the prompt for when editing a message subject in the FSE, which I assume has been replaced by prompts in msg_editor.ini.
Prompt #486 is a message quick scanning prompt.

Let’s consult the oracle (whatsnew.txt) about this:

+ Mystic now has a password policy in System Configuration where the minimum
   password length can be set along with number of required capital letters,
   numbers, and symbols.  It is highly recommended that the minimum password
   length is set to at least 7 characters.  Some default prompts have been
   updated to support this new feature: 18, 419, 420. If you have custom
   themes, you should take a look at the new defaults and consider updating
   your custom prompts as well.

+ Mystic will now validate that the user enters a valid e-mail address
   format when prompting for e-mail address during new user application and
   when editing user information.  Two new prompts have been added that will
   be displayed when they enter an invalid e-mail address: #463, #486.  You
   should update your prompts based on the new defaults.

Well, #18 and #420 will need to change to match my modifications and still be accurate, so I modify those using the new default.txt strings as a guide. #419 doesn’t need to change. Since I’m not using email functions on Distortion as of yet, I went ahead and copied of the new A40 strings for #463 and #486 for now, overwriting what i had..

·   Next we need to copy a few msg_index related files from our \text subdirectory. According to whatsnew.txt this relates to a new light bar message area lister. Since I don’t use this feature (again, Distortion forgoes many of the newer Mystic features to stick with the traditional ones) I’ll go ahead and copy them over, but I won’t worry about modifying them.

+ New menu command: M! This is a rewrite of the message area index reader
   rebuilt to work identically to the file base index lister.  See the
   msg_index.ini file for more details.  Command line option is the template
   name or default to msg_index.ini if none is specified.  I am not removing
   the old one just yet so that people have time to adapt to the new version
   and to test it for issues, but please note the old one will likely be
   replaced by this new one eventually once the features are all done and
   tested.

·   We’re asked to copy \data\cfgroot4.ans to our \data subdirectory. Taking a peak at the file shows that this is yet another template for one of MIS’s status screens. As mine are default, I copy the file over without any need to modify it.

·   Back up to the very first step to copy all of the executables from our C:\mystica40 directory (and \scripts subdirectory) to our Mystic installation, overwriting all of the old versions.

·   We then upgrade our data files by running “upgrade.exe” again. Again, if you run into any errors during these step, stop and troubleshoot, restoring to your backup if need be. Everything was fine on Distortion, however, and I delete my upgrade.exe.

·   Finally, I go to my \scripts subdirectory and run “mplc -all” to recompile all of my MPL scripts with the A40 version of MPLC.

This time I received a single error referring to a password variable not being found in “apply_sample.mps”. This is a stock script used to demo replacing the application process with an MPS and isn’t something I use on Distortion, and it makes sense that there might have been changes to it given all of 1.12 A40’s numerous password changes. I check the A40 installation and find that \scripts\apply_sample.mps had in fact been updated. This probably should have been mentioned in the upgrade.txt instructions. Oh well. Copying the new one over and re-running “mplc -all” produced no errors. Of course, since I’m not using apply_sample.mps, I could have just deleted it all the same. That said, some of you with highly customized setups might have scripted your application process, using this file as a starting point, so you made need to spend some quality time fixing it to work under A40.

•   Again, I briefly log into my system via local telnet and to make sure everything looks good. Our upgrade to A40 seems to be complete. Well, we’ve got momentum now… let’s keep going!

•   Once again, we consult the upgrade.txt file:

 .------------------------------------.
 | UPGRADING FROM 1.12 A40-A41 to A42 |-------------------------
 `------------------------------------'

 - Replace existing binaries with the new alpha binaries:

      mystic.exe
      mis.exe
      fidopoll.exe
      mutil.exe
      nodespy.exe
      qwkpoll.exe
      upgrade.exe
      mplc.exe (in scripts directory)
      mide.exe (in scripts directory)

 .--------------------------------.
 | UPGRADING FROM 1.12 A42 to A43 |-------------------------
 `--------------------------------'

 - Replace existing binaries with the new alpha binaries:
      mystic.exe
      mis.exe
      fidopoll.exe
      mutil.exe
      nodespy.exe
      qwkpoll.exe
      upgrade.exe
      mplc.exe (in scripts directory)
      mide.exe (in scripts directory)

 - Copy userchat.ans and userchat.ini from the TEXT folder into your TEXT
   folder

•   Interestingly, we see that the A40-A43 upgrade steps mostly only include replacing our binaries. I smell an opportunity to leapfrog! We’re skipping directly from A40 to A43!

•   I extract the copy of Mystic v1.12 A43 I downloaded originally when reviewing the upgrade instructions to a temporary directory (“c:\mtemp112a43”) and then proceed with the installation, installing it into second temporary directory (“C:\mystica43”.) Yes, this again.

·   Starting with the first step, since there aren’t many others this time, we’ll copy all of the executables from our C:\mystica43 directory (and \scripts subdirectory) to our Mystic installation, overwriting all of the old versions.

·   Again, I go to my \scripts subdirectory and run “mplc -all” to recompile all of my MPL scripts with the A43 version of MPLC. No problems.

·   A43 tells us we need to add a new \text\userchat.ans and \text\userchat.ini, file. Here’s what whatsnew.txt says on the subject:

+ Mystic's private user to user chat system now has a split screen chat
   option.  A new template userchat.ini and userchat.ans are required now to
   be accessible by your theme otherwise your user to user chat will not
   work.  See the default installation for these new files.

I went ahead and did a basic customization of the new screen and ini file to make it make Distortion a little better, thematically. I’m not going to go into a lot of detail right now, but suffice to say that one big benefit the new style of ini file based templates James has been adding lately is that customizing these screens is now incredibly easy and doesn’t require any of the old tricks of the trade, like animating the placement of control codes into the ANSI itself. I simply modify the ANSI template and edit the INI files with update coordinates and strings. Easy!

·   While in the whatsnew.txt I notice that a prompt string has changed slightly, despite not being referenced in upgrade.txt:

+ Prompt #464 message quote text now has &4 MCI code which is replaced by
   the time that the original message was written.

This is a great example of why you should always review your whatsnew.txt. In this case, the addition of the time on the message quote header is completely optional and wasn’t available to us before now (read: for years and years) so I have no great urge to modify it. I do, however, copy the description comment for #464 from A43’s default.txt file into my own for future reference.

•   With all that, we seem to be done. Now’s the time to give the whole setup one more test. I can already tell from my connection logs that inbound and outbound binkp and inbound telnet connections are all working. Logging into the board, everything appears to be functioning correctly. SUCCESS!

I hope this was helping to someone, somewhere! Stayed tuned for more tutorials of this sort in the future, most of which will likely be covering much more advanced topics.

Here’s a quick, generic guide on how to upgrade Mystic BBS from one version to another. I’m presenting this both because I’ve seen the occasional new Mystic SysOp ask for guidance on upgrading, but also because my BBS, Distortion, had been lagging behind several versions for a while, and the latest version as of this writing, 1.12 A43, seems to be fairly stable, so I figured it was time for me to upgrade. If my efforts can serve as a real-world demonstration of the upgrade process for others, why not? Note that this guide is definitely aimed at Mystic newbies, so if you’ve been at it for a while, you probably won’t get too much out of this.

While I’m demoing the process under Windows, it’s fundamentally the same for other builds of Mystic.

Process Overview:

•   First and foremost, backup your BBS. This can be done as simply as making a copy of your Mystic directory. Having this pre-upgrade backup available will allow you to “roll back” your changes if something should go wrong, or you encounter issues with the new version after the upgrade.

•   Next you need to download the version you intend on going to. While the latest version is listed prominently on http://www.mysticbbs.com, all of the older alpha versions of the current release and some much, much older files are also available at http://www.mysticbbs.com/downloads/.

•   Open upgrade.txt from the archive you just downloaded in your text editor of choice. Keep it open, as you’ll be referencing it a lot.

•   Scroll down to the section entitled “UPGRADING FROM xxx to xxx” for the version you’re currently running. In my case, Distortion was running 1.12 A38, so I’d be looking at the instructions titled “UPGRADING FROM 1.12 A37/A38 to A39”.

Read ALL of these instructions!

•   Many releases will only require replacing executables and sometimes recompiling your MPL scripts, but some involve many other steps. You should reference the whatsnew.txt file from the archive you downloaded earlier to get a better idea of what each of the required steps is referring to. You may be able to skip some steps related to features you’re not using, or you may need other information not listed in upgrade.txt.

Tip: In my opinion it’s much more convenient to reference the “what’s new” information from the Mystic Wiki, as it lists all of the changes for the entire version in an easier to read and search format, as well as linking to earlier version information too. http://wiki.mysticbbs.com/doku.php?id=whats_new_112 is the v1.12 what’s new, for instance.

•   If you’re upgrading through multiple versions in your upgrade, you should next scroll up to the next section. This would be “UPGRADING FROM 1.12 A39 to A40” for me, for example. Repeat the process of reading the upgrade instructions for this version and referencing the whatsnew.txt for that version if necessary. You should repeat this process until you get to the version you intend on moving to.

The purpose of doing this is to look for potential opportunities to avoid unnecessary, repeated tasks. You can often skip multiple steps, making a few changes as needed and then copying the executables from a later version, or even “leap over” versions entirely, saving yourself a lot of work. If you feel like there are too many changes and you’re paranoid about missing something, it may be safest just to follow each set of individual upgrade instructions one at a time.

In my case, I’ll be mostly following each section of version upgrade instructions one at a time.

•   If you’re able to leap to your intended version or you are only upgrading one version, you can begin the process. Otherwise, download the version you need to start with. For me, this would be 1.12 A39.

I’d recommend shutting down your BBS before actually going through the upgrade steps, as it’s possible you could accidentally corrupt some of your data files or produce various other errors, and that’s no fun!

•   I HIGHLY recommend reading whatsnew.txt in full for details on what’s been added or changed in the new version(s) you’re upgrading to, even if you’ve already read it when referencing changes. Upgrade.txt only includes the bare minimum steps required to upgrade to the new version and leaves out details on the vast majority of new features and enhancements. Whatsnew.txt is more or less the only source for documentation these days, so you’ll want to make sure you don’t miss out on anything new you might benefit from implementing. More importantly, it’s nice to know why things are suddenly working different in a new version, right?

•   After the upgrade is finish (and perhaps between versions, if going step by step) you should test your system, looking for any issues. Assuming none pop up, you’re done!

Maybe take one more skim through whatsnew.txt to consider the impact of some of the new changes as well as how you might implement some of the new features. Yes, I know I might be overselling this, but I suppose I have a lot of guilt about rarely taking advantage of James’s hard work with Distortion. 😉

Next in part 2, the fun part! We’ll go through my actual upgrade process…