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

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
--username/--password Basic authentication --username admin --password secret
-a, --allowed-extensions Restrict file types -a "*.pdf,*.doc,*.zip"
-t, --threads 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

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

🔧 Feature Documentation

🛡️ Security & Quality

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.

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

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

About

Powerful, beautiful, fast & functional multi threaded static web server using only stdlib 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 multithreaded-tcp-server multi-os highly-customizable single-executable-application fast-search-engine minimal-resource-usage monitoring-endpoint thoroughly-tested

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