1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
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>
|
