Installation Manager Administrator s Guide

Installation Manager Administrator s Guide Citrix XenApp 5.0 for Microsoft Windows Server 2008

Copyright and Trademark Notice Use of the product documented in this guide is subject to your prior acceptance of the End User License Agreement. A printable copy of the End User License Agreement is included with the installation media. Information in this document is subject to change without notice. Companies, names, and data used in examples herein are fictitious unless otherwise noted. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Citrix Systems, Inc. 2003-2008 Citrix Systems, Inc. All rights reserved. Citrix and Citrix XenApp are registered trademarks of Citrix Systems, Inc. in the United States and other countries. RSA Encryption 1996-1997 RSA Security Inc., All Rights Reserved. FLEXnet Operations and FLEXnet Publisher are trademarks and/or registered trademarks of Acresso Software Inc. and/or InstallShield Co. Inc Trademark Acknowledgements Microsoft, Windows, Windows PowerShell, Windows Server, Windows Vista, Visual Studio,.NET, and Active Directory are trademarks or registered trademarks of Microsoft Corporation in the U.S. and/or other countries. All other trademarks and registered trademarks are the property of their respective owners. Document Code: November 17, 2008 (AO)

Contents 1 Introducing Installation Manager................................................. 5 Finding Documentation.......................................................5 Documentation Conventions................................................6 Getting Support and Training...............................................6 Introducing Installation Manager...............................................7 Installation Manager Components............................................8 Getting Started Quickly With Installation Manager.................................9 2 Installing Installation Manager.................................................. 11 System Requirements.......................................................11 Requirements for the Task Management Computer.............................11 Requirements for the Target Servers.........................................12 Requirements for the File Share............................................12 Account and Permission Requirements.........................................12 Installing Installation Manager................................................13 To install Installation Manager.............................................14 Installing the Utilities Package.............................................14 Mixed Farm Considerations..................................................14 Uninstalling Installation Manager..............................................15 To uninstall Installation Manager...........................................15 To uninstall the Utilities Package...........................................15 Uninstalling the Utilities Package Using Installation Manager....................15 3 Deploying Tasks Using Installation Manager...................................... 17 Launching Installation Manager...............................................17 To launch Installation Manager.............................................17 The Installation Manager Window..........................................18 Deploying MSI and MSP Packages............................................19 To deploy an MSI or MSP package.........................................19 Deploying Task Scheduler Files...............................................20

4 Installation Manager Administrator s Guide To deploy a Task Scheduler file............................................20 Associating Published Applications with Servers.................................21 To associate a published application with a server..............................21 Deploying Command-line Tasks..............................................21 To deploy a command-line task............................................21 Rescheduling Tasks.........................................................22 To reschedule a task......................................................22 Removing Tasks...........................................................22 To remove a task from a server.............................................23 4 Using the PowerShell Cmdlets.................................................. 25 Importing the Cmdlets.......................................................25 To import the cmdlets....................................................25 To import cmdlets automatically............................................26 Listing XenApp Servers.....................................................26 Get-IMServer...........................................................26 Scheduling Tasks in Targets..................................................26 Create-IMMSITask......................................................27 Create-IMTask..........................................................29 Create-IMCMDTask.....................................................30 Getting Success or Failure Information About Tasks..............................31 Get-IMTask............................................................31 Removing Scheduled Tasks from Targets.......................................32 Remove-IMTask........................................................32 5 Error Messages............................................................... 33 IMAdmin Cmdlet Error Messages.............................................33 IMUtilities Cmdlet Error Messages............................................36

1 Introducing Installation Manager Welcome to Installation Manager for Citrix XenApp 5.0 for Windows 2008, Enterprise and Platinum Editions. This guide is intended for Citrix administrators responsible for using Installation Manager to deploy software components, such as hotfixes, service packs, and MSI packages on servers. It assumes knowledge of both Windows and XenApp administration. This topic introduces Installation Manager and its key components and describes the steps required to install and set up a typical Installation Manager environment. Finding Documentation For a list of known issues in this release, see the product readme. For more information about Citrix XenApp 5.0, please refer to Welcome to Citrix XenApp (Read_Me_First.html), which is included on the XenApp 5.0 for Windows 2008 installation media. This contains links to documents that will help get you started, and to the most up-to-date product documentation for XenApp and its components, plus related technologies. The Citrix Knowledge Center Web site, http://support.citrix.com, contains links to all product documentation, organized by product. Select the product you want to access and then click the Documentation tab from the product information page.

6 Installation Manager Administrator s Guide Documentation Conventions For consistency, Windows Vista and Windows Server 2008 (64-bit) terminology is used throughout the documentation set; for example, Documents rather than My Documents and Computer rather than My Computer are used. Citrix XenApp documentation uses the following typographic conventions. Convention Boldface Italics Monospace {braces} Meaning Commands, names of interface items such as text boxes, option buttons, and user input. Placeholders for information you provide. For example, filename means you type the actual name of a file. Italics are also used for new terms and titles of books. Text displayed in a text file. In a command, a series of items, one of which is required. For example, {yes no } means you must type yes or no. Do not type the braces themselves. [ brackets ] In a command, optional items. For example, [/ping] means you can type /ping with the command. Do not type the brackets themselves. (vertical bar) In a command, a separator between items in braces or brackets. For example, { /hold /release /delete } means you must type /hold or /release or /delete.... (ellipsis) The previous item(s) in the command can be repeated. For example, /route:devicename[, ] means you can type additional devicenames separated by commas. Getting Support and Training Citrix provides an online user forum for technical support. This forum can be accessed at http://support.citrix.com/xenappforum/. The Web site includes links to downloads, the Citrix Knowledge Center, Citrix Consulting Services, and other useful support pages. The Citrix Knowledge Center (http://support.citrix.com) offers a variety of technical support services, tools, and developer resources. Information about Citrix training is available at http://www.citrix.com/edu/.

