FernFS

A complete NFSv3 server implementation in Rust that allows you to export any custom file system over the network.

Features

Complete NFSv3 Protocol: Full implementation of all 21 procedures defined in RFC 1813
MOUNT Protocol: Support for filesystem exports and mount operations
PORTMAP Protocol: Service discovery support for compatibility
Async/Await: Built on Tokio for high-performance asynchronous I/O
Virtual File System: Clean abstraction layer for implementing custom backends
Cross-Platform: Works on Linux, macOS, and Windows
Standards Compliant: Follows RFC 1813 (NFSv3), RFC 5531 (RPC), and RFC 1832 (XDR)

Quick Start

Add this to your Cargo.toml:

[dependencies]
fernfs = "0.0.0"
tokio = { version = "1.0", features = ["full"] }

Examples

Running the Demo File System

The demo example creates an in-memory file system with some sample files:

cargo run --example demofs

Then mount it:

Linux:

mkdir /mnt/nfs
sudo mount -o proto=tcp,port=11111,mountport=11111,nolock,addr=127.0.0.1 127.0.0.1:/ /mnt/nfs

macOS:

mkdir /mnt/nfs
sudo mount_nfs -o nolocks,vers=3,tcp,rsize=131072,port=11111,mountport=11111 localhost:/ /mnt/nfs

Windows (Pro/Enterprise):

mount.exe -o anon,nolock,mtype=soft,fileaccess=6,casesensitive,lang=ansi,rsize=128,wsize=128,timeout=60,retry=2 \\127.0.0.1\\ X:

Mirror File System

The mirror example exports an existing directory over NFS:

cargo run --example mirrorfs /path/to/directory

Creating Your Own NFS Server

To create a custom NFS server, implement the NFSFileSystem trait:

use fernfs::{tcp::NFSTcpListener, vfs::NFSFileSystem};
use async_trait::async_trait;

struct MyFileSystem {
    // Your file system state
}

#[async_trait]
impl NFSFileSystem for MyFileSystem {
    fn capabilities(&self) -> fernfs::vfs::Capabilities {
        fernfs::vfs::Capabilities::ReadWrite
    }

    fn root_dir(&self) -> u64 {
        1 // Root directory file ID
    }

    async fn lookup(&self, dirid: u64, filename: &[u8]) -> Result<u64, fernfs::nfs::nfsstat3> {
        // Implement file lookup logic
        todo!()
    }

    async fn getattr(&self, id: u64) -> Result<fernfs::nfs::fattr3, fernfs::nfs::nfsstat3> {
        // Return file attributes
        todo!()
    }

    // Implement other required methods...
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let fs = MyFileSystem::new();
    let listener = NFSTcpListener::bind("127.0.0.1:11111", fs).await?;
    listener.handle_forever().await?;
    Ok(())
}

Architecture

The library is structured into several key components:

vfs: Virtual File System trait that you implement for your storage backend
tcp: TCP server that handles client connections and protocol dispatch
protocol: Internal implementation of NFS, MOUNT, and PORTMAP protocols
xdr: XDR (External Data Representation) encoding/decoding

File System Interface

The NFSFileSystem trait provides a clean abstraction with these key concepts:

File IDs: Every file/directory has a unique 64-bit identifier (like an inode number)
File Handles: Opaque handles that include generation numbers for stale handle detection
Stateless Operations: All operations are stateless and use file IDs for addressing
Async Support: All operations are async for high performance

Key Methods

lookup(): Resolve filename to file ID within a directory
getattr()/setattr(): Get/set file attributes
read()/write(): File I/O operations
readdir(): Directory listing with pagination
create()/mkdir()/remove(): File system modifications
symlink()/readlink(): Symbolic link operations

Use Cases

This library is perfect for:

Remote File Systems: Export cloud storage, databases, or APIs as file systems
Development Tools: Create virtual file systems for testing and development
Cross-Platform Mounting: Provide file access across different operating systems
Custom Storage: Expose specialized storage systems through a standard interface

Performance Considerations

Implement getattr() efficiently as it's called frequently
Use appropriate caching strategies in your file system implementation
Consider the NFS client's caching behavior when designing your backend
The server supports concurrent connections and operations

Standards Compliance

This implementation follows these RFCs:

RFC 1813: NFS Version 3 Protocol Specification
RFC 5531: RPC: Remote Procedure Call Protocol Specification Version 2
RFC 1832: XDR: External Data Representation Standard
RFC 1833: Binding Protocols for ONC RPC Version 2

CI/CD & Docker

This project uses GitFlic CI/CD for automated testing, security scanning, and deployment. The pipeline automatically runs on every push and merge request, ensuring code quality and reliability.

Features:

🔧 Automated Rust builds and testing
🐳 Docker containerization with multi-stage builds
🔒 Security scanning (dependencies + containers)
📦 Automatic artifact management
🚀 GitFlic container registry integration

Quick Start: Upload environment variables and push to main - everything else is pre-configured!

For complete setup instructions, see CI-CD.md

Contributing

Contributions are welcome! Areas where help is particularly appreciated:

Additional protocol features and edge cases
Performance optimizations
Documentation improvements
Platform-specific testing and fixes
Example implementations

Development Workflow

Fork the repository
Create a feature branch from main
Make your changes with appropriate tests
Ensure all CI/CD checks pass
Submit a merge request

License

This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.

fernfs 0.1.0