Install Falcon LogScale Collector on Linux - Custom

The documentation provides detailed instructions for performing a custom installation of the Falcon LogScale Collector on Linux systems, including steps for Ubuntu and RedHat distributions, configuration of system permissions, firewall settings, and service management. It covers essential post-installation tasks such as binding to lower port numbers, granting file system access, and running the collector manually for debugging purposes.

Important

The name of the Falcon LogScale Collector service varies:

  • If you use Full Installation the service is called logscale-collector,

  • If you installed using Custom Installation or a version prior to 1.361.1 of LogScale the service name is humio-log-collector This does not apply to macOS.

This procedure describes how to perform a custom installation of the Falcon LogScale Collector on a Linux.

  1. Download the Falcon LogScale Collector as described in Download Falcon LogScale Collector and Install - Custom or using the command-line, see Download Installers from the Command-line.

  2. Run the following command to install Falcon LogScale Collector on:

    • Ubuntu

      shell
      sudo dpkg -i humio-collector_x.x.x_linux_amd64.deb

    • RedHat

      shell
      $ sudo rpm -i humio-collector.rpm
Run the Falcon LogScale Collector Manually on Linux

The following procedures allow you to install Falcon LogScale Collector on Linux manually.

Note

Create a valid configuration before running the Log Collector, see Configuration for more information.

Configure Start-up on Boot

The package ships with a service file that can be enabled as a SystemD service to run at start-up by running:

shell
$ sudo systemctl enable humio-log-collector.service
Additional Steps on Linux

When the Falcon LogScale Collector (FLC) is configured to read from files, the humio-log-collector service/user needs read access to those files. By default, this user likely does not have access to a majority of log files in the /var/log directory. The sections below describe how to verify current access, and how to grant the appropriate permissions.

Verifying Read Access

Before making permission changes, it's worth checking what access the humio-log-collector user currently has.

  1. Check folder-level permissions by running:

    shell
    ls -dl <folder to check>

    For example, the /var/log directory typically shows r-x as the last permission set, meaning any user can read/execute at the directory level.

  2. Check file-level permissions within the directory:

    shell
    ls -al /var/log/*.log

    When reviewing the output, there are three categories of files to be aware of:

    • Readable (no changes needed): Files where the "other" permission set includes r. These can already be read by humio-log-collector.

    • Readable via group membership (adm group): Files owned by the adm group where the group permission set shows r--. These can be made readable by adding humio-log-collector to the adm group (see next section).

    • Not readable by default (root-only): Files where permissions show rw-------. These cannot be read without either changing file permissions or adding them to a group that humio-log-collector belongs to.

Identifying Permission Errors at Runtime

If FLC is started in debug mode and encounters files it cannot read, you will see errors similar to these:

shell
ERR go.crwd.dev/lc/log-collector/internal/sources/files/files.go:386 > Could not identify file. 
error="open /var/log/vmware-vmsvc-root.1.log: permission denied" 
path=/var/log/vmware-vmsvc-root.1.log

These permission denied errors confirm that the humio-log-collector user lacks read access to those specific files.

Granting File Permissions

Option 1: Add the Collector User to the adm Group

This is the recommended approach for granting access to log files owned by the adm group (such as auth.log, kern.log, or cloud-init.log). Adding humio-log-collector to the adm group grants read access to any file where the group permission includes r.

shell
$ sudo usermod -a -G adm humio-log-collector

Note

This will not grant access to files that are root-only (i.e., no group or "other" read permissions). For those files, see Option 2 or consider adjusting individual file permissions manually.

Option 2: Allow Access to all files on the Filesystem

The following capability can be added to the FLC process to grant read access to all files on the filesystem, regardless of their permissions.

Important

This provides broad access to all system files and is not recommended for anything other than testing purposes.

  1. Open an editor to create a systemd override file:

    shell
    $ sudo systemctl edit humio-log-collector.service

  2. Add the following lines in the editor:

    shell
    [Service] 
AmbientCapabilities=CAP_DAC_READ_SEARCH

  3. Save and close the editor. This creates an override file in /etc/systemd/system/humio-log-collector.service.d/ without modifying the original service file.

  4. Reload the systemd manager configuration:

    shell
    sudo systemctl daemon-reload

  5. Restart the service to apply the changes:

    shell
    $ sudo systemctl restart humio-log-collector.service

Binding to Lower Port Numbers (below 1024)

To allow the Falcon LogScale Collector to bind to port numbers below 1024 without running as root, you can use an override file to set the appropriate capability. Follow these steps:

  1. Create or edit an override file for the systemd unit: 

    $ sudo systemctl edit humio-log-collector.service

  2. In the editor, add the following lines: 

    [Service]
AmbientCapabilities=CAP_NET_BIND_SERVICE

  3. Save and close the editor.

  4. Reload the systemd manager configuration: 

    $ sudo systemctl daemon-reload

  5. Restart the service to apply the changes: 

    $ sudo systemctl restart humio-log-collector.service

This method sets the CAP_NET_BIND_SERVICE capability for the Falcon LogScale Collector process, allowing it to bind to ports below 1024 without needing root privileges. The capability is applied through systemd.

Firewall Configuration

If a firewall has been configured on your system it may interfere with the sending of Syslog data. The firewall configuration will need to be updated to allow the default syslog port, 1515, through the firewall.

On RedHat or Debian Linux installations this can be achieved using the command:

shell
$ sudo firewall-cmd --add-port=1515/tcp  --permanent

Other Linux installations may need a different configuration.

Run the Falcon LogScale Collector Manually for Debugging

You can run the Falcon LogScale Collector as a standalone process and ignore the service file etc for test purposes.

  1. Run one of the following commands:

    Note

    Make sure the dataDirectory value in config.yaml exists - default: dataDirectory: /var/lib/humio-log-collector

    • Run the following command to view errors:

      shell
      sudo -u humio-log-collector humio-log-collector --cfg /etc/humio-log-collector/config.yaml --log-level error --log-pretty

    • Run the following to view all debug information:

      shell
      sudo -u humio-log-collector -- humio-log-collector --cfg /etc/humio-log-collector/config.yaml --log-level debug --log-pretty

  2. When all changes complete, type <CTRL>+<C> to cancel the manually-run Log Collector in debug mode.

  3. Re-start the Log Collector with the following command:

    shell
    sudo systemctl start humio-log-collector.service

    and If prompted, enter the sudo password

  4. Check the status of the Log Collector service:

    shell
    sudo systemctl status humio-log-collector.service

The executable humio-log-collector is located in /usr/bin by default.