Deploying a Pre-Configured Citrix Client using Active Directory

This article will show you how to create a pre-configured Citrix Client and leverage Active Directory to deploy the client as well as overcome some of the idiosyncrasies found in the Citrix Client packager.

This article will show you how to create a pre-configured Citrix Client and leverage Active Directory to deploy the client. You may ask, “Why would I want to use Active Directory to deploy the client. Doesn’t Citrix offer the Auto Client Update?” The answer is yes, Citrix does provide an auto client update feature, but there are limitations such as:

If a workstation already has a Citrix client that was installed from an .msi package, then you cannot use the Auto Client Update feature.

From page 90 of the Citrix client Administrator’s Guide:
“Important You cannot automatically update previous versions of the client installed with Windows Installer (.msi) packages. You must redeploy a client installer package when a new version of the client is released.”

Also, refer to Citrix Article CTX108584.

The Auto Client Update feature also adds steps to the logon process since it has to check to see if the workstation has an up-to-date client. This can cause longer login times and user frustration. In fact, I recommend you turn off the Auto Client Update feature via a Citrix policy:

Getting Started

Tools Needed:

  • Citrix Presentation Server Client Packager
  • ORCA to modify the MSI file (today’s trivia, ORCA stands for One Really Cool Application)
  • Citrix Transform File to enable Single Sign On in the MSI file (optional)

The first thing you will need to do is get the Citrix Presentation Server Client Packager. You can download the latest Citrix Client Packager at http://www.citrix.com/download. The Citrix Client Packager contains the Citrix Program Neighborhood client, the Citrix Web client, and the Citrix Program Neighborhood Agent client.

Quote from Citrix:

You can customize the client packager to deploy and maintain any number and combination of clients network-wide. Based on Windows Installer technology (msi), the client packager lets you install, uninstall, modify, and repair clients as well as perform controlled client upgrades. An easy-to-use wizard guides you through the configuration step by step.

Create an Admin Install of the Citrix Client Packager

This is the part where you pre-configure the client(s).

Run msiexec /a Ica32Pkg.msi to create an administrative install of the package.
Note: this doesn’t actually install the client; it just creates the customized client installation files.


Select the “Uncompressed” option if you want to make modifications to the files (such as branding the client).

For this exercise, I have chosen not to install the full Program Neighborhood Client.

Important: If you elect to use the Local Name and Password, you will need to modify the MSI file using a transform (MST) file in order for this to work. More on this later.

In this example, I removed all the dialog boxes. It is not necessary to show any dialogs since we are going to push this client via Active Directory.

Making Post Setup Modifications

There are a couple of common post setup modifications that need to be made for the options I chose in this exercise. The first modification involves a bug in the client packager. If you specify not to install the Program Neighborhood client (as I chose not to in this exercise), it will still be installed to the workstation anyway as “Install on Demand” (see Citrix Article CTX105642).

So, to get around this, you will need to modify the MSI file by following these steps:

  • Launch ORCA.
  • Open the admin install MSI file (Ica32Pkg.msi) created earlier.
  • Select the Condition table.
  • Change the condition to “Not Installed” for the Program Neighborhood client.

There is another “feature” in the client packager that puts an icon for Program Neighborhood on the workstation desktop even if you chose not to install Program Neighborhood (see Citrix Article CTX108212)

So, once again, it’s ORCA to the rescue:

  • Launch ORCA.
  • Open the admin install MSI file (Ica32Pkg.msi) created earlier.
  • Select the Shortcut table.
  • Right click the row with “DesktopFolder…” in the Directory column and select Drop Row.

Enable Single Sign On for Active Directory Deployment

There is yet another “feature” in the client that disables single sign on in the client when deploying via Active Directory (see Citrix article CTX103439). As the article states, you will need to apply a transform (MST) in order for Single Sign On to work.

  • Download slfregfix.mst from http://support.citrix.com/article/entry.jspa?entryID=3936
  • Launch ORCA
  • Open the Ica32Pkg.msi file created above.
  • Select Transform -> Apply Transform…
  • Browse to slfregfix.mst.
  • Click on File -> Save Transformed As… and save the package as a different name (such as mod_Ica32Pkg.msi).


