Monitor changes to your file system

This feature is deprecated.

This feature has been deprecated as of Splunk Enterprise version 5.0. This means that although it continues to function in the current version of the Splunk platform, it might be removed in a future version. As an alternative, you can: Learn how to monitor file system changes on Windows systems. Use the auditd daemon on *nix systems and monitor output from the daemon. For a list of all deprecated features, see the topic Deprecated features in the Release Notes.

The Splunk platform file system change monitor tracks changes in your file system. The monitor watches a directory you specify and generates an event when that directory undergoes a change. It can detect when a file on the system is edited, deleted, or added. It detects changes on any file, including files that are not Splunk platform-specific files.

For example, you can configure the file system change monitor to watch the /etc/sysconfig/ directory and alert you any time the system configurations change.

To learn how to monitor file system changes on Windows with built-in Microsoft auditing tools, see Monitor file system changes.

The file system change monitor works with on-premises versions of the Splunk platform only. If you use Splunk Cloud, you must use a universal or heavy forwarder to send file system change data to the Splunk Cloud instance.

How the file system change monitor works

The file system change monitor detects changes on the *nix file system by using the following attributes:

• modification date/time
• group ID
• user ID
• file mode (read/write attributes, etc.)
• an optional Secure Hash Algorithm-256 (SHA256) hash of file contents

You can configure the following features of the file system change monitor:

• allow list using regular expressions
  • specify files that will be checked, no matter what
• deny list using regular expressions
  • specify files to skip
• directory recursion
  • including symbolic link traversal
  • scanning multiple directories, each with their own polling frequency
• cryptographic signing
  • creates a distributed audit trail of file system changes
• indexing entire file as an event on add/change
  • size cutoffs for sending entire file and/or hashing
• all change events indexed by, and searchable through, the Splunk platform

The file system change monitor generates audit events whenever any process changes, deletes, or adds to the contents of the $SPLUNK_HOME/etc/ directory. When you start an on-premises Splunk instance for the first time, it generates an audit event for each file in the $SPLUNK_HOME/etc/ directory and all its subdirectories. Afterward, any change in configuration, regardless of origin, generates an audit event for the affected file.

The file system change monitor sends data to various indexes depending on how you configure the file system monitoring input. If you have configured the signedaudit setting for the input, the instance sends the file system change to the audit index. If you have not configured signedaudit, then the instance writes the events to the main index, unless you specify another index.

The file system change monitor only tracks that a change has occurred. It does not track the user name of the account that made the change. For user-level monitoring, consider using built-in operating system audit tools, which have access to this information.

Do not configure the file system change monitor to monitor your root file system. Doing so can be very resource-intensive if you enable directory recursion.

Prerequisites to configuring the file system change monitor

• If you use Splunk cloud, you must configure a universal or heavy forwarder to connect to your Splunk Cloud instance to send file system change data there.
• You must use configuration files to configure the file system change monitor.

Configure the file system change monitor

To use the file system change monitor to watch any directory, add or edit an [fschange] stanza to the inputs.conf configuration file in the $SPLUNK_HOME/etc/system/local/ directory, or your own custom application directory in $SPLUNK_HOME/etc/apps/ on the machine from which you want to collect file system change information. For information on configuration files in general, see About configuration files in the Admin manual.

You must restart the Splunk platform any time you make changes to the [fschange] stanza in the inputs.conf file.

1. On the Splunk platform instance that is to send data to Splunk Cloud, use a text editor to open the inputs.conf configuration file.
2. Add [fschange:<directory>] stanzas to specify files or directories that the Splunk platform should monitor for changes.
3. Save the inputs.conf file and close it.
4. Restart the Splunk platform instance. File system change monitoring begins immediately.

File system change monitor syntax

Here is the syntax for the [fschange] stanza:

[fschange:<directory or file to monitor>]
<setting1> = <val1>
<setting2> = <val2>
...

The Splunk platform monitors all adds, updates, and deletes to the directory and its subdirectories. Any change generates an event that the Splunk platform indexes. <directory or file to monitor> defaults to $SPLUNK_HOME/etc/.

Configuration file settings for the file system change monitor

All settings for the file system change monitor are optional. Here is the list of available settings:

