An Andrew File System (AFS)-inspired, high-performance distributed virtual file system implemented in Go, communicating over gRPC, and secured with Zero-Trust mutual TLS. Designed for collaborative environments across Raspberry Pi clusters, Linux workstations, and cloud servers.
Complete Documentation Portal: dvfs-iit-gandhinagar.github.io/Distributed-Virtual-File-System
For in-depth architecture flows, formal security models, multi-node deployment runbooks, and the full 19-command CLI manual, visit our hosted documentation portal or explore the localdocs/directory.
+-----------------------------------+
| MetaServer (Coordinator) |
| - Dynamic Root Discovery (MDS) |
| - Heartbeat & Liveness Tracker |
| - State: MongoDB (dvfs database) |
+-----------------+-----------------+
^
Registration & | Advisory
Heartbeats | Routing
|
+-------------------------+-------------------------+
| |
v v
+-------------------------+ +-------------------------+
| FileServer Node 1 | | FileServer Node 2 |
| - Authoritative Storage | | - Authoritative Storage |
| - InodeStore (.dvfs...) | | - InodeStore (.dvfs...) |
| - Per-Directory .acl | | - Per-Directory .acl |
| - Streaming I/O (4 MB) | | - Streaming I/O (4 MB) |
| - Metrics HTTP (:9052) | | - Metrics HTTP (:9053) |
+------------+------------+ +------------+------------+
^ ^
| Push Invalidation |
| Callbacks |
| |
+--------------------------+------------------------+
|
+----------+----------+
| DVFS Client |
| - Interactive REPL |
| - Local CNode Cache |
| - Embedded Root CA |
| - Dynamic Gist SNI |
+---------------------+
- Multi-Root Virtual Namespace: Users interact with a private home root (
mydrive) and cluster-shared roots ([owner]: [folder]) presented via an interactive root menu (GetRoots). Navigatingcd ..from the top level of any root returns cleanly to root selection. - Whole-File Caching & Push Callbacks: AFS-style local UUID caching with zero-network reads on cache hits. Authoritative FileServers push gRPC
Invalidatecallbacks directly to connected clients upon file modification or deletion. - Authoritative Storage & Advisory Indexing: FileServers manage physical disk I/O, enforce ACLs, allocate logical Inode IDs, and execute atomic operations. The MetaServer coordinates cluster routing and indexes shared directories.
- Zero-Trust PKI & Dynamic Discovery: Inter-node communication is strictly encrypted with mutual TLS 1.3 using an air-gapped Root CA. Node certificates use DNS SANs (
dvfs1–dvfs9), decoupling TLS verification from dynamic campus DHCP IP addresses via Tailscale and GitHub Gist. - Soft Deletion Recycle Bin:
trashmoves files and directories into a hidden.trash/container with automatic collision suffixing (file__<inodeID>).restorereinstates files to their original parent (falling back to user root if the parent was deleted). - Dynamic Multi-Tenant Quotas: Per-user storage quotas with dynamic adjustment via
SetQuotagRPC and Admin Web Console, integer overflow protection, and mid-stream chunk scrapping with automatic storage rollback. - Integrated Observability & Remote Orchestration: FileServers expose
/metricsHTTP sidecars with streaming throughput, IOPS, and latency percentiles (p50/p95/p99). A centralized React web console monitors cluster health, triggers state-machine alerts, and executes remote SSH batch commands (systemctl,journalctl,apt,reboot).
- Go: 1.26+ installed
- Make & OpenSSL
- MongoDB: 7+ reachable by the MetaServer and Admin Console (locally:
docker run -d -p 27017:27017 mongo:7; seedocs/setup.md§3 for a production setup with auth)
# Clone the repository
git clone https://github.com/DVFS-IIT-Gandhinagar/Distributed-Virtual-File-System.git
cd Distributed-Virtual-File-System
# Generate development certificates
make certs
# Build all binaries into ./bin/
make build# Terminal 1: Start MetaServer Coordinator
./bin/metaserver -port=50051 -mongo_uri=mongodb://127.0.0.1:27017/dvfs
# Terminal 2: Start Storage FileServer
./bin/fileserver -id=fs1 -port=50052 -data=./fileserver_data -meta_addr=127.0.0.1:50051 -own_ip=127.0.0.1
# Terminal 3: Start Admin Web Console (Optional)
./bin/admin -port=8080 -mongo_uri=mongodb://127.0.0.1:27017/dvfs -static=./cmd/admin/static
# Terminal 4: Launch Interactive Client Shell
./bin/client -username=alice -ip_addr=127.0.0.1 -port=50051 -meta=trueInside the client REPL, type help to list all available commands (ls, cd, pwd, create, mkdir, read, upload, download, trash, restore, show_trash, clear_trash, delete, sharewith, unsharewith, viscache, refresh, info, clear, exit).
The complete documentation is organized into modular guides:
| Document | Description |
|---|---|
| Portal Home | Executive overview, design principles, and system topology. |
| Setup & Deployment Guide | Complete multi-node cluster deployment runbook for Raspberry Pis, Linux servers, systemd daemons, and development hosts. |
| System & Hosting Architecture | Inode data structures, FID identity, AFS workflows, 18 architectural design decisions, and IITGN campus workarounds (Fortinet, Gist, SANs). |
| Client CLI Reference | Full syntax, flags, examples, and behavior for all 20 terminal shell commands. |
| Client Caching & Push Callbacks | In-memory CNode tree, UUID cache files, push invalidations, 45s session TTL, and readline prompt protection. |
| Sharing & Access Control Lists | Authoritative ACL propagation (DFS), RootShare protocol, and formal security invariants. |
| Crash Recovery & Inode Persistence | Persistent InodeStore (.dvfs_inodes_index.json), MetaServer state snapshots, heartbeat isolation, and 4-terminal runbooks. |
| Recycle Bin & Trash Subsystem | Two-tier deletion safety, collision-safe renaming, metadata fallback, and 9-case test runbook. |
| Dynamic Storage Quotas | Per-user quota enforcement, SetQuota gRPC protocol, and mid-stream chunk scrapping. |
| Zero-Trust TLS & PKI | Offline Root CA ceremony, DNS SAN leaf certificates, and dynamic SNI resolution. |
| Telemetry & Performance Monitoring | HTTP metrics sidecars, real-time chunked throughput, latency percentiles, and CSV exports. |
| Remote Cluster Orchestration | Remote SSH execution, live journalctl streaming, deduplicated alerts, and command history. |
| Authentication & Access Control | SHA-256 password verification, constant-time checks, and cookie-authenticated WebSockets. |
| Project Artifacts & Poster | Academic presentation poster (Poster.pdf) and research findings summary. |
.
├── api/ # Protocol Buffer definitions and generated gRPC stubs
│ ├── fileserver/ # FileServer service & streaming RPCs
│ ├── metaserver/ # MetaServer routing & advisory RPCs
│ └── callback/ # Client push invalidation callback RPCs
├── cmd/ # Application entry points
│ ├── client/ # Interactive Cobra CLI REPL & cache engine
│ ├── fileserver/ # Authoritative storage daemon & metrics sidecar
│ ├── metaserver/ # Coordinator & liveness tracking daemon
│ └── admin/ # Centralized admin console server & React SPA
├── internal/ # Core business logic and shared domain packages
│ ├── client/ # CNode tree, cache handler, callback listener
│ ├── fileserver/ # InodeStore, ACL enforcement, chunk streaming, trash
│ ├── metaserver/ # Advisory index, state snapshotting, heartbeat monitor
│ ├── admin/ # Telemetry poller, alert engine, SSH orchestrator
│ └── domain/ # FID, Inode, and ACL domain types
├── docs/ # Full documentation source (Material for MkDocs)
├── scripts/ # Automation, systemd unit files, PKI, and campus workarounds
├── Makefile # Standard build, test, cert generation, and execution targets
└── mkdocs.yml # Documentation portal configuration
Run the automated test suite across all modules:
go test ./...Run test suite with race detection:
go test -race ./...