File System Monitoring

NetXMS monitors file systems for space utilization, inode usage, and individual file properties. This page covers file-level monitoring features beyond the basic file system metrics available through OS monitoring.

File Metrics

File.Content(path)

First line of file content (max 255 characters). Requires master server session.

Data Type

String

Platforms

All
Table 1. Arguments
Argument Type Description

path

String

File path

File.LineCount(path)

Number of lines in file.

Data Type

Unsigned Integer 64

Platforms

All
Table 2. Arguments
Argument Type Description

path

String

File path

File.Size(path)

File size in bytes. When path is a directory, returns the total size of matching files in it; recursion into subdirectories is controlled by the recursive argument (see File Count and Size Filtering).

Data Type

Unsigned Integer 64

Platforms

All
Table 3. Arguments
Argument Type Description

path

String

File path (or directory path when used with filters, see File Count and Size Filtering)

File.Type(path)

File type identifier.

Data Type

Unsigned Integer

Platforms

All
Table 4. Arguments
Argument Type Description

path

String

File path
Table 5. Return Values
Value Description

0

Does not exist

1

Directory

2

Device

3

Regular file

4

Other

File.Count(path, pattern, recursive, size, age)

Number of files matching criteria. See File Count and Size Filtering for argument details.

Data Type

Unsigned Integer

Platforms

All

File.FolderCount(path, pattern, recursive, size, age)

Number of subdirectories matching criteria. See File Count and Size Filtering for argument details.

Data Type

Unsigned Integer

Platforms

All

File.Time.Access(path)

Last access time (seconds since epoch).

Data Type

Unsigned Integer 64

Platforms

All
Table 6. Arguments
Argument Type Description

path

String

File path

File.Time.Change(path)

Last metadata change time (seconds since epoch).

Data Type

Unsigned Integer 64

Platforms

All
Table 7. Arguments
Argument Type Description

path

String

File path

File.Time.Modify(path)

Last modification time (seconds since epoch).

Data Type

Unsigned Integer 64

Platforms

All
Table 8. Arguments
Argument Type Description

path

String

File path

File.Hash.CRC32(path)

CRC32 checksum.

Data Type

Unsigned Integer

Platforms

All
Table 9. Arguments
Argument Type Description

path

String

File path

File.Hash.MD5(path)

MD5 hash digest.

Data Type

String

Platforms

All
Table 10. Arguments
Argument Type Description

path

String

File path

File.Hash.SHA1(path)

SHA-1 hash digest.

Data Type

String

Platforms

All
Table 11. Arguments
Argument Type Description

path

String

File path

File.Hash.SHA256(path)

SHA-256 hash digest.

Data Type

String

Platforms

All
Table 12. Arguments
Argument Type Description

path

String

File path

File Count and Size Filtering

The File.Count, File.Size, and File.FolderCount metrics share the same 5-argument signature for filtering files:

File.Count(path, pattern, recursive, size, age)
Table 13. Arguments
Argument Description

path

Directory path to search (required)

pattern

File name glob pattern (e.g., .log). Prefix with ! for inverse match (files NOT matching the pattern). Default:

recursive

Search subdirectories: 0 or false (no), 1 or true (yes). Default: 0

size

Size filter in bytes. Positive value: only files larger than this size. Negative value: only files smaller than abs(value). 0 = no filter.

age

Age filter in seconds. Positive value: only files older than this many seconds. Negative value: only files newer than abs(value) seconds. 0 = no filter.
The age parameter uses sign convention: positive = "older than N seconds" (modified before now - N), negative = "newer than N seconds" (modified within the last N seconds). For example, -1800 means files modified within the last 30 minutes.

Path Macro Support

The following macros are supported in path and pattern arguments for all File.* parameters:

  • Environment variables as {ENV_VAR_NAME}

  • strftime(3C) macros for date/time substitution

  • Text inside backtick (`) characters is executed as a command and the first line of output is used (requires the requesting server to be listed in MasterServers in agent configuration)

Examples
File.Count(/var/spool/myapp)
File.Count(/data/incoming,*.xml,0,1048576)
File.Count(/var/spool/queue,*,0,0,3600)
File.Count(/var/spool/queue,*,1,0,-1800)
File.Count(/var/log,!*.log,0)
File.Size(/var/log/app.log)

File Integrity Monitoring (FileMonitor)

The agent includes a built-in file integrity monitoring feature that detects file additions, modifications, and deletions using SHA-256 hashing.

Configuration

Configure monitored paths in the agent configuration file:

[FileMonitor]
Interval = 10800
Path = /etc/important-configs
Path = /home/user/critical-file.txt
Parameter Default Description

Path

Path to a file or directory to monitor. Directories are scanned recursively. Can be specified multiple times.

Interval

21600

Check interval in seconds (default: 6 hours)

No additional subagent is needed — FileMonitor is part of the agent core. The agent persists file state (hash, modification time, permissions) in its local database between restarts.

Generated Events

Event Code Description

SYS_AGENT_FILE_CHANGED

127

A monitored file’s content, modification time, or permissions changed. Parameter: file path.

SYS_AGENT_FILE_ADDED

128

A new file was detected in a monitored directory. Parameter: file path.

SYS_AGENT_FILE_DELETED

129

A previously tracked file no longer exists. Parameter: file path.

All three events have WARNING severity.

File Change Monitoring

To detect file modifications without FileMonitor, you can monitor file attributes over time using DCIs:

  • Use File.Time.Modify(path) to track when a file was last changed

  • Use File.Hash.SHA256(path) to detect content changes regardless of timestamps

  • Use File.Size(path) to detect growth or truncation

Configuration File Monitoring Example

To alert when a configuration file changes:

  1. Create a DCI with metric File.Hash.SHA256(/etc/myapp/config.yml)

  2. Set data type to String

  3. Add a threshold with function Diff with previous value, operation not equal, and value 0. For a String DCI, Diff computes 1 when the value differs from the previous poll and 0 when it is unchanged (compared as an integer), so the threshold activates whenever the hash changes.

File System Events

NetXMS can generate events based on file system conditions:

  • File system space running low (threshold on FileSystem.FreePerc)

  • Spool directory growing (threshold on File.Count)

  • Configuration file changed (threshold on file hash)

  • Inode exhaustion (threshold on FileSystem.FreeInodesPerc)

See Thresholds for configuring alert conditions.

Agent Configuration

File monitoring parameters are provided by the agent core — no additional subagent is needed.

For remote file browsing and management, load the filemgr.nsm subagent. See Remote File Management for details.

File Access Permissions

The agent runs under a specific user account and can only access files readable by that user. To monitor files owned by other users:

  • Run the agent as root (Linux) or LocalSystem (Windows)

  • Or grant the agent user read permissions on the target files/directories