Important Prerequisites

It's important to be aware of the following before you begin the upgrade process:

• You must have administrative rights on the computer that you are going to perform the upgrade on (local administrator).
• The new version of PerformanceGuard may require a different Java JDK version than your old one. If the new PerformanceGuard version requires a different JDK version, it is important that you install the required JDK version on the PerformanceGuard server before you install the new version of PerformanceGuard. See Software Requirements and Install Java JDK.
• You should install the new version at the same location as the one you are upgrading. Make a note of the location that PerformanceGuard is currently installed at.
• Make a note of database users that your current PerformanceGuard installation uses. You must specify those users when you install the new version.
• You must know the passwords of the PerformanceGuard database users, because you must specify those passwords when you install the new version.
• When you install the new version, 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.
• You can download the server installer for the latest PerformanceGuard version. You can download the server installer for the latest PerformanceGuard version from the CapaSystems wiki.

Step 1: Stop PerformanceGuard Services

Select /Start, type services.msc and press ENTER. Then stop these services:

• PerformanceGuard Backend Server
• PerformanceGuard Frontend Server
• PerformanceGuard Web Server

Step 2: Back Up PerformanceGuard Databases

Back up your PerformanceGuard frontend and backend server databases before you upgrade your PerformanceGuard installation. Having a backup is important in the unlikely case that something goes wrong during your upgrade.
See Database Backup for more information.

Step 3: Back Up Current PerformanceGuard Installation

Back up the content of the following folders in your current PerformanceGuard installation:

• [PerformanceGuard installation folder]\collector
• [PerformanceGuard installation folder]\display
• [PerformanceGuard installation folder]\notification
• [PerformanceGuard installation folder]\reports

Step 4: Remove Current PerformanceGuard Installation

Navigate to the list of installed programs and features, and then uninstall PerformanceGuard Server.

Step 5: Install New Version of PerformanceGuard

1. Start an elevated Windows command prompt and navigate to the folder that contains the installer for the new PerformanceGuard version. 

    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:

   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 your old PerformanceGuard installation was installed at another location, for example on the D: drive, it is important that you specify the location that your require, otherwise your new PerformanceGuard version will be installed at the default location on the C: drive.

   To install PerformanceGuard at a location other than the default C:\Program Files\PerformanceGuard, 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.
   1. 
   2. Installation: Select Use existing frontend database.
   3. Frontend database server: If your frontend server database exists on a SQL Server on the computer that you are installing the frontend server on, simply use the localhost default setting. If your frontend server database exists on another SQL Server on your network, click the browse button next to the field and select the required SQL Server.
   4. Frontend database: The name of the frontend server database. The name is normally pguardfe, but a different name may be used in your organization.
   5. Frontend authentication: Select either ...
      1. SQL Server Authentication where access to the frontend server database will be authenticated by the SQL Server
      2. or
      3. Windows Authentication where access to the frontend server database will be authenticated through the Windows credentials of an existing Active Directory user
   6. Frontend database user: In order to communicate with the frontend server database, PerformanceGuard needs access to the database with a user account.
      1. If using SQL Server authentication the name of that user account is normally pguardfe, but a different name may be used in your organization.
      2. If you use Windows authentication, you must specify the user name of an existing Active Directory user.
   7. Frontend AD domain (only relevant if you selected Windows Authentication): Specify the domain that the Active Directory user belongs to.
   8. 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.
   9. When ready, click Next.
6. This step applies if you selected to install the FRONTEND server.
   1. 
   2. Make sure that Let the installer run the SQL scripts against the database is selected.
   3. When ready, click Next.
7. This step applies if you selected to install the FRONTEND server. 
   1. By default, frontend server database files and log files will be placed at the SQL Server's default location for new databases (<Server default>). That's usually fine, but if you used other locations for frontend server database files and log files in your previous PerformanceGuard version, you should specify the paths to those locations so that the new PerformanceGuard version can also use those locations.
   2. 
   3. When ready, click Next.
8. This step applies if you selected to install the FRONTEND server.
   1. 
   2. 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.
   3. 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.
   4. When ready, click Next.
9. This step applies if you selected to install the WEB INTERFACE.
   1. 

   2. 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.

   3. When ready, click Next.
      
