Upgrading the on-premises gateway on Docker containers

To prepare for the upgrade

1. Review the system requirements and download the container images and utility files.
2. Back up the connector configurations, see Backing-up-and-restoring-connector-configurations.
3. Back up the /<IIGateway_INSTALL_DIR>/hii/docker-compose.yaml file.
4. Navigate to the /<IIGateway_INSTALL_DIR> directory, and run the following command to archive the hii directory: tar -cvf hii.tar hii
5. Before upgrading to version 25.1 if authentication is disabled for the on-premises gateway, and if you don't want to enable the authentication after the upgrade and you have customized the nginx.conf file, perform the following steps:
   1. Navigate to the /<IIGateway_INSTALL_DIR>/hii/conf directory.
   2. Back up the nginx.conf file to a temporary directory.
6. If you are upgrading to version 25.1 from 24.3.01 and authentication is enabled for the on-premises gateway before the upgrade, perform the following tasks:
   1. Create the iig_auth directory under the <userHome> directory if it doesn't exist. Back up the /<IIGateway_INSTALL_DIR>/hii/conf/nginx.conf file in the iig_auth directory.
   2. Check whether the <userHome>/iig_auth directory contains the external.conf file. If the file is not present, copy it from the /<IIGateway_INSTALL_DIR>/hii/conf/authproxy directory to the iig_auth directory.
7. If you are using BMC Helix IT Operations Management on premises and you are enabling authentication for the on-premises gateway for the first time after the upgrade, register the OAuth client.
   For more information, see Setting-up-authentication-for-the-on-premises-gateway.

Task 1: To upgrade the on-premises on Docker containers if you are a Helix subscriber

1. Go to the server where you want to upgrade the on-premises gateway.
2. Copy the following files that you have downloaded to the /<IIGateway_INSTALL_DIR> directory: 
   • Container images: bmc-hii-docker-images-<buildNumber>.tgz
   • Utility file: hii-bmc-<buildNumber>.zip
3. Perform the following steps to update the container images:

   1. Stop the docker-compose service:

      docker compose down

   2. Load the container images:

      docker load --input /<IIGateway_INSTALL_DIR>/bmc-hii-docker-images-<buildNo>.tgz
4. Navigate to the /opt/bmc/hii/defaults directory and delete the following files if they exist:
   • docker-compose.yaml_Rsso
   • podman-compose.yaml_Rsso
   • nginx.conf_Rsso

5. Obtain the database version:

   cat docker-compose.yaml | grep image | grep arango
6. Extract hii-bmc-<buildNumber>.zip and overwrite the existing files in the /<IIGateway_INSTALL_DIR>/hii directory.
7. If the database version is earlier than 3.12.2, perform the following steps to upgrade the database; otherwise, skip to step 8.

   1. Open the /<IIGateway_INSTALL_DIR>/hii/docker-compose.yaml file with a text editor and search for the following line:

      #      - --database.auto-upgrade

   2. Uncomment the line:

      - --database.auto-upgrade

   3. Start the docker-compose service:

      docker compose up -d

   4. Open the /<IIGateway_INSTALL_DIR>/hii/docker-compose.yaml file with a text editor and search for the following line:

      - --database.auto-upgrade

   5. Comment the line:

      #      - --database.auto-upgrade

   6. Stop the docker-compose service:

      docker compose down

8. Change permissions on the /<IIGateway_INSTALL_DIR>/hii/logs directory:

   chmod 777 /<IIGateway_INSTALL_DIR>/hii/logs