Introducing Installation Manager 1 Introducing Installation Manager 7 Installation Manager is a feature of XenApp, Enterprise and Platinum Editions, that allows you to rapidly deploy software to servers from a central location. For example, you can use Installation Manager to deploy patches to Citrix servers. This version of Installation Manager (that ships with XenApp 5.0) is based on Windows Task Scheduler 2.0 and Microsoft PowerShell 1.0 technologies. Using Installation Manager, you can distribute applications, service packs, software patches, and simple command-line script tasks to servers attended or unattended using any server running Windows Vista or Server 2008 on the network. Installation Manager can also distribute XML files generated by Windows Task Scheduler. Note: Citrix recommends using the application streaming feature to deliver applications in your XenApp environment (Enterprise and Platinum Editions only). For more information about application streaming, see the Application Streaming Guide. You can use Installation Manager to automate server restarts immediately after an application installs on a target server, making the application and the server ready for use. Installation Manager can notify users of impending operations, such as a server restart. A Microsoft Management Console (MMC) snap-in provides an easy-to-use graphical user interface to Installation Manager. For administrators familiar with Microsoft PowerShell, you can use Installation Manager s custom cmdlets in the PowerShell environment. Using the MMC or the PowerShell console, you can view the status of a particular task to see whether or not it ran successfully on the target servers. Installation Manager can retrieve the event log and result codes for any operations that fail and store results in XML format.

8 Installation Manager Administrator s Guide Installation Manager Components Installation Manager involves the interaction of the following components: Task management computer. This is a computer with the MMC installed. This computer is used to manage and schedule the tasks you deploy using Installation Manager. It need not be a separate computer; for example, you can use one of the target servers as the task management computer. File share. A shared folder is used to transfer task files that are to be deployed using Installation Manager to target servers, and to store cache files containing previously scheduled tasks and results. The file share can be on any Windows server; for example, on the task management computer. You can also have multiple file shares; for example, one in the US and one in the UK to speed up regional deployments. Target server(s). The server or servers on which tasks are to be deployed. The target server must be running Windows Server 2008 or be a XenApp server. Diagram showing the main Installation Manager components.

1 Introducing Installation Manager 9 Getting Started Quickly With Installation Manager This topic summarizes the steps required to install and set up a typical Installation Manager environment. 1. Identify the server(s) that will act as the task management computer(s) in your environment and install the Installation Manager Administration Package XA50_IM_ADMIN.MSI on these. 2. Configure a file share that will be used to transfer files to target servers and store execution history. 3. Configure the appropriate user access rights on the file share and target servers. 4. If you want to use Installation Manager to deploy MSI or MSP packages, install the Utilities package XA50_IM_UTIL.MSI on the appropriate target servers. 5. Use Installation Manager to deploy applications and software components on target servers. The following topics explain these steps in more detail.

10 Installation Manager Administrator s Guide

2 Installing Installation Manager This topic provides system requirement information, describes the permissions you need to use Installation Manager, and explains how to install Installation Manager. It also discusses mixed farm considerations. System Requirements Installation Manager consists of two packages: 1. Administration package. This contains the core Installation Manager functionality. You install this package on the task management computer. 2. Utilities package. This contains PowerShell cmdlets required for MSI or MSP installation only. You install this package on appropriate target servers. If the Utilities package is not installed, MSI or MSP installation will fail on those target servers. Requirements for the Task Management Computer The task management computer is used to manage and schedule the tasks you deploy using Installation Manager. It need not be a separate computer; for example, you can use one of the target servers as the task management computer. The task management computer must have: Windows Vista or Windows Server 2008 Microsoft Visual Studio.NET Framework 3.5 Microsoft PowerShell 1.0 for Windows Vista or Windows Server 2008 Microsoft Management Console 3.0 Citrix XenApp to list (enumerate) XenApp servers in the MMC or to use the Get-IMServer cmdlet, you must install the Citrix Access Management Console. Also, if XenApp is not installed, the Publish Application action is unavailable (see Associating Published Applications with Servers on

12 Installation Manager Administrator s Guide page 21) and you will be unable to deploy existing published applications to target servers. Requirements for the Target Servers Target servers are the servers on which applications and software components are to be deployed. These servers must have Windows Server 2008 installed. If you intend using Installation Manager to install MSI or MSP packages you must install the Utilities package on these target servers. If the Utilities package is not installed, MSI or MSP installation will fail on these target servers. The Utilities package requires the following on the target servers: Windows Server 2008 Microsoft Visual Studio.NET Framework 3.5 Microsoft PowerShell 1.0 for Windows Vista or Windows Server 2008 Citrix XenApp 5.0 for Microsoft Windows Server 2008 (optional only). Requirements for the File Share A shared folder is used to transfer task files that are to be deployed using Installation Manager to target servers, and to store cache files containing previously scheduled tasks and results. The file share can be on any Windows computer (Windows 2003, 2008, or Vista); for example, you can use the task management computer as the file share. Important: You must have the appropriate permissions to allow you to access the file share. See Account and Permission Requirements on page 12 for more information. Account and Permission Requirements This topic describes the user accounts and permissions required to create and schedule tasks on target servers using Installation Manager. Installation Manager uses Windows Task Scheduler 2.0 to schedule operations on target servers. It uses implicit authentication for remote access to the Task Scheduler API. Administrators creating Installation Manager tasks must have full control on the Installation Manager file share and belong to each target server s Local Administrator group. The following accounts and permissions are required: Create an Active Directory group (for example, named Installation Manager Administrators ).

