Important Prerequisites

• A computer/server with:
  • a 64-bit Microsoft Windows operating system (view supported Windows versions)
  • Microsoft .NET Framework 4.6 or newer

  • PerformanceGuard 7.5 and newer uses OpenJDK included in the installation file 

    For PerformanceGuard versions 7.4 or older you must install Java JDK 8 update 181 or later(see Install Java JDK)

• Administrative rights on the computer that you are going to perform the installation on (local administrator).

• A Microsoft SQL Server (MS SQL Server 2012 or newer, either on the same computer as PerformanceGuard or on a dedicated server). 

   Can I use SQL Server Express?

  SQL Server Express is only suitable for very small PerformanceGuard installations (less than 100 users) because SQL Server Express has an upper limit on its database size.

  PerformanceGuard doesn't itself use SQL Server Enterprise features, but you may use them in case you want to exploit more memory on large installations.

• During installation you'll get the option of authenticating service access to the PerformanceGuard databases through the Windows credentials of one or more existing Active Directory users. If you intend to use that option, make sure that the relevant user accounts have been set up in Active Directory.
• During installation you'll specify the user accounts that will run the various components of PerformanceGuard. If you are going to use Windows authentication (see the previous item), it is important that the user accounts have:
  • Full access to the folder in which you'll install the component in question
  • Full access to the Windows registry on the computer in question
• Download the PerformanceGuard installer. Download the PerformanceGuard installer from CapaSystems wiki.

Installation Procedure

1. Start an elevated Windows command prompt and navigate to the folder in which you placed the downloaded PerformanceGuard installer. 

    What's an elevated command prompt?

   It is a command prompt that's able to execute commands with administrative privileges. To get an elevated command prompt, click  /Start, type cmd, right-click Command Prompt in the search results, and select Run as administrator.

