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 two releases to the latest one. The upgrade steps are available in Upgrading from a specific version.


If you are upgrading from versions prior to versions 3.0.xx, 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.

Upgrading from a specific version

Select the version you need to upgrade from.

Task 1: To obtain the installation files

  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 want to download. 
  4. On the Product tab, select the files and click Download.

Task 2: To upload the zip files

Upload the model9-v3.2.0_build_f003c43-server.zip installation file to the designated server in binary mode.

Important

If installing the s390x version for Linux on z, use the model9-v3.2.0_build_f003c43-server-s390x.zip file.

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: 

    Important

    The first v in the following commands is not a variable. For example, model9-v3.0.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 /bin/bash -c "PGPASSWORD=model9 pg_dump --username postgres model9" > $MODEL9_HOME/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-v3.2.0_build_f003c43-server.zip 'model9*'

# On Linux on z issue:
unzip -o $M9INSTALL/model9-v3.2.0_build_f003c43-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: To load the new release artifacts

Deploy the new BMC AMI Cloud release container by using the following command:

# On Linux issue:
docker load -i $MODEL9_HOME/model9-v3.2.0_build_f003c43.docker

# On Linux on z issue:
docker load -i $MODEL9_HOME/model9-v3.2.0_build_f003c43-s390x.docker

Task 6: 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 of internal migration processes. Subsequent startups will not be affected.

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-v3.2.0 model9:v3.2.0.f003c43

# 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-v3.2.0 model9:v3.2.0.f003c43

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.

Task 1: To obtain the installation files

  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 want to download. 
  4. On the Product tab, select the files and click Download.

Task 2: To upload the zip files

Upload the model9-v3.2.0_build_f003c43-server.zip installation file to the designated server in binary mode.

Important

If installing the s390x version for Linux on z, use the model9-v3.2.0_build_f003c43-server-s390x.zip file.

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: 

    Important

    The first v in the following commands is not a variable. For example, model9-v3.0.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 /bin/bash -c "PGPASSWORD=model9 pg_dump --username postgres model9" > $MODEL9_HOME/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-v3.2.0_build_f003c43-server.zip 'model9*' 'postgres*'

# On Linux on z issue:
unzip -o $M9INSTALL/model9-v3.2.0_build_f003c43-server-s390x.zip 'model9*' 'postgres*'

#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: To load the new release artifacts

Deploy the new BMC AMI Cloud release container by using the following command:

# On Linux issue:
docker load -i $MODEL9_HOME/model9-v3.2.0_build_f003c43.docker

# On Linux on z issue:
docker load -i $MODEL9_HOME/model9-v3.2.0_build_f003c43-s390x.docker

Task 6: To upgrade the PostgreSQL version

The BMC AMI Cloud containers and PostgreSQL (Postgres) are linked over a Docker network. To verify that the network exists, issue the following command:

docker network ls |grep model9network

If the network exists, you should get a response similar to the following example:

587d239ba6ec model9network bridge local

If no result is returned, issue the following command to create the network:

docker network create -d bridge model9network
Warning

Make sure that you have backed up the database as described in Task 3: To back up the server before the upgrade.

Run the following commands:

# Stop Postgres container
docker stop model9db

# Remove Postgres container
docker rm model9db

# Load the new postgres:16.1 image
# on Linux issue:
docker load -i $MODEL9_HOME/postgres-16.1-alpine3.17-x86.docker.gz
# on Linux on z issue:
docker load -i $MODEL9_HOME/postgres-16.1-alpine3.17-s390x.docker.gz  

# Backup current database directory and create a new empty directory for the database files
mv $MODEL9_HOME/db/data $MODEL9_HOME/db/backup
mkdir $MODEL9_HOME/db/data

# 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:16.1-alpine3.17

# 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:16.1-alpine3.17

# Restore the database from backup
fileStamp=$(date +%Y-%m-%d)
docker cp model9db-$fileStamp.dump model9db:/tmp/model9db.dump
docker exec -it model9db psql -d model9 -f /tmp/model9db.dump -U postgres
docker exec -ti model9db rm /tmp/model9db.dump

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 file is in the $MODEL9_HOME/conf directory.

  2. Important

    Please note the following change in the upgrading procedure.

    If they are not already there, add the following parameters in the user's home directory:

    TZ=America/New_York
    EXTRA_JVM_ARGS=-Xmx2048m
    Warning

    If you have both CATALINA_OPTS and EXTRA_JVM_ARGS specified in the model9.env file, you must remove the CATALINA_OPTS parameter, and move the value to EXTRA_JVM_ARGS. For example, 

    EXTRA_JVM_ARGS=-Xmx2048m -Djavax.net.ssl.trustStore=/model9/keys/cacerts

  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-v<v.r.m>
    docker rm model9-v<v.r.m>
  4. Edit the time zone (TZ) setting to ensure proper scheduling in the model9.env file.
  5. Save the file.

Task 8: 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 of internal migration processes. Subsequent startups will not be affected.

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-v3.2.0 model9:v3.2.0_build_f003c43

# 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-v3.2.0 model9:v3.2.0_build_f003c43

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*