IronDrop

IronDrop file server

IronDrop is a file server written in Rust. It serves directories, supports optional uploads, provides search, and includes a monitoring page. It ships as a single binary with embedded templates.

IronDrop focuses on predictable behavior, simplicity, and low overhead. Use it to serve or share files locally or on your network.

Overview

Features

• File browsing and downloads with range requests and MIME detection
• Optional uploads with a drag-and-drop web UI (direct-to-disk streaming)
• Search (standard and ultra-compact modes for large directories)
• Monitoring dashboard at /monitor and a JSON endpoint (/monitor?json=1)
• Basic security features: rate limiting, optional Basic Auth, path safety checks
• Single binary; templates and assets are embedded
• Pure standard library networking and file I/O (no external HTTP stack or async runtime)
• Ultra-compact search index option for very large directory trees (tested up to ~10M entries)

Performance

Designed to keep memory usage steady and to stream large files without buffering them in memory. The ultra-compact search mode reduces memory for very large directory trees.

• Ultra-compact search: approximately ~110 MB of RAM for around 10 million paths; search latency depends on CPU, disk, and query specifics.
• No-dependency footprint: networking and file streaming are implemented with Rust's std::net and std::fs, producing a single self-contained binary.

Security

Includes rate limiting, optional Basic Auth, basic input validation, and path traversal protection. See RFC & OWASP Compliance and Security Fixes for details.

📦 Installation

Getting started with IronDrop is simple.

From Source

# Clone the repository
git clone https://github.com/dev-harsh1998/IronDrop.git
cd IronDrop

# Build the release binary
cargo build --release

# The executable will be in ./target/release/irondrop

System-Wide Installation (Recommended)

To use IronDrop from anywhere on your system, install it to a directory in your PATH:

# Linux/macOS - Install to /usr/local/bin (requires sudo)
sudo cp ./target/release/irondrop /usr/local/bin/

# Alternative: Install to ~/.local/bin (no sudo required)
mkdir -p ~/.local/bin
cp ./target/release/irondrop ~/.local/bin/
# Add ~/.local/bin to PATH if not already:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc  # or ~/.zshrc
source ~/.bashrc  # or restart terminal

# Windows (PowerShell as Administrator)
# Create program directory
New-Item -ItemType Directory -Force -Path "C:\Program Files\IronDrop"
# Copy executable
Copy-Item ".\target\release\irondrop.exe" "C:\Program Files\IronDrop\"
# Add to system PATH (requires restart or new terminal)
$env:PATH += ";C:\Program Files\IronDrop"
[Environment]::SetEnvironmentVariable("PATH", $env:PATH, [EnvironmentVariableTarget]::Machine)

Verify Installation:

# Test that irondrop is available globally
irondrop --version

# Now you can run from any directory:
irondrop -d ~/Documents --listen 0.0.0.0

Getting started

Quick start

Step 1: Download or build IronDrop

# Build from source (requires Rust)
git clone https://github.com/dev-harsh1998/IronDrop.git
cd IronDrop
cargo build --release

Step 2: Start sharing files immediately

# Share your current directory (safest - local access only)
./target/release/irondrop -d .

# Share with your network (accessible to other devices)
./target/release/irondrop -d . --listen 0.0.0.0

Step 3: Open your browser and visit http://localhost:8080

📖 Common Use Cases

🏠 Home File Sharing

# Share your Downloads folder with family devices
irondrop -d ~/Downloads --listen 0.0.0.0 --port 8080

💼 Work File Server

# Secure file server with uploads and authentication
irondrop -d ./shared-files \
  --enable-upload \
  --username admin \
  --password your-secure-password \
  --listen 0.0.0.0

🎬 Media Server

# Serve your media collection (videos, music, photos)
irondrop -d /path/to/media \
  --allowed-extensions "*.mp4,*.mp3,*.jpg,*.png" \
  --threads 16 \
  --listen 0.0.0.0

☁️ Cloud Storage Alternative

# Use a configuration file for consistent setup
irondrop --config-file ./config/production.ini

🛠️ Configuration Options

Command Line Options

IronDrop offers extensive customization through command-line arguments:

📄 Configuration File (Recommended for Production)

For consistent deployments, use an INI configuration file:

# Create your config file
cp config/irondrop.ini my-server.ini
# Edit it with your settings
# Then run:
irondrop --config-file my-server.ini

The configuration file supports all command-line options and more! See the detailed example with comments explaining every option.

Configuration Priority (highest to lowest):

1. Command line arguments
2. Environment variables (IRONDROP_*)
3. Configuration file
4. Built-in defaults

Key endpoints

Once IronDrop is running, these endpoints are available:

Notes

• Use authentication (--username/--password) when exposing to untrusted networks
• Adjust --threads based on workload

❓ Need Help?

# Get detailed help for all options
irondrop --help

# Check your version
irondrop --version

# Test with verbose logging
irondrop -d . --verbose true

For comprehensive documentation, see our Complete Documentation Index.

Version notes

Recent releases include direct-to-disk uploads, an ultra-compact search mode, and a /monitor page with a JSON endpoint.

Documentation

IronDrop has extensive documentation covering its architecture, API, and features.

📖 Core Documentation

• Complete Documentation Index - Central hub for all documentation
• Architecture Guide - System design and component overview
• API Reference - Complete HTTP API documentation
• Deployment Guide - Production deployment strategies

🔧 Feature Documentation

• Search Feature Deep Dive - Ultra-compact search system details
• Upload Integration Guide - File upload system and UI
• Direct Upload System - Memory-efficient direct streaming architecture
• Configuration System - INI-based configuration guide
• Template System - Embedded template engine

🛡️ Security & Quality

• Security Fixes - Security enhancements and mitigations
• RFC & OWASP Compliance - Standards compliance details
• Testing Documentation - Comprehensive test suite overview
• Monitoring Guide - Real-time monitoring and metrics

Testing

IronDrop is rigorously tested with 199 comprehensive tests across 16 test files covering all aspects of functionality.

Test Categories

• Integration Tests (16 tests): End-to-end functionality and HTTP handling
• Monitor Tests (2 tests): Real-time monitoring dashboard and metrics
• Rate Limiter Tests (7 tests): Memory-based rate limiting and DoS protection
• Template Tests (8 tests): Embedded template system and rendering
• Ultra-Compact Search Tests (10 tests): Advanced search engine functionality
• Configuration Tests (12 tests): INI parsing and configuration validation
• Core Server & Unit Tests (40 tests): Library functions, utilities, and core logic

# Run all tests
cargo test

# Run specific test categories
cargo test comprehensive_test    # Core server functionality
cargo test upload_integration    # Upload system tests
cargo test edge_case_test        # Edge cases and error handling
cargo test direct_upload_test    # Direct streaming validation

# Run tests with output
cargo test -- --nocapture

For detailed testing information, see Testing Documentation.

License

IronDrop is licensed under the MIT License.