Install PerformanceGuard Agents

Owned by Martin Moghadam
Last updated: Nov 18, 2021 by Henrik Wendt
7 min read

You can install PerformanceGuard agents all Windows platforms, including application servers and Citrix servers.
There are two different PerformanceGuard agent installation packages: One for computers with 32-bit operating systems, and one for computers with 64-bit operating systems. The agent version must match the operating system version. If you're in doubt about whether a computer has a 32-bit or a 64-bit operating system, look under Control Panel > System on the computer in question.

Quick Installation


Prerequisites:

  1. You must install the PerformanceGuard agent with local administrator rights on the computer.
  2. You must know the IP address or hostname of your PerformanceGuard frontend server.
  3. The computers that you want to install the PerformanceGuard agent on must have Windows Installer (2.0 or newer). They typically have. If in doubt, go to msdn.microsoft.com and search for Windows Installer.
  4. Download and unzip the PerformanceGuard agent installer. Download and unzip the PerformanceGuard agent installer from CapaSystems wiki.

Double-click the installer (.msi) file to install the agent. The installation usually takes less than a minute. There is no need to restart the computer after installation.
I've just installed an agent. Now I want to view startup data from the agent in PerformanceGuard. How can I speed up that process?  Because the computer doesn't need to be restarted when you install the agent, it can take a while before you get startup data from the agent. You can of course restart the computer in order to speed up the process, but for technical reasons, you should wait at least ten minutes after installing the agent before you restart the computer.

Command-Line Installation


You can also install the PerformanceGuard agent via a command line:

msiexec /i XXXXX.msi IP=xx.xx.xx.xx PORT=4001


Replace XXXXX.msi with the name of the agent installation file (note that names are different, depending on whether you use a 32-bit or a 64-bit agent installation file).
Replace xx.xx.xx.xx with the IP address or fully qualified domain name of your PerformanceGuard frontend server.

Installation Options


If required, you can run the agent installation file with a number of parameters:

Logging


It's good to have a log file if you run into problems and need to contact PerformanceGuard support. The log file can help supporters quickly diagnose the problem. You generate the log file, called install.log, with these parameters:

msiexec /lx!*v install.log /i XXXXX.msi

Replace XXXXX.msi with the name of the agent installation file (note that names are different, depending on whether you use a 32-bit or a 64-bit agent installation file).
Log generation also works when you remove agents.

Custom Encryption


It is recommended to use a custom encryption key when you install Agents for your AutoSteps, read further more below in Installation Guidelines:

msiexec /i XXXXX.msi ENCRYPTION=2 AESKEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Replace XXXXX.msi with the name of the agent installation file (note that names are different, depending on whether you use a 32-bit or a 64-bit agent installation file).
Replace xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx with the 128 bit long custom key.
The custom key should be written in hexadecimal. The key encryption should be based on valid numbers used in hexadecimal i.e. should be between 0-9 and A-F with 32 characters.

Service Start Delay


You can specify that the agent should wait for a certain number of seconds before it starts its service. This can occasionally be useful in order to ensure that the agent measures performance on the required network adapter (NIC) if a computer has more than one adapter.

