File System Scanner Agent Configuration - Linux

  • Updated on Oct 23, 2025
  • Published on Sep 24, 2025
  • 4 minute(s) read
Prev Next

1.0 Introduction

This article describes the minimum configuration requirements needed to successfully scan file system resources in an on-premises environment using the File System Scanner Agent on the Linux platform.

It also describes:

  • How to install the File System Scanner Agent.

  • How to configure the scanner through the configuration file parameters.

  • How to execute the File System Scanner Agent.

For detailed information on the File System infrastructure, refer to File System.

2.0 Scanning Permissions

For detailed information on on-premises connection scanning permissions, refer to On-premises Connection Permissions.

3.0 Prerequisites

The following are the prerequisites to configure a File System Scanner Agent on the Linux platform:

  • Fortanix On-premises Scanner: Ensure that the Fortanix On-premises Scanner ( fortanix-scanner ) package, which acts as the central service, is installed, configured, and running. It communicates with Fortanix Key Insight and with the File System Scanner Agents. When the file system scanning service (fs_accumulator) is enabled, this package starts a local HTTPS server to receive data from the agents.

    For detailed information on Fortanix On-premises Scanner installation and configuration, refer to On-premises Scanner Configuration.

  • Server Specifications

    • The server hosting the scanner must have at least 2 virtual Central Processing Units (vCPUs) allocated.

    • The server must have a minimum of 8 GB of Random Access Memory (RAM) to support the scanner.

    • The server should have at least 20 GB of storage capacity for temporarily storing scanned data.

  • Operating System and Libraries

    • Supported operating systems include Ubuntu 20.04, 22.04, 24.04, and RHEL 8/9 (alternatively, Rocky Linux 9). The necessary packages are available in .deb or .rpm formats.

  • Network Requirements

    • Outbound (File System Scanner Agent → Fortanix On-premises Scanner):

      File System Scanner Agent must be able to establish Transmission Control Protocol (TCP) connections to the Fortanix On-premises Scanner’s host and port, as defined in the configuration file.

    NOTE

    The File System Scanner Agent does not expose any ports. It only initiates outbound connections to the fortanix-scanner service.

4.0 File System Scanner Agent Installation

You must install the File System Scanner Agent package to manage your file system resources on a Linux host.

  1. Download the scanner package to your local machine. The deb or rpm package is provided with the downloaded package for the supported operating systems.

  2. Run the following command to install the scanner package:

    • Ubuntu 20.04

      sudo apt install ./fortanix-fs-scanner_<version>-focal_amd64.deb

    • Ubuntu 22.04

      sudo apt install ./fortanix-fs-scanner_<version>-jammy_amd64.deb

    • Ubuntu 24.04

      sudo apt install ./fortanix-fs-scanner_<version>-noble_amd64.deb

    • RHEL9

      sudo dnf install ./fortanix-fs-scanner-<version>-1.x86_64.rpm

  3. Generate the scanner configuration file as detailed in Section 5.0: File System Scanner Agent Configuration.

    NOTE

    A sample configuration file is present in /opt/fortanix/fs-scanner/conf/fortanix-fs-scanner.yaml.example.

  4. Initiate the scanning process as detailed in Section 6.0: Run the File System Scanner Agent.

NOTE

Installing a new version of the File System Scanner Agent for Linux will overwrite the following default files in the /opt/fortanix/fs-scanner/conf/ directory:

  • fortanix-fs-scanner.yaml.example

  • fortanix-fs-scanner.service.example

However, any custom files (for example, user-created configurations) in the same directory will not be removed during the upgrade.

TIP

To avoid potential loss of important settings, it is recommended to back up your configuration file before proceeding with the installation.

5.0 File System Scanner Agent Configuration

For detailed information on how to configure the File System Scanner Agent for the Linux platform, refer to File System Scanner Agent Configuration File.

6.0 Run the File System Scanner Agent

After the File System Scanner Agent is configured, it must be run with root privileges (for example, using sudo).

NOTE

  • You must start the fortanix-scanner package first before executing the File System Scanner Agent (fortanix-fs-scanner). If the fortanix-scanner service is not running, the File System Scanner Agent fails with a connection refused error when attempting to register a new scan.

  • After you start the File System Scanner Agent, any changes made to the scanner configuration file require restarting the scanner to apply the latest updates.

  • If the scan is interrupted or closed, the next scan will start from the beginning.

  • The scanner commands require the configuration file to be named config.yaml. If you are using the provided example file (fortanix-fs-scanner.yaml.example), ensure to copy or rename it to config.yaml before running any of the scanner commands in the following sections.

6.1 Manual Run

Run the following command to manually start the File System Scanner Agent:

sudo -u fortanix -H /opt/fortanix/fs-scanner/bin/fortanix-fs-scanner -c /opt/fortanix/fs-scanner/conf/config.yaml

6.2 Using a Scheduled Timer

To ensure the File System Scanner Agent runs automatically, it can be configured as a systemd timer. This allows the agent to run on a defined schedule without manual intervention. Using a systemd timer is the recommended approach for running the File System Scanner Agent.

This method uses the example unit files provided in /opt/fortanix/fs-scanner/conf/.

The systemd timer automatically triggers the scanner at the specified intervals. While manual execution of the agent is still possible (for example, during debugging), scheduling with a systemd timer ensures consistent and reliable operation.

In the downloaded package, you will find the following example files:

  • Service file: fortanix-fs-scanner.service.example - Ensures the File System Scanner Agent runs as a low-priority background task, minimizing impact on normal system operations.

  • Timer unit: fortanix-fs-scanner.timer.example - Defines the schedule for running the service.

Here is the sample timer file:

[Unit]

Description = Fortanix File System Scanner (scheduled)

[Timer]

OnCalendar=Sun 03:45

Persistent=false

[Install]

WantedBy=timers.target

This configuration runs the scanner every Sunday at 03:45 AM,  as specified in the OnCalendar parameter.

Perform the following steps to schedule the File System Scanner Agent:

  1. Run the following command to copy the example service and timer unit files into the systemd directory:

    sudo cp /opt/fortanix/fs-scanner/conf/fortanix-fs-scanner.service.example /usr/lib/systemd/system/fortanix-fs-scanner.service
sudo cp /opt/fortanix/fs-scanner/conf/fortanix-fs-scanner.timer.example /usr/lib/systemd/system/fortanix-fs-scanner.timer

  2. Run the following commands to enable and start the timer so it starts automatically on boot:

    sudo systemctl enable fortanix-fs-scanner.timer
sudo systemctl start fortanix-fs-scanner.timer

7.0 Troubleshooting

Refer to On-premises Connection Troubleshooting for guidance on troubleshooting steps for common issues encountered while configuring and running Fortanix Key Insight in on-premises environments.