README
¶
Fanotify Library
Fanotify library for Go provides a simple API to monitor filesystem for specific events. The library attempts to simplify specifying events/actions to the watcher by providing valid flag combinations. The flag features are validated against the user's kernel version.
Many of the useful features provided by fanotify are available from Linux kernel 5.1 onwards. Most of the useful features availabe through this library work best on kernels 5.1 or later.
Example: Listener watching for file/directory accessed events
package main
import (
"flag"
"fmt"
"os"
"github.com/opcoder0/fanotify"
)
func main() {
var listenPath string
flag.StringVar(&listenPath, "listen-path", "", "path to watch events")
flag.Parse()
if listenPath == "" {
fmt.Println("missing listen path")
os.Exit(1)
}
mountPoint := "/"
listener, err := fanotify.NewListener(mountPoint, 4096, true)
if err != nil {
fmt.Println(err)
os.Exit(1)
}
fmt.Println("Listening to events for:", listenPath)
listener.AddWatch(listenPath, fanotify.FileOrDirectoryAccessed)
go listener.Start()
i := 1
for event := range listener.Events {
fmt.Println(event)
if i == 5 {
fmt.Println("Enough events. Stopping...")
listener.Stop()
break
}
i++
}
}
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrCapSysAdmin indicates caller is missing CAP_SYS_ADMIN permissions ErrCapSysAdmin = errors.New("require CAP_SYS_ADMIN capability") // ErrInvalidFlagCombination indicates the bit/combination of flags are invalid ErrInvalidFlagCombination = errors.New("invalid flag bits") // ErrNilListener indicates the listener is nil ErrNilListener = errors.New("nil listener") // ErrUnsupportedOnKernelVersion indicates the feature/flag is unavailable for the current kernel version ErrUnsupportedOnKernelVersion = errors.New("feature unsupported on current kernel version") )
Functions ¶
This section is empty.
Types ¶
type Action ¶
type Action uint64
Action represents an event / operation on a particular file/directory
const ( // FileAccessed event when a file is accessed FileAccessed Action = unix.FAN_ACCESS // FileOrDirectoryAccessed event when a file or directory is accessed FileOrDirectoryAccessed Action = unix.FAN_ACCESS | unix.FAN_ONDIR // FileModified event when a file is modified FileModified Action = unix.FAN_MODIFY // FileClosed event when a file is closed FileClosed Action = unix.FAN_CLOSE_WRITE | unix.FAN_CLOSE_NOWRITE // FileOpened event when a file is opened FileOpened Action = unix.FAN_OPEN // FileOrDirectoryOpened event when a file or directory is opened FileOrDirectoryOpened Action = unix.FAN_OPEN | unix.FAN_ONDIR // FileOpenedForExec event when a file is opened with the intent to be executed. // Requires Linux kernel 5.0 or later FileOpenedForExec Action = unix.FAN_OPEN_EXEC // FileAttribChanged event when a file attribute has changed // Requires Linux kernel 5.1 or later (requires FID) FileAttribChanged Action = unix.FAN_ATTRIB // FileOrDirAttribChanged event when a file or directory attribute has changed // Requires Linux kernel 5.1 or later (requires FID) FileOrDirAttribChanged Action = unix.FAN_ATTRIB | unix.FAN_ONDIR // FileCreated event when file a has been created // Requires Linux kernel 5.1 or later (requires FID) FileCreated Action = unix.FAN_CREATE // FileOrDirCreated event when a file or directory has been created // Requires Linux kernel 5.1 or later (requires FID) FileOrDirCreated Action = unix.FAN_CREATE | unix.FAN_ONDIR // FileDeleted event when file a has been deleted // Requires Linux kernel 5.1 or later (requires FID) FileDeleted Action = unix.FAN_DELETE // FileOrDirDeleted event when a file or directory has been deleted // Requires Linux kernel 5.1 or later (requires FID) FileOrDirDeleted Action = unix.FAN_DELETE | unix.FAN_ONDIR // WatchedFileDeleted event when a watched file has been deleted // Requires Linux kernel 5.1 or later (requires FID) WatchedFileDeleted Action = unix.FAN_DELETE_SELF // WatchedFileOrDirDeleted event when a watched file or directory has been deleted // Requires Linux kernel 5.1 or later (requires FID) WatchedFileOrDirDeleted Action = unix.FAN_DELETE_SELF | unix.FAN_ONDIR // FileMovedFrom event when a file has been moved from the watched directory // Requires Linux kernel 5.1 or later (requires FID) FileMovedFrom Action = unix.FAN_MOVED_FROM // FileOrDirMovedFrom event when a file or directory has been moved from the watched directory // Requires Linux kernel 5.1 or later (requires FID) FileOrDirMovedFrom Action = unix.FAN_MOVED_FROM | unix.FAN_ONDIR // FileMovedTo event when a file has been moved to the watched directory // Requires Linux kernel 5.1 or later (requires FID) FileMovedTo Action = unix.FAN_MOVED_TO // FileOrDirMovedTo event when a file or directory has been moved to the watched directory // Requires Linux kernel 5.1 or later (requires FID) FileOrDirMovedTo Action = unix.FAN_MOVED_TO | unix.FAN_ONDIR // WatchedFileMoved event when a watched file has moved // Requires Linux kernel 5.1 or later (requires FID) WatchedFileMoved Action = unix.FAN_MOVE_SELF // WatchedFileOrDirMoved event when a watched file or directory has moved // Requires Linux kernel 5.1 or later (requires FID) WatchedFileOrDirMoved Action = unix.FAN_MOVE_SELF | unix.FAN_ONDIR )
type Event ¶
type Event struct {
// Fd is the open file descriptor for the file/directory being watched
Fd int
// Path holds the name of the parent directory
Path string
// FileName holds the name of the file under the watched parent. The value is only available
// when NewListener is created by passing `true` with `withName` argument. The feature is available
// only with kernels 5.9 or higher.
FileName string
// Mask holds bit mask representing the operation
Mask Action
// Pid Process ID of the process that caused the event
Pid int32
}
Event represents a notification from the kernel for the file, directory or a filesystem marked for watching.
type Listener ¶
type Listener struct {
// Events a buffered channel holding fanotify notifications for the watched file/directory.
Events chan Event
// contains filtered or unexported fields
}
Listener represents a fanotify notification group that holds a list of files, directories and filesystems under a given mountpoint for which events shall be created.
func NewListener ¶
NewListener returns a fanotify listener from which events can be read. Each listener supports listening to events under a single mount point.
For cases where multiple mountpoints need to be monitored multiple listener instances need to be used.
`mountpointPath` can be any file/directory under the mount point being watched. `maxEvents` defines the length of the buffered channel which holds the notifications. The minimum length is 4096. `withName` setting this to true populates the file name under the watched parent.
NOTE that this call requires CAP_SYS_ADMIN privilege
func (*Listener) ClearWatch ¶
ClearWatch stops watching for all actions
func (*Listener) DeleteWatch ¶
DeleteWatch stops watching the parent directory for the specified action
func (*Listener) Start ¶
func (l *Listener) Start()
Start starts the listener and polls the fanotify event notification group for marked events. The events are pushed into the Listener's `Events` buffered channel. The function panics if there nothing to watch.
func (*Listener) Stop ¶
func (l *Listener) Stop()
Stop stops the listener and closes the notification group and the events channel
func (*Listener) WatchMountPoint ¶
WatchMountPoint watches the entire mount point for specified actions
Source Files