Leveraging NFuse with the PN Agent - Citrix MetaFrame XP

As you are now aware, the real advantage of NFuse is not the fact that it "uses the web," but the fact that all client configuration is done centrally.

As you are now aware, the real advantage of NFuse is not the fact that it "uses the web," but the fact that all client configuration is done centrally. What this means is that if you need to make any changes to your users' configuration, you can make the changes to your NFuse web server. Your client devices instantly begin using those changes the next time they connect to your NFuse website.

Unfortunately, NFuse has some drawbacks. One of these is the simple fact that users must access a web page to get their applications. This can be strange for users who are used to accessing all of their applications via their Start Menu or Windows desktop.

Start Menu and Windows desktop integration is one of the nice features of the full 32-bit ICA client. As an administrator, you can use this client to place application icons directly in the Start Menus or on the desktops of your users' workstations. While this is very easy to use, it has one major drawback. Because the full ICA client is used, any changes that you make to your backend cause you to have to update the pn.ini and appserv.ini files on every single client workstation. Plus, it's easy for users to foul things up because Program Neighborhood gives them so many configuration options that are easy to access.

To get the best of both worlds, Citrix introduced the Program Neighborhood Agent as part of Feature Release 1 for MetaFrame XP. (It remains unchanged in Feature Release 2, other than the ability to support the inherent changes introduced directly by FR-2.) The Program Neighborhood Agent allows you to place application and content icons on directly your users' desktops, Start Menus, and system trays.

Advantages of the Program Neighborhood Agent

  • All client configuration is done centrally, allowing you to easily change settings.
  • No local client interface is installed. Users access MetaFrame XP applications simply by clicking on shortcuts.

Disadvantages of the Program Neighborhood Agent

  • It only works on 32-bit Windows clients.

NFuse 1.6 or newer is used as the logical backend for the PN Agent. The PN Agent is like NFuse without the web.

Understanding Program Neighborhood Agent Files

In order to support Program Neighborhood Agent (PNA) functionality, the NFuse 1.7 setup program copies the needed files into the /Citrix/PNAgent web directory on your NFuse web server. The entire Program Neighborhood Agent server system is comprised of only eight files:

  • Enum.asp This file is accessed by Program Neighborhood Agent clients to provide them with a list of published applications and content that they can access. This file works in the same way as the applist.asp file in a regular NFuse Classic website, except that instead of creating an HTML web page, it sends the results to the client agent. A similar file called smartcard_enum.asp is used for smart card application enumeration.
  • Launch.asp This file is invoked by PNA clients when they launch an application or content. This file works in the same way as launch.asp in regular NFuse Classic websites. A similar file called smartcard_launch.asp is used for smart card application launching.
  • Template.ica This template ICA file works just like the template ICA files in any NFuse website. If there are settings that you need to apply at the ICA file level for your PNA users, then you can make them here. Similar to NFuse Classic environments, there is also a guest_template.ica file for anonymous users.
  • Esninclude.asp This file contains logic that is invoked when the PN Agent is used to login to Enterprise Services for NFuse environments.
  • Config.xml This file contains all of the configuration for PNA clients. This file works in a similar fashion to the NFuse.conf file in a regular NFuse website, although the layout of the config.xml file is different because it is written in pure XML. Because this file controls everything, it's important that you understand it if you want to be able to use NFuse's Program Neighborhood Agent. Let's take a look at this file now.

Configuring PN Agent with the Config.xml File

The settings that the Program Neighborhood Agent uses are centrally controlled by the config.xml located in the /Citrix/PNAgent web directory.

Understanding XML Files

Since all PN Agent configuration is done via the config.xml file, and since the config.xml file is a standard XML file, it's probably worth spending a minute or two looking at what an XML file is.

An XML file is a type of document. It is based on a "markup language." While HTML documents are based on the "hypertext" markup language, XML documents are based on an "extensible" markup language (XML = eXtensible Markup Language). From a structural standpoint, XML documents are like HTML documents. The only difference is that there aren't any predefined tags in XML. That's why it's called "extensible." Since no tags are predefined, it can be extended in any way.

Think about how the HTML source code would look for this document:

Hello. My name is Brian.

The HTML code would look like this:

<p><b>Hello.</b> My name is <i>Brian.</i></p>

