CDFControl

CDFControl ReadMe (v1.5)

Description:

CDFControl is a software debugging utility that captures Citrix Diagnostic Facility (CDF) trace output messages that are output from the various Citrix product modules.

*Note* - CDFControl does NOT serve as a replacement to any of the other CDF tracing utilities, such as the Citrix Access Suite Console for tracing. It is simply offered as an alternative utility to use, when attempting to capture CDF traces.

Requirements:

• Citrix MetaFrame XP with Service Pack 4, or later versions of Citrix Presentation Server.

This utility should work with other Citrix Access Suite products (such as Password Manager); however, only the Citrix Presentation Server product line was tested.

Instructions for Use:

This utility will list the modules that are available for tracing, on the server that it is being run on. Therefore, if you do not see a familiar module in the list – then that module is not available for tracing on that respective server.

Configuring the Trace Session:

By default, CDFControl is configured to start a trace with the following properties:

• Sequential

• 50MB Log File Size

• Outputs the Event Trace Log file in the current directory

• Configures the Flags and Level to the most detailed and advanced settings available (Level 16, Flags: FFFFFF)

All the above settings are configurable options on the user interface.

Trace By Category

CDFControl also offers the ability to select tracing troubleshooting categories. This feature allows the user to simply select a troubleshooting category, and then CDFControl automatically checks the necessary tracing modules – based on the selected category.

For example: If “Smart Cards” is selected from the drop list menu, then modules such as “MF_Hook_SmartCards” will be checked automatically. Then all the user would have to do is click “Start Tracing”

(Note – the troubleshooting category selection is not available via the command line)

Using the CDFControl.ini file to load custom Trace Categories:

CDFControl is equipped with 15 preset tracing categories, for troubleshooting various components and issues. However, it is possible to load your own custom tracing categories to this list by means of an .ini file. This allows you to maintain your own personal list for tracing issues that pertain specifically to your environment or to an issue that is not available with the preset categories.

Loading the custom Trace Categories:

You can create this file using a standard text editor such as “Notepad.exe”.

The file must be named: “CDFControl.ini”

The file must exist in the same directory as the CDFControl.exe program.

The format of the file should be as follows:

//

Name:Test

MF_Hook_SmartCard

MF_Driver_Cdm

MF_DLL_Ctxnotif

MF_Service_CdmSvc

MF_DLL_Wsxica

MF_Hook_MfApHook

MF_DLL_Cdmprov

MF_Driver_Wdica

THF_Hook_SCard_Client

//

Name:Random

MF_DLL_Cdmprov

MF_DLL_Cpmmon

MF_DLL_Ctxnotif

MF_DLL_Cutildll

MF_DLL_Vclipbd

//

An example CDFControl.ini file is included with this utility.

Once you have configured your CDFControl.ini file:

Simply launch the CDFControl utility. CDFControl will automatically load the ini file on startup, if one is present. If you choose to load the ini file after the utility is started, in the “Trace by Category” section click the drop list menu à select “* Load Custom *” à select “Yes” to load the custom categories from the file.

You should now see your custom categories present.

To Start a Trace:

Simply check the desired tracing modules, and click the “Start Tracing” button.

To Stop a Trace:

Simply click the “Stop Tracing” button.

Command Line Usage:

Since this is intended to be used as a graphical user interface application, the command line features are limited.

*IMPORTANT* - The command line usage requires that CDFCommand.ctl file is used to list the desired tracing modules. This file must be named “CDFCommand.ctl” and it must be located in the same directory as CDFControl.exe, otherwise the command line usage will fail.

TIP – you can use the “Create .ctl File” button from the user interface of CDFControl, to create the “CDFCommand.ctl” file. This allows you to easily check the desired tracing modules, and simply create your own ctl file based on it.

To Start a Trace Session:

Example: CDFControl /start FFFFFF 16 50 seq

The parameters are:

/start [to determine if to start]

/stop [to determine if to stop]

FFFFFF [Flags: could be 0-FFFFFF]

16 [Level: 0-16]

50 [Max Log Size: user specified]

Seq [seq or cir: sequential or circular]

/? [Help syntax]

To Stop a Trace Session:

CDFControl /stop

Note - The .ctl file must be named: “CDFCommand.ctl”

Using a CDF XML Trace Template File from the Access Management Console:

1. Simply click “Options” from the menu in CDFControl.exe

2. Then click “Load modules from XML template”

3. Browse and select your CDF XML template file

4. The modules should now be selected from the list

Exporting a CDF XML Trace Template File:

1. Configure the logging options and check the desired modules to be exported

2. Simply click “Options” from the menu in CDFControl.exe

3. Then click “Export modules to XML template”

4. Type a name for the XML file and click “Save”

This produces an XML trace template file that can be imported into the Access Management Console for tracing

Enhancements from last release:

1. Default trace file naming convention based on timestamp. This ensures a unique name with every trace file.

2. Automatic generation of a .ctl file with each trace.

3. Automatic loading of the custom ini file (CDFControl.ini)

4. Fixed inconsistency where sometimes the Citrix Print Manager Service will not be traced

5. Added option to select *ALL* modules based on the Citrix product you are tracing

New Enhancements in this release:

1. New ‘Options’ menu item that allows the loading of a CDF XML Trace Template File

o This allows you to use the XML trace template file that can be exported from the Access Management Console!

2. New ‘Options’ menu item that allows you to export a CDF XML Trace Template File

o This allows you to export a XML trace template file that can be used with the Access Management Console!

Custom Tools Software Liability Disclaimer:

This software application is provided to you “AS IS” with no representations, warranties or conditions of any kind. You may use and distribute it at your own risk. CITRIX DISCLAIMS ALL WARRANTIES WHATSOEVER, EXPRESS, IMPLIED, WRITTEN, ORAL OR STATUTORY, INCLUDING WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NONINFRINGEMENT. Without limiting the generality of the foregoing, you acknowledge and agree that (a) the software application may exhibit errors, design flaws or other problems, possibly resulting in loss of data or damage to property; (b) it may not be possible to make the software application fully functional; and (c) Citrix may, without notice or liability to you, cease to make available the current version and/or any future versions of the software application. In no event should the code be used to support of ultra-hazardous activities, including but not limited to life support or blasting activities. NEITHER CITRIX NOR ITS AFFILIATES OR AGENTS WILL BE LIABLE, UNDER BREACH OF CONTRACT OR ANY OTHER THEORY OF LIABILITY, FOR ANY DAMAGES WHATSOEVER ARISING FROM USE OF THE SOFTWARE APPLICATION, INCLUDING WITHOUT LIMITATION DIRECT, SPECIAL, INCIDENTAL, PUNITIVE, CONSEQUENTIAL OR OTHER DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. You agree to indemnify and defend Citrix against any and all claims arising from your use, modification or distribution of the code.