IronDrop

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
• Native SSL/TLS support via --ssl-cert and --ssl-key (built-in HTTPS, no reverse proxy required)
• Single binary; templates and assets are embedded
• Core engine is dependency-free in critical paths: networking, search, and filesystem access are implemented in-house
• Standard production dependencies are still used where practical (for example clap, log/env_logger, and rustls)
• Ultra-compact search index option for very large directory trees (tested up to ~10M entries)
• WebDAV (RFC 4918 Class 1 + Class 2 core): OPTIONS, PROPFIND, PROPPATCH, MKCOL, PUT, DELETE, COPY, MOVE, LOCK, UNLOCK
  • Enabled only when --enable-webdav true (or equivalent config setting) is provided

WebDAV RFC 4918 support

IronDrop includes an RFC 4918-focused implementation. The WebDAV core engine is implemented in-house and keeps critical request/response logic dependency-free.

• Supported methods: OPTIONS, PROPFIND, PROPPATCH, MKCOL, PUT, DELETE, COPY, MOVE, LOCK, UNLOCK
• WebDAV is feature-gated and disabled by default; enable explicitly with --enable-webdav true
• Capability headers: DAV: 1,2, Allow, MS-Author-Via
• PROPFIND: allprop, propname, named prop, per-property propstat grouping (200/404), and finite-depth refusal (403 + propfind-finite-depth)
• PROPPATCH: dead-property set/remove with 207 Multi-Status results
• Locking: exclusive write locks, lock refresh, If header token evaluation (including Not conditions), and token-gated write preconditions
• Tree operations: lock-aware DELETE multistatus behavior (207 with 423/424 where applicable)

Current RFC scope limits:

• ACL/versioning/bindings RFCs are out of scope (RFC 3744, RFC 3253, RFC 5842)
• Lock and dead-property storage is in-process (non-persistent across server restarts)

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.
• Dependency profile: networking/search/filesystem core paths are dependency-free, while operational dependencies such as clap, log/env_logger, and rustls are used as stable standard building blocks.

Security

Includes native SSL/TLS (HTTPS), 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

🔒 HTTPS File Server

# Generate a self-signed certificate (for testing)
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes -subj '/CN=localhost'

# Serve files over HTTPS
irondrop -d ./files --ssl-cert cert.pem --ssl-key key.pem --listen 0.0.0.0

# HTTPS with authentication
irondrop -d ./files --ssl-cert cert.pem --ssl-key key.pem \
  --username admin --password secret --listen 0.0.0.0

🌐 Reverse Proxy (Nginx)

For production deployments, it is recommended to run IronDrop behind Nginx.

Root Domain Configuration:

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    client_max_body_size 0; # Enable large uploads
    proxy_buffering off;    # Enable streaming
}

Subpath Configuration (e.g., /webstorage/):

location /webstorage/ {
    proxy_pass http://127.0.0.1:8080/;
    proxy_redirect / /webstorage/;
    sub_filter 'href="/"' 'href="/webstorage/"';
    sub_filter_once off;
    # ... see deployment guide for full sub_filter list
}

See the Deployment Guide for full configuration examples and optimization settings.

🛠️ 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.

WebDAV can also be enabled in config:

[webdav]
enable_webdav = true

Quick CLI example:

irondrop -d ./shared --enable-webdav true --listen 0.0.0.0

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
• Use --ssl-cert and --ssl-key for native HTTPS without a reverse proxy

❓ 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
• WebDAV Implementation Guide - End-to-end flow and RFC 4918 behavior
• 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 272 automated tests:

• 48 unit tests in core source modules
• 224 integration/system tests across 28 test files (including WebDAV RFC suites)

Coverage Areas

• HTTP parser/request handling, auth, rate limiting, monitoring, uploads, search, and utilities
• WebDAV RFC-focused behavior (PROPFIND, PROPPATCH, COPY/MOVE, LOCK/UNLOCK, error XML, edge preconditions)
• Security and robustness paths (path traversal checks, symlink safeguards, malformed input handling)

# 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.