Upgrading VMware Mirage 4.x to 5.0

As VMware Mirage 5.0 is now available many want to upgrade to the latest version. While the way of doing an upgrade from 4.x to 5.0 has not change it will change with 5.0 going forward.

Up to version 5.0 you need to uninstall old versions of the Mirage server components first and then install the new ones. This needs to be done in a specific order:

  1. Uninstall all Mirage servers
  2. Uninstall Mirage management server
  3. Uninstall additional components (Mirage management console, WebAccess and WebManagement)

After everything is uninstalled the components need do be installed as follows:

  1. Install Mirage management server
  2. Install Mirage servers
  3. Install additional components

It is most important to (un)install the Mirage management server and Mirage server in the right order. The remaining components can be (un)installed in no particular order. For more information about upgrading Mirage have a look at the following article: Best practices for upgrading VMware Horizon Mirage.

For future upgrades, for example, from Mirage 5.0 to Mirage 5.next it will not be required to uninstall the Mirage server components first. You will be able to just run the MSI of the new Mirage version and it will automatically detect all existing settings (like database configuration, service account used, cache and storage location) and then do the upgrade.

From a technical point of view the upgrade from 4.4.x to 5.0 could also be done using this new mechanism. But because some advanced error handling needed to be implemented in the Mirage server software, which was implemented with Mirage 5.0 and is not available in prior versions of Mirage, it is not supported and therefore not recommended to use this upgrade method when upgrading from 4.4.x to 5.0. The traditional way via the (un)install upgrade method must be used.

Best practices for upgrading VMware Horizon Mirage

With the newest version of Mirage released just a few days ago there is often the question how to upgrade the Mirage servers to the latest release.

Luckily the instructions on how to upgrade Mirage servers are documented in the VMware Horizon Mirage Administrator’s Guide (page 265 ff.) and also as a separate KB article called: Best practices for upgrading VMware Mirage (2031711).

Unfortunately one crucial thing isn’t mentioned in the documentation: Do not use the “Create new storage areas.” option during the upgrade process of the Mirage management server.

MirageUpgradeNewStorageArea
If this option is used and the path of the original storage area is entered everything of your Mirage installation (Base Layer, AppLayer, CVD data, etc.) is getting deleted and is lost permanently if you haven’t created a backup before!

MirageUpgradeNewLocalCache

The same is true is when the “Create new local cache area.” is used while upgrading the Mirage server software. This situation is far less critical as only the local cache of the server itself is deleted but no important stuff like base layers and CVD data. This may result in some short-time performance penalties as the cache has to be filled again

So please make sure to keep this in mind before and while upgrading your Mirage servers.

Install Horizon Mirage silently

Testing different versions and new versions of a software product in a lab environment can be very cumbersome if you always have to install servers and clients manually. If you think further automating the installation process of Mirage server components also helps you to dynamically scale your Mirage deployment.

For this reasons I always try to automate the installation process of each product I have running in the lab. While this is most often very easy und nicely documented by the vendors (e.g. VMware Tools or the View Connection Server) this isn’t the case for the Mirage server components.

In the following article I cover how to install each Mirage component silently, beginning with the Mirage client. Please make sure you change the file name for each installer accordingly to the Mirage version and bitness you are using.

Software Prerequisites
Every Mirage component (client, server, console and file portal) requires Microsoft .NET Framework 3.5 SP1 to be installed. Please make sure .NET Framework is installed before trying to install any Mirage component silently.
The /qr parameter
Please make sure you use the /qr parameter to install the Mirage server components silently. Every other MSI unattended parameter like /qb or /qn will fail or prompt to accept the licensing agreement.

Mirage client

The unattended installation of the Mirage client is documented in the official VMware Horizon Mirage Administration Guide on page 52. Also my colleague Kim Nis Neuhauss wrote a detailed article about the different deployment methods of the Mirage client.

The installation of the client is really straight forward.

MirageClient.x64.59447.msi SERVERIP=MirageServer:Port USESSLTRANSPORT=true /quiet

