Product Documentation

Installing EdgeSight Agents

Oct 16, 2015

In most production environments, the agent is deployed and installed as described in “Agent Deployment and Installation Overview” in Install and Configure. You can also perform an agent installation on a single client system. You may want to use this method during evaluation or when deploying and installing small numbers of clients.

If you are deploying agents for monitoring virtual desktops, see Installing EdgeSight for Monitoring Virtual Desktops for information specific to that environment.

Note: Whatever deployment and installation methods you choose, you must have administrator privileges on the target machines.

Agent Mode

The EdgeSight for XenApp Agent has two modes of operation, Basic and Advanced:

  • Basic agents require only that you have a XenApp Enterprise license available on your Citrix License Server.
  • Advanced agents provide the fully featured version of EdgeSight for XenApp and require that you have either a XenApp-Platinum Edition license or an EdgeSight for XenApp license available on your Citrix License Server.

When an EdgeSight for XenApp Agent is installed on a XenApp or Presentation Server machine, the agent mode enabled by default depends on the version and edition of XenApp or Presentation Server. The following table shows the default agent mode by XenApp and Presentation Server version and edition. The table also shows whether the Mode tab is displayed on the Citrix System Monitoring Agent control panel applet.

XenApp or Presentation Server Version XenApp or Presentation Server Edition Default Agent Mode Mode Tab Available
6.5 Platinum Advanced No
6.5 Enterprise Basic Yes
6.0 Platinum Advanced No
6.0 Enterprise Basic Yes
5.0 Platinum Advanced No
5.0 Enterprise Basic Yes
4.5 Platinum Advanced No
4.5 Advanced/Standard Advanced No
4.5 Enterprise Basic Yes
4.0 Platinum Advanced No
4.0 Advanced/Standard Advanced No
4.0 Enterprise Basic Yes

Software Configuration Tasks

You may need to change the configuration of some software, such as antivirus software or personal firewalls, on machines which will run the EdgeSight Agent to ensure proper operation. You can perform these configuration tasks before or after installing the EdgeSight Agent. For more information, see Configuring Third Party Software.

Antivirus Configuration Checking

Due to the manner in which buffer overflow protection was implemented in McAfee VirusScan 8 or 8i with Patch 10, this feature may conflict with the operation of the EdgeSight Agent. (In later versions of McAfee VirusScan, this feature was implemented differently and does not conflict with EdgeSight Agent operation.) The EdgeSight Agent installer checks for McAfee 8 or 8i with Patch 10 or below on the target machine. If the EntApi.dll file is present with version 8.0.0.277 and below, the installation exits with an error. The check is performed on both full UI and unattended installations. In a command-line installation, the check can be omitted from the installation process by specifying the OVERRIDE_COMPCHECK property with a value of 1.

Note: The OVERRIDE_COMPCHECK property should only be used if you disable the McAfee buffer overflow protection feature as described under "Incompatibility Between McAfee Host Intrusion Protection (HIPS) V7.0 and the EdgeSight Agent" in the Known Issues and Fixed Issues in EdgeSight 5.4.

Installing an Agent Using the User Interface

Note that not all public installation properties are exposed when installing using the user interface. Properties not explicitly set from the user interface are set to their default value if one exists. To install an agent using the user interface:
  1. Insert the media.
  2. Select EdgeSight Agent Installers.
  3. Select the agent type to be installed to display the Welcome screen.
  4. Click Next to display the License Agreement screen.
  5. After reading the license, select the I accept radio button and click Next to display the Company Information screen.
  6. Enter the COMPANY name. This should match the company name specified during EdgeSight Server setup.

    If you are installing the agent on an endpoint device, enter the DEPARTMENT name. If no department name is provided, the agent data will be displayed under the root department.

    If you are installing the agent on XenApp, select the operational mode from the Mode drop-down menu. If you choose Basic mode, some capabilities are not available and no EdgeSight license is consumed. Basic mode is used when installing an EdgeSight for XenApp agent on an Enterprise Edition system.

    Click Next to display the Agent Location screen.

  7. Enter the installation path for the agent or accept the default value. You can browse to select a non-default location.
  8. Enter the installation path for the data files or accept the default. You can browse to select a non-default location. Click Next to display the Network Settings screen.
  9. Enter the server name and port number. These are required fields.
  10. The Automatically configure Windows Firewall for Port 9035 checkbox is selected by default. Enabling this feature automatically configures the firewall for the listen port (the port on which the agent listens for remote connections from the browser displaying the EdgeSight Server console). The firewall must be running, but can either be enabled or disabled. The exclusion is set up for Domain networks. If an exception for Private networks is required, the Domain exception can be used as a template. If you do not want Windows Firewall automatically configured, deselect the checkbox.
  11. If an SSL network connection is required, select the Use SSL checkbox. (This is equivalent to setting the CONNECTION_FLAGS property.)
  12. If a proxy server is used, select the Use a proxy server checkbox. Then enter the proxy server name and port and the username/password used to access the server. (This is equivalent to setting the PROXY_ADDRESS, PROXY_PORT, and PASSWORD properties.) Click Next to display the Advanced Settings screen.
  13. The Advanced Settings screen is only used if you are installing the EdgeSight for Endpoints agent or the EdgeSight for Virtual Desktops agent on virtual desktops in a pool. See Installing EdgeSight for Monitoring Virtual Desktops for instructions on installing and deploying agents in this type of environment. Click Next to display the Ready to Install screen.
  14. Click Install to begin the installation. (If you need to review or change any settings before installing, use the Back button to return to the configuration screens.) When the installation is complete, the Setup Complete screen is displayed.
  15. Click Finish to complete the installation. The Installer Information dialog is displayed, prompting you to reboot your system so that configuration changes will be applied.
  16. Click Yes to reboot your machine.

