FSpy
            (c) Richard Sammet (e-axe)
              http://mytty.org/fspy/ (defunct)


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 comile 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
---------------
drop me a line (or multiple) to
richard[tod]sammet[ta]gmail[tod]com

-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG v2.0.9 (GNU/Linux)

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
AKCXdZdSbpFPLJny+S7CKQ13CaVL7A==
=+atq
-----END PGP PUBLIC KEY BLOCK-----