Upgrading the management server on zCX

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

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

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

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 you want to download. 
  4. On the Product tab, select the files and click Download.
  5. Select the License Information tab to download a 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

    The output of the z/OS command D M=CPU is required.

Task 2: To upload the s390x installation zip file

Upload the s390x installation zip to the zCX instance using scp or any other tool in binary mode.

Copy the s390x installation zip from the zCX instance to the alpine container:

docker cp model9-v3.0.1_build_56bdebd-server-s390x.zip dummy:/root/model9-v3.0.1_build_56bdebd-server-s390x.zip

Task 3: To stop BMC AMI Cloud

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>

Task 4: To prepare the installation artifacts

In the Alpine container, open the BMC AMI Cloud artifact:

# Create a new docker volume for initdb
docker volume create model9db_initdb

# Stopping the old alpine container
docker stop dummy
docker rm dummy

# Running an alpine container and mounting the model9 docker volume
docker run -d --rm --name dummy \
-v model9:/root \
-v model9db_initdb:/docker-entrypoint-initdb.d \
s390x/alpine tail -f /dev/null

docker exec -it dummy sh
cd /root
unzip /root/model9-v3.0.1_build_56bdebd-server-s390x.zip 'model9*'

# Verify the existence of the diag directory. Create it if needed.
mkdir diag

# Backup the /conf directory.
tar -czf conf-backup.tar.gz conf

# Exit from the alpine container.
exit

Copy the docker container images from the alpine docker container (the one that was used during the initial installation):

docker cp dummy:/root/model9-v3.0.1_build_56bdebd-s390x.docker ./

Task 5: To load the new release artifacts

Load the new release docker containers:

docker load -i model9-v3.0.1_build_56bdebd-s390x.docker

Task 6: To back up the server before the upgrade

Warning

Back up the local configuration and database volume to avoid loss of data.

Run each command separately and check the results:

fileStamp=$(date +%Y-%m-%d)
docker cp dummy:/root/conf-backup.tar.gz ./conf-$fileStamp.tar.gz
docker exec -it model9db pg_dump -p 5432 -U postgres -d model9 -f /tmp/model9db-$fileStamp.dump
docker cp model9db:/tmp/model9db-$fileStamp.dump ./model9db-$fileStamp.dump
docker exec -ti model9db rm /tmp/model9db-$fileStamp.dump

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 zCX issue:
docker run --shm-size=256m -p 127.0.0.1:5432:5432 \
-v model9db:/var/lib/postgresql/data:z \
-v model9db_initdb:/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 verify and update the BMC AMI Cloud environmental variables file

BMC AMI Cloud management server loads its environmental variables from the model9.env file.

You can use this file for the following purposes:

  • Set simple (non-array) environment variables.
  • Simplify how you start the server.
  • Get a point of reference to the variables that the management server was started with.
  1. Verify that the   model9.env file is in the user's home 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 Xmx 8192m. 

    Important

    If the container is already up with a lower value, you can 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.
  5. Save the file.

If you make a change to any of the parameters in the environment variables file, stop, and remove the server Docker container, and issue the Docker run command again.

Task 9: To start the BMC AMI Cloud server

Run the new release container using the following command:

docker run -d -p <zCX-VIPA>:443:443 -p <zCX-VIPA>: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:/model9:z -h $(hostname) --restart unless-stopped \
--env-file <user home directory>/model9.env \
--network model9network \
--name model9-v3.0.1 model9:v3.0.1.56bdebd

Important

Replace <zCX-VIPA> with the zCX instance VIPA.

Warning

By default, BMC AMI Cloud uses ports 80 and 443 for the management server. If these ports are not available for use or you want to use different ports, update the -p parameters to use different ports. For example, to use port 8080 and port 8443, update the parameters as follows:
-p <zCX-VIPA>:8443:443 -p <zCX-VIPA>:8080:80

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 to download a 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

    The output of the z/OS command D M=CPU is required.

Task 2: To upload the s390x installation zip file

Upload the s390x installation zip to the zCX instance using scp or any other tool in binary mode.

Copy the s390x installation zip from the zCX instance to the alpine container:

docker cp model9-v3.0.0_build_7b35826-server-s390x.zip dummy:/root/model9-v3.0.0_build_7b35826-server-s390x.zip

Task 3: To stop BMC AMI Cloud

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>

Task 4: To prepare the installation artifacts

In the Alpine container, open the BMC AMI Cloud artifact:

# Create a new docker volume for initdb
docker volume create model9db_initdb

# Stopping the old alpine container
docker stop dummy
docker rm dummy

# Running an alpine container and mounting the model9 docker volume
docker run -d --rm --name dummy \
-v model9:/root \
-v model9db_initdb:/docker-entrypoint-initdb.d \
s390x/alpine tail -f /dev/null

docker exec -it dummy sh
cd /root
unzip /root/model9-v3.0.0_build_7b35826-server-s390x.zip 'model9*'

# Verify the existence of the diag directory. Create it if needed.
mkdir diag

# Backup the /conf directory.
tar -czf conf-backup.tar.gz conf

# Exit from the alpine container.
exit

Copy the docker container images from the alpine docker container (the one that was used during the initial installation):

docker cp dummy:/root/model9-v3.0.0_build_7b35826-s390x.docker ./

Task 5: To load the new release artifacts

Load the new release docker containers:

docker load -i model9-v3.0.0_build_7b35826-s390x.docker

Task 6: To back up the server before the upgrade

Warning

Back up the local configuration and database volume to avoid loss of data.

Run each command separately and check the results:

fileStamp=$(date +%Y-%m-%d)
docker cp dummy:/root/conf-backup.tar.gz ./conf-$fileStamp.tar.gz
docker exec -it model9db pg_dump -p 5432 -U postgres -d model9 -f /tmp/model9db-$fileStamp.dump
docker cp model9db:/tmp/model9db-$fileStamp.dump ./model9db-$fileStamp.dump
docker exec -ti model9db rm /tmp/model9db-$fileStamp.dump

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 zCX issue:
docker run --shm-size=256m -p 127.0.0.1:5432:5432 \
-v model9db:/var/lib/postgresql/data:z \
-v model9db_initdb:/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 verify and update the BMC AMI Cloud environmental variables file

BMC AMI Cloud management server loads its environmental variables from the model9.env file.

You can use this file for the following purposes:

  • Set simple (non-array) environment variables.
  • Simplify how you start the server.
  • Get a point of reference to the variables that the management server was started with.
  1. Verify that the   model9.env file is in the user's home 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 Xmx 8192m. 

    Important

    If the container is already up with a lower value, you can 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.
  5. Save the file.

If you make a change to any of the parameters in the environment variables file, stop, and remove the server Docker container, and issue the Docker run command again.

Task 9: To start the BMC AMI Cloud server

Run the new release container using the following command:

docker run -d -p <zCX-VIPA>:443:443 -p <zCX-VIPA>: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:/model9:z -h $(hostname) --restart unless-stopped \
--env-file <user home directory>/model9.env \
--network model9network \
--name model9-v3.0.0 model9:v3.0.0.7b35826

Important

Replace <zCX-VIPA> with the zCX instance VIPA.

Warning

By default, BMC AMI Cloud uses ports 80 and 443 for the management server. If these ports are not available for use or you want to use different ports, update the -p parameters to use different ports. For example, to use port 8080 and port 8443, update the parameters as follows:
-p <zCX-VIPA>:8443:443 -p <zCX-VIPA>:8080:80

 

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