vmware horizon migration tool user guide...this document version applies to vmware horizon migration...

VMware Horizon Migration Tool User Guide

1/31 @2017 VMware, Inc. All rights reserved.


Version 3.0.0

August 2017

VMware End User Computing



@2017 VMware, Inc. All rights reserved. This product is protected by U.S. and

international copyright and intellectual property laws. This product is covered by

one or more patents listed at http://www.vmware.com/download/patents.html.

VMware is a registered trademark or trademark of VMware, Inc. in the United

States and/or other jurisdictions. All other marks and names mentioned herein

may be trademarks of their respective companies.

VMware, Inc.

3401 Hillview Ave

Palo Alto, CA 94304

www.vmware.com

http://www.vmware.com/download/patents.html

http://www.vmware.com/



Contents

1. About This Guide ...................................................................................... 4

2. Overview.................................................................................................. 4

2.1. Features ............................................................................................ 4

2.2. Migration Scenarios ............................................................................ 5

2.3. Migration Process ............................................................................... 6

3. Prerequisites ............................................................................................ 7

3.1. System Requirements ........................................................................ 7

3.2. Software Requirements ...................................................................... 8

3.3. User Profile Privilege Requirement ...................................................... 8

4. Migration Step by Step .............................................................................. 9

4.1. Collecting information ......................................................................... 9

4.2. Migration from XenDesktop to Horizon 7 .............................................. 9

4.3. Migration from XenApp to Horizon 7 .................................................. 15

4.4. Migration from XenDesktop to Horizon Cloud ..................................... 23

5. Known Issues and Limitations ................................................................. 28

5.1. XenDesktop ..................................................................................... 28

5.2. XenApp ........................................................................................... 29

6. Scaling .................................................................................................. 29

7. Logging and Troubleshooting .................................................................. 30



1. About This Guide

This document guides you through how to use Horizon Migration Tool to migrate

from XenApp and/or XenDesktop to Horizon 7.x or Horizon Cloud.

This document version applies to VMware Horizon Migration Tool version 2.3.

2. Overview

2.1. Features

Horizon Migration Tool, which migrates published applications and virtual

desktops from XenApp & XenDesktop to Horizon 7 or Horizon Cloud, has the

following features:

For XenDesktop migration

• Environment checking

• Pool creation

• Pool migration

• Entitlement migration

• Migration status tracking

• Configuration validation.

For XenApp migration:

• Environment checking

• Farm and Pool creation

• App pools & desktop pools migration

• Entitlement migration, with flexibility (composition, etc.)

• Horizon agent readiness checking of RDSHs

• App availability checking on RDSHs

• Compatibility checking



• Configuration validation

2.2. Migration Scenarios

Supported XenApp & XenDesktop versions:

• XenApp & XenDesktop 7.6 and above

• XenApp 6.0

• XenApp 6.5

• XenApp 5.0

Supported XenApp types:

• Server desktop

• Application - server installed

Supported XenDesktop types

• Manual Pool

• Automated Pool (MCS pool and PVS pool)

Supported user and group types in entitlement:

• Domain users and groups

Supported Horizon versions:

• Horizon 7.2

• Horizon Cloud (16.11.0 and 17.1.0 releases)

Supported Migration Scenarios:

From To Horizon 7.2 Horizon Cloud

XenApp 5.0, 6.0, 6.5, 7.6 and above Yes No



XenDesktop 7.6 and above Yes Yes

Note:

XenApp 5.0, 6.0, 6.5 and XenApp & XenDesktop 7.6, 7.11, and 7.13 have been

tested. Other versions have not been tested, but versions about 7.6 should be

compatible.

2.3. Migration Process

The latest version of Horizon Migration Tool supports migrating a single Citrix

Delivery Site (or farm in Citrix 6.x) to Horizon directly. If you have a production

environment of large scale, migrate site by site (or farm by farm) instead of

migrating the whole system at the same time.

Processes for all the three migration scenarios are listed as below.

1. Process for migration from XenDesktop to Horizon 7