Installing EdgeSight Agents Using the Command Line

The MSI file uses public properties to specify custom install settings. You can edit public properties using the following methods:

  • Run the installer user interface (if the property is exposed). This method offers fewer installation options than using the command-line interface. Also, a log file is not created when the user interface is used for installation.
  • Create a transform file using a tool such as Orca.
  • Specify key/value pairs on the command line. This method allows you to control the full range of installation options, including specifying a log file, as well as being able to specify public properties. The syntax for key/value pairs is KEY=value.

See your MSI documentation for syntax rules for property values. The following table lists the public properties used when installing the EdgeSight agent:

Property Name Description
COMPANY The company under which data will be displayed on EdgeSight Server. If this property is not specified, the server considers the device unmanaged, and the agent cannot upload data to the server.
DEPARTMENT
The department under which data will be displayed on EdgeSight Server. Special characters are not allowed in the name of an EdgeSight department. If this property is not specified, the device is assigned to the default root department.
Note: This property is only required for EdgeSight for Endpoints agents; EdgeSight for Virtual Desktops agents and EdgeSight for XenApp agents use the Farm structure as the department structure.
INSTALLROOT

Location of the main Citrix EdgeSight directory. For example:

INSTALLROOT=”%programfiles%\citrix\system monitoring\Agent”

DATA_DIR

Location of the Citrix EdgeSight data directory, within quotation marks. If this property is not specified, data files are placed in the default location:

%ALLUSERSPROFILE%\Application Data\Citrix\System Monitoring\Data\

On Microsoft Vista systems, the default path is:

%ALLUSERSPROFILE%\Citrix\System Monitoring\Data\

Note that the data directory cannot be on a mapped drive.

DELETE_DATA_ON_UNINSTALL

Controls whether agent data files (database and log files) are deleted when the agent is uninstalled.

0 = Do not delete files on uninstall

1 = Delete files on uninstall

Default value is 1.

REMOTE_SECURITY

Determines whether security is enabled for remote connections from the server.

0 = Security disabled

1 = Security enabled

Default value is 1.

See the REMOTE_SECURITY_GROUP property for more information on remote device security.

Note: This option is deprecated and will be removed in a future version.

REMOTE_SECURITY_GROUP

Local machine group to which the current working user must belong for remote connections from the server. Note that it is the current working user of the machine that is checked, not the user account used to log into the Citrix EdgeSight Server Console.

The REMOTE_SECURITY and REMOTE_SECURITY_GROUP properties work together to determine the level of security for remote device access as follows:

RemoteSecurity=1, RemoteSecurityGroup=<not set>

This is the most secure and restrictive setting. In order to display real-time reports based on the agent database, the EdgeSight Server Console user must be a local administrator on the actual device.

RemoteSecurity=1, RemoteSecurityGroup=<Active Directory group>

An Active Directory group must exist or be set up in order to use the REMOTE_SECURITY_GROUP property. Add all EdgeSight users to this group who need access to the real-time reports. This approach allows you to carefully control those users with access to real-time reports.

RemoteSecurity=0, RemoteSecurityGroup=<any value>

This is the least secure setting. This gives all EdgeSight Server Console users the ability to display real-time reports. This setting is generally not recommended.

SYNCH_AD_TREE

