Product Documentation

Installing EdgeSight for Monitoring Virtual Desktops

Oct 16, 2015

When monitoring physical endpoint machines, EdgeSight Agents store performance and availability data in a local database. Because virtual desktops in a pool are not preserved across reboots, agents must store data externally on a database server and a file share. The following figure shows the components required for virtual desktop monitoring.


Conceptual illustration of pooled image setup

  • EdgeSight Server - In addition to displaying reports and providing an interface for administration and configuration, EdgeSight Server includes database broker components which respond to agent requests for a connection string to an EdgeSight Agent Database Server.
  • EdgeSight Agent Database Server -The EdgeSight Agent Database Server provides storage for data collected by EdgeSight Agents running on virtual desktops in a pool. During installation you will be asked to specify the name of the pool and the name of the EdgeSight Server which will act as the database broker. (Multiple agent database servers can be associated with a pool.) Once the agent database server has been installed, it registers with the EdgeSight Server and regularly reports its operational status.
  • Agent Data File Share - The agent data file share provides storage for files such as log files and INI files which are not stored on the EdgeSight Agent Database Server. It is recommended that you set up your file share on either the EdgeSight Server or on an Agent Database Server machine.
    Note: In the above diagram, Agent Data File Share is shown separately to indicate that it is not part of the EdgeSight Server or EdgeSight Agent Database Server installation and requires separate setup.
  • EdgeSight for Virtual Desktops Agent - Initially, the EdgeSight Agent requests a connection string to an EdgeSight Agent Database Server. Once the agent is operational, it writes data to the agent database server and copies files to the agent data file share.
  1. Install the EdgeSight Server that will also act as the broker for remote agent databases. See "Configuring Database Brokers" for details.
  2. Install one or more agent database servers for each pool. See "Installing the Agent Database Server" for details.
  3. Setup a file share for agent data that does not reside in the database. See "Installing the Agent Database Server" for details.
  4. Install the EdgeSight Agent on the disk to be used by virtual desktops. See "Installing th Agent" for details. For overall system requirements for a virtual desktop environment, see “Virtual Desktop Monitoring Requirements” in System Requirements for EdgeSight 5.4.

Configuring Database Brokers

EdgeSight Server software includes components that assist agents running on virtual desktops to locate and connect to remote databases. When you install the EdgeSight Server Website, it additionally installs Web services that perform the following operations:

  • Broker database connections for agents running on virtual desktops in a pool
  • Monitor the status of available agent databases

These components are installed by default; you do not have to explicitly select or configure them. This allows you to easily designate a different EdgeSight Server as the database broker.

If you have multiple EdgeSight Server installations, you need only select one to act as the database broker, though you may designate others if you wish. The EdgeSight Server that will act as the database broker is selected when you install the agent database server, as described in "Installing the Agent Database Server". Note that if an EdgeSight Server is not brokering database connections, no status information will be displayed on the Agent Database Broker pages of the server console. See Installing EdgeSight Server for detailed instructions on installing EdgeSight Server software.

Installing the Agent Database Server

The agent database server can be installed on a Windows physical or virtual server-class machine. The installation creates a database monitor. An agent database is created when an agent is brokered to the agent database server. The database stores data written by an EdgeSight Agent, while the database monitor reports database availability and status to the EdgeSight Server acting as a database broker. If a firewall is installed on the machine, port 9037 must be open to allow communication with EdgeSight agents. Each agent database server can support one image pool.

During installation you will be asked to specify the name of the pool and the name of the EdgeSight Server which will act as the database broker. Typical disk space usage is generally 70 MB per virtual desktop for the databases on a single disk. After the installation is complete, the database monitor reports the availability of the agent database server to the database broker.

  1. Insert the media.
  2. Select EdgeSight Component Installers.
  3. Select EdgeSight Agent Database Server to display the installer Welcome page.
  4. Click Next to display the End User License Agreement page.
  5. After reading the license agreement, select the I accept radio button and click Next to display the Network Settings page.
  6. Enter the broker name and port. The broker name is the name of the machine hosting the previously installed EdgeSight Server, which includes the database broker components. You can also enter an IP address or fully qualified domain name.
  7. The Automatically configure Windows Firewall for Port 9037 checkbox is selected by default. Enabling this feature automatically configures the firewall for the database listen port (the port on which the agent database server listens for remote connections from the database broker). 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.
  8. If an SSL network connection is required, select the Use SSL checkbox.
  9. 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.
  10. After specifying the network settings, click Next to display the Agent Location screen.
  11. Enter the installation path for the agent database server or accept the default value. You can browse to select a non-default location.
  12. Enter the installation path for the data files or accept the default. You can browse to select a non-default location.
  13. Enter a name for the pool hosting the agents which will store data on the agent database server. You can choose any pool name. For ease of use, you may want to choose one that corresponds to the XenDesktop desktop group name.
  14. Click Next to display the Ready to Install screen.
  15. Click Next to begin the installation and display the Performing Installation screen. When the installation is complete, the Setup Complete page is displayed.
  16. Click Finish to exit the setup wizard.

