Skip to main content

Filesystem monitoring with Fuse and Python

Project description

Build Status: master / release Build Status: development branch Project License: Apache License v2 Project Development Status Available on PyPi - the Python Package Index Available on PyPi - the Python Package Index

LoggedFS-python repository

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

loggedfs-0.0.6.tar.gz (23.5 kB view hashes)

Uploaded Source

Built Distribution

loggedfs-0.0.6-py3-none-any.whl (27.7 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page