Installing or updating a connector

IBM Security QRadar® Suite Software includes some connectors, but more are available on IBM® X-Force® Exchange / App Exchange. Install connectors from IBM X-Force Exchange / App Exchange to add new connectors to your QRadar Suite Software deployment, or to update existing connectors to the latest version.

Follow these steps to upgrade and install your connection, regardless of how you installed QRadar Suite Software, including installing from the IBM Cloud® catalog.

Important: You can install a connector only in on-premises installations of QRadar Suite Software.

You must install podman to successfully complete the steps.

Before you begin

Find the connectors that you want to install on IBM X-Force Exchange / App Exchange.

  • For Connected Assets and Risk connectors, set the Content Type to Assets and Risks.
  • For Universal Data Insights connectors, set the Content Type to Federated Search.

Install Cloud Pak CLI 3.23.1 or later

Procedure

  1. Download Cloud Pak CLI from https://github.com/IBM/cloud-pak-cli/releases.
  2. Extract the binary file that you downloaded by typing the following command, where <archive_file> is the name of the archive file that you downloaded.
    tar -xf <archive_file>
  3. Modify the permissions of the binary file by typing the following command, where <binary_file> is the name of the Cloud Pak binary file that you extracted from the archive.
    chmod 755 <binary_file>
  4. Move the binary file to the /usr/local/bin directory by typing the following command.
    mv <binary_file> /usr/local/bin/cloudctl
    Tip: If this command returns a No such file or directory or Not a directory error message, create the /usr/local/bin directory by typing the following command.
    sudo mkdir /usr/local/bin
  5. Ensure that Cloud Pak CLI is working by typing the following command.
    cloudctl version
    Tip: MacOS users might see a message that this tool cannot be opened because it is from an unidentified developer. Close this message and go to System Preferences > Security & Privacy. On the General tab, click Open Anyway or Allow Anyway. Repeat the cloudctl version command.

Install Red Hat OpenShift CLI 4.14 or later

The Red Hat® OpenShift® CLI client helps you develop, build, deploy, and run your applications on any Red Hat OpenShift or Kubernetes cluster. It also includes the administrative commands for managing a cluster under the adm subcommand.

Procedure

  1. Download Red Hat OpenShift CLI 4.14 or later from https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/ocp/stable-4.14/. The file to download is called openshift-client-<platform>-<version>.tar.gz.
  2. Extract the binary file that you downloaded by typing the following command, where <oc_cli_archive_file> is the name of the archive file that you downloaded.
    tar -xf <oc_cli_archive_file>
  3. Modify the permissions of the binary file by typing the following command, where <oc_cli_binary> is the name of the Red Hat OpenShift binary that you extracted from the archive.
  4. Move the binary file to the /usr/local/bin directory by typing the following command.
    mv <oc_cli_binary> /usr/local/bin/oc
    Tip: If this command returns a No such file or directory or Not a directory error message, create the /usr/local/bin directory by typing the following command.
    sudo mkdir /usr/local/bin
  5. Ensure that the Red Hat OpenShift CLI client is working by typing the following command.
    oc version
    Tip: MacOS users might see a message that this tool cannot be opened because it is from an unidentified developer. Close this message and go to System Preferences > Security & Privacy. On the General tab, click Open Anyway or Allow Anyway. Repeat the oc version command.

Installing or updating a connector

After you follow the prerequisite steps, install or update your connectors.

