Installing and managing the Linux connector

Install the connector to collect logs from Linux-based applications. Linux connectors are available in Red Hat Enterprise Linux versions 7 x86_64, 8 x86_64, and 9 x86_64.

The following are the list of tasks that you perform with 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 have the sudo permissions to install the connector. Alternatively, use the root user.
Confirm that the 24444 port is available on the Linux server from where the logs will be collected.
Make sure the non-root user is already created. You need to provide the non-root user while running the installation script, so that the td-agent ruby processes are launched with the non-root user.
Make sure that you have the following sudo commands permission:
- Sudo access to copy the installation shell script and connector package tar file to the /opt directory
- Sudo access to the /opt/td-agent directory, which is the installation script create directory
- Sudo access to execute the shell script
- Access to the following directories, so that you can copy the files that are required to register the connector as service:
  /etc/logrotate.d/
  /etc/systemd/system/
  /etc/systemd/system/multi-user.target.wants/
  /etc/prelink.conf.d/
  /var/log/
  /usr/sbin/
  /usr/lib/tmpfiles.d/
  /usr/share/man/man1/
- Access to the /opt/td-agent directory, which is the installation script create directory
- chown and chmod permissions
- Permissions for systemctl (Services alias commands)
- The /usr/bin/mkdir, /bin/tar, and /bin/rm directories

Important

Non-/opt folder installation is not supported for the Linux connector. This is a Fluentd limitation.

To download and install the connector

In BMC Helix Log Analytics, go to Collection > Connectors.
On the Connectors page, click Create.
Enter a unique name for the connector.
From the Select Connector Type list, select the appropriate connector based on the version.
By default, Linux Connector (RHEL8) is selected.
(Optional) Add a description for the connector.
From the Select Connector Type list, select the appropriate connector based on the version.
By default, Linux Connector (RHEL8) is selected.
In the Download Connector step, click Download.
Important
Select the /opt directory to download the connector. You cannot download the connector in any other directory.
In the Tags section, add tags in the form of key-value pairs to identify the connector.
For example, name-windows, location-pune.
Click + to add the tag.
Important
Make sure that you click + even if you are adding only one tag.
In the Download Install Script section, click Download.
Important
Make sure that you do not copy the script to any public domain.
Click Save.
Copy the installation script and tar.gz files to the /opt directory on the Linux (RHEL) server from where you want to collect logs.
Extract the tar.gz file, from the /opt folder by performing the following steps:
1. Navigate to the /opt directory by running the following command:
  cd /opt
2. Extract the tar.gz file by running the following command:
  tar -xvf tdc-connector-linux-<build_id>-<version>.tar.gz
  The connector file is extracted in the bmc-devtools directory.
Grant execute permission to the downloaded shell script, and then run the script.
Use the following options to provide the user name and group name:
- -u option to provide the user name
- -g option to provide the group name
  For example, run the following commands:
  ./install-connector-<connector-name>.sh -u <User_Account_Name> -g <Group_Name>
  sudo ./install-connector-my-bmc.sh -u <user name>-g <Group_Name>
  The processes for the connector service (td-agent.service) are run with the user name and group name that you provide. If you do not enter a user name, a user with td-agent user name is created and it is used to run the processes for the connector. If you use the root user, you do not need the keyword sudo in the command.
  After installation, the bmc-devtools directory is deleted and the connector is installed in the td-agent directory.
Start the connector service by running the following command:
sudo systemctl start td-agent.service

To communicate with the connector through a proxy

Open the /etc/systemd/system/td-agent.service file.
Search for the following line: LimitNOFILE=65536.
After this line, add the following entry:
Environment=HTTP_PROXY=http://<PROXY_HOST_OR_IP>:<PROXY_PORT>
Save the file.
Important
The connector communicates with the proxy over the HTTP protocol only.

To verify the connector installation

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

Created: The connector is 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 only delete a connector in this status.

To start and stop a connector

To start a connector, run the following command:
systemctl start td-agent.service
To stop a connector, run the following command:
systemctl stop td-agent.service

After you stop the connector, it might take up to 10 minutes to change the connector status to Suspended.

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:

Uninstall and delete the connector.
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.

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

(Optional) In the Description field, enter the connector description.
In the Download Connector field, click Download.
(Optional) In the Tags field, add tags to identify the connector; click + to add more tags.
For example: key-linux, value-bmc.
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.
Click Save.
Go to the Linux server where you want to collect logs.
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.
Run the following command to give read, write, and execute permissions to the extracted files:
chmod 777 upgrade-connector-<ConnectorName>.sh
Run the following command and follow the prompts on the screen to upgrade the connector and start the connector service:
sudo ./upgrade-connector-<connector-name>.sh -u

To verify the upgrade

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

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

To uninstall a connector

Navigate to the /opt/td-agent/scripts directory and copy the uninstall-<os-type>-connector.sh script.
os-type is the type of the Linux connector, for example, rhel8.
Paste the script in the /opt directory.
Run the uninstall-<os-type>-connector.sh script.
For example, for the RHEL 8 connector, run the following script:
uninstall-rhel8-connector.sh

To delete a connector

Ensure that the connector is not associated with a collection policy.
Stop the connector and wait for 5 minutes.
When you stop the connector, its status changes to Suspended.
On the Connector page, for the required connector, click the Actions menu and select Delete.
Confirm the deletion by clicking Yes.

Where to go from here

Creating-a-parsing-rule