Skip to Content

Deploying the on-premises gateway on Podman containers

Use the Podman container images to deploy the BMC Helix Intelligent Integrations on-premises gateway in your on-premises environment.

 

Related topics

Setting-up-and-going-live

Supported-out-of-the-box-integrations-for-BMC-Helix-Intelligent-Integrations

Upgrading-the-on-premises-gateway-on-Podman-containers

Monitoring BMC Helix Intelligent Integrations

Before you begin

Before you deploy the on-premises gateway, review the following prerequisites: 

  • Review the system requirements and obtain the container images and utility files.
  • If both BMC Helix Intelligent Integrations and BMC Helix applications are deployed in your on-premises environment as part of the BMC Helix IT Operations Management on-premises entitlement and you want to enable authentication for the on-premises gateway, register the OAuth client. For more information, see set up authentication for the on-premises gateway.

Depending upon whether you are a Helix subscriber or you are using BMC Helix Operations Management on premises, start the deployment process by performing one of the following tasks:

 

Task 1 (If you are a Helix subscriber): To deploy the on-premises gateway on Podman containers

  1. Go to the server where you want to deploy the on-premises gateway.
  2. Copy the following files that you obtained from BMC Support to a temporary directory, for example, /<IIGateway_INSTALL_DIR>:
    • Utility file: hii-bmc-<buildNumber>.zip
    • Container images: 
      On-premises gateway versionFile nameDescriptionDownload required?
      25.3.01bmc-hii-docker-images-<buildNumber>.tgzContainer images for deploying the on-premises gatewayYes
      bmc-hii-tp-docker-images-<buildNumber>.tgz

      Container images for monitoring the on-premises gateway node and container health by using dashboards

      Yes, if you want to monitor the on-premises gateway

      Even if you don't obtain and load these images, you can continue monitoring the on-premises gateway instances by using events.

      25.3.00bmc-hii-docker-images-<buildNumber>.tgzContainer images for deploying the on-premises gatewayYes
      bmc-hii-tp-docker-images-<buildNumber>.tgz

      Container images for Grafana

      		Yes
  3. Disable SELinux:
    1. Open the /etc/selinux/config file with a text editor.

    2. Set SELINUX to disabled.
      # This file controls the state of SELinux on the system.
      # SELINUX= can take one of these three values:
      #       enforcing - SELinux security policy is enforced.
      #       permissive - SELinux prints warnings instead of enforcing.
      #       disabled - No SELinux policy is loaded.
      SELINUX=disabled
      # SELINUXTYPE= can take one of these two values:
      #       targeted - Targeted processes are protected,
      #       mls - Multi Level Security protection.
      SELINUXTYPE=targeted

  4. Reboot the server:
    /sbin/reboot now

  5. Disable firewalld:
    systemctl disable firewalld

  6. Set the HOSTNAME variable to the fully-qualified domain name of the server where you are installing the on-premises gateway if not set already, as shown in the following example:
    echo "export HOSTNAME=hostA.mycompany.com" >> ~/.bash_profile
    source ~/.bash_profile

  7. Navigate to the <IIGateway_INSTALL_DIR> directory, and depending on the on-premises gateway version you are using, perform the following steps:

    VersionSteps
    25.3.01
    1. Load the container images to deploy the on-premises gateway:
      podman load --input bmc-hii-docker-images-<buildNumber>.tgz
    2. (Optional) Perform the following steps if you want to monitor the on-premises gateway node and container health by using dashboards:

      1. Untar the container images:
        tar -zxvf bmc-hii-tp-docker-images-<buildNumber>.tgz

      2. Load the container images:
        find ./bmc-hii-tp-docker-images-<VERSION> -type f -name "*.tgz" -exec podman load --input "{}" \;

    25.3.00

    1. Load the container images to deploy the on-premises gateway:
      podman load --input bmc-hii-docker-images-<buildNumber>.tgz
    2. Untar the container images for Grafana:
      tar -zxvf bmc-hii-tp-docker-images-<buildNumber>.tgz
    3. Load the container images for Grafana:
      podman load --input bmc-hii-tp-docker-images-<buildNumber>/hii-grafana.tgz
  8. Extract the utility file, hii-bmc-<buildNumber>.zip:
    unzip hii-bmc-<buildNumber>.zip

  9.  

    Configure SSL.
    1. Perform one of the following actions to obtain the certificate and private keys:

      • Generate a self-signed certificate by using the following command:

        openssl req -x509 -sha256 -days 397 -nodes -newkey rsa:2048 -subj "/CN=<commonName>/C=<countryName>/L=<locality>" -keyout <hostName>.key -out <hostName>.crt

        In the command, replace  <hostName>  with the fully qualified domain name of the server where you are installing the on-premises gateway.

      • Obtain a CA-signed certificate and private keys from the Certificate Authority.
    2. Create the certs directory in the /<IIGateway_INSTALL_DIR>/hii/conf directory if it does not exist.
    3. Copy the certificate and private key you obtained to the /<IIGateway_INSTALL_DIR>/hii/conf/certs directory, and ensure that the names of the certificate and private key files are in the following format:
      < hostName>.crt and <hostName>.key
      <hostName> is the fully-qualified domain name of the server where you are installing the on-premises gateway.

    4. Change permissions on the /<IIGateway_INSTALL_DIR>/hii/conf/certs directory:

      chmod -R 755 /<IIGateway_INSTALL_DIR>/hii/conf/certs
    5. Open the hii/conf/nginx.conf file with a text editor. 

    6. Comment the following line:

      listen 443 ssl

    7. Uncomment the following line:

      # listen 7443 ssl
    8. Save and close the file.

    If you encounter any issues, see To troubleshoot SSL issues to resolve them

  10. If you plan to deploy the on-premises gateway for which authentication is enabled, configure the protocol to be used (defaults to HTTP) for authorization between the on-premises gateway and the Identity Management System (IMS), which is part of the BMC Helix platform:
    1. Navigate to the /<IIGateway_INSTALL_DIR>/hii directory.
    2. Open the podman-compose.yaml file by using a text editor.
    3. Locate the mediator > environment section and search for the USE_HTTPS_IMS_URL parameter.

    4. Set the parameter to one of the following values: 

      • true: The HTTPS protocol is used for communication.
      • false (default): The HTTP protocol is used for communication.
      Warning
      Important (For version 25.3.00 only)

      Enclose the parameter value in double quotes, as shown in the following example:
      USE_HTTPS_IMS_URL: "false"

    5. Locate the backup > environment section and add the USE_HTTPS_IMS_URL parameter if it does not exist.

    6. Set the parameter to one of the following values: 

      • true: The HTTPS protocol is used for communication.
      • false (default): The HTTP protocol is used for communication.
      Warning
      Important (For version 25.3.00 only)

      Enclose the parameter value in double quotes, as shown in the following example:
      USE_HTTPS_IMS_URL: "false"

    7. Save and close the file.
  11. Depending on whether you want to enable or disable the authentication for the on-premises gateway, perform one of the following steps :
    • To deploy the on-premises gateway for which authentication is enabled, perform the following steps:
      1. Navigate to the /<IIGateway_INSTALL_DIR>/hii/scripts directory.
      2. Run the gateway_deployment.sh script:
        ./gateway_deployment.sh
      3. Enter podman when prompted for the deployment method.
      4. Enter y to deploy the on-premises gateway.
      5. 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..

          Warning

          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 the 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.
        • Host name: Fully-qualified name of the server where you want to deploy the on-premises gateway.
          After you provide all the credentials, the on-premises gateway is deployed. Also, the cred.json, external.config, and nginx.config configuration files are backed up in the /<userHome>/iig_auth directory.
      6. Perform one of the following tasks:
        • (Version 25.3.01 and later only) Go to step 12 if you want to monitor the on-premises gateway node and container health by using dashboards.
        • Go to step 13 to configure the BMC Helix destination.
    • To deploy the on-premises gateway for which authentication is disabled, perform the following steps:
      1. Navigate to the /<IIGateway_INSTALL_DIR>/hii/scripts directory.

      2. Run the gateway_deployment.sh script:

        ./gateway_deployment.sh

         

      3. Enter podman when prompted for the deployment method.

      4. Enter n to start deploying the on-premises gateway with authentication is disabled.

        Warning
        Important

        You can enable the authentication after the deployment if needed. For more information, see To enable authentication for the on-premises gateway after the deployment if you are a Helix subscriber.

      5. Perform one of the following tasks:
        1. (Version 25.3.01 and later only) Go to step 12 if you want to monitor the on-premises gateway node and container health by using dashboards.
        2. Go to step 13 to configure the BMC Helix destination.
  12. (Optional, Version 25.3.01 and later only) Perform the following steps to monitor the on-premises gateway node and container health by using dashboards:
    1. Navigate to the /<IIGateway_INSTALL_DIR>/hii/scripts directory.
    2. Run the gateway_monitoring_services_deployment.sh script:
      ./gateway_monitoring_services_deployment.sh
    3. Enter podman when prompted for the deployment method.
      After the deployment starts, if you see the following warning, ignore it: 
      Found orphan containers (swp-arangodb, swp-mediator, swp-fluentd, swp-ui, kafka-1, swp-nginx, swp-backup, zookeeper-1)
      for this project. If you removed or renamed this service in your compose file, you can run this command
      with the --remove-orphans flag to clean it up.
  13. Perform the following steps to configure the BMC Helix destination to which you want to send data collected by BMC Helix Intelligent Integrations:

    1. Create a file with the following contents and name it ade-default-destination-min.json:

      [
        {
          "entityKind": "Destination",
          "configWithSchema": {
            "config": {
              "connection": {
        "proxyUsername": "",
                "proxyPassword": "",
                "accessSecretKey": "CHANGEME",
                "allowUnsignedCertificate": false,
                "logResponses": false,
                "pipeLiningLimit": 1,
                "proxyHost": "",
                "logRequests": false,
                "timeout": {
                  "unit": "MINUTES",
                  "value": 15
                },
                "proxyPort": 8888,
                "maxResponseSize": 1000000,
                "usesHttps": true,
                "accessKey": "CHANGEME",
                "port": 443,
                "minConnections": 0,
                "tenantId": "CHANGEME",
                "connectingTimeout": {
                  "unit": "SECONDS",
                  "value": 30
                },
                "host": "CHANGEME - BMC Helix tenant host name - for example: swp-2021-1840-disceks1.abc.com",
                "poolTimeout": {
                  "unit": "MINUTES",
                  "value": 30
                },
                "maxOpenRequests": 1024,
                "maxConnections": 5,
                "maxRedirects": 5,
                "usesProxy": false
              },
              "poolTimeout": {
                "unit": "MINUTES",
                "value": 30
              }
            }
          },
          "instanceName": "BMC",
          "tenantId": "287c466d-7467-4e72-9e52-8357b4a27eaf",
          "typeName": "BmcDestination",
          "id": "CHANGEME - GENERATE NEW UUID using https://www.uuidgenerator.net/version4 e.g. 2643e089-18a8-4b0d-a58a-c022926812e0  MUST BE UNIQUE in a stack",
          "moduleId": "bmc"
        }
      ]
    2. Enter the values of the following parameters in the file:
      • proxyUsername: User name for the proxy.
      • proxyPassword: Password for the proxy.
      • proxyPort: Proxy port number.
      • proxyHost: Host name of the proxy.
      • usesProxy: Whether a proxy should be used for communication. Set its value to true or false depending on whether proxy should be used. 
    3. Replace the CHANGEME value of the following parameters with the generated values:

      • accessKeyand accessSecretKey: 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.

        Warning

        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 the access key and access secret key.
        • The access key and access secret key must have the Administrators group and the Administrator role assigned
      • tenantId(first occurrence only): BMC Helix tenant ID.
        Copy the tenant ID from the access key (key:<access key>::<secret key>,tenant id: <tenant ID>) that you generated earlier and replace the CHANGEME occurrences with the copied tenant ID.
      • host: BMC Helix tenant host name.
        For example, if the tenant URL is         https://swp-2021-1840-disceks1.abc.com, replace CHANGEME with swp-2021-1840-disceks1.abc.com.
      • id: Universally unique identifier (UUID).
        Access https://www.uuidgenerator.net/version4 to generate UUID.

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

      Warning

      Important

      • BMC Helix Portal does not display any tile for the BMC Helix Intelligent Integrations on-premises gateway. Access the UI by using the URL specified in this step. 
      • If you encounter an issue when accessing or using BMC Helix Intelligent Integrations, see Troubleshooting the BMC Helix Intelligent Integrations issues.

    5. Import the ade-default-destination-min.json file by using the Backup/Restore option to create the destination.
      For more information, see Backing-up-and-restoring-connector-configurations.

      Information
      Can I create more than one BMC destination for one instance of the on-premises gateway?

      No, BMC Helix Intelligent Integrations supports only one destination for one instance of on-premises gateway.

    6. Edit the destination connection details:
      1. On the CONNECTORS tab, click Configure Mediator ConfigureMediator_icon.pngon the DESTINATIONS panel.
      2. Replace the existing values in the Access Key and Access Secret Key fields with the values that you have copied in the ade-default-destination-min.json file in step 13(c). 
      3. Click Validate to validate the connection.
      4. Click Save & Close.
  14. If you are using SSL certificates, import them into the on-premises gateway.