9. If you have customized the docker-compose.yaml file before the upgrade, copy the customizations done in the file to the docker-compose.yaml file in the /<IIGateway_INSTALL_DIR>/hii directory.
10. Depending on whether you want to enable or disable authentication for the on-premises gateway after the upgrade, perform one of the following steps :
    • To upgrade to the on-premises gateway with authentication enabled, perform the following steps:
      1. (Optional) To register the BMC Helix Single Sign-On client again, perform the following steps:
         1. Delete the <userHome>/iig_auth directory.
         2. Replace the /<IIGateway_INSTALL_DIR>/hii/scripts/cred.json file with the cred.json file extracted from /<IIGateway_INSTALL_DIR>/hii in step 6.
      2. Navigate to the /<IIGateway_INSTALL_DIR>/hii/scripts directory.

      3. Run the gateway_deployment.sh script:

         ./gateway_deployment.sh

          

      4. Enter docker when prompted for the deployment method.
      5. Enter y to upgrade to the on-premises gateway with authentication enabled.
      6. Enter the following information:

         • Access key and access secret key: Access key and secret key required to access the BMC Helix applications.
           For instructions about how to generate the access key and secret key, see Setting up access keys for programmatic access.

           Important

           The keys are generated in the following format: key:<access key>::<access secret key>,tenant id:<tenant ID>. Enter <access key> and <access secret key> as the values of access key and access secret key.

           The access key and access secret key must have the Administrators group and the Administrator role assigned.

         • Tenant Id: BMC Helix tenant ID.
           Copy the tenant ID from the access key (key:<access key>::<secret key>,tenant id: <tenant ID>).
         • Tenant URL: BMC Helix tenant URL.
           For example, https://swp-2021-1840-disceks1.abc.com .
         • Host name: Name of the server where you want to deploy the on-premises gateway.
           The on-premises gateway is upgraded and authentication is enabled. Also, the cred.json, external.config, and nginx.config configuration files are backed up in the /<userHome>/iig_auth directory.
    • To upgrade to the on-premises gateway with authentication disabled, perform the following steps:
      1. If you have backed up the nginx.conf file, as described in Before you begin, copy the customizations done in the file to the nginx_noauth.conf file in the <IIGateway_INSTALL_DIR>/hii/defaults directory.
      2. Navigate to the /<IIGateway_INSTALL_DIR>/hii/scripts directory.

      3. Run the gateway_deployment.sh script:

         ./gateway_deployment.sh 

          

      4. Enter docker when prompted for the deployment method.
      5. Enter n to upgrade to the on-premises gateway with authentication disabled.
         The on-premises gateway is upgraded, and authentication is disabled.

11. Verify that all containers are running.

    docker ps -a

    If any of the container is in restarting state due to permission issues, set the user context for that container. For more information, see Troubleshooting-the-BMC-Helix-Intelligent-Integrations-issues.

12. Access the BMC Helix Intelligent Integrations UI by using the following URL: https://<hostName>:443/swpui
    <hostName> is the fully-qualified domain name of the server where the on-premises gateway is deployed. 
    For example, https://swp-2021-1840-disceks1.abc.com:443/swpui .

    Important

    After the upgrade is complete, you can access the BMC Helix Intelligent Integrations UI by using the URL specified in this step. BMC Helix Portal does not display any tile for the on-premises gateway. 

13. If the UI is accessible, delete and purge the existing container images:

    docker image prune -a

    When prompted, enter y to purge the previous version images from the repository.

Task 1: To upgrade the on-premises gateway on Docker containers if you are using BMC Helix IT Operations Management on premises

1. Go to the server where you want to upgrade the on-premises gateway.
2. Copy the following files that you have downloaded to the /<IIGateway_INSTALL_DIR> directory: 
   • Container images: bmc-hii-docker-images-<buildNumber>.tgz
   • Utility file: hii-bmc-<buildNumber>.zip
3. Perform the following steps to update the container images:

   1. Stop the docker-compose service:

      docker compose down

   2. Load the container images:

      docker load --input /<IIGateway_INSTALL_DIR>/bmc-hii-docker-images-<buildNo>.tgz
4. Navigate to the /opt/bmc/hii/defaults directory and delete the following files if they exist:
   • docker-compose.yaml_Rsso
   • podman-compose.yaml_Rsso
   • nginx.conf_Rsso

