Synopsis

LoggedFS-python is a FUSE-based filesystem which can log every operation that happens in it. It is a pure Python re-implementation of LoggedFS by Rémi Flament maintaining CLI compatibility. The project is heavily inspired by Stavros Korokithakis' 2013 blog post entitled "Writing a FUSE filesystem in Python" (source code repository). The filesystem is fully POSIX compliant, passing the pjdfstest test-suite, a descendant of FreeBSD's fstest. It furthermore passes stress tests with fsx-linux based on the fsx-flavor released by the Linux Test Project. It is intended to be suitable for production systems.

CAVEATS

PROJECT STATUS: BETA
THE FILESYSTEM IS CURRENTLY ONLY BEING DEVELOPED FOR AND TESTED ON LINUX. ANYONE INTERESTED IN CONFIRMING MAC OS X AND/OR ADDING BSD SUPPORT?

Installation

From the Python Package Index (PyPI):

pip install loggedfs

From GitHub:

pip install git+https://github.com/pleiszenburg/loggedfs-python.git@master

Supports Python 3.{5,6,7,8}.

Supports Linux. Support for MAC OS X and BSD is implemented but has yet not been tested.

Simple usage example

To start recording access to /tmp/TEST into /root/log.txt, just do:

sudo loggedfs -p -s -l /root/log.txt /tmp/TEST

To stop recording, just unmount as usual:

sudo fusermount -u /tmp/TEST

CLI usage

loggedfs --help
Usage: loggedfs [OPTIONS] DIRECTORY

Options:
  -f                            Do not start as a daemon. Write logs to stdout
                                if no log file is specified.

  -p                            Allow every user to see the new loggedfs.
  -c FILENAME                   Use the "config-file" to filter what you want
                                to log.

  -s                            Deactivate logging to syslog.
  -l FILE                       Use the "log-file" to write logs to.
  -j, --json                    Format output as JSON instead of traditional
                                loggedfs format.

  -b, --buffers                 Include read/write-buffers (compressed,
                                BASE64) in log.

  -m, --only-modify-operations  Exclude logging of all operations that can not
                                cause changes in the filesystem. Convenience
                                flag for accelerated logging.

  --help                        Show this message and exit.

Configuration

LoggedFS-python can use an XML configuration file if you want it to log operations only for certain files, for certain users, or for certain operations. LoggedFS-python is fully compatible with configuration files in LoggedFS' original format. Yet it can also handle additional fields (e.g. the command field).

Here is a sample configuration file :

<?xml version="1.0" encoding="UTF-8"?>

<loggedFS logEnabled="true" printProcessName="true">
    <includes>
        <include extension=".*" uid="*" action=".*" retname=".*" command=".*"/>
    </includes>
    <excludes>
        <exclude extension=".*\.bak$" uid="*" action=".*" retname="SUCCESS" command=".*"/>
        <exclude extension=".*" uid="1000" action=".*" retname="FAILURE" command=".*"/>
        <exclude extension=".*" uid="*" action="getattr" retname=".*" command=".*"/>
    </excludes>
</loggedFS>

This configuration can be used to log everything except if it concerns a *.bak file, or if the uid is 1000, or if the operation is getattr.

Need help?

Feel free to post questions in the GitHub issue tracker of this project.

Bugs & issues

Please report bugs in LoggedFS-python here in its GitHub issue tracker.

Miscellaneous

Library documentation: LoggedFS-python Jupyter Notebook
License (Apache License 2.0)
Contributing (Contributions are highly welcomed!)
Authors
Changes
Long-term ideas
Upstream issues (relevant bugs in dependencies)

pleiszenburg / loggedfs-python