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 HTTP layer is implemented in-house (request parsing, routing, streaming) without an external HTTP framework
• Tokio is used for the async runtime and networking; standard production dependencies are used where practical (for example clap, log/env_logger, tokio, and rustls/tokio-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), with Depth: 0, 1, and recursive infinity
• 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: the HTTP implementation is in-house; Tokio provides async scheduling and networking, and dependencies such as clap, log/env_logger, and rustls/tokio-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 crates.io

cargo install irondrop

Latest from Git

cargo install --git https://github.com/dev-harsh1998/IronDrop.git

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: Install IronDrop

cargo install irondrop

Step 2: Start sharing files immediately

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

# Share with your network (accessible to other devices)
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/):

Start IronDrop with the --base-path flag:

irondrop -d ./files --base-path /webstorage --listen 0.0.0.0

Then configure Nginx to forward the full path (no stripping needed):

location /webstorage/ {
    proxy_pass http://127.0.0.1:8080/webstorage/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    client_max_body_size 0;
    proxy_buffering off;
}

Note: No sub_filter hacks or extra /_irondrop/ location blocks are needed. The --base-path flag makes IronDrop fully reverse-proxy aware — all generated URLs (HTML links, JavaScript API calls, WebDAV hrefs, HTTP redirects) are automatically prefixed with the configured base path.

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
disable_rate_limit = false

Note: disable_rate_limit is ignored unless WebDAV is enabled.

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:

• v2.7.2: Major memory optimizations: WebDAV Transfer-Encoding: chunked background thread streaming (near-zero RAM usage for large tree traversals), Web UI 1,000-file pagination with lazy metadata loading, and a massive ~340MB reduction in default search index bootstrap footprint.
• v2.7.1: Direct-to-disk uploads, 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 325 automated tests:

• 44 unit tests in core source modules
• 281 integration/system tests across 30 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.