Now that you understand how NFuse works, we can start looking at how we make it do want you want.
The NFuse Configuration Process
Since the NFuse Java Objects are the main executable components of an NFuse web server, you actually change the properties of an NFuse web server by changing the properties of the NFuse Java Objects themselves. There are two different methods that can be used to configure those Java Objects:
- Modify a text configuration (NFuse.conf) that contains NFuse settings.
- Use a set of administrative web pages to graphically and interactively make certain changes.
Let's take a detailed look at these two configuration options.
Understanding the NFuse.conf File
When you install NFuse onto an IIS web server, all of the Java Objects and their related configuration and properties files are installed into the %programfiles%\Citrix\NFuse\ folder. When you install NFuse on an iPlanet or Apache web server, you must specify the location where you want the various components to be installed.
The NFuse Java Objects store all of their configuration information in a file called NFuse.conf, (located by default in the %programfiles%\Citrix \NFuse\conf\ folder on IIS web servers). You can directly edit this file with any text editor in order to make changes to NFuse. After you make changes to this file, you need to stop and start the web server service for the changes to take effect. (Using the iisreset command is an easy way to do this on IIS platforms.)
The NFuse.conf file controls all of the settings and behaviors of an NFuse web server, but the way the settings are used differs depending on the type of setting:
- Some of the settings affect the NFuse Java Objects directly (and therefore the NFuse server behavior). The NFuse Java Objects read the values of these settings from the NFuse.conf file when the web server is started. These settings are detailed in the "Configuring the NFuse Java Objects" section of this chapter.
- Some of the settings affect the NFuse web pages. Many NFuse web pages are built dynamically at run time by referring to settings in the NFuse.conf file. This allows the NFuse.conf file to control those web page options or behaviors. These settings are detailed in the "Configuring Default Web Page Options" of this chapter.
By having both types of settings controllable via the same NFuse.conf file, Citrix ensured that NFuse web sites could be language independent, since web pages written in any language can access the same settings in the NFuse.conf file.
The easiest way to understand an NFuse.conf file is to see an example of one from the real world. We'll take a look at an entire file right now. Then we'll focus on the specific configuration items that you'll actually be concerned with as a MetaFrame XP administrator.
#SessionField.NFuse_RelayServerPort=[TCP port pf SSL Relay]
SslKeystore=C:\\Program Files\\Common Files\\Citrix\\keystore\\cacerts\\
#OverrideClientInstallCaption=[Place your text here]
#ForceLoginDomain=[Place your domain here]
#NDSTreeName=[For NDS logins place NDS Tree name here,
and also change LoginType to NDS]
#SearchContextList=[NDS context1, NDS context2, ...]
Figure 11.2: A sample NFuse.conf file
Let's state some more facts about this NFuse.conf file. First of all, remember that in order for any changes to take affect, you will need to stop and start the web server service. Secondly, recall that this single file affects all of the NFuse web sites that you have on one web server. However, as we'll see later, it's possible to override the settings in this file on a page-by-page basis.
You will notice that some lines in the NFuse.conf file begin with a pound sign (#). This sign is the "comment" sign and lines that begin with it are ignored. If you change the contents of a line that starts with #, you need to remove the # for the changes to take affect.
Also, in the NFuse.conf file, the double backslash (\\) is the escape character that represents the "\" in a file path. So, for the path c:\winnt\brian, you would need to specify it as c:\\winnt\\brian.
As you can see, there are many configuration parameters included in this file. The "NFuse Classic Administrator's Guide" (NFuse_Guide.pdf included with the NFuse 1.7 download) provides a fantastic reference for details of all the options. However, as a real world NFuse administrator, only a subset of these fields will actually matter to you. Those are the fields that we will discuss here.
Using the NFuse Administrative Web Pages
If your NFuse web server is running on Internet Information Services on Windows 2000, there are graphical administration web pages that you can use to view and change the behavior of many of the basic NFuse options. These administrative web pages are essentially a graphical "front end" to the NFuse.conf configuration file. However, if your web server is not IIS 5.0 or newer, or if you want to make any advanced configuration changes, you'll need to edit the NFuse.conf file directly.
When you connect to the NFuse Administration web pages (at http://yourNFuseserver/Citrix/NFuseAdmin), you are presented with a pretty cool diagram that illustrates the different components of NFuse. You can click on different parts of the diagram to bring up a web page containing NFuse settings that affect that part. Each configuration page pulls its information from the NFuse.conf file.
There is a "Save" and a "Discard Changes" button on every configuration web page. After you enter the settings that you want, clicking the "Save" button writes those changes to the NFuse.conf file. However, it's important to remember that the NFuse Java Objects only read the settings from the NFuse.conf file when they are initially loaded. Therefore, in order to apply any changes that you make with the administrative web pages, you need to go into the "Apply changes" section of the administrative web site and click the "Apply changes" button after saving the changes. This button resets the NFuse Java Objects, causing them to reload the NFuse.conf file.
You don't really need to know much more about the NFuse administrative web pages. Throughout this chapter, as we describe specific options of the NFuse.conf file, we'll make a note if that particular option can be configured via the administrative web pages. This note will be in the form of (NFuse Admin Web Pages | …)
Configuring the NFuse Java Objects
The NFuse.conf file controls the properties of the NFuse Java Objects. These properties can be broken down into three broad categories:
- Properties that affect how the NFuse web server communicates with MetaFrame XP servers (via the Citrix XML service).
- Properties that affect how the NFuse web server formats the address of the MetaFrame XP server that it sends to the clients.
- Properties that affect the security of the NFuse web server.
We'll take a look at the first two types of properties next. We won't cover the NFuse security properties until we get to the security chapter, Chapter 15. After all, it does no good to secure NFuse until the rest of your system is secure.
The NFuse Communication with the XML Service
Remember from the explanation of how NFuse works that NFuse is able to function because it communicates with MetaFrame XP servers. This communication is conducted via the Citrix XML service running on one or more MetaFrame servers.
The following lines of the NFuse.conf file affect the NFuse server's communication with the Citrix XML service:
Notice that these lines are not in the same order as in the production NFuse.conf file listed in Figure 11.2. They are listed here together as a matter of convenience. However, you can generally put options in the NFuse.conf file in any order you like. In case of conflict, the last line wins.
(NFuse Admin Web Pages | MetaFrame Servers | Server list | Server addresses)
This line specifies the MetaFrame XP server (running the Citrix XML service) that NFuse will contact for all application information. This can be an IP address, a NetBIOS computer name, or fully qualified domain name. By default, the NFuse server will be configured to attempt to contact one server (the server that you specified during the initial NFuse setup):
An NFuse web server gets all of its information from the Citrix XML service running on a MetaFrame XP server in a server farm. If the one server that NFuse contacts goes down, then NFuse will not be able retrieve any user application information, even if all of the other MetaFrame XP servers in the farm are operational. For redundancy purposes, you can specify more than one server on this line with each server separated by commas:
The exact method of redundancy used depends on the setting in the EnableServerLoadBalancing line.
(NFuse Admin Web Pages | MetaFrame Servers | Server list | Use the server list for load balancing)
When this line is set to "On," the NFuse web server will use a "round robin" load balancing scheme to contact each server, selecting a different server from the SessionField.NFuse_CitrixServer line each time information is needed from a MetaFrame XP server.
If you set this line to "off," then NFuse will always contact the first server listed on the SessionField.NFuse_CitrixServer line. If this server ever fails, it will move on to the next one and so on.
After the NFuse web server opens a connection to a MetaFrame XP server via the Citrix XML service, this line specifies how long it will wait for a response before the server is deemed "unresponsive."
This line specifies how many times the NFuse server must contact an unresponsive MetaFrame XP server from the SessionField.NFuse _CitrixServer list before the NFuse server decides that the MetaFrame XP server has failed.
(NFuse Admin Web Pages | MetaFrame Servers | Server list | Bypass any failed server for __ minutes)
This item specifies the length of time (in minutes) that NFuse will not try to communicate with a MetaFrame XP server that has failed the number of times specified in the RetryCount. After this duration has passed, the server is added back to the list. This property applies whether EnableServerLoadBalancing is "on" or "off."
(NFuse Admin Web Pages | MetaFrame Servers | Settings for all servers | XML service port)
This is the TCP port that the Citrix XML service is running on the MetaFrame XP server specified on the previous item. If you have more than one MetaFrame XP server listed on the SessionField.NFuse_CitrixServer line, the XML service must be running on the same port on all the servers. By default, the Citrix XML service runs on port 80.
The NFuse Java Objects' Communication with the ICA Client
The NFuse.conf file also specifies the format of the MetaFrame XP server address that NFuse sends to the ICA client. This address format is controlled by the following line:
This allows you to specify the type of address that will be returned for the MetaFrame XP server in the ICA file that is sent to the client device. Valid options for the address include ipv4, ipv4-port, dns, and dns-port. Rather than explaining the different options, let's take a look at examples of each of the different types:
If you change the port that ICA uses (1494 by default), then you will need to use one of the two options that specifies the port in addition to the address. It is recommended that you use one of the port options regardless, just in case any of your users fouled up the configuration of their ICA clients by setting it to a different port. If you specify the port here, it will override a user's client setting.
If you plan to use one of the DNS-based options (which is required for SSL), you will need to have Feature Release 1 or 2 installed on the MetaFrame XP server running the Citrix XML service that the NFuse server communicates with.