Upgrade Polarity Server v4 to v5

This page will walk an administrator through upgrading from Polarity Server version 4 to version 5.

Ensure that the Server is running version 4.3.3 and Web version 4.4.5 before attempting the v5 upgrade, and that the PostgreSQL Server is running v13+

Confirm Operating System

Check your operating system to ensure you are running the correct install commands

uname -a
cat /etc/os-release

---

Database Backup

Check if backup exists

cd /app/polarity-server-backups 

Check for date of the backup, if it is from the day of the upgrade or the day before the upgrade you should be good to move forward with the upgrade. If not, or you just want to ensure you have the latest information follow the bext steps to create a backup.

Create DB backup

 sudo su - postgres -c '/app/polarity-server/data/backups/db-backup.sh'

If you see cannot access errors related to the logs, or .git directory of integrations these errors can be safely ignored. The backup script does not copy any logs you may have from your integrations but the integrations themselves are copied.

Convert TLS Key & Retain CA/Intermediate Certificate Chain

The v5 Polarity Server requires that the SSL key be in PEM format using the PKCS8 container. Most customers will already be using these formats.

Navigate to the key location

cd /etc/pki/tls/private

Make a backup copy of your existing key

cp server.key server.key.orig

Convert the key

openssl rsa -in server.key.orig -outform pem > server.key

Ensure you have a copy of the CA and intermediate certificates required to validate the TLS certificate used on the v5 Polarity Server.

If the v5 Polarity Server is unable to validate the entire chain for it’s TLS certificate, core integration functionality will not work properly

Edit DB Maximum Connection

The DB maximum connection needs to be added or edited in the Polarity .env file.

sudo vi /app/polarity-server/.env

Check to see if there is the line POLARITY_DB_CONNECTION_POOL_SIZE

if the line exists, edit it to be the following, if not please add the line to the .env file:

POLARITY_DB_CONNECTION_POOL_SIZE=50

Install and Check Dependencies

CentOS 7 / Amazon Linux 2

JQ

sudo yum install jq -y

Docker

sudo yum install docker -y

Issue installing repos CentOS 7/AL2

If you are not able to install packages using yum on CentOS 7, there is a chance that the PostgreSQL repo needs to be updated. Run the following command:

yum --disablerepo=* -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm

Docker Compose

wget https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)
mv docker-compose-$(uname -s)-$(uname -m) /usr/local/bin/docker-compose
chmod -v +x /usr/local/bin/docker-compose

With CentOS 7/AL2 we will need to ensure that docker-compose is added to the path to ensure the commands will work in the future.

vi ~/.bashrc 

Add the following line to the bottom of the file:

export PATH="$PATH:/usr/local/bin"

Then ensure the change takes effect immediately:

source ~/.bashrc 

CentOS Stream 8 / Rocky Linux 8 / RHEL 8

JQ

sudo dnf install jq -y

Docker

For RHEL 8, docker is an alias for podman. This may cause issues, so we recommend installing docker-ce from the Docker repo directly.

sudo dnf config-manager --add-repo=https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf install docker-ce -y --allowerasing

Docker Compose

wget https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m) -O ./docker-compose
mv ./docker-compose /usr/local/bin/
chmod -v +x /usr/local/bin/docker-compose

Enable and Check Docker Commands

Enable Docker

systemctl enable docker

Check the Docker version commands to ensure Docker and Docker Compose is running

docker --version
docker-compose --version

Download and Run Upgrade Script

Navigate to the /root directory or a directory such as /tmp

cd /root

Download the upgrade script

sudo wget {{URL Provided by Polarity Rep}}

Note the script is about 1.5GB so please ensure the directory has enough space for the script.

Make the script executable

sudo chmod u+x upgrade_v4_to_v5-al2-offline-selfextract.sh

Run the script

./upgrade_v4_to_v5-al2-offline-selfextract.sh

Script Prompts

When executing the script, it will prompt for different commands. Below is a guide to the commands and what we here at Polarity recommend:

The script is very verbose and will prompt for every step the script is executing so admins can easily see if anything has failed.

First Prompt: "Press any Key to Continue" - The initial prompt to let the admin know the script is running. Just press any key on the keyboard.

Second prompt: "Which directory do you wish to install Polarity V5 into?"

