Está en la página 1de 312

Advanced Concepts Guide

Citrix Presentation Server for Windows


Version 4.0

Citrix Presentation Server 4.0 for Windows


TM

Citrix Access Suite

Copyright and Trademark Notice


Information in this document is subject to change without notice. Companies, names, and data used in
examples herein are fictitious unless otherwise noted. Other than printing one copy for personal use, 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.
Copyright 2001-2005 Citrix Systems, Inc. All rights reserved.
Citrix, ICA (Independent Computing Architecture), MetaFrame, MetaFrame XP, and Program
Neighborhood are registered trademarks, and SpeedScreen is a trademark of Citrix Systems, Inc. in
the United States and other countries.
RSA Encryption 1996-1997 RSA Security Inc., All Rights Reserved.
Trademark Acknowledgements
Adobe, Acrobat, and PostScript are trademarks or registered trademarks of Adobe Systems
Incorporated in the U.S. and/or other countries.
Apple, LaserWriter, Mac, Macintosh, Mac OS, and Power Mac are registered trademarks or trademarks
of Apple Computer Inc.
DB2, Tivoli, and NetView are registered trademarks, and PowerPC is a trademark of International
Business Machines Corp. in the U.S. and other countries.
HP OpenView is a trademark of the Hewlett-Packard Company.
Java, Sun, and SunOS are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and
other countries. Solaris is a registered trademark of Sun Microsystems, Inc. Sun Microsystems, Inc has
not tested or approved this product.
Portions of this software are based in part on the work of the Independent JPEG Group.
Portions of this software contain imaging code owned and copyrighted by Pegasus Imaging
Corporation, Tampa, FL. All rights reserved.
Macromedia and Flash are trademarks or registered trademarks of Macromedia, Inc. in the United
States and/or other countries.
Microsoft, MS-DOS, Windows, Windows Media, Windows Server, Windows NT, Win32, Outlook,
ActiveX, Active Directory, and DirectShow are either registered trademarks or trademarks of
Microsoft Corporation in the United States and/or other countries.
Netscape and Netscape Navigator are registered trademarks of Netscape Communications Corp. in the
U.S. and other countries.
Novell Directory Services, NDS, and NetWare are registered trademarks of Novell, Inc. in the United
States and other countries. Novell Client is a trademark of Novell, Inc.
RealOne is a trademark of RealNetworks, Inc.
SpeechMike is a trademark of Koninklijke Philips Electronics N.V.
Unicenter is a registered trademark of Computer Associates International,
Inc. UNIX is a registered trademark of The Open Group.
All other trademarks and registered trademarks are the property of their
owners. Document Code: October 21, 2005 9:12 am (GG)

Contents

Contents
Chapter 1

Introduction
Document Conventions............................................................................................7
Getting More Information and Help........................................................................8

Chapter 2

Planning Your Deployment


Hardware Configuration .......................................................................................13
Operating System Configuration ...........................................................................17
Planning User Capacity ........................................................................................18

Chapter 3

Facilitating Server Farm Communication


Understanding Zones and Data Collector Communication. .................................23
Bandwidth Requirements for Server Farm Events ...............................................29
Implementing the Data Store ................................................................................37
Teaming Network Interface Card Configurations .................................................42
Multihoming Servers in the Farm .........................................................................45

Chapter 4

Deploying Citrix Presentation Server


Installation/Upgrade Considerations .....................................................................51
Obtaining Installation and Updates Information ...................................................52
Remapping Server Drives .....................................................................................54
Rapid Deployment of Citrix Presentation Server ..................................................54
Deploying Citrix Presentation Server Clients .......................................................61
Consolidating Multiple License Files ....................................................................73

Chapter 5

Managing Server Farms


Management Consoles for Citrix Presentation Server ..........................................75
Administering Server Farms .................................................................................81
Installation Manager Recommendations ...............................................................85
Resource Manager Recommendations ..................................................................90
Network Manager Issues .......................................................................................95
Using Visual Basic Scripts to Access the WMI Provider .....................................96

Advanced Concepts
Guide

Chapter 6

Deploying, Publishing, and Configuring Applications

Publishing
in
Domains
with
Thousands
of
Objects
.............................................................................................................................
113
Content
Redirection
.............................................................................................................................
114
Isolation
Environment
Rules
.............................................................................................................................
115
Using
Virtual
IP
Addresses
with
Published
Applications
.............................................................................................................................
122
Configuring SpeedScreen Browser Acceleration for Published Applications . . .
126 Media Formats and Network Types Supported by SpeedScreen Multimedia
Acceleration
.............................................................................................................................
132
SpeedScreen
MultiMedia
Acceleration
Configuration
Options
.............................................................................................................................
134
PDA
Synchronization
.............................................................................................................................
135
Using
Load
Managed
Groups
or
Isolation
Environments
.............................................................................................................................
138
TWAIN
Redirection
Support
.............................................................................................................................
139
Using Scripts to Add and Remove Users from Published Applications
.............................................................................................................................
141
Using Installation Manager to Deploy Windows Installer Packages
.............................................................................................................................
145

Chapter 7

Optimizing Citrix Presentation Server Performance


Network
Optimization
.............................................................................................................................
147
Server
Optimization

Contents

.............................................................................................................................
149
Applications
Optimization
.............................................................................................................................
155
Disk
Optimization
.............................................................................................................................
157
Memory
Optimization
.............................................................................................................................
159
User
Settings
Optimization
.............................................................................................................................
162
Audio
Recording
Optimization
.............................................................................................................................
163
Client
Audio
Mapping
Virtual
Driver
.............................................................................................................................
165
ICA
Priority
Packet
Tagging
.............................................................................................................................
167

Chapter 8

Security Issues and Guidelines


Improving
Your
Server
Security
.............................................................................................................................
171
Security
Considerations
for
the
Data
Store
.............................................................................................................................
173
Network
Security
Considerations
.............................................................................................................................
175
Configuring
Proxy/Firewall
Integration
.............................................................................................................................
180
Using
Smart
Cards
with
Citrix
Presentation
Server
.............................................................................................................................
185

Advanced Concepts
Guide
Using

Citrix
Products
in
a
Wireless
LAN
Environment
.............................................................................................................................
191
Deploying
the
Java
Client
Using
the
Web
Interface
.............................................................................................................................
192

Chapter 9

Troubleshooting
Troubleshooting
the
IMA
Service
.............................................................................................................................
193
Troubleshooting Application Compatibility Issues .............................................197
Troubleshooting Novell Directory Services Integration ......................................204
SQL Database Replication Troubleshooting Tips ...............................................207
Resource Manager Troubleshooting Q&A .........................................................208
Trusts and User Group Access Issues .................................................................211
Other Troubleshooting Recommendations .........................................................211
Collecting Information for Citrix Technical Support .........................................214

Chapter 10

Using Citrix Presentation Server with Novell Directory Services


Farm Layout and System Requirements .............................................................219
Setting Up Citrix Presentation Server for Use in Novell Directory Services ......221
Installing the Novell Client .................................................................................222
Using Citrix Presentation Server in the Novell Directory Services Environment
229 Enabling Novell Directory Services Usage in the Web Interface ................232
Novell Directory Services Usage with the Citrix Presentation Server Client .....234
Tips and Techniques ...........................................................................................236

Chapter 11

Printer Management
Enforcing Printer Compatibility ..........................................................................239
Session Printers Policy Rules ..............................................................................240
Printing Registry Settings. ..................................................................................243

Chapter 12

Replicating Data Stores Running Microsoft SQL Server


Preparing for Replication ....................................................................................251
Replicating a Data Store in SQL Server 2000 ....................................................254
Replicating a Data Store in SQL Server 7 ..........................................................264

7
Pointing Servers to the Replicated Data Store ....................................................267
Contents

Appendix A

Utilities .......................................................................................................................... 269


AIERUN .............................................................................................................270
AIESETUP .........................................................................................................271
DSVIEW .............................................................................................................273
MSGHOOK ........................................................................................................274
QPRINTER .........................................................................................................275
QUERYDC .........................................................................................................277
QUERYDS ..........................................................................................................279
QUERYHR .........................................................................................................282
SCCONFIG ........................................................................................................284
LMNEWLOG. ....................................................................................................286
LMSWITCH .......................................................................................................287
SSLAUTOCONFIG ............................................................................................288

Appendix B

Tested Hardware .......................................................................................................... 289

Appendix C

Error Codes .................................................................................................................. 295


IMA Error Codes ................................................................................................295
Event Log Error Messages ..................................................................................301
Isolation Environment Warning and Error Messages .........................................307

Appendix D

Registered Citrix Ports ................................................................................................ 309

Appendix E

Tested Applications for Isolation Environments ....................................................... 311


Acrobat Reader 4.05 and 5.1; Adobe Reader 6.01 and 7.0 .................................312
Crystal Reports 7.0 and 8.0 .................................................................................312
FoxPro 2.6 for DOS ............................................................................................313
Internet Explorer 5.5 and 6.0 ..............................................................................314
Sun Java Runtime Environment (JRE) 1.3 and 1.4 ............................................315
Microsoft Data Access Components (MDAC) 2.6 and 2.7 ................................315
Mozilla FireFox 1.0.2 .........................................................................................316
Microsoft Office 97, 2000, XP, and 2003 ..........................................................317
Oracle Client 8i and 9i ........................................................................................320
Microsoft Project 98 ...........................................................................................321
SAP GUI 4.6D and 6.2 .......................................................................................322
StarOffice 5.2 ......................................................................................................323
StarOffice 7.0 ......................................................................................................323

Advanced Concepts
Guide
WinZip 9.0 ..........................................................................................................324

Index .............................................................................................................................. 325

Introduction

CHAPTER 1

Advanced Concepts Guide for Citrix Presentation Server for Windows 4.0 this
book is a collection of best practices, tips, and suggestions for effectively
using Presentation Server. To get the most from this guide, you should be
familiar with the concepts and configuration procedures in the MetaFrame
Presentation Server Administrators Guide and the additional documentation for
Presentation Server componentsall of which are available in the Document
Center included on your Presentation Server CD.
Additional information is available from the Presentation Server readme file. See
the Presentation Server Client readme files for known issues and work arounds.
For further information or to get white papers about some of the topics discussed
in this document, visit the Citrix Web site at http://www.citrix.com.
Note All terminology, product references, and recommendations are subject
to change without notice.

Document Conventions
Presentation Server documentation uses the following typographic conventions
for menus, commands, keyboard keys, and items in the program interface:
Convention

Meaning

Boldface

Commands, names of interface items such as text boxes, option


buttons, and user input.

Italics

Placeholders for information or parameters that you provide. For


example, filename in a procedure means you type the actual name of a
file. Italics also are used for new terms and the titles of books.

%SystemRoot%

The Windows system directory, which can be WTSRV, WINNT,


WINDOWS, or other name you specify when you install
Windows.

Advanced Concepts
Guide
Convention

Meaning

Monospace

Text displayed in a text file.

{ braces }

A series of items, one of which is required in command statements. For


example, { yes | no } means you must type yes or no. Do not type
the braces themselves.

[ brackets ]

Optional items in command statements. For example, [/ping] means


that you can type /ping with the command. Do not type the brackets
themselves.

| (vertical bar)

A separator between items in braces or brackets in command statements.


For example, { /hold | /release | /delete } means you type /hold or
/release or /delete.

(ellipsis)

You can repeat the previous item or items in command statements.


For example, /route:devicename[,] means you can type additional
devicenames separated by commas.

Getting More Information and Help


This section describes how to get more information about Presentation Server
and how to contact Citrix.

Accessing Product Documentation


The documentation for Presentation Server includes online documentation,
known issues information, integrated on-screen assistance, and application help.

Online documentation is provided as Adobe Portable Document Format (PDF) files.


Online guides are provided that correspond to different features of Presentation Server.
For example, information about the Web Interface is contained in the Web Interface
Administrators Guide. Use the Document Center to access the complete set of online
guides.

Be sure to read the Readme files in the \Documentation directory of the product CD
before you install Presentation Server or when troubleshooting. This file contains
important information that includes last-minute documentation updates and corrections.

In many places in the Presentation Server user interface, integrated on-screen


assistance is available to help you complete tasks. For example, in the Access Suite
Console, you can position your mouse over a setting to display help text that explains
how to use that control.

Online help is available in many components. You can access the online help from
the Help menu or Help button.
Important To view, search, and print the PDF documentation, you need to have
Adobe Reader 5.0.5 with Search or Adobe Reader 6.0 or 7.0. You can
download Adobe Reader for free from Adobe Systems Web site at
http://www.adobe.com/.

Accessing the Document Center


The Document Center provides a single point of access to product documentation
and enables you to go straight to the section in the documentation that you need.
It also includes:

A list of common tasks and a link to each item of documentation.

A search function that covers all the PDF guides. This is useful when you need to
consult a number of different guides.

Cross-references among documents. You can move among documents as often as you
need using the links to other guides and the links to the Document Center.
You can access the Document Center from your product CD or install it on
your servers. To install the Document Center, select the option from the
Presentation Server Autorun screen.
To start the Document Center
1. From your product CD, navigate to the \Documentation folder.

or
On a server on which you installed the Document Center, select
Documentation from the Citrix program group on the servers Start menu.
2. Open document_center.pdf. The Document Center appears.
If you prefer to access the guides without using the Document Center, you can
navigate to the component PDF files using Windows Explorer. If you prefer to
use printed documentation, you can also print each guide using Adobe Reader.
Note The Advanced Concepts Guide is not part of the Documentation Center
at this time.

Getting Service and Support


Citrix provides technical support primarily through the Citrix Solutions Network
(CSN). Our CSN partners are trained and authorized to provide a high level of
support to our customers. Contact your supplier for first-line support or check for
your nearest CSN partner at http://www.citrix.com/support/.
In addition to the CSN channel program, Citrix offers a variety of selfservice, Web-based technical support tools from its Knowledge Center at
http://support.citrix.com/. Knowledge Center features include:

A knowledge base containing thousands of technical solutions to support your Citrix


environment

An online product documentation library

Interactive support forums for every Citrix product

Access to the latest hotfixes and service packs

Security bulletins

Online problem reporting and tracking (for customers with valid support
contracts)
Another source of support, Citrix Preferred Support Services, provides a range of
options that allows you to customize the level and type of support for your
organizations Citrix products.

Subscription Advantage
Subscription Advantage gives you an easy way to stay current with the latest
server-based software functionality and information. Not only do you get
automatic delivery of feature releases, software upgrades, enhancements, and
maintenance releases that become available during the term of your subscription,
you also get priority access to important Citrix technology information.
You can find more information on the Citrix Web site at
http://www.citrix.com/services/ (select Subscription Advantage). You can also
contact your Citrix sales representative or a member of the Citrix Solutions
Network for more information.

Customizing Citrix Presentation Server


The Citrix Developer Network (CDN) is at http://www. citrix.com/cdn/. This
open- enrollment membership program provides access to developer toolkits,
technical information, and test programs for software and hardware vendors,
system integrators, licensees, and corporate IT developers who incorporate Citrix
computing solutions into their products.

Most of the operations that you can perform using the Presentation Server user
interface can also be scripted by using the Citrix Software Development Kit
(SDK). The SDK also lets programmers customize most aspects of Presentation
Server. The SDK is available from http://www.citrix.com/cdn/.

Education and Training


Citrix offers a variety of instructor-led training and Web-based training solutions.
Instructor- led courses are offered through Citrix Authorized Learning Centers
(CALCs). CALCs provide high-quality classroom learning using professional
courseware developed by Citrix. Many of these courses lead to certification.
Web-based training courses are available through CALCs, resellers, and from the
Citrix Web site.
Information about programs and courseware for Citrix training and certification
is available from http://www.citrix.com/edu/.

CHAPTER 2

Planning Your
Deployment

This chapter includes recommendations for server hardware and operating


system configuration and for providing adequate server capacity for user
sessions. Before installing and deploying Presentation Server, read and consider
these sections.

Hardware Configuration
Citrix recommends the following hardware configuration options to improve the
performance of Presentation Server.

General Recommendations

Employ RAID ArraysBecause hard drives are the most common point of hardware
failure in multi-processor configurations, Citrix recommends a RAID (Redundant
Array of Independent Disks) setup. See the MetaFrame Presentation Server
Administrators Guide for more information regarding available RAID configurations.
If RAID is not an option, a fast SCSI 2, 3, or Ultra 160 drive is recommended. Faster
hard drives are inherently more responsive and may eliminate or curtail disk
bottlenecks. Currently 15,000 RPM hard drives are the most commonly deployed.

Install Multiple Disk ControllersFor quad and eight-way servers, install at least
two controllers, one for operating system disk usage and the other to store applications
and temporary files. Isolate the operating system as much as possible; do not install
applications on the controller where the operating system is installed. Distribute hard
drive access load as evenly as possible across the controllers.

1
4

Advanced Concepts
Guide

Note The deployment of servers with two processors has been found to
provide not only better overall efficiency but also a generally lower total cost
of ownership. However, each environment varies so the number of processors
employed should be based on specific requirements. For results of Citrix
eLabs CPU usage and Hyper-Threading testing, see Planning User
Capacity on page 18.

Provide Adequate Disk Space for User ProfilesPartition and hard drive size
depends on both the number of users connecting to computers running Presentation
Server and the applications running on the server. Running applications such as those
in the Microsoft Office Suite can result in user profile directory sizes of hundreds of
megabytes. Because a user profile is loaded on the system drive of the server during
session initialization, large numbers of user profiles can use gigabytes of disk space on
the server. You must have enough disk space for these profiles on the system drive of
the server.
Note Store roaming profiles and user data on a centralized file server,
Storage Area Network (SAN), or Network-Attached Storage (NAS) that can
adequately support the environment. In addition, locate this storage medium
near the servers so that minimal router hops are required and logon times are
not unnecessarily increased.

Enable Disk-Write CachingUsers may experience performance improvements if


disk-write caching is enabled on a servers RAID controller. For example, enabling
disk-write caching can help mitigate problems users experience when many users log
on at the same time. Citrix recommends that the cache be set to 50/50 (read/write) for
optimal performance.

Server Redundancy
When planning the hardware configuration of your server farm, consider
the following precautions:

At least one additional server should be available in the event of a single server failure.
It is typical for some organizations to plan for as much as 25% redundancy within the
production environment.

Servers that enable access to Presentation Server, such as Web Interface, the Secure
Gateway, and Citrix Access Gateway servers, serve as single points of failure if only
one server is deployed with a given functionality. Deploy two or more servers to
service each function to ensure continued access to the server farm.

Data Store Hardware Guidelines


The performance of various events within your Presentation Server environment
can be improved by increasing the CPU power and speed of the database server
that hosts the data store.
Testing shows that adding processors to the data store server can dramtically
improve response time when multiple simultaneous queries are being executed. If
the environment has large groups of servers coming online frequently, the
additional processors service the requests faster.
However, with serial events, such as installing or removing a farm server, the
additional processors show lower performance gains. To improve the processing
time for these types of events, increase the processor speed of the data store
hardware platform.
Note The response time of other farm events (such as recreating the local host
cache or replicating printer drivers to all farm servers) is more closely related to
the size of the farm rather than to the response time of the data store.

Objects in the Data Store


A major factor in determining the hardware needed to ensure the performance of
the data store is the number and size of object records in the data store. When
you create an object in the Presentation Server Console by performing an action
such as publishing an application or adding an administrator, you create a record
for that object in the data store database. The objects include the following:

Applications

Administrators

Folders

Installation Manager groups

Installation Manager packages

Load evaluators

Printers

Printer drivers

Policies

Resource Manager metrics

Servers

Isolation Environments

Some objects, such as applications and servers, create multiple entries in the data
store. As the number of entries in the data store grows, the time required to search
and retrieve the entries also grows.
As servers are added to the farm, the data store must service more requests.
Consequently, plan the data store hardware platform based on the total number
of servers you plan to include in the farm.
For more information about choosing a database for the data store, see the
MetaFrame Presentation Server Administrators Guide.

The Size of Data Store Objects


The following table shows the estimated sizes of object records created in the
data store when various tasks were performed in the Presentation Server
Console. Consider these estimates as guidelines only, because the size of an
objects entries in the data store depends on many factors.
Note These estimates were compiled with a SQL Server 2000, Service Pack
3 database.

Task

Size of Object
Record Created in
Data Store (Bytes)

Publish an application (for example, Wordpad)

12064

Create an isolation environment object

16468

Insert application into isolation environment object

4378

Publish application in an isolation environment

10602

Create a policy

8694

Configure all rules and assign policy to domain users group

1018

Create a Resource Manager application configured for one server

7555

Import a network print server/printer driver

2172

Add printer driver

4108

Add Resource Manager metric for one server (Citrix Presentation


Server/ data store bytes written/sec)

3324

Add one domain administrator as an administrator

1743

Add user group as Presentation Server administrator

1763

Configure Installation Manager properties (account, path)

1632

Task

Size of Object
Record Created in
Data Store (Bytes)

Add an Installation Manager package

24069

Create an Installation Manager package group

4405

Add a server folder

1187

Add an application folder

1189

Create a Load Manager load evaluator with one evaluation rule


(server user load)

1812

Add a server to a farm

74320

Operating System Configuration


The following Windows server operating system configuration options are
recommended to improve the performance, stability, and security of your
Presentation Server implementation.

General Recommendations

All partitions must be in Windows NT File System (NTFS) format. NTFS enables
security configuration, better performance, fault tolerance, and also saves disk space
usage because NTFS partitions have small and constant cluster sizes (the minimum size
is 4KB). File Allocation Table (FAT) partitions require much larger cluster sizes
because the size of the partition increases (with the minimum being 32KB). More space
is wasted on FAT partitions because the file system requires an amount of physical disk
space equal to the cluster size of the partition used to store a file, even if the file is
smaller than the cluster size. For more information about cluster sizes of FAT and
NTFS partitions, see Microsoft Knowledge Base article 140365.

If possible, when using Windows 2000 Server or Windows NT, install only one
network protocol on the server. This practice frees up system resources and reduces
network traffic. If multiple protocols are needed, set the bind order so that the most
commonly used protocol is first.

When working with Windows 2000 Server, increase the registry size to accommodate
the additional user profile and applications settings that are stored in the registry. On a
single-processor server, you must reserve at least 40MB for the registry. Reserve at
least 100MB on quad and eight-way servers.

You can also increase performance by correctly tuning the page file. For more
information about the page file, see Microsoft Knowledge Base article 197379.

Service Packs and Updates


For consistency and reduced troubleshooting, install the same service packs and
hotfixes on all servers in the server farm.
Important You can find late-breaking information and links to citical updates
for server operating systems and for Citrix installation files in the online Preinstallation Update Bulletin. Open the Pre-installation Checklist to access a link
to this site. You can find the checklist on the Presentation Server autorun screen.

Planning User Capacity


The number of users that a server running Presentation Server can support
depends on several factors including:

The servers hardware specifications

The CPU and memory requirements of the applications that are being run

The amount of user input being processed by the applications

The following sections present benchmark results regarding user capacity,


examine the potential benefits of Hyper-Threading, and discuss how to achieve
realistic sizing for the server by using Resource Manager.

Benchmarking Client Sessions


Citrix conducted benchmarking tests to quantify the number of simulated
Presentation Server Client sessions that can be connected to a server and still
have acceptable performance.
These tests simulated users continuously working with Microsoft Office
applications with a step size number of users defined as five. During each test,
the following steps were taken after the first five users were logged on:
1. Launched simulated user scripts on all five sessions.
2. Opened Microsoft Excel and simulated the creation of a spreadsheet.
3. Opened Microsoft Access and simulated the creation of an Access database.
4. Opened Microsoft PowerPoint and created a presentation.

Based on how long the test steps took to complete, a benchmarking score was
calculated. For these tests, a score of 80 was determined as the optimal load for a
server, meaning that the server had enough additional CPU and memory
resources to handle spikes in performance. Note that this score is a
benchmarking score and does not correspond to number of users or other test
variables. The benchmarking test sought the impact of additional CPU resources
on the number of client sessions that could be accomodated before the
benchmarking score fell below 80.

Test Configuration
The benchmarking test was conducted with the following hardware and software
configurations:

Server Configuration
Dell PowerEdge 6650
Quad Processor3.0GHz Xeon with 512KB L2 and 4MB L3 cache HyperThreading is enabled
5x 73GB U320 15K RPM HDD with Dell PERC 4/DC Raid Controller
16GB RAM
16GB Page File
Citrix Presentation Server 4.0
Microsoft Windows Server 2003
Microsoft Office XP Professional

Client Configuration
Pentium 3 800MHz with 256KB cache
256MB RAM
Citrix Program Neighborhood Client Version 9.00.32649
Microsoft Windows 2000 Service Pack 4

Test Results
Tests were performed by keeping the hardware static and disabling processors on
the server. A servers degradation point was considered to have been reached
when its score fell below 80. Results were collected for the server having 1, 2,
and 4 processors enabled.
Number of CPUs

Number of Simulated Users

% Performance Increase

101 +/- 1

N/A

184 +/- 1

82%

230 +/- 1

25%

Thus, the performance of the Dell PowerEdge 6650 with four processors enabled
and 230 concurrent simulated users, is equivalent to the performance of two
processors enabled with 184 concurrent simulated users, and equivalent to the
performance of one processor enabled with 101 concurrent simulated users.
Moving from a single to a dual processor system equates to an 82% increase in
performance while moving from a dual to a quad processor system equates to
only a 25% increase in performance. In other words, as CPUs are added to the
server, the increase in performance of the operating system becomes less. Server
scalability is not linear with the number of processors, and drops off sharply
between two-four processors. All tests were run on Windows Server 2003 32-bit.
In the 32-bit operating system, the setup is limited by the amount of kernel
memory available. This limitation is shown on the User Capacity Benchmark
graph where four processor setup does not reach 80% failure point.

Note When scaling Presentation Server, the number of actual users per
server varies based on the applications deployed.

Using Resource Manager to Determine User Capacity


Resource Managers summary database stores information concerning CPU and
memory usage for various processes running on Presentation Server. With this
information, you can estimate user capacity of a server:

Limit user access to approximately 20 users per processor.

Enable Resource Managers summary database.

Run tests that include the launch and use of applications running on that server.

Chapter 2 Planning Your


Deployment

2
1

Use the Report Center in the Access Suite Console to create a report that queries the
information required to assess server capacity. The report should contain the following
information:

Average CPU and memory usage for the specific processes

Average CPU and memory usage for other processes, such as Explorer.exe or
Winlogon.exe

A defined threshold, such as no more than 90% CPU usage and/or no more than
3GB of RAM used

A calculation to extrapolate the number of users that can be divided into the
threshold given the resource usage
The longer you can use these tests, the better the data averages you can collect
from the summary database.

CHAPTER 3

Facilitating Server
Farm Communication

To ensure that your server farm is correctly designed and implemented, it


must support the communication that occurs in the farm.This chapter
examines this communication among servers and between servers and the
data store.

Understanding Zones and Data Collector Communication


To understand server farm communication, you must be aware of how farms are
divided into zones and the role that data collectors play in keeping track of
changes in zones.
Zones in a server farm perform two functions:

Collecting data from member servers

Distributing changes to all servers in the farm

All member servers must belong to a zone. By default, the zone name is the
subnet ID on which the member server resides.
The zone data collector maintains all load and session information for every
server in its zone. Each data collector has a connection open to all other data
collectors in the farm. This connection is used to immediately relay any changes
reported by servers that are members of the zone by that zones data collector to
the data collectors of all other zones. The formula for interzone connections is N
* (N-1)/2, where N is the number of zones in the farm.
Important Citrix recommends that you maintain as few zones as possible
while still being able to complete application enumeration requests and
resolutions in a timely manner. Creating too many zones can decrease
performance in a farm, resulting in high network bandwidth consumption and
decreased performance of the zone data collectors.

2
4

Advanced Concepts
Guide

Configuring Data Collectors in Large Zones


By default, a single zone supports 512 member servers (prior to MetaFrame XP
Feature Release 3, the default was 256 member servers). If a zone has more than
512 member servers, each zone data collector and potential zone data collector
must have a new registry setting. This new setting controls how many open
connections to member servers a data collector can have at one time.
To prevent the data collector from constantly destroying and recreating
connections to stay within the limit, set the registry value higher than the number
of servers in the zone. You can configure this value by adding the following
value, expressed in hexadecimal notation, to the registry:
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\IMA\Runtime\MaxHostAddres
s CacheEntries (DWORD)
Value: 0x200 (default 512 entries)
Note If you do not have more than 512 servers in a zone, increasing this
value does not increase the performance of a zone

Data Collector Scalability in Large Farms


In large farms (800+ servers) containing more than one zone where the data
collectors are heavily utilized performing logon resolutions, data collectors may
become overloaded and stop performing resolutions for a short period of time.
This is caused when all the worker threads on each data collector are processing
IMA maintenance items such as IMA pings, gateway updates, load updates, and
so on while performing resolutions. These resolutions require the processing of
events at the remote data collector and the remote data collector has no worker
threads available to deliver the event.
The following registry settings increase IMA processing bandwidth by
increasing the number of worker threads available to the data collector and
shortening the time-out of stale events. Create these keys and values in the
registry of each zone data collector and all potential zone data collectors:
CAUTION Using Registry Editor incorrectly can cause serious problems that
may require you to reinstall your operating system. Citrix cannot guarantee that
problems resulting from the incorrect use of Registry Editor can be solved. Use
Registry Editor at your own risk.

HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\IMA

WorkQueueThreadCount (DWORD)

Value: 0x00000080 (hex)

EventTimeout (DWORD)

Value: 0x000007d0 (hex)

HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\IMA\RUNTIME

GatewayValidationInterval (DWORD)

Value: 0x00007530 (hex)

Note Data collectors stop performing logon resolutions in this way only if there
are multiple zones and each data collector is processing upwards of 40
resolutions per second. Setting these registry keys does not improve performance
if this condition is not experienced.

Approximating Traffic Generated by Updates to the


Data Collector
The amount of traffic generated when a member server updates the data collector
with requests and changed data can be estimated mathematically. In turn, a small
amount of traffic is then sent from the data collector to the member server. This
traffic accounts for approximately one half of the data sent from the member
server to the data collector, so for full bandwidth utilization, multiply the number
of bytes from the formula by 1.5. To approximate the amount of traffic destined
for the data collector, multiply the number of bytes from the formula by the
number of member servers in the zone.
These numbers are an approximation from data gathered by Citrix. Actual results
may vary.

Citrix Presentation Server 4.0: Bytes = 5600 + (200*Con) + (100*Discon) +


(300*Apps)

MetaFrame Presentation Server 3.0: Bytes = 4900 + (200*Con) +


(100*Discon)
+ (300*Apps)

MetaFrame XPe / Feature Release 3: Bytes = 6300 + (200*Con) +


(100*Discon) + (150*Apps)
Where:
Con = Number of connected sessions
Discon = Number of disconnected sessions
Apps = Number of published applications in the farm

Approximating Traffic among Data Collectors


During a zone update, approximately the same amount of data is transmitted
between data collectors, so for full bandwidth utilization, double the bytes from
the following formulas. To approximate the amount of traffic across all data
collector links, multiply the number of bytes obtained from the formula by the
number of data collectors minus 1 in the farm.
To approximate the amount of data sent between two data collectors during a full
zone transfer, use the following formula:

Citrix Presentation Server 4.0: Bytes = 13000 + (300*Con) + (300*Discon) +


(500*Apps)

MetaFrame Presentation Server 3.0: Bytes = 9530 + (300*Con) +


(300*Discon)
+ (500*Apps)

MetaFrame XPe: / Feature Release 3: Bytes = (7400 + (6.3*Srv_Zone))+


(400*Con) + (200*Discon) + (300*Apps)
Where:
Con = Number of connected sessions
Discon = Number of disconnected sessions
Apps = Number of published applications in the farm
Srv_Zone = Number of member servers in the zone
Note If the WAN is congested, you can use a QoS solution to help ensure
that IMA traffic is prioritized.

Traffic for Session-Based Events


The following tables illustrate the impact to network traffic and the amount of
data transmitted for session-based events. Each time these events occur, the
member server sends data to the zones data collector, which then sends data to
all other data collectors in the farm.

Citrix Presentation Server 4.0Sharing Load Information


Event

Data transmitted (approximate)

Connect

1.15KB

Disconnect

0.92KB

Reconnect

1.10KB

Logoff

0.66KB

Citrix Presentation Server 4.0Not Sharing Load Information


Event

Data transmitted (approximate)

Connect

0.87KB

Disconnect

0.50KB

Reconnect

0.80KB

Logoff

0.36KB

MetaFrame Presentation Server 3.0


Event

Data transmitted (approximate)

Connect

0.51KB

Disconnect

0.48KB

Reconnect

0.47KB

Logoff

0.30KB

MetaFrame XPe / Feature Release 3


Event

Data transmitted (approximate)

Connect

0.86KB

Disconnect

0.68KB

Reconnect

0.70KB

Logoff

0.63KB

Traffic for Inter-Zone Communication


The following tables list the amount of data sent by one data collector to another
when operations are performed by the Presentation Server Console on servers
that reside in different zones.

Citrix Presentation Server 4.0


Event

Data transmitted (approximate)

Presentation Server Console server query

0.61KB

Application publishing
3.78KB
Changing a zone data collector

12.3KB

MetaFrame Presentation Server 3.0


Event

Data transmitted (approximate)

Presentation Server Console server query


0.27KB Application publishing

2.7KB

Changing a zone data collector

12KB

MetaFrame XPe / Feature Release 3


Event
Presentation Server Console server query
0.53KB Application publishing

Data transmitted (approximate)

0.92KB
Changing a zone data collector

29KB

The bandwidth consumed when you publish an application varies depending on


the number of servers in the server farm. In general, the amount of bandwidth
consumed increases 466 bytes for every additional server in the server farm.
Starting a new server generates the most amount of traffic to the other data
collectors. Starting a new server generates about 5.6KB worth of traffic to the
data collector in a default configuration.

Bandwidth Requirements for Server Farm Events


The following sections discuss and quantify the bandwidth requirements for
normal communication in a server farm. This information can be used to
determine potential bandwidth requirements when planning for WAN-based
farms.
Note Data in the following sections was gathered from tests performed using a
Microsoft SQL 2000 data store. These results might not apply to all situations
and recommendations vary based upon how much bandwidth is being used by
other network applications.

Communication during Initial Farm Startup


The amount of data (in kilobytes) read from the data store during the initial
startup of the server farm is approximated by the following formulas:

Citrix Presentation Server 4.0: 436 + 3.15*(Srvs-1)

MetaFrame Presentation Server 3.0: 431 + 3.15*(Srvs-1)

MetaFrame XPe / Feature Release 3: 402 + 6.82*(Srvs-1) where:


Srvs = the number of servers in the farm
Apps = the number of published applications in the farmin MetaFrame XP
Feature Release 3 and later the number of published applications no longer
applies to the equation.

The following diagram shows the initial startup of a server farm:

When you start a server, it must initialize the IMA Service and also register with
the data collector for the zone in which it resides. This communication occurs in
the following sequence of events:

The IMA Service establishes a connection to the farms data store and then
downloads the information it needs to initialize. It also ensures that the data
contained in its local host cache is current.

After the IMA Service is initialized, the member server registers with the data
collector for the zone.

Next, the data collector relays all of the updated information written by the member
servers in the zone to all other data collectors in the farm to keep them synchronized
with each other. The collector-to-collector updates are a function of the amount of
information that is updated by the member server. The data collectors replicate only the
items that changed; they do not replicate all their tables every time an update is sent.
Note In the preceding diagram, there are only two zones. The data collector
replicates only the updates it receives from the member servers once to the other
data collector. If, for example, there are three zones, the data collector has to
replicate the same information twice. This causes higher bandwidth
consumption and places a higher load on the data collectors in the farm.

The amount of data read from the data store can require higher bandwidth as the
farm size increases and certain actions are executed, especially when several
servers are started simultaneously. Most network traffic consists of reads from
the database. Citrix recommends that the data store be replicated across all highlatency or low-bandwidth links. A replicated data store allows all reads to occur
on the network local to the server, resulting in improved farm performance.
If performance across the WAN is an issue, and having a replicated database at
each site is cost prohibitive, consider a QoS solution. The IMA Service start time
ranges from a few seconds to several minutes. When the amount of data
requested from the data store by the IMA Service is greater than the size of the
pipe between WAN segments, IMA waits for all of the data, resulting in a longer
startup time.
Note When the IMA Service takes a long time to restart, an error message
appears on the Presentation Server Console stating that the IMA Service could
not be started. The event log can have a message that states that the IMA Service
hung on starting. These errors are benign. The IMA Service does start correctly
after the requests to the data store are serviced.

Ordinary Farm Communication


The following figure shows the communication that occurs within a farm when it
is up and running:

Every 30 minutes a coherency check is performed between the member servers local
host cache and the data store. If neither has changed, this operation consumes
approximately only 500 bytes of bandwidth. If the check determines that something
changed, the member server searches the data store to determine what changed and
updates the information in the local host cache.

To ensure that the servers in its zone are functional, the data collector sends an
IMAPing to each of the member servers in its zone if it has not received an update
from the member server within the last 60 seconds. The data collector also asks the
member server for its server load if it has not received a load update within the past
five minutes.

Finally, the data collectors query the other data collectors in the farm to ensure they are
still data collectors, and to ensure they are still operational if they have not received an
update in the last 60 seconds.

Event-Based Communication
Most traffic is a result of the generation of events, such as when a client connects,
disconnects, or logs off. The member server sends updates to the data collector in
its zone. The data collector in turn must replicate this information to all the other
data collectors in the farm.
The following diagram shows what occurs when a user logs on:

The client device requests that the data collector determine the least loaded servers
in the farm.

The client then connects to the least loaded server returned by the data
collector.

The member server then updates its information to the data collector for its zone.

The data collector then forwards this information to all the other data collectors in the
farm.

New Data Collector Election


When a server in the farm is unable to communicate with the zone data collector,
a process is initiated to elect a new data collector.
The following diagram shows an example of what occurs in a farm after a new
data collector is elected:

The existing data collector for Zone 1 has an unplanned failure, such as a RAID
controller failing, and causes the server to present a fatal error. If the server is shut
down correctly, it triggers the election process before going down.

The servers in the zone recognize the data collector has gone down and start the
election process. In this example, the backup data collector is elected as the new data
collector for the zone.

The member servers in the zone send their information to the new data collector for the
zone.

In turn, the new data collector replicates this information to all other data
collectors in the farm.
Note The data collector election process is not dependent on the data store. If
the data collector goes down, sessions connected to other servers in the farm are
unaffected.

Local Host Cache Change Events


When configuration changes are made in the Presentation Server Console, the
changes are propagated across the farm using notification broadcasts. These
broadcasts take place when a change is made that is under 64KB in size, which is
usually the case. These broadcasts help to minimize WAN traffic and alleviate
contention on the data store. If a server misses a change notification, it picks up
the change the next time it does a local host cache coherency check.
Note In Presentation Server 3.0 and earlier, the broadcast would occur if
the change was under 10KB in size.
The following diagram shows an example of local host cache change events
communication:

The administrator makes a change in the Presentation Server Console affecting all the
servers in the farm.

The server that the console is connected to updates its local host cache and writes
the change to the data store.

The server forwards the change to the data collector for the zone in which it resides.
The data collector updates its local host cache.

The data collector forwards the change to all the member servers in its zone and all
other data collectors in the farm. All servers update their local host caches with the
change.

The data collectors in the other zones forward the update to all the member servers
in their zones, and they subsequently update their local host caches.

Citrix Presentation Server Console Communication


When the Presentation Server Console is launched, it gathers information from
several different sources. It pulls static information such as the server list from
the data store, dynamic data session information from the data collector, and
Resource Manager-specific information from the farm metric server.
The following table illustrates consumption of bandwidth to the data store when
the following actions are performed using the console:

Citrix Presentation Server 4.0


Action

Data transmitted (in KB)

Open Presentation Server Console

462.49

Server enumeration (one server)

Server details (one server)

244.72

Application enumeration (one application)

7.62

Application query

150.11

Publish Resource Manager application

60.3

Change farm metric server

17.9

Any Resource Manager report on the


local server

5.46

MetaFrame Presentation Server 3.0


Action

Data transmitted (in KB)

Server enumeration (one server)

Server details (one server)

169.88

Server query

26.10

Application enumeration (one application)

11.97

Application query

145.06

Add Resource Manager metric to application

11.33
21.95

Add Resource Manager metric to


application and configure
Change farm metric server

15.88

Any Resource Manager report on the


local server

6.58

MetaFrame XPe / Feature Release 3


Action

Data transmitted (in KB)

Server enumeration (one server)

0.66

Server details (one server)

14.31

Server query

7.13

Application enumeration (one application)

0.71

Application query

15.57

Add Resource Manager metric to application

3.69

Add Resource Manager metric to


application and configure

6.76

Change farm metric server

5.29

Any Resource Manager report on the


local server

1.56

Implementing the Data Store


The following sections discuss network optimizations for the data store and
setting up the data store in a Storage Area Network (SAN).

Data Store Network Optimizations


In large farms with powerful database servers, the network can become a
performance bottleneck when reading information from the data store. This is
particularly true when the database server hosts various resource-intensive
databases. Especially in large environments, the database server should not host
databases that are not associated with Presentation Server.
To find out if the network is the bottleneck, monitor the CPU usage on the data
store. If the CPU usage is not at 100% while the IMA Service is starting, and it is
still in the process of starting, the network may be the bottleneck. If the CPU
utilization is at or near 100%, it is likely that additional processors may be
needed.

Loss of Connectivity to the Data Store


In MetaFrame XP Feature Release 3 and earlier versions, if a farm member
server is unable to contact the data store for more than 96 consecutive hours,
licensing stops functioning on the member server and connections are disabled.
Connections to Presentation Server 3.0 and later are not dependent on
connectivity to the data store. After installation, the server makes an initial
connection to the data store to obtain the name and port number for license
server communication. Provided the server is able to connect to the license
server, or is within the grace period following a loss of connectivity to the license
server, a loss of connectivity to the data store results in the following:

Users can still log on

Administrators cannot make changes to the farm, such as adding, removing, or


modifying the properties of published applications using the Presentation Server
Console
Note Data collectors are not the only servers that communicate with the data
store. IMA on all the servers must be initialized with the same settings regardless
of the role of the server. Also, when the Presentation Server Console is opened, it
connects to a specified server. This servers IMA Service performs all reads and
writes to the data store for the Presentation Server Console. Most changes made
through the Presentation Server Console are written to the data store.

User connections to Presentation Server 3.0 and later require a connection to the
license server. If a farm member server loses connectivity to the license server,
the member server enters into a grace period. During this grace period logons
are not affected, but after the grace period expires, all user connections are
denied and only one administrator logon is granted.
Note Effective August 19th, 2004, Citrix increased the license server grace
period from four days (96 hours) to 30 days. If you obtained your license file
before this date, by reallocating your license files you can take advantage of the
30-day grace period. See Citrix Knowledge Base article CTX104782 for more
information.

Implementing the Data Store in a Storage Area Network


A Storage Area Network (SAN) is a dedicated high-speed network that is
separate and distinct from the Local Area Network (LAN). A SAN provides
shared storage through an external disk storage pool. The SAN is a back-end
network that carries only I/O traffic between servers and a disk storage pool
while the front-end network, the LAN, carries email, file, print, and Web traffic.
Implementing your server farms data store in a SAN can provide increased
reliability and improved performance.

Fibre Channel Technology


The most commonly used SCSI technology for SAN implementations is Fibre
Channel. Fibre Channel is the standard for bidirectional communications and it
features high performance, serial-interconnections.
Fibre Channel has the following capabilities:

Bidirectional data transfer rates up to 200Mbps

Support for up to 126 devices on a single host adapter

Communications up to 20km (approximately 12 miles)

Fibre Channel implementations can use either of the following networking


technologies:

Fibre Channel Arbitrated Loop (FC-AL)


FC-AL networks use shared media technology similar to Fibre Distributed
Data Interface (FDDI) or Token Ring. Each network node has one or more
ports that allow external communication; FC-AL creates logical point-topoint connections between ports.

Fibre Channel Fabric (FC-SW)


Fabric networks use switched network technology similar to switched
Ethernet. A fabric switch divides messages into packets containing data and a
destination address, and then transmits the packets individually to the
receiving node, which reassembles the message. Fabric switches can cascade,
allowing a SAN to support thousands of nodes.

Hardware Components
Storage Area Networks typically include the following hardware components:

Host I/O Bus


The current I/O bus standard is Peripheral Component Interface (PCI). Older
standards include Industry Standard Architecture (ISA) and Extended
Industry Standard Architecture (EISA).

Host Bus Adapter


The host bus adapter (HBA) is the interface from the server to the host I/O
bus. The HBA is similar in function to a Network Interface Card (NIC), but is
more complex.
HBA functions include the following:

Converting signals passed between the LAN and the SANs serial SCSI

Initializing the server onto an FC-AL network or providing a Fabric network logon

Scanning the FC-AL or Fabric network, then initializing all connected devices
in the same way that parallel SCSI scans for logical devices at system startup

Cabling
Fibre Channel cables include lines for transmitting and for receiving.
Because of the shape, you cannot install them incorrectly.

SAN networking equipment


There are many similarities between a SAN and other networks such as a
LAN. The basic network components are the same: hubs, switches, bridges,
and routers.

Storage devices and subsystems


A storage subsystem is a collection of devices that share a power distribution,
packaging, or management system such as tape libraries or RAID disk drives.

Tape backup
SANs provide easy, on-the-fly tape backup strategies. Tape backups are much
quicker and consume fewer resources, because all of the disk access occurs on
the SANs fiber network, not on the LAN. This allows the data store to be
backed up easily even while it is in use.

Cluster Failover Support


The data store is an integral part of the Presentation Server architecture. In large
enterprise environments, it is important to have the database available at all
times. For maximum availability, place the data store in a clustered database
environment with a SAN backbone.
Hardware redundancy allows the SAN to recover from most component
failures. Additional software such as Oracle 9i Real Application Cluster or SQL
Server 2000, utilizing Microsoft Clustering Services (MSCS), allows for failover
in a catastrophic software failure, and in Oracles case, improves performance.
Note Software such as Compaq's SANWorks may be required to manage
database clusters in certain hardware configurations.
Microsoft Clustering Services (MSCS) provides the ability to failover the data
store to a functioning server in the event of a catastrophic server failure. MSCS is
available on Windows 2000 Advanced Server and DataCenter products, and
Windows Server 2003. Citrix recommends this type of configuration even when
a SAN is not being deployed.
MSCS monitors the health of standard applications and services, and
automatically recovers mission-critical data and applications from many common
types of failures. A graphical management console allows you to monitor the
status of all resources in the cluster and to manage workloads accordingly. In
addition, Windows 2000 Server and Windows Server 2003 integrate middleware
and load balancing services that distribute network traffic evenly across the
clustered servers.
Redundancy and recovery can be built into each major component of the data
store. Deploying the following technologies can eliminate single points of failure
from the data store:

Microsoft Clustering Services

Redundant hardware

Software monitoring and management tools

The basic SAN configuration shown in the figure Redundant SAN


configuration illustrates each clustered server with dual HBAs cabled to
separate FC-AL switches. A system with this redundancy can continue running
when any component in this configuration fails.

Redundant SAN configuration


SAN architecture is very reliable and it provides redundant systems in all aspects
of the configuration with multiple paths to the network. Windows 2000
Advanced Server allows two nodes to be clustered. Windows 2000 Data Center
allows four clustered nodes.
If there is a software or hardware failure on the owner of the cluster node, the
servers in the farm lose their connection to the database. When the servers sense
that the connection is dropped, the farm goes into a two-minute wait period. The
servers then reconnect to the database. If servers in the farm cannot immediately
reconnect to the data store, they retry indefinitely, every two minutes. The
servers automatically reconnect to the database, which has the same IP address,
after it fails over to the other node of the cluster.

SQL Server
SQL Server clustering does not mean that both databases are active and load
balanced. With SQL clustering, the only supported clustering method allows one
server to handle all the requests while the other server simply stands by waiting
for the other machine to fail.
Note Citrix recommends that you use Windows NT authentication for
connecting to the database when installing Presentation Server to a clustered SQL
Server.

Oracle
Oracle Real Application Cluster (RAC) does allow true active-active clustering.
As database requests are sent using ODBC, they are load balanced among the
nodes of the cluster. This configuration provides both fault tolerance and
increased performance.

SAN Tuning
In addition to increased reliability, you can tune the SAN to provide better
database performance. When tested by Citrix, the data store was used mainly as a
repository for reading configuration information. In this configuration, the
number of reads far exceeds the number of writes. For optimal data access to the
data store through the SAN, you can tune the array controller on the SAN for
100% reads and 0% writes.
Note Tuning the SAN for 100% reads and 0% writes still allows servers to
write to the data store.

Teaming Network Interface Card Configurations


To avoid a potential network bottleneck, Citrix recommends that you use a
teaming Network Interface Card (NIC) solution to improve Presentation Serverrelated communications. NICs and always manually configure switch ports to
support full duplex and the highest speed available on both devices. This is
because the automatic sensing of router settings by the NICs and switch ports
does not always result in an optimal or compatible configuration. If the speed or
duplex settings are configured incorrectly, frames are dropped.
Many servers come with two installed NIC ports. These NICs can be configured
as follows, listed in the order of Citrix's recommendation:

Utilize both NICs and team using switch-assisted load balancing within the same
subnet if connecting to different blades within a large Layer 3 switch

Utilize both NICs and team using adaptive load balancing within the same subnet
if connecting to different blades within a large Layer 3 switch

Utilize both NICs and configure for failover onto two separate switches

Utilize one NIC and disable the second

Utilize both NICs and multihome to two different subnets

If two NIC and switch ports are available, these can be teamed, configured for
failover, or multihomed. Of these two options, Citrix recommends that you use
NIC teaming when the switch ports are located on different blades within a large
Layer 3 switch (for example, Cisco 6500 series) because NIC teaming enables
both failover and redundancy in addition to higher throughput.
Although the Layer 3 switch does represent a single point of failure in this case,
most large Layer 3 switches have an extremely low failure rate. More commonly,
an individual blade may fail. If a large Layer 3 switch that supports teaming
across blades is not available, a failover configuration is the best option. While
multihoming is a supported practice, NIC teaming is considered to be the better
option in nearly all situations. Multihoming is often configured incorrectly, and
security holes could be opened because access control lists configured on the
router are bypassed.
If it is not feasible to team the NICs and switch ports of all of the servers in
the farm, Citrix recommends that you apply this recommendation to the
following servers at a minimum:

Data store server(s)

Web Interface server(s)

Secure Gateway server(s)

License server

Citrix Access Gateway server(s)

Zone data collector(s)

Note Citrix recommends teaming NICs using the MAC address, not the IP
address because the MAC address is not subject to modification unless the
burned- in address (BIA) is modified, The MAC address is a more basic and
stable configuration. Follow the switch vendor's recommended practice for
manually configuring teaming or aggregating of the switch ports.

Network Fault Tolerance


Network fault tolerance functions as a failover option and provides the safety of
an additional backup link between the server and the switch. If the primary
adapter fails, the secondary adapter takes over with very minor interruption in
server operations. When tested by Citrix, failover caused an interruption of less
than 0.5 seconds and did not provide any noticeable impact on existing client
sessions.

Transmit Load Balancing


This option, formerly known as adaptive load balancing, creates a team of
adapters to increase transmission throughput and ensure that all network users
experience similar response times. All adapters must be linked to the same
network switch. As adapters are added to the server, they are grouped in teams to
provide a single virtual adapter with increased transmission bandwidth. For
example, a transmit load balancing team containing two Fast Ethernet adapters
configured for full-duplex operation provides an aggregate maximum transmit
rate of 200Mbps and a 100Mbps receive rate resulting in a total bandwidth of
300Mbps. One adapter is configured for transmit and receive, while the others are
configured for transmit only. Adapter teams configured for transmit load
balancing provide the benefit of network fault tolerance because if the primary
adapter that supports both transmit and receive fails, another adapter then
supports this functionality.

Switch-Assisted Load Balancing


Citrix tested data store connectivity on a 100Mbps switched LAN. This testing
was also repeated in a Gigabit Ethernet environment. It was found that two NICs
that were teamed using switch-assisted load balancing; that is, 400Mbps
throughput, provided ample throughput without the additional cost associated
with gigabit NICs, cables, and switch ports. However, in very large
environments, gigabit connectivity may be beneficial.
Unlike transmit load balancing, you can configure switch-assisted load balancing,
also known as Fast EtherChannel, to increase both transmitting and receiving
channels between the server and switch. For example, a Fast EtherChannel team
containing two Fast Ethernet adapters configured for full-duplex operation
provides an aggregate maximum transmit rate of 200Mbps and an aggregate
maximum receive rate of 200Mbps, resulting in a total bandwidth of 400Mbps.
All adapters are configured for transmit and receive, with the load spread roughly
equal.
Fast EtherChannel works only with Fast EtherChannel-enabled switches. The
Fast EtherChannel software continuously analyzes load on each adapter and
balances network traffic across the adapters as needed. Adapter teams
configured for Fast EtherChannel not only provide additional throughput and
redundancy but also provide the benefits of network fault tolerance. For more
information, see Citrix Knowledge Base article CTX434260 and/or contact your
hardware vendor.

Multihoming Servers in the Farm


Presentation Server includes support for multihomed servers. This section
explains how to implement Presentation Server on a server operating with two or
more network interface cards (NICs). It is important that you implement
multihoming exactly as it is described in the following sections. Also, review the
security of your environment to ensure that networks that are accessed do not
bypass routers or other security devices.
To provide access to two network segments with no direct route to each, you can
run Presentation Server on multihomed servers. Because each separate network
uses the same resources, the networks can access the same server farm.
Running Presentation Server on multihomed servers also allows you to separate
server-to-server communication from client-to-server communication. This
scenario is illustrated in the figure and is the subject of the examples in this
section.

Note Citrix recommends that you do not configure multihomed servers


running Presentation Server to operate as routers (TCP/IP forwarding).

Configuring the Routing Table


To run Presentation Server successfully on multihomed servers, you may need to
configure the local routing tables manually. When Windows automatically builds
the servers routing tables, the resulting network card binding order and default
gateway configuration may not meet your needs. For information about changing
the default gateway, see Configuring a Default Gateway on page 47.
When clients request a server name or published application, the server that
receives the request returns the TCP/IP address of the appropriate server.
The following requests from clients require address resolution:

Finding the address of the data collector

Finding the TCP/IP address of a given server name

Finding the TCP/IP address of the least loaded server for a published
application
When a server receives an address resolution request from a client, the server
compares the TCP/IP address of the client to its local routing table to determine
which network interface to return to the client. If the routing table is not
configured correctly, the clients request cannot be filled.
The preceding figure illustrates two multihomed servers, each with a connection
to the 10.8.1.0/24 and 172.16.1.0/24 subnets. Neither server is configured to
route between the two network interfaces.
When a client requests a response from a computer running Presentation Server:

The client with TCP/IP address 10.8.2.20 (ICA01) sends an address resolution request
to the server named MFSRV01.

MFSRV01 has the TCP/IP address 10.8.1.3. This server also has a second NIC with
TCP/IP address 172.16.1.3.

ICA01 is configured with MFSRV01 for its server location. ICA01 contacts
MFSRV01 and requests a load-balanced application.

The TCP/IP address of the least loaded server hosting the requested published
application must be supplied to ICA01. MFSRV01 determines that MFSRV02 is the
least loaded server.

MFSRV02 has two TCP/IP addresses, 10.8.1.4 and 172.16.1.4.

MFSRV02 determines the source address of ICA01. The server uses its local routing
table to determine what network interface should be returned to the client. In this case,
the NIC configured on the 10.8.2.0/24 network is returned to the client. If there is no
explicit entry for the NIC in the local routing table, the default route, configured
automatically by Windows, is used.

MFSRV01 uses the local routing table to correctly respond with the 10.8.1.4 address
when directing the client to MFSRV02.
To set up a routing table on a multihomed server running Presentation Server,
first configure a single default gateway and then add static routes.

Configuring a Default Gateway


Although Windows servers build multiple default gateways, the network
binding order of the NICs in the server determine which default gateway to use.
Using the example illustrated in the preceding figure, we selected the 10.8.1.1
address as our default gateway. However, we must move the network card
operating on the 10.8.1.0/24 network to the first position in the network binding
order.
There may be certain environments where the configuration of the network
binding order is not sufficient for the server to function correctly. For example, if
you have a server with two connections to the Internet where each connection
provides ICA connectivity for a diverse range of IP subnets, the server uses only
the default gateway of the first NIC in its network binding order (referred to as
Network 1).
If the server receives a request from a client on its second NIC (Network 2) that
is not the default gateway, and there is no entry in the local routing table of the
server for Network 2, the response to the client request is sent through Network
1, which causes the clients request to fail.
Alternatively, you can remove the additional default gateway configurations from
each NIC on the server. This is done through the servers TCP/IP configuration.
Using servers MFSRV01 and MFSRV02 from our example, we selected 10.8.1.1
as our default gateway for both servers and removed the default gateway setting
from the NICs operating on the 172.16.1.0/24 network.

Running the command line utility IPCONFIG on MFSRV01 returns the following:
Windows IP Configuration
Ethernet adapter Local Area Connection #1: Connectionspecific DNS Suffix
IP Address. . . . .
Subnet Mask . . . .
Default Gateway . .

.
.
.
.

:
. . . . . . : 10.8.1.3
. . . . . . : 255.255.255.0
. . . . . . : 10.8.1.1

Ethernet adapter Local Area Connection #2:


Connection-specific
IP Address. . . . .
Subnet Mask . . . .
Default Gateway . .

DNS
. .
. .
. .

Suffix . :
. . . . . : 172.16.1.3
. . . . . : 255.255.255.0
. . . . . :

Running IPCONFIG on MFSRV02 returns the following:


Windows IP Configuration
Ethernet adapter Local Area Connection #1:
Connection-specific
IP Address. . . . .
Subnet Mask . . . .
Default Gateway . .

DNS
. .
. .
. .

Suffix
. . . .
. . . .
. . . .

.
.
.
.

:
: 10.8.1.4
: 255.255.255.0
: 10.8.1.1

Ethernet adapter Local Area Connection #2:


Connection-specific
IP Address. . . . .
Subnet Mask . . . .
Default Gateway . .

DNS
. .
. .
. .

Suffix
. . . .
. . . .
. . . .

.
.
.
.

:
: 172.16.1.4
: 255.255.255.0
:

Adding Static Routes


You can define static, persistent routes to avoid potential routing conflicts.
Depending on your network configuration, adding static routes may be the only
way to provide ICA connectivity to a multihomed server. The following data
uses the example illustrated in the preceding figure.
Executing the ROUTE PRINT command from a command prompt on the routing
table on MFSRV01 returns the following:

Network Destination

==========================================================================
Interface List
0x1 ........................... MS TCP Loopback interface
0x2 ...00 a0 c9 2b f8 dc ...... Intel 8255x-based Integrated Fast Ethernet
0x3 ...00 c0 0d 01 12 f5 ...... Intel(R) PRO Adapter
==========================================================================
==========================================================================
Active Routes:
Netmask
Gateway
Interface Metric
0.0.0.0
0.0.0.0
10.8.1.1
10.8.1.3 1
10.8.1.0
255.255.255.0
10.8.1.3
10.8.1.3 1
10.8.1.3 255.255.255.255
127.0.0.1
127.0.0.1 1
10.255.255.255 255.255.255.255
10.8.1.3
10.8.1.3 1
127.0.0.0
255.0.0.0
127.0.0.1
127.0.0.1 1
172.16.1.0
255.255.255.0
172.16.1.3
172.16.1.3 1
172.16.1.3 255.255.255.255
127.0.0.1
127.0.0.1 1
172.16.1.255 255.255.255.255
172.16.1.3
172.16.1.3 1
224.0.0.0
224.0.0.0
10.8.1.3
10.8.1.3 1
224.0.0.0
224.0.0.0
172.16.1.3
172.16.1.3 1
255.255.255.255 255.255.255.255
10.8.1.3
10.8.1.3 1
Default Gateway:
10.8.1.1
==========================================================================
Persistent Routes:
None

MFSRV01 is currently configured with a default gateway using the router at


10.8.1.1. Note that the second client, ICA02, is located on the 192.168.1.0/24
network, which is accessed through the router at 172.16.1.1. For MFSRV01 to
have network connectivity and to avoid using the default gateway when
responding to requests from ICA02, define a static route for the 192.168.1.0/24
network:
ROUTE -p ADD 192.168.1.0 MASK 255.255.255.0 172.16.1.1

Executing ROUTE PRINT on MFSRV01 now returns:


===========================================================================
Interface List
0x1 ........................... MS TCP Loopback interface
0x2 ...00 a0 c9 2b f8 dc ...... Intel 8255x-based Integrated Fast Ethernet
0x3 ...00 c0 0d 01 12 f5 ...... Intel(R) PRO Adapter
===========================================================================
===========================================================================
Active Routes:
Network
Netmask
Gateway
Interface Metric
Destination
0.0.0.0
0.0.0.0
10.8.1.1
10.8.1.3 1
10.8.1.0
255.255.255.0
10.8.1.3
10.8.1.3 1
10.8.1.3 255.255.255.255
127.0.0.1
127.0.0.1 1
10.255.255.255 255.255.255.255
10.8.1.3
10.8.1.3 1
127.0.0.0
255.0.0.0
127.0.0.1
127.0.0.1 1
172.16.1.0
255.255.255.0
172.16.1.3
172.16.1.3 1
172.16.1.3 255.255.255.255
127.0.0.1
127.0.0.1 1
172.16.1.255 255.255.255.255
172.16.1.3
172.16.1.3 1
192.168.1.0
255.255.255.0
172.16.1.1
172.16.1.3 1
224.0.0.0
224.0.0.0
10.8.1.3
10.8.1.3 1
224.0.0.0
224.0.0.0
172.16.1.3
172.16.1.3 1
255.255.255.255 255.255.255.255
10.8.1.3
10.8.1.3 1
Default Gateway:
10.8.1.1
===========================================================================
Persistent Routes:
Network Address
Netmask Gateway Address
Metric 192.168.1.0
255.255.255.0 172.16.1.1
1

Configure MFSRV02 the same way. When the static routes are set up, both the
clients can ping the TCP/IP addresses of both servers and the servers can ping the
clients.
Each server can now correctly resolve the network interface to which either
client is connecting. The TCP/IP addresses that the ICA01 client can receive are
10.8.1.3 and 10.8.1.4. The TCP/IP addresses that the ICA02 client can receive
are
172.16.1.3 and 172.16.1.4

CHAPTER 4

Deploying Citrix Presentation


Server

This chapter discusses various issues related to the deployment of Presentation


Server and Presentation Server Clients. When installing or upgrading
Presentation Server, there are certain updates and other considerations that you
must be aware of. Also covered here are various methods for rapidly deploying
Presentation Server, client deployment issues, and the consolidation of license
files.

Installation/Upgrade Considerations
The following section contains some considerations to be aware of when
installing or upgrading to Presentation Server 3.0 or 4.0.

Presentation Server 3.0 and 4.0 require communication with a Citrix license server.
The license server can be installed in the environment before or after Presentation
Server is installed and the name of the Citrix license server can be provided either
while you are installing or after installation in the Presentation Server Console.

When upgrading a farm that uses Microsoft Access as the data store, always
upgrade the host server first or installation fails.

Servers running Presentation Server should not provide any additional services, such as
DHCP, DNS, and WINS. These services require additional server resources that reduce
user performance. All available server resources must be dedicated to support
Presentation Server and its associated applications.

Secure Sockets Layer (SSL) settings are intentionally not migrated for security
reasons. When upgrading to Presentation Server 3.0 or 4.0, reconfigure SSL manually.

You can install or upgrade in silent mode using: msiexec /i MPS.msi /qn. If you are
using unattended installation or command-line parameters to install Presentation Server,
a log file (Msi.log) is automatically created in the
%SystemRoot% directory.

5
2

Advanced Concepts
Guide

If upgrading a server that does not have Installation Manager and Resource Manager
installed, these components are not installed during the upgrade. To install these
components, verify that an Enterprise edition license is present on the Citrix license
server, and install these components using the Add/Remove Programs applet in the
Control Panel.

Citrix recommends that Presentation Server not be installed on a domain controller.


(Service Pack 2005.04 for Presentation Server 3.0 and Presentation Server 4.0 cannot
be installed on domain controllers). Domain controllers replicate the Active Directory
database and other data, as well as provide user authentication, and thus have heavy
network and processing requirements. More importantly, the security holes that may
be opened by allowing users to access applications loaded onto a domain controller
should be carefully considered. See Citrix Knowledgebase article CTX106529 for
more details.

The installation of Presentation Server 3.0 or 4.0 is a platform upgrade. After you
install either of these versions of Presentation Server you cannot downgrade to earlier
versions.

Obtaining Installation and Updates Information


Before you install Presentation Server, Citrix recommends that you read the
Installation Checklist and the Pre-installation Update Bulletin.

Installation Checklist
The Installation Checklist can be viewed by selecting View installation
checklist on the Presentation Server Setup window that appears after inserting
your installation CD. It outlines, among other items:

Downloading and installing critical updates before you install the product

Meeting system requirements

Installing and configuring the Access Suite licensing

Remapping server drive letters

Installing Presentation Server

Downloading and installing critical updates after you install the product

Pre-installation Update Bulletin


The Pre-installation Update Bulletin for MetaFrame Presentation Server 3.0 and
the Citrix Access Suite 4.0 Pre-installation Update Bulletin offer late-breaking
information and links to critical updates to server operating systems and to Citrix
installation files. These updates may be required to install or run the product and
should be applied prior to installation. Information regarding the required
updates can be found on the Pre-installation Update Bulletin. A link to the
bulletin is available on the Installation Checklist. The bulletin is divided into
three sections:

Pre-Installation Updates. Follow the instructions in Step 1 of the bulletin to download


and install the updates to Microsoft operating system components required to install or
run the product. Links to both the Microsoft Knowledge Base articles and patches for
download are provided. Read the Knowledge Base articles for descriptions of the
updates.

Installation Updates. Follow the instructions in Step 2 of the bulletin to download and
apply critical updates to Citrix installation packages. After downloading and executing
the update package, the Critical Update wizard guides you through the process of
applying the update to the Citrix components. The Critical Update wizard creates a
modified administrative image of the original CD-ROM of Presentation Server for
Windows on your hard drive. To install Presentation Server, use the modified
administrative image containing the critical installation updates instead of the original
CD-ROM.

Post-Installation Updates and the Critical Updates Web Page. Follow the instructions in
Step 3 of the bulletin to download and install critical post- installation hotfixes. The
instructions in Step 3 of the bulletin direct you to the Critical Updates Web page from
which you can download the hotfixes. Visit the Critical Updates Web page frequently
to determine if any critical hotfixes have been released by Citrix.

Remapping Server Drives


To change server drive letters during installation, choose the Remap Drives
option from the Autorun screen. If you are upgrading from an earlier release, the
Remap Drives option is not available and your existing drive mapping is
preserved for the upgrade.
To modify an existing drive mapping, run the DriveRemap utility
(DriveRemap.exe) located in the root folder of the Presentation Server CD. When
running DriveRemap.exe without parameters, the drive letter choices in the pull
down list may be grayed out because the existing drive letters cannot be
remapped. For more information, refer to Citrix Knowledge Base article
CTX950520.
Note Applications that hard code drive C for installation may not install or
function correctly with remapped drives. Consider using an isolation
environment for these applications.

Note Driveremap.exe does not remap hidden (administrative) shares listed in


the registry. For example, if you install Trend ServerProtect on Windows Server
2003 and view the registry value:
HKEY_LOCAL_MACHINE\SOFTWARE\TrendMicro\ServerProtect\
CurrentVersion\UncHomeDirectory, the value is similar to:
\\%computername%\c$\Program Files\Trend\SProtect. If you remap the server
drive at this point, this registry value is not modified.

Rapid Deployment of Citrix Presentation Server


Having a means of quickly rebuilding a server running Presentation Server helps
to minimize the impact that failures have on your users. An automated process
can provide the fastest and most efficient means of building or rebuilding a
server. For example, it is often faster to rebuild a server with an automated
mechanism than to troubleshoot. This section covers practices regarding rapid
deployment of Presentation Server in the enterprise environment, including the
use of blade servers, server cloning, and simultaneous installations.

Using Blade Servers in a Server Farm


The use of blade servers in your farm is an ideal fit for Presentation Server.
Blade servers have been introduced by most of the major server hardware
vendors. They offer a wide range of options depending on the vendor from SAN
connectivity, to storage blades, to unique imaging solutions.

Blades and Imaging


Most blade servers ship with some form of imaging software, that offers image
capture and deployment to servers. A base image can be installed on a single
machine, stored on the image server, and can then be deployed to all other like
servers in your data center.
You can image the base operating system and have the imaging software
perform an unattended install of Presentation Server using an answer file, or you
can image the system with Presentation Server already installed.
Important If you want to have remapped drives on the server running
Presentation Server, run the drive remap utility after the imaging process is
complete.

Scripting Configuration after Imaging


If a cloned version of Presentation Server is deployed, you must reconfigure
some settings to allow Presentation Server to function correctly.
Most imaging software suites allow the administrator to define scripts to be run
on the server after imaging completes. MetaFrame XP Feature Release 3 and later
includes a utility, Apputil, that adds a server to the Configured Servers list of a
published application. If the application does not exist on the server, Apputil can
also be used to deploy the application as an Installation Manager package.
With this utility, you can script various different configurations of an installation
depending on the application silo in which it resides. After the machine is imaged,
the script executes and the Installation Manager package is deployed to the
server.
The MFCOM SDK also allows scripting of other configuration options through
most kinds of scripting languages. Through the MFCOM SDK, new applications
can be published, the data collector preference level can be set, load evaluators
applied, and so on. This allows the Presentation Server configuration changes to
be applied rapidly as well. See the MFCOM SDK documentation for scripting
usage.

Rip and Replace


In the event of a hardware failure, blade servers provide the opportunity to replace
the server blade experiencing the failure with a new one. Presentation Server can
then be imaged back to the new blade. If the blade server assumes the same
name, it continues to function in the same capacity as the previous server running
Presentation Server.

Server Cloning
Server cloning can provide more rapid deployment than a scripted installation. A
few steps are required for cloning servers. These steps vary depending on the
type of data store used for the farm, and are described in the following sections.
Presentation Server is compatible with server cloning, but cloning software can
cause the operating system or its add-ons to function incorrectly after being
cloned. When using server cloning, it is important to clone one server and test its
functionality before deploying the rest of the farm. Also, although Citrix supports
server cloning if done by documented procedures, it is considered a best practice
to use an automated installation process for building and rebuilding servers so that
a clean server build is assured.
Caution Do not image a server with an SSL certificate installed because
SSL certificates are unique to the hardware.

Issues to Consider before Cloning a Server


Zone settings are not retained when cloning a server. When the Citrix IMA
Service on the cloned server starts for the first time, the server joins the default
zone. The name of the default zone is the ID of the subnet on which the cloned
server resides. When deploying images to servers on multiple subnets, assign
zone information for each server after the imaging process completes.
Prior to changing the Security ID (SID) on the machine used to access
the Presentation Server Console, add one of the following user accounts
as an administrator with full privileges:

A domain administrator

The local administrators group

A local administrator from a machine where the SID is not being changed

You must complete the following tasks before re-imaging a server that is already
a member of a server farm.
To prepare a server in a server farm for re-imaging
1. From the Presentation Server Console, remove the list of servers configured to host any
applications.
2. Remove the server from the server farm by uninstalling Presentation Server.
3. If the server entry still exists in the Presentation Server Console server list, right-click the
server name and remove it from the server list.
4. Apply the system image and add the server to the server farm.

Important If a server is not removed from a server farm before a new system
image is applied to it, performance problems can result. The Presentation Server
Console can display invalid data if the server is returned to the same server farm
because the old servers host record in the data store is applied to the newly
imaged server.
If cloning is not an option, you can create custom unattended installation scripts
for both the operating system and applications, including Presentation Server.
Note Removal of the WSID (workstation ID) line from the DSN file is no
longer necessary when imaging and deploying Presentation Server.

Rapid Deployment with Microsoft Access or MSDE


When using Microsoft Access or MSDE, you must install the first server in the
new server farm that hosts the data store. You can image the second server in the
farm for the deployment of additional servers.
To image a server for rapid deployment with Access
1. Install the first server in the farm.
2. Install a second server in the farm with an indirect connection to the data store you created on
the first server.
3. With the second server successfully installed and restarted, log on to the console of the second
server as a local or domain administrator.
4. On the second server, delete the Wfcname.ini file, if it exists, from the root drive of the server.
5. Stop the Citrix IMA Service using the Services Control Panel. Set the start up type to manual.
6. If Presentation Server, Enterprise Edition components are installed, see Cloning Citrix
Presentation Server Enterprise Edition Systems on page 59.
7. Take the image of the second server and then restart the second server.
8. Deploy the image obtained in Step 7.
Important It is important that some type of SID generation utility be
executed when deploying Windows 2000 Server or Windows Server 2003
images.

To set up the server and verify that it is added


1. Set the SID of the server with your chosen SID generator.
2. Rename the new server with a unique name.
3. Start the Citrix IMA Service and set the service to start automatically.
4. Verify that the server is successfully added to the farm by executing qfarm at a command
prompt. If the addition is successful, the newly imaged server appears in the list of servers.

Rapid Deployment with Microsoft SQL Server, Oracle, or IBM DB2


When using Microsoft SQL Server, Oracle, or IBM DB2 for the server farms
data store, you can image the first server in the farm and use it to deploy all other
servers.
To image a server for rapid deployment with SQL Server, Oracle, or IBM
DB2
1. Install the first server in the farm.
2. When the server is successfully restarted, log on to the console as a local or domain
administrator.
3. Delete the Wfcname.ini file, if it exists, from the root drive of the server.
4. Stop the Citrix IMA Service and set the start up type to manual.
5. If Presentation Server, Enterprise Edition components are installed, see Cloning Citrix
Presentation Server Enterprise Edition Systems on page 59.
6. Take the image of the server and then restart the server.
7. Deploy the image obtained in Step 6.
Important It is important that some type of SID generation utility be
executed when deploying Windows 2000 Server.
To verify that the server is added
1. Set the Security ID of the server with your chosen SID generator.
2. Rename the new server with a unique name.
3. Manually start the Citrix IMA Service and set the service to start automatically.
4. Verify that the server is successfully added to the farm by executing qfarm at a command
prompt on any server in the farm. If the addition is successful, the newly imaged server appears
in the list of servers.

Cloning Citrix Presentation Server Enterprise Edition Systems


If you are running Resource Manager on a server with Presentation Server
Enterprise Edition, you must delete the local database used by Resource Manager
(named RMLocalDatabase) so that the cloned server does not retain information
from the server you are using as the cloning source. The RMLocalDatabase is
installed in Citrix Resource Manager\LocalDB in the default installation
directory,
%Program Files%\Citrix.
On the cloned server, the RMLocalDatabase file is recreated automatically
when the Citrix IMA Service starts.

Simultaneous Installations
Citrix recommends that no more than 30 servers be simultaneously installed if
you are using a high powered server for your data store, (that is, a current
generation dual CPU database server or better.) For older database servers, do
not install more than 10 servers at the same time. During installation, servers must
write configurations to the same indexes in the data store. The more servers
installed at once, the greater the probability of creating deadlocks on the database
server.
Important Deadlocks occur when one server times out while waiting to write to a
piece of data that is locked by another server. In this event, the IMA Service
simply retries after a short interval.
When you install servers to a new zone, it is best to first install a single server in
the new zone. When installation of the first server in the zone is finished and the
server restarts, launch the Presentation Server Console and set the server
preference for the first server in the zone to Most Preferred. This avoids
problems with new servers in the zone becoming the zone data collector during
installation.
Important When creating a new farm, the first server installed in the first zone is
automatically configured with a server preference of Most Preferred. Therefore,
the process of setting the server preference applies only when creating additional
zones.

Deploying with Oracle Real Application Clusters


For Presentation Server for Windows, Citrix configured an Oracle Real
Application Cluster (RAC) environment using an EMC2 Celerra Network
Enterprise Server for the shared disk subsystem. The configuration tested used
the Oracle Cluster File System (CFS) on Oracle servers running Microsoft
Windows 2000 Server Service Pack 3.
When using an Oracle RAC configuration, all Oracle server nodes actively process
requests against the same backend database. Running with a RAC configuration
provides the following benefits:

All nodes can run using the same Oracle Home executable files. Using shared
executables guarantees that all nodes are using the same version and decreases upgrade
time.

All nodes can simultaneously access the same data, providing multiple front- end
servers to access the data. This provides exceptional performance gains with readintensive database operations.

Requests are automatically load-balanced across active nodes.

New requests to a failed server are automatically routed to a surviving node. In


addition to the fault tolerance benefits, using a RAC cluster for the Presentation
Server data store provides improved response time for the IMA Service on
startup and during read-intensive operations such as updates.

Test Environment
Two Cluster Servers with the following configuration:
Compaq ProLiant 1850R Dual P3 600Mhz
1GB RAM
16GB SCSI local disk
Emulex LightPulse 9000 Host Bus Adapter (HBA) connected by Fiber Optic
cable directly to the EMC2 Celerra
One 100Mbps Compaq NIC used for both normal and cluster communication

One EMC2 Celerra Enterprise Network Server with the following configuration:
51GB partition available to the cluster servers
Arbitrated Loop SAN configuration
Dedicated Fiber Adapter (FA) ports for access by the Emulex HBA cards

The Oracle CFS Software


The software for the Oracle Real Application Clusters, Cluster File System for
Windows NT or Windows 2000 Server, can be downloaded from Oracle.
The download includes updates for the software provided on the Oracle 9iR2 CD
media and the installation instructions in a file named Ocfs_relnotes.pdf that
contains pertinent information about setting up the CFS environment. Failure to
follow the guidelines explained in this document may result in a failed Oracle
RAC installation.

Process Overview
The following section lists the steps outlined in the ocfs_relnotes document. For a
more complete explanation of the steps, refer to that document.
1. Configure a physical connection to the shared disk subsystem.
2. Configure the shared disks on Windows 2000 Server.
3. Install Oracle Cluster File System (CFS).
4. Install Oracle 9iR2.
5. Patch the Oracle RAC files.
6. Reconfigure the Oracle listeners.
7. Create the database using the Database Configuration Assistant (DBCA).
8. Create a Tnsnames.ora file for the cluster configuration.
9. Install Presentation Server.

Deploying Citrix Presentation Server Clients


Presentation Server contains Microsoft Windows Installer (MSI) packages for
both Program Neighborhood and the Program Neighborhood Agent. The
following section describes how to deploy the clients to various client devices
using both the Windows Installer service and Active Directorys IntelliMirror.

Program Neighborhood Agent as a Pass-Through Client


You can choose to install Program Neighborhood Agent to be used as a passthrough client on the server during the Presentation Server installation. This
allows users to connect to the server desktop and use the functionality of the
Program Neighborhood Agent.

To install the Program Neighborhood Agent, select the Program


Neighborhood Agent component during the Presentation Server installation
and select Will be installed on local hard drive.
Note Program Neighborhood Agent is not selected to be installed by
default during a Presentation Server installation.
If you install the Program Neighborhood Agent, you are prompted later during
Setup to enter the URL of the server running the Web Interface for Presentation
Server. This server hosts the Program Neighborhood Agent configuration file. By
default, Presentation Server resolves the localhost as a server running the Web
Interface.
If you did a fresh install and didnt choose to install the Program Neighborhood
Agent, or did an upgrade, you can install the client after Setup.
To install the Program Neighborhood Agent after installation
1. In Control Panel, launch Add/Remove Programs.
2. Select Change on Citrix Presentation Server for Windows entry name.
3. Select to Modify the Windows Installer packages installed on the system and click Next.
4. Select the Program Neighborhood Agent component, select Will be installed on local hard
drive, and click Next.
5. Enter the server URL for the Web Interface Server or leave as localhost if Web Interface is
installed on the same computer as Presentation Server.
6. Select whether or not to enable pass-through Authentication and click Next.
7. Verify the component changes and click Finish.

Dynamic Client Name and Machine Name


Dynamic Client Name is a feature that is included in clients Version 7.00 and
later. Previous versions of the clients reported only the client name that was
statically configured during installation of the client and stored in the
Wfcname.ini file. If the Dynamic Client Name feature is not enabled, the client
name that is reported to the Presentation Server when connecting to a session is
stored in the registry key:
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\ICA Client\ClientName
When the Dynamic Client Name feature is enabled, the client calls the
Windows function GetComputerName, which retrieves the computers
NetBIOS name and reports it to the server.

Dynamic Client Name can be enabled or disabled during the installation process.
In Program Neighborhood, you can change this option after installation by
selecting Dynamic Client Name under Tools > ICA Settings > General. In all
other clients, including Program Neighborhood Agent, you can enable or disable
this feature by deleting or creating the
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\ICA Client\ClientName
registry value. These changes take effect on all new connections.
Note Earlier releases of the clients (prior to Version 6.30) stored the client name
in the C:\wfcname.ini file.

CAB-Based Client Packages


Three different CAB packages for the clients are shipped with Presentation Server:

Wfica.cab. The full Program Neighborhood (3.97MB)

Wficat.cab. The Web Client (2.2MB)

Wficac.cab. The minimal Web Client (1.3MB)

There are several benefits to the (Active-X) Web clients (Wficat.cab and
Wficac.cab). For example:

The user doesnt initiate the installation. The browser (Internet Explorer or Netscape
Navigator) initiates the installation on a need-to-download-and-install basis.

The CAB file package installation is fast because it is limited in size.

The CAB file is unpackaged in a temporary directory, leaving no or little footprint on


the target desktop. Changes made to a desktop are none or minimal (registration of
ActiveX ICA control).
Along with the benefits, trade-offs were made to keep the Web clients package
small and efficient. Because a smaller footprint means a reduction in size of the
client package, certain features from the full-fledged client represented by
Program Neighborhood or Program Neighborhood Agent are not available for
the two smaller sized CAB-based client packages (Wficat.cab and Wficac.cab).

Supported Features

The following features are supported by the Wficat.cab installation:

Client engine

ThinWire

Client drive mapping

Licensing

Connection Center

Auto-client reconnection

Zero Latency

Font Manager

Client Audio Mapping

Client Printer Mapping

Universal Printer Driver

Client COM port mapping

Netscape plug-in

Protocol Driver (128-bit)

Protocol driver (old compression)

Smartcard support

Active X control

ICA Client Object

SSL support

Client Auto Update

Name Resolver (TCP/IP)

Name Resolver (HTTP)

INI files

Support DLLs

TCP/IP protocol support

In addition to the preceding features, the following features are also


supported as of Presentation Server 3.0:

Bi-directional Audio

Session Reliability

Dynamic Session Reconfiguration

New logon look and feel

The following features are supported by the Wficac.cab installation:

Client engine

ThinWire

Client drive mapping

Licensing

Connection Center

Auto-client reconnection

Client Printer Mapping

Smartcard support

Active X control

ICA Client Object

SSL support

Name Resolver (TCP/IP)

Name Resolver (HTTP)

INI files

Support DLLs

TCP/IP protocol support.

In addition to the preceding features, the following features are also


supported as of Presentation Server 3.0:

Session Reliability

Dynamic Session Reconfiguration

New logon look and feel

Unsupported Features

Wficat.cab. The SpeedScreen Multimedia Acceleration feature is not supported

Wficac.cab. The following features are not supported:

Zero Latency

Font manager

Client Audio Mapping

Universal Printer Driver

Client COM port mapping

Netscape Plug-in

Protocol Driver (128-bit)

Protocol Driver (old compression)

Client Auto Update

SpeedScreen Multimedia Acceleration

Bi-directional audio

Wficac.cab Considerations
This section contains known issues and considerations regarding the new
Wficac.cab file, coupled with any known workarounds.

Upgrade Considerations
1. If one version of the client is already installed on the target machine, the same version CABbased Web Client package is not downloaded and installed by the Internet Explorer browser.
2. For the same version of Web Client installed on a target machine installed by the thin CAB file,
users cannot install the Web Client by the thick CAB file if there is a need to use more features.
The version numbers on the CAB files remain the same and Internet Explorer does not
download and install the thick CAB-based client.
Workaround. Users must uninstall the thin CAB-based Web Client using
Add/ Remove Programs in the Control Panel and then visit a Web page that
points them to the location to download the full version of the Web Client.

3. If a lower version of the full Web Client is installed on the target machine and users visit a
Web page that points to a higher version CAB-based Web Client, Internet Explorer always
prompts users to download and install the latest Web Client, leading to multiple client
installations on the target machine.
Workaround: Uninstall the Web Client and then visit the Web page pointing
to a higher version CAB-based Client.
Note By installing a smaller CAB client, even if it is a higher version,
some features are lost due to the minimization of the client.

Limitations/Constraints of WficaC.cab
1. The CAB-based ActiveX Web Client requires permission to download an ActiveX control
using Internet Explorer. The user needs the appropriate level of permissions to create subkeys
under HKEY_CLASSES_ROOT registry to correctly register the ActiveX control and to
register the .ica file type extension to support launching of ICA connections outside the
browser.
2. Internet Explorer 5.0 or later is the only supported browser for these versions of the CAB-based
client.
3. Only a limited number of client features are available in the minimal Web
client.

Deploying Clients Using Active Directory


Active Directory can be used to deploy Program Neighborhood Agent and
Program Neighborhood. This section describes how to publish or assign an
application for a group of users or computers using Active Directory.
The Microsoft definition of publish is to make an application available to a user
for installation through Add/Remove Programs or by launching a file associated
with the application. If the Windows Installer package is assigned to a user,
whenever the user logs on to a workstation, the Windows Installer service
advertises the set of applications that are listed in the Active Directory
Organizational Unit for that particular user. Advertising means that the class
IDs, extensions, and shortcuts are installed for the user so that when the user
double- clicks a file with an associated extension, or double-clicks the advertised
shortcut, the application is fully installed for that user.
For more information regarding assigning and publishing applications to users
and computers using Active directory group policies, refer to the Windows
online documentation.

Requirements

Program Neighborhood Agent (Version 7.00.13547 or later).

Program Neighborhood (Version 7.00.13547 or later).

Web Client (Version 8.x through 9.x).

Windows Installer Service. The Windows Installer service (Msiexec.exe) is present by


default on computers running the Windows 2000 Server or Windows Server 2003
operating systems. If the client device is running Windows NT 4.0 or Windows 9x,
you must install Windows Installer Version 2.0 or higher.
To deploy the Client Windows Installer package on a computer or set of
computers
1. Verify that your client device does not have a client installed.

2. Join an Active Directory domain. This allows you to assign or publish a Windows Installer
application for computers and users in that domain or in an organizational unit within the
Active Directory domain.
3. On a machine that belongs to the Active Directory domain, launch the Microsoft Management
Console (MMC) and load the Active Directory Users and Computers snap-in or go to Start
> Programs > Administrative Tools > Active Directory Users and Computers.
4. For this example, create a new Organizational Unit (OU) called MSI test and a new user called
MSIuser. Go to the Computers group and find the machine you added to the Active Directory
domain. Right-click the machine and select Move. Select the MSI Test folder and click OK.
Follow the same steps to add the new user from the Users group to the new OU folder.
Note The preceding step is necessary to test a contained number of users and
computers. In the next step we edit the Group Policy of that container to
ensure that any changes made to the Group Policy do not affect the rest of the
Active Directory domain.
5. Right-click the MSI test OU and go to Properties. From the Group Policy tab, create a new
Group Policy Objects link called Presentation Server Client Install.
6. Select the Presentation Server Client Install policy and click Edit. Under Computer
Configuration > Software Settings > Software Installation, right- click Software
Installation and select New > Package.

7. Browse to a network share containing the Ica32pkg.msi file, select the Windows Installer
package, and set the deployment method to Assigned. This step ensures that all environment
settings are present for the Automated Install for the client. Click OK. Software Installation
displays a software package assignment for deployment.
Note If you use a hidden share, for example \\Servername\c$\temp\, users
receive a pop-up window asking for the path to ICA32PKG.msi when they
launch Program Neighborhood (after it is deployed to the client devices). The
users client devices must have access to read from the share, otherwise
Windows cannot deploy the installation. This is as designed behavior of an
Active Directory.
8. Restart the client device. As the client restarts, Active Directory Group Policy automatically
installs the client on the computer. In the Windows Startup dialog box, a message appears
telling you that the client is being installed by Remote Managed Applications. This message
appears before the logon dialog box appears.
9. Log on to the client device and verify that the client is installed.
Important For Windows XP Professional operating systems, the machine has to
be restarted twice before the Active Directory Group Policy automatically installs
the client on the computer. However, if the Active Directory is based on
Windows Server 2003, you can avoid the second restart after creating the policy
by going to a command line on the client device and typing gpupdate /force.
This command prompts you to restart, but it is necessary to restart the Windows
XP Professional operating system only once.
To uninstall the Client Windows Installer package from a computer or set
of computers using Active Directory
1. On a machine that belongs to the Active Directory domain, launch the MMC and load the
Active Directory Users and Computers snap-in or go to Start > Programs >
Administrative Tools > Active Directory Users and Computers.
2. Right-click the MSI Test OU folder and select Properties. From the Group Policy tab, Edit
the Presentation Server Client Install policy. Under Computer Configuration > Software
Settings > Software Installation, right-click the Presentation Server Client Package and select
All Tasks > Remove. Ensure that Immediately Uninstall is checked, then click OK.

3. Restart the client device. As the system restarts, the Active Directory Group Policy
automatically uninstalls the client from the computer. On the Windows Startup dialog status
box, a message appears telling you that the client is being removed by Remote Managed
Applications. This message appears before the logon dialog box appears.
4. Log on to the client device and verify that the client is completely removed from the client
device.
To publish the Client Windows Installer package to a user or group of users
in an Active Directory domain
1. On a machine that belongs to the Active Directory domain, launch the MMC and load the
Active Directory Users and Computers snap-in or go to Start > Programs >
Administrative Tools > Active Directory Users and Computers.
2. If you did not create a new test OU for previous client installations, create a new OU called
MSI test and a new user called MSIuser.
3. In the Users folder, right-click MSIuser and select Move. Select the MSI Test OU folder and
click OK.
4. Right-click the MSI Test OU and select Properties. Go to the Group Policy tab, highlight the
Presentation Server Client Install policy, and click Edit. If you do not already have a
Presentation Server Client Install policy from a previous example, create a new Group Policy
Objects link named Presentation Server Client Install.
5. Under User Configuration > Software Settings, right-click Software Installation and select
New > Package. Browse to a network share containing the Ica32pkg.msi file, select the
Windows Installer package, and set the deployment method to Published. Click OK. Software
Installation displays a software package assignment for deployment.
Note If you use a hidden share, for example \\Servername\c$\temp\, users
receive a pop-up window asking for the path to ICA32PKG.msi when they
launch Program Neighborhood (after it is deployed to the client devices). The
users client devices must have access to read from the share, otherwise
Windows cannot deploy the installation. This is as designed behavior of an
Active Directory.
6. Close all management windows and restart the client.
7. Log on to the client device as MSIuser.

8. Go to Add/Remove Programs and click Add New Programs. Verify that the client is
included in the list and is ready to be added. Click Add and verify that the client is successfully
installed.
Note When using the Published method to make the client Windows Installer
package available to users for installation, you can also initiate installation of
the client by opening a file with the .ica extension.

Additional Notes
The client Windows Installer package can also be made available to users using
the Assigned deployment method. If you assign a package to users, only the class
IDs, extensions, and shortcuts are installed. When the user double-clicks a file
with an
.ica extension or double-clicks the shortcut, the client is fully installed for that user.
If you answer Yes to the option Would you like to enable and automatically use
your local user name and password for sessions from this client?, at least one
restart is required following the installation of the client.

Troubleshooting
Publishing the Program Neighborhood Agent, Program Neighborhood, and the
Web Client Windows Installer Packages to users is not supported on Windows
2000 Server or on Windows Server 2003. The only available method of using
Active Directory to deploy clients to Windows 2000 Server or to Windows
Server 2003 is to assign the package to a computer or to a group of computers.

Logging for a Client Windows Installer Package


Add an entry to the group policy for Windows Installer logging.
1. On a machine belonging to the Active Directory domain, launch the MMC and load the Active
Directory Users and Computers snap-in. Alternatively, select Start > Programs >
Administrative Tools > Active Directory Users and Computers.
2. Right-click the OU containing the target computers and select Properties.
3. Locate the Group Policy tab, highlight the Presentation Server Client Install
policy, and click Edit.
Note If you created a separate OU for your target servers, create a new
policy for the OU.

4. Within the Group Policy Editor for the policy, go to Computer Configuration
> Administrative Templates > Windows Components > Windows Installer
> Logging. Choose Enabled and select the required type of logging from the
list of available options.
5. Enter voicewarmup to enable all possible logging. The log file is created in
%SystemRoot%\Temp\msi*.log. Use the creation dates to differentiate log files.

Client Support on the Compaq iPaq


The Presentation Server Client is supported on Compaq iPaq devices. This
device can be used as a client as well as a server farm management tool for high
density servers.
The recommended client is the Client for Windows CE ARM Version 7.x or later.
Tip The client supports input from both the iPaq keyboard and
character recognizer and transcriber within a session.

IPaq Configuration
Configure the following settings in the client for better performance with WAN
connections:

Disable sound

Enable Enable Palette Device

Limit session color depth to 256 colors

Set the encryption level to Basic

If possible, avoid accessing the client drives in the session

To run the Presentation Server Console in a client session, set the ICA settings as
follows:

Window Size. Absolute (in pixels). When you set the Allow Intermediate Zoom
Factor, the client can dynamically zoom the session window.

Window Color. 256.

Data Compression. On.

Note You may experience problems with iPaq (Windows CE / PocketPC) if


deployed with earlier versions of the Web Interface (formerly known as NFuse).
This restriction is due to the lack of VBscript support in the PocketIE browser.
The Web Interface was tested with PocketPC and resolves these issues.

Consolidating Multiple License Files


If you have multiple Citrix license files installed on one license server, you can
use a text editor to combine the files into one file. For more information about the
format of license files, including a definition of INCREMENT lines, see the
Citrix Access Suite Licensing Guide.
Important Do not alter INCREMENT lines when combining license files or
the license is rendered invalid
To combine license files
1. Ensure that the <Server> section occurs only once at the top of the file (because all license files
being combined must be from the same HOSTNAME server).
2. Combine all of the INCREMENT lines from each license file into one contiguous list.
3. Append the Citrix terms at the end of the license file (especially if you have different edition
licenses).
4. Force the license server to reread the license file for changes to take effect. The following file
is an example of a combined license file. Note that the terms in
brackets <> are added for clarification and do not appear in the file itself.
# This file is in UTF-8 format.
#
<begin Server section>
SERVER this_host HOSTNAME=domain
VENDOR CITRIX
USE_SERVER
<end Server section>
<begin Increment section>
INCREMENT MPS_ENT_CCU CITRIX 2004.1027 27-oct-2004 99 \
VENDOR_STRING=;LT=NFR;GP=96;CL=ENT,ADV,STD;SA=0;ODP=0;AP=ADMIN
/ LOGON/ALW:NONADMIN/LOGON/ALW \
DUP_GROUP=V ISSUED=30-Apr-2004 NOTICE="Citrix Systems France" \
SN=OR867:1265 START=30-apr-2004 SIGN="XXXX XXXX XXXX XXXX XXXX
\ XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX \
XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX \
XXXX "
<end Increment section>
<begin Citrix terms>

#[English]
#CITRIXTERM FEATURE
1.0
MPS_STD_CCU EN
MetaFrame
Presentation Server, Standard Edition|Concurrent User
#CITRIXTERM FEATURE
1.0
MPS_ADV_CCU EN
MetaFrame
Presentation Server, Advanced Edition|Concurrent User
#CITRIXTERM FEATURE
1.0
MPS_ENT_CCU EN
MetaFrame
Presentation Server, Enterprise Edition|Concurrent User
#[German]
#CITRIXTERM FEATURE
1.0
MPS_STD_CCU DE
MetaFrame
Presentation Server, Standard Edition|Gleichzeitige Benutzer
#CITRIXTERM FEATURE
1.0
MPS_ADV_CCU DE
MetaFrame
Presentation Server, Advanced Edition|Gleichzeitige Benutzer
#CITRIXTERM FEATURE
1.0
MPS_ENT_CCU DE
MetaFrame
Presentation Server, Enterprise Edition|Gleichzeitige Benutzer
#[French]
#CITRIXTERM FEATURE
1.0
MPS_STD_CCU FR
MetaFrame
Presentation Server, dition Standard|Utilisateurs simultans
#CITRIXTERM FEATURE
1.0
MPS_ADV_CCU FR
MetaFrame
Presentation Server, dition Advanced|Utilisateurs simultans
#CITRIXTERM FEATURE
1.0
MPS_ENT_CCU FR
MetaFrame
Presentation Server, dition Enterprise|Utilisateurs simultans
#[Spanish]
#CITRIXTERM FEATURE
1.0
MPS_STD_CCU ES
MetaFrame
Presentation Server, Standard Edition|Usuario concurrente
#CITRIXTERM FEATURE
1.0
MPS_ADV_CCU ES
MetaFrame
Presentation Server, Advanced Edition|Usuario concurrente
#CITRIXTERM FEATURE
1.0
MPS_ENT_CCU ES
MetaFrame
Presentation Server, Enterprise Edition|Usuario concurrente
#[Japanese]
#CITRIXTERM FEATURE
1.0
MPS_STD_CCU JA
MetaFrame
Presentation Server, Standard Edition|\u540c\u6642\u4f7f\u7528\u30e6\u30fc\u30b6\u30fc
#CITRIXTERM FEATURE
1.0
MPS_ADV_CCU JA
MetaFrame
Presentation Server, Advanced Edition|\u540c\u6642\u4f7f\u7528\u30e6\u30fc\u30b6\u30fc
#CITRIXTERM FEATURE
1.0
MPS_ENT_CCU JA
MetaFrame
Presentation Server, Enterprise Edition
|\u540c\u6642\u4f7f\u7528\u30e6\u30fc\u30b6\u30fc
#
<end Citrix terms>

CHAPTER 5

Managing Server
Farms

This chapter includes recommendations and best practices for


managing Presentation Server.

Management Consoles for Citrix Presentation Server


The following sections discuss installing and using two management consoles that
are used to manage Presentation Server:

Presentation Server Console. You can use the Presentation Server Console to connect
to any server farm in your deployment and manage every aspect of the servers and
farm.

Access Suite Console. This console extends your ability to manage your deployment
by integrating consoles with the Microsoft Management Console (MMC). The Access
Suite Console snaps into the MMC to provide a central location for managing your
deployment. You can monitor, view, and run reports on multiple farms at the same
time using the Access Suite Console.

Installing the Management Consoles


The following procedures explain how to install the Presentation Server Console
and the Access Suite Console.
To install or upgrade the Presentation Server Console on standalone servers
1. Run Autorun from the Presentation Server CD.
2. Select Product Installations.
3. Select Install management consoles.
4. Accept the license agreement and follow the remaining dialog boxes to finish the installation
of the Presentation Server Console.

7
6

Advanced Concepts
Guide

If the Sun JRE 1_5_0_02 is installed prior to installing the Presentation Server
4.0 Console, logons to the console may fail. When JRE 1.5 is already present,
the JRE 1.4.2_06 installer does not add a registry key that is needed by the
console. This is resolved by the following steps:
1. Create the registry key: HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java
Runtime Environment\1.4.
2. Create a string value JavaHome.
3. Locate the following key in the registry:
HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Runtime Environment\1.4.2_06
and copy the data from the JavaHome value in that key to the JavaHome value in the
key you created.
To skip installation of the Presentation Server Console
Use the following command to skip the installation of the Presentation Server
Console during the Presentation Server installation:
msiexec /i mps.msi CTX_ADDLOCAL=all REINSTALL=CTX_MF_CMC

Note CTX_MF_CMC must be in upper case.


To install the Access Suite Console on standalone
servers
1. Run Autorun from the Presentation Server CD.
2. Select Product Installations.
3. Select Install management consoles.
4. Accept the license agreement and follow the remaining dialog boxes to finish the installation
of the Access Suite Console.

Using the
Console

Citrix

Presentation

Server

This section offers recommendations for using the Presentation Server Console in
an enterprise environment.

Configuring
Refresh

Data

By default, automatic refresh of data is disabled in the console. Enabling


automatic refresh increases CPU utilization and TCP traffic on the network.
Opening multiple instances of the console in the same farm with automatic
refresh enabled increases network congestion.

However, if you want to enable automatic refresh, to view real-time data related
to client connections and disconnections, for example, complete the following
tasks:
To enable automatic data refresh in the Presentation Server Console
1. Launch the console and log on to the farm.
2. Choose View > Preferences > User Data.
3. Select the automatic refresh options and enter the refresh rate. You can specify automatic
refresh for server data, server folders, and application user data.
4. Click OK to apply the settings.
Auto-refresh settings are saved on the server on which the console is running.

Performance Considerations
The console queries the data collector and the member servers for information
such as running processes, connected users, and server loads. Depending on the
size of the server farm, the console might affect performance in the server farm.
Consider the following recommendations for managing performance issues with
the console:

In Presentation Server deployments with hundreds of servers and thousands of users,


connect only one instance of the console to the farm for each zone.

Connect the console to a data collector so that the console can query data
directly, rather than through an intermediate server.

In large farms, the console can take a long time to refresh. The refresh time depends
on the number of servers in the zone, the number of clients requesting connections,
and the number of console instances that are requesting information. If the refresh
query takes longer to complete than the specified automatic refresh interval, the data
collector becomes overloaded. Make the automatic refresh interval for users and
applications as long as is practical. Citrix recommends that you do not use the
minimum refresh interval of 10 seconds. For best performance, disable automatic
refresh and manually refresh the data as needed.

When managing a farm across a congested WAN, run the console within a client
session to a remote server rather than running it locally. Running the console from
within a session reduces the amount of bandwidth consumed across the WAN and
provides better performance from the console.

Using Server and Application Folders


The console allows you to group servers and applications into folders. There is
no correlation between the console folders and Program Neighborhood folders
that appear in application sets.
The console folders help you manage a large number of servers and
applications and increase performance because the console queries about only
the servers or applications in the current folder view. One way to increase
response time is to divide the list of servers into folders based on zones.
Tip Viewing server details for large groups of servers may result in incomplete
information being gathered for all of the servers. To reduce this occurrence,
group servers in folders under the Servers node of the console.

Load Management
When you are selecting servers to configure for load management or attaching
load evaluators in large farms, the console can take several minutes to populate
the lists of available servers and selected servers. During this delay, the console
does not always indicate that it is still retrieving information.

Administrative Rights for Shadowing


To allow an administrator to shadow using the Presentation Server Console,
enable the following permissions at a minimum:
Administrators. Log on to the console
Servers. View Server Information
Sessions. View Session Management

Using the Access Suite Console


The Access Suite Console extends the ability to manage your Access Suite
deployment by integrating consoles with the Microsoft Management Console
(MMC). The Access Suite Console provides a central location for managing
your Access Suite deployment.

The Access Suite Console is supported on the following platforms: Windows


2000 Server, Windows 2000 Professional, Windows XP, and Windows Server
2003

Microsoft .NET Framework Version 1.1, available in the Support folder of the server
CD, is required to install the Citrix Access Suite Console

Recommendations
The following section provides some tips while using the Presentation Server
Extension and Access Suite Console.

The Access Suite Console uses pass-through authentication. Ensure that you are
logged on to the client device (where the console is installed) as an administrator for
the farm. To avoid issues with credentials, it is advisable to ensure that the console
machine belongs to the same domain as the farm member machines.

While running discovery, only one server name is required for the farm.

After the discovery is run for a certain farm, the discovered objects can be retained
by saving the .msc (Microsoft Management Console) file. When the
.msc file is launched again, it knows about the discovered objects. When
launching the Access Suite Console from the ICA tool bar or from the Start
menu, the choice to save the .msc file is not available because the console is
saved automatically every time you close it.

Published applications are not automatically updated for the Applications node in the
Presentation Server Extension. The discovery process needs to be run again for the
update to take effect.

If the Presentation Server Client is not installed on the machine, the option to shadow
is not available.

Use My Views to save your preferences to save you time in the future.

The Access Suite Console communicates with the server farm using the MetaFrame
COM server service. When troubleshooting, ensure that this service is running on the
server.

The Report Center


The Report Center in the Access Suite Console extends the reporting capabilities
of Resource Manager and allows you to generate reports from a variety of realtime and historic data sources. A wizard helps you select the type of report, the
data to be displayed, and the schedule for running the report. You can view the
status of your scheduled reports and adjust the report parameters.
Note Most Report Center reports depend on data from the Resource Manager
summary database. To create reports, you must have administrative rights to
that database.

The Report Center Extension enables administrators to generate HTML and CSV
reports from a variety of real-time and historic data sources. Commands are
available to view the reports from within the console and to make the reports
more widely available by copying them to other locations or emailing them to
selected recipients.
Each successful report and a copy of the specification used to generate it are
stored locally on the machine running the Access Suite Console. For reports that
you plan to run regularly, you can also generate named specifications recording
report formats, farm information, data source details, required time period, and
other report parameters. These can then be run manually or scheduled to run
when required.
If you want to generate reports from an Access Suite Console on a different
machine, neither previous reports and their associated specifications, nor any
named specification are available from the new console. However, you can copy
the necessary files to the machine running the new console and use them from
there, as long as the second machine has access to the same farm and Resource
Manager summary database as the first one.

Locations of User-Configured Report and Specification Files


The report and specifications files are stored in %USERPROFILE%\Local
Settings\Application Data\Citrix\ReportCenter on a server running Windows
2000 Server or Windows Server 2003.
Specifications are stored as .spec files in appropriately named folders within:
%USERPROFILE%\Local Settings\Application Data\Citrix\ReportCenter\CustomSettings\Specifications

Generated reports (and their associated unique specifications) are stored in:
%USERPROFILE%\Local Settings\Application Data\Citrix\ReportCenter\DataSets

Each set of related files in a folder has a unique system-generated name (such as
4C7F885E0EF72F30).
Note Each report folders set of files includes a Results.xml file containing the
raw data used to generate the necessary HTML reports, graphs, and CSV files
when the user requests them. Because the HTML and CSV folders and their
contents are generated only when required, they may not be present when you
examine the folders within DataSets. This is by design and both types of reports
can always be generated when required.

Chapter 5 Managing Server


Farms

8
1

To move previously created specifications and reports to the new console, copy
all the relevant folders to their corresponding position on the new machine. After
discovery is run and the Specifications and Jobs displays refreshed, all the
transferred items are listed as before.

Known Issue
In the Jobs display, the Elapsed Time values for the copied reports are incorrect
because of the way Report Center calculates elapsed time. It uses the creation
time of the files and this changes when the files are copied to the new machine.

Administering Server Farms


The following sections detail how to perform various tasks to administer your
server farm.

Renaming Servers
The name and security ID given to a server when it is installed and added to a
server farm generally remains unchanged, but the server can be renamed if
necessary.
To rename a server in a server farm
1. In the Presentation Server Console:

In the Add MetaFrame Administrators wizard, select Add local administrators


to the Administrator node

From the Privileges screen, choose Full Administration

2. Use chglogon /disable to prevent users from logging on to the server.


3. Remove the server to be renamed from any published applications assigned to that server.
4. Stop the Citrix IMA Service.
5. Change the name of the server.
6. Restart the server.
7. Use chlogon /enable to restore the previous setting.
8. Log on to the console using the local administrator account.
9. Expand the Servers folder.
10. Remove the old server name from the consoles list of servers.
11. Add the new server name to the list of configured servers for published applications.

Changing the Farm Membership of Servers


To change the farm membership of computers running Presentation Server, use the
chfarm command.
You can execute chfarm from:

%ProgramFiles%\Citrix\system32\citrix\ima

The Presentation Server CD

A network image of the CD

Executing chfarm does the following on the host server:

Attempts to remove the server from the farm.

Stops the Citrix IMA Service.

Configures the data store.

Restarts the IMA Service.

Important Considerations when Using chfarm


Consider the following when you use chfarm:

Misuse of chfarm can corrupt the data store. Before running the chfarm
command on any server in the farm, back up the data store.

Running chfarm on a server hosting the data store (Microsoft Access, MSDE) deletes
the current data store database. Do not use chfarm on the server hosting the Microsoft
Access or MSDE database until all other servers in that farm are moved to a new server
farm. Failure to follow this process causes errors when chfarm is executed on those
servers that no longer have a valid data store.

When you create a Microsoft Access data store on a server in a new server
farm:
1. Run chfarm first on the server hosting the new data store.
2. Execute chfarm on other servers to be added to the new server farm.
3. Run chfarm on any servers that hosted an old data store.

Close all connections to the Presentation Server Console on the local server before
executing the chfarm command.

Execute chfarm only on a functioning computer running Presentation Server.


Do not execute chfarm on a server that was removed from a server farm.

If chfarm reports any error, continuing the process can corrupt the data store.

Instead, click Cancel and use the procedure for restoring an unresponsive
server.

Using chfarm does not migrate published applications or any server settings to the new
server farm.
Note For more information about using chfarm with MSDE databases, see the
MetaFrame Presentation Server Administrators Guide.

Uninstalling Servers in Indirect Mode


In an indirect mode environment, if you uninstall Presentation Server from the
server that directly accesses the data store, any servers that indirectly access the
data store lose access to the data store. Information such as licensing and product
codes is lost. Citrix recommends that you uninstall Presentation Server from the
indirect servers first and the direct server last. Uninstalling Presentation Server
from the direct server first prevents any other servers from being removed from
the data store.
To force an uninstall of Presentation Server when the data store cannot be
accessed, use the following command:
msiexec /x mps.msi CTX_MF_FORCE_SUBSYSTEM_UNINSTALL=YES
where /x is the uninstall switch and mps.msi is the name and location of the
Presentation Server Windows Installer package. For more information about how
to pass properties to the Windows Installer, see the MetaFrame Presentation
Server Administrators Guide.

Cycle Booting Servers


You do not have to restart computers running Presentation Server regularly to
increase performance. However, cycle booting is often required to address
application memory leaks and similar residuals. To configure cycle booting,
follow the guidelines in this section.
When the Citrix IMA Service starts after you restart a server, it establishes a
connection to the data store and performs various reads to update the local host
cache. These reads can vary from a few hundred kilobytes of data to several
megabytes of data, depending on the size and configuration of the server farm.
To reduce the load on the data store and to reduce the Citrix IMA Service start
time, Citrix recommends maintaining cycle boot groups of no more than 100
servers. In large server farms with hundreds of servers, or when the database
hardware is not sufficient, restart servers in groups of approximately 50, with at
least 10 minute intervals between groups.

Tip If the Service Control Manager reports that the IMA Service could not be
started after you restart a server, but the service eventually starts, ignore this
message. The Service Control Manager has a time-out of six minutes. The IMA
Service can take longer than six minutes to start because the load on the
database exceeds the capabilities of the database hardware. To eliminate this
message, try restarting fewer servers at the same time.

User-to-User Shadowing Best Practices


Users can shadow other users without requiring administrator rights. Multiple
users from different locations can view presentations and training sessions,
allowing one- to-many, many-to-one, and many-to-many online collaboration.
Best practices for administering user-to-user shadowing include:

Do not assume that members of the administrators group have shadowing rights by
default. Although local administrators may have shadowing rights enabled in the Citrix
Connection Configuration Tool, they cannot shadow users who were assigned to the
policy by default. You must add the members of the local administrators group to the
list of people with shadowing rights in the user policy.

Although in general user policies take precedence over settings configured in other
utilities, shadowing is an exception. If shadowing is disabled during Presentation
Server Setup or disabled in the Citrix Connection Configuration Tool for a particular
connection, user policies with shadowing enabled have no effect.

Apply Service Pack 3 for Windows 2000 Server, or apply Microsoft Hotfix
Q281951 to disallow unwanted cross-server shadowing after configuring shadow
policies in the Presentation Server Console.

You can configure and manage user shadowing in the Citrix Connection Configuration
Tool, during installation of Presentation Server, and using the shadow policies. To
avoid unnecessary administration, use shadow policies as a central control for shadow
settings. Exceptions to this rule include the need to adhere to local governmental laws
that stipulate certain privacy requirements.

Installation Manager Recommendations


Installation Manager is available as a component with Presentation Server,
Enterprise Edition. For more information about using Installation Manager, see
the Installation Manager Administrators Guide.

Group Size Considerations


With Installation Manager, you can install applications to predefined groups of
servers. When you create server groups, you can install applications to a specific
set of servers quickly and efficiently. Creating server groups eliminates the need
to manually select individual servers with every installation.
When you create a server group for application deployment, consider the
following:

How you want to use your server groups

The operating system or application set installed

Keep your group size reasonable (see table)


Small

Medium

Large

Application size

< 5 MB

520MB

> 20MB

Recommended group size

< 100

< 80

< 50

Installation Manager deploys applications to servers simultaneously, but does not


use multicasting. Each target server reads the data from the location where the
installation package is stored. Large installation packages (for example, Microsoft
Office 2003) copy more than 200MB of data from the package server to the
target server. The amount of data transferred across the network is:
D=IxN
Where:
D = the amount of data
I = the size of the installation
N = the number of target servers
Smaller group sizes are needed when installing applications that require a server
to restart. Installations occur simultaneously and all of the servers restart at nearly
the same time. Because of this, a transient load is placed on the data store. The
capacity of the data store server and the internetworking infrastructure greatly
affect the performance of the network when you are deploying applications and
restarting servers. The table contains suggestions based on a 100Mbps switched
Ethernet infrastructure.

Cluster groups logically. Deployment is more efficient if several logical groups


are created that match the schema of the overall enterprise. One group might
contain servers that host standard business applications, another group can host
engineering applications, and so on.

Network Setup
The network setup recommendations for Presentation Server also apply to
Installation Manager. The more efficient and capable the network, the quicker and
easier applications are to install. The use of switches, high-speed backbones, and
high-speed disk drives greatly enhance the ability of Installation Manager to
install applications to large server farms efficiently.

Application Deployment Issues with Installation Manager


This section contains issues you should consider when using Installation
Manager in conjunction with Presentation Server to deploy applications.

Package Server
The following package server recommendations help ensure a clean package file:

Keep the package server as similar in configuration (both hardware and


software) as possible to the target server.

Make the package server as clean as possible. Roll back previously installed
applications before recording. For additional information, see the Installation Manager
Administrators Guide.

Do not run other applications while an image is recording.

Stop any unnecessary background processes before recording an installation using


Packager, including the IMA Service, especially if a manual install needs to be
performed. Background processes and file changes may be recorded by Packager and
could overwrite important files such as the local access database files used by the IMA
Service.

Do not package applications through an ICA session.

Deployment Server
The deployment server is the server where the package and installation files
reside. All target servers communicate with this server to get the files and
information required to install the application. The following recommendations
offer helpful information about deploying packages:

Place the deployment server on a server grade machine. Each target server requests
the same file set from the deployment server. The load on the deployment server can
be high. The deployment server must be capable of handling the combined load of
the servers in a deployment group connecting and requesting information
simultaneously.

Put the deployment server on a 100Mbps or greater switched Ethernet port.


Running the deployment server in a shared collision domain increases latency.
Connections can be refused due to time-out or server overload. This problem
increases on a busy network and when many servers are targeted for a single
installation.

Network Share Account


he network share account allows the target server to have access rights to the
network share point where the package is located.
To set up a network share account
1. Right-click the Citrix Installation Manager node in the Presentation Server Console and
choose Properties.
2. Type the domain account and password used to access network shares.
When running an unattended or silent installation, the network share account
must have administrator privileges on the target server.
Important Installation Manager supports only Windows domain
authentication models; it does not support workgroups.

Package Group Deployment


Package groups are used to deploy multiple packages to the same target server
or server groups in one schedule. Consider the following points when
deploying package groups:

To simplify deployment, create package groups from similar packages.

After the package groups are deployed, do not make changes such as adding packages
to or deleting packages from the package group. Making changes to the package
group may result in uninstall errors. If you must deploy new packages, create a new
package group and then deploy it.

If changes are made to a deployed package group, the Job status tab of the Job
Properties window does not report installation status for the deleted or newly added
package.

After scheduling an installation of a package group, do not make changes to the


package group contents, because it may result in temporarily inaccurate job result
information. Refresh the console to correct this behavior.

Job Scheduling and Staggered Installations


To lower bandwidth consumption, schedule the installation of packages during
times of low network usage
Installation Manager supports staggered installations of package groups.
Installation window options and multiple dates can be used for package groups
to schedule the installation job during a certain time period within specific days.
Consider the following recommendations when staggering installations:

Schedule the installation window during times of low network usage.

Select multiple dates if the installation of the packages in a package group requires
this for installation. The packages that havent been installed begin installation in
the same installation window on the selected dates.
Important A staggered installation of a single package is not supported.

User-Specified Reboot
The behavior of the server when it is restarted when deploying packages is
affected by three options:

Do not reboot servers if any user sessions are open. If you set this option before
deploying packages, the target server does not restart if a user connection to the target
server is detected even though the package deployment requires a restart. To finish the
deployment, the target server must be restarted manually after the user logs off. This
can be overwritten if you set the Force reboot after job option during the scheduling
of the installation of a package.

Delay reboot until the end of job. If you deploy a package group and one or more of
the applications requires a restart at the end of the deployment, you can set the Delay
reboot until the end of Job option when you schedule the installation. This postpones
the restart until the end of the entire package group deployment.

Force reboot after job. If you set this option, the server restarts after the package is
deployed. Any active user sessions receive a message from the server asking them to
log off. The messages are sent at five minute intervals for 15 minutes, and then the
server restarts. Any active sessions are terminated.

Recording Applications during Installation


Installation Manager Packager monitors the changes that occur on the packaging
server when an application is installed, records the changes as installation
commands in a script, and then packages all application files so you can deploy
the package on target servers. When recording applications, consider:

Installation Manager Packager cannot resume package recording if the server is


restarted while you are installing an application.

When recording an application that prompts the user for a restart, cancel the restart
and stop the recording on the Packager.

Installation Manager Packager cannot record an application that forces a restart that
cannot be canceled by the user.

Installation Manager Packager cannot record an application that requires multiple


server restarts during installation (see next point).

If an application has an unattended installation program, the Packager creates a package


from the unattended installation program only. The Packager does not record the actual
installation. When using the Packager to package the application, choose the Add
Unattended Program option to package an unattended install program and any other
necessary files. This method allows applications that require one or more restarts
during installation to be packaged using Installation Manager.

Application Deployment over a WAN


Do not deploy applications to target servers across a WAN. The amount of
bandwidth and time required to install an application over a WAN can congest
the network for extended periods of time, which can result in networking timeouts. To avoid this situation, take the following steps:

Create a new application package at the remote site where the application is to be
deployed

If there is more than one remote target server, copy the package and the
associated installation files over the WAN once; deploy it on that segment

Resource Manager Recommendations


Resource Manager is available as a component with Presentation Server, Enterprise
Edition. For more information about using Resource Manager, see the Resource
Manager Administrators Guide.
Resource Manager stores all of its configurations, settings, thresholds, and
metrics in the data store and in the local host cache. Resource Manager contains
a local Resource Manager database and a farm metric server.

Local Resource Manager Database


Servers with Resource Manager installed store their own metric information in a
local Microsoft Access Jet Database called RMLocalDatabase.mdb that is in
%ProgramFiles%\Citrix\Citrix Resource Manager\LocalDB.

This database is compacted when the IMA Service is started and once a day while
the IMA Service is running.

License Server Connection Failure is not a default metric. To set up license server
connection failure alerts, you must add the License Server Connection Failure
perfmon counter from the Presentation Server object to the server you want to
monitor.

Farm Metric Server


The farm metric server is used for application and server monitoring. The farm
metric server gathers its information from the data collector. Because the farm
metric server accesses the data collector every 15 seconds, configuring data
collectors to also perform the role of the farm metric server and the backup
farm metric server can improve performance. The farm metric server can also
perform the role of the database connection server.
Although Resource Manager can track any Performance Monitor counter as a
server metric, Citrix recommends you limit the total number of metrics tracked
on a server to fewer than 50.
Important In a farm that contains servers running various MetaFrame XP
feature release levels, the primary farm metric server must be running
MetaFrame XP Feature Release 2 or later or you encounter errors with the
summary database.

Chapter 5 Managing Server


Farms

9
1

Alerts
Resource Manager can send alerts to users or groups of users. The following list
offers tips for using alerts:

If your email service does not send alerts, confirm that you can access the mail server
using the configured account, and verify that the mail client being used (for example,
Microsoft Outlook) is the default mail client for the server.

To enable Resource Manager to send Simple Network Management Protocol (SNMP)


traps for application alerts, SNMP must be set up on the primary and backup farm
metric servers.

Summary Database
The summary database is used for storing historical data from servers in the
farm. You can produce reports, such as billing, based on the stored data. The
reports can use several criteria, such as CPU usage or application usage. Consider
the following when using the summary database:

Each farm that requires the summary database must have a database connection server,
that writes the metric information from other farm servers to the summary database.

The connection between the database connection server and the database where the
metric information is stored is defined by a system Data Source Name (DSN) called
RMSummaryDatabase.

Data is stored on each server in summary files. Summary files are updated whenever a
session or process terminates, whenever an event occurs, and once an hour for metrics.

Each Resource Manager server in the farm caches its own summary data locally for 24
hours and then transmits it to the database connection server at a configurable time of
day, preferably at off-peak hours.

Reports on data in the summary database can be generated by the Presentation Server
Console in a manner similar to those available for the local database for each server.
Tip By default, metrics are stored in the summary database. You can change
this on the Threshold Configuration screen. You can also specify the time of
day or week that metrics are recorded in the summary database on a per server
basis.

Data Purging
You can control how long data is stored in the summary database by purging the
database after a set period. You can also turn off purging, in which case all data
is kept for an indefinite period.
Note Active sessions and the processes associated with them are not purged
from the database whether they are or are not billed.

Note Processes are purged only if their parent session record is purged (that
is, to maintain data integrity, it is not desirable to purge only process records).

Summary
Files
Summary files are written only when the summary database is enabled in the
farm. When each file is created, it is given a random name and also a header, that
contains the following fields: Schema Version, Servers Name, Servers Domain,
and Farm Name.
Additional records are written to the file based on these
events:

When a process terminates, a process record is written to the file

Every 60 minutes a metric record is written for each metric configured to store
summary data

When a session is started, a session record is written

When a session ends, a session record is written

When an event is generated, an event record is written


Note Only server up and server down events are stored. The server down event
is generated by the farm metric server if a server cannot be contacted. The server
up event is generated by the server when the IMA Service is restarted.

Note Summary files can be copied manually to the database connection server or
other servers before the daily update starts. The header information in the
summary file ensures the records are associated with the correct server.

Folders and Zones


MetaFrame XP Feature Release 3 and later provides the ability to record which
folders and zone a server is in at the time of writing data to the summary file.
This information can be used to group servers when creating reports outside of
the console. By default, the summary period for server metrics is one hour.
If either the folder or zone changes for a server, just before writing the next set
of server metric records to the summary file, a new folder and zone record are
written. All following server metric records are associated with this new folder
and zone record. If the folder or zone changes multiple times within the summary
period, only the one record is written prior to writing the new server metric
records to the summary file. All other folder and zone changes go unrecorded.

Updates to the Database Connection Server


Uploads to the database connection server are initiated by the individual servers
in the farm based on the upload time configured. The following considerations
apply when uploading to the database connection server:

Only summary files that are not currently active are uploaded to the database
connection server.

If the database connection server receives another request to upload a summary file, it
logs a duplicate request and the old request is deleted from the list. This occurs if
updates take longer than 24 hours.

The default setting for concurrent uploads is 10. The default setting for concurrent
imports is one. This reduces the requirement for database connection licenses.

Importing a record into the summary database twice does not cause duplicate entries.

If a summary file takes longer than 30 minutes to transfer, the database connection
server assumes it timed out and deletes any record of requesting it. This file is not
retransmitted until the next update period 24 hours later unless a manual update is
invoked. If the uploaded summary file eventually reaches the database connection
server after it times out, it is ignored and deleted.

Upload time is compared to the server time; the servers time zone is used to determine
if uploads should begin. Example: A server farm has the majority of the machines in
New York and a smaller zone in the UK with the upload time set to 1 AM. The servers
in the USA begin to upload files at 1 AM EST, while machines in the UK start their
uploads at 1 AM UK time, which is 8 PM EST.

A duplicate upload request message in the database connection server log is an


indicator of problems in the system but is not an error. The duplicate request does not
cause any invalid or duplicate data in the summary database and can be treated as an
informational message. An example that could result in a duplicate upload request
would be a manual upload requested when an upload is already under way, either a
timed update or a previously requested manual upload. Uploads taking more than 24
hours to complete results in the next daily upload beginning before the previous one
completes.

SDB_Heuristics Table
With large amounts of data in a summary database (for example, 1GB or more), the
console may be unable to display very large reports. The sdb_heuristics table in the
summary database is used by Resource Manager to ensure that any summary report
generated can be displayed within the console. By default, the table contains the
following entries and values:
PK_HEURISTIC

HEURVALUE

BILL_HTML_MAX (characters)

72500

MAXIMUM_PRACTICAL_HTML_BYTES (bytes)

1048576

PROCESSES_PER_SESSION

10

SESSIONS_PER_USER_PER_DAY

USERSUM_HTML_BYTES_PER_PROCESS

128

When the administrator specifies various report options in the summary report
generation dialog boxes, Resource Manager performs calculations based upon
these options, and the entries in the SDB_HEURISTICS table, to estimate the
size of the report.
If the estimated value is greater than
MAXIMUM_PRACTICAL_HTML_BYTES (in the case of Process, User, and
Server Summary reports) and BILL_HTML_MAX (in the case of Billing
reports), a warning message appears, stating that the report may be too large to be
displayed within the console. You can cancel the report generation or continue. If
you continue and the report cannot be displayed, an error message appears. You
can save the report directly to disk and view the report using another application
capable of viewing HTML files (for example, Internet Explorer).
The values in the table can be modified to reflect the farm usage and control the
size of the reports.

Note The number of report windows open determines whether or not the
console can display additional reports. Each time a report is returned to the
console, a calculation is performed that subtracts the size of the report (in bytes
for Summary reports and characters for Billing reports) from the respective
maximum values in the table, producing an available size figure for subsequent
reports. Accordingly, you are more likely to receive a warning that a report
cannot be displayed if multiple reports are open. After a report is closed, its size
is returned to the available size figure for future reports.

Note If the summary database is not available, all reports (Current Process,
Current User, and Server Snapshot) make use of a default value of 1048576
bytes (= 524288 characters).

Network Manager Issues


Network Manager is available as a component with Presentation Server,
Enterprise Edition. For more information about using Network Manager, see the
Network Manager Administrators Guide. The following are issues to consider
when using Network Manager and supported SNMP monitoring tools.

In Tivoli NetView, the server icon is sometimes green, while the subsystem icons are
light blue. In this case, highlight the green server icon and perform a status update to
update the status of the subsystem icons. This is a Tivoli NetView IP map issue that
occurs when NetView is left running over long periods of time.

When using Tivoli NetView, if the Trapd.exe process is killed while the Metadis.exe
and Metalan.exe services are running, each service acquires 50% CPU utilization. The
services do not return to normal CPU levels until Trapd.exe is restarted. This is a
known issue with Tivoli NetView.

In HP Network Node Manager, a link-down status is represented by a blue


icon.
This occurs only if the server cannot be contacted by the console when the
status update is performed. In Tivoli NetView, a link-down status is
displayed in red.

When Network Manager is uninstalled from one of the SNMP management consoles,
by default the Network Manager icons stay in the IP map until they are deleted and
the nodes are rediscovered.

For Computer Associates Unicenter to be able to reclassify Windows servers as servers


running Presentation Server, it is necessary to configure and enable Security
Management (secadmin), otherwise a message similar to Security authorization
failure. The action has been denied appears in the Unicenter event log (conlog).
The following are known issues and recommendations for the SNMP Agent:

In Windows 2000 Server, the default security setting for the SNMP service is read
only. Network administrators cannot perform SET operations (logoff, disconnect,
send message, and terminate process) from Network Manager consoles unless the
security setting is read/create.
Action: Change security to read/create.

Microsoft has released security bulletins for SNMP security risks. Apply the
following bulletins to all servers and instances of the Presentation Server Console:

MS00-095: Windows NT 4.0

MS00-096: Windows 2000 Server

MS02-006: Windows 2000 Server and Windows XP

Tip Enable or disable the SNMP Agent when farm activity is low.

For Windows Server 2003, the SNMP service by default accepts only SNMP
messages from local host. Windows 2000 Server and previous operating systems
allowed any SNMP messages from any host from the start.
Action: Add more servers to the list of allowed hosts (recommended) or allow
messages from any host (not secure).

Older versions of Network Manager had the ability to shut down or restart a server.
To comply with Microsoft SNMP security, these options were removed in newer
versions of the plug-ins. Any attempt to restart a server with an older version of a
Network Manager plug-in is denied.

Using Visual Basic Scripts to Access the WMI Provider


Windows Management Instrumentation (WMI) is the standard management
infrastructure included as part of Microsoft Windows 2000 Server and Windows
Server 2003. The WMI Provider for Presentation Server supplies information
about servers and server farms. This information is displayed by the Presentation
Server Management Pack, which is a plug-in to Microsoft Operations Manager
(MOM). You must install the WMI Provider on each server you want to monitor
with MOM.

Another means of accessing information provided through the WMI Provider is by


using Visual Basic scripting. The scripts provided in this section are intended as
starting points that can be modified to meet specific requirements.
Note The data returned by the WMI Provider is read-only.
This section assumes familiarity with WMI and Microsoft Operations
Framework (MOF) files. Citrix recommends that you download a copy of the
Microsoft WMI tools including CIM studio from the Microsoft Web site.

WMI Provider Schema


The schema for the WMI Provider is as follows:

Classes. Version 1.0 of the WMI Provider has 45 classes that fall into two basic types:

Citrix classes. The information contained in these classes applies to all servers
in the farm.

MetaFrame classes. The information relates to a specific server in the farm.

Subclasses. Many of the classes are linked to subclasses; for example, the
Citrix_Server class has MetaFrame_Server as a subclass.

Events. Fourteen events relate to sessions, folders, applications, and servers.


One Citrix event relates to zone elections.

Associators. Many classes have associations between them. You might use these
when looking for a particular piece of data that is associated with the current class
instance you retrieved.

MethodsThe WMI Provider provides three methods to manage sessions, along


with methods to clear the zone election and disconnected session happening data.
Every time there is a zone election in the farm, WMI stores details about the
zone election in a file. Every time a user disconnects from the server, WMI
records when the disconnection took place. Over a period of time this file can
become quite large or contain outdated information. The WMI provider can
remove all the zone election/disconnection data or just data recorded before a
certain date.

Script Coding Styles


You can use three different styles of coding to access WMI information. The
scripts listed here generally use enumeration, but this is not necessarily the best
or the only way.

EnumerationThis method gets all the instances of data in a class. It can be used when
all the instances are needed and not one specific piece of data. For example, it can be
used to list all the servers in a farm or all the zones in a farm.

GetObjectThis is used to extract a specific piece of data. One issue with the
GetObject style is the limitation of having to access WMI employing the user the
script is running as.

WQLThis style is similar to SQL, though it has some limitations because it is a


subset of the language. One particular limitation is the lack of the LIKE operator that
may mean enumeration is needed instead. For example, the administrator cannot
specify a list of servers whose IP address is 10.30.32.xxx.

Permissions
It is important to note that you generally need administrator privileges to access
WMI information, both as a machine administrator and as a Citrix administrator.
The WMI Provider does respect the restricted administrator privileges that can be
set in the console. View-only administrators cannot log off or disconnect
sessions using the WMI Provider even if they are local server administrators.
Because scripts are generally running with administrator privileges, it may not be
possible to stop scripts from taking undesired actions, so scripts that disconnect,
send messages, or log off sessions must be well tested before running them in a
production environment.

Script Methods
Managing SessionsLogoff, Disconnect, and SendMessage
The three methods available for session management are Disconnect, Logoff, and
Sendmessage. These operate the same way that the Presentation Server Console
manages ICA sessions. Note that Metaframe_Session returns all the current
sessions, including the console and listener sessions, so even if there are no active
sessions on a server, five sessions are listed. When using MetaFrame_Session,
check that the correct number of sessions for real sessions exists by checking the
SessionState and SessionName properties.
The value returned by SessionState is numeric; this can be mapped using the
MetaFrame.mof file. Open the MetaFrame.mof file and look for
MetaFrame_Session to find an entry: [Values {.... This contains textual
translations of the numeric data.

In this case the list is zero-based, translating to:


0

User logged on

Connected to client

Connecting to client

Shadowing other session

Logged on but no client

Waiting for connection

Listening for connection

Reset in progress

Down due to error

Initializing

Note that a Session State of 1 indicates that a client is waiting for a logon.

Purging Event DataPurgeAllHappenings and


PurgeAllHappeningsBefore
MetaFrame Disconnect Events and zone elections are stored in the CIM
repository. This file grows unless you purge it using the PurgeAllHappenings or
PurgeAllHappeningsBefore methods.
Note To use the PurgeHappeningsBefore method, specify the date in
Coordinated Universal Time (UTC) format.
The following script purges all disconnected session happening events for
server SERVER01:
Option Explicit
Dim
sReturnValue
Dim objresult
Dim Service
Dim DatePast
Dim ProviderKey
Dim inParam
Dim NameSpaceLocator
Dim strServerName
StrServerName="SERVER01"
Set NameSpaceLocator = CreateObject
("WbemScripting.SWbemLocator")

10
0

Advanced Concepts
Guide
Set service = NameSpaceLocator.ConnectServer
(strServerName, "root\Citrix")
service.Security_.ImpersonationLevel = 3 ' use the
current
Windows NT credentials
Set ProviderKey = Service.Get("MetaFrame_Purge_
DisconnectedSession_Happening")
Set objresult = ProviderKey.ExecMethod_
("PurgeAllHappenings")
sReturnValue = objresult.Properties_("ReturnValue").Value
msgbox sReturnValue & " " & " events were purged ", 0, "Number
of events purged"

To keep data for a specific amount of time, for example analyzing disconnect data
over the last seven days, use the PurgeHappeningsBefore method.
In Visual Basic 6, use the format$ function to convert to UTC, but in VBS, break
up the string and provide it in the yyyymmddHHMMSS format with the
.000000- 000 piece appended to the end.
Set ProviderKey = Service.Get("MetaFrame_Purge_
DisconnectedSession_Happening")
Set inParam = ProviderKey.Methods_("PurgeHappeningsBefore").
InParameters.SpawnInstance_()
sDateTime = Format$(myDate, "yyyymmddHHMMSS") & ".000000-000"
inParam.Properties_.Add("dtPurge", wbemCimtypeDatetime).
Value = sDateTime
Set objresult = ProviderKey.ExecMethod_
("PurgeHappeningsBefore", inParam)

Performing Tasks
Converting Numeric Data to MOF Strings
To display the MOF string equivalent of data from the Provider, use the
Qualifiers_(Values) property to convert this data, where there is an
appropriate string in the MOF file:
strState = MFSession.Properties_("SessionState").Qualifiers_
("Values").Value(MFSession.SessionState)

To list all sessions on the server with the MOF string value rather than the
numeric one:
option explicit
Dim NameSpaceLocator
Dim Service
Dim strSession
Dim
objMFSessions
Dim MFSessions

Dim MFSession
Dim serverName
Dim
strSessionID
Dim strSessionList
Dim strState
Set NameSpaceLocator = CreateObject("WbemScripting.
SWbemLocator")
serverName=inputBox ("Please enter a server in the farm you
want to list Sessions")
if serverName ="" then
wscript.quit
end if
Set service = NameSpaceLocator.ConnectServer(serverName,
"root\Citrix")
service.Security_.ImpersonationLevel = 3 ' use the current
Windows NT credentials
Set objMFSessions=Service.get("MetaFrame_Session")
set MFSessions=objMFSessions.instances_
For each MFSession in MFSessions
strSessionID=MFSession.Properties_("SessionID")
strState=MFSession.Properties_("SessionState").Qualifiers_
("Values").Value(MFSession.SessionState
)
strSessionList=strSessionList & strSessionID & " : " &
strState & vbCRLF
next
Wscript.echo "Session List" & vbCRLF & strSessionList

Connecting to a Remote Server as a Different User


If you are not logged on as an administrator but you must run WMI scripts as a
different user on a remote machine, specify a particular user name and password:
Set service=NameSpaceLocator.ConnectServer(serverName,"root\
Citrix",strUserName,strPassword)

Specify a domain as part of the user name, for example:


StrUsername="Domain\Username"

Using Associators to Retrieve Data


Associators allow data retrieval based upon data from a different class. For
example, you may want to find out which clients are connected to a particular
server, or what applications are currently running. When listing all applications
running on a server, note that published desktops are not listed. In this instance,
the associator between Citrix_Server and MetaFrame_Application is
MetaFrame_ApplicationsRunningOnServer.
option explicit
Dim NameSpaceLocator

Dim Service
Dim
serverName
Dim Citrix_Servers
Dim ClassKey
Dim server
Dim AKey
Dim strAssociator
Dim AppAssociators
Set NameSpaceLocator = CreateObject("WbemScripting.
SWbemLocator")
Dim
MetaFrameApp
Dim strResult
serverName=inputBox ("Please enter a server in the farm you
want to check")
if serverName ="" then
wscript.quit
end if
Set service = NameSpaceLocator.ConnectServer(serverName,
"root\Citrix")
service.Security_.ImpersonationLevel = 3 ' use the current
Windows NT credentials

Set ClassKey = service.Get("Citrix_Server")


AKey="Metaframe_ApplicationsRunningOnServer"
Dim AppCount
Set Citrix_Servers =
ClassKey.Instances_ for each Server in
Citrix_Servers
strAssociator="MetaFrame_Server.ServerName=" &
chr(34) & server.ServerName & chr(34)
set AppAssociators=service.AssociatorsOf
(strAssociator,Akey)
strResult=Server.Properties_("ServerName") & vbCRLF
on error resume next ' following line can fail if
no
associators
appcount=AppAssociators.count
if appcount>0 then
for Each MetaFrameApp in AppAssociators
strResult=strResult & MetaFrameApp.
Properties_("BrowserName") & vbCRLF
next
wscript.echo strResult
else

strResul

Wscript.echo "No applications running on "


& end if

t next

To obtain a list of applications on a server, start with the MetaFrame_Server


class, then use the MetaFrame_ApplicationsRunningOnServer associators, then
the MetaFrame_Application class.
Note The on error resume next following line can fail if no associators line is
relevant if a server has no applications published (WMI returns an error
message that you can ignore).

Monitoring Citrix and MetaFrame Events


Citrix and MetaFrame events are more advanced, because they need an
application to receive them. Such an application is often referred to as a
consumer. While Visual Basic Scripting can be used, a GUI application is often
more suitable.
However, the code is fairly similar between the two, so specify the events you
want to subscribe to (listen for), then set up an event sink (specify where you
want the information to be sent).
A dialog box is displayed that allows you to halt the script (you click OK to halt
the script).
Run the script, then connect to the server. Try disconnecting the session. The
number returned can be converted to a text string by looking in the MetaFrame
MOF file.
The script receives all MetaFrame events; change the WQL to limit the type
of events that are needed.
Zone elections are CitrixEvent, so to monitor these, change the strQuery to Select
* from CitrixEvent.
To end the script, click OK in the message box saying Click OK to end.
It is useful to store event data in a database for use in reports about how a server
is being used or how many zone elections are taking place. If a large number of
disconnects occur in a short space of time, there may be a network problem. Over
time you can profile when users log on and when a server is likely to be
overloaded.
Option
Explicit dim
strQuery dim
objEvent
Dim NameSpaceLocator

dim service
dim objSink

dim
objConnector
Dim ServerName
serverName=inputBox ("Please enter a server in the farm you
want to check")
if serverName ="" then
wscript.quit
end if
strQuery="Select * from MetaFrameEvent"
set objConnector=GetObject("winmgmts:{impersonationLevel=
impersonate}!//" & servername & "/root/Citrix")
set objSink= Wscript.CreateObject("Wbemscripting.
SWbemSink","MYSINK_")
objConnector.ExecNotificationQueryAsync objSink,
strQuery
MsgBox "Click ok to end"
Sub MYSINK_OnObjectReady(objSvc,
objAsynContext) Dim PropertySet
Dim
PropertyInstance
Dim QualifierSet
Dim strResult
Dim eventType
set PropertySet=objSvc.properties_
for each PropertyInstance in PropertySet
strResult = strResult & PropertyInstance.Name & " = " &
PropertyInstance.Value & vbCRLF
Set QualifierSet = propertyInstance.Qualifiers_
EventType = EventType &
QualifierSet.Item("values").Value(propertyInstance.Value)
Next
Wscript.echo "Event took place" & vbCRLF & strResult & vbCRLF &
EventType
End sub

Sample Scripts
List All Servers in a Farm
The following script lists all servers in a farm. The script prompts for a server
name and then retrieves the details from the Citrix_Server class for that server
and all the other servers in the same farm. It is not necessary for the specified
server to be a data collector. If possible, run the script against a server that is the

only server in the farm and then a server that is part of a group of servers in the
farm.

The script performs four tasks:

Establishes a connection to the Citrix WMI Namespace on the server, using the current
Windows credentials

Obtains a list of all instances of data for the Citrix_Server class

For each Citrix server, lists all the property names and the values for the
Citrix_Server class

Displays the result in a message box Save the


script as Serverlist.vbs
Option Explicit
Dim NameSpaceLocator ' Top level handle to the WMI Namespace
to begin
Dim Service ' a pointer to the Citrix
namespace Dim ServerName ' The server to
connect to
Dim ClassProperty ' A specific property in the class
Dim ClassPropertySet ' The set of properties in the
class

The following line needs administrator permissions, so run the script as an


administrator:
Set NameSpaceLocator = CreateObject("WbemScripting.
SWbemLocator")
serverName=inputBox ("Please enter a server in the farm you
want to check")
if serverName<>"" then
' Connect to the Citrix specific namespace in WMI
Set service = NameSpaceLocator.ConnectServer(serverName,
"root\Citrix")
service.Security_.ImpersonationLevel = 3 '
use the current Windows NT credentials
Dim Citrix_Servers ' the list of Citrix servers in the
farm Dim server
' a single Citrix server
Dim ClassKey ' A pointer to the Citrix_Server class to
use Dim strResult
' a string for the message box
Set ClassKey = service.Get("Citrix_Server")
' now get a list of all the data (instances) in this
class Set Citrix_Servers = ClassKey.Instances_
strResult="Farm has " & ClassKey.instances_.count & "
servers in it." & vbCRLF
' Use enumeration to get a list of all the servers in this
class ' and all the properties in the Citrix_Server class
For Each server In Citrix_Servers
set ClassPropertySet = server.Properties_
for each ClassProperty in ClassPropertySet

strResult=strResult & ClassProperty.Name & " = " &


classProperty.Value & chr(9)
next
strResult = strResult & vbCRLF
Next
wscript.echo strResult
End if

Note There is no error handling in this script. It assumes that the right server
name was provided and that WMI Provider is installed on the server.
If there is more than one server in the farm, the server used to connect has
more properties than the other servers, such as NumberOfActiveSessions,
because the Citrix_Server Class has MetaFrame_Server as a subclass.
Here is an example of explicitly specifying a particular property:
For Each server in Citrix_Servers
StrResult =StrResult &server.Properties_
("ServerName")& " " & server.Properties_("IPAddress")
Next

Log off All Sessions on a Single Server


In a similar fashion to listing servers, this script enumerates all the sessions on a
server and logs them off. Note that the Windows console is listed and the script
logs that off. To avoid this, check the SessionName property for Console.
option explicit
Dim NameSpaceLocator
Dim Service
Dim strSession
Dim
objMFSessions
Dim MFSessions
Dim MFSession
Dim serverName
Dim strSessionID
Set NameSpaceLocator = CreateObject("WbemScripting.
SWbemLocator")
serverName=inputBox ("Please enter a server in the farm you
want to Logoff Sessions")
if serverName ="" then
wscript.quit
end if
Set service = NameSpaceLocator.ConnectServer(serverName,
"root\Citrix")
service.Security_.ImpersonationLevel = 3 ' use the current
Windows NT credentials

Set objMFSessions=Service.get("MetaFrame_Session")
set MFSessions=objMFSessions.instances_
For each MFSession in MFSessions
Select Case MFSession.Properties_("SessionState")
Case 0,3,4
strSessionID=MFSession.Properties_("SessionID")
wscript.echo strSessionID
MFSession.ExecMethod_("Logoff")
end select
next

Note To log off all sessions, you may need to run the script more than
once, because a user may log on while the script is running.
By combining this script with the server list script, you can log off all sessions on
all servers in the farm.

Sending Messages to Sessions


The script for sending messages to sessions is similar, but has an extra piece of
code to handle the message title and message. A method may take a different
number of parameters and data types; in this instance they are both strings.
option explicit
Dim NameSpaceLocator
Dim Service
dim strSession
Dim
objMFSessions
Dim MFSessions
Dim MFSession
Dim serverName
Dim objMethod
Dim inParam
dim outParam
Set NameSpaceLocator = CreateObject("WbemScripting.
SWbemLocator")
serverName=inputBox ("Please enter a server in the farm you
want to check")
if serverName ="" then
wscript.quit
end if
Set service = NameSpaceLocator.ConnectServer(serverName,
"root\Citrix")
service.Security_.ImpersonationLevel = 3 ' use the current
Windows NT credentials

Set objMFSessions=Service.get("MetaFrame_Session")
set MFSessions=objMFSessions.instances_
For each MFSession in MFSessions
Select Case MFSession.Properties_("SessionState")
Case 0,3 ' logged on or shadowing sessions only
set ObjMethod=MFSession.Methods_("SendMessage")
set inparam=ObjMethod.Inparameters.SpawnInstance_()
inParam.Properties_.Add("message",vbString).Value="Please
logoff, system going down in 5 minutes."
inParam.properties_.Add("Title",vbString).Value="Server
Warning"set outParam=MFSession.ExecMethod_("SendMessage",
inParam)
end select
Next

Porting to Visual Basic 6


You can port the code examples provided here to Visual Basic 6, but there are
extra requirements in Visual Basic (for example, specifying data types) that
Visual Basic Scripting hides. Visual Basic does, however, make debugging
easier, especially as scripts begin to grow in length. If you need a Web view of
the data, you could consider porting to Active Server Pages. The scripts were
written for the Windows 2000 Server platform. Visual Basic.NET can use the
Visual Basic Scripting style, but ideally it should use the System.Management
object class. While the basic principles are the same, the actual code is different.
For Visual Basic 6, specify data types and object types and add Microsoft WMI
Scripting V1.2 Library to the project references. If you are unsure what object
type the Provider is returning, use the generic Dim var as object and rely on
Visual Basic to perform late binding on the object.
If enumerating a class that has subclasses, take care if you assign the properties
into an array, because more properties may be returned than necessary. When
evaluating a class, the names of the subclasses are returned, but not their
properties.
Note Citrix_User, Citrix_UsersInGroup, and Citrix_Group can take a while to
evaluate, especially in large, distributed domains with several trust
relationships.

Events in Visual Basic


6
The code is similar to that preceding, but an event sink must be on a form.
First ensure Microsoft WMI Scripting V1.2 Library is added in the references
of the project.
You
add:

must

Option
explicit
Dim
withEvents
SwbemSink

sink

as

in the General Declarations section of a form in the application, and put the code
for the event subscription and sink as procedures on the form:
Public Function MFEvents() As ErrObject
On Error GoTo ErrorHandler
Dim
Services
As
swbemservices
Dim
strComputerName
as
string
StrComputerName ="server01"
Dim
NameSpaceLocator
As
SWbemLocator
Set NameSpaceLocator =
CreateObject("WbemScripting.SWbemLocator")
Set Services = NameSpaceLocator.ConnectServer(strComputerName,
"root\Citrix")
Dim
strQuery
As
String
Dim cntxt As SWbemNamedValueSet
Set sink = New SWbemSink
strQuery = "SELECT * FROM
MetaFrameEvent" Set cntxt = New
SWbemNamedValueSet cntxt.Add "sinkname",
"ExecNoteAsync"
Services.Security_.Privileges.Add (wbemPrivilegeSecurity)
Services.ExecNotificationQueryAsync sink, strQuery, , , , cntxt
ErrorHandler
:
If
Err
<>
0
Then
Set MFEvents = Err
Err.Clear
End
If
End
Function

Private Sub sink_OnObjectReady(ByVal objWbemObject as


WbemScripting.ISWbemObject,ByVal objWbemAsyncContext as
WbemScripting.ISWbemNamedValueSet)
'
Process
the
events
here
Dim cntxt_item As WbemScripting.SWbemNamedValue
Dim PropertySet As SWbemPropertySet
Dim
propertyInstance
As
SWbemProperty Dim QualifierSet As
SWbemQualifierSet Dim EventType As
String

11
0

Advanced Concepts
Guide
If objWbemObject.Properties_.Count <> 0 Then
Set PropertySet =
objWbemObject.Properties_ EventType =
Time$ & Chr$(9)
For Each propertyInstance In PropertySet
If propertyInstance.Name = "EventType" Then
Set QualifierSet = propertyInstance.Qualifiers_
EventType = EventType & "Type:" & Chr$(9)
Select Case objWbemObject.Properties_
("EventType").Origin
Case "MetaFrameEvent"
EventType = EventType &
QualifierSet.Item("values").Value(propertyInstance.Value)
End Select
EventType = EventType & Chr$(9)
Else
eventType = eventType & propertyInstance.Name & " :
"
& propertyInstance.Value & Chr$(9)
End If
Next
End If
MsgBox
EventType End
sub

Unsigned Long Integers


In Visual Basic 6, long integer types are SIGNED, but the WMI Provider has some
properties that are UINT32 (unsigned) and are not, therefore, understood by Visual
Basic. In the following section of code, CIMType 19 is a UINT32. Test to see if
the value is negative. If it is, convert the value to a double and add an amount that
corrects the signing problem.
If Not (IsNull(propertyInstance.Value))
Then If propertyInstance.CIMType = 19
And
CDbl(Val(propertyInstance.Value)) < 0 Then
sPropertyValue = Trim$(Str$
(CDbl(propertyInstance.Value) + CDbl(2 ^ 32)))
Else
sPropertyValue = propertyInstance.Value
End If
Else
sPropertyValue = "(null)"
End If

Dates and Times


These are returned in UTC format, so even if servers are located in different
time zones, connect/disconnect times are the same on each server. You must
manually take into account any time zone differences between servers and
clients.

OLE Server Busy Dialog Box


If the OLE server busy dialog box with the Switch To, Retry, and Cancel buttons
appears or the OLE server busy version appears, the application is requesting data
from the server and hasnt received a response. Wait until the code completes or
terminate the Visual Basic application.

You can change the title and message of the dialog box using the following code:
StrOleBusyTitle="Waiting On Remote Server"
StrOleBusyText="No response from Remote server yet."
App.OleServerBusyMsgTitle=strOleBusyTitle
App.OlseRequestPendingMsgTitle= strOleBusyTitle
App.OleServerBusyMsgText=strOleBusyText
App.OleRequestPendingMsgText=strOleBusyText

In Visual Basic.NET there is an option to set a time-out for how long the
application waits for a response.

NULL Data
If you are coding in Visual Basic 6, extra steps must be taken to check that data
returned from the Provider is not null (as opposed to being 0 or ) before
performing operations on the data. The following is an example of bad code:
if licenseObject.Properties_("GraceDays").Value <5 then
' ... take some action to warn license is going to
expire end if

This raises an error for activated licenses, that returns null for grace days. Either
set an error handler before this, or perform the following:
If not ( IsNull ( licenseObject.Properties_("GraceDays")
.Value)) then
' Now safe to test the value
if licencseObject.Properties_("GraceDays").Value <5 then
' ... take some action to warn license is going to expire
End if
End if

Visual Basic.NET
Visual Basic.NET has the System.Management class for WMI. The objects are
declared differently from Visual Basic 6. The following code segment lists all
the servers in a farm:
Imports system.management
Dim strServerName as string
StrServerName="server01"
Dim CitrixServerClass As New ManagementClass("Citrix_
Server")
CitrixServerClass.Scope = New ManagementScope("\\" &
strServerName & "
Dim Citrix_Servers As ManagementObjectCollection =
CitrixServerClass.GetInstances()
Dim Citrix_Server As ManagementObject
For Each Citrix_Server In
Citrix_Servers
Console.WriteLine("Server = " &
Citrix_Server("ServerName").ToString())
Next

CHAPTER 6

Deploying, Publishing,
and Configuring
Applications

This chapter includes information about deploying, publishing, and configuring


the applications in your server farm.
Important Test all new applications prior to deployment. Even
commonly deployed applications can impact Presentation Server.

Publishing in Domains with Thousands of Objects


Presentation Server was tested in domains with over 10,000 objects in a single
directory services container. There are a number of factors to consider when
using Presentation Server in an environment that contains a large number of
objects, such as Novell Directory Service or Microsoft Active Directory.
If you use a directory services environment with a large number of objects, the
following recommendations can help you when publishing applications:

Use groups to categorize and assign permissions to large numbers of users. An


application published to one group of 1,000 users requires the validation of only one
object for all 1,000 users. That same application published to 1,000 individual user
accounts requires the validation of 1,000 objects.

Do not assign more than 1,000 users or group objects to a published


application.
This decreases the application publishing time, because all user and group
accounts must be verified. Although the console may appear to time-out after
five minutes, the server continues to publish the application in the background.

Use the Add List of Names button instead of scrolling to locate a user when the users
container holds thousands of objects.

11
4

Advanced Concepts
Guide

In environments with hundreds or thousands of published applications, adding a new


server to the farm can be difficult. To add multiple applications to a server, launch the
Presentation Server Console and select the existing published applications you want to
publish to the new server. Dragging the selected applications to the server in the lefthand side of the console adds all of the selected applications to the server. Ensure that
the new server has access to the user accounts for which the applications are published.
If the machine does not have permissions for the existing user accounts, the accounts
are reset and replaced with the built-in user accounts.

Content Redirection
This section includes information about using the content redirection feature.
With content redirection, you determine which applicationsremote or local

users launch and in which situations. For information about how to configure
and use content redirection, see the MetaFrame Presentation Server
Administrators Guide.
The following points are known issues for server to client content redirection.

Content redirection from server to client is unidirectional. This means that if, for
example, a user clicks a URL in a mail program running in a remote session, the link is
launched in a browser installed on the Presentation Server Client device. However, if
the user attempts to use the mail to function inside the locally running browser, that
mail link is not redirected back to the remote mail application. The default mail
program on the client device opens.

For server to client content redirection to function, the server must access the
SHELL/open/command values for file types.

Microsoft Word for Windows (Winword.exe) does not redirect HTTP or HTTPS type
hyperlinks to the Web browser on the client device. For example, if a user clicks a
hyperlink encountered in a Word document running in the remote Word application,
the Web browser on the Presentation Server opens, not the locally installed Web
browser. The Microsoft Office suite does not directly access the Shell values and
redirects these types of links directly to the application itself.

Neither the Notepad text editor (Notepad.exe) nor the Write text editor
(Write.exe) support URL hyperlinks.

The Textpad text editor (Version 4.5.0, 32-bit edition from Helios Software Solutions)
redirects both the HTTP and HTTPS types of URL hyperlinks. This application does
not redirect multimedia URL links, however.
Note Content redirection from client to server is available only with
Presentation Server Advanced and Enterprise editions.

Isolation Environment Rules


You can use isolation environments to control application compatibility and
accessibility. Isolation environments are constructed by defining a set of rules that
specify how an application behaves within its confines. The default rules for
isolation environments are adequate for most environments. However, the rules
engine is powerful and flexible, and you can use it to create and alter rules, as
needed, to exert control over application interactions with operating system
resources.

Types of Isolation Environment Rules


The following sections describe the general types of rules you can create and best
practice information for such rules.

Isolation Rules
When you create a new isolation environment, its default behavior is to isolate
everything with a few exceptions. When an application requests access to a
system resource (such as a file, registry, or named object), a per user version of
the file or key is created as required. This default behavior mitigates most
application conflicts and allows applications to run correctly.
Isolation rules ensure that per user and per application level versions of files and
keys are created. This is the primary method used to isolate applications from
each other.

Isolation per user creates an individual copy of each resource that a particular user
accesses

Isolation per isolation environment creates a single copy of a resource for a


particular isolation environment

You can add one of these rules to ensure that there is one copy of a resource per
isolation environment. For example, you can create a rule that isolates the
registry hive, HKEY_LOCAL_MACHINE\SOFTWARE\classes, when you
install Microsoft Office. Because each user does not require a separate version of
this hive, you can create a rule that isolates this particular registry hive for the
isolation environment.

Ignore Rules
You can use the rules engine to define holes in the isolation environment so
that an application can write to the underlying system. Such rules are called
Ignore rules.
There are instances when an application inside an isolation environment needs to
share data with an application outside the isolation environment. For example, in
a scenario where users can print to network printers available within an ICA
session, these printers are automatically created when the user connects to a
published application. If the published application is running within an isolation
environment, called My_AIE, which has an isolation rule applied to it, autocreation of network printers fails because a copy of the registry hive
HKEY_CURRENT_USER\Printers that is created for each user. You can ensure
printer auto-creation occurs by creating a rule for My_AIE, that ignores the
registry hive HKEY_CURRENT_USER\Printers.

Redirect Rules
A Redirect rule redirects an application request for a file or registry key to a
specified location. For example, if an application creates the file, c:\temp\data.txt,
regardless of the user, you can redirect those files to c:\aietemp\%USERNAME
%.
For example, if UserA runs the application in an isolation environment, then
c:\temp\data.txt is created in c:\aietemp\UserA\data.txt.
In this example, the administrator may choose to clean up the \temp directory
each time the system starts up. By redirecting all access of c:\temp directory to
c:\aietemp on a per user basis, the administrator can clean up the temporary data
easily at startup.

Prioritization of Rules
A rule for an isolation environment is based on a specific location: either a file
path or a registry key path.
Rules are matched by the most specific path to the resource being accessed. A
rule applies to the object (file, registry or named object) specified and all the
children of the specified object, unless a more specific rule exists.

For instance, if you create the following rules:

An Ignore rule for the file path, C:\Documents and


Settings\%USERNAME%.
Every file and directory created under C:\Documents and Settings\
%USERNAME% is created in the system location because you specified,
through the Ignore rule, that this directory location is not isolated. If an
application opens the file C:\Documents and Settings\%USERNAME%\
ApplicationData\CompanyA\foo.txt, the Ignore rule for C:\Documents and
Settings\%USERNAME% applies.

A per user isolation rule for C:\Documents and Settings\%USERNAME%\Windows


because you want to isolate the per user Windows directory, C:\Documents and
Settings\%USERNAME%\Windows. If an application opens C:\Documents and
Settings\%USERNAME%\Windows\Win.ini, the isolate per user rule for
C:\Documents and Settings\Windows applies.

Restrictions and Limitations for Rules


Consider the following restrictions and limitations when constructing or altering the
rules for your isolation environment:

Do not modify or delete the default rules available for an isolation environment. If
you modify these rules, the isolation environment may be unable to run applications
correctly. For a list of the default rules applicable to isolation environments, see
Default Rules for Isolation Environments on page 121.

You can use an asterisk (*) as a wildcard character only at the end of an ignore
named object rule. For example, the rule ignore object* ignores all named objects
with a name starting with object. Use of an asterisk is not allowed in isolate or
redirect object rules.
Important Do not use the wildcard in a rule that applies to a file system or
registry key. By definition, the rule applies to all the children of a path
name.

File system rules can apply to either files or directories. You can create a rule to
alter the behavior of individual files or of directories and all of the files within them.
For example, you may have a Redirect rule for C:\temp\fileA.txt, as well as one for
C:\temp\subdir1.

Rules that specify a registry object apply only to registry keys. They do not apply
to registry values.

Do not modify rules after an application is installed and in use. If you do so, the
effect is similar to that when you rename directories or keys where an application is
installed. It can cause unpredictable results because the resources used by the
application were effectively moved or relocated by the modified rules.

Rules for an isolation environment are interpreted at run time, therefore any
modifications to existing rules are interpreted the next time you launch an application
associated with or installed in an isolation environment. If you are executing an
isolated application and modify the rule definitions, these changes do not affect running
applications. The modified rules are interpreted and take effect the next time the
application is executed.

A rule must be specified in terms of a full directory or key level. Matches are
performed on the full name of a given hierarchy level. For example, if you create a
redirect rule for C:\temp\fil, the rule applies only to a file or directory called
c:\temp\fil. The rule does not apply to any files or directories that have c:\temp\fil
as part of their name. For example, this rule does not apply to the file
C:\temp\fileA.txt, the directory c:\temp\filledWithFiles\, or any files under that
directory. The same principle applies for the file system, registry, and named objects
(with the exception of wildcards and named object rules as explained previously).

Using Environment Variables to Construct Rules


You can use environment variables to construct rules that contain references to
path locations that can change at run time. For example, an application data path
can change depending on the language selected. This can lead to errors if you use
the default rules for an isolation environment. Using an environment variable to
construct path-specific segments (such as a language-specific application data
location, AIE_COMMONAPPLICATIONDATA) ensures that an explicit rule is
created for the selected language. At run time,
AIE_COMMONAPPLICATIONDATA is substituted with the language-specific
application data location such as C:\Documents and Settings\All
Users\Application Data.
Citrix recommends that you use an environment variable to ensure universality of
a rule when any of the following conditions are true:

The path location contains a user name

Translation issues can occur with standard application locations

Relative locations can change; for example, the location where you install
Presentation Server

You can also use environment variables to quickly check where certain paths are
within a script. For example, to find out what the file system installation root for
an isolation environment is, use AIE_FSINSTALLROOT.
All environment variables for isolation environments are prefixed with AIE_.
When you create a new isolation environment, a number of default rules apply.
These default rules use the environment variables listed in the following table to
make the rules universally applicable. For a list of the default rules that apply to
an isolation environment, see Default Rules for Isolation Environments on
page 121.
Note Exercise caution when using backslash characters (\) with these
environment variables. Ensure that you insert a backslash (\) after an environment
variable before adding additional path information; for example,
AIE_USERAPPLICATIONDATA\MyData\Mine.
The environment variables available for isolation environments are as follows:
Environment Variable

Description

Example

AIE_COMMONAPPLICAT
IONDATA

Common application
data location

C:\Documents and Settings\All


Users\Application Data

AIE_COMMONDESKTOP

Common
desktop location

C:\Documents and Settings\All


Users\Desktop

AIE_COMMONSTARTME
NU

Common start
menu location

C:\Documents and Settings\All


Users\Start Menu

AIE_FSINSTALLROOT

File system install root

C:\Program Files\Citrix\AIE\MyAIE

AIE_FSUSERROOT

File system user root

C:\Documents and
Settings\Administrator\
Application Data\Citrix\AIE\MyAIE

AIE_METAFRAME

Installation location

C:\Program Files

AIE_NAME

Isolation environment
name

MyAIE

AIE_REGINSTALLROOT

Registry install root

HKLM\SOFTWARE\Citrix\AIE\MyA
IE

AIE_REGUSERROOT

Registry user root

HKCU\SOFTWARE\Citrix\AIE\MyAI
E

AIE_USERAPPLICATION
DATA

Users global
application data
location

C:\Documents and
Settings\Administrator\
Application Data

12
0

Advanced Concepts
Guide
Environment Variable

Description

Example

AIE_USERLOCALDATA

Users
local
application
data
location
(including
temporary files)
User desktop location

C:\Documents and
Settings\Administrator\Loca
l Settings\Application Data

AIE_USERSID

Unique security
identifier for the current
user; it is used
extensively internally
for security checking.

S-1-5-2001-

AIE_USERSTARTMENU

User Start
menu location

C:\Documents and
Settings\Administrator\Start
Menu

AIE_USERDESKTOP

C:\Documents and
Settings\Administrator\Desktop

Default Rules for Isolation Environments


File System Rules

Registry Rules

Named Object Rules

Ignore %AIE_METAFRAME
%\Installer Ignore %SystemRoot
%\explorer.exe
Ignore %SystemRoot%\system32\mydocs.dll
Ignore %SystemRoot%\system32\shell32.dll
Ignore %SystemRoot%\system32\spool\PRINTERS
Ignore %USERPROFILE%
Ignore A:\
Ignore B:\
Isolate %AIE_USERDESKTOP%
Isolate %AIE_USERSTARTMENU
Ignore HKCU\Control
Panel\Desktop Ignore HKCUControl
Panel\Mouse Ignore HKCU\Printers
Ignore
HKCU\SOFTWARE\Microsoft\Windows
NT\CurrentVersion
Ignore HKLM\SOFTWARE\Citrix\AppCloning
Ignore HKLMSOFTWARE\Citrix\CtxHook
Ignore HKLM\SOFTWARE\Citrix\IMS
Ignore
OleDfRoot*
Ignore WinSta0_DesktopSwitch
Ignore \??\pipe\Pipe$CtxSandbox_AD
F
Ignore
\??\pipe\Pipe$CtxSandbox_MSI
Ignore \??\pipe\lsarpc
Ignore \??\pipe\netlogo
n Ignore
\??\pipe\netsvcs Ignore
\??\pipe\samr Ignore
\??\pipe\srvsvc Ignore
\??\pipe\svcctl Ignore
\??\pipe\wkssvc Ignore
\KernelObjects Ignore
\NLS
Ignore\SECURITY\LSA_AUTHENTICATION_INITIALIZED
Ignore
\\.
\pipe\Pipe$CtxSandbox_ADF Ignore

Using Virtual IP Addresses with Published Applications


Some applications, such as CRM and CTI, utilize the user device IP address for
addressing, licensing, identification, or other purposes. Other applications may
bind to a static port, which, because the port is already in use, causes the failure
of multiple attempts to launch an application in a multiuser environment. For such
applications to function correctly in a Presentation Server environment, a unique
IP address is required for each device.
With the virtual IP Address feature, you can assign a static range of IP addresses
to a server and have these addresses individually allocated to each session so that
configured applications running within that session appear to have a unique
address. Also, you can configure applications that depend on communication
with localhost (127.0.0.1 by default) to use a unique address in the localhost
range (127.*).

How Virtual IP Addressing Works

The virtual IP Address feature works as follows:

During IMA startup, the virtual IP address assigner binds the assigned IP
addresses to the NIC that matches the same subnet as the virtual addresses.

When the virtual IP feature is enabled on the server, the virtual IP address allocator
allocates all new sessions connecting to the server an address from the pool of
available addresses that were assigned by the virtual IP address assigner.

E ach new session is allocated an address, that is removed from the pool of available
addresses. This assigned address can be seen in the Presentation Server Consoles
Servers node in the Sessions tab or through MFCOM calls. When the session logs
off, the allocated address is returned to the available address pool.

After an address is allocated to a session, it uses the allocated virtual address rather
than the systems primary IP address whenever the following calls are made:
Bindclosesocketconnect, WSAConnect, WSAAccept,
getpeername, getsockname, sendto, WSASendTo,
WSASocketW, gethostbyname, gethostbyaddr, getnameinfo,
getaddrinfo

Note All processes that require this feature must be added to the Virtual IP
Process list in the Presentation Server Consoles Farm properties Virtual IP
Processes section. Child processes do not automatically inherit this functionality.
Processes can be configured with full paths or just the executable name. For
security reasons, Citrix recommends that you use full paths. For more
information, see the MetaFrame Presentation Server Administrators Guide.

Virtual Loopback
When enabled, the Virtual Loopback function does not require any additional
configuration other than specifying which processes use the feature. When an
application uses the localhost address (127.0.0.1) in a Winsock call, the Virtual
Loopback feature simply replaces 127.0.0.1 with 127.X.X.X where X.X.X is a
representation of the session ID + 1. For example, a session ID of 7 would be
127.0.0.8. In the unlikely event that the session ID exceeds the fourth octet
(more than 255), the address rolls over to the next octet (127.0.1.0) to the
maximum of 127.255.255.255.
Virtual Loopback enables multiple published applications that depend on the
localhost interface for inter-process communication to function correctly within
the session. One example of such an application is Microsoft ActiveSync. To
provide the PDA synchronization feature, Presentation Server 4.0 utilizes the
virtual IP feature to create Terminal Services compatibility for ActiveSync.

Binding Applications
Applications are bound to specific IP addresses by inserting a filter component
between the application and Winsock function calls. The application then sees
only the IP address it is supposed to use. Any attempt by the application to listen
(for TCP or UDP) is automatically bound to its allocated virtual IP address (or
loopback address), and any originating connections opened by the application are
originated from the IP address bound to the application.
In functions that return an address such as gethostbyname() and GetAddrInfo(), if
the local host IP address is requested, virtual IP looks at the returned IP address
and changes it to the sessions virtual IP address. Applications that try to get the
local servers IP address through such name functions see only the unique virtual
IP address assigned to that session. This IP address is often used in subsequent
socket calls (such as bind or connect).
Often an application requests to bind to a port for listening on the address
0.0.0.0. When an application does this and uses a static port, you cannot launch
more than one instance of the application. The virtual IP feature also looks for
0.0.0.0 in these types of calls and changes the call to listen on the specific virtual
IP address. This enables more than one application to listen on the same port on
the same machine because they are all listening on different addresses. Note this
is changed only if its in an ICA session and the virtual IP feature is turned on.
For example, if two instances of an application running in different sessions both
try to bind to all interfaces (0.0.0.0) and a specific port, say 9000, they are bound
to VIPAddress1:9000 and VIPAddress2:9000, and there is no conflict.

Assigning IP Address Ranges


Before enabling the virtual IP feature, configure ranges of IP addresses that are
excluded from any DHCP servers or otherwise duplicated. These ranges must
share the same subnets as the assigned IP addresses of the computers running
Presentation Server that are configured for virtual IP, because there is no routing
mechanism in place to traverse subnets.
The pool of IP addresses assigned to the server farm must be large enough to
include all concurrent user sessions on every server that is configured, not just
the sessions running the applications requiring virtual IP address functionality.
These ranges are added in the virtual IP Addresses section of the Farm
Properties page of the Presentation Server Console. The servers that require
virtual IP functionality that share the same subnet as the address range should be
added to the range. The addresses in the range are distributed equally (by
default) among the selected servers and assigned. You can then change the
number of addresses assigned to each server. Citrix recommends that you
configure a Load Management Server User Load rule that is equal to or fewer
than the total number of addresses assigned to the server.
You can assign a specific address range to each computer or group of computers
running Presentation Server. This may be a viable option within environments
where the servers span subnets or where insufficient IP addresses exist within the
current subnet.

Configuring Virtual IP for Applications


The following procedure details how to view applications that bind to specific
IP addreses and ports and configure the processes of these applications to use
virtual IP addresses. For more information about configuring the virtual IP
Address feature, see the MetaFrame Presentation Server Administrators Guide.
To configure an application to use virtual IP addresses
1. Obtain the TCPView tool from Sysinternals (http://www.sysinternals.com).
This tool lists all applications that bind specific IP addresses and ports.
2. Disable the Resolve IP Addresses feature so that you see the addresses instead of host names.
3. Launch the application and, using TCPView, note which IP addresses and ports are opened by
the application and which process names are opening these ports.
4. Configure any processes that open the servers IP address, 0.0.0.0, or 127.0.0.1 to use the
virtual IP feature.
5. Launch an additional instance of the application to ensure that it does not open the same IP
address on a different port.

Client IP Address Feature


If an application fails because it requires a unique address strictly for
identification or licensing purposes, and the application does not require a virtual
address for communication, you can use the Client IP Address feature. This
feature hooks only calls that return a host IP address, such as gethostbyname().
Only use this feature with applications that send the value in this type of call to
the server application for identification or licensing.
If you deploy this feature, consider the IP addresses used by each client device.
For example, if two remote users use the same IP address, a conflict will arise
due to the duplicate address.
To configure an application to use client IP addresses, add two new entries to the
registry location HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\VIP\ on the
server where the application is deployed:

UseClientIP: REG_DWORD: 1 (enable) or 0 (disable, default)


UseClientIP is a DWORD value that should be set to either 1 or 0 (enable/
disable this feature). The disabled state is the default if the registry value is
not present.

HookProcessesClientIP: REG_MULTI_SZ
HookProcessesClientIP is a multi-string of process names from the
application (the executable names) that are to use the Client IP address
feature rather than normal virtual IP.

When these values are configured, configure either the Virtual IP Processes or
Virtual Loopback Processes with the same process names. This function creates
and manages the following registry entry, which is still required for the Client IP
feature to work:
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\CtxHook\AppInit_Dlls\
VIPHook\Processname
Note The virtual IP address feature functions only with applications that load
the user32.dll system dynamic library.

Configuring SpeedScreen Browser Acceleration for Published


Applications
SpeedScreen Browser Acceleration and Internet Explorer
There are two settings in Internet Explorer that are relevant to SpeedScreen
Browser Acceleration operation. These are the Automatic Image Resizing,
available in Internet Explorer 6.0 or later, and Play Animations in Web pages.

Automatic Image Resizing


Automatic Image Resizing causes images that are larger than the browser
window to be resized so that the complete image is visible within the browser
window. While the initial image prior to the resize may be rendered correctly
through SpeedScreen Browser Acceleration, the resized image is not. For optimal
performance, Citrix recommends disabling Automatic Image Resizing.

Play Animations in Web Page


When this feature is enabled, animated GIF images are rendered as animations
and SpeedScreen Browser Acceleration support for GIF images is disabled. Citrix
recommends that you disable Play Animations in Web pages. Disabling the
Play Animations in Web pages provides a further bandwidth reduction due to the
absence of animations that consume significant bandwidth.
Presentation Server disables both Automatic Resizing and the Play Animations for
all users on the server. The features are disabled when the user logs on for the
first time following the installation of Presentation Server. If a user subsequently
enables either of these settings, they are not modified again.
These features can be accessed by opening Internet Explorer and selecting Tools
> Internet Options, or by selecting Start > Settings > Control Panel >
Internet Options.

Advanced Configuration Information


This section contains information about automatically disabling the Internet
Explorer features previously described.
Presentation Server disables the Automatic Image Resizing and the Play
Animations features the first time a user logs on to Presentation Server. These
features are disabled only after the first time users log on.

Disabling of these features is controlled through two registry entries, one for each
feature. The registry values are contained in the registry key
HKEY_CURRENT_USER\SOFTWARE\Citrix. The registry values are defined
in the following table:
Value Name

Value

Description

DisablePlayAnimations

0
1 (default if not present)

Retain users setting.


Disable Play Animations in
Web pages in Internet Explorer.

DisableAutoImageResize

0
1 (default if not present)

Retain users setting.


Disable Automatic Image Resizing
in Internet Explorer.

If during logon, either of the registry settings is set to 1 or is not present, the
corresponding feature is disabled and the registry settings are set to 0. If either
registry setting is set to 0, the users settings for these two options are retained;
they are not automatically modified.
You may find this information useful when designing logoff scripts. For
example, you can ensure both features are disabled when the user next logs on
to the server by ensuring the logoff script sets these values to 1.

Configuring SpeedScreen Browser Acceleration on the


Client
SpeedScreen Browser Acceleration settings must be configured in ICA files.
The preferred configuration method is to use the Web Interface. By default,
SpeedScreen Browser Acceleration is enabled on the client for all connections.
Note that if either the server or the client has SpeedScreen Browser Acceleration
configured to OFF, it is disabled for that connection.
This section describes the ICA file parameters that can be used to configure
SpeedScreen Browser Acceleration.

Basic SpeedScreen Browser Acceleration ICA File Settings


SpeedScreenBA
Usage
SpeedScreenBA=[ON | OFF]

Description
Setting SpeedScreenBA=On enables SpeedScreen Browser Acceleration for a
connection. Note that the server settings may override this setting. Disabling
SpeedScreen Browser Acceleration on the server causes this setting to be
ignored for a connection.
Setting SpeedScreenBA=Off disables SpeedScreen Browser Acceleration for a
connection. This is disabled even if the server setting specifies that SpeedScreen
Browser Acceleration is to be enabled.

SpeedScreenBACompressionEnabled
Usage
SpeedScreenBACompressionEnabled=[ON | OFF]

Description
Setting SpeedScreenBACompressionEnabled=On enables SpeedScreen Browser
Acceleration JPEG image compression for a connection. Note that the server
settings may override this setting. If the server has disabled JPEG Image
compression, the server setting overrides the client setting.
Setting SpeedScreenBACompressionEnabled=Off disables SpeedScreen Browser
Acceleration JPEG compression for a connection. This is disabled even if the
server setting specifies that JPEG compression is to be enabled.

Advanced SpeedScreen Browser Acceleration ICA File Settings


SpeedScreenBACompressedCacheSize
Usage
SpeedScreenBACompressedCacheSize=value

Description
SpeedScreen Browser Acceleration uses a compressed cache to store JPEG and
GIF data sent from a computer running Presentation Server. By caching this data
on the client, pages that are revisited while retained in the cache display faster
because the server does not retransmit the cached images to the client. The size
of the cache determines how long images are stored in the cache and the number
of files that can be stored in the cache. When the cache is full, images previously
added to the cache are deleted from the cache (the oldest images are deleted
first). Initially the cache is empty and does not consume memory. As images are
added to the cache, the cache grows to accommodate the images. If an image
exceeds the maximum compressed cache size, it is not displayed through
SpeedScreen Browser Acceleration.
The value parameter is the maximum memory consumption that SpeedScreen
Browser Acceleration uses to store JPEG and GIF image data, measured in
kilobytes. The default value for this parameter is 16384KB (16MB).
Administrators can modify this setting to limit the maximum memory
consumption of the client or, alternatively, to allow higher maximum memory
consumption if required.
Increasing the memory consumption may provide some benefit on very slow
connections where the transmission time for images is very high.

SpeedScreenBADecompressedCacheSize
Usage
SpeedScreenBADecompressedCacheSize=value

Description
SpeedScreen Browser Acceleration stores the bitmap representations of JPEG and
GIF images in a decompressed cache. Using a decompressed cache means that
the JPEG and GIF images do not need to be decompressed each time they are
drawn. Using a decompressed cache provides a significant performance boost
when a page is scrolled because a scroll operation results in a number of drawing
operations on the same image.

13
0

Advanced Concepts
Guide

When an image needs to be drawn, it is decompressed and added to the


decompressed cache. Images remain in the decompressed cache until more space
is required in the cache. Images are deleted from the decompressed cache when
adding a new image could exceed the maximum decompressed cache size.
Images can be added and removed from the decompressed cache any number of
times while the image is in the compressed cache.
The maximum size of the decompressed cache size determines the maximum
dimensions of an image that can be displayed through SpeedScreen Browser
Acceleration. JPEG images require 24bpp (bits per pixel), while GIF images
require 8bpp. A larger decompressed cache size allows images with a larger
dimension to be displayed. Reducing the size of the decompressed cache reduces
the maximum image dimensions that can be displayed.
Images that exceed the maximum decompressed cache size when decompressed
are not downloaded to the client.

SpeedScreenBAMaximumCompressionLevel
Usage
SpeedScreenBAMaximumCompressionLevel=value

Description
The SpeedScreenBAMaximumCompressionLevel ICA file parameter defines
the maximum SpeedScreen compression level for a connection. The default
value for this parameter is 2 (high compression). The valid values for this
parameter are:
0

Low Compression

Medium Compression

High Compression

SpeedScreen JPEG Image Recompression performs a lossy compression on the


JPEG images transferred to the client. A higher compression level results in
reduced bandwidth consumption, but has significant impact on image quality.
The lower of the two compression levels specified on the client and the server is
used as the maximum compression level for a connection. Thus, if the client
specifies medium compression and the server high, the maximum compression
level used for the connection is medium.
This parameter is ignored if either the client or server indicates that compression
is not enabled for a connection.

SpeedScreen Browser Acceleration Limitations and


Known Issues
No Support for Transparent GIF Images
SpeedScreen Browser Acceleration does not support transparent GIF images. The
first figure shows a transparent GIF on a white background, the second on a blue
background, as it appears on a Web page.

Transparent GIF on a white background

Transparent GIF on a blue background

Images Resized in HTML


The HTML that describes a Web page can also specify the width and the height
that an image can use. This can be different from the actual width and height of
the image. In this case, Internet Explorer enlarges or reduces the image as
required to fit it into the size specified in the HTML. SpeedScreen Browser
Acceleration does not support images that are resized using this technique.
This feature is not the same as the Automatic Image Resizing feature described
previously. Automatic Image Resizing refers to the scaling of an image that is
larger than the browser display area so that it fits into the display area of the
browser.

Media Formats and Network Types Supported by SpeedScreen


Multimedia Acceleration
Supported Media Formats
SpeedScreen Multimedia Acceleration supports a range of multimedia playback
formats. The following table lists a few of the media types that were tested
successfully using Windows Media Player 6.4/8.0/9.0 and RealOne Player. In
general, SpeedScreen Multimedia Acceleration supports all media types that can
be decoded by a DirectShow based codec, regardless of file format.
SpeedScreen Multimedia Acceleration is supported when connecting to computers
running Windows 2000 Server and Windows Server 2003 from Presentation
Server Clients running on 32-bit Windows platforms.
Note Media type differs from file format. File formats can encapsulate various
media types, such as those listed in the following table. For example, a single
AVI file could contain a DIVX video stream and an AC3 digital audio stream
and would need both the DIVX and AC3 DirectShow codecs for correct
playback.

Media Type (Media


Encoding Format)

File Format
(File
Extension)

Media
Player 6.4/
8.0/9.0

RealOne
Player

QuickTime

DirectShow
-based
Media
Players

MPEG-1 Video

MPEG-4 Video

Indeo
Interactive
Video
MPEG-1 Audio

AC3 Audio

Fraunhofer
MPEG Layer-3
Codec
MP3

Y*

DIVX Video
XVID Video
Microsoft Video 1

AVI
MPEG
MPG
ASF

MP3

QuickTime

DirectShow
-based
Media
Players

RM

MOV

Media Type (Media


Encoding Format)

File Format
(File
Extension)

Media
Player 6.4/
8.0/9.0

WMA

WMA

Y*

WMV

WMV

Real Media
Quick Time

RealOne
Player

Y- Supported through SpeedScreen Multimedia Acceleration


X Not supported through SpeedScreen Multimedia Acceleration
* - Supported through SpeedScreen Multimedia Acceleration only when playing
through Windows Media Player 9.0. Data is transferred in uncompressed format.
Note The table describes only some of the more popular media types and file
formats. As stated, in general SpeedScreen Multimedia Acceleration supports
all media types that can be decoded by a DirectShow based codec, regardless
of file format.

Supported Network Types


When multimedia streams are rendered through SpeedScreen Multimedia
Acceleration because native (compressed) streams are being sent, bandwidth
usage is lower. The following network types are supported:

LAN - Supported.

WAN (DSL) - Conditional support. Audio streams are supported. Video streams are
supported based on the media type, actual content, network conditions, client and
server buffer configurations. Low resolution videos; for example, 320x240 work under
most circumstances. For higher resolution, videos frames are dropped as part of quality
control resulting in degraded video quality.

Satellite - Not supported.

Modem - Not supported.

Best Practices
The following recommendations are best practices for the implementation of
SpeedScreen Multimedia Acceleration.

Always upgrade the client devices to use the latest version of Microsofts
DirectX software.

Keep the servers version of Microsoft Windows Media Player upgraded to the latest
version/update.

When publishing audio applications, disable the Windows Logon sound event.
Only one process at a time can open the Citrix Audio Driver, and a published
applications attempt to open this driver can fail if the Windows logon event
is enabled because it has exclusive access to the device until a sound finishes
playing.

QuickTime is not supported by SpeedScreen Multimedia Acceleration; it should be


configured to use WaveOut instead of DirectSound.

SpeedScreen MultiMedia Acceleration Configuration Options


The following options can be used in the clients Appsrv.ini file for configuring
the SpeedScreen Multimedia Acceleration feature.

SpeedScreenMMAVideoEnabled Default
Value: TRUE
Description: Enable/Disable video playback

SpeedScreenMMAAudioEnabled Default
Value: TRUE
Description: Enable/Disable audio playback

SpeedScreenMMASecondsToBuffer Default
Value: 10
Description: Seconds of buffer in the client. Values range from 1-10. This
value is set on both the server and client and the connection is set up with the
smaller of these values.

SpeedScreenMMAMaximumBufferSize Default
Value: 30240
Description: Maximum size in kilobytes of the media queue that the client can
create. This is per stream, so the client could create a 30240KB queue for
audio and 30240KB queue for video.

SpeedScreenMMAMinBufferThreshHold Default
Value: 10
Description: Percent value with a range of 5-15. When the data in the media
queue reaches this value, the client requests a burst from the server to
replenish its media queue.

SpeedScreenMMAMaxBufferThreshHold Default
Value: 90
Description: Percent value with a range of 85-95. When the data in the media
queue reaches this value, the client requests that the server stop sending data
until the data in the queue levels off.

SpeedScreenMMAPlaybackPercent Default
Value: 35
Description: Percent value with a range of 25-45. This is the percentage of
the media queue that needs to be filled before playback on the client begins.

PDA Synchronization
Presentation Server 4.0 supports the synchronization of USB-tethered PDAs
running Microsoft Windows that use ActiveSync as the synchronization agent.
The following sections address publishing ActiveSync as a synchronization
agent, and issues that may arise when incorporating this feature into your
environment.
To enable PDA synchronization
1. Open the properties of a policy in which you want to enable PDA synchronization.
2. Enable the rule Client Devices > Resources > PDA Devices > Turn on automatic
virtual COM port mapping.
3. Disable the rule Client Devices > Resources > Ports > Turn off COM ports
(or set it to Not Configured).
Note
Do not plug PDAs into the server console while ICA sessions are
connected. If you do so, although PDA users in ICA sessions are isolated from
each other, they might have access to the PDA on the server console. In addition,
if you then unplug the PDA from the server console, all the PDAs in ICA
sessions are disconnected.

Consider the following when using the PDA synchronization feature:

Symbian operating system based and Blackberry PDAs are not supported

ActiveSync does not need to be installed on every client

A device driver for the PDA must be installed on the local client workstation so that the
clients operating system can recognize the PDA device

Publishing ActiveSync
To make ActiveSync available as a published application, it is important to
specify Wcesmgr.exe as the application to be launched, not Wcescomm.exe.
Wcescomm.exe is the notification area process.
If you have a PDA plugged into the USB port on the client, ActiveSync may
synchronize to the device. To prevent this from occurring:
1. Using the System Configuration Utility (msconfig), remove the ActiveSync options from the
Startup tab.
2. To prevent ActiveSync from recreating the startup entries, delete the following registry value:
HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\ Run: H/PC
Connection Agent
Note ActiveSync is not a multiuser or Terminal Services aware application, but
Presentation Server 4.0 utilizes the new virtual IP feature to create Terminal
Services compatibility. Although virtual IP is used to enable PDA
synchronization with ActiveSync, no explicit virtual IP configurations are
required by an administrator for PDA synchronization to function.

Potential Issues
The following is a list of issues and their workarounds discovered during the
testing of the PDA synchronization feature:

PDA synchronization malfunctions when Presentation Server is set to Advanced


edition. To enable support for PDA synchronization in the Advanced edition, apply
Hotfix PSE400W2K3002 for Windows 2003 or PSE400W2K002 for Windows 2000.

PDA synchronization with ActiveSync malfunctions within a Conferencing


Manager session.

When running ActiveSync as a non-seamless, published application, if you close the


main ActiveSync window, you cannot completely log off the ICA session until the
PDA is removed. Because the PDA remains in the USB cradle, the Wcescomm.exe
process is still active, and although you may not see the notification area icon, you
cannot close the session until this process is closed.

Do not use the default ActiveSync driver that ships with Windows XP. For
optimal performance, install the most recent version of ActiveSync.

Do not isolate ActiveSync. ActiveSync installs a service and isolation environments do


not support isolated services, so if ActiveSync is installed in an isolation environment,
it fails. Isolation environments can be configured on Presentation Server to isolate
other applications without impact on ActiveSync.

Disable COM port connections through ActiveSync. If you modify the connection
settings within ActiveSync to allow COM port connections and then disconnect and
reconnect the PDA in rapid succession, the PDA connects but you cannot start
Wcesmgr.exe until the currently running Wcesmgr.exe terminates or a one-minute
time-out occurs. This is a third party issue with ActiveSync and can occur on a console
outside of an ICA session as well.
To disable COM port connections for all users
Modify the registry key
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows CE Services
by specifying :

Value: REG_DWORD:ConnectTypesAllowed

Settings:

Allow serial cable or infrared connection to a COM port: 0x00000002

Allow network (Ethernet) and Remote Access Service (RAS) server


connection with the desktop computer: 0x00000004

Allow USB connection with the desktop computer: 0x00000008

The per-user key is created the first time ActiveSync is used by the respective
user, at which point all key values are populated using the defaults in
HKEY_LOCAL_MACHINE.
Note Users can enable ActiveSync COM port connections again by
modifying the options in Connection Settings.

Using Load Managed Groups or Isolation Environments


Prior to Presentation Server 4.0. the only way to segregate applications that
could not function together was by loading each application or application set
onto a different group of servers. Load managed groups are groups of servers
hosting the same application within one farm. Load managed groups, also
called application silos, are frequently used to address the following
requirements:

Numerous updates. Frequent updates cause downtime

Business. Per-server business unit funding

Back-end data source. Databases located in multiple data centers

Mission-critical application. One application cant be down due to other

Virtual IP. Designate virtual IP for specific servers instead of all servers to
minimize IP addresses
However, now that application isolation is an embedded feature of Presentation
Server 4.0, there are sound business and technical reasons for deploying
applications in load managed groups or isolation environments. Application
isolation can be used to address the following requirements:

Application conflicts. .dll files are installed in a unique location

Multiple versions. Each application being installed into a unique location


eliminates upgrade overwrites

Multiple languages. Legacy applications were not compatible with multiple


language versions

Hard-coded file paths. Typically addressed by revised file path below the default
application isolation environment directory
Note To ensure full functionality of applications installed using the
application isolation feature, thorough testing is required.
Consider the following example: You have a CTI application that requires a
unique IP address for each connection. Virtual IP is to be implemented but not
enough IP addresses can be allocated to support the total number of concurrent
connections in the farm. Because every connection to a server enabled for virtual
IP is assigned a virtual address, segregating the CTI application into its own load
managed group and configuring virtual IP for only those servers ensures that just
those connections are assigned virtual IP addresses.

TWAIN Redirection Support


Presentation Server 4.0 (Advanced and Enterprise Editions) can redirect clientconnected TWAIN imaging devices, notably document scanners, from the client
to the server, regardless of connection type. This allows users to control clientattached imaging devices from applications that run on the server and the
redirection is transparent.
Note Version 9.x or later of the Presentation Server Client for 32-bit Windows
is required for this feature.
To capture an image, users connect to a server from a client machine that has an
imaging device and the associated vendor-supplied TWAIN driver installed
locally. When the TWAIN application is run from within this session, the
application detects and interacts with the client-side device. The server-based
application that is accessed runs as a client-based application.
To control TWAIN redirection
You enable the redirection of TWAIN devices by enabling the policy rule
Configure TWAIN redirection.
1. Open the properties of a policy in which you want to control TWAIN redirection.
2. Enable the rule Client Devices > Resources > Other > Configure TWAIN redirection.
3. Use the options to allow and disallow TWAIN redirection, as well as control the level of data
compression.
Consider the following after enabling TWAIN redirection:

The image acquisition software must be installed on the computer running Presentation
Server. Examples of supported applications include: MS PictureIT, OmniPage,
PaperPort, Photoshop, Paint Shop Pro, IrFanView
Note 16-bit TWAIN drivers are not supported.

Image acquisition software that provides the USB device drivers must be
installed on the client platform.

14
0

Advanced Concepts
Guide

For TWAIN redirection, some applications are not Terminal Services aware and look
for Twain32.dll in the \WINDOWS directory of the user profile (by default,
C:\Documents and Settings\UserName\Windows). Copying Twain32.dll into the
\Windows directory of each user profile resolves this issue. You can also correct this
by adding the application to the Terminal Services application compatibility list with
the following two flags specified (see Microsoft Knowledge Base Article 186499 for
more information):

Windows 32-bit application: 0x00000008

Do not substitute user Windows directory: 0x00000400

To automate enabling these flags on your server, copy the following text to a
text editor and save it as a .reg file.
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\
CurrentVersion\Terminal Server\Compatibility\
Applications\Photoshop]
Flags=dword:00000408

Note You may need to combine these flags with other compatibility flags
needed for the application.

This feature supports the following modes of TWAIN information transfer:

Native

Buffered Memory (most scanning software works by default in Buffered


Memory mode).
Note The disk file transfer mode is not supported.

Using Scripts to Add and Remove Users from Published


Applications
If your farm has a large number of published applications, you can use
MFCOM- based scripts to batch the process of adding or removing accounts
from published applications, which can save you a substantial amount of time.
MFCOM is a COM server that exposes some of the Presentation Server control
and monitoring functions through objects and interfaces it defines. You can use
MFCOM with any COM-compliant programming or scripting language, such as
Visual Basic 6.0, Visual C++, VB.NET, C#.NET, C++.NET, Perl, and VBScript.
VBScript is included in most versions of Microsoft Windows. If you want to
take advantage of scripting to overcome the tasks associated with server
maintenance, you may find VBScript useful.

Running a Script
You can use the following sample script, addacct.wsf, in VBScript, to add or
remove an Active Directory domain user or group to or from a published
application.
Important Before you can run the script on a client, register MFCOM either
during the Presentation Server SDK installation process or manually using the
utility Mfreg.exe, which is provided with the Presentation Server SDK. For
more information, visit the Citrix Developer Network at
http://apps.citrix.com/cdn/.
To run the sample script
1. Copy the sample script into a text editor.
2. Save the script with the file name, addacct.wsf.
3. At a command prompt enter:
d:>cscript addacct.wsf
where d is the drive where the script was saved.
The sample script is as follows:
<package>
<job id="AddAcct">
<comment>
File: addacct.wsf
Description: Example of how to add a ADS user or group
to a published application.
Requirements:
WSH 5.5 or higher.
Copyright (c) 2004 Citrix Systems, Inc.

</comment>
<runtime>
<description>
Add a user or group to an application.
</description>
<example>
CScript //nologo USAGE: Addacct.wsf DOMAIN
NAME, USER|GROUP NAME
Example: Addacct.wsf MYADS Domain Users
Use Double Quotes for names such as Domain
Users
Example: Addacct.wsf MYADS JONDOE
</example>
</runtime>
<reference object="MetaFrameCOM.MetaFrameFarm"/>
<script language="VBScript">
Option Explicit
Dim

AAName, AcctName, theFarm, anApp, MFUser, aWinApp


if

WScript.Arguments.Count <> 2 Then


WScript.Echo "USAGE: Addacct.wsf DOMAIN
NAME, USER|GROUP NAME"
WScript.Echo ""
WScript.Echo "Example: Addacct.wsf MYADS
Domain Users"
WScript.Echo " Use Double Quotes for names such as
Domain Users"
WScript.Echo "Example: Addacct.wsf MYADS JONDOE"
WScript.Quit 0
Else
AAName = WScript.Arguments(0)
AcctName =
WScript.Arguments(1)
wscript.echo AAName, ACCTNAME
End If
'
'
' Check for errors and if any are found, quit.
'
'
Set theFarm = CreateObject("MetaFrameCOM.MetaFrame
Farm")
if Err.Number <> 0 Then
WScript.Echo "Can't create MetaFrameFarm object"
WScript.Echo "(" & Err.Number & ") " &
Err.Description WScript.Echo ""
WScript.Quit Err.Number

End if
'
' Initialize the farm object.
'
theFarm.Initialize(MetaFrameWinFarmObject)
if Err.Number <> 0 Then
WScript.Echo "Can't Initialize MetaFrameFarm object"
WScript.Echo "(" & Err.Number & ") " &
Err.Description WScript.Echo "quiting "
WScript.Quit Err.Number
End if
'
'
' Are you Citrix Administrator?
'
'
if theFarm.WinFarmObject.IsCitrixAdministrator = 0
then
WScript.Echo "You must be a Citrix admin to run this
script"
WScript.Echo ""
WScript.Quit 0
End If
'
' Display all applications in the farm.
'
'
For Each anApp In theFarm.Applications
if Err.Number <> 0 Then
WScript.Echo "Can't enumerate applications"
WScript.Echo "(" & Err.Number & ") " &
Err.Description WScript.Echo ""
WScript.Quit Err.Number
End if
'
'
Create the user
object. '
Set MFUser = CreateObject("MetaFrame
COM.MetaFrameUser")
MFUser.initialize MFAccountAuthorityADS, AAName,
MFAc
countDomainUser, AcctName
'
' Add the user or group to all published applications.
'
anApp.LoadData(TRUE)
if anApp.AppType = MetaFrameWinAppObject Then

' MetaFrameWinApp object.


Set aWinApp = anApp.WinAppObject
anApp.Adduser MFAccountAuthorityADS, AAName,
MFAccountDomainUser, AcctName
anApp.SaveData
end if
Next
</script>
</job>
</package>

Modifying a Script
You can also modify the script to perform other tasks applicable to your published
applications. For example, replacing the line:
anApp.Adduser MFAccountAuthorityADS, AAName,
MFAccountDomainUser, AcctName

with
anApp.removeuser MFAccountAuthorityADS, AAName,
MFAccountDomainUser, AcctName

removes an Active Directory user or group from all the published applications.
In this example, the MFAccountAuthorityADS and MFAccountDomainUser
enumerations are coded into the calls to add and remove Active Directory users
and groups. If you are adding or removing users and groups from other account
authorities such as Novell Directory Services, Windows NT, or the local machine,
modify these enumerations.

Using Installation Manager to Deploy Windows Installer


Packages
Consider the following issues before you use Installation Manager to deploy
Windows Installer packages (files with the .msi extension).

If you are applying more than one Windows Installer transform file (files with the .mst
extension) to the same Windows Installer package, each transform installs different
components but applies them to the same Windows Installer package. For example, if
you use transforms with an installation file for Microsoft Office, any components you
select in the transforms are not installed even though the installation job appears to
complete successfully.

Recording Microsoft patch packages (files with the .msp extension) is not necessary.
You can browse through Installation Manager and add the *.msp file.

You can uninstall a Microsoft patch package from the target server; however, you
cannot uninstall the patch itself from the server to which it was deployed. If you must
apply another patch to the application installed on the target server, first uninstall the
application on the target server and then deploy the application and the patch again.
Important When multiple Windows Installer packages are installed, a memory
leak can occur in Msiexec.exe. To avoid this, install the latest Windows
service pack.

Force Reinstall Option


When a package is scheduled to be deployed to a target server, Installation
Manager detects if the package is already installed. If an application from the
package is detected, Installation Manager does not deploy the application and
instead reports a status of Already Installed.
If you must overwrite an existing installation, set the Force Reinstall option on
the Properties screen of the already installed package. This new installation can
be used to fix any previously damaged installations or to overwrite the existing
application of the same version with any changes you applied.
Note After the Force Reinstall option overwrites a package, the package you
used to install the original application cannot be used to uninstall the application
from the target server. You can uninstall only the newly installed package.
After you use the Force Reinstall option on the same package, the Installed
Packages tab for the target server reports two records for the same package.

Installation Manager Compatability


The version of Installation Manager that ships with Presentation Server 3.0 or 4.0
also supports packages made using earlier versions of Installation Manager.
However, some applications may cause issues with this backwards compatibility.
Because of this, Citrix recommends that you recreate the packages using the
latest version of Installation Manager. Packages created with earlier versions
may have been packaged on servers that did not have the operating system and
other updates your server farm contains. When recording a package, the source
server should have a configuration similar to that of the target servers.

Using the Application Publishing Wizard


The Application Publishing wizard in the Applications node of the Presentation
Server Console allows you to deploy Installation Manager packages in the
server farm. You can use the Application Publishing wizard to install, publish,
and load balance applications automatically. Additionally, the command line
utility apputil can be used to add and remove servers from these published
packages through scripting, further automating the application installation
process. Installation Manager application packages added to the farm and
installed without using the Application Publishing wizard are not automatically
published or load balanced. For more information about apputil, see the
MetaFrame Presentation Server Administrators Guide.

Uninstalling a Package
By default, a deployed package can be uninstalled using only the original
package. For example, you cannot directly uninstall an ADF package that has a
status of Already Installed. Instead, perform another full installation using the
Force Reinstall option. This new package can be used to uninstall the same
package. The application can also be uninstalled from target servers without
Installation Manager by using Add/Remove Programs in Control Panel.
Note If you uninstall from the Already Installed package, the target server
does not detect the uninstallation and still reports that the package is installed.

CHAPTER 7

Optimizing Citrix
Presentation Server
Performance

This chapter suggests optimizations that can increase the performance of


Presentation Server running in a Windows environment. Many of the
recommendations are based on Microsoft Knowledge Base articles accessible
from the Microsoft Web site at http://support.microsoft.com.

Network Optimization
This section covers a few common network performance issues you can remedy
by adjusting the default Windows network configuration.

Refused Connections
The server can refuse connections because of self-imposed limits specified by the
MaxMpxCt and MaxWorkItem registry values. If this happens, users see the
following errors:
System could not log you on because domain <domainname> is not available.
You do not have access to logon to this session.
Before changing these values, read Microsoft Knowledge Base article 232476.
When modifying the following registry settings, ensure that the MaxWorkItems
value is always four times the MaxMpxCt value. Suggested new values for
MaxMpxCt and MaxWorkItems are 1024 and 4096 respectively.
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\
Services\LanmanServer\Parameters
Name: MaxMpxCt
Type: REG_DWORD
Data: 1024

14
8

Advanced Concepts
Guide

Name: MaxWorkItems
Type: REG_DWORD
Data: 4096

Network Cards
Most 10/100-based network cards auto-sense the network speed by default.
Manually setting these cards prevents the auto-sensing process from
interfering with communication and enforces the desired network speed. If the
server is connected to an auto-sensing switch, apply these settings to this
device as well.
Verify that only necessary protocols are installed, and that the binding order of
those protocols to the network interface card lists the most commonly used
protocol first.

Windows Network Status Icon


Windows 2000 Server and Windows Server 2003 provide an option to show the
network icon in the notification area. When this option is selected in a published
desktop environment, a network icon is displayed in the notification area within
the session. The network icon blinks each time network traffic occurs. The
network icon blinks for each update. When the network icon in the notification
area blinks, it causes the ICA session to update. Because the ICA session is being
updated, network traffic occurs that causes the network icon to blink. This causes
an infinite feedback loop.
To turn off the network status icon
1. Go to Start > Settings > Control Panel > Network and Dial-up Connections
> Local Area Connection.
2. Right-click Local Area Connection and select Properties.
3. Uncheck Show Icon in notification area when connected. In Windows 2000 Server, the
option states, Show Icon in taskbar when connected.
4. Repeat these steps for each network adapter or connection on every server in your farm.

Server Optimization
This section describes ways in which correctly configuring CPU utilization
and Windows settings, services, and applications for use in a multiuser
environment improves performance and prevents system problems.

CPU Utilization Management


The CPU utilization management feature introduced in Citrix Presentation Server
4.0 (requiring an Enterprise edition license) ensures that CPU resources are
equitably shared among users. This is accomplished by providing CPU
reservation and CPU shares.

CPU reservation is defined as a percentage of your servers CPU resource that is


guaranteed to be available to a user. If all of such a reserved allocation is not being
used, other users or processes can use the available resource, as needed. Note that
approximately 20% of the CPU resource is reserved and not available to users. The
percentages stated here are of the available, not the total, CPU resource.

CPU shares are percentages of the CPU time. By default, CPU utilization management
allocates eight shares for each user. If two users are logged onto a server (and no
console session), each of the users gets 50% of the CPU. If there are four users with
eight shares each, each user receives 25% of the CPU time.
Important The range for CPU share is 1-64. For CPU reservation, the total
cannot be more than 100%, which represents the entire CPU resource on the
machine.
The services used for CPU utilization management are CTXCPUUtilMgmt
User/ Session Synchronization and CTXCPUUtilMgmt Resource
Management. In addition to these two services, the Citrix CPU Utilization
Mgmt/CPU Rebalancer service is installed on Windows Server 2003 multiprocessor systems; it is not installed on Windows 2000 Server or servers with
only one processor. The CPU rebalancer service is used to alleviate a Microsoft
issue that appears in environments where a lot of short-lived processes are started
and stopped. Due to the performance impact the CPU rebalancer service can
have, by default it is set to Manual. If your environment is running many
short-lived applications that all appear to be running on the same CPU, setting
the service to Automatic is recommended . The CPU rebalancer service
corrects this by balancing the load equally across processors.

15
0

Advanced Concepts
Guide

Changing Default Values for CPU Share Allotment


It is possible to change the default value of eight shares per user in the registry. If
two users are present and the first user has a need for more CPU time, that user
can be assigned 16 shares, while the second user receives the default eight shares.
This allows the first user to get 66% of the CPU time while the second user
receives the remaining 33%.
1. Open the Registry Editor and browse to
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\CTXCPU.
2. In the right pane, double-click the Policy Multi-String value.
3. In the Edit Multi-String dialog box, go to the end of the NT AUTHORITY\SYSTEM
line and press return to go to the next line.
4. To assign 16 CPU shares for a local user named u1 on a Presentation Server named Server1,
type the following: Server1\u1,cpu.shares=16.
5. Save the settings and exit the Registry Editor.
6. Stop and restart the services CTXCPUUtilMgmt User/Session Synchronization and
CTXCPUUtilMgmt Resource Management.
To change the CPU reservation for users
1. Open the Registry Editor and browse to
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\CTXCPU.
2. In the right pane, double-click the Policy Multi-String.
3. In the Edit Multi-String dialog box, go to the end of the NT AUTHORITY\SYSTEM
line and press return to go to the next line.
4. Set the CPU shares. For example, to set CPU shares of 20% for users named u1, u2,
u3, and u4 on a server named Server1, type the following:
Server1\u1,cpu.reservation=20000
Server1\u2,cpu.reservation=20000
Server1\u3,cpu.reservation=20000
Server1\u4,cpu.reservation=20000
Note The value added in this string represents the desired percentage of
CPU reservation multiplied by 1,000. Twenty percent is thus 20000.
5. Save the settings and exit the Registry Editor.
6. Stop and restart the services CTXCPUUtilMgmt User/Session Synchronization and
CTXCPUUtilMgmt Resource Management.

Note CPU shares and reservation can be assigned only to individual users, not
user groups or applications. Also, CPU time sharing within a session is done by
the operating system and not by CPU utilization management.

Monitoring CPU Utilization Management


You can generate a CPU utilization report by using the Report Center feature in
the Access Suite Console. Generating CPU utilization reports requires the
Resource Manager Summary Database.
Additionally, five performance counters are available for monitoring CPU
utilization management. The counters are listed under the
CTXCPUUtilMgmtUser object on the server. They are:

CPU Entitlement

CPU Reservations

CPU Shares

CPU Usage

Long term CPU Usage.

Note To add the performance counters into Resource Manager or


performance monitor, ensure that the CPU utilization management services
are running .
For more information about the CPU utilization management feature, refer to the
Citrix Knowledgebase article CTX106021.

Auto-End Tasks
If an application does not correctly exit, either when closed or upon server
shutdown, the operating system can terminate the application using the AutoEnd Tasks feature. Auto-End Tasks terminates any task that does not respond
to a shutdown notice within the default time-out period.
Enabling Auto-End Tasks affects all applications on the server and can cause
issues with some applications that require a shutdown time period that is longer
than the default time-out period. Therefore, the default time-out period must be
greater than the time required for the longest successful shutdown for any server
application. To enable Auto-End Tasks and set the default time-out period,
modify the following registry settings:
HKEY_USERS\.DEFAULT\Control Panel\Desktop

Name: AutoEndTasks
Type: REG_SZ
Data: 1
Name: WaitToKillAppTimeout
Type: REG_SZ
Data: x
where x is the interval in milliseconds (default is 20000).
For more information, see Microsoft Knowledge Base articles 123058 and 191805.

System Hard Error Messages


Messages generated by system hard errors appear in the Presentation Server
Console. If left unanswered on an unattended console, messages can cause ICA
sessions to hang. You can configure system hard errors to create an entry in the
system log instead of displaying a message on the console.
Disabling the display of messages to the console decreases the likelihood of hung
ICA sessions, but increases the need to monitor the event log for these types of
errors. For more information, see Microsoft Knowledge Base articles 124873 and
229012.
The following registry change disables system hard error messages on the console:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control
\Windows
Name: ErrorMode
Type: REG_DWORD
Data: 00000002

Dr. Watson
If you are using Dr. Watson, run the Dr. Watson Application Compatibility script
to prevent stability problems. Citrix recommends that you disable the Visual
Notification option available on the main screen of Drwtsn32.exe.
You can disable Dr. Watson completely by clearing the following registry key
value:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows
NT\CurrentVersion\AeDebug
Name: Debugger
Type: REG_SZ
Data: (blank)
You can restore Dr. Watson as the default debugger by executing drwtsn32.exe i.

Configuring the Event Log


Change the default event log configuration to prevent log files from running out
of space, which generates errors.
To change event log settings on Windows 2000 Server and Windows Server
2003
1. Launch Event Viewer.
2. Right-click System Log and choose Properties.
3. Set the Maximum Log Size to at least 1024KB.
4. Choose Overwrite events as needed.
5. Click OK to save the settings.
Repeat Steps 35 for the Application Log.

Configuring Print Job Logging


By default, each print job logs two messages to the system log. On servers with
many users, this feature generates numerous events and fills up the log faster. If
you do not need these messages, you can disable them by changing the following
registry setting:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Print\
Providers
Name: EventLog
Type:
REG_DWORD
Data: 0
Removing the EventLog value from the registry and restarting the server reenables the logging of all print events.

Remote Procedure Call (RPC) Services


When opening RPC-aware applications such as Windows Explorer and Control
Panel, delays of several minutes can result from incorrect service startup settings.
Verify that the RPC service Startup type is set to Automatic and the RPC Locator
service Startup type is set to Manual.

Tuning the Load Bias Level


Prior to the release of MetaFrame Presentation Server 3.0, the data collector
temporarily increased the load of a server for each connection by 200 until it
received a load update from the server. This increase is known as the load bias.
In MetaFrame Presentation Server 3.0, this was changed to calculate the load
bias level based on the load evaluator settings. For example, if a Server User
Load evaluator was configured to report a full load at 40 users, the new bias level
would be 250, not 200. To manually set the load bias level, the following
registry key needs to be added to the farms data collectors and potential data
collectors:
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\IMA\LMS\ForceRegLoadBias
By default, this value is set to 0 (off). To force the load bias to the one
configured in
the registry, set this value to 1. While it is not generally recommended or necessary
to modify the load bias specified in the registry, this setting can be changed
by editing the value of:
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\IMA\LMS\LoadBias
The default value is 200.

Server Service
Configure the Server service to represent the server role more appropriately.
The performance boost realized from this server optimization setting depends
on the function of the server.
For example, if the server has available RAM, select the Maximize
Throughput for Network Applications. Otherwise, select Minimize Memory
Used.
To configure the Server service on Windows 2000 Server and Windows
Server 2003
1. From Control Panel, double-click Network and Dial-up Connections or
Network Connections.
2. Right-click or select Local Area Connection and choose Properties from the
Context menu.
3. Choose File and Printer Sharing for Microsoft Networks.
4. Click Properties.
For more information, see Microsoft Knowledge Base article 154075.

Level 2 Cache
For processors that use a direct-mapped L2 cache, configuring the value manually
can yield a performance improvement. A direct-mapped L2 cache does not
provide performance gains on Pentium II and later processors. For more
information, see Microsoft Knowledge Base articles 228766 and 183063.
Use the following registry setting to modify a direct-mapped L2 cache:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control
\Session Manager\Memory Management
Name: SecondLevelDataCache
Type: REG_DWORD
Data: x
where x is the L2 size in decimal (default: 0, which sets the cache to 256KB)
Example: If the CPU has a 512KB cache, set the entry to 512 (in decimal).

Applications Optimization
This section describes some applications settings and optimizations that can
improve performance.

Removing Unnecessary Features


To conserve ICA bandwidth, remove any unnecessary drive mappings, printers,
or ports. Unless any of the following features are needed for specific applications,
disable them:

Disable Active Desktop on Windows 2000 Server or Windows Server 2003


through Terminal Services Configuration

Desktop Wallpaper (In addition, remove any .bmp files in the %SystemRoot%
directory to prevent users from selecting them.)

Screen savers

Microsoft Office FindFast

Microsoft Office Assistants

Menu Refesh
For a published desktop, you can change the menu refresh rate to expedite menu
response time by modifying the following registry key:
HKEY_USERS\.DEFAULT\Control Panel\Desktop
Name: MenuShowDelay
Type: REG_SZ
Data: 10

Explorer Tips
You can disable the tips that are displayed at server startup by modifying the
following registry settings:
HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows
\CurrentVersion\Explorer\Tips
Name: DisplayInitialTipWindow
Type: REG_DWORD
Data: 0x0
Name: Next
Type: REG_DWORD
Data: 0x100
Name: ShowIE4
Type:
REG_DWORD
Data: 0x0
Name: Show
Type: REG_DWORD
Data: 0x0

Smooth Scrolling
Many applications have smooth scrolling or other features that increase the
frequency of updates sent to the client workstation. If applications exhibit poor
performance, disable these features to improve performance. Two common
settings are in Microsoft Excel and Microsoft Internet Explorer:

Microsoft Excel 97/2000


1. Choose Tools > Options.
2. Click the Edit tab.
3. Clear the Provide feedback with Animation check box.

Microsoft Internet Explorer 5


1. Choose Tools > Internet Options.
2. Click the Advanced tab.
3. Clear the Use Smooth Scrolling check box in the Browsing section.

Tip While the server is in install mode (change user /install), changing
application settings applies the changes to all future users. When finished, place
the server back into execute mode (change user /execute).

Microsoft Internet Explorer Wizard


On the first launch of Microsoft Internet Explorer, the Internet Connection
wizard requests the connection type. If you are using a LAN connection, you
can bypass this dialog box by editing the default users registry settings as
follows:
HKEY_USERS\.DEFAULT\SOFTWARE\Microsoft\Internet Connection Wizard
Name: Completed
Type: REG_DWORD
Data: 0x1

Disk Optimization
Use of the Client Drive Mapping Accelerator feature and also the modification of
certain registry settings can increase disk performance and throughput. This
section describes Client Drive Mapping Accelerator and enhancements such as
increasing I/O locks and disabling last file access updates.

Client Drive Mapping Accelerator


Client Drive Mapping Accelerator is a feature introduced in Presentation Server
4.0 that dramatically speeds up file operations and directory listings within an
ICA session.
To accomplish this increase in disk access performance, the Client Drive
Mapping Accelerator feature uses more paged pool kernel memory than
MetaFrame Presentation Server 3.0; thus it has the potential to cause kernel
memory to become a single server scalability bottleneck in 32-bit operating
systems. (Due to the redesigned Windows Server 2003 memory management
system, this operating system is less likely to be bound by paged pool kernel
memory.) If this bottleneck is encountered, the default size of the paged pool can
be increased by modifying the value of the following registry key for Windows
2000 Server:

\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session
Manager\Memory Management\PagedPoolSize
to -1 (xFFFFFFFF)
To disable Client Drive Mapping Accelerator, modify the value of the following
registry key to 0x00000007:
\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Terminal
Server\Wds\icawd\DriveOptimizeDisable

I/O Locks
The registry setting IoPageLockLimit specifies the limit of the number of bytes that can be locked for
I/O operations. Because RAM is being sacrificed for increased disk performance, determine the optimal
setting for this value through pilot tests. Changing this setting from the default can speed up file system
activity. Use the following table as a guide for changing the registry setting.
Server RAM (MB)

IoPageLockLimit (decimal)

IoPageLockLimit (hex)

64128

4096

1000

256

8192

2000

512

16384

4000

1024+

65536

10000

Modify the registry setting as follows:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control
\Session Manager\Memory Management
Name:
IoPageLockLimit Type:
REG_DWORD
Data: 0 (512KB is used)
For additional information about the IoPageLockLimit registry setting, see
Microsoft Knowledge Base articles 121965 and 102985.

Last Access Update


The NTFS file system stores the last time a file was accessed, whether it is
viewed in a directory listing, searched, or opened. In a multiuser environment,
this updating can cause a small performance decrease. To disable this feature,
modify the following registry setting:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem
Name: NtfsDisableLastAccessUpdate
Type: REG_DWORD
Data: 1

Memory Optimization
This section describes optimal configuration of virtual memory, the system page
file, and system page table entries.

Virtual Memory
The virtual memory optimization feature introduced in Citrix Presentation
Server 4.0 (requiring an Enterprise edition license) reduces the amount of
virtual memory usage by rebasing DLLs to optimized virtual addresses. This
rebasing modifies a copy of a DLL so that it loads at an optimal base memory
address to avoid collisions and relocations and the performance impact they
cause.

Services Required for Virtual Memory Optimization


The Citrix Virtual Memory Optimization Service is responsible for the virtual
memory optimization feature. The scheduling of memory optimization is
done using the Presentation Server Console.

Scheduling of Memory Optimization


By default, rebasing is scheduled to occur daily at 3:00AM. Use the options in
the Memory Optimization node under Farm Properties in the Presentation
Server Console to change the default scheduling. Also, an alternate user account
can be selected to run the scheduled task instead of using the local system
account.

16
0

Advanced Concepts
Guide

Exclusion List
Some applications are excluded from being rebased by virtual memory
optimization:

Applications that have digitally signed components.

Applications whose DLLs are protected by Windows Rights Management. For


example, applications such as Office 2003 do not benefit from this feature.

Applications whose executable programmatically checks the DLL after it is loaded.


For instructions about how to exclude applications, see the MetaFrame
Presentation Server Administrators Guide.
Note The digitally signed files and the components protected by Windows
Rights Management are detected by the system automatically and are excluded
from rebasing. The excluded DLLs and executables are in the registry at the
following locations:
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\SFO\ComponentExclusionLis
t and
KEY_LOCAL_MACHINE\SOFTWARE\Citrix\SFO\ProcessExclusionList

Troubleshooting DLL Rebasing


The following sections discuss how you can troubleshoot the rebasing of DLLs
that occurs when the virtual memory optimization feature is used.

Using Process Explorer to View Rebased DLLs


You can use Process Explorer from http://www.sysinternals.com to verify
whether or not memory optimization is truly rebasing DLLs. The goal of the
feature is to reduce the relocation of DLLs for applications. Process Explorer
shows the relocated DLLs and if the feature is working correctly, the number of
relocated DLLs is minimal.
To use Process Explorer
1. Install Process Explorer on all servers running Presentation Server.
2. Launch Process Explorer and click the View DLLs button.
3. In the Options menu, choose to configure highlighting and check the Relocated DLLs box.
4. When Process Explorer is configured, if you select a running process from the upper panel, the
DLLs or components that are loaded by that process are shown in the lower panel and the
relocated DLLs are highlighted.

Using the Repair.sfo File to View Rebased DLLs


Repair.sfo is an XML file located in Program Files\Citrix\Server Resource
Management\Memory Optimization Management\Data, that contains a list of
DLLs that were rebased or are in pending status. The file is created by the
Citrix Virtual Memory Optimization Service (CtxSFOSvc.exe).

Report Generation for Virtual Memory Optimization


You can use the Report Center feature in the Access Suite Console to generate a
report listing the virtual memory savings received when this feature is being
used.
For more information about the virtual memory optimization feature, refer to the
Citrix Knowledgebase article CTX106023. For a list of applications that show
positive results in virtual memory savings when using the virtual memory
optimization feature, see the Citrix Knowledgebase article CTX106022.

Page File
The page file is temporary storage used by the operating system to hold program
data that does not fit into the physical RAM of the server. The ratio of physical
memory to paged memory is the most important factor when determining the
size of a page file. When configuring the page file, follow these guidelines:

Place the page file on its own disk controller or on a partition that is separate from the
operating system, application, and user data files. If the page file must share a partition
or disk, place it on the partition or disk with the least amount of activity.

To prevent disk fragmentation of the page file, always set the page file initial size to
be the maximum size.

The optimal size of a page file is best determined by monitoring the server under a peak
load. Stress the server while observing the size of the page file. To conserve resources,
set the page file to a value slightly larger than the maximum utilized while under stress.

If the server is short on physical RAM, use the page file to provide additional
memory at the expense of performance.
Note For debugging purposes, create a page file on the root partition that
is slightly larger than the amount of RAM installed.

Page Table Entries


You can improve the number of users that can utilize a single server by manually
adjusting the page table entries (PTE) in the registry. The Windows kernel uses
PTE values to allocate physical RAM between two pools of memory. By
manually setting the maximum space allocated to the system PTE, the remaining
space can be used to increase the number of users supported on the server.
Determining the optimal configuration for PTE values is a complex task. For
detailed information, see the Microsoft Knowledge Base article 247904. A
Kernel Tuning Assistant for Windows 2000 Server is also available from
Microsoft.

User Settings Optimization


This section describes how correctly setting up users can provide additional
performance gains. Where possible, modify the Default User profile to include
the recommendations discussed here.
Tip When making changes to the Default User profile, restarting the server might
be necessary before the changes take effect because the Ntuser.dat file is in use
and unavailable to new users.

Windows Policies
Use system and group policies where possible, especially in an Active Directory
environment. For more information about configuring policies, see Microsoft
Knowledge Base articles 161334 and 260370.

Profiles
Users require an initial setup when logging on for the first time. This setup time is
minimized by the use of roaming profiles. For more information about configuring
roaming profiles, see Microsoft Knowledge Base articles 142682 and 154120.
When you set up roaming profiles:

Configure a dedicated server to host the profiles. If it is not possible to place the
profiles on a dedicated server, place them on an isolated disk or partition.

When using a server or drive dedicated to profiles and temp files, change the users
profile and temp directories to point to the dedicated location.

You can disable locally cached profiles by changing the access of the
following registry key and all subkeys to Read access only for everyone
except SYSTEM (which should have Full Control):
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WindowsNT
\CurrentVersion\ProfileList

Audio Recording Optimization


One of the features introduced with MetaFrame Presentation Server 3.0 (and with
Presentation Server Clients Version 8.0 or higher) is the ability to record sound in
an ICA session. This allows users to dictate a recording in one session, and then
have that data transcribed at a later date. This process is usually facilitated by
third party software, such as WinScribes Internet Author and Internet Typist,
used in conjunction with Philips SpeechMike devices or similar hardware.
Note The settings that control SpeedScreen Multimedia Acceleration are
totally separate from the settings that control the recording of audio; a user
could use SpeedScreen Multimedia Acceleration for playback and optimize the
settings for recording without degrading playback quality.

Setting up Audio Recording


Configuring the Server
By default, Presentation Server can record audio using a standard microphone.
To use the Philips SpeechMike devices, however, drivers must be installed on all
servers that are to have sessions that record audio. It is recommended that the
Philips drivers be installed before installing Presentation Server.
If using WinScribes Internet Author or Internet Typist, these programs also must
be installed on the servers. Refer to the WinScribe documentation for any setup
instructions. If the Philips SpeechMagic Speech Recognition server is used in
conjunction with WinScribes software, high quality audio is required for accurate
speech to text translation. This is because high quality audio does not use lossy
compression on the recorded audio, which can interfere with the accuracy of the
speech recognition algorithms.
Configure published desktops or published recording applications to use legacy
audio. Set the client connections ICA Settings Audio Quality to medium or high.
Medium is the default and is satisfactory for most applications.
Policies can also be used to control audio recording. See the policy
documentation in the MetaFrame Presentation Server Administrators Guide for
more information about configuring policies.

Configuring the Client


The client must have an audio playback device, such as a soundcard, and an
audio recording device, such as a microphone. The Philips SpeechMike devices
often serve both purposes.
Audio Recording works on Program Neighborhood, the Program Neighborhood
Agent, and Web Interface clients, and it needs to be enabled on whichever of
these clients is being used. Ensure that either desktop sessions or published audio
recording applications are correctly configured to allow sound in the client
settings. For most uses, medium audio quality is the recommended setting.
Ensure that the audio security settings, available from the Connection Center or a
sessions system menu, are configured to allow the recording of audio. These
settings work in the same manner as the preexisting file security dialogs.

Using the Philips SpeechMike


Ensure that the drivers for the device are installed correctly on both the client
and server. Make sure that the recorder works correctly on the local client. Do
this by loading the recorder utility that comes with the drivers. Ensure that
audio records and plays back locally.
Presentation Server supports using the SpeechMike controls and foot pedal
devices as well. Before attempting to use them in a session however, test them
locally in the Philips recording utility. If everything works locally on a client
device, the devices work in an ICA session.
SpeechMike controls may also need to be enabled inside the recording
application in use. This is currently true for Internet Author and Internet Typist.
See the applications documentation for details. Additionally, Citrix testing has
experienced issues with configured USB foot pedals in Internet Author and
Internet Typist. Citrix recommends that you use the default settings for these
devices.

Client Audio Mapping Virtual Driver


This section describes the configuration parameters for the Client Audio
Mapping Virtual Driver and best practices for changing these settings in the
Module.ini file.

NumCommandBuffers = 64

Description defines how many server-to-client commands can be buffered.

Maximum Limit = 65000.

Minimum Limit = 0. Setting this value to 0 causes the client to slow down or become
unresponsive to the commands sent by the server. Buffers must be defined because
after executing a command sent by the server, clients look in the buffer for the next
command. Also, if there are no buffers, the commands sent to the client by the server
might not be stored on the client and executed.

Recommended Value = 64.

NumDataBuffers = 24

Description = the maximum number of buffers that will be dynamically allocated.


This is only for 9.x Presentation Server Clients for 32-bit Windows; for previous
versions of the client connecting to Presentation Server 4.0, this setting defines how
many data buffers are available on the client to store the sound data sent by the server
to the client.

Maximum Limit = 65000. Setting this value too high leads to memory hogging on the
client, resulting in degraded performance.

Minimum Limit = 0. If this value is set to 0, no data buffers are available on the client.
The audio data being sent from the server to the client is not stored and eventually does
not play.

Recommended Value = 24.

MaxDataBufferSize = 2048

Description defines the size of the data buffer and also how many bytes of sound
data can be sent to the client from the server.

Maximum Limit = 2048 bytes. Out of 2048 bytes, 10 bytes are reserved for the sound
packet header while the remainder is the actual audio data that is played on the client.

Minimum Limit = 1000 bytes.

Recommended Value = 2048 bytes for the best sound performance on the
client.

CommandAckThresh = 1

Description defines the number of commands that a client receives before sending
an acknowledgement to the server.

Maximum Limit: depends upon the NumCommandBuffers.

DataAckThresh = 1

Description defines the number of sound packets the client receives before sending
an acknowledgement to the server.

Maximum Limit depends upon the NumDataBuffers.

AckDelayThresh = 50

Description defines how many milliseconds the client waits before it sends an
acknowledgement to the server for all the commands received from the server.

Maximum Limit = 350. AckDelayThresh and CommandAckThresh are not


interdependent. For example, if CommandAckThresh is set to 10 and AckDelayThresh
is 350 but 350 milliseconds did not elapse since the client last sent an acknowledgment
but 10 commands were sent by the server to the client, the client still sends the
acknowledgment. The same holds true if the 350 milliseconds passed but the server did
not send 10 commands. The client sends the acknowledgement to the server without
waiting for 10 commands.

PlaybackDelayThresh = 50

Description defines how many milliseconds the client waits before it sends an
acknowledgement to the server for all the sound data/packets received from the server.

Maximum Limit = 250. PlaybackDelayThresh and DataAckThresh are not


interdependent.

ICA Priority Packet Tagging


ICA priority packet tagging is a feature that identifies and tags ICA data based on
the virtual channel from which the data originated. This tagging allows a more
granular Quality of Service (QoS) solution by providing the ability to prioritize
ICA sessions based on the virtual channel data being transmitted. This section
describes virtual channel priorities and how ICA data is tagged with these
priorities when sent over an Ethernet network using TCP/IP.

Virtual Channel Priorities


ICA Priority Packet Tagging provides the ability to prioritize ICA sessions based
on the virtual channel data being transmitted. TCP/IP must be the protocol used.
This is accomplished by associating each virtual channel with a two-bit priority.
This two-bit priority is included as part of each ICA framing header. The two
priority bits combine to form four priority values:

00 (0) High Priority

01 (1) Medium Priority

10 (2) Low Priority

11 (3) Background Priority

Each virtual channel is assigned one of these priority values. The default
virtual channel priorities are as follows:
Virtual Channel

Default Priority

Description

CTXTW

Remote windows screen update data (ThinWire)

CTXTWI

Seamless windows screen update data (ThinWire)

CTXCLIP

Clipboard

CTXCAM

Client audio mapping

CTXLIC

License management

CTXVFM

Video server video (that is, not ThinWire video)

CTXPN

Program Neighborhood

CTXCCM

Client COM port mapping

CTXCDM

Client drive mapping

CTXCM

Client management (Client Auto Update)

CTXLPT

Printer mapping for non-spooling clients (that


is, WinTerms)

Virtual Channel

Default Priority

Description

CTXLPT2

Printer mapping for non-spooling clients (that is,


WinTerms)

CTXCOM1

Printer mapping for non-spooling clients (that


is, WinTerms)

CTXCOM2

Printer mapping for non-spooling clients (that is,


WinTerms)

CTXCPM

Printer mapping for spooling clients

OEMOEM

Used by OEMs

OEMOEM2

Used by OEMs

The priority settings for all virtual channels are stored in the following Registry
key:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Terminal
Server\Wds\icawd\Priority (REG_MULTI_SZ)
This key contains one line for each virtual channel in the format:
VirtualChannelName,Priority
VirtualChannelName is the standard virtual channel abbreviation as specified in
the table. VirtualChannelName must be seven characters, so trailing spaces must
be added before the comma when necessary. Priority is one of the following
numeric priority values: 0, 1, 2, 3.
The ThinWire virtual channels (CTXTW and CTXTWI) are the only high
priority virtual channels by default, thus ensuring that time-sensitive user
interface data is sent ahead of all other data.

ICA Data Transmission


The implementation of ICA Priority Packet Tagging is best understood by
examining how ICA data is packaged for transmission across an Ethernet
network using TCP/IP.

The following diagram depicts the flow of ICA data through each protocol layer
as it is generated by the client application (or server) and packaged for delivery
to a server (or client application) over a TCP/IP network:

ICA data travels through the same protocol layers but in the reverse direction
when received at the destination (client or server). All ICA protocol layers reside
at the presentation layer of the OSI networking model. The ICA protocol layers
depicted in the diagram are described further in the following sections.

Drivers Used with Virtual Channels


Each virtual channel has its own driver that sends data to the WinStation driver.
The format of the virtual channel data is not standardized because it depends
completely on the virtual channel implementation. The following drivers are also
used to support virtual channel communication:

17
0

Advanced Concepts
Guide

WinStation Driver
The WinStation driver receives ICA virtual channel data from multiple virtual
channel drivers and packages the data for receipt by lower network layers. The
WinStation driver works at the Application, Presentation, and Session layers of
the OSI networking model. The WinStation driver establishes the ICA session
between the client and the server, and maintains session information such as
whether or not compression and encryption are turned on, and whether or not
ICA Priority Packet Tagging is used. It also encodes ICA command information
and transforms input virtual channel data into ICA packets, which are placed in
the WinStation drivers input buffer.

Encryption Protocol Driver


When encryption is turned on, the encryption protocol driver adds an encryption
header to the output buffer data passed from the WinStation driver. All data after
the encryption header is encrypted, including the compression header (if
included).

Framing Protocol Driver


The framing protocol driver calculates the byte count of the output buffer and
adds a framing header. In addition to the byte count, the framing header includes
a two- bit priority value as determined by the WinStation driver. For example, if
the total byte count of the output buffer is 1320 bytes and the packet is high
priority, the binary value of the framing header is as follows:

The low order and high order bytes are reversed for network transmission and the
framing header is created as follows:

CHAPTER 8

Security Issues and


Guidelines

This chapter includes information about securing your server farm. The
information in this chapter is intended to supplement the information about
securing Presentation Server environments found in the following documents:

The Secure Gateway for Windows Administrators Guide

The MetaFrame Presentation Server Administrators Guide

The Web Interface Administrators Guide

The administrators guides for the Presentation Server Clients

Improving Your Server Security


This section describes how you can make your farm servers more secure.

Configuring Administrator Accounts


Limit administrator accounts to users who are members of the Windows network
administrators group. This group is presumed to be well controlled and to have
administrative access to network resources, including print servers.
To lessen the risk of compromising the domain administrator account, use a global
group of limited user accounts to administer servers in the farm.
To configure administrator accounts using a global group
1. In the domain where you manage user accounts, create a domain global group.
In this example, this group is named ServerAdmins.
2. Add the user accounts of people who need administrator privileges to the ServerAdmins
global group.
3. Add the ServerAdmins global group to each servers local Administrators group.

17
2

Advanced Concepts
Guide

4. In the Presentation Server Console, add the ServerAdmins global group to the list of
administrators.
5. When a new user account requires administrator privileges, add the account to the
ServerAdmins global group.
When administrators are members of an Active Directory domain, use a domain
local group for farms within a single Active Directory domain or a universal
group for farms that span a forest.

Configuring the SNMP Service


The SNMP service on Windows has read/write privileges by default. If you use
Network Manager or other SNMP management software for monitoring only the
server (not remote management), Citrix recommends that the privileges be read
only. If no SNMP consoles are used, remove the SNMP service from the server.
Note You must give read/create permissions to the SNMP service for
administrative tasks, such as logoff and disconnect through Network
Manager.
You can configure the SNMP community and designated management consoles
to prevent unauthorized access. Configure SNMP agents to accept traps from
known SNMP consoles only.
Microsoft has released security bulletins for SNMP security risks on Windows
NT 4.0 (MS00-095, MS02-006) and Windows 2000 Server (MS00-096, MS02006).
Tip Block incoming SNMP traffic from the Internet by using a firewall
that prevents passage of traffic on UDP ports 161 and 162.

Using NTFS Partitions


For maximum security, install Presentation Server only on NTFS-formatted disk
partitions. This ensures that the local Access databases are secured because the
folder %Program Files%\Citrix\Independent Management Architecture is marked
so that only system and local administrators have full control. Do not change
these Access Control Lists (ACLs).

Controlling Connection Access


For increased control of access to the Terminal Server listeners, use the Citrix
Connection Configuration Tool (Mfcfg.exe) to remove the Everyone group from
the Permissions list for each of the listeners and specify only the user groups
that require access.
Note On Windows Server 2003 it is no longer necessary to remove the
Everyone group from the Permissions lists of the listeners.

Security Considerations for the Data


Store
Users who access your farms servers do not require and should not be granted
any access to the data store.
When the data store connection is a direct one (that is, no intermediary server is
used) , all of the servers in the server farm share a single user account and
password for accessing the data store. Select a password that is not easy to
deduce. Keep the user name and password secure and give it to administrators
only for the purposes of installing Presentation Server.
If the user account for direct mode access to the database is changed at a later
time, the Citrix IMA Service fails to start on all servers configured with that
account. To reconfigure the Citrix IMA Service password, use the dsmaint
config command on each affected server. For information about the dsmaint
config command, see the MetaFrame Presentation Server Administrators Guide.
Citrix recommendations for securing the data store vary depending on the
database you use for the data store. The following sections discuss security
measures to consider for each of the database products supported by Presentation
Server.

Microsoft Access
For an Access data store, the default user name is citrix and the password is
citrix. If users have access to the data store server, change the password using
dsmaint config and keep the information in a safe place.
Important Be sure to create a backup of your data store before using
dsmaint config to change the password on your data store.

Microsoft SQL Server


The user account that is used to access the data store on Microsoft SQL Server
has public and db_owner roles on the server and database. System administrator
account credentials are not needed for data store access; do not use a system
administrator account because this poses an inherent security risk.
If the Microsoft SQL Server is configured for mixed mode security (you can use
either Microsoft SQL Server authentication or Windows NT authentication), you
may want to create a Microsoft SQL Server user account for the sole purpose of
accessing the data store. Because this Microsoft SQL Server user account would
access only the data store, there is no risk of compromising a Windows domain if
the users password is compromised.
Tip For high-security environments, Citrix recommends using only Windows
NT authentication.
For tighter security, you can change the user accounts permission to db_reader
and db_writer after the initial installation of the database with db_owner
permission.
Important Changing the user accounts permission from db_owner may cause
problems installing future service packs or feature releases for Presentation
Server. Be sure to change the account permission back to db_owner before
installing a service pack or feature release for Presentation Server.

Microsoft SQL Desktop Edition


Windows NT Authentication is supported for the Microsoft SQL Server Desktop
Edition (MSDE) database. For security reasons, Microsoft SQL Server
authentication is not supported. For further information, consult Microsoft
documentation. The user name and password typically is the local system
Administrator account. If users have access to the data store server, change the
password with the command dsmaint config and keep the information in a safe
place.

Oracle
If the data store is hosted on Oracle, give the Oracle user account that is used for
the server farm connect and resource permissions only. System administrator
(system or sys) account permissions are not needed for data store access.

IBM DB2
If the data store is hosted on IBM DB2, give the DB2 user account that is used
for the server farm the following permissions:

Connect database

Create tables

Register functions to execute to database managers process

Create schemas implicity

System administrator (DB2Admin) account permissions are not needed for data
store access.

Network Security Considerations


Place servers and the farms data store on networks that are more secure from
network packet capturing or sniffing. In some instances, including the
following, server-to-server communication is in clear text:

Communication between the Presentation Server Console and the member servers
over TCP port 2513, by default

Communication between the member servers and the data collectors over TCP port
2512, by default
Note You can use the imaport utility to change the IMA communication
ports to decrease security risks.

Communication between the member servers and the data store through ODBC

Microsoft SQL Server communication is secure when the multi-protocol


encryption option is configured correctly on both the Microsoft SQL Server and the
clients. For more information about enabling multi-protocol encryption, consult the
Microsoft SQL Server documentation.

Securing Your Network against Denial of Service Attacks


Denial of service (DoS) attacks saturate networks and servers with useless calls
for information. Attackers use multiple sites to make distributed attacks on one or
more networks, servers, or Web sites. Servers subjected to this sort of attack
either become unresponsive or too busy to be of use when a network becomes
flooded. Not only is the network compromised for communication, it also
becomes unavailable as a tool for tracing the attacks.

See the Microsoft Web site for recommendations for fixing registry settings to
make your networks and servers less prone to network DoS attacks. Try a
keyword search using Security Considerations for Network Attacks to see this
information. Microsoft suggests changing the following registry settings to help
secure your network against DoS attacks:

SynAttackProtect

TcpMaxHalfOpen

TcpMaxHalfRetried

Enable PMTUDiscovery

NoNameReleaseOnDemand

EnableDeadGWDetect

KeepAliveTime

PerformRouterDiscovery

EnableICMPRedirects

Securing the Citrix Presentation Server Console


The Presentation Server Console is a Java application that can be run on your
farms servers. Run the console only in environments where packet sniffing
cannot occur.
To run the console on a remote server
1. Make a secure connection from a client to a server.
2. Launch the console in the ICA session.
3. In the Log On to MetaFrame Farm dialog box, select the server on which the ICA session is
running.
Ensure that only administrators have access to the console. You can set NTFS
permissions so that non-administrators do not have Execute permission for the
console executable (Ctxload.exe).

Using SSLAutoConfig to Download and Configure


Certificates
Citrix SSL Relay can help secure communications among clients, servers
running the Web Interface, and computers running Presentation Server using
Secure Sockets Layer (SSL) or Transport Layer Security (TLS). To simplify the
initial configuration of SSL Relay, you can use a Citrix tool, SSLAutoConfig.
SSLAutoConfig can complete either of the following tasks:

Download and install certificates, configure the SSL Relay registry, and restart services

Download certificates without configuring SSL Relay

To set up SSL Relay, run SSLAutoConfig on each server in your server farm.
You can find SSLAutoConfig in the Support/SSL folder of the Server
installation
CD for Presentation Server.
The requirements for running SSLAutoConfig are:

Run SSLAutoConfig as a domain administrator

The servers on which you are running SSLAutoConfig must be in the same domain
as the server running your Certificate Authority (CA)
To use SSLAutoConfig

1. Copy the files sslautoconfig.exe and settings.ini from the Support/SSL folder of the Server
installation disk to a local folder.
2. Edit settings.ini so that it is correct for your servers.
A. Set DNSSuffix to the fully qualified domain name of the server on which you are
running SSLAutoConfig. To determine your DNSSuffix, enter ipconfig at a command
prompt and in the output find the value Connection-specific DNS Suffix.
Example:DNSSuffix=citrix.com
B. Set KeySize to the size of your certificate security key with its value bit- shifted 16 to
the left. Here are some common values:
512 = 33554432
1024 = 67108864
2048 = 134217728
Example: KeySize=33554432
C. Set CertServ to the name of the computer hosting the CA server and the name of the
CA server for which you are requesting a certificate.
Example: CertServ=mfcasrv01\MetaFrame CA

D. Set distinguished name settings according to your local attributes. For the value of
Country, use your two-character country code.
Examples:
OrgUnit=IT
Organization=Citrix Systems
Local=Fort Lauderdale
State=Florida
Country=US
E. Set OID to the type of certificate you are using.
Currently SSLAutoConfig supports only the OID setting for Server
Authentication Certificate, which is 1.3.6.1.5.5.7.3.1.
Example: OID=1.3.6.1.5.5.7.3.1
F. Set CertificateTemplate to select the correct authentication template to pass to the policy
engine. Certificate templates are used by newer certificate servers, such as those used in
Windows 2003. Currently, the only certificate template supported by SSLAutoConfig is
WebServer.
Example: CertificateTemplate=WebServer
3. On each server you want to configure, create a folder for running
SSLAutoConfig.
4. Copy your configured settings.ini file and sslautoconfig.exe to the folder you created on each
server you want to configure.
5. On each server you want to configure, from a command prompt, make the directory in
which SSLAutoConfig resides your current working directory.
6. On each server you want to configure, run SSLAutoConfig as a domain administrator.
For more information about the syntax and parameters associated with
SSLAutoConfig, see SSLAUTOCONFIG on page 288 in Appendix A.

Securing Client Communication


Depending on your environment, several features included with Presentation
Server allow you to further secure communications between clients and servers.
Presentation Server includes support for ICA encryption, which uses RSAs RC5
encryption, between servers and clients. Support for open standards technology has
been added, as has Citrix SSL Relay, which uses standard Secure Sockets Layer
(SSL) encryption between servers and clients.

MetaFrame XP Feature Release 2 and later includes the Secure Gateway for
MetaFrame. The Secure Gateway provides an SSL/TLS Internet gateway between
servers and clients located on the Internet.
For more information about setting encryption, see the Secure Gateway
Administrators Guide, the MetaFrame Presentation Server Administrators
Guide, and the Administrators Guides for the clients.

Securing Web Interface Communication


When using the Web Interface, you can put in place the following to secure
client- to-server communication:

Instruct users to connect to the Web Interface pages using HTTPS (secure HTTP).
The IIS server must have an SSL certificate installed to establish a secure HTTP
connection.

Configure the Web Interface ticketing feature to further secure the direct
communication between the clients and the servers.

Configure the Web Interface to use SSL Relay for encryption between the Web server
running the Web Interface and the servers.

If you are configuring SSL Relay on a server with a static IP address, set the following
registry key to the fully qualified domain name (FQDN) of the server:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\
Tcpip\Parameters\Domain
Tip To ensure that only ICA connections using SSL (typically port 443)
are allowed through a firewall, block port 1494.

Disabling Pass-Through Authentication


If your network does not have a mechanism to automatically log off inactive
users, you may want to disable pass-through authentication to prevent
unauthorized access to your server farm.
To disable pass-through authentication
1. In Program Neighborhood, choose Tools > ICA Settings.
2. Clear the check box for the Pass-Through Authentication option.

18
0

Advanced Concepts
Guide

3. Delete the following files from the client files folder to disable the feature and prevent a user
from enabling it again in the client:

Ssoncom.exe

Ssonstub.dll

Ssonsvr.exe

To disable pass-through authentication in Program Neighborhood Agent


1. Uninstall the client from Add/Remove programs.
2. Reinstall the Program Neighborhood Agent and ensure that you do not enable Pass-Through
Authentication when prompted during the install.
3. Delete the following files from the client files folder to disable the feature and prevent a user
from enabling it again in the client:

Ssoncom.exe

Ssonstub.dll

Ssonsvr.exe

4. Use the Program Neighborhood Agent Console or edit the Config.xml file to disable PassThrough Authentication under authentication options.

Configuring Proxy/Firewall Integration


The folowing sections discuss how to improve the security of your client-server
connections through the use of a firewall or a proxy server.

Securing Client Connections through a Proxy/Firewall


This section covers recommended configurations for clients connecting through a
firewall with SOCKS support or Secure Proxy connections. It assumes that the
firewall or Secure Proxy server is configured according to the servers
documentation and recommended configurations. For the purpose of this section,
the default ports are used for each component of the firewall/proxy policy
configuration.
The typical ports are as follows:
ICA Port: 1494
Common Gateway Protocol: 2598
SOCKS (v4 or v5): 1080

Web Proxy: 80 and/or 8080


Secure Proxy: 443 and/or 563
Note Some Web proxy configurations may use port 3128 as the default
Web proxy port.

NTLM Support
Windows NT LAN Manager (NTLM) authentication support was added starting
with client Version 7.00.14874. Prior to Version 7.00.14874, only SOCKSV5
and Secure Web Proxy authentication were supported, both of which use cleartext (basic authentication) to transmit the password information. NTLM
authentication is a Microsoft proprietary method that is more secure than basic
authentication and does not use clear text to transmit password information. It is
supported with Microsoft Proxy Server 2.0 and Microsoft ISA server. NTLM is a
challenge/ response process where the server challenges the client to encrypt a
random number with the client's password hash, while the server sends the same
challenge to the domain controller along with the clients response. The domain
controller decides the authenticity of the request.

Proxy ICA/INI File Parameters


If clients are connecting to a server farm through a proxy server, you must add
the following parameters to the users .ini files (located in %userprofile
%\Application Data\ICA Client\) or ICA files (including the Web Interface and
Citrix Program Neighborhood Template.ica) on the client device.
Each parameter is defined later in this section.
Add the parameters to the [WFCLIENT] section of the .ini or .ica file or in the
[<APPLICATION>] section only if the DoNotUseDefaultCSL=ON parameter is
set in the same section.

INI File Parameters for Client Version 6.20.986


ICASOCKSProtocolVersion={-1|0|4|5}
ICASOCKSProxyHost=FQDN Proxy Address or IP Address
ICASOCKSProxyPortNumber=Proxy Port
ICASOCKSrfc1929UserName=SOCKSv5 User Name
ICASOCKSrfc1929Password=SOCKSv5 User Name Password
ICASOCKSTimeout=Time in milliseconds after the client waits for initial
response from the proxy server

INI File Parameters for Client Version 6.30.1050


Tip The 6.30.1050 Version of the client responds to the 6.20.986 parameters
for backward compatibility.
ProxyType={None|Auto|Socks|SocksV4|SocksV5|Secure|Script}
ProxyHost=Proxy Address:Proxy Port or IP Address:Proxy Port
ProxyBypassList=Domain names/IP Addresses that the Proxy Server ignores at
connection time
ProxyAutoConfigURL=Address of Http server path of Auto-Configuration File
ProxyUsername=SOCKSv5/Secure Proxy Username
ProxyPassword=SOCKSv5/Secure Proxy Password
ProxyTimeout=Time in milliseconds after the client waits for initial response
from the proxy server; minimum value is 1000

Definitions of the Parameters


ProxyType. Determines the type of connection used by the client device.
None is the client always uses a direct connection to the server; there is no
connection to the proxy/firewall server
Auto uses the client devices Web browser settings (Microsoft Internet Explorer
4.x or later, Netscape Navigator 4.76 or later)
SOCKS creates a SOCKS connection to the server and auto-detects the SOCKS
version number used by the proxy/firewall
SOCKS V4 creates SOCKS Version 4 connections
SOCKS V5 creates SOCKS Version 5 connections
Secure connects through a secure tunnel protocol; usually a high encryption or
SSL/ TLS connection. You must configure the Citrix SSL/TLS Relay or use the
Secure Gateway for MetaFrame Presentation Server. Citrix recommends that you
use the SSL/TLS+HTTPS connection protocol or use TCP/IP+HTTPS and set
the encryption to 128-bit.
Script uses the JavaScript Proxy Auto-Configuration file (*.PAC) or the
Microsoft Internet Explorer Internet Settings file (*.INS) to configure the proxy
connection set in the mentioned formats. Set the ProxyType to Auto and use the
clients Web browser preferences for auto-configuration scripts. The path to the
file is set in the ProxyAutoConfigURL parameter.

ProxyHost. Includes the address of the proxy host and port number. To set the
IP address of the proxy server or to use its fully qualified domain name (FQDN),
enter the proxy/firewall port number at the end of the address using the following
sample formats: 192.168.0.1:8080 or proxy.citrix.com:1080.
ProxyBypassList. A semicolon- or comma-separated list of server addresses for
which the client will not use a proxy server.
For example: ProxyBypassList=*.company.net;10.12.*.*
The ProxyBypassList parameter is ignored if ProxyType=Auto or
ProxyType=None. When ProxyType=Auto, configure the bypass list in the
default Web browser. Use an asterisk as a wildcard character to bypass a group
of servers, such as: *.company.com or 192.18.*.*; 10.*.*.*
ProxyAutoConfigURL. Allows you to include an HTTP URL to a JavaScript
Proxy Auto-Configuration file (*.PAC) or the Microsoft Internet Explorer
Internet Settings file (*.INS).
This setting is used when an administrator wants to centralize proxy or firewall
server-client configuration by using a script file. The script file can be either a
JavaScript PAC file or Microsoft Internet Explorer INS file. For information
about creating these files, see the following:
MSDN Article on PAC Files:
http://www.microsoft.com/mind/0599/faq/faq0599.asp
Internet Explorer Administration Kit Article:
http://www.microsoft.com/windows/ieak/techinfo/deploy/60/en/ default.asp?
URL=/windows/ieak/techinfo/deploy/60/en/autodis.htm
ProxyUsername/ProxyPassword. Location to configure the SOCKS 5 or Secure
Proxy authentication credentials.
If the ProxyUsername/ProxyPassword parameters are not set and the proxy or
firewall connects the client to a server configured for SOCKS 5 or Secure Proxy
with authentication, the user is prompted for credentials. The user credentials are
for proxy authentication only and may not be the same as the users domain or
network credentials. When the ProxyUsername/ProxyPassword parameters are
set, the client passes the users credentials to the proxy server.

Important On any SOCKS 5 or Secure Proxy server configured to require


authentication, the user name and password are passed in clear text. Citrix
recommends that you do not set these parameters if credentials are going to be
passed through a public network such as the Internet. Even if the ICA connection
is set to use SSL/TLS+HTTPS, the credential packets are sent before any secured
tunnel is established. Note that this is not true for NTLM authentication, which is
supported by clients starting with Version 7.00.14874
ProxyTimeout. The time in milliseconds after the client waits for initial
response from the proxy server

Program Neighborhood and Proxy/Firewall Connections


You can improve the security of your client-server communications by selecting
the firewall settings that a Program Neighborhood Client connection uses.
To select the firewall settings for a Program Neighborhood connection
1. In Program Neighborhood, select a custom connection and click File >
Application Set Settings.
2. In the dialog box that appears, click the Connection tab and in the Server Location section
click the Firewalls button and select one of the following options:

Use Web browser proxy settings sets the ProxyType parameter to a value of Auto.

None (direct connection) sets the ProxyType parameter to a value of None.

SOCKS sets the ProxyType parameter to the value SOCKS. To specify a version
number for SOCKS, edit the users Appsrv.ini file and change the value for the
ProxyType to the correct version parameter. Add the proxy address and port fields to this
setting.

Secure (HTTPS) sets the ProxyType parameter to a value of Secure. You must specify the
proxy address and port fields. Doing so sets the ProxyHost parameter.
Note For more information, see the Client for 32-bit Windows
Administrators Guide.

Recommended Server and Client Configurations


Many proxy servers are configured to permit Web proxy connections only to
standard ports, typically ports 443 and 80. Client proxy connections use
destination ports based on the type of connection indicated in the ICA connection
properties. For example, an ICA connection configured to use TCP/IP with a
proxy server attempts to proxy to port 1494 on the computer running
Presentation Server. On certain proxy servers, this connection may be rejected.
For improved security, Citrix recommends that you configure your farms server
to run the Citrix SSL Relay Service on port 443. However, this may not be
practical in many medium to large environments, and in such cases, Secure
Gateway is recommended. Configure the client to use SSL/TLS+HTTPS to
connect. Configuring the client to use SSL/TLS+HTTPS forces it to contact the
proxy server with a destination port of 443 on the computer running Presentation
Server. This configuration allows connections through the proxy server without
having to reconfigure the proxy server policy. If you do not use SSL, configure
your server to allow port 1494. With Presentation Server 3.0 or 4.0, you may
also need to configure port 2598 for the Common Gateway Protocol that is used
for the session reliability feature.
If your proxy server is configured to allow connections only to an authorized set
of IP addresses, modify the proxy server policy to include the FQDN or IP
addresses of your farms servers.

Using Smart Cards with Citrix Presentation Server


This section includes information about using smart cards with Presentation
Server. This section assumes that your smart card environment is correctly
configured. Before you attempt to use smart cards with Presentation Server,
ensure that you set up the following:

Active Directory domains and Certificate Authorities are configured for smart card
support

The user PINs and certificates are saved to the smart card

The vendors smart card software tool is installed on the server

The vendors smart card software tool is installed on the clients, if necessary See the
documentation from your smart card vendor for details. For more
information about using smart cards with Windows 2000 Server, see Microsoft
Knowledge Base articles 313557 and 227873. For more information about
configuring Active Directory domains and Certificate Authority for smart card
support, see Microsoft Knowledge Base articles 313274, 257480, and 231881.

Default readers and cards supported by Microsoft are listed in the registry under
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Calais.
The minimum configuration to use smart cards in a Presentation Server
environment requires:

The Cryptographic Service Provider (CSP) is installed on the server

The smart card reader driver is installed on the client. This allows Program
Neighborhood to function using smart cards. Program Neighborhood Agent and Web
Interface both require the CSP to be installed on the client as well.
Note The built-in Schlumberger driver requires a registry modification to
enable it on Windows Server 2003. Add the text SLBCSP.DLL SLBIOP.DLL;
to the end of the string in this value:
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\CtxHook\AppInit_DLLs\Smart
CardHook\SpecialDLLSearch

Important Windows XP, Windows 2000 Server, and Windows Server 2003
include native support for some smart card readers. To determine if the reader is
supported by default, attach the reader to the client and let the operating system
detect and install the drivers. If there is not an option to log on using a smart card
after you restart the system, you must install the vendors software drivers. Also
Windows XP, Windows 2000 Server, and Windows Server 2003 have default
CSPs installed for many Schlumberger and GemPlus smart cards.

Copying Smart Card User Certificates


When users log on to servers in the farm to run applications that require
certificates, the certificate needs to be copied to the users personal store.
Certificates are copied to the personal store when users log on if the following
registry key exists on the server:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\
CurrentVersion\Winlogon\Notify\ScCertProp
If the preceding registry key does not exist on the server, see Microsoft
Knowledge Base articles 313557, 265087, and 281245 for additional information
about copying certificates.
The following procedure explains how to determine if the certificate is available in
the users personal store.

To determine if the certificate is available in the users personal store


1. Start Internet Explorer.
2. Click Tools and choose Internet Options.
3. Click the Certificates button on the Content tab.
4. The users certificate is listed on the Personal tab of the Certificates dialog box.
Important The users certificate must be present in the personal store to use
smart cards with the Program Neighborhood Agent and Web Interface.
You can also copy the users certificate to the personal store by logging on
locally to the server with the users smart card. Run the smart card tool on the
server and register the users certificate. This procedure varies depending upon
the smart card vendor tool that is installed. See the online help installed with the
specific tool for details.

Using Smart Cards with the Web Interface and the


Program Neighborhood Agent
Using smart cards with Presentation Server, the clients, or the Web Interface
simplifies the authentication process while enhancing logon security.
This section assumes that the server running the Web Interface is running
Windows 2000 Server with Microsoft Internet Information Services (IIS). To use
smart cards with the Web Interface, configure the IIS Web server and enable
smart card authentication using the Configure authentication methods task in
the Access Suite Console. To test the configuration, log on to the Web Interface
server (http//:your Web Interface Server) from a client with a smart card and
launch a published application. For more information, see the Web Interface
Administrators Guide.
To use smart cards with the Program Neighborhood Agent, you must configure
IIS to support smart card authentication.
Configure IIS to have a Certificate Authority that can be set up in an Active
Directory domain. For more information, see Microsofts documentation about
IIS and Certificate Authorities.
Note Citrix recommends that you use Active Directory if you want to use
smart cards with Presentation Server.

Configuring IIS for Smart Card Support


To configure IIS to support smart card authentication, you must complete the
following tasks:
1. Enable the Windows Directory Mapper Service.
2. Install a server certificate.
3. Ensure that SSL is enabled on the server running the Web Interface.
To enable the Windows Directory Mapper ServiceWindows 2000 Server
1. Open the Computer Management utility by right-clicking My Computer and choosing
Manage.
2. Navigate to and expand Services and Applications.
3. Navigate to and expand Internet Information Services; right-click and choose
Properties.
4. Under the Internet Information Services tab, in the Master Properties box, click Edit.
5. Select Enable the Windows Directory Service Mapper on the Directory Security tab.
6. Click OK until you return to the Computer Management dialog box.
To enable the Windows Directory Mapper ServiceWindows Server 2003
1. Open the Computer Management utility by right-clicking My Computer and choosing
Manage.
2. Navigate to and expand Services and Applications.
3. Navigate to and expand Internet Information Services; right-click the Web Sites node and
choose Properties.
4. From the Directory Security tab, select Enable the Windows Directory Service
Mapper.
5. Click OK until you return to the Computer Management dialog box.
To install a server certificate
1. In the Computer Management utility under Internet Information Services, expand the tree
until Default Web Site is displayed.
2. Right-click Default Web Site and choose Properties.
3. Click Server Certificate on the Directory Security tab to begin the Web Server
Certificate wizard. Click Next.
4. Choose Create New Certificate and click Next.

5. Choose Send the request immediately to the certification authority and click
Next.
6. Enter a friendly name for the certificate and click Next.
Tip Use the servers FQDN for the friendly name.
7. Enter the corresponding organization and organizational unit and click Next.
8. For the Common Name, enter the FQDN of the server running the Web Interface and
click Next.
9. Enter State/Province and City/Locality and click Next.
10. If the Certificate Authority is not automatically filled in, select it from the list.
11. Click Next twice and then click Finish.
To ensure that SSL is enabled on the server running the Web Interface
1. In the Computer Management utility under Internet Information Services, expand the tree
until Default Web Site appears.
2. Right-click Default Web Site and select Properties.
3. Choose the Web Site tab and ensure that SSL Port 443 is available for SSL connections.
4. Close the Computer Management utility.

Using ActivCard Gold 2.1 with Citrix Presentation Server


ActivCard Gold 2.1 is not multiuser compatible until it is updated with ActivCard
Service Pack 1 and a hotfix.
1. Install ActivCard CSP.
2. Install ActivCard CSP Service Pack 1.
3. Rename accsp.dll, accsp.sig, asphat32.dll and aspcom.dll in the system32 folder.
4. Contact ActivCard to receive the following private files and copy them to the system32 folder

accsp.dll

accsp.sig

asphat32.dll

aspcom.dll

MFC42D.DLL

19
0

Advanced Concepts
Guide

MFCO42D.DLL

MSVCRTD.DLL

5. At a command prompt, type regsvr32 accsp.dll to register the accsp (Activecard


Card Service Provider) library.
6. Restart the computer.
ActivCard Gold 2.2 and later should be fully multiuser compatible. Contact your
smart card vendor for more information and to obtain the latest compatible CSP.

Miscellaneous Smart Card Information


Caution CSPs from Schlumberger and ActivCard do not function correctly if
they are both installed on the same server. However, each can be installed with
the GemPlus CSP.

You can use smart cards with single sign-on only on client devices running Windows
XP, Windows 2000 Server, and Windows Server 2003 because they are the only
client operating systems that support logging on locally with a smart card.

To test that a server is set up correctly for logging on with a smart card over an ICA
connection, log on locally to the server using the smart card. If you can log on locally,
you can log on over an ICA session.

The CSP to be installed on the server depends on the type of smart card that is used.
However, most readers work with different vendors smart cards.

On Windows XP operating systems, Schlumberger Cryptoflex 8K cards can be used


without installing additional drivers; however, Schlumberger Cryptoflex 16K cards
require additional drivers.

On occasion, the USB readers can stop working for various reasons. Removing and
replacing the USB connector restores the reader to working order. Check Microsofts
Knowledge Base articles 265087 and 293507 for additional information.

Using Citrix Products in a Wireless LAN


Environment
The findings in this section are the result of coordinated testing between Citrix
and Compaq. Citrix and Compaq teamed together to test security in a wireless
Local Area Network (wLAN) environment to determine and evaluate the inherent
security risks associated with these types of networks. There is little physical
security associated with wLANs, resulting in the possibility that the radio signals
could be intercepted with malicious intent. For example, todays hackers are
using tools and methods to obtain MAC addresses and channels used by internal
networks.

Wireless LAN Vulnerabilities


The Wireless Equivalent Privacy (WEP) relies on the RC4 encryption algorithm
that uses the same key to scramble and unscramble packets. If the key
management system cycles through the same set of keys in a predictable manner,
determined intruders can correlate data with the keys to decipher the encryption.
This intrusion technique can be successful with both 40-bit and 128-bit RC4
encryptions. Additionally, the network name and MAC addresses are broadcast in
clear-text and can be easily intercepted. An intruder can then program these
addresses on a personal wLAN adapter to access the network.
Additionally, the Wireless Application Protocol, which is used by wireless
devices to access text, has a known security hole that allows intruders to intercept
decrypted data from transmission points before the data is encrypted for
transmission. During a transmission, the following security protocols are used:

Wireless Transport Layer Security (WTLS) - over the wLAN

Secure Socket Layer (SSL) - over the wired LAN

There is a split-second of vulnerability at the gateway when the data is decrypted


and then re-encrypted to switch protocols. Organizations cannot rely on the use
of encryption keys and SSIDs to provide adequate security in a wLAN
environment. However, using Presentation Server with the ICA protocol offers a
number of features that protect against security vulnerabilities.

Citrix Architecture Security


The architecture in Citrix products provides the following security features:

ICA Protocol. This protocol inherently prevents intruders from finding data or code.
Applications reside on a server and ICA transmits keystrokes, mouse clicks, and screen
updates. Only a graphic representation of the user interface actually crosses the
network.

Data encryption. The ICA protocol offers built-in encryption on the client and server,
adding an extra layer of protection against attempted hacking.

Authentication. Presentation Server offers an additional layer of authentication


security for role-based application access.

Device loss protection. The ICA protocol allows critical data to be stored and
protected on a server rather than the client, ensuring that the loss of a client device
creates only a minimal security risk.

Optimizing Citrix Technology over Wireless WANS


Citrix published a white paper that provides information concerning deployment
of Citrix products within wireless Wide Area Networks (wWANs). It includes
information such as performance tuning techniques and advice. The white paper
Optimizing Citrix Technology for Operation over Wireless Wide Area Networks
is available as Citrix Knowledge Base Article CTX101602.

Deploying the Java Client Using the Web Interface


The Presentation Server Client for Java, available from the Presentation Server
Components CD, runs in applet mode only. The Client for Java is streamlined for
use in environments where access to applications through a Web browser is
required. You can configure the Web Interface to download a Client for Java
package automatically to the client device when users launch applications. If
deploying the client using the Web Interface, you can configure the client
deployment options using the Access Suite Console. For more information, see
the Web Interface Administrators Guide.
If you select SSL/TLS, the Client for Java package contains built-in certificates
for a number of Certificate Authorities. See the Presentation Server Client for
Java Administrators Guide for a full list of built-in certificates.
If the environment already has server certificates from one of these Certificate
Authorities, the Client for Java already includes details of the necessary root
certificate to allow it to verify the authenticity of the server. However, if the
certificate is not one of those included in the built-in list of certificates used by
the Client for Java (for example, if your organization has its own Certificate
Authority), you must configure the Web Interface to pass the correct root
certificate to the Client for Java package when users launch applications.

CHAPTER 9

Troubleshootin
g

This chapter includes information that can help you troubleshoot issues you
may encounter with Presentation Server and its components.

Troubleshooting the IMA Service


The IMA Service is a core component of Presentation Server and runs on all
servers in a server farm. The solutions presented in this section can help resolve
many IMA issues.

IMA Service Fails to Start


The following guidelines and recommendations can be useful when the
IMA Service fails to start:

Examine the following registry setting:


HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\IMA\
Runtime\CurrentlyLoadingPlugin

If the value is blank, the IMA Service could not connect to the data store or the
local host cache is missing or corrupted.

If a value exists, the IMA Service made a connection to the data store. The value
displayed is the name of the subsystem that failed to load. For additional
information about subsystem troubleshooting, see IMA Service Logging on
page 194.

If you are connecting directly to the data store, verify that ODBC connectivity exists.
For more information, see ODBC Connection Fails on page 195.

If you are connecting to the data store through an intermediary server, verify that the
IMA Service is running on the server that is connecting directly to the data store.

Review the entries in the event log for the IMA Service error code that is
returned.

19
4

Advanced Concepts
Guide

Verify that the Spooler service is started in the System context rather than for a user.

If you see an IMA Service Failed message (with error code 2147483649) when
restarting a server, the local system account may be missing a \temp directory. Change
the IMA Service startup account to the local administrator. If the IMA Service starts
under the local administrators account, check for a missing temp directory. Switch the
service back to the local system account and try manually creating the temp directory
%SystemRoot%\temp. Verify that both the TMP and TEMP environment variables
point to this directory. For more information, see Microsoft Knowledge Base article
251254.

The Service Control Manager has a time-out of six minutes, but the IMA Service can
take longer than six minutes to start when the load on the data store database exceeds
the capabilities of the database hardware or when the network is experiencing high
latency. If the Service Control Manager reports that the IMA Service could not be
started but the service eventually starts, ignore this message and change the default
time-out value.
To change the default time-out value for the service control manager

1. Open HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control and create a new


DWORD value, ServicesPipeTimeout (if it does not already exist).
2. Select the ServicesPipeTimeout DWORD value and click Edit > Modify.
3. In the dialog box that opens, click Decimal. The value of this field is entered in milliseconds so
a value of 600000, for example, is equivalent to 10 minutes. Enter a value that corresponds to
your needs and click OK.
This change does not take effect until the server is restarted.

IMA Service Fails to Stop


The Microsoft Systems Management Server Network Monitor client utility is not
supported on servers running Presentation Server. The IMA Service fails to stop
when running on a server that has this utility installed. Uninstall the Network
Monitor client when installing Presentation Server on your server.

IMA Service Logging


For advanced troubleshooting of the IMA Service, you can enable logging at the
server level. Use the following procedure to enable logging for either debug
output (viewed using a debug hook utility like DBGVIEW from SysInternals:
http:// www.sysinternals.com/) or a text file.

To enable server logging of IMA events


1. Modify the following registry values in
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\IMA\Tracer:

Name: Log to Debugger Type:


REG_DWORD
Data: 0x0 (disables debug output) or 0x1 (enables debug output)

Name: Log to File Type:


REG_DWORD
Data: 0x0 (disables file output) or 0x1 (enables file output)

Name: LogFileName Type: REG_SZ


Data: full path and file name of the output file

2. The HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\IMA\Tracer registry key contains a


subkey for each subsystem about which information can be traced. Tracing for all subsystems is
on by default, but the specific types of messages for the subsystems are off. To enable tracing
for a subsystem, both the default value (specified as the first value in the key) and the message
values must have a value of 1. The default value must be 1 and must not be changed. Other
values within each key correspond to types of messages to log and are set to 0 by default. To
enable tracing for those items, set their value to 1.

ODBC Connection Fails


If you are connecting directly to the data store, ODBC connectivity is required
for correct operation of the IMA Service. If your ODBC connection fails, try the
following:
1. Verify that the database server is online.
2. Verify that the name of the DSN file that the IMA Service is using is correct by looking in the
registry at: HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\IMA\DataSourceName
3. Connect to the database using the DSN file with an ODBC Test Utility (such as Oracle ODBC
Test, DB2 Client Configuration Assistant test, or SQL Server ODBC Test).
4. Verify that the correct user name and password are being used for database connectivity. You
can change the user name and password using the dsmaint config command. For more
information, see the MetaFrame Presentation Server Administrators Guide.

5. Reinstall MDAC 2.6 Service Pack 1 or later to verify that the correct ODBC files are
installed.
6. Enable ODBC Tracing for further troubleshooting. For more information, see ODBC
Tracing on page 216.

Server Fails to Connect to Data Store


This error can indicate a corrupt local host cache. Before completing the
following steps, verify ODBC connectivity to the database. For more
information, see ODBC Connection Fails on page 195.
1. Copy Ima.mdb to another directory for backup purposes.
2. From a command prompt, recreate the local host cache using the dsmaint recreatelhc
command.
3. Restart the server.

Permanent Storage Fails to Initialize during Installation


When this error occurs, it usually indicates that the IMA Service cannot
create objects in the data store. Before completing the following steps, verify
ODBC connectivity to the database; see ODBC Connection Fails on page
195.
1. Verify that the user account for the database has permissions to create tables, stored procedures,
and index objects. For Microsoft SQL Server, the permission is db_owner. For Oracle, the
permission is resource. For IBM DB2, the permission is database administrator authority.
2. Verify that the system tablespace is not full on an Oracle server..

Recovering from a Failed Installation


If an installation fails, compare the list of servers in the Presentation Server
Console to the list of servers returned by queryhr. Use the command queryhr -d
hostID to remove any servers listed in the queryhr results that are not listed in the
console, otherwise the data collector may continue to attempt to contact them.
Caution Do not use the d switch on farm servers that are functioning
correctly. This switch removes the server from the farm and the server must
then be reinstalled into the farm to regain functionality.

Restoring an Unresponsive Server


If a member server is no longer responding to IMA requests and the IMA Service
cannot be started, the server is considered to be unresponsive. You cannot use the
chfarm command with an unresponsive server because the command requires
connectivity to the data store.
Caution The original state of the server cannot be recovered after performing
the following procedure. Before using this procedure, first attempt all the other
solutions in Troubleshooting the IMA Service on page 193.
To rejoin an unresponsive server to the farm
1. Uninstall Presentation Server from the unresponsive server.
2. Remove the unresponsive server from the farm using the Presentation Server console on
another server in the farm.
3. Reinstall Presentation Server on the unresponsive server and rejoin the farm during
installation.

Troubleshooting Application Compatibility Issues


You can address most common application issues through procedures described
in the following sections. If you still experience application compatibility issues
after completing these procedures, refer to Advanced Troubleshooting
Procedures on page 199.

Multiple Users Cannot Access an Application


Use the following troubleshooting procedures if a user cannot open more than
one instance of an application, or two users attempting to launch a published
application experience unexpected application behavior; this occurs when an
application uses the same configuration files or keys, regardless of the user.
To determine if an application runs correctly on Presentation Server
1. Install the application on a server running Presentation Server 4.0.
2. Execute the application as a specific user, for example, UserA. Modify and save some
configuration settings for UserA.
3. Execute the application as another user, for example, UserB.

4. Determine if UserB has the same configuration as User A. Specifically, check if UserB has the
configuration changes you made in the second step for UserA. If UserB has the same
configuration, this indicates that some configuration information is being shared and the
application has incompatabilities with Terminal Services.
5. Run the application simultaneously from multiple user accounts. Observe if there are issues
with configuration or application stability. These also indicate Terminal Services
incompatibilities.
If any of the described symptoms are evident, it is safe to conclude that
multiple users cannot access the application and that the application is
incompatible with Terminal Services.
To determine if an application runs correctly in an isolation environment
1. Create an isolation environment.
2. Install an application in the isolation environment. Alternatively, if the application is already
installed on the system, associate the application with the isolation environment.
3. Execute the application as a specific user, for example, UserA. Modify and save some
configuration settings for UserA.
4. Execute the application as another user, for example, UserB.
5. Determine if UserB has the same configuration as User A.
6. Run the application simultaneously from multiple user accounts and check for issues with
configuration or application stability.
If you can access the application from multiple user accounts, the application is
successfully isolated.

Difficulty Running Multiple Applications


Some applications simply are incompatible when installed on a single server. This
could be because the applications share specific system files (DLL, INI, and so
on) that can result in conflicting versions of the system files being present. For
example, applications that use the Java Runtime Environment (JRE) can cause
conflicts of this type.
To determine if applications run correctly on Presentation Server
1. Install the first application on a server running Presentation Server 4.0.
2. Install the second application on the same server.
3. If installation is successful, run both applications.

4. To determine if the applications exhibit problems when accessed by multiple users, follow steps
outlined in Multiple Users Cannot Access an Application on page 197.
If you encounter installation or execution problems while performing the
preceding steps, these applications are candidates for isolation.
To determine if applications run correctly in an isolation environment
1. Create an isolation environment for each application that is a candidate for isolation.
2. Install each application in these separate isolation environments.
3. Run both applications from valid user accounts and verify that there are no conflicts.
4. Determine if the applications exhibit problems when accessed by multiple users; follow the
procedure outlined in Multiple Users Cannot Access an Application on page 197.
If the applications install and run correctly, they were successfully isolated.

Advanced Troubleshooting Procedures


If you considered the issues raised in the preceding sections and you are still
experiencing application compatibility issues, use the following troubleshooting
procedures:

Applications Changing Services


Applications that install new services do not work correctly in an isolation
environment.
To determine if an application installs a service
1. Open the Windows Event Viewer and review the Applications section for CtxSbxAppMsg
messages related to Services.
2. If the application installs or deletes a service, do not isolate the application. If the application
does not install or delete a service, check for named objects.

Named Objects Issues


Named objects are used for inter-process communications. These named
objects can be isolated, but compatibility issues can occur when some named
objects are shared between isolated and non-isolated processes.

20
0

Advanced Concepts
Guide

To determine if named objects are causing problems


1. In the Presentation Server Console, select the isolation environment into which you installed
the application and from the Actions menu select Properties.
2. In the Properties dialog box, select Rules.
3. In the Rules pane, to create a new rule click Add.
4. Create an Ignore All rule to switch off Named Objects isolation.
5. Test the isolated application with the new rule.
6. If the application works correctly, view a log of the system object code; specifically, log
GUID dab267b2-296f-4042-9271-549f4d920855 MF_Hook_CtxSbx with an access mask of
0x2000 and a level of 3. This provides you with a list of object names that were modified
by application isolation. You can then further narrow down this list to determine which object is
causing the problem.
7. You can also run Process Explorer to identify objects used by the isolation environment
process.
8. Now that you have a list of Named Objects, add specific Ignore rules for the isolation
environment.
Important Pipes and section objects are often used for communications
between applications inside the isolation environment and systems
services outside the isolation environment.
If ignoring named objects does not resolve the application issues, proceed to the
next section.

File
Issues

System

Most of the file system is isolated by default. You may need to add additional
rules that allow an isolated application to access files updated by non-isolated
processes, however, especially if isolated applications exhibit any of the following
issues:

Isolated applications may have stale data; for example, applications have shared
template files.

Isolated applications crash or hang.

Isolated applications report errors. Typically these are DLL not found errors.

To diagnose file system related problems


1. To help diagnose faulty file system behavior, install the File Monitor tool (shareware utility
available from http://www.sysinternals.com/). File Monitor monitors and displays file system
activity on a system.
2. Capture a File Monitor trace of the applications execution when it is run within an isolation
environment, as well as when it is run directly on the system.
3. Compare the two traces to help identify deviations in file system activity by the isolated
application process. Important points to note are:

An isolation environment always fails FAST_IO_QUERY_OPEN requests for isolated


applications.

File Monitor path strings for isolation environment issued requests sometimes have
non-printable character labels prefixed to them. These labels are used internally by
isolation environments.

4. Identify any files or folders to be ignored using rules. Enforce Ignore rules for applications
associated with an isolation environment; when the problem is identified, narrow the rule set.
For example, if an isolated application requires a version of a system DLL other than the
version available in the isolation environment, create an Ignore rule that specifically ignores
the version of the DLL inside the isolation environment.
5. Identify issues related to environment variables such as %PATH% and
%WINDIR%.
6. To view settings for these variables as visible to an isolated application, launch a command
prompt within an isolation environment by typing the following command:
AIERUN Isolation_Environment_Name cmd.exe
If the value of the PATH variable is incorrect, create a batch file that
correctly sets this variable and then launches the isolated application.
Publish the batch file instead of the isolated application executable.
7. Identify issues related to the file system by viewing the file system as visible to an isolated
application. Launch a file explorer associated with the isolation environment as follows:
AIERUN Isolation_Environment_Name c:\program files\Internet
Explorer\Iexplore -e
If a required directory is not visible because it was previously deleted in the
isolation environment, run Windows Explorer outside the isolation
environment and clear the User Profile Root to remove the appropriate
deleted record.

8. Determine if a version of an isolated application has written configuration information to


the %USERPROFILE% directory. This could affect the functioning of other isolated
versions of that application. If this occured, remove this Ignore rule and determine if it
corrects the problem. Subsequently, narrow down the solution with more specific Isolate
rules while restoring the original Ignore rule. For example, if you are running multiple
versions of Microsoft Outlook, create an Isolate rule for
%USERPROFILE%\Application Data\Microsoft.
Important Clear the contents of the User Profile Root and the Installation Root
and reinstall or rerun the application every time you modify a rule. This removes
stale data in these locations.
If the compatibility issue you are experiencing is not related to the file system,
check the registry.

Checking the Registry


Applications store configuration information in the system registry. Most of the
registry is isolated by default; however, you may need to add additional rules that
enable an isolated application to access configuration data updated by nonisolated processes, especially if isolated applications exhibit any of the following
issues:

Isolated applications may have stale data; for example, ICA printers are not found

Isolated applications experience a fatal error

Isolated applications report errors

To diagnose registry related problems


1. To help diagnose registry configuration errors, install the Registry Monitor tool (shareware
utility available from http://www.sysinternals.com/). Registry Monitor is a registry monitoring
utility that identifies applications accessing your registry, which keys they are accessing, and the
registry data that they are reading and writing.
2. Capture a Registry Monitor trace of the application execution when it is run within an isolation
environment, as well as when the application is run directly on the operating system.
3. To see if registry keys that were accessed by the isolated application were also accessed by
non-isolated services or helper applications, check the Registry Monitor log.

Chapter 9 Troubleshooting

20
3

If these non-isolated components write to keys that were isolated during


installation or execution, you may get stale data in the isolation environment,
requiring you to add Ignore rules. These rules enable the isolated
application to access data written by non-isolated applications or services
successfully.
An example of such behavior is the HKEY_CURRENT_USER\Printers key,
that is updated with information about client printers. If this key is not
ignored, isolated applications are unable to get updated information about
which printers are available for a given session.
4. Install or run the application again to verify that the Ignore rule works as expected.
5. Identify registry keys that require Isolate rules. Check the Registry Monitor log to see if
registry keys that are ignored are shared among users of an application or among multiple
applications. Compatibility problems can occur if you have ignore rules that are too wide in
scope.
For example, if you have an ignore rule for the registry key,
HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows
NT\CurrentVersion, every key under this key is ignored. Microsoft Outlook
user information is stored under this key in
HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows
NT\CurrentVersion\Windows Messaging Subsystem.
To resolve any issues arising with this profile information, you can add an
isolate per user rule for
HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows
NT\CurrentVersion\Windows Messaging Subsystem.
Important Clear the contents of the User Profile Root and the Installation Root
and reinstall/rerun the application every time you modify a rule. This removes
stale data in these locations.

Troubleshooting Novell Directory Services Integration


This section lists troubleshooting tips and known issues that can occur when
using Presentation Server in a Novell Directory Services environment.

Troubleshooting Tips and Known Issues for ZENworks


If the ZENworks Dynamic Local User (DLU) policies are not being applied
on some servers, check the Novell Workstation Manager component of the
Novell Client, as described in the following procedure.
1. Right-click the My Network Places icon on the servers desktop and choose
Properties.
2. In the Network and Dial-up Connections window, right-click Local Area Connection
and choose Properties.
3. Choose Novell Workstation Manager from the components list and click
Properties.
4. Verify the following settings:

Workstation Manager is enabled

The tree name is set to the tree that has the DLU policies applied

All other options have the default settings applied

5. If you set the DLU policy in Novell Directory Services to delete users after they log off
(Volatile User option) and the volatile user accounts are not being deleted, ensure that the
Enable Volatile User Caching option is disabled.
If you are experiencing autologon problems with the ZENworks DLU feature as
the Windows authentication method, try the following:
1. Make a desktop connection using an ICA Custom Connection with the Autologon
feature enabled.
2. Specify User Credentials:

User name. A valid Distinguished Name such as .SampleUser.company

Password. A valid password

Domain. A domain that contains the Novell Directory Services tree name

3. Launch the connection.

Known Issue. ZENworks for Desktops Version 3 does not distinguish between
users with the same user name, even if they are in different contexts. If the first
user is still logged on when the second user logs on, the profile of the first user is
utilized by the second user.
Workaround. Be sure to use unique names in the tree. If your tree already
includes users with the same user name, you can work around this by creating
aliases.

Other Troubleshooting Tips and Known Issues

Logging on to a server can fail if you uninstall the Novell Client from the server after
Presentation Server is installed. If this occurs, do not restart the computer running
Presentation Server until you complete the following instructions:
After uninstalling the Novell Client, you must reapply the correct settings to
the registry. The following registry key contains the GINA values:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows
NT\CurrentVersion\Winlogon
The registry values for the default logon screen (without the Novell Client)
are: GinaDLL Data: Ctxgina.dll
CtxGinaDLL Data: Msgina.dll

If you cannot log on to or assign rights to published applications using Novell


Directory Services credentials, try the following troubleshooting tips to correct the
problem:

Verify that Novell Directory Services is enabled for the farm. To do this, rightclick the farm name in the console and choose Properties. From the
MetaFrame Settings tab, verify that the Novell Directory Services Preferred
Tree is set correctly.

Verify that you are using a valid user name, password, context, and tree name
during logon by logging on from another computer using the same information.

Verify that the Novell Client is configured correctly by browsing the tree and
logging on from the console of the server.

If the Novell Client displays an error message about an invalid user name, server,
or tree, log on to the console as the same user. If you do not log on successfully,
the Novell Client is not configured correctly.

If the client prompts you to reenter your credentials or displays an error message,
click Cancel to return to the Novell logon dialog box. On the NT/ 2000 tab, view
the user information:

If the User name field in the NT/2000 field contains a Distinguished Name
(.username.context.), upgrade to Novell Client 4.81 or later. (Older Novell
Clients do not parse the user name from the Distinguished Name.)

If the Domain name field is blank or set to the local machine name and
ZENworks DLU feature is being used, troubleshoot the Dynamic Local User
policies (DLU is not functioning correctly).

If the Domain name field is blank or is set to the local machine name and
ZENworks DLU feature is not being used, locate or create the following
registry key: SyncedDomainName in
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\ NDS. Set the registry
key value to the name of the Windows NT domain that is synchronized
with the Novell Directory Services tree.

If the Domain name field contains the name of the Novell Directory
Services tree, enable Novell Directory Services integration.

If the Domain name field contains the name of a Windows NT domain and
you are not using ZENworks DLU functionality for Windows authentication,
verify that the server has a valid trust relationship between the servers
domain and the users domain.

Known Issue. If you designate a Novell Directory Services preferred tree but
none of the servers are set to MetaFrame XP Feature Release 1 or later,
Presentation Server prompts your users for Novell Directory Services credentials
but does not accept them.
Workaround. Set the feature release level to Feature Release 1 or later on
at least one server in the farm, remove the Novell Directory Services tree
name in the NDS Preferred Tree field Farm Properties > MetaFrame
Settings, and then reset the feature release level to None.

Known Issue. The session sharing feature is not supported for Presentation Server
Client connections that are configured for Novell Directory Services user
credentials.
Workaround. To use session sharing for custom ICA connections
in Program Neighborhood, do not specify user credentials on the
Login Information tab in the Properties dialog box.

Known Issue. If you are connecting by dial-up ICA to a server that has the Novell
Client installed, the server returns the Microsoft logon dialog box instead of the
Novell logon dialog box. This occurs because the Use Default NT Authentication
check box is selected by default on computers running Windows 2000 Server.
Workaround. If you want to use Novell authentication on a server under
these circumstances, clear the Use Default NT Authentication check
box. To do this, from the Start menu choose Programs > Citrix >
Administration Tools > Citrix Connection Configuration Tool. If a
computer running Windows 2000 Server without Service Pack 2 is set up
to use the default Windows NT authentication and a third-party
authentication software such as the Novell Client is installed, the thirdparty logon dialog box appears instead of the default Windows logon
dialog box. To resolve this problem, install Service Pack 2 for Windows
2000 Server.

SQL Database Replication Troubleshooting Tips


The following general tips may be useful when replicating a data store contained
in a SQL Server database. For more information about the replication process,
see Replicating Data Stores Running Microsoft SQL Server on page 251.

Replication fails if any servers involved in the replication are using cloned or ghosted
images. Both the operating system and the SQL Server installations must be fresh.

Verify that the MSSQLServer, SQLServerAgent, and Microsoft Distributed


Transaction Coordinator (MSDTC) services are started under a domain user account
rather then the LocalSystem account.

Use SQL Query Analyzer to issue a Begin Distributed Trans statement to verify that
MSDTC is working correctly. If this fails, MSDTC is not configured correctly.

You may need to set up SQL Server for Mixed-mode authentication (Windows and
SQL Server), which requires a restart of the SQL Server service.

When troubleshooting, try reconfiguring authentication to use the SA SQL


Authentication account instead of Impersonation to determine if the problem is with the
trusted connections.

When troubleshooting a replication, use the following steps:

First, clean up the old subscriptions

If that fails, drop and recreate the subscription

If that fails, drop and recreate the publication and the subscription

As a last resort, disable replication, drop the distributed database, and then
reconfigure replication

Resource Manager Troubleshooting Q&A


The following section answers some common troubleshooting questions related
to Resource Manager.

Resource Manager Summary Database Data Source Name


Q: Is the Resource Manager summary database Data Source Name (DSN)
case sensitive?
A: The RMSummaRyDataBASE DSN is not case sensitive.

Resource Manager Node Still Shows in Presentation Server Console after Uninstalling
Resource Manager
Q: Resource Manager was installed on two servers in my farm. After
uninstalling Resource Manager from one of the servers, why does the
Resource Manager icon remain in the Presentation Server Console even
though the uninstallation completed without errors?
A: When at least one member server in a farm has Resource Manager
installed, the Resource Manager node appears in the Presentation Server
Console when viewed on any server in the farm.
Note The Resource Manager node can be removed from a Presentation
Server Console by removing or renaming the ResourceManager.jar file found
in
\Program Files\Citrix\Administration\Plugins\ and restarting the Presentation
Server Console.

Alerts Regarding High Context Switches/Second


Q: I installed Resource Manager with the default metrics configured on a
server and I receive alerts about high context switches. The server seems to be
functioning correctly and none of my users are complaining. Is this alert
serious?
A: The default metric threshold values are a baseline configuration for an
administrator to tune and they are determined for a minimal server
configuration. Although most metric defaults are suitable as a one size fits
all solution like Processor - %Processor Time defaults, some metrics like
System Context Switches / Sec must be tuned for the environment in which
they operate.

Zone Elections Counter


Q: What does the Zone Elections counter monitor in Resource Manager?
A: The Citrix MetaFrame Zone Elections counter monitors the number of
data collector elections that occurred in the servers zone since the IMA
Service started.
Monitoring this metric can be useful to determine whether or not excessive
data collector elections are taking place. Proactive monitoring can help
prevent excessive amounts of data from transmitting between zones as
elections are won. This can also be tracked with the Citrix MetaFrame Zone
Elections Won metric.

Error Message: [Oracle][ODBC][Ora]ORA-02074: cannot ROLLBACK in a distributed


transaction
Q: I am using Oracle and continually get messages about ROLLBACK of
distributed transactions. What does this mean?
A: Ensure that Disable MTS (Microsoft Transaction Server) support in
the Oracle ODBC driver workarounds configuration is set.
If the workaround is not enabled (by default on most Oracle ODBC
configurations) this leads to a unique key violation that terminates the SQL
transaction and the following Resource Manager server log entry: [Oracle]
[ODBC][Ora]ORA-02074: cannot ROLLBACK in a distributed transaction.

Error Message: Must Reparse Cursor to Change Bind Variable Datatype


Q: After restarting the Resource Manager database connection server, I
received an Oracle ODBC error in the Resource Manager server log stating
14 June 2003 11:32:26 - System - [Oracle][ODBC][Ora]ORA-01475: must
reparse cursor to change bind variable datatype. What does this mean?
A: If this message appears in the Resource Manager server log, setting the
Oracle ODBC workaround for Enable Closing Cursors can help resolve this
issue.

21
0

Advanced Concepts
Guide

Error Message: Failed to create summary database


Q: What needs to be done when I attempt to create the summary database
and the procedure fails with this message appearing in the Resource Manager
server log?
A: This summary database message informs the user that there was an error
deploying the schema for the summary databasefor example, server log
entry: 11 July 2002 12:26:02 - System - Failed to create summary database.
The most common causes of this error are:
There was a database problem while initially creating the summary database
schema. For example, an Oracle database configuration such as the rollback
segment is too small and non-autoextending; this can prevent successful
deployment of the Resource Manager schema.
Solution: Check the Oracle or SQL Server configuration settings to ensure
there is enough space in the database to create the schema. Several megabytes
should be enough space to create the schema. Also, check that all rollback
segments are autoextending; these can be tuned after the database is
created.
The database user has insufficient privileges to create the schema. For
example, Resource Manager may not be able to insert data into tables or
create packages.
Solution: Ensure that the user has rights to the database and can successfully
communicate with the database server.

Multiple Duplicate Import Request Messages


Q: The Resource Manager server log is showing multiple duplicate import
request messages. Is the data importing correctly?
A: This message appears in the Resource Manager server log when there are
multiple duplicate import requests. A message like the following is usually
observed multiple times in the server log file:
22 November 2004 00:02:10 - System - Ignoring duplicate import request
for file "C:\Program Files\Citrix Resource
Manager\SummaryFiles\1C2865FABC926CA" from host "XXXXXXX".
This is usually because the Update Now button was activated multiple
successive times or there are spurious network conditions that cause the server
to request an import more than once. In these conditions, this message is
normal and summary file imports complete unaffected.

Trusts and User Group Access Issues


This section outlines tasks that you can perform to overcome issues or improve
system performance when managing Presentation Server for Windows.

Forest Trusts
With Windows Active Directory forests, you can create a two-way forest trust
that allows a transitive trust among all child domains in the trusted forests.
However, Presentation Server does not support the use of this type of trust
among child domains. If you require a trust between two child domains in
separate forests, you must create an explicit trust between the domains.
Alternatively, you can place all servers in the same domain as follows:
1. Create a Local Group in the domain.
2. Populate this Domain Local Group with Global Groups from other domains.

User Access to Terminal Servers


By default on Windows Server 2003, members of the Administrators and
Remote Desktop Users groups can connect using Windows Terminal Services.
The Remote Desktop Users group contains no users when it is initially created;
you must manually add any users or groups who require Windows Terminal
Services access. If the users are not already members of the computers local
group, you must also add them. Unlike Windows 2000 Server policies, the Allow
log on locally policy (a Computer local policy under User rights) no longer
provides access to Terminal Service connections. For additional information, see
the Windows Server 2003 online documentation.

Other Troubleshooting Recommendations


This section discusses frequently encountered issues and recommendations or
workarounds that may help you troubleshoot and solve them.

Program Neighborhood Agent Cannot Connect through


the Secure Gateway
If a user receives the message Cannot connect to the MetaFrame server:
Protocol driver error when connecting to the Secure Gateway from the Program
Neighborhood Agent, the most likely cause is that the client device does not have
128-bit encryption installed.

Folders Do Not Appear in Program Neighborhood


Folders that you create to organize applications in the Presentation Server
Console are not related to application folders that appear in Program
Neighborhood.
To specify application folders for Program Neighborhood, use the Program
Neighborhood Settings tab in the Properties dialog box for the published
application.
To set an applications Program Neighborhood folder
1. Right-click the published application in the console and choose Properties.
2. On the Program Neighborhood Settings tab, type the folder name in the
Program Neighborhood Folder box.

Cannot Launch Secure Applications through Internet


Explorer
If you have users connecting through a secure Web Interface page (HTTPS) and
they receive an error message of ICA file not found, ensure the security
settings within Internet Explorer are not set to Do not save encrypted pages to
disk.
To check security settings in Internet Explorer
1. Open Internet Explorer.
2. Click Tools > Internet Options.
3. Click the Advanced tab.
4. Scroll down to Security.
5. Be sure Do not save encrypted pages to disk is cleared.
6. Click OK.

Reducing Printing Messages in the Event Viewer


To limit the growth of the event log and to ease troubleshooting, you can limit or
disable print messages from displaying in the event viewer.
To configure a printers logging options
1. Go to Start > Settings > Printers and select the printer you are configuring.
2. Go to File > Server Properties and open the Print Server Properties dialog box. Logging
options can be enabled or disabled under the Advanced tab in this dialog box.

Importing Network Printers from Other Domains


Printers cannot be imported from a network print server when:

The print server resides in a workgroup

The printer is in a different domain from any servers in the server farm

To enable the printer to be imported


1. Do one of the following:

Add the network print server to the same domain as the computers running Presentation
Server

Add one of the servers to the same domain as the network print server

2. Assign the printers to the Everyone group instead of to groups or users.


Authenticate without credentials to receive the list of printers assigned to
everyone.
3. To allow Novell users to access Microsoft print servers, you must enable the Guest account
and assign Everyone or Guest access.

USB Redirection Does Not Work

Presentation Server supports USB printers installed on the server

Presentation Server Clients support installed USB printers when the client platform is Windows
98, Windows XP, Windows 2000 Server, or Windows Me

Content Redirection Options Are Disabled When


Publishing an Application
If you install and then publish applications after installing Presentation Server,
you must update the file type associations in each servers registry.
To update file type associations in a server farm
1. Open the Presentation Server Console.
2. Expand the Servers node in the left window pane.
3. Right-click a server and select Update File Types from Registry.
4. When the file type updates are complete, check the properties of the published application. The
content redirection options are now enabled.

Disconnected Sessions
Presentation Server allows you to log Transport Driver Errors to a log file. This
allows you to track any kind of Winsock errors the client receives. This is useful
in troubleshooting why sessions are disconnected. To enable the logging, the
following parameters must be added when launching the ICA connection with
wfcrun32. The command is:
Wfcrun32 /c:0x00000040 /e:0x00100000 /logfile:<log file path>
<connection name>

where 0x00000040 enables logging of the Transport Driver. The value 0x00100000
tells the server to log any Auto Client Reconnect related information.
If an error is encountered, it is included in the logfile together with an error code.
The error code may be a Winsock error code. Check the Microsoft Developers
Network (MSDN) site for information about these codes.

MaxThreads and Session Reliability


When Session Reliability is enabled for client connections, the number of
connections is limited to 150 users on a server that may be powerful enough to
accept more. This is because of the ThreadsPerChild value of 150 in the
httpd.conf configuration file located in the %Program Files%\Citrix\XTE\conf
folder. The value is persistent but can be changed by editing the registry. In
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\XTEConfig add a DWord
Value called MaxThreads. Modify the value of MaxThreads to a decimal value
equal to or greater than the number of users you expect the machine to support.
After the value is set, stop and restart the IMA Service or restart the machine so
that your changes take effect.

Collecting Information for Citrix Technical Support


This section discusses methods for collecting information that Citrix Technical
Support can use for debugging purposes and for assisting you with your
troubleshooting efforts.

Obtaining System Information


When troubleshooting an issue, Citrix Technical Support may request
information about the state of your system. The easiest way to obtain such
information is to execute winmsd, which launches the System Information tool
on Windows 2000 Server. From the Microsoft Management Consoles Action
menu, select Save as System Information File. If necessary, you can then send
the file to Citrix Technical Support.

Obtaining Installation/Uninstallation Logs


If your Presentation Server installation fails to complete, Citrix Technical
Support requires an installation log file to troubleshoot the problem. From
MetaFrame XP Feature Release 2 onward, the installation is a Windows Installer
package (.msi file), and you must invoke the Windows Installer with the /l
command line option to create an installation log file. Citrix recommends that if
your Presentation Server installation does fail, you attempt a second installation
using the following command line to create a log file:
Msiexec /i CD\MF\mps.msi /l*v %SystemDrive%\msi.log
Replace CD with the CD drive letter (for example, D:) containing the
Presentation Server CD. If the Presentation Server CD was copied to a hard drive
or network share, you can also replace CD with the full path to the CD image.
This command creates a log file named Msi.log in the root of the system drive.
Further information about the Windows Installer is available at the Microsoft
Web site.

Capturing Citrix Presentation Server Console Debug


Output
To capture debug output from the Presentation Server console, launch the
console with the debugFile command line option. Citrix recommends that you
create a shortcut using the following procedure:
1. Right-click on the desktop and choose New > Shortcut from the context menu.
2. The Create Shortcut wizard starts. In the Type the location of the item field type:
%SystemRoot%\system32\java.exe. When prompted to Type a name for this shortcut:,
type a description such as Console Debugging.
3. Right-click the new shortcut and choose Properties from the context menu.
4. On the Shortcut tab, type the following text in the Target field (because of page width
constraints, the text is wrapped below but must be entered as one line):
java.exe -Djava.ext.dirs="ext;%ProgramFiles%\Java\ jre1.4.1\lib\ext" jar Tool.jar -debugFile:output.log
5. Change the Start in field to %ProgramFiles%\Citrix\Administration.
6. Click Change Icon and type:
%ProgramFiles%\Citrix\Administration\ctxload.exe

7. On the Layout tab, set the Screen buffer size to 9999 lines.
8. Click OK to save the shortcut.
When the shortcut is launched, two windows are displayed. The first window is
a command window containing the debug messages output by Java.exe. The
second window is the console user interface. If the console hangs or otherwise
fails, press CTRL + BREAK in the command window to view the stack trace.

ODBC Tracing
ODBC tracing information might be requested by Citrix Technical Support or
the database vendor support team. The procedure to enable ODBC tracing
depends on the database server software you are using. The following
procedures detail how to activate ODBC tracing for Microsoft SQL Server,
Oracle, and IBM DB2.
Microsoft SQL Server
1. Launch the ODBC Data Source Administrator.
2. Click the Tracing tab.
3. Type a path for the log file in the Log File Path box.
4. Click Start Tracing Now to begin tracing. Click Stop Tracing Now to end tracing.
Oracle
1. Launch the Net8 Assistant.
2. Click Configuration > Local > Profile.
3. Choose General from the drop-down box on the right-pane.
4. Use the Tracing and Logging tabs to configure ODBC tracing as needed.
IBM DB2
1. Launch the DB2 Client Configuration Assistant.
2. Click Client Settings > Diagnostics.
3. Set the Diagnostic error capture level to 4 (all errors, warnings, and information
messages).

Installation Manager Debug Files


Obtain the following Installation Manager files before contacting Citrix Technical
Support for Installation Manager troubleshooting questions:

wfs (the package script)

ael (the recorder log file)

aep (the packager project file)

log (the windows installer log file)

CHAPTER 10

Using Citrix Presentation


Server with Novell Directory
Services

Presentation Server supports Novell Directory Services authentication to servers,


published applications, and published content. This chapter explains how to use
Presentation Server, the Web Interface, and the Presentation Server Clients
(Version
6.20 and later) in a Novell Directory Services environment.
This chapter assumes that you are familiar with Novell Directory Services and
related Novell products. See the Novell Web site at http://www.novell.com for
more information about the Novell products referred to in this document.

Farm Layout and System Requirements


Using Presentation Server in a network environment that employs multiple
directory services requires careful planning. While the server farm can contain
servers that are in Windows NT or Windows 2000 Server domains and servers
enabled for Novell Directory Services, computers running the Novell Client and
that use Dynamic Local User functionality should be members of a workgroup,
not members of a domain. Use the Dynamic Local User feature of Novell
ZENworks for Desktops in this configuration.
To implement Presentation Server in a Novell Directory Services environment,
designate application servers to host applications and content published only for
Novell Directory Services users. These servers must run Version 4.81 or later of
the Novell Client for Windows NT/Windows 2000 Server and Presentation
Server. The following figure illustrates the required layout of a server farm in a
Novell Directory Services environment.

22
0

Advanced Concepts
Guide

The following software must be installed for Presentation Server to successfully


access Novell Directory Services:
On the Novell server (a server supporting Novell Directory Services
authentication and responding to Novell Directory Services queries from clients):
Novell Directory Services eDirectory 8.5 for Windows or for Novell NetWare
5 with Support Pack 6 or later, or for Novell NetWare 5.1 with Support Pack
2 or later, or NetWare 6 and later.
On Presentation
Servers:

Server

for

Windows

Novell Client for Windows NT/Windows 2000 Server, Version 4.81 or later

Computers running Presentation Server 3.0 or 4.0


-orComputers running MetaFrame XP Feature Release 2 or 3
Important If using ZENworks Dynamic Local User function to gain access
to Windows, you must install Novell ZENworks for Desktops 3 or later.
If you are not using ZENworks to gain access to Windows, you must have
accounts with the same user name and password in both Novell Directory Services
and Windows NT or Active Directory domains.
To synchronize domains, perform either of the following:

Manually synchronize accounts

Use third-party software such as Novells Account Management 2.1 or DirXML that can
automatically synchronize accounts between Novell Directory Services and Windows NT
domains
Important IP (Internet Protocol) is the only supported protocol for
interaction between Presentation Server, Novell Directory Services, and
ZENworks for Desktops.

Setting Up Citrix Presentation Server for Use in Novell


Directory Services
To enable the use of Presentation Server in a Novell Directory Services
environment, complete the following tasks.
1. Decide which servers are to host applications and content published for Novell Directory
Services users when Presentation Server is installed.
2. Install the Novell Client for Windows NT/Windows 2000 Server, Version 4.81 or later on
those servers (see Installing the Novell Client on page 222 for more information.)
3. Install Presentation Server and activate the required Presentation Server licenses.
4. Enable the Dynamic Local User policy in ZENworks for Desktops or ensure that the same
user accounts and passwords exist in both Novell Directory Services and Windows NT or
Active Directory domains.
5. You can also enable the SyncedDomainName key on each computer running Presentation
Server with Novell Directory Services Integration. This does not require the ZENworks DLU
Component.
A. Open the Registry Editor on the Presentation Server.
B. Go to HKEY_LOCAL_MACHINE\SOFTWARE\Citrix and add a new key called Novell
Directory Services.
C. On the new key, add a new SZ subkey called SyncedDomainName.
D. Set the value to the NetBIOS name of the domain with which you want to synchronize the
user names. There is no need to restart the server or IMA Service. Users synchronize the
NetWare user accounts with those of the Active Directory domain. Both users still must
exist on the NetWare tree and the Active Directory domain.

6. Enable Novell Directory Services usage for the farm.


A. Assign Presentation Server administrator privileges to Novell Directory Services objects.
B. Log on to the Presentation Server Console with Novell Directory Services credentials.
C. Publish applications, desktops, or content for Novell Directory Services users on
computers running Presentation Server to which only Novell Directory Services users
connect.
7. If you are using the Web Interface, enable Novell Directory Services usage in the Web
Interface.
8. Instruct users how to connect to published applications and content using their Novell
Directory Services credentials. If you are deploying the Program Neighborhood Agent, enable
Novell Directory Services usage in the Program Neighborhood Agent.

Installing the Novell Client


Citrix recommends installing the Novell Client and related service packs on a
server before installing Presentation Server.

Installation on a Server without Citrix Presentation Server


Complete the following tasks prior to installing Presentation Server.
1. Install and configure the Novell Client for Windows NT/Windows 2000 Server, Version 4.81 or
later.
Note If you choose to use ZENWorks DLU, it may be necessary to perform
a custom installation of the Novell Client and add the Workstation Manager
component; some clients do not install this component when performing a
Typical installation.
2. Restart the server.
3. Verify that you can log on to Novell Directory Services.
If you cannot log on to Novell Directory Services, you may need to add a
Directory Agent location to the Novell Client. A Directory Agent is needed
when the Novell server is located on a different subnet. If an agent does not
exist, ensure that the Novell server and the server running Presentation
Server are part of the same subnet.

4. To optimize logon and browsing response times, change the order of the network
providers using the following steps:
A. Right-click the My Network Places icon on the servers desktop.
B. Choose Properties from the short-cut menu. The Network and Dial-up Connections
dialog box appears.
C. Choose Advanced Settings on the Advanced menu. The Advanced Settings dialog
box appears.
D. On the Provider Order tab, adjust the order of the network providers so that Microsoft
Windows Network is above NetWare Services.
E. Click OK to close the Advanced Settings dialog box.
5. To optimize logon time, add the Windows fonts directory located in
%SystemRoot% to the system path environment variable.
6. To suppress a Presentation Server setup program error message informing you that the
FileSysChange parameter is invalid, complete the following steps:
A. Open the System.ini file located in %SystemRoot%.
B. In the [386Enh] section of System.ini, set the following value:
FileSysChange=off
C. Save and close the System.ini.
The appearance of this error message causes unattended setup of Presentation
Server to fail. Ensure that the FileSysChange parameter is set to off before
running an unattended installation.
7. Install Presentation Server.
If Presentation Server fails to install, complete the following steps:
1. Uninstall the Novell Client from the server.
2. Install Presentation Server and then install the Novell Client by following the instructions in
Installation on a Server with Citrix Presentation Server on page 224.
If the system is working correctly, you can skip to Using ZENworks to Simplify
User Credentials on page 226.

Installation on a Server with Citrix Presentation Server


If Presentation Server is already installed on the server before you install the
Novell Client, you must change the Windows registry on the server before and
after you install the Novell Client. If the Novell Client being installed is Version
4.9 or later, the following steps are not required.
Note If the server has the IPX protocol installed along with the Novell Client,
installation may fail and display a wowexec error message. To work around this
issue, disable the NWLink protocol on all adapters in the server. After
Presentation Server is installed, enable NWLink again.
If Presentation Server is already installed on the server, complete the
following tasks.
1. Run regedit.
2. Edit the following registry key:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows
NT\CurrentVersion\Winlogon
3. Double-click the GinaDLL entry located in the right-hand pane. In the String Editor dialog
box that appears, replace the value Ctxgina.dll with the value Msgina.dll.
4. Install and configure the Novell Client for Windows NT/Windows 2000 Server, Version 4.81 or
later.
5. Do not restart when prompted by the Novell Client Setup.
6. Edit the registry entry for GinaDLL as in Step 2. In the Edit String dialog box that appears,
replace the value Nwgina.dll with the value Ctxgina.dll. Click OK.
7. With the key path for Winlogon still selected, choose New > String Value from the Edit
menu.
8. Name the value CTXGINADLL and assign it a data type of REG_SZ.
9. Enter Nwgina.dll in the String Editor dialog box to assign this value to the new
CTXGINADLL entry.
On Presentation Server, Ctxgina.dll is loaded by Winlogon.exe to process the
auto-logon information transmitted by clients. Ctxgina.dll can process autologon credentials in excess of 20 characters. For example, if Ctxgina.dll is not
loaded, auto-logon user names greater than 20 characters are truncated to 20
characters by Termsrv.exe. When Ctxgina.dll acquires users auto-logon
credentials, they are passed in their entirety to the installed Gina.dll file to
complete the authentication process. In most cases, the installed GINA is
Msgina.dll. When the Novell Client is installed, the GINA is Nwgina.dll.

Note The preceding steps are required to ensure that CTXGINA is installed on
the server. CTXGINA is required for logging on automatically with user
names that exceed 20 characters.
10. To optimize logon and browsing response times, change the order of the network
providers using the following steps:
A. Right-click My Network Places on the servers desktop.
B. Choose Properties from the shortcut menu that appears. The Network and Dial-up
Connections dialog box appears.
C. Choose Advanced Settings on the Advanced menu. The Advanced Settings dialog
box appears.
D. On the Provider Order tab, adjust the order of the network providers so that Microsoft
Windows Network is above NetWare Services.
E. Click OK to close the Advanced Settings dialog box.
11. To optimize logon time, add the Windows fonts directory located in
%SystemRoot% to the system path environment variable.
The system is now ready for you to set up the Windows account authentication
to be used to access Windows 2000 Server systems.

Windows Account Authentication


When a Novell Client is running on a computer running Windows NT or
Windows 2000 Server, users are required to have two accounts: one for
authentication to Novell Directory Services and one to gain access to Windows.
You can use two different methods to allow users access to Windows:

Use Novells Dynamic Local User functionality, available in Novells ZENworks for
Desktop product (this is the only supported method if you are running MetaFrame XP
Feature Release 1).

Create user accounts with the same user name and password in both Novell Directory Services
and Windows NT or Active Directory domains for each user. Synchronizing the user accounts
in this way allows you to integrate Presentation Server and Novell Directory Services without
using Novells ZENworks.
If you want to use Presentation Server in a Novell Directory Services environment
using ZENworks, see Using ZENworks to Simplify User Credentials on page
226
If you want to use Presentation Server in a Novell Directory Services environment
without using ZENworks, see Configuration without ZENworks on page 228.

Using ZENworks to Simplify User Credentials


When the Novell Client is running on Windows NT or Windows 2000 Server,
users are normally required to enter separate sets of credentials to log on to
Windows and Novell Directory Services. Enabling the Dynamic Local User
policy in ZENworks for Desktops eliminates this need.
The following section explains how to configure the Container Package and User
Package in ZENworks for Desktops to eliminate the need for users to specify two
sets of credentials when connecting to Presentation Server. Configure the
Container Package to specify the users (by container) to whom you want to apply
the Dynamic Local User policy. Configure the User Package to specify how the
Dynamic Local User policy is applied to those users.
Note These settings are configured on the Novell server through ConsoleOne.

Configuring the Container Package


The ZENworks for Desktops Container Package searches for policies located
within the tree and then applies them to the users associated with a particular
container. Use the following example to create a Container Package that
searches only the local container for policies applied to users within that
container. This sample configuration is useful for small companies.
Complete the following tasks for containers that hold user objects requiring the
Dynamic Local User policy.
1. Select a container that holds user objects.
2. On the New Object menu, choose Policy Package > Container Package.
3. Choose Define Additional Properties and click Finish.
4. On the Policies tab, enable the Search policy.
5. In the Search policies up to field, choose Object Container to search only the container in
which the search policy resides.
The other choices are:
Root (default). Searches the local container and any container in the direct
path to the root of the tree. This is not recommended for medium to large
trees.
Partition. Searches the local container and any container up to the root of the
partition. This method works well for large environments, but you must
specify the partition boundaries.
Selected Container. Searches the container between the current container and
the root of the tree that you select.
6. Leave the search level at the default setting of 0.

7. Click Apply, then Close.


8. On the Associations tab, choose Add and browse to the container that holds the container
package you just created.
9. Click OK and then Close.

Configuring the User Package


The User Package in ZENworks for Desktops enables Dynamic Local User
functionality for users who are associated with that particular package. Use the
following example to create a User Package that enables the Dynamic Local
User functionality.
Important If the Search Policy Package, the User Policy Package, and the user
are not located in the same container, the policy is not applied to the user.
1. Choose the Organizational Unit that holds the Container Policy from above.
2. On the New Object menu, choose Policy Package > User Package.
3. Near the end of the wizard, choose Define Additional Properties and then click Finish.
4. Choose WinNT-2000 on the Policies tab.
5. Choose Enable Dynamic Local User and then choose Properties.
6. Choose Dynamic Local User at the top of the page.
7. Choose Manage Existing NT Account (if any). This changes the password and other items
to match for a seamless integration.
Note Novell recommends that you create a separate Dynamic Local User
policy for users who have the user name Administrator if the local
administrator account was not renamed.
8. Choose Use NetWare Credential. This creates a local Microsoft user who has the same user
name and password as the Novell Directory Services user. If this is not enabled, the Dynamic
Local User feature creates a random user name and password, resulting in the loss of
Presentation Server functionality.
Do not enable Volatile User unless you have very large profiles and want to
conserve disk space.
9. On the Not Member of tab, choose User > Add. Select the users or groups to whom you want
to apply the policy. Applying the policy to users gives them rights to log on and run
applications.

10. Click Apply and then OK two times to finish creating the policy.
11. If the computer running Presentation Server is also running Windows Server 2003, ensure
that you add a Custom Group to the policy. The Custom Group name should be Remote
Desktop Users.

Configuration without ZENworks


In an environment with a Novell Client running on Windows NT or Windows
2000 Server, users are required to enter separate sets of credentials to log on to
Windows and Novell Directory Services. Using synchronized accounts between
Novell Directory Services and Windows NT or Active Directory domains
eliminates this need.
To enable Presentation Server to work in a Novell Directory Services
environment without using ZENworks, set the following registry key on all the
servers that have the Novell Client installed but are not using ZENworks for
Desktops Dynamic Local User functionality. Set the value to the Windows NT or
Active Directory downlevel domain name containing the user accounts that match
the accounts in Novell Directory Services.
1. Run regedit.
2. Edit the following registry key:
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix
3. With the key path for Citrix still selected, choose New Key on the Edit menu.
4. Rename the newly created key to NDS.
5. Highlight the new key and choose New String Value on the Edit menu.
6. Enter SyncedDomainName in the String Value dialog box.
7. Enter the name of the Windows domain that has the same user accounts as Novell Directory
Services in the String Editor dialog box to assign this value to the new SyncedDomainName
entry.
Note When you set this registry key, Ctxgina.dll replaces the Novell
Directory Services tree name that is passed from the client to the server with
the string that is entered in SyncedDomainName. Ctxgina.dll then passes the
credentials to Nwgina.dll, allowing the user name and password to be
authenticated to Novell Directory Services. The domain is then specified in
SyncedDomainName.

Using Citrix Presentation Server in the Novell Directory


Services Environment
By default, Presentation Server supports only Microsoft Windows users. Use the
following steps to specify the preferred Novell Directory Services tree for the
farm. Presentation Server supports only one Novell Directory Services tree in
each farm.
1. Log on to the console and connect to a server configured for Novell Directory Services
support.
2. Right-click the farm node in the left pane of the console and choose
Properties.
3. Click the MetaFrame Settings tab in the Properties dialog box.
4. Specify the tree name in the NDS Preferred Tree field and then click OK. To disable Novell
Directory Services support for the farm, delete the entry in the NDS Preferred Tree field and
then click OK.

Assigning Citrix Presentation Server Administrator


Privileges to Novell Directory Services Objects
Use the following steps to assign administrator privileges to objects such as
country, organization, organization unit, group, user, or alias in a Novell
Directory Services tree.
1. Log on to the Presentation Server Console.
2. Right-click the Administrators node in the left-hand pane and choose Add MetaFrame
Administrator from the menu that appears.
3. In the Add MetaFrame Administrator dialog box, open the Novell Directory Services tree.
Objects in the Novell Directory Services tree represent container and leaf objects.
4. When prompted to log on to the tree, enter the distinguished name and password of a Novell
Directory Services user.
5. Select the Show Users option to display user and alias objects in this hierarchy.
6. Double-click to open container objects. Select the objects to be granted administrator
privileges. Add at least one Novell Directory Services user account that has read and
write privileges.
Note While it is possible to grant an administrator access to a context, users
within the context or in contexts that are children of the granted context are
also administrators. This is not recommended because of the difficulty of
managing permissions granted to contexts.

23
0

Advanced Concepts
Guide

7. Click Add. Select the level of permission and tasks you want to assign to the administrator.
8. Click Finish.

Logging On to the Citrix Presentation Server Console


Using Novell Directory Services Credentials
Use the following steps to use Novell Directory Services credentials to log on to
the console to manage a server farm.
1. Launch the Presentation Server Console.
2. Enter a distinguished name in the User Name field. A fully distinguished name starts with a
period and has a period between each object name up to the root of the tree.
For example, user JoeX, within two container objects (the Admin
organization unit within the PNQ organization) would enter
.JoeX.Admin.PNQ in the User Name field.
3. Enter a password in the Password field.
4. Enter the Novell Directory Services tree name in the Domain field.
5. Click OK.
Note Enabling pass-through authentication to the console is not supported
with Novell Directory Services users.

Publishing Applications for Novell Directory Services


Users
Use the following steps to publish applications on servers configured for
Novell Directory Services support. Only Novell Directory Services users can
connect to the applications you publish on these servers.
1. Log on to the console using Novell Directory Services credentials.
2. From the Actions menu, choose New > Published Application.
3. Follow the instructions in the Published Application wizard. Click Help to obtain detailed
help for each step.

4. On the Specify What to Publish dialog box, enter the UNC (universal naming convention)
path to the application you want to publish in the Command Line field.
For example, the Novell Directory Services tree MYNDSTREE contains
organization object MYORG, which contains NetWare volume NW50_SYS.
The executable path on NW50_SYS is \APPS\OFFICE\WINWORD.EXE.
The full UNC path to Winword.exe is
\\MYNDSTREE\MYORG\NW50_SYS\APPS\OFFICE
\WINWORD.EXE.
You can leave the Working Directory field blank.
5. Because the Application Publishing wizard cannot access the applications icon, default icons
appear in the Program Neighborhood Settings dialog box. To use the applications icon, you
can copy the icon file (ending with an .ico extension) or the entire executable to a computer
running Presentation Server that is not running the Novell Client. Click the Change Icon
button to browse for the icon or executable on this other server.
6. In the Specify Servers dialog box, be sure to select only those servers running the Novell
Client Version 4.81 or later.
7. In the Specify Users dialog box, select the Novell Directory Services tree from the list. This
enumerates the objects in the tree. Double-click container objects to open them. Choose the
Show Users option to view users and alias objects in the current container. Select the desired
object and click Add.
You can also manually enter Novell Directory Services user names. Choose
Add List of Names and enter one or more Novell Directory Services account
names separated by a semicolon (;). Each account name must be entered in
the fully distinguished name format prefixed by a Novell Directory Services
tree name and a slash (\).
For example, enter
CitrixNDSTree\.joeX.admin.pnq;CitrixNDSTree\.mary.test.pnq.
Click Check Names to validate the account names or click OK if you are
done adding accounts.
Double-click to open container or leaf objects until the object to be granted
access appears. Select the object and click Add.

Configuring Printer Autocreation in Novell Directory


Services
Use the console to choose Windows NT or Windows 2000 Server Active
Directory print queues and assign them to Novell Directory Services objects for
autocreation. Permissions to the print queue must be granted to the Dynamic
Local User created when the Novell Directory Services user logs on to a server.
This may require enabling the guest account on the print server. See the
Microsoft online Knowledge Base article 271901 for information about enabling
the guest account.
Presentation Server does not support autocreating Novell Directory Services
printers. See Novells documentation for autocreating Novell Directory Services
printers (NDPS and non-NDPS) in ZENworks for Desktops.

Enabling Novell Directory Services Usage in the Web Interface


Complete the following tasks to configure the Web Interface to work in a Novell
Directory Services environment.
1. Open the WebInterface.conf (or NFuse.conf) file located in
%SystemRoot%\Inetpub\wwwroot\Citrix\MetaFrame\conf(or
%SystemRoot%\Program Files\Citrix\NFuse\conf) on the server running the
Web Interface.
2. Edit the following parameters: Set the
LoginType to NDS.
Set the NDSTreeName to the name of the preferred Novell Directory Services
tree for the server farm.
3. If the optional parameter SearchContextList is not set, the Web Interface Contextless
authentication feature searches the entire tree to locate a user. This may take a long time in a
tree that has a lot of objects. Use SearchContextList to reduce the time required for
contextless authentication. Set this parameter to a comma-delimited list of contexts from the
Novell Directory Services tree. The Web Interface Contextless authentication feature searches
only these contexts to locate the user instead of the entire tree.
Note The Novell Client must be running on the server running the
Web Interface to allow authentication.
4. Restart the IIS Admin Service for the changes to take effect.

On the Web Interface logon page, Novell Directory Services user credentials can
be entered as follows:
1. User Name. You can specify either:
The full Novell Directory Services distinguished name of the user
(.joe.department.company or .CN=joe.OU=department.O=company)
-orThe full Novell Directory Services distinguished name of the alias for a user
(.joeAlias.department.company or
.CN=joeAlias.OU=department.O=company)
-orA partial name ("joe") and select [Find Context] from the Context field to
find all contexts where a user/alias with this name exists
2. Password. The Novell Directory Services users password.
3. TreeName. Shows the name of the Novell Directory Services tree supported by the farm.
Presentation Server supports only one Novell Directory Services tree per farm. This field cannot
be edited.
4. Context. You can select from this list by either:
A context used in a previous Web Interface/NFuse logon.
-orFind Context tab.
Selecting this and clicking the Log In button causes Web Interface/NFuse to
search the Novell Directory Services tree for all contexts that contain the
partial user/alias name. This search feature requires the Novell client to be
installed on the Web Interface/NFuse Web server, and be able to access the
Novell Directory Services tree. Because, searching the entire Novell
Directory Services tree may be slow, you can specify the Novell Directory
Services contexts that Web Interface/NFuse should search by specifying them
in the SearchContextList setting in the nfuse.conf file. For example:
SearchContextList=subdepartment.department.company
Do not prefix context names with a dot (.). Separate multiple contexts by
a comma (,).
Note Web Interface does not support pass-through authentication for
Novell Directory Services users.

Novell Directory Services Usage with the Citrix Presentation


Server Client
When users launch the Presentation Server Client, they can log on and be
authenticated using their Novell Directory Services credentials. Supported Novell
Directory Services credentials are user name (or distinguished name), password,
directory tree, and context.
Novell Directory Services support is integrated into the following:

Program Neighborhood and the Program Neighborhood Agent


If Novell Directory Services is enabled in the farm, Novell Directory
Services users enter their credentials on a Novell Directory Services tab on
the client logon screen. If users have the Novell Client (Version 4.81 or later)
installed, they can browse the Novell Directory Services tree to choose their
context.

Pass-Through Authentication
If users have the Novell Client (Version 4.81 or later) installed, their
credentials are passed to the server, eliminating the need for multiple system
and application authentications.
Note To enable pass-through authentication when using Novells
ZENworks for Desktops dynamic local user functionality, set the Use
NetWare Credentials value in the ZWFD DLU policy package to On.

Session Sharing
Session sharing works correctly with Novell Directory Services users only if
the application permissions are assigned at a user or container level. Session
sharing does not work if assigned at the group level.
The session sharing feature is not currently supported for custom ICA
connections that are configured with Novell Directory Services user
credentials (under Properties > Login Information). To use the session
sharing feature for custom connections, do not specify user credentials for a
connection on the connections Login Information tab.

Custom ICA Connections


When users run the Add New ICA Connection wizard, they must enter a
distinguished name in the User Name field, a password in the Password
field, and place the Novell Directory Services tree name in the Domain field.
Users running earlier versions of clients can also enter credentials in this
manner.

Single Sign-On
When the Novell Client is installed on the client device and Single Sign-On
is enabled, Single Sign-On sends users Novell Directory Services
credentials to the server. If you want users to use Windows credentials, add
the following to the Appsrv.ini or .ica file.

Appsrv.ini file - Under the [WFCLIENT] section, add or modify the


SSOnCredentialType entry to SSOnCredentialType=NT

ICA file - Under the application name section, add or modify the
SSOnCredentialType entry to SSOnCredentialType=NT

Configuring Default Contexts for Users


Configuring default contexts for users eliminates the need for users to know
their context when they log on. The following list contains ways to configure
default contexts on client devices:

Enable pass-through authentication for the client


If the client device is running the Novell Client, enable the Presentation
Server Client to use pass-through authentication. When pass-through
authentication is enabled on the client, the user name context and password
are passed from the Novell Client to the computer running Presentation
Server.

Edit the Windows registry on the client device


Create a script using regini or regedit that modifies the registry entry
HKEY_CURRENT_USER\SOFTWARE\Citrix\CtxLogon with the correct
context for the user. Edit the value RecentContexts to specify context(s).
Each context must appear on a new line.

Add a default context to Windows Installer Setup for Program Neighborhood or the Program
Neighborhood Agent.
At a command prompt, type:
msiexec /I MSI_Package /qn+ Default_NDSCONTEXT= Context
where MSI_Package is the name of the Windows Installer package and
Context is the default Novell Directory Services context you want to display
in the client. If you are including more than one context, separate the
contexts by a comma.

Add a default context to the self-extracting executable for Program Neighborhood.


Extract the client files from Ica32a.exe by typing at a command line:
ica32.exe -a -unpack:<Directory Location>
where <Directory Location> is the directory to which you want to extract the
client files.
1. Open the Appsrv.src file in a text editor.
2. Locate the section named [WFClient].
3. Add the following line to the list of parameters and values in the section:
DEFAULT_NDSCONTEXT=<Context1 [,]>. Include this parameter if you
want to set a default context for Novell Directory Services. If you are
including more than one context, place the entire value in quotation marks
and separate the contexts by a comma.
Examples of correct parameters:
DEFAULT_NDSCONTEXT=Context1
DEFAULT_NDSCONTEXT=Context1,Context2
Note The self-extracting executable setup program for the Program
Neighborhood Agent does not support adding a default context.

Tips and Techniques


Creating Aliases
If you must create aliases in Novell Directory Services, use the following
guidelines:

Ensure that the distinguished name of the object does not exceed 48 characters.

Alias object names are unique within the tree. The Alias object can be the same name as the
actual object.
Note You can use third-party tools, such as the Lyncx tool from Centralis, to
automate the process of creating aliases for large trees. See the Centralis Web site
at http:// www.centralis.co.uk for more information.
When users log on, they are given the rights of the object to which the alias
object points.

Organizing Published Applications for Novell Directory


Services Users
It may be helpful to set up groups in Novell Directory Services and associate
published applications with them.
For example, you can create a Novell Directory Services group called
Default_User_Apps for business and office applications. Add this group when
specifying which users have access to those published applications. When you
add new users to this group, they are granted rights to the applications.
Create a separate group for specialty applications that are not distributed to a
wide audience. For example, create a group in Novell Directory Services called
Accounting_Program and then publish an application called
Accounting_Program in Presentation Server. Specify the Novell Directory
Services group Accounting_Program to the published application called
Accounting_Program. When assigning new users to the accounting application,
simply add them to the group called Accounting_Program in Novell Directory
Services.

Debugging Novell Directory Services Issues


To capture tracing for debugging problems related to Novell Directory Services
support in Presentation Server, you must enable tracing for IMA_AAMS,
WinDrvSS, and NDSDrvSS components.

CHAPTER 11

Printer
Management

Presentation Server provides centralized printer management with the Presentation


Server Console.This chapter discusses printer compatibility, session printing
policy, and registry settings.

Enforcing Printer Compatibility


The printer compatibility feature allows you to prevent certain printer drivers
from being used. When users log on, auto-created client printers are checked
against a list of prohibited printers, enabling you to disallow print drivers that
cause issues on the servers in the farm.
Use the Presentation Server Console to configure printer drivers. To configure
drivers, log on to the console, expand the Printer Management plug-in, click
Drivers, and then click the Compatibility icon on the tool bar. Alternatively,
right- click the Drivers option, and then select Compatibility. In the Driver
Compatibility window, you can select one of two options: Allow only drivers in
the list or Allow all drivers except those in the list.
When users log on, client printers are automatically mapped and verified that
they can be created by comparing the printers against the list of allowed print
drivers. If a prohibited client printer is encountered, an event is generated in the
event log.

24
0

Advanced Concepts
Guide

Session Printers Policy Rules


Presentation Server 4.0 incorporates printer connections into the policy engine
and introduces new policy rules for session printers, that replace previous
methods of managing network printer settings. The session printers policy rules
help administrators to create customized printing workspaces based on policy
filter criteria and provides the ability to define a default printer without logon
scripts. This feature represents an extension of the auto-created network printer
feature. By using the policy engine, administrators can customize a client printer
workspace based on criteria such as client name, client IP address, server, user,
group, or access control.
These options extend the flexibility of policies to help you customize printer
workspaces for specific sites, groups, users, servers, and clients. These policy
options also add the capability to explicitly set the default printer for a user
without the use of logon scripts and preserve the printer properties overrides
available with auto-created network printer support.
The session printers policy helps administrators to designate the following:

Which network printers to connect within a session

A users default printer

The ability to override default values of common printer settings for network printers
Important This new policy rule cannot be used to manage the network printer
settings of previous versions of Presentation Server, so Citrix recommends
maintaining a farm containing mixed versions of Presentation Server only for
minimal periods of transition. If you have a farm with multiple versions of
Presentation Server, use the previous version of the Presentation Server Console
to manage network printer settings for previous versions of Presentation Server in
your farm.

Creating and Applying Policies for Session Printing


Three aspects are involved in the creation and application of a policy:
configuration, resolution, and enforcement.

Configuration
The session printers rule is not configured by default. To configure the rule, open
an existing policy object in the Presentation Server Console and then enable the
session printers rule for that policy. If the rule is enabled, you can modify its
settings. After the rule is configured, you can update the policys filter and
priority.

Resolution
Resolution of the session printers policy rule occurs when a user creates a new
session and Presentation Server determines which settings in a policy to apply.
Typically, for every rule the policy engine examines each policy in order of
priority. For the majority of the policy rules, if the state of the highest priority
policy is enabled, the settings from this policy are used. The policy engine
ignores any other rule defined in any of the other lower priority policies. In
contrast to this behavior, the session printers rule has the capability to merge with
lower priority policies. This allows more flexible printer workspace
configurations based on different filtering criteria. Presentation Server reflects the
resultant policy into the system registry, including the list of configured printers
and the default printer.

Enforcement
Printer connections are enforced during the logon process. The server receives
the printer connection settings from the registry and interacts with the IMA
printer subsystem to create the printers specified by the policy and possibly
override their settings.

Important Considerations
When introducing the new session printers policy into your environment,
consider the following:

The session printers policy rule merges its properties with lower priority policies. This
behavior is new, introduced in the policy engine for Presentation Server 4.0.

Beginning with Presentation Server 4.0, printer auto-creation functionality in the Printer node is
removed from the Presentation Server Console. The session printers policy is now the only
mechanism for adjusting printer settings on a network printer. Given that the session printers
policy is available only as part of Presentation Server 4.0, you cannot administer previous
versions of printer auto-creation settings with the new version of the Presentation Server
Console. Instead, use a previous version of the Presentation Server Console to access the autocreated objects.

Session printers rules do not affect the functionality of older servers. The IMA Service
continues to hold auto-connect network printer objects and can still create, delete, and manage
them separately from session printers. The Presentation Server Console location for
administering this functionality was removed. To administer auto-connect printer objects prior
to Presentation Server 4.0, use the matching version of the Presentation Server Console.

Troubleshooting
The following scenarios may arise when using the new session printers policy
rules. At the end of each scenarios description a possible resolution is provided.
Scenario. An administrator created a session printers policy and assigned it to
users of the Education Department. The administrator defined two network
printers, Printer1 and Printer2. Then the department gets a new printer named
Printer3. The administrator adds Printer3 to the policy, which is assigned to users
of the Education Department.
When the users of the Education department log on to the server through an ICA
session, they see only Printer1 and Printer2; Printer3 is not being auto-created.
Resolution. Install the driver for Printer3 on the server. If the driver for the
network printer is not available, the printer is not auto-created.
Scenario. An administrator has a policy defined to auto-create printers using
universal printer driver only, but the session network printers defined through a
session printers policy are not auto-created using the universal printer driver.
Resolution. Session network printers are never auto-created using the universal
printer driver, they are always auto-created using the native drivers. None of other
printer policies affect the session printers policy.
Scenario. An administrator has two session printers policies, Policy1 and
Policy2, and these are assigned to users of the Education Department and users
of the Support Department, respectively. Policy1 has Printer1 and Printer2
defined and Printer2 is further defined as the default printer. Policy2 has
Printer3 and Printer4 defined and Printer4 is defined as the default printer. Two
users, User21 and User23, are members of both departments, but are currently
working in the Education Department. When User21 and User23 connect to the
server through an ICA session, Printer1, Printer2, Printer3, and Printer4 are all
auto-created but Printer4 is set as the default printer. However, because User21
and User23 are currently working for the Education department, they want their
default printer to be Printer2.
Resolution. Policy2 is set to a higher priority than Policy1. Set Policy1 to a higher
priority than Policy2.

Printing Registry Settings


Presentation Server 4.0 provides registry settings that can be used to change
the behavior of printing. These settings are used to track the various printingrelated settings on a per-session basis.
During logon, the actual session settings for printing are derived from a
combination of policies, base Terminal Services defaults, and an optional
"DefaultPrnFlags" value in the servers registry. In the absence of a configured
policy or modifications to base Terminal Services defaults, default values for all
bit flags listed are initially zero. Setting a bit to 1 enables one of the documented
functions. Enabling the bit flag is often used to disable or turn off default
behavior.
To modify the system default values
1. Navigate to HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\Print
2. Add a REG_DWORD value named DefaultPrnFlags to the registry key.
For some settings, default values (before policy application) are actually taken
from settings managed by the Terminal Services base functionality instead of the
DefaultPrnFlags value. All settings with an initial default provided by Terminal
Services are highlighted. These defaults apply unless you set
CTXPRN_OVERRIDE_TS_DEFAULTS bit in the DefaultPrnFLags value.
Note Configured and enabled Presentation Server policy rules always
override default settings whether they are read from the registry or provided by
Terminal Services. However, policies do not exist for many of these settings
because they may not be of general interest or are intended only as a fail safe to
disable certain features for troubleshooting.

CTXPRN_OVERRIDE_TS_DEFAULTS (0x00000080)
Windows manages several printing-related session settings that it derives from
group policies, user settings, or the connection type defaults. Unless overridden,
these settings are used as intended defaults. Settings that give precedence to a
default provided by Terminal Services are highlighted. To override Terminal
Services defaults for any of the identified settings, this flag must be set in the
DefaultPrnFlags registry value read from
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\Print in the system registry.
If this flag is not set, the normal Terminal Services defaults apply.

Client Printer Autocreation Flags


CTXPRN_CLNTPRN_AUTOCREATE_NONE (0x00000004)
CTXPRN_CLNTPRN_AUTOCREATE_LOCAL_ONLY (0x00000002)
CTXPRN_CLNTPRN_AUTOCREATE_DEFAULT_ONLY (0x00000001)
Description. By default, all discovered client printers are auto-created. However,
if any of these flags are set, only a subset of discovered client printers is autocreated. If CTXPRN_CLNTPRN_AUTOCREATE_NONE is set, none of the
discovered client printers are auto-created. If AUTOCREATE_NONE is not set
and CTXPRN_CLNTPRN_AUTOCREATE_LOCAL_ONLY is set, only printers
that appear to be local to the client are auto-created. If AUOTCREATE_NONE
& AUTOCREATE_LOCAL_ONLY are not set but
CTXPRN_CLNTPRN_AUTOCREATE_DEFAULT_ONLY is set, only the
default client printer is auto-created.
Default Value. Unless overridden, Terminal Services defaults for these settings
are used. If the CTXPRN_OVERRIDE_TS_DEFAULTS flag is set in the
DefaultPrnFlags value at
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\Print\, the Terminal Services
defaults are ignored and default bit values are taken from this REG_DWORD
value.
Overriding Presentation Server policy rule. Printing > Client Printers > Autocreation.

CTXPRN_DISABLE_DIRECT_CONNECT_FOR_CLNTPRNS (0x00200000)
Description. When auto-creating a client printer that is actually a connection to a
shared network printer, using the logon credentials of the server session, the
system first establishs a direct connection from the server session to the network
print server. Failing this, the printer is still connected as a client printer. If this
flag is set, establishing a direct printer connection from the server to the print
server is avoided, thereby forcing all client printers to be connected indirectly
through the client.
Default Value. Zero, unless bit value is set in the REG_DWORD registry value
DefaultPrnFlags at HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\Print\.
Overriding Presentation Server policy rule. Printing > Client Printers >
Print job routing

CTXPRN_DONT_SET_DEFAULT_CLIENT_PRINTER (0x00000800)
Description. By default, the system sets the session users default printer to the
clients default printer. If this flag is set, the clients default printer is not set as
the session users default.
Default Value. Unless overridden, the Terminal Services default for this setting
is used. If the CTXPRN_OVERRIDE_TS_DEFAULTS flag is set in the
DefaultPrnFlags value at
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\Print\, the Terminal Services
default is ignored and default bit value is taken from this REG_DWORD value.
Overriding Presentation Server policy rule. Printing > Session printers.

CTXPRN_CREATE_LEGACY_CLIENT_PRINTERS (0x00000010)
Description. By default, the system uses printer names and ports that are
qualified by the session ID so that they are unique to a particular session. If set,
this flag causes printer and port names derived only from the client name to be
used. Although less secure, this setting is useful for applications that expect this
type of printer names to be used.
Default Value. Zero, unless bit value is set in the REG_DWORD registry value
DefaultPrnFlags at HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\Print\.
Overriding Presentation Server policy rule. Printing > Client Printers >
Legacy client printers.

Printer Driver Flags


CTXPRN_DRIVERS_AVOID_REGULAR_DRIVERS (0x00000100)
CTXPRN_DRIVERS_NO_UPD_FALLBACK (0x00000200)
CTXPRN_DRIVERS_ENABLE_UPD

(0x00000400)

Description. By default, the system uses standard printer drivers as requested


by the client, if they are available. If a driver is not available and the client
supports a universal printer driver, the printer is auto-created using the universal
driver as an alternative. The default behavior is modified by setting either of the
following combinations:

Use universal driver only:


CTXPRN_DRIVERS_AVOID_REGULAR_DRIVERS and
CTXPRN_DRIVERS_ENABLE_UPD

Use model-specific drivers only:


CTXPRN_DRIVERS_NO_UPD_FALLBACK set, others 0

Default Values. All zero, unless one or more of the bit values are set in the
REG_DWORD registry value DefaultPrnFlags at
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\Print\.
Overriding Presentation Server policy rule. Printing > Drivers > Universal
driver.

CTXPRN_DRIVERS_DISABLE_AUTO_INSTALL (0x00100000)
Description. By default, both the network printer and client printer auto-creation
processes install needed drivers from the native set of printer drivers that ships
with Windows (for example, Driver.cab/ntprint.inf). If set, this flag disables all
such automatic driver installations, implying that all drivers must be preinstalled
or replicated to all required servers
Default Value. Zero, unless bit value is set in the REG_DWORD registry value
DefaultPrnFlags at HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\Print\.
Overriding Presentation Server policy rule. Printing > Drivers > Native printer
driver auto-install.

CTXPRN_NO_UPD_FALLBACK_FOR_DISALLOWED_DRIVER (0x10000000)
Description. When a driver name presented from the client fails the compatibility
test (for example, driver name is present in an exclude list or not present in an
allow-only list) assuming universal printer driver fallback is enabled, the normal
behavior is to try to create the printer using the universal printer driver. If set, this
flag changes the default and prevents universal printer driver creation for printers
whose drivers fail the compatibility test.
Default Value. Zero, unless bit value is set in the REG_DWORD registry value
DefaultPrnFlags at HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\Print\.
Overriding Presentation Server policy rule: None.

Client Printer Properties Retention Flags


CTXPRN_DISABLE_CLNTPRN_PROPS_EXCHANGE_WITH_CLIENT
(0x00001000)
CTXPRN_DISABLE_CLNTPRN_PROPS_PROFILE_SAVE_RESTORE
(0x00002000)
Description. By default, the system saves modified printer properties by sending
them back to the client (if supported). Failing that, the system saves them in the
user profile on the server. Setting either flag has the effect of disabling the printer
properties save and restore to either (or both) the client exchange or the user
profile.

Default Value. Zero, unless bit value is set in the REG_DWORD registry value
DefaultPrnFlags at HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\Print\.
Overriding Presentation Server policy rule. Printing > Drivers > Printer
properties retention.

Client Printer Port Management Flags


CTXPRN_CREATE_BOTH_STD_AND_LEGACY_CLNTPRN_PORTS
(0x01000000)
CTXPRN_CREATE_PORTS_FOR_AUTOCREATED_CLNTPRNS_ONLY
(0x02000000)
CTXPRN_DONT_DELETE_CLNTPRN_PORTS

(0x04000000)

Description. By default, during logon or reconnect, the system creates ports for
all discovered client printers and deletes them at logoff. The style of port created
depends upon the CTXPRN_CREATE_LEGACY_CLIENT_PRINTERS flag. If
any of these flags are set, the default port creation and deletion is modified as
follows:

Instead of creating either legacy style or standard port names, both types of ports are
created: CTXPRN_CREATE_BOTH_STD_AND_LEGACY_CLNTPRN_PORTS

Creates ports only as needed for auto-created printers rather than for every discovered client
printer: CTXPRN_CREATE_PORTS_FOR_AUTOCREATED_CLNTPRNS_ONLY

Does not delete ports at logoff. This works around a Windows 2000 Server spooler issue (see
Microsoft Knowledgebase article 893691) that can trap the spooler service. However, enabling
this setting can lead to substantial port and handle accumulations in the spooler service that
eventually require the service to be restarted:
CTXPRN_DONT_DELETE_CLNTPRN_PORTS
Default Value. All zero, unless one or more of the bit values is set in the
REG_DWORD registry value DefaultPrnFlags at
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\Print\.

Overriding Presentation Server policy rule.


None.

Network Printer Connection Flags


CTXPRN_DISABLE_NETWORK_PRINTER_AUTOCONNECT (0x00400000)
CTXPRN_DISABLE_NETWORK_PRINTER_DISCONNECT (0x00800000)
Description. The Presentation Server policies evaluated at logon and reconnect
include a special policy rule called Session Printers that you can use to add and
delete network printer connections on behalf of the logon user and based on
various policy criteria. Normally these network printer connections are added
during logons and reconnects and then deleted during logoff. These two flags
help the administrator to disable all printer connection additions and deletions
temporarily without having to disable many different policies. Turning off just
the disconnection of network printers can improve server scalability at the
expense of allowing printer connections made by the Session Printers policy rule
to accumulate in user profiles.
Default Value. All zero, unless one or more of the bit values is set in the
REG_DWORD registry value DefaultPrnFlags at
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\Print\.
Overriding Presentation Server Policy rule. None.

Miscellaneous Printer Flags


CTXPRN_DISABLE_CLIENT_PRINTER_MAPPING (0x00000008)
Description. By default, the SPL virtual channel is initialized and client printer
mapping is enabled. If set, this flag disables the SPL virtual channel and
disables the client printer mapping functionality of the system.
Default Value. Unless overridden, the Terminal Services default for this setting
is used. If the CTXPRN_OVERRIDE_TS_DEFAULTS flag is set in the
DefaultPrnFlags value at
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\Print\, the Terminal Services
defaults are ignored and the default flag value is taken from this REG_DWORD
value.
Overriding Presentation Server policy rule. Printing > Client Printers >
Client printer mapping.

Chapter 11 Printer
Management

24
9

CTXPRN_DONT_AUTO_CONNECT_LPTS (0x00000040)
Description. For compatibility reasons, LPT ports discovered on the client are
automatically mapped in client sessions. If the remapped LPT port is never used,
there is no reason to have mapped it. If this flag is set, LPT ports can still be
mapped in a client session, but they are not automatically mapped. Instead, a net
use command or the equivalent WNet* API must be used to establish any
mapping just as you would for a redirected COM port.
Default Value. All zero, unless one or more of the bit values is set in the
REG_DWORD registry value DefaultPrnFlags at
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\Print\.
Overriding Presentation Server policy rule. None.

CTXPRN_ADMINS_CAN_MANAGE (0x00004000)
Description. To preclude the possibility of an administrative user inadvertently
printing to a printer in someone elses Terminal Services session, the default
security descriptor used to auto-create client printers no longer includes any
rights for the administrators group. Only the user executing in the correct
session context has rights to the auto-created printers for the session.
Administrators can still grant themselves rights to any client printer by taking
ownership of the print queue and adding the desired rights.
Default Value. Zero, unless the bit value is set in the REG_DWORD registry
value DefaultPrnFlags at
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\Print\.
Overriding Presentation Server policy rule. None.

CTXPRN_DONT_LOG_AUTOCREATE_FAILURE (0x08000000)
Description. By default, printer auto-creation failures cause events to be logged
in the event viewers application log. Even printers created by the universal
printer driver result in an event because this is one of the few ways administrators
can determine precisely which printer models are in use by the client population.
Because this can result in a flood of events in the event viewer, this flag
provides the means to avoid generating event log entries for auto-creation
failures.
Overriding Presentation Server policy rule.
None.

25
0

Advanced Concepts
Guide
Default Value. Zero, unless the bit value is set in the REG_DWORD registry

value DefaultPrnFlags at
HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\Print\.

CTXPRN_AUTO_CREATE_GENERIC_UPD_PRINTER (0x00000020)
Description. The latest 32-bit Windows clients are capable of receiving and
displaying print jobs in a viewer application on the client. For such a client, it is
possible to create a single, generic universal printer that is not bound to any of
the underlying client printers. This printer is generic in the sense that it does not
know about or manage any device-specific settings. As such, it is also more
efficient to use because there is no need for capabilities or document settings
exchanges with the client when printing. Because creating an additional printer
within a session incurs overhead, by default, the creation of the generic
universal printer driver printer is turned off.
If this flag is set, the system auto-creates the generic Citrix Universal Printer in
addition to the other printers dictated by other auto-creation flags. For users who
do not require special printer capabilities, creating only a single, generic,
universal printer driver printer within the session instead of one printer for each
underlying client printer can provide a scalability savings. To see this savings,
this flag must be enabled, and default auto-creation polices also must be
overridden or assigned through policies.
Default Value. Zero, unless bit value is set in the REG_DWORD registry value
DefaultPrnFlags at HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\Print\.
Overriding Presentation Server policy rule. None.

CHAPTER 12

Replicating Data Stores


Running Microsoft SQL Server

This chapter describes how to replicate the SQL Server database that hosts your
server farms data store.
A replicated SQL Server database is often used to service computers running
Presentation Server in secondary locations across WAN links. It is advisable to
place replicated data stores in such secondary locations so that data store reads
can occur faster and without creating bottlenecks on the WAN.

Preparing for Replication


Review the following sections before replicating your data store database.

Determining Subscription Status


Replication occurs between a distributor server and subscriber servers. The
distributor has an entry for each subscriber, and each subscriber has an entry for
the distributor. Before replicating the data store, you must ensure that these
server relationships are established.
1. Use the stored procedure sp_helpserver to determine which servers are configured as remote
servers and view their current settings. The output of this stored procedure includes the name of
the local server along with entries for each remote server that is contacted as part of the
replication process. Ensure that:

The local server has an entry in this list. If not, review Manually Adding a Server on
page 252.

The local servers ID is 0, and both the name and network_name match.

25
2

Advanced Concepts
Guide

On the subscriber, there is an entry for repl_distributor with the network_name


of the distributor server.

On the distributor, there is an entry for each subscriber with a status that includes sub.

2. Use the sp_helpsubscriberinfo stored procedure at the distributor to view the subscription
information. Ensure that:

One entry for each subscriber exists

The publisher is identified correctly

The login and password fields are blank if the Impersonate the SQL Server Agent (trusted
connection) option is set

3. Display any existing subscription entries using the sp_helpsubscription_properties stored


procedure on the subscriber in the database. Ensure that:

The publisher is the name of the server that holds the source database for publication.

The publisher_db is the name of the database on the publisher.

The publication displays the name of the publication to which the database is subscribing.

The publisher_login is SA and the next field has an encrypted password (these are set
with the sp_link_publication stored procedure).

Verify the SA user name in sp_link_publication is capitalized. Lowercase sa fails to


create the RPC connection.

These entries exist only in the subscribers database.

Stored Procedures for Configuring Replication


The following section discusses the stored procedures that are available to
configure database replication.

Manually Adding a Server


If the local server is not displayed in the sp_helpserver stored procedure output,
add it manually using the sp_addserver stored procedure. For example:
exec sp_addserver '<servername>', 'Local'
go
select @@servername

Chapter 12 Replicating Data Stores Running Microsoft SQL


Server

25

If the distributor is not displayed in the sp_helpserver stored procedure output,


add it manually using the sp_adddistributor stored procedure. For example:
exec sp_adddistributor '<servername>'
go
select @@servername

Linking a Publication
If all subscribers are set to Impersonate the SQL Server Agent (trusted
connection) at the distributor, the publication link may still fail. If you see the
Login Failed for User sa error message, it may be because the dynamic RPC
calls are being attempted with an incorrect password. To reset the publication
link, use the sp_link_publication stored procedure from the database on the
subscriber. For example:
sp_link_publication '<Distributor>, '<Database>',
'<Publication>', 0, 'SA', '<Pwd>'

Where:
Distributor = The name of the distributor server
Database = The name of the published database on the
distributor Publication = The name of the publication that is to
be linked Pwd = The password for the SA account on the
distributor

Execute the sp_link_publication stored procedure. Verify that conflicting information from
sp_helpsubscription_properties is not present between the master and subscriber databases.

If the databases contain different information, use sp_link_publication to set the same
information in both databases or use sp_droppublication to remove the publication from the
master database.

Verify the SA user name in sp_link_publication is capitalized. Lowercase sa fails to


create the RPC connection.

25

Advanced Concepts
Guide

Cleaning up Old Subscriptions


If you have an existing database that you are unable to drop, you can run the
stored procedure sp_subscription_cleanup to remove unwanted subscription
entries from the target database (the database on the distributor):
sp_subscription_cleanup '<Distributor>', '<Database>', '<Publication>'
Where:
Distributor = The name of the distributor server
Database = The name of the published database on the distributor
Publication = The name of the publication that is to be linked
This procedure removes the entries created by sp_link_publication.

Replicating a Data Store in SQL Server 2000


To replicate a SQL Server 2000 database, use SQL Enterprise Manager. Begin
by creating a new database on the SQL Server that can be used as the source for
all replicas you create. Ensure that the account you use to create the database has
db_owner permissions and is the same one you use on the replicated database.
Before beginning the replication process, complete the following tasks:

The Windows installations should be clean (from CD) installations instead of images. If
images of Windows are used, ensure that they do not come from the same image but from
different ones for each server. If your Windows installations come from the same image,
replication does not work.

Do not mix Windows 2000 Server with Windows Server 2003. The Distributed Transaction
Coordinator service operates differently in each operating system. If you mix the operating
systems, replication fails.

For Windows Server 2003 verify that both publisher and subscriber SQL Servers are in
the same domain

Install SQL Server on the servers designated for the data stores

Verify that the Microsoft Distributed Transaction Coordinator is installed on the servers
designated for the data stores

Chapter 12 Replicating Data Stores Running Microsoft SQL


Server

25

Setting Up the Servers


Complete the following tasks on servers running SQL Server to set up the data
store for distribution.
1. From the Start menu, open Administrative Tools and select Services.
2. From the Services tool, set up the same domain logon account for the following services (the
local system account does not work):

SQLServerAgent

MSSQLServer

MSDTC (Distributed Transaction Coordinator on Windows 2000 Server)

Note If you are configuring SQL replication on Windows Server 2003, verify
that the MSDTC service is using the Network Services security account (this
account uses a blank password).
If you are configuring SQL replication on Windows Server 2003, you must also
verify the MSDTC security settings.
1. From the Start menu, open Administrative Tools and select Component Services.
2. Open the Properties dialog box for the My Computer node.
3. Click the Security Configuration button that appears under the MSDTC tab.
4. In the Security Configuration dialog box that appears, verify that the Network DTC Access,
Network Administration, and Network Transaction boxes are checked.

Replicating the Database


To replicate the SQL Server 2000 database that contains the data store, complete
the following four general steps:

Step 1: Establishing the Distributor Server


1. Microsoft SQL 2000 servers acting as publisher, distributor, and subscriber must be in the
same Windows NT or Active Directory domain. Start SQL Services under the same
account.
2. Open Enterprise Manager on the server on which the source database is located.
3. Right-click the Replication folder and select Configure Publishing, Subscribers,
Distribution Wizard.

25

Advanced Concepts
Guide

4. On the Select Distributor page, select the current server to act as the
distributor.
5. Keep the default Snapshot folder.
6. On the Customize the Configuration page, choose the option No, use the following
default settings.
7. Click Finish.

Step 2: Enabling Transactional Replication on the Distributor


1. Right-click the Replication Monitor folder and choose Distributor Properties.
2. On the Publication Databases tab, check Trans next to the database you want to replicate, as
shown in the figure:

Chapter 12 Replicating Data Stores Running Microsoft SQL


Server

25

Step 3: Publishing the Source Database


1. Right-click the database name and go to New > Publication to start the Create Publication
wizard.
2. Click Show advanced options in this wizard and then click Next.
3. On the Choose Publication Database screen, select the database you want to replicate and
then click Next.
4. On the Select Publication Type page, choose Transactional publication.
5. On the Updatable Subscriptions page, select the Immediate updating option, as shown in the
figure:
.

6. On the Specify Subscriber Types page, select the Servers running SQL Server 2000
option. Click Next.

25

Advanced Concepts
Guide

7. On the left side of the Specify Articles page, select both Show and Publish All for the tables
object type. Do not publish stored procedures to the replicated databases.

8. Click Next on the Article Issues page.


9. Name the publication.
10. On the Customize the Properties of the Publication page, choose No, create the publication
as specified.

Chapter 12 Replicating Data Stores Running Microsoft SQL


Server

11. Click Finish to complete the wizard. The publication appears in the Publications
folder, as shown:

Step 4: Pushing the Published Database to Subscribers


1. Right-click the published database in the Publications folder and choose Push new
subscription to start the Push Subscription wizard.
2. Click Show advanced options in this wizard and then click Next.
3. On the Choose Subscribers page, select the subscribers for the published database.
4. On the next page, choose the destination database to which you want to replicate the
source database.
5. On the Set Distribution Agent Location page, choose to run the agent at the distributor.
6. Set the Distribution Agent Schedule to continuously.

25

26

Advanced Concepts
Guide

7. On the Initialize Subscription page, choose Yes, initialize the schema and data and select
the option to Start the Snapshot Agent.

8. On the Updateable Subscriptions page, select the Immediate updating


option.

Chapter 12 Replicating Data Stores Running Microsoft SQL


Server

26

9. On the Start Required Services page, the services that must be running are listed. Verify that
the applicable required services are running on the distributor server.

10. Click Finish on the next screen to complete the wizard.

Troubleshooting the Replication


Ensure that the following seven tables on the replicated database are present:

DATATABLE

INDEXTABLE

KEYTABLE

MSreplication_objects

MSreplication_subscriptions

MSsubscription_agents

MSsubscription_properties

If not all tables are present, delete the replication setup and begin again.
The dtproperties table also appears if you used the Database Diagram
wizard in Enterprise Manager.

26

Advanced Concepts
Guide

Setting the Password for the Replica Database


When the subscription (replica) database is created on the subscriber server, the
password for the SA account is not passed for security reasons and therefore
needs to be set manually. Complete the following tasks to change the password
for the SA account:
1. Select the subscription database on the subscriber server.
2. Select Tools > SQL Query Analyzer.
3. In the SQL Query Analyzer window type and run the following stored procedure:
sp_link_publication 'Distributor, 'Database', 'Publication', 0, 'SA', 'Pwd'
Where:
Distributor = The name of the distributor server
Database = The name of the published database on the
distributor Publication = The name of the publication that is to
be linked Pwd = The password for the SA account on the
distributor
Note If you encounter problems running the preceding stored procedure, an
alternative procedure is: sp_link_publication 'publisher', 'database', 'publication',
0, 'SA', 'password', 'distributor'.

Multi-Subscriber Replication
Multi-subscriber replication, defined as comprising one publisher and two or
more subscribers, requires additional considerations.
By default, Microsoft SQL Server leaves foreign key referential integrity
constraints intact in the subscriber databases. Because Presentation Server uses a
two-phase commit between the subscriber and the publisher (distributor), these
constraints are not necessary because integrity is maintained at the distributor.
After a subscriber commits a transaction at the distributor, the distributor pushes
the changes out to all remaining subscribers. However, the referential integrity
constraints on the remaining subscribers prevent the transactions from completing
correctly.
When this occurs, you see error messages similar to the following:
DELETE statement conflicted with COLUMN REFERENCE constraint
'FK__DATATABLE nodei 35BCFE0A'. The conflict occurred in database
'CTXIMA', table 'DATATABLE', column 'nodeid'. The row was not found at the
Subscriber when applying the replicated command.
To prevent the foreign key relationships from blocking the replicated transaction,
perform the following steps on the subscribers only.

Chapter 12 Replicating Data Stores Running Microsoft SQL


Server

26

1. In Enterprise Manager, select the data store database.


2. Click Tables, right click DATATABLE in the right pane, and select Design Table from the
context menu.
3. Click the Manage Relationships button.

4. Verify Enforce Relationship for Replication is checked for the relationship that starts with FK
DATATABLE nodei.

5. Save the changes to the DATATABLE


6. Repeat Steps 3 6 for INDEXTABLE and the foreign key relationship that starts with FK
INDEXTABL__nodei.
7. In the foreign key relationships under KEYTABLE, verify that the checkbox
for
Enforce relationship for replication is clear.

26

Advanced Concepts
Guide

8. Repeat Steps 1 8 for each subscriber database.


Note Completing these steps on the distributor database may corrupt the data
store. In addition, if you re-initialize the subscription, the schema is reread from
the distributor and Steps 19 must be completed on the subscribers again.

Replicating a Data Store in SQL Server 7


Before beginning the replication process, complete the following tasks:
1. Ensure that you are not using a cloned or imaged installation of Windows 2000 Server or
Windows Server 2003.
2. Install SQL Server 7 on the servers that host the server farm data store.
3. Create a database on both the source server (the distributor) and the server that hosts the
replicated database (the subscriber).
Important Both new databases must have the same name so that you
can replicate the source database to the copy.
4. Verify that the Microsoft Distributed Transaction Coordinator is installed on the servers that
host the data store.
This section discusses an environment with two servers running SQL Server 7,
referred to as the distributor and the subscriber.

Setting Up the Servers


Complete the following tasks to prepare the distributor and subscriber servers for
the replication process.
1. Verify that you created two databases (one on the distributor and one on the subscriber) with
the same name. The following procedures assume that both the distributor and the subscriber
are in the same SQL Server group.
2. From the Start menu, start the Services Manager.
3. In Services Manager, set up the same domain logon account for the following services (the
local system account does not work):

SQLServerAgent

MSSQLServer

MSDTC (Distributed Transaction Coordinator on Windows 2000 Server)

Chapter 12 Replicating Data Stores Running Microsoft SQL


Server

26

To set up the database distributor


1. Select one of the SQL Server databases you created as the source database to be replicated or
published.
2. Install Presentation Server and point it to the database selected in Step 1. The database on this
server is now the server farms data store and the server is the distributor server.

Replicating the Database


To replicate the SQL Server 7 database that contains the data store, complete the
following four general steps:

Step 1: Enabling Replication on the Distributor


1. From the Start menu, start the Enterprise Manager.
2. Select Replicate Data in the right pane of Enterprise Manager.
3. Select Configure Replication. This starts the Configure Publishing and Distribution
wizard. Click Next.
4. Select Yes, use Server as the Distributor/Publisher, where Server is the server you selected to
distribute the data store database.
5. Select No, use the following default settings as the distribution settings. The default settings
designate this server as the sole distributor.
6. Click Finish. This server is now set up to replicate the data store.

Step 2: Enabling Transactional Replication on the Distributor


1. From the Start menu, start the Enterprise Manager.
2. Select Replicate Data in the right pane of Enterprise Manager.
3. Select Configure Replication. The Publisher and Distributor Properties wizard appears. Click
Next.
4. On the Publication Databases tab, check the Trans box next to the database holding the data
store. Click OK. The data store can now be replicated using transactional replication.
Note The dsmaint utility returns an error if you try to publish a database that
is not enabled for replication.

26

Advanced Concepts
Guide

Step 3: Publishing the Source Database Using the dsmaint Utility


From a command prompt, enter the command dsmaint publishsqlds /
user:username /pwd:password, where username and password are the
credentials of the account used by Presentation Server to access the database.
This account needs db_owner rights to configure the publication.

Step 4: Pushing the Published Database to the Subscribers


Complete the following tasks to distribute the data store on the distributor using
the Push Subscription wizard.
1. Verify that the SQL Server set up as the subscriber is registered in the SQL Server group.
2. Start Enterprise Manager on the SQL Server set up as the distributor.
3. In the left pane of Enterprise Manager, expand the folders under the Database folder until you
see MFXPDS, the publication you created with the dsmaint command.
4. Right-click MFXPDS and choose Push New Subscription from the shortcut menu that
appears. Click Next.
5. The Choose Subscribers dialog box appears. Select the subscriber from the SQL Server group
tree. The subscriber is the destination to host the copy of the data store pushed from the
distributor. Click Next.
The Specify Immediate-Updating Subscriptions dialog box appears.
6. On this dialog box, select Yes, make this an immediate-updating subscription(s). You must
employ immediate updating subscriptions to ensure coherency. Click Next.
The Set Distribution Agent Schedule dialog box appears.
Important Merge replication is not supported by Presentation Server because
it cannot guarantee the uniqueness of object creation across all servers in the
enterprise.
7. Select Continuously in Set Distribution Agent Schedule.
Continuous updating and a two-phase commit algorithm ensure data
coherency. When the subscriber receives a request to write to the data store,
the data is initially written to the data store on the publisher, then propagated
by the distributor to the copy of the data store on the subscriber. The
distributor is the only server that can write information to the data store on the
subscriber. Click Next. The Initialize Subscription dialog box appears.

Chapter 12 Replicating Data Stores Running Microsoft SQL


Server

26

8. Select the following options on this dialog box:


Yes, initialize the schema and data at the Subscriber. The database on
the subscriber is not yet initialized, so the schema and data must be
initialized. Start the agent immediately. The Distribution Agent begins
replication as soon as the database becomes available. Click Next.
The Start Required Services dialog box appears.
9. On this dialog box, verify that all necessary services are running on both the distributor and
the subscriber. The state for the MSDTC service on the subscriber always displays as
Unknown even though it is running.
To verify that MSDTC is running, check Services in Administrative Tools in
the Control Panel on the subscriber. Click Next.
The Completing the Push Subscription wizard appears.
When the Push Subscription wizard is done running, replication begins. You
can monitor the progress of the replication in Replication Monitor in
Enterprise Manager.
10. When replication is complete, ensure that there are no replication alert errors in
Replication Monitor.

Pointing Servers to the Replicated Data Store


After replicating the server farms data store, you can install Presentation Server
on servers and point them to the replicated data store.
1. Start Presentation Server Setup.
2. When you are prompted for the location of the database that is hosting the server farms
data store, point the server to the replicated data store (on the subscriber).
3. When you are done installing Presentation Server, open the Presentation Server Console and
publish an application.
4. If the server can write the information about the published application to the data store, the
data store was successfully replicated on the subscriber.
Note You can redirect existing servers to the replicated copy of the data store
by running the dsmaint config command.

26

Advanced Concepts
Guide

APPENDIX A

Utilities

This chapter describes some of the Citrix utilities included with Presentation
Server that you can use for configuration, management, and troubleshooting. Use
command-line utilities at a command prompt, in a batch file on the computers
running Presentation Server, or in an ICA session. For more information about
Citrix utilities, see the MetaFrame Presentation Server Administrators Guide.
This chapter explains how to use the following utilities:
AIERUN
AIESETUP
DSVIEW
MSGHOOK
QPRINTER
QUERYDC
QUERYDS
QUERYHR
SCCONFIG
LMNEWLOG
LMSWITCH
SSLAUTOCONFIG

27
0

Advanced Concepts
Guide

AIERUN

Use this utility to launch an application into an isolation environment.

Syntax
aierun [/w] AIE_Name Application [application parameters]
aierun [/?]

Parameters
AIE_Name
The name of the isolation environment.
Application [application parameters]
The name of the application to launch in the named isolation environment.
You can also append application parameters, if any.

Options
/w
Waits for the application launched by aierun to exit before continuing.
This option is useful when aierun is used in a script or batch file.
/?
Displays the syntax for the command and information about the
command options.

Remarks
aierun is an internal launcher used by Presentation Server during application
launching. It should not be made available to users under normal circumstances.
Use of aierun from a desktop session is not supported.

Appendix A Utilities

AIESETUP

27

Use this utility to install an application into an isolation environment.


aiesetup launches the specified application installer and forces the
application to install within the specified isolation environment.

Syntax
aiesetup [/d] [/n] [/q] [/w] AIE_Name Setup_application [application
parameters]
aiesetup
[/?]
aiesetup
AIE_Name

[/e]

Parameters
AIE_Nam
e
The name of the isolation environment.
Setup_application [application parameters]
The name of an application installer, such as MSI or EXE, to run. You can
also append any parameters that the installer is required to process.
Note If the installation file is an MSI, you must prefix the command msiexec
/I to path/AppInstallationFile. For more information about the msiexec
command, refer to your Windows Server documentation.

Options
/d
Disables the automatic application discovery process for the isolation
environment.
/n
Disables automatically setting the Windows server to install mode. By
default, aiesetup automatically sets the Windows server to install mode
(using the change user install command).
/q
Waits for the application installer launched by aiesetup to exit and runs
application discovery in silent mode. This option is useful when aiesetup is
run by application deployment software such as Microsoft Systems
Management Server.

27

Advanced Concepts
Guide

/w
Waits for the application installer launched by aiesetup to exit before
continuing. This option is useful when aiesetup is used in a script or batch
file.
/e AIE_Name
Enumerates applications installed in the specified isolation environment.
/?
Displays the syntax for the command and information about the command
options.

Remarks

When installation is complete, the silent application discovery process is invoked. The
application discovery process locates application shortcuts added by the installer and adds the
information to the data store. Data collected by the application discovery process facilitates
publishing of applications installed in an isolation environment.

To omit the application discovery process, you can use the /d option with aiesetup. If you did
not use the /d switch for aiesetup, the following message is displayed at a command prompt:
Press <Enter> to start the application discovery process when application
installation completes.
Press Q to skip application discovery and quit.

Application isolation functionality includes the ability to install, and uninstall applications into
an isolation environment. This is useful in cases when different versions of an application
cannot be installed on a single server.

Security Restrictions

To execute aiesetup, you must be a Presentation Server administrator with permission to


perform the following tasks:

Manage isolation environments for the farm

Publish applications and edit properties for the farm

Installing an application into an isolation environment through a connection made with Remote
Desktop Connection is not supported. Run aiesetup on the server where you are installing the
application.

Appendix A Utilities

DSVIEW

27

Use this utility to view the contents of the data store or the local host cache and
to look up ContextIds and UIDs. This utility includes a user interface, as shown:

Remarks
Dsview replaces IMATester, a utility documented in earlier editions of the
MetaFrame XP Advanced Concepts Guide. It is located in the \support\debug\OS
folder on the Presentation Server CD; where OS is either w2k for Windows
2000 Server or W2K3 for Windows Server 2003.

Security Restrictions
Only local administrators can use dsview to view data.

27

Advanced Concepts
Guide

MSGHOOK
Use this utility to display all IMA traffic on a member server.

Syntax
msghook

Remarks

Execute msghook only if information is requested by a Citrix Technical Support


representative or a Citrix engineer. When invoked, this command significantly reduces
Presentation Server performance.

Msghook is not installed by default. It is located in the \support\debug\OS folder on the


Presentation Server CD; where OS is either w2k for Windows 2000 Server or W2K3 for
Windows Server 2003.

Security Restrictions
Only Presentation Server administrators can execute this command.

Appendix A Utilities

27

QPRINTER
Use this utility to monitor the progress of the printer driver replication queue and
to import printer name mapping parameters into the data store.

Syntax
qprinter [/replica]
qprinter [/imprmapping mappingfilename]

Parameters
mappingfilename
Specifies the full path to the text file containing the printer mapping
parameters to import. The filename cannot have more than 256 characters and
cannot contain quotation marks.

Options
/replica
Displays all the replication entries queued for distribution but not yet
completed.
/imprmapping mappingfilename
Imports printer mappings from the file specified by mappingfilename into the
data store. The file format can be in either the Wtsprnt.inf format or the
Wtsuprn.txt format.

27

Advanced Concepts
Guide

Remarks

The /replica switch displays all events in the queue, including broken or failed events.

The /imprmapping switch allows central administration of all printer name mappings. The
file can be imported once from any server in the farm and is available for all servers in the
farm.

The /imprmapping switch does not process an imcorrectly formatted file and does not return
an error message when provided with an invalid file format. To verify the information is
correctly imported into the data store, use the console.

The Presentation Server installation first attempts to import the Wtsuprn.txt file, followed by the
Wtsprnt.inf file. If the two files fail to import, no error message is returned. Use the
/imprmapping switch to manually import either file.

Qprinter is not installed by default. It is located in the \support\debug\OS folder on the


Presentation Server CD; where OS is either w2k for Windows 2000 Server or W2K3 for
Windows Server 2003.

Security Restrictions
Only Presentation Server administrators can execute this command.

Appendix A Utilities

QUERYD
C

27

Use this utility to determine the data collector for a given zone. Without any
parameters, querydc defaults to the host servers zone and returns the zone
name and name of the current zone data collector.

Syntax
querydc [a] querydc
[-e]
querydc [-z zonename]
querydc [-?]

Parameters
zonename
The name of the zone to be queried. Enclose multi-word zone names
within quotation marks.

Options
-a
Displays all zones in the farm with the current zone data collector for each.
-e
Forces a new zone data collector election in the current zone.
-z zonename
Displays the current zone data collector for the zone specified by zonename.
-?
Displays the syntax for the utility and information about the utilitys options.

27

Advanced Concepts
Guide

Remarks

Querydc uses the IMA Service to contact the local zone data collector for the requested
information. Therefore, the IMA Service must be running for querydc to be successful.

Querydc is not installed by default. It is located in the \support\debug\OS folder on the


Presentation Server CD; where OS is either w2k for Windows 2000 Server or W2K3 for
Windows Server 2003.

Security Restrictions
Only Presentation Server administrators can execute this command.

Appendix A Utilities

QUERYD
S

27

Because all dynamic information is stored in tables in the data collectors


physical RAM, this command-line utility is provided to query the current
information on the local zone data collector.

Syntax
queryds
tables
queryds /table:tablename
queryds
/query:querystring
(Query String is optional, but you must specify a
tablename.)

Parameters
tablenam
e
The name of the data collector table to query. Table names are case-sensitive.

Options
table
s
Returns a complete list of all tables available to query.
/table:tablename
Outputs to the screen the entire contents of the table specified by tablename.

28

Advanced Concepts
Guide

Remarks

You can use queryds to determine which servers are currently available in a farm. It retrieves
all information from the tables stored on the local zone data collector. For example, the
PN_Table contains information about all available servers that are accepting Program
Neighborhood connections. To view the entire contents of the PN_Table, execute the
following command:
queryds /table:PN_Table
The output when executed on a single-server farm looks similar to the
following:
[PN_Table]: 1 records.
name:588f
host:XPSERVER1
zone:Zone1
Version:1
Tcp:enabled
Ipx:enabled
Netbios:disabled

In a farm with 100 servers, this command outputs 702 lines of data. Use the findstr and sort
command-line utilities to filter and sort the output for easier reading.
Tip The findstr and sort commands are installed by default on both the
Terminal Server Edition and Windows 2000 Server families. For more
information about using the findstr command to filter output, type findstr /?
at a command prompt. For more information about the sort command, type
sort /? at a command prompt.

The first entry shows the number of records in the PN_Table. This number also corresponds
directly to the number of server records in the PN_Table. A server record does not exist in the
PN_Table unless the servers IMA Service is started and the server is accepting Program
Neighborhood connections. Thus, you can use the following command to determine how many
servers in the farm are online:
queryds /table:PN_Table | findstr /r PN_Table

Appendix A Utilities

28

The following command filters output using the word host (which prefaces each host name
in the table) and displays an alphabetized list of all the servers currently online:
queryds /table:PN_Table | findstr /r host | sort
Using queryds in this manner provides a fast, customizable method to query
any data collector table.

Queryds is not installed by default. It is located in the \support\debug\OS folder on the


Presentation Server CD; where OS is either w2k for Windows 2000 Server or W2K3 for
Windows Server 2003.

Security Restrictions
You must be a Presentation Server administrator to execute this command.

28

Advanced Concepts
Guide

QUERYHR
Use this utility to display information about member servers in the farm. Executing
queryhr with no parameters lists all servers in the farm.

Syntax
queryhr [-z]
queryhr [-h zonename]
queryhr [-l]
queryhr [-n hostname]
queryhr [-i hostid]
queryhr [-N]
queryhr [-d hostid]
queryhr [-?]

Parameters
zonename
The name of the zone to be queried. Enclose multi-word zone names within
quotation marks.
hostname
The name of the member server.
hostid
The host ID of the member server.

Options
-z
Displays all available zones in the farm.
-h zonename
Displays all member servers in the zone specified by zonename.
-l
Displays the host record of the local host server.
-n hostname
Displays the host record for the member server specified by hostname, which
is not case-sensitive.

Appendix A Utilities

28

-i hostid
Displays the record for the member server specified by hostid.
-N
Displays the farm name.
-d hostid
Deletes the IMA Host Entry identified by hostid from the data collector, data
store, and local host cache. For further information, see the Remarks section.
-?
Displays the syntax for the utility and information about the utilitys options.

Remarks

Queryhr obtains information from the local host cache.

Queryhr is best used to display information about servers in the farm, such as data collector
ranking, host ID, zone names, and host names.
Caution Do not use the d switch on farm servers that are working correctly.
After this switch is executed on a server, the server is no longer a member of
the farm and the IMA Service no longer starts. The server must be reinstalled
into the farm to restore functionality.

Queryhr is not installed by default. It is located in the \support\debug\OS folder on the


Presentation Server CD; where OS is either w2k for Windows 2000 Server or W2K3 for
Windows Server 2003.

Security Restrictions
You must be a Presentation Server administrator to execute this command.

28

Advanced Concepts
Guide

SCCONFIG
When using versions of Presentation Server prior to Version 4.0, only processes
required for smart card logon functionality (that is, Winlogon.exe and Lsass.exe)
are turned on by default. The smart card utility (Scconfig.exe) can be used to enable
or disable smart card functionality for specific processes.
Note Starting with Presentation Server 4.0, smart card functionality is enabled
for all processes and Scconfig has been deprecated.

Syntax
scconfig [/?]
scconfig [/server:sss] [/q]
scconfig [/farm] [/q]
scconfig [/server:sss] [/query]
scconfig [/farm] [/query]
scconfig [/server:sss] [/logon:on|off]
scconfig [/farm] [/logon:on|off]
scconfig [/server:sss] [/enable_process:ppp]
scconfig [/farm] [/enable_process:ppp]
scconfig [/server:sss]
[/disable_process:ppp] scconfig [/farm]
[/disable_process:ppp] scconfig
[/server:sss] [/inherit:on|off]

Parameters
sss
Name of server.
ppp
Name of process (for example, Outlook.exe).

Options
/farm
View or modify farm-wide settings.

Appendix A Utilities

28

/q, query
Query current settings.
/logon:on|off
Enable/disable smart card logon on the server or farm.
/enable_process:ppp
Enable smart card support for the process specified.
/disable_process:ppp
Disable smart card support for the process specified.
/inherit:on|off
Inherit server settings from the farm.
/server:sss
Server to view or modify. This defaults to the local server.
Example: To use Microsoft Outlook digital signatures and encryption with a smart
card, you must enable the process Outlook.exe. On the remote server, the server
subsystem handles the data store change event and makes the registry changes to
enable or disable the feature. Use the /farm option to query or set a farm-wide
default. Use the /inherit option to determine whether or not a server inherits a
farm- wide default. This functionality mimics that of twconfig and acrcfg.

28

Advanced Concepts
Guide

LMNEWLO
G

The lmnewlog utility switches the report log file by moving the existing report
log information to a new file, then starting a new report log with the original
report log file name. If you rotate report logs with lmnewlog instead of
lmswitchr, you do not have to change the file name in the REPORTLOG line of
the options file.

Syntax
lmnewlog
[-c
renamed_report_log

license_file_list]

feature

license_file_list]

CITRIX

orlmnewlog
[-c
renamed_report_log

Parameters
-c
license_file_list
Use the specified license files.
featur
e
Specifies any feature in the specified license files.
CITRIX
Specifies all features listed in the specified license files.
renamed_report_lo
g
New file path where existing report log information is to be moved.

Appendix A Utilities

LMSWITCH

28

The lmswitch utility switches the debug log file written by the Citrix vendor
daemon by closing the existing debug log for that vendor daemon and starting
a new debug log for that vendor daemon with a new file name. It also starts a
new debug log file written by that vendor daemon if one does not already
exist.

Syntax
lmswitch [-c license_file_list] vendor new_debug_log

Parameters
-c license_file_list
Use the specified license files.
vendor
Vendor daemon in this license file..
new_debug_log
Path to new debug log file.

Remarks
By default, debug log output from lmgrd and all vendor daemons started by
that lmgrd get written into the same debug file. lmswitch allows companies to
keep separate log files for different vendors and control the size of their debug
log file.
If debug log output is not already directed to a separate file for this vendor
daemon, lmswitch tells the vendor daemon to start writing its debug log output to
a file, new_debug_log. If this vendor daemon is already writing to its own debug
log, lmswitch tells the vendor daemon to close its current debug log file and start
writing its debug log output to new_debug_log.
Note The effect of lmswitch continues only until the vendor daemon is shut
down or its options file is reread through lmreread. When the vendor daemon is
restarted or its options file is reread, it looks for a DEBUGLOG line in the
options file to determine whether or not to write its debug log output into its own
file and, if so, what file to write.

28

Advanced Concepts
Guide

SSLAUTOCONFIG
You can use the SSLAutoConfig utility to set up SSL Relay for secure
communications. For more information, see Using SSLAutoConfig to
Download and Configure Certificates on page 177.

Syntax
sslautoconfig [-r] [-p port_number] [-f file_name]

Parameters
-r
Starts the server. The default setting is not to restart.
-p port_number
Overrides the default port number 443. If you are using IIS running on port
443, use -p to specify an alternate port number.
-f file_name
Specifies to use a settings file other than settings.ini in the current working
directory.

APPENDIX C

IMA Error Codes


The items in the following table are Citrix IMA Service error codes that can
appear in the Event Viewer
Hex value

Signed value

Unsigned
value

Mnemonic

00000000h

IMA_RESULT_SUCCESS

00000001h

IMA_RESULT_OPERATION_INCOMPLETE

00000002h

IMA_RESULT_CALL_NEXT_HOOK

00000003h

IMA_RESULT_DISCARD_MESSAGE

00000004h

IMA_RESULT_CREATED_NEW

00000005h

IMA_RESULT_FOUND_EXISTING

00000009h

IMA_RESULT_CONNECTION_IDLE

00130001h

1245185

1245185

IMA_RESULT_DS_NOT_INSTALLED

00130002h

1245186

1245186

IMA_RESULT_SECURITY_INFO_INCOMPLETE

002D0001h

2949121

2949121

IMA_RESULT_ALREADY_MASTER

80000001h

-2147483647

2147483649

IMA_RESULT_FAILURE

80000002h

-2147483646

2147483650

IMA_RESULT_NO_MEMORY

80000003h

-2147483645

2147483651

IMA_RESULT_INVALID_ARG

80000004h

-2147483644

2147483652

IMA_RESULT_UNKNOWN_MESSAGE

80000005h

-2147483643

2147483653

IMA_RESULT_DESTINATION_UNREACHABLE

80000006h

-2147483642

2147483654

IMA_RESULT_REFERENCE_COUNT_NOT_ZERO

80000007h

-2147483641

2147483655

IMA_RESULT_ENTRY_NOT_FOUND

29
6

Advanced Concepts
Guide

Hex value

Signed value

Unsigned
value

Mnemonic

80000008h

-2147483640

2147483656

IMA_RESULT_NETWORK_FAILURE

80000009h

-2147483639

2147483657

IMA_RESULT_NOT_IMPLEMENTED

8000000Ah

-2147483638

2147483658

IMA_RESULT_INVALID_MESSAGE

8000000Bh

-2147483637

2147483659

IMA_RESULT_TIMEOUT

8000000Ch

-2147483636

2147483660

IMA_RESULT_POINTER_IS_NULL

8000000Dh

-2147483635

2147483661

IMA_RESULT_UNINITIALIZED

8000000Eh

-2147483634

2147483662

IMA_RESULT_FINDITEM_FAILURE

8000000Fh

-2147483633

2147483663

IMA_RESULT_CREATEPOOL_FAILURE

80000010h

-2147483632

2147483664

IMA_RESULT_SUBSYS_NOT_FOUND

80000013h

-2147483629

2147483667

IMA_RESULT_PS_UNINITIALIZED

80000014h

-2147483628

2147483668

IMA_RESULT_REGMAPFAIL

80000015h

-2147483627

2147483669

IMA_RESULT_DEST_TOO_SMALL

80000016h

-2147483626

2147483670

IMA_RESULT_ACCESS_DENIED

80000017h

-2147483625

2147483671

IMA_RESULT_NOT_SHUTTING_DOWN

80000018h

-2147483624

2147483672

IMA_RESULT_MUSTLOAD_FAILURE

80000019h

-2147483623

2147483673

IMA_RESULT_CREATELOCK_FAILURE

8000001Ah

-2147483622

2147483674

IMA_RESULT_SHUTDOWN_FAILURE

8000001Ch

-2147483620

2147483676

IMA_RESULT_SENDWAIT_FAILURE

8000001Dh

-2147483619

2147483677

IMA_RESULT_NO_COLLECTORS

8000001Eh

-2147483618

2147483678

IMA_RESULT_UPDATED

8000001Fh

-2147483617

2147483679

IMA_RESULT_NO_CHANGE

80000020h

-2147483616

2147483680

IMA_RESULT_LEGACY_NOT_ENABLED

80000021h

-2147483615

2147483681

IMA_RESULT_VALUE_ALREADY_CREATED

80000022h

-2147483614

2147483682

IMA_RESULT_UID_EXCEEDED_BOUNDS

80000023h

-2147483613

2147483683

IMA_RESULT_NO_EVENTS

80000024h

-2147483612

2147483684

IMA_RESULT_NOT_FOUND

80000025h

-2147483611

2147483685

IMA_RESULT_ALREADY_EXISTS

80000026h

-2147483610

2147483686

IMA_RESULT_GROUP_ALREADY_EXISTS

Appendix C Error Codes

Hex value

Signed value

Unsigned
value

Mnemonic

80000027h

-2147483609

2147483687

IMA_RESULT_NOT_A_GROUP

80000028h

-2147483608

2147483688

IMA_RESULT_GROUP_DIR_ACCESS_FAILURE

80000029h

-2147483607

2147483689

IMA_RESULT_EOF

8000002Ah

-2147483606

2147483690

IMA_RESULT_REGISTRY_ERROR

8000002Bh

-2147483605

2147483691

IMA_RESULT_DSN_OPEN_FAILURE

8000002Ch

-2147483604

2147483692

IMA_RESULT_REMOVING_PSSERVER

8000002Dh

-2147483603

2147483693

IMA_RESULT_NO_REPLY_SENT

8000002Eh

-2147483602

2147483694

IMA_RESULT_PLUGIN_FAILED_VERIFY

8000002Fh

-2147483601

2147483695

IMA_RESULT_FILE_NOT_FOUND

80000030h

-2147483600

2147483696

IMA_RESULT_PLUGIN_ENTRY_NOT_FOUND

80000031h

-2147483599

2147483697

IMA_RESULT_CLOSED

80000032h

-2147483598

2147483698

IMA_RESULT_PATH_NAME_TOO_LONG

80000033h

-2147483597

2147483699

IMA_RESULT_CREATEMESSAGEPORT_FAILED

80000034h

-2147483596

2147483700

IMA_RESULT_ALTADDRESS_NOT_DEFINED

80000035h

-2147483595

2147483701

IMA_RESULT_WOULD_BLOCK

80000036h

-2147483594

2147483702

IMA_RESULT_ALREADY_CLOSED

80000037h

-2147483593

2147483703

IMA_RESULT_TOO_BUSY

80000038h

-2147483592

2147483704

IMA_RESULT_HOST_SHUTTING_DOWN

80000039h

-2147483591

2147483705

IMA_RESULT_PORT_IN_USE

8000003Ah

-2147483590

2147483706

IMA_RESULT_NOT_SUPPORTED

80040001h

-2147221503

2147745793

IMA_RESULT_FILE_OPEN_FAILURE

80040002h

-2147221502

2147745794

IMA_RESULT_SESSION_REQUEST_DENIED

80040003h

-2147221501

2147745795

IMA_RESULT_JOB_NOT_FOUND

80040004h

-2147221500

2147745796

IMA_RESULT_SESSION_NOT_FOUND

80040005h

-2147221499

2147745797

IMA_RESULT_FILE_SEEK_FAILURE

80040006h

-2147221498

2147745798

IMA_RESULT_FILE_READ_FAILURE

80040007h

-2147221497

2147745799

IMA_RESULT_FILE_WRITE_FAILURE

80040008h

-2147221496

2147745800

IMA_RESULT_JOB_CANNOT_BE_UPDATED

29

29

Advanced Concepts
Guide

Hex value

Signed value

Unsigned
value

Mnemonic

80040009h

-2147221495

2147745801

IMA_RESULT_NO_TARGET_HOSTS

8004000Ah

-2147221494

2147745802

IMA_RESULT_NO_SOURCE_FILES

80060001h

-2147090431

2147876865

IMA_RESULT_ATTR_NOT_FOUND

80060002h

-2147090430

2147876866

IMA_RESULT_CONTEXT_NOT_FOUND

80060003h

-2147090429

2147876867

IMA_RESULT_VALUE_NOT_FOUND

80060004h

-2147090428

2147876868

IMA_RESULT_DATA_NOT_FOUND

80060005h

-2147090427

2147876869

IMA_RESULT_ENTRY_LOCKED

80060006h

-2147090426

2147876870

IMA_RESULT_SEARCH_HASMORE

80060007h

-2147090425

2147876871

IMA_RESULT_INCOMPLETE

80060008h

-2147090424

2147876872

IMA_RESULT_READEXCEPTION

80060009h

-2147090423

2147876873

IMA_RESULT_WRITEEXCEPTION

8006000Ah

-2147090422

2147876874

IMA_RESULT_LDAP_PARTIALINSTALL

8006000Bh

-2147090421

2147876875

IMA_RESULT_LDAP_NOTREADY

8006000Ch

-2147090420

2147876876

IMA_RESULT_BUFFER_TOO_SMALL

8006000Dh

-2147090419

2147876877

IMA_RESULT_CONTAINER_NOT_EMPTY

8006000Eh

-2147090418

2147876878

IMA_RESULT_CONFIGURATION_ERROR

8006000Fh

-2147090417

2147876879

IMA_RESULT_GET_BASEOBJECT

80060010h

-2147090416

2147876880

IMA_RESULT_GET_DERIVEDOBJECT

80060011h

-2147090415

2147876881

IMA_RESULT_OBJECTCLASS_NOTMATCH

80060012h

-2147090414

2147876882

IMA_RESULT_ATTRIBUTE_NOTINDEXED

80060013h

-2147090413

2147876883

IMA_RESULT_OBJECTCLASS_VIOLATION

80060014h

-2147090412

2147876884

IMA_RESULT_ENUMFAIL

80060015h

-2147090411

2147876885

IMA_RESULT_ENUMNODATA

80060016h

-2147090410

2147876886

IMA_RESULT_DBCONNECT_FAILURE

80060017h

-2147090409

2147876887

IMA_RESULT_TRUNCATE

80060018h

-2147090408

2147876888

IMA_RESULT_DUPLICATE

80060019h

-2147090407

2147876889

IMA_RESULT_PS_NOTINITIALIZED

8006001Ah

-2147090406

2147876890

IMA_RESULT_USING_ORACLE_7

Appendix C Error Codes

Hex value

Signed value

Unsigned
value

Mnemonic

8006001Bh

-2147090405

2147876891

IMA_RESULT_USING_ORACLE_8

8006001Ch

-2147090404

2147876892

IMA_RESULT_USING_ORACLE_UNKNOWN

8006001Dh

-2147090403

2147876893

IMA_RESULT_LOAD_DAO_ENGINE_FAILED

8006001Eh

-2147090402

2147876894

IMA_RESULT_COMPACT_DB_FAILED

80060033h

-2147090381

2147876915

IMA_RESULT_ODBC_NO_CONNECTIONS
_AVAILABLE

80060034h

-2147090380

2147876916

IMA_RESULT_CREATE_SQL_ENVIRONMENT
_FAILED

80060035h

-2147090379

2147876917

IMA_RESULT_SQL_EXECUTE_FAILED

80060036h

-2147090378

2147876918

IMA_RESULT_SQL_FETCH_FAILED

80060037h

-2147090377

2147876919

IMA_RESULT_SQL_BIND_PARAM_FAILED

80060038h

-2147090376

2147876920

IMA_RESULT_SQL_GET_COLUMN_DATA_FAILED

80060039h

-2147090375

2147876921

IMA_RESULT_REPLICATED_DATA_CONTENTION

8006003Ah

-2147090374

2147876922

IMA_RESULT_DB_TABLE_NOT_FOUND

8006003Bh

-2147090373

2147876923

IMA_RESULT_CONNECTION_EXIST

8006003Ch

-2147090372

2147876924

IMA_RESULT_QUERY_MAX_NODEID_FAILED

8006003Dh

-2147090371

2147876925

IMA_RESULT_SQL_FUNCTION_SEQUENCE
_ERROR

8006003Eh

-2147090370

2147876926

IMA_RESULT_DB_CONNECTION_TIMEOUT

8006003Fh

-2147090369

2147876927

IMA_RESULT_SQL_INVALID_TRANSACTION
_STATE

80060040h

-2147090368

214787928

IMA_RESULT_DB_NO_DISK_SPACE

80110104h

-2146369276

2148598020

LMS_RESULT_NO_SERVER_AVAILABLE

80110105h

-2146369024

2148598272

IMA_RESULT_FULL_SERVER_OR_APP_LOAD
_REACHED

80130001h

-2146238463

2148728833

IMA_RESULT_MORE_ITEMS

80130002h

-2146238462

2148728834

IMA_RESULT_INVALID_ACCOUNT

80130003h

-2146238461

2148728835

IMA_RESULT_INVALID_PASSWORD

80130004h

-2146238460

2148728836

IMA_RESULT_EXPIRED_PASSWORD

80130005h

-2146238459

2148728837

IMA_RESULT_GROUP_IGNORED

80130006h

-2146238458

2148728838

IMA_RESULT_BUILTIN_GROUP

29

30

Advanced Concepts
Guide

Hex value

Signed value

Unsigned
value

Mnemonic

80130007h

-2146238457

2148728839

IMA_RESULT_DC_NOT_AVAILABLE

80130008h

-2146238456

2148728840

IMA_RESULT_NW_CLIENT_NOT_INSTALLED

80130009h

-2146238455

2148728841

IMA_RESULT_ACCOUNT_LOCKED_OUT

8013000Ah

-2146238454

2148728842

IMA_RESULT_INVALID_LOGON_HOURS

8013000Bh

-2146238453

2148728843

IMA_RESULT_ACCOUNT_DISABLED

8013000Ch

-2146238452

2148728844

IMA_RESULT_PREFERRED_TREE_NOT_SET

80160001h

-2146041855

2148925441

IMA_RESULT_NODE_NOT_FOUND

80160002h

-2146041854

2148925442

IMA_RESULT_NODE_NAME_INVALID

80160003h

-2146041853

2148925443

IMA_RESULT_NODE_NOT_EMPTY

80160004h

-2146041852

2148925444

IMA_RESULT_NODE_MOVE_DENIED

80160005h

-2146041851

2148925445

IMA_RESULT_NODE_NAME_NOT_UNIQUE

80160006h

-2146041850

2148925446

IMA_RESULT_NODE_RENAME_DENIED

80160007h

-2146041849

2148925447

IMA_RESULT_CONSTRAINT_VIOLATION

80160008h

-2146041848

2148925448

IMA_RESULT_LDAP_PROTOCOL_ERROR

80160009h

-2146041847

2148925449

IMA_RESULT_LDAP_SERVER_DOWN

8016000Ch

-2146041844

2148925452

IMA_RESULT_NODE_DELETE_DENIED

8016000Fh

-2146041841

2148925455

IMA_RESULT_CANNOTCHANGE_PASSWORD

80160010h

-2146041840

2148925456

IMA_RESULT_CANNOTCHANGE_LAST_RW

80160011h

-2146041839

2148925457

IMA_RESULT_LOGON_USER_DISABLED

80160012h

-2146041838

2148925458

IMA_RESULT_CMC_CONNECTION_DISABLED

80160013h

-2146041837

2148925459

IMA_RESULT_INSUFFICIENT_SERVER_SEC
_FOR_USER

80160014h

-2146041836

2148925460

IMA_RESULT_FEATURE_LICENSE_NOT_FOUND

80160015h

-2146041835

2148925461

IMA_RESULT_DISALLOW_CMC_LOGON

80260001h

-2144993279

2149974017

IMA_RESULT_NW_PRINT_SERVER_ALREADY
_PRESENT

80260002h

-2144993278

2149974018

IMA_RESULT_SERVER_ALREADY_PRESENT

802D0001h

-2144534527

2150432769

IMA_RESULT_TABLE_NOT_FOUND

802D0002h

-2144534526

2150432770

IMA_RESULT_NOT_TABLE_OWNER

Appendix C Error Codes

Hex value

Signed value

Unsigned
value

Mnemonic

802D0003h

-2144534525

2150432771

IMA_RESULT_INVALID_QUERY

802D0004h

-2144534524

2150432772

IMA_RESULT_TABLE_OWNER_HAS_CHANGED

802D0005h

-2144534523

2150432773

IMA_RESULT_SERVICE_NOT_AVAILABLE

802D0006h

-2144534522

2150432774

IMA_RESULT_ZONE_MASTER_UNKNOWN

802D0007h

-2144534521

2150432775

IMA_RESULT_NON_UNIQUE_HOSTID

802D0008h

-2144534520

2150432776

IMA_RESULT_REG_VALUE_NOT_FOUND

802D0009h

-2144534519

2150432777

IMA_RESULT_PARTIAL_LOAD

802D000Ah

-2144534518

2150432778

IMA_RESULT_GATEWAY_NOT_ESTABLISHED

802D000Bh

-2144534517

2150432779

IMA_RESULT_INVALID_GATEWAY

802D000Ch

-2144534516

2150432780

IMA_RESULT_SERVER_NOT_AVAILABLE

80300001h

-2144337919

2150629377

IMA_RESULT_SERVICE_NOT_SUPPORTED

80300002h

-2144337920

2150629378

IMA_RESULT_BUILD_SD_FAILED

80300003h

-2144337921

2150629379

IMA_RESULT_RPC_USE_ENDPOINT_FAILED

80300004h

-2144337922

2150629380

IMA_RESULT_RPC_REG_INTERFACE_FAILED

80300005h

-2144337923

2150629381

IMA_RESULT_RPC_LISTEN_FAILED

80300006h

-2144337924

2150629382

IMA_RESULT_BUILD_FILTER_FAILED

80300007h

-2144337925

2150629383

IMA_RESULT_RPC_BUFFER_TOO_SMALL

80300008h

-2144337926

2150629384

IMA_RESULT_REQUEST_TICKET_FAILED

80300009h

-2144337927

2150629385

IMA_RESULT_INVALID_TICKET

8030000Ah

-2144337928

2150629386

IMA_RESULT_LOAD_TICKETDLL_FAILED

301

Event Log Error Messages


The following error messages are found in ImaMsgs.dll and appear in the Event
Log.
Message ID

Message Text

3584

Failed to open system registry key with error %1

3585

Failed to initialize registrar component with error %1

3586

Failed to prepare the transport system for operation with error %1

30

Advanced Concepts
Guide
Message ID

Message Text

3587

Incompatible WinSock version

3588

Failed to prepare the messaging system for operation with error %1

3589

Invalid FailedComponentId (%1)

3590

Failed to prepare the plugin system with error %1

3591

Failed to initialize all components with error %1

3592

Failed to start transport with error %1

3593

Failed to create a new message port with error %1

3600

Failed to create an event queue with error %1

3601

Failed to load initial plugins with error %1

3602

Failed to unload initial plugin with error %1

3603

Failed to unload subsystems with error %2

3604

Failed to destroy system event queue with error %1

3605

Failed to stop transport with error %1

3606

Failed to stop system with error %1

3607

Failed to uninitialize system with error %1

3608

Failed to start system with error %1

3609

Failed to load plugin %1 with error %2

3610

Failed to initiate RPC for Remote Access Subsystem with error %1

3611

Failed to connect to the database. Error - %1 Increase the number


of processes available to the database.

3612

The server running Presentation Server failed to connect to the Data Store
%1. Invalid database user name or password. Please make sure they are
correct. If not, use DSMAINT CONFIG to change them.

3613

Failed to connect to the database with error. Error - %1 The ACCESS .mdb
file is missing.

3614

The server running Presentation Server failed to connect to the Data


Store. Error - %1 The database is down or there is a network failure.

3615

The server running Presentation Server failed to connect to the Data


Store. Error - %1 An unknown failure occurred while connecting to the
database.
Configuration error: Failed to read the farm name out of the registry on
a server configured to access the Data Store directly.

3616

Appendix C Error Codes

Message ID

30

Message Text

3617

Configuration error: Failed to get the farm name from the Data Store
proxy server with error %1. This server is configured to access the Data
Store indirectly. The server specified as the Data Store proxy is not
available. Verify that the Data Store proxy server is accessible and that
the IMA service is started on it.

3618

Configuration error: Failed to open IMA registry key.

3619

96 hours have passed since last successful connection to the Data Store.
This server will no longer accept connections until successful connection to
the Data Store is established.

3840

Unable to bind to group context in data store. Group consistency check


will not run. (Result: %1)

3841

Unable to locate groups in data store at DN %1. Group consistency


check will not run. (Result: %2)

3842

Group Consistency Check: Group at DN %1is missing the GroupMember


Attribute.

3843

Group Consistency Check: Group at DN %1 contained reference to


an unknown object with type %3 and UID %2.

3844

Group Consistency Check: Group at DN %3 contains an object with UID


%1 and type %2. This object is missing the %4 attribute.

3845

Group Consistency Check: Group at DN %3 contains an object with UID


%1 and type %2. This object is missing the value for the %4 attribute.

3872

Unable to bind to server contexts in data store. Server consistency


check will not run. (Result: %1)

3873

Server Consistency Check: Unable to locate host records in data store.


The server host record consistency check will not run. (Result: %1)

3874

Server Consistency Check: Unable to locate common server records in data


store. The common server consistency check will not run. (Result: %1)

3875

Server Consistency Check: Unable to locate server records in data store.


The server consistency check will not run. (Result: %1)

3876

Server Consistency Check: Host record for HostName %2 at DN %1


references a Common Server record that cannot be found in the data
store.
Server Consistency Check: Host record for HostName %2 at DN %1
references a Common Server record that has a HostName of %3.
This mismatch is an error.

3877

3878

Server Consistency Check: Host record for HostName %2 at DN %1


references a Common Server record that cannot be found in the data store.
(Result: %3)

30

Advanced Concepts
Guide
Message ID

Message Text

3879

Server Consistency Check: Common Server record for HostName %2 at DN


%1 references a Host record that cannot be found in the data store.

3880

Server Consistency Check: Common Server record for HostName %2 at DN


%1 has a HostID of %3. The corresponding Host record has a HostID of
%4. This mismatch is an error.

3881

Server Consistency Check: Common Server record for HostName %2 at DN


%1 references a Host record that cannot be found in the data store.
(Result:
%3)
Server Consistency Check: The Common Server record with HostName
%1 at DN %2 is invalid. There is no registered server product for this
record.
Server Consistency Check: The Common Server record with HostName
%1 at DN %2 is invalid. The corresponding Server record cannot be
accessed.
Server Consistency Check: The Server record with HostName %1 at DN
%2 is invalid. The associated Common Server UID is not set.

3882
3883
3884
3885
3886

Server Consistency Check: The Server record with HostName %1 at DN


%2 is invalid. The associated Common Server record cannot be
accessed.
Server Consistency Check: The Server record with HostName %1 at DN
%2 may be invalid. The Server record HostID of %3 does not match the
Common Server record HostID of %4.

3887

Server Consistency Check: The Server record with HostName %1 at DN


%2 is invalid. The associated Common Server record has a different
HostName (%3).

3888

Server Consistency Check: Unable to locate Load Manager for


MetaFrame XP(TM) Server entry for HostName %1. (Result: %2)

3889

Server Consistency Check: The Server record with HostName %1 at DN


%2 may be invalid. The Load Manager for MetaFrame XP(TM) Server
entry was not found.

3890

Server Consistency Check: The Server record with HostName %1 at DN


%2 is invalid. The associated Account Authority Server record was not
found.
Unable to bind to application contexts in data store. Application
consistency check will not run. (Result: %1)

3904
3905

Application Consistency Check: Unable to locate Common Application


records in the data store. Common application consistency check will
not run. (Result: %1)

3906

Application Consistency Check: Unable to locate Application records in


the data store. Application consistency check will not run. (Result: %1)

3907

Application Consistency Check: The Common Application record at DN %1


does not have a Friendly Name. (Result: %2)

Appendix C Error Codes

Message ID

30

Message Text

3908

Application Consistency Check: The Common Application record at DN %1


does not have a Browser Name. (Result: %2)

3909

Application Consistency Check: The Common Application record with


Friendly Name %1 at DN %2 does not have a specialized application
UID. (Result: %3)

3910

Application Consistency Check: The Common Application record with


Friendly Name %1 at DN %2 references an Application record that
cannot be accessed. (Result: %3)

3911

Application Consistency Check: The Common Application record with


Friendly Name %1 at DN %2 references an Application record. This
record does not have a Friendly Name. (Result: %3)

3912

Application Consistency Check: The Common Application record with


Friendly Name %1 at DN %2 references an Application record. This
record does not have a Browser Name. (Result: %3)

3913

Application Consistency Check: The Common Application record at DN %2


has a Friendly Name of %1. The corresponding Application record has a
Friendly Name of %3. This mismatch is an error.

3914

Application Consistency Check: The Common Application record at DN %2


has a Browser Name of %1. The corresponding Application record has a
Browser Name of %3. This mismatch is an error.

3915

Application Consistency Check: The Application record at DN %1 does not


have a Friendly Name. (Result: %2)

3916

Application Consistency Check: The Application record at DN %1 does not


have a Browser Name. (Result: %2)

3917

Application Consistency Check: The Application record with Friendly Name


%1 at DN %2 does not have a common application UID. (Result: %3)

3918

Application Consistency Check: The Application record with Friendly Name


%1 at DN %2 references a Common Application record (UID %3) that
cannot be accessed. (Result: %4)

3919

Application Consistency Check: The Application record with Friendly Name


%1 at DN %2 references a Common Application record. This record does
not have a Friendly Name. (Result: %3)

3920

Application Consistency Check: The Application record with Friendly Name


%1 at DN %2 references a Common Application record. This record does
not have a Browser Name. (Result: %3)

3921

Application Consistency Check: The Application record at DN %2 has a


Friendly Name of %1. The corresponding Common Application record
has a Friendly Name of %3. This mismatch is an error.

30

Advanced Concepts
Guide
Message ID

Message Text

3922

Application Consistency Check: The Application record at DN %2 has a


Browser Name of %1. The corresponding Common Application record
has a Browser Name of %3. This mismatch is an error.

3936

Common Application cleanup, deleting record at DN <%1>

3937

Application cleanup, deleting record at DN <%1>

3938

Server cleanup, deleting record at DN <%1>

3939

Common Server cleanup, deleting record at DN <%1>

3940

Server Host Record cleanup, deleting record at DN <%1>

3952

Unable to open Citrix Runtime registry key. Application terminated. (Status:


%1)

3953

Unable to read Neighborhood name from registry. Application terminated.


(Status: %1)

3954

Unable to initialize Data Store connection. This server must have a


direct connection to the data store. Application terminated. (Result: %1)

3956

Data Store Validation Utility. Version: %1

3957

Unable to initialize event log. Messages will be displayed on console only.

3958

%1 [ /Clean ] Perform validation checks on a Farm's data store. Results will


be displayed on the console and also entered into the Event Log. The
/Clean option will delete records that are inconsistent. The data store
should be backed up prior to using the /Clean option.

3959

All consistency checks were successful.

3960

Some consistency checks were unsuccessful. Results below indicate the


number of errors or -1 for test not run: Server Errors = %1, Application
Errors
= %2, Group Errors = %3.
The Data Collector is out of memory, and the Dynamic Store data might
be out of sync. Please elect a new Data Collector and make sure you
have enough memory on the new Data Collector.

3961

3968

Buffer overrun detected.

3969

Error occured during uninstall, some objects may have not been
removed from the data store properly. subsystem id = %1, error = %2.
Please verify data store consistency.

Appendix C Error Codes

Isolation Environment Warning and Error Messages


Isolation Environment Warning Messages
The following warning messages refer to isolation environment events and are
logged to the application event log:
Event Log Entry

Description

An isolated application in AIE %1 attempted


to install service %2. The service will not be
available.

This message is generated in the application


event log for a source CtxSbxAppMsg if an
error occurred because an application
attempted to install a service.

An isolated application in AIE %1 attempted


to delete a service. The service was not
deleted.

This message is generated in the


application event log for a source
CtxSbxAppMsg if an error occurred when an
application attempted to delete a service.

The file %2 was copied to %3 but the


short filename was not preserved.

This message is generated in the application


event log for a source CtxSbx if an error
occurred when an application attempts to do
something with short filenames.

Isolated Application Launch Failure Error Messages


Error Code

Windows Error Code

Probable Cause

0x00000002

ERROR_FILE_NOT_FOUND

Executable file not found.

0x00000003

ERROR_PATH_NOT_FOUND

Executable path not found.

0x00000005

ERROR_ACCESS_DENIED

Access denied.

0x00000008

ERROR_NOT_ENOUGH_MEM
ORY

Need more RAM.

0x00000032

ERROR_NOT_SUPPORTED

Not licensed/enabled for


isolation environments.

0x00000057

ERROR_INVALID_PARAMETER

Not enough command


line arguments.

0x0000006E

ERROR_OPEN_FAILED

Likely related to failure to read


AIE definition from data store,
licensing component failure.

30

30

Advanced Concepts
Guide

AIERUN Error Messages


Message ID

Message Text

IDS_AIE_NOT_FOUND

Specified isolation environment was not found (0x%08X).

IDS_EXECUTION_FAILED

Application execution failed (0x%08X).

IDS_INVALID_PARAMETER

An isolation environment or application was not specified.

IDS_AIE_NO_DRIVER

The isolation environment driver (CTXSBX.SYS) is not


present or loaded.

IDS_AIE_NOT_AVAILABLE

Application isolation is either not installed or disabled on


the server (0x%08x).

AIESETUP Error Messages


Message ID

Message Text

IDS_NOT_CITRIX_ADMIN

You must be a Citrix administrator to run this application.

IDS_AIE_NOT_FOUND

Specified isolation environment was not found (0x%08X).

IDS_INSTALL_FAILED

Application installation failed (0x%08X).

IDS_DISCOVER_FAILED

Application discovery failed (0x%08X).

IDS_INVALID_PARAMETER

An isolation environment or application was not specified.

IDS_AIE_NO_DRIVER

The isolation environment driver (CTXSBX.SYS) is not


present or loaded.

IDS_NO_APPLICATION

No application was specified.

IDS_AIE_NOT_AVAILABLE

Application isolation is either not installed or disabled on


the server (0x%08x).

APPENDIX D

Registered Citrix
Ports
The following table contains the default registered Citrix ports.
Name

Number

Protocol

Description

ica

1494

TCP

ICA

ica

1494

UDP

<not used>

ica

0x85BB

IPX

ICA

ica

0x9010

SPX

ICA

icabrowser

1604

TCP

<not used>

icabrowser

1604

UDP

ICA Browser

icabrowser

0x85BA

IPX

ICA Browser

citrixima

2512

TCP

IMA (server to server)

citrixima

2512

UDP

<not used>

citrixadmin

2513

TCP

IMA (Presentation Server Console to server)

citrixadmin

2513

UDP

<not used>

citriximaclient

2598

TCP

Common Gateway Protocol (Session Reliability)

citriximaclient

2598

UDP

<not used>

citrix-rtmp

2897

TCP

rtmp (Control) Video Frame

citrix-rtmp

2897

UDP

rtmp (Streaming Data) Video Frame

Citrix
Systems

3845

MIB

Private Enterprise Number. Used for SNMP MIB


Object ID and Active Directory Schema Object
Ids (OID).

Notes: The Default Citrix License Server port is 27000. The Access Suite Console uses
MSRPC on port 135 for communications.

33
PENDIX

Advanced Concepts
Guide