You just have to specify the SERVERIP parameter which should contain the FQDN and the port of your Mirage server and if you use SSL instead of TCP for communcation you have to add the USESSLTRANSPORT=true parameter.

Installing the Mirage servers components isn’t that easy as the parameters aren’t documented but it is of course possible!

Mirage management server

[yellow_box]The unattended installation of the Server components assumes that you already have a supported SQL server up and running on which the Mirage database will be installed on. Please make sure the account which is used for the unattended installation has the appropriate permissions on the SQL server instance.[/yellow_box]

To install the Mirage management server silently you have specifiy some of the following parameters:

Parameter Value Required Description
DBSERVER ServerName Yes This presents the FQDN of the SQL box on which you want to store the Mirage database
DBSERVERINSTANCE InstanceName No This is the name of the SQL instance in which you want to store the database. This parameter is only required if have a dedicated SQL instance of your server (i.e. for SQL Express
SERVICEACCOUNTMODE localsystem | CustomUser Yes Specifies wether you want to use the local system account (localsystem) or a dedicated service account (CustomUser) for the Mirage service.
SERVICEACCOUNT Domain\Username No Needs to be specified if CustomUser is choosen as SERVICEACCOUNTMODE.
SERVICEPASSWORD Password No Needs to be specified if CustomUser is choosen as SERVICEACCOUNTMODE.
ADMINGROUPACCOUNT Domain\Groupname Yes Name of the Active Directory group which will be appointed as Mirage administrators.
AFFECTSTORAGE 1 No Specifies if you want create a new storage areas (1) or let the installer decide (0) if it wants to create a new or use an existing one.
WORKDIR C:\PathToMirageStorage No If AFFECTSTORAGE is set this parameter specifies the path to the storage area.

For a new single-server installation using a local SQL Express installation and the storage area on an additional drive called E: you would use the following installation parameters:

mirage.management.server.x64.59447.msi DBSERVER=localhost DBSERVERINSTANCE=SQLEXPRESS SERVICEACCOUNTMODE=localsystem ADMINGROUPACCOUNT="HorizonFluxMirage Admins" AFFECTSTORAGE=1 WORKDIR="E:\MirageStorage"

To install a multi-server setup with a dedicated service account and SQL server you would use something like this:

mirage.management.server.x64.59447.msi DBSERVER=sql.horizonflux.com SERVICEACCOUNTMODE=CustomUser SERVICEACCOUNT=HorizonFluxMirageService SERVICEPASSWORD=TopSecretPassword ADMINGROUPACCOUNT="HorizonFluxMirage Admins" AFFECTSTORAGE=1 WORKDIR="\\file.horizonflux.com\MirageStorage" /qr

Mirage server

To do an unattended installation of the Mirage server some of the following parameters must be specified:

Parameter Value Required Description
DBSERVER ServerName Yes This presents the FQDN of the SQL box the Mirage database is stored on
DBSERVERINSTANCE InstanceName No This is the name of the SQL instance in which the Mirage database is stored. This parameter is only required if have a dedicated SQL instance of your server (i.e. for SQL Express
SERVICEACCOUNTMODE localsystem | CustomUser Yes Specifies wether you want to use the local system account (localsystem) or a dedicated service account (CustomUser) for the Mirage service.
SERVICEACCOUNT Domain\Username No Needs to be specified if CustomUser is choosen as SERVICEACCOUNTMODE.
SERVICEPASSWORD Password No Needs to be specified if CustomUser is choosen as SERVICEACCOUNTMODE.
AFFECTCACHE 1 No Specifies if you want create a new local cache area (1) or let the installer decide (0) if it wants to create a new or use an existing one.
CACHEDIR C:\Program Files\Wanova Mirage\LocalCache No If AFFECTCACHE is set this parameter specifies the path to the local cache area.
CHUNKCACHESIZE 102400 No If AFFECTCACHE is set this parameter specifies the size (in megabyte) of the local cache area.

For a single-server installation using a local SQL Express installation, a local system account and a 20GB local cache in the default location the following parameters will suffice:

msiexec /i mirage.server.x64.59447.msi DBSERVER=localhost DBSERVERINSTANCE=SQLEXPRESS SERVICEACCOUNTMODE=localsystem AFFECTCACHE=1 CHUNKCACHESIZE=20480 /qr

For a multi-server installation with a dedicated SQL server and service account and also a dedicated local cache drive the following installer switches would the job:

mirage.management.server.x64.59447.msi DBSERVER=sql.horizonflux.com SERVICEACCOUNTMODE=CustomUser SERVICEACCOUNT=HorizonFluxMirageService SERVICEPASSWORD=TopSecretPassword AFFECTCACHE=1 CACHEDIR=E:\MirageCache CHUNKCACHESIZE=102400 /qr

Mirage WebAccess

To install the Mirage WebAccess feature (also known as File Portal) you frist have to install the Microsoft Internet Information Service (IIS) with some additionally features. This can be done using the Server Manager or using two simple PowerShell commands. For a detailed description of what IIS features are needed and how to install them using PowerShell have a look at the following of my articles: Install Horizon Mirage prerequisites via PowerShell.

After you installed the required software components you can install the file portal silently using some of the following commands:

Parameter Value Required Description
ADMIN_VIRTUAL_DIR_VAL VirtualDirectoryName No The folder on which the admin file portal should be reachable, i.e. http://mirage/VirtualDirectoryName
MGMTSERVER ServerName Yes This presents the FQDN of the Mirage management server.
VIRTUAL_DIR_VAL VirtualDirectoryName No The folder on which the file portal should be reachable, i.e. http://mirage/VirtualDirectoryName

To install the File Portal on the same machine as the Management Server using all default setting the following command can be used:

mirage.WebAccess.x64.59447.msi MGMTSERVER=localhost /qr

To install the File Portal on a dedicated machine using different virtual directory names you could use the following command:

mirage.WebAccess.x64.59447.msi MGMTSERVER=mirage-web.horizonflux.com ADMIN_VIRTUAL_DIR_VAL=AdminWeb VIRTUAL_DIR_VAL=Web /qr

Mirage management console

To install the Mirage management console silently you don’t have to provide any additional parameters beside /quiet.

mirage.management.console.x64.59447.msi /quiet
Disclaimer
These unattended installation commands for the server components and the console are not officially documented and therefore most likely not supported by VMware. Please test this in a development environment before using on production systems.

Install Horizon Mirage prerequisites via PowerShell

For the installation of the Mirage server components some specific Windows features are needed.

For the Mirage server, the the management server and the management console Microsoft .NET Framework 3.5 SP1 is needed. The installation of this feature can be accomplished via the Server Manager or via PowerShell.

To install .NET Framwork via PowerShell just start PowerShell as an administrator and then run the following two commands:

Import-Module ServerManager
Add-WindowsFeature NET-Framework-Core

To install the Mirage File Portal (WebAccess) also requires .NET Framework 3.5 SP1 but additionally it requires the Microsoft Internet Information Service (IIS) with some additional components like the IIS 6 Management Compatibilit feature.

Source: http://www.vmware.com/pdf/mirage-administrators-guide-4.pdf, Page 44
Source: http://www.vmware.com/pdf/mirage-administrators-guide-4.pdf, Page 44

To install these features through the Server Manager can be a bit cumbersome and using the following PowerShell commands to install IIS and all the features required by the Mirage File Portal is much easier.

Import-Module ServerManager
Add-WindowsFeature Web-Static-Content, Web-Default-Doc, Web-Dir-Browsing, Web-Http-Errors, Web-Asp-Net, Web-Net-Ext, Web-ISAPI-Ext, Web-ISAPI-Filter, Web-Filtering, Web-Mgmt-Console, Web-Scripting-Tools, Web-Mgmt-Service, Web-Metabase, Web-WMI, Web-Lgcy-Scripting, Web-Lgcy-Mgmt-Console

If you haven’t installed .NET Framework before installing IIS just add the NET-Framework-Core at the end of the Add-WindowsFeature command for the IIS feature installation (and don’t forget to add a comma after Web-Lgcy-Mgmt-Console).