Deploying the on-premises gateway by using Podman containers

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

Before you begin

Before you deploy the BMC Helix Intelligent Integrations on-premises gateway, review the system requirements and download the container images and utility files.

Related topics

Setting-up-and-going-live

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

Monitoring-the-health-of-containers-in-an-on-premises-environment

To deploy the on-premises gateway by using 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>:
    • Container images: bmc-hii-docker-images -<buildNumber>.tgz
    • Utility file: hii-bmc -<buildNumber>.zip
  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. Load the container images:

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

  8. Navigate to the /<IIGateway_INSTALL_DIR> directory and extract the utility file, hii-bmc -<buildNumber>.zip:

    unzip hii-bmc-<buildNumber>.zip
  9. (Applicable for version 24.3.00) Perform the following steps to disable the authentication:

    1. Change permissions on the /<IIGateway_INSTALL_DIR>/hii/scripts/iig_noauth.sh file:

      chmod +x /<IIGateway_INSTALL_DIR>/hii/scripts/iig_noauth.sh

    2. Navigate to the /<IIGateway_INSTALL_DIR>/hii/scripts directory and run the following command:

      ./iig_noauth.sh -noauth

  10. (Applicable for version 24.3.01) Depending on whether you want to enable or disable the authentication, perform one of the following steps:
    • To enable the authentication, perform the following steps: 
      1. Navigate to the /<IIGateway_INSTALL_DIR>/hii/scripts directory and open the cred.json file with a text editor.
      2. Update the values of the following parameters: 

        • 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 the access_key and access_secret_key parameters.

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

        • tenant_id: Tenant ID
          Copy the tenant ID from the access key (key:<access key>::<access secret key>,tenant id: <tenant ID>)
        • tenant_url: Tenant URL
        • host_name: Host name where you want to deploy the BMC Helix Intelligent Integrations gateway.

      3. Change permissions on the /<IIGateway_INSTALL_DIR>/hii/scripts/iig_auth.sh file:

        chmod +x /<IIGateway_INSTALL_DIR>/hii/scripts/iig_auth.sh

      4. Navigate to the /<IIGateway_INSTALL_DIR>/hii/scripts directory and run the following command:

        ./iig_auth.sh -auth

        After the script file is successfully executed, cred.json and external.conf files are backed up in the /<usehome>/iig_auth directory.

    • To disable the authentication, perform the following steps: 

      1. Change permissions on the /<IIGateway_INSTALL_DIR>/hii/scripts/iig_auth.sh file:

        chmod +x /<IIGateway_INSTALL_DIR>/hii/scripts/iig_auth.sh

      2. Navigate to the /<IIGateway_INSTALL_DIR>/hii/scripts directory and run the following command:

        ./iig_auth.sh -noauth
  11. Configure SSL, see To configure SSL for BMC Helix Intelligent Integrations.

  12. 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"
      }
    ]
  13. 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 proxy should be used for communication. Set its value to true or false depending on whether proxy should be used. 
  14. Replace the CHANGEME value of the following parameters with the generated values:

    • accessKey and 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.

      Important

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

      The access key and 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.

  2. Access the BMC Helix Intelligent Integrations UI by using the following URL:
     https://<hostName>:7443/swpui
    hostName is the the fully-qualified domain name of the server where the on-premises gateway is deployed.

    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. 

  3. 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.

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

  4. 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 14. 
    3. Click Validate to validate the connection.
    4. Click Save & Close.

To configure SSL for BMC Helix Intelligent Integrations

  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. Open the hii/conf/nginx.conf file with a text editor. 

  5. In the following SSL configuration, replace <iihostname> with the fully qualified domain name of the server where you are installing the on-premises gateway.

    ssl_certificate /etc/nginx/certs/<iihostname>.crt;  #certificate path
    ssl_certificate_key /etc/nginx/certs/<iihostname>.key;  #certificate key

  6. Comment the following line:

    listen 443 ssl

  7. Uncomment the following line:

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

  9. Restart the podman-compose service.

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


Troubleshooting 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.

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*