Categorygithub.com/opcoder0/fanotify
modulepackage
0.4.2
Repository: https://github.com/opcoder0/fanotify.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
11
Dependents
0
Files
754 SLOC

# README

Fanotify Library

Fanotify library provides a simple API to monitor filesystem for events.

The listener is initialized with flags automatically based on the kernel version. The mark flag features that specify the the events to monitor a file/directory are validated and checked for valid combinations and validated against the kernel version.

fanotify has features spanning different kernel versions -

  • For Linux kernel version 5.0 and earlier no additional information about the underlying filesystem object is available.
  • For Linux kernel versions 5.1 - 5.8 additional information about the underlying filesystem object is correlated to an event.
  • For Linux kernel version 5.9 or later the modified file name is made available in the event.

Examples

Example code for different use-cases can be found here https://github.com/opcoder0/fanotify-examples

Known Issues

Certain flag combinations / event types cause issues with event reporting.

  • fanotify.FileCreated cannot be or-ed / combined with fanotify.FileClosed. The fanotify event notification group does not generate any event for this combination.
  • Using fanotify.FileOpened with any of the event types containing OrDirectory causes numerous duplicate events for the path.
  • fanotifyFileOrDirectoryOpened with any of the other event types causes numerous duplicate events for the path.

Tests

Running tests require CAP_SYS_ADM privilege. To run the tests make sure to add go to the sudo PATH.

The command runs all the tests except the ones that test the flag bugs mentioned in the "Known Issues" section above -

sudo go test -v

To run the tests with flag issues -

sudo go test -v -bug

# Functions

NewListener returns a fanotify listener from which filesystem notification events can be read.

# Constants

FileAccessed event when a file is accessed.
FileAccessPermission event when a permission to read a file or directory is requested.
FileAttribChanged event when a file attribute has changed Requires Linux kernel 5.1 or later (requires FID).
FileClosed event when a file is closed after write or no write.
FileClosedAfterWrite event when a file is closed.
FileClosedWithNoWrite event when a file is closed without writing.
FileCreated event when file a has been created Requires Linux kernel 5.1 or later (requires FID) BUG FileCreated does not work with FileClosed, FileClosedAfterWrite or FileClosedWithNoWrite.
FileDeleted event when file a has been deleted Requires Linux kernel 5.1 or later (requires FID).
FileModified event when a file is modified.
FileMovedFrom event when a file has been moved from the watched directory Requires Linux kernel 5.1 or later (requires FID).
FileMovedTo event when a file has been moved to the watched directory Requires Linux kernel 5.1 or later (requires FID).
FileOpened event when a file is opened.
FileOpenedForExec event when a file is opened with the intent to be executed.
FileOpenPermission event when a permission to open a file or directory is requested.
FileOpenToExecutePermission event when a permission to open a file for execution is requested.
FileOrDirectoryAccessed event when a file or directory is accessed.
FileOrDirectoryAttribChanged event when a file or directory attribute has changed Requires Linux kernel 5.1 or later (requires FID).
FileOrDirectoryCreated event when a file or directory has been created Requires Linux kernel 5.1 or later (requires FID).
FileOrDirectoryDeleted event when a file or directory has been deleted Requires Linux kernel 5.1 or later (requires FID).
FileOrDirectoryMovedFrom event when a file or directory has been moved from the watched directory Requires Linux kernel 5.1 or later (requires FID).
FileOrDirectoryMovedTo event when a file or directory has been moved to the watched directory Requires Linux kernel 5.1 or later (requires FID).
FileOrDirectoryOpened event when a file or directory is opened.
PermissionNone is used to indicate the listener is for notification events only.
PostContent is intended for event listeners that need to access files when they already contain their final content.
PreContent is intended for event listeners that need to access files before they contain their final data.
WatchedFileDeleted event when a watched file has been deleted Requires Linux kernel 5.1 or later (requires FID).
WatchedFileMoved event when a watched file has moved Requires Linux kernel 5.1 or later (requires FID).
WatchedFileOrDirectoryDeleted event when a watched file or directory has been deleted Requires Linux kernel 5.1 or later (requires FID).
WatchedFileOrDirectoryMoved event when a watched file or directory has moved Requires Linux kernel 5.1 or later (requires FID).

# Variables

ErrCapSysAdmin indicates caller is missing CAP_SYS_ADMIN permissions.
ErrInvalidFlagCombination indicates the bit/combination of flags are invalid.
ErrUnsupportedOnKernelVersion indicates the feature/flag is unavailable for the current kernel version.
ErrWatchPath indicates path needs to be specified for watching.

# Structs

Event represents a notification or a permission event from the kernel for the file, directory marked for watching.
Listener represents a generic notification group that holds a list of files, directories or a mountpoint for which notification or permission events shall be created.

# Type aliases

EventType represents an event / operation on a particular file/directory.
PermissionType represents value indicating when the permission event must be requested.