                       FSpy
         Originally by Richard Sammet (e-axe)
        Maintained by Bean Huo <beanhuo@iokpp.de>
       https://salsa.debian.org/debian/fspy


INTRODUCTION
------------
fspy is a lightweight Linux filesystem activity monitoring tool that supports
both inotify and fanotify kernel subsystems. It monitors filesystem events
(file/directory access, modification, creation, deletion) in real-time.

Key features:
  - Real-time filesystem event monitoring
  - Dual monitoring modes: inotify (efficient) and fanotify (process tracking)
  - Process tracking: identify which process is accessing files (requires root)
  - Recursive directory watching with configurable depth
  - Flexible filtering using strings or regular expressions
  - Customizable output format
  - Resource-efficient and fast
  - Diff tracking for file attributes (size, timestamps, permissions, etc.)
  - Type-specific monitoring (files, directories, symlinks, etc.)


REQUIREMENTS
------------
linux >= 2.6.13 (http://kernel.org)
inotify (for normal monitoring, available since Linux 2.6.13)
fanotify (for process tracking with -P flag)
  - Introduced in Linux kernel 2.6.36
  - Enabled and stable since Linux 2.6.37
  - Requires root privileges (CAP_SYS_ADMIN capability)
stat
glibc >= 2.4

Note: Process tracking (-P flag) requires root privileges (sudo) due to
fanotify's requirement for CAP_SYS_ADMIN capability.


COMPILE AND INSTALL
-------------------
Just type make to compile and make install to install the fspy
binary to /usr/local/bin.


MONITORING MODES
----------------
fspy supports two kernel monitoring APIs, automatically selected based on your needs:

1. inotify Mode (Default)
   - Used when: Running without -P flag
   - Root required: No
   - Performance: Efficient, targeted monitoring
   - Process info: No
   - Best for: Normal file monitoring, user files, development

2. fanotify Mode (Process Tracking)
   - Used when: Running with -P/--show-process flag
   - Kernel requirement: Linux >= 2.6.37 (introduced in 2.6.36, stable in 2.6.37)
   - Root required: Yes (must use sudo)
   - Performance: Higher overhead (mount-level monitoring)
   - Process info: Yes (PID, UID, command name)
   - Best for: Security auditing, intrusion detection, tracking file access

Key Difference:
  - inotify watches specific paths you specify (efficient)
  - fanotify monitors entire filesystems/mounts (can identify processes)

Both modes support all filtering and output options (-F, -I, -T, -O, -D).

Note: The -R (recursive) option is only applicable to inotify mode. When using
-P (fanotify mode), the entire mount point is automatically monitored, making
recursive depth specification unnecessary.


EXAMPLES
--------
Basic monitoring:
  fspy /tmp/
    Monitor all filesystem events in /tmp/ (non-recursive)

Recursive monitoring:
  fspy -R 2 -T f,d /etc/
    Monitor files and directories in /etc/ with recursive depth of 2
    (monitors /etc/*/*/* - base dir plus 2 levels deep)

Filtering output:
  fspy -F '\.conf$' /etc/
    Monitor only files ending with .conf in /etc/

  fspy -F '\.conf' -I 'wvdial.conf' /etc/
    Monitor .conf files but exclude wvdial.conf

Custom output format:
  fspy -O '[,T,], ,d,:,p,f' /tmp/
    Output: [Mon Sep  1 12:31:25 2008] file was opened:/tmp/myfile

  fspy -O 'Event: ,d, | Path: ,p,f, | Type: ,t' /var/log/
    Output: Event: file was modified | Path: /var/log/syslog | Type: file

Diff tracking (highlight changes):
  fspy -D s,A -O '[,T,], ,d,:,p,f, size: ,s, atime: ,A' /tmp/
    Track and display size and access time changes

  fspy -D s,M,O /home/user/documents/
    Monitor size, modification time, and permissions changes

Type-specific monitoring:
  fspy -T f -R 3 /var/log/
    Monitor only regular files, 3 levels deep

  fspy -T d /tmp/
    Monitor only directories

Adaptive mode (experimental):
  fspy -A -R 2 /var/
    Automatically add newly created items to the watch list

Process tracking (requires root):
  sudo fspy -P /etc/passwd
    Monitor /etc/passwd and show which process (PID/UID/CMD) accesses it

  sudo fspy -P -F '\.conf$' /etc/
    Track all .conf file access with process information

  sudo fspy -P -O 'f, - ,d, (PID:,w,)' -F '\.log' /var/log/
    Custom output showing filename, description, and PID for .log files

  sudo fspy -P -F '\.conf' -I '\.(bak|old)' -T f /etc/
    Security audit: Track .conf files, exclude backups, only regular files,
    show which processes are accessing them

Combined filtering with process tracking:
  sudo fspy -P -O '[,T,], UID:,U, ,d, ,f' -F 'shadow|passwd|group' /etc/
    Monitor sensitive files with timestamp, UID, description, and filename

For more details on options, run: fspy --help
Or see the manpage: man fspy
Or check the comprehensive documentation in: docs/README.md


MISC
----
Have a look at the manpage:
man 7 inotify

Especially interesting are the following files:
/proc/sys/fs/inotify/max_queued_events
/proc/sys/fs/inotify/max_user_instances
/proc/sys/fs/inotify/max_user_watches


BUGS & FEATURES
---------------
Please report bugs and feature requests at:
https://salsa.debian.org/debian/fspy/-/issues

Maintainer: Bean Huo <beanhuo@iokpp.de>
