Deploying the Logging agent for Windows

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: Service ID or Trusted Profile

   You can use a service ID or a Trusted Profile to authenticate with the IBM Cloud Logs service. Trusted Profile are only supported on Virtual Servers for VPC. 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.

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

   The Sender role is required to send logs to IBM Cloud Logs.

   For more information, see Granting IAM permissions for ingestion.

   For more information about Trusted Profiles, see Generating a Trusted Profile for ingestion.

3. Generate an API Key for service ID authentication.

   For authentication with trusted profiles, this step is not required.

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

Download the agent files

Complete the following steps:

1. Log in to your Windows environment.

2. Download the Windows agent ZIP archive.

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

3. Validate the checksum by running the following command:

   sha256sum -c <sha256_filename>
   

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

4. Using Powershell, expand the Windows agent archive in the Program Files directory.

   Expand-Archive -Path <archive_filename> -DestinationPath "C:\Program Files\"
   

   Where <archive_filename> is the name of the downloaded *.zip file.

5. Change the directory to the expanded Windows agent archive.

   cd "C:\Program Files\logs-agent"
   

6. Download the configuration file from the C:\Program Files\logs-agent location.

   wget https://logs-router-agent-config.s3.us.cloud-object-storage.appdomain.cloud/configure-logs-agent.ps1
   

Deploy the Logging agent to collect the Windows event log

Run the configuration Powershell script.

./configure-logs-agent.ps1 -TargetHost <target_host> -TargetPort <target_port> -AuthMode <auth_mode> -IAMEnv <IAM_environment> [[-IAMApiKey] <iam_api_key>] [-TrustedProfile] <trusted_profile_id>] -Channels <channels_list> [[-DBPath] <database_path>] [-VSISecureAccess]

Where

-TargetHost <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

-TargetPort <target_port>

Specifies the ingress endpoint port which will depend on your network connectivity to IBM Cloud Logs. Specify 3443 for IBM Cloud Logs Routing.

• 443: Public ingress endpoint
• 443: Private ingress endpoint (VPE)
• 3443: Private ingress endpoint (CSE)

-IAMEnv <IAM_environment>

(Optional) 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.

-AuthMode <auth_mode>

Specify IAMAPIKey or VSITrustedProfile.

-IAMApiKey <iam_api_key>

(Optional) 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.

-TrustedProfile <trusted_profile_id>

(Optional) Specify the trusted profile ID (required for VSITrustedProfile mode). When using trusted profiles, set to the ID configured in Granting IAM permissions for ingestion.

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

-Channels <channels_list>

(Optional) If a channels list is provided, a default winevtlog input plug-in will be configured to read events from the specified channels. Specify which channels to read from the Windows Event Log as a comma-separated list without spaces.

-DBPath <database_path>

(Optional) If the Channels parameter is provided, set this parameter to the database file to store the position of proccessed events. If this parameter is not set and the Channels parameter is provided, the default database file will be C:\Program Files\logs-agent\winevtlog.sqlite.

-VSISecureAccess

(Optional) Set this flag if you have secure access enabled in your VSI. This option is not enabled by default.

Configure the Logging agent to include or exclude files

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

1. Create the input plug-in configuration file input-tail.conf in C:\Program Files\logs-agent\etc.

2. Add 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              C:\logs\*.log
       Path_Key          file
       Exclude_Path      C:\logs\audit.log
       DB                C:\logs\fluent-bit.DB
       Buffer_Chunk_Size 32KB
       Buffer_Max_Size   256KB
       Skip_Long_Lines   On
       Refresh_Interval  10
   

3. Save the configuration file.

4. Modify the C:\Program Files\logs-agent\etc\fluent-bit.conf file to include the reference to the C:\Program Files\logs-agent\etc\input-windows-event-log.conf.

   @INCLUDE C:\Program Files\logs-agent\etc\input-windows-event-log.conf
   

   The main configuration file C:\Program Files\logs-agent\etc\fluent-bit.conf imports other files with the tag @INCLUDE <path_to_file>.

Add metadata

You must configure the Logging agent to include applicationName and subsystemName. You can also add custom metadata.

• The application name is the environment that produces and sends logs to an IBM Cloud Logs instance. Set the value to the hostname by using the variable ${COMPUTERNAME} or entering the computer host name.
• The subsystem name is the service or application that produces and sends logs to an IBM Cloud Logs instance. For example, you can set it to the provider name.

[FILTER]
    Name modify
    Match winevtlog.*
    Copy ProviderName subsystemName
    Add applicationName ${COMPUTERNAME}
    Add meta.source ${SOURCE}
    Add meta.channel ${Channel}
    Add meta.providerName ${ProviderName}
    Add meta.environment prod
    Add meta.platform windows

[FILTER]
    Name nest
    Match winevtlog.*
    Operation nest
    Wildcard meta.*
    Nest_under meta
    Remove_prefix meta.

Verify the agent configuration

Check that the agent configuration is correct by running the agent.

.\bin\fluent-bit.exe -c C:\Program Files\logs-agent\etc\fluent-bit.conf

The agent will start and establish a connection to the desired target.

Create a Windows service

Windows services are long-running background processes and are the preferred way to run the agent on Windows.

Complete the following steps:

1. To register the agent as a Windows service run the following command.

   A single space is required after binpath=.

   sc.exe create fluent-bit binpath= "C:\Program Files\logs-agent\bin\fluent-bit.exe -c \"C:\Program Files\logs-agent\etc\fluent-bit.conf\""
   

2. For agents using IAMAPIKey to authenticate, create an API Key in the registry for the fluent-bit service.

   New-ItemProperty -Path "HKLM:\System\CurrentControlSet\Services\fluent-bit" -Name "Environment" -Value "IAM_API_KEY=<my_api_key>" -PropertyType MultiString
   

3. Start the Windows service

   sc.exe start 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.