Skip to content

dev-harsh1998/IronDrop

BranchesTags

Repository files navigation

IronDrop

IronDrop Logo

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.

Rust CI

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:

Option Description Example
-d, --directory Required - Directory to serve -d /home/user/files
-l, --listen Listen address (default: 127.0.0.1) -l 0.0.0.0
-p, --port Port number (default: 8080) -p 3000
--enable-upload Enable file uploads --enable-upload true
--enable-webdav Enable WebDAV methods (OPTIONS, PROPFIND, PROPPATCH, MKCOL, PUT, DELETE, COPY, MOVE, LOCK, UNLOCK) --enable-webdav true
--disable-rate-limit Disable rate limiting only when WebDAV is enabled --enable-webdav true --disable-rate-limit true
--base-path Base URL path prefix for reverse proxy sub-path deployments --base-path /webstorage
--username/--password Basic authentication --username admin --password secret
-a, --allowed-extensions Restrict file types -a "*.pdf,*.doc,*.zip"
-t, --threads Tokio runtime worker threads (default: 8) -t 16
--config-file Use INI configuration file --config-file prod.ini
--ssl-cert SSL certificate file (PEM) for HTTPS --ssl-cert cert.pem
--ssl-key SSL private key file (PEM) for HTTPS --ssl-key key.pem
-v, --verbose Debug logging -v true

📄 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:

Endpoint Purpose Example
/ 📁 Directory listing and file browsing http://localhost:8080/
/monitor 📊 Real-time server monitoring dashboard http://localhost:8080/monitor
/search?q=term 🔍 File search API http://localhost:8080/search?q=document
/_irondrop/upload ⬆️ File upload endpoint (if enabled) Used by the web interface

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

🔧 Feature Documentation

🛡️ Security & Quality

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.

Made with ❤️ and 🦀 in Rust
Dependency-free core engine paths • Production ready • Battle tested with 325 automated tests

⭐ Star us on GitHub   •   Report an Issue   •   📚 Read the Docs   •   🧪 View Tests

About

Powerful, beautiful, fast & functional multi threaded static web server in rust with a template engine with multipart support

Topics

high-performance file-sharing cloud-storage self-hosted secure rust-lang template-engines webdav-server embedded-webserver owasp-top-ten rfcs multi-os highly-customizable single-executable-application fast-search-engine minimal-resource-usage monitoring-endpoint thoroughly-tested tokio-async

Resources

Readme

License

MIT license
Activity

Stars

21 stars

Watchers

1 watching

Forks

2 forks
Report repository

Releases 1

v2.6.4 Latest
Mar 21, 2026

Packages

 
 
 

Contributors

Languages