Task 1 (If you are using BMC Helix IT Operations Management on premises): To deploy the on-premises gateway on Podman containers

  1. Go to the server where you want to deploy the on-premises gateway.
  2. Copy the following files that you obtained to a temporary directory, for example, /<IIGateway_INSTALL_DIR>:
    • Utility file: hii-bmc-<buildNumber>.zip
    • Container images: 
      On-premises gateway versionFile nameDescriptionDownload required?
      25.3.00bmc-hii-docker-images-<buildNumber>.tgzContainer images for deploying the on-premises gatewayYes
      bmc-hii-tp-docker-images-<buildNumber>.tgz

      Container images for Grafana

      		Yes
  3. Disable SELinux:
    1. Open the /etc/selinux/config file with a text editor.

    2. Set SELINUXSELINUXData URI image to disabled.

      # This file controls the state of SELinux on the system.
      # SELINUX= can take one of these three values:
      #       enforcing - SELinux security policy is enforced.
      #       permissive - SELinux prints warnings instead of enforcing.
      #       disabled - No SELinux policy is loaded.
      SELINUX=disabled
      # SELINUXTYPE= can take one of these two values:
      #       targeted - Targeted processes are protected,
      #       mls - Multi Level Security protection.
      SELINUXTYPE=targeted

  4. Reboot the server:

    /sbin/reboot now

  5. Disable firewalld:

    systemctl disable firewalld

  6. Set the HOSTNAME variable to the fully-qualified domain name of the server where you are installing the on-premises gateway if not set already, as shown in the following example:

    echo "export HOSTNAME=hostA.mycompany.com" >> ~/.bash_profile
    source ~/.bash_profile

  7.  Navigate to the <IIGateway_INSTALL_DIR> directory and load the container images:

    1. Load the container images for the on-premises gateway:
      podman load --input bmc-hii-docker-images-<buildNumber>.tgz
    2. Untar the container images for Grafana:
      tar -zxvf bmc-hii-tp-docker-images-<buildNumber>.tgz
    3. Load the container images for Grafana:
      podman load --input bmc-hii-tp-docker-images-<buildNumber>/hii-grafana.tgz

  8. Extract the utility file, hii-bmc-<buildNumber>.zip:

    unzip hii-bmc-<buildNumber>.zip
  9. Configure SSL.
    1. Perform one of the following actions to obtain the certificate and private keys:

      • Generate a self-signed certificate by using the following command:

        openssl req -x509 -sha256 -days 397 -nodes -newkey rsa:2048 -subj "/CN=<commonName>/C=<countryName>/L=<locality>" -keyout <hostName>.key -out <hostName>.crt

        In the command, replace  <hostName>  with the fully qualified domain name of the server where you are installing the on-premises gateway.

      • Obtain a CA-signed certificate and private keys from the Certificate Authority.
    2. Create the certs directory in the /<IIGateway_INSTALL_DIR>/hii/conf directory if it does not exist.
    3. Copy the certificate and private key you obtained to the /<IIGateway_INSTALL_DIR>/hii/conf/certs directory, and ensure that the names of the certificate and private key files are in the following format:
      < hostName>.crt and <hostName>.key
      <hostName> is the fully-qualified domain name of the server where you are installing the on-premises gateway.

    4. Change permissions on the /<IIGateway_INSTALL_DIR>/hii/conf/certs directory:

      chmod -R 755 /<IIGateway_INSTALL_DIR>/hii/conf/certs
    5. Open the hii/conf/nginx.conf file with a text editor. 

    6. Comment the following line:

      listen 443 ssl

    7. Uncomment the following line:

      # listen 7443 ssl
    8. Save and close the file.

    If you encounter any issues, see To troubleshoot SSL issues to resolve them.

  10. If you plan to deploy the on-premises gateway for which authentication is enabled, configure the protocol to be used (defaults to HTTP) for authorization between the on-premises gateway and the Identity Management System (IMS), which is part of the BMC Helix platform:
    1. Navigate to the /<IIGateway_INSTALL_DIR>/hii directory.
    2. Open the podman-compose.yaml file by using a text editor.
    3. Locate the mediator > environment section and search for the USE_HTTPS_IMS_URL parameter.

    4. Set the parameter to one of the following values: 

      • true: The HTTPS protocol is used for communication.
      • false (default): The HTTP protocol is used for communication.
      Warning
      Important (For version 25.3.00 only)

      Enclose the parameter value in double quotes, as shown in the following example:
      USE_HTTPS_IMS_URL: "false"

    5. Locate the backup > environment section and add the USE_HTTPS_IMS_URL parameter if it does not exist.

    6. Set the parameter to one of the following values: 

      • true: The HTTPS protocol is used for communication.
      • false (default): The HTTP protocol is used for communication.
      Warning
      Important (For version 25.3.00 only)

      Enclose the parameter value in double quotes, as shown in the following example:
      USE_HTTPS_IMS_URL: "false"

    7. Save and close the file.
  11. Perform the following steps if you want to deploy the on-premises gateway for which the authentication is enabled; 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_urlrsso_external_urlData URI image and rsso_internal_urlrsso_internal_urlData URI image parameters and replace {RSSO_URL}{RSSO_URL}Data URI image with the OpenID Connect Issuer URL.
        • Search for the client_idclient_idData URI image parameter and replace {RSSO_CLIENT_ID}{RSSO_CLIENT_ID}Data URI image with the Client ID that you saved in a file while registering the OAuth client.
        • Search for the client_secretclient_secretData URI image parameter and replace {RSSO_CLIENT_SECRET}{RSSO_CLIENT_SECRET}Data URI image with the Client Secret that you saved in a file while registering the OAuth client.
        • Locate the proxiesproxiesData URI image section, and replace {TENANT_URL}{TENANT_URL}Data URI image 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-enabledneo.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-enabledneo.feature.flags.auth-enabled parameter to true.
      4. Save the file.

    3. Start the podman-compose service:

      podman compose -f podman-compose.yaml up -d

      Data URI image

    4. Go to step 13 to configure the BMC Helix destination.
  12. Perform the following steps if you want to deploy the on-premises gateway for which authentication is disabled:
    1. Navigate to the /<IIGateway_INSTALL_DIR>/hii/scripts directory.

    2. Run the gateway_deployment.sh script:

      ./gateway_deployment.sh

      Data URI image

       

    3. Enter podman when prompted for the deployment method.

    4. Enter n to start deploying the on-premises gateway with authentication disabled.

      Warning
      Important

      You can enable the authentication after the deployment if needed. For more information, see To enable authentication for the on-premises gateway after the deployment if you are using BMC Helix IT Operations Management on premises.

    5. Go to step 13 to configure the BMC Helix destination.
  13. Perform the following steps to configure the BMC Helix destination to which you want to send data collected by BMC Helix Intelligent Integrations:

    1. Create a file with the following contents and name it ade-default-destination-min.json:

      [
        {
          "entityKind": "Destination",
          "configWithSchema": {
            "config": {
              "connection": {
        "proxyUsername": "",
                "proxyPassword": "",
                "accessSecretKey": "CHANGEME",
                "allowUnsignedCertificate": false,
                "logResponses": false,
                "pipeLiningLimit": 1,
                "proxyHost": "",
                "logRequests": false,
                "timeout": {
                  "unit": "MINUTES",
                  "value": 15
                },
                "proxyPort": 8888,
                "maxResponseSize": 1000000,
                "usesHttps": true,
                "accessKey": "CHANGEME",
                "port": 443,
                "minConnections": 0,
                "tenantId": "CHANGEME",
                "connectingTimeout": {
                  "unit": "SECONDS",
                  "value": 30
                },
                "host": "CHANGEME - BMC Helix tenant host name - for example: swp-2021-1840-disceks1.abc.com",
                "poolTimeout": {
                  "unit": "MINUTES",
                  "value": 30
                },
                "maxOpenRequests": 1024,
                "maxConnections": 5,
                "maxRedirects": 5,
                "usesProxy": false
              },
              "poolTimeout": {
                "unit": "MINUTES",
                "value": 30
              }
            }
          },
          "instanceName": "BMC",
          "tenantId": "287c466d-7467-4e72-9e52-8357b4a27eaf",
          "typeName": "BmcDestination",
          "id": "CHANGEME - GENERATE NEW UUID using https://www.uuidgenerator.net/version4 e.g. 2643e089-18a8-4b0d-a58a-c022926812e0  MUST BE UNIQUE in a stack",
          "moduleId": "bmc"
        }
      ]

      Data URI image

    2. Enter the values of the following parameters in the file:
      • proxyUsernameproxyUsernameData URI image: User name for the proxy.
      • proxyPasswordproxyPasswordData URI image: Password for the proxy.
      • proxyPortproxyPortData URI image: Proxy port number.
      • proxyHostproxyHostData URI image: Host name of the proxy.
      • usesProxyusesProxyData URI image: Whether proxy should be used for communication. Set its value to true or false depending on whether proxy should be used. 
    3. Data URI imageReplace the CHANGEME value of the following parameters with the generated values:

      • accessKeyaccessKeyData URI imageand accessSecretKeyaccessSecretKeyData URI image: 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.

        Warning

        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 the access key and access secret key.
        • The access key and access secret key must have the Administrators group and the Administrator role assigned

        Data URI image

      • tenantIdtenantIdData URI image(first occurrence only): BMC Helix tenant ID.
        Copy the tenant ID from the access key (key:<access key>::<secret key>,tenant id: <tenant ID>) that you generated earlier and replace the CHANGEME occurrences with the copied tenant ID.
      • hosthostData URI image: BMC Helix tenant host name.
        For example, if the tenant URL is         https://swp-2021-1840-disceks1.abc.com, replace CHANGEME with swp-2021-1840-disceks1.abc.com.
      • ididData URI image: Universally unique identifier (UUID).
        Access https://www.uuidgenerator.net/version4 to generate UUID.

    4. Access the BMC Helix Intelligent IntegrationsData URI image UI by using the following URL:
      https://<hostName>:7443/swpui
      <hostName> is the fully-qualified domain name of the server where the on-premises gateway is deployed.
      For example,       https://ii-gateway-disceks1.abc.com:443/swpui.

      Warning

      Important

      • BMC Helix Portal does not display any tile for the BMC Helix Intelligent Integrations on-premises gateway. Access the UI by using the URL specified in this step. 
      • If you encounter an issue when accessing or using BMC Helix Intelligent Integrations, see Troubleshooting the BMC Helix Intelligent Integrations issues.

      Data URI image

    5. Import the ade-default-destination-min.json file by using the Backup/Restore option to create the destination.
      For more information, see Backing-up-and-restoring-connector-configurations.

      Information
      Can I create more than one BMC destination for one instance of the on-premises gateway?

      No, BMC Helix Intelligent Integrations supports only one destination for one instance of on-premises gateway.

      Data URI image

    6. Edit the destination connection details:
      1. On the CONNECTORS tab, click Configure Mediator ConfigureMediator_icon.png​Data URI imageon the DESTINATIONS panel.
      2. Replace the existing values in the Access Key and Access Secret Key fields with the values that you have copied in the ade-default-destination-min.json  file in step 13(c). 
      3. Click Validate to validate the connection.
      4. Click Save & Close.
  14. If you are using custom or CA-signed certificates, import them into the on-premises gateway.