2 Installing Installation Manager 13 Add the Active Directory group (for example, the Installation Manager Administrators group) as a member of each target server s Local Administrator, Distributed COM Users, and Event Log Readers local groups. Users of Windows Server 2008 can do this by creating a Group Policy Preference policy in Active Directory in order to combine these groups and simplify the permissions process. Assign full control rights to the Installation Manager Administrators group for the file share and folder. The group requires rights to manipulate access control lists (ACLs) on the share folder. Assign the share permissions by selecting the file and clicking Properties > Sharing > Advanced and setting the required options in the Permissions tab. Set the folder permissions by selecting the folder and clicking Properties > Security > Advanced > Edit Diagram summarizing the accounts and permissions required. Installing Installation Manager This topic tells you how to install Installation Manager on the task management computer.

14 Installation Manager Administrator s Guide To install Installation Manager To install the Administration Package on the computer that you want to use as the task management computer: 1. Log all users off the task management computer and close all applications, including the console. 2. Double-click the Administration Package (XA50_IM_ADMIN.MSI or XA50_IM_ADMIN_x64.MSI) on the task management computer. 3. When the Setup wizard starts, follow the instructions on-screen. Installing the Utilities Package If you want to use Installation Manager to install MSI or MSP packages you must install the Utilities package on the appropriate target servers. If the Utilities package is not installed, MSI or MSP installation will fail on these target servers. The Utilities package is not required for distributing Task Scheduler files or command-line tasks. When you install the Utilities package, this enables four pre-existing Windows firewall rules (previously disabled by default). It enables these rules to allow access to the Task Scheduler and Event Log Management services using DCOM. The enabled rules are: Remote Scheduled Task Management (RPC) Remote Scheduled Task Management (RPC-EPMAP) Remote Event Log Management (RPC) Remote Event Log Management (RPC-EPMAP) To install the Utilities Package 1. Log all users off the target server and close all applications, including the console. 2. Double-click the Utilities Package (XA50_IM_UTIL.MSI or XA50_IM_UTIL_x64.MSI) on the target server. 3. When the Setup wizard starts, follow the instructions on-screen. Mixed Farm Considerations Read this topic only if you have a mixture of servers running XenApp 5.0 and Presentation Server 4.5 with Feature Pack 1 in the same farm. If the farm contains only servers running XenApp 5.0, you do not need to read this information.

2 Installing Installation Manager 15 If you have a mixture of servers running XenApp 5.0 and Presentation Server 4.5 with Feature Pack 1 in the same farm, you can use this version of Installation Manager (that which ships with XenApp 5.0) only to deploy applications and software components on servers running Windows Server 2008. Task Scheduler 2.0 is not supported on Windows Server 2003 so, to deploy software components to these servers, use the previous version of Installation Manager that is installed on a server running Presentation Server 4.5 with Feature Pack 1. To do this, use the Presentation Server 4.5 versions of the Access Management Console and the Presentation Server Console. Uninstalling Installation Manager This topic tells you how to uninstall Installation Manager on the task management computer and the Utilities package, if you installed it, on the target servers. To uninstall Installation Manager 1. Log all users off the task management computer and close all applications, including the console. 2. Using Add or Remove Programs from the Control Panel, remove the Administration Package (XA50_IM_ADMIN.MSI or XA50_IM_ADMIN_x64.MSI) from the task management computer. To uninstall the Utilities Package 1. Log all users off the target server and close all applications, including the console. 2. Using Add or Remove Programs from the Control Panel, remove the Utilities Package (XA50_IM_UTIL.MSI or XA50_IM_UTIL_x64.MSI) on the target server. Uninstalling the Utilities Package Using Installation Manager You can use Installation Manager to uninstall the Utilities package quickly on multiple target servers. To do this, schedule a command-line task to uninstall the Utilities package (XA50_IM_UTIL.MSI or XA50_IM_UTIL_x64.MSI) from all the target servers. For more information about scheduling command-line tasks, see Deploying Command-line Tasks on page 21.

16 Installation Manager Administrator s Guide