2. Start the installation with the following command (plus any optional values—optional values are described in the following):  

   msiexec /i PerformanceGuard.msi /L*v! installLog.txt

   The /L*v! parameter in the command makes sure that the installer records a log file of the installation. In this case the log file will be called installLog.txt. The log file will be available at the location from which you run the installation, so if you run the installation file from C:\, the log file will be placed under C:\ too. 

   PerformanceGuard is by default installed in C:\Program Files\PerformanceGuard. If you want to install PerformanceGuard at another location, for example on the D: drive, add an INSTALLFOLDER parameter to the command, like in the following example where PerformanceGuard is going to be installed on the D: drive:

   msiexec /i PerformanceGuard.msi /L*v! installLog.txt INSTALLFOLDER="D:\PerformanceGuard"

   If you are installing on a Windows Server CORE (a type of server that doesn't have a graphical user interface), add the following to the command: 

   "/q"

   When the installer open window opens, click Next.

3. Read and accept the end-user license agreement, and then click Next.

4. Select which PerformanceGuard components you want to install.

   

    Which components do you recommend that I install?

   You should install all of the components. Most users simply install all of the components on the same computer, but in some environments it can make sense to install the Frontend server, Backend server and PerformanceGuard web interface on separate computers to achieve optimal performance. If required, you can even install more than one Frontend server to distribute the load. Read more about Multiple Frontend Servers.

   Then select the location at which you want to install PerformanceGuard. If you don't select a location yourself, PerformanceGuard will be installed in C:\Program Files\Performanceguard\. 

   When ready, click Next.
5. This step applies if you selected to install the FRONTEND server. 

   The frontend server runs as a service. Its job is to receive data from PerformanceGuard agents and store the data in a database from where the other components of the PerformanceGuard solution can get the data. You need to specify some details about that database:

   

1. • Installation: Select New installation of Frontend database.

   • Frontend database server: Which SQL Server should run the Frontend database? If the SQL Server that you want to use exists on the computer that you are installing the Frontend server on, simply use the localhost default setting. If you have another SQL Server on your network, and you want to install the Frontend server's database on that server, click the browse button next to the field and select the required SQL Server. 

     If your SQL Server uses another port than the default port 1433, you can add the port number after the server address. Example: localhost:6789

     If you want to use a particular instance on your SQL Server, you can add the instance name after the server address, separated by a backslash. You can also combine instance and port information if required. Examples: localhost\instance or localhost\instance:6789

   • Frontend database: The name of the Frontend server database. The name is normally pguardfe, but you can change that if required.
   • Frontend authentication: Select either ...
     • SQL Server Authentication where access to the Frontend server database will be authenticated by the SQL Server
     • or
     • Windows Authentication where access to the Frontend server database will be authenticated through the Windows credentials of an existing Active Directory use
   • Frontend database user: In order to communicate with the Frontend server database, PerformanceGuard needs access to the database with a user account.
     • If using SQL Server authentication the name of that user account is normally pguardfe, but you can change the name if required.
     • If you use Windows authentication, you must specify the user name of an existing Active Directory user.
   • Frontend AD domain (only relevant if you selected Windows Authentication): Specify the domain that the Active Directory user belongs to.
   • Frontend database password: Specify the password that PerformanceGuard should use when it accesses the Frontend server database with the user account that you specified previously. 

     • If you use SQL Server authentication, the password must follow the password policy for the SQL Server that you use. 

       View Microsoft's SQL Server password policies (link applies for SQL Server 2012, but you can select other SQL Server versions on the page).

     • If using Windows authentication specify the password of the Active Directory user.
   • When ready, click Next.

      6. This step applies if you selected to install the FRONTEND server.

In order to create the Frontend server database on the selected SQL Server, PerformanceGuard needs to know the following:

1. • Let the installer run the SQL scripts against the database: Determines whether the PerformanceGuard installer should create the Frontend server database for you automatically (recommended). If you select this option, you must provide system administrator credentials for the selected SQL Server in the following fields.
   • Authentication: SQL Server system administrator (SA) rights are required in order to create the Frontend server database. Select how the system administrator should be authenticated:
     • SQL Server Authentication where system administrator access will be authenticated by through the SQL Server
     • or
     • Windows Authentication where system administrator access will be authenticated through the Windows credentials of an existing Active Directory user

   • SA database user: Specify the user name of the SQL Server's system administrator account. 

     This must be a different user than the frontend database user that you specified previously.

• • • If using SQL Server authentication the name of that account is normally sa, but you can change the name if required.
    • If using Windows authentication you must specify the user name of an existing Active Directory user that has system administrator rights on the SQL Server.
  • SA user AD domain (only relevant if you selected Windows Authentication): Specify the domain that the Active Directory user belongs to.
  • Password for SA: Specify the password of the SQL Server's system administrator account.

Use the Test Connection button to verify that the connection to the database is working. 

When ready, click Next.
 
      7. This step applies if you selected to install the FRONTEND server.

By default, Frontend server database files will be placed at the SQL Server's default location for new databases (<Server default>). That's usually fine, but occasionally it may not be the best choice, for example if you expect to collect a lot of data, but there isn't much available disk space at the default location. That's why you are able to specify your own paths for data files as well as log files.

When ready, click Next.
 

      8. This step applies if you selected to install the FRONTEND server.

Specify communication settings for the Frontend database:

1. • Frontend server TCP port: On which TCP port should the Frontend server listen for data from agents? We recommend that you use port 4001 unless your organization's firewall administrator has told you to use another port.
   • Backend server host name: Your Frontend server is going to regularly communicate with the PerformanceGuard Backend server. That's why you must specify where the Frontend server will be able to find the Backend server. If you are installing everything on the same computer, simply use the localhost default setting. If the Backend server is going to be installed on another computer, specify the hostname or IP address of that computer.
   • AES key (optional): The AES key ensures a secure communication between PG Agent(s) and Frontend. Therefore it is recommended to specify an AES key, which you created when you installed the agents, otherwise the communication will be less secured.

When ready, click Next.
 
      9. This step applies if you selected to install the WEB INTERFACE.

Specify settings for the PerformanceGuard web server:

1. • Primary and Secondary web server port: PerformanceGuard has a web server service that runs the PerformanceGuard web interface. The web server needs to use two TCP ports. Make sure that no other applications use those ports. 

     When you move on, the installer automatically checks the availability of the ports that you specify.

     If you run into problems with port 80, see the troubleshooting article Port 80 Is Used by Another Service.

   • Use SSL: enable HTTPS. Change the port numbers to 443 and 8443 and add the Certificate File Path, The path to the certificate file on the local machine and the Certificate Password.

When ready, click Next.
 
      10. This step applies if you selected to install the BACKEND server.

The Backend server runs as a service. Its primary job is to receive and aggregate data from the Frontend server(s).

1. • Installation: Select New installation of Backend database.

   • Backend database server: Which server should run the Backend server database? If the SQL Server that you want to use exists on the computer that you are installing the Backend server on, simply use the localhost default setting. If you have another SQL Server on your network, and you want to install the Backend server's database on that server, click the browse button next to the field and select the required SQL Server. 

     If your SQL server uses another port than the default port 1433, you can add the port number after the server address. Example: localhost:6789

     If you want to use a particular instance on your SQL Server, you can add the instance name after the server address, separated by a backslash. You can also combine instance and port information if required. Examples: localhost\instance or localhost\instance:6789

• • Backend database: The name of the Backend server database. The name is normally pguard, but you can change that if required.
  • Backend authentication: Select either ...
    • SQL Server Authentication where access to the Backend server database will be authenticated by the SQL Server
    • or
    • Windows Authentication where access to the Backend server database will be authenticated through the Windows credentials of an existing Active Directory user
  • Backend database user: In order to communicate with the Backend database, PerformanceGuard needs access to the database with a user account.
    • If using SQL Server authentication the name of that user account is normally pguard, but you can change the name if required.
    • If you use Windows authentication, you must specify the user name of an existing Active Directory user.
  • Backend AD domain (only relevant if you selected Windows Authentication): Specify the domain that the Active Directory user belongs to.
  • Backend database password: Specify the password that PerformanceGuard should use when it accesses the Backend server database with the user account that you specified previously.

    • If you use SQL Server authentication, the password must follow the password policy for the SQL Server that you use. 

      View Microsoft's SQL Server password policies (link applies for SQL Server 2012, but you can select other SQL Server versions on the page).

• • • If using Windows authentication specify the password of the Active Directory user.

When ready, click Next.
 
      11. This step applies if you selected to install the BACKEND server.

The Backend server must know where to find the service that runs the PerformanceGuard web interface:

1. • Display hostname or ip: Specify the hostname or IP address of the computer that will run the PerformanceGuard Web Server service, which is the service that runs the PerformanceGuard web interface. If the service should run on the computer that you are currently installing on, simply use the default value localhost. The value of the Display TCP Port field is determined by a setting that you specified in step 9.

When ready, click Next.
 
      12. This step applies if you selected to install the BACKEND server.

In order to create the Backend server database on the selected SQL Server, PerformanceGuard needs to know the following:

1. • Let the installer run the SQL scripts against the database: Determines whether you want to let the PerformanceGuard installer create the Backend server database for you automatically (recommended). If you select this option, you must provide system administrator credentials for the selected SQL Server in the following fields.
   • Authentication: SQL Server system administrator (SA) rights are required in order to create the Backend server database. Select how the system administrator should be authenticated:
     • SQL Server Authentication where system administrator access will be authenticated by through the SQL Serve
     • or
     • Windows Authentication where system administrator access will be authenticated through the Windows credentials of an existing Active Directory user
   • SA database user: Specify the user name of the SQL Server's system administrator account.

This must be a different user than the backend database user that you specified previously.

• • • If using SQL Server authentication the name of that account is normally sa, but you can change the name if required.
    • If using Windows authentication you must specify the user name of an existing Active Directory user that has system administrator rights on the SQL Server.
  • SA database user: Specify the user name of the SQL Server's system administrator account.
  • SA user AD domain(only relevant if you selected Windows Authentication): Specify the domain that the Active Directory user belongs to.
  • Password for SA: Specify the password of the SQL Server's system administrator account.

Use theTest Connectionbutton to verify that the connection to the database works. 

When ready, click Next.
 
      13. This step applies if you selected to install the BACKEND server.

By default, Backend server database files will be placed at the SQL Server's default location for new databases (<Server default>). That's usually fine, but occasionally it may not be the best choice, for example if you expect to collect a lot of data, but there isn't much available disk space at the default location. That's why you are able to specify your own paths for data files as well as log files.

When ready, click Next.
 
      14. This step applies if you selected to install the BACKEND server.

Specify communication settings for the Backend database:

1. • Backend server TCP port: On which TCP port should the Backend server deliver data? We recommend that you use port 4008 unless your organization's firewall administrator has told you to use another port.

When ready, click Next.
 
      15. Click Install to execute the installation with the settings that you have specified.

 
      16. When installation is complete, click Finish.

Optional Parameters and Values

Installation Location

1. INSTALLFOLDER: Full file system path to the folder where you want PerformanceGuard to be installed. Default value: %ProgramFiles% (usually C:\Program Files)

Frontend Server Options

1. FE_DB_HOST: Hostname or IP address of the SQL Server that should be used for the PerformanceGuard Frontend server database. Default value: localhost

If your SQL server uses another port than the default port 1433, you can add the port number after the server address. Example: localhost:6789
If you want to use a particular instance on your SQL Server, you can add the instance name after the server address, separated by a backslash. You can also combine instance and port information if required. Examples: localhost\instance or localhost\instance:6789

1. FE_DATADIR: Path to the folder in which the Frontend server's database should be installed. Default value is <Server default>, which means that the SQL server's default database folder will be used.
2. FE_LOGDIR: Path to the folder in which the Frontend server's database transaction log files should reside. Default value is <Server default>, which means that the SQL server's default log folder will be used.
3. FE_DB_NAME: Name of Frontend server database. Default value: pguardfe
4. FE_DB_FILESIZE: Initial database file size limit (in MB) for the Frontend server's data files. Default value: 500
5. FE_DB_INCSIZE: Database file size increment limit (in MB) for the Frontend server's data files. Default value: 1000
6. FE_DB_AUTH: Authentication method for the Frontend server database. 1 = SQL Server authentication, 2 = Windows authentication.

Example: FE_DB_AUTH = 1 means that SQL Server authentication must be used for the Frontend server database.

1. FE_DB_USER: User name that should be used to access the Frontend server's database. Default value: pguardfe
2. FE_DB_PASSWORD: Password that should be used to access the Frontend server's database.
3. FE_DB_DOMAIN: Domain that the Frontend server database user belongs to.

This parameter is only relevant if you use Windows authentication. Don't use this parameter with SQL Server authentication.

1. FE_DB_SA_AUTH: Authentication method for the SQL Server's system administrator (sa) account when installing the Frontend server database. 1 = SQL Server authentication, 2 = Windows authentication.

Example: FE_DB_SA_AUTH = 1 means that SQL Server authentication must be used for the system administrator (sa) user.

1. FE_DB_SA_USER: User name for the SQL Server's system administrator (sa) account. Default value: sa
2. FE_DB_SA_PASSWORD: Password for the SQL Server's system administrator (sa) account.
3. FE_DB_SA_DOMAIN: Domain that the SQL Server's system administrator (sa) account belongs to.

This parameter is only relevant if you use Windows authentication. Don't use this parameter with SQL Server authentication.

1. FE_SERVICE_USER: The user account that runs the PerformanceGuard Frontend Server service.

Example: ourcompany\serveradmin

1. FE_SERVICE_PASSWORD: Password of the user account that runs the PerformanceGuard Frontend Server service.

Backend Server Options

1. BE_DISPLAY_HOST: Hostname or IP address of the computer that runs the PerformanceGuard backend server. Default value: localhost
2. BE_DB_HOST: Hostname or IP address of the SQL Server that should be used for the backend server database. Default value: localhost

If your SQL server uses another port than the default port 1433, you can add the port number after the server address. Example: localhost:6789
If you want to use a particular instance on your SQL Server, you can add the instance name after the server address, separated by a backslash. You can also combine instance and port information if required. Examples: localhost\instance or localhost\instance:6789

1. BE_DATADIR: Path to the folder in which the Backend server's database should be installed. Default value is <Server default>, which means that the SQL server's default database folder will be used.
2. BE_LOGDIR: Path to the folder in which the Backend server's database transaction log files should reside. Default value is <Server default>, which means that the SQL server's default log folder will be used.
3. BE_DB_NAME: Name of Backend server database. Default value: pguard
4. BE_DB_AUTH: Authentication method for the Backend server database. 1 = SQL Server authentication, 2 = Windows authentication.

Example: BE_DB_AUTH = 1 means that SQL Server authentication must be used for the Backend server database.

1. BE_DB_USER: SQL Server user name that should be used to access the Backend server's database. Default value: pguard
2. BE_DB_PASSWORD: SQL Server password that should be used to access the Backend server's database.
3. BE_DB_DOMAIN: Domain that the Backend server database user belongs to.

This parameter is only relevant if you use Windows authentication. Don't use this parameter with SQL Server authentication.

1. BE_DB_SA_AUTH: Authentication method for the SQL Server's system administrator (sa) account when installing the Backend server database. 1 = SQL Server authentication, 2 = Windows authentication.

Example: BE_DB_SA_AUTH = 1 means that SQL Server authentication must be used for the system administrator (sa) user.

1. BE_DB_SA_USER: User name for the SQL Server's system administrator (sa) account. Default value: sa
2. BE_DB_SA_PASSWORD: Password for the SQL Server's system administrator (sa) account.
3. BE_DB_SA_DOMAIN: Domain that the SQL Server's system administrator (sa) account belongs to.

This parameter is only relevant if you use Windows authentication. Don't use this parameter with SQL Server authentication.

1. BE_SERVICE_USER: The user account that runs the PerformanceGuard Backend Server service.

Example: ourcompany\serveradmin

1. BE_SERVICE_PASSWORD: Password of the user account that runs the PerformanceGuard Backend Server service.

Combined Frontend Server/Backend Server Options

1. BACKEND_HOSTNAME: The Backend server hostname that the Frontend server should use when connecting to the Backend server. Default value: localhost
2. BACKEND_PORT: The TCP port on which the Backend server will accept connections from the Frontend server. Default value: 4008
3. BACKEND_CONNECTIONS: The maximum number of connections that the Frontend server should open against the Backend server. Default value: 10
4. BACKEND_TIMEOUT: The number of seconds after which the Frontend server/Backend server sockets will time out. Default value: 90000

Web Interface Options
The following options relate to the PerformanceGuard web server service that runs the PerformanceGuard web interface.

1. MERLINPORT: The primary TCP port that the PerformanceGuard web server should use: Default value: 80
2. PGUARDPORT: The secondary TCP port that the PerformanceGuard web server should use: Default value: 81
3. PGUARDSECURE: Determines whether the PerformanceGuard web server should use HTTPS or not. Set to true if the PerformanceGuard web server should use HTTPS, set to false to use HTTP for the web server. Default value: false

Examples of installation commands

The following are examples only, your actual installation command will depend on what you want to achieve.

Install PerformanceGuard with T0p53cr3t as the password for the Backend and Frontend server databases, and log the installation progress in the file install.log:

msiexec /L*v! install.log /i PerformanceGuard.msi BE_DB_PASSWORD=T0p53cr3t FE_DB_PASSWORD=T0p53cr3t

Install PerformanceGuard with T0p53cr3t as the password for the Backend and Frontend server databases, and let the PerformanceGuard web server use TCP port 9000 as its secondary port:

msiexec /i PerformanceGuard.msi BE_DB_PASSWORD=T0p53cr3t FE_DB_PASSWORD=T0p53cr3t PGUARDPORT=9000

Install PerformanceGuard with T0p53cr3t as the password for the Backend and Frontend server databases, and let the databases reside on a separate SQL Server named sql-cluster:

msiexec /i PerformanceGuard.msi BE_DB_HOST=sql-cluster FE_DB_HOST=sql-cluster BE_DB_PASSWORD=T0p53cr3t FE_DB_PASSWORD=T0p53cr3t

Install PerformanceGuard in the folder C:\Performanceguard (make sure to use this option if you are performing this installation as last step of an upgrade) with T0p53cr3t as the password for the Backend and Frontend server databases:

msiexec /i PerformanceGuard.msi INSTALLFOLDER="C:\Performanceguard" BE_DB_PASSWORD=T0p53cr3t FE_DB_PASSWORD=T0p53cr3t

Multiple Frontend Servers

The idea behind using multiple PerformanceGuard Frontend servers is to distribute the load.
If you want to install multiple Frontend servers, simply run the PerformanceGuard installer (as described in the previous) on each required computer and then select to only install the Frontend server component.

For more information, including how to prioritize multiple Frontend servers, see Manage Frontend Servers.

Installation Troubleshooting

If something goes wrong during your installation, you'll see an error message. The error message will typically tell you that:

• the setup wizard ended prematurely, and
• that your system has not been modified

The latter is not always true. Your system may in fact have been modified, even if the error message tells you that it hasn't. Sometimes the entire PerformanceGuard system, including databases, may in fact have been installed, but if just a single of the PerformanceGuard services doesn't start after the installation has finished, the error message will appear.
You are therefore often able to solve the problem yourself.

If something goes wrong during your installation, you'll see an error message. The error message will typically tell you that:

• the setup wizard ended prematurely, and
• that your system has not been modified

The latter is not always true. Your system may in fact have been modified, even if the error message tells you that it hasn't. Sometimes the entire PerformanceGuard system, including databases, may in fact have been installed, but if just a single of the PerformanceGuard services doesn't start after the installation has finished, the error message will appear.
You are therefore often able to solve the problem yourself.

What You Should Do

If something goes wrong during your installation, you should first ask yourself if you have you met all of the prerequisites (see the beginning of this topic). For example, do you have administrative rights, and does the computer have the required version of Java JDK?
Next, you should check your installation log:

1. Open your installation log. If you followed the installation procedure in the previous, the log file is called installLog.txt. The log file will be available at the location from which you ran the installation, so if you ran the installation file from C:\, the log file will be placed under C:\ too.
2. Search the log for occurrences of return value 3.
3. Read the contents of the log file just before occurrences of return value 3 to determine which actions failed during the installation.

In this example (click thumbnail to view image in full size), a search for return value 3 revealed that there were problems with the user account specified for the PerformanceGuard Backend server database:

Going through the installation log as described will nearly always reveal what went wrong. In many cases you can solve the problem yourself. For instance, the problem identified in the example was solved simply by specifying the correct password for the Backend server database.

If you need help from PerformanceGuard support, you can find information about your support options on the CapaSystems website, http://www.capasystems.com/.