Installation Manager Administrator s Guide

38 

Loading....

Loading....

Loading....

Loading....

Loading....

Full text

(1)

Citrix XenApp™ 5.0 for Microsoft® Windows Server® 2008

Installation Manager Administrator’s Guide

(2)

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)

(3)

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

(4)

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

(5)

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)

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.

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/.

Convention Meaning

Boldface Commands, names of interface items such as text boxes, option buttons, and user input.

Italics 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.

Monospace Text displayed in a text file.

{braces} 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.

(7)

1 Introducing Installation Manager 7

Introducing Installation Manager

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 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.

(9)

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.

(10)
(11)

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)

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

(13)

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)

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.

(15)

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)
(17)

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)

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.

(19)

3 Deploying Tasks Using Installation Manager 19

Deploying MSI and MSP Packages

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)

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

(21)

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)

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.)

(23)

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)
(25)

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 snap-in (PSSnapIn) each time you start a PowerShell console, or by addsnap-ing lsnap-ines to the PowerShell environment profile to import the cmdlets automatically.

To import the cmdlets

In the Windows PowerShell console, type:

(26)

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>]

Example

In the Windows PowerShell console, type:

Get-IMServer -farm XenAppFarmIN -folder Servers\TargetFolder

This returns, for example:

FarmName IPAddress ServerName Location

XenAppFarm 123.123.0.1 XenAppSrv1 Servers/TargetFolder

Scheduling Tasks in Targets

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.

Parameter Description

farm IP address or DNS name of the MFCOM farm object. If not specified, the local server is used.

(27)

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 Description

name The unique name of the task.

msi 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.

targets 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).

mst 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. schedule 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)

logoffSessions 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.

disablelogon Disables logons to the target server during the installation process. reboot Forces a server restart after the package is successfully installed. Use

in conjunction with the message and timeout parameters. message Sends a message to all connected sessions. Use this option in

conjunction with the timeout parameter.

timeout The number of minutes connected sessions have until a server restart occurs. Use this option in conjunction with the message parameter. update 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. prepareUnc 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.

log The path to a file or XML object where the success or failure of the install on each target server is logged.

retrytime In the event that a target server cannot be contacted, specifies how long, in seconds, Installation Manager should continue retrying the installation task.

retryinterval Specifies how frequently, in seconds, the installation task should be retried during the period specified in retrytime.

whatif Validates the parameters specified and returns either success or failure; the cmdlet will not execute if whatif is specified.

(29)

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]

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.

Parameter Description

name A unique name for the task.

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. targets 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). update 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.

retrytime In the event that a target server cannot be contacted, specifies how long, in seconds, Installation Manager should continue retrying the task. retryinterval Specify how frequently, in seconds, the task should be retried during the

period specified in retrytime.

log The path to a file or XML object where the success/failure status of each target server is logged.

whatif Validates the parameters specified and returns either success or failure; the cmdlet will not execute if whatif is specified.

(30)

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 Description

name A unique name for the task.

command The command-line operation to execute on target servers.

targets 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). schedule 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.

update 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.

prepareUnc 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.

retrytime In the event that a target server cannot be contacted, specifies how long, in seconds, Installation Manager should continue retrying the task. retryinterval Specify how frequently, in seconds, the task should be retried during the

(31)

4 Using the PowerShell Cmdlets 31

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>]>]

log The path to a file or XML object where the success/failure status of each target server is logged.

whatif Validates the parameters specified and returns either success or failure; the cmdlet will not execute if whatif is specified.

Parameter Description

Parameter Description

targets 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).

name The name of the task.

fromdate The date from which you want status information. todate The date to which you want status information.

(32)

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>]

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.

Parameter Description

targets 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). name The name of the task you want to remove.

retrytime In the event that a target server cannot be contacted, specifies how long, in seconds, Installation Manager should continue retrying the task. retryinterval Specify how frequently, in seconds, the task should be retried during the

