Documentation

4.7. Local file system monitor

4.7.1. Introduction

This page describes the configuration options available for the local file system monitor resource.

The resource allows monitoring local file systems and emitting audit log events once files or sub-directories are changed inside the monitored path.

If the configured path does not exist, the monitor will fail to start.

If the configured path to monitor is removed while the resource is running, its content is reported as removed and the resource will continue to monitor the path and wait for it to be created. The resource monitor will not stop or fail.

4.7.2. Working with the source monitor

4.7.2.1. Understanding the changes poll interval

When the changes_poll_interval passes, the application will read all files, folders, and attributes (size, last modification time, etc) found in the monitored folder. Each snapshot is then compared with the previous.

If there are changes between the snapshots, they are notified to the application.

Before doing the actual notification, the application will wait for changes to be considered stable as defined by another option, stable_interval.

Note

Lower values help detect changes quicker, but increase the load, CPU, and network usage for local and remote servers.

The poll interval might drift.

For example, with a value of 72000 and a transfer started at 15:35, the product might be busy at 15:35. In this case, the check is done only at 15:36 and the next check will be scheduled for 17:36.

4.7.2.2. Changing the file stable period settings

When a new file is created or a file starts to be modified, it is not processed by SFTPPlus right away. This allows an external program to finish handling the file.

If no other changes to the file are observed after this interval, it is then processed.

Criteria for a file to be considered stable:

  • Size is not changed.

  • Last modified time attribute is not changed.

  • The configured stable interval has elapsed.

After the last modification is observed, this interval is then allowed to pass.

Each change will reset the stable interval for the file itself since each file has its own stable counter.

Since changes can only be observed with a resolution defined by changes_poll_interval, the stable_interval needs to be a multiple.

The following will check new files every hour and transfer stable files after two hours, even if the stable_interval is lower:

[transfers/b904e6a6-c29b-4ccf-8abd-edcae4d3324f]
changes_poll_interval = 3600
stable_interval = 60

4.7.2.3. File age discovery

The file age is determined based on the file's modified attribute.

Some file copy tools provided by the operating system or 3rd party might preserver the file attribute during the copy operation. In this case, even if you make a new copy of a file, it will be observed as an old file by the SFTPPlus system.

Windows Explorer or command prompt tools will preserve the original modified date of the copied file.

Linux and macOS tools will update the modified date of the copied files. The modified data is preserved only when the copy operation is done in archive mode.

Below you can find the list of available configuration options for resources of the monitor type, other than the standard resource configuration options.

4.7.3. source_path

Default value:

Empty

Optional:

Yes

Values:
  • Absolute path on the local file system.

  • Relative path to the server installation folder.

From version:

2.10.0

Description:

Path to the monitored source folder.

4.7.4. recursive

Default value:

No

Optional:

Yes

From version:

2.10.0

Values:
  • Yes

  • No

Description:

Determines whether the monitor should look for source files and folders only in the configured path, or recurse in all its descendant folders.

4.7.5. changes_poll_interval

Default value:

10

Optional:

Yes

From version:

3.0.0

Values:
  • Number of seconds.

Description:

This is the time interval that defines the delay used to observe the changes in the monitored path and compare snapshots, a record of any changes, in a monitored folder.

When set to zero or a negative number, the default value is used.

4.7.6. stable_interval

Default value:

10

Optional:

Yes

From version:

2.10.0

Values:
  • Number of seconds.

Description:

This is the interval after which a file is considered stable if no changes are made to it.

These values should be greater than the value of changes_poll_interval.

4.7.7. source_filter

Default value:

Empty

Optional:

Yes

From version:

2.10.0

Values:
  • Globbing expression containing wildcard characters.

  • Regular expression

  • Empty

Description:

It can be configured using a Globbing expression or regular expression.

It defines the pattern used to select source files to be transferred. For more details about the syntax used by this configuration option see the matching expression documentation.

Only files matching the expression will be transferred.

A globbing expression can contain multiple file mask filtering rules, separated by the pipe character |.

If a globbing expression doesn't include path separators, it only matches the file name. The parent path is ignored.

When using regular expressions, only file names are matched.

Leave it empty to transfer all files.

Since 4.16.0, the globbing expression can be used to filter based on the full file path, not only on the file name part.

4.7.8. retry_count

Default value:

5

Optional:

Yes

From version:

5.1.0

Values:
  • 0

  • Positive integer

Description:

It is the number of retries in the case the monitored directory is no longer available. The retries for a failed source directory, are done after changes_poll_interval seconds. If the directory is still not available after all retries, the whole resource fails and will need to be manually started, after investigating the root cause of the error.

When set to 0, failed operations are never retried and the resource is stopped on first failure.

4.7.9. file_age_notification

Default value:

0

Optional:

Yes

Values:
  • Number of seconds.

From version:

4.0.0

Description:

Age in seconds after which an event is triggered for files which are not modified in that time.

A separate event is emitted for each file.

Set it to 0 to disable triggering this type of events.

It will check for older files based on the changes_poll_interval configuration.

4.7.10. file_age_auto_delete

Default value:

0

Optional:

Yes

Values:
  • Number of seconds.

From version:

3.52.0

Description:

Age in seconds after which a file is automatically deleted if it is still found in the monitored path.

A separate event is emitted for each deleted file.

Set it to 0 to disable automatically deleting files.

It will check for older files based on the changes_poll_interval configuration.

4.7.11. monitored_operations

Default value:

all

Optional:

Yes

Values:
  • Comma-separated values.

  • disable

  • all

  • exist

  • create

  • modify

  • rename

  • delete

From version:

3.52.0

Description:

Comma-separated list of file operations for which to emit notification events.

Each action has a separate event ID.

Set it to all for emitting events for any file operation.

Set it to disable to not emit events for file operations.

If both all and disable are defined at the same time, the monitor will emit events for all file operations, ignoring the disable value.