loggedfs 0.0.4

Filesystem monitoring with Fuse and Python

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

• A CUSTOM BUG-FIXED VERSION OF FUSEPY IS REQUIRED FOR FULL POSIX COMPLIANCE. IT IS AUTOMATICALLY INSTALLED FROM GITHUB AS A DEPENDENCY OF THIS PACKAGE. IF THE LATEST OFFICIAL RELEASE OF FUSEPY IS USED INSTEAD, TIMESTAMPS WILL BE INACCURATE ON A NANOSECOND TO MICROSECOND SCALE AND UTIME_NOW AS WELL AS UTIME_OMIT WILL NOT BE HONORED. THERE WAS A PULL REQUEST TO FIX THIS, WHICH HAS BEEN REJECTED. ALTERNATIVE APPROACHES ARE BEING RESEARCHED.

• 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.{4,5,6,7}.

Supports Linux. Support for MAC OS X 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

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

• Full project documentation

  • at Read the Docs

  • at LoggedFS-python repository

• License (Apache License 2.0)

• Contributing (Contributions are highly welcomed!)

• FAQ

• Authors

• Changes

• Long-term ideas

• Upstream issues (relevant bugs in dependencies)