Setting Up the Agent Data File Share

Some agent data are not stored in the agent database, such as log files and INI files. Therefore, agents running on virtual desktops require access to an external file share. The file share must be configured with permissions allowing authenticated users to create subdirectories that will contain the files, plus settings. The disk space needed is minimal and the file copies are small and infrequent. It is recommended that you set up your file share on either the EdgeSight Server or on an agent database server machine.

On Windows 2003 Systems

The permissions required include both the file share permissions and the NTFS file system permissions. To create an agent data file share and set all permissions on a Windows 2003 system:

  1. Create a new folder. The file share should not be located on a specific user’s desktop. Record the folder UNC path for use during the agent installation process.
  2. Right click on the folder name and select Properties from the popup menu to display the Properties dialog.
  3. Select the Sharing tab. Select the Share this folder radio button.
  4. Click the Permissions button to display the Permissions dialog.
  5. Click Add to display the Select Computer, User, or Group dialog.
  6. Enter Authenticated Users in the Enter object name to select field. Click OK.
  7. Select the Authenticated Users group.
  8. Ensure that the Change and Read permissions are selected and click OK.
  9. Select the Security tab and click the Advanced button to display the Advanced Security Settings dialog.
  10. Deselect the checkbox which enables child objects to inherit permission entries from the parent. (The specific checkbox label may vary based on the operating system.) When this setting is disabled, a Security dialog is displayed advising you that permission entries will no longer be inherited. Click Remove.
  11. Click Add to display the Select Computer, User, or Group dialog.
  12. Enter Authenticated Users in the Enter object name to select field. Click OK to display the Permission Entry dialog.
  13. Select This folder only from the Apply onto drop down menu.
  14. Ensure that the following permissions are allowed:
    • List Folder / Read Data
    • Read Attributes
    • Read Extended Attributes
    • Create Folders / Append Data
    • Delete
    • Read Permissions


    Screen shot of Permission Entry for NetShare dialog box

  15. Click OK on all open dialog boxes.

On Windows 2008 Systems

To create an agent data file share and set all permissions on a Windows 2008 system:

  1. Create a new folder. The file share should not be located on a specific user’s desktop. Record the folder UNC path for use during the agent installation process.
  2. Right click on the folder name and select Properties from the popup menu to display the Properties dialog.
  3. Select the Sharing tab. Select the Share button to display the File Sharing dialog.
  4. Enter Authenticated Users in the text entry field. Click Add.
  5. Select the Authenticated Users group and click on Contributor in the drop-down menu.
  6. Click Share. When the operation is complete, click Done.
  7. Select the Security tab, select Authenticated Users from the list of groups and user names. Click the Advanced button to display the Advanced Security Settings dialog.
  8. Select Authenticated Users from the list of permission entries and click Edit to display the Advanced Security Settings dialog.
  9. Deselect the checkbox which enables child objects to inherit permission entries from the parent. (The specific checkbox label may vary based on the operating system.) When this setting is disabled, a Security dialog is displayed advising you that permission entries will no longer be inherited. Click Remove.
  10. Select Authenticated Users from the list of permission entries and click Edit to display the Permission Entry dialog.
  11. Select This folder only from the Apply to drop down menu.
  12. Ensure that the following permissions are allowed:
    • List Folder / Read Data
    • Read Attributes
    • Read Extended Attributes
    • Create Folders / Append Data
    • Delete
    • Read Permissions
  13. Click OK on all open dialog boxes.

Prerequisites for Installing EdgeSight Agents

Before installing the agent in a virtual desktop environment, you must perform the following tasks:
  1. Ensure that you have the information required during agent installation.
  2. Place the group of virtual desktops in maintenance mode and then shut them down.
  3. Set the vDisk access mode to private.
    Note: This procedure assumes that you are working with an existing master image. You can also install the agent as part of creating a master image prior to sharing the image out to the pool.