Determines whether to synchronize the Active Directory tree with the Citrix EdgeSight department tree.

0 = Synchronization disabled

1 = Synchronization enabled

Default value is 0.

ALLOWSERVEROS

Determine whether to allow an EdgeSight for Endpoints agent to be installed on a system running a server OS.

0=No installation on server OS

1=Install on server OS

Default value is 0.

Note: During a silent installation of an EdgeSight for Endpoints agent on a system running a server OS, the install fails unless the ALLOWSERVEROS property is set to 1.
ALLOWVIRTUAL

Determine whether to allow an EdgeSight for Endpoints agent to be installed silently on instances of XenDesktop 4.0 or later.

0=No installation on XenDesktop 4.0 or later instance

1=Install on XenDesktop 4.0 or later instance

Default value is 0.

Note: The EdgeSight for Endpoints agent does not collect session-related data on XenDesktop systems. If you wish to collect data relating to XenDesktop, please install the EdgeSight for Virtual Desktop Agent.
NO_CONTROL_PANEL

Determines whether the control panel applet is installed.

0=Install control panel applet.

1=Do not install control panel applet.

Default value is 0.

For more information, see "Configuring Agents Using the Control Panel".

FUNCTIONALITY_MODE

The operational mode (Basic or Advanced) for an EdgeSight for XenApp agent, as described in “Agent Mode”. The option values as are follows:

1 = Advanced Mode

2 = Basic Mode

SHOW_SERVICES_TAB

Determines whether the Service Control tab is displayed on the control panel applet. The tab allows users to enable or disable the Citrix System Monitoring Services.

0 = Services tab not displayed.

1 = Services tab displayed.

Default values are disabled (0) for EdgeSight for Endpoints Agents and enabled (1) for EdgeSight for XenApp Agents.

See "Configuring Agents Using the Control Panel" for more information on the control panel applet.

OVERRIDE_COMPCHECK

Overrides the version check described in “Antivirus Configuration Checking”. To override the check, specify this property with a value of 1.

Note: This property should only be used if you disable the McAfee buffer overflow protection feature as described under "Incompatibility Between McAfee Host Intrusion Protection (HIPS) V7.0 and the EdgeSight Agent" in the Known Issues topic for your release.

Network Settings
CONNECTION_FLAGS

0 = No SSL

1 = Use SSL

Default value is 0.

HTTP_TIMEOUT Determines how long to wait, in seconds, for a connection or other operation to complete. The default value is 30 seconds.
PROXY_FLAGS

0 - No proxy settings are selected

1 - Use proxy

3 - Use proxy and non-SSL tunnel (CONNECTION_FLAGS must be set to 0)

5 - Use proxy and require authentication (value must be supplied for PROXY_USER)

7 - Use proxy and require authentication (value must be supplied for PROXY_USER) and non-SSL tunnel (CONNECTION_FLAGS must be set to 0)

Default value is 0.

PROXY_PORT Port through which the agent communicates with the proxy server. The default port number is 8080.
PROXY_ADDRESS The hostname or IP address for the proxy server.
PROXY_USER The user name for the account used to access the proxy server.
PROXY_PASSWORD Password for access to the proxy server. The password is encrypted before being stored in the registry.
SERVER_NAME Server to which the agent will report data. This property is required. If no server name is supplied, the agent is unable to upload data to the server.
SERVER_PORT Port through which the agent communicates with the EdgeSight Server. The default port number is 80.
FIREWALL_EXCEPTION_ALLOWED Supply a value of 1 to allow Windows Firewall to be automatically configured to exclude the listen port (9035). The firewall must be running, but can either be enabled or disabled. If you do not want the firewall automatically configured, set the value to 0. The default value is 1.
Virtual Desktop Environment Properties

These properties are only used when installing the EdgeSight for Endpoints Agent on virtual desktops in a pool. See Installing EdgeSight for Monitoring Virtual Desktops for more information.

POOLED_INSTALL Supply a value of 1 to indicate that the agent is to be installed on virtual desktops in a pool. This property must be set to 1 to enable the remaining virtual desktop environment properties.
REMOTE_PATH The UNC path for the agent data file share.
IMAGE_POOL The name of the pool in which the virtual desktops will be running. This pool name is case sensitive and must match the pool name specified during the agent database server installation.
DBBROKER_FQDN The fully-qualified domain name or IP address of the EdgeSight Server which will be acting as the database broker.
BROKER_PORT The port associated with the EdgeSight Server which will be acting as the database broker.
BROKER_CONNECTION_FLAGS

0 = No SSL

1 = Use SSL