10. This step applies if you selected to install the BACKEND server.
    1. 
    2. Installation: Select Use existing backend database.
    3. Backend database server: If your backend server database exists on a SQL Server on the computer that you are installing the backend server on, simply use the localhost default setting. If your backend server database exists on another SQL Server on your network, click the browse button next to the field and select the required SQL Server.
    4. Backend database: The name of the backend server database. The name is normally pguard, but a different name may be used in your organization.
    5. Backend authentication: Select either ...
       1. SQL Server Authentication where access to the backend server database will be authenticated by the SQL Server
       2. or
       3. Windows Authentication where access to the backend server database will be authenticated through the Windows credentials of an existing Active Directory user
    6. Backend database user: In order to communicate with the backend database, PerformanceGuard needs access to the database with a user account.
       1. If using SQL Server authentication the name of that user account is normally pguard, but a different name may be used in your organization.
       2. If you use Windows authentication, you must specify the user name of an existing Active Directory user.
    7. Frontend AD domain (only relevant if you selected Windows Authentication): Specify the domain that the Active Directory user belongs to.
    8. Backend database password: Specify the password that PerformanceGuard should use when it accesses the backend database with the user account that you specified previously.
    9. When ready, click Next.
11. This step applies if you selected to install the BACKEND server.
    1. 
    2. 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'll 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.
          1. The value of the Display TCP Port field is determined by a setting that you specified in step 9.
    3. When ready, click Next.
12. This step applies if you selected to install the BACKEND server.
    
    1. 
    2. Make sure that Let the installer run the SQL scripts against the database is selected. When ready, click Next.
13. This step applies if you selected to install the BACKEND server.
    1. By default, backend server database files and log files will be placed at the SQL Server's default location for new databases (<Server default>). That's usually fine, but if you used other locations for backend server database files and log files in your previous PerformanceGuard version, you should specify the paths to those locations so that the new PerformanceGuard version can also use those locations.
    2. 
    3. When ready, click Next.
14. This step applies if you selected to install the BACKEND server.
    
    1. 
    2. 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.
    3. When ready, click Next
15. Click Install to execute the installation with the settings that you have specified.
    
    1. 
16. When installation is complete, click Finish.

 
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 upgraded, 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/.

Step 6: Restore Specific Modifications

At the end of the upgrade process you may need to re-apply certain configuration settings:
Stop Services
Select /Start, type services.msc and press ENTER. Then stop these services:

• PerformanceGuard Backend Server
• PerformanceGuard Frontend Server
• PerformanceGuard Web Server
• PerformanceGuard Web Server 2

Reports

Make sure that you move the content from your backup of the report folder (\[PerformanceGuard installation folder\]\reports) to the similar report folder in the new PerformanceGuard version. This way you'll be able to access any old reports in your new PerformanceGuard version.

Services Memory
The PerformanceGuard services—the Frontend server, Backend Server and Web Server services—are allocated a certain amount of memory (by default a minimum of 2048 MB and a maximum of 4096 MB).
If your previous PerformanceGuard installation used a higher maximum setting for some or all of the services, you must specify that again.

Other Changes
If you have made changes to the configuration of your old PerformanceGuard version, you'll need to edit the new version's configuration files. Open the configuration files in the following folders from your backup, compare them with the corresponding configuration files in your new PerformanceGuard version, and make any necessary changes to the new version's configuration files:

• [PerformanceGuard installation folder]\collector\conf

  Don't change the drivers parameter in the new version of the file config.properties. The reason is that the new PerformanceGuard version uses a different type of driver than your old version.

• [PerformanceGuard installation folder]\display\conf

  Don't change the JdbcDriver parameter in the new version of the file performanceguard.xml, and be careful if changing any of the other JDBC parameters, such as the connection string. The reason is that the new PerformanceGuard version uses a different type of driver than your old version.

  If you have used SSL, the ...\display\conf folder will contain a keystore file called pg.keystore. Remember to migrate that keystore file for SSL to work with your signed server certificate on the new PerformanceGuard version.

• [PerformanceGuard installation folder]\notification\conf

  Don't change the dbDriver parameter in the new version of the file config.properties, and be careful if changing the connection string in the dburl parameter. The reason is that the new PerformanceGuard version uses a different type of driver than your old version.

Start Services
Select /Start, type services.msc and press ENTER. Then start these services:

• PerformanceGuard Backend Server
• PerformanceGuard Frontend Server
• PerformanceGuard Web Server
• PerformanceGuard Web Server 2

License
When you access the PerformanceGuard web interface for the first time after upgrading, you must re-install your license.

Use your existing license from the backup of \[PerformanceGuard installation folder\]\display\conf\

What About PerformanceGuard Agents?

You don't need to upgrade the PerformanceGuard agents that are installed on your organization's computers. Old agents are compatible with new versions of PerformanceGuard.
Should you wish to upgrade your PerformanceGuard agents anyway, you can download the latest version of the PerformanceGuard agent installer from the CapaSystems wiki. Unless your existing agents are very old (version 5.x or earlier), you don't need to remove existing agents before you deploy the new version.