Setting	Description	Default
index=<indexname>	The index where the Splunk platform stores all events it generates.	main, unless you have turned on audit event signing, then _audit.
recurse=<true | false>	Whether or not to recurse all directories within the directory specified in [fschange]. Set to true to recurse all subdirectories and false to specify only the current directory.	true
followLinks=<true | false>	Whether or not the file system change monitor follows symbolic links. Set to true to follow symbolic links and false to not follow symbolic links.	false File system loops can occur if you set followLinks on a directory that has symbolic links to files in the same directory.
pollPeriod=N	Check this directory for changes every N seconds.	3600 seconds If you make a change to a file in the monitored directory, the file system audit events could take anywhere between 1 and 3600 seconds to be generated and become available in audit search.
hashMaxSize=N	Calculate a SHA1 hash for every file that is less than or equal to N size in bytes. This hash can be used as an additional method for detecting change in the file/directory.	-1, The splunk platform does not calculate a hash for change detection)
signedaudit=<true | false>	Send cryptographically signed add, update, or delete events. Set to true to generate events in the _audit index. Set to false if you're configuring the index setting. When setting signedaudit to true, confirm auditing is enabled in the audit.conf configuration file.	false
fullEvent=<true | false>	Send the full event if an add or update change is detected. Further qualified by the sendEventMaxSize attribute.	false
sendEventMaxSize=N	Only send the full event if the size of the event is less than or equal to N bytes. This limits the size of indexed file data.	-1 (unlimited)
sourcetype = <string>	Set the source type for events from this input. "sourcetype::" is prepended to <string>.	audittrail (if signedaudit=true) or fs_notification (if signedaudit=false)
filesPerDelay = <integer>	Injects a delay specified by delayInMills after processing <integer> files. This setting throttles file system monitoring so it does not consume as much CPU.	n/a
delayInMills = <integer>	The delay, in milliseconds, to use after processing every <integer> file as specified in filesPerDelay. This setting is used to throttle file system monitoring so it does not consume as much CPU.
filters=<filter1>,<filter2>,...<filterN>	Each of these filters applies from left to right for each file or directory that is found during the monitors poll cycle.	n/a

Define a filter for the file system change monitor

To define a filter to use with the filters attribute, add a [filter...] stanza as follows:

[filter:blacklist:backups] 
regex1 = .*bak
regex2 = .*bk
[filter:whitelist:code] 
regex1 = .*\.c 
regex2 = .*\.h 
 
[fschange:/etc] 
filters = backups,code 

The following list describes how the Splunk platform handles fschange allow list and deny list logic:

• The events go through the list of filters until they reach their first match.
• If the first filter to match an event is an allow list, then the Splunk platform indexes the event.
• If the first filter to match an event is a deny list, the filter prevents the event from getting indexed.
• If an event reaches the end of the chain with no matches, then the Splunk platform indexes the event.

To default to a situation where the Splunk platform does not index events if they don't match an allow list explicitly, end the chain with a deny list that matches all remaining events.

For example:

...
filters = <filter1>, <filter2>, ... terminal-blacklist

[filter:blacklist:terminal-blacklist] 
regex1 = .?

If you exclude a directory including a terminal deny list at the end of a series of allow lists, then the Splunk platform excludes all its subfolders and files because they do not pass any allow list. To accommodate this scenario, include all desired folders and subfolders explicitly before the deny list items in your filters.

Example of explicit inclusion and terminal exclusion

This configuration monitors files in the specified directory with the extensions .config, .xml, .properties, and .log and ignores all others.

In this example, the file system change monitor could exclude a directory. If this is the case, the Splunk platform excludes all of its subfolders and files as well. Only files in the specified directory would be monitored.

[filter:whitelist:configs]
regex1 = .*\.config 
regex2 = .*\.xml 
regex3 = .*\.properties 
regex4 = .*\.log
 
[filter:blacklist:terminal-denylist]
regex1 = .?
 
[fschange:/var/apache] 
index = sample 
recurse = true 
followLinks = false 
signedaudit = false 
fullEvent = true 
sendEventMaxSize = 1048576 
delayInMills = 1000 
filters = configs,terminal-denylist 

Use the file system change monitor with a universal forwarder

To forward file system change monitor events from a universal forwarder, you must configure the exchange stanza with the signedaudit = false and index=_audit settings.

[fschange:<directory or file to monitor>]
signedaudit = false
index=_audit

With this workaround, the Splunk platform indexes file system change monitor events into the _audit index with a sourcetype of fs_notification and a source of fschangemonitor, instead of a soiurce and sourcetype of audittrail.