Deploy the Package with Active Directory

Finally, after all the blood sweat and tears to create the admin install client package, you can deploy the package with Active Directory. The question you must answer here is do you want to assign or publish this package? Also, if you assign the package, do you want to assign it to computer or user objects? In this exercise, I assigned the package to computer objects. (For more information about assigning and publishing packages via a GPO with Active Directory, check out Active Directory® for Microsoft® Windows® Server 2003 Technical Reference)

<disclaimer> I strongly suggest you toughly test this in a separate test environment if you have one. If you do not have a separate test environment, at least create a test OU in your Active Directory to try this out.</disclaimer>

  • Open up Active Directory Users and Computers.
  • Right click on the OU you want to use to host the GPO to deploy the package and select Properties
  • Select the Group Policy tab.
  • Click edit to edit an existing Group Policy or New to create a new Group Policy. (Again, I suggest creating a new GPO for testing purposes).
  • Browse to Computer Configuration -> Software Settings -> Software installation.
  • Right click Software installation and select New -> Package.
  • Browse to the package created above.
  • Select Assigned on the Deploy Software Dialog.

Now, any computer object you move into this OU will automatically have the pre-configured Citrix ICA client installed upon logon (I suggest you only try moving a few computer objects into the OU for testing purposes). 

Be careful about placement of the Citrix client install files and network bandwidth. You may want to have different GPO’s specifying different install points based on location. Here’s what Microsoft has to say:

From Active Directory® for Microsoft® Windows® Server 2003 Technical Reference:

One of the most difficult aspects of managing software distribution using group policies is network utilization management. If you assign a large multi-megabyte application to a large group of users and all of those users install the application at the same time, the installation might take hours because of the significant increase in the volume of network traffic. There are a number of options for managing the network bandwidth. One option is to assign applications to computers and ask users to reboot the computers at the end of the day. You can also force a reboot of the workstation by using the GPUpdate command. If you apply this command to only a few workstations at a time, the impact on the network can be minimized.

Another option is to assign applications to small groups of users at one time. In most cases, you might also want to avoid assigning applications that will be completely installed when the user logs on. If you advertise an application but allow the user to initiate the installation, you will be able to at least spread out the software installation over some time. Although none of these options is ideal, you can use them to at least manage the bandwidth to some extent. Another way to manage network utilization if you have multiple sites is to use the Distributed File System (DFS). With DFS, you can create a logical directory structure that is independent of where the files are actually stored on the network. For example, you might create a DFS root named \\server1\softinst and then create subdirectories for all applications underneath that share point. With DFS, you can locate the subdirectories on multiple servers and configure multiple physical links to the same logical directories. If you use Active Directory-integrated DFS, you can even configure automatic replication of the folder contents between copies of the same directory. DFS is a site-aware application, which means that if you have multiple sites, the client computers will always connect to a copy of a DFS folder in their own site rather than cross a wide area network (WAN) link to access the folder on another site.

It is difficult to predict exactly what the effect of a network installation will be. One of the advantages of using group policies to install software is that you can easily perform a test to see what the effect is likely to be. For example, you can configure a GPO that includes the software package but make sure that GPO is not linked to any OU. You can then create a temporary OU, add a few user or computer accounts to the OU, and link the GPO to the OU. This configuration can be used to test how long it takes to install the applications to a small group of users. You can also pilot the software distribution by linking the GPO to a production OU but using group filtering to limit which users or computers will apply the GPO.

Regardless of the efforts you take to minimize the effect on the network, deploying a large application to a large number of users will always have some impact on the network. Since this is this case, you will probably have to plan on completing the installation over several days.

Conclusion

This article showed you how to make a pre-configured admin install of the Citrix ICA Client and the idiosyncrasies involved to make certain functionalities work. Also, we used Active Directory and Group Policy Objects to deploy this customized package. Note: you can use any deployment method you like to deliver the final MSI (such as SMS), but if you do not have SMS (or another deployment device) available in your environment, this method works well.

