Introduction

Upgrading a XenApp worker from XenApp 6.0 to XenApp 6.5 is now made easier by using the Citrix XenApp 6.0 to 6.5 Upgrade Utility. Citrix has created a script to perform what normally would be a long process of manually uninstalling XenApp 6.0 components in a select order, then installing XenApp 6.5. You can find more information (including the script) here:

http://support.citrix.com/article/CTX130614

Migration, which is defined as the new installation of XenApp on a clean OS, is still considered best practice, because it offers customers a clean working and more manageable environment. However, for those customers who are unable to migrate (eg. due to limited resources), we’ve created this utility to help facilitate the upgrade process. This new tool runs silently in the background and manages multiple reboots as the various packages are removed and in-turn, upgraded to the latest version of XenApp. To access the support forum specific to install/upgrade, please look here:

http://forums.citrix.com/forum.jspa?forumID=1313

Configure the script before you start

Since XenApp installations vary due to the large number of options, this utility does require the user to tailor the command-line options to meet his individual needs. Here are the options that must be tailored within the script:

  1. File location for the latest version of XenApp (UNC path).
  2. Install command-line. By default, we only include the XenApp role. Typically you want this option to include all of the optional components you previously installed in XenApp 6.0, so be sure to add those to the command-line as required. See appendix for all install command-line options.
  3. Farm Join command-line, establishing the location for the DSN file and establishing ODBC credentials at a minimum. We discuss the DSN file in more detail in the following section. See appendix for all XenApp 6.5 configure command-line options.

Modify the join command line

Taking a little extra time to review the accuracy of your Config/Join command-line will increase the probability that your newly upgraded XenApp worker will join the XA6.5 farm the first time. Don’t worry if your Farm Join doesn’t work though, with this utility you can always correct your mistake and run it again. Here are some of the settings that most often cause a potential Join operation to fail:

  1. DSN File location (/DSNFile option)
    The DSN file describes the connection details for third-party databases such as Microsoft SQL or Oracle. If you are using a third-party database, this DSN file already exists on all of the servers in your XA6.5 farm. Go to one of these servers and make a copy. The location is typically here: c:\Program Files (x86)\Citrix\Independent Management Architecture\mf20.dsn. Copy this file to a local directory on your XA6.0 server prior to running the XenApp upgrade utility. The utilities’ default Join command line expects the DSN file to be placed here: c:\mf20.dsn.
  2. ODBC UserName and Password (/OdbcUserName and /OdbcPassword options)
    The ODBC UserName and Password describe the credentials for connecting to your XA6.5 database. First, determine whether your database uses Windows or SQL-based connections. The utility specifies a “Windows” user by default. If your database uses SQL based credentials, add the command-line option: /AuthenticationType:Sql.
  3. SQL Express (/SimpleDB option)
    Some smaller farms may use a SQL Express database. For this command line, you will not require a DSN file. Instead, use the /ServerName and /SimpleDB command line options. Specify the IP address (or DNS name) for the server which hosts the SQL express database for the /ServerName. /SimpleDB does not require any additional parameter.

Temporarily disable restrictions

The XenApp Upgrade Utility is written in Powershell and is governed by the latest security restrictions in Windows Server 2008 R2. To run this script successfully and for best results, the user will want to temporarily make the following modifications to the operating system and the script, in advance:

  1. Disable UAC (User Account Control)
  2. Set Powershell execution policy for both 32-bit and 64-bit Powershell sessions to UNRESTRICTED
  3. Logon as a user who has local administrator privilege and Citrix Administrator privilege
  4. Remove security from downloaded powershell scripts with alternative data streams

Copy the script locally and ensure that there are no “alternative data streams” applied to the script if you download it from the web using a browser. These NTFS alternative data streams are added to the file with a Zone identifier, indicating the file’s origin. When applied, these will inhibit your ability to execute them properly on the local machine due to security policies. To ensure that these alternative data streams are not interfering with execution, open the properties dialog for the script file and verify that there is no “Block”. If there is, simply select “Unblock” from the dialog window.

Run the script

Now you are ready to run the script. When you run the script, it will assume that you are the currently logged-on user and prompt you for credentials. These credentials are not stored by the script, but instead are stored by the Task Scheduler and the operating system in an encrypted format. The task scheduler maintains these credentials throughout the process, so logging back into the system is not recommended until the upgrade process is complete.

Upgrade flow diagrams

Validate the successful completion of the script

The user can let the script run in the background, allowing sufficient time for the entire process to complete before checking progress (typically 30-45 minutes), or the user can logon while the script is executing to check progress. The latter method is a little tricky, since the script reboots several times during execution, resulting in the user session being logged-out even while he is in a session looking at the log results. The optimum method is to kick-off the script, wait 30-45 minutes and then logon to check progress. The first check is to go to the event viewer and filter by process, selecting process MSIEXEC. A fully successful run will have an event log entry which states: “Citrix XenApp upgrade Step 4:PASS! Citrix XenApp upgrade is complete”. Another place to check for more detailed execution status is to open the overall log file. This is set to C:\Windows\temp\XenAppUpgrade.log by default.

Run the script again due to an issue

Since this script does have four major steps, inevitably there can be an issue with one of them, requiring the user to run the script again. Fortunately, we have built-in functionality to resume from any step:

  1. Uninstall XA6.0
  2. Install XA6.5
  3. Join XA6.5
  4. Validate IMA Service

A hypothetical issue might be a case where steps 1 and 2 above run successfully, but there is a failure on step 3. The nice feature of this script is that the user can choose to resume the script at a point other than the beginning. In our case, let’s assume that there is an ODBC user credential issue with step 3 (Join XA6.5). The user can simply correct the issue by modifying the Join XA6.5 command-line within the script and run it again, this time specifying a “Step” parameter on the script command line. In our case, the new script command line is: “c:\UpgradeXenApp.ps1 3” which runs the script starting with Step 3, performing the XA6.5 join again.

Appendix

XenApp 6.5 Install Command-line reference
http://support.citrix.com/proddocs/topic/xenapp65-install/ps-install-command-line.html
XenApp 6.5 Configure Command-line reference
http://support.citrix.com/proddocs/topic/xenapp65-install/ps-config-command-line.html
XenApp 6.0 to 6.5 Upgrade Utility KB Article
http://support.citrix.com/article/CTX130614
Technical Guide for Upgrading/Migrating to XenApp 6.5:
http://support.citrix.com/article/CTX130888