3 Deploying Tasks Using Installation Manager This topic describes how to launch Installation Manager and use the Microsoft Management Console (MMC) to deploy applications and software components on target servers. It explains how to schedule the installation of an MSI or MSP package, application, Task Scheduler file, or a command-line task. It also explains how to reschedule and remove tasks. Launching Installation Manager This topic describes how to launch Installation Manager and use the Installation Manager window in the MMC. To launch Installation Manager 1. From the MMC, click File > Add/Remove Snap-in and add Installation Manager. 2. When prompted for the Installation Manager shared folder, either type the path to this or click Browse and navigate to it.

18 Installation Manager Administrator s Guide The Installation Manager Window The Installation Manager window has the following panes: The left pane displays the console tree. The top-middle pane displays tasks previously created using Installation Manager. This information is stored in the file share as IMTask.xml. The center-middle pane displays the results on each target server of the task selected in the pane above. This information is stored in sub-directories of the shared folder as ImTaskResults.xml. Click Refresh in the Actions pane to display the latest information from the target servers; the results do not refresh automatically. The bottom-middle pane displays the cmdlet equivalent of any action selected from the Actions pane. For example, selecting a task called InstallApp from the list in the top-middle pane and clicking Refresh displays Get-IMTask -Name InstallApp -Targets srvr2 -Log \\im\installapp\imtaskresult.xml The Actions pane displays the commands available in Installation Manager, such as Distribute Windows Task Scheduler file and Refresh.

Deploying MSI and MSP Packages 3 Deploying Tasks Using Installation Manager 19 This topic describes how to use Installation Manager to schedule the installation of an MSI or MSP package on target servers.you can also specify an MST (transform) file to change parameters in the MSI package. Note: To use Installation Manager to install MSI or MSP packages you must install the Utilities package on the appropriate target servers. If the Utilities package is not installed, MSI or MSP installation will fail on these target servers. To deploy an MSI or MSP package 1. From the Actions pane, click Schedule MSI package distribution. The Schedule MSI Package Distribution dialog box appears. 2. Enter the name of the task in Task name. This name must be unique or the task will fail, unless you click Advanced and select Overwrite existing task definition in the Advanced Options dialog box. If it is selected, the task will be updated with the new definition. 3. Specify the servers on which you want to install this package in Target list. Click Servers to select from Active Directory or XenApp server folders, or specify a comma-delimited list of servers by DNS name. 4. In MSI/MSP file path, enter the location of the MSI or MSP package to be scheduled for installation. To include a transform file, specify its location in MST list. To make the MSI, MSP, and MST files available from a single shared folder accessible by all target servers, click Advanced and specify a Shared folder in the Advanced Options dialog box. Any MSI, MSP and MST files selected will be copied to this folder, if not already present. Installation Manager also configures the path s access control list to include all Active Directory accounts with read permissions to the share. 5. Enter the date and time at which to start the installation in Schedule date and time or specify Now to trigger the task immediately. 6. To determine how users sessions running on the target servers behave during and after the installation process, use Session Options. Disable session logon during installation process. Select to prevent users from logging on during the installation. Logoff existing sessions. Select to force users to log off the server before executing the installation.

20 Installation Manager Administrator s Guide Reboot target after successful installation. Select to restart the server immediately after installation. To allow users time to save their work, specify how long to wait before users are logged off or the server restarts. You can also specify a message to send to all logged-on users to prompt them to save their work and logoff. 7. If Installation Manager fails to schedule the task on a server (for example, a server is off-line), it will try to reschedule the task. To specify how long Installation Manager should retry for, and the time interval between attempts, select Advanced and enter the times in the Retry Interval options. 8. Click OK to deploy the packages on the target servers. Deploying Task Scheduler Files This topic describes how to distribute a Task Scheduler file on target servers; it assumes knowledge of Task Scheduler. Use the Task Scheduler MMC console to create the Task Scheduler file. For information on using Task Scheduler, see your Microsoft documentation. Note: Installation Manager passes the Task Scheduler file directly to Windows Task Scheduler; it is not transferred using the file share. To deploy a Task Scheduler file 1. From the Actions pane, click Distribute Windows Task Scheduler file. The Distribute Windows Task Scheduler file dialog box appears. 2. Enter the name of the task in Task name. This name must be unique or the task will fail, unless you click Advanced and select Overwrite existing task definition in the Advanced Options dialog box. If it is selected, the task will be updated with the new definition. 3. Enter the location of the Task Scheduler file in Task XML file. 4. Specify the target servers on which you want to install this task in Target list. Click Servers to select from Active Directory or XenApp server folders, or specify a comma-delimited list of servers by DNS name. 5. If Installation Manager fails to schedule the task on a server (for example, a server is off-line), it will try to reschedule the task. To specify how long Installation Manager should retry for, and the time interval between

3 Deploying Tasks Using Installation Manager 21 attempts, select Advanced and enter the times in the Retry Interval options. 6. Click OK to deploy the tasks on the target servers. Associating Published Applications with Servers This topic describes how to add XenApp servers on which a certain application has been installed by Installation Manager to a preexisting published application object. This results in XenApp including these servers when load balancing session requests to that application. You achieve this by choosing an existing task that was used to install an application, and then associating that application with those servers for which the task was successful. To associate a published application with a server 1. Select a task from the list in the top-middle pane. 2. From the Actions pane, click Publish Application. 3. Click Browse. 4. Enter the name of the XenApp server from where Installation Manager will retrieve the list of published applications. 5. Click Go and select the published application from the list. 6. Click OK. Deploying Command-line Tasks This topic describes how to schedule the distribution of a command-line task on target servers. To deploy a command-line task 1. From the Actions pane, click Schedule command-line task. The Schedule command-line task dialog box appears. 2. Enter the name of the task in Task name. This name must be unique or the task will fail, unless you click Advanced and select Overwrite existing task definition in the Advanced Options dialog box. If it is selected, the task will be updated with the new definition. 3. Specify the target servers on which you want to install this command-line task in Target list. Click Servers to select from Active Directory or

