Preparing to upgrade the App Visibility Server and checking compatibility

Ensure that you prepare the TrueSight App Visibility Manager environment for an upgrade and that you understand how the upgrade changes or impacts the behavior from your earlier version:

Upgrade warning

If you have the App Visibility Manager version 11.0.00.003 (Fix Pack 3) configured to work with the SAML authentication type, and want to upgrade your TrueSight Operations Management to version 11.3.01, you must also apply the Fix Pack version 11.3.02 for the SAML authentication type to work.

Understanding the upgrade process

When you upgrade the TrueSight App Visibility Manager server components (portal, collector, and proxy), all the components must be the same version.

If more than one TrueSight App Visibility Manager server component is installed on a computer, the components are upgraded together. With the wizard upgrade utility, you can upgrade the components currently installed and install an additional component at the same time. With the silent upgrade script, you must first upgrade the current component or components, and then install other components.

The TrueSight App Visibility Manager portal and collector upgrade processes include the option to enable high availability. This option is available only if the server components are on separate computers. After you upgrade and enable high availability, ensure that you update each TrueSight App Visibility Manager collector, proxy, and agent to connect to the portal's load balancing server.

The following topics describe how to upgrade and verify your installed version of TrueSight App Visibility Manager server components to the latest version:

Use the following flowchart to help determine the order to perform the upgrade tasks.

TrueSight App Visibility Manager upgrade process overview

  1. Upgrade the server components (Portal, Collector, and Proxy)
  2. Upgrade the agents:
    • Upgrade App Visibility agents for Java.
    • Upgrade App Visibility agents for .NET.
    • Upgrade synthetic TEA Agents.

Note

As soon as you start upgrading components, data collection stops or is incomplete until all components run the same version.

App Visibiltiy upgrade process overview.png

Pre-upgrade tasks for the App Visibility server components

Changing App Visibility database authentication

The App Visibility portal and App Visibility collector each include an App Visibility database, which is a PostgreSQL database that uses trust authentication by default. This authentication assumes that anyone who can access the App Visibility portal or collector computers is authorized to access the database.

If you changed the authentication method for one or more databases, such as password authentication, you must change back to trust authentication before you upgrade the component or components. After you complete the upgrade, you can return to the authentication method of your choice. To change the authentication method, refer to the PostgreSQL documentation.

Warning

The database authentication method must be trust authentication before you begin the upgrade or else the upgrade fails, and you must manually restore the database.

Backing up the App Visibility database

Make a physical backup of the App Visibility PostgreSQL database to protect your data from loss. The output of a physical backup contains the data files that the App Visibility server can use directly, resulting in a faster recovery operation.

In a high-availability environment, back up your data from the active node to ensure that you have the most up-to-date data.

  1. On the computer with the App Visibility portal or collector, navigate to the following directory:

    • (Windows) collector_installationDirectory\collector\bin\db or portal_installationDirectory\portal\bin\db
    • (Linux) collector_installationDirectory/collector/bin/db or portal_installationDirectory/portal/bin/db

    If the portal and collector are installed on the same computer, they share a database, and you only need to perform the procedure in one place.
    If the portal and collector are on separate computers, perform the backup procedure on both components at the same time so that the backup content is consistent. Otherwise, the backup content does not match and the data is incorrect when restored.

  2. Run the following script:
    • (Windows) create-pgsql-dump.bat
    • (Linux) ./create-pgsql-dump.sh

The script creates a backup of the data in the avdb.dump file in the server component's installationDirectory\ADOP_DB\pgsql\backup directory.

BMC recommends that you move or copy the avdb.dump file outside the installation directory.

Recovering the App Visibility database

Note

In a high-availability environment, you must restore the database data in the following order.

  1. Stop the component service for the standby node.
  2. Stop the component service for the active node, restore the data on the active node (as instructed in the following procedure), and start the active node again.
  3. Start the standby node.
  1. Ensure that the avdb.dump file is in the server component's installationDirectory\ADOP_DB\pgsql\backup directory.

  2. Stop the component service:

    • On the computer with the App Visibility portal, stop the portal service.
    • On the computer with the App Visibility collector, stop the collector service.

    For information about stopping services, see Starting-and-stopping-the-App-Visibility-server-services.

  3. Navigate to the following directory, according to your system:

    • (Windows) collector_installationDirectory\collector\bin\db or portal_installationDirectory\portal\bin\db
    • (Linux) collector_installationDirectory/collector/bin/db or portal_installationDirectory/portal/bin/db

    If the portal and collector are installed on the same computer, they share a database, and you only need to perform the procedure in one place.
    If the portal and collector are on separate computers, perform the recovery procedure on both components at the same time so that the content is consistent. Otherwise, the content does not match and the data is incorrect when restored.

  4. Run the following script:
    • (Windows) restore-pgsql-dump.bat
    • (Linux) ./restore-pgsql-dump.sh
  5. Start the component service.

