Links

Upgrading the Model9 management server

Prerequisites

  1. 1.
    Ensure that there are no policies scheduled to run during the upgrade operation.
  2. 2.
    Ensure at least 4GB of free space under /var/lib/docker.
  3. 3.
    The supported upgrade path is from releases 2.7.x to 2.8.x. If the installed release is older than that, please refer to previous installation guides or to Model9 support for upgrade instructions.
The docker/podman commands must be executed using root or by using sudo.
Required Container version:
docker ==> (version 18 or above) or
podman ==> (version 4.4.1 or above)

Step 1: Upload the zip files

Upload the zip installation file model9-v2.8.2_build_ebcddfb-server.zip to the designated server in binary mode.
If installing the s390x version for Linux on z, use the file: model9-v2.8.2_build_ebcddfb-server-s390x.zip

Step 2: Backup the server before the upgrade

  1. 1.
    Set the default MODEL9_HOME environment variable using the following command:
    sudo su -
    export MODEL9_HOME=<model9 home>
  2. 2.
    Stop the server and remove the Model9 containers that are running using the following commands - Make sure to replace the "x" with the current fix pack version:
    docker stop model9-v2.7.x
    docker rm model9-v2.7.x
  3. 3.
    Verify that the container is not running using the following command:
    docker ps -a
  4. 4.
    Backup the local configuration and database:
    cd $MODEL9_HOME
    fileStamp=$(date +%Y-%m-%d)
    tar -czf conf-$fileStamp.tar.gz conf
    docker exec -it model9db pg_dump -p 5432 -U postgres -d model9 -f /tmp/model9db-$fileStamp.dump
    docker cp model9db:/tmp/model9db-$fileStamp.dump $MODEL9_HOME/model9db-$fileStamp.dump
    docker exec -ti model9db rm /tmp/model9db-$fileStamp.dump

Step 3: Unzip the installation files

The configuration file structure has been changed in this release and should be backed up before upgrading the server, as shown in the following example. Unzip the installation file to $MODEL9_HOME:
# The path to model9 installation zip uploaded
export M9INSTALL=/<path>
# Verify MODEL9_HOME parameter is defined
echo $MODEL9_HOME
cd $MODEL9_HOME
# Backup current configuration files
cp conf/model9-local.yml conf/model9-local.yml.backup
cp conf/logback.groovy conf/logback.groovy.backup
# Create the diag directory
mkdir diag
# On Linux issue:
unzip -o $M9INSTALL/model9-v2.8.2_build_ebcddfb-server.zip 'model9*'
# On Linux on z issue:
unzip -o $M9INSTALL/model9-v2.8.2_build_ebcddfb-server-s390x.zip 'model9*'
#Define docker to podman alias if using podman as the container platform
alias docker=podman
#When using sudo define sudo alias that will resolve other aliases
alias sudo='sudo '
Verify the $MODEL9_HOME/diag directory exists

Optional: Obfuscate the object storage credentials

Model9 allows obfuscating the object storage secret key so it won't appear in clear text within the configuration files.
The obfuscation utility resides in the $MODEL9_HOME/Utilities directory. To run the utility issue the following command:
$MODEL9_HOME/Utilities/model9-obfuscator.sh <object storage secret key>
The script's outcome is an obfuscated version of the object storage secret key. For example:
[root@rhel73 Utilities]# ./model9-obfuscator.sh objstoresecret
/model9/Utilities/model9-credential-encryptor model9-obfuscator.sh
15:24:59.677 INFO [i.m.c.Model9CredentialEncryptorEntryPoint-main] - *******************************************************************************
15:24:59.679 INFO [i.m.c.Model9CredentialEncryptorEntryPoint-main] - * Model9 Credential Encryptor *
15:24:59.679 INFO [i.m.c.Model9CredentialEncryptorEntryPoint-main] - * Website: https://www.model9.io *
15:24:59.679 INFO [i.m.c.Model9CredentialEncryptorEntryPoint-main] - * Contact: [email protected] *
15:24:59.679 INFO [i.m.c.Model9CredentialEncryptorEntryPoint-main] - * 2016-2021 (c) Model9 Software *
15:24:59.679 INFO [i.m.c.Model9CredentialEncryptorEntryPoint-main] - *******************************************************************************
15:24:59.702 INFO [i.m.c.Model9CredentialEncryptorEntryPoint-main] - Encrypting...
15:24:59.785 INFO [i.m.c.Model9CredentialEncryptorEntryPoint-main] - Encrypted: rNEiN6QZB+OrmDMZBSXYX4F0OlrtWBSbhEJAfU6LfwCPGrW7HsRMZw5599guVIs5
Use the obfuscated key when setting the object storage password for the server and the agent(s). If using the obfuscated secret add the following setting to the server's configuration file:
model9.objstore.endpoint.password_encrypted: true