5. Obtain the database version:

   cat docker-compose.yaml | grep image | grep arango
6. Extract hii-bmc-<buildNumber>.zip and overwrite the existing files in the /<IIGateway_INSTALL_DIR>/hii directory.
7. If the database version is earlier than 3.12.2, perform the following steps to upgrade the database; otherwise, skip to step 8.

   1. Open the /<IIGateway_INSTALL_DIR>/hii/docker-compose.yaml file with a text editor and search for the following line:

      #      - --database.auto-upgrade

   2. Uncomment the line:

      - --database.auto-upgrade

   3. Start the docker-compose service:

      docker compose up -d

   4. Open the /<IIGateway_INSTALL_DIR>/hii/ docker-compose.yaml file with a text editor and search for the following line:

      - --database.auto-upgrade

   5. Comment the line:

      #      - --database.auto-upgrade

   6. Stop the docker-compose service:

      docker compose down

8. Change permissions on the /<IIGateway_INSTALL_DIR>/hii/logs directory:

   chmod 777 /<IIGateway_INSTALL_DIR>/hii/logs
9. If you have customized the docker-compose.yaml file before the upgrade, copy the customizations done in the file to the docker-compose.yaml file in the /<IIGateway_INSTALL_DIR>/hii directory.
10. If authentication is disabled for the on-premises gateway before the upgrade and you don't want to enable authentication after the upgrade, perform the following steps; otherwise skip to step 11.
    1. If you have backed up the nginx.conf file, as described in Before you begin, copy the customizations done in the file to the nginx_noauth.conf file in the <IIGateway_INSTALL_DIR>/hii/defaults directory.
    2. Navigate to the /<IIGateway_INSTALL_DIR>/hii/scripts directory.

    3. Run the gateway_deployment.sh script:

       ./gateway_deployment.sh

        

    4. Enter docker when prompted for the deployment method.
    5. Enter n to deploy the on-premises gateway with authentication disabled.
       The on-premises gateway is upgraded, and authentication is disabled.
    6. Go to step 13 to verify the status of the containers. 
11. If authentication is disabled for the on-premises gateway before the upgrade, and you want to enable it for the first time after the upgrade, perform the following steps; otherwise skip to step 12:
    1. Perform the following steps to update the BMC Helix SSO configuration for Auth Proxy:
       1. Navigate to the <IIGATEWAY_INSTALL_DIR>/hii/conf/authproxy directory and open the external.conf file with a text editor.
       2. Update the file:
          • Search for the rsso_external_url and rsso_internal_url parameters and replace {RSSO_URL} with the OpenID Connect Issuer URL.
          • Search for the client_id parameter and replace {RSSO_CLIENT_ID} with the Client ID that you saved in a file while registering the OAuth client.
          • Search for the client_secret parameter and replace {RSSO_CLIENT_SECRET} with the Client Secret that you saved in a file while registering the OAuth client.
          • Locate the proxies section, and replace {TENANT_URL} with the BMC Helix tenant URL. For example, https://swp-2021-1840-disceks1.abc.com.
       3. Save the file.
    2. Perform the following steps to update the neo.feature.flags.auth-enabled parameter:
       1. Navigate to the /<IIGateway_INSTALL_DIR>/hii/conf directory.
       2. Open the swp.conf file with a text editor.
       3. Set the value of the neo.feature.flags.auth-enabled parameter to true.
       4. Save the file.

    3. Start the docker-compose service:

       docker compose up -d
    4. Go to step 13 to verify the status of the containers. 
