Installing and registering Data Collector by using the Data Collector installer package

The Data Collector installer package includes Data Collector installer files, the RPM file for the latest version of Data Collector, and a script that installs and registers Data Collector with the platform.

Before you begin

  • Ensure that you install Java™ on your computer or VM where you plan to install the Data Collector. For more information, see Installing Java.

  • Only Data Collector Administrators can create, register, edit, and delete a Data Collector instance. For more information, see User access, roles, and permissions.

  • Verify that your corporate firewall is able to accept incoming events that Data Collector ingests. For more information, see System requirements for Data Collector.

About this task

The Data Collector installer package automates most of the installation and registration process for Data Collector. You might need to register the Data Collector manually with prompts from the script. You can also edit and delete a Data Collector instance with the script.

For more information, see the following procedures:

Procedure

  1. Download the Data Collector installer package from IBM Fix Central (ibm.com/support/fixcentral/).
    Enter dc-installer-1.8.3 in the Search Fix Central field. The file name for the installer package is dc-installer-QRadarSuite-1.8.3.tgz.
  2. To verify that the file downloaded correctly, run the following command: 
    sha256sum dc-installer-QRadarSuite-1.8.3.tgz

    If the file downloaded correctly, the SHA256 checksum value is 7060f3b77c2b79f8747a6838710b814021d9166d651b75ae0faa19e30aa137a1.

  3. Log in to the Data Collector computer or VM as the root user.
  4. Create a temporary directory on your Data Collector instance where you can download the Data Collector installer package to, such as /dcinstall.
  5. Copy the Data Collector installer package to the temporary directory that you created.
    Important: Ensure that you complete the remaining steps of this task in the temporary directory that you created.
  6. Create an API key text file that the Data Collector installer package can read during the installing and registering processes.
    Important: If you do not create an API Key file, you are prompted for the API Key and API Secret when you run the Data Collector installer package.
    1. Log in to the platform with a user account that has the following permissions. You can either create a user or update a current user.
      Tip: When you create an API Key, that key has the same permissions as your account. To ensure that your API Key is reasonably secure, use an account with only the minimum permissions for installing and registering a Data Collector instance. Your account needs the Data Collector Admin permission for the Ingestion and data collection application. The account does not need access to any other services or applications on the platform.
    2. Create an API Key and call it dlc-operator.
    3. Download the API Key file by using the default file name of apiKey-dlc-operator-<XXXX>.txt, where <XXXX> is an ID that the platform assigns to the API Key. This value can be the numeric key ID.
    4. Copy this file to the temporary directory that you created.
  7. Unpack and run the Data Collector installer package by running the following command: 
    tar -zxvf dc-installer-QRadarSuite-1.8.3.tgz
    The Data Collector installer package contains the following files:
    install-dlc.sh
    The script for installing and registering Data Collector.
    dlc-service_<version>.rpm
    The RPM file for the most current version of Data Collector.
    dlc-installer.jar
    The Java Data Collector registration program.
    dlc-installer.conf
    The configuration file for the Data Collector registration program.
  8. Update the dlc-installer.conf file by populating the ServerUrl field with a URL to the platform instance.

    If you don't add the Server URL in the configuration file, the script prompts you to enter the information.

    For example, the URL might be https://prod-QRadar.itsc.example.com.
    Important: The Server URL value cannot be an IP address.
  9. When the script prompts you, enter values for the following parameters:
    Parameter Description
    DLC Name Enter a unique name for the Data Collector, or use the default value.

    The default name includes the UUID, such as DC 3e145186-5273-46f6-b698-16672d51ca76.

    The maximum number of characters is 64.
    DLC Description Enter a description for the Data Collector, or use the default value.

    The default value includes the UUID and creation time, such as DC 3e145186-5273-46f6-b698-16672d51ca76 Created on Mon Feb 11 12:12:49 PST 2023.

    The maximum number of characters is 1024.
    Event Timeout The number of milliseconds before an event timeout. Enter a number between 1 and 32767. The default value is 1440.
    The script generates the certificate signing request (CSR) and the connection bundle, and it completes the registration process.

Results