2. Process for migration from XenDesktop to Horizon Cloud



3. Process for migration from XenApp to Horizon 7

Note: Step 3 - it is OK to re-use the existing XenApp RDSH host and perform an

in-place migration. New RDSH hosts are used in the examples provided in this

guide.

3. Prerequisites

Before running Horizon Migration Tool, check your environment and make sure

the following requirements are met.

3.1. System Requirements

• The Horizon 7 infrastructure must be in the same domain as the XenApp

& XenDesktop.

• The Horizon infrastructure must meet Horizon requirements, refer to

VMware Horizon Documentation.

• The vCenter infrastructure must meet vSphere requirements, refer to

VMware vSphere Documentation.

• Put Citrix Delivery Groups into maintenance mode.

• Open firewall ports 135 and 445 on Citrix desktops and template virtual

machine.

https://www.vmware.com/support/pubs/view_pubs.html

https://www.vmware.com/support/pubs/vsphere-esxi-vcenter-server-6-pubs.html



3.2. Software Requirements

The Horizon Migration Tool should be run on Citrix Delivery Controller which

must have the following software installed:

• JRE 8 or above

Note: JRE8 is a must because Horizon API requires it. Both JRE or JDK

work. If no JRE is found on system, the installer of the Horizon Migration

Tool will install it for you.

• .NET Framework 2.0 for Windows 2008

• .NET Framework 3.5 for Windows 2012

Note: In case proper .NET Framework does not exist, the following

message will be displayed while running the Horizon Migration Tool:

• Windows Powershell

• vSphere 6.0 Update 1 or later is required for Horizon instant clone.

3.3. User Profile Privilege Requirement

• The user, which is used to run the Horizon Migration Tool, must have

XenApp & XenDesktop Delivery Site administrator privilege

• The user, which is used to connect to Horizon, must have administrator

privilege



4. Migration Step by Step

First, a video demo of the tool can be found in the following playlist:

https://youtu.be/CZE8TAzTctE

4.1. Collecting information

Given that you have setup your environment and meet the prerequisites, collect

the following information to start migration process:

Category Specific information

Horizon Host name or IP, User Name, Password, Domain

Horizon Agent Path of installation file

Domain information Domain user with administrator privilege

(This is only required when migrating XenDesktop to

Horizon Instant Clone pool)

vCenter Host IP, User Name, Password

4.2. Migration from XenDesktop to Horizon 7

1. Log in Citrix Delivery Controller server and launch Horizon Migration Tool by

double clicking “HorizonMigrationTool.exe”

2. Choose Source and Target.

Select “XenDesktop 7.6 and above” as source and “Horizon 7.2” as target.

Click “Next”.

https://youtu.be/CZE8TAzTctE



3. Summary of the Citrix dump information is displayed.

Click “Next”.

4. Fill in the target information:

Click Browse to select Horizon Agent installer.

Fill in IP address, user name and password of vCenter.

Click “Next”.



Note:

FQDN of vCenter won’t work here.

The user must have administrative privilege.

5. Fill in the login information for Horizon. If there is Certificate warning, click

“yes” to accept and forward.

Click “Next”.

Note: the domain name is pre-filled and must be changed to the same domain

as the Citrix environment if the pre-filled value is not the same as the Citrix

environment.

6. PVS Information (Only for PVS migration)



If PVS migration is selected in step1, this panel will be shown. Otherwise this

step will be bypassed.

Input pvs server NetBIos name or FQDN as PVS source. Click “Connect” to

parse information from PVS server. Select PVS image store path and disk

which will be used to migrate. Select the target information where PVS base

image will be converted into vCenter virtual machine. We will use this virtual

machine to build the Horizon desktop template.

7. Select Migration Pool Type.

Click “Next”.

Note: for “Instant Clone”, Domain Administrator credential is a must



8. Select pool to migrate. Click the Arrow to move the selected pool to the list on

the right side. The dialog Customize Pool Name will be displayed.

Change the pool name if necessary. Follow the Horizon Naming convention

when changing the pool name.

Click “Next”.

