Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/pleiszenburg/loggedfs-python

Filesystem monitoring with Fuse and Python
https://github.com/pleiszenburg/loggedfs-python

filesystem filesystem-logging filesystemwatcher fuse fuse-filesystem logging monitoring

Last synced: 2 months ago
JSON representation

Filesystem monitoring with Fuse and Python

Host: GitHub
URL: https://github.com/pleiszenburg/loggedfs-python
Owner: pleiszenburg
License: apache-2.0
Created: 2017-12-09T13:07:44.000Z (about 7 years ago)
Default Branch: master
Last Pushed: 2023-03-31T02:14:20.000Z (almost 2 years ago)
Last Synced: 2024-11-13T00:53:03.590Z (3 months ago)
Topics: filesystem, filesystem-logging, filesystemwatcher, fuse, fuse-filesystem, logging, monitoring
Language: Python
Size: 801 KB
Stars: 29
Watchers: 3
Forks: 5
Open Issues: 2
Metadata Files:
- Readme: README.rst
- Changelog: CHANGES.rst
- Contributing: CONTRIBUTING.rst
- License: LICENSE

Awesome Lists containing this project

README

.. |build_master| image:: https://img.shields.io/travis/pleiszenburg/loggedfs-python/master.svg?style=flat-square
:target: https://travis-ci.org/pleiszenburg/loggedfs-python
:alt: Build Status: master / release

.. |build_develop| image:: https://img.shields.io/travis/pleiszenburg/loggedfs-python/develop.svg?style=flat-square
:target: https://travis-ci.org/pleiszenburg/loggedfs-python
:alt: Build Status: development branch

.. |license| image:: https://img.shields.io/pypi/l/loggedfs.svg?style=flat-square
:target: https://github.com/pleiszenburg/loggedfs/blob/master/LICENSE
:alt: Project License: Apache License v2

.. |status| image:: https://img.shields.io/pypi/status/loggedfs.svg?style=flat-square
:target: https://github.com/pleiszenburg/loggedfs-python/milestone/1
:alt: Project Development Status

.. |pypi_version| image:: https://img.shields.io/pypi/v/loggedfs.svg?style=flat-square
:target: https://pypi.python.org/pypi/loggedfs
:alt: Available on PyPi - the Python Package Index

.. |pypi_versions| image:: https://img.shields.io/pypi/pyversions/loggedfs.svg?style=flat-square
:target: https://pypi.python.org/pypi/loggedfs
:alt: Available on PyPi - the Python Package Index

.. |loggedfs_python_logo| image:: http://www.pleiszenburg.de/loggedfs-python_logo.png
:target: https://github.com/pleiszenburg/loggedfs-python
:alt: LoggedFS-python repository

|loggedfs_python_logo|

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.

.. _LoggedFS: https://github.com/rflament/loggedfs
.. _Rémi Flament: https://github.com/rflament
.. _Stavros Korokithakis: https://github.com/skorokithakis
.. _Writing a FUSE filesystem in Python: https://www.stavros.io/posts/python-fuse-filesystem/
.. _source code repository: https://github.com/skorokithakis/python-fuse-sample
.. _POSIX: https://en.wikipedia.org/wiki/POSIX
.. _pjdfstest test-suite: https://github.com/pjd/pjdfstest
.. _fstest: https://github.com/zfsonlinux/fstest
.. _fsx-flavor: http://codemonkey.org.uk/projects/fsx/
.. _Linux Test Project: https://github.com/linux-test-project/ltp

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):

.. code:: bash

pip install loggedfs

From GitHub:

.. code:: bash

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.

.. _Python Package Index: https://pypi.org/

Simple usage example
====================

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

.. code:: bash

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

To stop recording, just unmount as usual:

.. code:: bash

sudo fusermount -u /tmp/TEST

CLI usage
=========

.. code:: bash

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 :

.. code:: xml

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.

.. _GitHub issue tracker: https://github.com/pleiszenburg/loggedfs-python/issues

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)

.. _LoggedFS-python Jupyter Notebook: https://github.com/pleiszenburg/loggedfs-python/blob/master/docs/library_demo.ipynb
.. _License: https://github.com/pleiszenburg/loggedfs-python/blob/master/LICENSE
.. _Contributing: https://github.com/pleiszenburg/loggedfs-python/blob/master/CONTRIBUTING.rst
.. _Authors: https://github.com/pleiszenburg/loggedfs-python/blob/master/AUTHORS.rst
.. _Changes: https://github.com/pleiszenburg/loggedfs-python/blob/master/CHANGES.rst
.. _Long-term ideas: https://github.com/pleiszenburg/loggedfs-python/milestone/2
.. _Upstream issues: https://github.com/pleiszenburg/loggedfs-python/issues?q=is%3Aissue+is%3Aopen+label%3Aupstream