The database data is recovered.

For more information about how to recover the PostgreSQL database data, see Backup and Restore.

Backing up customized agent and confidentiality policy files

If you created a customized agent policy, including adding comments, copy the contents of the policy and save it as a text file. This backup file can be used to compare the previous settings with the current.

  1. From the navigation pane of the TrueSight console, select Administration > App Visibility Agent Policies.
  2. From the Agent Policies tab, click the name of the agent policy you want to back up.
  3. Copy the contents of the agent policy and paste them into a text file.
  4. Save the text file as a back up.
  5. Click the Confidentiality Policies tab and click the name of the policy you want to back up.
  6. Copy the contents of the confidentiality policy and paste them into a text file.
  7. Save the text file as a back up.

If you customized other settings with the help of BMC Support, contact them for assistance backing up the settings.

Recovering customized agent and confidentiality policy files

If you have issues with your database, you can recover the backed-up policy files.

  1. From the navigation pane of the TrueSight console, select Administration > App Visibility Agent Policies.
  2. From the Agent Policies tab, edit the name of the agent policy you want to recover.
  3. Copy the contents from the saved text file and paste them into the agent policy.
  4. Save the agent policy.
  5. Click the Confidentiality Policies tab and edit the name of the policy you want to recover.
  6. Copy the contents from the saved text file and paste them into the confidentiality policy.
  7. Save the text file as a back up.

Checking upgrade compatibility

Consider the following version compatibility behaviors with the TrueSight App Visibility Manager upgrade:

Component version upgrade paths

  • App Visibility

     version of server and agents. Upgrade all the server components (portal, all collectors, and all proxies), agents for Java, agents for .NET, and TEA Agents to the latest supported version. For more information on supported the TrueSight Presentation Server version for the TrueSight App Visibility Manager, see Supported-Presentation-Server-integrations-with-TrueSight-Operations-Management-components.

    • App Visibility server version. You can upgrade the App Visibility server components from version 10.7 or11.0 to the current version of TrueSight App Visibility Manager. For versions earlier than 10.7 of the App Visibility server, first upgrade to a supported later version, and then upgrade to the current version.
      When you upgrade the App Visibility server, you can enable high-availability configuration for the App Visibility portal and collectors. You need to edit the App Visibility portal details in the TrueSight Presentation Server. For more information, see To edit a component's values.

    • Agent version. Upgrade the App Visibility agents (agents for Java, agents for .NET, and TEA Agents) from version 10.7 or11.0, to the current version of TrueSight App Visibility Manager. For versions earlier than 10.7 of the agents, first upgrade to a supported later version, and then upgrade to the current version.

Policy and configuration files

  • Out-of-the-box policy and configuration files. When you upgrade the server, all out-of-the-box policy files and configuration files are automatically upgraded, and the policies can work with the supported agents.

  • Customized policy and configuration files. When you upgrade the server, all customized policy files are merged with the upgraded files. Existing functionality and values are retained for earlier agents, and new functionality is added for upgraded agents.

    If you added comments to customized files, the comments are not retained after the upgrade.

Synthetic metric rule definitions

Synthetic metric rules in the current version are defined differently from earlier versions, enabling more choices and capabilities in rule definitions.The upgrade process migrates the same functionality from earlier versions into the current rule definitions.

To conform to the new rule definitions, the upgrade process adapts the following specific rules:

Metric rule

Rule definition in earlier version

Rule definition in current version

Out-of-the-box metric rules

  • Minor and Critical thresholds enabled.
  • Thresholds are different.
  • Consecutive values are different.
  • Minor and Critical thresholds enabled.
  • Thresholds from the earlier version are retained.
  • Consecutive value from the Critical setting, only, is converted to violation frequency.
  • Minor and Critical thresholds enabled.
  • Thresholds are the same.
  • Consecutive values are different.
  • Only the Critical threshold is enabled.
  • Threshold from the earlier version is retained.
  • Consecutive value from the Critical setting, only, is converted to violation frequency.

Custom metric rules

  • Minor and Critical thresholds enabled.
  • Thresholds are the same or different.
  • Consecutive values are different.
  • Two rules are created, one for the Minor settings and one for the Critical settings.
    The rule names is appended with - Minor or - Critical.
  • Each rule uses the corresponding threshold settings.
  • Each rule converts the consecutive value to the corresponding violation frequency.

For more information about upgraded rule, see Upgrading synthetic metric rules.

For more information creating and managing synthetic metric rules, see Configuring and managing synthetic metric rules.

To prepare for the App Visibility proxy component

To enable the App Visibility proxies to collect data from end users, and the clustered and embedded storage engines to communicate and operate at optimal efficiency, ensure that your system conforms to the following requirements.