22 Installation Manager Administrator s Guide XenApp server folders, or specify a comma-delimited list of servers by DNS name. 4. Enter the command, or location of the command, that you want to execute on the target servers. If you enter a path, the command must be available to execute on the target servers at the given path or it must be available in the profile "PATH". To make the command available from a single shared folder accessible by all target servers, click Advanced and specify a Shared folder in the Advanced Options dialog box. 5. Enter the date and time at which to execute the command in Schedule date and time or specify Now to trigger the task immediately. 6. If Installation Manager fails to schedule the task on a server (for example, a server is off-line), it will try to reschedule the task. To specify how long Installation Manager should retry for, and the time interval between attempts, select Advanced and enter the times in the Retry Interval options. 7. Click OK to deploy the command on the target servers. An exit code of zero indicates the operation completed successfully; a non-zero exit code indicates that it failed. Rescheduling Tasks You can reschedule a task to deploy at a later date. Rescheduling creates a copy of the selected task, allowing you to change its parameters. You can reschedule both command-line tasks and MSI/MSP package deployment. To reschedule a task 1. Select a task from the list in the top-middle pane. 2. From the Actions pane, click Reschedule. The Reschedule CMD Task or Reschedule MSI Task dialog box appears, depending on the task selected. 3. Update the task with any changes you wish to make, including when you want to run the task in Schedule date and time. For more information about each field, see Deploying MSI and MSP Packages on page 19 and Deploying Command-line Tasks on page 21. 4. Click OK. Removing Tasks You can remove the Task Scheduler entry for all target servers identified in a task. (This does not remove the task from the list in the MMC.)

3 Deploying Tasks Using Installation Manager 23 Note: If you remove a task that has already executed, this removes only its Task Scheduler entry; it does not undo the installation or deployment of files. To remove a task from a server 1. Select a task from the list in the top-middle pane. 2. From the Actions pane, click Remove.

24 Installation Manager Administrator s Guide

4 Using the PowerShell Cmdlets This topic describes the Installation Manager PowerShell cmdlets that you can import and run from within the Windows PowerShell 1.0 console. Read this topic only if you are familiar with Windows PowerShell. The following cmdlets are available: Get-IMServer lists servers in a farm Create-IMMSITask schedules an installation package Create-IMTask distributes a Task Scheduler file Create-IMCMDTask schedules a command-line task Get-IMTask shows task status information Remove-IMTask removes a task Note: The PowerShell command line is not case-sensitive; you can type cmdlets in lowercase, uppercase or a mixture of both. However, to make them easier to read, they appear in this topic in mixed case. For example, Get-IMServer and get-imserver is the same command. Importing the Cmdlets This topic explains how to import the Installation Manager cmdlets into the Windows PowerShell environment. You can import the cmdlets by adding the IMAdmin Windows PowerShell snapin (PSSnapIn) each time you start a PowerShell console, or by adding lines to the PowerShell environment profile to import the cmdlets automatically. To import the cmdlets In the Windows PowerShell console, type: Add -PSSnapIn IMAdmin

26 Installation Manager Administrator s Guide To import cmdlets automatically You can import the Installation Manager cmdlets automatically to the PowerShell environment by adding a line to profile.ps1 of the PowerShell environment profile. To import the Installation Manager cmdlets, add asnp IMAdmin. Listing XenApp Servers Get-IMServer Use this cmdlet to list (enumerate) the servers available in a specific XenApp farm. Important: To use the Get-IMServer cmdlet, you must install the Citrix Access Management Console on the task management computer. Usage Get-IMServer [-farm <addr>] [-folder <folder-path>] Parameter farm folder Description IP address or DNS name of the MFCOM farm object. If not specified, the local server is used. Path to the server folder in the target farm (in the format: \folder1\folder2). Example In the Windows PowerShell console, type: Get-IMServer -farm XenAppFarmIN -folder Servers\TargetFolder This returns, for example: FarmName IPAddress ServerName Location XenAppFarm Scheduling Tasks in Targets 123.123.0.1 XenAppSrv1 Servers/TargetFolder This topic describes how to schedule tasks on target servers using the cmdlets, such as the installation of an MSI, the distribution of a Task Scheduler file, or a command-line task.

