Citrix IMA Helper
Applicable Products
- XenApp 6.0 for Windows Server 2008 R2
- XenApp 6.5 for Windows Server 2008 R2
Description
The purpose of IMA Helper is to assist with narrowing-down IMA startup issues as much as possible so the administrator can reduce the time needed to troubleshoot and solve related problems.
Pre-requisites
• XenApp 6.0 or XenApp 6.5
• NET Framework 3.5 or newer
• Local Administrator rights (will only run if the user has local admin rights)
• Internet Access is required for the IMA Startup Analysis feature (analysis done in background using Citrix Diagnostics Facility (CDF) event collection, requiring download of TMF files)
Installing IMA Helper
IMA Helper is a standalone application. You do not need to install the application.
How to use IMA Helper
IMA Helper User Interface
• Feature Selection Tabs: Select the feature you wish to use. The available features are:
• IMA Status (default)
• IMA Datastore (database tools)
• IMA Startup (startup analysis)
• Network Tools (network tracing)
• Quick Controls: Several quick-access controls for IMA troubleshooting covered on its own page in this guide.
• Selected Feature Main Window: This is the main area for the selected feature. This is the only area in the tool that changes when you move between tabs. Multiple features can be run at the same time, simply change the tab as the current one is doing its work.
• Real-time IMA monitor: Monitor for IMA Service status, in real-time. Possible states are: Running, Stopped, Starting, and Stopping.
• XenApp / OS version info: Basic info on XenApp and OS versions, for quick reference.
• Start IMA: Checks if IMA isn’t already starting or Running, then tries to start the service.
• Stop IMA: Checks if IMA isn’t already stopping or Stopped, then tries to stop the service.
• Recreate LHC / Rade: issues a DSMAINT RECREATELHC and DSMAINT RECREATERADE.
• Kill IMA: After a disclaimer is shown to the user, the tool looks for the ImaSrv.exe process. If found, it attempts to kill it, regardless of the status of the service (running, starting, stopping). This is as good as opening Task Manager, right-clicking the process and choosing “End Process”.
• Kill MFCOM: After a disclaimer is shown to the user, the tool looks for the MFCOM.exe process. If found, it attempts to kill it, regardless of the status of the service (running, starting, stopping). This is as good as opening Task Manager, right-clicking the process and choosing “End Process”.
This tab displays information for IMA/MFCOM services, along with farm details. All the data is gathered locally, this only shows information that is available to the local server.
- Copy to Clipboard: Exports the data on this tab to the clipboard so it can easily be pasted into a text file or body of an email, for documentation purposes.
• IMA Service
• IMA Service Status: Current status of the IMA Service.
• IMA Logon Account: Account being used for the IMA Service at the system level.
• IMA Startup Mode: IMA Service Startup Mode.
• IMA Port: Inter-server communication port in use for IMA.
• IMA AAC Port: Console (DSC, AppCenter) communication port for IMA.
• MFCOM Service
• MFCOM Service Status: Current status of the MFCOM Service.
• MFCOM Logon Account: Account being used for the MFCOM Service at the system level.
• MFCOM Startup Mode: MFCOM Service Startup Mode.
• Farm Details
• Farm name: Farm this server is currently a part of, as seen in the local registry.
• Original Farm Admin: Windows account used during the installation of XenApp on this server.
• DSN File: DSN file currently in use by IMA to connect to the IMA Datastore.
• Database Type: Type of database for the IMA Datastore.
• Database Server: NetBIOS name of the computer hosting the IMA Datastore.
• Database Name: Database name for the IMA Datastore.
• This Server
• Hostname: Local server NetBIOS name.
• FQDN: Local server Fully Qualified Domain Name (if available).
• XenApp Version: Version of XenApp installed on the local server as seen in the local registry.
• HRP Level: Current Hotfix Rollup-pack level for the local server as seen by CPATCH.
• Citrix License Server: License Server the local server is configured with as seen in the local registry.
• Operating System: Local server’s Operating System as seen in the local registry.
• Service Pack Level: Local server’s OS Service Pack level as seen in the local registry.
• Session Host Mode: Whether or not the local server is configured in Session-Host mode.
• XML Port: XML port for the local server’s XML service (if applicable).
On this tab we have DSMAINT CONFIG and DSCHECK graphic user interfaces for easier use.
This feature is designed to facilitate the process of running DSMAINT CONFIG on XenApp servers. The tool provides a Graphical User Interface for DSMAINT CONFIG to the XenApp Administrator.
See documentation for DSMAINT CONFIG at http://support.citrix.com/proddocs/topic/xenapp65-admin/ps-commands-dsmaint-v2.html
How to use:
1. If needed, click on “Create New DSN” to open up the Operating System ODBC dialogue and create a new DSN (recommended).
2. Select type of authentication if required (Domain Account is default).
3. Input the credentials for Domain, User and Password.
• “Domain” is only applicable when “Domain Account” is the selected Authentication Type.
• The password is hidden by default. Uncheck “Hide Password” to display the password.
4. Select Browse and manually browse to the location of the DSN file to be used with DSMAINT CONFIG.
5. Select Run to run the command.
• The result (success / failure) is displayed in a message box, exactly how it would on a CMD.
This feature is designed to facilitate the process of running DSCHECK on XenApp servers. The tool provides a Graphical User Interface for DSCHECK to the XenApp Administrator.
DISCLAIMER: Caution! This tool modifies the data in your database. Using this tool incorrectly can cause serious and irrecoverable problems with the data. Citrix cannot guarantee that problems resulting from the incorrect use of this tool can be solved. Use this tool at your own risk and only as directed by Citrix support staff.
See documentation for DSCHECK at http://support.citrix.com/proddocs/topic/xenapp65-admin/ps-commands-dscheck.html and http://support.citrix.com/article/CTX124406
How to use:
1. Select the Module you wish to run DSCHECK with. Possible options are: Servers, Apps, Icons, Printers, Groups, FTA, Folders, HotfixFolder, LMS, and for XenApp 6.5 R01 and up, WorkerGroup.
2. Select the options you want to use.
• Each module has different options and required options.
• The options selected by default are always “check only”, non-destructive tests against the Datastore.
• Use this tool with caution.
3. Click on “Run”.
4. Read the disclaimer, and if you agree, click “Yes” to continue.
5. Click “Ok” to begin. A new window will open once the command finishes running, see below:
• Click “Close” to close it, or “Save to File” to save the output to a text file.
• The output also includes, for documentation purposes:
• Timestamp
• Command being run
• Database name and Server
The Master Check feature:
• The Master Check feature runs DSCHECK for all applicable modules in sequence, then displays the combined results. This is done with only the “check” option selected. This is for reporting purposes only. No changes are made by the Master Check feature.
• To use it, simply click on “Master Check”, click on “Yes” if you agree with the disclaimer, and then click “Ok”. The results will be shown in a new window, similar to the normal “Run” command. See above for details.
This feature is a startup analysis for the IMA Service, to be used when IMA Service fails to start. This analysis is accomplished by real-time Citrix Diagnostics Facility (CDF) event collection and analysis, all done in the background.
How to use:
1. Ensure IMA Service is stopped and not started or on a starting/stopping hung-up state
2. Click on “Start Analysis”
3. Once the analysis completes, the results will be shown under “Results” group.
Feature description:
• Analysis Steps: Analysis progress, step by step, with elapsed time for each step (stopwatch).
• IMA Service Dependencies: Checks if all the services that IMA Service depends on for XenApp 6.0 and XenApp 6.5 are running
• Plugin being loaded: Shows real-time information during the analysis on the Currently Loading Plugin
• IMA Plugins List: Shows status and time to load for each of the IMA Modules
• Analysis Results: The results for the analysis
• Failed plugin lookup: If the startup of IMA fails during plugin loading, the tool logs it here and creates a clickable link. When clicked, the local default browser is launched and a search for the plugin name is performed within citrix.com, using the browser’s default search engine.
• IMA Error code lookup: If a known error is found during this analysis on either the CDF event stream or the system Event Logs, the tool logs it here and creates a clickable link. When clicked, the local default browser is launched and a search for the error code is performed within citrix.com, using the browser’s default search engine.
Note: In the picture above, we see an example where the analysis failed on step 3 (Connecting to Datastore), but IMA was started successfully based on the LHC only. Notice how the tool was able to see the error code IMA_RESULT_DBCONNECT_FAILURE and log it as a clickable link.
This tab provides the admin with a basic Network Tracing Utility. This utility is able to trace any incoming/outgoing packets that the selected local NIC is able to see. Unlike other popular network tracing solutions, IMA Helper does not focus on in-depth network analysis and packet data is not displayed to the admin. The scope of this utility is to help troubleshoot IMA startup cases, and any other cases where in-depth analysis of network traces is not needed.
How to use:
1. Select the interface you want to trace on “Interface selector”
2. Confirm your IP and port filters (if applicable)
3. Click the “Start” button
4. Once the desired data has been collected, click the “Stop” button.
Feature description:
• IP Filtering: Allows the admin to filter the trace by IP. Default options are Localhost, SRC (source) and DST (destination). Two additional custom IP addresses can be specified.
• Port Filtering: Allows the admin to filter the trace by port. Default options are ports 1433 (SQL) and 443 (SSL). A quick filter option for ports 1494 (ICA) and 2598 (Session Reliability) is available. The admin can also use any number of custom ports. Separate the custom ports by comma (,) without spaces. Example: “1494,2598,3389”.
• Output window: Trace output is displayed here. Each entry here is a packet. Expand the packet node by clicking on the “+” icon to see additional information for the packet, such as length, TCP flags and others. Packet data is not displayed to the admin.
Packet segments:
• Theme selector: Select the preferred theme for the output window. The default theme is “Day”.
• Interface selector: Select the interface you want to trace. IPV4 interfaces only.
• Start/Stop button: Start or stop the tracing.
• Ping utility: Here you can quickly ping any hostname/FQDN/URL/IP address. Simply type in the address in the input field and click on “Go”. The results are displayed in the Output window.
• Search the output: Use this to search for specific IPs or any other strings within the output for the trace. Simply type in the string you want to search for in the input field and click on “Go”. Each time “Go” is pressed thereafter, the searcher jumps to the next entry. If the end of the output is reached, the searcher informs the admin then returns to the top of the output and searches again.
• Clear the output: Clear the output window of any text, including network trace and ping.
• Export to XML: Export the current output window to XML format so it can be parsed in 3rd party applications such as Microsoft Excel.
Security Permissions Required by IMA Helper
• Local Administrator rights (the application will only run if the user has local admin rights).
Data Modified by IMA Helper
• At execution, the file “CdfEng.dll” is created in “%windir%\System32”. This is a needed library for the Startup Analysis feature, which runs integrated with CDFControl.
• At execution, the file “CDFControl.xml is created in “%temp%”. This is a needed configuration file for the Startup Analysis feature, which runs integrated with CDFControl.
• When the Startup Analysis feature is used, the file “CDFlog.etl” is created in “%temp%”. This is a CDFControl trace file, used by the feature.
• No changes are made to the registry by IMA Helper.
How to undo the changes made by IMA Helper
This application creates a graphical user interface for DSMAINT CONFIG and DSCHECK, which are command line applications available on any XenApp servers by default. All data modifications are performed by DSMAINT CONFIG and/or DSCHECK. Refer to XenApp documentation for more information on how to undo the changes made by DSMAINT CONFIG and DSCHECK.
No other features in IMA Helper modify the system in any way.
Uninstalling IMA Helper
IMA Helper is a standalone application and you do not need to uninstall it. To remove the files created in the system by IMA Helper:
1. Manually delete “CdfEng.dll” from “%windir%\SysWOW64”.
2. Manually delete “CDFControl.xml” from “%temp%”.
3. If the Startup Analysis feature was run, manually delete “CDFlog.etl” from “%temp%”.
Contact Information
Questions? Concerns? Send any feedback for this tool to supporttools@citrix.com.
Disclaimer
These software applications are 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.