After you successfully install and register Data Collector with the installer package, the installer runs a self-test on the Data Collector instance. The following message is an example of the success message that you can see after the script completes the registration:
-------------------------
Connection Bundle saved to: /tmp/dlc-cdae1447-7116-48a0-9689-fde465f33d71.json.
Waiting for DLC service startup
Testing DLC Kafka communication paths...SUCCESS
Done with DLC Install.
Troubleshooting tips: The following issues can occur when you use the Data Collector installer package.
  • If the initial connectivity test does not connect to the platform, and you do not know the reason, contact a platform administrator. The platform might be unreachable, or the Data Collector manager might be unavailable. If you cannot reach the platform, you can still use the installer package, but you must manually register the Data Collector instance. For more information, see Registering Data Collector manually by using the installer script.
  • If the connection bundle does not generate, delete the Data Collector instance and reinstall it with the install-dlc.sh script. If you cannot generate the connection bundle, use the platform user interface (UI) to manage your Data Collector instance.
  • If the script cannot query Data Collector information, your API Key might not have the correct permissions. Generate an API Key with an account that has Admin permissions for the Ingestion and data collection service. For more information, see step 6.
  • If you cannot solve the issue, contact IBM Support.
    • Before you contact IBM Support, generate a log file with information from the installer. In the directory where you ran the installer, run the following command: 
      tar -czvf dlc.tgz log
      IBM Support can ask you to provide this file when you contact them.

Registering Data Collector manually by using the installer script

If the host of the Data Collector management service is valid, but the connection to the HTTPS port (443) is rejected, the registration program assumes that the port is administratively blocked. Then, the installer prompts you to choose to manually install Data Collector.

Before you begin

Important: Use this manual method only if your Data Collector instance cannot access the HTTPS port 443 from the platform. If you want the Data Collector instance to access the HTTPS port, then stop the installer script, resolve the networking issues to allow for port 443 access, and then rerun the install-dlc.sh script.

Procedure

  1. Select <Y> to continue with the manual installation, or select <ENTER> to quit.
  2. If you select <Y>, then the script runs and creates a CSR and saves it to the directory. The CSR file name contains the UUID, such as CSR-3e145186-5273-46f6-b698-16672d51ca76.txt.
  3. Copy the CSR to your clipboard.
  4. Log in to the platform with the account that you made or updated in step 6.
  5. In the general settings menu section, click Connections > Data Collectors, and then click Register a Data Collector.
  6. Enter a name and description for your Data Collector, and then click Next.
  7. Paste the certificate signing request from your Data Collector, and then click Next.
  8. Download the connection bundle to your Data Collector by clicking Download connection bundle. The connection bundle might take a few minutes to generate before you can click Download connection bundle to download it.
  9. Copy the connection bundle into a new text file named certBundle-<UUID>.txt, where <UUID> is the UUID for the Data Collector instance. The file name is case-sensitive.
  10. Save the file to the directory where you unpacked the installer package.
  11. Run the install-dlc.sh script again.

Results

After you complete these steps for the manual registration, the installer package queries for the name and location of the connection bundle file and then automatically applies it. Then, it restarts the Data Collector service, performs a self-test, and then deletes the csr-<UUID>.txt and certBundle-<UUID>.txt files.

Updating or deleting a Data Collector instance

Update or delete a Data Collector instance by rerunning the installer script. You can update parameter information or the connection bundle information, or you can delete a Data Collector instance.

Procedure

  1. Run the install-dlc.sh script in the repository where you unpacked your Data Collector instance.
  2. Select <C> to change any parameter values for your Data Collector instance. Press Enter to approve the value of a parameter.
  3. After you review the parameters, you can choose to regenerate the connection bundle and certificate signing request by selecting <Y>.
    Tip: You don't have to regenerate the connection bundle when you change the Data Collector name, description, or event timeout values. Regenerate the connection bundle only if you need to update the certificate.
    A new connection bundle is sent to your Data Collector instance, and this process can take a few minutes.
  4. To delete the Data Collector instance from the platform, select <D>.
    Tip: When you delete the Data Collector instance, the service RPM stops running, but it is not deleted. To manually delete the RPM, run the following command: 
    rpm -e dlc-service