4 Using the PowerShell Cmdlets 27 Create-IMMSITask Use this cmdlet to schedule the installation of an MSI or MSP package on target servers. Modifying Installation Defaults Installation Manager runs the installation of MSI or MSP packages without interaction with the console, using the defaults supplied by the package. However, for packages that do not supply defaults or to change the default values, you can either: Specify an MST file. An MST (transform) file consists of a collection of changes that are applied to an installation. Or Perform an administrative install. You run the MSI in administrative install mode, using msiexec /a on any computer. Complete the installation wizard as normal but instead of installing the software, generate another.msi package as a recording of the installation decisions. The resulting.msi can then be installed silently on other computers. Usage Create-IMMSITask -name <task-name> -msi <unc-path> -targets <target list> [-mst <mst-list-unc-path>] -schedule <date/time now> [-logoffsessions] [- disablelogon] [-reboot] [-timeout <minutes>] [-message <message>] [-update] [-prepareunc <unc-path>] [-log <xml path>] [-retrytime<seconds>][- retryinterval <seconds>] [-whatif] Parameter name msi targets mst schedule Description The unique name of the task. The path to the installation package you want to install, in UNC format. The path you specify must be accessible by all specified target servers. The command checks if this file exists; if it does not, an error is displayed. The target servers on which you want to install this package. Specify either a comma-delimited list of individual servers by DNS name or an object containing Name attributes (as returned by the Get- IMServer command). An optional list of paths to MSI transform files, in UNC format. The command checks if this file exists; if it does not, an error is displayed. The files must be accessible by all specified target servers. The date and time the installation task will run. Either specify a date in the format: DD/MM/YYYY and the time in 24-hour format: HH:MM:SS, enclosed in either single or double quotes, or specify now to execute the operation immediately.

28 Installation Manager Administrator s Guide Parameter logoffsessions disablelogon reboot message timeout update prepareunc log retrytime retryinterval whatif Description Disconnects all sessions before the installation process begins. You can use the message and timeout parameters to prompt users to save their work and log off. Disables logons to the target server during the installation process. Forces a server restart after the package is successfully installed. Use in conjunction with the message and timeout parameters. Sends a message to all connected sessions. Use this option in conjunction with the timeout parameter. The number of minutes connected sessions have until a server restart occurs. Use this option in conjunction with the message parameter. Overwrites any existing task of the same name. If this option is not specified and another task of the same name exists, this task will fail. Specifies a shared folder, in UNC format, that Installation Manager can use to transfer files to target servers. Installation Manager automatically transfers the files to this folder and updates the folder s access control list to ensure all servers have read access to it. You must have sufficient rights to set the UNC permissions. The path to a file or XML object where the success or failure of the install on each target server is logged. In the event that a target server cannot be contacted, specifies how long, in seconds, Installation Manager should continue retrying the installation task. Specifies how frequently, in seconds, the installation task should be retried during the period specified in retrytime. Validates the parameters specified and returns either success or failure; the cmdlet will not execute if whatif is specified.

4 Using the PowerShell Cmdlets 29 Example In the Windows PowerShell console, type the following: Create-IMMSITask -name Installmyapp -targets XAWRK1,XAWRK2,XAWRK3 -msi c:\localfolder\myapp.msi -mst c:\localfolder\myapp_silent.mst -schedule 26/09/2008 23:50:00 -prepareunc \\fileserver\im - retrytime 60 -retryinterval 10 -message Please save your work and logoff. Server will reboot for maintenance. -timeout 10 - logoffsessions -reboot Create-IMTask Use this cmdlet to distribute a Task Scheduler file on target servers. Use the Task Scheduler MMC console to create the file. Usage Create-IMTask -name <task-name> -targets <target list> -task <xml path> [-update] [-retrytime<seconds>][-retryinterval <seconds>] [-log <xml path>] [-whatif] Parameter name task targets update retrytime retryinterval log whatif Description A unique name for the task. The path to the XML file or PowerShell XML object you want to distribute. The XML schema is as per Task Scheduler 2.0 specifications. The target servers on which you want to distribute the file. Specify either a comma-delimited list of individual servers by DNS name or an object containing Name attributes (as returned by the Get-IMServer command). Overwrites any existing task definitions of the same name. If this option is not specified and another task of the same name exists, this task will fail. In the event that a target server cannot be contacted, specifies how long, in seconds, Installation Manager should continue retrying the task. Specify how frequently, in seconds, the task should be retried during the period specified in retrytime. The path to a file or XML object where the success/failure status of each target server is logged. Validates the parameters specified and returns either success or failure; the cmdlet will not execute if whatif is specified. Example You can use the Create-IMTask cmdlet to distribute a Windows Task Scheduler file that runs a backup script every evening. For example: 1. Open Task Scheduler, found in Administrative Tools.

30 Installation Manager Administrator s Guide 2. Select Action > Create Task. Use the Create Task dialog box to define the task you want to distribute. 3. Select the new task from the Task Scheduler Library, then choose Action > Export. 4. Save the Task Scheduler file in Installation Manager s shared folder. 5. In the Windows PowerShell console type the following: Create-IMTask -name Backuptask -targets XAWRK1,XAWRK2,XAWRK3 -task C:\task.xml -update -retrytime 60 -retryinterval 10 -log C:\log.xml Create-IMCMDTask Use this cmdlet to schedule the distribution of a command-line task on target servers. Usage Create-IMCMDTask -name <task-name> -command <command > -targets <target list> -schedule <date/time now> [-update] [-prepareunc <unc-path>] [-log <xml path>] [-retrytime<seconds>][-retryinterval <seconds>] [-whatif] Parameter name command targets schedule update prepareunc retrytime retryinterval Description A unique name for the task. The command-line operation to execute on target servers. The target servers on which you want to distribute the file. Specify either a comma-delimited list of individual servers by DNS name or an object containing Name attributes (as returned by the Get-IMServer command). The date and time the task will run. Either specify a date in the format: DD/MM/YYYY and the time in 24-hour format: HH:MM:SS, enclosed in either single or double quotes, or specify now to execute the operation immediately. Overwrites any existing task definitions of the same name. If this option is not specified and another task of the same name exists, this task will fail. Specifies a shared folder, in UNC format, that Installation Manager can use to transfer files to target servers. You must copy the files to this folder. Installation Manager then updates the access control l ist of the folder to ensure all servers have read access to it. You must have sufficient rights to set the UNC permissions. In the event that a target server cannot be contacted, specifies how long, in seconds, Installation Manager should continue retrying the task. Specify how frequently, in seconds, the task should be retried during the period specified in retrytime.

