Completing Pre-Upgrade Tasks

This section describes tasks to complete in order to ensure a successful upgrade.

Note: For software ESM, both XFS and EXT4 file system formats are supported during installation. However, ESM configures itself to the file system upon which it was first installed. You cannot change the file system type after installation, even during an upgrade.

To prepare your system for upgrade:

Verify that your current software ESM or ESM on an appliance is fully functional and that archives are intact.

If there is an issue with your existing system, contact Technical Support before you start the upgrade.
Run the resource validator (resvalidate) and fix invalid resources.

For more information, see Running the Resource Validator.
If you are a Premier/Flexcare customer seeking upgrade support by using your Flex credits, contact Technical Support to discuss upgrade assistance.
Copy the /opt/arcsight directory or complete tasks in the CORR-Engine Backup and Recovery Tech Note to create a backup copy of the system.

Caution: To avoid issues, complete the upgrade immediately after you back up the system.

If you do not want to back up events and archives, you can exclude the following directories from the backup:
- /opt/arcsight/logger/data/archives
- /opt/arcsight/logger/data/indexes
- /opt/arcsight/logger/data/logger
Note: After you restore the backup, ensure that the /opt/arcsight/logger/data/logger/ directory exists before you start the services. Otherwise, the loggerd service will not start.

The logger directories cannot be used to roll back a logger upgrade failure, but Technical Support might request them in order to investigate recovery options.
Prepare your resources for upgrade.

For more information, see Preparing Resources for Upgrade.
Ensure that your ESM installation has the correct file permissions.

For more information, see Ensuring Correct File Permissions
If you are upgrading software ESM, ensure that the /opt directory has at least 50 GB of free space and that the /tmp directory has at least 5 GB of free space.

Caution: Do not mount /opt or /opt/arcsight to the /tmp directory. Linux has a cleanup process that deletes files under /tmp. Subsequently, you will risk losing your ESM installation.
Set the Java (Manager) heap size.

Micro Focus recommends changing the Java heap size to at least 16 GB before you upgrade. If the heap size is less than 16 GB, the upgrade program displays a message recommending that you increase the heap size to at least 16 GB after the upgrade is complete.

To avoid that message, as user arcsight, run /opt/arcsight/manager/bin/arcsight managersetup to increase the Java heap size. For more information about managersetup, see the ESM Administrator's Guide.
If you are upgrading software ESM, install the time zone package.

For more information, see Software ESM: Installing the Time Zone Package.
Depending on your environment, install the following libraries:
- If you are upgrading in a RedHat or CentOS 8.1 environment:
  - ncurses-compat-libs
  - libnsl
  - libaio
  - numactl
- If you are upgrading in a SUSE Enterprise Linux 15 SP 1 environment:
  - libncurses5
  - libaio1
  - numactl
- If you are upgrading in a SUSE Enterprise Linux 12 SP 4 environment:
  - libaio1
  - numactl
- For all other environments:
  - libaio
  - numactl
If you are upgrading software ESM, install an entropy generator (normally provided by your operating system vendor) such rng-tools or haveged. ESM requires high levels of operating system entropy for secure cryptography.
If you are upgrading ESM in a RedHat or CentOS environment running X Windows, either download and install the required RPM package (LibXtst.x86_64) from https://centos.pkgs.org/7/centos-x86_64/libXtst-1.2.3-1.el7.x86_64.rpm.html or run the following command to install the LibXtst.so.6 library:

yum install libXtst
Download ArcSightESMSuite-7.5.0.xxxx.tar from the Licensing and Downloads site (where xxxx is the build number) and copy the file to the system you will be upgrading.

Micro Focus provides a digital public key to enable you to verify that the signed software that you received is from Micro Focus and has not been manipulated by a third party. For more information and instructions, visit the Signature Verification page.

To initiate license procurement, after you download the .tar file, follow the instructions in the Electronic Delivery Receipt that you receive in e-mail.
Test the upgrade before you upgrade your production environment.

For more information, see Testing the Upgrade.

Running the Resource Validator