BROKER_PROXY_FLAGS

0 = No proxy

1 = Proxy is of CERN type

2 = Proxy is a non-SSL tunnel to an SSL server

BROKER_PROXY_ADDRESS The hostname or IP address of the proxy server.
BROKER_PROXY_PORT Port through which the agent communicates with the proxy server.
BROKER_PROXY_USER The username used when accessing the proxy server.
BROKER_PROXY_PASSWORD Password for access to the proxy server. The password is encrypted before being stored in the registry.

Use the msiexec command to install the agent using the command-line interface. Public properties are specified as KEY=value pairs as described earlier in this topic. If a property has a default value, that value is used if the property is not specified on the command line.

When installing an EdgeSight for Endpoints agent using the command line, the following properties should always be specified:

  • SERVER_NAME - If the server name is not specified, the agent is unable to obtain configuration information or upload data.
  • COMPANY - If the company name is not specified, the device is considered an unmanaged device and cannot upload data to the server.
  • (On a system running a server OS:) ALLOWSERVEROS - If this property is not specified, a warning is issued. During a silent installation to a system running a server OS, the install fails unless the ALLOWSERVEROS property is set to 1.
  • (On a virtual desktop instance running XenDesktop 4.0 or later:) ALLOWVIRTUAL - If this property is not specified, a warning is issued. During a silent installation to a virtual desktop instance running XenDesktop 4.0 or later, the install fails unless the ALLOWVIRTUAL property is set to 1.

The following is a sample command line for the installation of an EdgeSight for Endpoints agent on a 64-bit desktop system:

Msiexec /i EdgeSightEPAgentx64.msi /l logfile.log /q 
SERVER_NAME=Myserver COMPANY=Mycompany DEPARTMENT=Mydept

The following is a sample command line for the installation of an EdgeSight for XenApp Agent on a 32-bit system running a server OS:

Msiexec /i EdgeSightXAAgent.msi /l logfile.log /q 
SERVER_NAME=Myserver COMPANY=Mycompany  
ALLOWSERVEROS=1 DATA_DIR=”d:\Mydata”

The /i flag is used to specify the package being installed. The /l flag is used to specify the installation log file name. (Capturing an installation log is strongly recommended.) Use the /q (quiet) flag to install an agent with no user interaction. For a complete list of standard MSI command-line arguments, open a Command Prompt window and type msiexec /h to invoke help, or refer to The Command-Line Options for the Microsoft Windows Installer Tool Msiexec.exe at http://support.microsoft.com/kb/314881.

Installing the EdgeSight for XenApp Agent in a Streamed Environment

Using the EdgeSight for XenApp Agent, you can implement monitoring of XenApp servers running in a streamed environment using Citrix Provisioning Server for Datacenters 4.5 or later.

The Provisioning Server solution’s streaming infrastructure is based on software streaming technology. It allows administrators to create a virtual disk (vDisk) that represents a computer hard drive, and then relocate that vDisk on an OS-Provisioning Server, or on a storage device that has access to a Provisioning Server. Once the vDisk is available, the target device no longer needs its local hard drive to operate; it boots directly across the network. The Provisioning Server streams the contents of the vDisk to the target device on demand, in real time, and the target device behaves as if it is running from its local drive.

Important: Although the operating system and applications are streamed to the target device, the EdgeSight Agent requires a persistent local drive to store its database.

Please review the following installation and configuration guidelines before deploying the EdgeSight for XenApp Agent in this environment.

Prerequisites

EdgeSight Server, Provisioning Server 4.5 or later for Datacenters, and the Citrix License Server for Windows must be installed on their respective machines. For installation instructions, refer to the following product documents:

Installing the EdgeSight Agent on a Master Target Device

After installing the Provisioning Server Target Device software on the master target device, but prior to imaging the system, install the EdgeSight agent. You can install the agent using the command-line or the user interface. In either case, keep in mind the following:

  • All target devices associated with a virtual disk (vDisk) must report to the same EdgeSight Server. If a subset of machines is to report to a different EdgeSight Server, create a new vDisk for these devices.
  • EdgeSight Agents detect when the vDisk is in private mode and will not start. This capability eliminates the need to set the EdgeSight agent service start mode to manual.
  • If the master target device has only one disk drive, the installer will not allow a nonexistent drive to be specified. Registry and file system changes are required before master target imaging. See “Installation on a Master Target Device with a Single Disk” later in this topic for more information.

Installing the Agent Using the Command-Line Interface

