# progitoor

![logo.png](./doc/logo.png)

## Introduction

`progitoor` is an overlay filesystem that stores ownership and other file metadata in a text database and presents
that view to processes running as root, while the actual files are user-owned and can be versioned in git.

A typical use-case is building root filesystems. In this scenario:
- The backing store could be files in a user-owned git branch somewhere in `~/project/`
- `progitoor` would mount the backing store and present the overlay under a mount point (e.g., `~/mnt/`)
- Files are created or modified within a `sudo chroot ~/mnt` will have their ownership and mtime persisted in
  `~/project/.progitoor` (which is ideally also git versioned)

## Theory of operation

File I/O is passed through `progitoor` using the FUSE filesystem driver. A `BTreeMap` is used for lookups when
file metadata needs to be remapped. The map is persisted (flushed) to a text file (`.progitoor` in the underlay)
every 30 seconds, and also when `progitoor` exits (normally on un-mounting the filesystem).

Each change to the map is also written to a journal file for safety. The flush operation deletes
the journal. If the journal file exists at start-up (indicating a crash), it is replayed (merged into the database
and deleted). File deletions are journaled by writing a special (tombstone) entry with an all-zero file mode.

## Building and installing

To install the latest version of `progitoor`, ensure you have a [Rust toolchain installed](https://rustup.rs/), then run:

```console
cargo install progitoor
```

Or, to build from source (binary in `target/release/progitoor`):

```console
cargo build --release
```

## Usage

Unless the optional `--foreground` flag is used, `progitoor` will mount the filesystem and then fork into the background and
exit, with logging to syslog. In foreground mode logging is sent to stdout.

The usage is compatible with normal `mount -o options <device> <mount point>`, specifically:
```console
USAGE:
    progitoor [FLAGS] [OPTIONS] <SOURCE> <TARGET>

FLAGS:
    -f, --foreground    Don't fork - remain in foreground
    -h, --help          Prints help information
    -V, --version       Prints version information

OPTIONS:
    -l, --loglevel <LOGLEVEL>    Specifies the log level [default: Info]
    -o <MOUNT_OPT>...            Specifies the mount options

ARGS:
    <SOURCE>
    <TARGET>
```

Valid log levels for `--loglevel` are `Debug`, `Info`, `Warn` and `Error`.

## Example

Running progitoor (foreground mode):
```console
$ mkdir project
$ mkdir mnt
$ progitoor ./project/ ./mnt/ --foreground
Source dir: "/home/simeon/project"
Mount point: "/home/simeon/mnt"
Using fuse mount options: ["-o", "nonempty", "-o", "allow_root", "-o", "auto_unmount", "-o", "suid", "-o", "exec"]
Periodic flusher thread starting
Ready to mount...
Mounting /home/simeon/mnt
Periodic flusher thread running
```

In another terminal, create some files, look at them (as user):
```console
$ cd mnt
mnt$ mkdir etc
mnt$ echo "fake data" > etc/passwd
mnt$ ls -ld etc/
drwxrwxr-x 2 simeon simeon 4096 Oct  3 09:27 etc/
mnt$ ls -l etc/
total 4
-rw-rw-r-- 1 simeon simeon 10 Oct  3 09:28 passwd
```

As root, adjust ownership:
```shell
mnt$ sudo chown -R root: etc/
```

The user's view is unchanged:
```console
mnt$ ls -ld etc/
drwxrwxr-x 2 simeon simeon 4096 Oct  3 09:27 etc/
mnt$ ls -l etc/
total 4
-rw-rw-r-- 1 simeon simeon 10 Oct  3 09:28 passwd
```

Root sees the remapped ownership:
```console
mnt$ sudo ls -ld etc/
drwxrwxr-x 2 root root 4096 Oct  3 09:27 etc/
mnt$ sudo ls -l etc/
total 4
-rw-rw-r-- 1 root root 10 Oct  3 09:28 passwd
```

## License

`progitoor` is licensed under the General Public License 3.0. Please see `LICENSE` for details.