Run the resource validator (resvalidate) and fix all invalid resources before you start the upgrade process. After the upgrade process is complete, run the resource validator again to see if a change in the schema rendered any resources invalid. For more information about fixing invalid resources, see Completing Required Post-Upgrade Tasks.

The resource validator verifies that the values expressed in the resource condition statement still apply to the resource, and that any resources upon which it depends are present and valid. The resource validator runs on any resource that contains a condition statement or populates the asset model. For example:

Active channels
Filters
Data monitors
Rules
Report queries and schedules
Assets and asset ranges
Zones
Actors

To run the resource validator:

Stop the ArcSight Manager:

/etc/init.d/arcsight_services stop manager

As user arcsight, run the following command:
```
/opt/arcsight/manager/bin/arcsight resvalidate -persist false
```
The resource validator generates validationReport.html and validationReport.xml in the /opt/arcsight/manager directory. Save these files to another directory so that you can compare them to the files that are generated after the upgrade.

Restart the ArcSight Manager:

/etc/init.d/arcsight_services start manager

After the upgrade is complete, run resvalidate again.

Preparing Resources for Upgrade

This section describes how the upgrade affects your resources and how to prepare your resources for upgrade.

Caution: Starting with ESM 7.0 Patch 1, the Event Reconciliation and Session Reconciliation data monitors are deprecated and no longer functional. If you customized these data monitors and apply the upgrade, the customized data monitors will appear as broken resources.

Standard, ESM-supplied resources are refreshed with new versions during upgrade. If you copied these resources to a custom group and then customized them, the upgrade does not affect the custom group.

If you customized standard resources in their original location, back up the resources to an .arb file (exclude related resources) before you upgrade. You can restore the resources after the upgrade is complete.

Note: When you restore an .arb file, you overwrite the version that the upgrade program provided. If the upgrade included improvements, the improvements will not be available. As an option, you can apply your customizations to the new version.

The upgrade does not affect the following customizations:

Asset modeling for network assets, including the following:

Assets and asset groups and their settings
Asset categories applied to assets and asset groups
Vulnerabilities applied to assets
Custom zones
Custom network resources
Custom location resources

SmartConnectors
Users and user groups
Report schedules
Archived reports
Notification destinations and priority settings
Cases

If you customized the Cases Editor user interface, back up the customized files in a separate location and restore them after the upgrade is complete.

Backing Up Resources Before Upgrading

Back up standard resources that you customized in their original location (not resources that you moved to a custom group), including active lists.

Note: The upgrade program does not preserve active list attributes such as the Time to Live (TTL) and description. The upgrade program does preserve entries that were added to active lists.

To back up resources:

In the ArcSight Console, for each resource type (filter, rule, active list, etc.), create a new group under your personal group and provide a name that identifies the contents.
Copy the resources to the new group.

Any resources that point to other resources remain unchanged; they still point to the other resource even if you also copied that resource. You must correct the pointers to point to the copied version.
Export the backup groups in a package:

From the Navigator panel Packages tab, right-click your group name and select New Package. In the Packages editor in the Inspect/Edit panel, name the package to identify the contents.
Right-click the group that you created and select Add to Package.
Select your new package and click OK.
Right-click your package name and select Export Package to Bundle.

Tip: Copy and paste configurations from the old resources to the new resources after the upgrade is complete.

Instead of overwriting the new resources with backup copies of the old ones, copy and paste configurations from the old resources one by one into the new ones. This procedure ensures that you preserve your configurations without overwriting any improvements provided in the upgrade.

Ensuring Correct File Permissions

The upgrade program checks your system to prevent upgrade failures due to incorrect file permissions. To avoid upgrade failures, you can manually perform these checks before you start the upgrade. Ensure that your ESM installation has the following file permissions:

User arcsight should own /opt/arcsight/ and all files and directories below it.
/opt/arcsight and all directories below it should have a minimum permission of 500. This is the minimum permission that allows the arcsight user to list files within a directory.
All files within /opt/arcsight or any subdirectory should have a minimum permission of 400. This is the minimum permission for the arcsight user to read the contents of the files.

If your ESM installation does not meet these requirements, you will need to resolve the issues before you can proceed with the upgrade.