Shutting Down Virtual Desktops

Important: Before shutting down virtual desktops, ensure that they are not in use to avoid loss of data.

Before installing the agent in a virtual desktop environment, you must ensure that the virtual desktops are in maintenance mode and are then shut down. To set the virtual desktops to maintenance mode and shut them down:

  1. Log on to the Desktop Delivery Controller (DDC) for the target desktop group and open the Citrix Access Management Console.
  2. Navigate to Citrix Resources > Desktop Delivery Controller > FarmName > Desktop Groups and click on the target group to display a list of the virtual desktops.
  3. Select all desktops in the group and right click on the group to display the pop-up menu. Select Enable maintenance mode to temporarily stop connections to the desktops.
  4. Right click on the group again and select Shutdown/suspend from the pop-up menu to display the Shutdown/suspend dialog.
  5. Select Shut down from the drop-down menu and click OK. (You may need to refresh the display to update the status displayed for the desktops.)

Setting the vDisk Access Mode to Private

You must set the access mode property for the vDisk associated with the target desktop group.

  1. Log on to the Provisioning Server associated with the vDisk on which the EdgeSight Agent will be installed and start the Provisioning Server Console.
  2. Navigate to FarmName > Stores and select the store associated with the target vDisk.
  3. Right click on the vDisk and select Properties from the pop-up menu.
  4. Click on the Edit file properties button to display the vdisk File Properties dialog.
  5. Select the Mode tab.
  6. Select Private access (single device, R/W access) from the Access Mode drop down menu and click OK.
  7. Click OK in the vdisk File Properties dialog.

Information Required During Agent Installation

Ensure that you have the following information at hand before installing the agent software on the master image:

  • The UNC path name of the agent data file share. The Network Service that will be running on desktops will need to be able to create directories and copy files to this share.
  • The fully-qualified domain name or IP address of the EdgeSight Server that will be acting as the database broker. In addition to the server name you can specify the port and SSL or proxy server information, if used.
  • 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. The pool name corresponds to the XenDesktop desktop group name.

Installing the Agent

You install the EdgeSight for Virtual Desktops Agent or the EdgeSight for Endpoints Agent on the master image. During the installation, you indicate that the agent is being installed on virtual desktops. After the agent installation is complete, you must reboot your master image.

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 and will host the agent database server and the agent data file share 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.

If you are running a firewall on the machine hosting the agent database server, the port used to communicate with EdgeSight agents must be open. The default port is 9037.

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 which 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 topic.

Agent Installation Methods

The MSI file uses public properties to specify custom install settings. You can set 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. See Installing EdgeSight Agents Using the Command Line for definitions of the public properties used when installing the EdgeSight agent.

Installing an Agent Using the User Interface

Note that not all public properties listed in Installing EdgeSight Agents Using the Command Line 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 EdgeSight for Virtual Desktops Agent or EdgeSight for Endpoints Agent 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. If you are installing an EdgeSight for Virtual Desktops agent for monitoring instances of XenDesktop 4.0 or later, the department field cannot be set because the department is determined by the XenDesktop Farm structure. 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. If an SSL network connection is required, select the Use SSL checkbox. (This is equivalent to setting the CONNECTION_FLAGS property.)
  11. 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.
  12. Select the Configure the agent for virtual desktops checkbox.
  13. In the Remote UNC Path field, enter the UNC path for the agent data file share, for example \\Myserver.mydomain.com\AgentFiles. For information on setting up the file share, see "Setting UP the Agent Data File Share".
  14. In the Pool Name field, enter 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, as described in "Install Agent Database Server".
  15. In the Database Broker field, enter the fully-qualified domain name of the EdgeSight Server which will be acting as the database broker. (The database broker components are installed on every EdgeSight Server and cannot be installed separately or moved.)
  16. If an SSL network connection is required, select the Use SSL checkbox.
  17. 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. Click Next to display the Ready to Install screen.
  18. If you need to review or change any settings before installing, use the Back button to return to the configuration screens.
  19. Click Install to begin the installation. When the installation is complete, the Setup Complete screen is displayed.
  20. Click Finish to complete the installation. The Installer Information dialog prompts you to reboot your system so that configuration changes will be applied.
  21. Click Yes to reboot your machine. It is recommended that you flush the DNS cache after rebooting the machine (ipconfig /flushdns). This can help prevent errors related to DNS caching when the agent initially accesses the network.