Client certificate for the App Visibility proxy

As the system administrator, configure your network to ensure that the App Visibility proxy can collect end-user browser data, and pass it on to the App Visibility collector and portal.

Before you install the App Visibility proxy, configure the following items:

  1. Define a host name that resolves to the App Visibility proxy’s IP address, or to a Virtual IP on a load balancing server.
  2. Create a certificate in which the Common Name matches the defined host name.
  3. Configure the load balancing server to do the following actions:
    • Negotiate HTTPS using the certificate created in Step 2.
    • Redirect end-user HTTP/HTTPS requests from this host name to the  host:port  of the App Visibility proxy.

Storage Transport certificate 

Storage Transport certificate ensures a secure connection is established between the storage nodes. You can install App Visibility Proxy with the custom certificate files. However, the files must be compatible with Searchguard plugin for Elasticsearch. 

Ensure that you have verified the required Search Guard security files (node-keystore, admin-keystore, truststore) and their passwords are available with you before you proceed to replace the App Visibility Proxy storage transport certificate.

For more information, see https://docs.search-guard.com/latest/.

To replace App Visibility Proxy Storage Transport certificate

  1. Stop the App Visibility Proxy services and storage engine in all nodes. For details, see Starting and stopping the App Visibility server services.

  2. Log on to the target host computer where the App Visibility proxy is to be installed.
  3. Copy the node-keystore, admin-keystore, truststore files to a temporary directory on the target host.

  4. Edit the adop-installer.properties file under Disk1 and specify the following:

    Notes

    - Use forward slash in file paths for both Linux and Windows.

    - Ensure that the following configuration files on Linux are accessible to only users with the root account privileges.

    • searchguard_ssl_transport_keystore_filepath= <full path of transport node-keystore  file> Example: c:/tmp/CN=apm.bmc.com-keystore.jks>
    • searchguard_ssl_transport_keystore_password= <node-keystore password>
    • searchguard_ssl_transport_truststore_filepath= <full path of transport truststore file>  Example: c:/tmp/truststore.jks>
    • searchguard_ssl_transport_truststore_password= <truststore password>
    • searchguard_ssl_transport_sgadmin_filepath= <full path of transport truststore file>  Example: c:/tmp/CN=sgadmin-keystore.jks>
    • searchguard_ssl_transport_sgadmin_password= <Admin-keystore password>
      Warning

      The adop-installer.properties file is used only for installation and contains passwords in plain text. Ensure that you secure this file. You can delete the file after installation.

  5. Stop the App Visibility Proxy services and storage engine in all nodes.

Private Certificate for the App Visibility Components

If you are adding a new proxy to an existing App visibility setup that uses private certificate (not the OOTB certificate),  you must configure the custom truststore and keystore files used by the existing App Visibility Manager components, along with their password and alias names.

  1. Log in to the target host computer where you want to install the App Visibility proxy.
  2. Copy the <myTruststoreFileName>.jks and <myKeystoreFileName>.jks  files to a temporary directory on the target host.
  3. Edit the adop-installer.properties file under Disk1, and specify the following:

Note

Use forward slash in file paths for both Linux and Windows.

  • keystore_type= <keystore type: JKS (default) or PKCS12>
  • keystore_filepath= <Full path of the keystore file>
  • keystore_password= <keystore password in plain text>
  • keystore_alias= <alias (default = selfsigned)>
  • truststore_type=< truststore type: JKS (default) or PKCS12>
  • truststore_filepath= <Full path of the truststore fie>
Warning

The adop-installer.properties file is used only for installation and contains passwords in plain text. Ensure that you secure this file. You can delete the file after installation.

App Visibility proxy prerequisites for Linux and Unix systems

Before you install the App Visibility proxy, ensure that your Linux or Unix system is prepared.

Element

Description

Swapping settings

On Linux systems, BMC recommends setting the sysctl value vm.swappiness to 0 (preferred) or 1. The setting disables or minimizes RAM swapping on the computer and enables the storage engine to run more efficiently.

System V (SysV) operating systems

For SysV init processes, ensure the following settings before you begin the installation process:

  • Ensure that Elasticsearch, as a non-root user, can run at least 2048 threads (4096 recommended).
    For details, see Elasticsearch configuration documentation for the number of threads

  • Set the vm.max_map_count parameter to 262144.
    For details, see Elasticsearch configuration documentation for virtual memory.

seccomp installation

Ensure that seccomp, a system call filter, is installed on your system. This defense mechanism is a requirement for the storage engine.

Seccomp is not supported in Linux kernel version 3.5 and earlier, therefore you cannot install the App Visibility proxy on such systems.


Where to go from here

If you are installing the product, perform the other preinstallation tasks listed in the Preparing-to-upgrade-TrueSight-Operations-Management-solution page. 

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*