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
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:
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
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.jsonThe 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
The above command will open the default text editor in which you should paste the following content:
[Unit]
After=docker.service
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
Last updated