The default is /app which is the directory we recommend. You can proceed and just hit [Enter]

Third Prompt: "Do you want to create a backup of the existing Polarity Platform v4 install directory (y/n)"

Here we recommend not creating a backup of the V4 install directory as there is a database backup already confirmed.

We recommend "n" or "no"

Fourth Prompt: "Do you want to create a backup of the existing .env file (y/n) [yes]:"

This prompt is asking if you want to ensure a backup of the .env file is taken, which we recommend to ensure configurations are saved correctly.

We recommend the default of "y" , "yes" or [Enter].

Fifth Prompt: "Do you want to using the values from the existing .env file (y/n) [yes]:"

This prompt will utilize the values that were setup in the .env file originally.

We recommend keeping these values and selecting the default of "y" , "yes" or [Enter]

Sixth Prompt: "Do you want to be prompted for each environment variable (y/n) [yes]:"

This prompt is to allow the admin to review and or change each of the values in the .env file.

We recommend "n" or "no"

Integration Prompts:

The script will upgrade each of the integrations that are currently installed on the V4 server to ensure the integrations will work correctly. The script will check and try and match the names of the integrations to Polarity supported integrations.

If there are any edited integrations or custom integrations present the script will prompt the admin to ask if they want to map the integration to a Polarity supported integration.

We recommend mapping integrations if they have been renamed to something else, for example "Splunk Firewall". We recommend mapping it to our Splunk integration then changing the name after teh upgrade is complete to ensure the values are saved in the database.

To map an integration to a Polarity supported one there are two ways to do so:

1. Name of the integration: Enter the name of the integration as it appears on the integrations github page, which can be found here: https://github.com/polarityio

2. Polarity Unique Identifier: Enter the Unique ID which can be found in the integration's config/config.json file on github: https://github.com/polarityio/splunk/config/config.json

   • The uniqe ID will look something like: "13aab2c0-a435-11ee-b809-03732f21d597"

Seventh Prompt: "Do you want to remove Polarity v4 packages (y/n) [no]:"

This prompt asks if admins want to remove the Version 4 packages from the server.

We recommend to keep the packages on the server until the V5 server is up and running without issues. The packages can be removed at a later date.

We recommend "n" or "no"

Final Prompt: "Do you want to remove Polarity v4 directories (y/n) [no]:"

This is the final prompt which asks if admins want to remove the Version 4 directories from the server.

We recommend to keep the directories on the server until the V5 server is up and running without issues. The directories can be removed at a later date.

We recommend "n" or "no"

Script is complete when you see:

All done. Good luck!

After Upgrade Steps

When finishing the v4 to v5 upgrade process, Docker will be running 2 containers (polarity_platform and polarity_web). The PostgreSQL, Redis Integration Cache, and Redis Metrics Cache services will continue to be running on the host outside of docker.

In the event your server reboots, it is important that the Redis services and PostgreSQL service start up after the Docker service starts. This is to ensure that the Docker network which is required for PostgreSQL, polarity-integration-cache, and polarity-metrics-cache is available for use.

To do this, you will override the systemd unit file for each service using the systemctl edit command. Starting with the PostgreSQL service run the following command:

systemctl edit postgresql-13

If you are running PostgreSQL 15, replace postgresql-13 with postgresql-15

The above command will open the default text editor in which you should paste the following content:

[Unit]
After=docker.service

The default text editor is most likely vi in which case you will need to press the i key to start "insert" mode before typing or pasting the above content.

If the editor is vi you can save the file by pressing esc and then :wq

Next you will want to modify the integration cache service:

systemctl edit polarity-integration-cache

Add the some text as you did for the PostgreSQL service. Finally, repeat the process for the Metrics cache:

systemctl edit polarity-metrics-cache

After making the necessary unit file changes, you will need to restart the services for the changes to take effect:

systemctl daemon-reload 
systemctl restart postgresql-13 
systemctl restart polarity-integration-cache 
systemctl restart polarity-metrics-cache

Finally, we recommend ensuring that the services are all enabled to start on boot with the following command:

systemctl enable postgresql-13 
systemctl enable polarity-integration-cache 
systemctl enable polarity-metrics-cache

Again, if you are running PostgreSQL 15, replace postgresql-13 with postgresql-15 in the above commands.