12. If authentication is enabled for the on-premises gateway before the upgrade and you want to continue with authentication after the upgrade, perform the following steps:
    1. Perform the following steps to update the neo.feature.flags.auth-enabled parameter:
       1. Navigate to the /<IIGateway_INSTALL_DIR>/hii/conf directory.
       2. Open the swp.conf file with a text editor.
       3. Set the value of the neo.feature.flags.auth-enabled parameter to true.
       4. Save the file.
    2. Copy the nginx.conf file from the <userHome>/iig_auth directory to the  /<IIGateway_INSTALL_DIR>/hii/conf directory.
    3. Copy the external.conf file from the <userHome>/iig_auth directory to the /<IIGateway_INSTALL_DIR>/hii/conf/authproxy directory.

    4. Start the docker-compose service:

       docker compose up -d
    5. Go to step 13 to verify the status of the containers. 

13. Verify that all containers are running.

    docker ps -a

    If any of the container is in restarting state due to permission issues, set the user context for that container. For more information, see Troubleshooting-the-BMC-Helix-Intelligent-Integrations-issues.

14. Access the BMC Helix Intelligent Integrations UI by using the following URL:
    https://<hostName>:443/swpui
    <hostName> is the fully-qualified domain name of the server where the on-premises gateway is deployed. 
    For example, https://swp-2021-1840-disceks1.abc.com:443/swpui

    Important

    After the upgrade is complete, you can access the BMC Helix Intelligent Integrations UI by using the URL specified in this step. BMC Helix Portal does not display any tile for the on-premises gateway.

15. If the UI is accessible, delete and purge the existing container images:

    docker image prune -a

    When prompted, enter y to purge the previous version images from the repository. 

Task 2: To import custom or CA-signed certificates into the on-premises gateway

1. Obtain the custom or CA-signed certificates from the BMC Helix platform deployment which the on-premises gateway is part of and save it in the <IIGateway_INSTALL_DIR>hii/conf folder.

2. Copy the cacerts file present in the swp-mediator container at /opt/java/openjdk/lib/security to the /<IIGateway_INSTALL_DIR>/hii/conf/certs directory by using the following command:

   docker cp swp-mediator:/opt/java/lib/security/cacerts /<IIGateway_INSTALL_DIR>hii/conf/certs/cacerts_mediator
   
   

3. (Required if authentication is enabled for the on-premises gateway) Copy the cacerts file present in the swp-authproxy container at /opt/java/openjdk/lib/security to the /<IIGateway_INSTALL_DIR>/hii/conf/certs directory by using the following command:

   docker cp swp-authproxy:/opt/java/openjdk/lib/security/cacerts /<IIGateway_INSTALL_DIR>hii/conf/certs/cacerts_authproxy
4. Navigate to the /<IIGateway_INSTALL_DIR>/hii/conf/certs folder.
5. Import the certificates into the copied files by using the keytool utility.

   • Import the certificates into the cacerts_mediator file by using the following command:

     keytool -importcert -file <certificate_name> -keystore cacerts_mediator -alias <alias_name>

     Replace the certificate_name with the certificate name that you obtained from the BMC Helix platform deployment.

   • (Required if authentication is enabled for the on-premises gateway) Import the certificates into the cacerts_authproxy file by using the following command:

     keytool -importcert -file <certificate_name> -keystore cacerts_authproxy -alias <alias_name>

     Replace the certificate_name with the certificate name that you obtained from the BMC Helix platform deployment.

6. Open the /<IIGateway_INSTALL_DIR>/hii/docker-compose.yaml file with a text editor:
7. Update the file:

   • Search for the  mediator  section and add the following line to the  volumes  section:

     - ./conf/certs/cacerts_mediator:/opt/java/lib/security/cacerts

   • (If authentication is enabled for the on-premises gateway) Search for the authproxy section and add the following line to the volumes section:

     - ./conf/certs/cacerts_authproxy:/opt/java/openjdk/lib/security/cacerts
8. Save and close the docker-compose.yaml file.

9. Restart the container service by using the following commands:

   docker compose down
   docker compose up -d

Task 3: To edit the connector in BMC Helix Intelligent Integrations

If there are any updates in the connector configuration during upgrade, the existing connector instances are not updated automatically after upgrade. You need to either create a new connector instance or stop the existing data stream and create a new data stream.