The PerformanceGuard agent service starts very quickly. However, the agent service may simply start too fast on a Windows 8 computer with two network adapters, one for PXE network boot and one for all other purposes: The fast-starting agent would begin to measure performance on the adapter that's active when the agent service starts (the adapter used for PXE), whereas you want it to measure performance on the computer's other adapter (which isn't used until some seconds later). You, therefore, specify a delay for the agent service so that it starts when the PXE boot is completed, and the computer uses the adapter that it's relevant to measure performance.

In that case, apply the /ssd (service start delay) parameter and the required number of seconds (must be an integer) to the MSI installer command line when you install the agent.

Example (where the service start delay should be 20 seconds):

msiexec /i XXXXX.msi IP=xx.xx.xx.xx PORT=4001 ssd=20


Replace XXXXX.msi with the name of the agent installation file (note that names are different, depending on whether you use a 32-bit or a 64-bit agent installation file).
Replace xx.xx.xx.xx with the IP address or fully qualified domain name of your PerformanceGuard frontend server.


How long a delay should I specify?  That depends on the computer that the agent is installed on. You may need to experiment with different delays before you find the optimal one. If in doubt, start out with a delay between 5-20 seconds, and then adjust the delay if required.


Will the delay affect the agent's startup measurements?  No, the agent will measure the computer's startup times correctly despite the delay. However, a long delay might affect the agent's login measurements, see the following note.


Don't set a service start delay that's so long that the agent service doesn't start up in time to measure login performance.

You can also specify the service start delay as a registry key parameter after the agent has been installed. See Agent Registry Keys in the Technical Reference section.

Silent Installation


If you deploy the agent to multiple client computers via a software distribution tool, you may want to keep the installation process completely transparent to the end-users.

In that case, apply the /q (quiet) and /n (don't ask) parameters to the MSI installer command line when you install the agent:

msiexec /i XXXXX.msi IP=xx.xx.xx.xx PORT=4001 /qn

Replace XXXXX.msi with the name of the agent installation file (note that names are different, depending on whether you use a 32-bit or a 64-bit agent installation file).
Replace xx.xx.xx.xx with the IP address or fully qualified domain name of your PerformanceGuard frontend server.


Installation Parameters


Name

Description

Default Value

IP=<server_ip>

The IP address or hostname of the PerformanceGuard Frontend server that the agent should connect to.

performanceguard

PORT=<port_no>

The TCP port number on which the PerformanceGuard Frontend server must listen for data from the agent.

4001

GROUP=<group_hint>

The agent configuration group into which the agent will be placed when it first connects.

Default

AGENT_ID=<agent_id>

The agent identifier. The agent_id parameter is most often used if you re-install the entire PerformanceGuard system, server as well as all agents. In this case, set it to agent_id=0. This will force the agent to retrieve a new ID from the server.
Only use this parameter if you are an experienced PerformanceGuard administrator. If you use this parameter without a clear understanding of the implications, you may corrupt agent configuration groups.
Be careful not to give several agents the same agent_id. You may of course assign an agent_id of zero to several agents.

0

SSD=<service_start_delay>

Defines the amount of time for which the agent will wait before it attaches to the network. On some hardware configurations, this value must be set to a value larger than zero, otherwise, the agent won't be able to collect network data. By default, this parameter isn't set.

 

ENCRYPTION="<0, -1, 1, -2 or 2>"

Defines whether the agent should use encryption when it communicates with the Frontend server.

  1. 0: Don't use encryption
  2. -1: Use encryption if the Frontend server supports encryption
  3. 1: Force use of encryption (that is: don't communicate with Frontend servers that don't support encryption)
  4. -2: Use custom defined encryption if the Frontend server supports encryption
  5. 2: Force use of custom-defined encryption

-1

AESKEY="<128bit key>"

It defines the custom key used when the agent encrypts data that it sends to the Frontend server.

No



Installation Procedure


  1. Navigate to the folder in which you placed the downloaded PerformanceGuard installer.
    2. Start the installation.
  2. Read and accept the end-user license agreement, and then click Next.
  3. Add PerformanceGuard server parameters where you want to install the agent(s).
    2. Specify settings for the PerformanceGuard web server:

      1. Server Address: The address of the PerformanceGuard Frontend server (collector) that the agent should connect to. 

        The server address must be the same DNS name as the name of the machine where PG Frontend is installed. We recommend that you should always use the same DNS name - otherwise you will need to reinstall if the address on the Frontend changes.

      2. Server Port: The TCP port number on which the PerformanceGuard Frontend server must listen for data from the agent. We recommend that you use port 4001 unless your organization's firewall administrator has told you to use another port.

    3. Specify settings for the Custom Encryption: 

      We recommend using the Custom Encryption features as it encrypts all the communication between the (collector) Frontend and the Backend.


      1. Enabled: Uses custom-defined encryption if the Frontend server supports encryption.
      2. Strong: Force use of custom-defined encryption. You can read more about encryption and AES key in Complete List of Installation Parameters

      3. Encryption Key (128bit): It is recommended to create an encryption key to ensure secure communication between PG Agent(s) and Frontend. Create a key consisting of Hexadecimals with 32 characters (as it uses four-bit binary coding i.e. with 4 bits, it is possible to create 16 different values. All single-digit hexadecimal numbers can be written with four bits.).


    4. The encryption key should be written in Hexadecimal. The key encryption should be based on valid numbers used in hexadecimal i.e. should be between 0-9 and A-F with 32 characters.

      Example:If you have created a key that is less than 32 characters or contains invalid symbols then you will get an invalid key error. 

      When ready, click Next.


  4. When the installation is complete, click Finish

  5. Check PerformanceGuard Agent has been installed successfully in your programs: Settings > Apps > Apps & Features.

Upgrade

See Agent Upgrade

Repair


It's possible to repair an agent. This means that it's possible to re-install the files for a client if the files have been corrupted or overwritten:

msiexec /f XXXXX.msi /qn

Replace XXXXX.msi with the name of the agent installation file (note that names are different, depending on whether you use a 32-bit or a 64-bit agent installation file).
A repair will recover the files used by the PerformanceGuard agent, but won't change or modify the configuration for a given agent.

Search this documentation

On this page

In this section