Presence Migration Guide

From PresenceWiki
Revision as of 11:57, 12 August 2015 by Rob (Talk | contribs)

Jump to: navigation, search

Introduction

This is a best practices guide to migrating Presence from one server to another, attempting to highlight some potential pitfalls that can be avoided with some planning.

Pre-Migration Checklist

Host Dependencies

Very often Presence Tasks are built to be dependent on the environment in which the Presence Server runs. Some examples include:

  • Use of absolute file paths
  • File dependencies
  • IP Address references
  • Executable Programs

These can cause a headache when migrating. For example:

  • Your Task may run a gateway program on the server's C Drive. Does this gateway program also exist on the new server's C Drive? If not, your Task will break unexpectedly.
  • Do your Tasks require any local files? For example, if you have an On Demand application, are there HTML files or images on the server that need to be copied across, possibly in the res\httpdocs directory?
  • Your Task may write to a file located in c:\myfiles\ - does the same directory exist on the new Server? Are Permissions set correctly?
  • The server's IP Address may be hard-coded in Tasks, or may appear in a list of authenticated servers on an FTP Server that a Task connects to. When the IP Address changes what implications will this have on your Tasks?

Careful thought needs to go into these questions and time should be spent ensuring that when the Server migration is complete everything will run as it used to. Consider replacing hard-coded file paths, IP Addresses, etc, with Global Variables so that these things can be easily changed - a Global Variable allows you to store such information in one place and reference it in your Tasks, instead of having to modify each Task individually, which can be very painstaking.

Firewall Considerations

Please consult the document describing Server Ports. Will these ports be accessible to client PCs and other machines that Presence is dependent on? Do you need to modify your firewall settings?

License Migration

Presence Server licenses are based on the physical address of the network card, also known as the MAC Address. In order for the Server to run successfully on the new host the license file must match that host's MAC Address. This will involve International Presence generating a new license file for you, which usually attracts an administration charge. This should be done in advance of the migration. For replacement license files please drop us an email.

Consider your users!

It is always worth thinking about Presence users before attempting to migrate as this can be a time consuming procedure and will result in some downtime.

Do you expose any Web Services to the outside world? Are you running a separate HTTP server to channel on demand requests? Are any other systems relying on Presence? Will you be inundated with phone calls from people who have not received the reports or alerts they were expecting?

Save yourself unnecessary stress by thinking about these things in advance and planning the downtime. If there are third party components that rely on Presence, think about the need to re-point those systems to the new Presence server, either now or after the migration is complete.

Migration Procedure

When the above points have been addressed and your are comfortable that the new environment will not cause any significant problems to your Tasks, it is time to begin the migration.

Suspend Presence Tasks from Live Task Queue

When the new Server starts you probably don't want all of your Tasks to run automatically without checking them first. Go to the Live Task Queue in the Administration Client and suspend any live Tasks. Make a note of any Tasks which were already suspended as you may not want to resume them when the migration is complete.

In order to suspend Tasks you can either do this individually, or you can select multiple Tasks from the list and suspend them all at once.

Shut Down Presence

Through the Heartbeat Client, stop the following Services:

  • Presence Server
  • Database Server
  • HTTP Server (if running)

When these services are stopped, launch the Windows Services control. Manually stop the following services:

  • Presence RPC Server
  • Presence Viii Heartbeat Server

Exit the Heartbeat Client. Launch Windows task manager and if a process called channelman.exe is running, manually stop this by right-clicking it and selecting "End Process Tree".

Database Backup

At this stage you should make a copy of any files in the "res/database" directory ending in .wal or .dbn. We also recommend running the compact tool on the Database - ":\program files\presence viii\bin\databasecompactor.exe"

Installation

Follow the standard Installation procedure on the new Host machine, as if this were a brand new installation. When the installation is complete, do not start any Presence services. It's fine for the Heartbeat and RPC Services to start (they will do so automatically when the Windows services are installed), but the database server and Presence server should not be allowed to start. It's not a disaster if they do, but you'll have to stop them again before proceding.

After Installation

Set Permissions

By default the Presence Windows Services (RPC Server and Heartbeat Server) will run under the local system account - i.e., whoever is logged on at the time of installation. We recommend creating a separate Windows account for Presence to run under so that the appropriate permissions can be set for that user. This should be applied to both Windows Services.

Copy resources

Any files which your Tasks are dependent on (resources) should now be copied across to the new installation. This may include files in the res\httpdocs directory or elsewhere.

Copy database

The files which you backed up earlier - .dbn and .wal files - should now be copied across to the new database directory on the new host, for example:

