# IronDrop
<div align="center">
<img src="irondrop-logo.png" alt="IronDrop Logo" width="150"/>
<h1>IronDrop file server</h1>
<p>
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.
</p>
[](https://github.com/dev-harsh1998/IronDrop/actions/workflows/rust.yml)
</div>
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](./doc/RFC_OWASP_COMPLIANCE.md) and [Security Fixes](./doc/SECURITY_FIXES.md) for details.
## 📦 Installation
Getting started with IronDrop is simple.
### From crates.io
```bash
cargo install irondrop
```
### Latest from Git
```bash
cargo install --git https://github.com/dev-harsh1998/IronDrop.git
```
**Verify Installation:**
```bash
# 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
```bash
cargo install irondrop
```
**Step 2:** Start sharing files immediately
```bash
# 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**
```bash
# Share your Downloads folder with family devices
irondrop -d ~/Downloads --listen 0.0.0.0 --port 8080
```
#### 💼 **Work File Server**
```bash
# 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**
```bash
# 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**
```bash
# Use a configuration file for consistent setup
irondrop --config-file ./config/production.ini
```
#### 🔒 HTTPS File Server
```bash
# 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:**
```nginx
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:
```bash
irondrop -d ./files --base-path /webstorage --listen 0.0.0.0
```
Then configure Nginx to forward the full path (no stripping needed):
```nginx
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](./doc/DEPLOYMENT.md#nginx-reverse-proxy-deployment) for full configuration examples and optimization settings.
### 🛠️ Configuration Options
#### **Command Line Options**
IronDrop offers extensive customization through command-line arguments:
| `-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:
```bash
# 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](./config/irondrop.ini) with comments explaining every option.
WebDAV can also be enabled in config:
```ini
[webdav]
enable_webdav = true
disable_rate_limit = false
```
Note: `disable_rate_limit` is ignored unless WebDAV is enabled.
Quick CLI example:
```bash
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:
| **`/`** | 📁 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?
```bash
# 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](./doc/README.md).
## 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**](./doc/README.md) - Central hub for all documentation
* [**Architecture Guide**](./doc/ARCHITECTURE.md) - System design and component overview
* [**API Reference**](./doc/API_REFERENCE.md) - Complete HTTP API documentation
* [**Deployment Guide**](./doc/DEPLOYMENT.md) - Production deployment strategies
### 🔧 **Feature Documentation**
* [**Search Feature Deep Dive**](./doc/SEARCH_FEATURE.md) - Ultra-compact search system details
* [**WebDAV Implementation Guide**](./doc/WEBDAV_IMPLEMENTATION.md) - End-to-end flow and RFC 4918 behavior
* [**Upload Integration Guide**](./doc/UPLOAD_INTEGRATION.md) - File upload system and UI
* [**Direct Upload System**](./doc/MULTIPART_README.md) - Memory-efficient direct streaming architecture
* [**Configuration System**](./doc/CONFIGURATION_SYSTEM.md) - INI-based configuration guide
* [**Template System**](./doc/TEMPLATE_SYSTEM.md) - Embedded template engine
### 🛡️ **Security & Quality**
* [**Security Fixes**](./doc/SECURITY_FIXES.md) - Security enhancements and mitigations
* [**RFC & OWASP Compliance**](./doc/RFC_OWASP_COMPLIANCE.md) - Standards compliance details
* [**Testing Documentation**](./doc/TESTING_DOCUMENTATION.md) - Comprehensive test suite overview
* [**Monitoring Guide**](./doc/MONITORING.md) - 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)
```bash
# 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](./doc/TESTING_DOCUMENTATION.md).
## License
IronDrop is licensed under the [MIT License](./LICENSE).
---
<div align="center">
<p>
<strong>Made with ❤️ and 🦀 in Rust</strong><br>
<em>Dependency-free core engine paths • Production ready • Battle tested with 325 automated tests</em>
</p>
<p>
<a href="https://github.com/dev-harsh1998/IronDrop">⭐ Star us on GitHub</a>
•
<a href="https://github.com/dev-harsh1998/IronDrop/issues">Report an Issue</a>
•
<a href="./doc/README.md">📚 Read the Docs</a>
•
<a href="./doc/TESTING_DOCUMENTATION.md">🧪 View Tests</a>
</p>
</div>
