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.

Important

Select the version tab depending on the version you want to upgrade to.


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 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-v3.0.1_build_56bdebd-server.zip to the designated server in binary mode.

Important

If installing the s390x version for Linux on z, use the file model9-v3.0.1_build_56bdebd-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: 

    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 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-v3.0.1_build_56bdebd-server.zip 'model9*'

# On Linux on z issue:
unzip -o $M9INSTALL/model9-v3.0.1_build_56bdebd-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.0.1_build_56bdebd.docker

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

Task 6: 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 7: 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 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.0.1 model9:v3.0.1.56bdebd

# 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.0.1 model9:v3.0.1.56bdebd

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 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 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-v3.0.0_build_7b35826-server.zip to the designated server in binary mode.

Important

If installing the s390x version for Linux on z, use the file model9-v3.0.0_build_7b35826-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: 

    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 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-v3.0.0_build_7b35826-server.zip 'model9*'

# On Linux on z issue:
unzip -o $M9INSTALL/model9-v3.0.0_build_7b35826-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.0.0_build_7b35826.docker

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

Task 6: 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 7: 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 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.0.0 model9:v3.0.0.7b35826

# 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.0.0 model9:v3.0.0.7b35826

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*