Source: Troubleshooting Installation Manager Issues
This document applies to:
- Installation Manager for MetaFrame Presentation Server 3.0
- Installation Manager for MetaFrame XPe
- Installation Manager for Presentation Server 4.0
- Installation Manager for Presentation Server 4.0 x64
Summary
Installation Manager is a component of the Enterprise Edition of Presentation Server and requires Enterprise Edition licensing. This document is designed to help with troubleshooting the various components of Installation Manager. The Knowledge Center contains several documents on environment specific Installation Manager errors and issues. If this document does not resolve your issue, search the Knowledge Center using more specific keywords or call Citrix Technical Support.
Architectural Understanding
Installation Manager subsystem of IMA
ADF Installer Service and Citrix Packager
Windows Installer Service and msi files
Data store objects for Installation Manager
Network Account and File share
Enterprise Licensing required
1
PS IMA IM RegistrWindows InstallerADF InstallerFile SystemMSI ADF PS IMA IM RegistrWindows InstallerADF InstallerFile SystemMSI ADF PS IMA IM RegistrWindows InstallerADF InstallerFile SystemMSI ADF Citrix 3rd Installation Manager“Clean” Server IM Packager IM Packager records file & registry changes during installation of software, creates installable package (ADF) and updates repository information IM reads MSI file or installable package from file share and installs software, using Windows installer (for MSI files) or separate service (for ADF packages) Package delivery, schedule, and reboot options controlled via (C)MC Software PackagFile Server IM PackagAdministration Desktop Management Console MSI FileMSI FileMSI FileSFile SystemRegistrrun modify monitor PS IMA IM RegistrWindows InstallerADF InstallerFile SystemMSI ADF update
Installation Manager Files and their roles are below:
Program FilesCitrixIMPackager- files for the Packager component are located in this directory and it is also the default location for projects created using the packager.
Program FilesCitrixInstalleraginst.log – ADF package install log. This log contains events during the installation of an ADF package.
Program FilesCitrixInstallerLogs – MSI log files created by Installation Manager appear here – Jobxxxx.log. This log contains events during the installation of an MSI package.
Program FilesCitrixInstallerAgentSVC.exe – the ADF installer service which also may be seen as “Gemini” in the Event Viewer.
2
Program FilesCitrixSystem32CitrixIMASubsystemsIMsSs.dll – the subsystem of IMA for Installation Manager functionality.
Program FilesCitrixAdministrationPluginsIMSMgr.jar – the Management Console plugin for the Installation Manager node.
Mixed Farm Environments
Version of Windows Operating System
Applications are written for and installed on the operating system and not for Presentation Server. Presentation Server simply “presents” the application once it is installed on the operating system. The application must run on and be packaged for either Windows 2000 or Windows 2003. In a mixed operating system farm, separate packages will be required for each operating system. An application should always be installed and tested manually before using Installation Manager to ensure that the application installs and runs properly on the operating system.
Large Farm Environments
Network File Share
Data store considerations
IMA communication
Below is a screen shot of the Installation Manager data store objects using DSVIEW.
3
Note: Any time the Management Console is involved, the IMA data store is involved which means that standard IMA troubleshooting steps should be taken, such as restarting IMA, rebuilding the local host cache, and running the Management Console directly on the affected server as a full farm administrator.
See CTX759510 – Function of the Local Host Cache on MetaFrame XP.
CTX107800 – DSCHECK should also be used to verify the data store.
Special considerations should be made when the Citrix Farm consists of a large number of servers spread out across zones. The actual package (MSI or ADF) should sit on a network file share located on the same subnet as the target Presentation Servers. This means that each subnet or zone across a WAN link should have its own copy of the application package and each copy must be imported into the data store separately because one of the properties of a package in the data store is the location on the network share.
4
When a package is scheduled for deployment, its actual network location is read from the data store and updates of the installation are written to the data store via IMA communication.
Special considerations should be made for farms with large numbers of installation packages. Each Installation Manager package contains many properties that are written to the data store such as network location, installation, and uninstallation records and references to transforms and command line parameters. As a result, the data store can become quite large and indexing of the package objects can slow down the updates to the Management Console.
For each imported package, there is one job entry, one install entry per server, and four install log entries to the data store.
Therefore, pushing out 180 packages to 120 servers will result in about:
21,600 job entries 21,600 install entries 86,400 install log entries
IMindexfixer.exe
This utility is specifically created to recreate the Installation Manager relationships when the data store was originally from an XP Feature Release/Service Pack 2 or earlier and had been upgraded to our latest products. The utility runs over IMA so it should work independent of data store type (SQL and Oracle).
1. Backup the data store.
2. Isolate a server in the farm (with no users logged on) from where you will run the utility.
3. Do not use Installation Manager while running the utility.
4. WAIT until it finishes which may take some time. For example: a 120 server farm where Installation Manager was used extensively could take 8 hours or more.
Troubleshooting the Packager
Use the same operating system as the target server
Verify the application installs on the console
Remapped drive issues
Server Reboots
5
DLL conflicts and mismatch
Recording process
The Citrix Packager is used when a MSI package is not available for an application. The packager is designed to create an application package for older applications that do not use Windows Installer. The packager can also be used to package files or service packs. Use a machine with the same operating system as the target servers to create the package and use a clean machine that does not contain conflicting DLL versions used by the application.
The recording process writes the steps of the installation to an ADF script file (xxxxxx.wfs)
. This script contains all of the steps to install the application on the target server. Typically these steps are file copies and registry changes. However, if an application install involves creating an ODBC connection to a back end server, or requires a reboot, or needs to access the Internet, or a specific mapped network drive, these steps will be recorded into the script and need to be taken into consideration when deploying the package.
The root build location is important. This is where the package is built and the script file must be in the root folder so that it can access the files and folders of the package when the script is read during deployment.
6
Additional Troubleshooting Steps:
• Does the application’s .exe function as a “wrapper” and subsequently spawn msiexec to install the “wrapped” msi components? MSI components are not “recorded”. See CTX822151 – Attempting to Package an MSI File Results in an Incomplete Recording of the Applications Installation Routine.
• Packaging can not complete if a restart takes place during the recording. Choose to restart later if an installation prompts you to restart. CTX155395 – Do not Record Server Reboot During Application Packaging.
• The Citrix packager does not acknowledge component file names that contain special characters.
• If a folder with the hidden attribute is included in the package, the hidden attribute is not retained when the package is deployed to servers. The hidden attribute must be manually set on the folder after the package is deployed.
• Does an application like WinZip package and deploy? Compare another application to see if it is an application specific problem.
• Does a standard MSI package deploy? If WinZip failed but a MSI was successful, the problem can be isolated to the packager.
• Installation Manager 2.x Packager does not Record Every Installation File. See CTX670564 – Installation Manager 2.x Packager Does not Record Every Installation File.
• From MetaFrame XP Service Pack 4 – 16. When using packages built with InstallShield Versions 6.2.xx and 6.3.xx, the packager did not record all the actions of the package installation. This problem occurred because the process filter recorded only the actions of the install and child processes. In InstallShield Versions 6.2.xx and 6.3.xx, the installation created a service IKernel.exe and used that service to install the actual files related to the package. To resolve the problem, you need to add the value UseIKernel to the following registry key.
HKEY_LOCAL_MACHINESOFTWARECitrixIMS2.0Packager Type: DWORD Value: UseIKernel = 1
With the above value set at 1, all the actions of the package installation are recorded.
7
Troubleshooting ADDING packages in the Management Console
Network Share for packages
Network Account permissions
Adding command line parameters and transforms
• The network account used for Installation Manager installations is specified in the properties of the Installation Manager node of the Management Console.
• This account needs to have permissions on the file share where the package is stored and adequate permission to install software on all Presentation Servers; typically a domain administrator’s account is used.
• For Novell environments see CTX103634 – Novell Network Share Point and Installation Manager Inquiry.
• When adding a package to the Management Console, the Citrix administrator has the option to add a command line switch and/or specify a transform file. See CTX104051 – Error: Invalid command line arguments …when Installing MSI packages.
• Test the switches and the transform with the Windows Installer (Msiexec.exe) Information on MSI switches available from the following Microsoft website http://support.microsoft.com/default.aspx?scid=kb;en-us;314881
• Error applying transforms. Verify that the specified transform paths are valid. CTX104225 – Error: Error applying transforms. Verify that the specified transform paths are valid.
8
Troubleshooting Failed Installations
Isolate to MSI or ADF deployment problem
Network Topology
Data store and IMA
Network share permissions
Once the package is imported into the data store, you can push it out to target servers with right-click > Install. When a problem occurs here, first determine if other packages install. Do all MSI and ADF packages fail?
• From the Management Console, go to the Job tab, to see the status. Click the Job Details button to check the log file generated.
• Check the Windows Event Log:
o WFS package errors under the source Gemini Installer
o MSI package errors under the source MsiInstaller
• Installation Manager creates install log files that appear in the following folder, depending on the type of package. Installation Manager creates install log files that appear in the following folders, depending on the type of package:
o MSI packages. MSI log files appear in:
Program FilesCitrixInstallerLogsJobxxxx.log
9
o ADF packages. ADF package install logs appear in:
Program FilesCitrixInstalleraginst.log
ADF Specific Package Deployment Issues
When an ADF package does not install, it may be necessary to edit the ADF script file (xxxxx.wfs). For more information see CTX9293 – Installation Script Reference.
The script defines the target directory and other information that may not be interpreted on the target servers correctly. If you edit the script, you may need to increment the version=2 number under the [Main] section.
Installation Manager Does Not Automatically Recognize Changes To the Version Field in WFS Files CTX105157 – Installation Manager Does Not Automatically Recognize Changes To the Version Field in WFS Files
Error: Failed to convert to a short path …when installing an ADF package CTX105751 – Error: Failed to convert to a short path …when installing an ADF package
10
ADF installation through Installation Manager hangs with Job Status of Pending CTX104013 – ADF installation through Installation Manager hangs with Job Status of Pending
Installation Manager and Application Isolation Environments with Presentation Server 4.0
Isolate to Installation Manager or AIE deployment problem
Test 1: Deploy package directly to server
Test 2: Install application directly to AIE
With Presentation Server 4.0, an Installation Manager package can be installed into an Application Isolation Environment (AIE). If problems occur, test the application deployment first directly to the server without using the AIE. Also install the application directly into the AIE to see if the problem is with the Installation Manager deployment or the AIE itself.
For more information about Application Isolation Environments see CTX106868 – Application Isolation Environments Explained.
In an AIE, uninstalling isolated applications using Installation Manager may not remove all files. A component or file is open during uninstall. The files, usually zero-byte, are deleted file markers created by the isolation environments to track deleted files. See CTX106598 – Uninstalling Isolated Applications Using Installation Manager May Leave Files Behind in an Isolation Environment After Completion.
More Information
The Advanced Concepts Guide for Presentation Servers contain important and detailed information about Installation Manager.
MetaFrame Presentation Server 3.0 – CTX104144 – Advanced Concepts Guide MetaFrame Presentation Server for Windows Version 3.0
Citrix Presentation Server 4.0 – CTX107059 – Advanced Concepts Guide
Installation Manager Hotfixes File version, date and timestamp
Hotfix Readme
11
Installation Manager hotfixes are usually released with the Hotfix Rollup Packs for Presentation Server. The readme for each rollup will specify the issues that were fixed. See the Hotfix Rollup Schedule for more information. CTX107180 – Hotfix Rollup Pack Schedule.
12