The Epoch Information Center is now online

Use the Epoch Information Center to get epoch offsets from Date/Time values, or get Date/Time values from an epoch offset. This information is useful for things like manipulating the Terminal Server shadow registry.

The what is now online? The Epoch Information Center. Okay, so what is an epoch and why should I care in a Terminal Server environment?

What is an epoch?
Epoch has many definitions. The definition we’re interested in is the UNIX definition. The UNIX definition specifies that the epoch is January 1, 1970 at midnight (UTC) (a.k.a. 01-01-1970 00:00:00). This Date/Time value can be considered “Time 0”. The epoch is used as a beacon to measure time in many computer programs (such as the Windows registry). Time can be measured as the number of seconds since the epoch or before the epoch (returning a positive or negative offset). This also allows you to compare Date/Time values.

Why should I care about an epoch in a Terminal Server environment?
There is one main reason you should care about the epoch offset in a Terminal Server environment. That reason is the shadow registry (HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Terminal Server\Install\Software). Brian Madden has written an excellent article on the shadow registry key and how it’s used. I’ve used his article and the Epoch Information Center to manipulate the shadow registry’s “LatestRegistryKey” value in a couple of scenarios.

Usage Scenarios

Scenario 1 (setting the LatestRegistryKey back in time):
The first usage scenario is addressed in Brian Madden’s article. This scenario involves setting the “LatestRegistryKey” value back in time.

Quote from Brian Madden’s article:

. . . Imagine that you have multiple Terminal Servers or Citrix servers that are all running the same application, such as Microsoft Office. If you’re like most companies, you probably installed Office on those servers a several months or even years ago. Since Office was originally installed via a user session operating in install mode, the server’s shadow key was created and timestamped with the original install time. Any users who did not have the appropriate Office settings in their own personal HKCU key received them when they logged on to the server for the first time.

Now, fast forward to today. What happens if you want to add more capacity to your server farm? Most likely you’d build a few more servers, install Office on them, and load-balance them with your existing servers.

Can you see the problem here? The timestamp on the shadow key area of the new Terminal Servers will be current, and in fact much newer than each user’s individual HKCU last update timestamp. Therefore, upon logging on to one of the new servers, userinit.exe will start comparing the key-by-key timestamps of all the HCKU\Software keys to the server’s shadow area software keys. Since the server just got a fresh install of Microsoft Office, those timestamps will be much newer than any of the user’s personalized settings in their own HKCU. The result? Mass deletion of all the Microsoft Office-specific keys in the user’s HKCU\Software hive.

From the user’s standpoint, it will appear as if all of their Office settings reverted back to the defaults, all because they were randomly load-balanced to a new Terminal Server. . .

Brian suggests a couple of solutions to address this exact problem. Another solution you could use is go to the Epoch Information Center, grab an epoch offset earlier than the other existing servers in the farm, and plug that offset in to the “LatestRegistryKey” value.  See below:


Note: be sure to select decimal when inserting the new value.

Scenario 2 (setting the LatestRegistryKey to the current time):
Imagine that you wanted to add a registry key to each user’s HKEY_CURRENT_USER\Software registry hive. You could write a logon script to do it, or you could add the registry keys to the shadow registry, use the Epoch Information Center to get the current (or future) epoch offset, and plug the epoch offset into the “LatestRegistryKey” (thus emulating the server install mode). The advantage of doing it without a login script is that you don’t have to come up with some logic in your script to figure out if this setting has already been applied, Windows takes care of that part for you.

Anyway, I hope you find the Epoch Information Center useful. The reason I put it online is because I’ve needed to get an epoch offset in the past and I thought some of you might find it useful as well.

How to get the Username AND Password of a user in Citrix Web Interface 4.0

Have you ever wanted to get the username and password from an authenticated user in Citrix Web Interface? This article tells you exactly how to do just that.