9. Review the summary.

Click “Next” to start migration.

10. If automated pool is selected as target pool in step 7, a “Confirm Before

Continue” dialog will be displayed. The information on the dialog reminds you

to log onto the virtual machine and configure volume license for the OS.



In the case of the following snapshot, the virtual machine is

autoMCSTemplate11_69789 on ESXi server 10.117.8.50.

Click Continue after finishing configuring license.

Note: OS license is a must. You should NOT log off from the virtual machine

even after finishing configuring license.

11. Click “Exit” to complete the migration.

12. Login to the Horizon admin console to check the status of the migrated pool.



4.3. Migration from XenApp to Horizon 7

We assume that new RDSH hosts and applications have been setup and installed

with Horizon Agent. If you want to perform an in-place migration, install Horizon

Agent in the existing RDSH hosts. However, the former scenario is recommended

and the following steps are done for this scenario.

1. Log into Citrix Delivery Controller server (XenApp server for version earlier

than 7). Launch Horizon Migration Tool by double clicking

“HorizonMigrationTool.exe”

2. Select Source and Target.

Select “Applications” as source and Horizon 7 as source and “Horizon 7.2” as

target.

Click “Next”.

3. Click “Next” on Welcome page.



4. Review Citrix dumping summary.

Click “Next”.

5. Fill in Horizon Credentials:

Host name or IP, User, and Password are required.

The domain is pre-filled and must be changed to the same domain as the

Citrix environment if the pre-filled value is not the same as the Citrix

environment.



Click Next.

6. Review RDSH status.

All the RDSH hosts from both Citrix and Horizon are listed and each line in the

table represents one RDSH host.

Click Next.

In XenApp

Farm

Horizon

Agent

Status

RDS Farm Enabled

Citrix RDSH

hosts: RDSH

hosts

managed by

current

Delivery

Controller

The name of

the XenApp

farm.

If the source

is Citrix 7.x,

then the

value of the

column “In

XenApp Farm”

“available” for

in-place

migration.

Otherwise,

the value is

“Not found”

The Horizon

farm to

which the

RDSH hosts

belongs.

Whether the

RDSH host is

enabled on

Horizon.

“Y” stands for

enabled.

“N” stands

for disabled.

No value



is empty for

the Citrix

RDSH hosts

because Citrix

has changed

its

terminology.

means

Horizon

Agent is not

installed on

this server.

Horizon

RDSH hosts:

RDSH hosts

installed with

Horizon

Agent and

registered to

the Horizon

system

provided in

step 5

The name of

the XenApp

farm for in-

place

migration.

Otherwise,

the value is

“(NO)”

Must be

“Available”.

If it is not

“Available”,

fix it and re-

run or refresh

the migration

tool.

The Horizon

farm to

which the

RDSH hosts

belongs.

The same as

above.



7. Select migration mode.

“advanced mode” provides more ability of managing pools.

“easy mode” put all the Horizon RDSH hosts into one farm and migrates

everything in Citrix to this new farm. In addition, easy mode only supports in-

place migration.

8. If “Advanced Mode” is selected, the configuration page is displayed.

Select applications to migrate from the left list.



If you want to migrate to a new farm, select Migrate To A NEW FARM

from the right list, click the arrow. The dialog Configure New farm is

displayed. Select available RDS hosts to create new farm.

Change the application name if you want.

Click OK.



If you want to migrate to an existing farm, select the target farm from

the right list. The dialog Create Application On Existing Farm is displayed.

Click OK.

Click Next.

9. Select entitlement to migrate.

Click Next.



10. Review Summary

Click Start Migration



11. Migration starts.

12. Login to the Horizon Admin Console to check the status of the migrated

Published App.

4.4. Migration from XenDesktop to Horizon Cloud

1. Launch Horizon Migration Tool by double clicking “HorizonMigrationTool.exe”

2. Select Source and Target.

Select “XenDesktop” as source and “Horizon Cloud” as target.

Click Next.



3. Review the dump information.

Click Next.

4. Input Horizon 7 agent installer path and vCenter information.