Installing an Agent Using the Command-Line Interface

Use the msiexec command to install the agent using the command-line interface. Public properties are specified as KEY=value pairs as described in Installing EdgeSight Agents Using the Command Line. If a property has a default value, that value is used if the property is not specified on the command line. When performing an installation in a virtual desktop environment 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.
  • POOLED_INSTALL—This flag and the following properties are required so that the agent can communicate with the database broker components of EdgeSight Server and can copy and retrieve files from the agent data file share.
  • REMOTE_PATH
  • IMAGE_POOL
  • DBBROKER_FQDN
  • BROKER_PORT

ALLOWSERVEROS should be specified if you attempt to install a Citrix EdgeSight for Endpoints agent on a system running a server OS. 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.

ALLOWVIRTUAL should be specified if you attempt to install an EdgeSight for Endpoints agent on a virtual desktop instance running XenDesktop 4.0 or later. 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 virtual desktop system:

Msiexec /i EdgeSightEPAgentx64.msi /l logfile.log /q 
SERVER_NAME=Myserver COMPANY=Mycompany DEPARTMENT=Mydept 
POOLED_INSTALL=1 REMOTE_PATH=”\\Myserver.mydoain.com\AgentFiles” 
IMAGE_POOL=Pool2 DBBROKER_FQDN=Myserver.dom1.com BROKER_PORT=80

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.

Deploying the Agent to Virtual Desktops in a Pool

To deploy the agent to the virtual desktops in a pool, perform the following tasks:
  1. Shut down the master image.
  2. Set the access mode property for the vDisk associated with the target desktop group to Standard Image.
  3. Disable maintenance mode on the desktop group.
    Note: This procedure assumes that you are working with an existing master image. You can also install the agent as part of creating a master image prior to sharing the image out to the pool. If you are not working with an existing vDisk, create the vDisk at this point in the procedure.

Shutting Down the Master image

The master image must be shut down so that the access mode property for the vDisk can be changed.

Setting the vDisk Access Mode

You must set the access mode property for the vDisk associated with the target desktop group.

  1. Log on to the Provisioning Server associated with the master image on which the EdgeSight Agent was installed and start the Provisioning Server Console.
  2. Navigate to FarmName > Stores and select the store associated with the target vDisk.
  3. Right click on the vDisk and select Properties from the pop-up menu.
  4. Click on the Edit file properties button to display the vdisk File Properties dialog.
  5. Select the Mode tab.
  6. Select Standard Image (multi-device, write-cache enabled) from the Access Mode drop down menu and click OK.
  7. Click OK in the vdisk File Properties dialog.

Disabling Maintenance Mode

To enable normal operation by the virtual desktops, you must ensure that maintenance mode is disabled. To disable maintenance mode for the desktop group:

  1. Log on to Desktop Delivery Controller (DDC) for the target desktop group and open the Citrix Access Management Console.
  2. Navigate to Citrix Resources > Desktop Delivery Controller > FarmName > Desktop Groups and click on the target group. A list of the virtual desktops is displayed.
  3. Select all desktops in the group and right click on the group to display the pop-up menu. Select Disable maintenance mode.

Post-Installation Configuration

You may need to change incorrect configuration settings using the agent’s control panel application.

Agent Database Connection Acquisition

When you configure the agent for virtual desktops, file monitor components are installed which manage copying files to and retrieving files from the agent data file share. The agent is configured to contact the database broker to receive a database connection string. If it fails to get a database connection, it shuts down and writes error information to the local SYS_EVENT_TXT.TXT log. If the file monitor components are functioning properly, a copy of the log file will also be placed on the agent data file share. You can change incorrect configuration settings using the agent’s control panel application. However, you must make those changes on the master image in order for them to be propagated to all desktops.

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.

In a virtual desktop environment, any changes to these settings must be made on the master image and then deployed to the pool.

The Service Control tab is disabled by default for EdgeSight for Virtual Desktops and 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.

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. Select the Remote Share tab. Edit the UNC path to the agent data file share as required.
  3. Select the EdgeSight Server tab. Edit the Citrix EdgeSight Server address and port number as required.
  4. 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.
  5. 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.
  6. Select the Broker Server tab. Edit the address and port number for the EdgeSight Server acting as the database broker as required. You can also edit SSL and proxy server settings as described in steps 4 and 5.
  7. When you have made all required settings changes, click OK to apply the changes and close the dialog.
    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.