Within the international HTML standard, the "p" tag is reserved for a paragraph, the "b" tag is reserved for bold, and the "i" tag is reserved for italics.

Within an XML document, no tags are reserved. XML tags can be anything, and it's up to the application to determine how they're used. For example, an XML document might look like this:


Notice that each XML tag consists of an opening tag and a closing tag. Similar to HTML, the closing tag must start with a slash ("/"). In this document, the "mylistofpeople" tag is called the "root" tag, since it surrounds the entire document.

Some of the lines in this file have been indented purely for ease of viewing by human readers. That XML document could have just as easily looked like this:

Madden</lastname><title>author</title><website>www.bri anmadden.com

Since XML is extensible, you can use it however you want. For example, you can modify the previous example so that it contains two people:


Notice that we've added a tag called "person" that surrounds each set of tags for each person. By doing this, we've "extended" the XML document. This document now infers that there is a tag called "person," and that tag consists of "firstname," "lastname," "title," and "website" tags.

You can edit any XML file with a standard text editor. (If you double-click an XML file in Windows, it will open in a cool, interactive way with Internet Explorer.) There are also dozens of freeware and shareware XML file editors on www.download.com.

Now that you understand the basics of XML, let's examine PN Agent's config.xml file. Rather than display the entire file at once, we're going to break it down into several sections and review each section separately.

Config.xml Header Information

The config.xml file opens with some standard XML header lines:

<?xml version="1.0" encoding="UTF-8"?>
<PNAgent_Configuration xmlns:xsi="https://www.w3.org/

The first line specifies the XML standard that this file follows (XML 1.0 in this case), and the second line is the "root" tag ("PNAgent_Configuration").

Folder Options

The first tag after the header information is "FolderDisplay." The settings in this tag allow you to specify whether you want to display icons for MetaFrame XP applications and content in the users' Start menu, system tray, or on their Windows desktop.

        <Enabled modifiable="true" forcedefault="false">true</Enabled>
        <RootFolder root="programs" modifiable="true" forcedefault="false"/>

Since this is the first config.xml tag that we're looking at, let's take a detailed looked at how it is structured.

