Upgrading the management server on Linux

This topic describes how to upgrade the management server on Linux.

Important

The supported upgrade path is from the previous release to the latest one. If the installed version is two or more releases older than the latest one, see earlier versions of this space or contact BMC Support.

Related topic

Upgrading

Prerequisites

  • No policies scheduled to run during the upgrade operation
  • At least 4 GB of free space under /var/lib/docker

  • Docker (version 18 or later) or Podman (version 4.4.1 or later)

    Important

    You must run the Docker or Podman commands using root or sudo.

Task 1: To obtain the installation files and license key

  2. Using the search bar, search for either BMC AMI Cloud Data or BMC AMI Cloud Vault. Both product files are composed with the same binaries.
  3. Click the version that you want to download. 
  4. On the Product tab, select the files and click Download.
  5. Select the License Information tab and download the temporary license key.

  6. To obtain a full license key, go toSupport Central and select Case Management. 

  7. Open a license key request by clicking on Create New Case and filling in the required information. 

    Important

    Supply the output of the z/OS command D M=CPU.

Task 2: To upload the zip files

Upload the zip installation file model9-v2.8.2_build_ebcddfb-server.zip to the designated server in binary mode.

Important

If installing the s390x version for Linux on z, use the file model9-v2.8.2_build_ebcddfb-server-s390x.zip

Task 3: To back up the server before the upgrade

  1. Set the default MODEL9_HOME environment variable by using the following command:

    sudo su -
    export MODEL9_HOME=<model9 home>

  2. Stop the server and remove the BMC AMI Cloud containers that are running by using the following commands, replacing v.r.m with the current fix pack version: 

    The first v in the following commands is not a variable. For example, model9-v2.7.0.

    docker stop model9-v<v.r.m>
    docker rm model9-v<v.r.m>

  3. Verify that the container is not running by using the following command:

    docker ps -a

  4. Back up 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

Task 4: To 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 '

Important

Verify that the $MODEL9_HOME/diag directory exists.

Task 5: (Optional) To obfuscate the object storage credentials

You can obfuscate the object storage secret key to prevent it appearing 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: support@model9.io                                                  *
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 agents. If using the obfuscated secret, add the following setting to the server's configuration file:

model9.objstore.endpoint.password_encrypted: true

Task 6: To deploy the BMC AMI Cloud container

Deploy the new BMC AMI Cloud release container by 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

Task 7: To verify and update the BMC AMI Cloud environmental variables file

BMC AMI Cloud 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. Verify that the model9.env is in the $MODEL9_HOME/conf directory.
  2. If they are not already there, add the following parameters in model9.env:

    1. When using Linux on intel, use the following parameters:

      TZ=America/New_York
      EXTRA_JVM_ARGS=-Xmx2048m

    2. When using Linux on z, use the following parameters:

      TZ=America/New_York
      CATALINA_OPTS=-Xmx2048m

  3. When running policies with objects of more than 100 KB objects, update the heap size to Xmx8192m. 

    Important

    If the container is already up with a lower value, you must stop and remove the current container and use the docker run command above to start it again: 

    docker stop model9-vx.y.z
    docker rm model9-vx.y.z
  4. Edit the time zone (TZ) setting to ensure proper scheduling in the model9.env file.
  5. Save the file.

Task 8: To update the PostgreSQL shared memory setting

Run the following commands:

# 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


Task 9: To start the BMC AMI Cloud management server

Important

The first BMC AMI Cloud management server startup following an upgrade might take longer than usual because internal migration processes. Subsequent startups will not be affected.

Warning

Earlier release agents are not compatible with the new release of the server. Complete the agent upgrade before starting to use the UI.

When the object storage provider is available and PostgreSQL is running, start the BMC AMI Cloud management server by 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

The BMC AMI Cloud container is now linked to other containers over a Docker network. For a full description of all Docker run parameters, see the docker runs topic in the Docker Docs site.

 

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