File System Scanner Agent Configuration

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 and Configuration

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

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

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

Generate and configure the File System Scanner Agent configuration file as detailed in File System Scanner Agent Configuration File.
NOTE
A sample configuration file is present in /opt/fortanix/fs-scanner/conf/fortanix-fs-scanner.yaml.example.
Initiate the scanning process as detailed in Section 5.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.

4.1 Scanning Files from Amazon S3 Mounted as Shared Drive

This section describes how to enable the File System Scanner Agent to access and scan data stored in an Amazon S3 bucket by mounting it as a shared drive on Linux.

Mounting an Amazon S3 bucket (for example, using Mountpoint for Amazon S3) exposes the bucket contents as a file system. The File System Scanner Agent can then traverse and scan the mounted path like a standard file system.

4.1.1 Prerequisites

In addition to the prerequisites listed in Section 3.0: Prerequisites,

Ensure you have access to an Amazon S3 bucket with appropriate permissions (at least read access).
Install the Mountpoint for Amazon S3 utility. For more information, refer to the AWS official documentation.
Ensure FUSE is enabled on the system, as it is required to mount the S3 bucket as a file system.
Ensure the File System Scanner Agent is installed on the same machine where the S3 bucket is mounted.

4.1.2 Configure S3 Mount and Enable Scanning

Perform the following steps to mount the S3 bucket as a shared drive and enable the File System Scanner Agent to access and scan the data:

Run the following commands to download and install an S3 mount utility (the example shown below uses Mountpoint for Amazon S3):
```
wget https://s3.amazonaws.com/mountpoint-s3-release/latest/x86_64/mount-s3.deb
sudo apt install ./mount-s3.deb
```
Run the following command to create a local directory to use as the mount path:
```
mkdir <mount-path>
```
Here, <mount-path> is the local directory where the S3 bucket will be mounted. For example, ~/s3-mount.
Run the following command to mount the S3 bucket:
```
mount-s3 <bucket name> <mount-path>
```
Here, <bucket name> is the name of your S3 bucket. For example, sandeep-ki-001.
By default, mounted S3 buckets may restrict access to the mounting user. Run the following commands to allow the File System Scanner Agent (running as another user, for example, fortanix) to access the mount:
- Enable FUSE configuration:
```
echo "user_allow_other" | sudo tee -a /etc/fuse.conf
```
- Remount the bucket with --allow-other:
```
fusermount -u <mount-path>
mount-s3 <bucket-name> <mount-path> --allow-other
```
This ensures the File System Scanner Agent can read files from the mounted path.
Add or modify the included_root_paths parameter in the File System Scanner Agent configuration file to include the mounted S3 path so that the scanner can traverse and scan the data.
```
included_root_paths:
  - <mount-path>
```
Here, <mount-path> is the directory used to mount the S3 bucket (as created in Step 2). For example, /home/sandeep/s3-mount.
Run the following command to start the scanner and scan the keys:
```
sudo -u fortanix -H /opt/fortanix/fs-scanner/bin/fortanix-fs-scanner -c <fs-scanner-config-file>
```
Here, <fs-scanner-config-file> is the path to the File System Scanner Agent configuration file.
For example, /home/sandeep/Downloads/terraform_azure_sql_vm_final/on-prem/only_fs_agent_config.yaml .

5.0 Run the File System Scanner Agent

After configuring the File System Scanner Agent, it can be run under a dedicated restricted user account (For example, fortanix) to follow a least-privilege security model.

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.

5.1 Manual Run

Recommended (Least Privilege): Run as the fortanix User
Use the following command to start the File System Scanner Agent as the dedicated fortanix user:
```
sudo -u fortanix -H /opt/fortanix/fs-scanner/bin/fortanix-fs-scanner -c /opt/fortanix/fs-scanner/conf/config.yaml
```
This ensures the scanner runs under a controlled, restricted account that has only the required permissions to read the intended file system paths.
Alternative (If already logged in as the fortanix user)
If you are already logged in as the fortanix user or another dedicated user with the required privileges, sudo is not needed.
```
/opt/fortanix/fs-scanner/bin/fortanix-fs-scanner -c /opt/fortanix/fs-scanner/conf/config.yaml
```

5.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:

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

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

6.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.

File System Scanner Agent Configuration - Linux