Step 4: Deploy the Model9 container

Deploy the new Model9 release container using the following command:
# On Linux issue:
docker load -i $MODEL9_HOME/model9-v2.8.2_build_ebcddfb.docker
# On Linux on z issue:
docker load -i $MODEL9_HOME/model9-v2.8.2_build_ebcddfb-s390x.docker

Step 5: Create/Verify the Model9 environmental variables file

Model9 management server loads its environmental variables from a file called model9.env located in the $MODEL9_HOME/conf directory. Verify the content of the model9.env configuration file:
  1. 1.
    Create the file model9.env in the $MODEL9_HOME/conf directory
  2. 2.
    If not already there, add the following parameters in model9.env
    1. 1.
      When using Linux on intel, use the following parameters in model9.env
      TZ=America/New_York
      EXTRA_JVM_ARGS=-Xmx2048m
    2. 2.
      When using Linux on z, use the following parameters in model9.env
      TZ=America/New_York
      CATALINA_OPTS=-Xmx2048m
    3. 3.
      When running policies with over 100k objects, update the heap size to Xmx4096m in the model9.env file.
    4. 4.
      Edit the time zone (TZ) setting to ensure proper scheduling in the model9.env file.
    5. 5.
      Save the file.

Step 6: Update the PostgreSQL shared memory setting

# Stop the Postgres container
docker stop model9db
# Remove the Postgres container
docker rm model9db
# Start Postgres docker container on Linux issue:
docker run --shm-size=256m -p 127.0.0.1:5432:5432 \
-v $MODEL9_HOME/db/data:/var/lib/postgresql/data:z \
-v $MODEL9_HOME/conf/docker-entrypoint-initdb.d:/docker-entrypoint-initdb.d:z \
--name model9db --restart unless-stopped \
--network model9network \
-e POSTGRES_PASSWORD=model9 -e POSTGRES_DB=model9 -d postgres:14.5
# Start Postgres docker container on Linux on z issue:
docker run --shm-size=256m -p 127.0.0.1:5432:5432 \
-v $MODEL9_HOME/db/data:/var/lib/postgresql/data:z \
-v $MODEL9_HOME/conf/docker-entrypoint-initdb.d:/docker-entrypoint-initdb.d:z \
--name model9db --restart unless-stopped \
--network model9network \
-e POSTGRES_PASSWORD=model9 -e POSTGRES_DB=model9 -d s390x/postgres:14.5

Step 7: Start the Model9 management server

Note
The first Model9 management server startup following an upgrade may take longer than usual due to internal migration processes. Subsequent startups will not be affected.
Note
Previous release agent(s) are not compatible with the new release of the server, complete the agent(s) upgrade before starting to use the UI
Once the object storage provider is available and PostgreSQL is running, start the Model9 management server using the following commands:
# On Linux issue:
docker run -d -p 0.0.0.0:443:443 -p 0.0.0.0:80:80 \
--sysctl net.ipv4.tcp_keepalive_time=600 \
--sysctl net.ipv4.tcp_keepalive_intvl=30 \
--sysctl net.ipv4.tcp_keepalive_probes=10 \
-v $MODEL9_HOME:/model9:z -h $(hostname) --restart unless-stopped \
--env-file $MODEL9_HOME/conf/model9.env \
--network model9network \
--name model9-v2.8.2 model9:v2.8.2.ebcddfb
# On Linux on z issue:
docker run -d -p 0.0.0.0:443:443 -p 0.0.0.0:80:80 \
--sysctl net.ipv4.tcp_keepalive_time=600 \
--sysctl net.ipv4.tcp_keepalive_intvl=30 \
--sysctl net.ipv4.tcp_keepalive_probes=10 \
-v $MODEL9_HOME:/model9:z -h $(hostname) --restart unless-stopped \
--env-file $MODEL9_HOME/conf/model9.env \
--network model9network \
--name model9-v2.8.2 model9:v2.8.2.ebcddfb
  1. 1.
    The Model9 container is now linked to other containers over a Docker network. When using a local MinIO proxy object storage that is deployed on the same server, the MinIO container needs to be stopped, removed, and brought up again adding "--network model9network" to the MinIO run command. Neglecting to do that will stop the server from connecting to the MinIO. Contact Model9 support for more information.
  2. 2.
    For a full description of all Docker run parameters, see the following URL: https://docs.docker.com/engine/reference/commandline/run