Installing and managing the Docker connector

To derive insights from logs and troubleshoot issues by analyzing the logs, start with log collection. To collect logs from applications running on docker containers, download and install Docker connector.

The following are the list of tasks that you can perform for the connector:

Before you begin

• Make sure that the host computer on which you plan to install the connector has a 2-core CPU and 16 GB RAM.
• Make sure that you are downloading and installing the connector on one of the following operating systems:
  • RHEL 8.x, 7.x
  • CentOS 8.x, 7.x
  • Ubuntu 20.x, 18.x
• Make sure that you have installed docker version 18.01 or later.

To download and install a connector

1. From the Collection menu, select Connectors.
2. On the Connectors page, click Create.
3. To add connector details, perform the following steps:
   1. In the Connector Name field, enter a unique name for the connector.
   2. From the Select Connector Type list, select Docker Connector.
   3. In the Description field, enter description of the connector.
4. In the Download Connector step, click Download.
5. In the Tags step, add tags (in the form of key-value pairs) to identify the connector, for example, name-windows, location-Pune, and so on.
6. In the Download Install Script step, click Download.
   The format of the .sh file name is install-connector-<connector name>.sh. For example, if you entered the connector name as my-bmc, the .sh filename is install-connector-my-bmc.sh.
7. To communicate with the connector through a proxy server, perform the following steps:
   1. Open the installation script (example: install-connector-my-bmc.sh).
   2. Locate the following command line: “echo 'FLUENTD_LOG_SIZE_BYTE=10000000' >> $ENV_VARIABLE_FILE_PATH”.
   3. Before this line, add the following command line:
      echo 'HTTP_PROXY=http://<proxy server>' >> $ENV_VARIABLE_FILE_PATH
   4. Save the file.
      
      ImportantThe connector communicates with the proxy over the HTTP protocol only.
8. Copy the downloaded script and docker image file to the same folder on a docker-enabled server. 
9. (Optional) To collect logs from files that are located outside the container, in the downloaded script, locate the docker create command statement and create mount points for the log directories.
   For example, if logs are generated in the /var/logs directory on the host filesystem, create a mount point by adding the following argument to the docker create command statement: -v /var/logs/:/fluentd/etc/log/.

10. Grant the execute permission to the downloaded script, and then run the script.
    For example, run the following commands:
    chmod +x install-connector-my-bmc.sh
    ./install-connector-my-bmc.sh

    Important: Script security and location

    • Do not copy the script on any public domains.
    • Copy the downloaded script in the same location as that of the docker image.
    • Download the connector on a docker host that can communicate with the integration source and BMC Helix APIs.

    To view the container logs, see the /opt/bmc/connectors/<connector_name>/logs/fluent.log file.

To verify the connector installation

To verify the connector installation, go to the Collection menu and click Connectors, and look for the installed connector on the page. Connectors are available in one of the following status:

• Created: The connector was installed successfully, but has not started sending heartbeats.
• Active: The connector is sending heartbeats.
• Suspended: The connector has not sent heartbeats for a pre-configured time. You can delete a connector only in this status.

To find the connector container ID

1. On the server where you installed the connector, open the command line interface.

2. Run the following command:
   docker ps
   The following image shows a sample container ID:
   

   The output of this command displays the following information:

   • The docker container ID
   • The build name
   • The command to run the docker container (that is /run.sh)
   • The docker container creation timeline
   • The docker container status and the timeline of the status
   • The ports used by the docker container
   • The connector name
     If multiple connectors are present on the container, they are all listed.

To reload a connector

1. Run the following command:
   docker ps

2. Log in to the docker container and reload the connector by running the following command:

   docker exec -it <containerID> bash reload.sh

To stop and stop a connector

• To start a connector, run the following command:
  docker start <containerID>
• To stop a connector, run the following command:
  docker stop <containerID>

To edit a connector

You cannot edit a connector. If there are updates to a connector, you have to delete it and install it again.

For example, to use the Fully Qualified Domain Name (FQDN) of the host in an installed connector, perform the following steps:

1. Make sure that the connector is not associated with a collection policy.
2. Stop the connector and wait for 5 minutes.
   When you stop the connector, its status changes to Suspended.
3. On the Connector page, for the required connector, click the Actions menu and select Delete.
   If you deleted the connector from the virtual machine before deleting it from the Connectors page, use the Force Delete option to remove the connector from BMC Helix Log Analytics.
4. Confirm the deletion by clicking Yes. 
5. Install the connector again.

To upgrade a connector

Connectors with a pending status are due for an upgrade. You can upgrade only the active connectors.

1. From the Collection menu, select Connectors.
2. Click the Action menu of the Docker connector that you want to upgrade and click Upgrade.
   

1. (Optional) In the Description field, enter the connector description.
2. In the Download Connector field, click Download.
3. (Optional) In the Tags field, add tags to identify the connector; click + to add more tags.
   For example: key-docker, value-bmc.
4. In the Download Install Script field, click Download.
   The script is downloaded as a .sh file with the name upgrade-connector-<connector name>.sh.
   For example, if you entered the connector name as my-bmc, the .sh file name is upgrade-connector-my-bmc.sh.
5. Click Save.
6. Go to the Linux server where you want to collect logs.

7. In the /opt directory, copy the upgrade script and tar.gz files and extract them.

   Important

   Make sure that you do not copy the script on any public domain.

8. Run the following command to give read, write, and execute permissions to the extracted files:

   chmod 777 upgrade-connector-<ConnectorName>.sh

9. Run the following command and follow the prompts on the screen to upgrade the connector and start the connector service:

   ./upgrade-connector-<connector-name>.sh

To verify the upgrade

Verify the upgrade after the connector starts as a Docker service.

1. Go to the Collection > Connectors page.
2. For the connector that you upgraded, verify that the upgrade status is Completed.

To delete a connector

1. Make sure that the connector is not associated with a collection policy.
2. Stop the connector and wait for 5 minutes.
   When you stop the connector, its status changes to Suspended.
3. On the Connector page, for the required connector, click the Actions menu and select Delete.
   If you deleted the connector from the virtual machine before deleting it from the Connectors page, use the Force Delete option to remove the connector from BMC Helix Log Analytics.
4. Confirm the deletion by clicking Yes. 
5. Delete the docker container from the computer where you had installed it. 

Where to go from here

Creating-a-parsing-rule