Task 2: To import SSL certificates into the on-premises gateway

Warning

Important

Make sure that the version of the keytool utility installed on the on-premises gateway host matches the version available in the swp-authproxy container.

  1. Obtain the SSL 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 directory .

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

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

  3. (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 using the following command:

    podman 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 directory.
  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.

    • (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/podman-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 podman-compose.yaml file.

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

    podman-compose -f podman-compose.yaml down
    podman-compose -f podman-compose.yaml up -d

To enable authentication for the on-premises gateway after the deployment if you are a Helix subscriber

  1. Stop the podman-compose service:
    podman compose -f podman-compose.yaml down
  2. Navigate to the /<IIGateway_INSTALL_DIR>/hii/scripts directory.

  3. Run the gateway_deployment.sh script:

    ./gateway_deployment.sh
  4. Enter podman when prompted for the deployment method.
  5. Enter y to deploy the on-premises gateway. 
  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.

      Warning

      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 the 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.
    • Host name: Fully-qualified domain name of the server where you want to deploy the on-premises gateway.
      After you provide all the credentials, the on-premises gateway is deployed. Also, the cred.json, external.config, and nginx.config configuration files are backed up in the /<userHome>/iig_auth directory.
  7. If you are using SSL certificates, import them into the on-premises gateway.

To enable authentication for the on-premises gateway after the deployment if you are using BMC Helix IT Operations Management on premises

  1. Make sure that you have registered the OAuth client.
    For more information, see Setting up authentication for the on-premises gateway.
  2. Stop the podman-compose service:
    podman compose -f podman-compose.yaml down
  3.  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 target_host parameter and replace {RSSO_TARGET_HOST} with swp-ui.
      • 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.
  4. Perform the following steps to update the neo.feature.flags.auth-enabled parameter:
    1. Navigate to the /<IIGateway_INSTALL_DIR>/hii/conf directory and open the swp.conf file with a text editor.
    2. Set the value of the neo.feature.flags.auth-enabled parameter to true.
    3. Save the file.

  5. Back up the /<IIGateway_INSTALL_DIR>/hii/podman-compose.yaml and /<IIGateway_INSTALL_DIR>/hii/conf/nginx.conf files.

  6. Copy the customizations done in the podman-compose.yaml and nginx.conf files to the podman-compose.yaml_Rsso and nginx.conf_Rsso files in the /<IIGateway_INSTALL_DIR>/hii/defaults directory.
  7. Remove _Rsso from the following file names:
    • podman-compose.yaml_Rsso
    • nginx.conf_Rsso
  8. Overwrite the /<IIGateway_INSTALL_DIR>/hii /podman-compose.yaml and /<IIGateway_INSTALL_DIR>/hii/conf/nginx.conf files with the files in the /<IIGateway_INSTALL_DIR>/hii/defaults directory.

  9. Start the podman-compose service:
    podman compose -f podman-compose.yaml up -d

  10. If you are using SSL certificates, import them into the on-premises gateway.

To troubleshoot SSL issues

Problem

Possible root cause

Possible resolution

Containers restart due to the permission-denied errors.

Containers don't have permission to read the mounted directory.

  1. Grant read permission to the mounted directory on the host.
  2. Disable SELinux.

You are not able to access the URL with the host name.

The firewall is blocking the connection.

Disable the firewall.

The swp-nginx container is not starting.

The nginx.conf file contains an invalid configuration.

Check the swp-nginx container logs.

Sometimes, missing semi-colon(;) at the end of the line causes an issue.

Where to go from here

After you deploy the on-premises gateway, perform the following tasks:

 

 

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

BMC Helix Intelligent Integrations 25.3