Procedure

  1. Create the following environment variables with the installer image name and the image inventory on your mirroring device by typing the following command.
    export CASE_NAME=ibm-cp-security
    export CASE_VERSION=1.0.54
  2. Download the IBM Security QRadar Suite Software installer and image inventory to your mirroring device by typing the following command.
    oc ibm-pak get $CASE_NAME --version $CASE_VERSION --disable-top-level-images-mode
    The CASE is saved to the ~/.ibm-pak/data/cases/$CASE_NAME/$CASE_VERSION directory and the log file is saved to ~/.ibm-pak/logs/oc-ibm_pak.log.
    Tip: If you want to save the CASE to a directory other than your home directory, set the $IBMPAK_HOME environment variable by typing the following command.
    export IBMPAK_HOME=<working_directory>

    When you set the $IBMPAK_HOME environment variable, the CASE is saved to <working_directory>/.ibm-pak/data/cases/$CASE_NAME/$CASE_VERSION and the log is saved to <working_directory>/.ibm-pak/logs/oc-ibm_pak.log.

    Important: If you change where the CASE is saved to, you must use $IBMPAK_HOME/.ibm-pak in place of ~/.ibm-pak throughout this procedure.
  3. Log in to your Red Hat OpenShift Container Platform cluster as a cluster administrator by typing one of the following commands, where <openshift_url> is the URL for your Red Hat OpenShift Container Platform environment.
    • Using a username and password.
      oc login <openshift_url> -u <cluster_admin_user> -p <cluster_admin_password>
    • Using a token.
      oc login --token=<token> --server=<openshift_url>
  4. Find your QRadar Suite Software namespace by typing the following commands.
    NAMESPACE=$(oc get pod -lname=udi-udiworkers --all-namespaces --no-headers | head -1 | awk '{print $1; exit}')
    echo $NAMESPACE
  5. Run the deploy-connector action by typing one of the following commands.
    • In an online environment:
      oc ibm-pak launch -t 1 $CASE_NAME --version $CASE_VERSION --inventory ibmSecurityOperatorSetup --namespace $NAMESPACE --action deploy-connector --args "--type <car_or_tis_or_udi> --connector_image <connector_image>"
      
    • In an air-gapped environment:
      oc ibm-pak launch -t 1 $CASE_NAME --version $CASE_VERSION --inventory ibmSecurityOperatorSetup --namespace $NAMESPACE --action deploy-connector --args "--type <car_or_tis_or_udi> --connector_image <connector_image> -registry ${LOCAL_DOCKER_REGISTRY}:${PORT}"

    The following arguments are required in the deploy-connector action.

    Argument Description
    --type The type of connector that you want to install. This value must be one of the following types:
    • car
    • tis
    • udi
    --connector_image The connector image that you want to install. A certified connector is hosted on the IBM Cloud Container Registry and has the format: icr.io/cpopen/cp4s/<image_name>:<connector_version>. An example image: icr.io/cpopen/cp4s/stix_shifter_modules_qradar:3.3.12
    Tip: For a certified connector, the connector’s tag is the connector’s version.

    You can find the connector image in the Installation section of the connector description on IBM X-Force Exchange / App Exchange.

    --registry Air-gapped environment only. The local Docker registry.

    In an online environment, the connector image is deployed into the cluster.

    In an air-gapped environment, the connector image is mirrored from the public registry into the local Docker registry and deployed it into the cluster.

    If the command outputs the following error, verify the connector image name and tag, then try again.
    [ERROR] Cannot pull image icr.io/cpopen/cp4s/<image_name>:<connector_version>. Make sure it exists.
    If the command outputs the following error, you must upgrade QRadar Suite Software to a version that supports the connector before you can install it.
    [ERROR] The image compatible with the following version(s) '<later_version_1>, <later_version_2>' but not with the current application version <version>
    If the command outputs the following warning, the connector doesn't contain information about which versions of QRadar Suite Software support the connector. The connector might install, but might not work with your version of QRadar Suite Software.
    [WARNING] 'compatibleReleases' label not found in the image labels
  6. Verify that the connector is deployed.
    1. Display a list of installed connectors by typing the following command.
      oc ibm-pak launch -t 1 $CASE_NAME --version $CASE_VERSION --inventory ibmSecurityOperatorSetup --namespace $NAMESPACE --action list-connectors
    2. Verify the connector version by typing the following command and viewing the specification in the output.
      oc ibm-pak launch -t 1 $CASE_NAME --version $CASE_VERSION --inventory ibmSecurityOperatorSetup --namespace $NAMESPACE --action get-connector --args "--name <connector_name>" | grep image

      The following arguments are required in the get-connector action.

      Argument Description
      --name The name of the connector as shown in the list that is returned by running the list-connectors action.
      The connector version shows as part of the image tag that gets returned. For example, the connector version 3.3.12 can be seen in icr.io/cpopen/cp4s/stix_shifter_modules_qradar:3.3.12. The connector version can be used to verify whether the connector is updated.
  7. If you no longer need a connector, delete it from your cluster.
    1. Display a list of installed connectors by typing the following command.
      oc ibm-pak launch -t 1 $CASE_NAME --version $CASE_VERSION --inventory ibmSecurityOperatorSetup --namespace $NAMESPACE --action list-connectors
    2. Delete a connector by typing the following command.
      oc ibm-pak launch  -t 1 $CASE_NAME --version $CASE_VERSION --inventory ibmSecurityOperatorSetup --namespace $NAMESPACE --action delete-connector --args "--name <connector_name>"

      The following arguments are required in the delete-connector action:

      Argument Description
      --name The name of the connector as shown in the list that is returned by running the list-connectors action.

What to do next

If your connector is installed from the IBM X-Force Exchange / App Exchange, you must reinstall your connector to avoid compatibility issues when QRadar Suite Software is updated.

If you have connectors that are included in the QRadar Suite Software release package, they are automatically updated when QRadar Suite Software is updated.

Restriction: You cannot host connectors that you install from the IBM X-Force Exchange / App Exchange on the IBM Security Edge Gateway. The Edge Gateway hosts only the version of connectors that are included in the QRadar Suite Software release package. If you update a QRadar Suite Software connector, the Edge Gateway continues to host the previous version.