The SERVER_NAME and COMPANY parameters should always be specified to ensure that configuration information can be obtained from the server and that data can be uploaded to the server. The following sample command line also shows the use of the DATA_DIR parameter to select the data files folder. Note that the data directory cannot be on a mapped drive.

msiexec.exe /i EdgeSightXAAgent.msi /l logfile.log /q 
SERVER_NAME=rsbetx COMPANY=Mycompany DATA_DIR=”d:\Citrix\System 
Monitoring\Mydata”

Installing the Agent Using the User Interface

In the Agent Location dialog, be sure to install the EdgeSight agent on the virtual disk (vDisk). The default location can be used. Change the data folder to a location on the physical disk that will be in each target device. Note that the data directory cannot be on a mapped drive.

In the Network Settings dialog, specify the server name and port number for the EdgeSight Server. All target devices that use the vDisk will report to this server. If a subset of target devices is going to report to a different EdgeSight server, a separate vDisk must be created for those devices. (Do not change the network settings on an individual device; these changes are not persisted if the device is rebooted.)

Installation on a Master Target Device with a Single Disk

If the master target device has only one disk drive, the installer will not allow you to specify a data folder on a nonexistent drive. In this case, perform the installation using the default values and then edit the registry and file system when the installation completes:

  1. Within the registry, navigate to the key HKLM\Software\Citrix\System Monitoring\Agent\Core\4.00 and change the DataPath to the appropriate location on the physical disk of the target devices.
  2. Within the file system, navigate to %ProgramFiles%\Citrix\System Monitoring\Agent\Core\Firebird and locate aliases.conf.
  3. Open aliases.conf in a text editor and change the RSDatr entry to match the location of the data folder on the physical disk of the target devices. For example: RSDatr = D:\Citrix\System Monitoring\Data\RSDatr.fdb

Imaging the Master Target Device Disk

Image the disk of the master target device.

Configuring Target Devices

Each target device must have a physical disk drive. The drive must have an NTFS partition that is visible to the streamed OS.

Set the boot order of the target device to boot from the network first.

Boot the target device from the shared vDisk. After booting the target device, the Citrix System Monitoring Agent service should be running and the service's data should be present on the target device's disk drive. If you need to troubleshoot a specific target device, registry changes for additional tracing should be made on the device, not on the vDisk. Note that these changes are not persisted if the device is rebooted.

Configuring Agents Using the Control Panel

If you need to reconfigure connection settings for agent to server communication after installation, use the Citrix System Monitoring Agent control panel applet. You must have Administrator privileges on the machine to launch the applet. To use the applet:
  1. From the Start menu, choose Settings > Control Panel and select Citrix System Monitoring Agent to display the Citrix System Monitoring Agent Settings dialog.
  2. Edit the Citrix EdgeSight Server address and port number as required.
  3. Select the Use SSL encryption checkbox if the Citrix EdgeSight Server is SSL enabled. To be SSL enabled, a valid SSL certificate issued by a trusted certificate authority must be present on the server running the Citrix EdgeSight Web site. If SSL support is enabled, all agent to server communications must be over SSL. If an agent attempts to connect to an SSL-enabled server without using SSL, an error is generated and the data upload is rejected.
  4. Select the Use a proxy server checkbox if a proxy server is used. Enter the proxy server address and port and indicate whether the server is a non-SSL tunnel and whether authentication is required. Supply the authentication username and password if required.
  5. If an EdgeSight for XenApp agent is installed on a machine running XenApp Enterprise, you can select the Mode tab and change the agent mode (Basic or Advanced). Note that this tab is not displayed on XenApp Platinum systems. For more information on agent modes, see “Agent Mode”.
  6. When you have made all required settings changes, click OK to apply the changes and close the dialog. If the Service Control tab has been enabled on the control panel applet, you can disable or enable the Citrix System Monitoring Service and the Firebird Server - CSMInstance service. Disabling these services stops the services and sets the startup type to disabled. Enabling the services starts the services and sets the startup type to automatic.
    Important: The Service Control capability is intended for use in the event that you suspect that an EdgeSight Agent is causing performance or software compatibility problems. By using the Service Control feature, you can disable services and keep them from restarting. If you uninstall the agent when a problem occurs, you may lose data which may help in resolving the problem.

    The Service Control tab is enabled by default for EdgeSight for XenApp agents, but it disabled by default for EdgeSight for Endpoints agents.

    The Service Control tab can be displayed by setting the SHOW_SERVICES_TAB parameter to 1 during agent installation, or by setting the HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\System Monitoring\Agent\Core\4.00\Control Panel\AllowServiceControl registry key to 1.