Click Browse to select Horizon Agent installer.

Fill in IP address, user name and password of vCenter.

Click “Next”.

Note:



FQDN of vCenter won’t work here.

The user must have administrative privilege.

5. Input information of the domain, provide domain user and password with

Administrative privilege. The domain must be the same domain as the Citrix

server.

Click “Next”.



6. Choose desktop pool to migrate. When prompted with dialog, enter the

credential of template’s guest OS admin username and password.

Click “Next”.

7. Review the summary.

Click “Next”.



8. The migration will begin. In the process of migration, there will be two

prompts.

- In the first prompt, login machine mentioned in the prompt as domain admin, manage license, etc. Leave the user logged in when finished

- In the second prompt, login machine mentioned in the prompt, install

DaaS agent

9. After the migration finishes successfully, a desktop template image with the

configuration files is created. This image can be used to deploy desktops in

Horizon Cloud.



5. Known Issues and Limitations

5.1. XenDesktop

When you migrate to Horizon 7, an error dialog can be displayed, which

prevents you from continuing the migration process. The dialog states that

conflicts happen while installing Horizon Agent. This is because it fails to

uninstall Citrix VDA silently.

Workaround: Login to the virtual machine mentioned in the dialog and

uninstall Citrix VDA manually. Click "OK" in the popped-out dialog to continue

after uninstalling successfully.

When you migrate to Horizon Instant Clone, it might fail to create the

desktop pool in Horizon. This is because the parent desktop is not fully

powered on during the process.

Workaround: Manually create target desktop pool with the parent virtual

machine and snapshot created by Horizon Migration Tool.



5.2. XenApp

When you migrate Citrix XenApp that allows anonymous access, the target

Published App cannot allow anonymous access. This is because that

Horizon 7 does not support anonymous access.

Workaround: None

When you migrate Citrix XenApp that is disabled, the target Published

Application is enabled. This is because that Horizon 7 does not support to

disable Published Application.

Workaround: None

When you migrate XenApp with relative path configured, you are required to

provide the full path of the execution or shortcut of the application. This is

because Horizon 7 does not support relative path of Published Application.

Workaround: Configure full path for the target Published Application per the

guide on the Horizon Migration Tool.

When the Horizon Migration Tool validates the availability of the XenApp,

error can occur if the application is run on a RDS host that belongs to

another domain than the XenApp Server from which the Horizon Migration

Tool is run.

Workaround: None

6. Scaling

XenDesktop

This migration tool should only be used in small scale migration within one

domain. It is highly recommended to migrate domain by domain.



For manual desktop pool migration, the tool migrates the VMs directly and

there should be no scalability issues. It is recommended to migrate one pool

at a time.

For automated desktop pool migration, the tool only migrates the template

and creates one pool accordingly. Administrators can scale the pool manually

on Horizon admin console after the migration process.

XenApp

The supported size of farm to be migrated is measured as user/group count

per application multiplies application count. The supported size is 100000. For

example:

• 100 applications, each application has 1000 users/groups (in average)

• 1000 applications, each application has 100 users/groups

• 2000 applications, each application has 50 users/groups

A user group is counted the same as a user in this formula. For example:

An application is entitled to user User1, and a group Group1, which

contains 100 users. In the aforementioned formula, we count 2 users for this

application.

7. Logging and Troubleshooting

1. Symptom: session timeout. Workaround: go back to previous login step and

login Horizon Connection server again.

2. Symptom: Some properties cannot be found in some “Unmarshall” exception.

Workaround: this is probably caused by incompatible Horizon connection

server version. Make sure the Horizon Connection server is Horizon 7, and

the upgrade the Horizon Agent.

3. Log file location



All log files and XenApp farm information files can be found in the x2v_log

directory, which is created by the tool in the same directory as

HorizonMigrationTool.exe. The log files contain application internal log, farm

dump information, as well as all logs of migration actions.

In case of error, package the x2v_log directory and send to development team

for support.

vmware horizon migration tool user guide...this document version applies to vmware horizon migration...

Documents