period specified in -retrytime.

log The path to a file or XML object where the success/failure status of each target server is logged.

(33)

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. The server may not be physically connected. -101 Invalid farm argument. Specify a

valid server address. The farm name supplied may either be syntactically wrong or may not exist.

103 This Citrix XenApp PowerShell snap-in contasnap-ins cmdlets used to perform remote management operations in your XenApp environments.

[Description of the Installation Manager snap-in]

-105 XenApp SDK is not installed or

Check DCOM Settings DCOM settings in the client machine are either absent or incorrect.

-106 The folder specified {0} does not exist. Specify a valid folder name in the format Servers/folder1/folder2.

The folder named does not exist.

-107 Access denied while enumerating

Servers/Folders in farm The administrator is not a Citrix Administrator.

2 EXECUTING The task is running.

-205 Server is unreachable. Check network

(34)

-207 You do not have permission to access the target server. You must be a local Administrator on that server.

The application cannot register a task as the logon credentials are not available.

209 Task Scheduler service not available on target. Installation manager requires Targets with windows vista , Server 2008 or above.

The application does not contain the Task Scheduler service, or the service is not responding properly. 211 Invalid Task XML format. Document

contains invalid tags. The task XML document does not comply to the Task Scheduler 2.0 standard schema.

212 Unable to write Log file {0}. check that the path exists and that you have write permissions to it.

The application cannot create the log file as it does not have write permission for the specified path. 214 Unable to read Task file {0} check

that the file exists and that you have read permissions to it.

The task file is not at the specified location or cannot be accessed due to incorrect permissions.

216 Specify the interval time in seconds

for the Retry parameter. A negative value was specified for the Retry interval time. 219 This task name already exists on the

target server. Enter a unique task name.

The task name specified already exists.

220 Network path {0} is unreachable.

Check network connections. The machines are physically disconnected. 221 Invalid Task XML format. Cannot

find "action" tag. The task XML file does not contain the mandatory <actions> tag.

222 You do not have permission to schedule a task. You must be a local Administrator on the target server.

Insufficient permissions exist to access the target task scheduler. 223 Invalid Task XML format. The

"command" tag contains invalid data. The task XML file does not contain the mandatory <command> tag.

224 Invalid Task XML format. The

"command" tag is not well-formed. The task XML <command> tag’s formation is not valid. 226 The filename, directory name, or

volume label syntax is incorrect for path {0}

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.

(35)

5 Error Messages 35

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. A retryinterval value has been specified without a retrytime value.

242 Missing retryinterval argument. It is

mandatory if retrytime is provided. 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.

The time and date specified for the Schedule parameter are not in the required format.

301 Unable to prepare UNC path {0}.

Check your credentials. Access denied to UNC path due to insufficient permission. 302 Invalid command argument. Specify a

valid command-line operation. A command argument is in the wrong format. 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

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.

The timeout value specified is not an integer.

404 Unable to read MSI file {0}. Check that the file exists and that you have read permissions to it.

Access denied to MSI File due to insufficient permission.

405 Unable to read MST file {0}. Check that the file exists and that you have read permissions to it.

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)

IMUtilities Cmdlet Error Messages

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.

Error No Error String Trigger or Condition

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.

Unable to access MSI log file.

702 Unable to connect to the XenApp farm. Specify only XenApp servers when using publish-app or disable-logon parameters.

XenApp farm initialization failed.

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

(37)

5 Error Messages 37

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. Error sending Terminal Services messages. 711 Unable to reboot server. The

installation was successful otherwise, reboot the server manually to complete the operation.

Error restarting Terminal Services target.

712 This Citrix XenApp PowerShell snap-in contasnap-ins cmdlets used to perform installations on XenApp servers.

[Description of the Installation Manager Utilities package] 715 Incorrect number of parameters to

MSIScriptlet.ps1 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)

Figure

Updating...

Related subjects :