\program files\presence viii\res\database\

These files contain all of your Task information, queue and schedule information, comparison data, contacts, edit history and task activity information.

Copy logs

Task logs are contained in files on the server that runs the Presence Database, under the following directory:

\program files\presence viii\res\logs\tasks\

If you wish to retain these logs, it is a good idea to zip them up into a manageable file and copy them across to the new Host.

Copy presenceconfig.xml

This needs to be copied from the "res\config" directory into the same directory on the new Server. Once copied, open the file with wordpad or a similar text editor, and modify any references to the old hostname.

http://www.international-presence.com/wikidocs/images/config_old_server_1.gif

...

http://www.international-presence.com/wikidocs/images/config_old_server_2.gif


Starting the new Server

Once you are comfortable that everything has been migrated it is time to restart the Presence Server on the new machine. This should be done with care and we recommend that it is done manually in order for the services to properly register themselves with the new Heartbeat Server.

Ensure the Heartbeat Client is running so you can see when processes are started and ready.

Start > Programs > Presence Viii > Heart Beat > Heart Beat Client

Start Database Server

First, start the Database Server:

:\program files\presence viii\bin\dbserv.exe

Or:

Start > Programs > Presence Viii > Server > Presence Database Server

Once this is running it should appear in the Heartbeat Client (with nothing else):

http://www.international-presence.com/wikidocs/images/heartbeat_client_db_only.gif

At this stage a couple of modifications need to be made to the database. Go into the "bin" directory within the Presence installation and locate the program called "sqltool.exe". Run it. Type in a username of "pbsysadmin" and the password which you entered on first installing Presence. Execute the following SQL Commands:

DELETE FROM APP.SERVERPORTS

DELETE FROM APP.MACHINES

UPDATE APP.TASKQUEUE SET MACHINEID=NULL

This will ensure there is no reference to the old server. Usually this happens automatically once the server starts up and notices that the old server is no longer available, but it is good practice to do it manually to eliminate the possibility of confusion once the server starts.

Start Presence Server

:\program files\presence viii\bin\presenceserver.exe

Or:

Start > Programs > Presence Viii > Server > Presence Server

As with the Database Server, once the server starts it should appear in the Heartbeat Client. Click on the Presence Server and select "Server Status" from the list of items in the left hand pane.

When the server first starts it will display a message of "Checking License". If the license is valid this message should be replaced with "Starting Process Queue". This can take some time, particularly if you have a large number of Tasks on the live task queue.

Remember that nothing will actually run at this stage, as we have suspended all Presence tasks earlier and the HTTP server is not yet started so no On Demand Tasks can run. When the message "Running (Expires ....)" is shown, the server is now ready to run Tasks.

Verify JDBC Connections

Spend some time verifying that your JDBC connections still work (Database Resources), and that Presence can still contact any other services that it needs to such as FTP servers, SMTP servers and web services.

If you are upgrading from an earlier version to 3.5.5 or later, you may need to replace your JDBC drivers with compatible ones. This is because Presence 3.5.5 uses an updated JRE (1.6) which may not be compatible with older JDBC drivers. For instance SQL Server requires sqljdbc4.jar in order to connect under the new JRE - see Connecting To SQL Server.

Resume Processes on Live Task Queue

Launch the Administration Client and open the Live Task Queue. If everything has gone according to plan you should see all of your Tasks here, still in their suspended state.

Resume them carefully. If they run now (due to having Catch Up enabled or not having a Schedule Node attached), check that they behave as they did on the old Server. Keep an eye on the log files to spot errors, and the Activity Archive.

Remember: If you have forgotten anything it is better to discover and fix the problem when you have just a few Tasks running, rather than trying to sort out problems with several hundred Tasks.

Resume HTTP Server

If you are using the Presence HTTP Server for On Demand Tasks, now is a good time to restart it and begin testing those:

:\program files\presence viii\bin\httpstart.exe

Or:

Start > Programs > Presence Viii > HTTP Server > Start HTTP Server

Odds and Ends

Finally, check any external systems or programs which rely on Presence Tasks and ensure that they have been modified to point to the new Server. Check the connections and output from such systems and make any modifications that are necessary.

Migration Complete

Hopefully your Presence Server is now running happily in its new home.

Trouble Shooting

If you encounter any problems with this procedure, please contact us on +01 (321) 7269941 (US and Americas) or +44 208 972 1390 (UK and Europe). Alternatively you can Email us.

Backing out

If all else fails and you need to go back to your original Presence server, just shut down the new server and restart the old one (ensuring that any external links are updated).

See Also