4 Using the PowerShell Cmdlets 31 Parameter log whatif Description The path to a file or XML object where the success/failure status of each target server is logged. Validates the parameters specified and returns either success or failure; the cmdlet will not execute if whatif is specified. Example You can use the Create-IMCMDTask cmdlet to run a command to install an application. For example: In the Windows PowerShell console, type the following: Create-IMCMDTask -name Installnotepad -command notepad.exe -targets XAWRK1,XAWRK2,XAWRK3 -update -retrytime 60 -retryinterval 10 -log C:\log.xml Getting Success or Failure Information About Tasks This topic describes how to obtain success or failure status information about scheduled tasks. The information is displayed in the PowerShell console, or you can use the log parameter to store the results in XML-format. Get-IMTask Use this cmdlet to obtain information about the status of a scheduled task on the target servers. Usage Get-IMTask -targets <targetlist> [-name <task-name>] [-fromdate <datetime>] [-todate <datetime>] [-log <xml path>]>] Parameter targets name fromdate todate log Description The target servers on which you want to obtain status information. Specify either a comma-delimited list of individual servers by DNS name or an object containing Name attributes (as returned by the Get- IMServer command). The name of the task. The date from which you want status information. The date to which you want status information. The XML path of the log file that contains the status information.

32 Installation Manager Administrator s Guide Example In the Windows PowerShell console, type: Get-IMTask -targets XAWRK1,XAWRK2 -name Installnotepad The console returns information about whether the task was successful or not, together with any messages and, if appropriate, error ids. Removing Scheduled Tasks from Targets This topic describes how to remove a scheduled task from a target server. Remove-IMTask Use this cmdlet to remove a particular task scheduled on target servers. Usage Remove-IMTask -targets <targetlist> -name <task-name> [-retrytime<seconds>][-retryinterval <seconds>][-log <xml path>] Parameter targets name retrytime retryinterval log Description The target servers on which you want to remove a task. Specify either a comma-delimited list of individual servers by DNS name or an object containing Name attributes (as returned by the Get-IMServer command). The name of the task you want to remove. In the event that a target server cannot be contacted, specifies how long, in seconds, Installation Manager should continue retrying the task. Specify how frequently, in seconds, the task should be retried during the period specified in -retrytime. The path to a file or XML object where the success/failure status of each target server is logged. Example In the Windows PowerShell console, type: Remove-IMTask -targets XAWRK1,XAWRK2 -name Installnotepad -retrytime 60 -retryinterval 10 The console returns information about whether the task was removed successfully or not, together with any messages and, if appropriate, error ids.

5 Error Messages This topic lists the errors that Installation Manager may report and their causes. IMAdmin Cmdlet Error Messages Error No Error String Trigger or Condition 0 SUCCESS The task has successfully run. -1 SCHEDULED The task is scheduled in the Task Scheduler. 1 FAILURE The task failed to register or execute. -100 A connection to the server could not be established. -101 Invalid farm argument. Specify a valid server address. 103 This Citrix XenApp PowerShell snapin contains cmdlets used to perform remote management operations in your XenApp environments. -105 XenApp SDK is not installed or Check DCOM Settings -106 The folder specified {0} does not exist. Specify a valid folder name in the format Servers/folder1/folder2. -107 Access denied while enumerating Servers/Folders in farm The server may not be physically connected. The farm name supplied may either be syntactically wrong or may not exist. [Description of the Installation Manager snap-in] DCOM settings in the client machine are either absent or incorrect. The folder named does not exist. The administrator is not a Citrix Administrator. 2 EXECUTING The task is running. -205 Server is unreachable. Check network connections. The task cannot register itself with the Task Scheduler.

