Deploying the Logging agent for Linux

Define the authentication method for the agent

Choose the type of identity and the authentication method for the agent. Then, create an API key if needed.

Complete the following steps:

1. Choose the type of identity: user or service ID.

   You can use a user, or a service ID as the identity that is used by the agent to authenticate with the IBM Cloud Logs service.

2. Grant permissions for ingestion to the identity that you have chosen.

   The role that is required for sending logs to IBM Cloud Logs is Sender.

   For more information, see Setting up IAM permissions for ingestion.

3. Generate an API Key for user authentication or for service ID authentication.

   For more information, see Generating an API Key for ingestion.

Download the required RPM or DEB packages

Complete the following steps:

1. Download the required RPM or DEB packages.

   For information about the current Logging agent version, see the agent release notes.

2. Validate the checksum by running the following command:

   sha256sum -c <sha256_filename>
   

   Where <sha256_filename> is the filename of the download *.sha256 file.

Set up and deploy the Logging agent configuration

Complete the following steps:

1. Log in to your Linux environment.

2. Install the agent.

   • For RHEL run:

     rpm -ivh <rpm_filename>
     

   • For Debian and Ubuntu run:

     dpkg -i <deb_filename>
     

   Where <rpm_filename> or <deb_filename> is the name of the downloaded *.rpm or *.deb file.

3. Download the configuration file.

   https://logs-router-agent-config.s3.us.cloud-object-storage.appdomain.cloud/post-config.sh
   

4. Run the configuration script.

   ./post-config.sh -h <target_host> -p <target_port> -t <target_path> -a <auth_mode> -k <iam_api_key> [--send-directly-to-icl] [-s <vsi_secure_access_enabled>] [-i <IAM_environment>]
   

   Where

   -t <target_path>

   Specify /logs/v1/singles to send data to an IBM Cloud Logs instance.

   -a <auth_mode>

   Specify IAMAPIKey or VSITrustedProfile.

   -k <iam_api_key>

   Specify the Cloud Identity and Access Management API key (required for IAMAPIKey mode). Make sure you follow the instructions in Generating an API Key.

   For more information about Cloud Identity and Access Management API Keys, see Managing API Keys.

   -d <trusted_profile_id>

   Specify the trusted profile ID (required for VSITrustedProfile mode). When using trusted profiles, set to the ID configured in Setting up Permissions for Ingestion. You must create the instance with the metadata service enabled and link the trusted profile to your instance by specifying the ID when creating it. For more information see Creating virtual server instances.

   For more information on Trusted Profiles, see Creating a Trusted Profile.

   --send-directly-to-icl

   Set this parameter to send logs directly to IBM Cloud Logs.

   -h <target_host>

   The host for IBM Cloud Logs ingestion, found in the Endpoints section of your IBM Cloud Logs instance Overview. Use the ingress endpoint. For more information, see Ingress endpoints

   -i <IAM_environment>

   Specifies whether a public or private endpoint is used for IAM authentication. Production indicates to use the public endpoint. PrivateProduction specifies to use the private endpoint. Production is the default.

   If your system does not have access to the public internet, you must use PrivateProduction to use the private endpoint.

   -p <target_port>

   Use 443 to send logs directly to IBM Cloud Logs.

   -s <vsi_secure_access_enabled>

   (Optional) Set this to true if you have secure access enabled in your VSI. It will be set to false by default. For example, -s true.

Add additional metadata fields

You can add additional metadata fields to the routed logs.

Complete the following steps:

1. Edit the fluent-bit.conf file in the /etc/fluent-bit/ folder.

2. Add your custom metadata using this structure: Add <meta.key_name> <your_custom_value>

   [FILTER]
     Name modify
     Match *
     Add subsystemName subsystemName
     Add applicationName applicationName
     Add meta.hostname ${HOSTNAME}
     Add meta.agentVersion agentVersion
   
   [FILTER]
     Name nest
     Match *
     Operation nest
     Wildcard meta.*
     Nest_under meta
     Remove_prefix meta.
   

   Where

   • applicationName: The application name defines the environment that produces and sends logs to IBM Cloud Logs. You must add an applicationName, for example, you can set it to ${HOSTNAME}.
   • subsystemName: The subsystem name is the service or application that produces and sends logs to IBM Cloud Logs. You must add a subsystemName.
   • <meta.key_name> is the name of the metadata field to be added (for example, meta.env) and <your_custom_value> is the value to be assigned to the field (for example, the name of your environment).

   For example, if you want to add the agent version and the region as metadata, the configuration would be similar to this:

   [FILTER]
     Name modify
     Match *
     Add subsystemName subsystemName
     Add applicationName ${HOSTNAME}
     Add agentVersion 1.3.1
     Add region us-east
   

3. Save the configuration file.

4. Restart the agent to apply the changes.

   systemctl daemon-reload && systemctl restart fluent-bit
   

Include or exclude files

By default, the Logging agent reads log files from /var/log, and forwards the log data to your logging instance.

You can configure the agent to include or exclude files that the agent monitors.

Complete the following steps:

1. Edit the fluent-bit.conf file in the /etc/fluent-bit/ folder.

2. Modify the INPUT section.

   Set the Path with the directories and files that you want to monitor.

   Set the Exclude_Path with the directories and files that you want to exclude from monitoring.

   [INPUT]
     Name              tail
     Tag               *
     Path              /var/log/*.log
     Path_Key          file
     Exclude_Path      /var/log/audit.log
     DB                /var/log/fluent-bit.DB
     Buffer_Chunk_Size 32KB
     Buffer_Max_Size   256KB
     Skip_Long_Lines   On
     Refresh_Interval  10
     storage.type      filesystem
     storage.pause_on_chunks_overlimit on
   

3. Save the configuration file.

4. Restart the agent to apply the changes.

   systemctl daemon-reload && systemctl restart fluent-bit
   

Verify logs are being delivered to your target destination

Complete the following steps:

1. Go to the web UI for your IBM Cloud Logs instance..

2. When your agent is correctly configured, you can see logs through the default dashboard view.

   For example, if you set the applicationName to the hostname in your agent, you can set the applicationname filter in a view to the name of your host.