Skip to content
fanotify

A Ruby gem for Linux

Your filesystem
has a lot to say.

Listen in Ruby. Watch file activity and respond to permission events with native Linux fanotify bindings.

Start listening Read the documentation

Ruby 3.2+ Linux 5.1+ MIT licensed

A change becomes an event.
/data
report.csvcreated
notes.txtmodified
Linux fanotify
Your Ruby handler
event.mask # => [:create]
event.name # => "report.csv"
Illustrated event flow. No polling loop to write.

From a file change
to a Ruby block.

Install the gem, choose a directory, and handle the events you care about. Start with ordinary notifications.

gem install fanotify

Builds a native extension. You’ll need a C compiler and Linux UAPI headers.

View on RubyGems
watch.rbRuby
require "fanotify"

Fanotify.watch("/data",
  events: %i[create delete modify]
) do |event|
  puts "#{event.mask.inspect} #{event.name}"
end

Example output

[:create] report.csv
[:modify] notes.txt

This example uses FID and filename reports, requiring Linux 5.9+. Unprivileged FID groups require Linux 5.13+ and a filesystem that supports file handles.

Observe what happens.
Decide what happens next.

Follow file activity

Build audit logs around create, delete, modify, and open events. Inspect file identity and name records from the kernel.

Explore the audit logger

Handle access decisions

Allow, deny, or defer permission events. Unanswered events are allowed when the handler returns, with cleanup built in.

Read the permission guide

Fetch data on demand

Explore pre-access range events for hierarchical storage. Experimental support needs Linux 6.14+ and an HSM-capable filesystem.

Explore lazy fetching

Close to the kernel.
Clear about the boundaries.

Fanotify is built for Linux. Kernel features, filesystem support, and process capabilities determine which events you can use.

Check platform support

The baseline

Ruby 3.2+ and Linux 5.1+ with CONFIG_FANOTIFY. Newer report types need newer kernels.

Permission events need care

Permission events and mount or filesystem marks need CAP_SYS_ADMIN. Permission handlers block the requesting process: keep them bounded and follow the handler safety rules.

Working on another OS?

The gem loads on macOS, BSD, and Windows, but Fanotify.supported? returns false. Run filesystem monitoring on Linux.