Note: There are some exceptions. User root is expected to own the files /opt/arcsight/manager/bin/setup_services.sh, /opt/arcsight/manager/bin/remove_services.sh, and the contents of the /opt/arcsight/services/highavail directory. The arcsight user does not need to own these files.

Software ESM: Installing the Time Zone Package

This section does not apply to ESM on an appliance.

ESM uses the time zone update package to automatically handle changes in time zone or changes between standard and daylight savings time. During the upgrade, ESM verifies whether the appropriate operating system time zone update package is installed. If it is not, you have the option to exit the upgrade program and install the latest package or continue the ESM upgrade and install the time zone update package later. Micro Focus recommends installing the time zone update package when prompted.

The package to use depends on your operating system version:

For this operating system:	Use this package or later:
RHEL or CentOS 8.2 or 8.1	`tzdata-2020f-1.el8.noarch.rpm`
RHEL or CentOS 7.9, 7.8, or 7.7	`tzdata-2020f-1.el7.noarch.rpm`
SLES 15 Service Pack 1	`timezone-2020f-3.41.2.x86_64.rpm`
SLES 12 Service Pack 5	`timezone-2020f-74.46.1.x86_64.rpm`

To install the time zone update package before upgrade:

Unpack the package and upload it to your server (for example, to /opt/work/<package name>).
As user root, run the following command:
```
rpm -Uvh /opt/work/<package name>
```
To check the time zone setting, run the following command:
```
timedatectl
```
If the time zone is not correct or it is not the desired time zone, run the following command to specify another time zone:
```
timedatectl set-timezone <time zone>
```
For example:
```
timedatectl set-timezone America/Los_Angeles
```

To install the time zone update package after the upgrade is complete:

Use the procedure above to install the correct time zone update package.
As user arcsight, shut down all ArcSight services:
```
/etc/init.d/arcsight_services stop all
```

As user arcsight, run the following command (all on one line):

/opt/arcsight/manager/jre/bin/java -jar /opt/arcsight/manager/lib/jre-tools/tzupdater/ziupdater-1.0.1.2.jar -V

As user arcsight, start all ArcSight services:
```
/etc/init.d/arcsight_services start all
```

Testing the Upgrade

Micro Focus recommends testing the upgrade before you upgrade your production environment. This section provides an example of how to perform this test.

To test the upgrade:

Install ESM in a test environment that matches your current production environment as closely as possible, including the following:
- The ESM version (major, minor, and patch) must be the same.
- The system (physical or virtual) must have sufficient memory and processing power to start all ESM services. Micro Focus recommends 16 GB RAM or greater.
- Ensure that the test version of ESM starts and works correctly before you import the test system tables.
- This is a system tables test only, so you do not need to configure LDAP, the SMTP server, or CA certificates.
Note: You must complete the remaining steps as user arcsight.
Stop the ArcSight Manager in the production environment:
```
/etc/init.d/arcsight_services stop manager
```

Export the system tables from the production environment:

cd /opt/arcsight/manager/bin

./arcsight export_system_tables arcsight <mysql password> arcsight -s

Start the ArcSight Manager in the production environment:
```
/etc/init.d/arcsight_services start all
```
Move the system tables dump to the test environment under /opt/arcsight/manager/tmp.
Stop the ArcSight Manager in the test environment.
```
/etc/init.d/arcsight_services stop manager
```

Import the system tables from the production environment into the test environment.

cd /opt/arcsight/manager/bin

./arcsight import_system_tables arcsight <mysql password> arcsight <system-table-dump filename>

Start the ArcSight Manager in the test environment:
```
/etc/init.d/arcsight_services start manager
```
Verify that the ArcSight Manager in the test environment is functioning.
Stop the ArcSight Manager in the test environment:
```
/etc/init.d/arcsight_services stop manager
```
Verify that the ArcSight Manager for the test system is completely shut down and that the mysql service is available.
Run resvalidate to validate resources.

For more information, see Running the Resource Validator.
Proceed with the upgrade procedure in the test environment.

For more information, see Running the Upgrade.