The first section in the "FolderDisplay" tag is "StartMenuDisplay." (We call this the "StartMenuDisplay" section since it opens with a <StartMenuDisplay> tag and ends with a </StartMenuDisplay> tag.

Within the "StartMenuDisplay" section, there are two tags: <Enabled> and <RootFolder>. The opening and closing "Enabled" tags surround its value: "true," in this case. However, you'll notice that there is some extra data shoved in the "Enabled" opening tag. A standard opening tag would look like this:


But in this case, the "Enabled" opening tag actually looks like this:

<Enabled modifiable="true" forcedefault="false">

In this case, the "Enabled" tag has extra attributes that have been applied to it. An attribute called "modifiable" has been added with a value of "true" and a "forcedefault" attribute has been added with a value of "false."

Take another look at the next tag:

<RootFolder root="programs" modifiable="true" forcedefault="false"/>

At first glance, it appears that this tag doesn't have a closing tag to go with it. (You would expect to see a </RootFolder> closing tag. In this case, the "RootFolder" tag doesn't need to surround any data, so the people who wrote the XML file simply stuck the "/" in the end of tag right before the closing ">."

With XML, you instead of specifying <tagname> and </tagname> opening and closing pairs, you can use the single tag (i.e. <tagname/>) shortcut if you don't need a pair of tags to surround some data.

Now that you understand the structure of the tags in the "StartMenuDisplay" section of the config.xml file, let's decipher what the values actually mean.

The "Enabled" tag in the "StartMenuDisplay" section is set to "true," which causes published applications to be automatically added to your users' Start menus. If you do not want any MetaFrame XP application icons to show up in your users' Start menus, you would change the value between the opening and closing "Enabled" tags to "false." A setting of "false" would look like this:

<Enabled modifiable="true" forcedefault="false">false</Enabled>

Remember the "modifiable" and "forcedefault" attributes that have been shoved inside the opening <Enabled> tag? These two attributes refer to some of the PN Agent options that your users can edit via the properties screen of their local PN Agent software.

As you look through the config.xml file, you'll notice that many tags have "modifiable" and "forcedefault" attribute options. Each of these can be set to either "true" or "false." If "modifiable" is set to "true," users will be able to change the particular setting specified by that tag. If "forcedefault" is set to true, then the settings will be changed back to the default settings each time the Program Neighborhood Agent is started on the client. Usually, you set one of these to true and the other to false. In the "StartMenuDisplay" tag, we are allowing our users to be able to change this setting if they want to (modifiable="true") and we are not forcing our users to take our default settings when their systems are reset (forcedefault="false").

Now we can take a look at the next tag: "RootFolder." This tag allows you to specify which folder (in the user's Start menu) your Program Neighborhood Agent published application icons will appear in. As you can see, in this example, the folder is set to "programs." You can change this folder to anything that you want. Notice again that the "modifiable" and "forcedefault" attributes are present, allowing you to specify whether you want users to be able to change this option and whether the system should force it to be the setting you specify.

Before we move on to the next section, notice that the "StartMenuDisplay" section is closed out with the </StartMenuDisplay> closing tag. There is no "FolderDisplay" closing tag yet because the next section ("DesktopDisplay") is also part of the "FolderDisplay" section. Let's take a look at that "DesktopDisplay" section now:

    <Enabled modifiable="true"
        <Name modifiable="true"
forcedefault="false">My Program Neighborhood
        <Location modifiable="true"

The "DesktopDisplay" section allows you to place a folder on the user's desktop that contains icons to their published applications. Like the other settings, the "enabled" tag can be set to "true" or "false" to turn that folder on or off.

The "Name" tag under the "Icon" section allows you to change the name of that folder. As you can see, the default setting of "My Program Neighborhood Applications" is pretty lame, and probably something that you'll want to change.

You should set the "Name" tag's "modifiable" attribute to "false." If you don't, your users will change the name of the folder and then forget that they changed it. Then they'll call you and you'll have to go to their desk to change it back.

The Location element allows you to specify a URL location to the icon that is used for the folder on the desktop. By default, this element does not exist in the config.xml file, and the default Program Neighborhood icon is used.

        <Enabled modifiable="true"

The next section, "SystemTrayMenuDisplay," allows you to place a little Program Neighborhood Agent icon in your users' system trays that they can use to access their published applications and content.

Notice that because this is the end of the Folder Display section, there is a final </FolderDisplay> tag that closes out the section.

Desktop Integration

The Desktop Integration section of the config.xml file is shown below:


You shouldn't have to change any of the settings in this section. In fact, Citrix specifically insists that you don't. Supposedly, this section is for features that haven't yet been added to PN Agent.

Configuration File

The configuration file section allows you to specify the URL of the config.xml file your clients will use for all their settings. By changing this, you can migrate users to different NFuse servers.

    <Location modifiable="true" forcedefault="false"

With the "Location" section, you can specify the URL location of the XML file that clients will use to access their PNA settings. This is something that you should definitely NOT let users change, by setting the modifiable attribute to "false." One thing that's interesting about this is that if you change the location, but you have "forcedefault" set to "true," it's possible that your users will never get the default again. This is because if you change the location and the users connect to the new location, they will use the settings from the XML file in the new location instead of this XML file.

The "Refresh" tag allows you to specify whether you want this configuration data to refresh periodically. It's important to note that this refresh does not control the available applications or content refresh, it controls the refresh of client agent settings from this config.xml file. You can control the time between refreshes with the "Period" tag, specified in hours.


The Request section of config.xml allows you to specify where clients should look for published application data and how often they should refresh their information.

    <Location replaceServerLocation="true">http://
modifiable="true" forcedefault="false" >true</
            <OnResourceRequest modifiable="true"
            <Poll modifiable="true"

This "Enumeration" tag lets you specify where and how the application list is refreshed. By default, the application enumeration is performed by the enum.asp file which is located in the same directory is the config.xml file. Smartcard_enum.asp is used when your users authenticate with smart cards. You can change the URL for that file with the "Location" tags.

The "OnApplicationStart" tag refreshes the list only when the Program Neighborhood Agent is started. "OnResourceRequest" refreshes the application list whenever an ICA session is started or published content is accessed. If you enable the "poll" tag, the application list will be refreshed after the number of hours in the "Period" tag elapses.

    <Location replaceServerLocation="true">http://
    <Location replaceServerLocation="true">https://

The "Resource" tag points the PNA client to the file that is used to launch ICA sessions or content. By default, this tag points to launch.asp, located in the same folder as the other PNA NFuse files.


The Logon section of the config.xml file contains settings that affect how users log on.


There are several values that you can place into the "LogonMethod" tags, depending on how you want users to authenticate to their PNA clients. As you can see in the example, you can have multiple "LogonMethod" tags to support different logon options.

A value of "sson" will use the user's single sign-on credentials. A value of "prompt" will prompt the user for their credentials. Adding "smartcard_" to the front of these to logon types enables them for use with smartcards.

You can also set the "LogonMethod" tag to "anonymous" for use when you want to allow users to log onto anonymous applications.

If your users need to authenticate to an NDS tree, you can set the "SupportNDS" element to "true." When you do this, specify the default NDS tree in the "DefaultTree" tag. (Remember that since this tag is written as a single tag with the trailing "/," you'll need to write out the full tag set to specify the tree. Your tag will then look like this: <DefaultTree>yourtree</DefaultTree>.

User Interface

The User Interface section of config.xml allows you to specify what components of the PN Agent client are available for users to view or edit.


For each of these settings, a value of "false" means that the properties dialog box will not show up for PN Agent clients. The "ServerSettings" tag is associated with the "Server" tab in the PN Agent Properties box. The "FolderDisplaySettings" tag is associated with the "Application Display Tab," and the "RefreshSettings" tag is associated with the "Application Refresh Tab."

Throughout the XML file, if have you set your "modifiable" attributes to "false," then it really doesn't matter whether these "UserInterface" tags are set to "true" or "false," because the users won't be able to change anything anyway.

File Cleanup

The file cleanup settings in the config.xml file allow you to specify whether the icons that have been placed on your users' desktops and Start menus should be removed.


A value of "true" in the "Logoff" tag causes the icons to be deleted when the user logs off. A value of "true" in the "Exit" tag causes them to be removed when the user exits the application. These file cleanup values aren't used very often, unless you have users that share workstations.

ICA Options

The ICA options section of the config.xml file allows you to specify session options that are available to your PN Agent users.


All of the "DisplaySize" tags dictate what display options are available to the users. The "Width" and "Height" tags of each "Dimension" tag specify the different resolutions that are available. For example, if you don't want users connecting at 640 x 480, then remove those tags, including the <Dimension> tag preceding it and the closing </Dimension> tag.

Notice that in addition to the "Dimension" tags, there is a "Percent" tag that allows you to specify session sizes as a percentage of screen size. You may add additional "Percent" tags as needed. Finally, there are two values available for the "Mode" tag. If you do not want seamless or full screen modes available, then remove the associated "Mode" tags.


The "ColorDepth" tags available here to PN Agent users are the same options that are available elsewhere. Within the config.xml file, the following color depth code is in place: 1=16 colors, 2=256 colors, 3=16-bit color, and 4=24-bit color. As with the other parameters, you may remove options that you do not want to present to users.


Similar to the other options, you can configure audio quality via the config.xml file. For example, if you want to disable sound for your PN Agent users, you would remove the excess tags so that your "Audio" section looked like this:


The last tag in the ICA options section specifies the ICA template file that is to be used when users launch applications.


Since PN Agent is based on NFuse technology, the ICA template file is used in the exact same way as it is in NFuse.

Config.xml Closing Tag

In order to signify the end of the config.xml file, you need to close the very first tag (the root tag) that was opened at the beginning of the file.


Designing your PN Agent Solution

The PN Agent can read it's settings from a config.xml file from any URL. (This doesn't have to be an NFuse web server.) However, it does need to access an NFuse Classic server in order to receive the user's published application icons (via enum.asp) and to launch published applications (via launch.asp).

Number of PN Agent Servers

Since the PN Agent ICA client only accesses the NFuse web server when applications are enumerated or launched, one NFuse server can support thousands of users. (Redundancy of these servers is discussed in Chapter 17.)

Number of Config.xml files

You can have multiple config.xml files on a single NFuse server. This allows you to have different sets of users with different PN Agent configurations if you point them to unique config.xml files.


Start the conversation

Send me notifications when other members comment.

Please create a username to comment.