furumi-ng/README.md

Furumi-ng

Remote filesystem over encrypted gRPC. Mount a directory from a remote server as a local folder via FUSE.

Designed for streaming media (video, music) over the network.

Architecture

furumi-server (gRPC + TLS)  ←→  furumi-client-core  ←→  furumi-mount-linux (FUSE)

• furumi-server — exposes a directory over gRPC with auto-TLS, Bearer token auth, and Prometheus metrics
• furumi-client-core — cross-platform gRPC client library with attribute caching
• furumi-mount-linux — mounts the remote directory locally via FUSE (read-only)

Quick Start

# Build
cargo build --release --workspace

# Server — auto-generates TLS certificate, saves it for client
./target/release/furumi-server \
  --root /path/to/media \
  --token mysecrettoken \
  --tls-cert-out /tmp/furumi-ca.pem

# Client — loads the server's certificate for encrypted connection
./target/release/furumi-mount-linux \
  --server https://server-ip:50051 \
  --token mysecrettoken \
  --tls-ca /tmp/furumi-ca.pem \
  --mount /mnt/remote

# Use it
ls /mnt/remote
mpv /mnt/remote/video.mkv

Encryption

TLS is enabled by default. The server auto-generates a self-signed certificate on each start — no manual cert management required. The certificate is used only for encryption, not for server identity verification.

To pass the certificate to the client:

1. Server: --tls-cert-out /path/to/cert.pem saves the generated cert
2. Client: --tls-ca /path/to/cert.pem loads it for the TLS handshake

To disable TLS (not recommended): --no-tls on the server, and use http:// on the client.

Configuration

All options can be set via CLI flags or environment variables.

Server

Flag	Env	Default	Description
--bind	FURUMI_BIND	0.0.0.0:50051	gRPC listen address
--root	FURUMI_ROOT	.	Directory to expose
--token	FURUMI_TOKEN	(empty, auth off)	Bearer token
--metrics-bind	FURUMI_METRICS_BIND	0.0.0.0:9090	Prometheus endpoint
--tls-cert-out	FURUMI_TLS_CERT_OUT	—	Save auto-generated cert PEM
--no-tls	—	false	Disable TLS

Client

Flag	Env	Default	Description
--server	FURUMI_SERVER	https://0.0.0.0:50051	Server address
--token	FURUMI_TOKEN	(empty)	Bearer token
--mount	FURUMI_MOUNT	—	Mount point directory
--tls-ca	FURUMI_TLS_CA	—	Server CA cert PEM file

Prometheus Metrics

Available at http://<metrics-bind>/metrics:

• furumi_grpc_requests_total — request count by method and status
• furumi_grpc_request_duration_seconds — request latency histogram
• furumi_bytes_read_total — total bytes streamed
• furumi_active_streams — current streaming connections
• furumi_file_open_errors_total — file access errors
• furumi_auth_failures_total — authentication failures

Requirements

• Linux with libfuse3-dev and pkg-config (for client)
• Rust 2024 edition

License

MIT