34 Installation Manager Administrator s Guide Error No Error String Trigger or Condition -207 You do not have permission to access the target server. You must be a local Administrator on that server. 209 Task Scheduler service not available on target. Installation manager requires Targets with windows vista, Server 2008 or above. 211 Invalid Task XML format. Document contains invalid tags. 212 Unable to write Log file {0}. check that the path exists and that you have write permissions to it. 214 Unable to read Task file {0} check that the file exists and that you have read permissions to it. 216 Specify the interval time in seconds for the Retry parameter. 219 This task name already exists on the target server. Enter a unique task name. 220 Network path {0} is unreachable. Check network connections. 221 Invalid Task XML format. Cannot find "action" tag. 222 You do not have permission to schedule a task. You must be a local Administrator on the target server. 223 Invalid Task XML format. The "command" tag contains invalid data. 224 Invalid Task XML format. The "command" tag is not well-formed. 226 The filename, directory name, or volume label syntax is incorrect for path {0} The application cannot register a task as the logon credentials are not available. The application does not contain the Task Scheduler service, or the service is not responding properly. The task XML document does not comply to the Task Scheduler 2.0 standard schema. The application cannot create the log file as it does not have write permission for the specified path. The task file is not at the specified location or cannot be accessed due to incorrect permissions. A negative value was specified for the Retry interval time. The task name specified already exists. The machines are physically disconnected. The task XML file does not contain the mandatory <actions> tag. Insufficient permissions exist to access the target task scheduler. The task XML file does not contain the mandatory <command> tag. The task XML <command> tag s formation is not valid. The task name specified is in an invalid format. 229 Invalid Task XML format. Task Scheduler cannot recognize the XML format. 230 Task successfully registered. The task registered successfully in the Task Scheduler. 233 Invalid task name. The task name specified does not start with an alphabetical character.

5 Error Messages 35 Error No Error String Trigger or Condition 234 Invalid target argument. Specify a valid server address. The server IP address provided is not valid. 239 Task successfully updated The existing task in the Task Scheduler updated successfully. 241 Missing retrytime argument. It is mandatory if retryinterval is provided. 242 Missing retryinterval argument. It is mandatory if retrytime is provided. A retryinterval value has been specified without a retrytime value. A retrytime value has been specified without a retryinterval value. 3 SCHEDULE_PENDING The task is yet to be registered in Task Scheduler. 300 Use the following date and 24-hour time format: DD/MM/YYYY HH:MM:SS. 301 Unable to prepare UNC path {0}. Check your credentials. 302 Invalid command argument. Specify a valid command-line operation. 303 Failed to assign read permissions of computer {0} to the path {1}. Ensure the path and computer name are correct, and that you have sufficient access rights to the path The time and date specified for the Schedule parameter are not in the required format. Access denied to UNC path due to insufficient permission. A command argument is in the wrong format. Failed to assign read permissions to the specified folder or file. 4 CANCELLED The task running has been aborted. 400 Specify a reboot timeout period in minutes for the Reboot-Timeout parameter. 404 Unable to read MSI file {0}. Check that the file exists and that you have read permissions to it. 405 Unable to read MST file {0}. Check that the file exists and that you have read permissions to it. The timeout value specified is not an integer. Access denied to MSI File due to insufficient permission. Access denied to MST File due to insufficient permission. 5 CANCEL_PENDING The task running is in the process of being aborted. 501 Task successfully removed. The task was removed successfully from the Task Scheduler. 6 REMOVED The task has been removed from the Task Scheduler.

36 Installation Manager Administrator s Guide Error No Error String Trigger or Condition 600 Unable to connect to Event Log of the target server. You must be a member of "Event Log Readers" group in the target server. Cannot connect to the EventLogger of the target machine. 601 Task not found. The task is not found in the target machineís Task Scheduler. 605 Task was scheduled. Task is scheduled to run on the target machine. 606 Task is running... The task is running on the target machine. 607 Scheduling... The task has yet to be registered. 608 Task was cancelled. The task running has been aborted. 609 Canceling task... The task running is in the process of being aborted. 610 Task failed. The task failed to execute. 611 Task Failed. Verify if IM Utilities is installed at target server The utilities package is not installed on the target machine. IMUtilities Cmdlet Error Messages Error No Error String Trigger or Condition 226 The filename, directory name, or volume label syntax is incorrect for path {0} 700 Installation failed: {0} MSIEXEC failed to run. 701 Unable to read Installation files using System credentials. Ensure "Everyone" has read permission to the share and "Advanced:Shared Folder" parameter contains the UNC path where the file is located. 702 Unable to connect to the XenApp farm. Specify only XenApp servers when using publish-app or disablelogon parameters. 703 Unable to add server to published application. The installation was successful, use Access Management Console to add the server to the published application object Unable to access MSI log file. XenApp farm initialization failed. Server may not exist.

5 Error Messages 37 Error No Error String Trigger or Condition 705 Published Application name is already existed 709 Terminal Server role is not enabled. Reboot and logoff parameters are only available for Terminal Server targets. Target server does not have Terminal Services enabled. 710 Unable to send message to connected sessions. Operation was canceled. 711 Unable to reboot server. The installation was successful otherwise, reboot the server manually to complete the operation. 712 This Citrix XenApp PowerShell snapin contains cmdlets used to perform installations on XenApp servers. 715 Incorrect number of parameters to MSIScriptlet.ps1 Error sending Terminal Services messages. Error restarting Terminal Services target. [Description of the Installation Manager Utilities package] Not all parameters were passed to scriplet file. 716 Missing MSI file path argument. MSI File is mandatory in scriptlet file. 718 Success. MSI installed successfully. 720 Missing task name argument. Task name is mandatory in Scriptlet file 723 Success. System will reboot. Task has run successfully, and the server will reboot to complete the installation. 724 Unable to write event to Windows Event Log. Error in writing to Event Logger.

38 Installation Manager Administrator s Guide