fofimon Manual page
Index
NAME
fofimon - Monitor selected folders and files for modifications.SYNOPSIS
- fofimon [OPTION]
OPTIONS
-v --version Prints version.
-h --help Prints this message.
--dont-watch Doesn't start watching.
-f --add-file FILEPATH Adds file FILEPATH to watch (unaffected by zone filters).
-z --add-zone DIRPATH Adds a watched zone with base directory DIRPATH.
ZONE OPTIONS (must follow --add-zone):
-m --max-depth DEPTH Sets the max depth of a zone. Examples of DEPTH:
0: just watches the base path of the zone (default).
1: watches base path and its direct subdirectories.
N: watches base path and N levels of subdirectories.
-1: watches all the directories in the subtree.
--pinned-file NAME File name that can't be excluded by the zone's filters.
--pinned-dir NAME Directory name that can't be excluded by the zone's filters.
--include-files REGEX Includes file name filter REGEX (POSIX).
--include-dirs REGEX Includes dir name filter REGEX (POSIX).
--exclude-files REGEX Excludes file name filter REGEX (POSIX). Overrides includes.
--exclude-dirs REGEX Excludes dir name filter REGEX (POSIX). Overrides includes.
--exclude-file NAME Excludes file name. Overrides includes.
--exclude-dir NAME Excludes dir name. Overrides includes.
--exclude-all Excludes all dir and file names. Overrides includes.
Same as defining regular expression filters ".*".
OUTPUT OPTIONS (if OUT ends with '.json', json output is used):
--print-zones [OUT] Prints directory zones (to OUT file if given).
--print-watched [OUT] Prints initial to be watched directories (to OUT file if given).
-l --live-events [OUTL] Prints single events as they happen
(to OUTL file if given, no json).
-o --print-modified [OUT] Prints watched modifications after Control-D is pressed
(to OUT file if given).
--skip-temporary Don't show temporary files in watched modifications.
--show-detail Show more info (-l and -o outputs).
DESCRIPTION
This a command line tool based on inotify that watches directories, tracking the creation, removal, modification and renaming of files and (sub)directories.
Motivation
It might be useful if:
- You want to know all the files that are created when installing an
application or its plugins and extensions.
- You don't trust an application and want to know what files it modifies.
- You want to know where an application stores configuration files,
to then copy them when migrating to a new computer or hopping to a
new Linux distribution.
Usage
To determine which directories (and their content) should be watched, you have to define directory zones. A directory zone is defined with a base path, the maximum depth (depth 0 meaning only the files in the base path) and optionally inclusion and exclusion filters. All the directories that exist when fofimon is started or are created at runtime within the zone are watched.
Note 1: fofimon doesn't follow symbolic links. Symbolic links to a directory are considered just files.
Note 2: the base path of a directory zone mustn't necessarily exist when fofimon is started.
Note 3: a directory zone the base path of which is within another directory zone shadows the ancestor.
Beside directory zones, fofimon also allows one to watch single files.
Before you run fofimon it is better to increase the maximum number of inotify watches (default is just 8192), especially if you want to watch most of the file system:
$ sudo sh -c 'echo 128000 >/proc/sys/fs/inotify/max_user_watches'
If it runs out of inotify watches, fofimon stops. It's therefore important to set the number to a high enough value. To that end you can use fofimon itself (preferably using sudo)
$ fofimon -z / -m -1 --dont-watch
which returns the current number of watchable directories in your system.
Usage examples
To watch the changes in your home directory to a depth of 4
(subdirectories):
$ fofimon \
-z ~/ -m 4 \
-l /tmp/fofi-actions.txt \
-o /tmp/fofi-results.txt \
--print-watched /tmp/fofi-watched.txt
To watch the changes in the whole file system except the Trash:
$ sudo fofimon \
-z / -m -1 \
-z ~/.local/share/Trash --exclude-all \
-l \
-o /tmp/fofi-results.txt
Output codes
Events (-l output): State (-o output):
c: create C: created
d: delete D: deleted
m: modify M: modified
a: attribute change T: temporary
f: rename from ?: inconsistent
t: rename to
Limitations
Because of the limitations of the inotify API, which is inode based, fofimon can only make a best effort to detect the changed files.
For instance, when a directory containing millions of files is renamed, the file system just assigns a new path to the directory inode, a simple operation that might last a few milliseconds. For fofimon, on the other hand, it means a lot of work. For each file and subdirectory in the renamed directory tree, it creates two entries, one for the source and one for the destination path. This can cause the loss of inotify events and consequently create inconsistencies in the reported results. In this kind of scenario it might be better to use inotifywait, which is available in most Linux distributions.
In particular circumstances fofimon might also fail to detect temporary files if renaming is done from or to an unwatched directory.
AUTHOR
Written by Stefano Marsili <efanomars@gmx.ch>.
LICENSE
Copyright © 2018-2020 Stefano Marsili.
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
Index
This document was created by man2html, using the manual pages.