Have you ever wanted to get the username and password from an authenticated user in Citrix Web Interface? I was once tasked to grab the username and password of the authenticated Citrix Web Interface user and pass those credentials along to a custom Lotus Notes web application. Using the Web Interface SDK (available at http://apps.citrix.com/cdn/sdk/webinterface_sdk.asp), I was able to get just what I needed. Here is how it’s done:

The down and dirty explanation
The first thing you’ll need to understand is the object model Citrix uses in Web Interface. Citrix provides you with a lot of base classes you can use to programmatically get the information you need. All these classes are documented in the SDK. The class we’re interested in for this example is the AccessToken class. The AccessToken class allows you to get the user’s username (but not the user’s password). To get the user’s password, you’ll need to use the PasswordBasedToken Interface. The AccessToken class implements the PasswordBasedToken interface which exposes a method called getPassword(). This method returns a string that is the user’s password. Check out the code below:

The code
<%
PasswordBasedToken pbt = null;
AccessToken ac = authGetPrimaryAccessToken();
pbt = (PasswordBasedToken)ac;

string strUsername = ac.getShortUserName();
string strPassword = pbt.getPassword();
%>

That was easy (almost too easy).
Notice the use of the authGetPrimaryAccessToken(). This is a function that Citrix gives you to get the primary access token holding the credentials the user used to authenticate to Web Interface. This function can be found at path_to_your_wi_server\site\serverscripts\authentication.cs and path_to_your_wi_server\auth\serverscripts\authentication.cs

The code placement
Ok, now you know the down and dirty explanation and the code used to get the username and password. So, where do you put this code? One place you could use is the layout.ascx file located at path_to_your_wi_server\site\include. Layout.ascx is a user control that constructs the look and feel of the Web interface page after authentication (see this article for more information). Just place the code before the tag. Now you can use the variables strUsername and strPassword wherever you like in the code.

Putting it all together
Here is the final product

Layout.ascx

<%

PasswordBasedToken pbt = null;
AccessToken ac = authGetPrimaryAccessToken();
pbt = (PasswordBasedToken)ac;
string strUsername = ac.getShortUserName();
string strPassword = pbt.getPassword();
%>

<html>
<head>
  <meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8">
  <meta NAME="ROBOTS" CONTENT="NOINDEX, NOFOLLOW, NOARCHIVE">
  <title><%=PageTitle%></title>
. . .

I hope this helps some of you out there trying to bring together disparate systems.

Visio Diagram of the Citrix Resource Manager Summary Database

Microsoft Visio drawing of the Citrix Resource Manager Summary Database.

Using the techniques explained in this article, I created the following graphical representations of the Citrix Resource Manager Summary Database.

Microsoft Visio Drawing of the Citrix Resource Manager Summary Database
Don’t have Microsoft Visio? No problem, just download a picture of the drawing here:
JPEG of the Citrix Resource Manager Summary Database (1770 x 1212)(800 x 600)

-OR-
Use the interactive pan and zoom web page here: (Note: requires IE 5.0 or above).
Interactive Pan and Zoom web page for the Citrix Resource Manager Summary Database

Branding the Citrix ICA Client

Using the techniques described in this article, it is possible to put your own custom logos on the Citrix ICA client during application launch.

Using the techniques described in this article, it is possible to put your own custom logos on the client during application launch. See screen shots below:

Before After
Disclaimer: This article is for informational purposes only. Be sure to reference your license agreement before implementing this in a production environment.
Tools Needed:

  • Citrix Presentation Server Client Packager
  • Resource Hacker (free)
  • Graphics Editing Software (Microsoft Paint is sufficient)

Step 1: Export Existing Citrix MetaFrame ImageThis step is performed to export the existing resource image so you can replace the image with a new one with identical dimensions.

Follow these steps to complete this task:

  • Launch Resource Hacker and open statuiUI.dll. Note: statuiUI.dll is located in C:\Program Files\Citrix\ICA Client\resource\en for an English installation.
  • Navigate to Bitmap -> 101 -> 1033 (Note: since I am using the English version of the client, 1033 is my locale ID. Your locale ID may differ)
  • Right click 1033 and select “Save [Bitmap : 101 : 1033]…” Save this bitmap to any desired location

Step 2: Modify the Exported Image

Using your preferred graphics editor, open up the bitmap exported in step 1.
Modify the image as desired and save as a different name if desired.

Step 3: Replace the Resource in statuiUI.dll

  • Make a backup of statuiUI.dll
  • Launch Resource Hacker
  • Navigate to Bitmap -> 101 -> 1033
  • Right click 1033 and select “Replace Resource…”
  • Click the button labeled “Open file with new bitmap…”
  • Navigate to the bitmap created in step 2.
  • Click the Replace button.
  • Save the new statuiUI.dll file.


You will now have a branded client when launching applications. Go ahead and try it out.

You will probably notice that about half way through the application launch process, the picture you created in this step reverts back to the original Citrix Metaframe bitmap if you are running Presentation Server 3.0 or above. Why does this happen? Read on.

Citrix introduced an improved user logon process in Presentation Server 3.0 and above that included a progress bar indicating connection status throughout the entire application launch process. Basically, when you launch a published application, the process starts on the client computer setting up the connection to the server. Then, the process gets handed over to the server to complete the application launch (logon to the server, load the profile, etc). Prior to Presentation Server 3.0, when the launch process got handed over to the server, the Windows logon dialog boxes were displayed. This created kind of a disjointed look and feel for the end user. In Presentation Server 3.0 and above, the Windows logon dialog boxes were “replaced” with new dialogs that look like the local client dialog. This gave the end user a smooth looking look and feel throughout the entire launch process.

So, how do you stop this seemingly regression from happening? Move on to step 4.


Step 4: Replace statuiUI.dll on the Server.

The “replacement” dialog box for the server piece of the launch process is located at system_drive:\Program Files\Citrix\System32\resource\en\statuiUI.dll. Simply make a backup of this file and replace it with the statuiUI.dll file created in step 3.

Note: this file may be locked if other people are logged in to the server.

Now, try launching an application again and you will notice that the branding stays throughout the entire launch process.

Another file that is fun to play with is the login screen for the PN Agent. That resource is C:\Program Files\Citrix\ICA Client\resource\en\pnagenUI.dll. Have fun!

Using Microsoft Visio to Reverse Engineer a Database

This article steps you through using Microsoft Visio’s Reverse Engineer feature to reverse engineer relational databases like Citrix’s Resource Manager Summary Database.

There are times when you want to get a graphical representation of a relational database (say, for instance, the Citrix Resource Manager Summary Database). You could wade through a DBMS management console (such as the Microsoft’s Enterprise Manager for SQL) to get a list of all the tables and primary key/foreign key relationships, then draw out these tables in some kind of graphics software. Or, you could use Microsoft Visio to do all this work for you. All you need is an ODBC connection and Microsoft Visio Professional.

  • Open Microsoft Visio Professional and create a new Database Model Diagram.
  • Click on the Database menu and select Reverse Engineer to start the Reverse Engineer Wizard.
  • Select an existing data source (DSN) or create a new one.
  • Select the information you want to add to the drawing. (I chose just the tables, primary keys, and foreign keys in this example).
  • Select the checkboxes for the tables (and views, if any) that you want to graph.
  • Select whether you want Visio to add the shapes to the drawing. If you don’t let the wizard add the shapes to the page now, you will be able to drag and drop the shapes onto the drawing after the wizard finishes extracting the information.
  • Review the selections made and click Finish.

I used the steps in the example demonstrated above to extract the Citrix Resource Manager Summary Database schema. As you can see from the screen shot below, Visio did a great job of extracting the information, but you’ll have to do quite a bit of moving shapes around to get a better picture of the relationships. Fortunately, I’ve already done this for you, and you can download the drawing in the Downloads section here

Click for a larger version
(Click for a larger version) 

One last really cool thing. You can also use Visio’s database features to generate databases from a drawing as well as update databases from a drawing. I often reverse engineer a database, make changes to the drawing, and let Visio make the changes to the database for me. That way my documentation and database structure stay in synch.