For the list of updates in various connectors in version 25.1, see 25-1-enhancements-and-patches. For information about editing an existing connector for data streams, see Editing-and-deleting-integrations and Starting-or-stopping-data-streams.

Task 4: To update the collector URL in the third-party product

If you have switched authentication for the on-premises gateway during upgrade, perform the following steps to update the collector URL in the third-party product (for example, Entuity) from which you are collecting data:

1. Access the BMC Helix Intelligent Integrations UI by using the following URL:
   https://<hostName>:443/swpui
   <hostName> is the fully-qualified domain name of the server where the on-premises gateway is deployed.
2. On the SOURCES panel, click Configure Mediator for the source connection that you created and then expand the < thirdPartyProduct Datatype> panel.
3. On the COLLECTOR CONFIGURATION tab, click copy to copy the existing, auto-generated collector URL and save the URL in a temporary file.
    For example, https://hostA/hii/api/mediator/v3/push/9mn-6c97-4c2e-8pc5-12c0asdf?token=API-KEY.
4. Depending on whether authentication is enabled or disabled for the on-premises gateway, perform the following steps:
   • If authentication is enabled, perform the following steps:

     1. Log on to BMC Helix Portal and generate an access key.
        For instructions about how to generate the access key, see Setting up access keys for programmatic access. 

     2. Copy the generated access key and save it in a temporary file.
        The key is generated in the format:<accessKey>::<secretKey>::<tenantID>.
        For example, Y40OSC49QZA11Q8A1H9H6::MnVLk69TNyCEponsthHJ1Hj1uKcjTB::385261281.
     3. Change the format of the access key to <tenantID>::<accessKey>::<secretKey>.
        For example, 385261281::Y40OSC49QZA11Q8A1H9H6::MnVLk69TNyCEponsthHJ1Hj1uKcjTB.
     4. In a temporary file, modify the auto-generated collector URL by replacing API-KEY with the access key that you formatted in the previous step.
        For example, https://host.ab.com/hii/api/mediator/v3/push/9mn-6c97-4c2e-8pc5-12c0asdfd?token=385261281::Y40OSC49QZA11Q8A1H9H6::MnVLk69TNyCEponsthHJ1Hj1uKcjTB .
   • If authentication is disabled, perform the following steps:
     1. Save the URL in a temporary file.
     2. Remove the following string from the collector URL: ?token=API-KEY
         The updated collector URL looks like the following example:
        https://hostA/hii/api/mediator/v3/push/9mn-6c97-4c2e-8pc5-12c0asdf  

Task 5: To configure the third-party product

Configure the third-party product again to forward data to BMC Helix Intelligent Integrations.
For the sample instructions to update the collector URL in a third-party product, see To configure a connection with Entuity for collecting incidents data.

To roll back the on-premises gateway upgrade

1. Stop the docker-compose service:

   docker compose down

2. Rename the /<IIGateway_INSTALL_DIR>/hii directory:

   mv hii hii_upgrade

   You might need this directory for debugging. 

3. If you have enabled authentication during the upgrade, navigate to the <userHome> directory and delete the iig_auth directory and any other directories or files created in this directory during the upgrade.

4. Delete and purge the container images:

   docker image prune -a

   When prompted, enter y to purge the images from the repository. 

5. Load the container images for the version from which you have upgraded:

   docker load --input /<IIGateway_INSTALL_DIR>/bmc-hii-docker-images-<buildNo>.tgz

6. Extract the backed up hii.tar:

   tar -xvf /<IIGateway_INSTALL_DIR>/hii.tar -C /<IIGateway_INSTALL_DIR>/

7. Start the docker-compose service:

   docker compose up -d
8. Access the BMC Helix Intelligent Integrations UI by using the following URL: https://<hostName>:443/swpui
   <hostName> is the fully-qualified domain name of the server where the on-premises gateway is deployed. 
   For example,  https://swp-2021-1840-disceks1.abc.com:443/swpui.