mfm/README.md

138 lines
4 KiB
Markdown
Raw Normal View History

2023-10-25 12:01:46 +00:00
<!--
# SPDX-License-Identifier: GPL-3.0-or-later
#
# SPDX-FileCopyrightText: 2023 Glenn Y. Rolland <glenux@glenux.net>
# Copyright © 2023 Glenn Y. Rolland <glenux@glenux.net>
-->
2023-10-25 12:46:06 +00:00
[![Build Status](https://cicd.apps.glenux.net/api/badges/glenux/mfm/status.svg)](https://cicd.apps.glenux.net/glenux/mfm)
2023-10-24 09:22:26 +00:00
# Minimalist Fuse Manager (MFM)
2023-10-20 09:33:12 +00:00
MFM is a Crystal-lang CLI designed to streamline the management of various FUSE filesystems, such as sshfs, gocryptfs, httpdirfs, and more. Through its user-friendly interface, users can effortlessly mount and unmount filesystems, get real-time filesystem status, and handle errors proficiently.
2023-10-20 09:33:12 +00:00
2023-10-24 09:22:26 +00:00
## Prerequisites & Dependencies
2023-10-20 09:33:12 +00:00
Before using MFM, make sure the following tools are installed on your system:
2023-10-20 09:33:12 +00:00
2023-10-24 09:22:26 +00:00
- **gocryptfs**: <https://github.com/rfjakob/gocryptfs>
- **sshfs**: <https://github.com/libfuse/sshfs>
- **httpdirfs**: <https://github.com/fangfufu/httpdirfs>
- **fzf**: <https://github.com/junegunn/fzf>
- libpcre3
- libevent-2.1
For Debian/Ubuntu you can use the following command:
```shell-session
$ sudo apt-get update && sudo apt-get install libpcre3 libevent-2.1-7 fzf gocryptfs httpdirfs sshfs
```
## Building from source
2023-10-20 09:33:12 +00:00
To build from source, you'll also need:
2023-10-24 09:22:26 +00:00
- **crystal-lang**: <https://crystal-lang.org/>
2023-10-24 09:22:26 +00:00
For Debian/Ubuntu you can use the following command:
```shell-session
$ sudo apt-get update && sudo apt-get install libpcre3-dev libevent-2.1-dev
```
2023-10-24 09:22:26 +00:00
## Installation
### 1. From Source
1. Clone or download the source code.
2. Navigate to the source directory.
3. Run `shards install` to fetch dependencies.
2023-10-24 09:22:26 +00:00
4. Compile using `shards build`.
5. The compiled binary will be in the `bin` directory.
2023-10-24 09:22:26 +00:00
### 2. Binary Download
Alternatively, download [a pre-compiled binary
version](https://code.apps.glenux.net/glenux/mfm/releases) of MFM.
2023-10-24 09:22:26 +00:00
## Usage
### Command Line Options
2023-10-20 09:33:12 +00:00
```
2023-10-24 09:22:26 +00:00
Usage: mfm [options]
2023-10-20 09:33:12 +00:00
2023-10-24 09:22:26 +00:00
Global options:
-c, --config FILE Specify configuration file
-h, --help Display this help
2023-10-20 09:33:12 +00:00
2023-10-25 14:34:24 +00:00
Commands (not implemented yet):
create Add a new filesystem
delete Remove an existing filesystem
edit Modify the configuration
2023-10-24 09:22:26 +00:00
```
2023-10-20 09:33:12 +00:00
### Demo
<video src="https://code.apps.glenux.net/glenux/mfm/media/branch/develop/doc/output.webm" width="810" height="595" style="max-width: 100%;" controls="controls"></video>
2023-10-20 09:33:12 +00:00
2023-10-24 09:22:26 +00:00
## Configuration
2023-10-20 09:33:12 +00:00
MFM uses a YAML configuration file, typically found at `~/.config/mfm.yml`, to
detail the filesystem names, types, and respective configurations.
2023-10-20 09:33:12 +00:00
2023-10-24 09:22:26 +00:00
### YAML File Format
2023-10-20 09:33:12 +00:00
```yaml
# NOT IMPLEMENTED YET
# version: "1"
# global:
# mountpoint: "/home/user/mnt/{{filesystem.name}}"
2023-10-24 09:22:26 +00:00
filesystems:
2023-10-24 09:22:26 +00:00
- type: "gocryptfs"
name: "Work - SSH Keys"
encrypted_path: "/home/user/.ssh/keyring.work.vault"
2023-10-24 09:22:26 +00:00
- type: "sshfs"
name: "Personal - Media Server"
remote_user: "{{env.USER}}"
2023-10-24 09:22:26 +00:00
remote_host: "mediaserver.local"
remote_path: "/mnt/largedisk/music"
remote_port: 22
2023-10-24 15:14:14 +00:00
- type: httpdirfs
name: "Debian Repository"
url: "http://ftp.debian.org/debian/"
# Add more filesystems as needed
2023-10-20 09:33:12 +00:00
```
2023-10-24 09:22:26 +00:00
## Contribution Guidelines
Contributing to MFM:
2023-10-24 09:22:26 +00:00
1. **Fork the Repository**: Start by forking MFM's repository.
2. **Create a Feature Branch**: Develop each feature or fix in its own branch.
3. **Commit Changes**: Provide clear and informative commit messages.
4. **Run Tests**: Ensure that all features are operational.
5. **Push to Your Fork**: Push your changes to your fork on GitHub.
6. **Submit a Pull Request**: Begin a pull request to the main repository and explain your changes.
7. **Review**: Await feedback from the maintainers and respond as necessary.
2023-10-24 09:22:26 +00:00
2023-10-25 14:38:20 +00:00
By contributing, you agree to our code of conduct and license terms.
2023-10-24 09:22:26 +00:00
## Authors and Contributors
2023-10-20 09:33:12 +00:00
2023-10-24 09:22:26 +00:00
- Glenn Y. Rolland - *Initial Work*
2023-10-20 09:33:12 +00:00
2023-10-24 09:22:26 +00:00
## Inspired By
2023-10-20 09:33:12 +00:00
- **Qasim**: A user-friendly FUSE manager. <https://code.apps.glenux.net/glenux/qasim>
- **Sirikali**: A Qt/C++ GUI front-end for various FUSE filesystems like cryfs, gocryptfs, securefs, ecryptfs, and encfs. <https://mhogomchungu.github.io/sirikali/>
2023-10-20 09:33:12 +00:00
## License
2023-10-25 12:01:46 +00:00
GNU GPL-3